Module brutils_voter_id

Description
Data Types
Function Index
Function Details

Validation, formatting and generation for the Brazilian voter id (título de eleitor).

Description

Validation, formatting and generation for the Brazilian voter id (título de eleitor).

A voter id is read from the RIGHT: the last 2 digits are check digits, the 2 before them encode the federative union (01 for São Paulo through 27 for Tocantins, 28 for titles issued abroad), and everything in front is the sequential number — normally 8 digits (12 in total), but 9 for some São Paulo and Minas Gerais titles (13 in total).

All functions operate on UTF-8 binaries.

Data Types

formatted_voter_id()

formatted_voter_id() = <<_:120>>

A display-formatted voter id, e.g. <<"6908 4709 28 28">>.

voter_id()

voter_id() = <<_:96>>

A generated voter id: always 12 digits. (Valid input may also be 13 digits for São Paulo and Minas Gerais titles.)

Function Index

format/1	Formats a valid 12-digit voter id for display with visual spacing: `<<"NNNN NNNN NN NN">>`.
generate/0	Generates a random valid voter id for a title issued abroad (federative union `ZZ`).
generate/1	Generates a random valid voter id for the given federative union (two-letter code, case insensitive; `<<"ZZ">>` for titles issued abroad).
is_valid/1	Returns whether the given term is a valid voter id: an all-digit binary of 12 digits — or 13 when the federative union code (the two digits before the final two) is `01` or `02` — whose federative union code is in the range `01`..`28` and whose two check digits match the ones computed from the first 8 sequential digits and the federative union.

Function Details

format/1

format(VoterId::binary()) -> {ok, formatted_voter_id()} | {error, invalid}

Formats a valid 12-digit voter id for display with visual spacing: <<"NNNN NNNN NN NN">>.

Valid 13-digit São Paulo / Minas Gerais titles yield {error, invalid}: the display mask has no slot for the 9th sequential digit. (The reference implementation silently slices the first 12 digits of such titles, dropping the last digit and shifting every group — corrupting the value; this port refuses instead of corrupting.)

  1> brutils_voter_id:format(<<"690847092828">>).
  {ok,<<"6908 4709 28 28">>}
  2> brutils_voter_id:format(<<"3476353100183">>).
  {error,invalid}

generate/0

generate() -> {ok, voter_id()}

Generates a random valid voter id for a title issued abroad (federative union ZZ).

Equivalent to generate(<<"ZZ">>), but with no error case — the default is always a known federative union.

  1> brutils_voter_id:generate().
  {ok,<<"721636202895">>}

generate/1

generate(Uf::binary()) -> {ok, voter_id()} | {error, invalid}

Generates a random valid voter id for the given federative union (two-letter code, case insensitive; <<"ZZ">> for titles issued abroad).

The result always has 12 digits — the 13-digit São Paulo / Minas Gerais variant is never generated. Unknown codes yield {error, invalid}.

  1> brutils_voter_id:generate(<<"sp">>).
  {ok,<<"454300320183">>}
  2> brutils_voter_id:generate(<<"XX">>).
  {error,invalid}

is_valid/1

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

Returns whether the given term is a valid voter id: an all-digit binary of 12 digits — or 13 when the federative union code (the two digits before the final two) is 01 or 02 — whose federative union code is in the range 01..28 and whose two check digits match the ones computed from the first 8 sequential digits and the federative union.

The 9th sequential digit of a 13-digit title is ignored by the checksum. Only the format is verified — the title is not checked for existence. The function is total: any non-binary term returns false rather than raising.

  1> brutils_voter_id:is_valid(<<"690847092828">>).
  true
  2> brutils_voter_id:is_valid(<<"690847092820">>).
  false

Generated by EDoc