1Locale::SubCountry(3) User Contributed Perl DocumentationLocale::SubCountry(3)
2
3
4

NAME

6       Locale::SubCountry - Convert state, province, county etc. names to/from
7       ISO 3166-2 codes, get all states in a country
8

SYNOPSIS

10           use Locale::SubCountry;
11
12           my $fr = Locale::SubCountry->new('France');
13           if ( not $fr )
14           {
15               die "Invalid country or code: France\n";
16           }
17           else
18           {
19               print($fr->country,"\n");        # France
20               print($fr->country_code,"\n");   # FR
21               print($fr->country_number,"\n"); # 250
22
23               if (  $fr->has_sub_countries )
24               {
25                   print($fr->code('Hautes-Alpes '),"\n");       # 05
26                   print($fr->full_name('03'),"\n");             # Allier
27                   my $upper_case = 1;
28                   print($fr->full_name('02',$upper_case),"\n"); # AINSE
29                   print($fr->level('02'),"\n");                 # Metropolitan department
30                   print($fr->level('A'),"\n");                  # Metropolitan region
31                   print($fr->level('BL'),"\n");                 # Overseas territorial collectivity
32                   print($fr->levels,"\n");                      # Metropolitan region => 22, Metropolitan department => 96 ...
33
34                   my @fr_names  = $fr->all_full_names;    # Ain, Ainse, Allier...
35                   my @fr_codes   = $fr->all_codes;        # 01, 02, 03 ...
36                   my %fr_names_keyed_by_code  = $fr->code_full_name_hash;  # 01 => Ain...
37                   my %fr_codes_keyed_by_name  = $fr->full_name_code_hash;  # Ain => 01 ...
38
39                   foreach my $code ( sort keys %fr_names_keyed_by_code )
40                   {
41                      printf("%-3s : %s\n",$code,$fr_names_keyed_by_code{$code});
42                   }
43               }
44           }
45
46           # Methods for fetching all country codes and names in the world
47
48           my $world = Locale::SubCountry::World->new();
49           my @all_countries     = $world->all_full_names;
50           my @all_country_codes = $world->all_codes;
51
52           my %all_countries_keyed_by_name = $world->full_name_code_hash;
53           my %all_country_keyed_by_code   = $world->code_full_name_hash;
54

DESCRIPTION

56       This module allows you to convert the full name for a country's
57       administrative region to the code commonly used for postal addressing.
58       The reverse look up can also be done.
59
60       Lists of sub country codes are useful for web applications that require
61       a valid state, county etc to be entered as part of a users location.
62
63       Sub countries are termed as states in the US and Australia, provinces
64       in Canada and counties in the UK and Ireland. Other terms include
65       region, department, city and territory. Countries such as France have
66       several levels of sub countries, such as Metropolitan department,
67       Metropolitan region etc.
68
69       Names and ISO 3166-2 codes for all sub countries in a country can be
70       returned as either a hash or an array.
71
72       Names and ISO 3166-1 codes for all countries in the world can be
73       returned as either a hash or an array. This in turn can be used to
74       fetch every sub country from every country (see examples/demo.pl).
75
76       Sub country codes are defined in "ISO 3166-2, Codes for the
77       representation of names of countries and their subdivisions".
78

METHODS

