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
58 administrative region to the code commonly used for postal addressing.
59 The reverse lookup can also be done. Sub country codes are defined in
60 "ISO 3166-2:1998, Codes for the representation of names of countries
61 and 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
79 available countries and ISO 3166-1 codes, before fetching their sub
80 country data. If you only need access to country data, then
81 Locale::Country 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
95 must be called before any of the following methods are invoked. The
96 method takes no arguments.
97 full_name_code_hash (for world objects)
99 Given a world object, returns a hash of full name/code pairs for every
100 country, keyed by country name.
101 code_full_name_hash for world objects)
103 Given a world object, returns a hash of full name/code pairs for every
104 country, keyed by country code.
105 all_full_names (for world objects)
107 Given a world object, returns an array of all country full names,
108 sorted alphabetically.
109 all_codes (for world objects)
111 Given a world object, returns an array of all country IS) 3166-1 codes,
112 sorted alphabetically.
113 new Locale::SubCountry
115 The "new" method creates an instance of a sub country object. This must
116 be called before any of the following methods are invoked. The method
117 takes a single argument, the name of the country that contains the sub
118 country that you want to work with. It may be specified either by the
119 ISO 3166-1 two letter code or the full name. For example:
120 AF - AFGHANISTAN
122 AL - ALBANIA
123 DZ - ALGERIA
124 AO - ANGOLA
125 AR - ARGENTINA
126 AM - ARMENIA
127 AU - AUSTRALIA
128 AT - AUSTRIA
129 All forms of upper/lower case are acceptable in the country's spelling.
131 If a country name is supplied that the module doesn't recognised, it
132 will die.
133 country
135 Returns the current country of a sub country object
136 country_code
138 Given a sub country object, returns the two letter ISO 3166-1 code of
139 the country
140 code
142 Given a sub country object, the "code" method takes the full name of a
143 sub country and returns the sub country's ISO 3166-2 code. The full
144 name can appear in mixed case. All white space and non alphabetic
145 characters are ignored, except the single space used to separate sub
146 country names such as "New South Wales". The code is returned as a
147 capitalised string, or "unknown" if no match is found.
148 full_name
150 Given a sub country object, the "full_name" method takes the ISO 3166-2
151 code of a sub country and returns the sub country's full name. The code
152 can appear in mixed case. All white space and non alphabetic characters
153 are ignored. The full name is returned as a title cased string, such as
154 "South Australia".
155 If an optional argument is supplied and set to a true value, the full
157 name is returned as an upper cased string.
158 category
160 Given a sub country object, the "category" method takes the ISO 3166-2
161 code of a sub country and returns the sub country's category type.
162 Examples are city, province,state and district. The category is
163 returned as a capitalised string, or "unknown" if no match is found.
164 regional_division
166 Given a sub country object, the "regional_division" method takes the
167 ISO 3166-2 code of a sub country and returns the sub country's
168 regionional_division. This is, an alphanumeric code. The
169 regional_division is returned as a capitalised string, or "unknown" if
170 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 countires such as Singapore do not have sub countries.
176 FIPS10_4_code
178 Given a sub country object, the "FIPS_10_4_code" method takes the ISO
179 3166-2 code of a sub country and returns the sub country's FIPS 10-4
180 code, or the string 'unknown', if none exists. FIPS is a standard
181 developed by the US government.
182 ISO3166_2_code
184 Given a sub country object, the "ISO3166_2_code" method takes the FIPS
185 10-4 code of a sub country and returns the sub country's ISO 3166-2
186 code, or the string 'unknown', if none exists.
187 full_name_code_hash (for subcountry objects)
189 Given a sub country object, returns a hash of all full name/code pairs,
190 keyed by sub country name. If the country has no sub countries, returns
191 undef.
192 code_full_name_hash (for subcountry objects)
194 Given a sub country object, returns a hash of all code/full name pairs,
195 keyed by sub country code. If the country has no sub countries, returns
196 undef.
197 all_full_names (for subcountry objects)
199 Given a sub country object, returns an array of all sub country full
200 names, sorted alphabetically. If the country has no sub countries,
201 returns undef.
202 all_codes (for subcountry objects)
204 Given a sub country object, returns an array of all sub country ISO
205 3166-2 codes, sorted alphabetically. If the country has no sub
206 countries, returns undef.
207
209 ISO 3166-1:1997 Codes for the representation of names of countries and
210 their subdivisions - Part 1: Country codes
211 ISO 3166-2:1998 Codes for the representation of names of countries and
213 their subdivisions - Part 2: Country subdivision code Also released as
214 AS/NZS 2632.2:1999
215 Federal Information Processing Standards Publication 10-4 1995 April
217 Specifications for COUNTRIES, DEPENDENCIES, AREAS OF SPECIAL
218 SOVEREIGNTY, AND THEIR PRINCIPAL ADMINISTRATIVE DIVISIONS
219 <http://www.statoids.com/statoids.html>
221 Locale::Country,Lingua::EN::AddressParse,
223 Geo::StreetAddress::USGeo::PostalAddressGeo::IP
224
226 ISO 3166-2:1998 defines all sub country codes as being up to 3 letters
227 and/or numbers. These codes are commonly accepted for countries like
228 the USA and Canada. In Australia this method of abbreviation is not
229 widely accepted. For example, the ISO code for 'New South Wales' is
230 'NS', but 'NSW' is the abbreviation that is most commonly used. I could
231 add a flag to enforce ISO-3166-2 codes if needed.
232 The ISO 3166-2 standard romanizes the names of provinces and regions in
234 non-latin script areas, such as Russia and South Korea. One
235 Romanisation is given for each province name. For Russia, the BGN
236 (1947) Romanization is used.
237 Several sub country names have more than one code, and may not return
239 the correct code for that sub country. These entries are usually
240 duplicated because the name represents two different types of sub
241 country, such as a province and a geographical unit. Examples are:
242 AZERBAIJAN : Laenkaeran; LA (the City), LAN (the Rayon)
244 AZERBAIJAN : Saeki; SA,SAK
245 AZERBAIJAN : Susa; SS,SUS
246 AZERBAIJAN : Yevlax; YE,YEV
247 INDONESIA : Kalimantan Timur; KI,KT
248 LAOS : Vientiane VI,VT
249 MOLDOVA : Hahul; CA,CHL
250 MOLDOVA : Bubasari; DU,DBI
251 MOLDOVA : Hrhei; OR,OHI
252 MOLDOVA : Coroca; SO,SOA
253 MOLDOVA : Gngheni; UN,UGI
254 MOZAMBIQUE : Maputo; MPM,L
255 FIPS codes are not provided for all sub countries.
257
259 None known
260
262 Locale::SubCountry was written by Kim Ryan <kimryan at cpan dot org>.
263
265 Alastair McKinstry provided many of the sub country codes and names.
266 Terrence Brannon produced Locale::US, which was the starting point for
268 this module.
269 Mark Summerfield and Guy Fraser provided the list of UK counties.
271 TJ Mather supplied the FIPS codes and many ammendments to the sub
273 country data
274
276 Copyright (c) 2008 Kim Ryan. All rights reserved.
277 This library is free software; you can redistribute it and/or modify it
279 under the same terms as Perl itself, either Perl version 5.8.4 or, at
280 your option, any later version of Perl 5 you may have available.
281perl v5.12.0 2008-04-20 Locale::SubCountry(3)