1 2=head1 NAME 3 4Locale::Country - ISO codes for country identification (ISO 3166) 5 6=head1 SYNOPSIS 7 8 use Locale::Country; 9 10 $country = code2country('jp'); # $country gets 'Japan' 11 $code = country2code('Norway'); # $code gets 'no' 12 13 @codes = all_country_codes(); 14 @names = all_country_names(); 15 16 # semi-private routines 17 Locale::Country::alias_code('uk' => 'gb'); 18 Locale::Country::rename_country('gb' => 'Great Britain'); 19 20 21=head1 DESCRIPTION 22 23The C<Locale::Country> module provides access to the ISO 24codes for identifying countries, as defined in ISO 3166-1. 25You can either access the codes via the L<conversion routines> 26(described below), or with the two functions which return lists 27of all country codes or all country names. 28 29There are three different code sets you can use for identifying 30countries: 31 32=over 4 33 34=item B<alpha-2> 35 36Two letter codes, such as 'tv' for Tuvalu. 37This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>. 38 39=item B<alpha-3> 40 41Three letter codes, such as 'brb' for Barbados. 42This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>. 43 44=item B<numeric> 45 46Numeric codes, such as 064 for Bhutan. 47This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>. 48 49=back 50 51All of the routines take an optional additional argument 52which specifies the code set to use. 53If not specified, it defaults to the two-letter codes. 54This is partly for backwards compatibility (previous versions 55of this module only supported the alpha-2 codes), and 56partly because they are the most widely used codes. 57 58The alpha-2 and alpha-3 codes are not case-dependent, 59so you can use 'BO', 'Bo', 'bO' or 'bo' for Bolivia. 60When a code is returned by one of the functions in 61this module, it will always be lower-case. 62 63As of version 2.00, Locale::Country supports variant 64names for countries. So, for example, the country code for "United States" 65is "us", so country2code('United States') returns 'us'. 66Now the following will also return 'us': 67 68 country2code('United States of America') 69 country2code('USA') 70 71 72=head1 CONVERSION ROUTINES 73 74There are three conversion routines: C<code2country()>, C<country2code()>, 75and C<country_code2code()>. 76 77=over 4 78 79=item code2country( CODE, [ CODESET ] ) 80 81This function takes a country code and returns a string 82which contains the name of the country identified. 83If the code is not a valid country code, as defined by ISO 3166, 84then C<undef> will be returned: 85 86 $country = code2country('fi'); 87 88=item country2code( STRING, [ CODESET ] ) 89 90This function takes a country name and returns the corresponding 91country code, if such exists. 92If the argument could not be identified as a country name, 93then C<undef> will be returned: 94 95 $code = country2code('Norway', LOCALE_CODE_ALPHA_3); 96 # $code will now be 'nor' 97 98The case of the country name is not important. 99See the section L<KNOWN BUGS AND LIMITATIONS> below. 100 101=item country_code2code( CODE, CODESET, CODESET ) 102 103This function takes a country code from one code set, 104and returns the corresponding code from another code set. 105 106 $alpha2 = country_code2code('fin', 107 LOCALE_CODE_ALPHA_3, LOCALE_CODE_ALPHA_2); 108 # $alpha2 will now be 'fi' 109 110If the code passed is not a valid country code in 111the first code set, or if there isn't a code for the 112corresponding country in the second code set, 113then C<undef> will be returned. 114 115=back 116 117 118=head1 QUERY ROUTINES 119 120There are two function which can be used to obtain a list of all codes, 121or all country names: 122 123=over 4 124 125=item C<all_country_codes( [ CODESET ] )> 126 127Returns a list of all two-letter country codes. 128The codes are guaranteed to be all lower-case, 129and not in any particular order. 130 131=item C<all_country_names( [ CODESET ] )> 132 133Returns a list of all country names for which there is a corresponding 134country code in the specified code set. 135The names are capitalised, and not returned in any particular order. 136 137Not all countries have alpha-3 and numeric codes - 138some just have an alpha-2 code, 139so you'll get a different number of countries 140depending on which code set you specify. 141 142=back 143 144 145=head1 SEMI-PRIVATE ROUTINES 146 147Locale::Country provides two semi-private routines for modifying 148the internal data. 149Given their status, they aren't exported by default, 150and so need to be called by prefixing the function name with the 151package name. 152 153=head2 alias_code 154 155Define a new code as an alias for an existing code: 156 157 Locale::Country::alias_code( ALIAS => CODE [, CODESET ] ) 158 159This feature was added as a mechanism for handling 160a "uk" code. The ISO standard says that the two-letter code for 161"United Kingdom" is "gb", whereas domain names are all .uk. 162 163By default the module does not understand "uk", since it is implementing 164an ISO standard. If you would like 'uk' to work as the two-letter 165code for United Kingdom, use the following: 166 167 Locale::Country::alias_code('uk' => 'gb'); 168 169With this code, both "uk" and "gb" are valid codes for United Kingdom, 170with the reverse lookup returning "uk" rather than the usual "gb". 171 172B<Note:> this function was previously called _alias_code, 173but the leading underscore has been dropped. 174The old name will be supported for all 2.X releases for 175backwards compatibility. 176 177=head2 rename_country 178 179If the official country name just isn't good enough for you, 180you can rename a country. For example, the official country 181name for code 'gb' is 'United Kingdom'. 182If you want to change that, you might call: 183 184 Locale::Country::rename_country('gb' => 'Great Britain'); 185 186This means that calling code2country('gb') will now return 187'Great Britain' instead of 'United Kingdom'. 188The original country name is retained as an alias, 189so for the above example, country2code('United Kingdom') 190will still return 'gb'. 191 192 193=head1 EXAMPLES 194 195The following example illustrates use of the C<code2country()> function. 196The user is prompted for a country code, and then told the corresponding 197country name: 198 199 $| = 1; # turn off buffering 200 201 print "Enter country code: "; 202 chop($code = <STDIN>); 203 $country = code2country($code, LOCALE_CODE_ALPHA_2); 204 if (defined $country) 205 { 206 print "$code = $country\n"; 207 } 208 else 209 { 210 print "'$code' is not a valid country code!\n"; 211 } 212 213=head1 DOMAIN NAMES 214 215Most top-level domain names are based on these codes, 216but there are certain codes which aren't. 217If you are using this module to identify country from hostname, 218your best bet is to preprocess the country code. 219 220For example, B<edu>, B<com>, B<gov> and friends would map to B<us>; 221B<uk> would map to B<gb>. Any others? 222 223=head1 KNOWN BUGS AND LIMITATIONS 224 225=over 4 226 227=item * 228 229When using C<country2code()>, the country name must currently appear 230exactly as it does in the source of the module. The module now supports 231a small number of variants. 232 233Possible extensions to this are: an interface for getting at the 234list of variant names, and regular expression matches. 235 236=item * 237 238In the current implementation, all data is read in when the 239module is loaded, and then held in memory. 240A lazy implementation would be more memory friendly. 241 242=item * 243 244Support for country names in different languages. 245 246=back 247 248=head1 SEE ALSO 249 250=over 4 251 252=item Locale::Language 253 254ISO two letter codes for identification of language (ISO 639). 255 256=item Locale::Script 257 258ISO codes for identification of scripts (ISO 15924). 259 260=item Locale::Currency 261 262ISO three letter codes for identification of currencies 263and funds (ISO 4217). 264 265=item Locale::SubCountry 266 267ISO codes for country sub-divisions (states, counties, provinces, etc), 268as defined in ISO 3166-2. 269This module is not part of the Locale-Codes distribution, 270but is available from CPAN in CPAN/modules/by-module/Locale/ 271 272=item ISO 3166-1 273 274The ISO standard which defines these codes. 275 276=item http://www.iso.org/iso/en/prods-services/iso3166ma/index.html 277 278Official home page for the ISO 3166 maintenance agency. 279 280=item http://www.egt.ie/standards/iso3166/iso3166-1-en.html 281 282Another useful, but not official, home page. 283 284=item http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html 285 286An appendix in the CIA world fact book which lists country codes 287as defined by ISO 3166, FIPS 10-4, and internet domain names. 288 289=back 290 291 292=head1 AUTHOR 293 294Neil Bowers E<lt>neil@bowers.comE<gt> 295 296=head1 COPYRIGHT 297 298Copyright (C) 2002, Neil Bowers. 299 300Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). 301 302This module is free software; you can redistribute it and/or 303modify it under the same terms as Perl itself. 304 305=cut 306 307