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