Documentation
¶
Overview ¶
Package br validates and formats the Brazilian values an application takes from a form and prints on a page: the CPF, the CNPJ, the CEP, an amount in reais, a date, and the federative unit.
It is a library. It registers no route, owns no table and decides no authorization, so nothing about it goes in bootstrap/app.go: a caller imports it and calls it.
Taking a value in ¶
ParseCPF, ParseCNPJ and ParseCEP read a value written bare or in its one conventional punctuation, and return the bare spelling to store. ValidCPF, ValidCNPJ and ValidCEP are the same question answered with a bool. The CPF and the CNPJ are checked against the check digits the Receita Federal computes; the CNPJ may be alphanumeric.
The same checks are rules of hesape/validation, registered when this package is initialized and named by RuleCPF, RuleCNPJ, RuleCPFOrCNPJ and RuleCEP:
var StoreCustomer = validation.MustCompile(validation.Rules{
"document": "required|" + br.RuleCPFOrCNPJ,
"postcode": "required|" + br.RuleCEP,
})
Printing a value ¶
CPF, CNPJ and CEP punctuate a stored value; BRL writes centavos as reais, R$ 1.234,56; Date writes a day as 31/12/2026. Each is a function of its argument alone.
UF is the closed set of the twenty-seven units, in the shape hesape/enum reads: UFValues, Label for the name a form shows, and Value and Scan for a column.
The files are laid out by subject:
cpf.go, cnpj.go, cep.go -> parsing, check digits and punctuation shape.go -> the masks the three share rules.go -> the hesape/validation rules money.go, date.go -> BRL and Date uf.go -> the UF enum
Index ¶
- Constants
- Variables
- func BRL(cents int64) string
- func CEP(s string) string
- func CNPJ(s string) string
- func CNPJCheckDigits(base string) (string, error)
- func CPF(s string) string
- func CPFCheckDigits(base string) (string, error)
- func Date(t time.Time) string
- func Mobile(s string) string
- func ParseCEP(s string) (string, error)
- func ParseCNPJ(s string) (string, error)
- func ParseCPF(s string) (string, error)
- func ParseMobile(s string) (string, error)
- func ValidCEP(s string) bool
- func ValidCNPJ(s string) bool
- func ValidCPF(s string) bool
- func ValidMobile(s string) bool
- type UF
Constants ¶
const ( // RuleCPF is a CPF, as ParseCPF accepts it. RuleCPF = "cpf" // RuleCNPJ is a CNPJ, numeric or alphanumeric, as ParseCNPJ accepts it. RuleCNPJ = "cnpj" // RuleCPFOrCNPJ is a value either ParseCPF or ParseCNPJ accepts: the // document field of a form a person or a company fills in. RuleCPFOrCNPJ = "cpf_or_cnpj" // RuleCEP is a CEP, as ParseCEP accepts it. RuleCEP = "cep" // RuleMobile is a Brazilian mobile number, as ParseMobile accepts it. RuleMobile = "celular" )
The names this package registers with hesape/validation, for a rule string:
var StoreCustomer = validation.MustCompile(validation.Rules{
"document": "required|" + br.RuleCPFOrCNPJ,
"postcode": "required|" + br.RuleCEP,
})
Write the constant rather than the name it holds. A rule name is real only once it is in the catalogue, and the catalogue is filled when this package is initialized: a rule set that names the constant imports the package, and Go initializes an imported package before the importer's own variables, so the set is compiled after the rules exist. A rule set that spells "cpf" in a package that does not import this one may be compiled first, and then it fails at boot with an unknown rule.
Each rule takes no argument; one written after a colon refuses every value, because an argument this package would ignore is a typo nothing reports. Each accepts what the matching Parse function accepts, and only a string: a CPF sent as a JSON number has already lost its leading zeros. A blank value is not checked -- write required, or nullable, beside the rule for that.
Variables ¶
var ErrInvalidCEP = errors.New("br: not a valid CEP")
ErrInvalidCEP is what ParseCEP returns for a value that is not a CEP.
var ErrInvalidCNPJ = errors.New("br: not a valid CNPJ")
ErrInvalidCNPJ is what ParseCNPJ and CNPJCheckDigits return for a value that is not a CNPJ.
var ErrInvalidCPF = errors.New("br: not a valid CPF")
ErrInvalidCPF is what ParseCPF and CPFCheckDigits return for a value that is not a CPF. It says nothing about which part was wrong, because the person who typed the value is the only one who can tell a typo from a wrong number.
var ErrInvalidMobile = errors.New("br: not a valid mobile number")
ErrInvalidMobile is what ParseMobile returns for a value that is not a Brazilian mobile number.
var ErrInvalidUF = errors.New("br: not a UF")
ErrInvalidUF is what ParseUF, Value and Scan return for a code outside the set.
Functions ¶
func BRL ¶
BRL writes an amount of reais held as a count of centavos, the way a Brazilian page prints money: R$ 1.234,56.
A dot separates each three digits of the reais, a comma stands before the two digits of the centavos, and the symbol leads with a space after it. A negative amount leads with the sign, before the symbol -- -R$ 1.234,56 -- because a sign written after the symbol reads as part of the amount. Zero is R$ 0,00, and every int64 is written, its most negative value included.
The amount is an integer because an amount that has to add up is held as one; no float64 appears on the way from it to the page. The result depends on nothing but the argument: hesape/number writes the same string from CurrencyFromCents(cents, "BRL") only while the process-wide locale is pt-BR, and a library cannot set that locale without setting it for everything else the application formats.
func CEP ¶
CEP writes a CEP punctuated, as 00000-000.
It takes the eight digits bare or already punctuated, and returns anything else unchanged: it formats, and does not validate. Validate with ParseCEP where the value is taken in.
func CNPJ ¶
CNPJ writes a CNPJ punctuated, as 00.000.000/0000-00, with its letters in capitals.
It takes the fourteen characters bare or already punctuated, and returns anything else unchanged: it formats, and does not validate. Validate with ParseCNPJ where the value is taken in.
func CNPJCheckDigits ¶
CNPJCheckDigits returns the two check digits of a CNPJ whose first twelve characters are base, and ErrInvalidCNPJ when base is not twelve digits or letters. A lower-case letter is read as its capital.
Each character is worth its ASCII code minus 48 -- a digit its own value, A seventeen, Z forty-two. A check digit is the sum of the characters before it, weighted from the right by 2 to 9 and again from 2, taken modulo eleven: a remainder below two gives zero, and any other gives eleven minus it.
func CPF ¶
CPF writes a CPF punctuated, as 000.000.000-00.
It takes the eleven digits bare or already punctuated, and returns anything else unchanged: it formats, and does not validate, so a page that prints a stored value shows what is stored rather than an empty cell. Validate with ParseCPF where the value is taken in.
func CPFCheckDigits ¶
CPFCheckDigits returns the two check digits of a CPF whose first nine digits are base, and ErrInvalidCPF when base is not nine digits.
Each check digit is the sum of the digits before it, weighted from 10 (or 11) down to 2, times ten, modulo eleven -- with ten written as zero. It is what a seeder or a factory needs to write a CPF that passes, without borrowing one that belongs to somebody.
func Date ¶
Date writes the calendar day of t as a Brazilian page prints it: 31/12/2026, day, month and four-digit year.
The day is the one t holds in its own location. An instant read from a database is usually in UTC, where a late evening in Brasília is already the next day, so convert it first -- br.Date(t.In(location)) -- with the location the reader lives in.
func Mobile ¶ added in v0.2.0
Mobile writes a mobile number punctuated, as (00) 00000-0000.
It takes the eleven digits bare or already punctuated, and returns anything else unchanged: it formats, and does not validate. Validate with ParseMobile where the value is taken in.
func ParseCEP ¶
ParseCEP returns the eight digits of a CEP, written bare (00000000) or punctuated (00000-000), and ErrInvalidCEP for anything else or for a code below 01000-000, where no range begins.
A CEP carries no check digit, so a code that passes may still address nothing: only a lookup in the Correios base can say it exists.
The digits come back bare, which is the spelling to store.
func ParseCNPJ ¶
ParseCNPJ returns the fourteen characters of a CNPJ, written bare (00000000000000) or punctuated (00.000.000/0000-00), and ErrInvalidCNPJ for anything else.
The first twelve positions may hold letters as well as digits: that is the alphanumeric CNPJ the Receita Federal issues, and the numeric CNPJ is the case of it whose twelve positions are all digits, checked by the same computation. The last two positions are the check digits, and are always digits. A letter typed in lower case is read as the capital it stands for, and comes back as one.
It refuses fourteen repetitions of one character, which no CNPJ is. It does not say whether the CNPJ was issued or is active: only the Receita Federal can.
The characters come back bare, which is the spelling to store.
func ParseCPF ¶
ParseCPF returns the eleven digits of a CPF, written bare (00000000000) or punctuated (000.000.000-00), and ErrInvalidCPF for anything else.
It checks the shape and the two check digits the Receita Federal computes, and refuses the eleven repetitions of one digit, whose check digits compute but which belong to nobody. It does not say whether the CPF was issued or is regular: only the Receita Federal can.
The digits come back bare, which is the spelling to store: a column that holds both spellings cannot be searched for either.
func ParseMobile ¶ added in v0.2.0
ParseMobile returns the eleven digits of a Brazilian mobile number, written bare (00000000000) or punctuated ((00) 00000-0000), and ErrInvalidMobile for anything else.
It checks the shape, that the area code is one Anatel assigns, that the number starts with 9 (every mobile number since 2016), and refuses the nine followed by eight zeros, which a form fills when somebody types nothing. It does not say whether the line exists: only the operator can.
The digits come back bare, which is the spelling to store.
func ValidMobile ¶ added in v0.2.0
ValidMobile reports whether ParseMobile accepts s.
Types ¶
type UF ¶
type UF string
UF is one of the twenty-seven federative units of Brazil -- the twenty-six states and the Federal District -- stored as its two-letter code.
It is a closed set in the shape a generated enum has: constants that are the only valid values, Valid to ask, Label for what a form shows, and a Value/Scan pair that refuses a code outside the set on the way to and from a column. So hesape/enum reads it like any other: enum.Options(br.UFValues()...) fills a select, and validation.EnumOf(br.UFValues()...) is the rule.
const ( UFAC UF = "AC" UFAL UF = "AL" UFAP UF = "AP" UFAM UF = "AM" UFBA UF = "BA" UFCE UF = "CE" UFDF UF = "DF" UFES UF = "ES" UFGO UF = "GO" UFMA UF = "MA" UFMT UF = "MT" UFMS UF = "MS" UFMG UF = "MG" UFPA UF = "PA" UFPB UF = "PB" UFPR UF = "PR" UFPE UF = "PE" UFPI UF = "PI" UFRJ UF = "RJ" UFRN UF = "RN" UFRS UF = "RS" UFRO UF = "RO" UFRR UF = "RR" UFSC UF = "SC" UFSP UF = "SP" UFSE UF = "SE" UFTO UF = "TO" )
The units, in the alphabetical order of their names, which is the order a list of them is read in. Stored exactly as written: the code is what the Correios, the Receita Federal and IBGE all print.
func ParseUF ¶
ParseUF turns request input into a UF, or wraps ErrInvalidUF.
It reads the code exactly as the set spells it, in capitals: the value a select sends back is the one Options gave it, and a value that differs from every option did not come from the form.
func UFValues ¶
func UFValues() []UF
UFValues lists the twenty-seven units in declaration order.
It is what fills a select and what a rule is built from, so the set is written once, here, and every list of units derives from it.
func (UF) Label ¶
Label is the name of the unit, which is what a form shows: São Paulo for SP. It is empty for a code outside the set.
It is separate from String on purpose. The code is a contract with every column and every message that holds it; the name is a contract with nobody, and changing how one is spelled must not be able to change a row.
func (*UF) Scan ¶
Scan implements sql.Scanner. A code the set does not hold is an error at the row that has it, rather than a value that behaves like a unit three layers up.