1NAME
2
3Locale::SubCountry - Convert state, province, county etc. names to/from ISO 3166-2 codes, get all states in a country
4
5SYNOPSIS
6
7    use Locale::SubCountry;
8
9    my $fr = Locale::SubCountry->new('France');
10    if ( not $fr )
11    {
12        die "Invalid country or code: France\n";
13    }
14    else
15    {
16        print($fr->country,"\n");        # France
17        print($fr->country_code,"\n");   # FR
18
19        if (  $fr->has_sub_countries )
20        {
21            print($fr->code('Hautes-Alpes '),"\n");       # 05
22            print($fr->full_name('03'),"\n");             # Allier
23            my $upper_case = 1;
24            print($fr->full_name('02',$upper_case),"\n"); # AINSE
25            print($fr->level('02'),"\n");                 # Metropolitan department
26            print($fr->level('A'),"\n");                  # Metropolitan region
27            print($fr->level('BL'),"\n");                 # Overseas territorial collectivity
28            print($fr->levels,"\n");                      # Metropolitan region => 22, Metropolitan department => 96 ...
29
30            my @fr_names  = $fr->all_full_names;    # Ain, Ainse, Allier...
31            my @fr_codes   = $fr->all_codes;        # 01, 02, 03 ...
32            my %fr_names_keyed_by_code  = $fr->code_full_name_hash;  # 01 => Ain...
33            my %fr_codes_keyed_by_name  = $fr->full_name_code_hash;  # Ain => 01 ...
34
35            foreach my $code ( sort keys %fr_names_keyed_by_code )
36            {
37               printf("%-3s : %s\n",$code,$fr_names_keyed_by_code{$code});
38            }
39        }
40    }
41
42    # Methods for fetching all country codes and names in the world
43
44    my $world = Locale::SubCountry::World->new();
45    my @all_countries     = $world->all_full_names;
46    my @all_country_codes = $world->all_codes;
47
48    my %all_countries_keyed_by_name = $world->full_name_code_hash;
49    my %all_country_keyed_by_code   = $world->code_full_name_hash;
50
51
52DESCRIPTION
53
54This module allows you to convert the full name for a country's administrative
55region to the code commonly used for postal addressing. The reverse look up
56can also be done.
57
58Lists of sub country codes are useful for web applications that require a valid
59state, county etc to be entered as part of a users location.
60
61Sub countries are termed as states in the US and Australia, provinces
62in Canada and counties in the UK and Ireland. Other terms include region,
63department, city and territory. Countries such as France have several
64levels of sub countries, such as Metropolitan department, Metropolitan region etc.
65
66Names and ISO 3166-2 codes for all sub countries in a country can be
67returned as either a hash or an array.
68
69Names and ISO 3166-1 codes for all countries in the world can be
70returned as either a hash or an array. This in turn can be used to
71fetch every sub country from every country (see examples/demo.pl).
72
73Sub country codes are defined in "ISO 3166-2,
74Codes for the representation of names of countries and their subdivisions".
75