Crate keshvar

Expand description

§Keshvar

This library contains collection of all sorts of useful information for every country.

Package | Documentation | Repository

§Demo

use keshvar::{CurrencyCode, WeekDay, Region, SubdivisionType, find_by_name};

let country_name_in_any_language = "estados unidos"; // The US in spanish!
let country = find_by_name(country_name_in_any_language).unwrap();
assert_eq!(country.iso_long_name(), "The United States of America");
assert_eq!(country.maybe_nationality(), Some("American"));
assert_eq!(country.currency_code(), CurrencyCode::USD);
assert_eq!(country.start_of_week(), WeekDay::Sunday);
assert_eq!(country.emoji(), "🇺🇸");
assert_eq!(country.country_code(), 1);
assert!(country.maybe_population().unwrap() > 330_000_000);
assert_eq!(country.maybe_region(), Some(Region::Americas));
assert!(country.unofficial_name_list().contains(&"United States"));
assert!(country.spoken_language_list().contains(&"en"));
assert!(country.distance_unit().is_mi()); // KM/MI
assert!(country.g7_member() && country.g20_member());
assert!(!country.eu_member() && !country.eea_member()); // Not in `European Union` and `European Economic Area` 
assert!(!country.gdpr_compliant()); // It's not GDPR compliant too!

let geo = country.geo();
assert_eq!(
    (geo.latitude(), geo.longitude()),
    (37.09024, -95.712891)
);
assert_eq!(
    (geo.min_latitude(), geo.max_longitude()),
    (18.91619, -66.96466)
);
assert_eq!(geo.bounds().northeast().latitude(), 71.3577635769);
assert_eq!(geo.bounds().southwest().longitude(), -171.791110603);

let subdivisions = country.subdivisions();
let california = subdivisions.get("CA").unwrap();
let geo = california.geo().unwrap();
assert_eq!(california.name(), "California");
assert_eq!(
    (geo.latitude(), geo.longitude()),
    (Some(36.778261), Some(-119.4179324))
);
assert_eq!(california.subdivision_type(), SubdivisionType::State);
assert_eq!(
    california.translations().get(&"cs"), // in Czech language
    Some(&"Kalifornie")
);

§Features

Cargo features to support different countries, sub-regions, regions, continents, and world regions.
For every country it supports:
- Short and long and unofficial names (parts of ISO 3166)
- Currency code
- Address format
- Official and spoken languages
- Nationality
- Postal code format
- Start of the week
- Phone number (E.164)
- GDPR compliance
- VAT (Value-added Tax) rate
- Distance unit
- …
Country Subdivisions. (Optional)
Geolocations for countries and their subdivisions (Optional)
Translations for countries and subdivisions (Optional)
serde integration (Optional)
chrono integration (Optional)
iso_currency (ISO 4217) integration (Optional)

§Installation

Add this library as a dependency (from commandline or do it manually) in your Cargo.toml file.

§Commandline

Run bellow command inside root directory of your Cargo project:

cargo add keshvar

§Manual

Add keshvar = "0.1" under dependencies section inside your Cargo.toml file.

Now you’re ready to use it inside your Cargo project.

§Cargo features

By default, all countries are included. Additionally, you can add subdivisions, translations, geo, search-iso-short-name, search-iso-long-name, search-iso-number, search-country-code, search-translations, emojis, serde-derive, chrono-integration, and iso-currency-integration to your Cargo.toml file:

[dependencies]
# Include:
# - all countries (which is the default).
# - Translations for all country names.
# - Geo for all countries.
# - serde support for serializing/deserializing keshvar's structs and enums
keshvar = {version = "<VERSION>", features = ["translations", "geo", "serde-derive"]}

If you do not want to support all countries, You can disable default features and include what countries you want:

[dependencies]
# Include:
# - only USA and Englang.
# - Subdivisions for included countries (here only USA and Englang).
keshvar = {version = "<VERSION>", default-features = false, features = ["us", "gb", "subdivisions"]}

Additionally, You can only include countries for different continents, regions, subregions, and world regions:

[dependencies]
# Include:
# - Countries of `asia` continent.
# - Countries of `oceania` region.
# - Countries of `northern-africa` subregion.
keshvar = {version = "<VERSION>", default-features = false, features = ["asia", "oceania", "northern-africa"]}

World region feature names: amer | apac | emea

§Examples

§Country struct

Main struct of this library is the Country struct. Most other types have a to_country() method, and we usually want to convert them to this struct.

use keshvar::{Country, Alpha2, Alpha3, GEC, IOC};

