# Trait rand::seq::SliceRandom

source · ```
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 choose_multiple<R>(
&self,
rng: &mut R,
amount: usize
) -> SliceChooseIter<'_, Self, Self::Item> ⓘ
where R: Rng + ?Sized;
fn choose_weighted<R, F, B, X>(
&self,
rng: &mut R,
weight: F
) -> Result<&Self::Item, WeightedError>
where R: Rng + ?Sized,
F: Fn(&Self::Item) -> B,
B: SampleBorrow<X>,
X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default;
fn choose_weighted_mut<R, F, B, X>(
&mut self,
rng: &mut R,
weight: F
) -> Result<&mut Self::Item, WeightedError>
where R: Rng + ?Sized,
F: Fn(&Self::Item) -> B,
B: SampleBorrow<X>,
X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default;
fn choose_multiple_weighted<R, F, X>(
&self,
rng: &mut R,
amount: usize,
weight: F
) -> Result<SliceChooseIter<'_, Self, Self::Item>, WeightedError>
where R: Rng + ?Sized,
F: Fn(&Self::Item) -> X,
X: Into<f64>;
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;
}
```

## Expand description

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§

## Required Methods§

source#### fn choose<R>(&self, rng: &mut R) -> Option<&Self::Item>where
R: Rng + ?Sized,

#### 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);
```

source#### fn choose_mut<R>(&mut self, rng: &mut R) -> Option<&mut Self::Item>where
R: Rng + ?Sized,

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

.

source#### fn choose_multiple<R>(
&self,
rng: &mut R,
amount: usize
) -> SliceChooseIter<'_, Self, Self::Item> ⓘwhere
R: Rng + ?Sized,

#### fn choose_multiple<R>( &self, rng: &mut R, amount: usize ) -> SliceChooseIter<'_, Self, Self::Item> ⓘwhere R: Rng + ?Sized,

**crate feature**only.

`alloc`

Chooses `amount`

elements from the slice at random, without repetition,
and in random order. The returned iterator is appropriate both for
collection into a `Vec`

and filling an existing buffer (see example).

In case this API is not sufficiently flexible, use `index::sample`

.

For slices, complexity is the same as `index::sample`

.

##### Example

```
use rand::seq::SliceRandom;
let mut rng = &mut rand::thread_rng();
let sample = "Hello, audience!".as_bytes();
// collect the results into a vector:
let v: Vec<u8> = sample.choose_multiple(&mut rng, 3).cloned().collect();
// store in a buffer:
let mut buf = [0u8; 5];
for (b, slot) in sample.choose_multiple(&mut rng, buf.len()).zip(buf.iter_mut()) {
*slot = *b;
}
```

source#### fn choose_weighted<R, F, B, X>(
&self,
rng: &mut R,
weight: F
) -> Result<&Self::Item, WeightedError>where
R: Rng + ?Sized,
F: Fn(&Self::Item) -> B,
B: SampleBorrow<X>,
X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default,

#### fn choose_weighted<R, F, B, X>( &self, rng: &mut R, weight: F ) -> Result<&Self::Item, WeightedError>where R: Rng + ?Sized, F: Fn(&Self::Item) -> B, B: SampleBorrow<X>, X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default,

**crate feature**only.

`alloc`

Similar to `choose`

, but where the likelihood of each outcome may be
specified.

The specified function `weight`

maps each item `x`

to a relative
likelihood `weight(x)`

. The probability of each item being selected is
therefore `weight(x) / s`

, where `s`

is the sum of all `weight(x)`

.

For slices of length `n`

, complexity is `O(n)`

.
For more information about the underlying algorithm,
see `distributions::WeightedIndex`

.

See also `choose_weighted_mut`

.

##### Example

```
use rand::prelude::*;
let choices = [('a', 2), ('b', 1), ('c', 1), ('d', 0)];
let mut rng = thread_rng();
// 50% chance to print 'a', 25% chance to print 'b', 25% chance to print 'c',
// and 'd' will never be printed
println!("{:?}", choices.choose_weighted(&mut rng, |item| item.1).unwrap().0);
```

source#### fn choose_weighted_mut<R, F, B, X>(
&mut self,
rng: &mut R,
weight: F
) -> Result<&mut Self::Item, WeightedError>where
R: Rng + ?Sized,
F: Fn(&Self::Item) -> B,
B: SampleBorrow<X>,
X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default,

#### fn choose_weighted_mut<R, F, B, X>( &mut self, rng: &mut R, weight: F ) -> Result<&mut Self::Item, WeightedError>where R: Rng + ?Sized, F: Fn(&Self::Item) -> B, B: SampleBorrow<X>, X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default,

**crate feature**only.

`alloc`

Similar to `choose_mut`

, but where the likelihood of each outcome may
be specified.

The specified function `weight`

maps each item `x`

to a relative
likelihood `weight(x)`

. The probability of each item being selected is
therefore `weight(x) / s`

, where `s`

is the sum of all `weight(x)`

.

For slices of length `n`

, complexity is `O(n)`

.
For more information about the underlying algorithm,
see `distributions::WeightedIndex`

.

See also `choose_weighted`

.

source#### fn choose_multiple_weighted<R, F, X>(
&self,
rng: &mut R,
amount: usize,
weight: F
) -> Result<SliceChooseIter<'_, Self, Self::Item>, WeightedError>where
R: Rng + ?Sized,
F: Fn(&Self::Item) -> X,
X: Into<f64>,

#### fn choose_multiple_weighted<R, F, X>( &self, rng: &mut R, amount: usize, weight: F ) -> Result<SliceChooseIter<'_, Self, Self::Item>, WeightedError>where R: Rng + ?Sized, F: Fn(&Self::Item) -> X, X: Into<f64>,

**crate feature**only.

`std`

Similar to `choose_multiple`

, but where the likelihood of each element’s
inclusion in the output may be specified. The elements are returned in an
arbitrary, unspecified order.

The specified function `weight`

maps each item `x`

to a relative
likelihood `weight(x)`

. The probability of each item being selected is
therefore `weight(x) / s`

, where `s`

is the sum of all `weight(x)`

.

If all of the weights are equal, even if they are all zero, each element has an equal likelihood of being selected.

This implementation uses `O(length + amount)`

space and `O(length)`

time
if the “nightly” feature is enabled, or `O(length)`

space and
`O(length + amount * log length)`

time otherwise.

##### Example

```
use rand::prelude::*;
let choices = [('a', 2), ('b', 1), ('c', 1)];
let mut rng = thread_rng();
// First Draw * Second Draw = total odds
// -----------------------
// (50% * 50%) + (25% * 67%) = 41.7% chance that the output is `['a', 'b']` in some order.
// (50% * 50%) + (25% * 67%) = 41.7% chance that the output is `['a', 'c']` in some order.
// (25% * 33%) + (25% * 33%) = 16.6% chance that the output is `['b', 'c']` in some order.
println!("{:?}", choices.choose_multiple_weighted(&mut rng, 2, |item| item.1).unwrap().collect::<Vec<_>>());
```

source#### fn shuffle<R>(&mut self, rng: &mut R)where
R: Rng + ?Sized,

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

.
The resulting permutation is picked uniformly from the set of all possible permutations.

##### 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);
```

