Trait Ensure

pub trait Ensure<T, E, F, Factory>: Iterator<Item = Result<T, E>> + Sized
where
    F: Fn(&T) -> bool,
    Factory: Fn(usize, T) -> E,
{
    // Provided method
    fn ensure(
        self,
        test: F,
        factory: Factory,
    ) -> EnsureIter<Self, T, E, F, Factory> { ... }
}

Provided Methods

fn ensure(self, test: F, factory: Factory) -> EnsureIter<Self, T, E, F, Factory>

Applies a boolean test too each element, and fails the iteration if any element violates the constraint.

ensure(validation, factory) is the general validation tool, it takes a boolean test as an argument and applies it to each of the elements in the iteration. If the test returns true, the element is wrapped in Ok(element). Otherwise, factory gets called on it and the index of the error.

Values already wrapped in Result::Err are ignored.

Examples

Basic usage:

use validiter::Ensure;
#[derive(Debug, PartialEq)]
struct Odd(usize, i32);
let mut iter = (0..=3).map(|v| Ok(v)).ensure(|i| i % 2 == 0, |i, v| Odd(i, v));
 
assert_eq!(iter.next(), Some(Ok(0)));
assert_eq!(iter.next(), Some(Err(Odd(1, 1))));
assert_eq!(iter.next(), Some(Ok(2)));
assert_eq!(iter.next(), Some(Err(Odd(3, 3))));

You might want to chain ensure validations to create a more complex test:

 enum IterError {
    Odd,
    NonPositive
 }
  
 let mut iter = (0..=3)
             .map(|v| Ok(v))
             .ensure(|i| i % 2 == 0, |_, _| IterError::Odd)
             .ensure(|i| *i > 0, |_, _| IterError::NonPositive);
 
 assert_eq!(iter.next(), Some(Err(IterError::NonPositive)));
 assert_eq!(iter.next(), Some(Err(IterError::Odd)));
 assert_eq!(iter.next(), Some(Ok(2)));
 assert_eq!(iter.next(), Some(Err(IterError::Odd)));

ensure ignores error elements:

 
let mut iter = [Err(0)]
                    .into_iter()
                    .ensure(|i| *i == 0, |_, v| v);

assert_eq!(iter.next(), Some(Err(0)));

Err(ValidErr::Invalid(element))

Examples found in repository

examples/numeric_csv_parsing.rs (line 39)

fn main() {
    // In this example we will use the 'cast_errs' method to
    // create a 'Vec<Vec<f64>>' collection, while ensuring
    // the mathematical validity if this collection as a numerical
    // matrix. To exercise the 'ensure' adapter, we'll force all
    // elements to be non-negative as well

    // Here we define the errors we expect to encounter in
    // the parsing process:
    #[derive(Debug)]
    enum MatParseErr {
        NotAFloat(usize, usize, ParseFloatError),
        NoColumns(usize),
        Negative(usize, usize, f64),
        NoRows,
        JaggedArray(usize, Vec<f64>, usize, usize),
    }

    // this is a CSV format str, with 2 rows and 2 columns
    let csv = "1.2, 3.0
                4.2, 0.5";

    // we'll use iterator methods on the CSV to build an actual matrix over f64
    let mat = csv
        .lines()
        .enumerate()
        .map(|(i, line)| {
            line.split(",")
                .map(|s| s.trim())
                .enumerate()
                .map(|(j, s)| {
                    s.parse::<f64>()
                        .map_err(|parse_err| MatParseErr::NotAFloat(i, j, parse_err))
                })
                .ensure(|val| *val >= 0.0, |j, val| MatParseErr::Negative(i, j, val))
                .at_least(1, |_| MatParseErr::NoColumns(i))
                .collect::<Result<Vec<f64>, MatParseErr>>()
        })
        .at_least(1, |_| MatParseErr::NoRows)
        .const_over(
            |vec| vec.len(),
            |i, vec, len, expected_len| MatParseErr::JaggedArray(i, vec, len, *expected_len),
        )
        .collect::<Result<Vec<_>, _>>();

    match mat {
        Ok(mat) => {
            assert_eq!(mat, vec![vec![1.2, 3.0], vec![4.2, 0.5]]);
            println!("{mat:?}")
        }
        Err(mperr) => match mperr {
            MatParseErr::NotAFloat(i, j, err) => println!("Got {err} at pos [{i}, {j}]"),
            MatParseErr::NoColumns(i) => {
                println!("Row {i} is without any data, which would force the matrix to be empty")
            }
            MatParseErr::Negative(i, j, val) => {
                println!("value {val} at pos [{i}, {j}] is negative")
            }
            MatParseErr::NoRows => println!("There are no rows in the matrix"),
            MatParseErr::JaggedArray(i, _vec, len, expected_len) => {
                println!("Row {i} has len {len}, when all rows should have length {expected_len}")
            }
        },
    }
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<I, T, E, F, Factory> Ensure<T, E, F, Factory> for I

where I: Iterator<Item = Result<T, E>>, F: Fn(&T) -> bool, Factory: Fn(usize, T) -> E,