Struct Because 

pub struct Because { /* private fields */ }

A report on its way out of the library, with the chain a caller can walk.

The report is still there whole - Deref reaches it, and so do facts::all and a {:?} of it - and beside it sits the same thing as an ordinary error chain, built the first time somebody asks and not before. A failure that nobody looks into costs the report it was already carrying and nothing more.

Implementations

impl Because

pub fn new(why: Report<StorageError>) -> Self

pub fn into_report(self) -> Report<StorageError>

The report, for the plumbing under the boundary.

pub fn caused(&self) -> Option<&Caused>

What is under the outermost context, as an error chain.

pub fn explain(&self) -> String

The whole report as a string, facts and all.

For a caller who is handing this to anyhow and wants everything in one place: .context(why.explain()).

Methods from Deref<Target = Report<StorageError>>

pub fn current_frame(&self) -> &Frame

Returns the direct current frames of this report.

To get an iterator over the topological sorting of all frames refer to frames().

This is not the same as Report::current_context, this function gets the underlying frames that make up this report, while Report::current_context traverses the stack of frames to find the current context. A Report and be made up of multiple Frames, which stack on top of each other. Considering PrintableA<PrintableA<Context>>, Report::current_frame will return the “outer” layer PrintableA, while Report::current_context will return the underlying Error (the current type parameter of this Report).

A report can be made up of multiple stacks of frames and builds a “group” of them, this can be achieved through first calling Report::expand and then either using Extend or Report::push.

pub fn current_context(&self) -> &C

where C: Send + Sync + 'static,

Returns the current context of the Report.

If the user want to get the latest context, current_context can be called. If the user wants to handle the error, the context can then be used to directly access the context’s type. This is only possible for the latest context as the Report does not have multiple generics as this would either require variadic generics or a workaround like tuple-list.

This is one disadvantage of the library in comparison to plain Errors, as in these cases, all context types are known.

Example

use std::io;

fn read_file(path: impl AsRef<Path>) -> Result<String, Report<io::Error>> {
    ...
}

let report = read_file("test.txt").unwrap_err();
let io_error = report.current_context();
assert_eq!(io_error.kind(), io::ErrorKind::NotFound);

pub fn as_error(&self) -> &(impl Error + Send + Sync + 'static)

where C: 'static,

Returns this Report as an Error.

pub fn frames(&self) -> Frames<'_>

Returns an iterator over the Frame stack of the report.

pub fn request_ref<T>(&self) -> RequestRef<'_, T>

where T: Send + Sync + 'static + ?Sized,

Creates an iterator of references of type T that have been attached or that are provided by Error objects.

pub fn request_value<T>(&self) -> RequestValue<'_, T>

where T: Send + Sync + 'static,

Creates an iterator of values of type T that have been attached or that are provided by Error objects.

pub fn contains<T>(&self) -> bool

where T: Send + Sync + 'static,

Returns if T is the type held by any frame inside of the report.

T could either be an attachment or a Error context.

Example

fn read_file(path: impl AsRef<Path>) -> Result<String, Report<io::Error>> {
    ...
}

let report = read_file("test.txt").unwrap_err();
assert!(report.contains::<io::Error>());

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: Send + Sync + 'static,

Searches the frame stack for a context provider T and returns the most recent context found.

T can either be an attachment or a new Error context.

Example

use std::io;

fn read_file(path: impl AsRef<Path>) -> Result<String, Report<io::Error>> {
    ...
}

let report = read_file("test.txt").unwrap_err();
let io_error = report.downcast_ref::<io::Error>().unwrap();
assert_eq!(io_error.kind(), io::ErrorKind::NotFound);

Trait Implementations

impl Debug for Because

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

Formats the value using the given formatter.

impl Deref for Because

type Target = Report<StorageError>

The resulting type after dereferencing.

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

Dereferences the value.

impl Display for Because

What the report says, which is its outermost context. The chain under it is caused and the whole of it is explain.

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

Formats the value using the given formatter.

impl From<Report<StorageError>> for Because

fn from(why: Report<StorageError>) -> Self

Converts to this type from the input type.