Trait IteratorRandom

pub trait IteratorRandom: Iterator + Sized {
    // Provided methods
    fn choose<R>(self, rng: &mut R) -> Option<Self::Item>
       where R: Rng + ?Sized { ... }
    fn choose_stable<R>(self, rng: &mut R) -> Option<Self::Item>
       where R: Rng + ?Sized { ... }
    fn choose_multiple_fill<R>(
        self,
        rng: &mut R,
        buf: &mut [Self::Item],
    ) -> usize
       where R: Rng + ?Sized { ... }
    fn choose_multiple<R>(self, rng: &mut R, amount: usize) -> Vec<Self::Item>
       where R: Rng + ?Sized { ... }
}

Extension trait on iterators, providing random sampling methods.

This trait is implemented on all iterators I where I: Iterator + Sized and provides methods for choosing one or more elements. You must use this trait:

use rand::seq::IteratorRandom;

let mut rng = rand::thread_rng();

let faces = "😀😎😐😕😠😢";
println!("I am {}!", faces.chars().choose(&mut rng).unwrap());

Example output (non-deterministic):

I am 😀!

Provided Methods

fn choose<R>(self, rng: &mut R) -> Option<Self::Item>

where R: Rng + ?Sized,

Choose one element at random from the iterator.

Returns None if and only if the iterator is empty.

This method uses Iterator::size_hint for optimisation. With an accurate hint and where Iterator::nth is a constant-time operation this method can offer O(1) performance. Where no size hint is available, complexity is O(n) where n is the iterator length. Partial hints (where lower > 0) also improve performance.

Note that the output values and the number of RNG samples used depends on size hints. In particular, Iterator combinators that don’t change the values yielded but change the size hints may result in choose returning different elements. If you want consistent results and RNG usage consider using IteratorRandom::choose_stable.

fn choose_stable<R>(self, rng: &mut R) -> Option<Self::Item>

where R: Rng + ?Sized,

Choose one element at random from the iterator.

Returns None if and only if the iterator is empty.

This method is very similar to choose except that the result only depends on the length of the iterator and the values produced by rng. Notably for any iterator of a given length this will make the same requests to rng and if the same sequence of values are produced the same index will be selected from self. This may be useful if you need consistent results no matter what type of iterator you are working with. If you do not need this stability prefer choose.

Note that this method still uses Iterator::size_hint to skip constructing elements where possible, however the selection and rng calls are the same in the face of this optimization. If you want to force every element to be created regardless call .inspect(|e| ()).

fn choose_multiple_fill<R>(self, rng: &mut R, buf: &mut [Self::Item]) -> usize

where R: Rng + ?Sized,

Collects values at random from the iterator into a supplied buffer until that buffer is filled.

Although the elements are selected randomly, the order of elements in the buffer is neither stable nor fully random. If random ordering is desired, shuffle the result.

Returns the number of elements added to the buffer. This equals the length of the buffer unless the iterator contains insufficient elements, in which case this equals the number of elements available.

Complexity is O(n) where n is the length of the iterator. For slices, prefer SliceRandom::choose_multiple.

fn choose_multiple<R>(self, rng: &mut R, amount: usize) -> Vec<Self::Item>

where R: Rng + ?Sized,

Available on crate feature alloc only.

Collects amount values at random from the iterator into a vector.

This is equivalent to choose_multiple_fill except for the result type.

Although the elements are selected randomly, the order of elements in the buffer is neither stable nor fully random. If random ordering is desired, shuffle the result.

The length of the returned vector equals amount unless the iterator contains insufficient elements, in which case it equals the number of elements available.

Complexity is O(n) where n is the length of the iterator. For slices, prefer SliceRandom::choose_multiple.

Object Safety

This trait is not object safe.

Implementors

impl<I> IteratorRandom for I

where I: Iterator + Sized,