# Trait futures_util::future::TryFutureExt [−] [src]

###

###

###

###

###

###

###

###

###

###

###

###

    pub trait TryFutureExt: TryFuture {
        fn map_ok<T, F>(self, f: F) -> MapOk<Self, F>ⓘNotable traits for MapOk<Fut, F>impl<Fut, F> Future for MapOk<Fut, F> where
        Map<IntoFuture<Fut>, MapOkFn<F>>: Future,     type Output = <Map<IntoFuture<Fut>, MapOkFn<F>> as Future>::Output;
        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>ⓘNotable traits for MapOkOrElse<Fut, F, G>impl<Fut, F, G> Future for MapOkOrElse<Fut, F, G> where
        Map<IntoFuture<Fut>, ChainFn<MapOkFn<F>, ChainFn<MapErrFn<G>, MergeResultFn>>>: Future,     type Output = <Map<IntoFuture<Fut>, ChainFn<MapOkFn<F>, ChainFn<MapErrFn<G>, MergeResultFn>>> as Future>::Output;
        where
            F: FnOnce(Self::Ok) -> T,
            E: FnOnce(Self::Error) -> T,
            Self: Sized,
        { ... }
        fn map_err<E, F>(self, f: F) -> MapErr<Self, F>ⓘNotable traits for MapErr<Fut, F>impl<Fut, F> Future for MapErr<Fut, F> where
        Map<IntoFuture<Fut>, MapErrFn<F>>: Future,     type Output = <Map<IntoFuture<Fut>, MapErrFn<F>> as Future>::Output;
        where
            F: FnOnce(Self::Error) -> E,
            Self: Sized,
        { ... }
        fn err_into<E>(self) -> ErrInto<Self, E>ⓘNotable traits for ErrInto<Fut, E>impl<Fut, E> Future for ErrInto<Fut, E> where
        MapErr<Fut, IntoFn<E>>: Future,     type Output = <MapErr<Fut, IntoFn<E>> as Future>::Output;
        where
            Self: Sized,
            Self::Error: Into<E>,
        { ... }
        fn ok_into<U>(self) -> OkInto<Self, U>ⓘNotable traits for OkInto<Fut, E>impl<Fut, E> Future for OkInto<Fut, E> where
        MapOk<Fut, IntoFn<E>>: Future,     type Output = <MapOk<Fut, IntoFn<E>> as Future>::Output;
        where
            Self: Sized,
            Self::Ok: Into<U>,
        { ... }
        fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F>ⓘNotable traits for AndThen<Fut1, Fut2, F>impl<Fut1, Fut2, F> Future for AndThen<Fut1, Fut2, F> where
        TryFlatten<MapOk<Fut1, F>, Fut2>: Future,     type Output = <TryFlatten<MapOk<Fut1, F>, Fut2> as Future>::Output;
        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>ⓘNotable traits for OrElse<Fut1, Fut2, F>impl<Fut1, Fut2, F> Future for OrElse<Fut1, Fut2, F> where
        TryFlattenErr<MapErr<Fut1, F>, Fut2>: Future,     type Output = <TryFlattenErr<MapErr<Fut1, F>, Fut2> as Future>::Output;
        where
            F: FnOnce(Self::Error) -> Fut,
            Fut: TryFuture<Ok = Self::Ok>,
            Self: Sized,
        { ... }
        fn inspect_ok<F>(self, f: F) -> InspectOk<Self, F>ⓘNotable traits for InspectOk<Fut, F>impl<Fut, F> Future for InspectOk<Fut, F> where
        Inspect<IntoFuture<Fut>, InspectOkFn<F>>: Future,     type Output = <Inspect<IntoFuture<Fut>, InspectOkFn<F>> as Future>::Output;
        where
            F: FnOnce(&Self::Ok),
            Self: Sized,
        { ... }
        fn inspect_err<F>(self, f: F) -> InspectErr<Self, F>ⓘNotable traits for InspectErr<Fut, F>impl<Fut, F> Future for InspectErr<Fut, F> where
        Inspect<IntoFuture<Fut>, InspectErrFn<F>>: Future,     type Output = <Inspect<IntoFuture<Fut>, InspectErrFn<F>> as Future>::Output;
        where
            F: FnOnce(&Self::Error),
            Self: Sized,
        { ... }
        fn try_flatten(self) -> TryFlatten<Self, Self::Ok>ⓘNotable traits for TryFlatten<Fut1, Fut2>impl<Fut1, Fut2> Future for TryFlatten<Fut1, Fut2> where
        TryFlatten<Fut1, Fut2>: Future,     type Output = <TryFlatten<Fut1, Fut2> as Future>::Output;
        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>ⓘNotable traits for UnwrapOrElse<Fut, F>impl<Fut, F> Future for UnwrapOrElse<Fut, F> where
        Map<IntoFuture<Fut>, UnwrapOrElseFn<F>>: Future,     type Output = <Map<IntoFuture<Fut>, UnwrapOrElseFn<F>> as Future>::Output;
        where
            Self: Sized,
            F: FnOnce(Self::Error) -> Self::Ok,
        { ... }
        fn into_future(self) -> IntoFuture<Self>ⓘNotable traits for IntoFuture<Fut>impl<Fut: TryFuture> Future for IntoFuture<Fut>    type Output = Result<Fut::Ok, Fut::Error>;
        where
            Self: Sized,
        { ... }
        fn try_poll_unpin(
            &mut self,
            cx: &mut Context<'_>
        ) -> Poll<Result<Self::Ok, Self::Error>>
        where
            Self: Unpin,
        { ... }
    }

