Struct rand::distributions::range::Range

pub struct Range<T: RangeImpl> { /* fields omitted */ }

Sample values uniformly between two bounds.

Range::new and Range::new_inclusive will set up a Range, which does some preparations up front to make sampling values faster. Range::sample_single is optimized for sampling values once or only a limited number of times from a range.

If you need to sample many values from a range, consider using new or new_inclusive. This is also the best choice if the range is constant, because then the preparations can be evaluated at compile-time. Otherwise sample_single may be the best choice.

Sampling uniformly from a range can be surprisingly complicated to be both generic and correct. Consider for example edge cases like low = 0u8, high = 170u8, for which a naive modulo operation would return numbers less than 85 with double the probability to those greater than 85.

Types should attempt to sample in [low, high) for Range::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, Range};

fn main() {
    let between = Range::new(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 Range<RangeInt<i32>>

Ignore the RangeInt<i32> parameterisation; these non-member functions are available to all range types. (Rust requires a type, and won't accept T: RangeImpl. Consider this a minor language issue.)

pub fn new<X: SampleRange>(low: X, high: X) -> Range<X::T>

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

pub fn new_inclusive<X: SampleRange>(low: X, high: X) -> Range<X::T>

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

pub fn sample_single<X: SampleRange, R: Rng + ?Sized>(
    low: X,
    high: X,
    rng: &mut R
) -> X

Sample a single value uniformly from [low, high). Panics if low >= high.

Trait Implementations

impl<T: Clone + RangeImpl> Clone for Range<T>

fn clone(&self) -> Range<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Copy + RangeImpl> Copy for Range<T>

impl<T: Debug + RangeImpl> Debug for Range<T>

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

Formats the value using the given formatter.

impl<T: RangeImpl> Distribution<T::X> for Range<T>

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

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

impl<T: RangeImpl> Sample<T::X> for Range<T>

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

Deprecated since 0.5.0

: use Distribution instead

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

impl<T: RangeImpl> IndependentSample<T::X> for Range<T>

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

Deprecated since 0.5.0

: use Distribution instead

Generate a random value.