.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Locale::SubCountry 3pm" .TH Locale::SubCountry 3pm "2012-04-18" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Locale::SubCountry \- convert state, province, county etc. names to/from code .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 11 \& my $country_code = \*(AqGB\*(Aq; \& my $UK = new Locale::SubCountry($country_code); \& if ( not $UK ) \& { \& die "Invalid code $country_code\en"; \& } \& elsif ( $UK\->has_sub_countries ) \& { \& print($UK\->full_name(\*(AqDGY\*(Aq),"\en"); # Dumfries and Galloway \& print($UK\->regional_division(\*(AqDGY\*(Aq),"\en"); # SCT (Scotland) \& } \& \& my $australia = new Locale::SubCountry(\*(AqAustralia\*(Aq); \& if ( not $australia ) \& { \& die "Invalid code: Australia\en"; \& } \& else \& { \& print($australia\->country,"\en"); # Australia \& print($australia\->country_code,"\en"); # AU \& \& if ( $australia\->has_sub_countries ) \& { \& print($australia\->code(\*(AqNew South Wales \*(Aq),"\en"); # NSW \& print($australia\->full_name(\*(AqS.A.\*(Aq),"\en"); # South Australia \& my $upper_case = 1; \& print($australia\->full_name(\*(AqQld\*(Aq,$upper_case),"\en"); # QUEENSLAND \& print($australia\->category(\*(AqNSW\*(Aq),"\en"); # state \& print($australia\->FIPS10_4_code(\*(AqACT\*(Aq),"\en"); # 01 \& print($australia\->ISO3166_2_code(\*(Aq02\*(Aq),"\en"); # 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\en",$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; .Ve .SH "DESCRIPTION" .IX Header "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 \*(L"\s-1ISO\s0 3166\-2:1998, Codes for the representation of names of countries and their subdivisions\*(R". .PP Sub countries are termed as states in the \s-1US\s0 and Australia, provinces in Canada and counties in the \s-1UK\s0 and Ireland. .PP Names and \s-1ISO\s0 3166\-2 codes for all sub countries in a country can be returned as either a hash or an array. .PP Names and \s-1ISO\s0 3166\-1 codes for all countries in the world can be returned as either a hash or an array. .PP \&\s-1ISO\s0 3166\-2 codes can be converted to \s-1FIPS\s0 10\-4 codes. The reverse lookup can also be done. .SH "METHODS" .IX Header "METHODS" Note that the following methods duplicate some of the functionality of the Locale::Country module (part of the Locale::Codes bundle). They are provided here because you may need to first access the list of available countries and \&\s-1ISO\s0 3166\-1 codes, before fetching their sub country data. If you only need access to country data, then Locale::Country should be used. .PP Note also the following method names are also used for sub country objects. (interface polymorphism for the technically minded). To avoid confusion, make sure that your chosen method is acting on the correct type of object. .PP .Vb 4 \& all_codes \& all_full_names \& code_full_name_hash \& full_name_code_hash .Ve .SS "new Locale::SubCountry::World" .IX Subsection "new Locale::SubCountry::World" The \f(CW\*(C`new\*(C'\fR method creates an instance of a world country object. This must be called before any of the following methods are invoked. The method takes no arguments. .SS "full_name_code_hash (for world objects)" .IX Subsection "full_name_code_hash (for world objects)" Given a world object, returns a hash of full name/code pairs for every country, keyed by country name. .SS "code_full_name_hash for world objects)" .IX Subsection "code_full_name_hash for world objects)" Given a world object, returns a hash of full name/code pairs for every country, keyed by country code. .SS "all_full_names (for world objects)" .IX Subsection "all_full_names (for world objects)" Given a world object, returns an array of all country full names, sorted alphabetically. .SS "all_codes (for world objects)" .IX Subsection "all_codes (for world objects)" Given a world object, returns an array of all country \s-1IS\s0) 3166\-1 codes, sorted alphabetically. .SS "new Locale::SubCountry" .IX Subsection "new Locale::SubCountry" The \f(CW\*(C`new\*(C'\fR method creates an instance of a sub country object. This must be called before any of the following methods are invoked. The method takes a single argument, the name of the country that contains the sub country that you want to work with. It may be specified either by the \s-1ISO\s0 3166\-1 two letter code or the full name. For example: .PP .Vb 8 \& AF \- Afghanistan \& AL \- Albania \& DZ \- Algeria \& AO \- Angola \& AR \- Argentina \& AM \- Armenia \& AU \- Australia \& AT \- Austria .Ve .PP If the code is specified, such as '\s-1AU\s0' the format may be in capitals or lower case If the full name is specified, such as 'Australia', the format must be in title case If a country name or code is specified that the module doesn't recognised, it will issue a warning. .SS "country" .IX Subsection "country" Returns the current country of a sub country object, the format is title case .SS "country_code" .IX Subsection "country_code" Given a sub country object, returns the two letter \s-1ISO\s0 3166\-1 code of the country .SS "code" .IX Subsection "code" Given a sub country object, the \f(CW\*(C`code\*(C'\fR method takes the full name of a sub country and returns the sub country's \s-1ISO\s0 3166\-2 code. The full name can appear in mixed case. All white space and non alphabetic characters are ignored, except the single space used to separate sub country names such as \*(L"New South Wales\*(R". The code is returned as a capitalised string, or \*(L"unknown\*(R" if no match is found. .SS "full_name" .IX Subsection "full_name" Given a sub country object, the \f(CW\*(C`full_name\*(C'\fR method takes the \s-1ISO\s0 3166\-2 code of a sub country and returns the sub country's full name. The code can appear in mixed case. All white space and non alphabetic characters are ignored. The full name is returned as a title cased string, such as \*(L"South Australia\*(R". .PP If an optional argument is supplied and set to a true value, the full name is returned as an upper cased string. .SS "category" .IX Subsection "category" Given a sub country object, the \f(CW\*(C`category\*(C'\fR method takes the \s-1ISO\s0 3166\-2 code of a sub country and returns the sub country's category type. Examples are city, province,state and district. The category is returned as a capitalised string, or \*(L"unknown\*(R" if no match is found. .SS "regional_division" .IX Subsection "regional_division" Given a sub country object, the \f(CW\*(C`regional_division\*(C'\fR method takes the \&\s-1ISO\s0 3166\-2 code of a sub country and returns the sub country's regionional_division. This is, an alphanumeric code. The regional_division is returned as a capitalised string, or \*(L"unknown\*(R" if no match is found. .SS "has_sub_countries" .IX Subsection "has_sub_countries" Given a sub country object, the \f(CW\*(C`has_sub_countries\*(C'\fR method returns 1 if the current country has sub countries, or 0 if it does not. Some small countries such as Singapore do not have sub countries. .SS "FIPS10_4_code" .IX Subsection "FIPS10_4_code" Given a sub country object, the \f(CW\*(C`FIPS_10_4_code\*(C'\fR method takes the \s-1ISO\s0 3166\-2 code of a sub country and returns the sub country's \s-1FIPS\s0 10\-4 code, or the string 'unknown', if none exists. \s-1FIPS\s0 is a standard developed by the \s-1US\s0 government. .SS "ISO3166_2_code" .IX Subsection "ISO3166_2_code" Given a sub country object, the \f(CW\*(C`ISO3166_2_code\*(C'\fR method takes the \s-1FIPS\s0 10\-4 code of a sub country and returns the sub country's \s-1ISO\s0 3166\-2 code, or the string 'unknown', if none exists. .SS "full_name_code_hash (for subcountry objects)" .IX Subsection "full_name_code_hash (for subcountry objects)" Given a sub country object, returns a hash of all full name/code pairs, keyed by sub country name. If the country has no sub countries, returns undef. .SS "code_full_name_hash (for subcountry objects)" .IX Subsection "code_full_name_hash (for subcountry objects)" Given a sub country object, returns a hash of all code/full name pairs, keyed by sub country code. If the country has no sub countries, returns undef. .SS "all_full_names (for subcountry objects)" .IX Subsection "all_full_names (for subcountry objects)" Given a sub country object, returns an array of all sub country full names, sorted alphabetically. If the country has no sub countries, returns undef. .SS "all_codes (for subcountry objects)" .IX Subsection "all_codes (for subcountry objects)" Given a sub country object, returns an array of all sub country \s-1ISO\s0 3166\-2 codes, sorted alphabetically. If the country has no sub countries, returns undef. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1ISO\s0 3166\-1:1997 Codes for the representation of names of countries and their subdivisions \- Part 1: Country codes .PP \&\s-1ISO\s0 3166\-2:1998 Codes for the representation of names of countries and their subdivisions \- Part 2: Country subdivision code Also released as \s-1AS/NZS\s0 2632.2:1999 .PP Federal Information Processing Standards Publication 10\-4 1995 April Specifications for \s-1COUNTRIES\s0, \s-1DEPENDENCIES\s0, \s-1AREAS\s0 \s-1OF\s0 \s-1SPECIAL\s0 \s-1SOVEREIGNTY\s0, \&\s-1AND\s0 \s-1THEIR\s0 \s-1PRINCIPAL\s0 \s-1ADMINISTRATIVE\s0 \s-1DIVISIONS\s0 .PP .PP Locale::Country,Lingua::EN::AddressParse, Geo::StreetAddress::USGeo::PostalAddressGeo::IP .SH "LIMITATIONS" .IX Header "LIMITATIONS" \&\s-1ISO\s0 3166\-2:1998 defines all sub country codes as being up to 3 letters and/or numbers. These codes are commonly accepted for countries like the \s-1USA\s0 and Canada. In Australia this method of abbreviation is not widely accepted. For example, the \s-1ISO\s0 code for 'New South Wales' is '\s-1NS\s0', but '\s-1NSW\s0' is the abbreviation that is most commonly used. I could add a flag to enforce \&\s-1ISO\-3166\-2\s0 codes if needed. .PP The \s-1ISO\s0 3166\-2 standard romanizes the names of provinces and regions in non-latin script areas, such as Russia and South Korea. One Romanisation is given for each province name. For Russia, the \s-1BGN\s0 (1947) Romanization is used. .PP Several sub country names have more than one code, and may not return the correct code for that sub country. These entries are usually duplicated because the name represents two different types of sub country, such as a province and a geographical unit. Examples are: .PP .Vb 12 \& AZERBAIJAN : La\*:nka\*:ran; LA (the City), LAN (the Rayon) \& AZERBAIJAN : Sa\*:ki; SA,SAK \& AZERBAIJAN : Susa; SS,SUS \& AZERBAIJAN : Yevlax; YE,YEV \& INDONESIA : Kalimantan Timur; KI,KT \& LAOS : Vientiane VI,VT \& MOLDOVA : Hahul; CA,CHL \& MOLDOVA : Bubasari; DU,DBI \& MOLDOVA : Hrhei; OR,OHI \& MOLDOVA : Coroca; SO,SOA \& MOLDOVA : Gngheni; UN,UGI \& MOZAMBIQUE : Maputo; MPM,L .Ve .PP \&\s-1FIPS\s0 codes are not provided for all sub countries. .SH "BUGS" .IX Header "BUGS" None known .SH "AUTHOR" .IX Header "AUTHOR" Locale::SubCountry was written by Kim Ryan . .SH "CREDITS" .IX Header "CREDITS" Alastair McKinstry provided many of the sub country codes and names. .PP Terrence Brannon produced Locale::US, which was the starting point for this module. .PP Mark Summerfield and Guy Fraser provided the list of \s-1UK\s0 counties. .PP \&\s-1TJ\s0 Mather supplied the \s-1FIPS\s0 codes and many ammendments to the sub country data .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (c) 2011 Kim Ryan. All rights reserved. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.