Commit | Line | Data |
f768f60b |
1 | =pod |
6b14ceb7 |
2 | |
3 | =head1 NAME |
4 | |
f768f60b |
5 | Locale::Country - standard codes for country identification |
6b14ceb7 |
6 | |
7 | =head1 SYNOPSIS |
8 | |
f768f60b |
9 | use Locale::Country; |
6b14ceb7 |
10 | |
f768f60b |
11 | $country = code2country('jp' [,CODESET]); # $country gets 'Japan' |
12 | $code = country2code('Norway' [,CODESET]); # $code gets 'no' |
6b14ceb7 |
13 | |
f768f60b |
14 | @codes = all_country_codes( [CODESET]); |
15 | @names = all_country_names(); |
6b14ceb7 |
16 | |
f768f60b |
17 | # semi-private routines |
18 | Locale::Country::alias_code('uk' => 'gb'); |
19 | Locale::Country::rename_country('gb' => 'Great Britain'); |
6b14ceb7 |
20 | |
f768f60b |
21 | =head1 DESCRIPTION |
6b14ceb7 |
22 | |
f768f60b |
23 | The C<Locale::Country> module provides access to several code sets |
24 | that can be used for identifying countries, such as those defined in |
25 | ISO 3166-1. |
6b14ceb7 |
26 | |
f768f60b |
27 | Most of the routines take an optional additional argument which |
28 | specifies the code set to use. If not specified, the default ISO |
29 | 3166-1 two-letter codes will be used. |
6b14ceb7 |
30 | |
f768f60b |
31 | =head1 SUPPORTED CODE SETS |
6b14ceb7 |
32 | |
f768f60b |
33 | There are several different code sets you can use for identifying |
34 | countries. The ones currently supported are: |
6b14ceb7 |
35 | |
f768f60b |
36 | =over 4 |
6b14ceb7 |
37 | |
f768f60b |
38 | =item B<alpha-2> |
6b14ceb7 |
39 | |
f768f60b |
40 | This is the set of two-letter (lowercase) codes from ISO 3166-1, such |
41 | as 'tv' for Tuvalu. |
6b14ceb7 |
42 | |
f768f60b |
43 | This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>. |
6b14ceb7 |
44 | |
f768f60b |
45 | This is the default code set. |
6b14ceb7 |
46 | |
f768f60b |
47 | =item B<alpha-3> |
6b14ceb7 |
48 | |
f768f60b |
49 | This is the set of three-letter (lowercase) codes from ISO 3166-1, |
50 | such as 'brb' for Barbados. These codes are actually defined and |
51 | maintained by the U.N. Statistics division. |
6b14ceb7 |
52 | |
f768f60b |
53 | This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>. |
6b14ceb7 |
54 | |
f768f60b |
55 | =item B<numeric> |
6b14ceb7 |
56 | |
f768f60b |
57 | This is the set of three-digit numeric codes from ISO 3166-1, such as |
58 | 064 for Bhutan. These codes are actually defined and maintained by the |
59 | U.N. Statistics division. |
6b14ceb7 |
60 | |
f768f60b |
61 | If a 2-digit code is entered, it is converted to 3 digits by prepending |
62 | a 0. |
6b14ceb7 |
63 | |
f768f60b |
64 | This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>. |
6b14ceb7 |
65 | |
f768f60b |
66 | =item B<fips-10> |
6b14ceb7 |
67 | |
f768f60b |
68 | The FIPS 10 data are two-letter (uppercase) codes assigned by the |
69 | National Geospatial-Intelligence Agency. |
6b14ceb7 |
70 | |
f768f60b |
71 | This code set is identified with the symbol C<LOCALE_CODE_FIPS>. |
6b14ceb7 |
72 | |
f768f60b |
73 | =item B<dom> |
6b14ceb7 |
74 | |
f768f60b |
75 | The IANA is responsible for assigning two-letter (uppercase) top-level |
76 | domain names to each country. |
6b14ceb7 |
77 | |
f768f60b |
78 | This code set is identified with the symbol C<LOCALE_CODE_DOM>. |
6b14ceb7 |
79 | |
80 | =back |
81 | |
f768f60b |
82 | =head1 ROUTINES |
6b14ceb7 |
83 | |
84 | =over 4 |
85 | |
f768f60b |
86 | =item B<code2country ( CODE [,CODESET] )> |
6b14ceb7 |
87 | |
f768f60b |
88 | =item B<country2code ( NAME [,CODESET] )> |
6b14ceb7 |
89 | |
f768f60b |
90 | =item B<country_code2code ( CODE ,CODESET ,CODESET2 )> |
6b14ceb7 |
91 | |
f768f60b |
92 | =item B<all_country_codes ( [CODESET] )> |
6b14ceb7 |
93 | |
f768f60b |
94 | =item B<all_country_names ( [CODESET] )> |
917211f5 |
95 | |
f768f60b |
96 | =item B<Locale::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )> |
917211f5 |
97 | |
f768f60b |
98 | =item B<Locale::Country::add_country ( CODE ,NAME [,CODESET] )> |
6b14ceb7 |
99 | |
f768f60b |
100 | =item B<Locale::Country::delete_country ( CODE [,CODESET] )> |
6b14ceb7 |
101 | |
f768f60b |
102 | =item B<Locale::Country::add_country_alias ( NAME ,NEW_NAME )> |
6b14ceb7 |
103 | |
f768f60b |
104 | =item B<Locale::Country::delete_country_alias ( NAME )> |
6b14ceb7 |
105 | |
f768f60b |
106 | =item B<Locale::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )> |
6b14ceb7 |
107 | |
f768f60b |
108 | =item B<Locale::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )> |
917211f5 |
109 | |
f768f60b |
110 | =item B<Locale::Country::delete_country_code_alias ( CODE [,CODESET] )> |
917211f5 |
111 | |
f768f60b |
112 | These routines are all documented in the Locale::Codes man page. |
917211f5 |
113 | |
f768f60b |
114 | =item B<alias_code ( ALIAS, CODE [,CODESET] )> |
917211f5 |
115 | |
f768f60b |
116 | Version 2.07 included 2 functions for modifying the internal data: |
117 | rename_country and alias_code. Both of these could be used only to |
118 | modify the internal data for country codes. |
917211f5 |
119 | |
f768f60b |
120 | As of 3.10, the internal data for all types of codes can be modified. |
6b14ceb7 |
121 | |
f768f60b |
122 | The alias_code function is preserved for backwards compatibility, but |
123 | the following two are identical: |
6b14ceb7 |
124 | |
f768f60b |
125 | alias_code(ALIAS,CODE [,CODESET]); |
126 | rename_country_code(CODE,ALIAS [,CODESET]); |
6b14ceb7 |
127 | |
f768f60b |
128 | and the latter should be used for consistency. |
6b14ceb7 |
129 | |
f768f60b |
130 | The alias_code function is deprecated (though there is no currently no |
131 | plan to remove it). |
6b14ceb7 |
132 | |
f768f60b |
133 | B<Note:> this function was previously called _alias_code, but the |
134 | leading underscore has been dropped. The old name was supported for |
135 | all 2.X releases, but has been dropped as of 3.00. |
6b14ceb7 |
136 | |
f768f60b |
137 | =back |
6b14ceb7 |
138 | |
f768f60b |
139 | =head1 SEE ALSO |
6b14ceb7 |
140 | |
141 | =over 4 |
142 | |
f768f60b |
143 | =item B<Locale::Codes> |
6b14ceb7 |
144 | |
f768f60b |
145 | =item B<Locale::Constants> |
6b14ceb7 |
146 | |
f768f60b |
147 | =item B<Locale::SubCountry> |
6b14ceb7 |
148 | |
f768f60b |
149 | ISO codes for country sub-divisions (states, counties, provinces, |
150 | etc), as defined in ISO 3166-2. This module is not part of the |
151 | Locale-Codes distribution, but is available from CPAN in |
152 | CPAN/modules/by-module/Locale/ |
6b14ceb7 |
153 | |
f768f60b |
154 | =item B<http://www.iso.org/iso/country_codes> |
6b14ceb7 |
155 | |
f768f60b |
156 | Official home page for the ISO 3166 maintenance agency. |
6b14ceb7 |
157 | |
f768f60b |
158 | Unfortunately, they do not make the actual ISO available for free, |
159 | so I cannot check the alpha-3 and numerical codes here. |
6b14ceb7 |
160 | |
f768f60b |
161 | =item B<http://www.iso.org/iso/list-en1-semic-3.txt> |
6b14ceb7 |
162 | |
f768f60b |
163 | The source of ISO 3166-1 two-letter codes used by this |
164 | module. |
6b14ceb7 |
165 | |
f768f60b |
166 | =item B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm> |
6b14ceb7 |
167 | |
f768f60b |
168 | The source of the official ISO 3166-1 three-letter codes and |
169 | three-digit codes. |
917211f5 |
170 | |
f768f60b |
171 | For some reason, this table is incomplete! Several countries are |
172 | missing from it, and I cannot find them anywhere on the UN site. I |
173 | get as much of the data from here as I can. |
917211f5 |
174 | |
f768f60b |
175 | =item B<http://earth-info.nga.mil/gns/html/digraphs.htm> |
6b14ceb7 |
176 | |
f768f60b |
177 | The official list of the FIPS 10 codes. |
6b14ceb7 |
178 | |
f768f60b |
179 | =item B<http://www.iana.org/domains/> |
6b14ceb7 |
180 | |
f768f60b |
181 | Official source of the top-level domain names. |
6b14ceb7 |
182 | |
f768f60b |
183 | =item B<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html> |
6b14ceb7 |
184 | |
f768f60b |
185 | Although not the official source of any of the data, the World |
186 | Factbook maintained by the CIA is a great source of the data, |
187 | especially since I can't get the official data from the ISO. Since |
188 | it's maintained by the CIA, and since it's updated every two weeks, I |
189 | use this as the source for some missing data. |
6b14ceb7 |
190 | |
f768f60b |
191 | =item B<http://www.statoids.com/wab.html> |
6b14ceb7 |
192 | |
f768f60b |
193 | Another unofficial source of data. Currently, it is not used to get |
194 | data, but the notes and explanatory material were very useful for |
195 | understanding discrepancies between the sources. |
6b14ceb7 |
196 | |
197 | =back |
198 | |
6b14ceb7 |
199 | =head1 AUTHOR |
200 | |
f768f60b |
201 | See Locale::Codes for full author history. |
6b14ceb7 |
202 | |
f768f60b |
203 | Currently maintained by Sullivan Beck (sbeck@cpan.org). |
6b14ceb7 |
204 | |
f768f60b |
205 | =head1 COPYRIGHT |
6b14ceb7 |
206 | |
f768f60b |
207 | Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). |
208 | Copyright (c) 2001-2010 Neil Bowers |
209 | Copyright (c) 2010-2010 Sullivan Beck |
6b14ceb7 |
210 | |
211 | This module is free software; you can redistribute it and/or |
212 | modify it under the same terms as Perl itself. |
213 | |
214 | =cut |