// Copyright 2018-2020 Developers of the Rand project. // Copyright 2017 The Rust Project Developers. // // Licensed under the Apache License, Version 2.0 or the MIT license // , at your // option. This file may not be copied, modified, or distributed // except according to those terms. //! A distribution uniformly sampling numbers within a given range. //! //! [`Uniform`] is the standard distribution to sample uniformly from a range; //! e.g. `Uniform::new_inclusive(1, 6).unwrap()` can sample integers from 1 to 6, like a //! standard die. [`Rng::random_range`] is implemented over [`Uniform`]. //! //! # Example usage //! //! ``` //! use rand::Rng; //! use rand::distr::Uniform; //! //! let mut rng = rand::rng(); //! let side = Uniform::new(-10.0, 10.0).unwrap(); //! //! // sample between 1 and 10 points //! for _ in 0..rng.random_range(1..=10) { //! // sample a point from the square with sides -10 - 10 in two dimensions //! let (x, y) = (rng.sample(side), rng.sample(side)); //! println!("Point: {}, {}", x, y); //! } //! ``` //! //! # Extending `Uniform` to support a custom type //! //! To extend [`Uniform`] to support your own types, write a back-end which //! implements the [`UniformSampler`] trait, then implement the [`SampleUniform`] //! helper trait to "register" your back-end. See the `MyF32` example below. //! //! At a minimum, the back-end needs to store any parameters needed for sampling //! (e.g. the target range) and implement `new`, `new_inclusive` and `sample`. //! Those methods should include an assertion to check the range is valid (i.e. //! `low < high`). The example below merely wraps another back-end. //! //! The `new`, `new_inclusive`, `sample_single` and `sample_single_inclusive` //! functions use arguments of //! type `SampleBorrow` to support passing in values by reference or //! by value. In the implementation of these functions, you can choose to //! simply use the reference returned by [`SampleBorrow::borrow`], or you can choose //! to copy or clone the value, whatever is appropriate for your type. //! //! ``` //! use rand::prelude::*; //! use rand::distr::uniform::{Uniform, SampleUniform, //! UniformSampler, UniformFloat, SampleBorrow, Error}; //! //! struct MyF32(f32); //! //! #[derive(Clone, Copy, Debug)] //! struct UniformMyF32(UniformFloat); //! //! impl UniformSampler for UniformMyF32 { //! type X = MyF32; //! //! fn new(low: B1, high: B2) -> Result //! where B1: SampleBorrow + Sized, //! B2: SampleBorrow + Sized //! { //! UniformFloat::::new(low.borrow().0, high.borrow().0).map(UniformMyF32) //! } //! fn new_inclusive(low: B1, high: B2) -> Result //! where B1: SampleBorrow + Sized, //! B2: SampleBorrow + Sized //! { //! UniformFloat::::new_inclusive(low.borrow().0, high.borrow().0).map(UniformMyF32) //! } //! fn sample(&self, rng: &mut R) -> Self::X { //! MyF32(self.0.sample(rng)) //! } //! } //! //! impl SampleUniform for MyF32 { //! type Sampler = UniformMyF32; //! } //! //! let (low, high) = (MyF32(17.0f32), MyF32(22.0f32)); //! let uniform = Uniform::new(low, high).unwrap(); //! let x = uniform.sample(&mut rand::rng()); //! ``` //! //! [`SampleUniform`]: crate::distr::uniform::SampleUniform //! [`UniformSampler`]: crate::distr::uniform::UniformSampler //! [`UniformInt`]: crate::distr::uniform::UniformInt //! [`UniformFloat`]: crate::distr::uniform::UniformFloat //! [`UniformDuration`]: crate::distr::uniform::UniformDuration //! [`SampleBorrow::borrow`]: crate::distr::uniform::SampleBorrow::borrow #[path = "uniform_float.rs"] mod float; #[doc(inline)] pub use float::UniformFloat; #[path = "uniform_int.rs"] mod int; #[doc(inline)] pub use int::{UniformInt, UniformUsize}; #[path = "uniform_other.rs"] mod other; #[doc(inline)] pub use other::{UniformChar, UniformDuration}; use core::fmt; use core::ops::{Range, RangeInclusive, RangeTo, RangeToInclusive}; use crate::distr::Distribution; use crate::{Rng, RngCore}; /// Error type returned from [`Uniform::new`] and `new_inclusive`. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum Error { /// `low > high`, or equal in case of exclusive range. EmptyRange, /// Input or range `high - low` is non-finite. Not relevant to integer types. NonFinite, } impl fmt::Display for Error { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str(match self { Error::EmptyRange => "low > high (or equal if exclusive) in uniform distribution", Error::NonFinite => "Non-finite range in uniform distribution", }) } } #[cfg(feature = "std")] impl std::error::Error for Error {} #[cfg(feature = "serde")] use serde::{Deserialize, Serialize}; /// 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`](super::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)); /// ``` /// /// [`new`]: Uniform::new /// [`new_inclusive`]: Uniform::new_inclusive /// [`Rng::random_range`]: Rng::random_range /// [`__m128i`]: https://doc.rust-lang.org/core/arch/x86/struct.__m128i.html /// [`u32x4`]: std::simd::u32x4 /// [`f32x4`]: std::simd::f32x4 /// [`mask32x4`]: std::simd::mask32x4 /// [`simd_support`]: https://github.com/rust-random/rand#crate-features #[derive(Clone, Copy, Debug, PartialEq, Eq)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] #[cfg_attr(feature = "serde", serde(bound(serialize = "X::Sampler: Serialize")))] #[cfg_attr( feature = "serde", serde(bound(deserialize = "X::Sampler: Deserialize<'de>")) )] pub struct Uniform(X::Sampler); impl Uniform { /// 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. pub fn new(low: B1, high: B2) -> Result, Error> where B1: SampleBorrow + Sized, B2: SampleBorrow + Sized, { X::Sampler::new(low, high).map(Uniform) } /// 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. pub fn new_inclusive(low: B1, high: B2) -> Result, Error> where B1: SampleBorrow + Sized, B2: SampleBorrow + Sized, { X::Sampler::new_inclusive(low, high).map(Uniform) } } impl Distribution for Uniform { fn sample(&self, rng: &mut R) -> X { self.0.sample(rng) } } /// Helper trait for creating objects using the correct implementation of /// [`UniformSampler`] for the sampling type. /// /// See the [module documentation] on how to implement [`Uniform`] range /// sampling for a custom type. /// /// [module documentation]: crate::distr::uniform pub trait SampleUniform: Sized { /// The `UniformSampler` implementation supporting type `X`. type Sampler: UniformSampler; } /// 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)`. /// /// [module documentation]: crate::distr::uniform /// [`sample_single`]: UniformSampler::sample_single pub trait UniformSampler: Sized { /// The type sampled by this implementation. type X; /// 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(low: B1, high: B2) -> Result where B1: SampleBorrow + Sized, B2: SampleBorrow + Sized; /// Construct self, with inclusive bounds `[low, high]`. /// /// Usually users should not call this directly but prefer to use /// [`Uniform::new_inclusive`]. fn new_inclusive(low: B1, high: B2) -> Result where B1: SampleBorrow + Sized, B2: SampleBorrow + Sized; /// Sample a value. fn sample(&self, rng: &mut R) -> Self::X; /// 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(lb: T, ub: T) -> T { /// let mut rng = rand::rng(); /// ::Sampler::sample_single(lb, ub, &mut rng).unwrap() /// } /// ``` fn sample_single( low: B1, high: B2, rng: &mut R, ) -> Result where B1: SampleBorrow + Sized, B2: SampleBorrow + Sized, { let uniform: Self = UniformSampler::new(low, high)?; Ok(uniform.sample(rng)) } /// 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. fn sample_single_inclusive( low: B1, high: B2, rng: &mut R, ) -> Result where B1: SampleBorrow + Sized, B2: SampleBorrow + Sized, { let uniform: Self = UniformSampler::new_inclusive(low, high)?; Ok(uniform.sample(rng)) } } impl TryFrom> for Uniform { type Error = Error; fn try_from(r: Range) -> Result, Error> { Uniform::new(r.start, r.end) } } impl TryFrom> for Uniform { type Error = Error; fn try_from(r: ::core::ops::RangeInclusive) -> Result, Error> { Uniform::new_inclusive(r.start(), r.end()) } } /// Helper trait similar to [`Borrow`] but implemented /// only for [`SampleUniform`] and references to [`SampleUniform`] /// in order to resolve ambiguity issues. /// /// [`Borrow`]: std::borrow::Borrow pub trait SampleBorrow { /// Immutably borrows from an owned value. See [`Borrow::borrow`] /// /// [`Borrow::borrow`]: std::borrow::Borrow::borrow fn borrow(&self) -> &Borrowed; } impl SampleBorrow for Borrowed where Borrowed: SampleUniform, { #[inline(always)] fn borrow(&self) -> &Borrowed { self } } impl SampleBorrow for &Borrowed where Borrowed: SampleUniform, { #[inline(always)] fn borrow(&self) -> &Borrowed { self } } /// Range that supports generating a single sample efficiently. /// /// Any type implementing this trait can be used to specify the sampled range /// for `Rng::random_range`. pub trait SampleRange { /// Generate a sample from the given range. fn sample_single(self, rng: &mut R) -> Result; /// Check whether the range is empty. fn is_empty(&self) -> bool; } impl SampleRange for Range { #[inline] fn sample_single(self, rng: &mut R) -> Result { T::Sampler::sample_single(self.start, self.end, rng) } #[inline] fn is_empty(&self) -> bool { !(self.start < self.end) } } impl SampleRange for RangeInclusive { #[inline] fn sample_single(self, rng: &mut R) -> Result { T::Sampler::sample_single_inclusive(self.start(), self.end(), rng) } #[inline] fn is_empty(&self) -> bool { !(self.start() <= self.end()) } } macro_rules! impl_sample_range_u { ($t:ty) => { impl SampleRange<$t> for RangeTo<$t> { #[inline] fn sample_single(self, rng: &mut R) -> Result<$t, Error> { <$t as SampleUniform>::Sampler::sample_single(0, self.end, rng) } #[inline] fn is_empty(&self) -> bool { 0 == self.end } } impl SampleRange<$t> for RangeToInclusive<$t> { #[inline] fn sample_single(self, rng: &mut R) -> Result<$t, Error> { <$t as SampleUniform>::Sampler::sample_single_inclusive(0, self.end, rng) } #[inline] fn is_empty(&self) -> bool { false } } }; } impl_sample_range_u!(u8); impl_sample_range_u!(u16); impl_sample_range_u!(u32); impl_sample_range_u!(u64); impl_sample_range_u!(u128); impl_sample_range_u!(usize); #[cfg(test)] mod tests { use super::*; use core::time::Duration; #[test] #[cfg(feature = "serde")] fn test_uniform_serialization() { let unit_box: Uniform = Uniform::new(-1, 1).unwrap(); let de_unit_box: Uniform = bincode::deserialize(&bincode::serialize(&unit_box).unwrap()).unwrap(); assert_eq!(unit_box.0, de_unit_box.0); let unit_box: Uniform = Uniform::new(-1., 1.).unwrap(); let de_unit_box: Uniform = bincode::deserialize(&bincode::serialize(&unit_box).unwrap()).unwrap(); assert_eq!(unit_box.0, de_unit_box.0); } #[test] fn test_custom_uniform() { use crate::distr::uniform::{SampleBorrow, SampleUniform, UniformFloat, UniformSampler}; #[derive(Clone, Copy, PartialEq, PartialOrd)] struct MyF32 { x: f32, } #[derive(Clone, Copy, Debug)] struct UniformMyF32(UniformFloat); impl UniformSampler for UniformMyF32 { type X = MyF32; fn new(low: B1, high: B2) -> Result where B1: SampleBorrow + Sized, B2: SampleBorrow + Sized, { UniformFloat::::new(low.borrow().x, high.borrow().x).map(UniformMyF32) } fn new_inclusive(low: B1, high: B2) -> Result where B1: SampleBorrow + Sized, B2: SampleBorrow + Sized, { UniformSampler::new(low, high) } fn sample(&self, rng: &mut R) -> Self::X { MyF32 { x: self.0.sample(rng), } } } impl SampleUniform for MyF32 { type Sampler = UniformMyF32; } let (low, high) = (MyF32 { x: 17.0f32 }, MyF32 { x: 22.0f32 }); let uniform = Uniform::new(low, high).unwrap(); let mut rng = crate::test::rng(804); for _ in 0..100 { let x: MyF32 = rng.sample(uniform); assert!(low <= x && x < high); } } #[test] fn value_stability() { fn test_samples( lb: T, ub: T, expected_single: &[T], expected_multiple: &[T], ) where Uniform: Distribution, { let mut rng = crate::test::rng(897); let mut buf = [lb; 3]; for x in &mut buf { *x = T::Sampler::sample_single(lb, ub, &mut rng).unwrap(); } assert_eq!(&buf, expected_single); let distr = Uniform::new(lb, ub).unwrap(); for x in &mut buf { *x = rng.sample(&distr); } assert_eq!(&buf, expected_multiple); } test_samples( 0f32, 1e-2f32, &[0.0003070104, 0.0026630748, 0.00979833], &[0.008194133, 0.00398172, 0.007428536], ); test_samples( -1e10f64, 1e10f64, &[-4673848682.871551, 6388267422.932352, 4857075081.198343], &[1173375212.1808167, 1917642852.109581, 2365076174.3153973], ); test_samples( Duration::new(2, 0), Duration::new(4, 0), &[ Duration::new(2, 532615131), Duration::new(3, 638826742), Duration::new(3, 485707508), ], &[ Duration::new(3, 117337521), Duration::new(3, 191764285), Duration::new(3, 236507617), ], ); } #[test] fn uniform_distributions_can_be_compared() { assert_eq!( Uniform::new(1.0, 2.0).unwrap(), Uniform::new(1.0, 2.0).unwrap() ); // To cover UniformInt assert_eq!( Uniform::new(1_u32, 2_u32).unwrap(), Uniform::new(1_u32, 2_u32).unwrap() ); } }