NAME

Countries.pm - Perl module providing country name, country code, and continent information

SYNOPSIS

    use CAIDA::Countries;
    my $countries = new CAIDA::Countries();
    print "Canada's 2-letter ISO code is: " .
        $country->get_iso2code_by_name('Canada') . "\n";
    print "Zimbabwe is on the continent of " .
        $country->get_contname_by_contcode(
        $country->get_continent_by_iso2code(
        $country->get_iso2code_by_name('Zimbabwe'))) . ".\n";

DESCRIPTION

Countries is a module that lets you look up information on countries, continents, and country locations. It is meant to provide general, relatively static information. It does not map latitude and longitude to a specific country, but it does map the name of a country to the latitude and longitude of its geographic center.

Module Setup
new(COUNTRY-NAME--ISO2--FILE, ISO2--LOCATION--FILE, ISO2--ISO3--FILE, ISO2--FIPS--FILE, CONTINENT-CODE--CONTINENT-NAME--FILE)
    sets up a new Countries module object.  takes five optional arguments
    describing the location of the input data files you wish to use to
    perform the country/country code/continent/location mappings.  in all
    files, a # indicates a comment line to be ignored.  if specified, each
    data source file will be used in lieu of the defaults listed below:
COUNTRY-NAME--ISO2--FILE
    file of the format:
    "ISO-2-letter-code<tab>country-full-name\n"
    a name in parentheses indicates an alternate name for that country.  a
    name in square brackets indicates an optional addition (usually a prefix)
    to the existing name.
    default: <your-coral-directory>/etc/iso3166_2letter.txt
ISO2--LOCATION--FILE
    file of the format:
    "ISO-2-letter-code<tab>continent-code<tab>latitude,longitude\n"
    default: <your-coral-directory/etc/iso3166_loc.txt
ISO2--ISO3--FILE
    file of the format:
    "ISO-2-letter-code<tab>ISO-3-letter-code\n"
    default: <your-coral-directory/etc/iso3166_3letter.txt
ISO2--FIPS--FILE
    file of the format:
    "ISO-2-letter-code<tab>fips-code\n"
    default: <your-coral-directory/etc/iso3166_fips.txt
CONTINENT-CODE--CONTINENT-NAME--FILE
    file of the format:
    "continent-code<tab>continent-name\n"
    default: <your-coral-directory/etc/continents.txt
These files are further documented in conjunction with other CoralReef data files at: txt_data_files

Country Name Information
Countries.pm lets you look up country names by country code (ISO2, ISO3, or FIPS), look up country code (ISO2, ISO3, FIPS) by country name, and convert between verious types of country codes.
get_name_by_iso2code(ISO2CODE)
    returns the full name of the country specified by the given ISO 2-letter
    country code.
get_name_by_iso3code(ISO3CODE)
    returns the full name of the country specified by the given ISO 3-letter
    country code.
get_name_by_fipscode(FIPSCODE)
    returns the full name of the country specified by the given FIPS
    country code.
get_iso2code_by_name(COUNTRY-NAME)
    returns the ISO 2-letter country code that corresponds to the provided
    name of a country.
get_iso2code_by_iso3code(ISO3CODE)
    returns the ISO 2-letter country code that corresponds to the given ISO
    3-letter country code.
get_iso2code_by_fipscode(FIPSCODE)
    returns the ISO 2-letter country code that corresponds to the given 
    FIPS country code.
get_iso3code_by_name(COUNTRY-NAME)
    returns the ISO 3-letter country code that corresponds to the provided
    name of a country.
get_iso3code_by_iso2code(ISO2CODE)
    returns the ISO 3-letter country code that corresponds to the given ISO
    2-letter country code.
get_iso3code_by_fipscode(FIPSCODE)
    returns the ISO 3-letter country code that corresponds to the given
    FIPS country code.
