# Trait rand::seq::IndexedRandom

source · ```
pub trait IndexedRandom: Index<usize> {
// Required method
fn len(&self) -> usize;
// Provided methods
fn is_empty(&self) -> bool { ... }
fn choose<R>(&self, rng: &mut R) -> Option<&Self::Output>
where R: Rng + ?Sized { ... }
fn choose_multiple<R>(
&self,
rng: &mut R,
amount: usize
) -> SliceChooseIter<'_, Self, Self::Output> ⓘ
where Self::Output: Sized,
R: Rng + ?Sized { ... }
fn choose_weighted<R, F, B, X>(
&self,
rng: &mut R,
weight: F
) -> Result<&Self::Output, WeightError>
where R: Rng + ?Sized,
F: Fn(&Self::Output) -> B,
B: SampleBorrow<X>,
X: SampleUniform + Weight + PartialOrd<X> { ... }
fn choose_multiple_weighted<R, F, X>(
&self,
rng: &mut R,
amount: usize,
weight: F
) -> Result<SliceChooseIter<'_, Self, Self::Output>, WeightError>
where Self::Output: Sized,
R: Rng + ?Sized,
F: Fn(&Self::Output) -> X,
X: Into<f64> { ... }
}
```

## Expand description

Extension trait on indexable lists, providing random sampling methods.

This trait is implemented on `[T]`

slice types. Other types supporting
`std::ops::Index<usize>`

may implement this (only `Self::len`

must be
specified).

## Required Methods§

## Provided Methods§

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

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

Uniformly sample one element

Returns a reference to one uniformly-sampled 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::IndexedRandom;
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_multiple<R>(
&self,
rng: &mut R,
amount: usize
) -> SliceChooseIter<'_, Self, Self::Output> ⓘ

Available on **crate feature **`alloc`

only.

#### fn choose_multiple<R>( &self, rng: &mut R, amount: usize ) -> SliceChooseIter<'_, Self, Self::Output> ⓘ

**crate feature**only.

`alloc`

Uniformly sample `amount`

distinct elements

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::IndexedRandom;
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::Output, WeightError>where
R: Rng + ?Sized,
F: Fn(&Self::Output) -> B,
B: SampleBorrow<X>,
X: SampleUniform + Weight + PartialOrd<X>,

Available on **crate feature **`alloc`

only.

#### fn choose_weighted<R, F, B, X>(
&self,
rng: &mut R,
weight: F
) -> Result<&Self::Output, WeightError>where
R: Rng + ?Sized,
F: Fn(&Self::Output) -> B,
B: SampleBorrow<X>,
X: SampleUniform + Weight + PartialOrd<X>,

**crate feature**only.

`alloc`

Biased sampling for one element

Returns a reference to one element of the slice, sampled according
to the provided weights. Returns `None`

only if the slice is empty.

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_multiple_weighted<R, F, X>(
&self,
rng: &mut R,
amount: usize,
weight: F
) -> Result<SliceChooseIter<'_, Self, Self::Output>, WeightError>

Available on **crate feature **`std`

only.

#### fn choose_multiple_weighted<R, F, X>( &self, rng: &mut R, amount: usize, weight: F ) -> Result<SliceChooseIter<'_, Self, Self::Output>, WeightError>

**crate feature**only.

`std`

Biased sampling of `amount`

distinct elements

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<_>>());
```

## Object Safety§

**not**object safe.