Struct Error

pub struct Error<Kind> { /* private fields */ }
Expand description

The generic error type for the Astral engine.

Error can be created with crafted error messages and a particular value of Kind and optionally with a arbitrary error payload.

It is useful but not necessary, that Kind implements Debug and Display so std::error::Error is implemented.

§Example

use std::fmt::{self, Debug, Display, Formatter};
use std::error::Error as StdError;

use astral::error::Error;

#[derive(Debug, PartialEq)]
enum MyErrorKind {
    Variant,
}

impl Display for MyErrorKind {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        Debug::fmt(self, f)
    }
}

let my_error = Error::new(MyErrorKind::Variant, "oh no!");

let my_error2 = Error::new(MyErrorKind::Variant, my_error);

assert_eq!(*my_error2.kind(), MyErrorKind::Variant);
assert!(my_error2.source().is_none());

Implementations§

§

impl<Kind> Error<Kind>

pub fn new<E>(kind: Kind, error: E) -> Self
where E: Into<Box<dyn Error + Send + Sync>>,

Creates a new error from a known kind of error as well as an arbitrary error payload. The error argument is an arbitrary payload which will be contained in this Error. The resulting error don’t have a source error returned by Error::source.

§Example
use std::error::Error as StdError;

use astral::error::Error;

let my_error = Error::new(MyErrorKind::Variant, "oh no!");

let my_error2 = Error::new(MyErrorKind::Variant, my_error);

assert!(my_error2.source().is_none());

pub fn chained<E, S>(kind: Kind, error: E, source: S) -> Self
where E: Into<Box<dyn Error + Send + Sync>>, S: Into<Box<dyn Error + Send + Sync>>,

Creates a new error from a known kind of error as well as an arbitrary error payload and keeps another payload as source error.

The error argument is an arbitrary payload which will be contained in this Error. The source argument is an error, which will be returned by Error::source

§Example
use std::error::Error as StdError;

use astral::error::Error;

let my_error = Error::new(MyErrorKind::Variant, "oh no!");

let my_error2 = Error::chained(MyErrorKind::Variant, "failed!", my_error);

assert_eq!(my_error2.source()?.to_string(), "oh no!");

pub fn get_ref(&self) -> Option<&(dyn Error + Send + Sync + 'static)>

Returns a reference to the inner error wrapped by this error (if any).

If this Error was constructed via new or chained then this function will return Some, otherwise it will return None.

§Examples
use astral::error::Error;

#[derive(Debug)]
enum MyErrorKind {
	Variant,
}

fn print_error<Kind>(err: &Error<Kind>) {
    if let Some(inner_err) = err.get_ref() {
        println!("Inner error: {:?}", inner_err);
    } else {
        println!("No inner error");
    }
}

fn main() {
    // Will print "Inner error: Variant".
    print_error(&Error::new(MyErrorKind::Variant, "oh no!"));
}

pub fn get_mut(&mut self) -> Option<&mut (dyn Error + Send + Sync + 'static)>

Returns a mutable reference to the inner error wrapped by this error (if any).

If this Error was constructed via new or chained then this function will return Some, otherwise it will return None.

§Examples
use std::{error, fmt};
use std::fmt::Display;

use astral::error::Error;

#[derive(Debug)]
struct MyError {
    v: String,
}

impl MyError {
    fn new() -> MyError {
        MyError {
            v: "oh no!".to_string()
        }
    }

    fn change_message(&mut self, new_message: &str) {
        self.v = new_message.to_string();
    }
}

impl error::Error for MyError {}

impl Display for MyError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "MyError: {}", &self.v)
    }
}

fn change_error<Kind>(mut err: Error<Kind>) -> Error<Kind> {
    if let Some(inner_err) = err.get_mut() {
        inner_err.downcast_mut::<MyError>().unwrap().change_message("I've been changed!");
    }
    err
}

#[derive(Debug)]
enum MyErrorKind {
	Variant,
}

fn print_error<Kind>(err: &Error<Kind>) {
    if let Some(inner_err) = err.get_ref() {
        println!("Inner error: {}", inner_err);
    } else {
        println!("No inner error");
    }
}

fn main() {
    // Will print "Inner error: ...".
    print_error(&change_error(Error::new(MyErrorKind::Variant, MyError::new())));
}

pub fn into_inner(self) -> Option<Box<dyn Error + Send + Sync>>

Consumes the Error, returning its inner error (if any).

If this Error was constructed via new or chained then this function will return Some, otherwise it will return None.

§Example
use astral::error::Error;

let my_error = Error::new(MyErrorKind::Variant, "oh no!");

let my_error2 = Error::new(MyErrorKind::Variant, my_error);

assert_eq!(my_error2.into_inner()?.to_string(), "oh no!");

pub fn kind(&self) -> &Kind

Returns the corresponding Kind for this error.

§Example
use astral::error::Error;

#[derive(Debug, PartialEq)]
enum MyErrorKind {
    Variant,
}

let my_error = Error::new(MyErrorKind::Variant, "oh no!");
assert_eq!(*my_error.kind(), MyErrorKind::Variant);

Trait Implementations§

§

impl<Kind> Debug for Error<Kind>
where Kind: Debug,

§

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

Formats the value using the given formatter. Read more
§

impl<Kind> Display for Error<Kind>
where Kind: Display,

§

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

Formats the value using the given formatter. Read more
§

impl<Kind> Error for Error<Kind>
where Kind: Debug + Display,

§

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

Returns the lower-level source of this error, if any. Read more
1.0.0 · Source§

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()
1.0.0 · Source§

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

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting
Source§

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)
Provides type-based access to context intended for error reports. Read more
§

impl<Kind> From<Kind> for Error<Kind>

§

fn from(kind: Kind) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

§

impl<Kind> Freeze for Error<Kind>
where Kind: Freeze,

§

impl<Kind> !RefUnwindSafe for Error<Kind>

§

impl<Kind> Send for Error<Kind>
where Kind: Send,

§

impl<Kind> Sync for Error<Kind>
where Kind: Sync,

§

impl<Kind> Unpin for Error<Kind>
where Kind: Unpin,

§

impl<Kind> !UnwindSafe for Error<Kind>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<!> for T

Source§

fn from(t: !) -> T

Converts to this type from the input type.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.