# IteratorRandom in rand::seq - Rust
Extension trait on iterators, providing random sampling methods.
Keywords: rust, rustlang, rust-lang, IteratorRandom

# Trait rand::seq::IteratorRandom

source · [−]

    pub trait IteratorRandom: Iterator + Sized {
        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,
        { ... }
    }

Expand description

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

source

#### 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`.

source

#### 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| ())`.

source

#### 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`.

source

#### fn choose_multiple<R>(self, rng: &mut R, amount: usize) -> Vec<Self::Item> where
R: Rng + ?Sized,

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`.

## Implementors

source

### impl<I> IteratorRandom for I where
I: Iterator + Sized,