[p5sagit/p5-mst-13.2.git] / lib / Locale / Country.pm

#-----------------------------------------------------------------------

=head1 NAME

Locale::Country - ISO codes for country identification (ISO 3166)

=head1 SYNOPSIS

    use Locale::Country;
    
    $country = code2country('jp');               # $country gets 'Japan'
    $code    = country2code('Norway');           # $code gets 'no'
    
    @codes   = all_country_codes();
    @names   = all_country_names();
    
    # add "uk" as a pseudo country code for United Kingdom
    Locale::Country::_alias_code('uk' => 'gb');

=cut

#-----------------------------------------------------------------------

package Locale::Country;
use strict;
require 5.002;

#-----------------------------------------------------------------------

=head1 DESCRIPTION

The C<Locale::Country> module provides access to the ISO
codes for identifying countries, as defined in ISO 3166.
You can either access the codes via the L<conversion routines>
(described below), or with the two functions which return lists
of all country codes or all country names.

There are three different code sets you can use for identifying
countries:

=over 4

=item B<alpha-2>

Two letter codes, such as 'tv' for Tuvalu.
This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.

=item B<alpha-3>

Three letter codes, such as 'brb' for Barbados.
This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.

=item B<numeric>

Numeric codes, such as 064 for Bhutan.
This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.

=back

All of the routines take an optional additional argument
which specifies the code set to use.
If not specified, it defaults to the two-letter codes.
This is partly for backwards compatibility (previous versions
of this module only supported the alpha-2 codes), and
partly because they are the most widely used codes.

The alpha-2 and alpha-3 codes are not case-dependent,
so you can use 'BO', 'Bo', 'bO' or 'bo' for Bolivia.
When a code is returned by one of the functions in
this module, it will always be lower-case.

As of version 2.00, Locale::Country supports variant
names for countries. So, for example, the country code for "United States"
is "us", so country2code('United States') returns 'us'.
Now the following will also return 'us':

    country2code('United States of America') 
    country2code('USA') 

=cut

#-----------------------------------------------------------------------

require Exporter;
use Carp;
use Locale::Constants;


#-----------------------------------------------------------------------
#	Public Global Variables
#-----------------------------------------------------------------------
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
$VERSION   = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/);
@ISA       = qw(Exporter);
@EXPORT    = qw(code2country country2code
                all_country_codes all_country_names
		country_code2code
		LOCALE_CODE_ALPHA_2 LOCALE_CODE_ALPHA_3 LOCALE_CODE_NUMERIC);

#-----------------------------------------------------------------------
#	Private Global Variables
#-----------------------------------------------------------------------
my $CODES     = [];
my $COUNTRIES = [];


#=======================================================================

=head1 CONVERSION ROUTINES

There are three conversion routines: C<code2country()>, C<country2code()>,
and C<country_code2code()>.

=over 8

=item code2country( CODE, [ CODESET ] )

This function takes a country code and returns a string
which contains the name of the country identified.
If the code is not a valid country code, as defined by ISO 3166,
then C<undef> will be returned:

    $country = code2country('fi');

=item country2code( STRING, [ CODESET ] )

This function takes a country name and returns the corresponding
country code, if such exists.
If the argument could not be identified as a country name,
then C<undef> will be returned:

    $code = country2code('Norway', LOCALE_CODE_ALPHA_3);
    # $code will now be 'nor'

The case of the country name is not important.
See the section L<KNOWN BUGS AND LIMITATIONS> below.

=item country_code2code( CODE, CODESET, CODESET )

This function takes a country code from one code set,
and returns the corresponding code from another code set.

    $alpha2 = country_code2code('fin',
		 LOCALE_CODE_ALPHA_3 => LOCALE_CODE_ALPHA_2);
    # $alpha2 will now be 'fi'

If the code passed is not a valid country code in
the first code set, or if there isn't a code for the
corresponding country in the second code set,
then C<undef> will be returned.

=back

=cut

#=======================================================================
sub code2country
{
    my $code = shift;
    my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;


    return undef unless defined $code;

    #-------------------------------------------------------------------
    # Make sure the code is in the right form before we use it
    # to look up the corresponding country.
    # We have to sprintf because the codes are given as 3-digits,
    # with leading 0's. Eg 052 for Barbados.
    #-------------------------------------------------------------------
    if ($codeset == LOCALE_CODE_NUMERIC)
    {
	return undef if ($code =~ /\D/);
	$code = sprintf("%.3d", $code);
    }
    else
    {
	$code = lc($code);
    }

    if (exists $CODES->[$codeset]->{$code})
    {
        return $CODES->[$codeset]->{$code};
    }
    else
    {
        #---------------------------------------------------------------
        # no such country code!
        #---------------------------------------------------------------
        return undef;
    }
}

sub country2code
{
    my $country = shift;
    my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;


    return undef unless defined $country;
    $country = lc($country);
    if (exists $COUNTRIES->[$codeset]->{$country})
    {
        return $COUNTRIES->[$codeset]->{$country};
    }
    else
    {
        #---------------------------------------------------------------
        # no such country!
        #---------------------------------------------------------------
        return undef;
    }
}

sub country_code2code
{
    (@_ == 3) or croak "country_code2code() takes 3 arguments!";

    my $code = shift;
    my $inset = shift;
    my $outset = shift;
    my $outcode = shift;
    my $country;


    return undef if $inset == $outset;
    $country = code2country($code, $inset);
    return undef if not defined $country;
    $outcode = country2code($country, $outset);
    return $outcode;
}

#=======================================================================

=head1 QUERY ROUTINES

There are two function which can be used to obtain a list of all codes,
or all country names:

=over 8

=item C<all_country_codes( [ CODESET ] )>

