Expose the municipality behind a not-found CEPHEADv0.2.0main

A CEP that fails a lookup is rarely random: it is usually someone who
knows the city and guessed the number, and the classic guess is the -000
that 957 municipalities never received. The API now names, on the 404
itself, the municipality that CEP would have belonged to, so a caller can
say "not found — did you mean somewhere in Areal/RJ?" instead of just
"not found".

CepNotFound carries it as an optional Faixa. It stays an error: the block
is context, not an address, and the range it describes is sparse, which
is why it reports a count alongside the first and last CEP that actually
exist there rather than the bounds the Correios publish. Parsing it is
best-effort on purpose — a missing, empty or malformed block leaves the
optional empty, since a 404 is already the answer and reading the hint
attached to it must never cost the diagnosis.

1 files changed, 4 insertions, 2 deletions

diff --git a/include/cepis/cepis.hpp b/include/cepis/cepis.hpp
index 4ac3f1f..1861d88 100644
--- a/include/cepis/cepis.hpp
+++ b/include/cepis/cepis.hpp
@@ -28,8 +28,10 @@
 /// ```cpp
 /// try {
 ///   const cepis::Address a = cepis::lookup(cep_from_form);
-/// } catch (const cepis::CepNotFound&) {
-///   // the CEP does not exist: ask the user for another
+/// } catch (const cepis::CepNotFound& error) {
+///   // the CEP does not exist: ask the user for another. `error.faixa()`
+///   // often names the municipality it would have belonged to — context for
+///   // the message, never an address.
 /// } catch (const cepis::Error&) {
 ///   // network, server, rate limit: retry later
 /// }