Commit | Line | Data |
47a334e9 |
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); |
6b6e008c |
61 | $VERSION = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/); |
47a334e9 |
62 | @ISA = qw(Exporter); |
63 | @EXPORT = qw(&code2currency ¤cy2code |
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. |
6b6e008c |
227 | Currency codes are not currently supported by this module, |
228 | in the same way Locale::Country supports multiple codesets. |
47a334e9 |
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). |
6b6e008c |
249 | |
250 | =item Locale::Script |
251 | |
252 | ISO codes for identification of written scripts (ISO 15924). |
47a334e9 |
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 |
6b6e008c |
269 | Neil Bowers E<lt>neil@bowers.comE<gt> |
47a334e9 |
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 |