Returns a list of all two-letter country codes.
The codes are guaranteed to be all lower-case,
and not in any particular order.

=item C<all_country_names( [ CODESET ] )>

Returns a list of all country names for which there is a corresponding
country code in the specified code set.
The names are capitalised, and not returned in any particular order.

Not all countries have alpha-3 and numeric codes -
some just have an alpha-2 code,
so you'll get a different number of countries
depending on which code set you specify.

=back

=cut

#=======================================================================
sub all_country_codes
{
    my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;

    return keys %{ $CODES->[$codeset] };
}

sub all_country_names
{
    my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;

    return values %{ $CODES->[$codeset] };
}

#-----------------------------------------------------------------------

=head1 CODE ALIASING

This module supports a semi-private routine for specifying two letter
code aliases.

    Locale::Country::_alias_code( ALIAS => CODE [, CODESET ] )

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.

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:

    use Locale::Country;
    
    Locale::Country::_alias_code('uk' => 'gb');

With this code, both "uk" and "gb" are valid codes for United Kingdom,
with the reverse lookup returning "uk" rather than the usual "gb".

=cut

#-----------------------------------------------------------------------

sub _alias_code
{
    my $alias = shift;
    my $real  = shift;
    my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;

    my $country;


    if (not exists $CODES->[$codeset]->{$real})
    {
        carp "attempt to alias \"$alias\" to unknown country code \"$real\"\n";
        return undef;
    }
    $country = $CODES->[$codeset]->{$real};
    $CODES->[$codeset]->{$alias} = $country;
    $COUNTRIES->[$codeset]->{"\L$country"} = $alias;

    return $alias;
}

#-----------------------------------------------------------------------

=head1 EXAMPLES

The following example illustrates use of the C<code2country()> function.
The user is prompted for a country code, and then told the corresponding
country name:

    $| = 1;   # turn off buffering
    
    print "Enter country code: ";
    chop($code = <STDIN>);
    $country = code2country($code, LOCALE_CODE_ALPHA_2);
    if (defined $country)
    {
        print "$code = $country\n";
    }
    else
    {
        print "'$code' is not a valid country code!\n";
    }

=head1 DOMAIN NAMES

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.

For example, B<edu>, B<com>, B<gov> and friends would map to B<us>;
B<uk> would map to B<gb>. Any others?

=head1 KNOWN BUGS AND LIMITATIONS

=over 4

=item *

When using C<country2code()>, the country name must currently appear
exactly as it does in the source of the module. The module now supports
a small number of variants.

Possible extensions to this are: an interface for getting at the
list of variant names, and regular expression matches.

=item *

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.

=item *

Support for country names in different languages.

=back

=head1 SEE ALSO

=over 4

=item Locale::Language

ISO two letter codes for identification of language (ISO 639).

=item Locale::Script

ISO codes for identification of scripts (ISO 15924).

=item Locale::Currency

ISO three letter codes for identification of currencies
and funds (ISO 4217).

=item ISO 3166

The ISO standard which defines these codes.

=item http://www.din.de/gremien/nas/nabd/iso3166ma/

Official home page for ISO 3166

=item http://www.egt.ie/standards/iso3166/iso3166-1-en.html

Another useful, but not official, home page.

=item http://www.cia.gov/cia/publications/factbook/docs/app-f.html

An appendix in the CIA world fact book which lists country codes
as defined by ISO 3166, FIPS 10-4, and internet domain names.

=back


=head1 AUTHOR

Neil Bowers E<lt>neil@bowers.comE<gt>

=head1 COPYRIGHT

Copyright (C) 2002, Neil Bowers.

Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=cut

#-----------------------------------------------------------------------

#=======================================================================
# initialisation code - stuff the DATA into the ALPHA2 hash
#=======================================================================
{
    my ($alpha2, $alpha3, $numeric);
    my ($country, @countries);


    while (<DATA>)
    {
        next unless /\S/;
        chop;
        ($alpha2, $alpha3, $numeric, @countries) = split(/:/, $_);

        $CODES->[LOCALE_CODE_ALPHA_2]->{$alpha2} = $countries[0];
	foreach $country (@countries)
	{
	    $COUNTRIES->[LOCALE_CODE_ALPHA_2]->{"\L$country"} = $alpha2;
	}

	if ($alpha3)
	{
            $CODES->[LOCALE_CODE_ALPHA_3]->{$alpha3} = $countries[0];
	    foreach $country (@countries)
	    {
		$COUNTRIES->[LOCALE_CODE_ALPHA_3]->{"\L$country"} = $alpha3;
	    }
	}

	if ($numeric)
	{
            $CODES->[LOCALE_CODE_NUMERIC]->{$numeric} = $countries[0];
	    foreach $country (@countries)
	    {
		$COUNTRIES->[LOCALE_CODE_NUMERIC]->{"\L$country"} = $numeric;
	    }
	}

    }
}

1;

