README

   1 NAME
   2
   3 Locale::SubCountry - convert state, county, province etc names to/from code
   4
   5 SYNOPSIS
   6
   7    my $UK = new Locale::SubCountry('GB');
   8    if ( $UK->has_sub_countries )
   9    {
  10        print($UK->full_name('DGY'),"\n");           # Dumfries and Galloway
  11        print($UK->regional_division('DGY'),"\n");   # SCT (Scotland)
  12    }
  13
  14    my $australia = new Locale::SubCountry('AUSTRALIA');
  15    print($australia->country,"\n");                 # AUSTRALIA
  16    print($australia->country_code,"\n");            # AU
  17
  18    if ( $australia->has_sub_countries )
  19    {
  20        print($australia->code('New South Wales '),"\n");     # NSW
  21        print($australia->full_name('S.A.'),"\n");            # South Australia
  22        my $upper_case = 1;
  23        print($australia->full_name('Qld',$upper_case),"\n"); # QUEENSLAND
  24        print($australia->category('NSW'),"\n");              # state
  25        print($australia->FIPS10_4_code('ACT'),"\n");         # 01
  26        print($australia->ISO3166_2_code('02'),"\n");         # NSW
  27
  28        my @aus_state_names  = $australia->all_full_names;
  29        my @aus_code_names   = $australia->all_codes;
  30        my %aus_states_keyed_by_code  = $australia->code_full_name_hash;
  31        my %aus_states_keyed_by_name  = $australia->full_name_code_hash;
  32
  33        foreach my $code ( sort keys %aus_states_keyed_by_code )
  34        {
  35           printf("%-3s : %s\n",$code,$aus_states_keyed_by_code{$code});
  36        }
  37    }
  38
  39    # Methods for country codes and names
  40
  41    my $world = new Locale::SubCountry::World;
  42    my @all_countries     = $world->all_full_names;
  43    my @all_country_codes = $world->all_codes;
  44
  45    my %all_countries_keyed_by_name = $world->full_name_code_hash;
  46    my %all_country_keyed_by_code   = $world->code_full_name_hash;
  47
  48
  49
  50 HOW TO INSTALL
  51
  52     perl Makefile.PL
  53     make
  54     make test
  55     make install
  56
  57
  58 DESCRIPTION
  59
  60 This module allows you to convert the full name for a countries administrative
  61 region to the code commonly used for postal addressing. The reverse lookup
  62 can also be done.  Sub country codes are defined in "ISO 3166-2:1998,
  63 Codes for the representation of names of countries and their subdivisions".
  64
  65 Sub countries are termed as states in the US and Australia, provinces
  66 in Canada and counties in the UK and Ireland.
  67
  68 Names and ISO 3166-2 codes for all sub countries in a country can be
  69 returned as either a hash or an array.
  70
  71 Names and ISO 3166-1 codes for all countries in the world can be
  72 returned as either a hash or an array.
  73
  74 ISO 3166-2 codes can be converted to FIPS 10-4 codes. The reverse lookup can
  75 also be done.
  76
  77
  78 AUTHOR
  79
  80 Locale::SubCountry was written by Kim Ryan, kimryan at cpan dot org
  81
  82
  83 CREDITS
  84
  85 Alastair McKinstry provided many of the sub country codes and names.
  86
  87 Terrence Brannon produced Locale::US, which was the starting point for
  88 this module.
  89
  90 Mark Summerfield and Guy Fraser provided the list of UK counties.
  91
  92 TJ Mather suuplied the FIPS codes and many amendments to the sub country data
  93
  94
  95 COPYRIGHT AND LICENCE
  96
  97 Copyright (C) 2008 by Kim Ryan. All rights reserved.
  98
  99 This library is free software; you can redistribute it and/or modify
 100 it under the same terms as Perl itself, either Perl version 5.8.4 or,
 101 at your option, any later version of Perl 5 you may have available.
 102
 103
 104
 105
 106
 107