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 -- and a CPF or a CNPJ with part of it hidden.
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.
ParseMobile reads a mobile number the same way. ParseBRL reads an amount in reais as a person types it, R$ 1.234,56, or as an HTML number input submits it, 1234.56, and returns centavos.
The same checks are rules of hesape/validation, registered when this package is initialized and named by RuleCPF, RuleCNPJ, RuleCPFOrCNPJ, RuleCEP, RuleMobile and RuleBRL:
var StoreCustomer = validation.MustCompile(validation.Rules{
"document": "required|" + br.RuleCPFOrCNPJ,
"postcode": "required|" + br.RuleCEP,
})
Printing a value ¶
CPF, CNPJ, CEP and Mobile punctuate a stored value; BRL writes centavos as reais, R$ 1.234,56, and FormatBRL writes them without the grouping or without zero centavos; Date writes a day as 31/12/2026. RedactCPF and RedactCNPJ write a document with part of it hidden, through a Redaction such as KeepCPFMiddle, ***.456.789-**. Each is a function of its arguments 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 mobile.go -> the mobile number shape.go -> the masks they share redact.go -> RedactCPF, RedactCNPJ and Redaction rules.go -> the hesape/validation rules money.go, date.go -> BRL, FormatBRL, ParseBRL 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 FormatBRL(cents int64, f BRLFormat) string
- func Mobile(s string) string
- func ParseBRL(s string) (int64, error)
- 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 RedactCNPJ(s string, r Redaction) string
- func RedactCPF(s string, r Redaction) string
- func ValidBRL(s string) bool
- func ValidCEP(s string) bool
- func ValidCNPJ(s string) bool
- func ValidCPF(s string) bool
- func ValidMobile(s string) bool
- type BRLFormat
- type Redaction
- 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" // RuleBRL is an amount in reais, as ParseBRL accepts it: the price or the // budget field of a form. RuleBRL = "brl" )
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 ErrInvalidBRL = errors.New("br: not a valid amount in reais")
ErrInvalidBRL is what ParseBRL returns for a value that is not an amount in reais.
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.
BRL is FormatBRL with the zero BRLFormat.
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 FormatBRL ¶ added in v0.3.0
FormatBRL writes an amount of reais held as a count of centavos, as BRL does, departing from it in what f says: R$ 1234,56 without the grouping, R$ 47 without the zero centavos. The sign, the symbol and the comma are BRL's, and every int64 is written.
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 ParseBRL ¶ added in v0.3.0
ParseBRL reads an amount in reais as a person types it into a form, and returns it as a count of centavos, or ErrInvalidBRL.
The amount may be led by the symbol, R$, with or without a space after it, and whitespace around the whole is ignored. The reais are digits, bare (1234) or grouped by dots in threes (1.234); a comma then gives one or two digits of centavos (1.234,56, and 1.234,5 for fifty centavos). An amount with no comma may instead give its centavos after a single dot, when that dot is followed by one or two digits and nothing else (1234.56): that is how an HTML number input submits a value, and no grouping of thousands leaves fewer than three digits after a dot. A dot followed by three digits always groups thousands, so 1.500 is fifteen hundred reais -- a number input that should take centavos says step="0.01", which keeps a third decimal out of it.
Everything else is refused: a sign, another currency or a lower-case r$, a space or a dot inside the digits other than as above, a group of other than three digits, a third digit of centavos, a comma with nothing after it, a digit outside ASCII, and an amount past the largest int64. Zero is an amount; a form that needs a positive one says so itself.
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 RedactCNPJ ¶ added in v0.3.0
RedactCNPJ writes a CNPJ with the positions r hides replaced, as r spells it.
It takes the fourteen characters bare or punctuated, as ParseCNPJ reads them, a lower-case letter shown as its capital, and does not check the check digits. For anything else, or a redaction of neither length, it returns "".
func RedactCPF ¶ added in v0.3.0
RedactCPF writes a CPF with the positions r hides replaced, as r spells it.
It takes the eleven digits bare or punctuated, as ParseCPF reads them, and does not check the check digits: a page that hides a stored value hides it whether or not it was ever valid. For anything else -- a value of another shape, or a redaction of neither length -- it returns "", and never the value it was given: a redaction that fell back to its input would print the document it exists to hide.
func ValidMobile ¶ added in v0.2.0
ValidMobile reports whether ParseMobile accepts s.
Types ¶
type BRLFormat ¶ added in v0.3.0
type BRLFormat struct {
// WithoutGrouping writes the reais with no dot between their thousands:
// R$ 1234,56.
WithoutGrouping bool
// WithoutZeroCents leaves the centavos off an amount of whole reais, the
// way a price list writes one: R$ 47, and still R$ 199,50.
WithoutZeroCents bool
}
BRLFormat is how FormatBRL departs from BRL. Its zero value departs in nothing, so each field names what it leaves out.
type Redaction ¶ added in v0.3.0
type Redaction string
A Redaction is how a page writes a document with part of it hidden, spelled the way the document is spelled: '#' shows the character in that position, and every other character is written as it stands.
"***.###.###-**" the fourth to the ninth digits of a CPF, punctuated "***######**" the same digits, bare "•••.###.###-••" the same digits, hidden behind bullets
A Redaction has the length, in characters, of either spelling of the document: the punctuated one (14 for a CPF, 18 for a CNPJ) or the bare one (11 and 14). Where the punctuated spelling holds a separator, the redaction writes its own character there, so it chooses the punctuation as well as the hiding. The length alone says which spelling a redaction is, so one written for a document of another kind is read as whichever of the two it measures, or refused.
The named redactions are the ones Brazilian sources publish and pages print. A redaction written as a literal is just as good: any string of one of the two lengths is one.
const ( // KeepCPFMiddle shows the fourth to the ninth digits of a CPF, punctuated: // ***.456.789-**. It is how the Portal da Transparência publishes the CPF // of a public agent. KeepCPFMiddle Redaction = "***.###.###-**" // KeepCPFMiddleBare shows the same six digits with no punctuation: // ***456789**. It is how the Receita Federal's open CNPJ data publishes the // CPF of a partner. KeepCPFMiddleBare Redaction = "***######**" // KeepCPFCheckDigits shows only the two check digits of a CPF, which // identify nobody: ***.***.***-00. KeepCPFCheckDigits Redaction = "***.***.***-##" // KeepCPFLastFive shows the last five digits of a CPF, as a profile page // reminds its owner which CPF it holds: ***.***.789-00. KeepCPFLastFive Redaction = "***.***.###-##" // KeepCNPJEnds shows the first two and the last two characters of a CNPJ: // 12.***.***/****-35. KeepCNPJEnds Redaction = "##.***.***/****-##" )
The redactions a page usually needs. Each is a constant of the type, so a call reads br.RedactCPF(cpf, br.KeepCPFMiddle).
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.