__DATA__
ad:and:020:Andorra
ae:are:784:United Arab Emirates
af:afg:004:Afghanistan
ag:atg:028:Antigua and Barbuda
ai:aia:660:Anguilla
al:alb:008:Albania
am:arm:051:Armenia
an:ant:530:Netherlands Antilles
ao:ago:024:Angola
aq:::Antarctica
ar:arg:032:Argentina
as:asm:016:American Samoa
at:aut:040:Austria
au:aus:036:Australia
aw:abw:533:Aruba
az:aze:031:Azerbaijan
ba:bih:070:Bosnia and Herzegovina
bb:brb:052:Barbados
bd:bgd:050:Bangladesh
be:bel:056:Belgium
bf:bfa:854:Burkina Faso
bg:bgr:100:Bulgaria
bh:bhr:048:Bahrain
bi:bdi:108:Burundi
bj:ben:204:Benin
bm:bmu:060:Bermuda
bn:brn:096:Brunei Darussalam
bo:bol:068:Bolivia
br:bra:076:Brazil
bs:bhs:044:Bahamas
bt:btn:064:Bhutan
bv:::Bouvet Island
bw:bwa:072:Botswana
by:blr:112:Belarus
bz:blz:084:Belize
ca:can:124:Canada
cc:::Cocos (Keeling) Islands
cd:cod:180:Congo, The Democratic Republic of the:Congo, Democratic Republic of the
cf:caf:140:Central African Republic
cg:cog:178:Congo
ch:che:756:Switzerland
ci:civ:384:Cote D'Ivoire
ck:cok:184:Cook Islands
cl:chl:152:Chile
cm:cmr:120:Cameroon
cn:chn:156:China
co:col:170:Colombia
cr:cri:188:Costa Rica
cu:cub:192:Cuba
cv:cpv:132:Cape Verde
cx:::Christmas Island
cy:cyp:196:Cyprus
cz:cze:203:Czech Republic
de:deu:276:Germany
dj:dji:262:Djibouti
dk:dnk:208:Denmark
dm:dma:212:Dominica
do:dom:214:Dominican Republic
dz:dza:012:Algeria
ec:ecu:218:Ecuador
ee:est:233:Estonia
eg:egy:818:Egypt
eh:esh:732:Western Sahara
er:eri:232:Eritrea
es:esp:724:Spain
et:eth:231:Ethiopia
fi:fin:246:Finland
fj:fji:242:Fiji
fk:flk:238:Falkland Islands (Malvinas):Falkland Islands (Islas Malvinas)
fm:fsm:583:Micronesia, Federated States of
fo:fro:234:Faroe Islands
fr:fra:250:France
fx:::France, Metropolitan
ga:gab:266:Gabon
gb:gbr:826:United Kingdom:Great Britain
gd:grd:308:Grenada
ge:geo:268:Georgia
gf:guf:254:French Guiana
gh:gha:288:Ghana
gi:gib:292:Gibraltar
gl:grl:304:Greenland
gm:gmb:270:Gambia
gn:gin:324:Guinea
gp:glp:312:Guadeloupe
gq:gnq:226:Equatorial Guinea
gr:grc:300:Greece
gs:::South Georgia and the South Sandwich Islands
gt:gtm:320:Guatemala
gu:gum:316:Guam
gw:gnb:624:Guinea-Bissau
gy:guy:328:Guyana
hk:hkg:344:Hong Kong
hm:::Heard Island and McDonald Islands
hn:hnd:340:Honduras
hr:hrv:191:Croatia
ht:hti:332:Haiti
hu:hun:348:Hungary
id:idn:360:Indonesia
ie:irl:372:Ireland
il:isr:376:Israel
in:ind:356:India
io:::British Indian Ocean Territory
iq:irq:368:Iraq
ir:irn:364:Iran, Islamic Republic of:Iran
is:isl:352:Iceland
it:ita:380:Italy
jm:jam:388:Jamaica
jo:jor:400:Jordan
jp:jpn:392:Japan
ke:ken:404:Kenya
kg:kgz:417:Kyrgyzstan
kh:khm:116:Cambodia
ki:kir:296:Kiribati
km:com:174:Comoros
kn:kna:659:Saint Kitts and Nevis
kp:prk:408:Korea, Democratic People's Republic of:Korea, North:North Korea
kr:kor:410:Korea, Republic of:Korea, South:South Korea
kw:kwt:414:Kuwait
ky:cym:136:Cayman Islands
kz:kaz:398:Kazakstan
la:lao:418:Lao People's Democratic Republic
lb:lbn:422:Lebanon
lc:lca:662:Saint Lucia
li:lie:438:Liechtenstein
lk:lka:144:Sri Lanka
lr:lbr:430:Liberia
ls:lso:426:Lesotho
lt:ltu:440:Lithuania
lu:lux:442:Luxembourg
lv:lva:428:Latvia
ly:lby:434:Libyan Arab Jamahiriya:Libya
ma:mar:504:Morocco
mc:mco:492:Monaco
md:mda:498:Moldova, Republic of
mg:mdg:450:Madagascar
mh:mhl:584:Marshall Islands
mk:mkd:807:Macedonia, the Former Yugoslav Republic of:Macedonia, Former Yugoslav Republic of:Macedonia
ml:mli:466:Mali
mm:mmr:104:Myanmar
mn:mng:496:Mongolia
mo:mac:446:Macau
mp:mnp:580:Northern Mariana Islands
mq:mtq:474:Martinique
mr:mrt:478:Mauritania
ms:msr:500:Montserrat
mt:mlt:470:Malta
mu:mus:480:Mauritius
mv:mdv:462:Maldives
mw:mwi:454:Malawi
mx:mex:484:Mexico
my:mys:458:Malaysia
mz:moz:508:Mozambique
na:nam:516:Namibia
nc:ncl:540:New Caledonia
ne:ner:562:Niger
nf:nfk:574:Norfolk Island
ng:nga:566:Nigeria
ni:nic:558:Nicaragua
nl:nld:528:Netherlands
no:nor:578:Norway
np:npl:524:Nepal
nr:nru:520:Nauru
nu:niu:570:Niue
nz:nzl:554:New Zealand
om:omn:512:Oman
pa:pan:591:Panama
pe:per:604:Peru
pf:pyf:258:French Polynesia
pg:png:598:Papua New Guinea
ph:phl:608:Philippines
pk:pak:586:Pakistan
pl:pol:616:Poland
pm:spm:666:Saint Pierre and Miquelon
pn:pcn:612:Pitcairn:Pitcairn Island
pr:pri:630:Puerto Rico
ps:pse:275:Palestinian Territory, Occupied
pt:prt:620:Portugal
pw:plw:585:Palau
py:pry:600:Paraguay
qa:qat:634:Qatar
re:reu:638:Reunion
ro:rom:642:Romania
ru:rus:643:Russian Federation:Russia
rw:rwa:646:Rwanda
sa:sau:682:Saudi Arabia
sb:slb:090:Solomon Islands
sc:syc:690:Seychelles
sd:sdn:736:Sudan
se:swe:752:Sweden
sg:sgp:702:Singapore
sh:shn:654:Saint Helena
si:svn:705:Slovenia
sj:sjm:744:Svalbard and Jan Mayen:Jan Mayen:Svalbard
sk:svk:703:Slovakia
sl:sle:694:Sierra Leone
sm:smr:674:San Marino
sn:sen:686:Senegal
so:som:706:Somalia
sr:sur:740:Suriname
st:stp:678:Sao Tome and Principe
sv:slv:222:El Salvador
sy:syr:760:Syrian Arab Republic:Syria
sz:swz:748:Swaziland
tc:tca:796:Turks and Caicos Islands
td:tcd:148:Chad
tf:::French Southern Territories
tg:tgo:768:Togo
th:tha:764:Thailand
tj:tjk:762:Tajikistan
tk:tkl:772:Tokelau
tm:tkm:795:Turkmenistan
tn:tun:788:Tunisia
to:ton:776:Tonga
tp:tmp:626:East Timor
tr:tur:792:Turkey
tt:tto:780:Trinidad and Tobago
tv:tuv:798:Tuvalu
tw:twn:158:Taiwan, Province of China:Taiwan
tz:tza:834:Tanzania, United Republic of:Tanzania
ua:ukr:804:Ukraine
ug:uga:800:Uganda
um:::United States Minor Outlying Islands
us:usa:840:United States:USA:United States of America
uy:ury:858:Uruguay
uz:uzb:860:Uzbekistan
va:vat:336:Holy See (Vatican City State):Hole See (Vatican City)
vc:vct:670:Saint Vincent and the Grenadines
ve:ven:862:Venezuela
vg:vgb:092:Virgin Islands, British:British Virgin Islands
vi:vir:850:Virgin Islands, U.S.
vn:vnm:704:Vietnam
vu:vut:548:Vanuatu
wf:wlf:876:Wallis and Futuna
ws:wsm:882:Samoa
ye:yem:887:Yemen
yt:::Mayotte
yu:yug:891:Yugoslavia
za:zaf:710:South Africa
zm:zmb:894:Zambia
zr:::Zaire
zw:zwe:716:Zimbabwe
Commit	Line	Data
47a334e9	1	#-----------------------------------------------------------------------
	2
	3	=head1 NAME
	4
	5	Locale::Country - ISO codes for country identification (ISO 3166)
	6
	7	=head1 SYNOPSIS
	8
	9	use Locale::Country;