let country = Country::try_from("US").unwrap();
// IOC (International Olympic Committee):
assert_eq!(IOC::USA.to_country(), country);
// GEC (Geopolitical Entities and Codes):
assert_eq!(GEC::US.to_country(), country);
// ISO 3166 alpha2 code:
assert_eq!(Alpha2::US.to_country(), country);
// ISO 3166 alpha3 code:
assert_eq!(Alpha3::USA.to_country(), country);

For more info see Country.

§Iterating

use keshvar::{
  CountryIterator,   // To iterate over all included countries
  ContinentIterator, // To iterate over all supported continents (based on included countries)
  SubRegionIterator, // To iterate over all supported subregions (based on included countries)
};
use keshvar::{Alpha2, SubRegion, WeekDay, CurrencyCode};

let mut list = Vec::new();
// Doing iteration by for loop:
for country in CountryIterator::new() {
    let start_at_mon = country.start_of_week() == WeekDay::Monday;
    let use_usd_currency = country.currency_code() == CurrencyCode::USD;
    if start_at_mon && use_usd_currency {
        list.push(country)
    }
}
// Found 17 countries:
assert_eq!(17, list.len());
assert!(list.contains(&Alpha2::ZW.to_country())); // It contains The Republic of Zimbabwe (ZW alpha2 code)


// Use Any `Iterator` method you want:
let supported_continents = ContinentIterator::new().count();
assert_eq!(7, supported_continents);

// Doing iteration in a functional way:
let list: Vec<_> = SubRegionIterator::new()
    // Start filtering our supported subregions:
    .filter(
        |subregion| {
            subregion
                // Get alpha2 codes for countries of this subregion:
                .alpha2_list()
                // Iterate over them:
                .iter()
                // Try convert them to Alpha2 enum:
                .filter_map(|alpha2_str| Alpha2::try_from(*alpha2_str).ok())
                // Convert Alpha2 enums to Country structs:
                .map(|alpha2| alpha2.to_country())
                // Take countries that their start day of the week is sunday:
                .filter(|country| country.start_of_week() == WeekDay::Sunday)
                // Check if this filter has more than 4 output items:
                .count() > 4
        }
    ).collect();
// So there is just one subregion that contains more than 4 countries that
// their start day of the week is sunday:
assert_eq!(1, list.len());
assert_eq!(SubRegion::WesternAsia, list[0]);

§Subdivisions

Enable subdivisions feature inside Cargo.toml file:

[dependencies]
keshvar = {version = "<VERSION>", features = ["subdivisions"]}

§Example

use std::collections::HashMap;
use keshvar::{GEC, Country, Subdivision, SubdivisionType, SubdivisionGeo};

// Load from GEC (Geopolitical Entities and Codes)
let country: Country = GEC::UK.to_country(); // England
// A hashmap containing string subdivision codes as keys and `Subdivision` structs as values:
let subdivisions: &HashMap<_, Subdivision> = country.subdivisions();
let london = subdivisions.get("LND").unwrap();
assert_eq!("London, City of", london.name());
assert_eq!(SubdivisionType::CityCorporation, london.subdivision_type());

// If you enabled `translations` feature:
assert_eq!(Some(&"مدينة لندن"), london.translations().get("ar")); // Arabic

// If you enabled `geo` feature:
let geo = london.geo().unwrap();
assert_eq!(Some(51.5073509), geo.latitude());
assert_eq!(Some(-0.1277583), geo.longitude());

§Translations

Enable translations feature inside Cargo.toml file:

[dependencies]
keshvar = {version = "<VERSION>", features = ["translations"]}

§Example

use std::collections::HashMap;
use keshvar::{Alpha2, CountryIterator};

// Load from alpha2 code
let country = Alpha2::CN.to_country(); // China
// A hashmap containing languages as keys and translations as values:
let translations = country.translations();
assert_eq!(Some(&"Chine"), translations.get("fr")); // French
assert_eq!(Some(&"Китай"), translations.get("ru")); // Russian

// Find in all translations for country name "Ізраїль"
let search_text = "Ізраїль";
// Iterate over all included countries:
let country = CountryIterator::new()
    .find(
        |country| {
            //  Search for the given name in translations:
            country
                .translations()
                .values()
                .collect::<Vec<&&str>>()
                .contains(&&search_text)
        }
    ).unwrap();
// Actually "Ізраїль" is "Israel" in ukrainian language
assert_eq!("Israel", country.iso_short_name());

§Geo

Enable geo feature inside Cargo.toml file:

[dependencies]
keshvar = {version = "<VERSION>", features = ["geo"]}

§Example

use keshvar::{IOC, Country, CountryGeo, CountryGeoBounds};

