Struct `Choose`

struct Choose<'a, T> { ... }

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

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.

fn num_choices(self: &Self) -> NonZeroUsize

Returns the count of choices in this distribution

`impl SampleString for Choose<'_, char>`

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

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

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

`impl<'a, T> Freeze for Choose<'a, T>`

`impl<'a, T> RefUnwindSafe for Choose<'a, T>`

`impl<'a, T> Send for Choose<'a, T>`

`impl<'a, T> Sync for Choose<'a, T>`

`impl<'a, T> Unpin for Choose<'a, T>`

`impl<'a, T> UnwindSafe for Choose<'a, T>`

`impl<'a, T: $crate::clone::Clone> Clone for Choose<'a, T>`

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

`impl<'a, T: $crate::fmt::Debug> Debug for Choose<'a, T>`

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

`impl<'a, T: $crate::marker::Copy> Copy for Choose<'a, T>`

`impl<T> Any for Choose<'a, T>`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for Choose<'a, T>`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for Choose<'a, T>`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for Choose<'a, T>`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for Choose<'a, T>`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for Choose<'a, T>`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, U> Into for Choose<'a, T>`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for Choose<'a, T>`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for Choose<'a, T>`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

`impl<V, T> VZip for Choose<'a, T>`

fn vzip(self: Self) -> V