.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CURRENCY 1"
.TH CURRENCY 1 "2002-11-24" "perl v5.8.0" "Perl Programmers Reference Guide"
.SH "NAME"
Locale::Currency \- ISO three letter codes for currency identification (ISO 4217)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Locale::Currency;
.Ve
.PP
.Vb 2
\&    $curr = code2currency('usd');     # $curr gets 'US Dollar'
\&    $code = currency2code('Euro');    # $code gets 'eur'
.Ve
.PP
.Vb 2
\&    @codes   = all_currency_codes();
\&    @names   = all_currency_names();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Locale::Currency\*(C'\fR module provides access to the \s-1ISO\s0 three-letter
codes for identifying currencies and funds, as defined in \s-1ISO\s0 4217.
You can either access the codes via the \*(L"conversion routines\*(R"
(described below),
or with the two functions which return lists of all currency codes or
all currency names.
.PP
There are two special codes defined by the standard which aren't
understood by this module:
.IP "\s-1XTS\s0" 4
.IX Item "XTS"
Specifically reserved for testing purposes.
.IP "\s-1XXX\s0" 4
.IX Item "XXX"
For transactions where no currency is involved.
.SH "CONVERSION ROUTINES"
.IX Header "CONVERSION ROUTINES"
There are two conversion routines: \f(CW\*(C`code2currency()\*(C'\fR and \f(CW\*(C`currency2code()\*(C'\fR.
.IP "\fIcode2currency()\fR" 4
.IX 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 \s-1ISO\s0 4217, then \f(CW\*(C`undef\*(C'\fR
will be returned.
.Sp
.Vb 1
\&    $curr = code2currency($code);
.Ve
.IP "\fIcurrency2code()\fR" 4
.IX 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 \f(CW\*(C`undef\*(C'\fR will be returned.
.Sp
.Vb 1
\&    $code = currency2code('French Franc');
.Ve
.Sp
The case of the currency name is not important.
See the section \*(L"\s-1KNOWN\s0 \s-1BUGS\s0 \s-1AND\s0 \s-1LIMITATIONS\s0\*(R" below.
.SH "QUERY ROUTINES"
.IX Header "QUERY ROUTINES"
There are two function which can be used to obtain a list of all
currency codes, or all currency names:
.ie n .IP """all_currency_codes()""" 4
.el .IP "\f(CWall_currency_codes()\fR" 4
.IX Item "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.
.ie n .IP """all_currency_names()""" 4
.el .IP "\f(CWall_currency_names()\fR" 4
.IX Item "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 particular order.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The following example illustrates use of the \f(CW\*(C`code2currency()\*(C'\fR function.
The user is prompted for a currency code, and then told the corresponding
currency name:
.PP
.Vb 1
\&    $| = 1;    # turn off buffering
.Ve
.PP
.Vb 11
\&    print "Enter currency code: ";
\&    chop($code = <STDIN>);
\&    $curr = code2currency($code);
\&    if (defined $curr)
\&    {
\&        print "$code = $curr\en";
\&    }
\&    else
\&    {
\&        print "'$code' is not a valid currency code!\en";
\&    }
.Ve
.SH "KNOWN BUGS AND LIMITATIONS"
.IX Header "KNOWN BUGS AND LIMITATIONS"
.IP "\(bu" 4
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.
.IP "\(bu" 4
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.
.IP "\(bu" 4
\&\s-1ISO\s0 4217 also defines a numeric code for each currency.
Currency codes are not currently supported by this module,
in the same way Locale::Country supports multiple codesets.
.IP "\(bu" 4
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 Russian Ruble has two codes: rub and rur.
The Belarussian Ruble has two codes: byr and byb.
The \fIcurrency2code()\fR function only returns one code, so
you might not get back the code you expected.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "Locale::Country" 4
.IX Item "Locale::Country"
\&\s-1ISO\s0 codes for identification of country (\s-1ISO\s0 3166).
.IP "Locale::Script" 4
.IX Item "Locale::Script"
\&\s-1ISO\s0 codes for identification of written scripts (\s-1ISO\s0 15924).
.IP "\s-1ISO\s0 4217:1995" 4
.IX Item "ISO 4217:1995"
Code for the representation of currencies and funds.
.IP "http://www.bsi\-global.com/iso4217currency" 4
.IX Item "http://www.bsi-global.com/iso4217currency"
Official web page for the \s-1ISO\s0 4217 maintenance agency.
This has the latest list of codes, in \s-1MS\s0 Word format. Boo.
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael Hennecke <hennecke@rz.uni\-karlsruhe.de>
and
Neil Bowers <neil@bowers.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2002, Neil Bowers.
.PP
Copyright (c) 2001 Michael Hennecke and
Canon Research Centre Europe (\s-1CRE\s0).
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.