garde

Garde uses the typestate pattern to ensure that a value has been successfully validated before it is used in your application.

1. Wrap your raw data in Unvalidated<T>.
2. Call .validate() or .validate_with(ctx) on the Unvalidated<T> instance.
3. If successful, you receive a Valid<T> wrapper.

The only way to obtain a Valid<T> is through the Unvalidated::validate methods, providing a type-level guarantee that the data has passed validation rules.

use garde::{Unvalidated, Valid};

// 1. Wrap raw data
let unvalidated = Unvalidated::new(my_data);

// 2. Validate
match unvalidated.validate() {
    Ok(valid_data) => {
        // 3. Use Valid<T>
        let data = valid_data.into_inner();
        // ...
    }
    Err(report) => {
        // Handle errors
    }
}

Pattern validation relies on two main abstractions:

1. Matcher: A trait for types that can check if a string matches a pattern. regex::Regex implements Matcher (when the regex feature is enabled). Matcher is also implemented for std::sync::LazyLock<T> and once_cell::sync::Lazy<T> where T: Matcher.
2. Pattern: A trait implemented for the types being validated (the "haystack"). This trait allows the field to be checked against a Matcher.

When validate is called, the Pattern implementation calls is_match on the provided Matcher using the field's value as the input string.

The #[garde(pattern(...))] rule allows you to validate a field against a pattern. You can provide a regular expression as a string literal (requires the regex feature) or an expression that implements the Matcher trait.

Important Performance Note: The expression provided to pattern(...) is evaluated every time validate is called. To avoid expensive re-computation (like re-parsing a regex), use std::sync::LazyLock or once_cell::sync::Lazy to wrap your matcher.

#[derive(garde::Validate)]
struct Test {
    #[garde(pattern(r"[a-zA-Z0-9][a-zA-Z0-9_]+"))]
    v: String,
}

To prevent expensive pattern re-evaluation during every validation call, wrap your Matcher (such as a regex::Regex) in a lazy initialization type like std::sync::LazyLock or once_cell::sync::Lazy. This ensures the pattern is compiled only once.

use std::sync::LazyLock;
use regex::Regex;

static LAZY_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"[a-zA-Z0-9][a-zA-Z0-9_]+").unwrap());

#[derive(garde::Validate)]
struct Test {
    #[garde(pattern(LAZY_RE))]
    v: String,
}

You can validate IP addresses in your structs using the #[garde(ip)] attribute. This rule works on any type that implements the Ip trait. By default, it has a blanket implementation for any type that implements garde::rules::AsStr (such as String or &str).

#[derive(garde::Validate)]
struct Test {
    #[garde(ip)]
    v: String,
}

You can validate email addresses in your structs by using the #[garde(email)] attribute on a field. This works for any type that implements the Email trait, which includes all types implementing garde::rules::AsStr (like String or &str) and Option<T> where T implements Email.

#[derive(garde::Validate)]
struct Test {
    #[garde(email)]
    v: String,
}

If you have a custom type and want to use Garde's byte length validation rules, implement the HasBytes trait for your type. This allows your type to be used with the Bytes validation logic.

use garde::rules::length::bytes::HasBytes;

struct MyData([u8; 10]);

impl HasBytes for MyData {
    fn num_bytes(&self) -> usize {
        self.0.len()
    }
}

The Error struct represents a single validation failure message.

• Use Error::new(message) to create a new error. The message can be any type that implements ToCompactString (like &str or String).
• Use .message() to retrieve the error message as a &str.

let err = Error::new("must be at least 5 characters long");
println!("Error: {}", err.message());