• NAME
• SYNOPSIS
• DESCRIPTION
• FUNCTIONS

NAME

Geography::USStates - USA State Data

SYNOPSIS

use Geography::USStates; # -- just getState* functions use Geography::USStates qw(:areas); # -- just getArea* functions use Geography::USStates qw(:both); # -- just getState*Area* functions use Geography::USStates qw(:both); # -- all functions

# ------ US STATES BASED $state = getState('mn'); # -- get the statename 'Minnesota'

$state = getState('wisconsin'); # -- get the abbreviation 'wi'

@states = getStateNames(); # -- return all state names

@states = getStateAbbrevs(); # -- return all state abbrevations (AL, AK, ..)

%s = getStates(); # -- return hash $states{'MN'} = 'Minnesota'

%s = getStates(case=>'upper'); # -- return hash $states{'MN'} = 'MINNESOTA'

%s = getStates(case=>'lower'); # -- return hash $states{'MN'} = 'minnesota'

%s = getStates(hashkey=>'name');# -- return hash $states{'Minnesota'} = 'MN'

# ------ US AREAS $area = getArea('gu'); # -- get the area name 'Guam'

$area = getArea('guam'); # -- get the abbreviation 'gu'

@areas = getAreaNames(); # -- return all area names

@areas = getAreaAbbrevs(); # -- return all area abbrevations (DC, GU, ..)

%a = getAreas(); # -- return hash $states{'GU'} = 'Guam'

%a = getAreas(case=>'upper'); # -- return hash $states{'GU'} = 'GUAM'

%a = getAreas(case=>'lower'); # -- return hash $states{'GU'} = 'guam'

%a = getAreas(hashkey=>'name'); # -- return hash $states{'Guam'} = 'GU'

# ------ Lookup both US States and Dependant areas # -- get the statename 'Minnesota' or 'Guam' respectivily $state = getStateOrArea('mn' || 'gu');

# -- get the abbreviation 'wi' or 'gu' respectivily $state = getStateOrArea('wisconsin' || 'guam');

# -- return all states and areas names together @states = getStatesAndAreasNames();

# -- return all states and areas abbreviations together @states = getStatesAndAreasAbbrevs();

# -- same as getStates() but it returns the areas in the hash too %s = getStatesAndAreas(); %s = getStatesAndAreas(case=>'upper'); %s = getStatesAndAreas(case=>'lower'); %s = getStatesAndAreas(hashkey=>'name');

DESCRIPTION

This module allows you to get information on US State names, their abbreviations, and couple the two together (in hashes). As well as states, the US has ``Dependant Area's'' like Guam, and the Virgin Islands. Sometimes you want to offer these areas in your application so you can get access to those via the getArea*() functions and the getState*Area*() functions.

FUNCTIONS

o getState($statename || $stateabbrev)

  Given an abbreviation a statename is returned.
  Given a name an abbreviatin is returned

  e.g. print getState('MN');
       would print 'Minnesota'

       print getState('wisconsin');
       would print 'WI'

 o B<getStateNames>()

    Return all of the states in an array

    e.g. map { print "$_\n" } getStateNames();
         would print "Alabama\nAlaska\n...";

  o B<getStateAbbrevs>()

    Return all of the abbrevs in an array

    e.g. map { print "$_\n" } getStateAbbrevs();
         would print "AL\nAK\n...";

  o B<getStates>(%hash | $hashref) [keys: case => upper||lower, hashkey=>name]

    A hash is returned with both abbrev and statename. By default it returns
    the state abbrev as the key and the state name as the value

    e.g. $hash{MN} = 'Minnesota';

    You can also pass params in a hash or hashref. To force the state names
    to be lower case, or upper case you do:

    getStates(case => 'upper'); # -- for upper case... lower for lower case

    If you want to return a hash where the name is the key you do:

    my %s = getStates(hashkey => 'name');
    and then
    $s{'Minnesota'} = 'MN';

  =head1 AUTHOR

  Dion Almaer (dion@almaer.com)