mingw/html/lib/Locale/Country.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::Country - ISO codes for country 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::Country - ISO codes for country 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="#semiprivate_routines">SEMI-PRIVATE ROUTINES</a></li>
  28         <ul>
  29
  30                 <li><a href="#alias_code">alias_code</a></li>
  31                 <li><a href="#rename_country">rename_country</a></li>
  32         </ul>
  33
  34         <li><a href="#examples">EXAMPLES</a></li>
  35         <li><a href="#domain_names">DOMAIN NAMES</a></li>
  36         <li><a href="#known_bugs_and_limitations">KNOWN BUGS AND LIMITATIONS</a></li>
  37         <li><a href="#see_also">SEE ALSO</a></li>
  38         <li><a href="#author">AUTHOR</a></li>
  39         <li><a href="#copyright">COPYRIGHT</a></li>
  40 </ul>
  41 <!-- INDEX END -->
  42
  43 <hr />
  44 <p>
  45 </p>
  46 <h1><a name="name">NAME</a></h1>
  47 <p>Locale::Country - ISO codes for country identification (ISO 3166)</p>
  48 <p>
  49 </p>
  50 <hr />
  51 <h1><a name="synopsis">SYNOPSIS</a></h1>
  52 <pre>
  53     use Locale::Country;
  54
  55     $country = code2country('jp');        # $country gets 'Japan'
  56     $code    = country2code('Norway');    # $code gets 'no'
  57
  58     @codes   = all_country_codes();
  59     @names   = all_country_names();
  60
  61     # semi-private routines
  62     Locale::Country::alias_code('uk' =&gt; 'gb');
  63     Locale::Country::rename_country('gb' =&gt; 'Great Britain');</pre>
  64 <p>
  65 </p>
  66 <hr />
  67 <h1><a name="description">DESCRIPTION</a></h1>
  68 <p>The <code>Locale::Country</code> module provides access to the ISO
  69 codes for identifying countries, as defined in ISO 3166-1.
  70 You can either access the codes via the <a href="#conversion_routines">conversion routines</a>
  71 (described below), or with the two functions which return lists
  72 of all country codes or all country names.</p>
  73 <p>There are three different code sets you can use for identifying
  74 countries:</p>
  75 <dl>
  76 <dt><strong><a name="item_alpha_2d2"><strong>alpha-2</strong></a></strong>
  77
  78 <dd>
  79 <p>Two letter codes, such as 'tv' for Tuvalu.
  80 This code set is identified with the symbol <code>LOCALE_CODE_ALPHA_2</code>.</p>
  81 </dd>
  82 </li>
  83 <dt><strong><a name="item_alpha_2d3"><strong>alpha-3</strong></a></strong>
  84
  85 <dd>
  86 <p>Three letter codes, such as 'brb' for Barbados.
  87 This code set is identified with the symbol <code>LOCALE_CODE_ALPHA_3</code>.</p>
  88 </dd>
  89 </li>
  90 <dt><strong><a name="item_numeric"><strong>numeric</strong></a></strong>
  91
  92 <dd>
  93 <p>Numeric codes, such as 064 for Bhutan.
  94 This code set is identified with the symbol <code>LOCALE_CODE_NUMERIC</code>.</p>
  95 </dd>
  96 </li>
  97 </dl>
  98 <p>All of the routines take an optional additional argument
  99 which specifies the code set to use.
 100 If not specified, it defaults to the two-letter codes.
 101 This is partly for backwards compatibility (previous versions
 102 of this module only supported the alpha-2 codes), and
 103 partly because they are the most widely used codes.</p>
 104 <p>The alpha-2 and alpha-3 codes are not case-dependent,
 105 so you can use 'BO', 'Bo', 'bO' or 'bo' for Bolivia.
 106 When a code is returned by one of the functions in
 107 this module, it will always be lower-case.</p>
 108 <p>As of version 2.00, Locale::Country supports variant
 109 names for countries. So, for example, the country code for ``United States''
 110 is ``us'', so country2code('United States') returns 'us'.
 111 Now the following will also return 'us':</p>
 112 <pre>
 113     country2code('United States of America')
 114     country2code('USA')</pre>
 115 <p>
 116 </p>
 117 <hr />
 118 <h1><a name="conversion_routines">CONVERSION ROUTINES</a></h1>
 119 <p>There are three conversion routines: <a href="#item_code2country"><code>code2country()</code></a>, <a href="#item_country2code"><code>country2code()</code></a>,
 120 and <a href="#item_country_code2code"><code>country_code2code()</code></a>.</p>
 121 <dl>
 122 <dt><strong><a name="item_code2country">code2country( CODE, [ CODESET ] )</a></strong>
 123
 124 <dd>
 125 <p>This function takes a country code and returns a string
 126 which contains the name of the country identified.
 127 If the code is not a valid country code, as defined by ISO 3166,
 128 then <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> will be returned:</p>
 129 </dd>
 130 <dd>
 131 <pre>
 132     $country = code2country('fi');</pre>
 133 </dd>
 134 </li>
 135 <dt><strong><a name="item_country2code">country2code( STRING, [ CODESET ] )</a></strong>
 136
 137 <dd>
 138 <p>This function takes a country name and returns the corresponding
 139 country code, if such exists.
 140 If the argument could not be identified as a country name,
 141 then <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> will be returned:</p>
 142 </dd>
 143 <dd>
 144 <pre>
 145     $code = country2code('Norway', LOCALE_CODE_ALPHA_3);
 146     # $code will now be 'nor'</pre>
 147 </dd>
 148 <dd>
 149 <p>The case of the country name is not important.
 150 See the section <a href="#known_bugs_and_limitations">KNOWN BUGS AND LIMITATIONS</a> below.</p>
 151 </dd>
 152 </li>
 153 <dt><strong><a name="item_country_code2code">country_code2code( CODE, CODESET, CODESET )</a></strong>
 154
 155 <dd>
 156 <p>This function takes a country code from one code set,
 157 and returns the corresponding code from another code set.</p>
 158 </dd>
 159 <dd>
 160 <pre>
 161     $alpha2 = country_code2code('fin',
 162                  LOCALE_CODE_ALPHA_3, LOCALE_CODE_ALPHA_2);
 163     # $alpha2 will now be 'fi'</pre>
 164 </dd>
 165 <dd>
 166 <p>If the code passed is not a valid country code in
 167 the first code set, or if there isn't a code for the
 168 corresponding country in the second code set,
 169 then <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> will be returned.</p>
 170 </dd>
 171 </li>
 172 </dl>
 173 <p>
 174 </p>
 175 <hr />
 176 <h1><a name="query_routines">QUERY ROUTINES</a></h1>
 177 <p>There are two function which can be used to obtain a list of all codes,
 178 or all country names:</p>
 179 <dl>
 180 <dt><strong><a name="item_all_country_codes"><code>all_country_codes( [ CODESET ] )</code></a></strong>
 181
 182 <dd>
 183 <p>Returns a list of all two-letter country codes.
 184 The codes are guaranteed to be all lower-case,
 185 and not in any particular order.</p>
 186 </dd>
 187 </li>
 188 <dt><strong><a name="item_all_country_names"><code>all_country_names( [ CODESET ] )</code></a></strong>
 189
 190 <dd>
 191 <p>Returns a list of all country names for which there is a corresponding
 192 country code in the specified code set.
 193 The names are capitalised, and not returned in any particular order.</p>
 194 </dd>
 195 <dd>
 196 <p>Not all countries have alpha-3 and numeric codes -
 197 some just have an alpha-2 code,
 198 so you'll get a different number of countries
 199 depending on which code set you specify.</p>
 200 </dd>
 201 </li>
 202 </dl>
 203 <p>
 204 </p>
 205 <hr />
 206 <h1><a name="semiprivate_routines">SEMI-PRIVATE ROUTINES</a></h1>
 207 <p>Locale::Country provides two semi-private routines for modifying
 208 the internal data.
 209 Given their status, they aren't exported by default,
 210 and so need to be called by prefixing the function name with the
 211 package name.</p>
 212 <p>
 213 </p>
 214 <h2><a name="alias_code">alias_code</a></h2>
 215 <p>Define a new code as an alias for an existing code:</p>
 216 <pre>
 217     Locale::Country::alias_code( ALIAS =&gt; CODE [, CODESET ] )</pre>
 218 <p>This feature was added as a mechanism for handling
 219 a ``uk'' code. The ISO standard says that the two-letter code for
 220 ``United Kingdom'' is ``gb'', whereas domain names are all .uk.</p>
 221 <p>By default the module does not understand ``uk'', since it is implementing
 222 an ISO standard. If you would like 'uk' to work as the two-letter
 223 code for United Kingdom, use the following:</p>
 224 <pre>
 225     Locale::Country::alias_code('uk' =&gt; 'gb');</pre>
 226 <p>With this code, both ``uk'' and ``gb'' are valid codes for United Kingdom,
 227 with the reverse lookup returning ``uk'' rather than the usual ``gb''.</p>
 228 <p><strong>Note:</strong> this function was previously called _alias_code,
 229 but the leading underscore has been dropped.
 230 The old name will be supported for all 2.X releases for
 231 backwards compatibility.</p>
 232 <p>
 233 </p>
 234 <h2><a name="rename_country">rename_country</a></h2>
 235 <p>If the official country name just isn't good enough for you,
 236 you can rename a country. For example, the official country
 237 name for code 'gb' is 'United Kingdom'.
 238 If you want to change that, you might call:</p>
 239 <pre>
 240     Locale::Country::rename_country('gb' =&gt; 'Great Britain');</pre>
 241 <p>This means that calling <a href="#item_code2country"><code>code2country('gb')</code></a> will now return
 242 'Great Britain' instead of 'United Kingdom'.
 243 The original country name is retained as an alias,
 244 so for the above example, country2code('United Kingdom')
 245 will still return 'gb'.</p>
 246 <p>
 247 </p>
 248 <hr />
 249 <h1><a name="examples">EXAMPLES</a></h1>
 250 <p>The following example illustrates use of the <a href="#item_code2country"><code>code2country()</code></a> function.
 251 The user is prompted for a country code, and then told the corresponding
 252 country name:</p>
 253 <pre>
 254     $| = 1;   # turn off buffering
 255
 256     print &quot;Enter country code: &quot;;
 257     chop($code = &lt;STDIN&gt;);
 258     $country = code2country($code, LOCALE_CODE_ALPHA_2);
 259     if (defined $country)
 260     {
 261         print &quot;$code = $country\n&quot;;
 262     }
 263     else
 264     {
 265         print &quot;'$code' is not a valid country code!\n&quot;;
 266     }</pre>
 267 <p>
 268 </p>
 269 <hr />
 270 <h1><a name="domain_names">DOMAIN NAMES</a></h1>
 271 <p>Most top-level domain names are based on these codes,
 272 but there are certain codes which aren't.
 273 If you are using this module to identify country from hostname,
 274 your best bet is to preprocess the country code.</p>
 275 <p>For example, <strong>edu</strong>, <strong>com</strong>, <strong>gov</strong> and friends would map to <strong>us</strong>;
 276 <strong>uk</strong> would map to <strong>gb</strong>. Any others?</p>
 277 <p>
 278 </p>
 279 <hr />
 280 <h1><a name="known_bugs_and_limitations">KNOWN BUGS AND LIMITATIONS</a></h1>
 281 <ul>
 282 <li>
 283 <p>When using <a href="#item_country2code"><code>country2code()</code></a>, the country name must currently appear
 284 exactly as it does in the source of the module. The module now supports
 285 a small number of variants.</p>
 286 <p>Possible extensions to this are: an interface for getting at the
 287 list of variant names, and regular expression matches.</p>
 288 </li>
 289 <li>
 290 <p>In the current implementation, all data is read in when the
 291 module is loaded, and then held in memory.
 292 A lazy implementation would be more memory friendly.</p>
 293 </li>
 294 <li>
 295 <p>Support for country names in different languages.</p>
 296 </li>
 297 </ul>
 298 <p>
 299 </p>
 300 <hr />
 301 <h1><a name="see_also">SEE ALSO</a></h1>
 302 <dl>
 303 <dt><strong><a name="item_locale_3a_3alanguage">Locale::Language</a></strong>
 304
 305 <dd>
 306 <p>ISO two letter codes for identification of language (ISO 639).</p>
 307 </dd>
 308 </li>
 309 <dt><strong><a name="item_locale_3a_3ascript">Locale::Script</a></strong>
 310
 311 <dd>
 312 <p>ISO codes for identification of scripts (ISO 15924).</p>
 313 </dd>
 314 </li>
 315 <dt><strong><a name="item_locale_3a_3acurrency">Locale::Currency</a></strong>
 316
 317 <dd>
 318 <p>ISO three letter codes for identification of currencies
 319 and funds (ISO 4217).</p>
 320 </dd>
 321 </li>
 322 <dt><strong><a name="item_locale_3a_3asubcountry">Locale::SubCountry</a></strong>
 323
 324 <dd>
 325 <p>ISO codes for country sub-divisions (states, counties, provinces, etc),
 326 as defined in ISO 3166-2.
 327 This module is not part of the Locale-Codes distribution,
 328 but is available from CPAN in CPAN/modules/by-module/Locale/</p>
 329 </dd>
 330 </li>
 331 <dt><strong><a name="item_iso_3166_2d1">ISO 3166-1</a></strong>
 332
 333 <dd>
 334 <p>The ISO standard which defines these codes.</p>
 335 </dd>
 336 </li>
 337 <dt><strong><a name="item_http_3a_2f_2fwww_2eiso_2eorg_2fiso_2fen_2fprods_2d"><a href="http://www.iso.org/iso/en/prods-services/iso3166ma/index.html">http://www.iso.org/iso/en/prods-services/iso3166ma/index.html</a></a></strong>
 338
 339 <dd>
 340 <p>Official home page for the ISO 3166 maintenance agency.</p>
 341 </dd>
 342 </li>
 343 <dt><strong><a name="item_http_3a_2f_2fwww_2eegt_2eie_2fstandards_2fiso3166_"><a href="http://www.egt.ie/standards/iso3166/iso3166-1-en.html">http://www.egt.ie/standards/iso3166/iso3166-1-en.html</a></a></strong>
 344
 345 <dd>
 346 <p>Another useful, but not official, home page.</p>
 347 </dd>
 348 </li>
 349 <dt><strong><a name="item_http_3a_2f_2fwww_2ecia_2egov_2fcia_2fpublications_"><a href="http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html">http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html</a></a></strong>
 350
 351 <dd>
 352 <p>An appendix in the CIA world fact book which lists country codes
 353 as defined by ISO 3166, FIPS 10-4, and internet domain names.</p>
 354 </dd>
 355 </li>
 356 </dl>
 357 <p>
 358 </p>
 359 <hr />
 360 <h1><a name="author">AUTHOR</a></h1>
 361 <p>Neil Bowers &lt;<a href="mailto:neil@bowers.com">neil@bowers.com</a>&gt;</p>
 362 <p>
 363 </p>
 364 <hr />
 365 <h1><a name="copyright">COPYRIGHT</a></h1>
 366 <p>Copyright (C) 2002-2004, Neil Bowers.</p>
 367 <p>Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).</p>
 368 <p>This module is free software; you can redistribute it and/or
 369 modify it under the same terms as Perl itself.</p>
 370 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 371 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 372 <big><strong><span class="block">&nbsp;Locale::Country - ISO codes for country identification</span></strong></big>
 373 </td></tr>
 374 </table>
 375
 376 </body>
 377
 378 </html>