https://github.com/patch/geo-region-pm6
Geo::Region (Perl 6): Geographical regions and groupings using UN M.49 + CLDR data
https://github.com/patch/geo-region-pm6
cldr i18n perl6 unicode
Last synced: 2 months ago
JSON representation
Geo::Region (Perl 6): Geographical regions and groupings using UN M.49 + CLDR data
- Host: GitHub
- URL: https://github.com/patch/geo-region-pm6
- Owner: patch
- License: other
- Created: 2014-12-06T16:19:01.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2018-08-03T22:23:46.000Z (about 7 years ago)
- Last Synced: 2025-03-25T03:25:38.731Z (7 months ago)
- Topics: cldr, i18n, perl6, unicode
- Language: Perl
- Homepage:
- Size: 91.8 KB
- Stars: 2
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# NAME
Geo::Region - Geographical regions and groupings using UN M.49 and CLDR data
# VERSION
This document describes Geo::Region for Perl 6, built with Unicode CLDR v26.
# SYNOPSIS
```perl
use Geo::Region;
use Geo::Region::Enum;
$amer = Geo::Region.new(include => Region::Americas);
$emea = Geo::Region.new(
include => (Region::Europe, Region::WesternAsia, Region::Africa)
);
$apac = Geo::Region.new(
include => (Region::Asia, Region::Oceania),
exclude => Region::WesternAsia,
);
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.)
}
```
# DESCRIPTION
This class is used to create geographical regions and groupings of subregions
and countries. Default regional groupings are provided using the [Unicode CLDR
v26 Territory
Containment](http://unicode.org/cldr/charts/26/supplemental/territory_containment_un_m_49.html)
data, which is an extension of the United Nations [UN
M.49 (Rev.3)](http://unstats.un.org/unsd/methods/m49/m49regin.htm) standard.
## Regions
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 enumerations in [Geo::Region::Enum](lib/Geo/Region/Enum.pm).
## Countries
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**.
## Constructor
The `new` class method is used to construct a Geo::Region object along with the
`include` argument and optional `exclude` argument.
- `include`
Accepts either a single region code or an array reference of region or country
codes to be included in the resulting custom region.
```perl
# countries in the European Union (EU)
Geo::Region.new(include => Region::EuropeanUnion)
# countries in Asia (142) plus Russia (RU)
Geo::Region.new(include => (Region::Asia, Country::Russia))
```
- `exclude`
Accepts values in the same format as `include`. This can be used to exclude
countries or subregions from a region.
```perl
# countries in Europe (150) which are not in the European Union (EU)
Geo::Region.new(
include => Region::Europe,
exclude => Region::EuropeanUnion,
)
```
## Methods
- `contains`
Given a country or region code, determines if the region represented by the
Geo::Region instance contains it.
```perl
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.
```perl
if $subregion.is-within($region) {
```
- `countries`
Returns a list of country codes of the countries within the region represented
by the Geo::Region instance.
```perl
for $region.countries -> $country {
```
# SEE ALSO
- [Geo::Region::Enum](lib/Geo/Region/Enum.pm) — Enumerations for UN M.49 and CLDR region codes
- [Unicode CLDR: UN M.49 Territory
Containment](http://unicode.org/cldr/charts/26/supplemental/territory_containment_un_m_49.html)
- [United Nations: UN M.49 Standard Country, Area, & Region
Codes](http://unstats.un.org/unsd/methods/m49/m49regin.htm)
- [Geo::Region](https://metacpan.org/pod/Geo::Region) for Perl 5
# AUTHOR
Nick Patch
# COPYRIGHT AND LICENSE
© 2014 Nick Patch
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl 6 itself.