[−][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: PartialOrd + SampleUniform>(&mut self, low: T, high: T) -> T
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));
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.
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.
fn choose<'a, T>(&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);
fn choose_mut<'a, T>(&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.
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);
fn gen_iter<T>(&mut self) -> Generator<T, &mut Self> where
Standard: Distribution<T>,
Standard: Distribution<T>,
use Rng::sample_iter(&Standard) instead
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)>>());
fn gen_weighted_bool(&mut self, n: u32) -> bool
use gen_bool instead
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));
fn gen_ascii_chars(&mut self) -> AsciiGenerator<&mut Self>
use sample_iter(&Alphanumeric) instead
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);
Implementors
impl<R: RngCore + ?Sized> Rng for R
[src]
impl<R: RngCore + ?Sized> Rng for R
fn gen<T>(&mut self) -> T where | [src] |
fn gen_range<T: PartialOrd + SampleUniform>(&mut self, low: T, high: T) -> T | [src] |
fn sample<T, D: Distribution<T>>(&mut self, distr: D) -> T | [src] |
ⓘImportant traits for DistIter<'a, D, R, T>
fn sample_iter<'a, T, D: Distribution<T>>( | [src] |
fn fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T) | [src] |
fn try_fill<T: AsByteSliceMut + ?Sized>( | [src] |
fn gen_bool(&mut self, p: f64) -> bool | [src] |
fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T> | [src] |
fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T> | [src] |
fn shuffle<T>(&mut self, values: &mut [T]) | [src] |
ⓘImportant traits for Generator<T, R>
fn gen_iter<T>(&mut self) -> Generator<T, &mut Self> where | [src] |
use Rng::sample_iter(&Standard) instead
fn gen_weighted_bool(&mut self, n: u32) -> bool | [src] |
use gen_bool instead
ⓘImportant traits for AsciiGenerator<R>
fn gen_ascii_chars(&mut self) -> AsciiGenerator<&mut Self> | [src] |
use sample_iter(&Alphanumeric) instead