Trait UniformSampler

pub trait UniformSampler: Sized {
    type X;

    // Required methods
    fn new<B1, B2>(low: B1, high: B2) -> Result<Self, Error>
       where B1: SampleBorrow<Self::X> + Sized,
             B2: SampleBorrow<Self::X> + Sized;
    fn new_inclusive<B1, B2>(low: B1, high: B2) -> Result<Self, Error>
       where B1: SampleBorrow<Self::X> + Sized,
             B2: SampleBorrow<Self::X> + Sized;
    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X;

    // Provided methods
    fn sample_single<R: Rng + ?Sized, B1, B2>(
        low: B1,
        high: B2,
        rng: &mut R,
    ) -> Result<Self::X, Error>
       where B1: SampleBorrow<Self::X> + Sized,
             B2: SampleBorrow<Self::X> + Sized { ... }
    fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
        low: B1,
        high: B2,
        rng: &mut R,
    ) -> Result<Self::X, Error>
       where B1: SampleBorrow<Self::X> + Sized,
             B2: SampleBorrow<Self::X> + 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).

Required 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::X> + Sized, B2: SampleBorrow<Self::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::X> + Sized, B2: SampleBorrow<Self::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, rng: &mut R) -> Self::X

Sample a value.

Provided Methods

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

where B1: SampleBorrow<Self::X> + Sized, B2: SampleBorrow<Self::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};
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::X, Error>

where B1: SampleBorrow<Self::X> + Sized, B2: SampleBorrow<Self::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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl UniformSampler for UniformChar

type X = char

impl UniformSampler for UniformDuration

type X = Duration

impl UniformSampler for UniformFloat<f32>

type X = f32

impl UniformSampler for UniformFloat<f64>

type X = f64

impl UniformSampler for UniformFloat<f32x2>

Available on crate feature simd_support only.

type X = Simd<f32, 2>

impl UniformSampler for UniformFloat<f32x4>

Available on crate feature simd_support only.

type X = Simd<f32, 4>

impl UniformSampler for UniformFloat<f32x8>

Available on crate feature simd_support only.

type X = Simd<f32, 8>

impl UniformSampler for UniformFloat<f32x16>

Available on crate feature simd_support only.

type X = Simd<f32, 16>

impl UniformSampler for UniformFloat<f64x2>

Available on crate feature simd_support only.

type X = Simd<f64, 2>

impl UniformSampler for UniformFloat<f64x4>

Available on crate feature simd_support only.

type X = Simd<f64, 4>

impl UniformSampler for UniformFloat<f64x8>

Available on crate feature simd_support only.

type X = Simd<f64, 8>

impl UniformSampler for UniformInt<i8>

type X = i8

impl UniformSampler for UniformInt<i16>

type X = i16

impl UniformSampler for UniformInt<i32>

type X = i32

impl UniformSampler for UniformInt<i64>

type X = i64

impl UniformSampler for UniformInt<i128>

type X = i128

impl UniformSampler for UniformInt<u8>

type X = u8

impl UniformSampler for UniformInt<u16>

type X = u16

impl UniformSampler for UniformInt<u32>

type X = u32

impl UniformSampler for UniformInt<u64>

type X = u64

impl UniformSampler for UniformInt<u128>

type X = u128

impl UniformSampler for UniformUsize

Available on 32-bit or 64-bit only.

type X = usize

impl<const LANES: usize> UniformSampler for UniformInt<Simd<i8, LANES>>

where LaneCount<LANES>: SupportedLaneCount, Simd<u8, LANES>: WideningMultiply<Output = (Simd<u8, LANES>, Simd<u8, LANES>)>, StandardUniform: Distribution<Simd<u8, LANES>>,

Available on crate feature simd_support only.

type X = Simd<i8, LANES>

impl<const LANES: usize> UniformSampler for UniformInt<Simd<i16, LANES>>

where LaneCount<LANES>: SupportedLaneCount, Simd<u16, LANES>: WideningMultiply<Output = (Simd<u16, LANES>, Simd<u16, LANES>)>, StandardUniform: Distribution<Simd<u16, LANES>>,

Available on crate feature simd_support only.

type X = Simd<i16, LANES>

impl<const LANES: usize> UniformSampler for UniformInt<Simd<i32, LANES>>

where LaneCount<LANES>: SupportedLaneCount, Simd<u32, LANES>: WideningMultiply<Output = (Simd<u32, LANES>, Simd<u32, LANES>)>, StandardUniform: Distribution<Simd<u32, LANES>>,

Available on crate feature simd_support only.

type X = Simd<i32, LANES>

impl<const LANES: usize> UniformSampler for UniformInt<Simd<i64, LANES>>

where LaneCount<LANES>: SupportedLaneCount, Simd<u64, LANES>: WideningMultiply<Output = (Simd<u64, LANES>, Simd<u64, LANES>)>, StandardUniform: Distribution<Simd<u64, LANES>>,

Available on crate feature simd_support only.

type X = Simd<i64, LANES>

impl<const LANES: usize> UniformSampler for UniformInt<Simd<u8, LANES>>

where LaneCount<LANES>: SupportedLaneCount, Simd<u8, LANES>: WideningMultiply<Output = (Simd<u8, LANES>, Simd<u8, LANES>)>, StandardUniform: Distribution<Simd<u8, LANES>>,

Available on crate feature simd_support only.

type X = Simd<u8, LANES>

impl<const LANES: usize> UniformSampler for UniformInt<Simd<u16, LANES>>

where LaneCount<LANES>: SupportedLaneCount, Simd<u16, LANES>: WideningMultiply<Output = (Simd<u16, LANES>, Simd<u16, LANES>)>, StandardUniform: Distribution<Simd<u16, LANES>>,

Available on crate feature simd_support only.

type X = Simd<u16, LANES>

impl<const LANES: usize> UniformSampler for UniformInt<Simd<u32, LANES>>

where LaneCount<LANES>: SupportedLaneCount, Simd<u32, LANES>: WideningMultiply<Output = (Simd<u32, LANES>, Simd<u32, LANES>)>, StandardUniform: Distribution<Simd<u32, LANES>>,

Available on crate feature simd_support only.

type X = Simd<u32, LANES>

impl<const LANES: usize> UniformSampler for UniformInt<Simd<u64, LANES>>

where LaneCount<LANES>: SupportedLaneCount, Simd<u64, LANES>: WideningMultiply<Output = (Simd<u64, LANES>, Simd<u64, LANES>)>, StandardUniform: Distribution<Simd<u64, LANES>>,

Available on crate feature simd_support only.

type X = Simd<u64, LANES>