NAME
Business::BR::RG - Perl module to test for correct RG numbers
SYNOPSIS
basic use
use Business::BR::RG;
print "ok " if test_rg('390.533.447-05'); # prints 'ok '
print "bad " unless test_rg('231.002.999-00'); # prints 'bad '
using all methods
use Business::BR::RG qw /canon_rg test_rg random_rg format_rg parse_rg/;
test_rg('48.391.390-x') # 1
canon_rg('11.456.789-x') # '11456789X'
test_rg('48.190.390-X') # 0
test_rg('48.190') # undef
format_rg('48.19.0.3.9.0.X') # '48.190.390-X'
my ($base, $dv) = parse_rg('48.19.0.3.9.0.X');
print $base # '48190390'
print $dv # 'X'
my $hashref = parse_rg('48.19.0.3.9.0.X');
print $hashref->{base} . '-' . $hashref->{dv}; # 48190390-X
DESCRIPTION
The RG number is an identification number of Brazilian citizens emitted
by the Department of Public Safety, which is called "Secretaria de
SeguranÃ§a PÃºblica (SSP)".
RG stands for "Registro Geral", and it is valid for all brazil
territory. May be use as passport to Argentina, Paraguay, Uruguay and
Chile.
The RG is comprised of a base of 8 digits and one check digit.
It is usually written like '12.002.999-0' so as to be more
human-readable.
This module provides "test_rg" for checking that a RG number is
*correct*. Here a *correct RG number* means
* it is 9 digits long
* it satisfies the check equation mentioned below
Before checking, any non-digit letter is stripped, making it easy to
test formatted entries like '21.002.999-00' and entries with extra
blanks like ' 99.221.222-00 '. Except the letter X, because it's
represents the number 10.
test_rg
test_rg('39.985.676-X') # incorrect RG, returns 0
test_rg(' 39.985.676-6 ') # is ok, returns 1
test_rg('123') # nope, returns undef
Tests whether a RG number is correct. Before testing, any non-digit
[except X, no matter its case] character is stripped. Then it is
expected to be 9 digits long and to satisfy check equation which
validate the check digit. See "THE CHECK EQUATIONS".
The policy to get rid of '.' and '-' is very liberal. It indeeds
discards anything that is not a digit (0, 1, ..., 9, or X) or
letter. That is handy for discarding spaces as well
test_rg(' 39.985.676-6 ') # is ok, returns 1
But extraneous inputs like '3.9.9 8w5.6w7h6?6' are also accepted. If
you are worried about this kind of input, just check against a
regex:
warn "bad RG: only digits (9) expected"
unless ($rg =~ /^\d{8}(\d|x)$/i);
warn "bad RG: does not match mask '__.___.___-_'"
unless ($rg =~ /^\d{2}\.\d{3}\.\d{3}-(\d|x)$/i);
NOTE. Integer numbers like 1234567 with fewer than 8 digits will be
normalized (eg. to "001234567") before testing.
canon_rg
canon_rg(99); # returns '000000099'
canon_rg('99.999.999-9'); # returns '999999999'
Brings a candidate for a RG number to a canonical form. In case, the
argument is an integer, it is formatted to at least 9 digits.
Otherwise, it is stripped of any non-alphanumeric [again, except x]
characters and returned as it is.
format_rg
format_rg('00000000'); # returns '00.000.000-0'
Formats its input into '00.000.000-0' mask. First, the argument is
canon'ed and then dots and hyphen are added to the first 9 digits of
the result. So you can call format_rg even when its already
formated.
parse_rg
($base, $dv) = parse_rg($rg);
$hashref = parse_rg('99.222.111-0'); # { base => '99222111', dv => '0' }
Splits a candidate for RG number into base and check digits (dv -
dÃgitos de verificaÃ§Ã£o). It canon's the argument before splitting
it into 8- and 1-digit parts. In a list context, returns a
two-element list with the base and the check digits. In a scalar
context, returns a hash ref with keys 'base' and 'dv' and associated
values.
random_rg
$rand_rg = random_rg($valid);
$correct_rg = random_rg();
$rg = random_rg(1); # also a correct RG
$bad_rg = random_rg(0); # an incorrect RG
Generates a random RG. If $valid is omitted or 1, it is guaranteed
to be *correct*. If $valid is 0, it is guaranteed to be *incorrect*.
This function is intented for mass test. (Use it wisely.)
The implementation is simple: just generate a 8-digits random
number, hopefully with a uniform distribution and then compute the
check digits. If $valid==0, the check digits are computed not to
satisfy the check equations.
EXPORT
"test_rg" is exported by default. "canon_rg", "format_rg", "parse_rg"
and "random_rg" can be exported on demand.
THE CHECK EQUATIONS
A correct RG number has one check digit which are computed from the base
8 first digits. Consider the RG number written as 9 digits
c[1] c[2] c[3] c[4] c[5] c[6] c[7] c[8] dv[1]
To check whether a RG is correct or not, it has to satisfy the check
equations:
c[1]*2 + c[2]*3 + c[3]*4 + c[4]*5 + c[5]*6 + c[6]*7 + c[7]*8 + c[8]*9 +
dv[9] * 100 = 0 (mod 11)
BUGS
until now I do not found any RG that has less than 8 digits. But, I
guess, old people still have it. For now, this is the only way that I
found to check RG. If you found any bug, feel free to send e-mail, open
an issue on github or open a RT.
SEE ALSO
Note that this module only tests correctness. It doesn't enter the merit
whether the RG number actually exists at the Brazilian government
databases.
Please reports bugs via CPAN RT or github.
You may be interested too in validation of CPF/CNPJ. So you can look at:
Business::BR::CNPJ
Business::BR::CPF
You should too make a search about the Business::BR namespace.
SUPPORT
Perldoc
You can find documentation for this module with the perldoc command (to
read this)
perldoc Business\:\:BR\:\:RG
Github
If you want to contribute with the code, you can fork this module on
github:
You can even report a issue.
AUTHOR
Renato CRON,
COPYRIGHT AND LICENSE
Copyright (C) 2011 by Renato CRON
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself, either Perl version 5.10.1 or, at
your option, any later version of Perl 5 you may have available.