Trait ExactSizeStream

pub trait ExactSizeStream: Stream {
    // Provided method
    fn len(&self) -> usize { ... }
}

Available on unstable only.

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

fn len(&self) -> usize

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

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<I: ExactSizeStream + ?Sized + Unpin> ExactSizeStream for &mut I

fn len(&self) -> usize

Implementors

impl<T> ExactSizeStream for Pending<T>