1 2=head1 NAME 3 4Locale::Currency - ISO three letter codes for currency identification (ISO 4217) 5 6=head1 SYNOPSIS 7 8 use Locale::Currency; 9 10 $curr = code2currency('usd'); # $curr gets 'US Dollar' 11 $code = currency2code('Euro'); # $code gets 'eur' 12 13 @codes = all_currency_codes(); 14 @names = all_currency_names(); 15 16 17=head1 DESCRIPTION 18 19The C<Locale::Currency> module provides access to the ISO three-letter 20codes for identifying currencies and funds, as defined in ISO 4217. 21You can either access the codes via the L<conversion routines> 22(described below), 23or with the two functions which return lists of all currency codes or 24all currency names. 25 26There are two special codes defined by the standard which aren't 27understood by this module: 28 29=over 4 30 31=item XTS 32 33Specifically reserved for testing purposes. 34 35=item XXX 36 37For transactions where no currency is involved. 38 39=back 40 41 42=head1 CONVERSION ROUTINES 43 44There are two conversion routines: C<code2currency()> and C<currency2code()>. 45 46=over 4 47 48=item code2currency() 49 50This function takes a three letter currency code and returns a string 51which contains the name of the currency identified. If the code is 52not a valid currency code, as defined by ISO 4217, then C<undef> 53will be returned. 54 55 $curr = code2currency($code); 56 57=item currency2code() 58 59This function takes a currency name and returns the corresponding 60three letter currency code, if such exists. 61If the argument could not be identified as a currency name, 62then C<undef> will be returned. 63 64 $code = currency2code('French Franc'); 65 66The case of the currency name is not important. 67See the section L<KNOWN BUGS AND LIMITATIONS> below. 68 69=back 70 71 72=head1 QUERY ROUTINES 73 74There are two function which can be used to obtain a list of all 75currency codes, or all currency names: 76 77=over 4 78 79=item C<all_currency_codes()> 80 81Returns a list of all three-letter currency codes. 82The codes are guaranteed to be all lower-case, 83and not in any particular order. 84 85=item C<all_currency_names()> 86 87Returns a list of all currency names for which there is a corresponding 88three-letter currency code. The names are capitalised, and not returned 89in any particular order. 90 91=back 92 93 94=head1 EXAMPLES 95 96The following example illustrates use of the C<code2currency()> function. 97The user is prompted for a currency code, and then told the corresponding 98currency name: 99 100 $| = 1; # turn off buffering 101 102 print "Enter currency code: "; 103 chop($code = <STDIN>); 104 $curr = code2currency($code); 105 if (defined $curr) 106 { 107 print "$code = $curr\n"; 108 } 109 else 110 { 111 print "'$code' is not a valid currency code!\n"; 112 } 113 114=head1 KNOWN BUGS AND LIMITATIONS 115 116=over 4 117 118=item * 119 120In the current implementation, all data is read in when the 121module is loaded, and then held in memory. 122A lazy implementation would be more memory friendly. 123 124=item * 125 126This module also includes the special codes which are 127not for a currency, such as Gold, Platinum, etc. 128This might cause a problem if you're using this module 129to display a list of currencies. 130Let Neil know if this does cause a problem, and we can 131do something about it. 132 133=item * 134 135ISO 4217 also defines a numeric code for each currency. 136Currency codes are not currently supported by this module, 137in the same way Locale::Country supports multiple codesets. 138 139=item * 140 141There are three cases where there is more than one 142code for the same currency name. 143Kwacha has two codes: mwk for Malawi, and zmk for Zambia. 144The Russian Ruble has two codes: rub and rur. 145The Belarussian Ruble has two codes: byr and byb. 146The currency2code() function only returns one code, so 147you might not get back the code you expected. 148 149=back 150 151=head1 SEE ALSO 152 153=over 4 154 155=item Locale::Country 156 157ISO codes for identification of country (ISO 3166). 158 159=item Locale::Script 160 161ISO codes for identification of written scripts (ISO 15924). 162 163=item ISO 4217:1995 164 165Code for the representation of currencies and funds. 166 167=item http://www.bsi-global.com/iso4217currency 168 169Official web page for the ISO 4217 maintenance agency. 170This has the latest list of codes, in MS Word format. Boo. 171 172=back 173 174=head1 AUTHOR 175 176Michael Hennecke E<lt>hennecke@rz.uni-karlsruhe.deE<gt> 177and 178Neil Bowers E<lt>neil@bowers.comE<gt> 179 180=head1 COPYRIGHT 181 182Copyright (C) 2002, Neil Bowers. 183 184Copyright (c) 2001 Michael Hennecke and 185Canon Research Centre Europe (CRE). 186 187This module is free software; you can redistribute it and/or 188modify it under the same terms as Perl itself. 189 190=cut 191 192