Trait UniformSampler

trait UniformSampler: Sized

Helper trait handling actual uniform sampling.

See the module documentation on how to implement Uniform range sampling for a custom type.

Implementation of sample_single is optional, and is only useful when the implementation can be faster than Self::new(low, high).sample(rng).

Associated Types

type X

The type sampled by this implementation.

Required Methods

fn new<B1, B2>(low: B1, high: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Construct self, with inclusive lower bound and exclusive upper bound [low, 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.

Usually users should not call this directly but prefer to use Uniform::new.

fn new_inclusive<B1, B2>(low: B1, high: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Construct self, with inclusive bounds [low, high].

Usually users should not call this directly but prefer to use Uniform::new_inclusive.

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

Sample a value.

Provided Methods

fn sample_single<R: Rng + ?Sized, B1, B2>(low: B1, high: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, 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.

By default this is implemented using UniformSampler::new(low, high).sample(rng). However, for some types more optimal implementations for single usage may be provided via this method (which is the case for integers and floats). Results may not be identical.

Note that to use this method in a generic context, the type needs to be retrieved via SampleUniform::Sampler as follows:

use rand::distr::uniform::{SampleUniform, UniformSampler};
# #[allow(unused)]
fn sample_from_range<T: SampleUniform>(lb: T, ub: T) -> T {
    let mut rng = rand::rng();
    <T as SampleUniform>::Sampler::sample_single(lb, ub, &mut rng).unwrap()
}

fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low: B1, high: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample a single value uniformly from a range with inclusive lower bound and inclusive upper bound [low, high].

By default this is implemented using UniformSampler::new_inclusive(low, high).sample(rng). However, for some types more optimal implementations for single usage may be provided via this method. Results may not be identical.

Implementors