Locale::SubCountry(3) User Contributed Perl DocumentationLocale::SubCountry(3)NAMELocale::SubCountry - convert state, province, county etc. names to/from
code
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"); # CT (Scotland)
}
my $australia = new Locale::SubCountry('AUSTRALIA');
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:1998, 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.
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
All forms of upper/lower case are acceptable in the country's spelling.
If a country name is supplied that the module doesn't recognised, it
will die.
country
Returns the current country of a sub country object
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
countires such as Singapore do not have sub countries.
FIPS10_4_code
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
ISO 3166-1:1997 Codes for the representation of names of countries and
their subdivisions - Part 1: Country codes
ISO 3166-2:1998 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>
Locale::Country,Lingua::EN::AddressParse,
Geo::StreetAddress::USGeo::PostalAddressGeo::IP
LIMITATIONS
ISO 3166-2:1998 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 : Laenkaeran; LA (the City), LAN (the Rayon)
AZERBAIJAN : Saeki; SA,SAK
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
FIPS codes are not provided for all sub countries.
BUGS
None known
AUTHORLocale::SubCountry was written by Kim Ryan <kimryan at cpan dot org>.
CREDITS
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) 2008 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, either Perl version 5.8.4 or, at
your option, any later version of Perl 5 you may have available.
perl v5.14.1 2008-04-20 Locale::SubCountry(3)
