Carry the municipality of a CEP that does not existHEADv0.2.0main

A 404 from the API now brings a "faixa" naming the municipality the CEP
would have belonged to, and NotFound carries it. A CEP that fails is
rarely a random number: it is usually someone who knows the city and
guessed the digits, so naming the city turns a dead end into an answer
the caller can show.

It stays an error. The range it carries is the CEPs that actually exist
there, not the bounds the Correios publish — those start at the very CEP
that just failed — and it is sparse, which is what "ceps" measures. The
field is decoration on a failure, so parsing it is entirely defensive:
absent, null or malformed all yield None rather than costing a clean
not-found.

Breaking: NotFound gained a field, hence 0.2.0.

1 files changed, 16 insertions, 1 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 84262d7..686520f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -44,6 +44,21 @@
 //! }
 //! ```
 //!
+//! A CEP that does not exist is rarely a random number — usually someone knew
+//! the city and guessed the digits. So [`Error::NotFound`] carries the
+//! municipality that CEP would have belonged to, when the API can name one:
+//!
+//! ```no_run
+//! # let cep_from_form = "25845000";
+//! if let Err(err @ cepis::Error::NotFound { .. }) = cepis::lookup(cep_from_form) {
+//!     match err.faixa() {
+//!         // "no such CEP in Areal/RJ" — still not found, just better phrased
+//!         Some(faixa) => println!("no such CEP in {}", faixa.municipality()),
+//!         None => println!("no such CEP"),
+//!     }
+//! }
+//! ```
+//!
 //! 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.
@@ -65,7 +80,7 @@ pub use crate::client::{
     Client, ClientBuilder, DEFAULT_URL, MAX_BATCH, RETRIABLE_STATUS, normalize_cep,
 };
 pub use crate::error::{Error, Result};
-pub use crate::model::{Address, Geo, Health};
+pub use crate::model::{Address, Faixa, Geo, Health};
 
 /// The version of this library, as sent in the `User-Agent`.
 pub const VERSION: &str = env!("CARGO_PKG_VERSION");