From 487b4c5628c02130580c675925a1d64b09a5f6cb Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:33:37 -0300 Subject: Carry the municipality of a CEP that does not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- src/lib.rs | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'src/lib.rs') 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"); -- cgit v1.3