Module: BrazilianUtils::CPFUtils

Defined in:
lib/brazilian-utils/cpf-utils.rb

Class Method Summary collapse

Class Method Details

.display(cpf) ⇒ String?

Note:

This method should not be used in new code and is only provided for backward compatibility. Use format_cpf instead.

Formats a CPF for display with visual aid symbols (legacy method).

This function takes a numbers-only CPF string as input and adds standard formatting visual aid symbols for display.

Examples:

display("12345678901")   #=> "123.456.789-01"
display("98765432101")   #=> "987.654.321-01"

Parameters:

  • cpf (String) —

    A numbers-only CPF string.

Returns:

  • (String, nil) —

    A formatted CPF string with standard visual aid symbols, nil if the input is invalid.



54
55
56
57
58
59
60
61
62
63
 
# File 'lib/brazilian-utils/cpf-utils.rb', line 54

def self.display(cpf)
  return nil unless cpf.to_s.match?(/^\d{11}$/)
  return nil if cpf.chars.uniq.length == 1

  format('%s.%s.%s-%s',
         cpf[0..2],
         cpf[3..5],
         cpf[6..8],
         cpf[9..10])
end

.format_cpf(cpf) ⇒ String?

Formats a CPF for display with visual aid symbols.

This function takes a numbers-only CPF string as input and adds standard formatting visual aid symbols for display.

Examples:

format_cpf("82178537464")   #=> "821.785.374-64"
format_cpf("55550207753")   #=> "555.502.077-53"

Parameters:

  • cpf (String) —

    A numbers-only CPF string.

Returns:

  • (String, nil) —

    A formatted CPF string with standard visual aid symbols, nil if the input is invalid.



77
78
79
80
81
82
83
84
85
 
# File 'lib/brazilian-utils/cpf-utils.rb', line 77

def self.format_cpf(cpf)
  return nil unless valid?(cpf)

  format('%s.%s.%s-%s',
         cpf[0..2],
         cpf[3..5],
         cpf[6..8],
         cpf[9..10])
end

.generate ⇒ String

Generates a random valid CPF digit string.

This function generates a random valid CPF string.

Examples:

generate()   #=> "10895948109"
generate()   #=> "52837606502"

Returns:

  • (String) —

    A random valid CPF string.



140
141
142
143
 
# File 'lib/brazilian-utils/cpf-utils.rb', line 140

def self.generate
  base = format('%09d', rand(1..999_999_998))
  base + checksum(base)
end

.parse(value) ⇒ String

Removes CPF formatting and keeps only digits, capped to 11 digits.

Examples:

parse("943.895.751-04")  #=> "94389575104"

Parameters:

  • value (String, Integer) —

    A CPF, with or without formatting.

Returns:

  • (String) —

    The parsed digits.



199
200
201
202
203
 
# File 'lib/brazilian-utils/cpf-utils.rb', line 199

def self.parse(value)
  return '' unless value.is_a?(String) || value.is_a?(Integer)

  value.to_s.gsub(/\D/, '')[0, 11]
end

.remove_symbols(dirty) ⇒ String

Removes specific symbols from a CPF string.

This function is an alias for the sieve function, offering a more descriptive name.

Examples:

remove_symbols("123.456.789-01")   #=> "12345678901"
remove_symbols("987-654-321.01")   #=> "98765432101"

Parameters:

  • dirty (String) —

    The CPF string containing symbols to be removed.

Returns:

  • (String) —

    A new string with the specified symbols removed.



35
36
37
 
# File 'lib/brazilian-utils/cpf-utils.rb', line 35

def self.remove_symbols(dirty)
  sieve(dirty)
end

.sieve(dirty) ⇒ String

Note:

This method should not be used in new code and is only provided for backward compatibility. Use remove_symbols instead.

Removes specific symbols from a CPF (Brazilian Individual Taxpayer Number) string.

This function takes a CPF string as input and removes all occurrences of the '.', '-' characters from it.

Examples:

sieve("123.456.789-01")     #=> "12345678901"
sieve("987-654-321.01")     #=> "98765432101"

Parameters:

  • dirty (String) —

    The CPF string containing symbols to be removed.

Returns:

  • (String) —

    A new string with the specified symbols removed.



20
21
22
 
# File 'lib/brazilian-utils/cpf-utils.rb', line 20

def self.sieve(dirty)
  dirty.to_s.delete('.-')
end

.valid?(cpf) ⇒ Boolean

Returns whether or not the verifying checksum digits of the given CPF match its base number.

This function does not verify the existence of the CPF; it only validates the format of the string.

Examples:

valid?("82178537464")   #=> true
valid?("55550207753")   #=> true
valid?("00000000000")   #=> false
valid?("123.456.789-01")   #=> false (must be numbers only)

Parameters:

  • cpf (String) —

    The CPF to be validated, an 11-digit string

Returns:

  • (Boolean) —

    true if the checksum digits match the base number, false otherwise.



127
128
129
 
# File 'lib/brazilian-utils/cpf-utils.rb', line 127

def self.valid?(cpf)
  cpf.is_a?(String) && validate(cpf)
end

.validate(cpf) ⇒ Boolean

Note:

This method should not be used in new code and is only provided for backward compatibility. Use valid? instead.

Validates the checksum digits of a CPF.

This function checks whether the verifying checksum digits of the given CPF match its base number. The input should be a digit string of the proper length.

Examples:

validate("82178537464")   #=> true
validate("55550207753")   #=> true

Parameters:

  • cpf (String) —

    A numbers-only CPF string.

Returns:

  • (Boolean) —

    true if the checksum digits are valid, false otherwise.



104
105
106
107
108
109
110
111
 
# File 'lib/brazilian-utils/cpf-utils.rb', line 104

def self.validate(cpf)
  return false unless cpf.to_s.match?(/^\d{11}$/)
  return false if cpf.chars.uniq.length == 1

  (0..1).all? do |i|
    hashdigit(cpf, i + 10) == cpf[9 + i].to_i
  end
end