Struct Uniform

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

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

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::RngExt;

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.

Trait Implementations

impl SampleString for Uniform<char>

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

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

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

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

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

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

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

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

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

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

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

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

impl<X: SampleUniform> Serialize for Uniform<X> where X::Sampler: Serialize,

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

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

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

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

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

Auto Trait Implementations

impl<X> Freeze for Uniform<X> where <X as SampleUniform>::Sampler: Freeze,

impl<X> RefUnwindSafe for Uniform<X> where <X as SampleUniform>::Sampler: RefUnwindSafe,

impl<X> Send for Uniform<X> where <X as SampleUniform>::Sampler: Send,

impl<X> Sync for Uniform<X> where <X as SampleUniform>::Sampler: Sync,

impl<X> Unpin for Uniform<X> where <X as SampleUniform>::Sampler: Unpin,

impl<X> UnsafeUnpin for Uniform<X> where <X as SampleUniform>::Sampler: UnsafeUnpin,

impl<X> UnwindSafe for Uniform<X> where <X as SampleUniform>::Sampler: UnwindSafe,

Blanket Implementations

impl<T> Any for Uniform<X> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Uniform<X> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Uniform<X> where T: ?Sized,

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

impl<T> CloneToUninit for Uniform<X> where T: Clone,

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

impl<T> DeserializeOwned for Uniform<X> where T: for<'de> Deserialize<'de>,

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

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for Uniform<X> where T: Clone,

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

impl<T, U> Into<U> for Uniform<X> where U: From<T>,

fn into(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<U> for Uniform<X> where U: Into<T>,

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

impl<T, U> TryInto<U> for Uniform<X> where U: TryFrom<T>,

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