=pod

=head1 NAME

Locale::Currency - standard codes for currency identification

=head1 SYNOPSIS

    use Locale::Currency;

    $curr = code2currency('usd');     # $curr gets 'US Dollar'
    $code = currency2code('Euro');    # $code gets 'eur'

    @codes   = all_currency_codes();
    @names   = all_currency_names();


=head1 DESCRIPTION

The C<Locale::Currency> module provides access to standard codes used
for identifying currencies and funds, such as those defined in ISO 4217.

You can either access the codes via the L<conversion routines>
(described below), or with the two functions which return lists of all
currency codes or all currency names.

=head1 CURRENCY NAMES

Locale::Currency supports variant names for currencies.

Currency names come from the standards, but common aliases are included
(and others may be added). If you have a common alias for a currency,
let me know and I'll add it, with some restrictions.

=head1 SUPPORTED CODE SETS

The following code sets are currently supported:

=over 4

=item B<alpha>

This is a set of three-letter (uppercase) codes from ISO 4217 such
as EUR for Euro.

Two of the codes specified by the standard (XTS which is reserved
for testing purposes and XXX which is for transactions where no
currency is involved) are omitted.

This code set is identified with the symbol C<LOCALE_CURR_ALPHA>.
It is the default code set in all functions.

=item B<num>

This is the set of numeric codes from ISO 4217.

This code set is identified with the symbol C<LOCALE_CURR_NUMERIC>.

=back

=head1 CONVERSION ROUTINES

There are two conversion routines: C<code2currency()> and C<currency2code()>.

=over 4

=item code2currency()

This function takes a three letter currency code and returns a string
which contains the name of the currency identified. If the code is not
a valid currency code, as defined by ISO 4217, then C<undef> will be
returned.

   $curr = code2currency($code);

=item currency2code()

This function takes a currency name and returns the corresponding
three letter currency code, if such exists.  If the argument could not
be identified as a currency name, then C<undef> will be returned.

   $code = currency2code('French Franc');

The case of the currency name is not important.

=item currency_code2code( CODE, CODESET, CODESET )

This function takes a currency code from one code set, and returns the
corresponding code from another code set.

Both CODESETs must be explicitly entered.

   currency_code2code('aym', LOCALE_CURR_ALPHA,
                     LOCALE_CURR_NUMERIC);
      => 'ay'

If the code passed is not a valid currency code in the first code set,
or if there isn't a code for the corresponding currency in the second
code set, then C<undef> will be returned.

=back

=head1 QUERY ROUTINES

There are two function which can be used to obtain a list of all
currency codes, or all currency names:

=over 4

=item C<all_currency_codes()>

Returns a list of all three-letter currency codes.  The codes are
guaranteed to be all lower-case, and not in any particular order.

=item C<all_currency_names()>

Returns a list of all currency names for which there is a
corresponding three-letter currency code. The names are capitalized,
and not returned in any particular order.

=back

=head1 EXAMPLES

The following example illustrates use of the C<code2currency()> function.
The user is prompted for a currency code, and then told the corresponding
currency name:

   $| = 1;    # turn off buffering

   print "Enter currency code: ";
   chop($code = <STDIN>);
   $curr = code2currency($code);
   if (defined $curr)
   {
       print "$code = $curr\n";
   } else {
       print "'$code' is not a valid currency code!\n";
   }

=head1 KNOWN BUGS AND LIMITATIONS

=over 4

=item *

Currently, currency names are in pure ASCII. I plan to relax that in the
future.

=back

=head1 SEE ALSO

=over 4

=item Locale::Codes

=item Locale::Constants

=item http://www.iso.org/iso/support/currency_codes_list-1.htm

The ISO 4217 data.

=back

=head1 AUTHOR

See Locale::Codes for full author history.

Currently maintained by Sullivan Beck (sbeck@cpan.org).

=head1 COPYRIGHT

   Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
   Copyright (c) 2001      Michael Hennecke
   Copyright (c) 2001-2010 Neil Bowers
   Copyright (c) 2010-2010 Sullivan Beck

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

=cut
