From 497b1c1b01f6c9a584e5b40e02aff4763447529c Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:39:06 -0300 Subject: Report the municipality behind a CEP that does not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- src/main.zig | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'src/main.zig') diff --git a/src/main.zig b/src/main.zig index 6bb9777..77baae8 100644 --- a/src/main.zig +++ b/src/main.zig @@ -79,6 +79,13 @@ pub fn main(init: std.process.Init) !u8 { if (ceps.items.len == 1) { var address = client.lookup(ceps.items[0], .{ .diagnostics = &diag }) catch |err| { try out.print("{s}: {t}: {s}\n", .{ ceps.items[0], err, diag.message() }); + // Not an address — the lookup failed. Only where the number would + // have landed, which is usually the useful thing to say back. + if (diag.faixa()) |faixa| { + try out.print(" would be in {s}/{s}, which has {d} CEPs between {s} and {s}\n", .{ + faixa.localidade, faixa.uf, faixa.ceps, faixa.cep_ini, faixa.cep_fim, + }); + } return 1; }; defer address.deinit(gpa); -- cgit v1.3