# [−][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));

###
ⓘImportant traits for DistIter<'a, D, R, T>

### Important traits for DistIter<'a, D, R, T>

`impl<'a, D, R, T> Iterator for DistIter<'a, D, R, T> where
D: Distribution<T>,
R: Rng + 'a, type Item = T;`
`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
    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>`

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

Deprecated since 0.6.0:

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

Deprecated since 0.6.0:

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

Deprecated since 0.6.0:

use SliceRandom::shuffle instead

Shuffle a mutable slice in place.

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

Loading content...

## Implementors

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

Loading content...

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)