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 $UK_counties = new Locale::SubCountry('AUSTRALIA'); print($australia->code('New South Wales '),"\n"); # NSW print($australia->full_name('S.A.'),"\n"); # South Australia $upper_case = 1; print($australia->full_name('Qld',$upper_case),"\n"); # QUEENSLAND print($australia->country,"\n"); # AUSTRALIA print($australia->country_code,"\n"); # AU print($australia->sub_country_type,"\n"); # State print($australia->FIPS10_4_code('ACT'),"\n"); # 01 print($australia->ISO3166_2_code('02'),"\n"); # NSW @aus_state_names = $australia->all_full_names; @aus_code_names = $australia->all_codes; %aus_states_keyed_by_code = $australia->code_full_name_hash; %aus_states_keyed_by_name = $australia->full_name_code_hash; foreach $code ( sort keys %aus_states_keyed_by_name ) { printf("%-3s : %s\n",$code,$all_australian_states{$code}); } # Methods for country codes and names $world = new Locale::SubCountry::World; @all_countries = $world->all_full_names; @all_country_codes = $world->all_codes; %all_countries_keyed_by_name = $world->full_name_code_hash; %all_country_keyed_by_code = $world->code_full_name_hash;
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 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.
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
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.
new
Given a world object, returns a hash of full name/code pairs for every country, keyed by country name.
Given a world object, returns a hash of full name/code pairs for every country, keyed by country code.
Given a world object, returns an array of all country full names, sorted alphabetically.
Given a world object, returns an array of all country IS) 3166-1 codes, sorted alphabetically.
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.
Returns the current country of a sub country object
Given a sub country object, returns the two letter ISO 3166-1 code of the country
Given a sub country object, returns the sub country type (state, county etc), or 'unknown' if a value is not defined.
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.
code
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".
full_name
If an optional argument is supplied and set to a true value, the full name is returned as an upper cased string.
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. FIPS is a standard developed by the US government.
FIPS_10_4_code
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.
Given a sub country object, returns a hash of all full name/code pairs, keyed by sub country name.
Given a sub country object, returns a hash of all code/full name pairs, keyed by sub country code.
Given a sub country object, returns an array of all sub country full names, sorted alphabetically.
Given a sub country object, returns an array of all sub country ISO 3166-2 codes, sorted alphabetically.
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
Locale::Country Lingua::EN::AddressParse Geo::IP
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 give you 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 types of sub country, such as a province and a geographical unit
AZERBAIJAN : Länkäran; LA (the City), LAN (the Rayon) 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
FIPS codes are not provided for all sub countries.
None known
Copyright (c) 2000-2002 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 <kimryan@cpan.org>. <http://www.data-distillers.com>
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 suuplied the FIPS codes and many ammendments to the sub country data
Code/Sub country data. Comments (lines starting with #) and blank lines are ignored. Read in at start up by first un-named block. Format is:
Country=<COUNTRY NAME> SubCountryType=<Sub Country Type> # optional field, specify state, county etc Code=<COUNTRY CODE> # from ISO 3166-1 format ISO3166-2 Code:FIPS10-4 Code:Full Name ISO3166-2 Code:FIPS10-4 Code:Full Name ISO3166-2 Code:FIPS10-4 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 'CÔTE'. Assuming CP1252
To install Locale::SubCountry::World, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Locale::SubCountry::World
CPAN shell
perl -MCPAN -e shell install Locale::SubCountry::World
For more information on module installation, please visit the detailed CPAN module installation guide.