1Locale::SubCountry(3) User Contributed Perl DocumentationLocale::SubCountry(3)
2
6 Locale::SubCountry - Convert state, province, county etc. names to/from
7 ISO 3166-2 codes, get all states in a country
8
10 use Locale::SubCountry;
11 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 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 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 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 # Methods for fetching all country codes and names in the world
47 my $world = Locale::SubCountry::World->new();
49 my @all_countries = $world->all_full_names;
50 my @all_country_codes = $world->all_codes;
51 my %all_countries_keyed_by_name = $world->full_name_code_hash;
53 my %all_country_keyed_by_code = $world->code_full_name_hash;
54
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 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 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 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 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 Sub country codes are defined in "ISO 3166-2, Codes for the
77 representation of names of countries and their subdivisions".
78
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 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 all_codes
93 all_full_names
94 code_full_name_hash
95 full_name_code_hash
96 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 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 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 all_full_names (for world objects)
111 Given a world object, returns an array of all country full names,
112 sorted alphabetically.
113 all_codes (for world objects)
115 Given a world object, returns an array of all country ISO 3166-1 codes,
116 sorted alphabetically.
117 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 AF - Afghanistan
126 AL - Albania
127 DZ - Algeria
128 AO - Angola
129 AR - Argentina
130 AM - Armenia
131 AU - Australia
132 AT - Austria
133 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 country
140 Returns the current country name of a sub country object. The format is
141 in title case, such as 'United Kingdom'
142 country_code
144 Given a sub country object, returns the alpha-2 ISO 3166-1 code of the
145 country, such as 'GB'
146 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 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 If an optional argument is supplied and set to a true value, the full
163 name is returned as an upper cased string.
164 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 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 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 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 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 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
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 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 ISO 3166-1 Codes for the representation of names of countries and their
206 subdivisions - Part 1: Country codes
207 ISO 3166-2 Codes for the representation of names of countries and their
209 subdivisions - Part 2: Country subdivision code
210
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 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 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 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
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 This library is free software; you can redistribute it and/or modify it
241 under the same terms as Perl itself.
242
244 Ron Savage for many corrections to the data
245 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 This library is free software; you can redistribute it and/or modify it
253 under the same terms as Perl itself.
254perl v5.38.0 2023-07-20 Locale::SubCountry(3)