Attribute Macro fehler::throws

#[throws]

Annotations a function that "throws" a Result.

Inside functions tagged with throws, you can use ? and the throw! macro to return errors, but you don't need to wrap the successful return values in Ok.

Using this syntax, you can write fallible functions almost as if they were nonfallible. Every time a function call would return a Result, you "re-raise" the error using ?, and if you wish to raise your own error, you can return it with the throw! macro.

Example

use std::io::{self, Read};

use fehler::{throw, throws};

#[throws(io::Error)]
fn main() {
    let mut file = std::fs::File::open("The_House_of_the_Spirits.txt")?;
    let mut text = String::new();
    file.read_to_string(&mut text)?;

    if !text.starts_with("Barrabas came to us by sea, the child Clara wrote") {
        throw!(io::Error::from_raw_os_error(22));
    }

    println!("Okay!");
}

Default Error Type

This macro supports a "default error type" - if you do not pass a type to the macro, it will use the type named Error in this scope. So if you have defined an error type in this module, that will be the error thrown by this function.

You can access this feature by omitting the arguments entirely or by passing _ as the type.

Example

use fehler::throws;

// Set the default error type for this module:
type Error = std::io::Error;

#[throws]
fn main() {
   let file = std::fs::read_to_string("my_file.txt")?;
   println!("{}", file);
}

Throwing as an Option

This syntax can also support functions which return an Option instead of a Result. The way to access this is to pass as Option as the argument to throw.

In functions that return Option, you can use the throw!() macro without any argument to return None.

Example

use fehler::{throw, throws};

#[throws(as Option)]
fn example<T: Eq + Ord>(slice: &[T], needle: &T) -> usize {
    if !slice.contains(needle) {
        throw!();
    }
    slice.binary_search(needle).ok()?
}

Other Try types

The ? syntax in Rust is controlled by a trait called Try, which is currently unstable. Because this feature is unstable and I don't want to maintain compatibility if its interface changes, this crate currently only works with two stable Try types: Result and Option. However, its designed so that it will hopefully support other Try types as well in the future.

It's worth noting that Try also has some other stable implementations: specifically Poll. Because of the somewhat unusual implementation of Try for those types, this crate does not support throws syntax on functions that return Poll (so you can't use this syntax when implementing a Future by hand, for example). I hope to come up with a way to support Poll in the future.