error_kind/traits/trivial_error.rs
1// =============================================================================
2// USES
3// =============================================================================
4
5// -----------------------------------------------------------------------------
6use crate::Error;
7use crate::details::StaticString;
8
9// =============================================================================
10// TRAITS
11// =============================================================================
12
13/// An error that is able to be constructed trivially from an [`ErrorKind`].
14///
15/// This trait powers the [`err!`] macro, allowing you to use type inference to
16/// construct an error based solely on a provided `ErrorKind`.
17///
18/// It's usually implemented for you by the `Error` derive macro. But there
19/// are times when the derive macro cannot automatically implement this.
20///
21/// See the [`Error`] trait documentation for more information.
22///
23/// [`ErrorKind`]: crate::ErrorKind
24/// [`err!`]: crate::err
25pub trait TrivialError: Error {
26 /// Construct a new error with the provided `error_kind`.
27 fn new(error_kind: Self::Kind) -> Self;
28
29 /// Construct a new error with the provided `error_kind` and `description`.
30 ///
31 /// The description will only be captured if your error type is configured
32 /// to collect description information. See [`envelopes`] for more details.
33 ///
34 /// [`envelopes`]: crate::envelopes
35 fn with_description<S>(error_kind: Self::Kind, description: S) -> Self
36 where
37 S: StaticString;
38}