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.
74 #-----------------------------------------------------------------------
78 use Locale::Constants;
81 #-----------------------------------------------------------------------
82 # Public Global Variables
83 #-----------------------------------------------------------------------
84 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
85 $VERSION = sprintf("%d.%02d", q$Revision: 1.7 $ =~ /(\d+)\.(\d+)/);
87 @EXPORT = qw(code2country country2code
88 all_country_codes all_country_names
90 LOCALE_CODE_ALPHA_2 LOCALE_CODE_ALPHA_3 LOCALE_CODE_NUMERIC);
92 #-----------------------------------------------------------------------
93 # Private Global Variables
94 #-----------------------------------------------------------------------
99 #=======================================================================
101 =head1 CONVERSION ROUTINES
103 There are three conversion routines: C<code2country()>, C<country2code()>,
104 and C<country_code2code()>.
108 =item code2country( CODE, [ CODESET ] )
110 This function takes a country code and returns a string
111 which contains the name of the country identified.
112 If the code is not a valid country code, as defined by ISO 3166,
113 then C<undef> will be returned:
115 $country = code2country('fi');
117 =item country2code( STRING, [ CODESET ] )
119 This function takes a country name and returns the corresponding
120 country code, if such exists.
121 If the argument could not be identified as a country name,
122 then C<undef> will be returned:
124 $code = country2code('Norway', LOCALE_CODE_ALPHA_3);
125 # $code will now be 'nor'
127 The case of the country name is not important.
128 See the section L<KNOWN BUGS AND LIMITATIONS> below.
130 =item country_code2code( CODE, CODESET, CODESET )
132 This function takes a country code from one code set,
133 and returns the corresponding code from another code set.
135 $alpha2 = country_code2code('fin',
136 LOCALE_CODE_ALPHA_3 => LOCALE_CODE_ALPHA_2);
137 # $alpha2 will now be 'fi'
139 If the code passed is not a valid country code in
140 the first code set, or if there isn't a code for the
141 corresponding country in the second code set,
142 then C<undef> will be returned.
148 #=======================================================================
152 my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
155 return undef unless defined $code;
157 #-------------------------------------------------------------------
158 # Make sure the code is in the right form before we use it
159 # to look up the corresponding country.
160 # We have to sprintf because the codes are given as 3-digits,
161 # with leading 0's. Eg 052 for Barbados.
162 #-------------------------------------------------------------------
163 if ($codeset == LOCALE_CODE_NUMERIC)
165 return undef if ($code =~ /\D/);
166 $code = sprintf("%.3d", $code);
173 if (exists $CODES->[$codeset]->{$code})
175 return $CODES->[$codeset]->{$code};
179 #---------------------------------------------------------------
180 # no such country code!
181 #---------------------------------------------------------------
189 my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
192 return undef unless defined $country;
193 $country = lc($country);
194 if (exists $COUNTRIES->[$codeset]->{$country})
196 return $COUNTRIES->[$codeset]->{$country};
200 #---------------------------------------------------------------
202 #---------------------------------------------------------------
207 sub country_code2code
209 (@_ == 3) or croak "country_code2code() takes 3 arguments!";
218 return undef if $inset == $outset;
219 $country = code2country($code, $inset);
220 return undef if not defined $country;
221 $outcode = country2code($country, $outset);
225 #=======================================================================
227 =head1 QUERY ROUTINES
229 There are two function which can be used to obtain a list of all codes,
230 or all country names:
234 =item C<all_country_codes( [ CODESET ] )>
236 Returns a list of all two-letter country codes.
237 The codes are guaranteed to be all lower-case,
238 and not in any particular order.
240 =item C<all_country_names( [ CODESET ] )>
242 Returns a list of all country names for which there is a corresponding
243 country code in the specified code set.
244 The names are capitalised, and not returned in any particular order.
246 Not all countries have alpha-3 and numeric codes -
247 some just have an alpha-2 code,
248 so you'll get a different number of countries
249 depending on which code set you specify.
255 #=======================================================================
256 sub all_country_codes
258 my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
260 return keys %{ $CODES->[$codeset] };
263 sub all_country_names
265 my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
267 return values %{ $CODES->[$codeset] };
270 #-----------------------------------------------------------------------
274 This module supports a semi-private routine for specifying two letter
277 Locale::Country::_alias_code( ALIAS => CODE [, CODESET ] )
279 This feature was added as a mechanism for handling
280 a "uk" code. The ISO standard says that the two-letter code for
281 "United Kingdom" is "gb", whereas domain names are all .uk.
283 By default the module does not understand "uk", since it is implementing
284 an ISO standard. If you would like 'uk' to work as the two-letter
285 code for United Kingdom, use the following:
289 Locale::Country::_alias_code('uk' => 'gb');
291 With this code, both "uk" and "gb" are valid codes for United Kingdom,
292 with the reverse lookup returning "uk" rather than the usual "gb".
296 #-----------------------------------------------------------------------
302 my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
307 if (not exists $CODES->[$codeset]->{$real})
309 carp "attempt to alias \"$alias\" to unknown country code \"$real\"\n";
312 $country = $CODES->[$codeset]->{$real};
313 $CODES->[$codeset]->{$alias} = $country;
314 $COUNTRIES->[$codeset]->{"\L$country"} = $alias;
319 #-----------------------------------------------------------------------
323 The following example illustrates use of the C<code2country()> function.
324 The user is prompted for a country code, and then told the corresponding
327 $| = 1; # turn off buffering
329 print "Enter country code: ";
330 chop($code = <STDIN>);
331 $country = code2country($code, LOCALE_CODE_ALPHA_2);
332 if (defined $country)
334 print "$code = $country\n";
338 print "'$code' is not a valid country code!\n";
343 Most top-level domain names are based on these codes,
344 but there are certain codes which aren't.
345 If you are using this module to identify country from hostname,
346 your best bet is to preprocess the country code.
348 For example, B<edu>, B<com>, B<gov> and friends would map to B<us>;
349 B<uk> would map to B<gb>. Any others?
351 =head1 KNOWN BUGS AND LIMITATIONS
357 When using C<country2code()>, the country name must currently appear
358 exactly as it does in the source of the module. For example,
360 country2code('United States')
362 will return B<us>, as expected. But the following will all return C<undef>:
364 country2code('United States of America')
365 country2code('Great Britain')
366 country2code('U.S.A.')
368 If there's need for it, a future version could have variants
373 In the current implementation, all data is read in when the
374 module is loaded, and then held in memory.
375 A lazy implementation would be more memory friendly.
383 =item Locale::Language
385 ISO two letter codes for identification of language (ISO 639).
387 =item Locale::Currency
389 ISO three letter codes for identification of currencies
390 and funds (ISO 4217).
394 The ISO standard which defines these codes.
396 =item http://www.din.de/gremien/nas/nabd/iso3166ma/
398 Official home page for ISO 3166
400 =item http://www.egt.ie/standards/iso3166/iso3166-1-en.html
402 Another useful, but not official, home page.
404 =item http://www.cia.gov/cia/publications/factbook/docs/app-f.html
406 An appendix in the CIA world fact book which lists country codes
407 as defined by ISO 3166, FIPS 10-4, and internet domain names.
414 Neil Bowers E<lt>neilb@cre.canon.co.ukE<gt>
418 Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
420 This module is free software; you can redistribute it and/or
421 modify it under the same terms as Perl itself.
425 #-----------------------------------------------------------------------
427 #=======================================================================
428 # initialisation code - stuff the DATA into the ALPHA2 hash
429 #=======================================================================
431 my ($alpha2, $alpha3, $numeric);
439 ($alpha2, $alpha3, $numeric, $country) = split(/:/, $_, 4);
441 $CODES->[LOCALE_CODE_ALPHA_2]->{$alpha2} = $country;
442 $COUNTRIES->[LOCALE_CODE_ALPHA_2]->{"\L$country"} = $alpha2;
446 $CODES->[LOCALE_CODE_ALPHA_3]->{$alpha3} = $country;
447 $COUNTRIES->[LOCALE_CODE_ALPHA_3]->{"\L$country"} = $alpha3;
452 $CODES->[LOCALE_CODE_NUMERIC]->{$numeric} = $country;
453 $COUNTRIES->[LOCALE_CODE_NUMERIC]->{"\L$country"} = $numeric;
463 ae:are:784:United Arab Emirates
464 af:afg:004:Afghanistan
465 ag:atg:028:Antigua and Barbuda
469 an:ant:530:Netherlands Antilles
473 as:asm:016:American Samoa
477 az:aze:031:Azerbaijan
478 ba:bih:070:Bosnia and Herzegovina
480 bd:bgd:050:Bangladesh
482 bf:bfa:854:Burkina Faso
488 bn:brn:096:Brunei Darussalam
498 cc:::Cocos (Keeling) Islands
499 cd:cod:180:Congo, The Democratic Republic of the
500 cf:caf:140:Central African Republic
502 ch:che:756:Switzerland
503 ci:civ:384:Cote D'Ivoire
504 ck:cok:184:Cook Islands
509 cr:cri:188:Costa Rica
511 cv:cpv:132:Cape Verde
512 cx:::Christmas Island
514 cz:cze:203:Czech Republic
519 do:dom:214:Dominican Republic
524 eh:esh:732:Western Sahara
530 fk:flk:238:Falkland Islands (Malvinas)
531 fm:fsm:583:Micronesia, Federated States of
532 fo:fro:234:Faroe Islands
534 fx:::France, Metropolitan
536 gb:gbr:826:United Kingdom
539 gf:guf:254:French Guiana
545 gp:glp:312:Guadeloupe
546 gq:gnq:226:Equatorial Guinea
548 gs:::South Georgia and the South Sandwich Islands
551 gw:gnb:624:Guinea-Bissau
554 hm:::Heard Island and McDonald Islands
563 io:::British Indian Ocean Territory
565 ir:irn:364:Iran, Islamic Republic of
572 kg:kgz:417:Kyrgyzstan
576 kn:kna:659:Saint Kitts and Nevis
577 kp:prk:408:Korea, Democratic People's Republic of
578 kr:kor:410:Korea, Republic of
580 ky:cym:136:Cayman Islands
582 la:lao:418:Lao People's Democratic Republic
584 lc:lca:662:Saint Lucia
585 li:lie:438:Liechtenstein
590 lu:lux:442:Luxembourg
592 ly:lby:434:Libyan Arab Jamahiriya
595 md:mda:498:Moldova, Republic of
596 mg:mdg:450:Madagascar
597 mh:mhl:584:Marshall Islands
598 mk:mkd:807:Macedonia, the Former Yugoslav Republic of
603 mp:mnp:580:Northern Mariana Islands
604 mq:mtq:474:Martinique
605 mr:mrt:478:Mauritania
606 ms:msr:500:Montserrat
613 mz:moz:508:Mozambique
615 nc:ncl:540:New Caledonia
617 nf:nfk:574:Norfolk Island
620 nl:nld:528:Netherlands
625 nz:nzl:554:New Zealand
629 pf:pyf:258:French Polynesia
630 pg:png:598:Papua New Guinea
631 ph:phl:608:Philippines
634 pm:spm:666:Saint Pierre and Miquelon
636 pr:pri:630:Puerto Rico
637 ps:pse:275:Palestinian Territory, Occupied
644 ru:rus:643:Russian Federation
646 sa:sau:682:Saudi Arabia
647 sb:slb:090:Solomon Islands
648 sc:syc:690:Seychelles
652 sh:shn:654:Saint Helena
654 sj:sjm:744:Svalbard and Jan Mayen
656 sl:sle:694:Sierra Leone
657 sm:smr:674:San Marino
661 st:stp:678:Sao Tome and Principe
662 sv:slv:222:El Salvador
663 sy:syr:760:Syrian Arab Republic
665 tc:tca:796:Turks and Caicos Islands
667 tf:::French Southern Territories
670 tj:tjk:762:Tajikistan
672 tm:tkm:795:Turkmenistan
675 tp:tmp:626:East Timor
677 tt:tto:780:Trinidad and Tobago
679 tw:twn:158:Taiwan, Province of China
680 tz:tza:834:Tanzania, United Republic of
683 um:::United States Minor Outlying Islands
684 us:usa:840:United States
686 uz:uzb:860:Uzbekistan
687 va:vat:336:Holy See (Vatican City State)
688 vc:vct:670:Saint Vincent and the Grenadines
690 vg:vgb:092:Virgin Islands, British
691 vi:vir:850:Virgin Islands, U.S.
694 wf:wlf:876:Wallis and Futuna
698 yu:yug:891:Yugoslavia
699 za:zaf:710:South Africa