1Locale::SubCountry(3) User Contributed Perl DocumentationLocale::SubCountry(3)
2
6 Locale::SubCountry - convert state, province, county etc. names to/from
7 code
8
10 my $country_code = 'GB';
11 my $UK = new Locale::SubCountry($country_code);
12 if ( not $UK )
13 {
14 die "Invalid code $country_code\n";
15 }
16 elsif ( $UK->has_sub_countries )
17 {
18 print($UK->full_name('DGY'),"\n"); # Dumfries and Galloway
19 print($UK->regional_division('DGY'),"\n"); # CT (Scotland)
20 }
21 my $australia = new Locale::SubCountry('AUSTRALIA');
23 print($australia->country,"\n"); # AUSTRALIA
24 print($australia->country_code,"\n"); # AU
25 if ( $australia->has_sub_countries )
27 {
28 print($australia->code('New South Wales '),"\n"); # NSW
29 print($australia->full_name('S.A.'),"\n"); # South Australia
30 my $upper_case = 1;
31 print($australia->full_name('Qld',$upper_case),"\n"); # QUEENSLAND
32 print($australia->category('NSW'),"\n"); # state
33 print($australia->FIPS10_4_code('ACT'),"\n"); # 01
34 print($australia->ISO3166_2_code('02'),"\n"); # NSW
35 my @aus_state_names = $australia->all_full_names;
37 my @aus_code_names = $australia->all_codes;
38 my %aus_states_keyed_by_code = $australia->code_full_name_hash;
39 my %aus_states_keyed_by_name = $australia->full_name_code_hash;
40 foreach my $code ( sort keys %aus_states_keyed_by_code )
42 {
43 printf("%-3s : %s\n",$code,$aus_states_keyed_by_code{$code});
44 }
45 }
46 # Methods for country codes and names
48 my $world = new Locale::SubCountry::World;
50 my @all_countries = $world->all_full_names;
51 my @all_country_codes = $world->all_codes;
52 my %all_countries_keyed_by_name = $world->full_name_code_hash;
54 my %all_country_keyed_by_code = $world->code_full_name_hash;
55
57 This module allows you to convert the full name for a countries admin‐
58 istrative region to the code commonly used for postal addressing. The
59 reverse lookup can also be done. Sub country codes are defined in "ISO
60 3166-2:1998, Codes for the representation of names of countries and
61 their subdivisions".
62 Sub countries are termed as states in the US and Australia, provinces
64 in Canada and counties in the UK and Ireland.
65 Names and ISO 3166-2 codes for all sub countries in a country can be
67 returned as either a hash or an array.
68 Names and ISO 3166-1 codes for all countries in the world can be
70 returned as either a hash or an array.
71 ISO 3166-2 codes can be converted to FIPS 10-4 codes. The reverse
73 lookup can also be done.
74
76 Note that the following methods duplicate some of the functionality of
77 the Locale::Country module (part of the Locale::Codes bundle). They are
78 provided here because you may need to first access the list of avail‐
79 able countries and ISO 3166-1 codes, before fetching their sub country
80 data. If you only need access to country data, then Locale::Country
81 should be used.
82 Note also the following method names are also used for sub country
84 objects. (interface polymorphism for the technically minded). To avoid
85 confusion, make sure that your chosen method is acting on the correct
86 type of object.
87 all_codes
89 all_full_names
90 code_full_name_hash
91 full_name_code_hash
92 new Locale::SubCountry::World
94 The "new" method creates an instance of a world country object. This
96 must be called before any of the following methods are invoked. The
97 method takes no arguments.
98 full_name_code_hash (for world objects)
100 Given a world object, returns a hash of full name/code pairs for every
102 country, keyed by country name.
103 code_full_name_hash for world objects)
105 Given a world object, returns a hash of full name/code pairs for every
107 country, keyed by country code.
108 all_full_names (for world objects)
110 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 IS) 3166-1 codes,
117 sorted alphabetically.
118 new Locale::SubCountry
120 The "new" method creates an instance of a sub country object. This must
122 be called before any of the following methods are invoked. The method
123 takes a single argument, the name of the country that contains the sub
124 country that you want to work with. It may be specified either by the
125 ISO 3166-1 two letter code or the full name. For example:
126 AF - AFGHANISTAN
128 AL - ALBANIA
129 DZ - ALGERIA
130 AO - ANGOLA
131 AR - ARGENTINA
132 AM - ARMENIA
133 AU - AUSTRALIA
134 AT - AUSTRIA
135 All forms of upper/lower case are acceptable in the country's spelling.
137 If a country name is supplied that the module doesn't recognised, it
138 will die.
139 country
141 Returns the current country of a sub country object
143 country_code
145 Given a sub country object, returns the two letter ISO 3166-1 code of
147 the country
148 code
150 Given a sub country object, the "code" method takes the full name of a
152 sub country and returns the sub country's ISO 3166-2 code. The full
153 name can appear in mixed case. All white space and non alphabetic char‐
154 acters are ignored, except the single space used to separate sub coun‐
155 try names such as "New South Wales". The code is returned as a capi‐
156 talised string, or "unknown" if no match is found.
157 full_name
159 Given a sub country object, the "full_name" method takes the ISO 3166-2
161 code of a sub country and returns the sub country's full name. The code
162 can appear in mixed case. All white space and non alphabetic characters
163 are ignored. The full name is returned as a title cased string, such as
164 "South Australia".
165 If an optional argument is supplied and set to a true value, the full
167 name is returned as an upper cased string.
168 category
170 Given a sub country object, the "category" method takes the ISO 3166-2
172 code of a sub country and returns the sub country's category type.
173 Examples are city, province,state and district. The category is
174 returned as a capitalised string, or "unknown" if no match is found.
175 regional_division
177 Given a sub country object, the "regional_division" method takes the
179 ISO 3166-2 code of a sub country and returns the sub country's region‐
180 ional_division. This is, an alphanumeric code. The regional_division is
181 returned as a capitalised string, or "unknown" if no match is found.
182 has_sub_countries
184 Given a sub country object, the "has_sub_countries" method returns 1 if
186 the current country has sub countries, or 0 if it does not. Some small
187 countires such as Singapore do not have sub countries.
188 FIPS10_4_code
190 Given a sub country object, the "FIPS_10_4_code" method takes the ISO
192 3166-2 code of a sub country and returns the sub country's FIPS 10-4
193 code, or the string 'unknown', if none exists. FIPS is a standard
194 developed by the US government.
195 ISO3166_2_code
197 Given a sub country object, the "ISO3166_2_code" method takes the FIPS
199 10-4 code of a sub country and returns the sub country's ISO 3166-2
200 code, or the string 'unknown', if none exists.
201 full_name_code_hash (for subcountry objects)
203 Given a sub country object, returns a hash of all full name/code pairs,
205 keyed by sub country name. If the country has no sub countries, returns
206 undef.
207 code_full_name_hash (for subcountry objects)
209 Given a sub country object, returns a hash of all code/full name pairs,
211 keyed by sub country code. If the country has no sub countries, returns
212 undef.
213 all_full_names (for subcountry objects)
215 Given a sub country object, returns an array of all sub country full
217 names, sorted alphabetically. If the country has no sub countries,
218 returns undef.
219 all_codes (for subcountry objects)
221 Given a sub country object, returns an array of all sub country ISO
223 3166-2 codes, sorted alphabetically. If the country has no sub coun‐
224 tries, returns undef.
225
227 ISO 3166-1:1997 Codes for the representation of names of countries and
228 their subdivisions - Part 1: Country codes
229 ISO 3166-2:1998 Codes for the representation of names of countries and
231 their subdivisions - Part 2: Country subdivision code Also released as
232 AS/NZS 2632.2:1999
233 Federal Information Processing Standards Publication 10-4 1995 April
235 Specifications for COUNTRIES, DEPENDENCIES, AREAS OF SPECIAL
236 SOVEREIGNTY, AND THEIR PRINCIPAL ADMINISTRATIVE DIVISIONS
237 <http://www.statoids.com/statoids.html>
239 Locale::Country,Lingua::EN::AddressParse, Geo::StreetAd‐
241 dress::USGeo::PostalAddressGeo::IP
242
244 ISO 3166-2:1998 defines all sub country codes as being up to 3 letters
245 and/or numbers. These codes are commonly accepted for countries like
246 the USA and Canada. In Australia this method of abbreviation is not
247 widely accepted. For example, the ISO code for 'New South Wales' is
248 'NS', but 'NSW' is the abbreviation that is most commonly used. I could
249 add a flag to enforce ISO-3166-2 codes if needed.
250 The ISO 3166-2 standard romanizes the names of provinces and regions in
252 non-latin script areas, such as Russia and South Korea. One Romanisa‐
253 tion is given for each province name. For Russia, the BGN (1947) Roman‐
254 ization is used.
255 Several sub country names have more than one code, and may not return
257 the correct code for that sub country. These entries are usually dupli‐
258 cated because the name represents two different types of sub country,
259 such as a province and a geographical unit. Examples are:
260 AZERBAIJAN : Länkäran; LA (the City), LAN (the Rayon)
262 AZERBAIJAN : Säki; SA,SAK
263 AZERBAIJAN : Susa; SS,SUS
264 AZERBAIJAN : Yevlax; YE,YEV
265 INDONESIA : Kalimantan Timur; KI,KT
266 LAOS : Vientiane VI,VT
267 MOLDOVA : Hahul; CA,CHL
268 MOLDOVA : Bubasari; DU,DBI
269 MOLDOVA : Hrhei; OR,OHI
270 MOLDOVA : Coroca; SO,SOA
271 MOLDOVA : Gngheni; UN,UGI
272 MOZAMBIQUE : Maputo; MPM,L
273 FIPS codes are not provided for all sub countries.
275
277 None known
278
280 Locale::SubCountry was written by Kim Ryan <kimryan at cpan dot org>.
281
283 Alastair McKinstry provided many of the sub country codes and names.
284 Terrence Brannon produced Locale::US, which was the starting point for
286 this module.
287 Mark Summerfield and Guy Fraser provided the list of UK counties.
289 TJ Mather supplied the FIPS codes and many ammendments to the sub coun‐
291 try data
292
294 Copyright (c) 2006 Kim Ryan. All rights reserved.
295 This library is free software; you can redistribute it and/or modify it
297 under the same terms as Perl itself, either Perl version 5.8.4 or, at
298 your option, any later version of Perl 5 you may have available.
299perl v5.8.8 2006-11-25 Locale::SubCountry(3)