This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to Locale::Codes 2.00.
[perl5.git] / lib / Locale / Currency.pm
1 #-----------------------------------------------------------------------
2
3 =head1 NAME
4
5 Locale::Currency - ISO three letter codes for currency identification (ISO 4217)
6
7 =head1 SYNOPSIS
8
9     use Locale::Currency;
10
11     $curr = code2currency('usd');     # $curr gets 'US Dollar'
12     $code = currency2code('Euro');    # $code gets 'eur'
13
14     @codes   = all_currency_codes();
15     @names   = all_currency_names();
16
17 =cut
18
19 #-----------------------------------------------------------------------
20
21 package Locale::Currency;
22 use strict;
23 require 5.002;
24
25 #-----------------------------------------------------------------------
26
27 =head1 DESCRIPTION
28
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>
32 (described below),
33 or with the two functions which return lists of all currency codes or
34 all currency names.
35
36 There are two special codes defined by the standard which aren't
37 understood by this module:
38
39 =over 4
40
41 =item XTS
42
43 Specifically reserved for testing purposes.
44
45 =item XXX
46
47 For transactions where no currency is involved.
48
49 =back
50
51 =cut
52
53 #-----------------------------------------------------------------------
54
55 require Exporter;
56
57 #-----------------------------------------------------------------------
58 #       Public Global Variables
59 #-----------------------------------------------------------------------
60 use vars qw($VERSION @ISA @EXPORT);
61 $VERSION      = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/);
62 @ISA          = qw(Exporter);
63 @EXPORT       = qw(&code2currency &currency2code
64                    &all_currency_codes &all_currency_names );
65
66 #-----------------------------------------------------------------------
67 #       Private Global Variables
68 #-----------------------------------------------------------------------
69 my %CODES      = ();
70 my %CURRENCIES = ();
71
72
73 #=======================================================================
74
75 =head1 CONVERSION ROUTINES
76
77 There are two conversion routines: C<code2currency()> and C<currency2code()>.
78
79 =over 8
80
81 =item code2currency()
82
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>
86 will be returned.
87
88     $curr = code2currency($code);
89
90 =item currency2code()
91
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.
96
97     $code = currency2code('French Franc');
98
99 The case of the currency name is not important.
100 See the section L<KNOWN BUGS AND LIMITATIONS> below.
101
102 =back
103
104 =cut
105
106 #=======================================================================
107 sub code2currency
108 {
109     my $code = shift;
110
111
112     return undef unless defined $code;
113     $code = lc($code);
114     if (exists $CODES{$code})
115     {
116         return $CODES{$code};
117     }
118     else
119     {
120         #---------------------------------------------------------------
121         # no such currency code!
122         #---------------------------------------------------------------
123         return undef;
124     }
125 }
126
127 sub currency2code
128 {
129     my $curr = shift;
130
131
132     return undef unless defined $curr;
133     $curr = lc($curr);
134     if (exists $CURRENCIES{$curr})
135     {
136         return $CURRENCIES{$curr};
137     }
138     else
139     {
140         #---------------------------------------------------------------
141         # no such currency!
142         #---------------------------------------------------------------
143         return undef;
144     }
145 }
146
147 #=======================================================================
148
149 =head1 QUERY ROUTINES
150
151 There are two function which can be used to obtain a list of all
152 currency codes, or all currency names:
153
154 =over 8
155
156 =item C<all_currency_codes()>
157
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.
161
162 =item C<all_currency_names()>
163
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.
167
168 =back
169
170 =cut
171
172 #=======================================================================
173 sub all_currency_codes
174 {
175     return keys %CODES;
176 }
177
178 sub all_currency_names
179 {
180     return values %CODES;
181 }
182
183 #-----------------------------------------------------------------------
184
185 =head1 EXAMPLES
186
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
189 currency name:
190
191     $| = 1;    # turn off buffering
192
193     print "Enter currency code: ";
194     chop($code = <STDIN>);
195     $curr = code2currency($code);
196     if (defined $curr)
197     {
198         print "$code = $curr\n";
199     }
200     else
201     {
202         print "'$code' is not a valid currency code!\n";
203     }
204
205 =head1 KNOWN BUGS AND LIMITATIONS
206
207 =over 4
208
209 =item *
210
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.
214
215 =item *
216
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.
223
224 =item *
225
226 ISO 4217 also defines a numeric code for each currency.
227 Currency codes are not currently supported by this module,
228 in the same way Locale::Country supports multiple codesets.
229
230 =item *
231
232 There are three cases where there is more than one
233 code for the same currency name.
234 Kwacha has two codes: mwk for Malawi, and zmk for Zambia.
235 The Russian Ruble has two codes: rub and rur.
236 The Belarussian Ruble has two codes: byr and byb.
237 The currency2code() function only returns one code, so
238 you might not get back the code you expected.
239
240 =back
241
242 =head1 SEE ALSO
243
244 =over 4
245
246 =item Locale::Country
247
248 ISO codes for identification of country (ISO 3166).
249
250 =item Locale::Script
251
252 ISO codes for identification of written scripts (ISO 15924).
253
254 =item ISO 4217:1995
255
256 Code for the representation of currencies and funds.
257
258 =item http://www.bsi-global.com/iso4217currency
259
260 Official web page for the ISO 4217 maintenance agency.
261 This has the latest list of codes, in MS Word format. Boo.
262
263 =back
264
265 =head1 AUTHOR
266
267 Michael Hennecke E<lt>hennecke@rz.uni-karlsruhe.deE<gt>
268 and
269 Neil Bowers E<lt>neil@bowers.comE<gt>
270
271 =head1 COPYRIGHT
272
273 Copyright (c) 2001 Michael Hennecke and
274 Canon Research Centre Europe (CRE).
275
276 This module is free software; you can redistribute it and/or
277 modify it under the same terms as Perl itself.
278
279 =cut
280
281 #-----------------------------------------------------------------------
282
283 #=======================================================================
284 # initialisation code - stuff the DATA into the CODES hash
285 #=======================================================================
286 {
287     my $code;
288     my $currency;
289
290
291     while (<DATA>)
292     {
293         next unless /\S/;
294         chop;
295         ($code, $currency) = split(/:/, $_, 2);
296         $CODES{$code} = $currency;
297         $CURRENCIES{"\L$currency"} = $code;
298     }
299 }
300
301 1;
302
303 __DATA__
304 adp:Andorran Peseta
305 aed:UAE Dirham
306 afa:Afghani
307 all:Lek
308 amd:Armenian Dram
309 ang:Netherlands Antillean Guilder
310 aoa:Kwanza
311 aon:New Kwanza
312 aor:Kwanza Reajustado
313 ars:Argentine Peso
314 ats:Schilling
315 aud:Australian Dollar
316 awg:Aruban Guilder
317 azm:Azerbaijanian Manat
318
319 bam:Convertible Marks
320 bbd:Barbados Dollar
321 bdt:Taka
322 bef:Belgian Franc
323 bgl:Lev
324 bgn:Bulgarian Lev
325 bhd:Bahraini Dinar
326 bhd:Dinar
327 bif:Burundi Franc
328 bmd:Bermudian Dollar
329 bnd:Brunei Dollar
330 bob:Boliviano
331 bov:MVDol
332 brl:Brazilian Real
333 bsd:Bahamian Dollar
334 btn:Ngultrum
335 bwp:Pula
336 byb:Belarussian Ruble
337 byr:Belarussian Ruble
338 bzd:Belize Dollar
339
340 cad:Candian Dollar
341 cdf:Franc Congolais
342 chf:Swiss Franc
343 clf:Unidades de Formento
344 clp:Chilean Peso
345 cny:Yuan Renminbi
346 cop:Colombian Peso
347 crc:Costa Rican Colon
348 cup:Cuban Peso
349 cve:Cape Verde Escudo
350 cyp:Cyprus Pound
351 czk:Czech Koruna
352
353 dem:German Mark
354 djf:Djibouti Franc
355 dkk:Danish Krone
356 dop:Dominican Peso
357 dzd:Algerian Dinar
358
359 ecs:Sucre
360 ecv:Unidad de Valor Constante (UVC)
361 eek:Kroon
362 egp:Egyptian Pound
363 ern:Nakfa
364 esp:Spanish Peseta
365 etb:Ethiopian Birr
366 eur:Euro
367
368 fim:Markka
369 fjd:Fiji Dollar
370 fkp:Falkland Islands Pound
371 frf:French Franc
372
373 gbp:Pound Sterling
374 gel:Lari
375 ghc:Cedi
376 gip:Gibraltar Pound
377 gmd:Dalasi
378 gnf:Guinea Franc
379 grd:Drachma
380 gtq:Quetzal
381 gwp:Guinea-Bissau Peso
382 gyd:Guyana Dollar
383
384 hkd:Hong Kong Dollar
385 hnl:Lempira
386 hrk:Kuna
387 htg:Gourde
388 huf:Forint
389
390 idr:Rupiah
391 iep:Irish Pound
392 ils:Shekel
393 inr:Indian Rupee
394 iqd:Iraqi Dinar
395 irr:Iranian Rial
396 isk:Iceland Krona
397 itl:Italian Lira
398
399 jmd:Jamaican Dollar
400 jod:Jordanian Dinar
401 jpy:Yen
402
403 kes:Kenyan Shilling
404 kgs:Som
405 khr:Riel
406 kmf:Comoro Franc
407 kpw:North Korean Won
408 krw:Won
409 kwd:Kuwaiti Dinar
410 kyd:Cayman Islands Dollar
411 kzt:Tenge
412
413 lak:Kip
414 lbp:Lebanese Pound
415 lkr:Sri Lanka Rupee
416 lrd:Liberian Dollar
417 lsl:Loti
418 ltl:Lithuanian Litas
419 luf:Luxembourg Franc
420 lvl:Latvian Lats
421 lyd:Libyan Dinar
422
423 mad:Moroccan Dirham
424 mdl:Moldovan Leu
425 mgf:Malagasy Franc
426 mkd:Denar
427 mmk:Kyat
428 mnt:Tugrik
429 mop:Pataca
430 mro:Ouguiya
431 mtl:Maltese Lira
432 mur:Mauritius Rupee
433 mvr:Rufiyaa
434 mwk:Kwacha
435 mxn:Mexican Nuevo Peso
436 myr:Malaysian Ringgit
437 mzm:Metical
438
439 nad:Namibia Dollar
440 ngn:Naira
441 nio:Cordoba Oro
442 nlg:Netherlands Guilder
443 nok:Norwegian Krone
444 npr:Nepalese Rupee
445 nzd:New Zealand Dollar
446
447 omr:Rial Omani
448
449 pab:Balboa
450 pen:Nuevo Sol
451 pgk:Kina
452 php:Philippine Peso
453 pkr:Pakistan Rupee
454 pln:Zloty
455 pte:Portuguese Escudo
456 pyg:Guarani
457
458 qar:Qatari Rial
459
460 rol:Leu
461 rub:Russian Ruble
462 rur:Russian Ruble
463 rwf:Rwanda Franc
464
465 sar:Saudi Riyal
466 sbd:Solomon Islands Dollar
467 scr:Seychelles Rupee
468 sdd:Sudanese Dinar
469 sek:Swedish Krona
470 sgd:Singapore Dollar
471 shp:St. Helena Pound
472 sit:Tolar
473 skk:Slovak Koruna
474 sll:Leone
475 sos:Somali Shilling
476 srg:Surinam Guilder
477 std:Dobra
478 svc:El Salvador Colon
479 syp:Syrian Pound
480 szl:Lilangeni
481
482 thb:Baht
483 tjr:Tajik Ruble
484 tmm:Manat
485 tnd:Tunisian Dollar
486 top:Pa'anga
487 tpe:Timor Escudo
488 trl:Turkish Lira
489 ttd:Trinidad and Tobago Dollar
490 twd:New Taiwan Dollar
491 tzs:Tanzanian Shilling
492
493 uah:Hryvnia
494 uak:Karbovanets
495 ugx:Uganda Shilling
496 usd:US Dollar
497 usn:US Dollar (Next day)
498 uss:US Dollar (Same day)
499 uyu:Peso Uruguayo
500 uzs:Uzbekistan Sum
501
502 veb:Bolivar
503 vnd:Dong
504 vuv:Vatu
505
506 wst:Tala
507
508 xaf:CFA Franc BEAC
509 xag:Silver
510 xau:Gold
511 xba:European Composite Unit
512 xbb:European Monetary Unit
513 xbc:European Unit of Account 9
514 xb5:European Unit of Account 17
515 xcd:East Caribbean Dollar
516 xdr:SDR
517 xeu:ECU (until 1998-12-31)
518 xfu:UIC-Franc
519 xfo:Gold-Franc
520 xof:CFA Franc BCEAO
521 xpd:Palladium
522 xpf:CFP Franc
523 xpt:Platinum
524
525 yer:Yemeni Rial
526 yum:New Dinar
527
528 zal:Financial Rand
529 zar:Rand
530 zmk:Kwacha
531 zrn:New Zaire
532 zwd:Zimbabwe Dollar