ch-parsing 0.2.0

Typed input parsing with structured, locale-neutral errors
Documentation
use std::borrow::Cow;
use std::fmt;

use crate::error::{ParseError, ParseErrorCode, ParseResult};

const ACCOUNT_HASH_LENGTH: usize = 8;
const ACCOUNT_HASH_CHARACTER_CLASS: &str = "ascii_uppercase_alphanumeric";

/// Validated account hash containing eight uppercase ASCII letters or digits.
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct AccountHash(String);

impl AccountHash {
    /// Trims and validates an account hash.
    ///
    /// # Errors
    ///
    /// Returns [`ParseErrorCode::InvalidFormat`] for `field` when the value is
    /// not exactly eight uppercase ASCII letters or digits.
    pub fn parse(raw: &str, field: impl Into<Cow<'static, str>>) -> ParseResult<Self> {
        let trimmed = raw.trim();
        if trimmed.len() != ACCOUNT_HASH_LENGTH
            || !trimmed
                .bytes()
                .all(|byte| byte.is_ascii_uppercase() || byte.is_ascii_digit())
        {
            return Err(ParseError::for_field(field, ParseErrorCode::InvalidFormat)
                .with_parameter("expected_length", ACCOUNT_HASH_LENGTH.to_string())
                .with_parameter("actual_length", trimmed.chars().count().to_string())
                .with_parameter("allowed_characters", ACCOUNT_HASH_CHARACTER_CLASS));
        }

        Ok(Self(trimmed.to_owned()))
    }

    /// Returns the validated hash as a borrowed string slice.
    #[must_use]
    pub fn as_str(&self) -> &str {
        self.0.as_str()
    }

    /// Consumes the hash and returns its owned string representation.
    #[must_use]
    pub fn into_inner(self) -> String {
        self.0
    }
}

impl AsRef<str> for AccountHash {
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl fmt::Display for AccountHash {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(self.as_str())
    }
}

impl From<AccountHash> for String {
    fn from(hash: AccountHash) -> Self {
        hash.into_inner()
    }
}

#[cfg(test)]
mod tests {
    use super::AccountHash;
    use crate::error::ParseErrorCode;

    #[test]
    fn parses_and_normalizes_valid_account_hashes() {
        for raw in ["ABCD1234", "  ABCD1234  ", "00000000", "ZZZZZZZZ"] {
            let parsed = AccountHash::parse(raw, "account_hash").unwrap();
            assert_eq!(parsed.as_str(), raw.trim());
            assert_eq!(parsed.to_string(), raw.trim());
            assert_eq!(parsed.as_ref(), raw.trim());
        }
    }

    #[test]
    fn rejects_every_invalid_character_class_and_length_case() {
        for raw in [
            "",
            "ABC123",
            "ABCDEFGHI",
            "abcd1234",
            "ABCD-123",
            "ABCD_123",
            "ÄBCD1234",
            "ABCD 123",
        ] {
            let error = AccountHash::parse(raw, "account_hash").unwrap_err();
            assert_eq!(error.code(), ParseErrorCode::InvalidFormat, "{raw:?}");
            assert_eq!(error.field(), Some("account_hash"));
            assert_eq!(error.parameter("expected_length"), Some("8"));
            assert_eq!(
                error.parameter("allowed_characters"),
                Some("ascii_uppercase_alphanumeric")
            );
        }
    }

    #[test]
    fn reports_scalar_length_without_echoing_rejected_input() {
        let error = AccountHash::parse("ÄBCD1234", "identifier").unwrap_err();
        assert_eq!(error.parameter("actual_length"), Some("8"));
        assert!(
            error
                .parameters()
                .iter()
                .all(|parameter| parameter.value() != "ÄBCD1234")
        );
    }
}