macro_rules! err {
($error_kind:expr $(,)?) => { ... };
($error_kind:expr, $($arg:tt)*) => { ... };
}Expand description
Uses type inference to construct trivial error types with a provided ErrorKind.
Calling this macro is equivalent to calling one of the following trait functions:
TrivialError::new($error_kind.into())TrivialError::with_description($error_kind.into(), format!($args))
In Rust, this can compile as long as the left-hand side of the expression has an explicit type (the variable we’re binding it to, or the result of a function).
In order to use this macro, your error type needs to implement the TrivialError trait. This is automatically implemented for you if your error type is derived with only a single field (see Error for details on this).
§no-alloc
If the alloc feature is not enabled for this crate, the description information will be checked using format_args!, but it will not be used (since we cannot allocate a string).
This ensures you can still write err!(error_kind, "description: {}", value), regardless of how your crate is configured.
This is one of the benefits of using a macro here. You can litter around details that you compile out of a production library.
The idea being that a library will only incur the cost if:
- It’s possible to allocate (feature = “alloc”)
- Your error collects the description (see
envelopes)
§Examples
This macro is intended to be used for the really common pattern of returning with an error from a function.
use error_kind::err;
fn example() -> Result<(), MyError> {
// ..
if !some_check {
return Err(err!(MyErrorKind::Variant, "description"));
}
Ok(())
}For added convenience, an Err! macro is also exported, which wraps even the Err(_) part of this operation.
use error_kind::Err;
fn example() -> Result<(), MyError> {
// ..
if !some_check {
return Err!(MyErrorKind::Variant, "description");
}
Ok(())
}If you have an aversion to macros, or you don’t want to be able to compile-out formatting based on alloc support, you can just call the constructors directly.
use error_kind::TrivialError;
fn example() -> Result<(), MyError> {
// ..
if !some_check {
return Err(MyError::with_description(
MyErrorKind::Variant,
"description",
));
}
Ok(())
}