Locale::SubCountry - convert state, province, county etc. names to/from code

   my $UK = new Locale::SubCountry('GB');
   if ( $UK->has_sub_countries )
   {
       print($UK->full_name('DGY'),"\n");           # Dumfries and Allow
       print($UK->regional_division('DGY'),"\n");   # CT (Scotland)
   }

   my $australia = new Locale::SubCountry('AUSTRALIA');
   print($australia->country,"\n");                 # AUSTRALIA
   print($australia->country_code,"\n");            # AU

   if ( $australia->has_sub_countries )
   {
       print($australia->code('New South Wales '),"\n");     # NSW
       print($australia->full_name('S.A.'),"\n");            # South Australia
       my $upper_case = 1;
       print($australia->full_name('Qld',$upper_case),"\n"); # QUEENSLAND
       print($australia->category('NSW'),"\n");              # state
       print($australia->FIPS10_4_code('ACT'),"\n");         # 01
       print($australia->ISO3166_2_code('02'),"\n");         # NSW

       my @aus_state_names  = $australia->all_full_names;
       my @aus_code_names   = $australia->all_codes;
       my %aus_states_keyed_by_code  = $australia->code_full_name_hash;
       my %aus_states_keyed_by_name  = $australia->full_name_code_hash;

       foreach my $code ( sort keys %aus_states_keyed_by_code )
       {
          printf("%-3s : %s\n",$code,$aus_states_keyed_by_code{$code});
       }
   }

   # Methods for country codes and names

   my $world = new Locale::SubCountry::World;
   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;

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 CWnew 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.

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 CWnew 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. For example:

    AF - AFGHANISTAN
    AL - ALBANIA
    DZ - ALGERIA
    AO - ANGOLA
    AR - ARGENTINA
    AM - ARMENIA
    AU - AUSTRALIA
    AT - AUSTRIA

All forms of upper/lower case are acceptable in the country's spelling. If a country name is supplied that the module doesn't recognised, 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, the CWcode 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.

Given a sub country object, the CWfull_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.

If an optional argument is supplied and set to a true value, the full name is returned as an upper cased string.

Given a sub country object, the CWcategory method takes the ISO 3166-2 code of a sub country and returns the sub country's category type. Examples are city, province,state and district. The category is returned as a capitalised string, or unknown if no match is found.

Given a sub country object, the CWregional_division method takes the ISO 3166-2 code of a sub country and returns the sub country's regionional_division. This is, an alphanumeric code. The regional_division is returned as a capitalised string, or unknown if no match is found.

Given a sub country object, the CWhas_sub_countries method returns 1 if the current country has sub countries, or 0 if it does not. Some small countires such as Singapore do not have sub countries.

Given a sub country object, the CWFIPS_10_4_code method takes the ISO 3166-2 code of a sub country and returns the sub country's FIPS 10-4 code, or the string 'unknown', if none exists. FIPS is a standard developed by the US government.

Given a sub country object, the CWISO3166_2_code method takes the FIPS 10-4 code of a sub country and returns the sub country's ISO 3166-2 code, or the string 'unknown', if none exists.

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.

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.

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.

Given a sub country object, returns an array of all sub country ISO 3166-2 codes, sorted alphabetically. If the country has no sub countries, returns undef.

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

<http://www.statoids.com/statoids.html>

Locale::Country,Lingua::EN::AddressParse, Geo::StreetAddress::USGeo::PostalAddressGeo::IP

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 this method of abbreviation is not widely accepted. For example, the ISO code for 'New South Wales' is 'NS', but 'NSW' is the abbreviation that is most commonly 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.

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 : 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

Locale::SubCountry was written by Kim Ryan <kimryan at cpan dot org>.

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 supplied the FIPS codes and many ammendments to the sub country data

Copyright (c) 2005 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, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.