1 #-----------------------------------------------------------------------
5 Locale::Currency - ISO three letter codes for currency identification (ISO 4217)
11 $curr = code2currency('usd'); # $curr gets 'US Dollar'
12 $code = currency2code('Euro'); # $code gets 'eur'
14 @codes = all_currency_codes();
15 @names = all_currency_names();
19 #-----------------------------------------------------------------------
21 package Locale::Currency;
25 #-----------------------------------------------------------------------
29 The C<Locale::Currency> module provides access to the ISO three-letter
30 codes for identifying currencies and funds, as defined in ISO 4217.
31 You can either access the codes via the L<conversion routines>
33 or with the two functions which return lists of all currency codes or
36 There are two special codes defined by the standard which aren't
37 understood by this module:
43 Specifically reserved for testing purposes.
47 For transactions where no currency is involved.
53 #-----------------------------------------------------------------------
57 #-----------------------------------------------------------------------
58 # Public Global Variables
59 #-----------------------------------------------------------------------
60 use vars qw($VERSION @ISA @EXPORT);
61 $VERSION = sprintf("%d.%02d", q$Revision: 1.3 $ =~ /(\d+)\.(\d+)/);
63 @EXPORT = qw(&code2currency ¤cy2code
64 &all_currency_codes &all_currency_names );
66 #-----------------------------------------------------------------------
67 # Private Global Variables
68 #-----------------------------------------------------------------------
73 #=======================================================================
75 =head1 CONVERSION ROUTINES
77 There are two conversion routines: C<code2currency()> and C<currency2code()>.
83 This function takes a three letter currency code and returns a string
84 which contains the name of the currency identified. If the code is
85 not a valid currency code, as defined by ISO 4217, then C<undef>
88 $curr = code2currency($code);
92 This function takes a currency name and returns the corresponding
93 three letter currency code, if such exists.
94 If the argument could not be identified as a currency name,
95 then C<undef> will be returned.
97 $code = currency2code('French Franc');
99 The case of the currency name is not important.
100 See the section L<KNOWN BUGS AND LIMITATIONS> below.
106 #=======================================================================
112 return undef unless defined $code;
114 if (exists $CODES{$code})
116 return $CODES{$code};
120 #---------------------------------------------------------------
121 # no such currency code!
122 #---------------------------------------------------------------
132 return undef unless defined $curr;
134 if (exists $CURRENCIES{$curr})
136 return $CURRENCIES{$curr};
140 #---------------------------------------------------------------
142 #---------------------------------------------------------------
147 #=======================================================================
149 =head1 QUERY ROUTINES
151 There are two function which can be used to obtain a list of all
152 currency codes, or all currency names:
156 =item C<all_currency_codes()>
158 Returns a list of all three-letter currency codes.
159 The codes are guaranteed to be all lower-case,
160 and not in any particular order.
162 =item C<all_currency_names()>
164 Returns a list of all currency names for which there is a corresponding
165 three-letter currency code. The names are capitalised, and not returned
166 in any particular order.
172 #=======================================================================
173 sub all_currency_codes
178 sub all_currency_names
180 return values %CODES;
183 #-----------------------------------------------------------------------
187 The following example illustrates use of the C<code2currency()> function.
188 The user is prompted for a currency code, and then told the corresponding
191 $| = 1; # turn off buffering
193 print "Enter currency code: ";
194 chop($code = <STDIN>);
195 $curr = code2currency($code);
198 print "$code = $curr\n";
202 print "'$code' is not a valid currency code!\n";
205 =head1 KNOWN BUGS AND LIMITATIONS
211 In the current implementation, all data is read in when the
212 module is loaded, and then held in memory.
213 A lazy implementation would be more memory friendly.
217 This module also includes the special codes which are
218 not for a currency, such as Gold, Platinum, etc.
219 This might cause a problem if you're using this module
220 to display a list of currencies.
221 Let Neil know if this does cause a problem, and we can
222 do something about it.
226 ISO 4217 also defines a numeric code for each currency.
227 Currency codes are not currently supported by this module.
231 There are three cases where there is more than one
232 code for the same currency name.
233 Kwacha has two codes: mwk for Malawi, and zmk for Zambia.
234 The Russian Ruble has two codes: rub and rur.
235 The Belarussian Ruble has two codes: byr and byb.
236 The currency2code() function only returns one code, so
237 you might not get back the code you expected.
245 =item Locale::Country
247 ISO codes for identification of country (ISO 3166).
248 Supports alpha-2, alpha-3, and numeric codes.
249 The currency codes use the alpha-2 codeset.
253 Code for the representation of currencies and funds.
255 =item http://www.bsi-global.com/iso4217currency
257 Official web page for the ISO 4217 maintenance agency.
258 This has the latest list of codes, in MS Word format. Boo.
264 Michael Hennecke E<lt>hennecke@rz.uni-karlsruhe.deE<gt>
266 Neil Bowers E<lt>neilb@cre.canon.co.ukE<gt>
270 Copyright (c) 2001 Michael Hennecke and
271 Canon Research Centre Europe (CRE).
273 This module is free software; you can redistribute it and/or
274 modify it under the same terms as Perl itself.
278 #-----------------------------------------------------------------------
280 #=======================================================================
281 # initialisation code - stuff the DATA into the CODES hash
282 #=======================================================================
292 ($code, $currency) = split(/:/, $_, 2);
293 $CODES{$code} = $currency;
294 $CURRENCIES{"\L$currency"} = $code;
306 ang:Netherlands Antillean Guilder
309 aor:Kwanza Reajustado
312 aud:Australian Dollar
314 azm:Azerbaijanian Manat
316 bam:Convertible Marks
333 byb:Belarussian Ruble
334 byr:Belarussian Ruble
340 clf:Unidades de Formento
344 crc:Costa Rican Colon
346 cve:Cape Verde Escudo
357 ecv:Unidad de Valor Constante (UVC)
367 fkp:Falkland Islands Pound
378 gwp:Guinea-Bissau Peso
407 kyd:Cayman Islands Dollar
432 mxn:Mexican Nuevo Peso
433 myr:Malaysian Ringgit
439 nlg:Netherlands Guilder
442 nzd:New Zealand Dollar
452 pte:Portuguese Escudo
463 sbd:Solomon Islands Dollar
475 svc:El Salvador Colon
486 ttd:Trinidad and Tobago Dollar
487 twd:New Taiwan Dollar
488 tzs:Tanzanian Shilling
494 usn:US Dollar (Next day)
495 uss:US Dollar (Same day)
508 xba:European Composite Unit
509 xbb:European Monetary Unit
510 xbc:European Unit of Account 9
511 xb5:European Unit of Account 17
512 xcd:East Caribbean Dollar
514 xeu:ECU (until 1998-12-31)