logo

Trait async_std::stream::ExactSizeStream

source · [−]
pub trait ExactSizeStream: Stream {
    fn len(&self) -> usize { ... }
}
Available on unstable only.
Expand description

A stream that knows its exact length.

Many Streams don’t know how many times they will iterate, but some do. If a stream knows how many times it can iterate, providing access to that information can be useful. For example, if you want to iterate backwards, a good start is to know where the end is.

When implementing an ExactSizeStream, you must also implement Stream. When doing so, the implementation of size_hint must return the exact size of the stream.

The len method has a default implementation, so you usually shouldn’t implement it. However, you may be able to provide a more performant implementation than the default, so overriding it in this case makes sense.

Examples

Basic usage:

// a finite range knows exactly how many times it will iterate
let five = 0..5;

assert_eq!(5, five.len());

In the module level docs, we implemented an Stream, Counter. Let’s implement ExactSizeStream for it as well:

impl ExactSizeStream for Counter {
    // We can easily calculate the remaining number of iterations.
    fn len(&self) -> usize {
        5 - self.count
    }
}

// And now we can use it!

let counter = Counter::new();

assert_eq!(5, counter.len());

Provided Methods

Returns the exact number of times the stream will iterate.

This method has a default implementation, so you usually should not implement it directly. However, if you can provide a more efficient implementation, you can do so. See the trait-level docs for an example.

This function has the same safety guarantees as the size_hint function.

Examples

Basic usage:

// a finite range knows exactly how many times it will iterate
let five = 0..5;

assert_eq!(5, five.len());

Implementations on Foreign Types

Implementors