[−][src]Crate adhocerr
A library for the construction of efficient static/dynamic single use error types per callsite.
[dependencies]
adhocerr = "0.1"
Examples
Creating a root cause error:
use adhocerr::err; fn get_git_root(start: &Path) -> Result<PathBuf, impl Error + 'static> { start .ancestors() .find(|a| a.join(".git").is_dir()) .map(Path::to_owned) .ok_or(err!("Unable to find .git/ in parent directories")) }
Wrapping another Error:
use adhocerr::wrap; fn record_success() -> Result<(), impl Error + 'static> { std::fs::write(".success", "true").map_err(wrap!("Failed to save results of script")) }
Details
This crate provides two primary macros. err!
and wrap!
. The former, err!
,
is used to create ad-hoc error types without a root cause from strings. wrap!
on the other hand is used to create new errors with a source member.
Both of these macros have two versions, and they generate completely code,
depending on whether or not string interopoation (format!
-like code) is used
in the error message. When the error message is a fixed string, the macro
declares a new struct in line that has the string itself inserted into its
Display
implementation. This way no memory is used or allocations made to
hold the error when they are not needed.
For err!
this means that your error type is a Zero Sized Type (ZST), for
wrap!
this means that your Wrapper error is the same size as the original
error you're wrapping.
When runtime interpolation is used and a String
allocation is necessary it
uses pre defined Error types to wrap the String to avoid declaring new types
unnecessarily, but hides them behind an impl Trait boundary.
Expanded
The Expanded version of the example above would look like this:
fn get_git_root(start: &Path) -> Result<PathBuf, impl Error + 'static> { start .ancestors() .find(|a| a.join(".git").is_dir()) .map(Path::to_owned) .ok_or({ #[derive(Debug)] struct AdhocError; impl std::error::Error for AdhocError { fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { None } } impl core::fmt::Display for AdhocError { fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { f.write_str("Unable to find .git/ in parent directories") } } AdhocError }) }
Re-exports
pub use err as format_err; |
Macros
bail | Return an ad-hoc error immediately |
ensure | Return early with an error if a condition is not satisfied. |
err | Create an ad-hoc error type with zero size if none is needed |
wrap | Thinly wrap an error by defining a hidden error type and returning a closure to construct it |