[−][src]Trait rand::seq::SliceRandom
Extension trait on slices, providing random mutation and sampling methods.
An implementation is provided for slices. This may also be implementable for other types.
Associated Types
type Item
The element type.
Required methods
fn choose<R: ?Sized>(&self, rng: &mut R) -> Option<&Self::Item> where
R: Rng,
R: Rng,
Returns a reference to one random element of the slice, or None
if the
slice is empty.
Depending on the implementation, complexity is expected to be 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,
R: Rng,
Returns a mutable reference to one random element of the slice, or
None
if the slice is empty.
Depending on the implementation, complexity is expected to be O(1)
.
ⓘImportant traits for SliceChooseIter<'a, S, T>fn choose_multiple<R: ?Sized>(
&self,
rng: &mut R,
amount: usize
) -> SliceChooseIter<Self, Self::Item> where
R: Rng,
&self,
rng: &mut R,
amount: usize
) -> SliceChooseIter<Self, Self::Item> where
R: Rng,
Produces an iterator that chooses amount
elements from the slice at
random without repeating any, and returns them in random order.
In case this API is not sufficiently flexible, use index::sample
then
apply the indices to the slice.
Complexity is expected to be 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,
&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
, where the likelihood of each outcome may be
specified. The specified function weight
maps items 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)
.
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,
&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
, where the likelihood of each outcome may be
specified. The specified function weight
maps items 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)
.
See also choose_weighted
.
fn shuffle<R: ?Sized>(&mut self, rng: &mut R) where
R: Rng,
R: Rng,
Shuffle a mutable slice in place.
Depending on the implementation, complexity is expected to be O(1)
.
Example
use rand::thread_rng; use rand::seq::SliceRandom; 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,
&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.
Complexity is expected to be O(m)
where m = amount
.
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]
R: Rng,
fn choose_mut<R: ?Sized>(&mut self, rng: &mut R) -> Option<&mut Self::Item> where
R: Rng,
[src]
R: Rng,
ⓘImportant traits for SliceChooseIter<'a, S, T>fn choose_multiple<R: ?Sized>(
&self,
rng: &mut R,
amount: usize
) -> SliceChooseIter<Self, Self::Item> where
R: Rng,
[src]
&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,
[src]
&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,
[src]
&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,
[src]
R: Rng,
fn partial_shuffle<R: ?Sized>(
&mut self,
rng: &mut R,
amount: usize
) -> (&mut [Self::Item], &mut [Self::Item]) where
R: Rng,
[src]
&mut self,
rng: &mut R,
amount: usize
) -> (&mut [Self::Item], &mut [Self::Item]) where
R: Rng,