Struct nannou::rand::rand::distributions::WeightedIndex [−][src]
pub struct WeightedIndex<X> where
X: SampleUniform + PartialOrd<X>, { /* fields omitted */ }
Expand description
A distribution using weighted sampling of discrete items
Sampling a WeightedIndex
distribution returns the index of a randomly
selected element from the iterator used when the WeightedIndex
was
created. The chance of a given element being picked is proportional to the
value of the element. The weights can use any type X
for which an
implementation of Uniform<X>
exists.
Performance
Time complexity of sampling from WeightedIndex
is O(log N)
where
N
is the number of weights. As an alternative,
rand_distr::weighted_alias
supports O(1)
sampling, but with much higher initialisation cost.
A WeightedIndex<X>
contains a Vec<X>
and a Uniform<X>
and so its
size is the sum of the size of those objects, possibly plus some alignment.
Creating a WeightedIndex<X>
will allocate enough space to hold N - 1
weights of type X
, where N
is the number of weights. However, since
Vec
doesn’t guarantee a particular growth strategy, additional memory
might be allocated but not used. Since the WeightedIndex
object also
contains, this might cause additional allocations, though for primitive
types, Uniform<X>
doesn’t allocate any memory.
Sampling from WeightedIndex
will result in a single call to
Uniform<X>::sample
(method of the Distribution
trait), which typically
will request a single value from the underlying RngCore
, though the
exact number depends on the implementation of Uniform<X>::sample
.
Example
use rand::prelude::*;
use rand::distributions::WeightedIndex;
let choices = ['a', 'b', 'c'];
let weights = [2, 1, 1];
let dist = WeightedIndex::new(&weights).unwrap();
let mut rng = thread_rng();
for _ in 0..100 {
// 50% chance to print 'a', 25% chance to print 'b', 25% chance to print 'c'
println!("{}", choices[dist.sample(&mut rng)]);
}
let items = [('a', 0), ('b', 3), ('c', 7)];
let dist2 = WeightedIndex::new(items.iter().map(|item| item.1)).unwrap();
for _ in 0..100 {
// 0% chance to print 'a', 30% chance to print 'b', 70% chance to print 'c'
println!("{}", items[dist2.sample(&mut rng)].0);
}
Implementations
pub fn new<I>(weights: I) -> Result<WeightedIndex<X>, WeightedError> where
I: IntoIterator,
X: for<'a> AddAssign<&'a X> + Clone + Default,
<I as IntoIterator>::Item: SampleBorrow<X>,
pub fn new<I>(weights: I) -> Result<WeightedIndex<X>, WeightedError> where
I: IntoIterator,
X: for<'a> AddAssign<&'a X> + Clone + Default,
<I as IntoIterator>::Item: SampleBorrow<X>,
Creates a new a WeightedIndex
Distribution
using the values
in weights
. The weights can use any type X
for which an
implementation of Uniform<X>
exists.
Returns an error if the iterator is empty, if any weight is < 0
, or
if its total value is 0.
Update a subset of weights, without changing the number of weights.
new_weights
must be sorted by the index.
Using this method instead of new
might be more efficient if only a small number of
weights is modified. No allocations are performed, unless the weight type X
uses
allocation internally.
In case of error, self
is not modified.
Trait Implementations
impl<X> Clone for WeightedIndex<X> where
X: Clone + SampleUniform + PartialOrd<X>,
<X as SampleUniform>::Sampler: Clone,
impl<X> Clone for WeightedIndex<X> where
X: Clone + SampleUniform + PartialOrd<X>,
<X as SampleUniform>::Sampler: Clone,
impl<X> Debug for WeightedIndex<X> where
X: Debug + SampleUniform + PartialOrd<X>,
<X as SampleUniform>::Sampler: Debug,
impl<X> Debug for WeightedIndex<X> where
X: Debug + SampleUniform + PartialOrd<X>,
<X as SampleUniform>::Sampler: Debug,
Generate a random value of T
, using rng
as the source of randomness.
fn sample_iter<R>(self, rng: R) -> DistIter<Self, R, T>ⓘ where
R: Rng,
fn sample_iter<R>(self, rng: R) -> DistIter<Self, R, T>ⓘ where
R: Rng,
Create an iterator that generates random values of T
, using rng
as
the source of randomness. Read more
Auto Trait Implementations
impl<X> RefUnwindSafe for WeightedIndex<X> where
X: RefUnwindSafe,
<X as SampleUniform>::Sampler: RefUnwindSafe,
impl<X> Send for WeightedIndex<X> where
X: Send,
<X as SampleUniform>::Sampler: Send,
impl<X> Sync for WeightedIndex<X> where
X: Sync,
<X as SampleUniform>::Sampler: Sync,
impl<X> Unpin for WeightedIndex<X> where
X: Unpin,
<X as SampleUniform>::Sampler: Unpin,
impl<X> UnwindSafe for WeightedIndex<X> where
X: UnwindSafe,
<X as SampleUniform>::Sampler: UnwindSafe,
Blanket Implementations
impl<S, D, Swp, Dwp, T> AdaptInto<D, Swp, Dwp, T> for S where
T: Component + Float,
Swp: WhitePoint,
Dwp: WhitePoint,
D: AdaptFrom<S, Swp, Dwp, T>,
impl<S, D, Swp, Dwp, T> AdaptInto<D, Swp, Dwp, T> for S where
T: Component + Float,
Swp: WhitePoint,
Dwp: WhitePoint,
D: AdaptFrom<S, Swp, Dwp, T>,
Mutably borrows from an owned value. Read more
Convert into T with values clamped to the color defined bounds Read more
Convert into T. The resulting color might be invalid in its color space Read more
Convert into T, returning ok if the color is inside of its defined range,
otherwise an OutOfBounds
error is returned which contains the unclamped color. Read more