Trait futures::prelude::TryFutureExt[−][src]

pub trait TryFutureExt: TryFuture {
    fn flatten_sink(self) -> FlattenSink<Self, Self::Ok>
    where
        Self::Ok: Sink,
        <Self::Ok as Sink>::SinkError == Self::Error,
    { ... }

    fn map_ok<T, F>(self, op: F) -> MapOk<Self, F>
    where
        F: FnOnce(Self::Ok) -> T,
    { ... }

    fn map_err<E, F>(self, op: F) -> MapErr<Self, F>
    where
        F: FnOnce(Self::Error) -> E,
    { ... }

    fn err_into<E>(self) -> ErrInto<Self, E>
    where
        Self::Error: Into<E>,
    { ... }

    fn and_then<Fut, F>(self, async_op: F) -> AndThen<Self, Fut, F>
    where
        F: FnOnce(Self::Ok) -> Fut,
        Fut: TryFuture<Error = Self::Error>,
    { ... }

    fn or_else<Fut, F>(self, async_op: F) -> OrElse<Self, Fut, F>
    where
        F: FnOnce(Self::Error) -> Fut,
        Fut: TryFuture<Ok = Self::Ok>,
    { ... }

    fn unwrap_or_else<F>(self, op: F) -> UnwrapOrElse<Self, F>
    where
        F: FnOnce(Self::Error) -> Self::Ok,
    { ... }

    fn into_future(self) -> IntoFuture<Self> { ... }
}

Adapters specific to Result-returning futures

Provided Methods

Flatten the execution of this future when the successful result of this future is a sink.

This can be useful when sink initialization is deferred, and it is convenient to work with that sink as if sink was available at the call site.

Note that this function consumes this future and returns a wrapped version of it.

Map this future's result to a different type, returning a new future of the resulting type.

This function is similar to the Option::map or Iterator::map where it will change the type of the underlying future. This is useful to chain along a computation once a future has been resolved.

The closure provided will only be called if this future is resolved successfully. If this future returns an error, panics, or is dropped, then the closure provided will never be invoked.

Note that this function consumes the receiving future and returns a wrapped version of it, similar to the existing map methods in the standard library.

Examples

use futures::prelude::*;
use futures::future;
use futures::executor::block_on;

let future = future::ready::<Result<i32, i32>>(Ok(1));
let new_future = future.map_ok(|x| x + 3);
assert_eq!(block_on(new_future), Ok(4));

Calling map_ok on an errored Future has no effect:

use futures::prelude::*;
use futures::future;
use futures::executor::block_on;

let future = future::ready::<Result<i32, i32>>(Err(1));
let new_future = future.map_ok(|x| x + 3);
assert_eq!(block_on(new_future), Err(1));

Map this future's error to a different error, returning a new future.

This function is similar to the Result::map_err where it will change the error type of the underlying future. This is useful for example to ensure that futures have the same error type when used with combinators like select and join.

The closure provided will only be called if this future is resolved with an error. If this future returns a success, panics, or is dropped, then the closure provided will never be invoked.

Note that this function consumes the receiving future and returns a wrapped version of it.

Examples

use futures::future;
use futures::prelude::*;
use futures::executor::block_on;

let future = future::ready::<Result<i32, i32>>(Err(1));
let new_future = future.map_err(|x| x + 3);
assert_eq!(block_on(new_future), Err(4));

Calling map_err on a successful Future has no effect:

use futures::future;
use futures::prelude::*;
use futures::executor::block_on;

let future = future::ready::<Result<i32, i32>>(Ok(1));
let new_future = future.map_err(|x| x + 3);
assert_eq!(block_on(new_future), Ok(1));

Map this future's error to a new error type using the Into trait.

This function does for futures what try! does for Result, by letting the compiler infer the type of the resulting error. Just as map_err above, this is useful for example to ensure that futures have the same error type when used with combinators like select and join.

Note that this function consumes the receiving future and returns a wrapped version of it.

Examples

use futures::prelude::*;
use futures::future;

let future_with_err_u8 = future::ready::<Result<(), u8>>(Err(1));
let future_with_err_i32 = future_with_err_u8.err_into::<i32>();

Execute another future after this one has resolved successfully.

This function can be used to chain two futures together and ensure that the final future isn't resolved until both have finished. The closure provided is yielded the successful result of this future and returns another value which can be converted into a future.

Note that because Result implements the IntoFuture trait this method can also be useful for chaining fallible and serial computations onto the end of one future.

If this future is dropped, panics, or completes with an error then the provided closure f is never called.

Note that this function consumes the receiving future and returns a wrapped version of it.

Examples

use futures::prelude::*;
use futures::future::{self, Ready};

let future_of_1 = future::ready::<Result<i32, i32>>(Ok(1));
let future_of_4 = future_of_1.and_then(|x| {
    future::ready(Ok(x + 3))
});

let future_of_err_1 = future::ready::<Result<i32, i32>>(Err(1));
future_of_err_1.and_then(|_| -> Ready<Result<(), i32>> {
    panic!("should not be called in case of an error");
});

Execute another future if this one resolves with an error.

Return a future that passes along this future's value if it succeeds, and otherwise passes the error to the closure f and waits for the future it returns. The closure may also simply return a value that can be converted into a future.

Note that because Result implements the IntoFuture trait this method can also be useful for chaining together fallback computations, where when one fails, the next is attempted.

If this future is dropped, panics, or completes successfully then the provided closure f is never called.

Note that this function consumes the receiving future and returns a wrapped version of it.

Examples

use futures::prelude::*;
use futures::future::{self, Ready};

let future_of_err_1 = future::ready::<Result<i32, i32>>(Err(1));
let future_of_4 = future_of_err_1.or_else(|x| {
    future::ready::<Result<i32, ()>>(Ok(x + 3))
});

let future_of_1 = future::ready::<Result<i32, i32>>(Ok(1));
future_of_1.or_else(|_| -> Ready<Result<i32, ()>> {
    panic!("should not be called in case of success");
});

Handle errors generated by this future by converting them into Self::Item.

Because it can never produce an error, the returned UnwrapOrElse future can conform to any specific Error type, including Never.

Examples

use futures::prelude::*;
use futures::future;
use futures::executor::block_on;

let future = future::ready::<Result<(), &str>>(Err("Boom!"));
let new_future = future.unwrap_or_else(|_| ());
assert_eq!(block_on(new_future), ());

Wraps a TryFuture so that it implements Future. TryFutures currently do not implement the Future trait due to limitations of the compiler.

Implementors