# Trait rand::Rng

``````pub trait Rng: RngCore {
// Provided methods
fn random<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 gen_iter<T>(self) -> DistIter<Standard, Self, T> ⓘ
where Self: Sized,
Standard: Distribution<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 gen_bool(&mut self, p: f64) -> bool { ... }
fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool { ... }
fn gen<T>(&mut self) -> T
where Standard: Distribution<T> { ... }
}``````
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.random()`); one may hope the optimiser can remove redundant references later.

Example:

``````use rand::Rng;

fn foo<R: Rng + ?Sized>(rng: &mut R) -> f32 {
rng.random()
}
``````

## Provided Methods§

source

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

Return a random value via the `Standard` distribution.

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

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

The `rng.random()` method is able to generate arrays and tuples (up to 12 elements), so long as all element types can be generated.

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 mut rng = thread_rng();
let tuple: (u8, i32, char) = rng.random(); // arbitrary tuple support

let arr1: [f32; 32] = rng.random();        // 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, or if `high - low` overflows for floats.

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

let mut rng = thread_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 gen_iter<T>(self) -> DistIter<Standard, Self, T> ⓘwhere Self: Sized, Standard: Distribution<T>,

Generate values via an iterator

This is a just a wrapper over `Rng::sample_iter` using `distributions::Standard`.

Note: this method consumes its argument. Use `(&mut rng).gen_iter()` to avoid consuming the RNG.

##### §Example
``````use rand::{rngs::mock::StepRng, Rng};

let rng = StepRng::new(1, 1);
let v: Vec<i32> = rng.gen_iter().take(5).collect();
assert_eq!(&v, &[1, 2, 3, 4, 5]);``````
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 mut rng = thread_rng();
let x = rng.sample(Uniform::new(10u32, 15).unwrap());
// Type annotation requires two types, the type and distribution; the
// distribution can be inferred.
let y = rng.sample::<u16, _>(Uniform::new(10, 15).unwrap());``````
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: this method consumes its arguments. Use `(&mut rng).sample_iter(..)` to avoid consuming the RNG.

##### §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> = (&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).unwrap();
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.

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

let mut arr = [0i8; 20];
thread_rng().fill(&mut arr[..]);``````
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};

let mut rng = thread_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};

let mut rng = thread_rng();
println!("{}", rng.gen_ratio(2, 3));``````
source

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

👎Deprecated since 0.9.0: Renamed to `random` to avoid conflict with the new `gen` keyword in Rust 2024.

## Object Safety§

This trait is not object safe.

source§