# [−][src]Trait rand::Rng

```pub trait Rng: RngCore {
fn gen<T>(&mut self) -> T    where        Standard: Distribution<T>,
{ ... }
fn gen_range<T: SampleUniform, B1, B2>(&mut self, low: B1, high: B2) -> T    where        B1: SampleBorrow<T> + Sized,        B2: SampleBorrow<T> + Sized,
{ ... }
fn sample<T, D: Distribution<T>>(&mut self, distr: D) -> T { ... }
fn sample_iter<'a, T, D: Distribution<T>>(        &'a mut self,         distr: &'a D    ) -> DistIter<'a, D, Self, T>    where        Self: Sized,
{ ... }
fn fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T) { ... }
fn try_fill<T: AsByteSliceMut + ?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 { ... }
fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T> { ... }
fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T> { ... }
fn shuffle<T>(&mut self, values: &mut [T]) { ... }
}```

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 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

### `fn gen<T>(&mut self) -> T where    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, `

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, `

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
.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];

### `fn try_fill<T: AsByteSliceMut + ?Sized>(    &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];
```

### `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>`

Deprecated since 0.6.0:

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>`

Deprecated since 0.6.0:

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])`

Deprecated since 0.6.0:

Shuffle a mutable slice in place.

Deprecated: use `seq::SliceRandom::shuffle` instead.

## Implementors

### `impl<R: RngCore + ?Sized> Rng for R`[src]

#### `fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T>`[src]

Deprecated since 0.6.0:

#### `fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>`[src]

Deprecated since 0.6.0: