pub trait Rng: RngCore {
Show 13 methods
fn gen<T>(&mut self) -> T
where
Standard: Distribution<T>,
{ ... }
fn gen_range<T>(&mut self, low: T, high: T) -> T
where
T: PartialOrd<T> + SampleUniform,
{ ... }
fn sample<T, D>(&mut self, distr: D) -> T
where
D: Distribution<T>,
{ ... }
fn sample_iter<T, D, 'a>(
&'a mut self,
distr: &'a D
) -> DistIter<'a, D, Self, T>
where
D: Distribution<T>,
Self: Sized,
{ ... }
fn fill<T>(&mut self, dest: &mut T)
where
T: AsByteSliceMut + ?Sized,
{ ... }
fn try_fill<T>(&mut self, dest: &mut T) -> Result<(), Error>
where
T: AsByteSliceMut + ?Sized,
{ ... }
fn gen_bool(&mut self, p: f64) -> bool { ... }
fn choose<T, 'a>(&mut self, values: &'a [T]) -> Option<&'a T> { ... }
fn choose_mut<T, 'a>(&mut self, values: &'a mut [T]) -> Option<&'a mut T> { ... }
fn shuffle<T>(&mut self, values: &mut [T]) { ... }
fn gen_iter<T>(&mut self) -> Generator<T, &mut Self>
where
Standard: Distribution<T>,
{ ... }
fn gen_weighted_bool(&mut self, n: u32) -> bool { ... }
fn gen_ascii_chars(&mut self) -> AsciiGenerator<&mut Self> { ... }
}
Expand description
An automatically-implemented extension trait on RngCore
providing high-level
generic methods for sampling values and other convenience methods.
This is the primary trait to use when generating random values.
Generic usage
The basic pattern is fn foo<R: Rng + ?Sized>(rng: &mut R)
. Some
things are worth noting here:
- Since
Rng: RngCore
and everyRngCore
implementsRng
, it makes no difference whether we useR: Rng
orR: RngCore
. - The
+ ?Sized
un-bounding allows functions to be called directly on type-erased references; i.e.foo(r)
wherer: &mut RngCore
. Without this it would be necessary to writefoo(&mut r)
.
An alternative pattern is possible: fn foo<R: Rng>(rng: R)
. This has some
trade-offs. It allows the argument to be consumed directly without a &mut
(which is how from_rng(thread_rng())
works); also it still works directly
on references (including type-erased references). Unfortunately within the
function foo
it is not known whether rng
is a reference type or not,
hence many uses of rng
require an extra reference, either explicitly
(distr.sample(&mut rng)
) or implicitly (rng.gen()
); one may hope the
optimiser can remove redundant references later.
Example:
use rand::Rng;
fn foo<R: Rng + ?Sized>(rng: &mut R) -> f32 {
rng.gen()
}
Provided Methods§
sourcefn gen<T>(&mut self) -> Twhere
Standard: Distribution<T>,
fn gen<T>(&mut self) -> Twhere
Standard: Distribution<T>,
sourcefn gen_range<T>(&mut self, low: T, high: T) -> Twhere
T: PartialOrd<T> + SampleUniform,
fn gen_range<T>(&mut self, low: T, high: T) -> Twhere
T: PartialOrd<T> + SampleUniform,
Generate a random value in the range [low
, high
), i.e. inclusive of
low
and exclusive of high
.
This function is optimised for the case that only a single sample is
made from the given range. See also the Uniform
distribution
type which may be faster if sampling from the same range repeatedly.
Panics
Panics if low >= high
.
Example
use rand::{thread_rng, Rng};
let mut rng = thread_rng();
let n: u32 = rng.gen_range(0, 10);
println!("{}", n);
let m: f64 = rng.gen_range(-40.0f64, 1.3e5f64);
println!("{}", m);
sourcefn sample<T, D>(&mut self, distr: D) -> Twhere
D: Distribution<T>,
fn sample<T, D>(&mut self, distr: D) -> Twhere
D: Distribution<T>,
Sample a new value, using the given distribution.
Example
use rand::{thread_rng, Rng};
use rand::distributions::Uniform;
let mut rng = thread_rng();
let x = rng.sample(Uniform::new(10u32, 15));
// Type annotation requires two types, the type and distribution; the
// distribution can be inferred.
let y = rng.sample::<u16, _>(Uniform::new(10, 15));
sourcefn sample_iter<T, D, 'a>(&'a mut self, distr: &'a D) -> DistIter<'a, D, Self, T>where
D: Distribution<T>,
Self: Sized,
fn sample_iter<T, D, 'a>(&'a mut self, distr: &'a D) -> DistIter<'a, D, Self, T>where
D: Distribution<T>,
Self: Sized,
Create an iterator that generates values using the given distribution.
Example
use rand::{thread_rng, Rng};
use rand::distributions::{Alphanumeric, Uniform, Standard};
let mut rng = thread_rng();
// Vec of 16 x f32:
let v: Vec<f32> = thread_rng().sample_iter(&Standard).take(16).collect();
// String:
let s: String = rng.sample_iter(&Alphanumeric).take(7).collect();
// Combined values
println!("{:?}", thread_rng().sample_iter(&Standard).take(5)
.collect::<Vec<(f64, bool)>>());
// Dice-rolling:
let die_range = Uniform::new_inclusive(1, 6);
let mut roll_die = rng.sample_iter(&die_range);
while roll_die.next().unwrap() != 6 {
println!("Not a 6; rolling again!");
}
sourcefn fill<T>(&mut self, dest: &mut T)where
T: AsByteSliceMut + ?Sized,
fn fill<T>(&mut self, dest: &mut T)where
T: AsByteSliceMut + ?Sized,
Fill dest
entirely with random bytes (uniform value distribution),
where dest
is any type supporting AsByteSliceMut
, namely slices
and arrays over primitive integer types (i8
, i16
, u32
, etc.).
On big-endian platforms this performs byte-swapping to ensure portability of results from reproducible generators.
This uses fill_bytes
internally which may handle some RNG errors
implicitly (e.g. waiting if the OS generator is not ready), but panics
on other errors. See also try_fill
which returns errors.
Example
use rand::{thread_rng, Rng};
let mut arr = [0i8; 20];
thread_rng().fill(&mut arr[..]);
sourcefn try_fill<T>(&mut self, dest: &mut T) -> Result<(), Error>where
T: AsByteSliceMut + ?Sized,
fn try_fill<T>(&mut self, dest: &mut T) -> Result<(), Error>where
T: AsByteSliceMut + ?Sized,
Fill dest
entirely with random bytes (uniform value distribution),
where dest
is any type supporting AsByteSliceMut
, namely slices
and arrays over primitive integer types (i8
, i16
, u32
, etc.).
On big-endian platforms this performs byte-swapping to ensure portability of results from reproducible generators.
This uses try_fill_bytes
internally and forwards all RNG errors. In
some cases errors may be resolvable; see ErrorKind
and
documentation for the RNG in use. If you do not plan to handle these
errors you may prefer to use fill
.
Example
use rand::{thread_rng, Rng};
let mut arr = [0u64; 4];
thread_rng().try_fill(&mut arr[..])?;
sourcefn gen_bool(&mut self, p: f64) -> bool
fn gen_bool(&mut self, p: f64) -> bool
Return a bool with a probability p
of being true.
This is a wrapper around distributions::Bernoulli
.
Example
use rand::{thread_rng, Rng};
let mut rng = thread_rng();
println!("{}", rng.gen_bool(1.0 / 3.0));
Panics
If p
< 0 or p
> 1.
sourcefn choose<T, 'a>(&mut self, values: &'a [T]) -> Option<&'a T>
fn choose<T, 'a>(&mut self, values: &'a [T]) -> Option<&'a T>
Return a random element from values
.
Return None
if values
is empty.
Example
use rand::{thread_rng, Rng};
let choices = [1, 2, 4, 8, 16, 32];
let mut rng = thread_rng();
println!("{:?}", rng.choose(&choices));
assert_eq!(rng.choose(&choices[..0]), None);
sourcefn choose_mut<T, 'a>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>
fn choose_mut<T, 'a>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>
Return a mutable pointer to a random element from values
.
Return None
if values
is empty.
sourcefn shuffle<T>(&mut self, values: &mut [T])
fn shuffle<T>(&mut self, values: &mut [T])
Shuffle a mutable slice in place.
This applies Durstenfeld’s algorithm for the Fisher–Yates shuffle which produces an unbiased permutation.
Example
use rand::{thread_rng, Rng};
let mut rng = thread_rng();
let mut y = [1, 2, 3];
rng.shuffle(&mut y);
println!("{:?}", y);
rng.shuffle(&mut y);
println!("{:?}", y);
sourcefn gen_iter<T>(&mut self) -> Generator<T, &mut Self>where
Standard: Distribution<T>,
fn gen_iter<T>(&mut self) -> Generator<T, &mut Self>where
Standard: Distribution<T>,
Return an iterator that will yield an infinite number of randomly generated items.
Example
use rand::{thread_rng, Rng};
let mut rng = thread_rng();
let x = rng.gen_iter::<u32>().take(10).collect::<Vec<u32>>();
println!("{:?}", x);
println!("{:?}", rng.gen_iter::<(f64, bool)>().take(5)
.collect::<Vec<(f64, bool)>>());
sourcefn gen_weighted_bool(&mut self, n: u32) -> bool
fn gen_weighted_bool(&mut self, n: u32) -> bool
Return a bool with a 1 in n chance of true
Example
use rand::{thread_rng, Rng};
let mut rng = thread_rng();
assert_eq!(rng.gen_weighted_bool(0), true);
assert_eq!(rng.gen_weighted_bool(1), true);
// Just like `rng.gen::<bool>()` a 50-50% chance, but using a slower
// method with different results.
println!("{}", rng.gen_weighted_bool(2));
// First meaningful use of `gen_weighted_bool`.
println!("{}", rng.gen_weighted_bool(3));
sourcefn gen_ascii_chars(&mut self) -> AsciiGenerator<&mut Self>
fn gen_ascii_chars(&mut self) -> AsciiGenerator<&mut Self>
Return an iterator of random characters from the set A-Z,a-z,0-9.
Example
use rand::{thread_rng, Rng};
let s: String = thread_rng().gen_ascii_chars().take(10).collect();
println!("{}", s);