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 S |
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 S |
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 S |
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 |
4345d05b CBW |
34 | countries. A code set may be specified using either a name, or a |
35 | constant that is automatically exported by this module. | |
36 | ||
37 | For example, the two are equivalent: | |
38 | ||
39 | $country = code2country('jp','alpha-2'); | |
40 | $country = code2country('jp',LOCALE_CODE_ALPHA_2); | |
41 | ||
42 | The codesets currently supported are: | |
6b14ceb7 | 43 | |
f768f60b | 44 | =over 4 |
6b14ceb7 | 45 | |
4345d05b | 46 | =item B<alpha-2, LOCALE_CODE_ALPHA_2> |
6b14ceb7 | 47 | |
f768f60b S |
48 | This is the set of two-letter (lowercase) codes from ISO 3166-1, such |
49 | as 'tv' for Tuvalu. | |
6b14ceb7 | 50 | |
f768f60b | 51 | This is the default code set. |
6b14ceb7 | 52 | |
4345d05b | 53 | =item B<alpha-3, LOCALE_CODE_ALPHA_3> |
6b14ceb7 | 54 | |
f768f60b S |
55 | This is the set of three-letter (lowercase) codes from ISO 3166-1, |
56 | such as 'brb' for Barbados. These codes are actually defined and | |
57 | maintained by the U.N. Statistics division. | |
6b14ceb7 | 58 | |
4345d05b | 59 | =item B<numeric, LOCALE_CODE_NUMERIC> |
6b14ceb7 | 60 | |
f768f60b S |
61 | This is the set of three-digit numeric codes from ISO 3166-1, such as |
62 | 064 for Bhutan. These codes are actually defined and maintained by the | |
63 | U.N. Statistics division. | |
6b14ceb7 | 64 | |
f768f60b S |
65 | If a 2-digit code is entered, it is converted to 3 digits by prepending |
66 | a 0. | |
6b14ceb7 | 67 | |
4345d05b | 68 | =item B<fips-10, LOCALE_CODE_FIPS> |
6b14ceb7 | 69 | |
f768f60b S |
70 | The FIPS 10 data are two-letter (uppercase) codes assigned by the |
71 | National Geospatial-Intelligence Agency. | |
6b14ceb7 | 72 | |
4345d05b | 73 | =item B<dom, LOCALE_CODE_DOM> |
6b14ceb7 | 74 | |
f768f60b S |
75 | The IANA is responsible for assigning two-letter (uppercase) top-level |
76 | domain names to each country. | |
6b14ceb7 | 77 | |
6b14ceb7 JH |
78 | =back |
79 | ||
f768f60b | 80 | =head1 ROUTINES |
6b14ceb7 JH |
81 | |
82 | =over 4 | |
83 | ||
f768f60b | 84 | =item B<code2country ( CODE [,CODESET] )> |
6b14ceb7 | 85 | |
f768f60b | 86 | =item B<country2code ( NAME [,CODESET] )> |
6b14ceb7 | 87 | |
f768f60b | 88 | =item B<country_code2code ( CODE ,CODESET ,CODESET2 )> |
6b14ceb7 | 89 | |
f768f60b | 90 | =item B<all_country_codes ( [CODESET] )> |
6b14ceb7 | 91 | |
f768f60b | 92 | =item B<all_country_names ( [CODESET] )> |
917211f5 | 93 | |
f768f60b | 94 | =item B<Locale::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )> |
917211f5 | 95 | |
f768f60b | 96 | =item B<Locale::Country::add_country ( CODE ,NAME [,CODESET] )> |
6b14ceb7 | 97 | |
f768f60b | 98 | =item B<Locale::Country::delete_country ( CODE [,CODESET] )> |
6b14ceb7 | 99 | |
f768f60b | 100 | =item B<Locale::Country::add_country_alias ( NAME ,NEW_NAME )> |
6b14ceb7 | 101 | |
f768f60b | 102 | =item B<Locale::Country::delete_country_alias ( NAME )> |
6b14ceb7 | 103 | |
f768f60b | 104 | =item B<Locale::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )> |
6b14ceb7 | 105 | |
f768f60b | 106 | =item B<Locale::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )> |
917211f5 | 107 | |
f768f60b | 108 | =item B<Locale::Country::delete_country_code_alias ( CODE [,CODESET] )> |
917211f5 | 109 | |
c69a30ec | 110 | These routines are all documented in the Locale::Codes::API man page. |
917211f5 | 111 | |
f768f60b | 112 | =item B<alias_code ( ALIAS, CODE [,CODESET] )> |
917211f5 | 113 | |
f768f60b S |
114 | Version 2.07 included 2 functions for modifying the internal data: |
115 | rename_country and alias_code. Both of these could be used only to | |
116 | modify the internal data for country codes. | |
917211f5 | 117 | |
f768f60b | 118 | As of 3.10, the internal data for all types of codes can be modified. |
6b14ceb7 | 119 | |
f768f60b S |
120 | The alias_code function is preserved for backwards compatibility, but |
121 | the following two are identical: | |
6b14ceb7 | 122 | |
f768f60b S |
123 | alias_code(ALIAS,CODE [,CODESET]); |
124 | rename_country_code(CODE,ALIAS [,CODESET]); | |
6b14ceb7 | 125 | |
f768f60b | 126 | and the latter should be used for consistency. |
6b14ceb7 | 127 | |
c69a30ec CBW |
128 | The alias_code function is deprecated and will be removed at some point |
129 | in the future. | |
6b14ceb7 | 130 | |
f768f60b S |
131 | B<Note:> this function was previously called _alias_code, but the |
132 | leading underscore has been dropped. The old name was supported for | |
133 | all 2.X releases, but has been dropped as of 3.00. | |
6b14ceb7 | 134 | |
f768f60b | 135 | =back |
6b14ceb7 | 136 | |
f768f60b | 137 | =head1 SEE ALSO |
6b14ceb7 JH |
138 | |
139 | =over 4 | |
140 | ||
f768f60b | 141 | =item B<Locale::Codes> |
6b14ceb7 | 142 | |
e1137bc7 SB |
143 | The Locale-Codes distribution. |
144 | ||
c69a30ec CBW |
145 | =item B<Locale::Codes::API> |
146 | ||
147 | The list of functions supported by this module. | |
148 | ||
f768f60b | 149 | =item B<Locale::SubCountry> |
6b14ceb7 | 150 | |
f768f60b S |
151 | ISO codes for country sub-divisions (states, counties, provinces, |
152 | etc), as defined in ISO 3166-2. This module is not part of the | |
153 | Locale-Codes distribution, but is available from CPAN in | |
154 | CPAN/modules/by-module/Locale/ | |
6b14ceb7 | 155 | |
f768f60b | 156 | =item B<http://www.iso.org/iso/country_codes> |
6b14ceb7 | 157 | |
f768f60b | 158 | Official home page for the ISO 3166 maintenance agency. |
6b14ceb7 | 159 | |
f768f60b S |
160 | Unfortunately, they do not make the actual ISO available for free, |
161 | so I cannot check the alpha-3 and numerical codes here. | |
6b14ceb7 | 162 | |
f768f60b | 163 | =item B<http://www.iso.org/iso/list-en1-semic-3.txt> |
6b14ceb7 | 164 | |
f768f60b S |
165 | The source of ISO 3166-1 two-letter codes used by this |
166 | module. | |
6b14ceb7 | 167 | |
f768f60b | 168 | =item B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm> |
6b14ceb7 | 169 | |
f768f60b S |
170 | The source of the official ISO 3166-1 three-letter codes and |
171 | three-digit codes. | |
917211f5 | 172 | |
f768f60b S |
173 | For some reason, this table is incomplete! Several countries are |
174 | missing from it, and I cannot find them anywhere on the UN site. I | |
175 | get as much of the data from here as I can. | |
917211f5 | 176 | |
f768f60b | 177 | =item B<http://earth-info.nga.mil/gns/html/digraphs.htm> |
6b14ceb7 | 178 | |
f768f60b | 179 | The official list of the FIPS 10 codes. |
6b14ceb7 | 180 | |
f768f60b | 181 | =item B<http://www.iana.org/domains/> |
6b14ceb7 | 182 | |
f768f60b | 183 | Official source of the top-level domain names. |
6b14ceb7 | 184 | |
f768f60b | 185 | =item B<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html> |
6b14ceb7 | 186 | |
4345d05b CBW |
187 | The World Factbook maintained by the CIA is a potential source of |
188 | the data. Unfortunately, it adds/preserves non-standard codes, so it is no | |
189 | longer used as a source of data. | |
6b14ceb7 | 190 | |
f768f60b | 191 | =item B<http://www.statoids.com/wab.html> |
6b14ceb7 | 192 | |
f768f60b S |
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 JH |
196 | |
197 | =back | |
198 | ||
6b14ceb7 JH |
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 S |
207 | Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). |
208 | Copyright (c) 2001-2010 Neil Bowers | |
4764fecd | 209 | Copyright (c) 2010-2012 Sullivan Beck |
6b14ceb7 JH |
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 |