Crate fastrand

A simple and fast random number generator.

The implementation uses Wyrand, a simple and fast generator but not cryptographically secure.

Examples

Flip a coin:

if fastrand::bool() {
    println!("heads");
} else {
    println!("tails");
}

Generate a random i32:

let num = fastrand::i32(..);

Choose a random element in an array:

let v = vec![1, 2, 3, 4, 5];
let i = fastrand::usize(..v.len());
let elem = v[i];

Sample values from an array with O(n) complexity (n is the length of array):

fastrand::choose_multiple(vec![1, 4, 5].iter(), 2);
fastrand::choose_multiple(0..20, 12);

Shuffle an array:

let mut v = vec![1, 2, 3, 4, 5];
fastrand::shuffle(&mut v);

Generate a random Vec or [String]:

use std::iter::repeat_with;

let v: Vec<i32> = repeat_with(|| fastrand::i32(..)).take(10).collect();
let s: String = repeat_with(fastrand::alphanumeric).take(10).collect();

To get reproducible results on every run, initialize the generator with a seed:

// Pick an arbitrary number as seed.
fastrand::seed(7);

// Now this prints the same number on every run:
println!("{}", fastrand::u32(..));

To be more efficient, create a new Rng instance instead of using the thread-local generator:

use std::iter::repeat_with;

let mut rng = fastrand::Rng::new();
let mut bytes: Vec<u8> = repeat_with(|| rng.u8(..)).take(10_000).collect();

This crate aims to expose a core set of useful randomness primitives. For more niche algorithms, consider using the fastrand-contrib crate alongside this one.

Features

• std (enabled by default): Enables the std library. This is required for the global generator and global entropy. Without this feature, Rng can only be instantiated using the with_seed method.
• js: Assumes that WebAssembly targets are being run in a JavaScript environment. See the WebAssembly Notes section for more information.

WebAssembly Notes

For non-WASI WASM targets, there is additional sublety to consider when utilizing the global RNG. By default, std targets will use entropy sources in the standard library to seed the global RNG. However, these sources are not available by default on WASM targets outside of WASI.

If the js feature is enabled, this crate will assume that it is running in a JavaScript environment. At this point, the getrandom crate will be used in order to access the available entropy sources and seed the global RNG. If the js feature is not enabled, the global RNG will use a predefined seed.

Modules

• global_rng 🔒
  A global, thread-local random number generator.

Macros

• rng_integer 🔒

Structs

• Rng
  A random number generator.

Functions

• alphabetic
  Generates a random char in ranges a-z and A-Z.
• alphanumeric
  Generates a random char in ranges a-z, A-Z and 0-9.
• bool
  Generates a random bool.
• char
  Generates a random char in the given range.
• choice
  Choose an item from an iterator at random.
• choose_multiple
  Collects amount values at random from the iterator into a vector.
• digit
  Generates a random digit in the given base.
• f32
  Generates a random f32 in range 0..1.
• f64
  Generates a random f64 in range 0..1.
• get_seed
  Gives back current seed that is being held by the thread-local generator.
• i8
  Generates a random i8 in the given range.
• i16
  Generates a random i16 in the given range.
• i32
  Generates a random i32 in the given range.
• i64
  Generates a random i64 in the given range.
• i128
  Generates a random i128 in the given range.
• isize
  Generates a random isize in the given range.
• lowercase
  Generates a random char in range a-z.
• mul_high_u32 🔒
  Computes (a * b) >> 32.
• mul_high_u64 🔒
  Computes (a * b) >> 64.
• mul_high_u128 🔒
  Computes (a * b) >> 128.
• seed
  Initializes the thread-local generator with the given seed.
• shuffle
  Shuffles a slice randomly.
• u8
  Generates a random u8 in the given range.
• u16
  Generates a random u16 in the given range.
• u32
  Generates a random u32 in the given range.
• u64
  Generates a random u64 in the given range.
• u128
  Generates a random u128 in the given range.
• uppercase
  Generates a random char in range A-Z.
• usize
  Generates a random usize in the given range.