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.
Subcountry regions are defined as states in the US and Australia, provinces in Canada and counties in the UK.
Additionally, names and codes for all subcountry regions in a country can be returned as either a hash or an array.
METHODS
new
The new method creates an instance of a subcountry 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 subcountries 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 subcountry 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 subcountries 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 subcountry in the currently assigned country and returns the subcountries 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 subcountry name.
code_full_name_hash
Returns a hash of code/name pairs for the currently assigned country, keyed by subcountry code.
all_full_names
Returns an array of subcountry names for the currently assigned country, sorted alphabetically.
all_codes
Returns an array of subcountry 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'.
ISO 3166-2:1998 defines all subcountry 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.
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.