Enum validated::Validated

pub enum Validated<T, E> {
    Good(T),
    Fail(NEVec<E>),
}

Similar to Result, but cumulative in its error type.

Error weaving

Consider that when using collect in a “Traversable” way to pull a single Result out of an Iterator containing many Results, it will fail on the first Err and short-circuit the iteration. This is suboptimal if we wish to be made aware of every failure that (would have) occurred.

use validated::Validated::{self, Good, Fail};
use nonempty_collections::*;

let v = vec![Ok(1), Ok(2), Ok(3)];
let r: Validated<Vec<u32>, &str> = Good(vec![1, 2, 3]);
assert_eq!(r, v.into_iter().collect());

let v = vec![Ok(1), Err("Oh!"), Ok(2), Err("No!"), Ok(3)];
let r: Validated<Vec<u32>, &str> = Fail(nev!["Oh!", "No!"]);
assert_eq!(r, v.into_iter().collect());

Naturally iterators of Validated values can be collected in a similar way:

use validated::Validated::{self, Good, Fail};
use nonempty_collections::*;

let v = vec![Good(1), Good(2), Good(3)];
let r: Validated<Vec<u32>, &str> = Good(vec![1, 2, 3]);
assert_eq!(r, v.into_iter().collect());

let v = vec![Good(1), Validated::fail("No!"), Good(3), Validated::fail("Ack!")];
let r: Validated<Vec<u32>, &str> = Fail(nev!["No!", "Ack!"]);
assert_eq!(r, v.into_iter().collect());

Mapping composite results

This type also provides mapN methods, which are surprisingly missing on Option and Result.

use validated::Validated::{self, Good, Fail};

let v: Validated<u32, &str> = Good(1).map3(Good(2), Good(3), |a, b, c| a + b + c);
assert_eq!(v, Good(6));

For Validated in particular these are quite useful, as a meaningful and_then cannot be written for it.

Formally, Validated is not a Monad, but it is an Applicative Functor.

Variants

Good(T)

Analogous to Result::Ok.

Fail(NEVec<E>)

Analogous to Result::Err, except that the error type is cumulative.

Implementations

impl<T, E> Validated<T, E>

pub fn fail(e: E) -> Validated<T, E>

Fail with the given error.

pub fn as_mut(&mut self) -> Validated<&mut T, &mut E>

Converts from &mut Validated<T, E> to Validated<&mut T, &mut E>.

Note: In the case of Fail, a new Vec of references is allocated.

pub fn as_ref(&self) -> Validated<&T, &E>

Converts from &Validated<T, E> to Validated<&T, &E>.

Produces a new Validated, containing references to the original, leaving the original in place.

Note: In the case of Fail, a new Vec of references is allocated.

pub fn expect(self, msg: &str) -> T

Returns the contained Good value, consuming self.

Panics

Panics with a custom message if self is actually the Fail variant.

pub fn is_good(&self) -> bool

Was a given Validated operation completely successful?

pub fn is_fail(&self) -> bool

Did a given Validated operation have at least one failure?

pub fn iter(&self) -> Iter<'_, T>

Returns an iterator over the possibly contained value.

The iterator yields one value if the result is Good, otherwise nothing.

pub fn iter_mut(&mut self) -> IterMut<'_, T>

Returns a mutable iterator over the possibly contained value.

The iterator yields one value if the result is Good, otherwise nothing.

pub fn map<U, F>(self, op: F) -> Validated<U, E>

where F: FnOnce(T) -> U,

Applies a function to the T value of a Good variant, or leaves a Fail variant untouched.

use validated::Validated::{self, Good, Fail};

let v: Validated<u32, &str> = Good(1);
let r = v.map(|n| n * 2);
assert_eq!(r, Good(2));

let v: Validated<u32, &str> = Validated::fail("No!");
let r = v.map(|n| n * 2);
assert_eq!(r, Validated::fail("No!"));

pub fn map_err<R, F>(self, op: F) -> Validated<T, R>

where F: FnOnce(NEVec<E>) -> NEVec<R>,

Applies a function to the Vec<E> of a Fail variant, or leaves a Good variant untouched.

pub fn map2<U, Z, F>(self, vu: Validated<U, E>, f: F) -> Validated<Z, E>

where F: FnOnce(T, U) -> Z,

Maps a function over two Validated, but only if both are of the Good variant. If both failed, then their errors are concatenated.

use validated::Validated::{self, Good, Fail};

let v: Validated<u32, &str> = Good(1).map2(Good(2), |a, b| a + b);
assert_eq!(v, Good(3));

let v: Validated<u32, &str> = Good(1).map2(Validated::fail("No!"), |a, b: u32| a + b);
assert_eq!(v, Validated::fail("No!"));

pub fn map3<U, V, Z, F>( self, vu: Validated<U, E>, vv: Validated<V, E>, f: F ) -> Validated<Z, E>

