Nutype 0.5.0 with custom errors

[greyblake]

Changes

• [FEATURE] Added support for custom error types and validation functions via the error and with attributes.
• [BREAKING] Replaced lazy_static with std::sync::LazyLock for regex validation. This requires Rust 1.80 or higher and may cause compilation issues on older Rust versions due to the use of std::sync::LazyLock. If upgrading Rust isn't an option, you can still use lazy_static explicitly as a workaround.
• [BREAKING] The fallible ::new() constructor has been fully replaced by ::try_new().

Highlights

Custom errors

Previously, custom validation logic in nutype could be achieved by passing a predicate attribute, as shown below:

#[nutype(validate(predicate = |n| n % 2 == 1))]
struct OddNumber(i64);

This would automatically generate a simple error type:

enum OddNumberError {
    PredicateViolated,
}

However, this approach often lacked flexibility. Many users needed more detailed error handling. For example, some users wanted to attach additional information to errors or provide more descriptive error messages. Others preferred to use a single error type across their application, but found it cumbersome to map very specific errors to a more general error type.

To address these needs, nutype now introduces the with attribute for custom validation functions and the error attribute for specifying custom error types:

#[nutype(
    validate(with = validate_name, error = NameError),
    derive(Debug, AsRef, PartialEq),
)]
struct Name(String);

// Custom error type. It can also implement std::error::Error.
#[derive(Debug, PartialEq)]
enum NameError {
    TooShort,
    TooLong,
}

// Custom validation function
fn validate_name(name: &str) -> Result<(), NameError> {
    let count = name.encode_utf16().count();
    if count < 3 {
        Err(NameError::TooShort)
    } else if count > 10 {
        Err(NameError::TooLong)
    } else {
        Ok(())
    }
}

With this enhancement, users have full control over the error type and how errors are constructed during validation, making the error handling process more powerful and adaptable to different use cases.

Transition from fallible::new() to ::try_new()

In version 0.4.3, the fallible ::new() constructor was deprecated but still available. Now, it has been fully replaced by ::try_new(). For example, to initialize a Name from the previous example:

let name = Name::try_new("Anton").unwrap();

This change ensures a more consistent and explicit error-handling approach when creating instances.
Note that ::new() is still used as a non-fallible constructor if there a newtype has no validation.

---

This discussion was created from the release Nutype 0.5.0 with custom errors.