NAME

Business::CINS - Verify CUSIP International Numbering System Numbers

SYNOPSIS

  use Business::CINS;
  $cn = Business::CINS->new('035231AH2');
  print "Looks good.\n" if $cn->is_valid;

  $cn = Business::CINS->new('392690QT', 1);
  $chk = $cn->check_digit;
  $cn->cins($cn->cins.$chk);
  print $cn->is_valid ? "Looks good." : "Invalid: ", $cn->error, "\n";

DESCRIPTION

This module verifies CINSes, which are financial identifiers issued by the Standard & Poor's Company for US and Canadian securities. This module cannot tell if a CINS references a real security, but it can tell you if the given CINS is properly formatted.

METHODS

new([CINS_NUMBER[, IS_FIXED_INCOME]])

The new constructor takes two optional arguments: the CINS number and a Boolean value signifying whether this CINS refers to a fixed income security. CINSes for fixed income securities are validated a little differently than other CINSes.

cins([CINS_NUMBER])

If no argument is given to this method, it will return the current CINS number. If an argument is provided, it will set the CINS number and then return the CINS number.

is_fixed_income([TRUE_OR_FALSE])

If no argument is given to this method, it will return whether the CINS object is marked as a fixed income security. If an argument is provided, it will set the fixed income property and then return the fixed income setting.

domicile_code ()

Returns the domicile code from the CINS number.

issuer_num()

Returns the issuer number from the CINS number.

issuer_num()

Returns the issue number from the CINS number.

is_valid()

Returns true if the checksum of the CINS is correct otherwise it returns false and $Business::CINS::ERROR will contain a description of the problem.

error()

If the CINS object is not valid (! is_valid()) it returns the reason it is Not valid. Otherwise returns undef.

check_digit()

This method returns the checksum of the given object. If the CINS number of the object contains a check_digit, it is ignored. In other words this method recalculates the check_digit each time.

Business::CINS->domicile_descr([CODE])

Given a domicile code it will return a description of the code. The valid domicile codes are

  A = Austria         J = Japan          S = South Africa
  B = Belgium         K = Denmark        T = Italy
  C = Canada          L = Luxembourg     U = United States
  D = Germany         M = Mid-East       V = Africa - Other
  E = Spain           N = Netherlands    W = Sweden
  F = France          P = South America  X = Europe-Other
  G = United Kingdom  Q = Australia      Y = Asia
  H = Switzerland     R = Norway

If no CODE is given, it will return the hash of codes.

CAVEATS

This module uses the Algorithm::LUHN module and it adds characters to the valid_chars map of Algorithm::LUHN. So if you rely on the default valid map in the same program you use Business::CINS you might be surprised.

AUTHOR

This module was written by Tim Ayers (http://search.cpan.org/search?author=TAYERS).

COPYRIGHT

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.