wordval-utils 1.0.8

Wordval utilities: string manipulation, date handling, masking, ID generation, validation, crypto, web helpers, collection tools, retry utilities
Documentation
//! 设计契约式前置校验(design by contract)
//!
//! 校验函数返回类型化的 [`Result`],把「非法参数」在构造期暴露为错误值
//! 而非 panic——底座 crate 对外部输入一律用这套校验,`assert!` 只允许
//! 出现在不可达的内部不变量上。
//!
//! ```rust
//! use wordval_utils::correctness::{check_positive_usize, CorrectnessError};
//!
//! let err = check_positive_usize(0, "capacity").unwrap_err();
//! assert!(matches!(err, CorrectnessError::NotPositive { .. }));
//! ```

use std::fmt;

/// 校验失败的类型化错误
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CorrectnessError {
    /// 谓词不成立
    PredicateFailed {
        /// 失败说明
        message: String,
    },
    /// 字符串为空
    EmptyString {
        /// 参数名
        param: String,
    },
    /// 字符串全为空白
    WhitespaceString {
        /// 参数名
        param: String,
    },
    /// 字符串包含非 ASCII 字符
    NonAsciiString {
        /// 参数名
        param: String,
        /// 实际值
        value: String,
    },
    /// 必须为正的值不是正数
    NotPositive {
        /// 参数名
        param: String,
        /// 实际值
        value: String,
        /// 类型名
        type_name: &'static str,
    },
    /// 数值超出闭区间
    OutOfRange {
        /// 参数名
        param: String,
        /// 实际值
        value: String,
        /// 下界(含)
        min: String,
        /// 上界(含)
        max: String,
    },
}

impl fmt::Display for CorrectnessError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::PredicateFailed { message } => write!(f, "condition failed: {message}"),
            Self::EmptyString { param } => write!(f, "invalid string for '{param}', was empty"),
            Self::WhitespaceString { param } => {
                write!(f, "invalid string for '{param}', was all whitespace")
            }
            Self::NonAsciiString { param, value } => write!(
                f,
                "invalid string for '{param}' contained a non-ASCII char, was '{value}'"
            ),
            Self::NotPositive {
                param,
                value,
                type_name,
            } => write!(f, "invalid {type_name} for '{param}' not positive, was {value}"),
            Self::OutOfRange {
                param,
                value,
                min,
                max,
            } => write!(
                f,
                "invalid value for '{param}' out of range [{min}, {max}], was {value}"
            ),
        }
    }
}

impl std::error::Error for CorrectnessError {}

/// 校验结果别名
pub type CorrectnessResult<T> = Result<T, CorrectnessError>;

/// 校验谓词成立
pub fn check_predicate_true(cond: bool, message: impl Into<String>) -> CorrectnessResult<()> {
    if cond {
        Ok(())
    } else {
        Err(CorrectnessError::PredicateFailed {
            message: message.into(),
        })
    }
}

/// 校验 usize 为正
pub fn check_positive_usize(value: usize, param: &str) -> CorrectnessResult<()> {
    if value > 0 {
        Ok(())
    } else {
        Err(CorrectnessError::NotPositive {
            param: param.to_string(),
            value: value.to_string(),
            type_name: "usize",
        })
    }
}

/// 校验非负整数(u64)为正
pub fn check_positive_u64(value: u64, param: &str) -> CorrectnessResult<()> {
    if value > 0 {
        Ok(())
    } else {
        Err(CorrectnessError::NotPositive {
            param: param.to_string(),
            value: value.to_string(),
            type_name: "u64",
        })
    }
}

/// 校验字符串非空
pub fn check_non_empty_str(value: &str, param: &str) -> CorrectnessResult<()> {
    if value.is_empty() {
        Err(CorrectnessError::EmptyString {
            param: param.to_string(),
        })
    } else {
        Ok(())
    }
}

/// 校验字符串非空且非全空白
pub fn check_not_blank_str(value: &str, param: &str) -> CorrectnessResult<()> {
    check_non_empty_str(value, param)?;
    if value.trim().is_empty() {
        Err(CorrectnessError::WhitespaceString {
            param: param.to_string(),
        })
    } else {
        Ok(())
    }
}

/// 校验字符串全为 ASCII
pub fn check_ascii_str(value: &str, param: &str) -> CorrectnessResult<()> {
    if value.is_ascii() {
        Ok(())
    } else {
        Err(CorrectnessError::NonAsciiString {
            param: param.to_string(),
            value: value.to_string(),
        })
    }
}

/// 校验 f64 落在闭区间 `[min, max]`
pub fn check_in_range_f64(value: f64, min: f64, max: f64, param: &str) -> CorrectnessResult<()> {
    if value.is_nan() || value < min || value > max {
        Err(CorrectnessError::OutOfRange {
            param: param.to_string(),
            value: value.to_string(),
            min: min.to_string(),
            max: max.to_string(),
        })
    } else {
        Ok(())
    }
}

/// 校验 usize 落在闭区间 `[min, max]`
pub fn check_in_range_usize(value: usize, min: usize, max: usize, param: &str) -> CorrectnessResult<()> {
    if value < min || value > max {
        Err(CorrectnessError::OutOfRange {
            param: param.to_string(),
            value: value.to_string(),
            min: min.to_string(),
            max: max.to_string(),
        })
    } else {
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn predicate_true_ok_and_err() {
        assert!(check_predicate_true(true, "x").is_ok());
        let e = check_predicate_true(false, "delay must be non-zero").unwrap_err();
        assert_eq!(e.to_string(), "condition failed: delay must be non-zero");
    }

    #[test]
    fn positive_checks() {
        assert!(check_positive_usize(1, "n").is_ok());
        assert!(matches!(
            check_positive_usize(0, "capacity"),
            Err(CorrectnessError::NotPositive { .. })
        ));
        assert!(check_positive_u64(7, "jitter").is_ok());
        assert!(check_positive_u64(0, "jitter").is_err());
    }

    #[test]
    fn string_checks() {
        assert!(check_non_empty_str("a", "s").is_ok());
        assert!(check_non_empty_str("", "s").is_err());
        assert!(check_not_blank_str("  ", "s").is_err());
        assert!(check_not_blank_str(" a ", "s").is_ok());
        assert!(check_ascii_str("abc*", "s").is_ok());
        assert!(check_ascii_str("中文", "s").is_err());
    }

    #[test]
    fn range_checks() {
        assert!(check_in_range_f64(2.0, 1.0, 100.0, "factor").is_ok());
        assert!(check_in_range_f64(150.0, 1.0, 100.0, "factor").is_err());
        // NaN 必须被拒绝
        assert!(check_in_range_f64(f64::NAN, 1.0, 100.0, "factor").is_err());
        assert!(check_in_range_usize(5, 1, 5, "n").is_ok());
        assert!(check_in_range_usize(6, 1, 5, "n").is_err());
    }
}