Module brutils_pis

Description
Data Types
Function Index
Function Details

Utilities for the Brazilian PIS/PASEP (Programa de Integração Social) number.

Description

Utilities for the Brazilian PIS/PASEP (Programa de Integração Social) number.

A PIS is an 11-digit identifier assigned to workers: a 10-digit base number followed by 1 check digit. It is commonly displayed as "NNN.NNNNN.NN-N".

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

Data Types

formatted_pis()

formatted_pis() = <<_:112>>

A display-formatted PIS, e.g. <<"120.56798.81-8">>.

pis()

pis() = <<_:88>>

A raw PIS: 11 ASCII digits, e.g. <<"12056798818">>.

Function Index

format/1	Formats a valid PIS for display, adding the standard visual aid symbols: `<<"NNN.NNNNN.NN-N">>`.
generate/0	Generates a random valid PIS as a raw, numbers-only binary.
is_valid/1	Returns whether the given term is a valid PIS: a binary of exactly 11 ASCII digits whose check digit (the last one) matches the one computed from its 10-digit base.
remove_symbols/1	Removes the formatting symbols `.` and `-` from a PIS string.

Function Details

format/1

format(Pis::binary()) -> {ok, formatted_pis()} | {error, invalid}

Formats a valid PIS for display, adding the standard visual aid symbols: <<"NNN.NNNNN.NN-N">>.

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

  1> brutils_pis:format(<<"12056798818">>).
  {ok,<<"120.56798.81-8">>}
  2> brutils_pis:format(<<"12056798810">>).
  {error,invalid}

generate/0

generate() -> pis()

Generates a random valid PIS as a raw, numbers-only binary.

The 10-digit base is drawn uniformly — zero included, so the result may start with (or be all) zeros — and the check digit is computed from it, so the result always satisfies is_valid/1.

  1> brutils_pis:generate().
  <<"32519670521">>

is_valid/1

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

Returns whether the given term is a valid PIS: a binary of exactly 11 ASCII digits whose check digit (the last one) matches the one computed from its 10-digit base.

Unlike CPF and CNPJ, PIS reserves no repeated-digit sequences — such values stand or fall by their check digit alone (notably, <<"00000000000">> is a valid PIS). Only the format is verified — the PIS is not checked for existence. Formatting symbols are not stripped, so a formatted PIS such as <<"120.56798.81-8">> is invalid; clean it with remove_symbols/1 first. The function is total: any non-binary term returns false rather than raising.

  1> brutils_pis:is_valid(<<"12056798818">>).
  true
  2> brutils_pis:is_valid(<<"12056798810">>).
  false

remove_symbols/1

remove_symbols(Pis::binary()) -> binary()

Removes the formatting symbols . and - from a PIS 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_pis:remove_symbols(<<"120.56798.81-8">>).
  <<"12056798818">>
  2> brutils_pis:remove_symbols(<<"120/567.98 81-a">>).
  <<"120/56798 81a">>

Generated by EDoc