error_kind/envelopes/error_envelope.rs
1// =============================================================================
2// USES
3// =============================================================================
4
5// -----------------------------------------------------------------------------
6use crate::details::StaticString;
7use crate::{ErrorContext, ErrorKind};
8use core::fmt::{Debug, Display};
9
10// =============================================================================
11// TRAITS
12// =============================================================================
13
14/// Wraps an [`ErrorKind`] collecting optional debugging information.
15///
16/// For more information about this trait, see the [`envelopes`] module.
17///
18/// [`envelopes`]: crate::envelopes
19pub trait ErrorEnvelope: ErrorContext + Debug + Display {
20 /// The `ErrorKind` contained within this envelope.
21 type Kind: ErrorKind;
22
23 /// How to map one `ErrorKind` to another within this envelope.
24 type Envelope<K: ErrorKind>: ErrorEnvelope;
25
26 /// Converts the underlying error kind into a compatible error kind.
27 fn convert<K>(self) -> Self::Envelope<K>
28 where
29 K: ErrorKind + From<Self::Kind>;
30
31 /// The error kind held within this envelope.
32 fn error_kind(&self) -> Self::Kind;
33
34 /// Constructs a new envelope with the provided `error_kind`.
35 fn new(error_kind: Self::Kind) -> Self;
36
37 /// Constructs a new envelope with the provided `error_kind` and `description`.
38 fn with_description<S>(error_kind: Self::Kind, description: S) -> Self
39 where
40 S: StaticString;
41}