get_fipscode_by_name(COUNTRY-NAME)
    returns the FIPS country code that corresponds to the provided
    name of a country.
get_fipscode_by_iso2code(ISO2CODE)
    returns the FIPS country code that corresponds to the given ISO 2-letter
    country code.
get_fipscode_by_iso3code(ISO3CODE)
    returns the FIPS country code that corresponds to the given ISO
    3-letter country code.
Continent Information
get_contname_by_contcode(CONTINENT-CODE)
    returns the continent code that corresponds to the provided
    continent name.
get_contcode_by_contname(CONTINENT-NAME)
    returns the continent name that corresponds to the provided
    continent code.
get_continent_by_name(COUNTRY-NAME)
    returns the continent code that corresponds to the provided
    country name.
get_continent_by_iso2code(ISO2CODE)
    returns the continent code that corresponds to the provided
    iso 2-letter country code.
get_continent_by_iso3code(ISO3CODE)
    returns the continent code that corresponds to the provided
    iso 3-letter country code.
get_continent_by_fipscode(FIPSCODE)
    returns the continent code that corresponds to the provided
    fips country code.
get_names_by_contcode(CONTINENT-CODE)
    returns a reference to an array that is a list of the names of all of
    the countries inside the continent that corresponds to the provided
    continent code.
get_iso2codes_by_contcode(CONTINENT-CODE)
    returns a reference to an array that is a list of the ISO 2-letter
    country codes of all of the countries inside the continent that
    corresponds to the provided continent code.
get_iso3codes_by_contcode(CONTINENT-CODE)
    returns a reference to an array that is a list of the ISO 3-letter
    country codes of all of the countries inside the continent that
    corresponds to the provided continent code.
get_fipscodes_by_contcode(CONTINENT-CODE)
    returns a reference to an array that is a list of the FIPS
    country codes of all of the countries inside the continent that
    corresponds to the provided continent code.
Location Information
get_location_by_name(COUNTRY-NAME)
    returns a string of the form "continent<tab>latitude,longitude" that
    corresponds to the geographic center of the country specified by the
    given country name.
get_location_by_iso2code(ISO2CODE)
    returns a string of the form "continent<tab>latitude,longitude" that
    corresponds to the geographic center of the country specified by the
    given iso 2-letter country code.
get_location_by_iso3code(ISO3CODE)
    returns a string of the form "continent<tab>latitude,longitude" that
    corresponds to the geographic center of the country specified by the
    given iso 3-letter country code.
get_location_by_fipscode(FIPSCODE)
    returns a string of the form "continent<tab>latitude,longitude" that
    corresponds to the geographic center of the country specified by the
    given fips country code.
get_latlon_by_name(COUNTRY-NAME)
    returns a string of the form "latitude,longitude" that corresponds
    to the geographic center of the country specified by the given
    country name.
get_latlon_by_iso2code(ISO2CODE)
    returns a string of the form "latitude,longitude" that corresponds
    to the geographic center of the country specified by the given
    iso 2-letter country code.
get_latlon_by_iso3code(ISO3CODE)
    returns a string of the form "latitude,longitude" that corresponds
    to the geographic center of the country specified by the given
    iso 3-letter country code.
get_latlon_by_fipscode(FIPSCODE)
    returns a string of the form "latitude,longitude" that corresponds
    to the geographic center of the country specified by the given
    fipscountry code.
get_split_loc(ISO2CODE, TARGET-FLAG)
    
    if target-flag is 0:
    returns the continent code that corresponds to the provided
    iso 2-letter country code.
    if target-flag is 1:
    returns a string of the form "latitude,longitude" that corresponds
    to the geographic center of the country specified by the given
    iso 2-letter country code.
    
    this function is used extensively within the module to support all of the
    previously documented functions; it is available for external use as well.
Data Output
    each of these functions takes a reference to a file as an optional
    argument.  if no file reference is given, the data is sent to STDOUT.