80       Note that the following methods duplicate some of the functionality of
81       the Locale::Country module (part of the Locale::Codes bundle). They are
82       provided here because you may need to first access the list of
83       countries and ISO 3166-1 codes, before fetching their sub country data.
84       If you only need access to country data, then Locale::Country should be
85       used.
86
87       Note also the following method names are also used for sub country
88       objects.  (interface polymorphism for the technically minded). To avoid
89       confusion, make sure that your chosen method is acting on the correct
90       type of object.
91
92           all_codes
93           all_full_names
94           code_full_name_hash
95           full_name_code_hash
96
97   Locale::SubCountry::World->new()
98       The "new" method creates an instance of a world country object. This
99       must be called before any of the following methods are invoked. The
100       method takes no arguments.
101
102   full_name_code_hash (for world objects)
103       Given a world object, returns a hash of full name/code pairs for every
104       country, keyed by country name.
105
106   code_full_name_hash  for world objects)
107       Given a world object, returns a hash of full name/code pairs for every
108       country, keyed by country code.
109
110   all_full_names (for world objects)
111       Given a world object, returns an array of all country full names,
112       sorted alphabetically.
113
114   all_codes (for world objects)
115       Given a world object, returns an array of all country ISO 3166-1 codes,
116       sorted alphabetically.
117
118   Locale::SubCountry->new()
119       The "new" method creates an instance of a sub country object. This must
120       be called before any of the following methods are invoked. The method
121       takes a single argument, the name of the country that contains the sub
122       country that you want to work with. It may be specified either by the
123       ISO 3166-1 alpha-2  code or the full name. For example:
124
125           AF - Afghanistan
126           AL - Albania
127           DZ - Algeria
128           AO - Angola
129           AR - Argentina
130           AM - Armenia
131           AU - Australia
132           AT - Austria
133
134       If the code is specified, such as 'AU'  the format may be in capitals
135       or lower case If the full name is specified, such as 'Australia', the
136       format must be in title case If a country name or code is specified
137       that the module doesn't recognised, it will issue a warning.
138
139   country
140       Returns the current country name of a sub country object. The format is
141       in title case, such as 'United Kingdom'
142
143   country_code
144       Given a sub country object, returns the alpha-2 ISO 3166-1 code of the
145       country, such as 'GB'
146
147   code
148       Given a sub country object, the "code" method takes the full name of a
149       sub country and returns the sub country's alpha-2 ISO 3166-2 code. The
150       full name can appear in mixed case. All white space and non alphabetic
151       characters are ignored, except the single space used to separate sub
152       country names such as "New South Wales".  The code is returned as a
153       capitalised string, or "unknown" if no match is found.
154
155   full_name
156       Given a sub country object, the "full_name" method takes the alpha-2
157       ISO 3166-2 code of a sub country and returns the sub country's full
158       name. The code can appear in mixed case. All white space and non
159       alphabetic characters are ignored. The full name is returned as a title
160       cased string, such as "South Australia".
161
162       If an optional argument is supplied and set to a true value, the full
163       name is returned as an upper cased string.
164
165   level
166       Given a sub country object, the "level" method takes the alpha-2 ISO
167       3166-2 code of a sub country and returns the sub country's level .
168       Examples are city, province,state and district, and usually relates to
169       the a regions size.  The level is returned as a  string, or "unknown"
170       if no match is found.
171
172   has_sub_countries
173       Given a sub country object, the "has_sub_countries" method returns 1 if
174       the current country has sub countries, or 0 if it does not. Some small
175       countries such as New Caledonia" do not have sub countries.
176
177   full_name_code_hash  (for sub country objects)
178       Given a sub country object, returns a hash of all full name/code pairs,
179       keyed by sub country name. If the country has no sub countries, returns
180       undef.
181
182   code_full_name_hash  (for sub country objects)
183       Given a sub country object, returns a hash of all code/full name pairs,
184       keyed by sub country code. If the country has no sub countries, returns
185       undef.
186
187   all_full_names  (for sub country objects)
188       Given a sub country object, returns an array of all sub country full
189       names, sorted alphabetically. If the country has no sub countries,
190       returns undef.
191
192   all_codes  (for sub country objects)
193       Given a sub country object, returns an array of all sub country alpha-2
194       ISO 3166-2 codes.  If the country has no sub countries, returns undef.
195

SEE ALSO

197       All codes have been downloaded from the latest version of the Debian
198       Salsa project <https://salsa.debian.org/iso-codes-team/iso-codes/> and
199       then files iso_3166-1.json, iso_3166-2.json
200
201       Locale::Country,Lingua::EN::AddressParse,
202       Geo::StreetAddress::US,Geo::PostalAddress,Geo::IP
203       WWW::Scraper::Wikipedia::ISO3166 for obtaining ISO 3166-2 data
204
205       ISO 3166-1 Codes for the representation of names of countries and their
206       subdivisions - Part 1: Country codes
207
208       ISO 3166-2 Codes for the representation of names of countries and their
209       subdivisions - Part 2: Country subdivision code
210

LIMITATIONS

212       The ISO 3166-2 standard romanizes the names of provinces and regions in
213       non-latin script areas, such as Russia and South Korea. One
214       Romanisation is given for each province name. For Russia, the BGN
215       (1947) Romanization is used.
216
217       Several sub country names have more than one code, and may not return
218       the correct code for that sub country. These entries are usually
219       duplicated because the name represents two different types of sub
220       country, such as a province and a geographical unit. Examples are:
221
222           AZERBAIJAN : Lankaran; LA (the Municipality), LAN (the Rayon) [see note]
223           AZERBAIJAN : Saki; SA,SAK [see note]
224           AZERBAIJAN : Susa; SS,SUS
225           AZERBAIJAN : Yevlax; YE,YEV
226           LAOS       : Vientiane VI the Vientiane, VT the Prefecture
227           MOZAMBIQUE : Maputo; MPM (City),L (Province)
228
229       Note: these names are spelt with  diacrtic characters (such as two dots
230       above some of the 'a' characters). This causes utf8 errors on some
231       versions of Perl, so they are omitted here. See the
232       Locale::SubCountry::Codes module for correct spelling
233

AUTHOR

235       Locale::SubCountry was written by Kim Ryan <kimryan at cpan dot org>.
236
238       This software is Copyright (c) 2018 by Kim Ryan.
239
240       This library is free software; you can redistribute it and/or modify it
241       under the same terms as Perl itself.
242

CREDITS

244       Ron Savage for many corrections to the data
245
246       Terrence Brannon produced Locale::US, which was the starting point for
247       this module.
248
250       Copyright (c) 2019 Kim Ryan. All rights reserved.
251
252       This library is free software; you can redistribute it and/or modify it
253       under the same terms as Perl itself.
254
255
256
257perl v5.38.0                      2023-07-20             Locale::SubCountry(3)
Impressum