88c28ceb	10
47a334e9	11	$country = code2country('jp'); # $country gets 'Japan'
47a334e9	12	$code = country2code('Norway'); # $code gets 'no'
88c28ceb	13
47a334e9	14	@codes = all_country_codes();
47a334e9	15	@names = all_country_names();
88c28ceb	16
47a334e9	17	# add "uk" as a pseudo country code for United Kingdom
	18	Locale::Country::_alias_code('uk' => 'gb');
	19
	20	=cut
	21
	22	#-----------------------------------------------------------------------
	23
	24	package Locale::Country;
	25	use strict;
	26	require 5.002;
	27
	28	#-----------------------------------------------------------------------
	29
	30	=head1 DESCRIPTION
	31
	32	The C<Locale::Country> module provides access to the ISO
	33	codes for identifying countries, as defined in ISO 3166.
	34	You can either access the codes via the L<conversion routines>
	35	(described below), or with the two functions which return lists
	36	of all country codes or all country names.
	37
	38	There are three different code sets you can use for identifying
	39	countries:
	40
	41	=over 4
	42
	43	=item B<alpha-2>
	44
	45	Two letter codes, such as 'tv' for Tuvalu.
	46	This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
	47
	48	=item B<alpha-3>
	49
	50	Three letter codes, such as 'brb' for Barbados.
	51	This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
	52
	53	=item B<numeric>
	54
	55	Numeric codes, such as 064 for Bhutan.
	56	This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.
	57
	58	=back
	59
	60	All of the routines take an optional additional argument
	61	which specifies the code set to use.
	62	If not specified, it defaults to the two-letter codes.
	63	This is partly for backwards compatibility (previous versions
	64	of this module only supported the alpha-2 codes), and
	65	partly because they are the most widely used codes.
	66
	67	The alpha-2 and alpha-3 codes are not case-dependent,
	68	so you can use 'BO', 'Bo', 'bO' or 'bo' for Bolivia.
	69	When a code is returned by one of the functions in
	70	this module, it will always be lower-case.
	71
6b6e008c	72	As of version 2.00, Locale::Country supports variant
	73	names for countries. So, for example, the country code for "United States"
	74	is "us", so country2code('United States') returns 'us'.
	75	Now the following will also return 'us':
	76
	77	country2code('United States of America')
	78	country2code('USA')
	79
47a334e9	80	=cut
	81
	82	#-----------------------------------------------------------------------
	83
	84	require Exporter;
	85	use Carp;
	86	use Locale::Constants;
	87
	88
	89	#-----------------------------------------------------------------------
	90	# Public Global Variables
	91	#-----------------------------------------------------------------------
	92	use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