// Load from IOC (International Olympic Committee)
let country: Country = IOC::INA.to_country(); // The Republic of Indonesia (Asia)
let geo: CountryGeo = country.geo();
assert_eq!((-0.789275, 113.921327), (geo.latitude(), geo.longitude()));
assert_eq!((6.216999899999999, 141.0425), (geo.max_latitude(), geo.max_longitude()));
assert_eq!((-11.1082999, 94.7351), (geo.min_latitude(), geo.min_longitude()));
let bounds = geo.bounds();
assert_eq!((6.216999899999999, 141.0425), (bounds.northeast().latitude(), bounds.northeast().longitude()));
assert_eq!((-11.1082999, 94.7351), (bounds.southwest().latitude(), bounds.southwest().longitude()));

§Search functions

use keshvar::{Alpha2, Alpha3, Region, SubRegion, Continent};
// Utility functions:
use keshvar::{
    find_by_iso_short_name, // if `search-iso-short-name` feature is enabled
    find_by_iso_long_name,  // if `search-iso-long-name` feature is enabled
    find_by_code            // if `search-country-code` feature is enabled
};

let country = find_by_iso_short_name("united states of america").unwrap();
assert_eq!(Some("American"), country.maybe_nationality());

let country = find_by_iso_long_name("ukraine").unwrap();
assert_eq!(Alpha2::UA, country.alpha2());
assert_eq!(Some(SubRegion::EasternEurope), country.maybe_subregion());

let country = find_by_code(971).unwrap(); // The United Arab Emirates (Asia)
assert_eq!(Alpha3::ARE, country.alpha3());
assert_eq!(Continent::Asia, country.continent());

§Naming

keshvar (/keʃvar/ or کِشوَر) simply means country in persian/farsi language.

§Contribution

See CONTRIBUTING.md file.

§License

keshvar source-code generator and the generated source are distributed under BSD-3-Clause license (See LICENSE file) but the data that is used to feed the generator is distributed under MIT License (See countries license file). Additionally, The population data which is from World Bank dataset is licensed by its maintainers under the Public Domain Dedication and License (PDDL).

Modules§

countries: Contains separate modules for every country.

Structs§

ContinentIterator: An iterator over all of your supported Continents.
Country: A struct containing useful information for a country.
CountryGeo: GEO information for a Country.
CountryGeoBound: GEO information for a northeast/southwest bound for a Country..
CountryGeoBounds: Northeast and southwest GEO bounds for a Country.
CountryIterator: An iterator over all of your included Countries.
RegionIterator: An iterator over all of your supported Regions.
SubRegionIterator: An iterator over all of your supported SubRegions.
Subdivision: A struct containing useful information about a subdivision.
SubdivisionGeo: GEO information for a Subdivision.
VatRates: Value-added Tax
WorldRegionIterator: An iterator over all of your supported WorldRegions.

Enums§

Alpha2: An enum containing Alpha2 codes for all countries.
Alpha3: An enum containing Alpha3 codes for all countries.
Continent: An enum containing all seven continents.
CurrencyCode: An enum containing currency codes.
DistanceUnit
GEC: An enum containing Geopolitical Entities and Codes (GEC).
IOC: An enum containing International Olympic Committee (IOC) codes.
Region: An enum containing all six regions.
SearchError: Error enum for different search errors.
SearchedItems: An enum showing what items we did search before yielding error.
SubRegion: An enum containing sub-regions.
SubdivisionType: An enum containing countries subdivision types.
WeekDay: Name of the weekday. Used to show start day of the week for each country.
WorldRegion: An enum containing all four world regions.

Constants§

SUPPORTED_ALPHA2_LIST: A constant list containing all included Alpha2 codes.
SUPPORTED_CONTINENT_LIST: A constant list containing all included Continents.
SUPPORTED_G7_ALPHA2_LIST: A constant list containing all included Alpha2 codes that are members of G7.
SUPPORTED_G20_ALPHA2_LIST: A constant list containing all included Alpha2 codes that are members of G20.
SUPPORTED_REGION_LIST: A constant list containing all included Regions.
SUPPORTED_SUBREGION_LIST: A constant list containing all included SubRegions.
SUPPORTED_WORLD_REGION_LIST: A constant list containing all included WorldRegions.

Functions§

find_by_code: Find by country code.
find_by_iso_long_name: Find first match in all included country iso long names.
find_by_iso_short_name: Find first match in all included country iso short names.
find_by_name: find_by_iso_long_name + find_by_iso_short_name + find in all translated and unofficial names.
find_by_number: Find by ISO 3166-1 number.
find_in_subdivisions

Crate keshvarCopy item path

§Keshvar

§Demo

§Features

§Installation

§Commandline

§Manual

§Cargo features

§Examples

§Country struct

§Iterating

§Subdivisions

§Example

§Translations

§Example

§Geo

§Example

§Search functions

§Naming

§Contribution

§License

Modules§

Structs§

Enums§

Constants§

Functions§

Crate keshvar