Struct cap_rand::distributions::Slice

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

A distribution to sample items uniformly from a slice.

Slice::new constructs a distribution referencing a slice and uniformly samples references from the items in the slice. It may do extra work up front to make sampling of multiple values faster; if only one sample from the slice is required, SliceRandom::choose can be more efficient.

Steps are taken to avoid bias which might be present in naive implementations; for example slice[rng.gen() % slice.len()] samples from the slice, but may be more likely to select numbers in the low range than other values.

This distribution samples with replacement; each sample is independent. Sampling without replacement requires state to be retained, and therefore cannot be handled by a distribution; you should instead consider methods on SliceRandom, such as SliceRandom::choose_multiple.

Example

use rand::Rng;
use rand::distributions::Slice;

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

// build a string of 10 vowels
let vowel_string: String = rng
    .sample_iter(&vowels_dist)
    .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, SliceRandom::choose may be preferred:

use rand::seq::SliceRandom;

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

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

Implementations

impl<'a, T> Slice<'a, T>

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

Create a new Slice instance which samples uniformly from the slice. Returns Err if the slice is empty.

Trait Implementations

impl<'a, T> Clone for Slice<'a, T> where
    T: Clone, 

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, T> Debug for Slice<'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 Slice<'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) -> DistIter<Self, R, T> where
    R: Rng, 

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

fn map<F, S>(self, func: F) -> DistMap<Self, F, T, S> where
    F: Fn(T) -> S, 

Create a distribution of values of ‘S’ by mapping the output of Self through the closure F

impl<'a, T> Copy for Slice<'a, T> where
    T: Copy,