where F: FnOnce(T, U, V) -> Z,

Maps a function over three Validated, but only if all three are of the Good variant. If any failed, then their errors are concatenated.

use validated::Validated::{self, Good, Fail};

let v: Validated<u32, &str> = Good(1).map3(Good(2), Good(3), |a, b, c| a + b + c);
assert_eq!(v, Good(6));

let v: Validated<u32, &str> = Good(1).map3(Good(2), Validated::fail("No!"), |a, b, c: u32| a + b + c);
assert_eq!(v, Validated::fail("No!"));

pub fn map4<U, V, W, Z, F>( self, vu: Validated<U, E>, vv: Validated<V, E>, vw: Validated<W, E>, f: F ) -> Validated<Z, E>

where F: FnOnce(T, U, V, W) -> Z,

Maps a function over four Validated, but only if all four are of the Good variant. If any failed, then their errors are concatenated.

pub fn ok(self) -> Result<T, NEVec<E>>

Converts self into a Result.

pub fn unwrap(self) -> T

Returns the contained Good value, consuming self.

Examples

use validated::Validated;

let v: Validated<u32, &str> = Validated::Good(1);
assert_eq!(v.unwrap(), 1);

Panics

Panics if self is actually the Fail variant.

pub fn unwrap_or(self, default: T) -> T

Returns the contained Good value or a provided default.

Arguments passed to unwrap_or are eagerly evaluated; if you are passing the result of a function call, it is recommended to use Validated::unwrap_or_else instead.

Examples

use validated::Validated;

let v: Validated<u32, &str> = Validated::Good(1);
assert_eq!(v.unwrap_or(2), 1);

let v: Validated<u32, &str> = Validated::fail("Oh no!");
assert_eq!(v.unwrap_or(2), 2);

pub fn unwrap_or_else<F>(self, op: F) -> T

where F: FnOnce(NEVec<E>) -> T,

Returns the contained Good value or computes it from a closure.

impl<T: Default, E> Validated<T, E>

pub fn unwrap_or_default(self) -> T

Returns the contained Good value or the default for T.

impl<T: Deref, E> Validated<T, E>

pub fn as_deref(&self) -> Validated<&T::Target, &E>

Like Result::as_deref.

impl<T: DerefMut, E> Validated<T, E>

pub fn as_deref_mut(&mut self) -> Validated<&mut T::Target, &mut E>

Like Result::as_deref_mut.

Trait Implementations

impl<T: Clone, E: Clone> Clone for Validated<T, E>

fn clone(&self) -> Validated<T, E>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug, E: Debug> Debug for Validated<T, E>

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

Formats the value using the given formatter.

impl<T, E> From<Result<T, E>> for Validated<T, E>

fn from(r: Result<T, E>) -> Self

Converts to this type from the input type.

impl<T, U, E> FromIterator<Result<T, E>> for Validated<U, E>

where U: FromIterator<T>,

fn from_iter<I: IntoIterator<Item = Result<T, E>>>(iter: I) -> Self

Creates a value from an iterator.

impl<T, U, E> FromIterator<Validated<T, E>> for Validated<U, E>

where U: FromIterator<T>,

fn from_iter<I: IntoIterator<Item = Validated<T, E>>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: Hash, E: Hash> Hash for Validated<T, E>

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<'a, T, E> IntoIterator for &'a Validated<T, E>

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Iter<'a, T>

Creates an iterator from a value.

impl<'a, T, E> IntoIterator for &'a mut Validated<T, E>

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IterMut<'a, T>

Creates an iterator from a value.

impl<T, E> IntoIterator for Validated<T, E>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Ord, E: Ord> Ord for Validated<T, E>

fn cmp(&self, other: &Validated<T, E>) -> 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 + PartialOrd,

Restrict a value to a certain interval.

impl<T: PartialEq, E: PartialEq> PartialEq for Validated<T, E>

fn eq(&self, other: &Validated<T, E>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<T: PartialOrd, E: PartialOrd> PartialOrd for Validated<T, E>

fn partial_cmp(&self, other: &Validated<T, E>) -> Option<Ordering>

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<T, U, E> Sum<Result<U, E>> for Validated<T, E>

where T: Sum<U>,

use validated::Validated;

let ns: Validated<u32, ()> = [Ok(1), Ok(2), Ok(3)].into_iter().sum();
assert_eq!(Validated::Good(6), ns);

fn sum<I>(iter: I) -> Self

where I: Iterator<Item = Result<U, E>>,

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl<T, U, E> Sum<Validated<U, E>> for Validated<T, E>

where T: Sum<U>,

fn sum<I>(iter: I) -> Self

where I: Iterator<Item = Validated<U, E>>,

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl<T: Eq, E: Eq> Eq for Validated<T, E>

impl<T, E> StructuralPartialEq for Validated<T, E>