Struct status::Status

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

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();
}

Methods

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

pub fn new<U>(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"));
}

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

Add a public error.

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

Add an internal error.

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(()),
        }
    }
}

Important traits for Chain<'a>

impl<'a> Iterator for Chain<'a> type Item = &'a (dyn Error + 'static);

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
}

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
}

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);
    }
}

pub fn into_err<T>(self) -> Result<T, Self>

Convenience for returning an error.

Trait Implementations

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

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

Formats the value using the given formatter.

impl<K: Debug + Kind, C: Debug + Context> Debug for Status<K, C>

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

Formats the value using the given formatter.

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

type Target = C

The resulting type after dereferencing.

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

Dereferences the value.

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

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

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

fn cause(&self) -> Option<&dyn Error>

Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

The lower-level cause of this error, if any.

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

The lower-level source of this error, if any.

fn description(&self) -> &str

This method is soft-deprecated.

fn backtrace(&self) -> Option<&Backtrace>

🔬 This is a nightly-only experimental API. (backtrace)

Returns a stack backtrace, if available, of where this error ocurred.