bionic (3) Locale::SubCountry.3pm.gz
NAME
Locale::SubCountry - Convert state, province, county etc. names to/from ISO 3166-2 codes, get all states
in a country
SYNOPSIS
use Locale::SubCountry;
my $fr = Locale::SubCountry->new('France');
if ( not $fr )
{
die "Invalid country or code: France\n";
}
else
{
print($fr->country,"\n"); # France
print($fr->country_code,"\n"); # FR
print($fr->country_number,"\n"); # 250
if ( $fr->has_sub_countries )
{
print($fr->code('Hautes-Alpes '),"\n"); # 05
print($fr->full_name('03'),"\n"); # Allier
my $upper_case = 1;
print($fr->full_name('02',$upper_case),"\n"); # AINSE
print($fr->level('02'),"\n"); # Metropolitan department
print($fr->level('A'),"\n"); # Metropolitan region
print($fr->level('BL'),"\n"); # Overseas territorial collectivity
print($fr->levels,"\n"); # Metropolitan region => 22, Metropolitan department => 96 ...
my @fr_names = $fr->all_full_names; # Ain, Ainse, Allier...
my @fr_codes = $fr->all_codes; # 01, 02, 03 ...
my %fr_names_keyed_by_code = $fr->code_full_name_hash; # 01 => Ain...
my %fr_codes_keyed_by_name = $fr->full_name_code_hash; # Ain => 01 ...
foreach my $code ( sort keys %fr_names_keyed_by_code )
{
printf("%-3s : %s\n",$code,$fr_names_keyed_by_code{$code});
}
}
}
# Methods for fetching all country codes and names in the world
my $world = Locale::SubCountry::World->new();
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 country's administrative region to the code
commonly used for postal addressing. The reverse look up can also be done.
Lists of sub country codes are useful for web applications that require a valid state, county etc to be
entered as part of a users location.
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. Countries such as France have
several levels of sub countries, such as Metropolitan department, Metropolitan region etc.
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.
This in turn can be used to fetch every sub country from every country (see examples/demo.pl).
Sub country codes are defined in "ISO 3166-2, Codes for the representation of names of countries and
their subdivisions".
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
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
Locale::SubCountry::World->new()
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 ISO 3166-1 codes, sorted alphabetically.
Locale::SubCountry->new()
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 alpha-2 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 name of a sub country object. The format is in title case, such as 'United
Kingdom'
country_code
Given a sub country object, returns the alpha-2 ISO 3166-1 code of the country, such as 'GB'
code
Given a sub country object, the "code" method takes the full name of a sub country and returns the sub
country's alpha-2 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 alpha-2 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.
level
Given a sub country object, the "level" method takes the alpha-2 ISO 3166-2 code of a sub country and
returns the sub country's level . Examples are city, province,state and district, and usually relates to
the a regions size. The level is returned as a 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 New Caledonia" do not have sub countries.
full_name_code_hash (for sub country 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 sub country 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 sub country 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 sub country objects)
Given a sub country object, returns an array of all sub country alpha-2 ISO 3166-2 codes. If the country
has no sub countries, returns undef.
SEE ALSO
All codes have been downloaded from the latest version of the Alioth project
<https://pkg-isocodes.alioth.debian.org/>
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 Codes for the representation of names of countries and their subdivisions - Part 1: Country
codes
ISO 3166-2 Codes for the representation of names of countries and their subdivisions - Part 2: Country
subdivision code
<http://www.statoids.com/statoids.html> is a good source for sub country codes plus other statistical
data.
LIMITATIONS
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 Municipality), LAN (the Rayon) [see note]
AZERBAIJAN : Saki; SA,SAK [see note]
AZERBAIJAN : Susa; SS,SUS
AZERBAIJAN : Yevlax; YE,YEV
LAOS : Vientiane VI the Vientiane, VT the Prefecture
MOZAMBIQUE : Maputo; MPM (City),L (Province)
Note: these names are spelt with diacrtic characters (such as 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::Codes module for correct spelling
AUTHOR
Locale::SubCountry was written by Kim Ryan <kimryan at cpan dot org>.
COPYRIGHT AND LICENCE
This software is Copyright (c) 2018 by Kim Ryan.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.
CREDITS
Ron Savage for many corrections to the data
Terrence Brannon produced Locale::US, which was the starting point for this module.
COPYRIGHT AND LICENSE
Copyright (c) 2018 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.