currency(3)

NAME

Locale::Currency - ISO three letter codes for currency
identification (ISO 4217)

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();

DESCRIPTION

The "Locale::Currency" module provides access to the ISO
three-letter codes for identifying currencies and funds,
as defined in ISO 4217. You can either access the codes
via the "conversion routines" (described below), or with
the two functions which return lists of all currency codes
or all currency names.

There are two special codes defined by the standard which
aren't understood by this module:

XTS Specifically reserved for testing purposes.

XXX For transactions where no currency is involved.

CONVERSION ROUTINES

There are two conversion routines: "code2currency()" and
"currency2code()".

code2currency(): This function takes a three letter currency code and
returns a string which contains the name of the cur
rency identified. If the code is not a valid currency
code, as defined by ISO 4217, then "undef" will be
returned.

$curr = code2currency($code);
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 "undef" will be returned.

$code = currency2code('French Franc');; The case of the currency name is not important. See
the section "KNOWN BUGS AND LIMITATIONS" below.

QUERY ROUTINES

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

"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.
"all_currency_names()": Returns a list of all currency names for which there
is a corresponding three-letter currency code. The
names are capitalised, and not returned in any partic
ular order.

EXAMPLES

The following example illustrates use of the "code2cur rency()" 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 = $curr0;; }
else
{
print "'$code' is not a valid currency code!0;; }

KNOWN BUGS AND LIMITATIONS

� In the current implementation, all data is read in: when the module is loaded, and then held in memory. A
lazy implementation would be more memory friendly.
� This module also includes the special codes which are: not for a currency, such as Gold, Platinum, etc. This
might cause a problem if you're using this module to
display a list of currencies. Let Neil know if this
does cause a problem, and we can do something about
it.
� ISO 4217 also defines a numeric code for each cur: rency. Currency codes are not currently supported by
this module, in the same way Locale::Country supports
multiple codesets.
� There are three cases where there is more than one: code for the same currency name. Kwacha has two
codes: mwk for Malawi, and zmk for Zambia. The Rus
sian Ruble has two codes: rub and rur. The Belarus
sian Ruble has two codes: byr and byb. The cur_
rency2code() function only returns one code, so you might not get back the code you expected.

AUTHOR

Michael Hennecke <hennecke@rz.uni-karlsruhe.de> and Neil
Bowers <neil@bowers.com>

COPYRIGHT

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

docs.sk

comprehensive documentation repository

In section