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: 1.3 $ =~ /(\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
 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