pub trait Error: Error + ErrorContext {
type Kind: ErrorKind;
// Required method
fn error_kind(&self) -> Self::Kind;
}Expand description
An error that contains an associated ErrorKind.
Error types are expected to be fairly simple structs, usually containing only a single field.
use error_kind::{Error, ErrorKind};
#[derive(Clone, Copy, Debug, ErrorKind)]
enum MyErrorKind {
Variant,
}
#[derive(Debug, Error)]
struct MyError(MyErrorKind);If you plan on having many different kinds of errors within a crate, you may wish to make your type generic over the kind of error.
use error_kind::{Error, ErrorKind};
#[derive(Debug, Error)]
struct MyError<K: ErrorKind>(K);Your error kind can also be wrapped in envelopes to collect additional
error information.
§Traits Implemented
The derive macro helps us out a lot here, implementing the following traits:
DisplayErrorContextError(bothcoreanderror_kind)From(via#[error(domains(...))])TrivialError
You can disable any of these by using the #[error(disable(...))] attribute
(e.g. #[error(disable(From, Display))]).
You can force-hide certain trait implementations from documentation by using
the #[error(hidden(...))] attribute (e.g.
#[error(hidden(TrivialError))]).
#[derive(Debug, Error)]
#[error(disable(Display, TrivialError))]
#[error(hidden(core::error::Error))]
struct NoDisplayExample(MyErrorKind);
// Though, now you have to implement `Display` yourself.
// This is required since `Display` is a supertrait of `Error`.
impl std::fmt::Display for NoDisplayExample {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
// ...
}
}§Error Domains
If your crate defines any ErrorDomains that you would like your error to
be able to convert between, register them with #[error(domains(...))].
This allows for…
- Conversion from
MyError<MyErrorKind>toMyError<_>for any registeredErrorDomainwhich containsMyErrorKind. - Conversion from
MyError<MyErrorDomain>toMyError<_>for any registeredErrorDomainwhich contains a superset of allErrorKinds present inMyErrorDomain.
#[derive(Clone, Copy, Debug, ErrorDomain, PartialEq)]
enum MyErrorDomain1 {
Kind1(MyErrorKind1),
Kind2(MyErrorKind2),
// ...
}
#[derive(Clone, Copy, Debug, ErrorDomain, PartialEq)]
#[error(domains(MyErrorDomain1))] // <- Suggest a subset domain
enum MyErrorDomain2 {
Kind1(MyErrorKind1),
Kind2(MyErrorKind2),
Kind3(MyErrorKind3),
// ...
}
#[derive(Debug, Error, Eq, PartialEq)]
#[error(domains(MyErrorDomain1, MyErrorDomain2))] // Because of this...
struct MyError<K: ErrorKind>(K);
// ... these conversions work as expected!
assert_eq!(
MyError(MyErrorDomain1::Kind1(MyErrorKind1::Variant)),
From::from(MyError(MyErrorKind1::Variant)),
);
assert_eq!(
MyError(MyErrorDomain2::Kind1(MyErrorKind1::Variant)),
From::from(MyError(MyErrorKind1::Variant)),
);
// ... and perhaps surprisingly, this also works!
assert_eq!(
MyError(MyErrorDomain2::Kind1(MyErrorKind1::Variant)),
From::from(MyError(MyErrorDomain1::Kind1(MyErrorKind1::Variant))),
);Learn More: While you don’t need to understand how this works, if you are curious to learn, see the
IsNotandMatchIntotraits.
§Trivial Errors
The TrivialError trait is used to power the err! macro.
If the error type only contains one field (the error kind), it’s said to be trivial. In these cases, we can easily say how to properly construct it!
use error_kind::{Error, ErrorKind, TrivialError};
#[derive(Clone, Copy, Debug, ErrorKind)]
enum MyErrorKind {
Variant,
}
#[derive(Debug, Error)]
struct MyError(MyErrorKind);
// Allowed via the `TrivialError` trait.
let _ = MyError::new(MyErrorKind::Variant);However, if more than one field is present, the derive macro is not certain
that taking the Default for the other values is the right thing to do.
As such, it will simply avoid implementing this trait.
use error_kind::{Error, ErrorKind, TrivialError};
#[derive(Clone, Copy, Debug, ErrorKind)]
enum MyErrorKind {
Variant,
}
#[derive(Debug, Error)]
struct MyError(#[error_kind]MyErrorKind, u32);
// Not allowed, because of multiple fields. :(
let _ = MyError::new(MyErrorKind::Variant);In those cases, if you know better, you can implement TrivialError
manually.
§Recommendation: Provide an error_kind Function
Though users can depend on this trait to acquire the underlying error kind, it’s more ergonomic to simply provide a function on the error type itself.
The Error derive macro will not implement this for you!
use error_kind::{Error, ErrorKind};
#[derive(Copy, Clone, Debug, ErrorKind)]
pub enum MyErrorKind {
Error1,
}
#[derive(Debug, Error)]
pub struct MyError {
error_kind: MyErrorKind,
}
impl MyError {
// We have to implement this manually, if we want it.
pub fn error_kind(&self) -> MyErrorKind {
self.error_kind
}
}§Examples
This type supports named and unnamed type constructions.
#[derive(Debug, Error)]
struct NamedExample {
error_kind: MyErrorKind,
}
#[derive(Debug, Error)]
struct UnnamedExample(MyErrorKind);If multiple fields are present, one field must be marked as the field which
contains our ErrorKind (using #[error_kind]).
#[derive(Debug, Error)]
struct MyError(u32, #[error_kind]MyErrorKind, i16);Your error type is allowed to be generic over the ErrorKind. It’s highly
recommended that you add a bounds to the type parameter, however.
#[derive(Debug, Error)]
struct MyError<K: ErrorKind> {
field_a: u32,
#[error_kind]
field_b: K,
field_c: i16,
}Required Associated Types§
Required Methods§
Sourcefn error_kind(&self) -> Self::Kind
fn error_kind(&self) -> Self::Kind
Returns the ErrorKind contained within this error.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".