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