NAME
Locale::SubCountry - convert state, province, county etc. names to/from code
SYNOPSIS
use Locale::SubCountry;
$UK_counties = new Locale::SubCountry('GB');
print($UK_counties->full_name('DUMGAL')); # Dumfries & Galloway
$country = 'AUSTRALIA';
@all_countries = &all_country_names;
if ( grep(/$country/, @all_countries) )
{
$australia = new Locale::SubCountry($country);
}
else
{
die "No data for $country";
}
print($australia->code('New South Wales ')); # NSW
print($australia->full_name('S.A.')); # South Australia
$upper_case = 1;
print($australia->full_name('Qld',$upper_case)); # QUEENSLAND
print $australia->country; # AUSTRALIA
print $australia->country_code; # AU
print $australia->sub_country_type; # State
@all_country_codes = &all_country_codes;
%all_australian_states = $australia->full_name_code_hash;
foreach $abbrev ( sort keys %australian_states )
{
printf("%-3s : %s\n",$abbrev,%all_australian_states{$abbrev});
}
%all_australian_codes = $australia->code_full_name_hash;
@all_australian_states = $australia->all_full_names;
@all_australian_codes = $australia->all_codes;REQUIRES
Perl 5.005 or above
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.
Additionally, names and codes for all sub countries in a country can be returned as either a hash or an array.
METHODS
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 two letter code or the full name. These are currently:
AF - AFGHANISTAN
AL - ALBANIA
DZ - ALGERIA
AO - ANGOLA
AR - ARGENTINA
AM - ARMENIA
AU - AUSTRALIA
AT - AUSTRIA
AZ - AZERBAIJAN
BS - BAHAMAS
BH - BAHRAIN
BD - BANGLADESH
BY - BELARUS
BE - BELGIUM
BZ - BELIZE
BJ - BENIN
BT - BHUTAN
BO - BOLIVIA
BA - BOSNIA AND HERZEGOVINA
BW - BOTSWANA
BR - BRAZIL
BN - BRUNEI DARUSSALAM
BG - BULGARIA
BF - BURKINA FASO
KH - CAMBODIA
CM - CAMEROON
CA - CANADA
CV - CAPE VERDE
CF - CENTRAL AFRICAN REPUBLIC
TD - CHAD
CL - CHILE
CN - CHINA
CO - COLOMBIA
KM - COMOROS
CG - CONGO
CR - COSTA RICA
CI - CÔTE D'IVOIRE
HR - CROATIA
CU - CUBA
CY - CYPRUS
CX - CZECH REPUBLIC
CO - CONGO, THE DEMOCRATIC REPUBLIC OF THE CONGO
DK - DENMARK
DJ - DJIBOUTI
DO - DOMINICAN REPUBLIC
EC - ECUADOR
EG - EGYPT
SV - EL SALVADOR
QQ - EQUATORIAL GUINEA
ER - ERITREA
EE - ESTONIA
ET - ETHIOPIA
FJ - FIJI
FR - FRANCE
GA - GABON
GM - GAMBIA
GE - GEORGIA
DE - GERMANY
GH - GHANA
GR - GREECE
GT - GUATEMALA
GN - GUINEA
GW - GUINEA BISSAU
GY - GUYANA
HT - HAITI
HN - HONDURAS
HU - HUNGARY
IE - ICELAND
IN - INDIA
ID - INDONESIA
IL - ISRAEL
IN - IRAN (ISLAMIC REPUBLIC OF)
IQ - IRAQ
IE - IRELAND
IT - ITALY
JM - JAMAICA
JP - JAPAN
JO - JORDAN
KZ - KAZAKHSTAN
KE - KENYA
KI - KIRIBATI
KP - KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF
KR - KOREA, REPUBLIC OF
KW - KUWAIT
KG - KYRGYZSTAN
LA - LAO PEOPLE'S DEMOCRATIC REPUBLIC
LV - LATVIA
LB - LEBANON
LS - LESOTHO
LR - LIBERIA
LY - LIBYAN ARAB JAMAHIRIYA
LT - LITHUANIA
MG - MADAGASCAR
MW - MALAWI
MY - MALAYSIA
MV - MALDIVES
ML - MALI
MH - MARSHALL ISLANDS
MR - MAURITANIA
MU - MAURITIUS
MX - MEXICO
FM - MICRONESIA (FEDERATED STATES OF)
MD - MOLDOVA, REPUPLIC OF
MN - MONGOLIA
MA - MOROCCO
MZ - MOZAMBIQUE
MM - MYANMAR
NA - NAMIBIA
NL - NETHERLANDS
NZ - NEW ZEALAND
NI - NICARAGUA
NE - NIGER
NG - NIGERIA
NO - NORWAY
OM - OMAN
PK - PAKISTAN
PA - PANAMA
PG - PAPUA NEW GUINEA
PY - PARAGUAY
PE - PERU
PH - PHILIPPINES
PL - POLAND
PT - PORTUGAL
QA - QATAR
RO - ROMANIA
RU - RUSSIA
RW - RWANDA
ST - SAO TOME AND PRINCIPE
SA - SAUDI ARABIA
SN - SENEGAL
SL - SIERRA LEONE
SK - SLOVAKIA
SI - SLOVENIA
SB - SOLOMON ISLANDS
SO - SOMALIA
ZA - SOUTH AFRICA
ES - SPAIN
LK - SRI LANKA
SH - ST HELENA
SD - SUDAN
SR - SURINAME
SZ - SWAZILAND
SE - SWEDEN
CH - SWITZERLAND
SY - SYRIAN ARAB REPUBLIC
TW - TAIWAN, PROVINCE OF CHINA
TJ - TAJIKISTAN
TZ - TANZANIA, UNITED REPUBLIC OF
TH - THAILAND
TG - TOGO
TT - TRINIDAD AND TOBAGO
TN - TUNISIA
TR - TURKEY
TM - TURKMENISTAN
UG - UGANDA
UA - UKRAINE
AE - UNITED ARAB EMIRATES
GB - UNITED KINGDOM
US - UNITED STATES
UM - UNITED STATES MINOR OUTLYING ISLANDS
UY - URUGUAY
UZ - UZBEKISTAN
VU - VANUATU
VE - VENEZUELA
VN - VIET NAM
WF - WALLIS AND FUTUNA ISLANDS
YE - YEMEN
YU - YUGOSLAVIA
ZM - ZAMBIA
ZW - ZIMBABWE
All forms of upper/lower case are acceptable in the country's spelling. If a country name is supplied that the module doesn't recognise, it will die.
country
Returns the current country of the sub country object
country_code
Returns the two letter current country of the sub country object
sub_country_type
Returns the current sub country type (state, county etc) for the sub country object, or 'unknown' if a value is not defined.
code
The code method takes the full name of a sub country in the currently assigned country and returns the sub country's 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
The full_name method takes the code of a sub country in the currently assigned 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.
full_name_code_hash
Returns a hash of name/code pairs for the currently assigned country, keyed by sub country name.
code_full_name_hash
Returns a hash of code/name pairs for the currently assigned country, keyed by sub country code.
all_full_names
Returns an array of sub country names for the currently assigned country, sorted alphabetically.
all_codes
Returns an array of sub country codes for the currently assigned country, sorted alphabetically.
all_country_names
Returns an array of all country names that this module can do lookups for, sorted alphabetically. This is implemented as a conventional subroutine rather than a method. This allows us to check if lookups can be done for a given country before actually creating the lookup object.
all_country_codes
Returns an array of all country 2 letter codes that this module can do lookups for, sorted alphabetically. This is implemented as a conventional subroutine rather than a method. This allows us to check if lookups can be done for a given country code before actually creating the lookup object.
SEE ALSO
ISO 3166-2:1998, Codes for the representation of names of countries and their subdivisions Also released as AS/NZS 2632.2:1999
Locale::Country Locale::US
LIMITATIONS
If a sub country's full name contains the word 'and', it is represented by an ampersand, as in 'Dumfries & Galloway'.
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, Ireland and the UK, this method of abbreviation is not widely accepted. For example, the ISO code for 'New South Wales' is 'NS', but 'NSW' is the only abbreviation that is actually 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.
The ISO 3166-2 standard will typically list more than one type of sub country for each country. For example, Australia has states and territories, Italy has provinces and regions. Normally I use all the different types of sub country. This module will not tell the type of each individual subcountry. It could be recorded if needed, but would take a lot of effort. Instead, the most common type of sub country is recorded for each country. So for Australia, this would be 'State'.
The following 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 type of sub country, such as a province and a geographical unit
AZERBAIJAN : Länkäran; LA,LAN AZERBAIJAN : Säki; 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
BUGS
COPYRIGHT
Copyright (c) 2000-1 Kim Ryan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html).
AUTHOR
Locale::SubCountry was written by Kim Ryan <kimaryan@ozemail.com.au> in 2000.
CREDITS
Alastair McKinstry provided nearly all the sub country codes and names.
Terrence Brannon produced Locale::US, which was the starting point for this module. Some of the ideas in Geography::States were also used.
Mark Summerfield and Guy Fraser provided the list of UK counties.
Code/Sub country data. Comments (lines starting with #) and blank lines are ignored. Read in at start up by INIT subroutine.
Format is: Country=<COUNTRY NAME> SubCountryType=<Sub Country Type> # optional field, specify state, county etc Code=<COUNTRY CODE> # from ISO 3166-1 format CODE:Full Name CODE:Full Name CODE:Full Name ...
Country=<COUNTRY NAME> ...
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 110:
Non-ASCII character seen before =encoding in 'CÔTE'. Assuming CP1252