NAME

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

SYNOPSIS

   use Locale::SubCountry;

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

   $country = 'AUSTRALIA';
   @all_countries = &all_country_names;
   if ( grep(/$country/, @all_countries) )
   {
      $australia = new Locale::SubCountry($country);
   }
   else
   {
      die "No data for $country";
   }

   print($australia->code('New South Wales ')); # NSW
   print($australia->full_name('S.A.'));        # South Australia

   $upper_case = 1;
   print($australia->full_name('Qld',$upper_case)); # QUEENSLAND
   print $australia->country;          # AUSTRALIA
   print $australia->country_code;     # AU
   print $australia->sub_country_type; # State

   @all_country_codes = &all_country_codes;

   %all_australian_states = $australia->full_name_code_hash;
   foreach $abbrev ( sort keys %australian_states )
   {
      printf("%-3s : %s\n",$abbrev,%all_australian_states{$abbrev});
   }

   %all_australian_codes = $australia->code_full_name_hash;

   @all_australian_states = $australia->all_full_names;
   @all_australian_codes = $australia->all_codes;


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

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

Additionally, names and codes for all subcountry regions in a country can be
returned as either a hash or an array.


COPYRIGHT


Copyright (c) 2000-1 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@cpan.org
http://www.data-distillers.com


CREDITS

Alastair McKinstry provided nearly all the sub country codes and names.

Terrence Brannon produced Locale::US, which was the starting point for
this module. Some of the ideas in Geography::States were also used.

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