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 duplicate 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>

Available on crate feature alloc only.

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>

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 56 bytes