view release on metacpan or  search on metacpan

lib/Algorithm/LUHN_XS.pm  view on Meta::CPAN

This function returns the checksum of the given number. 

It's about 50% faster than check_digit() because it doesn't support the valid_chars() function, and only produces a valid output for numeric input.  If you pass 
it input with alpha characters, it will return -1. Works great for Credit 
Cards, but not for things like L<CUSIP identifiers|https://en.wikipedia.org/wiki/CUSIP>.

=cut

# check_digit, check_digit_fast, and check_digit_rff are XS defined functions

=item valid_chars LIST

By default this module only recognizes 0..9 as valid characters, but sometimes
you want to consider other characters as valid, e.g. Standard & Poor's
identifers may contain 0..9, A..Z, @, #, *. This function allows you to add
additional characters to the accepted list.

LIST is a mapping of C<character> =E<gt> C<value>.
For example, Standard & Poor's maps A..Z to 10..35
so the LIST to add these valid characters would be (A, 10, B, 11, C, 12, ...)

Please note that this I<adds> or I<re-maps> characters, so any characters
already considered valid but not in LIST will remain valid.

If you do not provide LIST,
this function returns the current valid character map.

Note that the check_digit_rff() and is_valid_rff() functions do not support
the valid_chars() function.  Both only support numeric inputs, and map them
to their literal values.

=cut

sub valid_chars {
  return %map unless @_;
  while (@_) {
    my ($k, $v) = splice @_, 0, 2;
    $map{$k} = $v;
  }
  _al_init_vc(\%map);
}


sub _dump_map {
  my %foo = valid_chars();
  my ($k,$v);
  print "$k => $v\n" while (($k, $v) = each %foo);
  return 1;
}

=back

=cut

__END__

=head1 CAVEATS

This module, because of how valid_chars() stores data in the XS portion,
is NOT thread safe.

The _fast and _rff versions of is_valid() and check_digit() don't have the 
same return values for failure as the original Algorithm::LUHN module.
Specifically: 

=over 4

=item * is_valid_fast() and is_valid_rff() return 0 on failure, but
        is_valid() returns the empty string.

=item * check_digit_fast() and check_digit_rff() return -1 on failure, but
        check_digit() returns undef.

=back

Also, be careful with passing long numbers around.  Perl will, depending 
on the context, convert things like 12345678912345 to 1.2345678912345e+1.
Try to keep things in "string context".


=head1 SEE ALSO

L<Algorithm::LUHN> is the original pure perl module this is based on.

L<Algorithm::CheckDigits> provides a front-end to a large collection
of modules for working with check digits.

L<Business::CreditCard> provides three functions for checking credit
card numbers. L<Business::CreditCard::Object> provides an OO interface
to those functions.

L<Business::CardInfo> provides a class for holding credit card details,
and has a type constraint on the card number, to ensure it passes the
LUHN check.

L<Business::CCCheck> provides a number of functions for checking
credit card numbers.

L<Regexp::Common> supports combined LUHN and issuer checking
against a card number.

L<Algorithm::Damm> implements a different kind of check digit algorithm,
the L<Damm algorithm|https://en.wikipedia.org/wiki/Damm_algorithm>
(Damm, not Damn).

L<Math::CheckDigits> implements yet another approach to check digits.

Neil Bowers has also written a
L<review of LUHN modules|http://neilb.org/reviews/luhn.html>,
which covers them in more detail than this section.

=head1 REPOSITORY

L<https://github.com/krschwab/Algorithm-LUHN_XS>

=head1 AUTHOR

This module was written by
Kerry Schwab (http://search.cpan.org/search?author=KSCHWAB).