Skip to main content

ErrorDomain

Trait ErrorDomain 

Source
pub trait ErrorDomain: ErrorKind { }
Expand description

A marker trait for a type that denotes a domain of possible error kinds.

These types are expected to be very simple enums, with the following rules:

  • Each field must contain a single unnamed field.
  • The unnamed field must contain an ErrorKind type.
  • Each type may only be used once within the enum.

§Display Formatting

The derive macro for this trait will automatically implement Display for you. The default process is to break the variant name into words, lowercase it, and then separate the words by spaces.

Then, the error domain will print alongside its value: “{domain}: {value}”.

#[derive(Clone, Copy, Debug, ErrorDomain)]
enum ParseErrorDomain {
    Io(IoErrorKind),        // Prints "io: {0}"
    Parse(ParseErrorKind),  // Prints "parse: {0}"
    // ...
}

If you don’t like a particular display format, you can change it with the #[error(...)] attribute on a variant.

#[derive(Clone, Copy, Debug, ErrorDomain)]
enum ParseErrorDomain {
    Io(IoErrorKind),        // Prints "io: {0}"
    #[error("custom: {0}")]
    Parse(ParseErrorKind),  // Prints "custom: {0}"
    // ...
}

The {0} will expand to the value in the unnamed field.

§Purpose

An ErrorDomain allows us to compose multiple different error kinds together.

This allows us to maintain the following design principles:

  1. Avoid deeply-nested enums to keep error kinds small and efficient.
  2. Ensure that subset type can unambiguously convert into any given superset ErrorDomain.

The second point is the most important, because it’ll allow for very ergonomic usage of your error types. Thanks to this rule, from conversion for Error<SubsetDomain> can be implemented for Error<SupersetDomain>.

#[derive(Clone, Copy, Debug, ErrorKind, PartialEq)]
enum IoErrorKind {
    BadFileDescriptor,
    FileNotFound,
    // ...
}

#[derive(Clone, Copy, Debug, ErrorKind, PartialEq)]
enum ParseErrorKind {
    InvalidFormat,
    UnexpectedEndOfData,
    // ...
}

#[derive(Clone, Copy, Debug, ErrorDomain, PartialEq)]
enum ParseErrorDomain {
    Io(IoErrorKind),
    Parse(ParseErrorKind),
    // ...
}

// Thanks to the rules of `ErrorDomain`, this is possible!
assert_eq!(
    ParseErrorDomain::Io(IoErrorKind::FileNotFound),
    From::from(IoErrorKind::FileNotFound),
);

This also works across ErrorDomain types as well.

#[derive(Clone, Copy, Debug, ErrorKind, PartialEq)]
enum LogicErrorKind {
    InvalidOperation,
    TimedOut,
    // ...
}

#[derive(Clone, Copy, Debug, ErrorDomain, PartialEq)]
#[error(domains(ParseErrorDomain))] // <- List subset domains here.
enum ProcessingErrorDomain {
    Io(IoErrorKind),
    Logic(LogicErrorKind),
    Parse(ParseErrorKind),
    // ...
}

// Thanks to the rules of `ErrorDomain`, this is possible!
assert_eq!(
    ProcessingErrorDomain::Io(IoErrorKind::FileNotFound),
    From::from(ParseErrorDomain::Io(IoErrorKind::FileNotFound)),
);

Learn More: While you don’t need to understand how this works, if you are curious to learn, see the IsNot and MatchInto traits.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§