% 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.
}