Debian Codegraph @

.cargo/vendor/rand/README.md

raw
1 # Rand
2
3 [![Test Status](https://github.com/rust-random/rand/actions/workflows/test.yml/badge.svg?event=push)](https://github.com/rust-random/rand/actions)
4 [![Crate](https://img.shields.io/crates/v/rand.svg)](https://crates.io/crates/rand)
5 [![Book](https://img.shields.io/badge/book-master-yellow.svg)](https://rust-random.github.io/book/)
6 [![API](https://img.shields.io/badge/api-master-yellow.svg)](https://rust-random.github.io/rand/rand)
7 [![API](https://docs.rs/rand/badge.svg)](https://docs.rs/rand)
8
9 Rand is a set of crates supporting (pseudo-)random generators:
10
11 - Built over a standard RNG trait: [`rand_core::RngCore`](https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html)
12 - With fast implementations of both [strong](https://rust-random.github.io/book/guide-rngs.html#cryptographically-secure-pseudo-random-number-generators-csprngs) and
13 [small](https://rust-random.github.io/book/guide-rngs.html#basic-pseudo-random-number-generators-prngs) generators: [`rand::rngs`](https://docs.rs/rand/latest/rand/rngs/index.html), and more RNGs: [`rand_chacha`](https://docs.rs/rand_chacha), [`rand_xoshiro`](https://docs.rs/rand_xoshiro/), [`rand_pcg`](https://docs.rs/rand_pcg/), [rngs repo](https://github.com/rust-random/rngs/)
14 - [`rand::rng`](https://docs.rs/rand/latest/rand/fn.rng.html) is an asymptotically-fast, automatically-seeded and reasonably strong generator available on all `std` targets
15 - Direct support for seeding generators from the [getrandom] crate
16
17 With broad support for random value generation and random processes:
18
19 - [`StandardUniform`](https://docs.rs/rand/latest/rand/distr/struct.StandardUniform.html) random value sampling,
20 [`Uniform`](https://docs.rs/rand/latest/rand/distr/struct.Uniform.html)-ranged value sampling
21 and [more](https://docs.rs/rand/latest/rand/distr/index.html)
22 - Samplers for a large number of non-uniform random number distributions via our own
23 [`rand_distr`](https://docs.rs/rand_distr) and via
24 the [`statrs`](https://docs.rs/statrs)
25 - Random processes (mostly choose and shuffle) via [`rand::seq`](https://docs.rs/rand/latest/rand/seq/index.html) traits
26
27 All with:
28
29 - [Portably reproducible output](https://rust-random.github.io/book/portability.html)
30 - `#[no_std]` compatibility (partial)
31 - *Many* performance optimisations thanks to contributions from the wide
32 user-base
33
34 Rand **is not**:
35
36 - Small (LoC). Most low-level crates are small, but the higher-level `rand`
37 and `rand_distr` each contain a lot of functionality.
38 - Simple (implementation). We have a strong focus on correctness, speed and flexibility, but
39 not simplicity. If you prefer a small-and-simple library, there are
40 alternatives including [fastrand](https://crates.io/crates/fastrand)
41 and [oorandom](https://crates.io/crates/oorandom).
42 - Primarily a cryptographic library. `rand` does provide some generators which
43 aim to support unpredictable value generation under certain constraints;
44 see [SECURITY.md](https://github.com/rust-random/rand/blob/master/SECURITY.md) for details.
45 Users are expected to determine for themselves
46 whether `rand`'s functionality meets their own security requirements.
47
48 Documentation:
49
50 - [The Rust Rand Book](https://rust-random.github.io/book)
51 - [API reference (master branch)](https://rust-random.github.io/rand)
52 - [API reference (docs.rs)](https://docs.rs/rand)
53
54
55 ## Versions
56
57 Rand is *mature* (suitable for general usage, with infrequent breaking releases
58 which minimise breakage) but not yet at 1.0. Current `MAJOR.MINOR` versions are:
59
60 - Version 0.9 was released in January 2025.
61
62 See the [CHANGELOG](https://github.com/rust-random/rand/blob/master/CHANGELOG.md) or [Upgrade Guide](https://rust-random.github.io/book/update.html) for more details.
63
64 ## Crate Features
65
66 Rand is built with these features enabled by default:
67
68 - `std` enables functionality dependent on the `std` lib
69 - `alloc` (implied by `std`) enables functionality requiring an allocator
70 - `os_rng` (implied by `std`) enables `rngs::OsRng`, using the [getrandom] crate
71 - `std_rng` enables inclusion of `StdRng`, `ThreadRng`
72 - `small_rng` enables inclusion of the `SmallRng` PRNG
73
74 Optionally, the following dependencies can be enabled:
75
76 - `log` enables logging via [log](https://crates.io/crates/log)
77
78 Additionally, these features configure Rand:
79
80 - `nightly` includes some additions requiring nightly Rust
81 - `simd_support` (experimental) enables sampling of SIMD values
82 (uniformly random SIMD integers and floats), requiring nightly Rust
83 - `unbiased` use unbiased sampling for algorithms supporting this option: Uniform distribution.
84
85 (By default, bias affecting no more than one in 2^48 samples is accepted.)
86
87 Note: enabling this option is expected to affect reproducibility of results.
88
89 Note that nightly features are not stable and therefore not all library and
90 compiler versions will be compatible. This is especially true of Rand's
91 experimental `simd_support` feature.
92
93 Rand supports limited functionality in `no_std` mode (enabled via
94 `default-features = false`). In this case, `OsRng` and `from_os_rng` are
95 unavailable (unless `os_rng` is enabled), large parts of `seq` are
96 unavailable (unless `alloc` is enabled), and `ThreadRng` is unavailable.
97
98 ## Portability and platform support
99
100 Many (but not all) algorithms are intended to have reproducible output. Read more in the book: [Portability](https://rust-random.github.io/book/portability.html).
101
102 The Rand library supports a variety of CPU architectures. Platform integration is outsourced to [getrandom].
103
104 ### WebAssembly support
105
106 The [WASI](https://github.com/WebAssembly/WASI/tree/main) and Emscripten
107 targets are directly supported. The `wasm32-unknown-unknown` target is not
108 *automatically* supported. To enable support for this target, refer to the
109 [`getrandom` documentation for WebAssembly](https://docs.rs/getrandom/latest/getrandom/#webassembly-support).
110 Alternatively, the `os_rng` feature may be disabled.
111
112 # License
113
114 Rand is distributed under the terms of both the MIT license and the
115 Apache License (Version 2.0).
116
117 See [LICENSE-APACHE](https://github.com/rust-random/rand/blob/master/LICENSE-APACHE) and [LICENSE-MIT](https://github.com/rust-random/rand/blob/master/LICENSE-MIT), and
118 [COPYRIGHT](https://github.com/rust-random/rand/blob/master/COPYRIGHT) for details.
119
120 [getrandom]: https://crates.io/crates/getrandom