home *** CD-ROM | disk | FTP | other *** search
/ PC World 2005 June / PCWorld_2005-06_cd.bin / software / vyzkuste / firewally / firewally.exe / framework-2.3.exe / Currency.pod < prev    next >
Text File  |  2003-11-07  |  4KB  |  192 lines
  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, 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.  
  192.