Expand description
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 thestd
library. This is required for the global generator and global entropy. Without this feature,Rng
can only be instantiated using thewith_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.
Structs§
- A random number generator.
Functions§
- Generates a random
char
in ranges a-z and A-Z. - Generates a random
char
in ranges a-z, A-Z and 0-9. - Generates a random
bool
. - Generates a random
char
in the given range. - Choose an item from an iterator at random.
- Collects
amount
values at random from the iterator into a vector. - Generates a random digit in the given
base
. - Generates a random
f32
in range0..1
. - Generates a random
f64
in range0..1
. - Gives back current seed that is being held by the thread-local generator.
- Generates a random
i8
in the given range. - Generates a random
i16
in the given range. - Generates a random
i32
in the given range. - Generates a random
i64
in the given range. - Generates a random
i128
in the given range. - Generates a random
isize
in the given range. - Generates a random
char
in range a-z. - Initializes the thread-local generator with the given seed.
- Shuffles a slice randomly.
- Generates a random
u8
in the given range. - Generates a random
u16
in the given range. - Generates a random
u32
in the given range. - Generates a random
u64
in the given range. - Generates a random
u128
in the given range. - Generates a random
char
in range A-Z. - Generates a random
usize
in the given range.