Module brutils_cep

Description
Data Types
Function Index
Function Details

Utilities for the Brazilian CEP (Código de Endereçamento Postal).

Description

Utilities for the Brazilian CEP (Código de Endereçamento Postal).

A CEP is an 8-digit postal code, commonly displayed as "NNNNN-NNN". It carries no check digit: validation is purely structural and says nothing about whether the code exists.

All functions operate on UTF-8 binaries. Leading zeros are significant, so a CEP is never handled as an integer.

Data Types

cep()

cep() = <<_:64>>

A raw CEP: 8 ASCII digits, e.g. <<"01310200">>.

formatted_cep()

formatted_cep() = <<_:72>>

A display-formatted CEP, e.g. <<"01310-200">>.

Function Index

format/1	Formats a valid CEP for display, adding the standard dash: `<<"NNNNN-NNN">>`.
generate/0	Generates a random CEP as a raw, numbers-only binary.
is_valid/1	Returns whether the given term is a valid CEP: a binary of exactly 8 ASCII digits.
remove_symbols/1	Removes the formatting symbols `.` and `-` from a CEP string.

Function Details

format/1

format(Cep::binary()) -> {ok, formatted_cep()} | {error, invalid}

Formats a valid CEP for display, adding the standard dash: <<"NNNNN-NNN">>.

The input must be a raw, numbers-only CEP accepted by is_valid/1; anything else yields {error, invalid}.

  1> brutils_cep:format(<<"01310200">>).
  {ok,<<"01310-200">>}
  2> brutils_cep:format(<<"1234567">>).
  {error,invalid}

generate/0

generate() -> cep()

Generates a random CEP as a raw, numbers-only binary.

Each of the 8 digits is drawn independently, so the result may start with (or entirely be) zeros. With no check digit to compute, every output is valid by construction.

  1> brutils_cep:generate().
  <<"31809498">>

is_valid/1

is_valid(Cep::term()) -> boolean()

Returns whether the given term is a valid CEP: a binary of exactly 8 ASCII digits.

That is the entire rule — a CEP carries no check digit, so any 8-digit sequence is structurally valid (including repeated ones like <<"00000000">>), and validity says nothing about whether the postal code exists. Formatting symbols are not stripped, so <<"01310-200">> is invalid; clean it with remove_symbols/1 first. The function is total: any non-binary term returns false rather than raising.

  1> brutils_cep:is_valid(<<"01310200">>).
  true
  2> brutils_cep:is_valid(<<"01310-200">>).
  false

remove_symbols/1

remove_symbols(Cep::binary()) -> binary()

Removes the formatting symbols . and - from a CEP string.

Only those two characters are removed; any other character (letters, spaces, slashes, ...) is kept unchanged. This is a pure character filter: it does not validate the input.

  1> brutils_cep:remove_symbols(<<"01310-200">>).
  <<"01310200">>
  2> brutils_cep:remove_symbols(<<"abc.xyz">>).
  <<"abcxyz">>

Generated by EDoc