vendor/rand_core/README.md

   1 # rand_core
   2
   3 [![Build Status](https://travis-ci.org/rust-random/rand.svg)](https://travis-ci.org/rust-random/rand)
   4 [![Build Status](https://ci.appveyor.com/api/projects/status/github/rust-random/rand?svg=true)](https://ci.appveyor.com/project/rust-random/rand)
   5 [![Latest version](https://img.shields.io/crates/v/rand_core.svg)](https://crates.io/crates/rand_core)
   6 [![Book](https://img.shields.io/badge/book-master-yellow.svg)](https://rust-random.github.io/book/)
   7 [![API](https://img.shields.io/badge/api-master-yellow.svg)](https://rust-random.github.io/rand/rand_core)
   8 [![API](https://docs.rs/rand_core/badge.svg)](https://docs.rs/rand_core)
   9 [![Minimum rustc version](https://img.shields.io/badge/rustc-1.22+-lightgray.svg)](https://github.com/rust-random/rand#rust-version-requirements)
  10
  11 Core traits and error types of the [rand] library, plus tools for implementing
  12 RNGs.
  13
  14 This crate is intended for use when implementing the core trait, `RngCore`; it
  15 defines the core traits to be implemented as well as several small functions to
  16 aid in their implementation and types required for error handling.
  17
  18 The main [rand] crate re-exports most items defined in this crate, along with
  19 tools to convert the integer samples generated by `RngCore` to many different
  20 applications (including sampling from restricted ranges, conversion to floating
  21 point, list permutations and secure initialisation of RNGs). Most users should
  22 prefer to use the main [rand] crate.
  23
  24 Links:
  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](CHANGELOG.md)
  29
  30 [rand]: https://crates.io/crates/rand
  31
  32
  33 ## Functionality
  34
  35 The `rand_core` crate provides:
  36
  37 -   base random number generator traits
  38 -   error-reporting types
  39 -   functionality to aid implementation of RNGs
  40
  41 The traits and error types are also available via `rand`.
  42
  43 ## Crate Features
  44
  45 `rand_core` supports `no_std` and `alloc`-only configurations, as well as full
  46 `std` functionality. The differences between `no_std` and full `std` are small,
  47 comprising `RngCore` support for `Box<R>` types where `R: RngCore`,
  48 `std::io::Read` support for types supporting `RngCore`, and
  49 extensions to the `Error` type's functionality.
  50
  51 The `std` feature is *not enabled by default*. This is primarily to avoid build
  52 problems where one crate implicitly requires `rand_core` with `std` support and
  53 another crate requires `rand` *without* `std` support. However, the `rand` crate
  54 continues to enable `std` support by default, both for itself and `rand_core`.
  55
  56 The `serde1` feature can be used to derive `Serialize` and `Deserialize` for RNG
  57 implementations that use the `BlockRng` or `BlockRng64` wrappers.
  58
  59
  60 # License
  61
  62 `rand_core` is distributed under the terms of both the MIT license and the
  63 Apache License (Version 2.0).
  64
  65 See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
  66 [COPYRIGHT](COPYRIGHT) for details.