| 1 | =pod |
| 2 | |
| 3 | =head1 NAME |
| 4 | |
| 5 | Locale::Country - standard codes for country identification |
| 6 | |
| 7 | =head1 SYNOPSIS |
| 8 | |
| 9 | use Locale::Country; |
| 10 | |
| 11 | $country = code2country('jp' [,CODESET]); # $country gets 'Japan' |
| 12 | $code = country2code('Norway' [,CODESET]); # $code gets 'no' |
| 13 | |
| 14 | @codes = all_country_codes( [CODESET]); |
| 15 | @names = all_country_names(); |
| 16 | |
| 17 | # semi-private routines |
| 18 | Locale::Country::rename_country('gb' => 'Great Britain'); |
| 19 | |
| 20 | =head1 DESCRIPTION |
| 21 | |
| 22 | This module provides access to several code sets |
| 23 | that can be used for identifying countries, such as those defined in |
| 24 | ISO 3166-1. |
| 25 | |
| 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. |
| 29 | |
| 30 | =head1 SUPPORTED CODE SETS |
| 31 | |
| 32 | There are several different code sets you can use for identifying |
| 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: |
| 42 | |
| 43 | =over 4 |
| 44 | |
| 45 | =item B<alpha-2, LOCALE_CODE_ALPHA_2> |
| 46 | |
| 47 | This is the set of two-letter (lowercase) codes from ISO 3166-1, such |
| 48 | as 'tv' for Tuvalu. |
| 49 | |
| 50 | This is the default code set. |
| 51 | |
| 52 | =item B<alpha-3, LOCALE_CODE_ALPHA_3> |
| 53 | |
| 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. |
| 57 | |
| 58 | =item B<numeric, LOCALE_CODE_NUMERIC> |
| 59 | |
| 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. |
| 63 | |
| 64 | If a 2-digit code is entered, it is converted to 3 digits by prepending |
| 65 | a 0. |
| 66 | |
| 67 | =item B<dom, LOCALE_CODE_DOM> |
| 68 | |
| 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. |
| 72 | |
| 73 | =back |
| 74 | |
| 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 | |
| 78 | =head1 ROUTINES |
| 79 | |
| 80 | =over 4 |
| 81 | |
| 82 | =item B<code2country(CODE [,CODESET] [,'retired'])> |
| 83 | |
| 84 | =item B<country2code(NAME [,CODESET] [,'retired'])> |
| 85 | |
| 86 | =item B<country_code2code(CODE ,CODESET ,CODESET2)> |
| 87 | |
| 88 | =item B<all_country_codes([CODESET] [,'retired'])> |
| 89 | |
| 90 | =item B<all_country_names([CODESET] [,'retired'])> |
| 91 | |
| 92 | =item B<Locale::Country::rename_country(CODE ,NEW_NAME [,CODESET])> |
| 93 | |
| 94 | =item B<Locale::Country::add_country(CODE ,NAME [,CODESET])> |
| 95 | |
| 96 | =item B<Locale::Country::delete_country(CODE [,CODESET])> |
| 97 | |
| 98 | =item B<Locale::Country::add_country_alias(NAME ,NEW_NAME)> |
| 99 | |
| 100 | =item B<Locale::Country::delete_country_alias(NAME)> |
| 101 | |
| 102 | =item B<Locale::Country::rename_country_code(CODE ,NEW_CODE [,CODESET])> |
| 103 | |
| 104 | =item B<Locale::Country::add_country_code_alias(CODE ,NEW_CODE [,CODESET])> |
| 105 | |
| 106 | =item B<Locale::Country::delete_country_code_alias(CODE [,CODESET])> |
| 107 | |
| 108 | These routines are all documented in the L<Locale::Codes::API> man page. |
| 109 | |
| 110 | =back |
| 111 | |
| 112 | =head1 SEE ALSO |
| 113 | |
| 114 | =over 4 |
| 115 | |
| 116 | =item L<Locale::Codes> |
| 117 | |
| 118 | The Locale-Codes distribution. |
| 119 | |
| 120 | =item L<Locale::Codes::API> |
| 121 | |
| 122 | The list of functions supported by this module. |
| 123 | |
| 124 | =item L<Locale::SubCountry> |
| 125 | |
| 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/ |
| 130 | |
| 131 | =item L<http://www.iso.org/iso/home/standards/country_codes.htm> |
| 132 | |
| 133 | Official home page for the ISO 3166 maintenance agency. |
| 134 | |
| 135 | =item L<http://www.iso.org/iso/home/standards/country_codes/iso-3166-1_decoding_table.htm> |
| 136 | |
| 137 | The source of ISO 3166-1 two-letter codes used by this |
| 138 | module. |
| 139 | |
| 140 | =item L<http://www.iana.org/domains/root/db/> |
| 141 | |
| 142 | Official source of the top-level domain names. |
| 143 | |
| 144 | =item L<http://unstats.un.org/unsd/methods/m49/m49alpha.htm> |
| 145 | |
| 146 | The source of the official ISO 3166-1 three-letter codes and |
| 147 | three-digit codes. |
| 148 | |
| 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 |
| 151 | no longer use this as a source of data. |
| 152 | |
| 153 | =item L<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html> |
| 154 | |
| 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. |
| 158 | |
| 159 | =item L<http://www.statoids.com/wab.html> |
| 160 | |
| 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. |
| 164 | |
| 165 | =back |
| 166 | |
| 167 | =head1 AUTHOR |
| 168 | |
| 169 | See Locale::Codes for full author history. |
| 170 | |
| 171 | Currently maintained by Sullivan Beck (sbeck@cpan.org). |
| 172 | |
| 173 | =head1 COPYRIGHT |
| 174 | |
| 175 | Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). |
| 176 | Copyright (c) 2001-2010 Neil Bowers |
| 177 | Copyright (c) 2010-2016 Sullivan Beck |
| 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 |