Crate celes 

Rust implementation of countries as specified by Country Codes and ISO 3166-1

Enable the subdivisions feature for current ISO 3166-2 subdivision codes and English names from Unicode CLDR.

If any countries are missing, please open an issue or submit a pull request.

Cargo features

• serde (enabled by default) implements serialization and deserialization using canonical country and subdivision codes.
• subdivisions adds current ISO 3166-2 codes and English names from Unicode CLDR.

Disable default features to use the core country API without serde. All core lookups are allocation-free and compatible with no_std.

The main struct is Country, which provides the following fields:

• code - The three-digit numeric code for the country.
• value - The numeric code as an integer.
• alpha2 - The alpha-2 country code.
• alpha3 - The alpha-3 country code.
• long_name - The official state name of the country.
• aliases - Other names by which the country is known.

Each country can be created by calling a function whose name is the country’s name in snake_case.

Usage

use celes::Country;

let gb = Country::the_united_kingdom_of_great_britain_and_northern_ireland();
println!("{}", gb);

let usa = Country::the_united_states_of_america();
println!("{}", usa);

Each country can also be created from a string or its numeric code. Country provides several lookup methods:

• Country::from_code - Creates a country from a three-digit numeric code.
• Country::from_value - Creates a country from a numeric code represented as an integer.
• Country::from_alpha2 - Creates a country from an alpha-2 code.
• Country::from_alpha3 - Creates a country from an alpha-3 code.
• Country::from_alias - Creates a country from a common alias.
• Country::from_name - Creates a country from its full state name without spaces or underscores.

Country implements core::str::FromStr. It accepts any string identifier supported by the lookup methods above, including:

• Country aliases such as UnitedKingdom, GreatBritain, Russia, and America.
• The full country name.
• The numeric code, such as "840".
• The alpha-2 code.
• The alpha-3 code.

If you are uncertain which function to use, use Country::from_str; it accepts all valid string identifiers and is case-insensitive.

From String Example

use celes::Country;
use core::str::FromStr;

// All of these are equivalent.
assert_eq!("US", Country::from_str("USA").unwrap().alpha2);
assert_eq!("US", Country::from_str("US").unwrap().alpha2);
assert_eq!("US", Country::from_str("America").unwrap().alpha2);
assert_eq!("US", Country::from_str("UnitedStates").unwrap().alpha2);
assert_eq!("US", Country::from_str("TheUnitedStatesOfAmerica").unwrap().alpha2);

// All of these are equivalent.
assert_eq!("GB", Country::from_str("England").unwrap().alpha2);
assert_eq!("GB", Country::from_str("gb").unwrap().alpha2);
assert_eq!("GB", Country::from_str("Scotland").unwrap().alpha2);
assert_eq!("GB", Country::from_str("TheUnitedKingdomOfGreatBritainAndNorthernIreland").unwrap().alpha2);

Subdivision Example

Enable the subdivisions feature to parse ISO 3166-2 codes, find their countries, and list the subdivisions belonging to a country.

use celes::{Country, Subdivision};
use core::str::FromStr;

let california = Subdivision::from_str("US-CA").unwrap();
assert_eq!(california.name, "California");
assert_eq!(
    california.country(),
    Country::the_united_states_of_america()
);

let canada = Country::canada();
assert!(canada
    .subdivisions()
    .iter()
    .any(|subdivision| subdivision.code == "CA-ON"));

Structs

Country

Represents a country according to ISO 3166.

Subdivision

A current ISO 3166-2 country subdivision.

Enums

CountryParseError

An error returned when a value cannot be resolved to a country.

SubdivisionParseError

An error returned when a value cannot be resolved to an ISO 3166-2 subdivision.

Constants

SUBDIVISION_DATA_VERSION

The Unicode CLDR release used for the bundled ISO 3166-2 subdivision data.