dump_continents_to_countries(FILEREF)
    prints the continent code/iso 2-letter country code mappings as an
    alphabetized list to the specified file as lines of the form: 
    "continent-code<tab>iso-2-letter-code<tab>iso-2-letter-code...\n"
dump_locations (FILEREF)
    prints the ISO 2-letter code/location mappings to the specified file
    as lines of the form: 
    "iso-2-letter-code<tab>continent-code<tab>latitude,longitude\n"
dump_countries (FILEREF)
    prints the country name/ISO 2-letter code mappings to the specified
    file as lines of the form: 
    "country-name<tab>iso-2-letter-code\n"
dump_iso2codes_to_countries (FILEREF)
    prints the ISO 2-letter code/country name mappings to the specified
    file as lines of the form: 
    "iso-2-letter-code<tab>country-name\n"
dump_iso2codes_to_iso3codes (FILEREF)
    prints the ISO 2-letter code/ISO 3-letter code mappings to the
    specified file as lines of the form: 
    "iso-2-letter-code<tab>iso-3-letter-code\n"
dump_iso3codes_to_iso2codes (FILEREF)
    prints the ISO 3-letter code/ISO 2-letter code mappings to the
    specified file as lines of the form: 
    "iso-3-letter-code<tab>iso-2-letter-code\n"
dump_iso2codes_to_fipscodes (FILEREF)
    prints the ISO 2-letter code/FIPS code mappings to the specified file
    as lines of the form: 
    "iso-2-letter-code<tab>fips-code\n"
dump_fipscodes_to_iso2_codes (FILEREF)
    prints the FIPS code/ISO 2-letter code mappings to the specified file
    as lines of the form: 
    "fips-code<tab>iso-2-letter-code\n"
dump_continents_to_names (FILEREF)
    prints the continent name/continent code mappings to the specified
    file as lines of the form: 
    "continent-code<tab>continent-name\n"
dump_names_to_continents (FILEREF)
    prints the continent code/country name mappings to the specified
    file as lines of the form: 
    "continent-name<tab>continent-code\n"

ERRORS

EXAMPLES

    use CAIDA::Countries;
    my $country = new CAIDA::Countries();
    $country->get_iso2code_by_name('Canada');
    $country->get_name_by_iso2code('ca');
    $country->get_iso3code_by_iso2code('ca');
    $country->get_iso2code_by_iso3code('can');
    $country->get_fipscode_by_iso2code('cc');
    $country->get_iso2code_by_fipscode('ck');
    $country->get_location_by_iso2code('ca');
    $country->get_iso2codes_by_contcode('na');
    $country->get_continent_by_iso2code('ca');
    $country->get_latlon_by_iso2code('ca');
    $country->get_name_by_iso3code('can');
    $country->get_name_by_fipscode('ck');
    $country->get_names_by_contcode('na');
    $country->get_fipscode_by_name('Cocos Islands');
    $country->get_fipscode_by_iso3code('cck');
    $country->get_fipscodes_by_contcode('na');
    $country->get_continent_by_name('Canada');
    $country->get_continent_by_iso3code('can');
    $country->get_continent_by_fipscode('ck');
    $country->get_latlon_by_name('Canada');
    $country->get_latlon_by_iso3code('can');
    $country->get_latlon_by_fipscode('ck');
    $country->get_location_by_name('Canada');
    $country->get_location_by_iso3code('can');
    $country->get_location_by_fipscode('ck');
    $country->get_contname_by_contcode('na');
    $country->get_contcode_by_contname('North America');
    
    my $loc = 'ca';
    $country->get_split_loc($loc, 0);
    $country->get_split_loc($loc, 1);
    
    $country->dump_countries();

ENVIRONMENT

SEE ALSO

NOTES

WARNINGS

DIAGNOSTICS

BUGS

RESTRICTIONS

AUTHOR

CoralReef Development team, CAIDA <coral-info@caida.org>