Adapters specific to `Result`-returning futures

## Provided methods

### `fn map_ok<T, F>(self, f: F) -> MapOk<Self, F>ⓘ

### Notable traits for MapOk<Fut, F>

`impl<Fut, F> Future for MapOk<Fut, F> where
Map<IntoFuture<Fut>, MapOkFn<F>>: Future, type Output = <Map<IntoFuture<Fut>, MapOkFn<F>> as Future>::Output;`
where
F: FnOnce(Self::Ok) -> T,
Self: Sized,` [src]

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

### `fn map_ok_or_else<T, E, F>(self, e: E, f: F) -> MapOkOrElse<Self, F, E>ⓘ

### Notable traits for MapOkOrElse<Fut, F, G>

`impl<Fut, F, G> Future for MapOkOrElse<Fut, F, G> where
Map<IntoFuture<Fut>, ChainFn<MapOkFn<F>, ChainFn<MapErrFn<G>, MergeResultFn>>>: Future, type Output = <Map<IntoFuture<Fut>, ChainFn<MapOkFn<F>, ChainFn<MapErrFn<G>, MergeResultFn>>> as Future>::Output;`
where
F: FnOnce(Self::Ok) -> T,
E: FnOnce(Self::Error) -> T,
Self: Sized,` [src]

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

### `fn map_err<E, F>(self, f: F) -> MapErr<Self, F>ⓘ

### Notable traits for MapErr<Fut, F>

`impl<Fut, F> Future for MapErr<Fut, F> where
Map<IntoFuture<Fut>, MapErrFn<F>>: Future, type Output = <Map<IntoFuture<Fut>, MapErrFn<F>> as Future>::Output;`
where
F: FnOnce(Self::Error) -> E,
Self: Sized,` [src]

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

### `fn err_into<E>(self) -> ErrInto<Self, E>ⓘ

### Notable traits for ErrInto<Fut, E>

`impl<Fut, E> Future for ErrInto<Fut, E> where
MapErr<Fut, IntoFn<E>>: Future, type Output = <MapErr<Fut, IntoFn<E>> as Future>::Output;`
where
Self: Sized,
Self::Error: Into<E>,` [src]

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

### `fn ok_into<U>(self) -> OkInto<Self, U>ⓘ

### Notable traits for OkInto<Fut, E>

