Struct Choose 

pub struct Choose<'a, T> { /* private fields */ }

A distribution to uniformly sample elements of a slice

Like IndexedRandom::choose, this uniformly samples elements of a slice without modification of the slice (so called “sampling with replacement”). This distribution object may be a little faster for repeated sampling (but slower for small numbers of samples).

Examples

Since this is a distribution, Rng::sample_iter and Distribution::sample_iter may be used, for example:

use rand::distr::{Distribution, slice::Choose};

let vowels = ['a', 'e', 'i', 'o', 'u'];
let vowels_dist = Choose::new(&vowels).unwrap();

// build a string of 10 vowels
let vowel_string: String = vowels_dist
    .sample_iter(&mut rand::rng())
    .take(10)
    .collect();

println!("{}", vowel_string);
assert_eq!(vowel_string.len(), 10);
assert!(vowel_string.chars().all(|c| vowels.contains(&c)));

For a single sample, IndexedRandom::choose may be preferred:

use rand::seq::IndexedRandom;

let vowels = ['a', 'e', 'i', 'o', 'u'];
let mut rng = rand::rng();

println!("{}", vowels.choose(&mut rng).unwrap());

Implementations

impl<'a, T> Choose<'a, T>

pub fn new(slice: &'a [T]) -> Result<Choose<'a, T>, Empty>

Create a new Choose instance which samples uniformly from the slice.

Returns error Empty if the slice is empty.

pub fn num_choices(&self) -> NonZero<usize>

Returns the count of choices in this distribution

Trait Implementations

impl<'a, T> Clone for Choose<'a, T>

where T: Clone,

fn clone(&self) -> Choose<'a, T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, T> Copy for Choose<'a, T>

where T: Copy,

impl<'a, T> Debug for Choose<'a, T>

where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a, T> Distribution<&'a T> for Choose<'a, T>

fn sample<R>(&self, rng: &mut R) -> &'a T

where R: Rng + ?Sized,

Generate a random value of T, using rng as the source of randomness.

fn sample_iter<R>(self, rng: R) -> Iter<Self, R, T>

where R: Rng, Self: Sized,

Create an iterator that generates random values of T, using rng as the source of randomness.

fn map<F, S>(self, func: F) -> Map<Self, F, T, S>

where F: Fn(T) -> S, Self: Sized,

Map sampled values to type S

impl SampleString for Choose<'_, char>

Available on crate feature alloc only.

fn append_string<R>(&self, rng: &mut R, string: &mut String, len: usize)

where R: Rng + ?Sized,

Append len random chars to string

fn sample_string<R>(&self, rng: &mut R, len: usize) -> String

where R: Rng + ?Sized,

Generate a String of len random chars