NAME
Locale::SubCountry - convert state, province, county etc. names to/from code
SYNOPSIS
use Locale::SubCountry;
$UK_counties = new Locale::SubCountry('UK');
print($UK_counties->full_name('DUMGAL')); # Dumfries & Galloway
$country = 'AUSTRALIA';
@all_countries = &all_countries;
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->sub_country_type; # State
%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 conversion can also be done.
Sub countries are termed as states in the US and Australia, provinces in Canada and counties in the UK.
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. These are currently:
AFGHANISTAN
ALGERIA
ANGOLA
ARGENTENIA
ARMENIA
AUSTRALIA
AUSTRIA
AZERBAIJAN
BAHAMAS
BAHRAIN
BANGLADESH
BELARUS
BELGIUM
BELIZE
BENIN
BHUTAN
BOLIVIA
BOSNIA-HERZEGOVINA
BOTSWANA
BRAZIL
BRUNEI DARUSSALAM
BULGARIA
BURKINA FASO
CAMBODIA
CAMEROON
CANADA
CAPE VERDE
CENTRAL AFRICAN REPUBLIC
CHAD
CHILE
CHINA
COLOMBIA
COMORROS
CONGO
COSTA RICA
CROATIA
CUBA
CYPRUS
CZECH REPUBLIC
DEMOCRATIC REPUBLIC OF CONGO
DENMARK
DJIBOUTI
DOMINICAN REPUBLIC
ECUADOR
EGYPT
EL SALVADOR
EQUATORIAL GUINEA
ERITREA
ESTONIA
ETHIOPIA
FEDERATED STATES OF MICRONESIA
FIGI
FRANCE
GABON
GAMBIA
GEORGIA
GERMANY
GHANA
GREECE
GUATEMALA
GUINEA
GUINEA BISSAU
GUYANA
HAITI
HONDURAS
HUNGARY
ICELAND
INDIA
INDONESIA
IRAN
IRAQ
IRELAND
ITALY
IVORY COAST
JAMAICA
JAPAN
JORDAN
KAZAKHSTAN
KENYA
KIRIBATI
KUWAIT
KYRGYSTAN
LAOS
LATVIA
LEBANON
LESOTHO
LIBERIA
LIBYA
LITHUANIA
MADAGASCAR
MALAWI
MALAYSIA
MALDIVES
MALI
MARSHALL ISLANDS
MAURITANIA
MAURITIUS
MEXICO
MOLDOVA
MONGOLIA
MOROCCO
MOZAMBIQUE
MYANMAR
NAMIBIA
NETHERLANDS
NEW ZEALAND
NICARAGUA
NIGER
NIGERIA
NORTH KOREA
NORWAY
OMAN
PAKISTAN
PANAMA
PAPUA NEW GUINEA
PARAGUAY
PERU
PHILIPPINES
POLAND
PORTUGAL
QATAR
ROMANIA
RUSSIA
RWANDA
SAINT HELENA
SAO TOME
SAUDI ARABIA
SENEGAL
SIERRA LEONE
SLOVAKIA
SLOVENIA
SOLOMON ISLANDS
SOMALIA
SOUTH AFRICA
SOUTH KOREA
SPAIN
SRI LANKA
SUDAN
SURINAME
SWAZILAND
SWEDEN
SWITZERLAND
SYRIA
TAIWAN
TAJIKISTAN
TANZANIA
THAILAND
TOGO
TRINIDAD AND TOBAGO
TUNISIA
TURKEY
TURKMENISTAN
UGANDA
UK
UKRAINE
UNITED ARAB EMIRAYES
UNITED STATES MINOR OUTLYING ISLANDS
URUGUAY
USA
UZBEKISTAN
VANUATU
VENEZUELA
VIETNAM
WALLIS AND FORTUNA
YEMEN
YUGOSLAVIA
ZAMBIA
ZIMBABWEAll 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
sub_country_type
Returns the current sub country type (state, county etc) of the sub country object. Currently only defined for
Australia : State Canada : Province France : Department Germany : Lander Ireland : County UK : County USA : State
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 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_countries
Returns an array of all country names that SubCountry 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.
SEE ALSO
ISO 3166-2:1998, Standard for naming sub country codes 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 2 letters. This works for USA, Canada etc. In Australia 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 an enforce ISO-3166 flag 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 for Italy lists alphabetic codes for provinces and numeric codes for the regions they belong to, both are listed.
The following sub country names have more than one code, and may not return the correct code for that sub country.
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 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.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 335:
Non-ASCII character seen before =encoding in 'Länkäran;'. Assuming CP1252