Trait futures_util::try_future::TryFutureExt

pub trait TryFutureExt: TryFuture {
    fn flatten_sink(self) -> FlattenSink<Self, Self::Ok>
    where
        Self::Ok: Sink<SinkError = Self::Error>,
        Self: Sized,
    { ... }
    fn map_ok<T, F>(self, f: F) -> MapOk<Self, F>
    where
        F: FnOnce(Self::Ok) -> T,
        Self: Sized,
    { ... }
    fn map_err<E, F>(self, f: F) -> MapErr<Self, F>
    where
        F: FnOnce(Self::Error) -> E,
        Self: Sized,
    { ... }
    fn err_into<E>(self) -> ErrInto<Self, E>
    where
        Self: Sized,
        Self::Error: Into<E>,
    { ... }
    fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F>
    where
        F: FnOnce(Self::Ok) -> Fut,
        Fut: TryFuture<Error = Self::Error>,
        Self: Sized,
    { ... }
    fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F>
    where
        F: FnOnce(Self::Error) -> Fut,
        Fut: TryFuture<Ok = Self::Ok>,
        Self: Sized,
    { ... }
    fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F>
    where
        Self: Sized,
        F: FnOnce(Self::Error) -> Self::Ok,
    { ... }
    fn compat(self) -> Compat<Self>
    where
        Self: Sized + Unpin,
    { ... }
    fn into_future(self) -> IntoFuture<Self>
    where
        Self: Sized,
    { ... }
    fn try_join<Fut2>(self, other: Fut2) -> TryJoin<Self, Fut2>
    where
        Fut2: TryFuture<Error = Self::Error>,
        Self: Sized,
    { ... }
    fn try_join3<Fut2, Fut3>(
        self, 
        future2: Fut2, 
        future3: Fut3
    ) -> TryJoin3<Self, Fut2, Fut3>
    where
        Fut2: TryFuture<Error = Self::Error>,
        Fut3: TryFuture<Error = Self::Error>,
        Self: Sized,
    { ... }
    fn try_join4<Fut2, Fut3, Fut4>(
        self, 
        future2: Fut2, 
        future3: Fut3, 
        future4: Fut4
    ) -> TryJoin4<Self, Fut2, Fut3, Fut4>
    where
        Fut2: TryFuture<Error = Self::Error>,
        Fut3: TryFuture<Error = Self::Error>,
        Fut4: TryFuture<Error = Self::Error>,
        Self: Sized,
    { ... }
    fn try_join5<Fut2, Fut3, Fut4, Fut5>(
        self, 
        future2: Fut2, 
        future3: Fut3, 
        future4: Fut4, 
        future5: Fut5
    ) -> TryJoin5<Self, Fut2, Fut3, Fut4, Fut5>
    where
        Fut2: TryFuture<Error = Self::Error>,
        Fut3: TryFuture<Error = Self::Error>,
        Fut4: TryFuture<Error = Self::Error>,
        Fut5: TryFuture<Error = Self::Error>,
        Self: Sized,
    { ... }
}

Adapters specific to Result-returning futures

Provided methods

fn flatten_sink(self) -> FlattenSink<Self, Self::Ok> where
    Self::Ok: Sink<SinkError = Self::Error>,
    Self: Sized, 

Flattens 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 the sink was available at the call site.

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

Examples

#![feature(futures_api)]
use futures::future::{Future, TryFutureExt};
use futures::sink::Sink;

fn make_sink_async() -> impl Future<Output = Result<
    impl Sink<SinkItem = T, SinkError = E>,
    E,
>> { // ... }
fn take_sink(sink: impl Sink<SinkItem = T, SinkError = E>) { /* ... */ }

let fut = make_sink_async();
take_sink(fut.flatten_sink())

fn map_ok<T, F>(self, f: F) -> MapOk<Self, F> where
    F: FnOnce(Self::Ok) -> T,
    Self: Sized, 

Maps this future's success value to a different value.

This method can be used to change the Ok type of the future into a different type. It is similar to the Result::map method. You can use this method to chain along a computation once the future has been resolved.

The provided closure f will only be called if this future is resolved to an Ok. If it resolves to an Err, panics, or is dropped, then the provided closure will never be invoked.

Note that this method consumes the future it is called on and returns a wrapped version of it.

Examples

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

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

Calling map_ok on an errored future has no effect:

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

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

fn map_err<E, F>(self, f: F) -> MapErr<Self, F> where
    F: FnOnce(Self::Error) -> E,
    Self: Sized, 

Maps this future's error value to a different value.

This method can be used to change the Error type of the future into a different type. It is similar to the Result::map_err method. You can use this method for example to ensure that futures have the same Error type when using select! or join!.

The provided closure f will only be called if this future is resolved to an Err. If it resolves to an Ok, panics, or is dropped, then the provided closure will never be invoked.

Note that this method consumes the future it is called on and returns a wrapped version of it.

Examples

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

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

Calling map_err on a successful future has no effect:

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

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

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

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

This method does for futures what the ?-operator does for Result: It lets the compiler infer the type of the resulting error. Just as map_err, this is useful for example to ensure that futures have the same Error type when using select! or join!.

Note that this method consumes the future it is called on and returns a wrapped version of it.

Examples

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

let future_err_u8 = future::ready(Err::<(), u8>(1));
let future_err_i32 = future_err_u8.err_into::<i32>();

fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F> where
    F: FnOnce(Self::Ok) -> Fut,
    Fut: TryFuture<Error = Self::Error>,
    Self: Sized, 

Executes another future after this one resolves successfully. The success value is passed to a closure to create this subsequent future.

The provided closure f will only be called if this future is resolved to an Ok. If this future resolves to an Err, panics, or is dropped, then the provided closure will never be invoked. The Error type of this future and the future returned by f have to match.

Note that this method consumes the future it is called on and returns a wrapped version of it.

Examples

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

let future = future::ready(Ok::<i32, i32>(1));
let future = future.and_then(|x| future::ready(Ok::<i32, i32>(x + 3)));
assert_eq!(await!(future), Ok(4));

Calling and_then on an errored future has no effect:

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

let future = future::ready(Err::<i32, i32>(1));
let future = future.and_then(|x| future::ready(Err::<i32, i32>(x + 3)));
assert_eq!(await!(future), Err(1));

fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F> where
    F: FnOnce(Self::Error) -> Fut,
    Fut: TryFuture<Ok = Self::Ok>,
    Self: Sized, 

Executes another future if this one resolves to an error. The error value is passed to a closure to create this subsequent future.

The provided closure f will only be called if this future is resolved to an Err. If this future resolves to an Ok, panics, or is dropped, then the provided closure will never be invoked. The Ok type of this future and the future returned by f have to match.

Note that this method consumes the future it is called on and returns a wrapped version of it.

Examples

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

let future = future::ready(Err::<i32, i32>(1));
let future = future.or_else(|x| future::ready(Err::<i32, i32>(x + 3)));
assert_eq!(await!(future), Err(4));

Calling or_else on a successful future has no effect:

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

let future = future::ready(Ok::<i32, i32>(1));
let future = future.or_else(|x| future::ready(Ok::<i32, i32>(x + 3)));
assert_eq!(await!(future), Ok(1));

fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F> where
    Self: Sized,
    F: FnOnce(Self::Error) -> Self::Ok, 

Unwraps this future's ouput, producing a future with this future's Ok type as its Output type.

If this future is resolved successfully, the returned future will contain the original future's success value as output. Otherwise, the closure f is called with the error value to produce an alternate success value.

This method is similar to the Result::unwrap_or_else method.

Examples

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

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

Important traits for Compat<R>

impl<R: AsyncRead03> Read for Compat<R>impl<W: AsyncWrite03> Write for Compat<W>

fn compat(self) -> Compat<Self> where
    Self: Sized + Unpin, 

Wraps a TryFuture into a future compatable with libraries using futures 0.1 future definitons. Requires the compat feature to enable.

fn into_future(self) -> IntoFuture<Self> where
    Self: Sized, 

Wraps a TryFuture into a type that implements Future.

TryFutures currently do not implement the Future trait due to limitations of the compiler.

Examples

#![feature(futures_api)]
use futures::future::{Future, TryFuture, TryFutureExt};

fn make_try_future() -> impl TryFuture<Ok = T, Error = E> { // ... }
fn take_future(future: impl Future<Output = Result<T, E>>) { /* ... */ }

take_future(make_try_future().into_future());

fn try_join<Fut2>(self, other: Fut2) -> TryJoin<Self, Fut2> where
    Fut2: TryFuture<Error = Self::Error>,
    Self: Sized, 

Joins the result of two futures, waiting for them both to complete or for one to produce an error.

This function will return a new future which awaits both this and the other future to complete. If successful, the returned future will finish with a tuple of both results. If unsuccesful, it will complete with the first error encountered.

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

Examples

When used on multiple futures that return Ok, try_join will return Ok of a tuple of the values:

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

let a = future::ready(Ok::<i32, i32>(1));
let b = future::ready(Ok::<i32, i32>(2));
let pair = a.try_join(b);

assert_eq!(await!(pair), Ok((1, 2)));

If one of the futures resolves to an error, try_join will return that error:

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

let a = future::ready(Ok::<i32, i32>(1));
let b = future::ready(Err::<i32, i32>(2));
let pair = a.try_join(b);

assert_eq!(await!(pair), Err(2));

fn try_join3<Fut2, Fut3>(
    self,
    future2: Fut2,
    future3: Fut3
) -> TryJoin3<Self, Fut2, Fut3> where
    Fut2: TryFuture<Error = Self::Error>,
    Fut3: TryFuture<Error = Self::Error>,
    Self: Sized, 

Same as try_join, but with more futures.

Examples

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

let a = future::ready(Ok::<i32, i32>(1));
let b = future::ready(Ok::<i32, i32>(2));
let c = future::ready(Ok::<i32, i32>(3));
let tuple = a.try_join3(b, c);

assert_eq!(await!(tuple), Ok((1, 2, 3)));

fn try_join4<Fut2, Fut3, Fut4>(
    self,
    future2: Fut2,
    future3: Fut3,
    future4: Fut4
) -> TryJoin4<Self, Fut2, Fut3, Fut4> where
    Fut2: TryFuture<Error = Self::Error>,
    Fut3: TryFuture<Error = Self::Error>,
    Fut4: TryFuture<Error = Self::Error>,
    Self: Sized, 

Same as try_join, but with more futures.

Examples

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

let a = future::ready(Ok::<i32, i32>(1));
let b = future::ready(Ok::<i32, i32>(2));
let c = future::ready(Ok::<i32, i32>(3));
let d = future::ready(Ok::<i32, i32>(4));
let tuple = a.try_join4(b, c, d);

assert_eq!(await!(tuple), Ok((1, 2, 3, 4)));

fn try_join5<Fut2, Fut3, Fut4, Fut5>(
    self,
    future2: Fut2,
    future3: Fut3,
    future4: Fut4,
    future5: Fut5
) -> TryJoin5<Self, Fut2, Fut3, Fut4, Fut5> where
    Fut2: TryFuture<Error = Self::Error>,
    Fut3: TryFuture<Error = Self::Error>,
    Fut4: TryFuture<Error = Self::Error>,
    Fut5: TryFuture<Error = Self::Error>,
    Self: Sized, 

Same as try_join, but with more futures.

Examples

#![feature(async_await, await_macro, futures_api)]
use futures::future::{self, TryFutureExt};

let a = future::ready(Ok::<i32, i32>(1));
let b = future::ready(Ok::<i32, i32>(2));
let c = future::ready(Ok::<i32, i32>(3));
let d = future::ready(Ok::<i32, i32>(4));
let e = future::ready(Ok::<i32, i32>(5));
let tuple = a.try_join5(b, c, d, e);

assert_eq!(await!(tuple), Ok((1, 2, 3, 4, 5)));

Loading content...

Implementors

impl<Fut: TryFuture> TryFutureExt for Fut

fn flatten_sink(self) -> FlattenSink<Self, Self::Ok> where
    Self::Ok: Sink<SinkError = Self::Error>,
    Self: Sized, 

fn map_ok<T, F>(self, f: F) -> MapOk<Self, F> where
    F: FnOnce(Self::Ok) -> T,
    Self: Sized, 

fn map_err<E, F>(self, f: F) -> MapErr<Self, F> where
    F: FnOnce(Self::Error) -> E,
    Self: Sized, 

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

fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F> where
    F: FnOnce(Self::Ok) -> Fut,
    Fut: TryFuture<Error = Self::Error>,
    Self: Sized, 

fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F> where
    F: FnOnce(Self::Error) -> Fut,
    Fut: TryFuture<Ok = Self::Ok>,
    Self: Sized, 

fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F> where
    Self: Sized,
    F: FnOnce(Self::Error) -> Self::Ok, 

Important traits for Compat<R>

impl<R: AsyncRead03> Read for Compat<R>impl<W: AsyncWrite03> Write for Compat<W>

fn compat(self) -> Compat<Self> where
    Self: Sized + Unpin, 

fn into_future(self) -> IntoFuture<Self> where
    Self: Sized, 

fn try_join<Fut2>(self, other: Fut2) -> TryJoin<Self, Fut2> where
    Fut2: TryFuture<Error = Self::Error>,
    Self: Sized, 

fn try_join3<Fut2, Fut3>(
    self,
    future2: Fut2,
    future3: Fut3
) -> TryJoin3<Self, Fut2, Fut3> where
    Fut2: TryFuture<Error = Self::Error>,
    Fut3: TryFuture<Error = Self::Error>,
    Self: Sized, 

fn try_join4<Fut2, Fut3, Fut4>(
    self,
    future2: Fut2,
    future3: Fut3,
    future4: Fut4
) -> TryJoin4<Self, Fut2, Fut3, Fut4> where
    Fut2: TryFuture<Error = Self::Error>,
    Fut3: TryFuture<Error = Self::Error>,
    Fut4: TryFuture<Error = Self::Error>,
    Self: Sized, 

fn try_join5<Fut2, Fut3, Fut4, Fut5>(
    self,
    future2: Fut2,
    future3: Fut3,
    future4: Fut4,
    future5: Fut5
) -> TryJoin5<Self, Fut2, Fut3, Fut4, Fut5> where
    Fut2: TryFuture<Error = Self::Error>,
    Fut3: TryFuture<Error = Self::Error>,
    Fut4: TryFuture<Error = Self::Error>,
    Fut5: TryFuture<Error = Self::Error>,
    Self: Sized, 

Loading content...