6b6e008c	93	$VERSION = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/);
47a334e9	94	@ISA = qw(Exporter);
	95	@EXPORT = qw(code2country country2code
	96	all_country_codes all_country_names
	97	country_code2code
	98	LOCALE_CODE_ALPHA_2 LOCALE_CODE_ALPHA_3 LOCALE_CODE_NUMERIC);
	99
	100	#-----------------------------------------------------------------------
	101	# Private Global Variables
	102	#-----------------------------------------------------------------------
	103	my $CODES = [];
	104	my $COUNTRIES = [];
	105
	106
	107	#=======================================================================
	108
	109	=head1 CONVERSION ROUTINES
	110
	111	There are three conversion routines: C<code2country()>, C<country2code()>,
	112	and C<country_code2code()>.
	113
	114	=over 8
	115
	116	=item code2country( CODE, [ CODESET ] )
	117
	118	This function takes a country code and returns a string
	119	which contains the name of the country identified.
	120	If the code is not a valid country code, as defined by ISO 3166,
	121	then C<undef> will be returned:
	122
	123	$country = code2country('fi');
	124
	125	=item country2code( STRING, [ CODESET ] )
	126
	127	This function takes a country name and returns the corresponding
	128	country code, if such exists.
	129	If the argument could not be identified as a country name,
	130	then C<undef> will be returned:
	131
	132	$code = country2code('Norway', LOCALE_CODE_ALPHA_3);
	133	# $code will now be 'nor'
	134
	135	The case of the country name is not important.
	136	See the section L<KNOWN BUGS AND LIMITATIONS> below.
	137
	138	=item country_code2code( CODE, CODESET, CODESET )
	139
	140	This function takes a country code from one code set,
	141	and returns the corresponding code from another code set.
	142
	143	$alpha2 = country_code2code('fin',
	144	LOCALE_CODE_ALPHA_3 => LOCALE_CODE_ALPHA_2);
	145	# $alpha2 will now be 'fi'
	146
	147	If the code passed is not a valid country code in
	148	the first code set, or if there isn't a code for the
	149	corresponding country in the second code set,
	150	then C<undef> will be returned.
	151
	152	=back
	153
	154	=cut
	155
	156	#=======================================================================
	157	sub code2country
158	{
159	my $code = shift;
160	my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
161
162
163	return undef unless defined $code;
164
165	#-------------------------------------------------------------------
166	# Make sure the code is in the right form before we use it
167	# to look up the corresponding country.
168	# We have to sprintf because the codes are given as 3-digits,
169	# with leading 0's. Eg 052 for Barbados.
170	#-------------------------------------------------------------------
171	if ($codeset == LOCALE_CODE_NUMERIC)
172	{
173	return undef if ($code =~ /\D/);
174	$code = sprintf("%.3d", $code);
175	}
176	else
177	{
178	$code = lc($code);
179	}
180
181	if (exists $CODES->[$codeset]->{$code})
182	{
183	return $CODES->[$codeset]->{$code};
184	}
185	else
186	{
187	#---------------------------------------------------------------
188	# no such country code!
189	#---------------------------------------------------------------
190	return undef;
191	}
192	}
193
194	sub country2code
195	{
196	my $country = shift;
197	my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
198
199
200	return undef unless defined $country;
201	$country = lc($country);
202	if (exists $COUNTRIES->[$codeset]->{$country})
203	{
204	return $COUNTRIES->[$codeset]->{$country};
205	}
206	else
207	{
208	#---------------------------------------------------------------
209	# no such country!
210	#---------------------------------------------------------------
211	return undef;
212	}
213	}
214
215	sub country_code2code
216	{
217	(@_ == 3) or croak "country_code2code() takes 3 arguments!";
218
219	my $code = shift;
220	my $inset = shift;
221	my $outset = shift;
222	my $outcode = shift;
223	my $country;
224
225
226	return undef if $inset == $outset;
227	$country = code2country($code, $inset);
228	return undef if not defined $country;
229	$outcode = country2code($country, $outset);
230	return $outcode;
231	}
232
233	#=======================================================================
234
235	=head1 QUERY ROUTINES
236
237	There are two function which can be used to obtain a list of all codes,
238	or all country names:
239
240	=over 8
241
242	=item C<all_country_codes( [ CODESET ] )>
243
244	Returns a list of all two-letter country codes.
245	The codes are guaranteed to be all lower-case,
246	and not in any particular order.
247
248	=item C<all_country_names( [ CODESET ] )>
249
250	Returns a list of all country names for which there is a corresponding
251	country code in the specified code set.
252	The names are capitalised, and not returned in any particular order.
253
254	Not all countries have alpha-3 and numeric codes -
255	some just have an alpha-2 code,
256	so you'll get a different number of countries
257	depending on which code set you specify.
258
259	=back
260
261	=cut
262
263	#=======================================================================
264	sub all_country_codes
265	{
266	my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
267
268	return keys %{ $CODES->[$codeset] };
269	}
270
271	sub all_country_names
272	{
273	my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
274
275	return values %{ $CODES->[$codeset] };
276	}
277
278	#-----------------------------------------------------------------------
279
280	=head1 CODE ALIASING
281
282	This module supports a semi-private routine for specifying two letter
283	code aliases.
284
285	Locale::Country::_alias_code( ALIAS => CODE [, CODESET ] )
286
287	This feature was added as a mechanism for handling
288	a "uk" code. The ISO standard says that the two-letter code for
289	"United Kingdom" is "gb", whereas domain names are all .uk.
290
291	By default the module does not understand "uk", since it is implementing
292	an ISO standard. If you would like 'uk' to work as the two-letter
293	code for United Kingdom, use the following:
294
295	use Locale::Country;
88c28ceb	296
47a334e9	297	Locale::Country::_alias_code('uk' => 'gb');
	298
	299	With this code, both "uk" and "gb" are valid codes for United Kingdom,
	300	with the reverse lookup returning "uk" rather than the usual "gb".
	301
	302	=cut
	303
	304	#-----------------------------------------------------------------------
	305
	306	sub _alias_code
	307	{
	308	my $alias = shift;
	309	my $real = shift;
	310	my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
	311
	312	my $country;
	313
	314
	315	if (not exists $CODES->[$codeset]->{$real})
	316	{
	317	carp "attempt to alias \"$alias\" to unknown country code \"$real\"\n";
	318	return undef;
	319	}
	320	$country = $CODES->[$codeset]->{$real};
	321	$CODES->[$codeset]->{$alias} = $country;
	322	$COUNTRIES->[$codeset]->{"\L$country"} = $alias;
	323
	324	return $alias;
	325	}
	326
	327	#-----------------------------------------------------------------------
	328
	329	=head1 EXAMPLES
	330
	331	The following example illustrates use of the C<code2country()> function.
	332	The user is prompted for a country code, and then told the corresponding
	333	country name:
	334
	335	$\| = 1; # turn off buffering
