Provided by: liblocale-subcountry-perl_1.62-1_all bug

NAME

       Locale::SubCountry - Convert state, province, county etc. names to/from ISO 3166-2 codes

SYNOPSIS

           my $country_code = 'GB';
           my $UK = new Locale::SubCountry($country_code);
           if ( not $UK )
           {
               die "Invalid code $country_code\n";
           }
           elsif (  $UK->has_sub_countries )
           {
               print($UK->full_name('DGY'),"\n");           # Dumfries and Galloway
               print($UK->regional_division('DGY'),"\n");   # SCT (Scotland)
           }

           my $australia = new Locale::SubCountry('Australia');
           if ( not $australia )
           {
               die "Invalid code: Australia\n";
           }
           else
           {
               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;

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:2007, 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. Ohter terms include region, department, city and
       territory.

       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.

METHODS

       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

   new Locale::SubCountry::World
       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.

   full_name_code_hash (for world objects)
       Given a world object, returns a hash of full name/code pairs for every country, keyed by
       country name.

   code_full_name_hash  for world objects)
       Given a world object, returns a hash of full name/code pairs for every country, keyed by
       country code.

   all_full_names (for world objects)
       Given a world object, returns an array of all country full names, sorted alphabetically.

   all_codes (for world objects)
       Given a world object, returns an array of all country IS) 3166-1 codes, sorted
       alphabetically.

   new Locale::SubCountry
       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. For example:

           AF - Afghanistan
           AL - Albania
           DZ - Algeria
           AO - Angola
           AR - Argentina
           AM - Armenia
           AU - Australia
           AT - Austria

       If the code is specified, such as 'AU'  the format may be in  capitals or lower case If
       the full name is specified, such as 'Australia', the format must be in title case If a
       country name or code is specified that the module doesn't recognised, it will issue a
       warning.

   country
       Returns the current country of a sub country object, the format is title case

   country_code
       Given a sub country object, returns the two letter ISO 3166-1 code of the country

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

   full_name
       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".

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

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

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

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

   FIPS10_4_code
       NOTE: On September 2, 2008, FIPS 10-4 was one of ten standards withdrawn by NIST as a
       Federal Information Processing Standard. It may not be supported by this module in the
       future.

       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, or the string 'unknown', if none
       exists. FIPS is a standard  developed by the US government.

   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, or the string 'unknown', if none
       exists.

   full_name_code_hash  (for subcountry objects)
       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.

   code_full_name_hash  (for subcountry objects)
       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.

   all_full_names  (for subcountry objects)
       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.

   all_codes  (for subcountry objects)
       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.

SEE ALSO

       Locale::Country,Lingua::EN::AddressParse,
       Geo::StreetAddress::US,Geo::PostalAddress,Geo::IP WWW::Scraper::Wikipedia::ISO3166 for
       obtaining ISO 3166-2 data

       ISO 3166-1:2007 Codes for the representation of names of countries and their subdivisions
       - Part 1: Country codes

       ISO 3166-2:2007 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> is a good source for sub country codes plus other
       statistical data.

LIMITATIONS

       ISO 3166-2:2007 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 : Lankaran; LA (the City), LAN (the Rayon) [see note]
           AZERBAIJAN : Saki; SA,SAK [see note]
           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

       Note: these names are spelt with a diaeresis character (two dots) above some of the 'a'
       characters. This causes utf8 errors on some versions of Perl, so they are omitted here.
       See the Locale::SubCountry::Data module for correct spelling

       FIPS codes are not provided for all sub countries.

AUTHOR

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

CREDITS

       Ron Savage for many corrections to the data

       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 AND LICENSE

       Copyright (c) 2013 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.