Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Locale::SubCountry(3) User Contributed Perl DocumentationLocale::SubCountry(3)

NAME
       Locale::SubCountry - Convert state, province, county etc. names to/from
       ISO 3166-2 codes, get all states	in a country

SYNOPSIS
	   use Locale::SubCountry;

	   my $fr = Locale::SubCountry->new('France');
	   if (	not $fr	)
	   {
	       die "Invalid country or code: France\n";
	   }
	   else
	   {
	       print($fr->country,"\n");	# France
	       print($fr->country_code,"\n");	# FR
	       print($fr->country_number,"\n");	# 250

	       if (  $fr->has_sub_countries )
	       {
		   print($fr->code('Hautes-Alpes '),"\n");	 # 05
		   print($fr->full_name('03'),"\n");		 # Allier
		   my $upper_case = 1;
		   print($fr->full_name('02',$upper_case),"\n"); # AINSE
		   print($fr->level('02'),"\n");		 # Metropolitan	department
		   print($fr->level('A'),"\n");			 # Metropolitan	region
		   print($fr->level('BL'),"\n");		 # Overseas territorial	collectivity
		   print($fr->levels,"\n");			 # 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\n",$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;

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.

       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.

       Sub countries are termed	as states in the US and	Australia, provinces
       in Canada and counties in the UK	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.

       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. This in turn can be used to
       fetch every sub country from every country (see examples/demo.pl).

       Sub country codes are defined in	"ISO 3166-2, Codes for the
       representation of names of countries and	their subdivisions".

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 ISO 3166-1	codes, before fetching their sub country data.
       If you only need	access to country data,	then Locale::Country should be
       used.

       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.

	   all_codes
	   all_full_names
	   code_full_name_hash
	   full_name_code_hash

   Locale::SubCountry::World->new()
       The "new" 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.

   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.

   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.

   all_full_names (for world objects)
       Given a world object, returns an	array of all country full names,
       sorted alphabetically.

   all_codes (for world	objects)
       Given a world object, returns an	array of all country ISO 3166-1	codes,
       sorted alphabetically.

   Locale::SubCountry->new()
       The "new" 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
       ISO 3166-1 alpha-2  code	or the full name. For example:

	   AF -	Afghanistan
	   AL -	Albania
	   DZ -	Algeria
	   AO -	Angola
	   AR -	Argentina
	   AM -	Armenia
	   AU -	Australia
	   AT -	Austria

       If the code is specified, such as 'AU'  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.

   country
       Returns the current country name	of a sub country object. The format is
       in title	case, such as 'United Kingdom'

   country_code
       Given a sub country object, returns the alpha-2 ISO 3166-1 code of the
       country,	such as	'GB'

   code
       Given a sub country object, the "code" method takes the full name of a
       sub country and returns the sub country's alpha-2 ISO 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 "New South	Wales".	 The code is returned as a
       capitalised string, or "unknown"	if no match is found.

   full_name
       Given a sub country object, the "full_name" method takes	the alpha-2
       ISO 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 "South Australia".

       If an optional argument is supplied and set to a	true value, the	full
       name is returned	as an upper cased string.

   level
       Given a sub country object, the "level" method takes the	alpha-2	ISO
       3166-2 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 "unknown"
       if no match is found.

   has_sub_countries
       Given a sub country object, the "has_sub_countries" 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.

   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.

   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.

   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.

   all_codes  (for sub country objects)
       Given a sub country object, returns an array of all sub country alpha-2
       ISO 3166-2 codes.  If the country has no	sub countries, returns undef.

SEE ALSO
       All codes have been downloaded from the latest version of the Alioth
       project <https://pkg-isocodes.alioth.debian.org/>

       Locale::Country,Lingua::EN::AddressParse,
       Geo::StreetAddress::US,Geo::PostalAddress,Geo::IP
       WWW::Scraper::Wikipedia::ISO3166	for obtaining ISO 3166-2 data

       ISO 3166-1 Codes	for the	representation of names	of countries and their
       subdivisions - Part 1: Country codes

       ISO 3166-2 Codes	for the	representation of names	of countries and their
       subdivisions - Part 2: Country subdivision code

       <http://www.statoids.com/statoids.html> is a good source	for sub
       country codes plus other	statistical data.

LIMITATIONS
       The ISO 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 BGN
       (1947) Romanization is used.

       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:

	   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)

       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

AUTHOR
       Locale::SubCountry was written by Kim Ryan <kimryan at cpan dot org>.

COPYRIGHT AND LICENCE
       This software is	Copyright (c) 2016 by Kim Ryan.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

CREDITS
       Ron Savage for many corrections to the data

       Terrence	Brannon	produced Locale::US, which was the starting point for
       this module.

COPYRIGHT AND LICENSE
       Copyright (c) 2017 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.

perl v5.24.1			  2017-07-02		 Locale::SubCountry(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | LIMITATIONS | AUTHOR | COPYRIGHT AND LICENCE | CREDITS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Locale::SubCountry&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help