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

###

###

###

###

###

###

###

###

###

###

    pub trait FutureExt: Future {
        fn map<U, F>(self, f: F) -> Map<Self, F>ⓘNotable traits for Map<Fut, F>impl<Fut, F> Future for Map<Fut, F> where
        Map<Fut, F>: Future,     type Output = <Map<Fut, F> as Future>::Output;
        where
            F: FnOnce(Self::Output) -> U,
            Self: Sized,
        { ... }
        fn map_into<U>(self) -> MapInto<Self, U>ⓘNotable traits for MapInto<Fut, T>impl<Fut, T> Future for MapInto<Fut, T> where
        Map<Fut, IntoFn<T>>: Future,     type Output = <Map<Fut, IntoFn<T>> as Future>::Output;
        where
            Self::Output: Into<U>,
            Self: Sized,
        { ... }
        fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F>ⓘNotable traits for Then<Fut1, Fut2, F>impl<Fut1, Fut2, F> Future for Then<Fut1, Fut2, F> where
        Flatten<Map<Fut1, F>, Fut2>: Future,     type Output = <Flatten<Map<Fut1, F>, Fut2> as Future>::Output;
        where
            F: FnOnce(Self::Output) -> Fut,
            Fut: Future,
            Self: Sized,
        { ... }
        fn left_future<B>(self) -> Either<Self, B>ⓘNotable traits for Either<A, B>impl<A, B> Future for Either<A, B> where
        A: Future,
        B: Future<Output = A::Output>,     type Output = A::Output;
        where
            B: Future<Output = Self::Output>,
            Self: Sized,
        { ... }
        fn right_future<A>(self) -> Either<A, Self>ⓘNotable traits for Either<A, B>impl<A, B> Future for Either<A, B> where
        A: Future,
        B: Future<Output = A::Output>,     type Output = A::Output;
        where
            A: Future<Output = Self::Output>,
            Self: Sized,
        { ... }
        fn into_stream(self) -> IntoStream<Self>
        where
            Self: Sized,
        { ... }
        fn flatten(self) -> Flatten<Self>ⓘNotable traits for Flatten<F>impl<F> Future for Flatten<F> where
        Flatten<F, <F as Future>::Output>: Future,
        F: Future,     type Output = <Flatten<F, <F as Future>::Output> as Future>::Output;
        where
            Self::Output: Future,
            Self: Sized,
        { ... }
        fn flatten_stream(self) -> FlattenStream<Self>
        where
            Self::Output: Stream,
            Self: Sized,
        { ... }
        fn fuse(self) -> Fuse<Self>ⓘNotable traits for Fuse<Fut>impl<Fut: Future> Future for Fuse<Fut>    type Output = Fut::Output;
        where
            Self: Sized,
        { ... }
        fn inspect<F>(self, f: F) -> Inspect<Self, F>ⓘNotable traits for Inspect<Fut, F>impl<Fut, F> Future for Inspect<Fut, F> where
        Map<Fut, InspectFn<F>>: Future,     type Output = <Map<Fut, InspectFn<F>> as Future>::Output;
        where
            F: FnOnce(&Self::Output),
            Self: Sized,
        { ... }
        fn unit_error(self) -> UnitError<Self>ⓘNotable traits for UnitError<Fut>impl<Fut> Future for UnitError<Fut> where
        Map<Fut, OkFn<()>>: Future,     type Output = <Map<Fut, OkFn<()>> as Future>::Output;
        where
            Self: Sized,
        { ... }
        fn never_error(self) -> NeverError<Self>ⓘNotable traits for NeverError<Fut>impl<Fut> Future for NeverError<Fut> where
        Map<Fut, OkFn<Never>>: Future,     type Output = <Map<Fut, OkFn<Never>> as Future>::Output;
        where
            Self: Sized,
        { ... }
        fn poll_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output>
        where
            Self: Unpin,
        { ... }
        fn now_or_never(self) -> Option<Self::Output>
        where
            Self: Sized,
        { ... }
    }

An extension trait for `Future`s that provides a variety of convenient adapters.

