Report the municipality a missing CEP would have belonged toHEADv0.2.0main

A CEP that fails a lookup is rarely a random number: it is usually someone
who knows the city and guessed, and the classic guess is the -000 that 957
municipalities never received. The API now answers those 404s with a faixa
naming the municipality that owns the band the number fell into, which is
the difference between telling a user "invalid CEP" and "no such CEP in
Areal/RJ".

It is context for an error and never an address, so it rides on the
cepis_not_found condition instead of turning the failure into a success,
and cep_ini/cep_fim are the endpoints that exist rather than the range the
Correios publish - the interval between them is sparse, which is what ceps
counts. Parsing is deliberately unable to signal: a faixa that is null, an
array, a string or half a body leaves a clean not-found behind, because the
caller asked for the CEP, not for the decoration on its absence.

1 files changed, 53 insertions, 0 deletions

diff --git a/man/cepis_faixa.Rd b/man/cepis_faixa.Rd
new file mode 100644
index 0000000..5d3f7ff
--- /dev/null
+++ b/man/cepis_faixa.Rd
@@ -0,0 +1,53 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/models.R
+\name{cepis_faixa}
+\alias{cepis_faixa}
+\title{The municipality a CEP that does not exist would have belonged to}
+\description{
+The \code{faixa} field of a \link[=cepis_conditions]{cepis_not_found} condition, a
+plain list of class \code{cepis_faixa}. It is \strong{context for an error, not an
+address}: the CEP asked for does not exist, and nothing here says
+otherwise. What it does say is which municipality owns the band of numbers
+the CEP fell into.
+
+It exists because a CEP that fails is rarely random — it is usually
+someone who knows the city and guessed the number, and the classic guess is
+the \code{-000} that 957 municipalities never received.
+}
+\section{Fields}{
+
+\describe{
+\item{\code{localidade}, \code{uf}, \code{estado}, \code{regiao}}{municipality, state code,
+state name, region — the same names, and the same meaning, as in a
+\link{cepis_address}.}
+\item{\code{ibge}}{the municipality's IBGE code, so the answer can be joined
+to other data without matching on the name.}
+\item{\code{cep_ini}, \code{cep_fim}}{the smallest and the largest CEP that
+\strong{actually exists} in that municipality. Not the range the Correios
+publish: the DNE's own start for Areal/RJ is \code{25845000}, which is
+precisely the CEP that just failed.}
+\item{\code{ceps}}{how many CEPs the municipality really has.}
+}
+}
+
+\section{The range is sparse}{
+
+Areal's 118 CEPs are scattered over the ~4900 numbers between \code{25845001}
+and \code{25849899}. \code{cep_ini} and \code{cep_fim} are two endpoints that exist, not a
+promise about anything in between — never present the pair as a list of
+valid CEPs, and never iterate from one to the other. \code{ceps} is there so the
+emptiness of the interval is visible: 118 out of 4899.
+}
+
+\section{When there is no faixa}{
+
+\code{NULL}, and not a list of empty strings, when the CEP falls in a band no
+municipality owns. The API \strong{omits} the field rather than sending null,
+and this package keeps that distinction intact: \code{is.null(x$faixa)} means
+the number is close to nothing, not that the fields came back blank.
+
+Only \code{\link[=cep_lookup]{cep_lookup()}} reports it. In \code{\link[=cep_lookup_many]{cep_lookup_many()}} a CEP that does not
+exist is still \code{NULL} at its position: the endpoint behind a batch is CSV
+and says nothing about ranges.
+}
+