Locale::SubCountry - convert state, province, county etc. names to/from code
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;
Perl 5.005 or above
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 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.
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 two letter code or the full name. These are currently:
new
AF - AFGHANISTAN 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 CO - CONGO CR - COSTA RICA CI - COTE D'IVOIRE HR - CROATIA CU - CUBA CY - CYPRUS CX - CZECH REPUBLIC CO - DEMOCRATIC REPUBLIC OF 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 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.
Returns the current country of the sub country object
Returns the two lwttwr current country of the sub country object
Returns the current sub country type (state, county etc) for the sub country object, or 'unknown' if a value is not defined. Currently sub country types are defined for:
Australia : State Canada : Province France : Department Germany : Länder Ireland : County UK : County USA : State
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.
code
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".
full_name
If an optional argument is supplied and set to a true value, the full name is returned as an upper cased string.
Returns a hash of name/code pairs for the currently assigned country, keyed by sub country name.
Returns a hash of code/name pairs for the currently assigned country, keyed by sub country code.
Returns an array of sub country names for the currently assigned country, sorted alphabetically.
Returns an array of sub country codes for the currently assigned country, sorted alphabetically.
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.
Returns an array of all country 2 leteer 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.
ISO 3166-2:1998, Standard for naming sub country codes Locale::Country Locale::US
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
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).
Locale::SubCountry was written by Kim Ryan <kimaryan@ozemail.com.au> in 2000.
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> Code=<COUNTRY CODE> # from ISO 3166 format SubCountryType=<Sub Country Type> # optional field, specify state, county etc CODE:Full Name CODE:Full Name CODE:Full Name ...
Country=<COUNTRY NAME> ...
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'Länder'. Assuming CP1252
To install Locale::SubCountry, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Locale::SubCountry
CPAN shell
perl -MCPAN -e shell install Locale::SubCountry
For more information on module installation, please visit the detailed CPAN module installation guide.