## Provided methods

### `fn map<U, F>(self, f: F) -> Map<Self, F>ⓘ

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

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

Map this future’s output to a different type, returning a new future of the resulting type.

This function is similar to the `Option::map` or `Iterator::map` where it will change the type of the underlying future. This is useful to chain along a computation once a future has been resolved.

Note that this function consumes the receiving future and returns a wrapped version of it, similar to the existing `map` methods in the standard library.

# Examples

    use futures::future::FutureExt;

    let future = async { 1 };
    let new_future = future.map(|x| x + 3);
    assert_eq!(new_future.await, 4);

### `fn map_into<U>(self) -> MapInto<Self, U>ⓘ

### Notable traits for MapInto<Fut, T>

`impl<Fut, T> Future for MapInto<Fut, T> where
Map<Fut, IntoFn<T>>: Future, type Output = <Map<Fut, IntoFn<T>> as Future>::Output;`
where
Self::Output: Into<U>,
Self: Sized,` [src]

Map this future’s output to a different type, returning a new future of the resulting type.

This function is equivalent to calling `map(Into::into)` but allows naming the return type.

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

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

`impl<Fut1, Fut2, F> Future for Then<Fut1, Fut2, F> where
Flatten<Map<Fut1, F>, Fut2>: Future, type Output = <Flatten<Map<Fut1, F>, Fut2> as Future>::Output;`
where
F: FnOnce(Self::Output) -> Fut,
Fut: Future,
Self: Sized,` [src]

Chain on a computation for when a future finished, passing the result of the future to the provided closure `f`.

The returned value of the closure must implement the `Future` trait and can represent some more work to be done before the composed future is finished.

The closure `f` is only run after successful completion of the `self` future.

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

# Examples

    use futures::future::FutureExt;

    let future_of_1 = async { 1 };
    let future_of_4 = future_of_1.then(|x| async move { x + 3 });
    assert_eq!(future_of_4.await, 4);

### `fn left_future<B>(self) -> Either<Self, B>ⓘ

### Notable traits for Either<A, B>

`impl<A, B> Future for Either<A, B> where
A: Future,
B: Future<Output = A::Output>, type Output = A::Output;`
where
B: Future<Output = Self::Output>,
Self: Sized,` [src]

Wrap this future in an `Either` future, making it the left-hand variant of that `Either`.

This can be used in combination with the `right_future` method to write `if` statements that evaluate to different futures in different branches.

# Examples

    use futures::future::FutureExt;

    let x = 6;
    let future = if x < 10 {
        async { true }.left_future()
    } else {
        async { false }.right_future()
    };

    assert_eq!(future.await, true);

### `fn right_future<A>(self) -> Either<A, Self>ⓘ

### Notable traits for Either<A, B>

`impl<A, B> Future for Either<A, B> where
A: Future,
B: Future<Output = A::Output>, type Output = A::Output;`
where
A: Future<Output = Self::Output>,
Self: Sized,` [src]

Wrap this future in an `Either` future, making it the right-hand variant of that `Either`.

This can be used in combination with the `left_future` method to write `if` statements that evaluate to different futures in different branches.

# Examples

    use futures::future::FutureExt;

    let x = 6;
    let future = if x > 10 {
        async { true }.left_future()
    } else {
        async { false }.right_future()
    };

    assert_eq!(future.await, false);

### `fn into_stream(self) -> IntoStream<Self> where
Self: Sized,` [src]

Convert this future into a single element stream.

The returned stream contains single success if this future resolves to success or single error if this future resolves into error.

# Examples

    use futures::future::FutureExt;
    use futures::stream::StreamExt;

    let future = async { 17 };
    let stream = future.into_stream();
    let collected: Vec<_> = stream.collect().await;
    assert_eq!(collected, vec![17]);

### `fn flatten(self) -> Flatten<Self>ⓘ

### Notable traits for Flatten<F>

