NAME
Locale::SubCountry - convert state, province, county etc names to/from code
SYNOPSIS
use Locale::SubCountry;
$UK_counties = new Locale::SubCountry('UK');
print($UK_counties->full_name('DUMGAL')); # Dumfries & Galloway
$country = 'AUSTRALIA';
@all_countries = &all_countries;
if ( grep(/$country/, @all_countries) )
{
$australia = new Locale::SubCountry($country);
}
else
{
die "No data for $country";
}
print($australia->code('New South Wales ')); # NSW
print($australia->full_name('S.A.')); # South Australia
$upper_case = 1;
print($australia->full_name('Qld',$upper_case)); # QUEENSLAND
%all_australian_states = $australia->full_name_code_hash;
foreach $abbrev ( sort keys %australian_states )
{
printf("%-3s : %s\n",$abbrev,%all_australian_states{$abbrev});
}
%all_australian_codes = $australia->code_full_name_hash;
@all_australian_states = $australia->all_full_names;
@all_australian_codes = $australia->all_codes;REQUIRES
Perl 5.005 or above
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 conversion can also be done.
Sub countries are termed as states in the US and Australia, provinces in Canada and counties in the UK.
Additionally, names and codes for all sub countries in a country can be returned as either a hash or an array.
METHODS
new
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 countries that you want to work with. These are currently:
Australia
Belarus
Brazil
Canada
Denmark
Dominican Republic
Eritrea
France
Germany
Indonesia
Italy
Netherlands
Nigeria
Poland
Romania
Russia
South Korea
Spain
Turkey
UK
USA
Vietnam
YugoslaviaAll 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.
code
The code method takes the full name of a sub country in the currently assigned country and returns the sub country's 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
The name method takes the code of a sub country in the currently assigned 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.
full_name_code_hash
Returns a hash of name/code pairs for the currently assigned country, keyed by sub country name.
code_full_name_hash
Returns a hash of code/name pairs for the currently assigned country, keyed by sub country code.
all_full_names
Returns an array of sub country names for the currently assigned country, sorted alphabetically.
all_codes
Returns an array of sub country codes for the currently assigned country, sorted alphabetically.
all_countries
Returns an array of all country names that SubCountry can do lookups for, sorted alphabetically. This is implemented as a conventional subroutine rather than a method. This allows us to check if lookups can be done for a given country before actually creating the lookup object.
SEE ALSO
ISO 3166-2:1998, Standard for naming sub country codes Locale::Country Geography::States
LIMITATIONS
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 2 letters. This works for USA, Canada etc. In Australia 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 an enforce ISO-3166 flag 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 for Italy lists alphabetic codes for provinces and numeric codes for the regions they belong to, both are listed.
The Indonesian sub region of Kalimantan Timur has two codes, KI and KT.
BUGS
COPYRIGHT
Copyright (c) 2000 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).
AUTHOR
Locale::SubCountry was written by Kim Ryan <kimaryan@ozemail.com.au> in 2000.
CREDITS
Terrence Brannon produced Locale::US, which was the starting point for this module.
Codes for Canadian, Netherlands and Brazilian sub countries were taken from the Geography::States module.
Mark Summerfield and Guy Fraser provided the list of UK counties.
Alastair McKinstry provided the data for Belarus, Denmark, the Dominican Republic, Eritrea, France, Germany, Indonesia, Ireland, Italy, Japan, Nigera, Poland, Romania, Russia, South Korea, Spain, Turkey, Vietnam and Yugoslavia.