Struct rand_distr::Uniform
source · pub struct Uniform<X>(/* private fields */)
where
X: SampleUniform;
Expand description
Sample values uniformly between two bounds.
Uniform::new
and Uniform::new_inclusive
construct a uniform
distribution sampling from the given range; these functions may do extra
work up front to make sampling of multiple values faster. If only one sample
from the range is required, Rng::gen_range
can be more efficient.
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 Standard
distribution.
Steps are taken to avoid bias, which might be present in naive
implementations; for example rng.gen::<u8>() % 170
samples from the range
[0, 169]
but is twice as likely to select numbers less than 85 than other
values. Further, the implementations here give more weight to the high-bits
generated by the RNG than the low bits, since with some RNGs the low-bits
are of lower quality than the high bits.
Implementations must sample in [low, high)
range for
Uniform::new(low, high)
, i.e., excluding high
. In particular, care must
be taken to ensure that rounding never results values < low
or >= high
.
§Example
use rand::distr::{Distribution, Uniform};
let between = Uniform::try_from(10..10000).unwrap();
let mut rng = rand::thread_rng();
let mut sum = 0;
for _ in 0..1000 {
sum += between.sample(&mut rng);
}
println!("{}", sum);
For a single sample, Rng::gen_range
may be preferred:
use rand::Rng;
let mut rng = rand::thread_rng();
println!("{}", rng.gen_range(0..10));
Implementations§
source§impl<X> Uniform<X>where
X: SampleUniform,
impl<X> Uniform<X>where
X: SampleUniform,
sourcepub fn new<B1, B2>(low: B1, high: B2) -> Result<Uniform<X>, Error>where
B1: SampleBorrow<X>,
B2: SampleBorrow<X>,
pub fn new<B1, B2>(low: B1, high: B2) -> Result<Uniform<X>, Error>where
B1: SampleBorrow<X>,
B2: SampleBorrow<X>,
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.
sourcepub fn new_inclusive<B1, B2>(low: B1, high: B2) -> Result<Uniform<X>, Error>where
B1: SampleBorrow<X>,
B2: SampleBorrow<X>,
pub fn new_inclusive<B1, B2>(low: B1, high: B2) -> Result<Uniform<X>, Error>where
B1: SampleBorrow<X>,
B2: SampleBorrow<X>,
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.
Trait Implementations§
source§impl<'de, X> Deserialize<'de> for Uniform<X>
impl<'de, X> Deserialize<'de> for Uniform<X>
source§fn deserialize<__D>(
__deserializer: __D,
) -> Result<Uniform<X>, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(
__deserializer: __D,
) -> Result<Uniform<X>, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,
source§impl DistString for Uniform<char>
impl DistString for Uniform<char>
Note: the String
is potentially left with excess capacity if the range
includes non ascii chars; optionally the user may call
string.shrink_to_fit()
afterwards.
source§impl<X> Distribution<X> for Uniform<X>where
X: SampleUniform,
impl<X> Distribution<X> for Uniform<X>where
X: SampleUniform,
source§impl<X> Serialize for Uniform<X>
impl<X> Serialize for Uniform<X>
source§fn serialize<__S>(
&self,
__serializer: __S,
) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>where
__S: Serializer,
fn serialize<__S>(
&self,
__serializer: __S,
) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>where
__S: Serializer,
source§impl<X> TryFrom<RangeInclusive<X>> for Uniform<X>where
X: SampleUniform,
impl<X> TryFrom<RangeInclusive<X>> for Uniform<X>where
X: SampleUniform,
impl<X> Copy for Uniform<X>
impl<X> Eq for Uniform<X>
impl<X> StructuralPartialEq for Uniform<X>where
X: SampleUniform,
Auto Trait Implementations§
impl<X> Freeze for Uniform<X>
impl<X> RefUnwindSafe for Uniform<X>
impl<X> Send for Uniform<X>
impl<X> Sync for Uniform<X>
impl<X> Unpin for Uniform<X>
impl<X> UnwindSafe for Uniform<X>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)