`impl<F> Future for Flatten<F> where
Flatten<F, <F as Future>::Output>: Future,
F: Future, type Output = <Flatten<F, <F as Future>::Output> as Future>::Output;`
where
Self::Output: Future,
Self: Sized,` [src]

Flatten the execution of this future when the output of this future is itself another future.

This can be useful when combining futures together to flatten the computation out the final result.

This method is roughly equivalent to `self.then(|x| x)`.

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

# Examples

    use futures::future::FutureExt;

    let nested_future = async { async { 1 } };
    let future = nested_future.flatten();
    assert_eq!(future.await, 1);

### `fn flatten_stream(self) -> FlattenStream<Self> where
Self::Output: Stream,
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::FutureExt;
    use futures::stream::{self, StreamExt};

    let stream_items = vec![17, 18, 19];
    let future_of_a_stream = async { stream::iter(stream_items) };

    let stream = future_of_a_stream.flatten_stream();
    let list: Vec<_> = stream.collect().await;
    assert_eq!(list, vec![17, 18, 19]);

### `fn fuse(self) -> Fuse<Self>ⓘ

### Notable traits for Fuse<Fut>

`impl<Fut: Future> Future for Fuse<Fut> type Output = Fut::Output;`
where
Self: Sized,` [src]

Fuse a future such that `poll` will never again be called once it has completed. This method can be used to turn any `Future` into a `FusedFuture`.

Normally, once a future has returned `Poll::Ready` from `poll`, any further calls could exhibit bad behavior such as blocking forever, panicking, never returning, etc. If it is known that `poll` may be called too often then this method can be used to ensure that it has defined semantics.

If a `fuse`d future is `poll`ed after having returned `Poll::Ready` previously, it will return `Poll::Pending`, from `poll` again (and will continue to do so for all future calls to `poll`).

This combinator will drop the underlying future as soon as it has been completed to ensure resources are reclaimed as soon as possible.

### `fn inspect<F>(self, f: F) -> Inspect<Self, F>ⓘ

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

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

Do something with the output 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`.

# Examples

    use futures::future::FutureExt;

    let future = async { 1 };
    let new_future = future.inspect(|&x| println!("about to resolve: {}", x));
    assert_eq!(new_future.await, 1);

### `fn unit_error(self) -> UnitError<Self>ⓘ

### Notable traits for UnitError<Fut>

`impl<Fut> Future for UnitError<Fut> where
Map<Fut, OkFn<()>>: Future, type Output = <Map<Fut, OkFn<()>> as Future>::Output;`
where
Self: Sized,` [src]

Turns a `Future<Output = T>` into a `TryFuture<Ok = T, Error = ()`>.

### `fn never_error(self) -> NeverError<Self>ⓘ

### Notable traits for NeverError<Fut>

`impl<Fut> Future for NeverError<Fut> where
Map<Fut, OkFn<Never>>: Future, type Output = <Map<Fut, OkFn<Never>> as Future>::Output;`
where
Self: Sized,` [src]

Turns a `Future<Output = T>` into a `TryFuture<Ok = T, Error = Never`>.

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

A convenience for calling `Future::poll` on `Unpin` future types.

### `fn now_or_never(self) -> Option<Self::Output> where
Self: Sized,` [src]

Evaluates and consumes the future, returning the resulting output if the future is ready after the first call to `Future::poll`.

If `poll` instead returns `Poll::Pending`, `None` is returned.

This method is useful in cases where immediacy is more important than waiting for a result. It is also convenient for quickly obtaining the value of a future that is known to always resolve immediately.

# Examples

    use futures::{future::ready, future::pending};
    let future_ready = ready("foobar");
    let future_pending = pending::<&'static str>();

    assert_eq!(future_ready.now_or_never(), Some("foobar"));
    assert_eq!(future_pending.now_or_never(), None);

In cases where it is absolutely known that a future should always resolve immediately and never return `Poll::Pending`, this method can be combined with `expect()`:

    let future_ready = ready("foobar");

    assert_eq!(future_ready.now_or_never().expect("Future not ready"), "foobar");

Loading content...

## Implementors

### `impl<T: ?Sized> FutureExt for T where
T: Future,` [src]

Loading content...