Trait futures_util::future::TryFutureExt
source · pub trait TryFutureExt: TryFuture {
Show 15 methods
// Provided methods
fn flatten_sink<Item>(self) -> FlattenSink<Self, Self::Ok>
where Self::Ok: Sink<Item, Error = 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_ok_or_else<T, E, F>(self, e: E, f: F) -> MapOkOrElse<Self, F, E> ⓘ
where F: FnOnce(Self::Ok) -> T,
E: FnOnce(Self::Error) -> 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 ok_into<U>(self) -> OkInto<Self, U> ⓘ
where Self: Sized,
Self::Ok: Into<U> { ... }
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 inspect_ok<F>(self, f: F) -> InspectOk<Self, F> ⓘ
where F: FnOnce(&Self::Ok),
Self: Sized { ... }
fn inspect_err<F>(self, f: F) -> InspectErr<Self, F> ⓘ
where F: FnOnce(&Self::Error),
Self: Sized { ... }
fn try_flatten(self) -> TryFlatten<Self, Self::Ok> ⓘ
where Self::Ok: TryFuture<Error = Self::Error>,
Self: Sized { ... }
fn try_flatten_stream(self) -> TryFlattenStream<Self>
where Self::Ok: TryStream<Error = Self::Error>,
Self: Sized { ... }
fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F> ⓘ
where Self: Sized,
F: FnOnce(Self::Error) -> Self::Ok { ... }
fn into_future(self) -> IntoFuture<Self> ⓘ
where Self: Sized { ... }
fn try_poll_unpin(
&mut self,
cx: &mut Context<'_>
) -> Poll<Result<Self::Ok, Self::Error>>
where Self: Unpin { ... }
}
Expand description
Adapters specific to Result
-returning futures
Provided Methods§
sourcefn flatten_sink<Item>(self) -> FlattenSink<Self, Self::Ok>
fn flatten_sink<Item>(self) -> FlattenSink<Self, Self::Ok>
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
use futures::future::{Future, TryFutureExt};
use futures::sink::Sink;
fn make_sink_async() -> impl Future<Output = Result<
impl Sink<T, Error = E>,
E,
>> { // ... }
fn take_sink(sink: impl Sink<T, Error = E>) { /* ... */ }
let fut = make_sink_async();
take_sink(fut.flatten_sink())
sourcefn map_ok<T, F>(self, f: F) -> MapOk<Self, F> ⓘ
fn map_ok<T, F>(self, f: F) -> MapOk<Self, F> ⓘ
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
use futures::future::TryFutureExt;
let future = async { Ok::<i32, i32>(1) };
let future = future.map_ok(|x| x + 3);
assert_eq!(future.await, Ok(4));
Calling map_ok
on an errored future has no
effect:
use futures::future::TryFutureExt;
let future = async { Err::<i32, i32>(1) };
let future = future.map_ok(|x| x + 3);
assert_eq!(future.await, Err(1));
sourcefn map_ok_or_else<T, E, F>(self, e: E, f: F) -> MapOkOrElse<Self, F, E> ⓘ
fn map_ok_or_else<T, E, F>(self, e: E, f: F) -> MapOkOrElse<Self, F, E> ⓘ
Maps this future’s success value to a different value, and permits for error handling resulting in the same type.
This method can be used to coalesce your Ok
type and Error
into another type,
where that type is the same for both outcomes.
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.
The provided closure e
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
use futures::future::TryFutureExt;
let future = async { Ok::<i32, i32>(5) };
let future = future.map_ok_or_else(|x| x * 2, |x| x + 3);
assert_eq!(future.await, 8);
let future = async { Err::<i32, i32>(5) };
let future = future.map_ok_or_else(|x| x * 2, |x| x + 3);
assert_eq!(future.await, 10);
sourcefn map_err<E, F>(self, f: F) -> MapErr<Self, F> ⓘ
fn map_err<E, F>(self, f: F) -> MapErr<Self, F> ⓘ
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
use futures::future::TryFutureExt;
let future = async { Err::<i32, i32>(1) };
let future = future.map_err(|x| x + 3);
assert_eq!(future.await, Err(4));
Calling map_err
on a successful future has
no effect:
use futures::future::TryFutureExt;
let future = async { Ok::<i32, i32>(1) };
let future = future.map_err(|x| x + 3);
assert_eq!(future.await, Ok(1));
sourcefn err_into<E>(self) -> ErrInto<Self, E> ⓘ
fn err_into<E>(self) -> ErrInto<Self, 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
use futures::future::TryFutureExt;
let future_err_u8 = async { Err::<(), u8>(1) };
let future_err_i32 = future_err_u8.err_into::<i32>();
sourcefn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F> ⓘ
fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F> ⓘ
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
use futures::future::TryFutureExt;
let future = async { Ok::<i32, i32>(1) };
let future = future.and_then(|x| async move { Ok::<i32, i32>(x + 3) });
assert_eq!(future.await, Ok(4));
Calling and_then
on an errored future has no
effect:
use futures::future::TryFutureExt;
let future = async { Err::<i32, i32>(1) };
let future = future.and_then(|x| async move { Err::<i32, i32>(x + 3) });
assert_eq!(future.await, Err(1));
sourcefn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F> ⓘ
fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F> ⓘ
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
use futures::future::TryFutureExt;
let future = async { Err::<i32, i32>(1) };
let future = future.or_else(|x| async move { Err::<i32, i32>(x + 3) });
assert_eq!(future.await, Err(4));
Calling or_else
on a successful future has
no effect:
use futures::future::TryFutureExt;
let future = async { Ok::<i32, i32>(1) };
let future = future.or_else(|x| async move { Ok::<i32, i32>(x + 3) });
assert_eq!(future.await, Ok(1));
sourcefn inspect_ok<F>(self, f: F) -> InspectOk<Self, F> ⓘ
fn inspect_ok<F>(self, f: F) -> InspectOk<Self, F> ⓘ
Do something with the success value of a future before passing it on.
When using futures, you’ll often chain several of them together. While
working on such code, you might want to check out what’s happening at
various parts in the pipeline, without consuming the intermediate
value. To do that, insert a call to inspect_ok
.
§Examples
use futures::future::TryFutureExt;
let future = async { Ok::<_, ()>(1) };
let new_future = future.inspect_ok(|&x| println!("about to resolve: {}", x));
assert_eq!(new_future.await, Ok(1));
sourcefn inspect_err<F>(self, f: F) -> InspectErr<Self, F> ⓘ
fn inspect_err<F>(self, f: F) -> InspectErr<Self, F> ⓘ
Do something with the error value of a future before passing it on.
When using futures, you’ll often chain several of them together. While
working on such code, you might want to check out what’s happening at
various parts in the pipeline, without consuming the intermediate
value. To do that, insert a call to inspect_err
.
§Examples
use futures::future::TryFutureExt;
let future = async { Err::<(), _>(1) };
let new_future = future.inspect_err(|&x| println!("about to error: {}", x));
assert_eq!(new_future.await, Err(1));
sourcefn try_flatten(self) -> TryFlatten<Self, Self::Ok> ⓘ
fn try_flatten(self) -> TryFlatten<Self, Self::Ok> ⓘ
Flatten the execution of this future when the successful result of this future is another future.
This is equivalent to future.and_then(|x| x)
.
sourcefn try_flatten_stream(self) -> TryFlattenStream<Self>
fn try_flatten_stream(self) -> TryFlattenStream<Self>
Flatten the execution of this future when the successful result of this future is a stream.
This can be useful when stream initialization is deferred, and it is convenient to work with that stream as if stream was available at the call site.
Note that this function consumes this future and returns a wrapped version of it.
§Examples
use futures::future::TryFutureExt;
use futures::stream::{self, TryStreamExt};
let stream_items = vec![17, 18, 19].into_iter().map(Ok);
let future_of_a_stream = async { Ok::<_, ()>(stream::iter(stream_items)) };
let stream = future_of_a_stream.try_flatten_stream();
let list = stream.try_collect::<Vec<_>>().await;
assert_eq!(list, Ok(vec![17, 18, 19]));
sourcefn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F> ⓘ
fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F> ⓘ
Unwraps this future’s output, 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
use futures::future::TryFutureExt;
let future = async { Err::<(), &str>("Boom!") };
let future = future.unwrap_or_else(|_| ());
assert_eq!(future.await, ());
sourcefn into_future(self) -> IntoFuture<Self> ⓘwhere
Self: Sized,
fn into_future(self) -> IntoFuture<Self> ⓘwhere
Self: Sized,
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
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());
sourcefn try_poll_unpin(
&mut self,
cx: &mut Context<'_>
) -> Poll<Result<Self::Ok, Self::Error>>where
Self: Unpin,
fn try_poll_unpin(
&mut self,
cx: &mut Context<'_>
) -> Poll<Result<Self::Ok, Self::Error>>where
Self: Unpin,
A convenience method for calling TryFuture::try_poll
on Unpin
future types.