Commit | Line | Data |
---|---|---|
f768f60b | 1 | =pod |
6b14ceb7 JH |
2 | |
3 | =head1 NAME | |
4 | ||
f768f60b | 5 | Locale::Country - standard codes for country identification |
6b14ceb7 JH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
f768f60b | 9 | use Locale::Country; |
6b14ceb7 | 10 | |
f768f60b S |
11 | $country = code2country('jp' [,CODESET]); # $country gets 'Japan' |
12 | $code = country2code('Norway' [,CODESET]); # $code gets 'no' | |
6b14ceb7 | 13 | |
f768f60b S |
14 | @codes = all_country_codes( [CODESET]); |
15 | @names = all_country_names(); | |
6b14ceb7 | 16 | |
f768f60b | 17 | # semi-private routines |
f768f60b | 18 | Locale::Country::rename_country('gb' => 'Great Britain'); |
6b14ceb7 | 19 | |
f768f60b | 20 | =head1 DESCRIPTION |
6b14ceb7 | 21 | |
68bfa5ea | 22 | This module provides access to several code sets |
f768f60b S |
23 | that can be used for identifying countries, such as those defined in |
24 | ISO 3166-1. | |
6b14ceb7 | 25 | |
f768f60b S |
26 | Most of the routines take an optional additional argument which |
27 | specifies the code set to use. If not specified, the default ISO | |
28 | 3166-1 two-letter codes will be used. | |
6b14ceb7 | 29 | |
f768f60b | 30 | =head1 SUPPORTED CODE SETS |
6b14ceb7 | 31 | |
f768f60b | 32 | There are several different code sets you can use for identifying |
4345d05b CBW |
33 | countries. A code set may be specified using either a name, or a |
34 | constant that is automatically exported by this module. | |
35 | ||
36 | For example, the two are equivalent: | |
37 | ||
38 | $country = code2country('jp','alpha-2'); | |
39 | $country = code2country('jp',LOCALE_CODE_ALPHA_2); | |
40 | ||
41 | The codesets currently supported are: | |
6b14ceb7 | 42 | |
f768f60b | 43 | =over 4 |
6b14ceb7 | 44 | |
4345d05b | 45 | =item B<alpha-2, LOCALE_CODE_ALPHA_2> |
6b14ceb7 | 46 | |
f768f60b S |
47 | This is the set of two-letter (lowercase) codes from ISO 3166-1, such |
48 | as 'tv' for Tuvalu. | |
6b14ceb7 | 49 | |
f768f60b | 50 | This is the default code set. |
6b14ceb7 | 51 | |
4345d05b | 52 | =item B<alpha-3, LOCALE_CODE_ALPHA_3> |
6b14ceb7 | 53 | |
f768f60b S |
54 | This is the set of three-letter (lowercase) codes from ISO 3166-1, |
55 | such as 'brb' for Barbados. These codes are actually defined and | |
56 | maintained by the U.N. Statistics division. | |
6b14ceb7 | 57 | |
4345d05b | 58 | =item B<numeric, LOCALE_CODE_NUMERIC> |
6b14ceb7 | 59 | |
f768f60b S |
60 | This is the set of three-digit numeric codes from ISO 3166-1, such as |
61 | 064 for Bhutan. These codes are actually defined and maintained by the | |
62 | U.N. Statistics division. | |
6b14ceb7 | 63 | |
f768f60b S |
64 | If a 2-digit code is entered, it is converted to 3 digits by prepending |
65 | a 0. | |
6b14ceb7 | 66 | |
4345d05b | 67 | =item B<dom, LOCALE_CODE_DOM> |
6b14ceb7 | 68 | |
b15b9c2a SB |
69 | The IANA is responsible for delegating management of the top level country |
70 | domains. The country domains are the two-letter (lowercase) codes from ISO 3166 | |
71 | with a few other additions. | |
6b14ceb7 | 72 | |
6b14ceb7 JH |
73 | =back |
74 | ||
94eda824 SB |
75 | NOTE: As of version 3.27, the FIPS code set is no longer supported. See the |
76 | Locale::Codes::Changes document for details. | |
77 | ||
f768f60b | 78 | =head1 ROUTINES |
6b14ceb7 JH |
79 | |
80 | =over 4 | |
81 | ||
68bfa5ea | 82 | =item B<code2country(CODE [,CODESET] [,'retired'])> |
6b14ceb7 | 83 | |
68bfa5ea | 84 | =item B<country2code(NAME [,CODESET] [,'retired'])> |
6b14ceb7 | 85 | |
68bfa5ea | 86 | =item B<country_code2code(CODE ,CODESET ,CODESET2)> |
6b14ceb7 | 87 | |
68bfa5ea | 88 | =item B<all_country_codes([CODESET] [,'retired'])> |
6b14ceb7 | 89 | |
68bfa5ea | 90 | =item B<all_country_names([CODESET] [,'retired'])> |
917211f5 | 91 | |
68bfa5ea | 92 | =item B<Locale::Country::rename_country(CODE ,NEW_NAME [,CODESET])> |
917211f5 | 93 | |
68bfa5ea | 94 | =item B<Locale::Country::add_country(CODE ,NAME [,CODESET])> |
6b14ceb7 | 95 | |
68bfa5ea | 96 | =item B<Locale::Country::delete_country(CODE [,CODESET])> |
6b14ceb7 | 97 | |
68bfa5ea | 98 | =item B<Locale::Country::add_country_alias(NAME ,NEW_NAME)> |
6b14ceb7 | 99 | |
68bfa5ea | 100 | =item B<Locale::Country::delete_country_alias(NAME)> |
6b14ceb7 | 101 | |
68bfa5ea | 102 | =item B<Locale::Country::rename_country_code(CODE ,NEW_CODE [,CODESET])> |
6b14ceb7 | 103 | |
68bfa5ea | 104 | =item B<Locale::Country::add_country_code_alias(CODE ,NEW_CODE [,CODESET])> |
917211f5 | 105 | |
68bfa5ea | 106 | =item B<Locale::Country::delete_country_code_alias(CODE [,CODESET])> |
917211f5 | 107 | |
68bfa5ea | 108 | These routines are all documented in the L<Locale::Codes::API> man page. |
917211f5 | 109 | |
f768f60b | 110 | =back |
6b14ceb7 | 111 | |
f768f60b | 112 | =head1 SEE ALSO |
6b14ceb7 JH |
113 | |
114 | =over 4 | |
115 | ||
68bfa5ea | 116 | =item L<Locale::Codes> |
6b14ceb7 | 117 | |
e1137bc7 SB |
118 | The Locale-Codes distribution. |
119 | ||
68bfa5ea | 120 | =item L<Locale::Codes::API> |
c69a30ec CBW |
121 | |
122 | The list of functions supported by this module. | |
123 | ||
68bfa5ea | 124 | =item L<Locale::SubCountry> |
6b14ceb7 | 125 | |
f768f60b S |
126 | ISO codes for country sub-divisions (states, counties, provinces, |
127 | etc), as defined in ISO 3166-2. This module is not part of the | |
128 | Locale-Codes distribution, but is available from CPAN in | |
129 | CPAN/modules/by-module/Locale/ | |
6b14ceb7 | 130 | |
68bfa5ea | 131 | =item L<http://www.iso.org/iso/home/standards/country_codes.htm> |
6b14ceb7 | 132 | |
f768f60b | 133 | Official home page for the ISO 3166 maintenance agency. |
6b14ceb7 | 134 | |
68bfa5ea | 135 | =item L<http://www.iso.org/iso/home/standards/country_codes/iso-3166-1_decoding_table.htm> |
b15b9c2a | 136 | |
f768f60b S |
137 | The source of ISO 3166-1 two-letter codes used by this |
138 | module. | |
6b14ceb7 | 139 | |
68bfa5ea | 140 | =item L<http://www.iana.org/domains/root/db/> |
e744ae18 SB |
141 | |
142 | Official source of the top-level domain names. | |
143 | ||
68bfa5ea | 144 | =item L<http://unstats.un.org/unsd/methods/m49/m49alpha.htm> |
6b14ceb7 | 145 | |
f768f60b S |
146 | The source of the official ISO 3166-1 three-letter codes and |
147 | three-digit codes. | |
917211f5 | 148 | |
f768f60b S |
149 | For some reason, this table is incomplete! Several countries are |
150 | missing from it, and I cannot find them anywhere on the UN site. I | |
e744ae18 | 151 | no longer use this as a source of data. |
6b14ceb7 | 152 | |
68bfa5ea | 153 | =item L<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html> |
6b14ceb7 | 154 | |
4345d05b CBW |
155 | The World Factbook maintained by the CIA is a potential source of |
156 | the data. Unfortunately, it adds/preserves non-standard codes, so it is no | |
157 | longer used as a source of data. | |
6b14ceb7 | 158 | |
68bfa5ea | 159 | =item L<http://www.statoids.com/wab.html> |
6b14ceb7 | 160 | |
f768f60b S |
161 | Another unofficial source of data. Currently, it is not used to get |
162 | data, but the notes and explanatory material were very useful for | |
163 | understanding discrepancies between the sources. | |
6b14ceb7 JH |
164 | |
165 | =back | |
166 | ||
6b14ceb7 JH |
167 | =head1 AUTHOR |
168 | ||
f768f60b | 169 | See Locale::Codes for full author history. |
6b14ceb7 | 170 | |
f768f60b | 171 | Currently maintained by Sullivan Beck (sbeck@cpan.org). |
6b14ceb7 | 172 | |
f768f60b | 173 | =head1 COPYRIGHT |
6b14ceb7 | 174 | |
f768f60b S |
175 | Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). |
176 | Copyright (c) 2001-2010 Neil Bowers | |
add9356c | 177 | Copyright (c) 2010-2016 Sullivan Beck |
6b14ceb7 JH |
178 | |
179 | This module is free software; you can redistribute it and/or | |
180 | modify it under the same terms as Perl itself. | |
181 | ||
182 | =cut |