Trait futures_util::future::TryFutureExt

source ·
pub trait TryFutureExt: TryFuture {
Show 14 methods // Provided methods 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§

source

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
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));
source

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,

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);
source

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
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));
source

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
use futures::future::TryFutureExt;

let future_err_u8 = async { Err::<(), u8>(1) };
let future_err_i32 = future_err_u8.err_into::<i32>();
source

fn ok_into<U>(self) -> OkInto<Self, U>
where Self: Sized, Self::Ok: Into<U>,

Maps this future’s Ok to a new type using the Into trait.

source

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
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));
source

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
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));
source

fn inspect_ok<F>(self, f: F) -> InspectOk<Self, F>
where F: FnOnce(&Self::Ok), Self: Sized,

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));
source

fn inspect_err<F>(self, f: F) -> InspectErr<Self, F>
where F: FnOnce(&Self::Error), Self: Sized,

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));
source

fn try_flatten(self) -> TryFlatten<Self, Self::Ok>
where Self::Ok: TryFuture<Error = Self::Error>, Self: Sized,

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).

source

fn try_flatten_stream(self) -> TryFlattenStream<Self>
where Self::Ok: TryStream<Error = Self::Error>, Self: Sized,

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]));
source

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

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, ());
source

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
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());
source

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.

Implementors§

source§

impl<Fut: ?Sized + TryFuture> TryFutureExt for Fut