world-region

Crates.ioworld-region
lib.rsworld-region
version
sourcesrc
created_at2024-12-19 22:19:45.664357
updated_at2025-02-06 23:02:10.994629
descriptionA Rust crate providing enums and conversions for World regions and their subregions, building on the africa, europe, north-america, etc crates.
homepage
repositoryhttps://github.com/klebs6/klebs-general
max_upload_size
id1489637
Cargo.toml error:TOML parse error at line 18, column 1 | 18 | autolib = false | ^^^^^^^ unknown field `autolib`, expected one of `name`, `version`, `edition`, `authors`, `description`, `readme`, `license`, `repository`, `homepage`, `documentation`, `build`, `resolver`, `links`, `default-run`, `default_dash_run`, `rust-version`, `rust_dash_version`, `rust_version`, `license-file`, `license_dash_file`, `license_file`, `licenseFile`, `license_capital_file`, `forced-target`, `forced_dash_target`, `autobins`, `autotests`, `autoexamples`, `autobenches`, `publish`, `metadata`, `keywords`, `categories`, `exclude`, `include`
size0
(klebs6)

documentation

https://docs.rs/world-region

README

WorldRegion Crate

The WorldRegion crate provides a robust, structured representation of countries, continents, and their subregions. It allows you to:

  • Convert between Country enums and a WorldRegion enum that supports continents and subdivided regions (like states/provinces or regional groupings).
  • Retrieve ISO3166 Alpha2, Alpha3, and CountryCode representations from world regions.
  • Serialize and deserialize WorldRegion values to and from JSON, including continent, country, and optional subregion fields.
  • Handle errors gracefully through structured error types (e.g., WorldRegionConversionError, WorldRegionParseError).
  • Support abbreviation lookups and conversions to and from Country, making it easy to integrate geography into your application.

Features

  • continent-to-country conversions: Convert a Country into the corresponding WorldRegion variant or vice versa.
  • ISO codes: Extract ISO3166 Alpha2, Alpha3, and CountryCode variants directly from a WorldRegion.
  • Serialization & Deserialization: Serialize WorldRegion into a structured JSON object with continent, country, and optional region keys. Deserialize back to WorldRegion easily.
  • Error Handling: Fine-grained error enums to understand why a conversion or parse failed.

Example

use world_region::{WorldRegion, Country};
use std::convert::TryFrom;

// Convert a known country to its world region
let c = Country::France;
let wr = WorldRegion::try_from(c).expect("France should be in Europe");
println!("{:?}", wr); // e.g., WorldRegion::Europe(EuropeRegion::France(FranceRegion::IleDeFrance))

// Convert back to a country
let back: Country = wr.try_into().expect("Should convert back to France");
assert_eq!(back, Country::France);

// Obtain ISO codes
use std::convert::TryInto;
let alpha2: Iso3166Alpha2 = wr.clone().try_into().expect("Alpha2 conversion");
assert_eq!(alpha2, Iso3166Alpha2::FR);

Serialization / Deserialization

use serde_json;
use world_region::{WorldRegion, EuropeRegion, FranceRegion};

let wr = WorldRegion::Europe(EuropeRegion::France(FranceRegion::IleDeFrance));
let json = serde_json::to_string(&wr).expect("serialize");
println!("{}", json);
// Outputs: {"continent":"Europe","country":"France","region":"Ile-de-France"}

let deserialized: WorldRegion = serde_json::from_str(&json).expect("deserialize");
assert_eq!(deserialized, wr);

Error Handling

Conversions can fail if a country or region isn't represented. Errors are returned via Result<T, WorldRegionConversionError> or WorldRegionParseError, allowing you to handle them gracefully.

License

This crate is distributed under the MIT license. See LICENSE for details.

Commit count: 357

cargo fmt