Struct CountryCode 

pub struct CountryCode { /* private fields */ }

A validated ISO 3166-1 alpha-2 country code.

CountryCode is a two byte, Copy, allocation free value object. Once constructed, it is guaranteed to be a code that ISO 3166-1 officially assigns. There is no way to get a CountryCode that has not passed validation.

Internally, the code is stored as two raw uppercase ASCII letters ('A'..='Z').

Constructing a CountryCode

• CountryCode::parse and CountryCode::new accept two character strings, in any ASCII case, trimmed of surrounding whitespace.
• CountryCode::from_bytes accepts exactly two pre normalized uppercase ASCII bytes.
• FromStr and TryFrom<&str> behave like parse, for use in generic code.

All of them run the same validation and return CountryCodeError on failure. See the module level documentation for the validation rules and design rationale.

Implementations

impl CountryCode

pub fn parse(input: &str) -> Result<Self, CountryCodeError>

Parses a country code from a string.

The parser trims surrounding whitespace and folds ASCII letters to uppercase before validation. This is the primary constructor. CountryCode::new, FromStr, and TryFrom<&str> all delegate to it.

Errors

Returns CountryCodeError if the input is empty, does not contain exactly two characters after trimming, contains a non letter character, or names a code that ISO 3166-1 does not officially assign.

Examples

use ftracker_identifiers::CountryCode;

assert!(CountryCode::parse("US").is_ok());
assert!(CountryCode::parse("us").is_ok()); // lowercase is folded automatically
assert!(CountryCode::parse(" BR ").is_ok()); // surrounding whitespace is trimmed
assert!(CountryCode::parse("ZZ").is_err()); // well formed but not assigned

pub fn new(input: &str) -> Result<Self, CountryCodeError>

Alias for CountryCode::parse.

Errors

See CountryCode::parse.

Examples

use ftracker_identifiers::CountryCode;

assert_eq!(CountryCode::new("US"), CountryCode::parse("US"));

pub fn from_bytes(bytes: [u8; 2]) -> Result<Self, CountryCodeError>

Constructs a CountryCode directly from two raw ASCII bytes.

Each byte must already be an uppercase letter. Use CountryCode::parse if the input might contain surrounding whitespace or lowercase letters.

Errors

Returns CountryCodeError under the same conditions as CountryCode::parse, except that length is guaranteed by the [u8; 2] type itself: CountryCodeError::InvalidLength cannot occur here.

Examples

use ftracker_identifiers::CountryCode;

let code = CountryCode::from_bytes(*b"US").unwrap();
assert_eq!(code.as_str(), "US");

// A well formed but unassigned code is rejected just like it would be through `parse`.
assert!(CountryCode::from_bytes(*b"ZZ").is_err());

pub fn as_bytes(&self) -> &[u8; 2]

Returns the two raw ASCII bytes backing this code (for example, b"US").

Examples

use ftracker_identifiers::CountryCode;

let code = CountryCode::parse("US").unwrap();
assert_eq!(code.as_bytes(), b"US");

pub fn as_str(&self) -> &str

Returns the two character country code as a &str.

This never allocates. The bytes are guaranteed to be valid ASCII by construction.

Examples

use ftracker_identifiers::CountryCode;

let code = CountryCode::parse("US").unwrap();
assert_eq!(code.as_str(), "US");

Trait Implementations

impl<'a> Arbitrary<'a> for CountryCode

fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

impl AsRef<[u8]> for CountryCode

fn as_ref(&self) -> &[u8]

Equivalent to CountryCode::as_bytes, borrowed as a slice.

impl AsRef<str> for CountryCode

fn as_ref(&self) -> &str

Equivalent to CountryCode::as_str.

impl Clone for CountryCode

fn clone(&self) -> CountryCode

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for CountryCode

impl Debug for CountryCode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for CountryCode

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for CountryCode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for CountryCode

impl FromStr for CountryCode

fn from_str(s: &str) -> Result<Self, Self::Err>

Delegates to CountryCode::parse, enabling input.parse::<CountryCode>() and use in generic code bounded by FromStr.

type Err = CountryCodeError

The associated error which can be returned from parsing.

impl Hash for CountryCode

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl JsonSchema for CountryCode

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn json_schema(_: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

impl Ord for CountryCode

fn cmp(&self, other: &CountryCode) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for CountryCode

fn eq(&self, other: &CountryCode) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<&str> for CountryCode

fn eq(&self, other: &&str) -> bool

Compares against a string slice by its canonical two letter representation.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<CountryCode> for str

fn eq(&self, other: &CountryCode) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<CountryCode> for &str

fn eq(&self, other: &CountryCode) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<str> for CountryCode

fn eq(&self, other: &str) -> bool

Compares against a string slice by its canonical two letter representation.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for CountryCode

fn partial_cmp(&self, other: &CountryCode) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for CountryCode

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for CountryCode

impl TryFrom<&[u8]> for CountryCode

fn try_from(value: &[u8]) -> Result<Self, Self::Error>

Validates a byte slice as a country code. The slice must be exactly two pre normalized uppercase ASCII bytes; any other length yields CountryCodeError::InvalidLength. Once the length is confirmed, this behaves like CountryCode::from_bytes.

type Error = CountryCodeError

The type returned in the event of a conversion error.

impl TryFrom<&str> for CountryCode

fn try_from(value: &str) -> Result<Self, Self::Error>

Delegates to CountryCode::parse, enabling CountryCode::try_from(input) and use in generic code bounded by TryFrom<&str>.

type Error = CountryCodeError

The type returned in the event of a conversion error.

impl TryFrom<[u8; 2]> for CountryCode

fn try_from(value: [u8; 2]) -> Result<Self, Self::Error>

Delegates to CountryCode::from_bytes. The two bytes must already be pre normalized uppercase ASCII letters.

type Error = CountryCodeError

The type returned in the event of a conversion error.