Creates a future that resolves to the next item in the stream.
Note that because next doesn't take ownership over the stream,
the Stream type must be [Unpin]. If you want to use next with a
!Unpin stream, you'll first have to pin the stream. This can
be done by boxing the stream using Box::pinned or
pinning it to the stack using the pin_mut! macro from the pin_utils
crate.
Converts this stream into a future of (next_item, tail_of_stream).
If the stream terminates, then the next item is None.
The returned future can be used to compose streams and futures together
by placing everything into the "world of futures".
Note that because into_future moves the stream, the Stream type
must be [Unpin]. If you want to use into_future with a
!Unpin stream, you'll first have to pin the stream. This can
be done by boxing the stream using Box::pinned or
pinning it to the stack using the pin_mut! macro from the pin_utils
crate.
Maps this stream's items to a different type, returning a new stream of
the resulting type.
The provided closure is executed over all elements of this stream as
they are made available. It is executed inline with calls to
poll_next.
Note that this function consumes the stream passed into it and returns a
wrapped version of it, similar to the existing map methods in the
standard library.
Filters the values produced by this stream according to the provided
asynchronous predicate.
As values of this stream are made available, the provided predicate f
will be run against them. If the predicate returns a Future which
resolves to true, then the stream will yield the value, but if the
predicate returns a Future which resolves to false, then the value
will be discarded and the next value will be produced.
Note that this function consumes the stream passed into it and returns a
wrapped version of it, similar to the existing filter methods in the
standard library.
Filters the values produced by this stream while simultaneously mapping
them to a different type according to the provided asynchronous closure.
As values of this stream are made available, the provided function will
be run on them. If the future returned by the predicate f resolves to
Some(item) then the stream will yield the value item, but if
it resolves to None then the next value will be produced.
Note that this function consumes the stream passed into it and returns a
wrapped version of it, similar to the existing filter_map methods in
the standard library.
Computes from this stream's items new items of a different type using
an asynchronous closure.
The provided closure f will be called with an Item once a value is
ready, it returns a future which will then be run to completion
to produce the next value on this stream.
Note that this function consumes the stream passed into it and returns a
wrapped version of it.
Concatenate all items of a stream into a single extendable
destination, returning a future representing the end result.
This combinator will extend the first item with the contents
of all the subsequent results of the stream. If the stream is
empty, the default value will be returned.
Works with all collections that implement the
Extend trait.
Execute an accumulating asynchronous computation over a stream,
collecting all the values into one final result.
This combinator will accumulate all values returned by this stream
according to the closure provided. The initial state is also provided to
this method and then is returned again by each execution of the closure.
Once the entire stream has been exhausted the returned future will
resolve to this value.
Skip elements on this stream while the provided asynchronous predicate
resolves to true.
This function, like Iterator::skip_while, will skip elements on the
stream until the predicate f resolves to false. Once one element
returns false all future elements will be returned from the underlying
stream.
Take elements from this stream while the provided asynchronous predicate
resolves to true.
This function, like Iterator::take_while, will take elements from the
stream until the predicate f resolves to false. Once one element
returns false it will always return that the stream is done.
Runs this stream to completion, executing the provided asynchronous
closure for each element on the stream.
The closure provided will be called for each item this stream produces,
yielding a future. That future will then be executed to completion
before moving on to the next item.
The returned value is a Future where the Output type is (); it is
executed entirely for its side effects.
To process each item in the stream and produce another stream instead
of a single future, use then instead.
Runs this stream to completion, executing the provided asynchronous
closure for each element on the stream concurrently as elements become
available.
This is similar to StreamExt::for_each, but the futures
produced by the closure are run concurrently (but not in parallel--
this combinator does not introduce any threads).
The closure provided will be called for each item this stream produces,
yielding a future. That future will then be executed to completion
concurrently with the other futures produced by the closure.
The first argument is an optional limit on the number of concurrent
futures. If this limit is not None, no more than limit futures
will be run concurrently. The limit argument is of type
Into<Option<usize>>, and so can be provided as either None,
Some(10), or just 10. Note: a limit of zero is interpreted as
no limit at all, and will have the same result as passing in None.
This method is only available when the std feature of this
library is activated, and it is activated by default.
Fuse a stream such that poll_next will never
again be called once it has finished.
Normally, once a stream has returned None from
poll_next any further calls could exhibit bad
behavior such as block forever, panic, never return, etc. If it is known
that poll_next may be called after stream
has already finished, then this method can be used to ensure that it has
defined semantics.
The poll_next method of a fused stream
is guaranteed to return None after the underlying stream has
finished.
Catches unwinding panics while polling the stream.
Caught panic (if any) will be the last element of the resulting stream.
In general, panics within a stream can propagate all the way out to the
task level. This combinator makes it possible to halt unwinding within
the stream itself. It's most commonly used within task executors. This
method should not be used for error handling.
Note that this method requires the UnwindSafe bound from the standard
library. This isn't always applied automatically, and the standard
library provides an AssertUnwindSafe wrapper type to apply it
after-the fact. To assist using this method, the Stream trait is
also implemented for AssertUnwindSafe<St> where St implements
Stream.
This method is only available when the std feature of this
library is activated, and it is activated by default.
An adaptor for creating a buffered list of pending futures.
If this stream's item can be converted into a future, then this adaptor
will buffer up to at most n futures and then return the outputs in the
same order as the underlying stream. No more than n futures will be
buffered at any point in time, and less than n may also be buffered
depending on the state of each future.
The returned stream will be a stream of each future's output.
This method is only available when the std feature of this
library is activated, and it is activated by default.
An adaptor for creating a buffered list of pending futures (unordered).
If this stream's item can be converted into a future, then this adaptor
will buffer up to n futures and then return the outputs in the order
in which they complete. No more than n futures will be buffered at
any point in time, and less than n may also be buffered depending on
the state of each future.
The returned stream will be a stream of each future's output.
This method is only available when the std feature of this
library is activated, and it is activated by default.
An adaptor for chunking up items of the stream inside a vector.
This combinator will attempt to pull items from this stream and buffer
them into a local vector. At most capacity items will get buffered
before they're yielded from the returned stream.
Note that the vectors returned from this iterator may not always have
capacity elements. If the underlying stream ended and only a partial
vector was created, it'll be returned. Additionally if an error happens
from the underlying stream then the currently buffered items will be
yielded.
This method is only available when the std feature of this
library is activated, and it is activated by default.
This combinator will attempt to pull items from both streams. Each
stream will be polled in a round-robin fashion, and whenever a stream is
ready to yield an item that item is yielded.
After one of the two input stream completes, the remaining one will be
polled exclusively. The returned stream completes when both input
streams have completed.
Note that this method consumes both streams and returns a wrapped
version of them.
A future that completes after the given stream has been fully processed
into the sink, including flushing.
This future will drive the stream to keep producing items until it is
exhausted, sending each item to the sink. It will complete once both the
stream is exhausted and the sink has received and flushed all items.
Note that the sink is not closed.
On completion, the sink is returned.
Note that this combinator is only usable with Unpin sinks.
Sinks that are not Unpin will need to be pinned in order to be used
with forward.
Do something with each item of this stream, afterwards passing it on.
This is similar to the Iterator::inspect method in the standard
library where it allows easily inspecting each value as it passes
through the stream, for example to debug what's going on.