<P>There are two conversion routines: <A HREF="#item_code2country"><CODE>code2country()</CODE></A> and <A HREF="#item_country2code"><CODE>country2code()</CODE></A>.</P>
<P>This module supports a semi-private routine for specifying two letter
code aliases. This feature was added as a mechanism for handling
a ``uk'' code. The ISO standard says that the two-letter code for
``United Kingdom'' is ``gb'', whereas domain names are all .uk.</P>
<P>By default the module does not understand ``uk'', since it is implementing
an ISO standard. If you would like 'uk' to work as the two-letter
code for United Kingdom, use the following:</P>
<PRE>
use Locale::Country;
</PRE>
<PRE>
Locale::Country::_alias_code('uk' => 'gb');</PRE>
<P>With this code, both ``uk'' and ``gb'' are valid codes for United Kingdom,
with the reverse lookup returning ``uk'' rather than the usual ``gb''.</P>
<P>
<HR>
<H1><A NAME="examples">EXAMPLES</A></H1>
<P>The following example illustrates use of the <A HREF="#item_code2country"><CODE>code2country()</CODE></A> function.
The user is prompted for a country code, and then told the corresponding
country name:</P>
<PRE>
$| = 1; # turn off buffering
</PRE>
<PRE>
print "Enter country code: ";
chop($code = <STDIN>);
$country = code2country($code);
if (defined $country)
{
print "$code = $country\n";
}
else
{
print "'$code' is not a valid country code!\n";
}</PRE>
<P>
<HR>
<H1><A NAME="domain names">DOMAIN NAMES</A></H1>
<P>Most top-level domain names are based on these codes,
but there are certain codes which aren't.
If you are using this module to identify country from hostname,
your best bet is to preprocess the country code.</P>
<P>For example, <STRONG>edu</STRONG>, <STRONG>com</STRONG>, <STRONG>gov</STRONG> and friends would map to <STRONG>us</STRONG>;
<STRONG>uk</STRONG> would map to <STRONG>gb</STRONG>. Any others?</P>
<P>
<HR>
<H1><A NAME="known bugs and limitations">KNOWN BUGS AND LIMITATIONS</A></H1>
<UL>
<LI>
When using <A HREF="#item_country2code"><CODE>country2code()</CODE></A>, the country name must currently appear
exactly as it does in the source of the module. For example,
<PRE>
country2code('United States')</PRE>
<P>will return <STRONG>us</STRONG>, as expected. But the following will all return <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A>:</P>
<PRE>
country2code('United States of America')
country2code('Great Britain')
country2code('U.S.A.')</PRE>
<P>If there's need for it, a future version could have variants
for country names.</P>
<P></P>
<LI>
In the current implementation, all data is read in when the
module is loaded, and then held in memory.
A lazy implementation would be more memory friendly.
