Struct Refined 

pub struct Refined<T, V: Validator<T>> { /* private fields */ }

A value of type T that is guaranteed to satisfy the validator V.

Refined is the heart of the parse-dont-validate pattern: a value is checked once, when the wrapper is constructed, and the type then proves the invariant for the rest of the value’s life. Code that receives a Refined<T, V> never has to re-validate, because a Refined that violates V cannot be constructed through safe code.

The wrapper is #[repr(transparent)] and stores only the value plus a zero-sized marker, so it has the exact same size and layout as T. The guarantee costs nothing at runtime.

There is deliberately no DerefMut and no public field: handing out a &mut T would let a caller mutate the value into an invalid state behind the type’s back. To change a refined value, build a new one with Refined::new (or recover the inner value with Refined::into_inner, change it, and re-wrap it).

Examples

Define a rule, alias a domain type, and construct it:

use type_lib::{Refined, ValidationError, Validator};

struct NonEmpty;

impl<S: AsRef<str> + ?Sized> Validator<S> for NonEmpty {
    type Error = ValidationError;

    fn validate(value: &S) -> Result<(), Self::Error> {
        if value.as_ref().is_empty() {
            Err(ValidationError::new("non_empty", "value must not be empty"))
        } else {
            Ok(())
        }
    }
}

/// A username that can never be empty.
type Username = Refined<String, NonEmpty>;

let user = Username::new("alice".to_owned());
assert!(user.is_ok());
assert!(Username::new(String::new()).is_err());

Read the inner value through Deref, Refined::get, or Refined::into_inner:

let user = Username::new("alice".to_owned())?;

assert_eq!(user.len(), 5);          // via Deref to String
assert_eq!(user.get(), "alice");    // borrow the inner value
assert_eq!(user.into_inner(), "alice"); // take ownership back

Implementations

impl<T, V: Validator<T>> Refined<T, V>

pub fn new(value: T) -> Result<Self, V::Error>

Validates value and, on success, wraps it.

This is the only safe way to construct a Refined, which is what makes the invariant trustworthy everywhere else.

Errors

Returns V::Error when value fails V’s rule. The value is dropped in that case.

Examples

let ok = Refined::<&str, NonEmpty>::new("hi");
assert!(ok.is_ok());

let bad = Refined::<&str, NonEmpty>::new("");
assert!(bad.is_err());

pub fn get(&self) -> &T

Borrows the validated inner value.

The same borrow is also available through Deref, so methods of T can be called directly on a Refined; get is the explicit form for when inference needs a nudge.

Examples

let n = Refined::<i32, AnyI32>::new(7).expect("always valid");
assert_eq!(*n.get(), 7);

pub fn into_inner(self) -> T

Consumes the wrapper and returns the inner value.

Use this when you need to mutate or transform the value: take it out, change it, then re-wrap with Refined::new to re-establish the guarantee.

Examples

let n = Refined::<i32, AnyI32>::new(7).expect("always valid");
assert_eq!(n.into_inner(), 7);

Trait Implementations

impl<T, V: Validator<T>> AsRef<T> for Refined<T, V>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Clone, V: Validator<T>> Clone for Refined<T, V>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug, V: Validator<T>> Debug for Refined<T, V>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, V: Validator<T>> Deref for Refined<T, V>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: Display, V: Validator<T>> Display for Refined<T, V>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Hash, V: Validator<T>> Hash for Refined<T, V>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: Ord, V: Validator<T>> Ord for Refined<T, V>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: PartialEq, V: Validator<T>> PartialEq for Refined<T, V>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialOrd, V: Validator<T>> PartialOrd for Refined<T, V>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: Copy, V: Validator<T>> Copy for Refined<T, V>

impl<T: Eq, V: Validator<T>> Eq for Refined<T, V>