45
45
//! # Extending `Uniform` to support a custom type
46
46
//!
47
47
//! To extend [`Uniform`] to support your own types, write a back-end which
48
- //! implements the [`UniformImpl `] trait, then implement the [`SampleUniform`]
48
+ //! implements the [`UniformSampler `] trait, then implement the [`SampleUniform`]
49
49
//! helper trait to "register" your back-end. See the `MyF32` example below.
50
50
//!
51
51
//! At a minimum, the back-end needs to store any parameters needed for sampling
56
56
//! use rand::{Rng, thread_rng};
57
57
//! use rand::distributions::Distribution;
58
58
//! use rand::distributions::uniform::{Uniform, SampleUniform};
59
- //! use rand::distributions::uniform::{UniformImpl , UniformFloat};
59
+ //! use rand::distributions::uniform::{UniformSampler , UniformFloat};
60
60
//!
61
61
//! #[derive(Clone, Copy, PartialEq, PartialOrd)]
62
62
//! struct MyF32(f32);
65
65
//! struct UniformMyF32 {
66
66
//! inner: UniformFloat<f32>,
67
67
//! }
68
- //! impl UniformImpl for UniformMyF32 {
68
+ //! impl UniformSampler for UniformMyF32 {
69
69
//! type X = MyF32;
70
70
//! fn new(low: Self::X, high: Self::X) -> Self {
71
71
//! UniformMyF32 {
72
72
//! inner: UniformFloat::<f32>::new(low.0, high.0),
73
73
//! }
74
74
//! }
75
75
//! fn new_inclusive(low: Self::X, high: Self::X) -> Self {
76
- //! UniformImpl ::new(low, high)
76
+ //! UniformSampler ::new(low, high)
77
77
//! }
78
78
//! fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X {
79
79
//! MyF32(self.inner.sample(rng))
80
80
//! }
81
81
//! }
82
82
//!
83
83
//! impl SampleUniform for MyF32 {
84
- //! type Impl = UniformMyF32;
84
+ //! type Sampler = UniformMyF32;
85
85
//! }
86
86
//!
87
87
//! let (low, high) = (MyF32(17.0f32), MyF32(22.0f32));
93
93
//! [`Uniform::sample_single`]: struct.Uniform.html#method.sample_single
94
94
//! [`Rng::gen_range`]: ../../trait.Rng.html#method.gen_range
95
95
//! [`SampleUniform`]: trait.SampleUniform.html
96
- //! [`UniformImpl `]: trait.UniformImpl .html
96
+ //! [`UniformSampler `]: trait.UniformSampler .html
97
97
//! [`UniformInt`]: struct.UniformInt.html
98
98
//! [`UniformFloat`]: struct.UniformFloat.html
99
99
//! [`UniformDuration`]: struct.UniformDuration.html
@@ -156,29 +156,29 @@ use distributions::float::IntoFloat;
156
156
/// [`sample_single`]: struct.Uniform.html#method.sample_single
157
157
#[ derive( Clone , Copy , Debug ) ]
158
158
pub struct Uniform < X : SampleUniform > {
159
- inner : X :: Impl ,
159
+ inner : X :: Sampler ,
160
160
}
161
161
162
162
impl < X : SampleUniform > Uniform < X > {
163
163
/// Create a new `Uniform` instance which samples uniformly from the half
164
164
/// open range `[low, high)` (excluding `high`). Panics if `low >= high`.
165
165
pub fn new ( low : X , high : X ) -> Uniform < X > {
166
166
assert ! ( low < high, "Uniform::new called with `low >= high`" ) ;
167
- Uniform { inner : X :: Impl :: new ( low, high) }
167
+ Uniform { inner : X :: Sampler :: new ( low, high) }
168
168
}
169
169
170
170
/// Create a new `Uniform` instance which samples uniformly from the closed
171
171
/// range `[low, high]` (inclusive). Panics if `low > high`.
172
172
pub fn new_inclusive ( low : X , high : X ) -> Uniform < X > {
173
173
assert ! ( low <= high, "Uniform::new_inclusive called with `low > high`" ) ;
174
- Uniform { inner : X :: Impl :: new_inclusive ( low, high) }
174
+ Uniform { inner : X :: Sampler :: new_inclusive ( low, high) }
175
175
}
176
176
177
177
/// Sample a single value uniformly from `[low, high)`.
178
178
/// Panics if `low >= high`.
179
179
pub fn sample_single < R : Rng + ?Sized > ( low : X , high : X , rng : & mut R ) -> X {
180
180
assert ! ( low < high, "Uniform::sample_single called with low >= high" ) ;
181
- X :: Impl :: sample_single ( low, high, rng)
181
+ X :: Sampler :: sample_single ( low, high, rng)
182
182
}
183
183
}
184
184
@@ -189,17 +189,17 @@ impl<X: SampleUniform> Distribution<X> for Uniform<X> {
189
189
}
190
190
191
191
/// Helper trait for creating objects using the correct implementation of
192
- /// [`UniformImpl `] for the sampling type.
192
+ /// [`UniformSampler `] for the sampling type.
193
193
///
194
194
/// See the [module documentation] on how to implement [`Uniform`] range
195
195
/// sampling for a custom type.
196
196
///
197
- /// [`UniformImpl `]: trait.UniformImpl .html
197
+ /// [`UniformSampler `]: trait.UniformSampler .html
198
198
/// [module documentation]: index.html
199
199
/// [`Uniform`]: struct.Uniform.html
200
200
pub trait SampleUniform : PartialOrd +Sized {
201
- /// The `UniformImpl ` implementation supporting type `X`.
202
- type Impl : UniformImpl < X = Self > ;
201
+ /// The `UniformSampler ` implementation supporting type `X`.
202
+ type Sampler : UniformSampler < X = Self > ;
203
203
}
204
204
205
205
/// Helper trait handling actual uniform sampling.
@@ -212,8 +212,8 @@ pub trait SampleUniform: PartialOrd+Sized {
212
212
///
213
213
/// [module documentation]: index.html
214
214
/// [`Uniform`]: struct.Uniform.html
215
- /// [`sample_single`]: struct.UniformImpl .html#method.sample_single
216
- pub trait UniformImpl : Sized {
215
+ /// [`sample_single`]: struct.UniformSampler .html#method.sample_single
216
+ pub trait UniformSampler : Sized {
217
217
/// The type sampled by this implementation.
218
218
type X : PartialOrd ;
219
219
@@ -243,19 +243,19 @@ pub trait UniformImpl: Sized {
243
243
///
244
244
/// Via this method, implementations can provide a method optimized for
245
245
/// sampling only a single value from the specified range. The default
246
- /// implementation simply calls `UniformImpl ::new` then `sample` on the
246
+ /// implementation simply calls `UniformSampler ::new` then `sample` on the
247
247
/// result.
248
248
fn sample_single < R : Rng + ?Sized > ( low : Self :: X , high : Self :: X , rng : & mut R )
249
249
-> Self :: X
250
250
{
251
- let uniform: Self = UniformImpl :: new ( low, high) ;
251
+ let uniform: Self = UniformSampler :: new ( low, high) ;
252
252
uniform. sample ( rng)
253
253
}
254
254
}
255
255
256
- /// The back-end implementing [`UniformImpl `] for integer types.
256
+ /// The back-end implementing [`UniformSampler `] for integer types.
257
257
///
258
- /// Unless you are implementing [`UniformImpl `] for your own type, this type
258
+ /// Unless you are implementing [`UniformSampler `] for your own type, this type
259
259
/// should not be used directly, use [`Uniform`] instead.
260
260
///
261
261
/// # Implementation notes
@@ -295,7 +295,7 @@ pub trait UniformImpl: Sized {
295
295
/// multiply by `range`, the result is in the high word. Then comparing the low
296
296
/// word against `zone` makes sure our distribution is uniform.
297
297
///
298
- /// [`UniformImpl `]: trait.UniformImpl .html
298
+ /// [`UniformSampler `]: trait.UniformSampler .html
299
299
/// [`Uniform`]: struct.Uniform.html
300
300
#[ derive( Clone , Copy , Debug ) ]
301
301
pub struct UniformInt < X > {
@@ -308,10 +308,10 @@ macro_rules! uniform_int_impl {
308
308
( $ty: ty, $signed: ty, $unsigned: ident,
309
309
$i_large: ident, $u_large: ident) => {
310
310
impl SampleUniform for $ty {
311
- type Impl = UniformInt <$ty>;
311
+ type Sampler = UniformInt <$ty>;
312
312
}
313
313
314
- impl UniformImpl for UniformInt <$ty> {
314
+ impl UniformSampler for UniformInt <$ty> {
315
315
// We play free and fast with unsigned vs signed here
316
316
// (when $ty is signed), but that's fine, since the
317
317
// contract of this macro is for $ty and $unsigned to be
@@ -322,7 +322,7 @@ macro_rules! uniform_int_impl {
322
322
#[ inline] // if the range is constant, this helps LLVM to do the
323
323
// calculations at compile-time.
324
324
fn new( low: Self :: X , high: Self :: X ) -> Self {
325
- UniformImpl :: new_inclusive( low, high - 1 )
325
+ UniformSampler :: new_inclusive( low, high - 1 )
326
326
}
327
327
328
328
#[ inline] // if the range is constant, this helps LLVM to do the
@@ -510,9 +510,9 @@ wmul_impl_usize! { u64 }
510
510
511
511
512
512
513
- /// The back-end implementing [`UniformImpl `] for floating-point types.
513
+ /// The back-end implementing [`UniformSampler `] for floating-point types.
514
514
///
515
- /// Unless you are implementing [`UniformImpl `] for your own type, this type
515
+ /// Unless you are implementing [`UniformSampler `] for your own type, this type
516
516
/// should not be used directly, use [`Uniform`] instead.
517
517
///
518
518
/// # Implementation notes
@@ -530,9 +530,9 @@ wmul_impl_usize! { u64 }
530
530
/// because the boundaries of a floats range are a bit of a fuzzy concept due to
531
531
/// rounding errors.
532
532
///
533
- /// [`UniformImpl `]: trait.UniformImpl .html
534
- /// [`new`]: trait.UniformImpl .html#tymethod.new
535
- /// [`new_inclusive`]: trait.UniformImpl .html#tymethod.new_inclusive
533
+ /// [`UniformSampler `]: trait.UniformSampler .html
534
+ /// [`new`]: trait.UniformSampler .html#tymethod.new
535
+ /// [`new_inclusive`]: trait.UniformSampler .html#tymethod.new_inclusive
536
536
/// [`Uniform`]: struct.Uniform.html
537
537
/// [`Standard`]: ../struct.Standard.html
538
538
#[ derive( Clone , Copy , Debug ) ]
@@ -544,10 +544,10 @@ pub struct UniformFloat<X> {
544
544
macro_rules! uniform_float_impl {
545
545
( $ty: ty, $bits_to_discard: expr, $next_u: ident) => {
546
546
impl SampleUniform for $ty {
547
- type Impl = UniformFloat <$ty>;
547
+ type Sampler = UniformFloat <$ty>;
548
548
}
549
549
550
- impl UniformImpl for UniformFloat <$ty> {
550
+ impl UniformSampler for UniformFloat <$ty> {
551
551
type X = $ty;
552
552
553
553
fn new( low: Self :: X , high: Self :: X ) -> Self {
@@ -560,7 +560,7 @@ macro_rules! uniform_float_impl {
560
560
}
561
561
562
562
fn new_inclusive( low: Self :: X , high: Self :: X ) -> Self {
563
- UniformImpl :: new( low, high)
563
+ UniformSampler :: new( low, high)
564
564
}
565
565
566
566
fn sample<R : Rng + ?Sized >( & self , rng: & mut R ) -> Self :: X {
@@ -594,12 +594,12 @@ macro_rules! uniform_float_impl {
594
594
uniform_float_impl ! { f32 , 32 - 23 , next_u32 }
595
595
uniform_float_impl ! { f64 , 64 - 52 , next_u64 }
596
596
597
- /// Implementation of [`UniformImpl `] for `Duration`.
597
+ /// Implementation of [`UniformSampler `] for `Duration`.
598
598
///
599
- /// Unless you are implementing [`UniformImpl `] for your own types, this type
599
+ /// Unless you are implementing [`UniformSampler `] for your own types, this type
600
600
/// should not be used directly, use [`Uniform`] instead.
601
601
///
602
- /// [`UniformImpl `]: trait.UniformImpl .html
602
+ /// [`UniformSampler `]: trait.UniformSampler .html
603
603
/// [`Uniform`]: struct.Uniform.html
604
604
#[ cfg( feature = "std" ) ]
605
605
#[ derive( Clone , Copy , Debug ) ]
@@ -622,11 +622,11 @@ enum UniformDurationMode {
622
622
623
623
#[ cfg( feature = "std" ) ]
624
624
impl SampleUniform for Duration {
625
- type Impl = UniformDuration ;
625
+ type Sampler = UniformDuration ;
626
626
}
627
627
628
628
#[ cfg( feature = "std" ) ]
629
- impl UniformImpl for UniformDuration {
629
+ impl UniformSampler for UniformDuration {
630
630
type X = Duration ;
631
631
632
632
#[ inline]
@@ -686,7 +686,7 @@ impl UniformImpl for UniformDuration {
686
686
#[ cfg( test) ]
687
687
mod tests {
688
688
use Rng ;
689
- use distributions:: uniform:: { Uniform , UniformImpl , UniformFloat , SampleUniform } ;
689
+ use distributions:: uniform:: { Uniform , UniformSampler , UniformFloat , SampleUniform } ;
690
690
691
691
#[ should_panic]
692
692
#[ test]
@@ -819,22 +819,22 @@ mod tests {
819
819
struct UniformMyF32 {
820
820
inner : UniformFloat < f32 > ,
821
821
}
822
- impl UniformImpl for UniformMyF32 {
822
+ impl UniformSampler for UniformMyF32 {
823
823
type X = MyF32 ;
824
824
fn new ( low : Self :: X , high : Self :: X ) -> Self {
825
825
UniformMyF32 {
826
826
inner : UniformFloat :: < f32 > :: new ( low. x , high. x ) ,
827
827
}
828
828
}
829
829
fn new_inclusive ( low : Self :: X , high : Self :: X ) -> Self {
830
- UniformImpl :: new ( low, high)
830
+ UniformSampler :: new ( low, high)
831
831
}
832
832
fn sample < R : Rng + ?Sized > ( & self , rng : & mut R ) -> Self :: X {
833
833
MyF32 { x : self . inner . sample ( rng) }
834
834
}
835
835
}
836
836
impl SampleUniform for MyF32 {
837
- type Impl = UniformMyF32 ;
837
+ type Sampler = UniformMyF32 ;
838
838
}
839
839
840
840
let ( low, high) = ( MyF32 { x : 17.0f32 } , MyF32 { x : 22.0f32 } ) ;
0 commit comments