importing upstream 1.41Locale_SubCountry_1_41

1 files changed, 107 insertions, 0 deletions

diff --git a/README b/README
new file mode 100755
index 0000000..ae3933d
--- /dev/null
+++ b/README
@@ -0,0 +1,107 @@
+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;
+
+
+
+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.
+
+
+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 amendments to the sub country data
+
+
+COPYRIGHT AND LICENCE
+
+Copyright (C) 2008 by Kim Ryan. All rights reserved.
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself, either Perl version 5.8.4 or,
+at your option, any later version of Perl 5 you may have available.
+
+
+
+
+
+