[−][src]Trait rand::Rng
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
fn gen<T>(&mut self) -> T where
Standard: Distribution<T>,
Standard: Distribution<T>,
Return a random value supporting the Standard
distribution.
Example
use rand::{thread_rng, Rng}; let mut rng = thread_rng(); let x: u32 = rng.gen(); println!("{}", x); println!("{:?}", rng.gen::<(f64, bool)>());
fn gen_range<T: SampleUniform, B1, B2>(&mut self, low: B1, high: B2) -> T where
B1: SampleBorrow<T> + Sized,
B2: SampleBorrow<T> + Sized,
B1: SampleBorrow<T> + Sized,
B2: SampleBorrow<T> + Sized,
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);
fn sample<T, D: Distribution<T>>(&mut self, distr: D) -> 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));
ⓘImportant traits for DistIter<'a, D, R, T>fn sample_iter<'a, T, D: Distribution<T>>(
&'a mut self,
distr: &'a D
) -> DistIter<'a, D, Self, T> where
Self: Sized,
&'a mut self,
distr: &'a D
) -> DistIter<'a, D, Self, T> where
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!"); }
fn fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T)
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[..]);
fn try_fill<T: AsByteSliceMut + ?Sized>(
&mut self,
dest: &mut T
) -> Result<(), Error>
&mut self,
dest: &mut T
) -> Result<(), Error>
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[..])?;
fn gen_bool(&mut self, p: f64) -> bool
Return a bool with a probability p
of being true.
See also the Bernoulli
distribution, which may be faster if
sampling from the same probability repeatedly.
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
.
fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool
Return a bool with a probability of numerator/denominator
of being
true. I.e. gen_ratio(2, 3)
has chance of 2 in 3, or about 67%, of
returning true. If numerator == denominator
, then the returned value
is guaranteed to be true
. If numerator == 0
, then the returned
value is guaranteed to be false
.
See also the Bernoulli
distribution, which may be faster if
sampling from the same numerator
and denominator
repeatedly.
Panics
If denominator == 0
or numerator > denominator
.
Example
use rand::{thread_rng, Rng}; let mut rng = thread_rng(); println!("{}", rng.gen_ratio(2, 3));
fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T>
use SliceRandom::choose instead
Return a random element from values
.
Deprecated: use [seq::SliceRandom::choose
] instead.
fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>
use SliceRandom::choose_mut instead
Return a mutable pointer to a random element from values
.
Deprecated: use [seq::SliceRandom::choose_mut
] instead.
fn shuffle<T>(&mut self, values: &mut [T])
use SliceRandom::shuffle instead
Shuffle a mutable slice in place.
Deprecated: use [seq::SliceRandom::shuffle
] instead.