NAME
Locale::SubCountry - convert state, province, county etc names to/from code
SYNOPSIS
use Locale::SubCountry;
$australia = new Locale::SubCountry('Australia');
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_states = $australia->code_full_name_hash;
@australian_names = $australia->all_full_names;
@australian_codes = $australia->all_codes;
$UK_counties = new Locale::SubCountry('UK');
print($UK_counties->full_name('DUMGAL')); # Dumfries & GallowayREQUIRES
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 country regions are defined as states in the US and Australia, provinces in Canada and counties in the UK.
Additionally, names and codes for all sub-country regions in a country can be returned as either a hash or an array.
METHODS
new
The new method creates an instance of a state 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 states, counties etc that you want to work with. These are currently:
Australia
Brazil
Canada
Netherlands
UK
USAAll 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 region in the currently assigned country and returns the regions 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 region 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 region in the currently assigned country and returns the regions 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 name.
code_full_name_hash
Returns a hash of code/name pairs for the currently assigned country, keyed by code.
all_full_names
Returns an array of region names for the currently assigned country, sorted alphabetically.
all_codes
Returns an array of region codes for the currently assigned country, sorted alphabetically.
SEE ALSO
ISO 3166-2:1998, Standard for naming sub country codes Locale::Country Geography::States
LIMITATIONS
If a regions full name contains the word 'and', it is represented by an ampersand, as in Dumfries & Galloway
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.
Terrence Brannon produced Locale::US, which was the starting point for this module.
codes for Canadian, Netherlands and Brazilian regions were taken from Geography::States.
Mark Summerfield and Guy Fraser provided the list of UK counties.