Geo::Region - Geographical regions and groupings using UN M.49 and CLDR data
This document describes Geo::Region v0.07, built with Unicode CLDR v27.
use Geo::Region; use Geo::Region::Constant qw( :all ); $amer = Geo::Region->new( AMERICAS ); $emea = Geo::Region->new([ EUROPE, WESTERN_ASIA, AFRICA ]); $apac = Geo::Region->new([ ASIA, OCEANIA ], exclude => WESTERN_ASIA ); if ( $amer->contains($country) ) { # country is in the Americas (US, MX, BR, etc.) } elsif ( $emea->contains($country) ) { # country is in Europe, the Middle East, and Africa (FR, SA, ZW, etc.) } elsif ( $apac->contains($country) ) { # country is in Asia-Pacific (JP, TH, AU, etc.) }
This class is used to create geographical regions and groupings of subregions and countries. Default regional groupings are provided using the Unicode CLDR v27 Territory Containment data, which is an extension of the United Nations UN M.49 (Rev.3) standard.
Regions and subregions are represented with UN M.49 region codes, such as 419 for Latin America and 035 for Southeast Asia. Either the official format using a three-digit 0-padded string like '035' or an integer like 35 may be used with this class. Note when using the 0-padded format that it must be quoted as a string so as not to be treated as on octal literal. The CLDR also adds two additional two-letter region codes which are supported: EU for the European Union and QO for Outlying Oceania. These region codes are all available as constants in Geo::Region::Constant.
0
'035'
35
Countries and territories are represented with ISO 3166-1 alpha-2 country codes, such as JP for Japan and AQ for Antarctica, and are case insensitive. Unlike with region codes, the three-digit forms of country codes are not currently supported, nor are three-letter codes. The deprecated code UK for the United Kingdom is supported as an alias of the official code GB.
The new class method is used to construct a Geo::Region object along with the include argument and optional exclude argument.
new
include
exclude
Accepts either a single region code or an array reference of region or country codes to be included in the resulting custom region. When passed to the new constructor as the first or only argument, the value may be given without the include key.
# countries in the European Union (EU) Geo::Region->new( include => EUROPEAN_UNION ) Geo::Region->new( EUROPEAN_UNION ) # countries in Asia (142) plus Russia (RU) Geo::Region->new( include => [ ASIA, RUSSIA ]) Geo::Region->new([ ASIA, RUSSIA ])
Accepts values in the same format as include. This can be used to exclude countries or subregions from a region.
# countries in Europe (150) which are not in the European Union (EU) Geo::Region->new( include => EUROPE, exclude => EUROPEAN_UNION ) Geo::Region->new( EUROPE, exclude => EUROPEAN_UNION )
contains
Given a country or region code, determines if the region represented by the Geo::Region instance contains it.
if ( $region->contains($country) ) {
is_within
Given a region code, determines if all the countries and regions represented by the Geo::Region instance are within it.
if ( $subregion->is_within($region) ) {
countries
Returns a list of country codes of the countries within the region represented by the Geo::Region instance.
for ( $region->countries ) {
Geo::Region::Constant — Constants for UN M.49 and CLDR region codes
Unicode CLDR: UN M.49 Territory Containment
United Nations: UN M.49 Standard Country, Area, & Region Codes
Locale::CLDR: Territory Containment
Geo::Region for Perl 6
Nick Patch <patch@cpan.org>
This project is brought to you by Perl CLDR and Shutterstock. Additional open source projects from Shutterstock can be found at code.shutterstock.com.
© 2014–2015 Shutterstock, Inc.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Unicode is a registered trademark of Unicode, Inc., in the United States and other countries.
To install Geo::Region, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Geo::Region
CPAN shell
perl -MCPAN -e shell install Geo::Region
For more information on module installation, please visit the detailed CPAN module installation guide.