88c28ceb	336
47a334e9	337	print "Enter country code: ";
	338	chop($code = <STDIN>);
	339	$country = code2country($code, LOCALE_CODE_ALPHA_2);
	340	if (defined $country)
	341	{
	342	print "$code = $country\n";
	343	}
	344	else
	345	{
	346	print "'$code' is not a valid country code!\n";
	347	}
	348
	349	=head1 DOMAIN NAMES
	350
	351	Most top-level domain names are based on these codes,
	352	but there are certain codes which aren't.
	353	If you are using this module to identify country from hostname,
	354	your best bet is to preprocess the country code.
	355
	356	For example, B<edu>, B<com>, B<gov> and friends would map to B<us>;
	357	B<uk> would map to B<gb>. Any others?
	358
	359	=head1 KNOWN BUGS AND LIMITATIONS
	360
	361	=over 4
	362
	363	=item *
	364
	365	When using C<country2code()>, the country name must currently appear
6b6e008c	366	exactly as it does in the source of the module. The module now supports
6b6e008c	367	a small number of variants.
47a334e9	368
6b6e008c	369	Possible extensions to this are: an interface for getting at the
6b6e008c	370	list of variant names, and regular expression matches.
47a334e9	371
	372	=item *
	373
	374	In the current implementation, all data is read in when the
	375	module is loaded, and then held in memory.
	376	A lazy implementation would be more memory friendly.
	377
6b6e008c	378	=item *
	379
	380	Support for country names in different languages.
	381
47a334e9	382	=back
	383
	384	=head1 SEE ALSO
	385
	386	=over 4
	387
	388	=item Locale::Language
	389
	390	ISO two letter codes for identification of language (ISO 639).
	391
6b6e008c	392	=item Locale::Script
	393
	394	ISO codes for identification of scripts (ISO 15924).
	395
47a334e9	396	=item Locale::Currency
	397
	398	ISO three letter codes for identification of currencies
	399	and funds (ISO 4217).
	400
	401	=item ISO 3166
	402
	403	The ISO standard which defines these codes.
	404
	405	=item http://www.din.de/gremien/nas/nabd/iso3166ma/
	406
	407	Official home page for ISO 3166
	408
	409	=item http://www.egt.ie/standards/iso3166/iso3166-1-en.html
	410
	411	Another useful, but not official, home page.
	412
	413	=item http://www.cia.gov/cia/publications/factbook/docs/app-f.html
	414
	415	An appendix in the CIA world fact book which lists country codes
	416	as defined by ISO 3166, FIPS 10-4, and internet domain names.
	417
	418	=back
	419
	420
	421	=head1 AUTHOR
	422
6b6e008c	423	Neil Bowers E<lt>neil@bowers.comE<gt>
47a334e9	424
	425	=head1 COPYRIGHT
	426
6b6e008c	427	Copyright (C) 2002, Neil Bowers.
6b6e008c	428
47a334e9	429	Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
	430
	431	This module is free software; you can redistribute it and/or
	432	modify it under the same terms as Perl itself.
	433
	434	=cut
	435
	436	#-----------------------------------------------------------------------
	437
	438	#=======================================================================
	439	# initialisation code - stuff the DATA into the ALPHA2 hash
	440	#=======================================================================
	441	{
	442	my ($alpha2, $alpha3, $numeric);
6b6e008c	443	my ($country, @countries);
47a334e9	444
	445
	446	while (<DATA>)
	447	{
	448	next unless /\S/;
	449	chop;
6b6e008c	450	($alpha2, $alpha3, $numeric, @countries) = split(/:/, $_);
47a334e9	451
6b6e008c	452	$CODES->[LOCALE_CODE_ALPHA_2]->{$alpha2} = $countries[0];
	453	foreach $country (@countries)
	454	{
	455	$COUNTRIES->[LOCALE_CODE_ALPHA_2]->{"\L$country"} = $alpha2;
	456	}
47a334e9	457
	458	if ($alpha3)
	459	{
6b6e008c	460	$CODES->[LOCALE_CODE_ALPHA_3]->{$alpha3} = $countries[0];
	461	foreach $country (@countries)
	462	{
	463	$COUNTRIES->[LOCALE_CODE_ALPHA_3]->{"\L$country"} = $alpha3;
	464	}
47a334e9	465	}
	466
	467	if ($numeric)
	468	{
6b6e008c	469	$CODES->[LOCALE_CODE_NUMERIC]->{$numeric} = $countries[0];
	470	foreach $country (@countries)
	471	{
	472	$COUNTRIES->[LOCALE_CODE_NUMERIC]->{"\L$country"} = $numeric;
	473	}
47a334e9	474	}
	475
	476	}
	477	}
	478
	479	1;
	480
	481	__DATA__
	482	ad:and:020:Andorra
	483	ae:are:784:United Arab Emirates
	484	af:afg:004:Afghanistan
	485	ag:atg:028:Antigua and Barbuda
	486	ai:aia:660:Anguilla
	487	al:alb:008:Albania
	488	am:arm:051:Armenia
	489	an:ant:530:Netherlands Antilles
	490	ao:ago:024:Angola
	491	aq:::Antarctica
	492	ar:arg:032:Argentina
	493	as:asm:016:American Samoa
	494	at:aut:040:Austria
	495	au:aus:036:Australia
	496	aw:abw:533:Aruba
	497	az:aze:031:Azerbaijan
	498	ba:bih:070:Bosnia and Herzegovina
	499	bb:brb:052:Barbados
	500	bd:bgd:050:Bangladesh
	501	be:bel:056:Belgium
	502	bf:bfa:854:Burkina Faso
	503	bg:bgr:100:Bulgaria
	504	bh:bhr:048:Bahrain
	505	bi:bdi:108:Burundi
	506	bj:ben:204:Benin
	507	bm:bmu:060:Bermuda
	508	bn:brn:096:Brunei Darussalam
	509	bo:bol:068:Bolivia
	510	br:bra:076:Brazil
	511	bs:bhs:044:Bahamas
	512	bt:btn:064:Bhutan
	513	bv:::Bouvet Island
	514	bw:bwa:072:Botswana
	515	by:blr:112:Belarus
	516	bz:blz:084:Belize
	517	ca:can:124:Canada
	518	cc:::Cocos (Keeling) Islands
