Trait WriteErrorList

pub trait WriteErrorList<E>: Sized + Sealed<E> {
    // Required methods
    fn push(&mut self, error: E);
    fn subwriter<'sub, SubMapFn, SubErr: 'sub>(
        &'sub mut self,
        map_fn: SubMapFn,
    ) -> impl WriteErrorList<SubErr> + 'sub
       where SubMapFn: FnOnce(ErrorList<SubErr>) -> E + 'sub;

    // Provided methods
    fn sublist<SubMapFn, SubErr>(
        &mut self,
        map_fn: SubMapFn,
    ) -> Sublist<'_, SubErr, SubMapFn, Self, E>
       where SubMapFn: FnOnce(ErrorList<SubErr>) -> E { ... }
    fn finish(self) { ... }
}

Types that are capable of having errors and sublists of errors pushed onto them

This is the main trait that allows a function to record a list of non-fatal errors it encounters during its execution. Generally, the WriteErrorList::push method will be used when such an error occurs to record the error and any relevant information.

Often, a function will want to call a subfunction and add any non-fatal errors encountered to its own list of errors. There are 2 strategies it could use:

1. Let the subfunction directly push onto its error list For functions that are at the same level of abstraction and use the same error type, it might make the most sense for them to just share an error list. In this case, simply pass a mutable reference to the error list. For any type that implements this trait, a mutable reference to it implements the trait too. This allows a single function to be a composition of a bunch of functions that each share a single flat error list.

2. Map the subfunction’s error list to the caller For a subfunction that is at a different level of abstraction than the caller and uses its own error type, this makes the most sense; consume the subfunction’s entire error list and store it as a single error of the caller’s higher-level error type. Of course, those subfunctions may implement this same strategy for subfunctions they call, creating a hierarchy of errors.

   In this case, call the WriteErrorList::subwriter() function as a parameter to the subfunction. If you need to manipulate the list after the subfunction has returned, instead call WriteErrorList::sublist and pass a mutable reference as a parameter.

Function parameters should always prefer to take an object by this trait, and should rarely take parameters as concrete types like ErrorList or Sublist. Doing so would prevent callers from being able to decide what strategy they want to use to merge the subfunction’s errors with its own, and would also prevent them from using the DontCare call if they want to opt out of receiving non-fatal error information.

Passing by this trait may also help prevent logic errors: Directly passing a Sublist allows the subfunction to query the contents of the list it’s passed. Functions may incorrectly rely on the fact that they are always passed an empty list, and will suddenly break if that assumption doesn’t hold.

Required Methods

fn push(&mut self, error: E)

Add an error to the list of errors

fn subwriter<'sub, SubMapFn, SubErr: 'sub>( &'sub mut self, map_fn: SubMapFn, ) -> impl WriteErrorList<SubErr> + 'sub

where SubMapFn: FnOnce(ErrorList<SubErr>) -> E + 'sub,

Create a new mapping error writer with this as its parent

Creates a error writer for use by a subfunction. When the subfunction is finished, either by explicitly calling WriteErrorList::finish or by letting it drop, the list of errors it has written using WriteErrorList::push will be passed as an ErrorList<SubErr> to the given map_fn, which is expected to map it to our error type, E.

Use of this function should always be preferred to WriteErrorList::sublist when the caller does not need to inspect or manipulate the list returned by the subfunction and simply wants to pass it upward to its own caller, as this function will pass forward alternate strategies for collecting the errors, like DontCare (which turns WriteErrorList::push into a no-op). In constrast, WriteErrorList::sublist actually materializes a list that will collect all the errors of all the lists below it, even if the caller above it passed in a DontCare.

Provided Methods

fn sublist<SubMapFn, SubErr>( &mut self, map_fn: SubMapFn, ) -> Sublist<'_, SubErr, SubMapFn, Self, E>

where SubMapFn: FnOnce(ErrorList<SubErr>) -> E,

Start a new error list with this error list as its parent

This works in a very similar manner to WriteErrorList::subwriter, but it materializes an actual concrete Sublist type. This function should only be used if the function needs to be able to inspect or manipulate the errors returned by the subfunction, as it always collects all errors written by the subfunction’s call graph. Otherwise, WriteErrorList::subwriter should be used.

fn finish(self)

Finish this error list

This doesn’t normally need to be called, as the Drop implementation will take care of all the details of cleaning up and ensuring that sublists are mapped up to their parent.

This is mostly useful when a caller maintains a binding to a subfunction’s error list and passes it by mutable reference instead of by value. Before the caller can continue to use its own error list, the sublist must release its exclusive reference.

This function simply calls drop(), but it’s just a bit more clear about the intent.

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.

Implementations on Foreign Types

impl<E, T: WriteErrorList<E>> WriteErrorList<E> for &mut T

fn push(&mut self, error: E)

fn subwriter<'sub, SubMapFn, SubErr: 'sub>( &'sub mut self, map_fn: SubMapFn, ) -> impl WriteErrorList<SubErr> + 'sub

where SubMapFn: FnOnce(ErrorList<SubErr>) -> E + 'sub,

Implementors

impl<'a, E, MapFn, Parent, ParentErr> WriteErrorList<E> for Sublist<'a, E, MapFn, Parent, ParentErr>

where MapFn: FnOnce(ErrorList<E>) -> ParentErr, Parent: WriteErrorList<ParentErr>,

impl<E> WriteErrorList<E> for DontCare

impl<E> WriteErrorList<E> for ErrorOccurred

impl<E> WriteErrorList<E> for ErrorList<E>