Struct rand::distributions::Uniform

pub struct Uniform<X: SampleUniform> { /* fields omitted */ }

Sample values uniformly between two bounds.

Uniform::new and Uniform::new_inclusive construct a uniform distribution sampling from the given range; these functions may do extra work up front to make sampling of multiple values faster.

When sampling from a constant range, many calculations can happen at compile-time and all methods should be fast; for floating-point ranges and the full range of integer types this should have comparable performance to the Standard distribution.

Steps are taken to avoid bias which might be present in naive implementations; for example rng.gen::<u8>() % 170 samples from the range [0, 169] but is twice as likely to select numbers less than 85 than other values. Further, the implementations here give more weight to the high-bits generated by the RNG than the low bits, since with some RNGs the low-bits are of lower quality than the high bits.

Implementations should attempt to sample in [low, high) for Uniform::new(low, high), i.e., excluding high, but this may be very difficult. All the primitive integer types satisfy this property, and the float types normally satisfy it, but rounding may mean high can occur.

Example

use rand::distributions::{Distribution, Uniform};

fn main() {
    let between = Uniform::from(10..10000);
    let mut rng = rand::thread_rng();
    let mut sum = 0;
    for _ in 0..1000 {
        sum += between.sample(&mut rng);
    }
    println!("{}", sum);
}

Methods

impl<X: SampleUniform> Uniform<X>

pub fn new(low: X, high: X) -> Uniform<X>

Create a new Uniform instance which samples uniformly from the half open range [low, high) (excluding high). Panics if low >= high.

pub fn new_inclusive(low: X, high: X) -> Uniform<X>

Create a new Uniform instance which samples uniformly from the closed range [low, high] (inclusive). Panics if low > high.

Trait Implementations

impl<T: SampleRange> Sample<T> for Range<T>

fn sample<R: Rng>(&mut self, rng: &mut R) -> T

Deprecated since 0.5.0

: use Distribution instead

Generate a random value of Support, using rng as the source of randomness.

impl<T: SampleRange> IndependentSample<T> for Range<T>

fn ind_sample<R: Rng>(&self, rng: &mut R) -> T

Deprecated since 0.5.0

: use Distribution instead

Generate a random value.

impl<X: SampleUniform> Distribution<X> for Uniform<X>

fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> X

Generate a random value of T, using rng as the source of randomness.

Important traits for DistIter<'a, D, R, T>

impl<'a, D, R, T> Iterator for DistIter<'a, D, R, T> where
    D: Distribution<T>,
    R: Rng + 'a,  type Item = T;

fn sample_iter<'a, R>(&'a self, rng: &'a mut R) -> DistIter<'a, Self, R, T> where     Self: Sized,     R: Rng,

Create an iterator that generates random values of T, using rng as the source of randomness.

impl<X: SampleUniform> From<Range<X>> for Uniform<X>

fn from(r: Range<X>) -> Uniform<X>

Performs the conversion.

impl<X: Clone + SampleUniform> Clone for Uniform<X> where     X::Sampler: Clone,

fn clone(&self) -> Uniform<X>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<X: Copy + SampleUniform> Copy for Uniform<X> where     X::Sampler: Copy,

impl<X: Debug + SampleUniform> Debug for Uniform<X> where     X::Sampler: Debug,

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.