[Summary view] [Print] [Text view]

   1  
   2  =head1 NAME
   3  
   4  Locale::Currency - ISO three letter codes for currency identification (ISO 4217)
   5  
   6  =head1 SYNOPSIS
   7  
   8      use Locale::Currency;
   9  
  10      $curr = code2currency('usd');     # $curr gets 'US Dollar'
  11      $code = currency2code('Euro');    # $code gets 'eur'
  12  
  13      @codes   = all_currency_codes();
  14      @names   = all_currency_names();
  15  
  16  
  17  =head1 DESCRIPTION
  18  
  19  The C<Locale::Currency> module provides access to the ISO three-letter
  20  codes for identifying currencies and funds, as defined in ISO 4217.
  21  You can either access the codes via the L<conversion routines>
  22  (described below),
  23  or with the two functions which return lists of all currency codes or
  24  all currency names.
  25  
  26  There are two special codes defined by the standard which aren't
  27  understood by this module:
  28  
  29  =over 4
  30  
  31  =item XTS
  32  
  33  Specifically reserved for testing purposes.
  34  
  35  =item XXX
  36  
  37  For transactions where no currency is involved.
  38  
  39  =back
  40  
  41  
  42  =head1 CONVERSION ROUTINES
  43  
  44  There are two conversion routines: C<code2currency()> and C<currency2code()>.
  45  
  46  =over 4
  47  
  48  =item code2currency()
  49  
  50  This function takes a three letter currency code and returns a string
  51  which contains the name of the currency identified. If the code is
  52  not a valid currency code, as defined by ISO 4217, then C<undef>
  53  will be returned.
  54  
  55      $curr = code2currency($code);
  56  
  57  =item currency2code()
  58  
  59  This function takes a currency name and returns the corresponding
  60  three letter currency code, if such exists.
  61  If the argument could not be identified as a currency name,
  62  then C<undef> will be returned.
  63  
  64      $code = currency2code('French Franc');
  65  
  66  The case of the currency name is not important.
  67  See the section L<KNOWN BUGS AND LIMITATIONS> below.
  68  
  69  =back
  70  
  71  
  72  =head1 QUERY ROUTINES
  73  
  74  There are two function which can be used to obtain a list of all
  75  currency codes, or all currency names:
  76  
  77  =over 4
  78  
  79  =item C<all_currency_codes()>
  80  
  81  Returns a list of all three-letter currency codes.
  82  The codes are guaranteed to be all lower-case,
  83  and not in any particular order.
  84  
  85  =item C<all_currency_names()>
  86  
  87  Returns a list of all currency names for which there is a corresponding
  88  three-letter currency code. The names are capitalised, and not returned
  89  in any particular order.
  90  
  91  =back
  92  
  93  
  94  =head1 EXAMPLES
  95  
  96  The following example illustrates use of the C<code2currency()> function.
  97  The user is prompted for a currency code, and then told the corresponding
  98  currency name:
  99  
 100      $| = 1;    # turn off buffering
 101  
 102      print "Enter currency code: ";
 103      chop($code = <STDIN>);
 104      $curr = code2currency($code);
 105      if (defined $curr)
 106      {
 107          print "$code = $curr\n";
 108      }
 109      else
 110      {
 111          print "'$code' is not a valid currency code!\n";
 112      }
 113  
 114  =head1 KNOWN BUGS AND LIMITATIONS
 115  
 116  =over 4
 117  
 118  =item *
 119  
 120  In the current implementation, all data is read in when the
 121  module is loaded, and then held in memory.
 122  A lazy implementation would be more memory friendly.
 123  
 124  =item *
 125  
 126  This module also includes the special codes which are
 127  not for a currency, such as Gold, Platinum, etc.
 128  This might cause a problem if you're using this module
 129  to display a list of currencies.
 130  Let Neil know if this does cause a problem, and we can
 131  do something about it.
 132  
 133  =item *
 134  
 135  ISO 4217 also defines a numeric code for each currency.
 136  Currency codes are not currently supported by this module,
 137  in the same way Locale::Country supports multiple codesets.
 138  
 139  =item *
 140  
 141  There are three cases where there is more than one
 142  code for the same currency name.
 143  Kwacha has two codes: mwk for Malawi, and zmk for Zambia.
 144  The Russian Ruble has two codes: rub and rur.
 145  The Belarussian Ruble has two codes: byr and byb.
 146  The currency2code() function only returns one code, so
 147  you might not get back the code you expected.
 148  
 149  =back
 150  
 151  =head1 SEE ALSO
 152  
 153  =over 4
 154  
 155  =item Locale::Country
 156  
 157  ISO codes for identification of country (ISO 3166).
 158  
 159  =item Locale::Script
 160  
 161  ISO codes for identification of written scripts (ISO 15924).
 162  
 163  =item ISO 4217:1995
 164  
 165  Code for the representation of currencies and funds.
 166  
 167  =item http://www.bsi-global.com/iso4217currency
 168  
 169  Official web page for the ISO 4217 maintenance agency.
 170  This has the latest list of codes, in MS Word format. Boo.
 171  
 172  =back
 173  
 174  =head1 AUTHOR
 175  
 176  Michael Hennecke E<lt>hennecke@rz.uni-karlsruhe.deE<gt>
 177  and
 178  Neil Bowers E<lt>neil@bowers.comE<gt>
 179  
 180  =head1 COPYRIGHT
 181  
 182  Copyright (C) 2002-2004, Neil Bowers.
 183  
 184  Copyright (c) 2001 Michael Hennecke and
 185  Canon Research Centre Europe (CRE).
 186  
 187  This module is free software; you can redistribute it and/or
 188  modify it under the same terms as Perl itself.
 189  
 190  =cut
 191