Locale::Country(3pm)

1Locale::Country(3pm)   Perl Programmers Reference Guide   Locale::Country(3pm)
2
3
4

NAME

6       Locale::Country - ISO codes for country identification (ISO 3166)
7

SYNOPSIS

9           use Locale::Country;
10
11           $country = code2country('jp');        # $country gets 'Japan'
12           $code    = country2code('Norway');    # $code gets 'no'
13
14           @codes   = all_country_codes();
15           @names   = all_country_names();
16
17           # semi-private routines
18           Locale::Country::alias_code('uk' => 'gb');
19           Locale::Country::rename_country('gb' => 'Great Britain');
20

DESCRIPTION

22       The "Locale::Country" module provides access to the ISO codes for
23       identifying countries, as defined in ISO 3166-1.  You can either access
24       the codes via the "conversion routines" (described below), or with the
25       two functions which return lists of all country codes or all country
26       names.
27
28       There are three different code sets you can use for identifying
29       countries:
30
31       alpha-2
32           Two letter codes, such as 'tv' for Tuvalu.  This code set is
33           identified with the symbol "LOCALE_CODE_ALPHA_2".
34
35       alpha-3
36           Three letter codes, such as 'brb' for Barbados.  This code set is
37           identified with the symbol "LOCALE_CODE_ALPHA_3".
38
39       numeric
40           Numeric codes, such as 064 for Bhutan.  This code set is identified
41           with the symbol "LOCALE_CODE_NUMERIC".
42
43       All of the routines take an optional additional argument which
44       specifies the code set to use.  If not specified, it defaults to the
45       two-letter codes.  This is partly for backwards compatibility (previous
46       versions of this module only supported the alpha-2 codes), and partly
47       because they are the most widely used codes.
48
49       The alpha-2 and alpha-3 codes are not case-dependent, so you can use
50       'BO', 'Bo', 'bO' or 'bo' for Bolivia.  When a code is returned by one
51       of the functions in this module, it will always be lower-case.
52
53       As of version 2.00, Locale::Country supports variant names for
54       countries. So, for example, the country code for "United States" is
55       "us", so country2code('United States') returns 'us'.  Now the following
56       will also return 'us':
57
58           country2code('United States of America')
59           country2code('USA')
60

CONVERSION ROUTINES

62       There are three conversion routines: "code2country()",
63       "country2code()", and "country_code2code()".
64
65       code2country( CODE, [ CODESET ] )
66           This function takes a country code and returns a string which
67           contains the name of the country identified.  If the code is not a
68           valid country code, as defined by ISO 3166, then "undef" will be
69           returned:
70
71               $country = code2country('fi');
72
73       country2code( STRING, [ CODESET ] )
74           This function takes a country name and returns the corresponding
75           country code, if such exists.  If the argument could not be
76           identified as a country name, then "undef" will be returned:
77
78               $code = country2code('Norway', LOCALE_CODE_ALPHA_3);
79               # $code will now be 'nor'
80
81           The case of the country name is not important.  See the section
82           "KNOWN BUGS AND LIMITATIONS" below.
83
84       country_code2code( CODE, CODESET, CODESET )
85           This function takes a country code from one code set, and returns
86           the corresponding code from another code set.
87
88               $alpha2 = country_code2code('fin',
89                            LOCALE_CODE_ALPHA_3, LOCALE_CODE_ALPHA_2);
90               # $alpha2 will now be 'fi'
91
92           If the code passed is not a valid country code in the first code
93           set, or if there isn't a code for the corresponding country in the
94           second code set, then "undef" will be returned.
95

QUERY ROUTINES

97       There are two function which can be used to obtain a list of all codes,
98       or all country names:
99
100       "all_country_codes( [ CODESET ] )"
101           Returns a list of all two-letter country codes.  The codes are
102           guaranteed to be all lower-case, and not in any particular order.
103
104       "all_country_names( [ CODESET ] )"
105           Returns a list of all country names for which there is a
106           corresponding country code in the specified code set.  The names
107           are capitalised, and not returned in any particular order.
108
109           Not all countries have alpha-3 and numeric codes - some just have
110           an alpha-2 code, so you'll get a different number of countries
111           depending on which code set you specify.
112

SEMI-PRIVATE ROUTINES

114       Locale::Country provides two semi-private routines for modifying the
115       internal data.  Given their status, they aren't exported by default,
116       and so need to be called by prefixing the function name with the
117       package name.
118
119   alias_code
120       Define a new code as an alias for an existing code:
121
122           Locale::Country::alias_code( ALIAS => CODE [, CODESET ] )
123
124       This feature was added as a mechanism for handling a "uk" code. The ISO
125       standard says that the two-letter code for "United Kingdom" is "gb",
126       whereas domain names are all .uk.
127
128       By default the module does not understand "uk", since it is
129       implementing an ISO standard. If you would like 'uk' to work as the
130       two-letter code for United Kingdom, use the following:
131
132           Locale::Country::alias_code('uk' => 'gb');
133
134       With this code, both "uk" and "gb" are valid codes for United Kingdom,
135       with the reverse lookup returning "uk" rather than the usual "gb".
136
137       Note: this function was previously called _alias_code, but the leading
138       underscore has been dropped.  The old name will be supported for all
139       2.X releases for backwards compatibility.
140
141   rename_country
142       If the official country name just isn't good enough for you, you can
143       rename a country. For example, the official country name for code 'gb'
144       is 'United Kingdom'.  If you want to change that, you might call:
145
146           Locale::Country::rename_country('gb' => 'Great Britain');
147
148       This means that calling code2country('gb') will now return 'Great
149       Britain' instead of 'United Kingdom'.  The original country name is
150       retained as an alias, so for the above example, country2code('United
151       Kingdom') will still return 'gb'.
152

EXAMPLES

154       The following example illustrates use of the "code2country()" function.
155       The user is prompted for a country code, and then told the
156       corresponding country name:
157
158           $| = 1;   # turn off buffering
159
160           print "Enter country code: ";
161           chop($code = <STDIN>);
162           $country = code2country($code, LOCALE_CODE_ALPHA_2);
163           if (defined $country)
164           {
165               print "$code = $country\n";
166           }
167           else
168           {
169               print "'$code' is not a valid country code!\n";
170           }
171

DOMAIN NAMES

173       Most top-level domain names are based on these codes, but there are
174       certain codes which aren't.  If you are using this module to identify
175       country from hostname, your best bet is to preprocess the country code.
176
177       For example, edu, com, gov and friends would map to us; uk would map to
178       gb. Any others?
179

KNOWN BUGS AND LIMITATIONS

181       ·   When using "country2code()", the country name must currently appear
182           exactly as it does in the source of the module. The module now
183           supports a small number of variants.
184
185           Possible extensions to this are: an interface for getting at the
186           list of variant names, and regular expression matches.
187
188       ·   In the current implementation, all data is read in when the module
189           is loaded, and then held in memory.  A lazy implementation would be
190           more memory friendly.
191
192       ·   Support for country names in different languages.
193

AUTHOR

225       Neil Bowers <neil@bowers.com>
226

COPYRIGHT

228       Copyright (C) 2002-2004, Neil Bowers.
229
230       Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
231
232       This module is free software; you can redistribute it and/or modify it
233       under the same terms as Perl itself.
234
235
236
237perl v5.10.1                      2009-02-12              Locale::Country(3pm)