1 #-----------------------------------------------------------------------
5 Locale::Country - ISO codes for country identification (ISO 3166)
11 $country = code2country('jp'); # $country gets 'Japan'
12 $code = country2code('Norway'); # $code gets 'no'
14 @codes = all_country_codes();
15 @names = all_country_names();
17 # add "uk" as a pseudo country code for United Kingdom
18 Locale::Country::_alias_code('uk' => 'gb');
22 #-----------------------------------------------------------------------
24 package Locale::Country;
28 #-----------------------------------------------------------------------
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.
38 There are three different code sets you can use for identifying
45 Two letter codes, such as 'tv' for Tuvalu.
46 This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
50 Three letter codes, such as 'brb' for Barbados.
51 This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
55 Numeric codes, such as 064 for Bhutan.
56 This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.
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.
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.
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':
77 country2code('United States of America')
82 #-----------------------------------------------------------------------
86 use Locale::Constants;
89 #-----------------------------------------------------------------------
90 # Public Global Variables
91 #-----------------------------------------------------------------------
92 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
93 $VERSION = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/);
95 @EXPORT = qw(code2country country2code
96 all_country_codes all_country_names
98 LOCALE_CODE_ALPHA_2 LOCALE_CODE_ALPHA_3 LOCALE_CODE_NUMERIC);
100 #-----------------------------------------------------------------------
101 # Private Global Variables
102 #-----------------------------------------------------------------------
107 #=======================================================================
109 =head1 CONVERSION ROUTINES
111 There are three conversion routines: C<code2country()>, C<country2code()>,
112 and C<country_code2code()>.
116 =item code2country( CODE, [ CODESET ] )
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:
123 $country = code2country('fi');
125 =item country2code( STRING, [ CODESET ] )
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:
132 $code = country2code('Norway', LOCALE_CODE_ALPHA_3);
133 # $code will now be 'nor'
135 The case of the country name is not important.
136 See the section L<KNOWN BUGS AND LIMITATIONS> below.
138 =item country_code2code( CODE, CODESET, CODESET )
140 This function takes a country code from one code set,
141 and returns the corresponding code from another code set.
143 $alpha2 = country_code2code('fin',
144 LOCALE_CODE_ALPHA_3 => LOCALE_CODE_ALPHA_2);
145 # $alpha2 will now be 'fi'
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.
156 #=======================================================================
160 my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
163 return undef unless defined $code;
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)
173 return undef if ($code =~ /\D/);
174 $code = sprintf("%.3d", $code);
181 if (exists $CODES->[$codeset]->{$code})
183 return $CODES->[$codeset]->{$code};
187 #---------------------------------------------------------------
188 # no such country code!
189 #---------------------------------------------------------------
197 my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
200 return undef unless defined $country;
201 $country = lc($country);
202 if (exists $COUNTRIES->[$codeset]->{$country})
204 return $COUNTRIES->[$codeset]->{$country};
208 #---------------------------------------------------------------
210 #---------------------------------------------------------------
215 sub country_code2code
217 (@_ == 3) or croak "country_code2code() takes 3 arguments!";
226 return undef if $inset == $outset;
227 $country = code2country($code, $inset);
228 return undef if not defined $country;
229 $outcode = country2code($country, $outset);
233 #=======================================================================
235 =head1 QUERY ROUTINES
237 There are two function which can be used to obtain a list of all codes,
238 or all country names:
242 =item C<all_country_codes( [ CODESET ] )>
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.
248 =item C<all_country_names( [ CODESET ] )>
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.
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.
263 #=======================================================================
264 sub all_country_codes
266 my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
268 return keys %{ $CODES->[$codeset] };
271 sub all_country_names
273 my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
275 return values %{ $CODES->[$codeset] };
278 #-----------------------------------------------------------------------
282 This module supports a semi-private routine for specifying two letter
285 Locale::Country::_alias_code( ALIAS => CODE [, CODESET ] )
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.
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:
297 Locale::Country::_alias_code('uk' => 'gb');
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".
304 #-----------------------------------------------------------------------
310 my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
315 if (not exists $CODES->[$codeset]->{$real})
317 carp "attempt to alias \"$alias\" to unknown country code \"$real\"\n";
320 $country = $CODES->[$codeset]->{$real};
321 $CODES->[$codeset]->{$alias} = $country;
322 $COUNTRIES->[$codeset]->{"\L$country"} = $alias;
327 #-----------------------------------------------------------------------
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
335 $| = 1; # turn off buffering
337 print "Enter country code: ";
338 chop($code = <STDIN>);
339 $country = code2country($code, LOCALE_CODE_ALPHA_2);
340 if (defined $country)
342 print "$code = $country\n";
346 print "'$code' is not a valid country code!\n";
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.
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?
359 =head1 KNOWN BUGS AND LIMITATIONS
365 When using C<country2code()>, the country name must currently appear
366 exactly as it does in the source of the module. The module now supports
367 a small number of variants.
369 Possible extensions to this are: an interface for getting at the
370 list of variant names, and regular expression matches.
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.
380 Support for country names in different languages.
388 =item Locale::Language
390 ISO two letter codes for identification of language (ISO 639).
394 ISO codes for identification of scripts (ISO 15924).
396 =item Locale::Currency
398 ISO three letter codes for identification of currencies
399 and funds (ISO 4217).
403 The ISO standard which defines these codes.
405 =item http://www.din.de/gremien/nas/nabd/iso3166ma/
407 Official home page for ISO 3166
409 =item http://www.egt.ie/standards/iso3166/iso3166-1-en.html
411 Another useful, but not official, home page.
413 =item http://www.cia.gov/cia/publications/factbook/docs/app-f.html
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.
423 Neil Bowers E<lt>neil@bowers.comE<gt>
427 Copyright (C) 2002, Neil Bowers.
429 Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
431 This module is free software; you can redistribute it and/or
432 modify it under the same terms as Perl itself.
436 #-----------------------------------------------------------------------
438 #=======================================================================
439 # initialisation code - stuff the DATA into the ALPHA2 hash
440 #=======================================================================
442 my ($alpha2, $alpha3, $numeric);
443 my ($country, @countries);
450 ($alpha2, $alpha3, $numeric, @countries) = split(/:/, $_);
452 $CODES->[LOCALE_CODE_ALPHA_2]->{$alpha2} = $countries[0];
453 foreach $country (@countries)
455 $COUNTRIES->[LOCALE_CODE_ALPHA_2]->{"\L$country"} = $alpha2;
460 $CODES->[LOCALE_CODE_ALPHA_3]->{$alpha3} = $countries[0];
461 foreach $country (@countries)
463 $COUNTRIES->[LOCALE_CODE_ALPHA_3]->{"\L$country"} = $alpha3;
469 $CODES->[LOCALE_CODE_NUMERIC]->{$numeric} = $countries[0];
470 foreach $country (@countries)
472 $COUNTRIES->[LOCALE_CODE_NUMERIC]->{"\L$country"} = $numeric;
483 ae:are:784:United Arab Emirates
484 af:afg:004:Afghanistan
485 ag:atg:028:Antigua and Barbuda
489 an:ant:530:Netherlands Antilles
493 as:asm:016:American Samoa
497 az:aze:031:Azerbaijan
498 ba:bih:070:Bosnia and Herzegovina
500 bd:bgd:050:Bangladesh
502 bf:bfa:854:Burkina Faso
508 bn:brn:096:Brunei Darussalam
518 cc:::Cocos (Keeling) Islands
519 cd:cod:180:Congo, The Democratic Republic of the:Congo, Democratic Republic of the
520 cf:caf:140:Central African Republic
522 ch:che:756:Switzerland
523 ci:civ:384:Cote D'Ivoire
524 ck:cok:184:Cook Islands
529 cr:cri:188:Costa Rica
531 cv:cpv:132:Cape Verde
532 cx:::Christmas Island
534 cz:cze:203:Czech Republic
539 do:dom:214:Dominican Republic
544 eh:esh:732:Western Sahara
550 fk:flk:238:Falkland Islands (Malvinas):Falkland Islands (Islas Malvinas)
551 fm:fsm:583:Micronesia, Federated States of
552 fo:fro:234:Faroe Islands
554 fx:::France, Metropolitan
556 gb:gbr:826:United Kingdom:Great Britain
559 gf:guf:254:French Guiana
565 gp:glp:312:Guadeloupe
566 gq:gnq:226:Equatorial Guinea
568 gs:::South Georgia and the South Sandwich Islands
571 gw:gnb:624:Guinea-Bissau
574 hm:::Heard Island and McDonald Islands
583 io:::British Indian Ocean Territory
585 ir:irn:364:Iran, Islamic Republic of:Iran
592 kg:kgz:417:Kyrgyzstan
596 kn:kna:659:Saint Kitts and Nevis
597 kp:prk:408:Korea, Democratic People's Republic of:Korea, North:North Korea
598 kr:kor:410:Korea, Republic of:Korea, South:South Korea
600 ky:cym:136:Cayman Islands
602 la:lao:418:Lao People's Democratic Republic
604 lc:lca:662:Saint Lucia
605 li:lie:438:Liechtenstein
610 lu:lux:442:Luxembourg
612 ly:lby:434:Libyan Arab Jamahiriya:Libya
615 md:mda:498:Moldova, Republic of
616 mg:mdg:450:Madagascar
617 mh:mhl:584:Marshall Islands
618 mk:mkd:807:Macedonia, the Former Yugoslav Republic of:Macedonia, Former Yugoslav Republic of:Macedonia
623 mp:mnp:580:Northern Mariana Islands
624 mq:mtq:474:Martinique
625 mr:mrt:478:Mauritania
626 ms:msr:500:Montserrat
633 mz:moz:508:Mozambique
635 nc:ncl:540:New Caledonia
637 nf:nfk:574:Norfolk Island
640 nl:nld:528:Netherlands
645 nz:nzl:554:New Zealand
649 pf:pyf:258:French Polynesia
650 pg:png:598:Papua New Guinea
651 ph:phl:608:Philippines
654 pm:spm:666:Saint Pierre and Miquelon
655 pn:pcn:612:Pitcairn:Pitcairn Island
656 pr:pri:630:Puerto Rico
657 ps:pse:275:Palestinian Territory, Occupied
664 ru:rus:643:Russian Federation:Russia
666 sa:sau:682:Saudi Arabia
667 sb:slb:090:Solomon Islands
668 sc:syc:690:Seychelles
672 sh:shn:654:Saint Helena
674 sj:sjm:744:Svalbard and Jan Mayen:Jan Mayen:Svalbard
676 sl:sle:694:Sierra Leone
677 sm:smr:674:San Marino
681 st:stp:678:Sao Tome and Principe
682 sv:slv:222:El Salvador
683 sy:syr:760:Syrian Arab Republic:Syria
685 tc:tca:796:Turks and Caicos Islands
687 tf:::French Southern Territories
690 tj:tjk:762:Tajikistan
692 tm:tkm:795:Turkmenistan
695 tp:tmp:626:East Timor
697 tt:tto:780:Trinidad and Tobago
699 tw:twn:158:Taiwan, Province of China:Taiwan
700 tz:tza:834:Tanzania, United Republic of:Tanzania
703 um:::United States Minor Outlying Islands
704 us:usa:840:United States:USA:United States of America
706 uz:uzb:860:Uzbekistan
707 va:vat:336:Holy See (Vatican City State):Hole See (Vatican City)
708 vc:vct:670:Saint Vincent and the Grenadines
710 vg:vgb:092:Virgin Islands, British:British Virgin Islands
711 vi:vir:850:Virgin Islands, U.S.
714 wf:wlf:876:Wallis and Futuna
718 yu:yug:891:Yugoslavia
719 za:zaf:710:South Africa