NAME

Weather::GHCN::CountryCodes - convert between various country codes

VERSION

version v0.0.004

SYNOPSIS

  use Weather::GHCN::CountryCodes qw(:all);

DESCRIPTION

The CountryCodes module provides functions to search a table of country codes and country names using various search criteria. It can also do a direct lookup of a country entry using the 2-character GEC (formerly FIPS) code.

The source for the mapping table is taken from the CIA World Factbook. See https://www.cia.gov/library/publications/the-world-factbook/appendix/appendix-d.html

The module is primarily for use by modules Weather::GHCN::Options, and Weather::GHCN::StationTable.

FUNCTIONS

get_country_by_gec($code)

For a given GEC (FIPS) country code, return a hash containing the country name and other country codes. Returns empty if the code was not found.

search_country( $search [, $type] )

Search the country table and return the entries which match the search criteria. The optional $type argument allows you to designate which field the search criteria is to be matched against, as follows:

    name      does an unanchored pattern match on the country name
    gec       matches the GEC (formerly FIPS) country code
    iso2      matches the ISO 3166 2-character country code
    iso3      matches the ISO 3166 3-character country code
    isonum    matches the ISO 3166 country numeric code
    nato      matches the STANAG 1059 country code used by NATO
    internet  matches the internet country code (such as .ca)

If the search criteria is only two-characters long, then the type defaults to gec. To match a name, the search criteria must be longer than three characters, otherwise you'll get results from matches against gec or iso3.

In list context, all matches are returned. In scalar context, only the first match is returned. Undef is returned if there are no matches.

country_table

Returns the country table.

SEARCHABLE FIELDS

For the purposes of this module, short names have been assigned to each type of search field. These names are provided below, along with a description of the field taken from the CIA World Handbook:

name

gec

GEOPOLITICAL ENTITIES and CODES (formerly FIPS PUB 10-4): FIPS PUB 10-4 was withdrawn by the National Institute of Standards and Technology on 2 September 2008 based on Public Law 104-113 (codified OMB Circular A-119 and the National Technology Transfer and Advancement Act of 1995). The National Geospatial-Intelligence Agency (NGA), as the maintenance authority for FIPS PUB 10-4, has continued to maintain and provide regular updates to its content in a document known as Geopolitical Entities and Codes (GEC) (Formerly FIPS 1PUB 10-4).

iso2

iso3

isonum

ISO 3166: Codes for the Representation of Names of Countries (ISO 3166) is prepared by the International Organization for Standardization. ISO 3166 includes two- and three-character alphabetic codes and three-digit numeric codes that may be needed for activities involving exchange of data with international organizations that have adopted that standard. Except for the numeric codes, ISO 3166 codes have been adopted in the US as FIPS 104-1: American National Standard Codes for the Representation of Names of Countries, Dependencies, and Areas of Special Sovereignty for Information Interchange.

nato

STANAG 1059: Letter Codes for Geographical Entities (8th edition, 2004) is a Standardization Agreement (STANAG) established and maintained by the North Atlantic Treaty Organization (NATO/OTAN) for the purpose of providing a common set of geo-spatial identifiers for countries, territories, and possessions. The 8th edition established trigraph codes for each country based upon the ISO 3166-1 alpha-3 character sets. These codes are used throughout NATO.

internet

Internet: The Internet country code is the two-letter digraph maintained by the International Organization for Standardization (ISO) in the ISO 3166 Alpha-2 list and used by the Internet Assigned Numbers Authority (IANA) to establish country-coded top-level domains (ccTLDs).

AUTHOR

Gary Puckering

COPYRIGHT AND LICENSE

Copyright 2022 by Gary Puckering.

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