|
| 1 | +// Copyright 2017 The Rust Project Developers. See the COPYRIGHT |
| 2 | +// file at the top-level directory of this distribution and at |
| 3 | +// https://rust-lang.org/COPYRIGHT. |
| 4 | +// |
| 5 | +// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or |
| 6 | +// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license |
| 7 | +// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your |
| 8 | +// option. This file may not be copied, modified, or distributed |
| 9 | +// except according to those terms. |
| 10 | + |
| 11 | +//! Basic floating-point number distributions |
| 12 | +
|
| 13 | + |
| 14 | +/// A distribution to sample floating point numbers uniformly in the open |
| 15 | +/// interval `(0, 1)` (not including either endpoint). |
| 16 | +/// |
| 17 | +/// See also: [`Closed01`] for the closed `[0, 1]`; [`Uniform`] for the |
| 18 | +/// half-open `[0, 1)`. |
| 19 | +/// |
| 20 | +/// # Example |
| 21 | +/// ```rust |
| 22 | +/// use rand::{weak_rng, Rng}; |
| 23 | +/// use rand::distributions::Open01; |
| 24 | +/// |
| 25 | +/// let val: f32 = weak_rng().sample(Open01); |
| 26 | +/// println!("f32 from (0,1): {}", val); |
| 27 | +/// ``` |
| 28 | +/// |
| 29 | +/// [`Uniform`]: struct.Uniform.html |
| 30 | +/// [`Closed01`]: struct.Closed01.html |
| 31 | +#[derive(Clone, Copy, Debug)] |
| 32 | +pub struct Open01; |
| 33 | + |
| 34 | +/// A distribution to sample floating point numbers uniformly in the closed |
| 35 | +/// interval `[0, 1]` (including both endpoints). |
| 36 | +/// |
| 37 | +/// See also: [`Open01`] for the open `(0, 1)`; [`Uniform`] for the half-open |
| 38 | +/// `[0, 1)`. |
| 39 | +/// |
| 40 | +/// # Example |
| 41 | +/// ```rust |
| 42 | +/// use rand::{weak_rng, Rng}; |
| 43 | +/// use rand::distributions::Closed01; |
| 44 | +/// |
| 45 | +/// let val: f32 = weak_rng().sample(Closed01); |
| 46 | +/// println!("f32 from [0,1]: {}", val); |
| 47 | +/// ``` |
| 48 | +/// |
| 49 | +/// [`Uniform`]: struct.Uniform.html |
| 50 | +/// [`Open01`]: struct.Open01.html |
| 51 | +#[derive(Clone, Copy, Debug)] |
| 52 | +pub struct Closed01; |
| 53 | + |
| 54 | + |
| 55 | +macro_rules! float_impls { |
| 56 | + ($mod_name:ident, $ty:ty, $mantissa_bits:expr, $method_name:ident) => { |
| 57 | + mod $mod_name { |
| 58 | + use Rng; |
| 59 | + use distributions::{Distribution, Uniform}; |
| 60 | + use super::{Open01, Closed01}; |
| 61 | + |
| 62 | + const SCALE: $ty = (1u64 << $mantissa_bits) as $ty; |
| 63 | + |
| 64 | + impl Distribution<$ty> for Uniform { |
| 65 | + /// Generate a floating point number in the half-open |
| 66 | + /// interval `[0,1)`. |
| 67 | + /// |
| 68 | + /// See `Closed01` for the closed interval `[0,1]`, |
| 69 | + /// and `Open01` for the open interval `(0,1)`. |
| 70 | + #[inline] |
| 71 | + fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> $ty { |
| 72 | + rng.$method_name() |
| 73 | + } |
| 74 | + } |
| 75 | + impl Distribution<$ty> for Open01 { |
| 76 | + #[inline] |
| 77 | + fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> $ty { |
| 78 | + // add 0.5 * epsilon, so that smallest number is |
| 79 | + // greater than 0, and largest number is still |
| 80 | + // less than 1, specifically 1 - 0.5 * epsilon. |
| 81 | + rng.$method_name() + 0.5 / SCALE |
| 82 | + } |
| 83 | + } |
| 84 | + impl Distribution<$ty> for Closed01 { |
| 85 | + #[inline] |
| 86 | + fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> $ty { |
| 87 | + // rescale so that 1.0 - epsilon becomes 1.0 |
| 88 | + // precisely. |
| 89 | + rng.$method_name() * SCALE / (SCALE - 1.0) |
| 90 | + } |
| 91 | + } |
| 92 | + } |
| 93 | + } |
| 94 | +} |
| 95 | +float_impls! { f64_rand_impls, f64, 52, next_f64 } |
| 96 | +float_impls! { f32_rand_impls, f32, 23, next_f32 } |
| 97 | + |
| 98 | + |
| 99 | +#[cfg(test)] |
| 100 | +mod tests { |
| 101 | + use {Rng, RngCore, impls}; |
| 102 | + use distributions::{Open01, Closed01}; |
| 103 | + |
| 104 | + const EPSILON32: f32 = ::core::f32::EPSILON; |
| 105 | + const EPSILON64: f64 = ::core::f64::EPSILON; |
| 106 | + |
| 107 | + struct ConstantRng(u64); |
| 108 | + impl RngCore for ConstantRng { |
| 109 | + fn next_u32(&mut self) -> u32 { |
| 110 | + let ConstantRng(v) = *self; |
| 111 | + v as u32 |
| 112 | + } |
| 113 | + fn next_u64(&mut self) -> u64 { |
| 114 | + let ConstantRng(v) = *self; |
| 115 | + v |
| 116 | + } |
| 117 | + |
| 118 | + fn fill_bytes(&mut self, dest: &mut [u8]) { |
| 119 | + impls::fill_bytes_via_u64(self, dest) |
| 120 | + } |
| 121 | + } |
| 122 | + |
| 123 | + #[test] |
| 124 | + fn floating_point_edge_cases() { |
| 125 | + let mut zeros = ConstantRng(0); |
| 126 | + assert_eq!(zeros.gen::<f32>(), 0.0); |
| 127 | + assert_eq!(zeros.gen::<f64>(), 0.0); |
| 128 | + |
| 129 | + let mut one = ConstantRng(1); |
| 130 | + assert_eq!(one.gen::<f32>(), EPSILON32); |
| 131 | + assert_eq!(one.gen::<f64>(), EPSILON64); |
| 132 | + |
| 133 | + let mut max = ConstantRng(!0); |
| 134 | + assert_eq!(max.gen::<f32>(), 1.0 - EPSILON32); |
| 135 | + assert_eq!(max.gen::<f64>(), 1.0 - EPSILON64); |
| 136 | + } |
| 137 | + |
| 138 | + #[test] |
| 139 | + fn fp_closed_edge_cases() { |
| 140 | + let mut zeros = ConstantRng(0); |
| 141 | + assert_eq!(zeros.sample::<f32, _>(Closed01), 0.0); |
| 142 | + assert_eq!(zeros.sample::<f64, _>(Closed01), 0.0); |
| 143 | + |
| 144 | + let mut one = ConstantRng(1); |
| 145 | + let one32 = one.sample::<f32, _>(Closed01); |
| 146 | + let one64 = one.sample::<f64, _>(Closed01); |
| 147 | + assert!(EPSILON32 < one32 && one32 < EPSILON32 * 1.01); |
| 148 | + assert!(EPSILON64 < one64 && one64 < EPSILON64 * 1.01); |
| 149 | + |
| 150 | + let mut max = ConstantRng(!0); |
| 151 | + assert_eq!(max.sample::<f32, _>(Closed01), 1.0); |
| 152 | + assert_eq!(max.sample::<f64, _>(Closed01), 1.0); |
| 153 | + } |
| 154 | + |
| 155 | + #[test] |
| 156 | + fn fp_open_edge_cases() { |
| 157 | + let mut zeros = ConstantRng(0); |
| 158 | + assert_eq!(zeros.sample::<f32, _>(Open01), 0.0 + EPSILON32 / 2.0); |
| 159 | + assert_eq!(zeros.sample::<f64, _>(Open01), 0.0 + EPSILON64 / 2.0); |
| 160 | + |
| 161 | + let mut one = ConstantRng(1); |
| 162 | + let one32 = one.sample::<f32, _>(Open01); |
| 163 | + let one64 = one.sample::<f64, _>(Open01); |
| 164 | + assert!(EPSILON32 < one32 && one32 < EPSILON32 * 2.0); |
| 165 | + assert!(EPSILON64 < one64 && one64 < EPSILON64 * 2.0); |
| 166 | + |
| 167 | + let mut max = ConstantRng(!0); |
| 168 | + assert_eq!(max.sample::<f32, _>(Open01), 1.0 - EPSILON32 / 2.0); |
| 169 | + assert_eq!(max.sample::<f64, _>(Open01), 1.0 - EPSILON64 / 2.0); |
| 170 | + } |
| 171 | + |
| 172 | + #[test] |
| 173 | + fn rand_open() { |
| 174 | + // this is unlikely to catch an incorrect implementation that |
| 175 | + // generates exactly 0 or 1, but it keeps it sane. |
| 176 | + let mut rng = ::test::rng(510); |
| 177 | + for _ in 0..1_000 { |
| 178 | + // strict inequalities |
| 179 | + let f: f64 = rng.sample(Open01); |
| 180 | + assert!(0.0 < f && f < 1.0); |
| 181 | + |
| 182 | + let f: f32 = rng.sample(Open01); |
| 183 | + assert!(0.0 < f && f < 1.0); |
| 184 | + } |
| 185 | + } |
| 186 | + |
| 187 | + #[test] |
| 188 | + fn rand_closed() { |
| 189 | + let mut rng = ::test::rng(511); |
| 190 | + for _ in 0..1_000 { |
| 191 | + // strict inequalities |
| 192 | + let f: f64 = rng.sample(Closed01); |
| 193 | + assert!(0.0 <= f && f <= 1.0); |
| 194 | + |
| 195 | + let f: f32 = rng.sample(Closed01); |
| 196 | + assert!(0.0 <= f && f <= 1.0); |
| 197 | + } |
| 198 | + } |
| 199 | +} |
0 commit comments