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<Self, 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) -> NonZeroUsize

Returns the count of choices in this distribution

Trait Implementations

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

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

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>

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

Append len random chars to string

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

Generate a String of len random chars

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