diff options
| author | Murilo Ijanc <[email protected]> | 2026-07-27 20:39:06 -0300 |
|---|---|---|
| committer | Murilo Ijanc <[email protected]> | 2026-07-27 20:39:06 -0300 |
| commit | 497b1c1b01f6c9a584e5b40e02aff4763447529c (patch) | |
| tree | b50feb4252ba93cf045be3aaac14a96eeb04dff5 /src/root.zig | |
| parent | 87166a5299aa551517a86379a0c05eb2110b52b0 (diff) | |
| download | zig-497b1c1b01f6c9a584e5b40e02aff4763447529c.tar.gz | |
A CEP that fails to resolve is rarely a random number. It is almost always
someone who knows the city and guessed the digits, and the classic guess is
the -000 that 957 municipalities never received. The API now says so: a 404
carries an optional faixa block naming the municipality the number would have
belonged to, and answering "no such CEP in Areal/RJ, which has 118 of them" is
a great deal more useful than "not found".
It arrives through Diagnostics, which is where every other detail a Zig error
tag cannot carry already travels, and it is read with diag.faixa(). Like
message(), it lives in a fixed buffer inside the value and allocates nothing,
so no caller has to learn a new deinit for it.
The lookup still fails. faixa is context for the error, never an address, and
cep_ini/cep_fim are the smallest and largest CEP that actually exist there
rather than the bounds the Correios publish — for Areal the DNE's own start is
25845000, which is exactly the CEP that failed. The range is also sparse, 118
CEPs over ~4,900 numbers, so ceps is the count and the pair must never be
presented as a list. The doc comments and the README say all three, because
this field is easy to misread as a success.
Parsing is deliberately inert: a faixa that is missing, null, not an object,
nameless or oversized yields null, and an unreadable body is skipped. Nothing
about this field may promote a clean not-found into a parse failure.
Diffstat (limited to 'src/root.zig')
| -rw-r--r-- | src/root.zig | 5 |
1 files changed, 5 insertions, 0 deletions
diff --git a/src/root.zig b/src/root.zig index 0a83c5c..d97c8ea 100644 --- a/src/root.zig +++ b/src/root.zig @@ -44,6 +44,10 @@ //! }; //! ``` //! +//! After `error.NotFound`, `diag.faixa()` may name the municipality the CEP +//! would have belonged to. It is context for the failure and never an address — +//! see `Faixa`. +//! //! Note on field names: the API surface is English, but the **data fields keep //! the API's own Portuguese names** (`logradouro`, `bairro`, `localidade`). //! What you read in the JSON is what you access on the value. @@ -77,6 +81,7 @@ pub const Diagnostics = errors.Diagnostics; pub const isRetriable = errors.isRetriable; pub const Address = model.Address; +pub const Faixa = model.Faixa; pub const Geo = model.Geo; pub const Health = model.Health; |