source#### fn partial_shuffle<R>(
&mut self,
rng: &mut R,
amount: usize
) -> (&mut [Self::Item], &mut [Self::Item])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,

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`

.

## Implementations on Foreign Types§

source§### impl<T> SliceRandom for [T]

### 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,

source§#### fn choose_multiple<R>(
&self,
rng: &mut R,
amount: usize
) -> SliceChooseIter<'_, Self, Self::Item> ⓘwhere
R: Rng + ?Sized,

#### fn choose_multiple<R>( &self, rng: &mut R, amount: usize ) -> SliceChooseIter<'_, Self, Self::Item> ⓘwhere R: Rng + ?Sized,

**crate feature**only.

`alloc`

source§#### fn choose_weighted<R, F, B, X>(
&self,
rng: &mut R,
weight: F
) -> Result<&Self::Item, WeightedError>where
R: Rng + ?Sized,
F: Fn(&Self::Item) -> B,
B: SampleBorrow<X>,
X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default,

#### fn choose_weighted<R, F, B, X>( &self, rng: &mut R, weight: F ) -> Result<&Self::Item, WeightedError>where R: Rng + ?Sized, F: Fn(&Self::Item) -> B, B: SampleBorrow<X>, X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default,

**crate feature**only.

`alloc`

source§#### fn choose_weighted_mut<R, F, B, X>(
&mut self,
rng: &mut R,
weight: F
) -> Result<&mut Self::Item, WeightedError>where
R: Rng + ?Sized,
F: Fn(&Self::Item) -> B,
B: SampleBorrow<X>,
X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default,

#### fn choose_weighted_mut<R, F, B, X>( &mut self, rng: &mut R, weight: F ) -> Result<&mut Self::Item, WeightedError>where R: Rng + ?Sized, F: Fn(&Self::Item) -> B, B: SampleBorrow<X>, X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default,

**crate feature**only.

`alloc`

source§#### fn choose_multiple_weighted<R, F, X>(
&self,
rng: &mut R,
amount: usize,
weight: F
) -> Result<SliceChooseIter<'_, Self, Self::Item>, WeightedError>where
R: Rng + ?Sized,
F: Fn(&Self::Item) -> X,
X: Into<f64>,

#### fn choose_multiple_weighted<R, F, X>( &self, rng: &mut R, amount: usize, weight: F ) -> Result<SliceChooseIter<'_, Self, Self::Item>, WeightedError>where R: Rng + ?Sized, F: Fn(&Self::Item) -> X, X: Into<f64>,

**crate feature**only.

`std`