1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
#![deny(intra_doc_link_resolution_failure)] #![cfg_attr(docsrs, feature(doc_cfg))] #![deny(missing_docs)] #![deny(warnings)] #![deny(rust_2018_idioms)] //! Lightweight static `Jurisdiction` information. //! //! This crate provides interfaces to work with jurisdictions for areas around the world. //! Information about a jurisdiction includes //! * ISO 3166 [Alpha2] and [Alpha3] character codes. //! * ISO 3166 numeric country code. //! * [UN M49] region classifications. //! //! The [Jurisdiction] object is a lightweight object, the size of a pointer, //! suitable for transfer in API surfaces throughout an ecosystem. Serialization on //! API boundaries may choose to employ any of the standardized classification formats. //! //! # Examples //! //! Retrieve jurisdiction from API boundary and validate supported jurisdictions //! ```rust //! use anyhow::{Result, anyhow, format_err}; //! use jurisdiction::{Jurisdiction, Alpha2, Alpha3}; //! use jurisdiction::region::{Region, SubRegion}; //! use std::str::FromStr; //! //! fn supported_jurisdiction(alpha: &str) -> Result<Jurisdiction> { //! let jurisdiction = Jurisdiction::from_str(alpha)?; //! match jurisdiction.alpha2() { //! Alpha2::NO | Alpha2::SE | Alpha2::DK => Ok(jurisdiction), //! _ => Err(format_err!("only scandinavian countries are supported")), //! } //! } //! //! let jurisdiction = supported_jurisdiction("NO").expect("unsupported"); //! //! assert_eq!(jurisdiction, Alpha2::NO); //! assert_eq!(jurisdiction.alpha2(), Alpha2::NO); //! assert_eq!(jurisdiction.alpha2().to_string(), "NO"); //! //! assert_eq!(jurisdiction, Alpha3::NOR); //! assert_eq!(jurisdiction.alpha3(), Alpha3::NOR); //! assert_eq!(jurisdiction.alpha3().to_string(), "NOR"); //! //! assert_eq!(jurisdiction.country_code(), 578); //! //! assert_eq!(jurisdiction.region(), Region::Europe); //! assert_eq!(jurisdiction.sub_region(), SubRegion::NorthernEurope); //! ``` //! //! Construct `Jurisdiction` from string: //! ```rust //! # use jurisdiction::{Jurisdiction, Alpha2}; //! # use std::str::FromStr; //! let jurisdiction = Jurisdiction::from_str("NO"); //! assert!(jurisdiction.is_ok()); //! assert_eq!(jurisdiction.unwrap(), Alpha2::NO); //! ``` //! //! Construct `Jurisdiction` from `Alpha2`/`Alpha3`: //! ```rust //! # use jurisdiction::{Jurisdiction, Alpha2, Alpha3}; //! # use std::str::FromStr; //! let jurisdiction = Jurisdiction::from(Alpha2::NO); //! assert_eq!(jurisdiction, Alpha2::NO); //! //! let jurisdiction = Jurisdiction::from(Alpha3::NOR); //! assert_eq!(jurisdiction, Alpha3::NOR); //! ``` //! //! # Static jurisdiction information //! //! All the static information about a jurisdiction is embedded into the application binary //! through a `lazy_static` hashmap declaration, populated on first use from const definitions. //! This way, the only copy of the definition should reside in the hashmap. //! //! This map is not publicly exported from the crate, only accessible through `Jurisdiction`. //! A `Jurisdiction` object simply contains the reference to the definition within this hashmap, //! making all look-up operations a simple pointer dereference into the statically //! stored item in this global hashmap. //! //! //! # Features //! This crate has the following features: //! //! * `region`: Include the [region] module with region definitions and `Jurisdiction` array //! methods returning the zoning jurisdictions within these regions (`in_*_region`). //! //! //! [UN M49]: https://unstats.un.org/unsd/methodology/m49/overview //! [region]: mod.region.html //! [Jurisdiction]: struct.Jurisdiction.html //! [Alpha2]: enum.Alpha2.html //! [Alpha3]: enum.Alpha3.html mod definition; mod generated; mod jurisdiction; #[cfg(feature = "region")] pub mod region; // Re-export generated modules use crate::generated::alpha; // Publicly export types pub use crate::alpha::{Alpha2, Alpha3}; pub use crate::jurisdiction::Jurisdiction; // Assert properties about crate types use static_assertions as sa; #[cfg(feature = "region")] sa::assert_impl_all!(crate::region::Region: Sized, Send, Sync); #[cfg(feature = "region")] sa::assert_impl_all!(crate::region::SubRegion: Sized, Send, Sync); #[cfg(feature = "region")] sa::assert_impl_all!(crate::region::IntermediateRegion: Sized, Send, Sync); #[cfg(feature = "region")] sa::assert_eq_size!(crate::region::Region, u8); #[cfg(feature = "region")] sa::assert_eq_size!(crate::region::SubRegion, u8); #[cfg(feature = "region")] sa::assert_eq_size!(crate::region::IntermediateRegion, u8); sa::assert_impl_all!(crate::definition::Definition: Sized, Send, Sync); // Assert that the Jurisdiction object is the same size as a simple pointer. sa::assert_eq_size!(Jurisdiction, usize); sa::assert_eq_size!(Alpha2, u8); sa::assert_eq_size!(Alpha3, u8);