2 // Copyright 2013-2017 The Rust Project Developers.
4 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
5 // https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6 // <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
18 /// An automatically-implemented extension trait on [`RngCore`] providing high-level
28 /// - Since `Rng: RngCore` and every `RngCore` implements `Rng`, it makes no
30 /// - The `+ ?Sized` un-bounding allows functions to be called directly on
31 ///   type-erased references; i.e. `foo(r)` where `r: &mut dyn RngCore`. Without
35 /// trade-offs. It allows the argument to be consumed directly without a `&mut`
37 /// on references (including type-erased references). Unfortunately within the
49 /// fn foo<R: Rng + ?Sized>(rng: &mut R) -> f32 {
78     /// (< 64 bit), it will likely be faster to instead use [`Rng::fill`].
88     /// rng.fill(&mut arr2);                    // array fill
93     fn gen<T>(&mut self) -> T  in gen()
98     /// Generate a random value in the given range.
101     /// made from the given range. See also the [`Uniform`] distribution
102     /// type which may be faster if sampling from the same range repeatedly.
108     /// Panics if the range is empty.
117     /// // Exclusive range
120     /// let m: f64 = rng.gen_range(-40.0..1.3e5);
123     /// // Inclusive range
129     fn gen_range<T, R>(&mut self, range: R) -> T  in gen_range()
134         assert!(!range.is_empty(), "cannot sample empty range");  in gen_range()
135         range.sample_single(self)  in gen_range()
152     fn sample<T, D: Distribution<T>>(&mut self, distr: D) -> T {  in sample()
185     /// // Dice-rolling:
192     fn sample_iter<T, D>(self, distr: D) -> distributions::DistIter<D, Self, T>  in sample_iter()
200     /// Fill any type implementing [`Fill`] with random data
203     /// this cannot be guaranteed for third-party implementations.
213     /// thread_rng().fill(&mut arr[..]);
218     fn fill<T: Fill + ?Sized>(&mut self, dest: &mut T) {  in fill()  method
219         dest.try_fill(self).unwrap_or_else(|_| panic!("Rng::fill failed"))  in fill()
222     /// Fill any type implementing [`Fill`] with random data
225     /// this cannot be guaranteed for third-party implementations.
227     /// This is identical to [`fill`] except that it forwards errors.
235     /// # fn try_inner() -> Result<(), Error> {
245     /// [`fill`]: Rng::fill
246     fn try_fill<T: Fill + ?Sized>(&mut self, dest: &mut T) -> Result<(), Error> {  in try_fill()
270     fn gen_bool(&mut self, p: f64) -> bool {  in gen_bool()
299     fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool {  in gen_ratio()
313 /// [Chapter on Portability](https://rust-random.github.io/book/portability.html)).
314 pub trait Fill {  interface
315     /// Fill self with random data
316     fn try_fill<R: Rng + ?Sized>(&mut self, rng: &mut R) -> Result<(), Error>;  in try_fill()
322         impl Fill for [$t] {  impl
323             fn try_fill<R: Rng + ?Sized>(&mut self, rng: &mut R) -> Result<(), Error> {
339 impl Fill for [u8] {  impl
340     fn try_fill<R: Rng + ?Sized>(&mut self, rng: &mut R) -> Result<(), Error> {  in try_fill()
348         impl Fill for [$t] {  impl
350             fn try_fill<R: Rng + ?Sized>(&mut self, rng: &mut R) -> Result<(), Error> {
366         impl Fill for [Wrapping<$t>] {  impl
368             fn try_fill<R: Rng + ?Sized>(&mut self, rng: &mut R) -> Result<(), Error> {
397 impl<T, const N: usize> Fill for [T; N]  impl
398 where [T]: Fill
400     fn try_fill<R: Rng + ?Sized>(&mut self, rng: &mut R) -> Result<(), Error> {  in try_fill()
409         impl<T> Fill for [T; $n] where [T]: Fill {  impl
410             fn try_fill<R: Rng + ?Sized>(&mut self, rng: &mut R) -> Result<(), Error> {
417         impl_fill_arrays!($n - 1, $($NN,)*);
463         // Convert to byte sequence and back to u64; byte-swap twice if BE.  in test_fill()
465         rng.fill(&mut array[..]);  in test_fill()
471         rng.fill(&mut array[..]);  in test_fill()
477         rng.fill(&mut warray[..]);  in test_fill()
483         rng.fill(&mut array);  in test_fill()
492         rng.fill(&mut array);  in test_fill_empty()
493         rng.fill(&mut array[..]);  in test_fill_empty()
500             let a = r.gen_range(-4711..17);  in test_gen_range_int()
501             assert!((-4711..17).contains(&a));  in test_gen_range_int()
502             let a: i8 = r.gen_range(-3..42);  in test_gen_range_int()
503             assert!((-3..42).contains(&a));  in test_gen_range_int()
506             let a: i32 = r.gen_range(-100..2000);  in test_gen_range_int()
507             assert!((-100..2000).contains(&a));  in test_gen_range_int()
512             assert_eq!(r.gen_range(-12i64..-11), -12i64);  in test_gen_range_int()
521             let a = r.gen_range(-4.5..1.7);  in test_gen_range_float()
522             assert!((-4.5..1.7).contains(&a));  in test_gen_range_float()
523             let a = r.gen_range(-1.1..=-0.3);  in test_gen_range_float()
524             assert!((-1.1..=-0.3).contains(&a));  in test_gen_range_float()
527             assert_eq!(r.gen_range(-11.0..=-11.0), -11.);  in test_gen_range_float()
537         r.gen_range(5..-2);  in test_gen_range_panic_int()
598         assert!(((sum - expected) as i32).abs() < 500);  in test_gen_ratio_average()