summaryrefslogtreecommitdiffstats
path: root/third_party/rust/rand_core/README.md
blob: d32dd6853d0433c4b20e272b5fcd1fd0e9071ba2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# rand_core

[![Test Status](https://github.com/rust-random/rand/workflows/Tests/badge.svg?event=push)](https://github.com/rust-random/rand/actions)
[![Latest version](https://img.shields.io/crates/v/rand_core.svg)](https://crates.io/crates/rand_core)
[![Book](https://img.shields.io/badge/book-master-yellow.svg)](https://rust-random.github.io/book/)
[![API](https://img.shields.io/badge/api-master-yellow.svg)](https://rust-random.github.io/rand/rand_core)
[![API](https://docs.rs/rand_core/badge.svg)](https://docs.rs/rand_core)
[![Minimum rustc version](https://img.shields.io/badge/rustc-1.36+-lightgray.svg)](https://github.com/rust-random/rand#rust-version-requirements)

Core traits and error types of the [rand] library, plus tools for implementing
RNGs.

This crate is intended for use when implementing the core trait, `RngCore`; it
defines the core traits to be implemented as well as several small functions to
aid in their implementation and types required for error handling.

The main [rand] crate re-exports most items defined in this crate, along with
tools to convert the integer samples generated by `RngCore` to many different
applications (including sampling from restricted ranges, conversion to floating
point, list permutations and secure initialisation of RNGs). Most users should
prefer to use the main [rand] crate.

Links:

-   [API documentation (master)](https://rust-random.github.io/rand/rand_core)
-   [API documentation (docs.rs)](https://docs.rs/rand_core)
-   [Changelog](https://github.com/rust-random/rand/blob/master/rand_core/CHANGELOG.md)

[rand]: https://crates.io/crates/rand


## Functionality

The `rand_core` crate provides:

-   base random number generator traits
-   error-reporting types
-   functionality to aid implementation of RNGs

The traits and error types are also available via `rand`.

## Versions

The current version is:
```
rand_core = "0.6.0"
```

Rand libs have inter-dependencies and make use of the
[semver trick](https://github.com/dtolnay/semver-trick/) in order to make traits
compatible across crate versions. (This is especially important for `RngCore`
and `SeedableRng`.) A few crate releases are thus compatibility shims,
depending on the *next* lib version (e.g. `rand_core` versions `0.2.2` and
`0.3.1`). This means, for example, that `rand_core_0_4_0::SeedableRng` and
`rand_core_0_3_0::SeedableRng` are distinct, incompatible traits, which can
cause build errors. Usually, running `cargo update` is enough to fix any issues.

## Crate Features

`rand_core` supports `no_std` and `alloc`-only configurations, as well as full
`std` functionality. The differences between `no_std` and full `std` are small,
comprising `RngCore` support for `Box<R>` types where `R: RngCore`,
`std::io::Read` support for types supporting `RngCore`, and
extensions to the `Error` type's functionality.

The `std` feature is *not enabled by default*. This is primarily to avoid build
problems where one crate implicitly requires `rand_core` with `std` support and
another crate requires `rand` *without* `std` support. However, the `rand` crate
continues to enable `std` support by default, both for itself and `rand_core`.

The `serde1` feature can be used to derive `Serialize` and `Deserialize` for RNG
implementations that use the `BlockRng` or `BlockRng64` wrappers.


# License

`rand_core` is distributed under the terms of both the MIT license and the
Apache License (Version 2.0).

See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
[COPYRIGHT](COPYRIGHT) for details.