rand::Rng - Rust
Description: API documentation for the Rust `Rng` trait in crate `rand`.
Keywords: rust, rustlang, rust-lang, Rng

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

    pub trait Rng {
        fn next_u32(&mut self) -> u32;

        fn next_u64(&mut self) -> u64 { ... }
        fn next_f32(&mut self) -> f32 { ... }
        fn next_f64(&mut self) -> f64 { ... }
        fn fill_bytes(&mut self, dest: &mut [u8]) { ... }
        fn gen<T: Rand>(&mut self) -> T
        where
            Self: Sized,
        { ... }
        fn gen_iter<'a, T: Rand>(&'a mut self) -> Generator<'a, T, Self>
        where
            Self: Sized,
        { ... }
        fn gen_range<T: PartialOrd + SampleRange>(&mut self, low: T, high: T) -> T
        where
            Self: Sized,
        { ... }
        fn gen_weighted_bool(&mut self, n: u32) -> bool
        where
            Self: Sized,
        { ... }
        fn gen_ascii_chars<'a>(&'a mut self) -> AsciiGenerator<'a, Self>
        where
            Self: Sized,
        { ... }
        fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T>
        where
            Self: Sized,
        { ... }
        fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>
        where
            Self: Sized,
        { ... }
        fn shuffle<T>(&mut self, values: &mut [T])
        where
            Self: Sized,
        { ... }
    }

A random number generator.

## Required Methods

### `fn next_u32(&mut self) -> u32`

Return the next random u32.

This rarely needs to be called directly, prefer `r.gen()` to `r.next_u32()`.

## Provided Methods

### `fn next_u64(&mut self) -> u64`

Return the next random u64.

By default this is implemented in terms of `next_u32`. An implementation of this trait must provide at least one of these two methods. Similarly to `next_u32`, this rarely needs to be called directly, prefer `r.gen()` to `r.next_u64()`.

### `fn next_f32(&mut self) -> f32`

Return the next random f32 selected from the half-open interval `[0, 1)`.

This uses a technique described by Saito and Matsumoto at MCQMC'08. Given that the IEEE floating point numbers are uniformly distributed over [1,2), we generate a number in this range and then offset it onto the range [0,1). Our choice of bits (masking v. shifting) is arbitrary and should be immaterial for high quality generators. For low quality generators (ex. LCG), prefer bitshifting due to correlation between sequential low order bits.

See: A PRNG specialized in double precision floating point numbers using an affine transition

- http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/ARTICLES/dSFMT.pdf
- http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/dSFMT-slide-e.pdf

By default this is implemented in terms of `next_u32`, but a random number generator which can generate numbers satisfying the requirements directly can overload this for performance. It is required that the return value lies in `[0, 1)`.

See `Closed01` for the closed interval `[0,1]`, and `Open01` for the open interval `(0,1)`.

### `fn next_f64(&mut self) -> f64`

Return the next random f64 selected from the half-open interval `[0, 1)`.

By default this is implemented in terms of `next_u64`, but a random number generator which can generate numbers satisfying the requirements directly can overload this for performance. It is required that the return value lies in `[0, 1)`.

See `Closed01` for the closed interval `[0,1]`, and `Open01` for the open interval `(0,1)`.

### `fn fill_bytes(&mut self, dest: &mut [u8])`

Fill `dest` with random data.

This has a default implementation in terms of `next_u64` and `next_u32`, but should be overridden by implementations that offer a more efficient solution than just calling those methods repeatedly.

This method does not have a requirement to bear any fixed relationship to the other methods, for example, it does not have to result in the same output as progressively filling `dest` with `self.gen::<u8>()`, and any such behaviour should not be relied upon.

This method should guarantee that `dest` is entirely filled with new data, and may panic if this is impossible (e.g. reading past the end of a file that is being used as the source of randomness).

# Example

    use rand::{thread_rng, Rng};

    let mut v = [0u8; 13579];
    thread_rng().fill_bytes(&mut v);
    println!("{:?}", &v[..]);

### `fn gen<T: Rand>(&mut self) -> T where
Self: Sized,`

Return a random value of a `Rand` type.

# 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_iter<'a, T: Rand>(&'a mut self) -> Generator<'a, T, Self> where
Self: Sized,`

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_range<T: PartialOrd + SampleRange>(&mut self, low: T, high: T) -> T where
Self: Sized,`

Generate a random value in the range [`low`, `high`).

This is a convenience wrapper around `distributions::Range`. If this function will be called repeatedly with the same arguments, one should use `Range`, as that will amortize the computations that allow for perfect uniformity, as they only happen on initialization.

# 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 gen_weighted_bool(&mut self, n: u32) -> bool where
Self: Sized,`

Return a bool with a 1 in n chance of true

# Example

    use rand::{thread_rng, Rng};

    let mut rng = thread_rng();
    println!("{}", rng.gen_weighted_bool(3));

### `fn gen_ascii_chars<'a>(&'a mut self) -> AsciiGenerator<'a, Self> where
Self: Sized,`

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

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

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> where
Self: Sized,`

Return a mutable pointer to a random element from `values`.

Return `None` if `values` is empty.

### `fn shuffle<T>(&mut self, values: &mut [T]) where
Self: Sized,`

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

## Implementors

- `impl Rng for IsaacRng`
- `impl Rng for Isaac64Rng`
- `impl Rng for ChaChaRng`
- `impl<R: Rng, Rsdr: Reseeder<R>> Rng for ReseedingRng<R, Rsdr>`
- `impl Rng for OsRng`
- `impl<R: Read> Rng for ReadRng<R>`
- `impl<'a, R: ?Sized> Rng for &'a mut R where
  R: Rng,`
- `impl<R: ?Sized> Rng for Box<R> where
  R: Rng,`
- `impl Rng for XorShiftRng`
- `impl Rng for StdRng`
- `impl Rng for ThreadRng`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand 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`)