nutype

The newtype with guarantees.

Nutype is a proc macro that allows adding extra constraints like sanitization and validation to the regular newtype pattern. The generated code makes it impossible to instantiate a value without passing the checks. It works this way even with serde deserialization.

• Quick start
• Inner types (String | Integer | Float | Decimal | Other)
• Custom (sanitizers | validators | errors)
• Deriving traits
• Constants
• Recipes
• Constructor visibility
• Breaking constraints with new_unchecked
• Feature Flags
• Support Ukrainian military forces
• Similar projects

Quick start

…

For more please see:

• Examples
• Tests

Inner types

Available sanitizers, validators, and derivable traits are determined by the inner type, which falls into the following categories:

• String
• Integer (u8, u16,u32, u64, u128, i8, i16, i32, i64, i128, usize, isize)
• Float (f32, f64)
• Decimal (rust_decimal::Decimal, requires the rust_decimal feature)
• Anything else

String

At the moment the string inner type supports only String (owned) type.

String sanitizers

String validators

Regex validation

Requirements:

• regex feature of nutype is enabled.
• You have to explicitly include regex as a dependency.

There are a number of ways you can use regex.

A regular expression can be defined right in place:

#[nutype(validate(regex = "^[0-9]{3}-[0-9]{3}$"))]
pub struct PhoneNumber(String);

or it can be defined with std::sync::LazyLock:

use regex::Regex;

static PHONE_NUMBER_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new("^[0-9]{3}-[0-9]{3}$").unwrap());

#[nutype(validate(regex = PHONE_NUMBER_REGEX))]
pub struct PhoneNumber(String);

or it can be defined with lazy_static:

use lazy_static::lazy_static;
use regex::Regex;

lazy_static! {
    static ref PHONE_NUMBER_REGEX: Regex = Regex::new("^[0-9]{3}-[0-9]{3}$").unwrap();
}

#[nutype(validate(regex = PHONE_NUMBER_REGEX))]
pub struct PhoneNumber(String);

or once_cell:

use once_cell::sync::Lazy;
use regex::Regex;

static PHONE_NUMBER_REGEX: Lazy<Regex> =
    Lazy::new(|| Regex::new("[0-9]{3}-[0-9]{3}$").unwrap());

#[nutype(validate(regex = PHONE_NUMBER_REGEX))]
pub struct PhoneNumber(String);

String derivable traits

The following traits can be derived for a string-based type: Debug, Clone, PartialEq, Eq, PartialOrd, Ord, FromStr, AsRef, Deref, From, TryFrom, Into, Hash, Borrow, Display, Default, Serialize, Deserialize.

Integer

The integer inner types are: u8, u16,u32, u64, u128, i8, i16, i32, i64, i128, usize, isize.

Integer sanitizers

Integer validators

Integer derivable traits

The following traits can be derived for an integer-based type: Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, FromStr, AsRef, Deref, Into, From, TryFrom, Hash, Borrow, Display, Default, Serialize, Deserialize.

Float

The float inner types are: f32, f64.

Float sanitizers

Float validators

Float derivable traits

The following traits can be derived for a float-based type: Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, FromStr, AsRef, Deref, Into, From, TryFrom, Hash, Borrow, Display, Default, Serialize, Deserialize.

It's also possible to derive Eq and Ord if the validation rules guarantee that NaN is excluded. This can be done applying by finite validation. For example:

#[nutype(
    validate(finite),
    derive(PartialEq, Eq, PartialOrd, Ord),
)]
struct Size(f64);

Decimal

The rust_decimal::Decimal type is supported as an inner type behind the rust_decimal feature flag.

Requirements:

• The rust_decimal feature of nutype is enabled.
• You have to explicitly include rust_decimal as a dependency of your crate.
• For derive(Arbitrary) you also need rust_decimal's rust-fuzz feature, and for derive(Serialize, Deserialize) its serde feature.

All three spellings of the inner type are detected:

struct A(Decimal);                  // assumes `use rust_decimal::Decimal;`
struct B(rust_decimal::Decimal);
struct C(::rust_decimal::Decimal);

Example:

use nutype::nutype;
use rust_decimal::Decimal;

#[nutype(
    validate(greater_or_equal = 0, less_or_equal = 100),  // bare literals, no dec!() needed
    derive(Debug, Clone, Copy, PartialEq, PartialOrd, Display),
)]
pub struct Percentage(Decimal);

Note the asymmetry: bounds in the attribute are written as bare literals (parsed at compile time via rust_decimal's FromStr), while values passed to try_new() are real Decimals, so you typically reach for dec!(...) or Decimal::from(...) there.

Decimal sanitizers

Decimal validators