.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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" ''
. ds C`
. ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "2021-01-18" "perl v5.32.0" "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 ISO 3166\-2 codes, get all states in a country
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Locale::SubCountry;
\&
\& my $fr = Locale::SubCountry\->new(\*(AqFrance\*(Aq);
\& if ( not $fr )
\& {
\& die "Invalid country or code: France\en";
\& }
\& else
\& {
\& print($fr\->country,"\en"); # France
\& print($fr\->country_code,"\en"); # FR
\& print($fr\->country_number,"\en"); # 250
\&
\& if ( $fr\->has_sub_countries )
\& {
\& print($fr\->code(\*(AqHautes\-Alpes \*(Aq),"\en"); # 05
\& print($fr\->full_name(\*(Aq03\*(Aq),"\en"); # Allier
\& my $upper_case = 1;
\& print($fr\->full_name(\*(Aq02\*(Aq,$upper_case),"\en"); # AINSE
\& print($fr\->level(\*(Aq02\*(Aq),"\en"); # Metropolitan department
\& print($fr\->level(\*(AqA\*(Aq),"\en"); # Metropolitan region
\& print($fr\->level(\*(AqBL\*(Aq),"\en"); # Overseas territorial collectivity
\& print($fr\->levels,"\en"); # Metropolitan region => 22, Metropolitan department => 96 ...
\&
\& my @fr_names = $fr\->all_full_names; # Ain, Ainse, Allier...
\& my @fr_codes = $fr\->all_codes; # 01, 02, 03 ...
\& my %fr_names_keyed_by_code = $fr\->code_full_name_hash; # 01 => Ain...
\& my %fr_codes_keyed_by_name = $fr\->full_name_code_hash; # Ain => 01 ...
\&
\& foreach my $code ( sort keys %fr_names_keyed_by_code )
\& {
\& printf("%\-3s : %s\en",$code,$fr_names_keyed_by_code{$code});
\& }
\& }
\& }
\&
\& # Methods for fetching all country codes and names in the world
\&
\& my $world = Locale::SubCountry::World\->new();
\& 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 country's administrative
region to the code commonly used for postal addressing. The reverse look up
can also be done.
.PP
Lists of sub country codes are useful for web applications that require a valid
state, county etc to be entered as part of a users location.
.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. Other terms include region,
department, city and territory. Countries such as France have several
levels of sub countries, such as Metropolitan department, Metropolitan region etc.
.PP
Names and \s-1ISO 3166\-2\s0 codes for all sub countries in a country can be
returned as either a hash or an array.
.PP
Names and \s-1ISO 3166\-1\s0 codes for all countries in the world can be
returned as either a hash or an array. This in turn can be used to
fetch every sub country from every country (see examples/demo.pl).
.PP
Sub country codes are defined in \*(L"\s-1ISO 3166\-2,\s0
Codes for the representation of names of countries and their subdivisions\*(R".
.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 countries and
\&\s-1ISO 3166\-1\s0 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 "Locale::SubCountry::World\->\fBnew()\fP"
.IX Subsection "Locale::SubCountry::World->new()"
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-1ISO 3166\-1\s0 codes,
sorted alphabetically.
.SS "Locale::SubCountry\->\fBnew()\fP"
.IX Subsection "Locale::SubCountry->new()"
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 3166\-1\s0
alpha\-2 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 name of a sub country object. The format is in title case,
such as 'United Kingdom'
.SS "country_code"
.IX Subsection "country_code"
Given a sub country object, returns the alpha\-2 \s-1ISO 3166\-1\s0 code of the country,
such as '\s-1GB\s0'
.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 alpha\-2 \s-1ISO 3166\-2\s0 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 alpha\-2 \s-1ISO 3166\-2\s0 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 "level"
.IX Subsection "level"
Given a sub country object, the \f(CW\*(C`level\*(C'\fR method takes the alpha\-2 \s-1ISO 3166\-2\s0 code
of a sub country and returns the sub country's level . Examples are city,
province,state and district, and usually relates to the a regions size.
The level is returned as a 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 New Caledonia" do not have sub countries.
.SS "full_name_code_hash (for sub country objects)"
.IX Subsection "full_name_code_hash (for sub country 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 sub country objects)"
.IX Subsection "code_full_name_hash (for sub country 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 sub country objects)"
.IX Subsection "all_full_names (for sub country 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 sub country objects)"
.IX Subsection "all_codes (for sub country objects)"
Given a sub country object, returns an array of all sub country alpha\-2 \s-1ISO 3166\-2\s0 codes.
If the country has no sub countries, returns undef.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
All codes have been downloaded from the latest version of the Debian Salsa project
and then files iso_3166\-1.json, iso_3166\-2.json
.PP
Locale::Country,Lingua::EN::AddressParse,
Geo::StreetAddress::US,Geo::PostalAddress,Geo::IP
WWW::Scraper::Wikipedia::ISO3166 for obtaining \s-1ISO 3166\-2\s0 data
.PP
\&\s-1ISO 3166\-1\s0 Codes for the representation of names of countries and their
subdivisions \- Part 1: Country codes
.PP
\&\s-1ISO 3166\-2\s0 Codes for the representation of names of countries and their
subdivisions \- Part 2: Country subdivision code
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
The \s-1ISO 3166\-2\s0 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 6
\& AZERBAIJAN : Lankaran; LA (the Municipality), LAN (the Rayon) [see note]
\& AZERBAIJAN : Saki; SA,SAK [see note]
\& AZERBAIJAN : Susa; SS,SUS
\& AZERBAIJAN : Yevlax; YE,YEV
\& LAOS : Vientiane VI the Vientiane, VT the Prefecture
\& MOZAMBIQUE : Maputo; MPM (City),L (Province)
.Ve
.PP
Note: these names are spelt with diacrtic characters (such as two dots above
some of the 'a' characters). This causes utf8 errors on some versions
of Perl, so they are omitted here. See the Locale::SubCountry::Codes module
for correct spelling
.SH "AUTHOR"
.IX Header "AUTHOR"
Locale::SubCountry was written by Kim Ryan .
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is Copyright (c) 2018 by Kim Ryan.
.PP
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
.SH "CREDITS"
.IX Header "CREDITS"
Ron Savage for many corrections to the data
.PP
Terrence Brannon produced Locale::US, which was the starting point for
this module.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2019 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.