Expand description
Annotate unwraps as manually checked
The safe_unwrap
macros allows unwrapping and annotating that the unwrap
will never fail.
An example:
#[macro_use]
extern crate safe_unwrap;
fn main() {
let res = Some(42);
// we know that unwrapping res will never fail, so it is safe to call unwrap
let val = safe_unwrap!("is constant value", res);
assert_eq!(val, 42);
}
In release builds, safe_unwrap!(expr)
is equivalent to expr.unwrap()
;
in debug builds, expect()
will be called with a message indicating that
the assumed invariant has been violated.
Alternative, for Result
and Option
types, you can risk a small bit of
overhead in exchange for nicer syntax:
extern crate safe_unwrap;
use safe_unwrap::SafeUnwrap;
fn main() {
let res = Some(42);
// works only for Result and Option types
let val = res.safe_unwrap("is constant value");
assert_eq!(val, 42);
#[cfg(feature = "std")]
{
// With `std`, two additional methods are available.
let val = res.unwrap_or_abort("is constant value");
assert_eq!(val, 42);
let val = res.unwrap_or_exit("is constant value");
assert_eq!(val, 42);
}
}
The semantics of .safe_unwrap
are otherwise the same as the
safe_unwrap!
macro. The tradeoff here is that you are at the mercy of the
LLVM optimizer to remove the unused static string "is constant value"
from the resulting executable (often works in release mode).
§std
support
By default, no_std
is supported. With the std
feature, SafeUnwrap
has
two additional methods, which require the standard library. They work the
same way as safe_unwrap
, but:
unwrap_or_abort
aborts the process instead of panicking.unwrap_or_exit
exits with code 1 instead of panicking.