An unwrap! macro for Rust.

The crate provides two macros, unwrap! and unwrap_err!. The former can be used to unwrap values of type Result or Option (or any type that implements VerboseUnwrap) and is comparable to calling unwrap(). The latter can be used to unwrap an error from a Result (or any type that implements VerboseUnwrapErr) and is comparable to calling unwrap_err().

The advantage of using these macros over the .unwrap(), .expect(), .unwrap_err() or .expect_err() methods is that, on a panic, they will print the file name, line number, column number, and function name of where the macro was called from.

Documentation

Example

This code:

rust let x: Result<(), u32> = Err(123); let y = unwrap!(x);

Panics with the following message:

```

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! unwrap! called on Result::Err ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! example.rs:2,9 in examplemodule::examplefunction

Err(123)

```

unwrap! can also be called with an optional error message. This is supplied as a format string and arguments.

rust let x: Option<()> = None; let y = unwrap!(x, "Oh no! {}", 123);

Prints:

```

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! unwrap! called on Option::None ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! example.rs:2,9 in examplemodule::examplefunction Oh no! 123

```

Similarly, for unwrap_err! this code:

rust let x: Result<u32, ()> = Ok(456); let y = unwrap_err!(x);

Panics with the following message:

```

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! unwraperr! called on Result::Ok ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! example.rs:2,9 in examplemodule::example_function

Ok(456)

```

Implementation

The unwrap crate provides a trait for types which can be unwrapped.

rust trait VerboseUnwrap { type Wrapped; fn verbose_unwrap(self, message: Option<std::fmt::Arguments>, module_path: &str, file: &str, line_number: u32, column: u32) -> Self::Wrapped; }

This is implemented by both Result and Option. The unwrap! macro simply calls this trait method:

rust macro_rules! unwrap( ($e:expr) => ( $crate::VerboseUnwrap::verbose_unwrap($e, None, module_path!(), file!(), line!(), column!()) ); ($e:expr, $($arg:tt)*) => ( $crate::VerboseUnwrap::verbose_unwrap($e, Some(format_args!($($arg)*)), module_path!(), file!(), line!(), column!()) ); );

Likewise there's a trait for types which can have inner error types unwrapped.

rust pub trait VerboseUnwrapErr { type Wrapped; fn verbose_unwrap_err(self, message: Option<Arguments>, module_path: &str, file: &str, line_number: u32, column: u32) -> Self::Wrapped; }

This is implemented by Result, and the unwrap_err! macro calls this trait method:

rust macro_rules! unwrap_err( ($e:expr) => ( $crate::VerboseUnwrapErr::verbose_unwrap_err($e, None, module_path!(), file!(), line!(), column!()) ); ($e:expr, $($arg:tt)*) => ( $crate::VerboseUnwrapErr::verbose_unwrap_err($e, Some(format_args!($($arg)*)), module_path!(), file!(), line!(), column!()) ); );

Usage

Add this to your dependencies in Cargo.toml

unwrap = "~1.1.0"

Then import it using #[macro_use]

```

[macro_use]

extern crate unwrap; ```