# Trait rand::Rng

``````pub trait Rng: RngCore {
// Provided methods
fn gen<T>(&mut self) -> T
where Standard: Distribution<T> { ... }
fn gen_range<T, R>(&mut self, range: R) -> T
where T: SampleUniform,
R: SampleRange<T> { ... }
fn sample<T, D: Distribution<T>>(&mut self, distr: D) -> T { ... }
fn sample_iter<T, D>(self, distr: D) -> DistIter<D, Self, T> ⓘ
where D: Distribution<T>,
Self: Sized { ... }
fn fill<T: Fill + ?Sized>(&mut self, dest: &mut T) { ... }
fn try_fill<T: Fill + ?Sized>(&mut self, dest: &mut T) -> Result<(), Error> { ... }
fn gen_bool(&mut self, p: f64) -> bool { ... }
fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool { ... }
}``````
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 every `RngCore` implements `Rng`, it makes no difference whether we use `R: Rng` or `R: RngCore`.
• The `+ ?Sized` un-bounding allows functions to be called directly on type-erased references; i.e. `foo(r)` where `r: &mut dyn RngCore`. Without this it would be necessary to write `foo(&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§

source

#### fn gen<T>(&mut self) -> Twhere Standard: Distribution<T>,

Return a random value supporting the `Standard` distribution.

##### §Example
``````use rand::{thread_rng, Rng};

let x: u32 = rng.gen();
println!("{}", x);
println!("{:?}", rng.gen::<(f64, bool)>());``````
##### §Arrays and tuples

The `rng.gen()` method is able to generate arrays (up to 32 elements) and tuples (up to 12 elements), so long as all element types can be generated. When using `rustc` ≥ 1.51, enable the `min_const_gen` feature to support arrays larger than 32 elements.

For arrays of integers, especially for those with small element types (< 64 bit), it will likely be faster to instead use `Rng::fill`.

``````use rand::{thread_rng, Rng};

let tuple: (u8, i32, char) = rng.gen(); // arbitrary tuple support

let arr1: [f32; 32] = rng.gen();        // array construction
let mut arr2 = [0u8; 128];
rng.fill(&mut arr2);                    // array fill``````
source

#### fn gen_range<T, R>(&mut self, range: R) -> Twhere T: SampleUniform, R: SampleRange<T>,

Generate a random value in the given range.

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.

Only `gen_range(low..high)` and `gen_range(low..=high)` are supported.

##### §Panics

Panics if the range is empty.

##### §Example
``````use rand::{thread_rng, Rng};

// Exclusive range
let n: u32 = rng.gen_range(0..10);
println!("{}", n);
let m: f64 = rng.gen_range(-40.0..1.3e5);
println!("{}", m);

// Inclusive range
let n: u32 = rng.gen_range(0..=10);
println!("{}", n);``````
source

#### 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 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));``````
source

#### fn sample_iter<T, D>(self, distr: D) -> DistIter<D, Self, T> ⓘwhere D: Distribution<T>, Self: Sized,

Create an iterator that generates values using the given distribution.

Note that this function takes its arguments by value. This works since `(&mut R): Rng where R: Rng` and `(&D): Distribution where D: Distribution`, however borrowing is not automatic hence `rng.sample_iter(...)` may need to be replaced with `(&mut rng).sample_iter(...)`.

##### §Example
``````use rand::{thread_rng, Rng};
use rand::distributions::{Alphanumeric, Uniform, Standard};

// Vec of 16 x f32:
let v: Vec<f32> = (&mut rng).sample_iter(Standard).take(16).collect();

// String:
let s: String = (&mut rng).sample_iter(Alphanumeric)
.take(7)
.map(char::from)
.collect();

// Combined values
println!("{:?}", (&mut rng).sample_iter(Standard).take(5)
.collect::<Vec<(f64, bool)>>());

// Dice-rolling:
let die_range = Uniform::new_inclusive(1, 6);
let mut roll_die = (&mut rng).sample_iter(die_range);
while roll_die.next().unwrap() != 6 {
println!("Not a 6; rolling again!");
}``````
source

#### fn fill<T: Fill + ?Sized>(&mut self, dest: &mut T)

Fill any type implementing `Fill` with random data

The distribution is expected to be uniform with portable results, but this cannot be guaranteed for third-party implementations.

This is identical to `try_fill` except that it panics on error.

##### §Example
``````use rand::{thread_rng, Rng};

let mut arr = [0i8; 20];
source

#### fn try_fill<T: Fill + ?Sized>(&mut self, dest: &mut T) -> Result<(), Error>

Fill any type implementing `Fill` with random data

The distribution is expected to be uniform with portable results, but this cannot be guaranteed for third-party implementations.

This is identical to `fill` except that it forwards errors.

##### §Example
``````use rand::{thread_rng, Rng};

let mut arr = [0u64; 4];
``````
source

#### 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};

println!("{}", rng.gen_bool(1.0 / 3.0));``````
##### §Panics

If `p < 0` or `p > 1`.

source

#### 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};

println!("{}", rng.gen_ratio(2, 3));``````

## Object Safety§

This trait is not object safe.

source§