+=pod
=head1 NAME
-Locale::Country - ISO codes for country identification (ISO 3166)
+Locale::Country - standard codes for country identification
=head1 SYNOPSIS
- use Locale::Country;
-
- $country = code2country('jp'); # $country gets 'Japan'
- $code = country2code('Norway'); # $code gets 'no'
-
- @codes = all_country_codes();
- @names = all_country_names();
-
- # semi-private routines
- Locale::Country::alias_code('uk' => 'gb');
- Locale::Country::rename_country('gb' => 'Great Britain');
+ use Locale::Country;
+ $country = code2country('jp' [,CODESET]); # $country gets 'Japan'
+ $code = country2code('Norway' [,CODESET]); # $code gets 'no'
-=head1 DESCRIPTION
-
-The C<Locale::Country> module provides access to the ISO
-codes for identifying countries, as defined in ISO 3166-1.
-You can either access the codes via the L<conversion routines>
-(described below), or with the two functions which return lists
-of all country codes or all country names.
-
-There are three different code sets you can use for identifying
-countries:
-
-=over 4
-
-=item B<alpha-2>
-
-Two letter codes, such as 'tv' for Tuvalu.
-This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
+ @codes = all_country_codes( [CODESET]);
+ @names = all_country_names();
-=item B<alpha-3>
+ # semi-private routines
+ Locale::Country::alias_code('uk' => 'gb');
+ Locale::Country::rename_country('gb' => 'Great Britain');
-Three letter codes, such as 'brb' for Barbados.
-This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
+=head1 DESCRIPTION
-=item B<numeric>
+The C<Locale::Country> module provides access to several code sets
+that can be used for identifying countries, such as those defined in
+ISO 3166-1.
-Numeric codes, such as 064 for Bhutan.
-This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.
+Most of the routines take an optional additional argument which
+specifies the code set to use. If not specified, the default ISO
+3166-1 two-letter codes will be used.
-=back
+=head1 SUPPORTED CODE SETS
-All of the routines take an optional additional argument
-which specifies the code set to use.
-If not specified, it defaults to the two-letter codes.
-This is partly for backwards compatibility (previous versions
-of this module only supported the alpha-2 codes), and
-partly because they are the most widely used codes.
+There are several different code sets you can use for identifying
+countries. The ones currently supported are:
-The alpha-2 and alpha-3 codes are not case-dependent,
-so you can use 'BO', 'Bo', 'bO' or 'bo' for Bolivia.
-When a code is returned by one of the functions in
-this module, it will always be lower-case.
+=over 4
-As of version 2.00, Locale::Country supports variant
-names for countries. So, for example, the country code for "United States"
-is "us", so country2code('United States') returns 'us'.
-Now the following will also return 'us':
+=item B<alpha-2>
- country2code('United States of America')
- country2code('USA')
+This is the set of two-letter (lowercase) codes from ISO 3166-1, such
+as 'tv' for Tuvalu.
+This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
-=head1 CONVERSION ROUTINES
+This is the default code set.
-There are three conversion routines: C<code2country()>, C<country2code()>,
-and C<country_code2code()>.
+=item B<alpha-3>
-=over 4
+This is the set of three-letter (lowercase) codes from ISO 3166-1,
+such as 'brb' for Barbados. These codes are actually defined and
+maintained by the U.N. Statistics division.
-=item code2country( CODE, [ CODESET ] )
+This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
-This function takes a country code and returns a string
-which contains the name of the country identified.
-If the code is not a valid country code, as defined by ISO 3166,
-then C<undef> will be returned:
+=item B<numeric>
- $country = code2country('fi');
+This is the set of three-digit numeric codes from ISO 3166-1, such as
+064 for Bhutan. These codes are actually defined and maintained by the
+U.N. Statistics division.
-=item country2code( STRING, [ CODESET ] )
+If a 2-digit code is entered, it is converted to 3 digits by prepending
+a 0.
-This function takes a country name and returns the corresponding
-country code, if such exists.
-If the argument could not be identified as a country name,
-then C<undef> will be returned:
+This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.
- $code = country2code('Norway', LOCALE_CODE_ALPHA_3);
- # $code will now be 'nor'
+=item B<fips-10>
-The case of the country name is not important.
-See the section L<KNOWN BUGS AND LIMITATIONS> below.
+The FIPS 10 data are two-letter (uppercase) codes assigned by the
+National Geospatial-Intelligence Agency.
-=item country_code2code( CODE, CODESET, CODESET )
+This code set is identified with the symbol C<LOCALE_CODE_FIPS>.
-This function takes a country code from one code set,
-and returns the corresponding code from another code set.
+=item B<dom>
- $alpha2 = country_code2code('fin',
- LOCALE_CODE_ALPHA_3, LOCALE_CODE_ALPHA_2);
- # $alpha2 will now be 'fi'
+The IANA is responsible for assigning two-letter (uppercase) top-level
+domain names to each country.
-If the code passed is not a valid country code in
-the first code set, or if there isn't a code for the
-corresponding country in the second code set,
-then C<undef> will be returned.
+This code set is identified with the symbol C<LOCALE_CODE_DOM>.
=back
-
-=head1 QUERY ROUTINES
-
-There are two function which can be used to obtain a list of all codes,
-or all country names:
+=head1 ROUTINES
=over 4
-=item C<all_country_codes( [ CODESET ] )>
-
-Returns a list of all two-letter country codes.
-The codes are guaranteed to be all lower-case,
-and not in any particular order.
-
-=item C<all_country_names( [ CODESET ] )>
-
-Returns a list of all country names for which there is a corresponding
-country code in the specified code set.
-The names are capitalised, and not returned in any particular order.
-
-Not all countries have alpha-3 and numeric codes -
-some just have an alpha-2 code,
-so you'll get a different number of countries
-depending on which code set you specify.
-
-=back
+=item B<code2country ( CODE [,CODESET] )>
+=item B<country2code ( NAME [,CODESET] )>
-=head1 SEMI-PRIVATE ROUTINES
+=item B<country_code2code ( CODE ,CODESET ,CODESET2 )>
-Locale::Country provides two semi-private routines for modifying
-the internal data.
-Given their status, they aren't exported by default,
-and so need to be called by prefixing the function name with the
-package name.
+=item B<all_country_codes ( [CODESET] )>
-=head2 alias_code
+=item B<all_country_names ( [CODESET] )>
-Define a new code as an alias for an existing code:
+=item B<Locale::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )>
- Locale::Country::alias_code( ALIAS => CODE [, CODESET ] )
+=item B<Locale::Country::add_country ( CODE ,NAME [,CODESET] )>
-This feature was added as a mechanism for handling
-a "uk" code. The ISO standard says that the two-letter code for
-"United Kingdom" is "gb", whereas domain names are all .uk.
+=item B<Locale::Country::delete_country ( CODE [,CODESET] )>
-By default the module does not understand "uk", since it is implementing
-an ISO standard. If you would like 'uk' to work as the two-letter
-code for United Kingdom, use the following:
+=item B<Locale::Country::add_country_alias ( NAME ,NEW_NAME )>
- Locale::Country::alias_code('uk' => 'gb');
+=item B<Locale::Country::delete_country_alias ( NAME )>
-With this code, both "uk" and "gb" are valid codes for United Kingdom,
-with the reverse lookup returning "uk" rather than the usual "gb".
+=item B<Locale::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )>
-B<Note:> this function was previously called _alias_code,
-but the leading underscore has been dropped.
-The old name will be supported for all 2.X releases for
-backwards compatibility.
+=item B<Locale::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-=head2 rename_country
+=item B<Locale::Country::delete_country_code_alias ( CODE [,CODESET] )>
-If the official country name just isn't good enough for you,
-you can rename a country. For example, the official country
-name for code 'gb' is 'United Kingdom'.
-If you want to change that, you might call:
+These routines are all documented in the Locale::Codes man page.
- Locale::Country::rename_country('gb' => 'Great Britain');
+=item B<alias_code ( ALIAS, CODE [,CODESET] )>
-This means that calling code2country('gb') will now return
-'Great Britain' instead of 'United Kingdom'.
-The original country name is retained as an alias,
-so for the above example, country2code('United Kingdom')
-will still return 'gb'.
+Version 2.07 included 2 functions for modifying the internal data:
+rename_country and alias_code. Both of these could be used only to
+modify the internal data for country codes.
+As of 3.10, the internal data for all types of codes can be modified.
-=head1 EXAMPLES
+The alias_code function is preserved for backwards compatibility, but
+the following two are identical:
-The following example illustrates use of the C<code2country()> function.
-The user is prompted for a country code, and then told the corresponding
-country name:
+ alias_code(ALIAS,CODE [,CODESET]);
+ rename_country_code(CODE,ALIAS [,CODESET]);
- $| = 1; # turn off buffering
-
- print "Enter country code: ";
- chop($code = <STDIN>);
- $country = code2country($code, LOCALE_CODE_ALPHA_2);
- if (defined $country)
- {
- print "$code = $country\n";
- }
- else
- {
- print "'$code' is not a valid country code!\n";
- }
+and the latter should be used for consistency.
-=head1 DOMAIN NAMES
+The alias_code function is deprecated (though there is no currently no
+plan to remove it).
-Most top-level domain names are based on these codes,
-but there are certain codes which aren't.
-If you are using this module to identify country from hostname,
-your best bet is to preprocess the country code.
+B<Note:> this function was previously called _alias_code, but the
+leading underscore has been dropped. The old name was supported for
+all 2.X releases, but has been dropped as of 3.00.
-For example, B<edu>, B<com>, B<gov> and friends would map to B<us>;
-B<uk> would map to B<gb>. Any others?
+=back
-=head1 KNOWN BUGS AND LIMITATIONS
+=head1 SEE ALSO
=over 4
-=item *
-
-When using C<country2code()>, the country name must currently appear
-exactly as it does in the source of the module. The module now supports
-a small number of variants.
-
-Possible extensions to this are: an interface for getting at the
-list of variant names, and regular expression matches.
-
-=item *
+=item B<Locale::Codes>
-In the current implementation, all data is read in when the
-module is loaded, and then held in memory.
-A lazy implementation would be more memory friendly.
+=item B<Locale::Constants>
-=item *
+=item B<Locale::SubCountry>
-Support for country names in different languages.
+ISO codes for country sub-divisions (states, counties, provinces,
+etc), as defined in ISO 3166-2. This module is not part of the
+Locale-Codes distribution, but is available from CPAN in
+CPAN/modules/by-module/Locale/
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item Locale::Language
+=item B<http://www.iso.org/iso/country_codes>
-ISO two letter codes for identification of language (ISO 639).
+Official home page for the ISO 3166 maintenance agency.
-=item Locale::Script
+Unfortunately, they do not make the actual ISO available for free,
+so I cannot check the alpha-3 and numerical codes here.
-ISO codes for identification of scripts (ISO 15924).
+=item B<http://www.iso.org/iso/list-en1-semic-3.txt>
-=item Locale::Currency
+The source of ISO 3166-1 two-letter codes used by this
+module.
-ISO three letter codes for identification of currencies
-and funds (ISO 4217).
+=item B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm>
-=item Locale::SubCountry
+The source of the official ISO 3166-1 three-letter codes and
+three-digit codes.
-ISO codes for country sub-divisions (states, counties, provinces, etc),
-as defined in ISO 3166-2.
-This module is not part of the Locale-Codes distribution,
-but is available from CPAN in CPAN/modules/by-module/Locale/
+For some reason, this table is incomplete! Several countries are
+missing from it, and I cannot find them anywhere on the UN site. I
+get as much of the data from here as I can.
-=item ISO 3166-1
+=item B<http://earth-info.nga.mil/gns/html/digraphs.htm>
-The ISO standard which defines these codes.
+The official list of the FIPS 10 codes.
-=item http://www.iso.org/iso/en/prods-services/iso3166ma/index.html
+=item B<http://www.iana.org/domains/>
-Official home page for the ISO 3166 maintenance agency.
+Official source of the top-level domain names.
-=item http://www.egt.ie/standards/iso3166/iso3166-1-en.html
+=item B<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html>
-Another useful, but not official, home page.
+Although not the official source of any of the data, the World
+Factbook maintained by the CIA is a great source of the data,
+especially since I can't get the official data from the ISO. Since
+it's maintained by the CIA, and since it's updated every two weeks, I
+use this as the source for some missing data.
-=item http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html
+=item B<http://www.statoids.com/wab.html>
-An appendix in the CIA world fact book which lists country codes
-as defined by ISO 3166, FIPS 10-4, and internet domain names.
+Another unofficial source of data. Currently, it is not used to get
+data, but the notes and explanatory material were very useful for
+understanding discrepancies between the sources.
=back
-
=head1 AUTHOR
-Neil Bowers E<lt>neil@bowers.comE<gt>
+See Locale::Codes for full author history.
-=head1 COPYRIGHT
+Currently maintained by Sullivan Beck (sbeck@cpan.org).
-Copyright (C) 2002-2004, Neil Bowers.
+=head1 COPYRIGHT
-Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
+ Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
+ Copyright (c) 2001-2010 Neil Bowers
+ Copyright (c) 2010-2010 Sullivan Beck
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=cut
-
projects / p5sagit/p5-mst-13.2.git / blobdiff