1N/ALocale::Country - ISO codes for country identification (ISO 3166)
1N/A use Locale::Country;
1N/A $country = code2country('jp'); # $country gets 'Japan'
1N/A $code = country2code('Norway'); # $code gets 'no'
1N/A @codes = all_country_codes();
1N/A @names = all_country_names();
1N/A # semi-private routines
1N/A Locale::Country::alias_code('uk' => 'gb');
1N/A Locale::Country::rename_country('gb' => 'Great Britain');
1N/AThe C<Locale::Country> module provides access to the ISO
1N/Acodes for identifying countries, as defined in ISO 3166-1.
1N/AYou can either access the codes via the L<conversion routines>
1N/A(described below), or with the two functions which return lists
1N/Aof all country codes or all country names.
1N/AThere are three different code sets you can use for identifying
1N/ATwo letter codes, such as 'tv' for Tuvalu.
1N/AThis code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
1N/AThree letter codes, such as 'brb' for Barbados.
1N/AThis code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
1N/ANumeric codes, such as 064 for Bhutan.
1N/AThis code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.
1N/AAll of the routines take an optional additional argument
1N/Awhich specifies the code set to use.
1N/AIf not specified, it defaults to the two-letter codes.
1N/AThis is partly for backwards compatibility (previous versions
1N/Aof this module only supported the alpha-2 codes), and
1N/Apartly because they are the most widely used codes.
1N/AThe alpha-2 and alpha-3 codes are not case-dependent,
1N/Aso you can use 'BO', 'Bo', 'bO' or 'bo' for Bolivia.
1N/AWhen a code is returned by one of the functions in
1N/Athis module, it will always be lower-case.
1N/AAs of version 2.00, Locale::Country supports variant
1N/Anames for countries. So, for example, the country code for "United States"
1N/Ais "us", so country2code('United States') returns 'us'.
1N/ANow the following will also return 'us':
1N/A country2code('United States of America')
1N/A=head1 CONVERSION ROUTINES
1N/AThere are three conversion routines: C<code2country()>, C<country2code()>,
1N/Aand C<country_code2code()>.
1N/A=item code2country( CODE, [ CODESET ] )
1N/AThis function takes a country code and returns a string
1N/Awhich contains the name of the country identified.
1N/AIf the code is not a valid country code, as defined by ISO 3166,
1N/Athen C<undef> will be returned:
1N/A $country = code2country('fi');
1N/A=item country2code( STRING, [ CODESET ] )
1N/AThis function takes a country name and returns the corresponding
1N/Acountry code, if such exists.
1N/AIf the argument could not be identified as a country name,
1N/Athen C<undef> will be returned:
1N/A $code = country2code('Norway', LOCALE_CODE_ALPHA_3);
1N/A # $code will now be 'nor'
1N/AThe case of the country name is not important.
1N/ASee the section L<KNOWN BUGS AND LIMITATIONS> below.
1N/A=item country_code2code( CODE, CODESET, CODESET )
1N/AThis function takes a country code from one code set,
1N/Aand returns the corresponding code from another code set.
1N/A $alpha2 = country_code2code('fin',
1N/A LOCALE_CODE_ALPHA_3, LOCALE_CODE_ALPHA_2);
1N/A # $alpha2 will now be 'fi'
1N/AIf the code passed is not a valid country code in
1N/Athe first code set, or if there isn't a code for the
1N/Acorresponding country in the second code set,
1N/Athen C<undef> will be returned.
1N/A=head1 QUERY ROUTINES
1N/AThere are two function which can be used to obtain a list of all codes,
1N/Aor all country names:
1N/A=item C<all_country_codes( [ CODESET ] )>
1N/AReturns a list of all two-letter country codes.
1N/AThe codes are guaranteed to be all lower-case,
1N/Aand not in any particular order.
1N/A=item C<all_country_names( [ CODESET ] )>
1N/AReturns a list of all country names for which there is a corresponding
1N/Acountry code in the specified code set.
1N/AThe names are capitalised, and not returned in any particular order.
1N/ANot all countries have alpha-3 and numeric codes -
1N/Asome just have an alpha-2 code,
1N/Aso you'll get a different number of countries
1N/Adepending on which code set you specify.
1N/A=head1 SEMI-PRIVATE ROUTINES
1N/ALocale::Country provides two semi-private routines for modifying
1N/AGiven their status, they aren't exported by default,
1N/Aand so need to be called by prefixing the function name with the
1N/ADefine a new code as an alias for an existing code:
1N/A Locale::Country::alias_code( ALIAS => CODE [, CODESET ] )
1N/AThis feature was added as a mechanism for handling
1N/Aa "uk" code. The ISO standard says that the two-letter code for
1N/A"United Kingdom" is "gb", whereas domain names are all .uk.
1N/ABy default the module does not understand "uk", since it is implementing
1N/Aan ISO standard. If you would like 'uk' to work as the two-letter
1N/Acode for United Kingdom, use the following:
1N/A Locale::Country::alias_code('uk' => 'gb');
1N/AWith this code, both "uk" and "gb" are valid codes for United Kingdom,
1N/Awith the reverse lookup returning "uk" rather than the usual "gb".
1N/AB<Note:> this function was previously called _alias_code,
1N/Abut the leading underscore has been dropped.
1N/AThe old name will be supported for all
2.X releases for
1N/Abackwards compatibility.
1N/A=head2 rename_country
1N/AIf the official country name just isn't good enough for you,
1N/Ayou can rename a country. For example, the official country
1N/Aname for code 'gb' is 'United Kingdom'.
1N/AIf you want to change that, you might call:
1N/A Locale::Country::rename_country('gb' => 'Great Britain');
1N/AThis means that calling code2country('gb') will now return
1N/A'Great Britain' instead of 'United Kingdom'.
1N/AThe original country name is retained as an alias,
1N/Aso for the above example, country2code('United Kingdom')
1N/Awill still return 'gb'.
1N/AThe following example illustrates use of the C<code2country()> function.
1N/AThe user is prompted for a country code, and then told the corresponding
1N/A $| = 1; # turn off buffering
1N/A print "Enter country code: ";
1N/A chop($code = <STDIN>);
1N/A $country = code2country($code, LOCALE_CODE_ALPHA_2);
1N/A if (defined $country)
1N/A print "$code = $country\n";
1N/A print "'$code' is not a valid country code!\n";
1N/AMost top-level domain names are based on these codes,
1N/Abut there are certain codes which aren't.
1N/AIf you are using this module to identify country from hostname,
1N/Ayour best bet is to preprocess the country code.
1N/AFor example, B<edu>, B<com>, B<gov> and friends would map to B<us>;
1N/AB<uk> would map to B<gb>. Any others?
1N/A=head1 KNOWN BUGS AND LIMITATIONS
1N/AWhen using C<country2code()>, the country name must currently appear
1N/Aexactly as it does in the source of the module. The module now supports
1N/Aa small number of variants.
1N/APossible extensions to this are: an interface for getting at the
1N/Alist of variant names, and regular expression matches.
1N/AIn the current implementation, all data is read in when the
1N/Amodule is loaded, and then held in memory.
1N/AA lazy implementation would be more memory friendly.
1N/ASupport for country names in different languages.
1N/A=item Locale::Language
1N/AISO two letter codes for identification of language (ISO 639).
1N/AISO codes for identification of scripts (ISO 15924).
1N/A=item Locale::Currency
1N/AISO three letter codes for identification of currencies
1N/Aand funds (ISO 4217).
1N/A=item Locale::SubCountry
1N/AISO codes for country sub-divisions (states, counties, provinces, etc),
1N/Aas defined in ISO 3166-2.
1N/AThis module is not part of the Locale-Codes distribution,
1N/AThe ISO standard which defines these codes.
1N/AOfficial home page for the ISO 3166 maintenance agency.
1N/AAnother useful, but not official, home page.
1N/AAn appendix in the CIA world fact book which lists country codes
1N/Aas defined by ISO 3166, FIPS 10-4, and internet domain names.
1N/ANeil Bowers E<lt>neil@bowers.comE<gt>
1N/ACopyright (C) 2002, Neil Bowers.
1N/ACopyright (c) 1997-2001 Canon Research Centre Europe (CRE).
1N/AThis module is free software; you can redistribute it
and/or 1N/Amodify it under the same terms as Perl itself.