/ 
Locale-RegionAbbrev-1.00
/ Locale::RegionAbbrev

NAME

Locale::RegionAbbrev - convert state, county etc names to/from abbreviation

SYNOPSIS

use Locale::RegionAbbrev;

$australia = new Locale::RegionAbbrev('Australia');

print($australia->abbreviation('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->name_abbreviation_hash;
foreach $abbrev ( sort keys %australian_states )
{
   printf("%-3s : %s\n",$abbrev,%all_australian_states{$abbrev});
}

%all_australian_states = $australia->abbreviation_name_hash;

@australian_names = $australia->all_full_names;
@australian_abbreviations = $australia->all_abbreviations;

$UK_counties = new Locale::RegionAbbrev('UK');
print($UK_counties->full_name('DUMGAL'));  # Dumfries & Galloway

REQUIRES

Perl 5.005 or above

DESCRIPTION

This module allows you to convert the full name for a countries administrative region to the abbreviation commonly used for postal addressing. The reverse conversion can also be done.

Regions are defined as states in the US and Australia, provinces in Canada and counties in the UK.

Additionally, names and abbreviations for all 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
USA

and must be spelt in exactly this way. If a country name is passed that the module doesn't recognise, it will die.

abbreviation

The abbreviation method takes the full name of a region in the currently assigned country and returns the regions abbreviation. 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 abbreviation is returned as a capitalised string, or "unknown" if no match is found.

full_name

The name method takes the abbreviation of a region in the currently assigned country and returns the regions full name. The abbreviation 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.

name_abbreviation_hash

Returns a hash of name/abbreviation pairs for the currently assigned country, keyed by name.

abbreviation_name_hash

Returns a hash of abbreviation/name pairs for the currently assigned country, keyed by abbreviation.

all_full_names

Returns an array of region names for the currently assigned country, sorted alphabetically.

all_abbreviations

Returns an array of region abbreviations for the currently assigned country, sorted alphabetically.

SEE ALSO

Locale::Country Geography::States

LIMITATIONS

If an 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::RegionAbbrev was written by Kim Ryan <kimaryan@ozemail.com.au> in 2000.

Terrence Brannon produced Locale::US, which was the starting point for this module.

Abbreviations for Canadian, Netherlands and Brazilian regions were taken from Geography::States.

Mark Summerfield and Guy Fraser provided the list of UK counties.