Module woah::docs

Documentation, including crate features and examples.

Why are the docs like this?

Putting the docs in Rustdoc means they can be run as documentation tests. Breaking them up into modules helps keep them from getting too unwieldy, so people can still navigate the API itself with ease.

woah::Result has a lot of methods, and the way they’re grouped and presented by Rustdoc isn’t always easy to navigate. To help, this page explains them in groups of similar methods.

Methods

See if the Result is a particular variant

These methods, the “is” methods, return a bool based on what variant is present.

1. is_ok
2. is_err
3. is_local_err
4. is_fatal_err

See if the Result contains a value

These methods check if the Result contains a particular value.

1. contains
2. contains_err
3. contains_local_err
4. contains_fatal_err

Get an Option if a variant is present

These methods try to get the contained value out, returning an Option in case it’s another variant.

1. ok
2. err
3. local_err
4. fatal_err

Reference the contained value

Gets a reference (immutable or mutable) to the contained value.

1. as_ref
2. as_mut

Dereference the contained value

Dereferences the contained value if it implements Deref.

1. as_deref
2. as_deref_err
3. as_deref_local_err
4. as_deref_fatal_err

Dereferences the contained value mutably if it implements DerefMut.

1. as_deref_mut
2. as_deref_mut_err
3. as_deref_mut_local_err
4. as_deref_mut_fatal_err

Map over the contained value

Applies some function to the contained value.

1. map
2. map_or
3. map_or_else

Applies some function to the contained value, if it’s a local or fatal error.

1. map_err
2. map_err_or
3. map_err_or_else

Applies some function to the contained value, if it’s a local error.

1. map_local_err
2. map_local_err_or
3. map_local_err_or_else

Applies some function to the contained value, if it’s a fatal error.

1. map_fatal_err
2. map_fatal_err_or
3. map_fatal_err_or_else

Iterate over the contained value

1. iter
2. iter_mut
3. into_iter (for woah::Result)
4. into_iter (for &woah::Result)
5. into_iter (for &mut woah::Result)

Compose Results

1. and
2. and_then
3. or
4. or_else
5. or_else_fatal
6. or_else_local
7. or_fatal
8. or_local

Unwrap the Result

1. unwrap
2. unwrap_err
3. unwrap_fatal_err
4. unwrap_local_err
5. unwrap_or
6. unwrap_or_default
7. unwrap_or_else
8. expect
9. expect_err
10. expect_fatal_err
11. expect_local_err

Copy or clone the contained value

1. cloned (for &woah::Result)
2. cloned (for &mut woah::Result)
3. copied (for &woah::Result)
4. copied (for &mut woah::Result)

Transpose when holding an Option

1. transpose

Convert to and from a std::result::Result

1. into_result
2. into_result_default

Use woah::Result with the question mark operator

1. Try impl (nightly-only, with nightly feature or try_trait feature)

Use woah::Result as the return type of main

1. Termination impl (nightly-only, with nightly feature, or termination_trait and std features)

Build a woah::Result from an iterator

1. FromIterator impl (nightly-only, with nightly feature, or from_iterator_trait feature)

Features

woah can be used on stable or nightly. On nightly, enabling the nightly feature is recommended, to get the full power of the woah::Result type, including:

• Being able to use it with the question mark operator,
• Being able to make it the return type of fn main,
• Gaining a number of useful additional methods, including from_iter (which enables easy conversion from Vec<woah::Result<T, L, F> into woah::Result<Vec<T>, L, F> via the collect method).

The following table is the full list of features. If you want to use woah without any dependencies, you can disable the either_methods feature, which otherwise imports the either crate to add additional methods.

Feature Name	Channels	Depends On	What It Does
default	Stable, Beta, Nightly	either_methods	Enables default features (currently just either_methods).
nightly	Nightly	None	Enables all nightly-only features. This feature is permanently unstable, and changes to the APIs enabled by this feature are never considered breaking changes.
serde	Stable, Beta, Nightly	None	Implements serde::Serialize and serde::Deserialize for woah::Result.
std	Stable, Beta, Nightly	None	Use the standard library. Turn off to make the crate no_std compatible. Turning off the standard library conflicts with the termination_trait feature, so turning off std will automatically disable that feature.
either_methods	Stable, Beta, Nightly	None	Adds the either crate as a dependency and provides convenience methods for operating on Either<LocalErr, FatalErr>.

Examples

Examples of using woah on both stable and nightly.

Example on stable

use woah::prelude::*;
use std::cmp::Ordering;

match get_number() {
    StdOk(num) => println!("Got a number: {}", num),
    StdResult::Err(fatal_err) => eprintln!("Fatal error: {:?}", fatal_err),
}

fn get_number() -> StdResult<i64, FatalError> {
    // propagate any fatal error
    let result: StdResult<i64, LocalError> = compare_numbers(5, 5)?;

    // handle any local error
    let num = result.unwrap_or_else(|local_err| {
        println!("Local error: {:?}", local_err);
        i64::default()
    });

    StdOk(num)
}

fn compare_numbers(x: i64, y: i64) -> StdResult<StdResult<i64, LocalError>, FatalError> {
    match x.cmp(&y) {
        Ordering::Greater => Ok(x),
        Ordering::Equal => LocalErr(LocalError::SomeError),
        Ordering::Less => FatalErr(FatalError::CatastrophicError),
    }.into_result()
}

#[derive(Debug)]
enum LocalError { SomeError, AnotherError }

#[derive(Debug)]
enum FatalError { BigBadError, CatastrophicError }

Example on nightly

This uses --features nightly to enable nightly-only features.

use woah::prelude::*;
use std::cmp::Ordering;

match get_number() {
    StdOk(num) => println!("Got a number: {}", num),
    StdResult::Err(fatal_err) => eprintln!("Fatal error: {:?}", fatal_err),
}

fn get_number() -> StdResult<i64, FatalError> {
    // propagate any fatal error
    let result: StdResult<i64, LocalError> = compare_numbers(5, 10)?;

    // handle any local error
    let num = result.unwrap_or_else(|local_err| {
        println!("Local error: {:?}", local_err);
        i64::default()
    });

    StdOk(num)
}

fn compare_numbers(x: i64, y: i64) -> Result<i64, LocalError, FatalError> {
    match x.cmp(&y) {
        Ordering::Greater => Ok(x),
        Ordering::Equal => LocalErr(LocalError::Equal),
        Ordering::Less => FatalErr(FatalError::Less),
    }
}

#[derive(Debug)]
enum LocalError { Equal }

#[derive(Debug)]
enum FatalError { Less }