6b6e008c	519	cd:cod:180:Congo, The Democratic Republic of the:Congo, Democratic Republic of the
47a334e9	520	cf:caf:140:Central African Republic
	521	cg:cog:178:Congo
	522	ch:che:756:Switzerland
	523	ci:civ:384:Cote D'Ivoire
	524	ck:cok:184:Cook Islands
	525	cl:chl:152:Chile
	526	cm:cmr:120:Cameroon
	527	cn:chn:156:China
	528	co:col:170:Colombia
	529	cr:cri:188:Costa Rica
	530	cu:cub:192:Cuba
	531	cv:cpv:132:Cape Verde
	532	cx:::Christmas Island
	533	cy:cyp:196:Cyprus
	534	cz:cze:203:Czech Republic
	535	de:deu:276:Germany
	536	dj:dji:262:Djibouti
	537	dk:dnk:208:Denmark
	538	dm:dma:212:Dominica
	539	do:dom:214:Dominican Republic
	540	dz:dza:012:Algeria
	541	ec:ecu:218:Ecuador
	542	ee:est:233:Estonia
	543	eg:egy:818:Egypt
	544	eh:esh:732:Western Sahara
	545	er:eri:232:Eritrea
	546	es:esp:724:Spain
	547	et:eth:231:Ethiopia
	548	fi:fin:246:Finland
	549	fj:fji:242:Fiji
6b6e008c	550	fk:flk:238:Falkland Islands (Malvinas):Falkland Islands (Islas Malvinas)
47a334e9	551	fm:fsm:583:Micronesia, Federated States of
	552	fo:fro:234:Faroe Islands
	553	fr:fra:250:France
	554	fx:::France, Metropolitan
	555	ga:gab:266:Gabon
6b6e008c	556	gb:gbr:826:United Kingdom:Great Britain
47a334e9	557	gd:grd:308:Grenada
	558	ge:geo:268:Georgia
	559	gf:guf:254:French Guiana
	560	gh:gha:288:Ghana
	561	gi:gib:292:Gibraltar
	562	gl:grl:304:Greenland
	563	gm:gmb:270:Gambia
	564	gn:gin:324:Guinea
	565	gp:glp:312:Guadeloupe
	566	gq:gnq:226:Equatorial Guinea
	567	gr:grc:300:Greece
	568	gs:::South Georgia and the South Sandwich Islands
	569	gt:gtm:320:Guatemala
	570	gu:gum:316:Guam
	571	gw:gnb:624:Guinea-Bissau
	572	gy:guy:328:Guyana
	573	hk:hkg:344:Hong Kong
	574	hm:::Heard Island and McDonald Islands
	575	hn:hnd:340:Honduras
	576	hr:hrv:191:Croatia
	577	ht:hti:332:Haiti
	578	hu:hun:348:Hungary
	579	id:idn:360:Indonesia
	580	ie:irl:372:Ireland
	581	il:isr:376:Israel
	582	in:ind:356:India
	583	io:::British Indian Ocean Territory
	584	iq:irq:368:Iraq
6b6e008c	585	ir:irn:364:Iran, Islamic Republic of:Iran
47a334e9	586	is:isl:352:Iceland
	587	it:ita:380:Italy
	588	jm:jam:388:Jamaica
	589	jo:jor:400:Jordan
	590	jp:jpn:392:Japan
	591	ke:ken:404:Kenya
	592	kg:kgz:417:Kyrgyzstan
	593	kh:khm:116:Cambodia
	594	ki:kir:296:Kiribati
	595	km:com:174:Comoros
	596	kn:kna:659:Saint Kitts and Nevis
6b6e008c	597	kp:prk:408:Korea, Democratic People's Republic of:Korea, North:North Korea
6b6e008c	598	kr:kor:410:Korea, Republic of:Korea, South:South Korea
47a334e9	599	kw:kwt:414:Kuwait
	600	ky:cym:136:Cayman Islands
	601	kz:kaz:398:Kazakstan
	602	la:lao:418:Lao People's Democratic Republic
	603	lb:lbn:422:Lebanon
	604	lc:lca:662:Saint Lucia
	605	li:lie:438:Liechtenstein
	606	lk:lka:144:Sri Lanka
	607	lr:lbr:430:Liberia
	608	ls:lso:426:Lesotho
	609	lt:ltu:440:Lithuania
	610	lu:lux:442:Luxembourg
	611	lv:lva:428:Latvia
