ExEssentials.BrazilianDocument.Formatter (ExEssentials v0.8.0)

View Source

Provides formatting and masking for Brazilian CPF and CNPJ documents, including support for alphanumeric CNPJs.

This module exposes functions to:

* `format/1` — formats CPF and CNPJ numbers using the standard visual
  patterns used in Brazil.
* `mask/1` — masks CPF and CNPJ numbers, hiding sensitive parts while
  keeping the standard visual notation.

## Examples

  iex> ExEssentials.BrazilianDocument.Formatter.format("39053344705")
  "390.533.447-05"

  iex> ExEssentials.BrazilianDocument.Formatter.format("11222333000181")
  "11.222.333/0001-81"

  iex> ExEssentials.BrazilianDocument.Formatter.format("AB123CD456EF01")
  nil

  iex> ExEssentials.BrazilianDocument.Formatter.mask("44286185060")
  "***.861.850-**"

  iex> ExEssentials.BrazilianDocument.Formatter.mask("63219659000153")
  "63.***.***/0001-5*"

The format/1 and mask/1 functions detect the document type and delegate to the appropriate CPF or CNPJ implementation.

Summary

Functions

cnpj_format(cnpj)

Formats a CNPJ string using the standard Brazilian notation. Supports both numeric and alphanumeric CNPJs. Returns nil if the document is invalid.

cnpj_mask(cnpj)

Masks a CNPJ string by hiding the second and third digit groups with ***, while keeping the first two digits and the branch (4th group) visible. The last two characters are partially masked, showing only the first and replacing the last one with *.

cpf_format(cpf)

Formats a CPF string with dots and dash. Only valid CPFs are formatted; otherwise, returns nil.

cpf_mask(cpf)

Masks a CPF string, hiding the first three and the last two digits, while keeping the middle six digits visible. Only valid CPFs are masked; otherwise, returns nil.

format(document)

Formats a string as either CPF or CNPJ depending on its length. It delegates to cpf_format/1 or cnpj_format/1 accordingly.

mask(document)

Masks a string as either CPF or CNPJ depending on its length. It delegates to cpf_mask/1 or cnpj_mask/1 accordingly.

Functions

cnpj_format(cnpj)

@spec cnpj_format(cnpj :: String.t()) :: String.t() | nil

Formats a CNPJ string using the standard Brazilian notation. Supports both numeric and alphanumeric CNPJs. Returns nil if the document is invalid.

## Parameters

- cnpj: a numeric or alphanumeric CNPJ string.

## Examples

  iex> ExEssentials.BrazilianDocument.Formatter.cnpj_format("20495056000171")
  "20.495.056/0001-71"

  iex> ExEssentials.BrazilianDocument.Formatter.cnpj_format("12ABC34501DE35")
  "12.ABC.345/01DE-35"

  iex> ExEssentials.BrazilianDocument.Formatter.cnpj_format("20495056000172")
  nil

  iex> ExEssentials.BrazilianDocument.Formatter.cnpj_format("AB123CD456EF01")
  nil

cnpj_mask(cnpj)

@spec cnpj_mask(cnpj :: String.t()) :: String.t() | nil

Masks a CNPJ string by hiding the second and third digit groups with ***, while keeping the first two digits and the branch (4th group) visible. The last two characters are partially masked, showing only the first and replacing the last one with *.

Supports both numeric and alphanumeric CNPJs. Returns nil if the document is invalid.

## Parameters

- cnpj: a numeric or alphanumeric CNPJ string.

## Examples

  iex> ExEssentials.BrazilianDocument.Formatter.cnpj_mask("20495056000171")
  "20.***.***/0001-7*"

  iex> ExEssentials.BrazilianDocument.Formatter.cnpj_mask("12ABC34501DE35")
  "12.***.***/01DE-3*"

  iex> ExEssentials.BrazilianDocument.Formatter.cnpj_mask("20495056000172")
  nil

  iex> ExEssentials.BrazilianDocument.Formatter.cnpj_mask("AB123CD456EF01")
  nil

cpf_format(cpf)

@spec cpf_format(cpf :: String.t()) :: String.t() | nil

Formats a CPF string with dots and dash. Only valid CPFs are formatted; otherwise, returns nil.

## Parameters

- cpf: a string of 11 digits (formatted or not).

## Examples

  iex> ExEssentials.BrazilianDocument.Formatter.cpf_format("70694167096")
  "706.941.670-96"

  iex> ExEssentials.BrazilianDocument.Formatter.cpf_format("70694167099")
  nil

cpf_mask(cpf)

@spec cpf_mask(cpf :: String.t()) :: String.t() | nil

Masks a CPF string, hiding the first three and the last two digits, while keeping the middle six digits visible. Only valid CPFs are masked; otherwise, returns nil.

## Parameters

- cpf: a string of 11 digits (formatted or not).

## Examples

  iex> ExEssentials.BrazilianDocument.Formatter.cpf_mask("70694167096")
  "***.941.670-**"

  iex> ExEssentials.BrazilianDocument.Formatter.cpf_mask("70694167099")
  nil

format(document)

@spec format(document :: String.t()) :: String.t() | nil

Formats a string as either CPF or CNPJ depending on its length. It delegates to cpf_format/1 or cnpj_format/1 accordingly.

## Parameters

- document: a string containing a CPF or CNPJ.

## Returns

- A formatted document string if valid, otherwise `nil`.

## Examples

  iex> ExEssentials.BrazilianDocument.Formatter.format("44286185060")
  "442.861.850-60"

  iex> ExEssentials.BrazilianDocument.Formatter.format("63219659000153")
  "63.219.659/0001-53"

  iex> ExEssentials.BrazilianDocument.Formatter.format("12ABC34501DE38")
  nil

mask(document)

@spec mask(document :: String.t()) :: String.t() | nil

Masks a string as either CPF or CNPJ depending on its length. It delegates to cpf_mask/1 or cnpj_mask/1 accordingly.

## Parameters

- document: a string containing a CPF or CNPJ.

## Returns

- A formatted document string if valid, otherwise `nil`.

## Examples

  iex> ExEssentials.BrazilianDocument.Formatter.mask("44286185060")
  "***.861.850-**"

  iex> ExEssentials.BrazilianDocument.Formatter.mask("63219659000153")
  "63.***.***/0001-5*"

  iex> ExEssentials.BrazilianDocument.Formatter.mask("12ABC34501DE38")
  nil