Trait SliceRandom

pub trait SliceRandom {
    type Item;

    // Required methods
    fn choose<R>(&self, rng: &mut R) -> Option<&Self::Item>
       where R: Rng + ?Sized;
    fn choose_mut<R>(&mut self, rng: &mut R) -> Option<&mut Self::Item>
       where R: Rng + ?Sized;
    fn shuffle<R>(&mut self, rng: &mut R)
       where R: Rng + ?Sized;
    fn partial_shuffle<R>(
        &mut self,
        rng: &mut R,
        amount: usize,
    ) -> (&mut [Self::Item], &mut [Self::Item])
       where R: Rng + ?Sized;
}

Extension trait on slices, providing random mutation and sampling methods.

This trait is implemented on all [T] slice types, providing several methods for choosing and shuffling elements. You must use this trait:

use rand::seq::SliceRandom;

let mut rng = rand::thread_rng();
let mut bytes = "Hello, random!".to_string().into_bytes();
bytes.shuffle(&mut rng);
let str = String::from_utf8(bytes).unwrap();
println!("{}", str);

Example output (non-deterministic):

l,nmroHado !le

Required Associated Types

type Item

The element type.

Required Methods

fn choose<R>(&self, rng: &mut R) -> Option<&Self::Item>

where R: Rng + ?Sized,

Returns a reference to one random element of the slice, or None if the slice is empty.

For slices, complexity is O(1).

Example

use rand::thread_rng;
use rand::seq::SliceRandom;

let choices = [1, 2, 4, 8, 16, 32];
let mut rng = thread_rng();
println!("{:?}", choices.choose(&mut rng));
assert_eq!(choices[..0].choose(&mut rng), None);

fn choose_mut<R>(&mut self, rng: &mut R) -> Option<&mut Self::Item>

where R: Rng + ?Sized,

Returns a mutable reference to one random element of the slice, or None if the slice is empty.

For slices, complexity is O(1).

fn shuffle<R>(&mut self, rng: &mut R)

where R: Rng + ?Sized,

Shuffle a mutable slice in place.

For slices of length n, complexity is O(n).

Example

use rand::seq::SliceRandom;
use rand::thread_rng;

let mut rng = thread_rng();
let mut y = [1, 2, 3, 4, 5];
println!("Unshuffled: {:?}", y);
y.shuffle(&mut rng);
println!("Shuffled:   {:?}", y);

fn partial_shuffle<R>( &mut self, rng: &mut R, amount: usize, ) -> (&mut [Self::Item], &mut [Self::Item])

where R: Rng + ?Sized,

Shuffle a slice in place, but exit early.

Returns two mutable slices from the source slice. The first contains amount elements randomly permuted. The second has the remaining elements that are not fully shuffled.

This is an efficient method to select amount elements at random from the slice, provided the slice may be mutated.

If you only need to choose elements randomly and amount > self.len()/2 then you may improve performance by taking amount = values.len() - amount and using only the second slice.

If amount is greater than the number of elements in the slice, this will perform a full shuffle.

For slices, complexity is O(m) where m = amount.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T> SliceRandom for [T]

type Item = T

fn choose<R>(&self, rng: &mut R) -> Option<&Self::Item>

where R: Rng + ?Sized,

fn choose_mut<R>(&mut self, rng: &mut R) -> Option<&mut Self::Item>

where R: Rng + ?Sized,

fn shuffle<R>(&mut self, rng: &mut R)

where R: Rng + ?Sized,

fn partial_shuffle<R>( &mut self, rng: &mut R, amount: usize, ) -> (&mut [Self::Item], &mut [Self::Item])

where R: Rng + ?Sized,

Implementors