NAME
    Business::IS::PIN - Validate and process Icelandic PIN numbers
    (Icelandic: kennitölur)

SYNOPSIS
        # Functional interface
        use Business::IS::PIN qw(:all);

        my $kt = '0902862349'; # Yours truly

        if (valid $kt) {
            # Extract YYYY-MM-DD
            my $year  = year  $kt;
            my $month = month $kt
            my $day   = day   $kt;

            # ...
        }

        # OO interface that doesn't pollute your namespace
        use Business::IS::PIN;

        my $kt = Business::IS::PIN->new('0902862349');

        if ($kt->valid and $kt->person) {
            printf "You are a Real Boy(TM) born on %d-%d-%d\n",
                $kt->year, $kt->month, $kt->day;
        } elsif ($kt->valid and $kt->company) {
            warn "Begone, you spawn of capitalism!";
        } else {
            die "EEEK!";
        }

DESCRIPTION
    This module provides an interface for validating the syntax of and
    extracting information from Icelandic personal identification numbers
    (Icelandic: *kennitala*). These are unique 10-digit numbers assigned to
    all Icelandic citizens, foreign citizens with permanent residence and
    corporations (albeit with a slightly different format, see below).

LIMITATIONS
    The National Statistical Institute of Iceland (Icelandic: *Hagstofa*) -
    a goverment organization - handles the assignment of these numbers. This
    module will tell you whether the formatting of a given number is valid,
    not whether it was actually assigned to someone. For that you need to
    pay through the nose to the NSIoI, or cleverly leech on someone who is:)

EXPORT
    None by default, every function in this package except for "new" can be
    exported individually, :all exports them all.

METHODS & FUNCTIONS
  new
    Optional constructor which takes a valid kennitala or a fragment of one
    as its argument. Returns an object that stringifies to whatever string
    is provided.

    If a fragment is provided functions in this package that need
    information from the omitted part (such as "year") will not work.

  valid
    Takes a 9-10 character kennitala and returns true if its checksum is
    valid, false otherwise.

  checksum
    Takes a the first 8 characters of a kennitala and returns the 9th
    checksum digit.

  person
    Returns true if the kennitala belongs to an individual, false otherwise.

  company
    Returns true if the kennitala belongs to a company, false otherwise.

  year
    Return the four-digit year part of the kennitala. For this function to
    work a complete 10-digit number must have been provided.

  month
    Return the two-digit month part of the kennitala.

  day
    Return the two-digit day part of the kennitala.

Format
    The format of an IPIN is relatively simple:

       DDMMYY-SSDC

    Where DDMMYY is a two-digit day, month and year, SS is a pseudo-random
    serial number, D is the check digit computed from preceding part and C
    stands for the century and is not included when calculating the checksum
    digit - 8 for 1800s, and 9 and 0 for the 1900s and 2000s respectively.
    It is customary to place a dash between the first 6 and last 4 digits
    when formatting the number.

    To compute the check digit from a given IPIN 0902862349 the following
    algorithm is used:

          0   9    0   2    8    6    2   3  4  9
        * 3   2    7   6    5    4    3   2
        = 0 + 18 + 0 + 12 + 40 + 24 + 6 + 6 = 106

        checkdigit = (11 - 106 % 11) % 11

    I.e. each digit 1..8 is multiplied by 3..2, 7..2 respectively and the
    result of each multiplication added together to get 106. 106 is then
    used as the divend in a modulo operation with 11 as the divisor to get 7
    which is then subtracted from 11 to get 4 - in this case the check
    digit, if the result had been 11 a second modulo operation 11 % 11 would
    have left us with 0.

CAVEATS
    Only supports identity numbers assigned between the years 1800-2099.
    Please resurrect the author when this becomes an issue.

BUGS
    Please report any bugs that aren't already listed at
    <http://rt.cpan.org/Dist/Display.html?Queue=Is-Kennitala> to
    <http://rt.cpan.org/Public/Bug/Report.html?Queue=Is-Kennitala>

SEE ALSO
    <http://www.hagstofa.is/?PageID=1474>

AUTHOR
    Ævar Arnfjörð Bjarmason <avar@cpan.org>

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

