mingw/html/lib/Locale/Currency.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Locale::Currency - ISO three letter codes for currency identification</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Locale::Currency - ISO three letter codes for currency identification</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#conversion_routines">CONVERSION ROUTINES</a></li>
  26         <li><a href="#query_routines">QUERY ROUTINES</a></li>
  27         <li><a href="#examples">EXAMPLES</a></li>
  28         <li><a href="#known_bugs_and_limitations">KNOWN BUGS AND LIMITATIONS</a></li>
  29         <li><a href="#see_also">SEE ALSO</a></li>
  30         <li><a href="#author">AUTHOR</a></li>
  31         <li><a href="#copyright">COPYRIGHT</a></li>
  32 </ul>
  33 <!-- INDEX END -->
  34
  35 <hr />
  36 <p>
  37 </p>
  38 <h1><a name="name">NAME</a></h1>
  39 <p>Locale::Currency - ISO three letter codes for currency identification (ISO 4217)</p>
  40 <p>
  41 </p>
  42 <hr />
  43 <h1><a name="synopsis">SYNOPSIS</a></h1>
  44 <pre>
  45     use Locale::Currency;</pre>
  46 <pre>
  47     $curr = code2currency('usd');     # $curr gets 'US Dollar'
  48     $code = currency2code('Euro');    # $code gets 'eur'</pre>
  49 <pre>
  50     @codes   = all_currency_codes();
  51     @names   = all_currency_names();</pre>
  52 <p>
  53 </p>
  54 <hr />
  55 <h1><a name="description">DESCRIPTION</a></h1>
  56 <p>The <code>Locale::Currency</code> module provides access to the ISO three-letter
  57 codes for identifying currencies and funds, as defined in ISO 4217.
  58 You can either access the codes via the <a href="#conversion_routines">conversion routines</a>
  59 (described below),
  60 or with the two functions which return lists of all currency codes or
  61 all currency names.</p>
  62 <p>There are two special codes defined by the standard which aren't
  63 understood by this module:</p>
  64 <dl>
  65 <dt><strong><a name="item_xts">XTS</a></strong>
  66
  67 <dd>
  68 <p>Specifically reserved for testing purposes.</p>
  69 </dd>
  70 </li>
  71 <dt><strong><a name="item_xxx">XXX</a></strong>
  72
  73 <dd>
  74 <p>For transactions where no currency is involved.</p>
  75 </dd>
  76 </li>
  77 </dl>
  78 <p>
  79 </p>
  80 <hr />
  81 <h1><a name="conversion_routines">CONVERSION ROUTINES</a></h1>
  82 <p>There are two conversion routines: <a href="#item_code2currency"><code>code2currency()</code></a> and <a href="#item_currency2code"><code>currency2code()</code></a>.</p>
  83 <dl>
  84 <dt><strong><a name="item_code2currency"><code>code2currency()</code></a></strong>
  85
  86 <dd>
  87 <p>This function takes a three letter currency code and returns a string
  88 which contains the name of the currency identified. If the code is
  89 not a valid currency code, as defined by ISO 4217, then <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a>
  90 will be returned.</p>
  91 </dd>
  92 <dd>
  93 <pre>
  94     $curr = code2currency($code);</pre>
  95 </dd>
  96 </li>
  97 <dt><strong><a name="item_currency2code"><code>currency2code()</code></a></strong>
  98
  99 <dd>
 100 <p>This function takes a currency name and returns the corresponding
 101 three letter currency code, if such exists.
 102 If the argument could not be identified as a currency name,
 103 then <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> will be returned.</p>
 104 </dd>
 105 <dd>
 106 <pre>
 107     $code = currency2code('French Franc');</pre>
 108 </dd>
 109 <dd>
 110 <p>The case of the currency name is not important.
 111 See the section <a href="#known_bugs_and_limitations">KNOWN BUGS AND LIMITATIONS</a> below.</p>
 112 </dd>
 113 </li>
 114 </dl>
 115 <p>
 116 </p>
 117 <hr />
 118 <h1><a name="query_routines">QUERY ROUTINES</a></h1>
 119 <p>There are two function which can be used to obtain a list of all
 120 currency codes, or all currency names:</p>
 121 <dl>
 122 <dt><strong><a name="item_all_currency_codes"><code>all_currency_codes()</code></a></strong>
 123
 124 <dd>
 125 <p>Returns a list of all three-letter currency codes.
 126 The codes are guaranteed to be all lower-case,
 127 and not in any particular order.</p>
 128 </dd>
 129 </li>
 130 <dt><strong><a name="item_all_currency_names"><code>all_currency_names()</code></a></strong>
 131
 132 <dd>
 133 <p>Returns a list of all currency names for which there is a corresponding
 134 three-letter currency code. The names are capitalised, and not returned
 135 in any particular order.</p>
 136 </dd>
 137 </li>
 138 </dl>
 139 <p>
 140 </p>
 141 <hr />
 142 <h1><a name="examples">EXAMPLES</a></h1>
 143 <p>The following example illustrates use of the <a href="#item_code2currency"><code>code2currency()</code></a> function.
 144 The user is prompted for a currency code, and then told the corresponding
 145 currency name:</p>
 146 <pre>
 147     $| = 1;    # turn off buffering</pre>
 148 <pre>
 149     print &quot;Enter currency code: &quot;;
 150     chop($code = &lt;STDIN&gt;);
 151     $curr = code2currency($code);
 152     if (defined $curr)
 153     {
 154         print &quot;$code = $curr\n&quot;;
 155     }
 156     else
 157     {
 158         print &quot;'$code' is not a valid currency code!\n&quot;;
 159     }</pre>
 160 <p>
 161 </p>
 162 <hr />
 163 <h1><a name="known_bugs_and_limitations">KNOWN BUGS AND LIMITATIONS</a></h1>
 164 <ul>
 165 <li>
 166 <p>In the current implementation, all data is read in when the
 167 module is loaded, and then held in memory.
 168 A lazy implementation would be more memory friendly.</p>
 169 </li>
 170 <li>
 171 <p>This module also includes the special codes which are
 172 not for a currency, such as Gold, Platinum, etc.
 173 This might cause a problem if you're using this module
 174 to display a list of currencies.
 175 Let Neil know if this does cause a problem, and we can
 176 do something about it.</p>
 177 </li>
 178 <li>
 179 <p>ISO 4217 also defines a numeric code for each currency.
 180 Currency codes are not currently supported by this module,
 181 in the same way Locale::Country supports multiple codesets.</p>
 182 </li>
 183 <li>
 184 <p>There are three cases where there is more than one
 185 code for the same currency name.
 186 Kwacha has two codes: mwk for Malawi, and zmk for Zambia.
 187 The Russian Ruble has two codes: rub and rur.
 188 The Belarussian Ruble has two codes: byr and byb.
 189 The <a href="#item_currency2code"><code>currency2code()</code></a> function only returns one code, so
 190 you might not get back the code you expected.</p>
 191 </li>
 192 </ul>
 193 <p>
 194 </p>
 195 <hr />
 196 <h1><a name="see_also">SEE ALSO</a></h1>
 197 <dl>
 198 <dt><strong><a name="item_locale_3a_3acountry">Locale::Country</a></strong>
 199
 200 <dd>
 201 <p>ISO codes for identification of country (ISO 3166).</p>
 202 </dd>
 203 </li>
 204 <dt><strong><a name="item_locale_3a_3ascript">Locale::Script</a></strong>
 205
 206 <dd>
 207 <p>ISO codes for identification of written scripts (ISO 15924).</p>
 208 </dd>
 209 </li>
 210 <dt><strong><a name="item_iso_4217_3a1995">ISO 4217:1995</a></strong>
 211
 212 <dd>
 213 <p>Code for the representation of currencies and funds.</p>
 214 </dd>
 215 </li>
 216 <dt><strong><a name="item_http_3a_2f_2fwww_2ebsi_2dglobal_2ecom_2fiso4217cur"><a href="http://www.bsi-global.com/iso4217currency">http://www.bsi-global.com/iso4217currency</a></a></strong>
 217
 218 <dd>
 219 <p>Official web page for the ISO 4217 maintenance agency.
 220 This has the latest list of codes, in MS Word format. Boo.</p>
 221 </dd>
 222 </li>
 223 </dl>
 224 <p>
 225 </p>
 226 <hr />
 227 <h1><a name="author">AUTHOR</a></h1>
 228 <p>Michael Hennecke &lt;<a href="mailto:hennecke@rz.uni-karlsruhe.de">hennecke@rz.uni-karlsruhe.de</a>&gt;
 229 and
 230 Neil Bowers &lt;<a href="mailto:neil@bowers.com">neil@bowers.com</a>&gt;</p>
 231 <p>
 232 </p>
 233 <hr />
 234 <h1><a name="copyright">COPYRIGHT</a></h1>
 235 <p>Copyright (C) 2002-2004, Neil Bowers.</p>
 236 <p>Copyright (c) 2001 Michael Hennecke and
 237 Canon Research Centre Europe (CRE).</p>
 238 <p>This module is free software; you can redistribute it and/or
 239 modify it under the same terms as Perl itself.</p>
 240 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 241 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 242 <big><strong><span class="block">&nbsp;Locale::Currency - ISO three letter codes for currency identification</span></strong></big>
 243 </td></tr>
 244 </table>
 245
 246 </body>
 247
 248 </html>