README.md
1# rand_core
2
3[](https://travis-ci.org/rust-random/rand)
4[](https://ci.appveyor.com/project/rust-random/rand)
5[](https://crates.io/crates/rand_core)
6[](https://rust-random.github.io/book/)
7[](https://rust-random.github.io/rand/rand_core)
8[](https://docs.rs/rand_core)
9[](https://github.com/rust-random/rand#rust-version-requirements)
10
11Core traits and error types of the [rand] library, plus tools for implementing
12RNGs.
13
14This crate is intended for use when implementing the core trait, `RngCore`; it
15defines the core traits to be implemented as well as several small functions to
16aid in their implementation and types required for error handling.
17
18The main [rand] crate re-exports most items defined in this crate, along with
19tools to convert the integer samples generated by `RngCore` to many different
20applications (including sampling from restricted ranges, conversion to floating
21point, list permutations and secure initialisation of RNGs). Most users should
22prefer to use the main [rand] crate.
23
24Links:
25
26- [API documentation (master)](https://rust-random.github.io/rand/rand_core)
27- [API documentation (docs.rs)](https://docs.rs/rand_core)
28- [Changelog](https://github.com/rust-random/rand/blob/master/rand_core/CHANGELOG.md)
29
30[rand]: https://crates.io/crates/rand
31
32
33## Functionality
34
35The `rand_core` crate provides:
36
37- base random number generator traits
38- error-reporting types
39- functionality to aid implementation of RNGs
40
41The traits and error types are also available via `rand`.
42
43## Versions
44
45The current version is:
46```
47rand_core = "0.5.0"
48```
49
50Rand libs have inter-dependencies and make use of the
51[semver trick](https://github.com/dtolnay/semver-trick/) in order to make traits
52compatible across crate versions. (This is especially important for `RngCore`
53and `SeedableRng`.) A few crate releases are thus compatibility shims,
54depending on the *next* lib version (e.g. `rand_core` versions `0.2.2` and
55`0.3.1`). This means, for example, that `rand_core_0_4_0::SeedableRng` and
56`rand_core_0_3_0::SeedableRng` are distinct, incompatible traits, which can
57cause build errors. Usually, running `cargo update` is enough to fix any issues.
58
59## Crate Features
60
61`rand_core` supports `no_std` and `alloc`-only configurations, as well as full
62`std` functionality. The differences between `no_std` and full `std` are small,
63comprising `RngCore` support for `Box<R>` types where `R: RngCore`,
64`std::io::Read` support for types supporting `RngCore`, and
65extensions to the `Error` type's functionality.
66
67The `std` feature is *not enabled by default*. This is primarily to avoid build
68problems where one crate implicitly requires `rand_core` with `std` support and
69another crate requires `rand` *without* `std` support. However, the `rand` crate
70continues to enable `std` support by default, both for itself and `rand_core`.
71
72The `serde1` feature can be used to derive `Serialize` and `Deserialize` for RNG
73implementations that use the `BlockRng` or `BlockRng64` wrappers.
74
75
76# License
77
78`rand_core` is distributed under the terms of both the MIT license and the
79Apache License (Version 2.0).
80
81See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
82[COPYRIGHT](COPYRIGHT) for details.
83
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}