diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Locale/Country.pod')
| -rw-r--r-- | Master/tlpkg/tlperl/lib/Locale/Country.pod | 328 |
1 files changed, 119 insertions, 209 deletions
diff --git a/Master/tlpkg/tlperl/lib/Locale/Country.pod b/Master/tlpkg/tlperl/lib/Locale/Country.pod index b13cd22a4a7..509dff846d7 100644 --- a/Master/tlpkg/tlperl/lib/Locale/Country.pod +++ b/Master/tlpkg/tlperl/lib/Locale/Country.pod @@ -1,306 +1,216 @@ +=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 * +=item B<Locale::Codes> -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. +=item B<Locale::Constants> -Possible extensions to this are: an interface for getting at the -list of variant names, and regular expression matches. +The Locale-Codes distribution. -=item * +=item B<Locale::SubCountry> -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. +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/ -=item * - -Support for country names in different languages. - -=back +=item B<http://www.iso.org/iso/country_codes> -=head1 SEE ALSO - -=over 4 - -=item Locale::Language +Official home page for the ISO 3166 maintenance agency. -ISO two letter codes for identification of language (ISO 639). +Unfortunately, they do not make the actual ISO available for free, +so I cannot check the alpha-3 and numerical codes here. -=item Locale::Script +=item B<http://www.iso.org/iso/list-en1-semic-3.txt> -ISO codes for identification of scripts (ISO 15924). +The source of ISO 3166-1 two-letter codes used by this +module. -=item Locale::Currency +=item B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm> -ISO three letter codes for identification of currencies -and funds (ISO 4217). +The source of the official ISO 3166-1 three-letter codes and +three-digit codes. -=item Locale::SubCountry +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. -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/ +=item B<http://earth-info.nga.mil/gns/html/digraphs.htm> -=item ISO 3166-1 +The official list of the FIPS 10 codes. -The ISO standard which defines these codes. +=item B<http://www.iana.org/domains/> -=item http://www.iso.org/iso/en/prods-services/iso3166ma/index.html +Official source of the top-level domain names. -Official home page for the ISO 3166 maintenance agency. +=item B<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html> -=item http://www.egt.ie/standards/iso3166/iso3166-1-en.html +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. -Another useful, but not official, home page. +=item B<http://www.statoids.com/wab.html> -=item http://www.cia.gov/cia/publications/factbook/docs/app-d-1.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-2011 Sullivan Beck This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut - |