[−][src]Trait futures::future::TryFutureExt
Adapters specific to Result
-returning futures
Provided Methods
fn flatten_sink(self) -> FlattenSink<Self, Self::Ok> where
Self::Ok: Sink,
<Self::Ok as Sink>::SinkError == Self::Error,
Self::Ok: Sink,
<Self::Ok as Sink>::SinkError == Self::Error,
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,
F: FnOnce(Self::Ok) -> T,
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,
F: FnOnce(Self::Error) -> E,
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::Error: Into<E>,
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>,
F: FnOnce(Self::Ok) -> Fut,
Fut: TryFuture<Error = Self::Error>,
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>,
F: FnOnce(Self::Error) -> Fut,
Fut: TryFuture<Ok = Self::Ok>,
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
F: FnOnce(Self::Error) -> Self::Ok,
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), ());
fn compat(self) -> Compat<Self> where
Self: Unpin,
Self: 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>
Wraps a TryFuture
into a type that implements
Future
.
TryFuture
s 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>,
Fut2: TryFuture<Error = Self::Error>,
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,
future2: Fut2,
future3: Fut3
) -> TryJoin3<Self, Fut2, Fut3> where
Fut2: TryFuture<Error = Self::Error>,
Fut3: TryFuture<Error = Self::Error>,
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,
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>,
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,
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>,
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)));
Implementors
impl<Fut> TryFutureExt for Fut where
Fut: TryFuture,
[src]
impl<Fut> TryFutureExt for Fut where
Fut: TryFuture,
fn flatten_sink(self) -> FlattenSink<Self, Self::Ok> where
Self::Ok: Sink,
<Self::Ok as Sink>::SinkError == Self::Error,
[src]
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, f: F) -> MapOk<Self, F> where
F: FnOnce(Self::Ok) -> T,
[src]
fn map_ok<T, F>(self, f: F) -> MapOk<Self, F> where
F: FnOnce(Self::Ok) -> T,
fn map_err<E, F>(self, f: F) -> MapErr<Self, F> where
F: FnOnce(Self::Error) -> E,
[src]
fn map_err<E, F>(self, f: F) -> MapErr<Self, F> where
F: FnOnce(Self::Error) -> E,
fn err_into<E>(self) -> ErrInto<Self, E> where
Self::Error: Into<E>,
[src]
fn err_into<E>(self) -> ErrInto<Self, E> where
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>,
[src]
fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F> where
F: FnOnce(Self::Ok) -> Fut,
Fut: TryFuture<Error = Self::Error>,
fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F> where
F: FnOnce(Self::Error) -> Fut,
Fut: TryFuture<Ok = Self::Ok>,
[src]
fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F> where
F: FnOnce(Self::Error) -> Fut,
Fut: TryFuture<Ok = Self::Ok>,
fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F> where
F: FnOnce(Self::Error) -> Self::Ok,
[src]
fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F> where
F: FnOnce(Self::Error) -> Self::Ok,
ⓘImportant traits for Compat<R>fn compat(self) -> Compat<Self> where
Self: Unpin,
[src]
fn compat(self) -> Compat<Self> where
Self: Unpin,
fn into_future(self) -> IntoFuture<Self>
[src]
fn into_future(self) -> IntoFuture<Self>
fn try_join<Fut2>(self, other: Fut2) -> TryJoin<Self, Fut2> where
Fut2: TryFuture<Error = Self::Error>,
[src]
fn try_join<Fut2>(self, other: Fut2) -> TryJoin<Self, Fut2> where
Fut2: TryFuture<Error = Self::Error>,
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>,
[src]
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>,
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>,
[src]
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>,
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>,
[src]
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>,