6b6e008c	612	ly:lby:434:Libyan Arab Jamahiriya:Libya
47a334e9	613	ma:mar:504:Morocco
	614	mc:mco:492:Monaco
	615	md:mda:498:Moldova, Republic of
	616	mg:mdg:450:Madagascar
	617	mh:mhl:584:Marshall Islands
6b6e008c	618	mk:mkd:807:Macedonia, the Former Yugoslav Republic of:Macedonia, Former Yugoslav Republic of:Macedonia
47a334e9	619	ml:mli:466:Mali
	620	mm:mmr:104:Myanmar
	621	mn:mng:496:Mongolia
	622	mo:mac:446:Macau
	623	mp:mnp:580:Northern Mariana Islands
	624	mq:mtq:474:Martinique
	625	mr:mrt:478:Mauritania
	626	ms:msr:500:Montserrat
	627	mt:mlt:470:Malta
	628	mu:mus:480:Mauritius
	629	mv:mdv:462:Maldives
	630	mw:mwi:454:Malawi
	631	mx:mex:484:Mexico
	632	my:mys:458:Malaysia
	633	mz:moz:508:Mozambique
	634	na:nam:516:Namibia
	635	nc:ncl:540:New Caledonia
	636	ne:ner:562:Niger
	637	nf:nfk:574:Norfolk Island
	638	ng:nga:566:Nigeria
	639	ni:nic:558:Nicaragua
	640	nl:nld:528:Netherlands
	641	no:nor:578:Norway
	642	np:npl:524:Nepal
	643	nr:nru:520:Nauru
	644	nu:niu:570:Niue
	645	nz:nzl:554:New Zealand
	646	om:omn:512:Oman
	647	pa:pan:591:Panama
	648	pe:per:604:Peru
	649	pf:pyf:258:French Polynesia
	650	pg:png:598:Papua New Guinea
	651	ph:phl:608:Philippines
	652	pk:pak:586:Pakistan
	653	pl:pol:616:Poland
	654	pm:spm:666:Saint Pierre and Miquelon
6b6e008c	655	pn:pcn:612:Pitcairn:Pitcairn Island
47a334e9	656	pr:pri:630:Puerto Rico
	657	ps:pse:275:Palestinian Territory, Occupied
	658	pt:prt:620:Portugal
	659	pw:plw:585:Palau
	660	py:pry:600:Paraguay
	661	qa:qat:634:Qatar
	662	re:reu:638:Reunion
	663	ro:rom:642:Romania
6b6e008c	664	ru:rus:643:Russian Federation:Russia
47a334e9	665	rw:rwa:646:Rwanda
	666	sa:sau:682:Saudi Arabia
	667	sb:slb:090:Solomon Islands
	668	sc:syc:690:Seychelles
	669	sd:sdn:736:Sudan
	670	se:swe:752:Sweden
	671	sg:sgp:702:Singapore
	672	sh:shn:654:Saint Helena
	673	si:svn:705:Slovenia
6b6e008c	674	sj:sjm:744:Svalbard and Jan Mayen:Jan Mayen:Svalbard
47a334e9	675	sk:svk:703:Slovakia
	676	sl:sle:694:Sierra Leone
	677	sm:smr:674:San Marino
	678	sn:sen:686:Senegal
	679	so:som:706:Somalia
	680	sr:sur:740:Suriname
	681	st:stp:678:Sao Tome and Principe
	682	sv:slv:222:El Salvador
6b6e008c	683	sy:syr:760:Syrian Arab Republic:Syria
47a334e9	684	sz:swz:748:Swaziland
	685	tc:tca:796:Turks and Caicos Islands
	686	td:tcd:148:Chad
	687	tf:::French Southern Territories
	688	tg:tgo:768:Togo
	689	th:tha:764:Thailand
	690	tj:tjk:762:Tajikistan
	691	tk:tkl:772:Tokelau
	692	tm:tkm:795:Turkmenistan
	693	tn:tun:788:Tunisia
	694	to:ton:776:Tonga
	695	tp:tmp:626:East Timor
	696	tr:tur:792:Turkey
	697	tt:tto:780:Trinidad and Tobago
	698	tv:tuv:798:Tuvalu
6b6e008c	699	tw:twn:158:Taiwan, Province of China:Taiwan
6b6e008c	700	tz:tza:834:Tanzania, United Republic of:Tanzania
47a334e9	701	ua:ukr:804:Ukraine
	702	ug:uga:800:Uganda
	703	um:::United States Minor Outlying Islands
6b6e008c	704	us:usa:840:United States:USA:United States of America
47a334e9	705	uy:ury:858:Uruguay
47a334e9	706	uz:uzb:860:Uzbekistan
6b6e008c	707	va:vat:336:Holy See (Vatican City State):Hole See (Vatican City)
47a334e9	708	vc:vct:670:Saint Vincent and the Grenadines
47a334e9	709	ve:ven:862:Venezuela
6b6e008c	710	vg:vgb:092:Virgin Islands, British:British Virgin Islands
47a334e9	711	vi:vir:850:Virgin Islands, U.S.
	712	vn:vnm:704:Vietnam
	713	vu:vut:548:Vanuatu
	714	wf:wlf:876:Wallis and Futuna
	715	ws:wsm:882:Samoa
	716	ye:yem:887:Yemen
	717	yt:::Mayotte
	718	yu:yug:891:Yugoslavia
	719	za:zaf:710:South Africa
	720	zm:zmb:894:Zambia
	721	zr:::Zaire
	722	zw:zwe:716:Zimbabwe