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); |
61 | $VERSION = sprintf("%d.%02d", q$Revision: 1.3 $ =~ /(\d+)\.(\d+)/); |
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. |
227 | Currency codes are not currently supported by this module. |
228 | |
229 | =item * |
230 | |
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. |
238 | |
239 | =back |
240 | |
241 | =head1 SEE ALSO |
242 | |
243 | =over 4 |
244 | |
245 | =item Locale::Country |
246 | |
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. |
250 | |
251 | =item ISO 4217:1995 |
252 | |
253 | Code for the representation of currencies and funds. |
254 | |
255 | =item http://www.bsi-global.com/iso4217currency |
256 | |
257 | Official web page for the ISO 4217 maintenance agency. |
258 | This has the latest list of codes, in MS Word format. Boo. |
259 | |
260 | =back |
261 | |
262 | =head1 AUTHOR |
263 | |
264 | Michael Hennecke E<lt>hennecke@rz.uni-karlsruhe.deE<gt> |
265 | and |
266 | Neil Bowers E<lt>neilb@cre.canon.co.ukE<gt> |
267 | |
268 | =head1 COPYRIGHT |
269 | |
270 | Copyright (c) 2001 Michael Hennecke and |
271 | Canon Research Centre Europe (CRE). |
272 | |
273 | This module is free software; you can redistribute it and/or |
274 | modify it under the same terms as Perl itself. |
275 | |
276 | =cut |
277 | |
278 | #----------------------------------------------------------------------- |
279 | |
280 | #======================================================================= |
281 | # initialisation code - stuff the DATA into the CODES hash |
282 | #======================================================================= |
283 | { |
284 | my $code; |
285 | my $currency; |
286 | |
287 | |
288 | while (<DATA>) |
289 | { |
290 | next unless /\S/; |
291 | chop; |
292 | ($code, $currency) = split(/:/, $_, 2); |
293 | $CODES{$code} = $currency; |
294 | $CURRENCIES{"\L$currency"} = $code; |
295 | } |
296 | } |
297 | |
298 | 1; |
299 | |
300 | __DATA__ |
301 | adp:Andorran Peseta |
302 | aed:UAE Dirham |
303 | afa:Afghani |
304 | all:Lek |
305 | amd:Armenian Dram |
306 | ang:Netherlands Antillean Guilder |
307 | aoa:Kwanza |
308 | aon:New Kwanza |
309 | aor:Kwanza Reajustado |
310 | ars:Argentine Peso |
311 | ats:Schilling |
312 | aud:Australian Dollar |
313 | awg:Aruban Guilder |
314 | azm:Azerbaijanian Manat |
315 | |
316 | bam:Convertible Marks |
317 | bbd:Barbados Dollar |
318 | bdt:Taka |
319 | bef:Belgian Franc |
320 | bgl:Lev |
321 | bgn:Bulgarian Lev |
322 | bhd:Bahraini Dinar |
323 | bhd:Dinar |
324 | bif:Burundi Franc |
325 | bmd:Bermudian Dollar |
326 | bnd:Brunei Dollar |
327 | bob:Boliviano |
328 | bov:MVDol |
329 | brl:Brazilian Real |
330 | bsd:Bahamian Dollar |
331 | btn:Ngultrum |
332 | bwp:Pula |
333 | byb:Belarussian Ruble |
334 | byr:Belarussian Ruble |
335 | bzd:Belize Dollar |
336 | |
337 | cad:Candian Dollar |
338 | cdf:Franc Congolais |
339 | chf:Swiss Franc |
340 | clf:Unidades de Formento |
341 | clp:Chilean Peso |
342 | cny:Yuan Renminbi |
343 | cop:Colombian Peso |
344 | crc:Costa Rican Colon |
345 | cup:Cuban Peso |
346 | cve:Cape Verde Escudo |
347 | cyp:Cyprus Pound |
348 | czk:Czech Koruna |
349 | |
350 | dem:German Mark |
351 | djf:Djibouti Franc |
352 | dkk:Danish Krone |
353 | dop:Dominican Peso |
354 | dzd:Algerian Dinar |
355 | |
356 | ecs:Sucre |
357 | ecv:Unidad de Valor Constante (UVC) |
358 | eek:Kroon |
359 | egp:Egyptian Pound |
360 | ern:Nakfa |
361 | esp:Spanish Peseta |
362 | etb:Ethiopian Birr |
363 | eur:Euro |
364 | |
365 | fim:Markka |
366 | fjd:Fiji Dollar |
367 | fkp:Falkland Islands Pound |
368 | frf:French Franc |
369 | |
370 | gbp:Pound Sterling |
371 | gel:Lari |
372 | ghc:Cedi |
373 | gip:Gibraltar Pound |
374 | gmd:Dalasi |
375 | gnf:Guinea Franc |
376 | grd:Drachma |
377 | gtq:Quetzal |
378 | gwp:Guinea-Bissau Peso |
379 | gyd:Guyana Dollar |
380 | |
381 | hkd:Hong Kong Dollar |
382 | hnl:Lempira |
383 | hrk:Kuna |
384 | htg:Gourde |
385 | huf:Forint |
386 | |
387 | idr:Rupiah |
388 | iep:Irish Pound |
389 | ils:Shekel |
390 | inr:Indian Rupee |
391 | iqd:Iraqi Dinar |
392 | irr:Iranian Rial |
393 | isk:Iceland Krona |
394 | itl:Italian Lira |
395 | |
396 | jmd:Jamaican Dollar |
397 | jod:Jordanian Dinar |
398 | jpy:Yen |
399 | |
400 | kes:Kenyan Shilling |
401 | kgs:Som |
402 | khr:Riel |
403 | kmf:Comoro Franc |
404 | kpw:North Korean Won |
405 | krw:Won |
406 | kwd:Kuwaiti Dinar |
407 | kyd:Cayman Islands Dollar |
408 | kzt:Tenge |
409 | |
410 | lak:Kip |
411 | lbp:Lebanese Pound |
412 | lkr:Sri Lanka Rupee |
413 | lrd:Liberian Dollar |
414 | lsl:Loti |
415 | ltl:Lithuanian Litas |
416 | luf:Luxembourg Franc |
417 | lvl:Latvian Lats |
418 | lyd:Libyan Dinar |
419 | |
420 | mad:Moroccan Dirham |
421 | mdl:Moldovan Leu |
422 | mgf:Malagasy Franc |
423 | mkd:Denar |
424 | mmk:Kyat |
425 | mnt:Tugrik |
426 | mop:Pataca |
427 | mro:Ouguiya |
428 | mtl:Maltese Lira |
429 | mur:Mauritius Rupee |
430 | mvr:Rufiyaa |
431 | mwk:Kwacha |
432 | mxn:Mexican Nuevo Peso |
433 | myr:Malaysian Ringgit |
434 | mzm:Metical |
435 | |
436 | nad:Namibia Dollar |
437 | ngn:Naira |
438 | nio:Cordoba Oro |
439 | nlg:Netherlands Guilder |
440 | nok:Norwegian Krone |
441 | npr:Nepalese Rupee |
442 | nzd:New Zealand Dollar |
443 | |
444 | omr:Rial Omani |
445 | |
446 | pab:Balboa |
447 | pen:Nuevo Sol |
448 | pgk:Kina |
449 | php:Philippine Peso |
450 | pkr:Pakistan Rupee |
451 | pln:Zloty |
452 | pte:Portuguese Escudo |
453 | pyg:Guarani |
454 | |
455 | qar:Qatari Rial |
456 | |
457 | rol:Leu |
458 | rub:Russian Ruble |
459 | rur:Russian Ruble |
460 | rwf:Rwanda Franc |
461 | |
462 | sar:Saudi Riyal |
463 | sbd:Solomon Islands Dollar |
464 | scr:Seychelles Rupee |
465 | sdd:Sudanese Dinar |
466 | sek:Swedish Krona |
467 | sgd:Singapore Dollar |
468 | shp:St. Helena Pound |
469 | sit:Tolar |
470 | skk:Slovak Koruna |
471 | sll:Leone |
472 | sos:Somali Shilling |
473 | srg:Surinam Guilder |
474 | std:Dobra |
475 | svc:El Salvador Colon |
476 | syp:Syrian Pound |
477 | szl:Lilangeni |
478 | |
479 | thb:Baht |
480 | tjr:Tajik Ruble |
481 | tmm:Manat |
482 | tnd:Tunisian Dollar |
483 | top:Pa'anga |
484 | tpe:Timor Escudo |
485 | trl:Turkish Lira |
486 | ttd:Trinidad and Tobago Dollar |
487 | twd:New Taiwan Dollar |
488 | tzs:Tanzanian Shilling |
489 | |
490 | uah:Hryvnia |
491 | uak:Karbovanets |
492 | ugx:Uganda Shilling |
493 | usd:US Dollar |
494 | usn:US Dollar (Next day) |
495 | uss:US Dollar (Same day) |
496 | uyu:Peso Uruguayo |
497 | uzs:Uzbekistan Sum |
498 | |
499 | veb:Bolivar |
500 | vnd:Dong |
501 | vuv:Vatu |
502 | |
503 | wst:Tala |
504 | |
505 | xaf:CFA Franc BEAC |
506 | xag:Silver |
507 | xau:Gold |
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 |
513 | xdr:SDR |
514 | xeu:ECU (until 1998-12-31) |
515 | xfu:UIC-Franc |
516 | xfo:Gold-Franc |
517 | xof:CFA Franc BCEAO |
518 | xpd:Palladium |
519 | xpf:CFP Franc |
520 | xpt:Platinum |
521 | |
522 | yer:Yemeni Rial |
523 | yum:New Dinar |
524 | |
525 | zal:Financial Rand |
526 | zar:Rand |
527 | zmk:Kwacha |
528 | zrn:New Zaire |
529 | zwd:Zimbabwe Dollar |