Struct 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<Self, 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> Clone for Slice<'a, T>

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> Debug for Slice<'a, T>

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

Formats the value using the given formatter.

impl<'a, T> Distribution<&'a T> for Slice<'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) -> DistIter<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) -> DistMap<Self, F, T, S>

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

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

impl<'a, T: Copy> Copy for Slice<'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: 40 bytes