Add package doc

This commit is contained in:
Gabriel Augendre 2021-08-21 19:52:10 +02:00
parent c01b54ef50
commit ec024a0189

View file

@ -1,3 +1,5 @@
// Package data is used to parse the insee number into a usable and human-readable data structure.
// All the required data is embedded in the package so no external file is required.
package data package data
import ( import (
@ -10,9 +12,14 @@ import (
) )
var ( var (
// Male is one of the possible values for InseeData.Gender.
Male = "homme" Male = "homme"
// Female is the other possible value for InseeData.Gender.
Female = "femme" Female = "femme"
// Unknown is a value used when determining the value of a string field in InseeData was not possible.
Unknown = "inconnu(e)" Unknown = "inconnu(e)"
// France is the only item in the default slice for InseeData.Countries.
France = "FRANCE"
) )
//go:embed curated_data/countries.json //go:embed curated_data/countries.json
@ -24,22 +31,42 @@ var rawDepartments []byte
//go:embed curated_data/cities.json //go:embed curated_data/cities.json
var rawCities []byte var rawCities []byte
// InseeData contains human-readable data about the insee number used to construct it.
type InseeData struct { type InseeData struct {
// InseeNumber is the raw number, as given.
InseeNumber string `json:"insee_number"` InseeNumber string `json:"insee_number"`
// Gender is either Male or Female.
Gender string `json:"gender"` Gender string `json:"gender"`
// Year of birth.
Year int `json:"year"` Year int `json:"year"`
// Month of birth.
Month time.Month `json:"month"` Month time.Month `json:"month"`
// Department of birth, represented with its name.
Department string `json:"department"` Department string `json:"department"`
// City of birth, represented with its name.
City string `json:"city"` City string `json:"city"`
// CityCode is the INSEE code of the City of birth.
CityCode string `json:"city_code"` CityCode string `json:"city_code"`
// Foreign is false if the person is born in France, true otherwise.
Foreign bool `json:"foreign"` Foreign bool `json:"foreign"`
// Countries is the list of country names matching the CountryCode.
// Some country codes may match multiple countries, so Countries is a slice.
// This is always set to `{"FRANCE"}` when Foreign is false.
Countries []string `json:"countries"` Countries []string `json:"countries"`
// CountryCode is the code of the birth country.
CountryCode string `json:"country_code"` CountryCode string `json:"country_code"`
// Continent of birth.
Continent string `json:"continent"` Continent string `json:"continent"`
// OrderOfBirth is the order of birth of the person in the city or country (if Foreign) of birth at the year/month of birth.
// For example, 384 would mean that the person is the 384th born in the specific city/country on the given year/month.
OrderOfBirth int `json:"order_of_birth"` OrderOfBirth int `json:"order_of_birth"`
// ControlKey is the complement to 97 of the insee number (minus the last two digits) modulo 97.
ControlKey int `json:"control_key"` ControlKey int `json:"control_key"`
} }
// NewInseeData generates an InseeData struct, extracting the data into the relevant fields.
// The data is converted to a human-readable format before being stored.
// If a value can't be determined, the corresponding field is generally set to Unknown.
func NewInseeData(inseeNumber string) (*InseeData, error) { func NewInseeData(inseeNumber string) (*InseeData, error) {
if len(inseeNumber) != 15 { if len(inseeNumber) != 15 {
return nil, fmt.Errorf("le numéro INSEE number must contain 15 characters") return nil, fmt.Errorf("le numéro INSEE number must contain 15 characters")
@ -57,7 +84,7 @@ func NewInseeData(inseeNumber string) (*InseeData, error) {
} }
var city string var city string
var department string var department string
countries_ := []string{"FRANCE"} countries_ := []string{France}
countryCode := "" countryCode := ""
continent := "Europe" continent := "Europe"
foreign := (dep >= 91 && dep <= 96) || dep == 99 foreign := (dep >= 91 && dep <= 96) || dep == 99
@ -118,6 +145,8 @@ func NewInseeData(inseeNumber string) (*InseeData, error) {
}, nil }, nil
} }
// IsValid returns true when the insee number is valid and false when not.
// The insee number is valid when it matches its ControlKey.
func (insee InseeData) IsValid() (bool, error) { func (insee InseeData) IsValid() (bool, error) {
r := strings.NewReplacer( r := strings.NewReplacer(
"2A", "19", "2A", "19",
@ -132,6 +161,7 @@ func (insee InseeData) IsValid() (bool, error) {
return code == insee.ControlKey, nil return code == insee.ControlKey, nil
} }
// String returns a string representation of the InseeData in a human-readable format, suited for printing to stdout.
func (insee InseeData) String() string { func (insee InseeData) String() string {
var result []string var result []string
result = append(result, insee.InseeNumber) result = append(result, insee.InseeNumber)