Struct Status

Source

pub struct Status<K: Kind = Unkind, C: Context = AdhocContext> { /* private fields */ }

Expand description

A container for use in Result<_, Status>..

Goals:

Easy crate inter-op while maintaining programmatic processing.
User-friendly without losing helpful debug information.

Note: this is optimized for the happy-path. When failing frequently inside of an inner loop, consider using your Kind to convey your status.

§Example

use status::Kind;

#[derive(Copy, Clone, Debug, derive_more::Display)]
enum ErrorKind {
  #[display(fmt = "Failed to read file")]
  Read,
  #[display(fmt = "Failed to parse")]
  Parse,
}
type Status = status::Status<ErrorKind>;
type Result<T, E = Status> = std::result::Result<T, E>;

fn read_file() -> Result<()> {
    return ErrorKind::Read.into_err();
}

Implementations§

Source §

impl<K: Kind, C: Context> Status<K, C>

Source

pub fn new(kind: U) -> Self
where U: Into<K>,

Create a container for the specified status Kind.

§Example

fn read_file() -> Result<(), status::Status> {
    return Err(status::Status::new("Failed to read file"));
}

Source

pub fn with_source<E>(self, error: E) -> Self
where E: Error + 'static,

Add a public error.

Source

pub fn with_internal<E>(self, error: E) -> Self
where E: Error + 'static,

Add an internal error.

Source

pub fn context_with<F>(self, context: F) -> Self
where F: Fn(C) -> C,

Extend the Context.

Source

pub fn context(&self) -> &C

Access the Context for programmatic usage.

Source

pub fn kind(&self) -> K

Programmatic identifier for which error occurred.

§Example

#[derive(Copy, Clone, Debug, derive_more::Display)]
enum ErrorKind {
  #[display(fmt = "Failed to read file")]
  Read,
  #[display(fmt = "Failed to parse")]
  Parse,
}

fn read_file() -> Result<()> {
}

fn process_file() -> Result<()> {
    match read_file() {
        Ok(_) => Ok(()),
        Err(e) => match e.kind() {
          ErrorKind::Read => Err(e),
          ErrorKind::Parse => Ok(()),
        }
    }
}

Source

pub fn sources(&self) -> Chain<'_> ⓘ

An iterator for the chain of sources.

When debugging, to display internal sources, run Status::into_internal.

§Example

use status::Status;
use std::io;

pub fn underlying_io_error_kind(error: &Status) -> Option<io::ErrorKind> {
    for cause in error.sources() {
        if let Some(io_error) = cause.downcast_ref::<io::Error>() {
            return Some(io_error.kind());
        }
    }
    None
}

Source

pub fn root_source(&self) -> Option<&(dyn Error + 'static)>

The lowest level cause of this error — this error’s cause’s cause’s cause etc.

The root cause is the last error in the iterator produced by sources().

§Example

use status::Status;
use std::io;

pub fn underlying_io_error_kind(error: &Status) -> Option<io::ErrorKind> {
    let cause = error.root_source()?;
    if let Some(io_error) = cause.downcast_ref::<io::Error>() {
        return Some(io_error.kind());
    }
    None
}

Source

pub fn into_internal(self) -> InternalStatus<K, C>

View of Status, exposing implementation details.

Error::source and InternalStatus::sources are for debug / display purposes only and relying on them programmatically is likely to break across minor releases.

§Example

fn display_status(status: status::Status) {
    if std::env::var("DEBUG").as_ref().map(|s| s.as_ref()).unwrap_or("0") == "1" {
        let status = status.into_internal();
        println!("{}", status);
    } else {
        println!("{}", status);
    }
}