Struct `Uniform`

struct Uniform<X: SampleUniform>(_)

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>`

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.

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.

`impl SampleString for super::Uniform<char>`

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

`impl<'de, X: SampleUniform> Deserialize for Uniform<X>`

fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error> where __D: _serde::Deserializer<'de>

`impl<T> Any for Uniform<X>`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for Uniform<X>`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for Uniform<X>`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for Uniform<X>`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> DeserializeOwned for Uniform<X>`

`impl<T> From for Uniform<X>`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for Uniform<X>`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, U> Into for Uniform<X>`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for Uniform<X>`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for Uniform<X>`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

`impl<V, T> VZip for Uniform<X>`

fn vzip(self: Self) -> V

`impl<X> Freeze for Uniform<X>`

`impl<X> RefUnwindSafe for Uniform<X>`

`impl<X> Send for Uniform<X>`

`impl<X> Sync for Uniform<X>`

`impl<X> Unpin for Uniform<X>`

`impl<X> UnwindSafe for Uniform<X>`

`impl<X: $crate::clone::Clone + SampleUniform> Clone for Uniform<X>`

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

`impl<X: $crate::cmp::Eq + SampleUniform> Eq for Uniform<X>`

`impl<X: $crate::cmp::PartialEq + SampleUniform> PartialEq for Uniform<X>`

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

`impl<X: $crate::fmt::Debug + SampleUniform> Debug for Uniform<X>`

fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<'_>) -> $crate::fmt::Result

`impl<X: $crate::marker::Copy + SampleUniform> Copy for Uniform<X>`

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

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

`impl<X: SampleUniform> Serialize for Uniform<X>`

fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error> where __S: _serde::Serializer

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

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

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

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

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