Struct rand::distributions::Uniform

source ·
pub struct Uniform<X: SampleUniform>(/* private fields */);
Expand description

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. If only one sample from the range is required, Rng::gen_range can be more efficient.

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 must sample in [low, high) range for Uniform::new(low, high), i.e., excluding high. In particular, care must be taken to ensure that rounding never results values < low or >= high.

§Example

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

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

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

use rand::Rng;

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

Implementations§

source§

impl<X: SampleUniform> Uniform<X>

source

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).

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

source

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§

source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

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

Deserialize this value from the given Serde deserializer. Read more
source§

impl DistString for Uniform<char>

Note: the String is potentially left with excess capacity if the range includes non ascii chars; optionally the user may call string.shrink_to_fit() afterwards.

source§

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

Append len random chars to string
source§

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

Generate a String of len random chars
source§

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

source§

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

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

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

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

fn map<F, S>(self, func: F) -> DistMap<Self, F, T, S>
where F: Fn(T) -> S, Self: Sized,

Create a distribution of values of ‘S’ by mapping the output of Self through the closure F Read more
source§

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

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

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

Serialize this value into the given Serde serializer. Read more
source§

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

§

type Error = Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

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

§

type Error = Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

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

source§

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

source§

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

Auto Trait Implementations§

§

impl<X> RefUnwindSafe for Uniform<X>

§

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> UnwindSafe for Uniform<X>

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

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

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

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

source§

fn into(self) -> U

Calls U::from(self).

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

source§

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

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

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

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

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