Struct Uniform

pub struct Uniform<X: SampleUniform>(/* private fields */);

Sample values uniformly between two bounds.

Construction

Uniform::new and Uniform::new_inclusive construct a uniform distribution sampling from the given low and high limits. Uniform may also be constructed via TryFrom as in Uniform::try_from(1..=6).unwrap().

Constructors may do extra work up front to allow faster sampling of multiple values. Where only a single sample is required it is suggested to use Rng::random_range or one of the sample_single methods instead.

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 StandardUniform distribution.

Provided implementations

• char (UniformChar): samples a range over the implementation for u32
• f32, f64 (UniformFloat): samples approximately uniformly within a range; bias may be present in the least-significant bit of the significand and the limits of the input range may be sampled even when an open (exclusive) range is used
• Integer types (UniformInt) may show a small bias relative to the expected uniform distribution of output. In the worst case, bias affects 1 in 2^n samples where n is 56 (i8 and u8), 48 (i16 and u16), 96 (i32 and u32), 64 (i64 and u64), 128 (i128 and u128). The unbiased feature flag fixes this bias.
• usize (UniformUsize) is handled specially, using the u32 implementation where possible to enable portable results across 32-bit and 64-bit CPU architectures.
• Duration (UniformDuration): samples a range over the implementation for u32 or u64
• SIMD types (requires simd_support feature) like x86’s __m128i and std::simd’s u32x4, f32x4 and mask32x4 types are effectively arrays of integer or floating-point types. Each lane is sampled independently from its own range, potentially with more efficient random-bit-usage than would be achieved with sequential sampling.

Example

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

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

For a single sample, Rng::random_range may be preferred:

use rand::Rng;

let mut rng = rand::rng();
println!("{}", rng.random_range(0..10));

Implementations

impl<X: SampleUniform> Uniform<X>

pub fn new<B1, B2>(low: B1, high: B2) -> Result<Uniform<X>, Error>

where B1: SampleBorrow<X> + Sized, B2: SampleBorrow<X> + Sized,

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

For discrete types (e.g. integers), samples will always be strictly less than high. For (approximations of) continuous types (e.g. f32, f64), samples may equal high due to loss of precision but may not be greater than high.

Fails if low >= high, or if low, high or the range high - low is non-finite. In release mode, only the range is checked.

pub fn new_inclusive<B1, B2>(low: B1, high: B2) -> Result<Uniform<X>, Error>

where B1: SampleBorrow<X> + Sized, B2: SampleBorrow<X> + Sized,

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

Fails if low > high, or if low, high or the range high - low is non-finite. In release mode, only the range is checked.

Trait Implementations

impl<X: Clone + SampleUniform> Clone for Uniform<X>

where X::Sampler: Clone,

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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.

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.

fn sample_iter<R>(self, rng: R) -> Iter<Self, R, T>

where R: Rng, Self: Sized,

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

fn map<F, S>(self, func: F) -> Map<Self, F, T, S>

where F: Fn(T) -> S, Self: Sized,

Map sampled values to type S

impl<X: PartialEq + SampleUniform> PartialEq for Uniform<X>

where X::Sampler: PartialEq,

fn eq(&self, other: &Uniform<X>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl SampleString for Uniform<char>

fn append_string<R: Rng + ?Sized>( &self, rng: &mut R, string: &mut String, len: usize, )

Append len random chars to string

fn sample_string<R: Rng + ?Sized>(&self, rng: &mut R, len: usize) -> String

Generate a String of len random chars

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

type Error = Error

The type returned in the event of a conversion error.

fn try_from(r: Range<X>) -> Result<Uniform<X>, Error>

Performs the conversion.

impl<X: SampleUniform> TryFrom<RangeInclusive<X>> for Uniform<X>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(r: RangeInclusive<X>) -> Result<Uniform<X>, Error>

Performs the conversion.

impl<X: Copy + SampleUniform> Copy for Uniform<X>

where X::Sampler: Copy,

impl<X: Eq + SampleUniform> Eq for Uniform<X>

where X::Sampler: Eq,

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