Trait ErrorStash 

pub trait ErrorStash<E, W>: ErrorStashInternal<E, W>
where
    E: Debug + Display + 'static,
    W: Send + 'static,
{
    // Required methods
    fn to_result<T>(self, closure: impl FnOnce() -> T) -> Result<T, W>;
    fn to_error(self) -> Option<W>;

    // Provided methods
    fn is_empty(&self) -> bool { ... }
    fn len(&self) -> usize { ... }
    fn ok(&self) -> Option<()> { ... }
    fn check_fmt(&mut self, condition: bool, args: Arguments<'_>) -> &mut Self
       where E: From<String> { ... }
    fn fail_unless_empty(&mut self) -> Result<(), W> { ... }
}

Collects child errors, then emits a wrapper error if any were collected.

ErrorStashes are useful when validating data where multiple independent errors may occur, and you want to report all of them together rather than failing fast on the first error.

E is the child error type that implements std::fmt::Debug. W is the wrapper error type that implements std::error::Error.

Terminal methods

ErrorStash methods that can return the wrapper error type W are called “terminal methods” because callers are expected to call them with the ? operator and return from the calling function if any errors were collected. For example, fail_unless_empty will return early from the calling function if any errors were collected (and continue execution otherwise).

The terminal methods of error stashes are:

• to_result
• to_error
• [fail_now][ErrorStash::fail_now]
• fail_unless_empty

These methods will reset the stash to an empty state if any errors were collected prior to the call. This generally doesn’t matter if they’re called with ? because the calling function will return and the stash will no longer be needed. However, if you call a terminal method without ?, be aware that following the call the stash will be empty- if it is a stash type that takes additional configuration, like the summary message in [BoxedStash], that configuration will also be reset to its default state.

Required Methods

fn to_result<T>(self, closure: impl FnOnce() -> T) -> Result<T, W>

If no errors have been collected, calls the closure and returns Ok(result). Otherwise, consumes the collected errors and returns Err(W).

fn to_error(self) -> Option<W>

If no errors have been collected, returns None. Otherwise, consumes the collected errors and returns Some(W).

Provided Methods

fn is_empty(&self) -> bool

Returns true if no errors have been collected.

let mut stash = BoxedStash::new();
assert!(stash.is_empty());
stash.push("an error");
assert!(!stash.is_empty());

fn len(&self) -> usize

Returns the number of collected errors.

let mut stash = BoxedStash::new();
assert_eq!(stash.len(), 0);
stash.push("an error");
stash.push("another error");
assert_eq!(stash.len(), 2);

fn ok(&self) -> Option<()>

If no errors have been collected, returns Some(()). Otherwise, returns None.

This method is designed for use with the ? operator in functions that return Option<T>, such as functions that have their ErrorStash passed into them and don’t return their errors directly. It can be called at any time with ? to return from the function if any errors have been collected.

fn check_fmt(&mut self, condition: bool, args: Arguments<'_>) -> &mut Self

where E: From<String>,

If the condition is false, adds a formatted error to the stash. Otherwise, does nothing.

This method is like check, but allows you to provide a dynamically generated error value via the format_args! macro, as long as this stash’s error type implements From<String>. This is always true for BoxedStash, but for TypedStash it depends on the error type used.

For performance, the formatting is only evaluated if the condition is false.

Example

let mut stash = BoxedStash::new();
let value = 42;
stash.check_fmt(value > 100, format_args!("value {} is not greater than 100", value));
assert_eq!(stash.len(), 1);
// `errors()` is not part of the public trait surface, so consume the stash
// and inspect the returned wrapper to check the formatted message.
let wrapper = stash.to_error().unwrap();
let vec = wrapper.to_vec();
assert_eq!(vec[0].to_string(), "value 42 is not greater than 100");

If you want to return immediately if the condition is false, chain a call to [fail_unless_empty] after this method. For example:

let mut stash = BoxedStash::new();
let value = 42;
stash.check_fmt(value > 100, format_args!("value {} is not greater than 100", value))
     .fail_unless_empty()?;

fn fail_unless_empty(&mut self) -> Result<(), W>

If no errors have been collected, returns Ok(()). Otherwise, consumes the collected errors and returns Err(W).

Typically, you will call this method with the ? operator, returning early from the current function if any errors were collected, and continuing execution otherwise. If you call this method without ?, be aware that this stash’s collected errors will be consumed and it will always be empty after this call.

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 ErrorStash<Box<dyn Error + Sync + Send>, ErrorList<Box<dyn Error + Sync + Send>>> for BoxedStash

impl<E, W> ErrorStash<E, W> for TypedStash<E, W>

where E: Debug + Display + Send + 'static, W: Error + Send + 'static,