NAME

Locale::US - two letter codes for state identification in the United States and vice versa.

SYNOPSIS

use Locale::US;

$state   = code2state('AL');               # $state gets 'Alabama'
$code    = state2code('Alabama');          # $code gets 'AL'

@codes   = all_state_codes();
$coder   = all_state_codes_ref();
@names   = all_state_names();
$namer   = all_state_names_ref();

%code_hash  = all_code_hash();
%state_hash = all_state_hash();

DESCRIPTION

The Locale::US module provides access to the two-letter codes for identifying states in the United States. You can either access the codes via the "conversion routines" (described below), or with the two functions which return lists of all states codes or all state names.

CONVERSION ROUTINES

There are two conversion routines: code2state() and state2code().

code2state()

This function takes a two letter state code and returns a string which contains the name of the state identified. If the code is not a valid state code, then undef will be returned:

$state = code2state('CA');

state2code()

This function takes a state name and returns the corresponding two letter state code, if such exists. If the argument could not be identified as a state name, then undef will be returned:

$code = state2code('California');

The case of the state name is not important. See the section "KNOWN BUGS AND LIMITATIONS" below.

QUERY ROUTINES

There are two function which can be used to obtain a list of all codes, or all state names:

all_state_codes()

Returns a list of all two-letter state codes. The codes are guaranteed to be all lower-case, and not in any particular order.

all_state_names()

Returns a list of all state names for which there is a corresponding two-letter state code. The names are capitalised, and not returned in any particular order.

all_code_hash()

Returns a hash of all states names keyed by two-letter state code.

all_state_hash()

Returns a hash of all codes names keyed by state name.

EXAMPLES

The following example illustrates use of the code2state() function. The user is prompted for a state code, and then told the corresponding country name:

$| = 1;   # turn off buffering

print "Enter state code: ";
chop($code = <STDIN>);
$state = code2state($code);
if (defined $state)
{
    print "$code = $state\n";
}
else
{
    print "'$code' is not a valid state code!\n";
}

KNOWN BUGS AND LIMITATIONS

• When using state2code(), the country name must currently appear exactly as it does in the source of the module. For example,

  state2code('Alabama')

  will return AL, as expected. But the following will all return undef:

  state2code('Alabama ')
  state2code(' Alabama')

  If there's need for it, a future version could have variants for state names.

• In the current implementation, all data is read in when the module is loaded, and then held in memory. A lazy implementation would be more memory friendly.

SEE ALSO

Locale::Country

http://www.usps.gov/ncsc/lookups/usps_abbreviations.htm

Online file with the USPS two-letter codes for the United States and its possessions.

AUXILLIARY CODE:

lynx -dump http://www.usps.gov/ncsc/lookups/usps_abbreviations.htm > kruft.txt

kruft2codes.pl

AUTHOR

Terrence Brannon <tbrannon@end70.com>

COPYRIGHT

Copyright (c) 1999 End70 Corporation

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.