This library contains collection of all sorts of useful information for every country.
Package | Documentation | Repository
```rust use keshvar::{CurrencyCode, WeekDay, Region, SubdivisionType, findbyname};
let countrynameinanylanguage = "estados unidos"; // The US in spanish! let country = findbyname(countrynameinanylanguage).unwrap(); asserteq!(country.isolongname(), "The United States of America"); asserteq!(country.nationality(), Some("American")); asserteq!(country.currencycode(), CurrencyCode::USD); asserteq!(country.startofweek(), WeekDay::Sunday); asserteq!(country.emoji(), "🇺🇸"); asserteq!(country.countrycode(), 1); asserteq!(country.region(), Some(Region::Americas)); assert!(country.unofficialnamelist().contains(&"United States")); assert!(country.spokenlanguage_list().contains(&"en"));
let geo = country.geo(); asserteq!( (geo.latitude(), geo.longitude()), (37.09024, -95.712891) ); asserteq!( (geo.minlatitude(), geo.maxlongitude()), (18.91619, -66.96466) ); asserteq!(geo.bounds().northeast().latitude(), 71.3577635769); asserteq!(geo.bounds().southwest().longitude(), -171.791110603);
let subdivisions = country.subdivisions(); let california = subdivisions.get("CA").unwrap(); let geo = california.geo().unwrap(); asserteq!(california.name(), "California"); asserteq!( (geo.latitude(), geo.longitude()), (Some(36.778261), Some(-119.4179324)) ); asserteq!(california.subdivisiontype(), SubdivisionType::State); assert_eq!( california.translations().get(&"cs"), // in Czech language Some(&"Kalifornie") ); ```
serde integration (Optional)chrono integration (Optional)iso_currency (ISO 4217) integration (Optional)Add this library as a dependency (from commandline or do it manually) in your Cargo.toml file.
Run bellow command inside root directory of your Cargo project:
shell
cargo add keshvar
Add keshvar = "0.1" under dependencies section inside your Cargo.toml file.
Now you're ready to use it inside your Cargo project.
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:
```toml
[dependencies]
keshvar = {version = "
If you do not want to support all countries, You can disable default features and include what countries you want:
toml
[dependencies]
keshvar = {version = "
Additionally, You can only include countries for different continents, regions, subregions, and world regions:
toml
[dependencies]
asia continent.oceania region.northern-africa subregion.keshvar = {version = "
[Continent](crate::Continent) feature names:africa|antarctica|asia|australia|europe|north-america|south-america`
Region feature names: americas | oceania | region-africa | region-antarctica | region-asia | region-europe
Subregion feature names: australia-and-new-zealand | caribbean | central-america | central-asia | eastern-africa | eastern-asia | eastern-europe | melanesia | micronesia | middle-africa | northern-africa | northern-america | northern-europe | polynesia | south-eastern-asia | southern-africa | southern-asia | southern-europe | subregion-south-america | western-africa | western-asia | western-europe
World region feature names: amer | apac | emea
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.
```rust
use keshvar::{Country, Alpha2, Alpha3, GEC, IOC};
let country = Country::tryfrom("US").unwrap();
// IOC (International Olympic Committee):
asserteq!(IOC::USA.tocountry(), country);
// GEC (Geopolitical Entities and Codes):
asserteq!(GEC::US.tocountry(), country);
// ISO 3166 alpha2 code:
asserteq!(Alpha2::US.tocountry(), country);
// ISO 3166 alpha3 code:
asserteq!(Alpha3::USA.to_country(), country);
``
For more info see [Country`](crate::Country).
```rust 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 startatmon = country.startofweek() == WeekDay::Monday; let useusdcurrency = country.currencycode() == CurrencyCode::USD; if startatmon && useusdcurrency { list.push(country) } } // Found 17 countries: asserteq!(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 supportedcontinents = ContinentIterator::new().count();
asserteq!(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: .alpha2list() // Iterate over them: .iter() // Try convert them to Alpha2 enum: .filtermap(|alpha2str| Alpha2::tryfrom(*alpha2str).ok()) // Convert Alpha2 enums to Country structs: .map(|alpha2| alpha2.tocountry()) // Take countries that their start day of the week is sunday: .filter(|country| country.startofweek() == 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: asserteq!(1, list.len()); asserteq!(SubRegion::WesternAsia, list[0]); ```
Enable subdivisions feature inside Cargo.toml file:
toml
[dependencies]
keshvar = {version = "<VERSION>", features = ["subdivisions"]}
```rust use std::collections::HashMap; use keshvar::{GEC, Country, Subdivision, SubdivisionType, SubdivisionGeo};
// Load from GEC (Geopolitical Entities and Codes)
let country: Country = GEC::UK.tocountry(); // England
// A hashmap containing string subdivision codes as keys and Subdivision structs as values:
let subdivisions: &HashMap<&str, Subdivision> = country.subdivisions();
let london = subdivisions.get("LND").unwrap();
asserteq!("London, City of", london.name());
asserteq!(SubdivisionType::CityCorporation, london.subdivisiontype());
// If you enabled translations feature:
assert_eq!(Some(&"مدينة لندن"), london.translations().get("ar")); // Arabic
// If you enabled geo feature:
let geo = london.geo().unwrap();
asserteq!(Some(51.5073509), geo.latitude());
asserteq!(Some(-0.1277583), geo.longitude());
```
Enable translations feature inside Cargo.toml file:
toml
[dependencies]
keshvar = {version = "<VERSION>", features = ["translations"]}
```rust use std::collections::HashMap; use keshvar::{Alpha2, CountryIterator};
// Load from alpha2 code let country = Alpha2::CN.tocountry(); // China // A hashmap containing languages as keys and translations as values: let translations: &HashMap<&str, &str> = country.translations(); asserteq!(Some(&"Chine"), translations.get("fr")); // French assert_eq!(Some(&"Китай"), translations.get("ru")); // Russian
// Find in all translations for country name "Ізраїль"
let searchtext = "Ізраїль";
// Iterate over all included countries:
let country = CountryIterator::new()
.find(
|country| {
// Search for the given name in translations:
country
.translations()
.values()
.collect::
Enable geo feature inside Cargo.toml file:
toml
[dependencies]
keshvar = {version = "<VERSION>", features = ["geo"]}
```rust use keshvar::{IOC, Country, CountryGeo, CountryGeoBounds};
// Load from IOC (International Olympic Committee) let country: Country = IOC::INA.tocountry(); // The Republic of Indonesia (Asia) let geo: CountryGeo = country.geo(); asserteq!((-0.789275, 113.921327), (geo.latitude(), geo.longitude())); asserteq!((6.216999899999999, 141.0425), (geo.maxlatitude(), geo.maxlongitude())); asserteq!((-11.1082999, 94.7351), (geo.minlatitude(), geo.minlongitude())); let bounds = geo.bounds(); asserteq!((6.216999899999999, 141.0425), (bounds.northeast().latitude(), bounds.northeast().longitude())); asserteq!((-11.1082999, 94.7351), (bounds.southwest().latitude(), bounds.southwest().longitude())); ```
``rust
use keshvar::{Alpha2, Alpha3, Region, SubRegion, Continent};
// Utility functions:
use keshvar::{
find_by_iso_short_name, // ifsearch-iso-short-namefeature is enabled
find_by_iso_long_name, // ifsearch-iso-long-namefeature is enabled
find_by_code // ifsearch-country-code` feature is enabled
};
let country = findbyisoshortname("united states of america").unwrap(); assert_eq!(Some("American"), country.nationality());
let country = findbyisolongname("ukraine").unwrap(); asserteq!(Alpha2::UA, country.alpha2()); asserteq!(Some(SubRegion::EasternEurope), country.subregion());
let country = findbycode(971).unwrap(); // The United Arab Emirates (Asia) asserteq!(Alpha3::ARE, country.alpha3()); asserteq!(Continent::Asia, country.continent()); ```
keshvar (/keʃvar/ or کِشوَر) simply means country in persian/farsi language.
See CONTRIBUTING.md file.
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).