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