Trait IndexedRandom Copy item path

The length

True when the length is zero

Uniformly sample one element

Returns a reference to one uniformly-sampled random element of the slice, or None if the slice is empty.

For slices, complexity is O(1).

§Example

use rand::seq::IndexedRandom;

let choices = [1, 2, 4, 8, 16, 32];
let mut rng = rand::rng();
println!("{:?}", choices.choose(&mut rng));
assert_eq!(choices[..0].choose(&mut rng), None);

Return an iterator which samples from self with replacement

Returns None if and only if self.is_empty().

§Example

use rand::seq::IndexedRandom;

let choices = [1, 2, 4, 8, 16, 32];
let mut rng = rand::rng();
for choice in choices.choose_iter(&mut rng).unwrap().take(3) {
    println!("{:?}", choice);
}

Uniformly sample amount distinct elements from self

Chooses amount elements from the slice at random, without repetition, and in random order. The returned iterator is appropriate both for collection into a Vec and filling an existing buffer (see example).

In case this API is not sufficiently flexible, use index::sample.

For slices, complexity is the same as index::sample.

§Example

use rand::seq::IndexedRandom;

let mut rng = &mut rand::rng();
let sample = "Hello, audience!".as_bytes();

// collect the results into a vector:
let v: Vec<u8> = sample.sample(&mut rng, 3).cloned().collect();

// store in a buffer:
let mut buf = [0u8; 5];
for (b, slot) in sample.sample(&mut rng, buf.len()).zip(buf.iter_mut()) {
    *slot = *b;
}

Uniformly sample a fixed-size array of distinct elements from self

Chooses N elements from the slice at random, without repetition, and in random order.

For slices, complexity is the same as index::sample_array.

§Example

use rand::seq::IndexedRandom;

let mut rng = &mut rand::rng();
let sample = "Hello, audience!".as_bytes();

let a: [u8; 3] = sample.sample_array(&mut rng).unwrap();

Biased sampling for one element

Returns a reference to one element of the slice, sampled according to the provided weights. Returns None if and only if self.is_empty().

The specified function weight maps each item x to a relative likelihood weight(x). The probability of each item being selected is therefore weight(x) / s, where s is the sum of all weight(x).

For slices of length n, complexity is O(n). For more information about the underlying algorithm, see the WeightedIndex distribution.

See also choose_weighted_mut.

§Example

use rand::prelude::*;

let choices = [('a', 2), ('b', 1), ('c', 1), ('d', 0)];
let mut rng = rand::rng();
// 50% chance to print 'a', 25% chance to print 'b', 25% chance to print 'c',
// and 'd' will never be printed
println!("{:?}", choices.choose_weighted(&mut rng, |item| item.1).unwrap().0);

Biased sampling with replacement

Returns an iterator which samples elements from self according to the given weights with replacement (i.e. elements may be repeated). Returns None if and only if self.is_empty().

See also doc for Self::choose_weighted.

Biased sampling of amount distinct elements

Similar to sample, but where the likelihood of each element’s inclusion in the output may be specified. Zero-weighted elements are never returned; the result may therefore contain fewer elements than amount even when self.len() >= amount. The elements are returned in an arbitrary, unspecified order.

The specified function weight maps each item x to a relative likelihood weight(x). The probability of each item being selected is therefore weight(x) / s, where s is the sum of all weight(x).

This implementation uses O(length + amount) space and O(length) time. See index::sample_weighted for details.

§Example

use rand::prelude::*;

let choices = [('a', 2), ('b', 1), ('c', 1)];
let mut rng = rand::rng();
// First Draw * Second Draw = total odds
// -----------------------
// (50% * 50%) + (25% * 67%) = 41.7% chance that the output is `['a', 'b']` in some order.
// (50% * 50%) + (25% * 67%) = 41.7% chance that the output is `['a', 'c']` in some order.
// (25% * 33%) + (25% * 33%) = 16.6% chance that the output is `['b', 'c']` in some order.
println!("{:?}", choices.sample_weighted(&mut rng, 2, |item| item.1).unwrap().collect::<Vec<_>>());

Deprecated: use Self::sample instead

Deprecated: use Self::sample_array instead

Deprecated: use Self::sample_weighted instead