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