# [−] [src] Trait rand::seq::SliceRandom

    pub trait SliceRandom {
        type Item;
        fn choose<R: ?Sized>(&self, rng: &mut R) -> Option<&Self::Item>
        where
            R: Rng;
        fn choose_mut<R: ?Sized>(&mut self, rng: &mut R) -> Option<&mut Self::Item>
        where
            R: Rng;
        fn choose_multiple<R: ?Sized>(
            &self,
            rng: &mut R,
            amount: usize
        ) -> SliceChooseIter<Self, Self::Item>
        where
            R: Rng;
        fn choose_weighted<R: ?Sized, F, B, X>(
            &self,
            rng: &mut R,
            weight: F
        ) -> Result<&Self::Item, WeightedError>
        where
            R: Rng,
            F: Fn(&Self::Item) -> B,
            B: SampleBorrow<X>,
            X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default;
        fn choose_weighted_mut<R: ?Sized, F, B, X>(
            &mut self,
            rng: &mut R,
            weight: F
        ) -> Result<&mut Self::Item, WeightedError>
        where
            R: Rng,
            F: Fn(&Self::Item) -> B,
            B: SampleBorrow<X>,
            X: SampleUniform + for<'a> AddAssign<&'a X> + PartialOrd<X> + Clone + Default;
        fn shuffle<R: ?Sized>(&mut self, rng: &mut R)
        where
            R: Rng;
        fn partial_shuffle<R: ?Sized>(
            &mut self,
            rng: &mut R,
            amount: usize
        ) -> (&mut [Self::Item], &mut [Self::Item])
        where
            R: Rng;
    }

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;

    fn main() {
        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

## Associated Types

### `type Item`

The element type.

Loading content...

## Required methods

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

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: ?Sized>(&mut self, rng: &mut R) -> Option<&mut Self::Item> where
R: Rng,`

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

For slices, complexity is `O(1)`.

###
ⓘImportant traits for SliceChooseIter<'a, S, T>

### Important traits for SliceChooseIter<'a, S, T>

`impl<'a, S: Index<usize, Output = T> + ?Sized + 'a, T: 'a> Iterator for SliceChooseIter<'a, S, T> type Item = &'a T;`
`fn choose_multiple<R: ?Sized>(
&self,
rng: &mut R,
amount: usize
) -> SliceChooseIter<Self, Self::Item> where
R: Rng,`

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;
    }

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

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)`. See also `choose_weighted_mut`, `distributions::weighted`.

# Example

    use rand::prelude::*;

    let choices = [('a', 2), ('b', 1), ('c', 1)];
    let mut rng = thread_rng();
    // 50% chance to print 'a', 25% chance to print 'b', 25% chance to print 'c'
    println!("{:?}", choices.choose_weighted(&mut rng, |item| item.1).unwrap().0);

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

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)`. See also `choose_weighted`, `distributions::weighted`.

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

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: ?Sized>(
&mut self,
rng: &mut R,
amount: usize
) -> (&mut [Self::Item], &mut [Self::Item]) where
R: Rng,`

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

Loading content...

## Implementations on Foreign Types

### `impl<T> SliceRandom for [T]` [src]

#### `type Item = T`

#### `fn choose<R: ?Sized>(&self, rng: &mut R) -> Option<&Self::Item> where
R: Rng,` [src]

#### `fn choose_mut<R: ?Sized>(&mut self, rng: &mut R) -> Option<&mut Self::Item> where
R: Rng,` [src]

####
ⓘImportant traits for SliceChooseIter<'a, S, T>

### Important traits for SliceChooseIter<'a, S, T>

`impl<'a, S: Index<usize, Output = T> + ?Sized + 'a, T: 'a> Iterator for SliceChooseIter<'a, S, T> type Item = &'a T;`
`fn choose_multiple<R: ?Sized>(
&self,
rng: &mut R,
amount: usize
) -> SliceChooseIter<Self, Self::Item> where
R: Rng,` [src]

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

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

#### `fn shuffle<R: ?Sized>(&mut self, rng: &mut R) where
R: Rng,` [src]

#### `fn partial_shuffle<R: ?Sized>(
&mut self,
rng: &mut R,
amount: usize
) -> (&mut [Self::Item], &mut [Self::Item]) where
R: Rng,` [src]

Loading content...

## Implementors

Loading content...

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)