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)