NAME

Locale::SubCountry - convert state, county, province etc names to/from code

SYNOPSIS

   my $UK = new Locale::SubCountry('GB');
   if ( $UK->has_sub_countries )
   {
       print($UK->full_name('DGY'),"\n");           # Dumfries and Galloway
       print($UK->regional_division('DGY'),"\n");   # SCT (Scotland)
   }

   my $australia = new Locale::SubCountry('AUSTRALIA');
   print($australia->country,"\n");                 # AUSTRALIA
   print($australia->country_code,"\n");            # AU

   if ( $australia->has_sub_countries )
   {
       print($australia->code('New South Wales '),"\n");     # NSW
       print($australia->full_name('S.A.'),"\n");            # South Australia
       my $upper_case = 1;
       print($australia->full_name('Qld',$upper_case),"\n"); # QUEENSLAND
       print($australia->category('NSW'),"\n");              # state
       print($australia->FIPS10_4_code('ACT'),"\n");         # 01
       print($australia->ISO3166_2_code('02'),"\n");         # NSW

       my @aus_state_names  = $australia->all_full_names;
       my @aus_code_names   = $australia->all_codes;
       my %aus_states_keyed_by_code  = $australia->code_full_name_hash;
       my %aus_states_keyed_by_name  = $australia->full_name_code_hash;

       foreach my $code ( sort keys %aus_states_keyed_by_code )
       {
          printf("%-3s : %s\n",$code,$aus_states_keyed_by_code{$code});
       }
   }
   
   # Methods for country codes and names
   
   my $world = new Locale::SubCountry::World;
   my @all_countries     = $world->all_full_names;
   my @all_country_codes = $world->all_codes;

   my %all_countries_keyed_by_name = $world->full_name_code_hash;
   my %all_country_keyed_by_code   = $world->code_full_name_hash;



REQUIRES

Perl 5.005 or above

HOW TO INSTALL

    perl Makefile.PL
    make
    make test
    make install


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 lookup
can also be done.  Sub country codes are defined in "ISO 3166-2:1998,
Codes for the representation of names of countries and their subdivisions".

Sub countries are termed as states in the US and Australia, provinces
in Canada and counties in the UK and Ireland.

Names and ISO 3166-2 codes for all sub countries in a country can be
returned as either a hash or an array.

Names and ISO 3166-1 codes for all countries in the world can be
returned as either a hash or an array.

ISO 3166-2 codes can be converted to FIPS 10-4 codes. The reverse lookup can 
also be done.

COPYRIGHT


Copyright (c) 2004 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, kimryan at cpan dot org


CREDITS

Alastair McKinstry provided many of the sub country codes and names.

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

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

TJ Mather suuplied the FIPS codes and many ammendments to the sub country data