I’ve just published failure 0.1.1 to crates.io. It’s mostly some incremental improvements to failure that have been suggested since the first release two weeks ago.

Improvements to the derive

A big change in version 0.1.1 is that the derive can be used without depending on the failure_derive crate separately. All that needs to be done is tagging the extern crate statement with #[macro_use]:

// No direct dependency on `failure_derive`
#[macro_use] extern crate failure;

#[derive(Fail, Debug)]
#[fail(display = "An error occurred.")]
pub struct MyError;

If you don’t need to use the derive, and don’t want to pull it in as a dependency, this is controlled through a derive feature, which is on by default but can be turned off.

Additionally, the derive can now be used in no_std, whereas it originally couldn’t been. Note that if you want to use the derive in no_std, you will still need to depend on it separately (and turn off all default features in both failure and failure_derive).

bail! and ensure!

If you were a fan of the bail! and ensure! macros from error-chain, good news. failure now has a version of these macros as well.

The bail! macro returns an error immediately, based on a format string. The ensure! macro additionally takes a conditional, and returns the error only if that conditional is false. You can think of bail! and ensure! as being analogous to panic! and assert!, but throwing errors instead of panicking.

The causes Iterator

The Fail trait and Error type have gained a new method: causes. This returns an iterator over the causes of this failure.

if let Err(e) = some_function() {
    for cause in e.causes() {
        println!("{}", cause);
    }
}

Note that the first item returned by this iterator is this failure itself, and this iterator therefore always has at least one item, even if this failure is its own “root cause.”