oficina / docs Public

Download this file

1	# fastrand
2
3	[](
4	https://github.com/smol-rs/fastrand/actions)
5	[](
6	https://github.com/smol-rs/fastrand)
7	[](
8	https://crates.io/crates/fastrand)
9	[](
10	https://docs.rs/fastrand)
11
12	A simple and fast random number generator.
13
14	The implementation uses [Wyrand](https://github.com/wangyi-fudan/wyhash), a simple and fast
15	generator but **not** cryptographically secure.
16
17	## Examples
18
19	Flip a coin:
20
21	```rust
22	if fastrand::bool() {
23	println!("heads");
24	} else {
25	println!("tails");
26	}
27	```
28
29	Generate a random `i32`:
30
31	```rust
32	let num = fastrand::i32(..);
33	```
34
35	Choose a random element in an array:
36
37	```rust
38	let v = vec![1, 2, 3, 4, 5];
39	let i = fastrand::usize(..v.len());
40	let elem = v[i];
41	```
42
43	Sample values from an array with `O(n)` complexity (`n` is the length of the array):
44
45	```rust
46	fastrand::choose_multiple([1, 4, 5], 2);
47	fastrand::choose_multiple(0..20, 12);
48	```
49
50	Shuffle an array:
51
52	```rust
53	let mut v = vec![1, 2, 3, 4, 5];
54	fastrand::shuffle(&mut v);
55	```
56
57	Generate a random `Vec` or `String`:
58
59	```rust
60	use std::iter::repeat_with;
61
62	let v: Vec<i32> = repeat_with(|| fastrand::i32(..)).take(10).collect();
63	let s: String = repeat_with(fastrand::alphanumeric).take(10).collect();
64	```
65
66	To get reproducible results on every run, initialize the generator with a seed:
67
68	```rust
69	// Pick an arbitrary number as seed.
70	fastrand::seed(7);
71
72	// Now this prints the same number on every run:
73	println!("{}", fastrand::u32(..));
74	```
75
76	To be more efficient, create a new `Rng` instance instead of using the thread-local
77	generator:
78
79	```rust
80	use std::iter::repeat_with;
81
82	let mut rng = fastrand::Rng::new();
83	let mut bytes: Vec<u8> = repeat_with(|| rng.u8(..)).take(10_000).collect();
84	```
85
86	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.
87
88	# Features
89
90	- `std` (enabled by default): Enables the `std` library. This is required for the global
91	generator and global entropy. Without this feature, [`Rng`] can only be instantiated using
92	the [`with_seed`](https://docs.rs/fastrand/latest/fastrand/struct.Rng.html#method.with_seed) method.
93	- `js`: Assumes that WebAssembly targets are being run in a JavaScript environment.
94
95	[`fastrand-contrib`]: https://crates.io/crates/fastrand-contrib
96
97	## License
98
99	Licensed under either of
100
101	* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
102	* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/license/mit)
103
104	at your option.
105
106	#### Contribution
107
108	Unless you explicitly state otherwise, any contribution intentionally submitted
109	for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
110	dual licensed as above, without any additional terms or conditions.
111