{ "$schema": "../cases.schema.json", "format": 1, "domain": "cep", "title": { "en": "CEP", "pt-BR": "CEP" }, "functions": [ { "id": "cep.format", "level": "core", "summary": "Formats a value as a Brazilian postal code (CEP).", "description": "Formats a CEP as `00000-000`.\n\n- `options.pad` left-pads the value with zeros to 8 digits first. Otherwise, a CEP that starts with `0` and comes as a number loses that zero.\n- Every character that is not a digit is removed, and digits past the 8th are dropped. An incomplete value is masked only as far as it goes (`010010` is `01001-0`).\n- Pending decision (findings §2 #2, #3): the reference (JS) formats only the characters an incomplete value has. It returns an empty string for empty or invalid input. The other libraries return `null`.\n- An empty value, or one without digits, returns an empty string even with `pad`. Until 2.4.0 `pad` returned the whole zero mask (`00000-000`).\n- A number is read only when it is a safe non-negative integer. Any other number (negative, fractional, non-finite) returns an empty string, with or without `pad`.", "params": [ { "name": "value", "type": "string | number" }, { "name": "options", "type": "FormatCepOptions", "optional": true } ], "returns": "string", "cases": [ { "id": "cep.format#[\"91906292\"]", "args": [ "91906292" ], "expect": { "returns": "91906-292" }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.format#[\"91906293\"]", "args": [ "91906293" ], "expect": { "returns": "91906-293" }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.format#[\"00000000\"]", "args": [ "00000000" ], "expect": { "returns": "00000-000" }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.format#[\"21749676\"]", "args": [ "21749676" ], "expect": { "returns": "21749-676" }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.format#[\"21749677\"]", "args": [ "21749677" ], "expect": { "returns": "21749-677" }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.format#[\"41790070\"]", "args": [ "41790070" ], "expect": { "returns": "41790-070" }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.format#[\"41790071\"]", "args": [ "41790071" ], "expect": { "returns": "41790-071" }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.format#[\"\"]", "args": [ "" ], "expect": { "returns": "" }, "note": "JavaScript's own test: should format CEP with mask" }, { "id": "cep.format#[\"0\"]", "args": [ "0" ], "expect": { "returns": "0" }, "note": "JavaScript's own test: should format CEP with mask" }, { "id": "cep.format#[\"01\"]", "args": [ "01" ], "expect": { "returns": "01" }, "note": "JavaScript's own test: should format CEP with mask" }, { "id": "cep.format#[\"010\"]", "args": [ "010" ], "expect": { "returns": "010" }, "note": "JavaScript's own test: should format CEP with mask" }, { "id": "cep.format#[\"0100\"]", "args": [ "0100" ], "expect": { "returns": "0100" }, "note": "JavaScript's own test: should format CEP with mask" }, { "id": "cep.format#[\"01001\"]", "args": [ "01001" ], "expect": { "returns": "01001" }, "note": "JavaScript's own test: should format CEP with mask" }, { "id": "cep.format#[\"010010\"]", "args": [ "010010" ], "expect": { "returns": "01001-0" }, "note": "JavaScript's own test: should format CEP with mask" }, { "id": "cep.format#[\"0100100\"]", "args": [ "0100100" ], "expect": { "returns": "01001-00" }, "note": "JavaScript's own test: should format CEP with mask" }, { "id": "cep.format#[\"01001000\"]", "args": [ "01001000" ], "expect": { "returns": "01001-000" }, "note": "JavaScript's own test: should format CEP with mask" }, { "id": "cep.format#[\"01001000000000\"]", "args": [ "01001000000000" ], "expect": { "returns": "01001-000" }, "note": "JavaScript's own test" }, { "id": "cep.format#[\"a0.10cr01?00#ab0\"]", "args": [ "a0.10cr01?00#ab0" ], "expect": { "returns": "01001-000" }, "note": "JavaScript's own test: should remove all non numeric characters" }, { "id": "cep.format#empty-with-pad", "args": [ "", { "pad": true } ], "expect": { "returns": "" }, "note": "changed in 2.5.0 (#615): a value with no digits gives an empty string even with pad; JavaScript's own test: should return an empty string for a value without digits even when padding" }, { "id": "cep.format#no-digits-with-pad", "args": [ "abc", { "pad": true } ], "expect": { "returns": "" }, "note": "JavaScript's own test: should return an empty string for a value without digits even when padding" }, { "id": "cep.format#pad", "args": [ "9250000", { "pad": true } ], "expect": { "returns": "09250-000" }, "note": "JavaScript docs example" }, { "id": "cep.format#number-pad", "args": [ 1310100, { "pad": true } ], "expect": { "returns": "01310-100" }, "note": "JavaScript docs example: pad left-pads a number" }, { "id": "cep.format#[\"92500000\"]", "args": [ "92500000" ], "expect": { "returns": "92500-000" }, "note": "JavaScript docs example" }, { "id": "cep.format#negative-number", "args": [ -92500000 ], "expect": { "returns": "" }, "note": "JavaScript docs example: not a non-negative safe integer" }, { "id": "cep.format#negative-number-pad", "args": [ -20040020, { "pad": true } ], "expect": { "returns": "" }, "note": "JavaScript's own test: when it is a negative, fractional or unsafe number" }, { "id": "cep.format#fractional-number", "args": [ 1.5 ], "expect": { "returns": "" }, "note": "JavaScript's own test: when it is a negative, fractional or unsafe number" }, { "id": "cep.format#unsafe-number", "args": [ 9007199254740992 ], "expect": { "returns": "" }, "note": "JavaScript's own test: when it is a negative, fractional or unsafe number" } ] }, { "id": "cep.generate", "level": "core", "summary": "Generates a random Brazilian CEP.", "description": "Generates a random CEP: 8 digits, unformatted.\n\n- A CEP has no check digit, so every 8-digit string is structurally valid.\n- The CEP is drawn inside the ranges the Correios assign to the states, each CEP with the same chance. It always belongs to a state, so `cep.getState` never returns `null` for it.\n- `00000-000` to `00999-999` and `78900-000` to `78999-999`, which no state owns, are never generated. Until 2.4.0 any 8-digit string could come out, about 1 in 90 of them in one of those two ranges.\n- A range is the block a state owns, not a promise that every CEP in it is in use, so the CEP generated may not be the CEP of a real address.", "params": [], "returns": "string", "cases": [ { "id": "cep.generate#generated-is-valid", "args": [], "expect": { "satisfies": "cep.isValid" }, "repeat": 5, "note": "every generated value must pass the lib's own validator" } ] }, { "id": "cep.getAddressInfo", "level": "core", "summary": "Fetches the address information for a CEP from several providers at the same time.", "description": "Fetches the address of a CEP from several providers at once and returns the first successful answer (network call).\n\n- A string `cep` has every character that is not a digit removed (`\"CEP 01310-100\"` works). Exactly 8 digits must remain.\n- A number must be a safe non-negative integer. It is left-padded with zeros to 8 digits only from `1000000` (`01000-000`, the lowest CEP the Correios assign). A smaller number is rejected. 2.4.0 padded any number, so `123` was looked up as `00000-123`.\n- The result carries `cep` (8 digits, no mask), `state` (two-letter code), `city`, `neighborhood` and `street`. `neighborhood` and `street` are empty when the CEP covers a whole city.\n- `options.providers` picks which providers to query. The function retries transient network failures per provider.\n- `options.timeoutMs` limits the whole lookup, retries included. When it runs out, the call fails with a service error. It must be a positive finite number.\n- `options.signal` (an `AbortSignal` in JavaScript) cancels the lookup, and the call fails with the signal's reason, as `fetch` does. A signal that is already aborted fails before any request. Without these options the lookup has no time limit.\n- Fails with an error. The error tells apart an invalid CEP or option, a CEP that no provider knows, and a service failure.\n- A provider being down is not \"not found\". BrasilAPI answers 404 both for an unknown CEP and when its own backends fail. Its 404 counts as not found only when no other provider failed to answer (a network error or an HTTP error status). Next to such a failure, the call fails with a service error. A lone BrasilAPI 404, or a BrasilAPI 404 together with ViaCEP's `erro: true`, is still not found. 2.4.0 let the 404 win, so an outage could be reported as an unknown CEP.\n- An address is only accepted when it agrees with the CEP asked for: its digits, left-padded with zeros to 8 digits, must be the CEP (a provider that answers `1310100` for `01310-100` means the same CEP and is accepted, while `1310101` is another CEP and is not), and its state, when it names one, must be the state that owns the CEP range (see `cep.getState`). Otherwise that provider counts as not knowing the CEP. BrasilAPI, for instance, answered `99999-999`, a Rio Grande do Sul CEP, with a city of Paraná. Until 2.4.0 such an answer was returned.\n- Once the lookup settles, the requests of the providers that lost the race are aborted.\n- `options.providers` accepts `viacep`, `brasilapi` and `widenet`, raced in the order given (default `[\"viacep\", \"brasilapi\"]`). A name that is not a known provider is ignored. A list with no known provider is an invalid option. `widenet` is deprecated and left out of the default list: its endpoint now redirects to `ws.apicep.com`, which is usually unavailable, so it only adds a failing provider to the race.", "params": [ { "name": "cep", "type": "string | number" }, { "name": "options", "type": "GetAddressInfoByCepOptions", "optional": true } ], "returns": "AddressInfo", "network": true, "cases": [] }, { "id": "cep.getInfoByAddress", "level": "core", "summary": "Looks up every CEP of a Brazilian street on the ViaCEP API.", "description": "Looks up every CEP of a street on the ViaCEP service (network call).\n\n- `params` carries the state (federative unit, read ignoring case and surrounding whitespace), the city and the street. Before the query, the function trims the city and the street and removes their accents.\n- Each result is the ViaCEP record unchanged, under ViaCEP's own field names: `cep` (masked, `00000-000`), `logradouro`, `complemento`, `unidade`, `bairro`, `localidade`, `uf`, `estado`, `regiao`, `ibge`, `gia`, `ddd` and `siafi`. A field the service adds later is passed through too.\n- The function retries transient network failures.\n- Fails with an error. The error tells apart a missing or invalid state/city/street, an address with no match, and an HTTP error from the service.\n- A request that cannot be performed at all (no connection, for example) fails with the underlying network error, not with one of these errors.\n- `params.federalUnit` is the two-letter state code, for example `SP`. It must be a string and a known UF. `params.city` and `params.street` are the city and the street name (or part of it).\n- `city` and `street` must be strings with at least 3 characters once trimmed and stripped of accents, the minimum ViaCEP accepts. A blank value, a value that is not a string, or one under 3 characters fails with the validation error before any request.\n- A `params` that is not an object (omitted, `null`, a string) and a `federalUnit` that is not a string fail with the validation error too.\n- ViaCEP caps the list at 50 addresses, so a short street name that matches more streets returns only the first 50.", "params": [ { "name": "params", "type": "GetCepInfoByAddressParams" } ], "returns": "CepAddressInfo[]", "network": true, "cases": [] }, { "id": "cep.getState", "level": "extended", "summary": "Gets the Brazilian state a CEP belongs to, from the CEP ranges of each state.", "description": "Returns the state that owns the CEP range a CEP falls in. It runs offline: the answer comes from a table of ranges, not from a network call.\n\n- `value` is read as `cep.isValid` reads it: 8 digits, as a string or a number, with spaces, dots, hyphens and slashes ignored.\n- A number must be a non-negative integer: `-20040020` and `2004002.5` return `null`. A CEP that starts with `0` must be passed as a string.\n- The result is the same object as `state.getByIbgeCode` and `state.list` return (a new copy each call).\n- Returns `null` for an invalid CEP, a value that is neither a string nor a number, and a CEP outside every range.\n- Two blocks belong to no state: `00000-000` to `00999-999`, and `78900-000` to `78999-999`. In the second one, MT ends at `78899-999`.\n- A range is the block assigned to a state. It does not mean every CEP inside it is in use. SP is one range, so `10000-000` returns SP although no city uses `10xxx`.\n- The table is the answer of the Correios \"Busca Faixa de CEP\" search when only the state is given.\n\n| UF | CEP |\n|---|---|\n| SP | 01000-000 to 19999-999 |\n| RJ | 20000-000 to 28999-999 |\n| ES | 29000-000 to 29999-999 |\n| MG | 30000-000 to 39999-999 |\n| BA | 40000-000 to 48999-999 |\n| SE | 49000-000 to 49999-999 |\n| PE | 50000-000 to 56999-999 |\n| AL | 57000-000 to 57999-999 |\n| PB | 58000-000 to 58999-999 |\n| RN | 59000-000 to 59999-999 |\n| CE | 60000-000 to 63999-999 |\n| PI | 64000-000 to 64999-999 |\n| MA | 65000-000 to 65999-999 |\n| PA | 66000-000 to 68899-999 |\n| AP | 68900-000 to 68999-999 |\n| AM | 69000-000 to 69299-999 and 69400-000 to 69899-999 |\n| RR | 69300-000 to 69399-999 |\n| AC | 69900-000 to 69999-999 |\n| DF | 70000-000 to 72799-999 and 73000-000 to 73699-999 |\n| GO | 72800-000 to 72999-999 and 73700-000 to 76799-999 |\n| RO | 76800-000 to 76999-999 |\n| TO | 77000-000 to 77999-999 |\n| MT | 78000-000 to 78899-999 |\n| MS | 79000-000 to 79999-999 |\n| PR | 80000-000 to 87999-999 |\n| SC | 88000-000 to 89999-999 |\n| RS | 90000-000 to 99999-999 |", "params": [ { "name": "value", "type": "string | number" } ], "returns": "State?", "cases": [ { "id": "cep.getState#[\"01310-100\"]", "args": [ "01310-100" ], "expect": { "returns": { "code": "SP", "name": "São Paulo", "regionCode": "SE", "regionName": "Sudeste", "ibgeCode": 35 } }, "note": "from the maintainer briefing, #562" }, { "id": "cep.getState#df-block-goias", "args": [ "72800-000" ], "expect": { "returns": { "code": "GO", "name": "Goiás", "regionCode": "CO", "regionName": "Centro-Oeste", "ibgeCode": 52 } }, "note": "from the maintainer briefing, #562: between the two DF blocks, the range belongs to GO" }, { "id": "cep.getState#gap-after-mt", "args": [ "78900-000" ], "expect": { "returns": null }, "note": "from the maintainer briefing, #562: MT ends at 78899-999" }, { "id": "cep.getState#number", "args": [ 20040020 ], "expect": { "returns": { "code": "RJ", "name": "Rio de Janeiro", "regionCode": "SE", "regionName": "Sudeste", "ibgeCode": 33 } }, "note": "JavaScript's own test: should accept a number" }, { "id": "cep.getState#[\"92.500-000\"]", "args": [ "92.500-000" ], "expect": { "returns": { "code": "RS", "name": "Rio Grande do Sul", "regionCode": "S", "regionName": "Sul", "ibgeCode": 43 } }, "note": "JavaScript's own test: should ignore spaces, dots and hyphens" }, { "id": "cep.getState#[\"70 040 010\"]", "args": [ "70 040 010" ], "expect": { "returns": { "code": "DF", "name": "Distrito Federal", "regionCode": "CO", "regionName": "Centro-Oeste", "ibgeCode": 53 } }, "note": "JavaScript's own test: should ignore spaces, dots and hyphens" }, { "id": "cep.getState#[\" 01310-100 \"]", "args": [ " 01310-100 " ], "expect": { "returns": { "code": "SP", "name": "São Paulo", "regionCode": "SE", "regionName": "Sudeste", "ibgeCode": 35 } } }, { "id": "cep.getState#[\"69300-000\"]", "args": [ "69300-000" ], "expect": { "returns": { "code": "RR", "name": "Roraima", "regionCode": "N", "regionName": "Norte", "ibgeCode": 14 } }, "note": "JavaScript's own test: should resolve the ranges of the North" }, { "id": "cep.getState#[\"69050000\"]", "args": [ "69050000" ], "expect": { "returns": { "code": "AM", "name": "Amazonas", "regionCode": "N", "regionName": "Norte", "ibgeCode": 13 } }, "note": "JavaScript's own test: should resolve both ranges of the states with two" }, { "id": "cep.getState#[\"69650000\"]", "args": [ "69650000" ], "expect": { "returns": { "code": "AM", "name": "Amazonas", "regionCode": "N", "regionName": "Norte", "ibgeCode": 13 } }, "note": "JavaScript's own test: should resolve both ranges of the states with two" }, { "id": "cep.getState#[\"72799999\"]", "args": [ "72799999" ], "expect": { "returns": { "code": "DF", "name": "Distrito Federal", "regionCode": "CO", "regionName": "Centro-Oeste", "ibgeCode": 53 } } }, { "id": "cep.getState#[\"73350000\"]", "args": [ "73350000" ], "expect": { "returns": { "code": "DF", "name": "Distrito Federal", "regionCode": "CO", "regionName": "Centro-Oeste", "ibgeCode": 53 } }, "note": "JavaScript's own test: should resolve both ranges of the states with two" }, { "id": "cep.getState#[\"72900000\"]", "args": [ "72900000" ], "expect": { "returns": { "code": "GO", "name": "Goiás", "regionCode": "CO", "regionName": "Centro-Oeste", "ibgeCode": 52 } }, "note": "JavaScript's own test: should resolve both ranges of the states with two" }, { "id": "cep.getState#[\"73700000\"]", "args": [ "73700000" ], "expect": { "returns": { "code": "GO", "name": "Goiás", "regionCode": "CO", "regionName": "Centro-Oeste", "ibgeCode": 52 } } }, { "id": "cep.getState#[\"74000000\"]", "args": [ "74000000" ], "expect": { "returns": { "code": "GO", "name": "Goiás", "regionCode": "CO", "regionName": "Centro-Oeste", "ibgeCode": 52 } }, "note": "JavaScript's own test: should resolve both ranges of the states with two" }, { "id": "cep.getState#[\"10000000\"]", "args": [ "10000000" ], "expect": { "returns": { "code": "SP", "name": "São Paulo", "regionCode": "SE", "regionName": "Sudeste", "ibgeCode": 35 } }, "note": "JavaScript's own test: should answer the owner of the range even for a CEP no city uses" }, { "id": "cep.getState#[\"01000000\"]", "args": [ "01000000" ], "expect": { "returns": { "code": "SP", "name": "São Paulo", "regionCode": "SE", "regionName": "Sudeste", "ibgeCode": 35 } } }, { "id": "cep.getState#[\"68899999\"]", "args": [ "68899999" ], "expect": { "returns": { "code": "PA", "name": "Pará", "regionCode": "N", "regionName": "Norte", "ibgeCode": 15 } } }, { "id": "cep.getState#[\"68900000\"]", "args": [ "68900000" ], "expect": { "returns": { "code": "AP", "name": "Amapá", "regionCode": "N", "regionName": "Norte", "ibgeCode": 16 } } }, { "id": "cep.getState#[\"69900000\"]", "args": [ "69900000" ], "expect": { "returns": { "code": "AC", "name": "Acre", "regionCode": "N", "regionName": "Norte", "ibgeCode": 12 } } }, { "id": "cep.getState#[\"76800000\"]", "args": [ "76800000" ], "expect": { "returns": { "code": "RO", "name": "Rondônia", "regionCode": "N", "regionName": "Norte", "ibgeCode": 11 } } }, { "id": "cep.getState#[\"78899999\"]", "args": [ "78899999" ], "expect": { "returns": { "code": "MT", "name": "Mato Grosso", "regionCode": "CO", "regionName": "Centro-Oeste", "ibgeCode": 51 } } }, { "id": "cep.getState#[\"79000000\"]", "args": [ "79000000" ], "expect": { "returns": { "code": "MS", "name": "Mato Grosso do Sul", "regionCode": "CO", "regionName": "Centro-Oeste", "ibgeCode": 50 } } }, { "id": "cep.getState#[\"99999999\"]", "args": [ "99999999" ], "expect": { "returns": { "code": "RS", "name": "Rio Grande do Sul", "regionCode": "S", "regionName": "Sul", "ibgeCode": 43 } } }, { "id": "cep.getState#[\"00000000\"]", "args": [ "00000000" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null in the gap below 01000-000" }, { "id": "cep.getState#[\"00999999\"]", "args": [ "00999999" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null in the gap below 01000-000" }, { "id": "cep.getState#[\"78950000\"]", "args": [ "78950000" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null in the gap after Mato Grosso" }, { "id": "cep.getState#[\"78999999\"]", "args": [ "78999999" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null in the gap after Mato Grosso" }, { "id": "cep.getState#[\"12345\"]", "args": [ "12345" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null for an invalid CEP" }, { "id": "cep.getState#[\"013101000\"]", "args": [ "013101000" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null for an invalid CEP" }, { "id": "cep.getState#empty", "args": [ "" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null for an invalid CEP" }, { "id": "cep.getState#[\"abc01310100\"]", "args": [ "abc01310100" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null for a CEP with letters" }, { "id": "cep.getState#[\"01310-10a\"]", "args": [ "01310-10a" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null for a CEP with letters" }, { "id": "cep.getState#[\"CEP 01310-100\"]", "args": [ "CEP 01310-100" ], "expect": { "returns": null } }, { "id": "cep.getState#[\"__proto__\"]", "args": [ "__proto__" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null for a value that is neither a string nor a number" }, { "id": "cep.getState#seven-digit-number", "args": [ 1310100 ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null for a number that is not 8 digits: a CEP starting with 0 must be a string" }, { "id": "cep.getState#[-20040020]", "args": [ -20040020 ], "expect": { "returns": null }, "note": "from the maintainer briefing, #562: a negative number is rejected" }, { "id": "cep.getState#[2004002.5]", "args": [ 2004002.5 ], "expect": { "returns": null }, "note": "from the maintainer briefing, #562: a fractional number is rejected" }, { "id": "cep.getState#[null]", "args": [ null ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null for a value that is neither a string nor a number" } ] }, { "id": "cep.isValid", "level": "core", "summary": "Checks whether a CEP is valid.", "description": "Validates a CEP: exactly 8 digits.\n\n- `cep` may be a string or a number. A CEP that starts with `0` must be a string.\n- Pending decision (findings §2 #1): the reference (JS) ignores spaces, dots and hyphens (`01310-200` is valid). The other libraries accept digits only.\n- Spaces, dots, hyphens and slashes are ignored, wherever they appear. Any other character makes the value invalid.\n- A number is read only when it is a safe non-negative integer: `-20040020` and `2004002.1` are invalid. `isValid` and `getState` read the number `1310100` as 7 digits and reject it, while `getAddressInfo` and `format` with `pad` left-pad it.", "params": [ { "name": "cep", "type": "string | number" } ], "returns": "boolean", "cases": [ { "id": "cep.isValid#[\"91906292\"]", "args": [ "91906292" ], "expect": { "returns": true }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.isValid#[\"91906293\"]", "args": [ "91906293" ], "expect": { "returns": true }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.isValid#[\"00000000\"]", "args": [ "00000000" ], "expect": { "returns": true }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.isValid#[\"21749676\"]", "args": [ "21749676" ], "expect": { "returns": true }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.isValid#[\"21749677\"]", "args": [ "21749677" ], "expect": { "returns": true }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.isValid#[\"41790070\"]", "args": [ "41790070" ], "expect": { "returns": true }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.isValid#[\"41790071\"]", "args": [ "41790071" ], "expect": { "returns": true }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.isValid#[\"\"]", "args": [ "" ], "expect": { "returns": false }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.isValid#[\" \"]", "args": [ " " ], "expect": { "returns": false }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.isValid#[\"abc\"]", "args": [ "abc" ], "expect": { "returns": false }, "note": "consensus of 5 libs (go, javascript, python, ruby, rust)" }, { "id": "cep.isValid#[\"12345\"]", "args": [ "12345" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when length is less than 8" }, { "id": "cep.isValid#[\"123456789\"]", "args": [ "123456789" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when length is greater than 8" }, { "id": "cep.isValid#[\"abc01310100\"]", "args": [ "abc01310100" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when it contains letters" }, { "id": "cep.isValid#[\"0131010a\"]", "args": [ "0131010a" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when it contains letters" }, { "id": "cep.isValid#[\"01310100\"]", "args": [ "01310100" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when is a CEP valid without mask" }, { "id": "cep.isValid#[\"01310-100\"]", "args": [ "01310-100" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when is a CEP valid with mask" }, { "id": "cep.isValid#[20040020]", "args": [ 20040020 ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when is a CEP valid as a number" }, { "id": "cep.isValid#[\" 01310-100 \"]", "args": [ " 01310-100 " ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when is a CEP valid with leading/trailing whitespace" }, { "id": "cep.isValid#[\"92.500-000\"]", "args": [ "92.500-000" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when is a CEP valid with any punctuation the published version accepted" }, { "id": "cep.isValid#[\"013 10 100\"]", "args": [ "013 10 100" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when is a CEP valid with any punctuation the published version accepted" }, { "id": "cep.isValid#[\"01310.100\"]", "args": [ "01310.100" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when is a CEP valid with any punctuation the published version accepted" }, { "id": "cep.isValid#[\"01310/100\"]", "args": [ "01310/100" ], "expect": { "returns": true }, "note": "JavaScript's own test: when the mask uses a slash, one of the mask characters isValidCpf reads" }, { "id": "cep.isValid#[\"0131/0100\"]", "args": [ "0131/0100" ], "expect": { "returns": true }, "note": "JavaScript's own test: when is a CEP valid with slashes, which the mask characters include" }, { "id": "cep.isValid#[\"--0131 0100\"]", "args": [ "--0131 0100" ], "expect": { "returns": true }, "note": "JavaScript's own test: when is a CEP valid with slashes, which the mask characters include" }, { "id": "cep.isValid#[\"01310/100/\"]", "args": [ "01310/100/" ], "expect": { "returns": true }, "note": "JavaScript's own test: when is a CEP valid with slashes, which the mask characters include" }, { "id": "cep.isValid#[-20040020]", "args": [ -20040020 ], "expect": { "returns": false }, "note": "JavaScript's own test: when it is a negative or fractional number" }, { "id": "cep.isValid#[2004002.1]", "args": [ 2004002.1 ], "expect": { "returns": false }, "note": "JavaScript's own test: when it is a negative or fractional number" }, { "id": "cep.isValid#seven-digit-number", "args": [ 1310100 ], "expect": { "returns": false }, "note": "JavaScript docs: a 7-digit number is rejected, the leading zero is lost" }, { "id": "cep.isValid#[\"9250000A\"]", "args": [ "9250000A" ], "expect": { "returns": false }, "note": "JavaScript docs example" }, { "id": "cep.isValid#[null]", "args": [ null ], "expect": { "returns": false }, "note": "JavaScript's own test: when it is null" } ] }, { "id": "cep.parse", "level": "extended", "summary": "Removes the formatting characters of a CEP and returns only the digits.", "description": "Removes CEP formatting and keeps only digits, capped at 8 digits.\n\n- Non-digit characters are removed, and the result is capped at 8 digits.\n- A number is read only when it is a safe non-negative integer. Any other number (negative, fractional, non-finite, past the safe range) returns an empty string. `null` and other values that are neither a string nor a number return an empty string.", "params": [ { "name": "value", "type": "string | number" } ], "returns": "string", "cases": [ { "id": "cep.parse#masked", "args": [ "01001-000" ], "expect": { "returns": "01001000" } }, { "id": "cep.parse#unmasked", "args": [ "01001000" ], "expect": { "returns": "01001000" } }, { "id": "cep.parse#strips-non-digits", "args": [ "a0.10cr01?00#ab0" ], "expect": { "returns": "01001000" } }, { "id": "cep.parse#empty", "args": [ "" ], "expect": { "returns": "" } }, { "id": "cep.parse#caps-length", "args": [ "01001000123" ], "expect": { "returns": "01001000" }, "note": "reference truncates to the 8 characters of the document; asserted by the reference (JS) unit tests" }, { "id": "cep.parse#[\"91906292\"]", "args": [ "91906292" ], "expect": { "returns": "91906292" }, "note": "consensus of 3 libs (python, ruby, rust)" }, { "id": "cep.parse#[\"91906293\"]", "args": [ "91906293" ], "expect": { "returns": "91906293" }, "note": "consensus of 3 libs (python, ruby, rust)" }, { "id": "cep.parse#[\"00000000\"]", "args": [ "00000000" ], "expect": { "returns": "00000000" }, "note": "consensus of 3 libs (python, ruby, rust)" }, { "id": "cep.parse#[\"21749676\"]", "args": [ "21749676" ], "expect": { "returns": "21749676" }, "note": "consensus of 3 libs (python, ruby, rust)" }, { "id": "cep.parse#[\"21749677\"]", "args": [ "21749677" ], "expect": { "returns": "21749677" }, "note": "consensus of 3 libs (python, ruby, rust)" }, { "id": "cep.parse#[\"41790070\"]", "args": [ "41790070" ], "expect": { "returns": "41790070" }, "note": "consensus of 3 libs (python, ruby, rust)" }, { "id": "cep.parse#[\"41790071\"]", "args": [ "41790071" ], "expect": { "returns": "41790071" }, "note": "consensus of 3 libs (python, ruby, rust)" }, { "id": "cep.parse#[\"91906-292\"]", "args": [ "91906-292" ], "expect": { "returns": "91906292" }, "note": "consensus of 3 libs (python, ruby, rust)" }, { "id": "cep.parse#[\"21749-676\"]", "args": [ "21749-676" ], "expect": { "returns": "21749676" }, "note": "consensus of 3 libs (python, ruby, rust)" }, { "id": "cep.parse#[\"41790-070\"]", "args": [ "41790-070" ], "expect": { "returns": "41790070" }, "note": "consensus of 3 libs (python, ruby, rust)" }, { "id": "cep.parse#negative-number", "args": [ -20040020 ], "expect": { "returns": "" }, "note": "JavaScript's own test: when it is a negative, fractional or unsafe number" }, { "id": "cep.parse#fractional-number", "args": [ 1.5 ], "expect": { "returns": "" }, "note": "JavaScript's own test: when it is a negative, fractional or unsafe number" }, { "id": "cep.parse#unsafe-number", "args": [ 9007199254740992 ], "expect": { "returns": "" }, "note": "JavaScript's own test: when it is a negative, fractional or unsafe number" }, { "id": "cep.parse#null", "args": [ null ], "expect": { "returns": "" }, "note": "JavaScript's own test: should return an empty string for null" }, { "id": "cep.parse#number", "args": [ 20040020 ], "expect": { "returns": "20040020" }, "note": "number input" } ] } ] }