NAME¶
Locale::SubCountry - Convert state, province, county etc. names to/from ISO
3166-2 codes
SYNOPSIS¶
my $country_code = 'GB';
my $UK = new Locale::SubCountry($country_code);
if ( not $UK )
{
die "Invalid code $country_code\n";
}
elsif ( $UK->has_sub_countries )
{
print($UK->full_name('DGY'),"\n"); # Dumfries and Galloway
print($UK->regional_division('DGY'),"\n"); # SCT (Scotland)
}
my $australia = new Locale::SubCountry('Australia');
if ( not $australia )
{
die "Invalid code: Australia\n";
}
else
{
print($australia->country,"\n"); # Australia
print($australia->country_code,"\n"); # AU
if ( $australia->has_sub_countries )
{
print($australia->code('New South Wales '),"\n"); # NSW
print($australia->full_name('S.A.'),"\n"); # South Australia
my $upper_case = 1;
print($australia->full_name('Qld',$upper_case),"\n"); # QUEENSLAND
print($australia->category('NSW'),"\n"); # state
print($australia->FIPS10_4_code('ACT'),"\n"); # 01
print($australia->ISO3166_2_code('02'),"\n"); # NSW
my @aus_state_names = $australia->all_full_names;
my @aus_code_names = $australia->all_codes;
my %aus_states_keyed_by_code = $australia->code_full_name_hash;
my %aus_states_keyed_by_name = $australia->full_name_code_hash;
foreach my $code ( sort keys %aus_states_keyed_by_code )
{
printf("%-3s : %s\n",$code,$aus_states_keyed_by_code{$code});
}
}
}
# Methods for country codes and names
my $world = new Locale::SubCountry::World;
my @all_countries = $world->all_full_names;
my @all_country_codes = $world->all_codes;
my %all_countries_keyed_by_name = $world->full_name_code_hash;
my %all_country_keyed_by_code = $world->code_full_name_hash;
DESCRIPTION¶
This module allows you to convert the full name for a countries administrative
region to the code commonly used for postal addressing. The reverse lookup can
also be done. Sub country codes are defined in "ISO 3166-2:2007, Codes
for the representation of names of countries and their subdivisions".
Sub countries are termed as states in the US and Australia, provinces in Canada
and counties in the UK and Ireland. Other terms include region, department,
city and territory.
Names and ISO 3166-2 codes for all sub countries in a country can be returned as
either a hash or an array.
Names and ISO 3166-1 codes for all countries in the world can be returned as
either a hash or an array.
ISO 3166-2 codes can be converted to FIPS 10-4 codes. The reverse lookup can
also be done.
METHODS¶
Note that the following methods duplicate some of the functionality of the
Locale::Country module (part of the Locale::Codes bundle). They are provided
here because you may need to first access the list of available countries and
ISO 3166-1 codes, before fetching their sub country data. If you only need
access to country data, then Locale::Country should be used.
Note also the following method names are also used for sub country objects.
(interface polymorphism for the technically minded). To avoid confusion, make
sure that your chosen method is acting on the correct type of object.
all_codes
all_full_names
code_full_name_hash
full_name_code_hash
new Locale::SubCountry::World¶
The "new" method creates an instance of a world country object. This
must be called before any of the following methods are invoked. The method
takes no arguments.
full_name_code_hash (for world objects)¶
Given a world object, returns a hash of full name/code pairs for every country,
keyed by country name.
code_full_name_hash for world objects)¶
Given a world object, returns a hash of full name/code pairs for every country,
keyed by country code.
all_full_names (for world objects)¶
Given a world object, returns an array of all country full names, sorted
alphabetically.
all_codes (for world objects)¶
Given a world object, returns an array of all country IS) 3166-1 codes, sorted
alphabetically.
new Locale::SubCountry¶
The "new" method creates an instance of a sub country object. This
must be called before any of the following methods are invoked. The method
takes a single argument, the name of the country that contains the sub country
that you want to work with. It may be specified either by the ISO 3166-1 two
letter code or the full name. For example:
AF - Afghanistan
AL - Albania
DZ - Algeria
AO - Angola
AR - Argentina
AM - Armenia
AU - Australia
AT - Austria
If the code is specified, such as 'AU' the format may be in capitals or lower
case If the full name is specified, such as 'Australia', the format must be in
title case If a country name or code is specified that the module doesn't
recognised, it will issue a warning.
country¶
Returns the current country of a sub country object, the format is title case
country_code¶
Given a sub country object, returns the two letter ISO 3166-1 code of the
country
code¶
Given a sub country object, the "code" method takes the full name of a
sub country and returns the sub country's ISO 3166-2 code. The full name can
appear in mixed case. All white space and non alphabetic characters are
ignored, except the single space used to separate sub country names such as
"New South Wales". The code is returned as a capitalised string, or
"unknown" if no match is found.
full_name¶
Given a sub country object, the "full_name" method takes the ISO
3166-2 code of a sub country and returns the sub country's full name. The code
can appear in mixed case. All white space and non alphabetic characters are
ignored. The full name is returned as a title cased string, such as
"South Australia".
If an optional argument is supplied and set to a true value, the full name is
returned as an upper cased string.
category¶
Given a sub country object, the "category" method takes the ISO 3166-2
code of a sub country and returns the sub country's category type. Examples
are city, province,state and district. The category is returned as a
capitalised string, or "unknown" if no match is found.
regional_division¶
Given a sub country object, the "regional_division" method takes the
ISO 3166-2 code of a sub country and returns the sub country's
regionional_division. This is, an alphanumeric code. The regional_division is
returned as a capitalised string, or "unknown" if no match is found.
has_sub_countries¶
Given a sub country object, the "has_sub_countries" method returns 1
if the current country has sub countries, or 0 if it does not. Some small
countries such as Singapore do not have sub countries.
FIPS10_4_code¶
NOTE: On September 2, 2008, FIPS 10-4 was one of ten standards withdrawn by NIST
as a Federal Information Processing Standard. It may not be supported by this
module in the future.
Given a sub country object, the "FIPS_10_4_code" method takes the ISO
3166-2 code of a sub country and returns the sub country's FIPS 10-4 code, or
the string 'unknown', if none exists. FIPS is a standard developed by the US
government.
ISO3166_2_code¶
Given a sub country object, the "ISO3166_2_code" method takes the FIPS
10-4 code of a sub country and returns the sub country's ISO 3166-2 code, or
the string 'unknown', if none exists.
full_name_code_hash (for subcountry objects)¶
Given a sub country object, returns a hash of all full name/code pairs, keyed by
sub country name. If the country has no sub countries, returns undef.
code_full_name_hash (for subcountry objects)¶
Given a sub country object, returns a hash of all code/full name pairs, keyed by
sub country code. If the country has no sub countries, returns undef.
all_full_names (for subcountry objects)¶
Given a sub country object, returns an array of all sub country full names,
sorted alphabetically. If the country has no sub countries, returns undef.
all_codes (for subcountry objects)¶
Given a sub country object, returns an array of all sub country ISO 3166-2
codes, sorted alphabetically. If the country has no sub countries, returns
undef.
SEE ALSO¶
Locale::Country,Lingua::EN::AddressParse,
Geo::StreetAddress::US,Geo::PostalAddress,Geo::IP
WWW::Scraper::Wikipedia::ISO3166 for obtaining ISO 3166-2 data
ISO 3166-1:2007 Codes for the representation of names of countries and their
subdivisions - Part 1: Country codes
ISO 3166-2:2007 Codes for the representation of names of countries and their
subdivisions - Part 2: Country subdivision code Also released as AS/NZS
2632.2:1999
Federal Information Processing Standards Publication 10-4 1995 April
Specifications for COUNTRIES, DEPENDENCIES, AREAS OF SPECIAL SOVEREIGNTY, AND
THEIR PRINCIPAL ADMINISTRATIVE DIVISIONS
<
http://www.statoids.com/statoids.html> is a good source for sub country
codes plus other statistical data.
LIMITATIONS¶
ISO 3166-2:2007 defines all sub country codes as being up to 3 letters and/or
numbers. These codes are commonly accepted for countries like the USA and
Canada. In Australia this method of abbreviation is not widely accepted. For
example, the ISO code for 'New South Wales' is 'NS', but 'NSW' is the
abbreviation that is most commonly used. I could add a flag to enforce
ISO-3166-2 codes if needed.
The ISO 3166-2 standard romanizes the names of provinces and regions in
non-latin script areas, such as Russia and South Korea. One Romanisation is
given for each province name. For Russia, the BGN (1947) Romanization is used.
Several sub country names have more than one code, and may not return the
correct code for that sub country. These entries are usually duplicated
because the name represents two different types of sub country, such as a
province and a geographical unit. Examples are:
AZERBAIJAN : Lankaran; LA (the City), LAN (the Rayon) [see note]
AZERBAIJAN : Saki; SA,SAK [see note]
AZERBAIJAN : Susa; SS,SUS
AZERBAIJAN : Yevlax; YE,YEV
INDONESIA : Kalimantan Timur; KI,KT
LAOS : Vientiane VI,VT
MOLDOVA : Hahul; CA,CHL
MOLDOVA : Bubasari; DU,DBI
MOLDOVA : Hrhei; OR,OHI
MOLDOVA : Coroca; SO,SOA
MOLDOVA : Gngheni; UN,UGI
MOZAMBIQUE : Maputo; MPM,L
Note: these names are spelt with a diaeresis character (two dots) above some of
the 'a' characters. This causes utf8 errors on some versions of Perl, so they
are omitted here. See the Locale::SubCountry::Data module for correct spelling
FIPS codes are not provided for all sub countries.
AUTHOR¶
Locale::SubCountry was written by Kim Ryan <kimryan at cpan dot org>.
CREDITS¶
Ron Savage for many corrections to the data
Alastair McKinstry provided many of the sub country codes and names.
Terrence Brannon produced Locale::US, which was the starting point for this
module.
Mark Summerfield and Guy Fraser provided the list of UK counties.
TJ Mather supplied the FIPS codes and many ammendments to the sub country data
COPYRIGHT AND LICENSE¶
Copyright (c) 2014 Kim Ryan. All rights reserved.
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.