`impl<Fut, E> Future for OkInto<Fut, E> where
MapOk<Fut, IntoFn<E>>: Future, type Output = <MapOk<Fut, IntoFn<E>> as Future>::Output;`
where
Self: Sized,
Self::Ok: Into<U>,` [src]

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

### `fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F>ⓘ

### Notable traits for AndThen<Fut1, Fut2, F>

`impl<Fut1, Fut2, F> Future for AndThen<Fut1, Fut2, F> where
TryFlatten<MapOk<Fut1, F>, Fut2>: Future, type Output = <TryFlatten<MapOk<Fut1, F>, Fut2> as Future>::Output;`
where
F: FnOnce(Self::Ok) -> Fut,
Fut: TryFuture<Error = Self::Error>,
Self: Sized,` [src]

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

### `fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F>ⓘ

### Notable traits for OrElse<Fut1, Fut2, F>

`impl<Fut1, Fut2, F> Future for OrElse<Fut1, Fut2, F> where
TryFlattenErr<MapErr<Fut1, F>, Fut2>: Future, type Output = <TryFlattenErr<MapErr<Fut1, F>, Fut2> as Future>::Output;`
where
F: FnOnce(Self::Error) -> Fut,
Fut: TryFuture<Ok = Self::Ok>,
Self: Sized,` [src]

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

### `fn inspect_ok<F>(self, f: F) -> InspectOk<Self, F>ⓘ

### Notable traits for InspectOk<Fut, F>

`impl<Fut, F> Future for InspectOk<Fut, F> where
Inspect<IntoFuture<Fut>, InspectOkFn<F>>: Future, type Output = <Inspect<IntoFuture<Fut>, InspectOkFn<F>> as Future>::Output;`
where
F: FnOnce(&Self::Ok),
Self: Sized,` [src]

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

### `fn inspect_err<F>(self, f: F) -> InspectErr<Self, F>ⓘ

### Notable traits for InspectErr<Fut, F>

`impl<Fut, F> Future for InspectErr<Fut, F> where
Inspect<IntoFuture<Fut>, InspectErrFn<F>>: Future, type Output = <Inspect<IntoFuture<Fut>, InspectErrFn<F>> as Future>::Output;`
where
F: FnOnce(&Self::Error),
Self: Sized,` [src]

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

### `fn try_flatten(self) -> TryFlatten<Self, Self::Ok>ⓘ

### Notable traits for TryFlatten<Fut1, Fut2>

`impl<Fut1, Fut2> Future for TryFlatten<Fut1, Fut2> where
TryFlatten<Fut1, Fut2>: Future, type Output = <TryFlatten<Fut1, Fut2> as Future>::Output;`
where
Self::Ok: TryFuture<Error = Self::Error>,
Self: Sized,` [src]

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

### `fn try_flatten_stream(self) -> TryFlattenStream<Self> where
Self::Ok: TryStream<Error = Self::Error>,
Self: Sized,` [src]

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

### `fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F>ⓘ

### Notable traits for UnwrapOrElse<Fut, F>

`impl<Fut, F> Future for UnwrapOrElse<Fut, F> where
Map<IntoFuture<Fut>, UnwrapOrElseFn<F>>: Future, type Output = <Map<IntoFuture<Fut>, UnwrapOrElseFn<F>> as Future>::Output;`
where
Self: Sized,
F: FnOnce(Self::Error) -> Self::Ok,` [src]

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

### `fn into_future(self) -> IntoFuture<Self>ⓘ

### Notable traits for IntoFuture<Fut>

`impl<Fut: TryFuture> Future for IntoFuture<Fut> type Output = Result<Fut::Ok, Fut::Error>;`
where
Self: Sized,` [src]

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

### `fn try_poll_unpin(
&mut self,
cx: &mut Context<'_>
) -> Poll<Result<Self::Ok, Self::Error>> where
Self: Unpin,` [src]

A convenience method for calling `TryFuture::try_poll` on `Unpin` future types.

Loading content...

## Implementors

### `impl<Fut: ?Sized + TryFuture> TryFutureExt for Fut` [src]

Loading content...