Expand description
Envelopes an ErrorKind to collect optional diagnostic information.
Describedcollects an error description.Diagnosticcollects all possible diagnostics information.Locatedcollects the location the error occurred.
These types do not compose, so you cannot Described<Located<K>>.
Using an envelope is optional, ErrorKind by itself just ignores all diagnostic information.
§About Envelopes
The ErrorEnvelope types exist to wrap an ErrorKind, allowing it to collect additional information littered around the codebase during error propagation.
This allows us to control how detailed our error message will be without changing other parts of the code!
use error_kind::{error, Err, Error, ErrorKind};
#[derive(Copy, Clone, Debug, ErrorKind, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub enum MyErrorKind {
SomeSimpleError,
}
#[derive(Clone, Debug, Error)]
pub struct MyError {
error: error_kind::envelopes::Diagnostic<MyErrorKind>,
}
#[error("calling some_function with fail={fail}")]
fn some_function(fail: bool) -> Result<(), MyError> {
if fail {
return Err!(
MyErrorKind::SomeSimpleError,
"asked to fail explicitly",
);
}
Ok(())
}
fn main() {
let err = some_function(true).unwrap_err();
println!("error: {err}");
}Since the envelope is Diagnostic, all the additional context is captured and presented!
error: some simple error: asked to fail explicitly
with context
╰─ calling some_function with fail=trueThe Diagnostic envelope even collects source lines and backtraces, which can be printed when formatting with the alternate error format ("{error:#}").
This system takes advantage of the heavy optimizations of the Rust compiler.
If an envelope type doesn’t capture some piece of debugging information, it will aggressively inline to suggest to the calling code that the data is not needed.
§Printing Locations and Backtraces
The default display format for any envelopes provided by this crate work in the following way:
"{error}"will print all collected user-relevant information.- Will Print: description, context, and error kind.
- Will Omit: backtraces and source locations.
"{error:#}"will print all collected information.- Will Print: Everything.
- Will Omit: Nothing.
fn main() {
let err = some_function(true).unwrap_err();
// Backtrace & locations printed (if captured)!
println!("error: {err:#}");
}§Accessing Internal Information
ErrorEnvelopes explicitly don’t grant access to the information they wrap.
You should always construct your code in a way in which the information passed into the error envelope is not necessary. It’s only there to help understand why a failure occurred.
As such, there’s no way to inspect any of this “diagnostic” information.
Structs§
- Described
alloc - An envelope that collects error descriptions
- Diagnostic
alloc - An envelope that collects detailed diagnostic information.
- Located
- An envelope that collects error locations
Traits§
- Error
Envelope - Wraps an
ErrorKindcollecting optional debugging information.