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

A CEP that fails is rarely a random number. It is usually someone who
knows the city and guessed the last digits, and the classic guess is the
-000 that 957 municipalities never received. The API now answers those
404s with a faixa block naming the municipality the CEP would have
belonged to, and telling a caller "that CEP does not exist, did you mean
somewhere in Areal/RJ?" is worth far more than telling them "no".

It rides on cepis_error_t rather than on cepis_address_t because it is
context for a failure, not an address: the lookup still returns
CEPIS_ERR_NOT_FOUND and still hands back no address. Embedded by value
with a has_faixa flag, so the error keeps owning nothing and keeps
living on the stack with nothing to free; cepis_error_faixa gives the
absent case the same NULL-or-not shape as cepis_address_t::geo, which is
what the API's omit-never-null encoding calls for.

Parsing is total on purpose. A body that is not JSON, a faixa that is
null, a string, an array, or an object with no localidade all mean "the
API named no municipality". A 404 is already the answer, and failing to
read the garnish must never turn it into a different one.

The bounds need reading with care, hence the length of the comments:
cep_ini and cep_fim are the smallest and largest CEP that actually
exist, not the range the Correios publish -- the DNE's own start for
Areal is 25845000, exactly the CEP that just failed -- and the range is
sparse, 118 CEPs scattered over the ~4900 numbers up to 25849899. That
is what ceps is for.

1 files changed, 8 insertions, 0 deletions

diff --git a/src/cli.c b/src/cli.c
index e4c9bd4..009de33 100644
--- a/src/cli.c
+++ b/src/cli.c
@@ -157,8 +157,16 @@ int main(int argc, char **argv)
         if (count == 1) {
                 cepis_address_t *address = NULL;
                 if (cepis_lookup(client, ceps[0], &address, &err) != CEPIS_OK) {
+                        const cepis_faixa_t *faixa = cepis_error_faixa(&err);
                         fprintf(stderr, "error: %s: %s\n",
                                 cepis_status_str(err.status), err.message);
+                        if (faixa != NULL)
+                                fprintf(stderr,
+                                        "note: it would be in %s/%s, where "
+                                        "%lld CEP(s) exist between %s and %s\n",
+                                        faixa->localidade, faixa->uf,
+                                        faixa->ceps, faixa->cep_ini,
+                                        faixa->cep_fim);
                         status = 1;
                 } else {
                         print_address(address);