yggdrasil/rand
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Revise crate doc for rand_pcg, rand_chacha (#1454)

Browse Source 
* Pub-reexport rand_core from rand_pcg
* Add getrandom feature to rand_pcg, rand_chacha
This commit is contained in:
Diggory Hardy 2024-05-23 07:21:07 +01:00 committed by GitHub
parent 10a1fa4d22
commit defeb0cea3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 127 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
rand_chacha/Cargo.toml
View File

@ -16,6 +16,7 @@ edition = "2021"
rust-version = "1.61"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--generate-link-to-definition"]
[dependencies]
@ -26,9 +27,10 @@ serde = { version = "1.0", features = ["derive"], optional = true }
[dev-dependencies]
# Only to test serde1
serde_json = "1.0"
rand_core = { path = "../rand_core", version = "=0.9.0-alpha.1", features = ["getrandom"] }
[features]
default = ["std"]
getrandom = ["rand_core/getrandom"]
std = ["ppv-lite86/std", "rand_core/std"]
simd = [] # deprecated
serde1 = ["serde"]

71
rand_chacha/src/lib.rs
View File

@ -6,7 +6,76 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! The ChaCha random number generator.
//! The ChaCha random number generators.
//!
//! These are native Rust implementations of RNGs derived from the
//! [ChaCha stream ciphers] by D J Bernstein.
//!
//! ## Generators
//!
//! This crate provides 8-, 12- and 20-round variants of generators via a "core"
//! implementation (of [`BlockRngCore`]), each with an associated "RNG" type
//! (implementing [`RngCore`]).
//!
//! These generators are all deterministic and portable (see [Reproducibility]
//! in the book), with testing against reference vectors.
//!
//! ## Cryptographic (secure) usage
//!
//! Where secure unpredictable generators are required, it is suggested to use
//! [`ChaCha12Rng`] or [`ChaCha20Rng`] and to seed via
//! [`SeedableRng::from_os_rng`].
//!
//! See also the [Security] chapter in the rand book. The crate is provided
//! "as is", without any form of guarantee, and without a security audit.
//!
//! ## Seeding (construction)
//!
//! Generators implement the [`SeedableRng`] trait. Any method may be used,
//! but note that `seed_from_u64` is not suitable for usage where security is
//! important. Some suggestions:
//!
//! 1. With a fresh seed, **direct from the OS** (implies a syscall):
//! ```
//! # use {rand_core::SeedableRng, rand_chacha::ChaCha12Rng};
//! let rng = ChaCha12Rng::from_os_rng();
//! # let _: ChaCha12Rng = rng;
//! ```
//! 2. **From a master generator.** This could be [`rand::thread_rng`]
//! (effectively a fresh seed without the need for a syscall on each usage)
//! or a deterministic generator such as [`ChaCha20Rng`].
//! Beware that should a weak master generator be used, correlations may be
//! detectable between the outputs of its child generators.
//!
//! See also [Seeding RNGs] in the book.
//!
//! ## Generation
//!
//! Generators implement [`RngCore`], whose methods may be used directly to
//! generate unbounded integer or byte values.
//! ```
//! use rand_core::{SeedableRng, RngCore};
//! use rand_chacha::ChaCha12Rng;
//!
//! let mut rng = ChaCha12Rng::from_seed(Default::default());
//! let x = rng.next_u64();
//! assert_eq!(x, 0x53f955076a9af49b);
//! ```
//!
//! It is often more convenient to use the [`rand::Rng`] trait, which provides
//! further functionality. See also the [Random Values] chapter in the book.
//!
//! [ChaCha stream ciphers]: https://cr.yp.to/chacha.html
//! [Reproducibility]: https://rust-random.github.io/book/crate-reprod.html
//! [Seeding RNGs]: https://rust-random.github.io/book/guide-seeding.html
//! [Security]: https://rust-random.github.io/book/guide-rngs.html#security
//! [Random Values]: https://rust-random.github.io/book/guide-values.html
//! [`BlockRngCore`]: rand_core::block::BlockRngCore
//! [`RngCore`]: rand_core::RngCore
//! [`SeedableRng`]: rand_core::SeedableRng
//! [`SeedableRng::from_os_rng`]: rand_core::SeedableRng::from_os_rng
//! [`rand::thread_rng`]: https://docs.rs/rand/latest/rand/fn.thread_rng.html
//! [`rand::Rng`]: https://docs.rs/rand/latest/rand/trait.Rng.html
#![doc(
html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",

3
rand_pcg/Cargo.toml
View File

@ -16,10 +16,12 @@ edition = "2021"
rust-version = "1.61"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--generate-link-to-definition"]
[features]
serde1 = ["serde"]
getrandom = ["rand_core/getrandom"]
[dependencies]
rand_core = { path = "../rand_core", version = "=0.9.0-alpha.1" }
@ -30,3 +32,4 @@ serde = { version = "1", features = ["derive"], optional = true }
# deps yet, see: https://github.com/rust-lang/cargo/issues/1596
# Versions prior to 1.1.4 had incorrect minimal dependencies.
bincode = { version = "1.1.4" }
rand_core = { path = "../rand_core", version = "=0.9.0-alpha.1", features = ["getrandom"] }

70
rand_pcg/src/lib.rs
View File

@ -8,48 +8,78 @@
//! The PCG random number generators.
//!
//! This is a native Rust implementation of a small selection of PCG generators.
//! This is a native Rust implementation of a small selection of [PCG generators].
//! The primary goal of this crate is simple, minimal, well-tested code; in
//! other words it is explicitly not a goal to re-implement all of PCG.
//!
//! ## Generators
//!
//! This crate provides:
//!
//! - `Pcg32` aka `Lcg64Xsh32`, officially known as `pcg32`, a general
//! - [`Pcg32`] aka [`Lcg64Xsh32`], officially known as `pcg32`, a general
//! purpose RNG. This is a good choice on both 32-bit and 64-bit CPUs
//! (for 32-bit output).
//! - `Pcg64` aka `Lcg128Xsl64`, officially known as `pcg64`, a general
//! - [`Pcg64`] aka [`Lcg128Xsl64`], officially known as `pcg64`, a general
//! purpose RNG. This is a good choice on 64-bit CPUs.
//! - `Pcg64Mcg` aka `Mcg128Xsl64`, officially known as `pcg64_fast`,
//! - [`Pcg64Mcg`] aka [`Mcg128Xsl64`], officially known as `pcg64_fast`,
//! a general purpose RNG using 128-bit multiplications. This has poor
//! performance on 32-bit CPUs but is a good choice on 64-bit CPUs for
//! both 32-bit and 64-bit output.
//!
//! Both of these use 16 bytes of state and 128-bit seeds, and are considered
//! value-stable (i.e. any change affecting the output given a fixed seed would
//! be considered a breaking change to the crate).
//! These generators are all deterministic and portable (see [Reproducibility]
//! in the book), with testing against reference vectors.
//!
//! # Example
//! ## Seeding (construction)
//!
//! To initialize a generator, use the [`SeedableRng`][rand_core::SeedableRng] trait:
//! Generators implement the [`SeedableRng`] trait. All methods are suitable for
//! seeding. Some suggestions:
//!
//! 1. Seed **from an integer** via `seed_from_u64`. This uses a hash function
//! internally to yield a (typically) good seed from any input.
//! ```
//! # use {rand_core::SeedableRng, rand_pcg::Pcg64Mcg};
//! let rng = Pcg64Mcg::seed_from_u64(1);
//! # let _: Pcg64Mcg = rng;
//! ```
//! 2. With a fresh seed, **direct from the OS** (implies a syscall):
//! ```
//! # use {rand_core::SeedableRng, rand_pcg::Pcg64Mcg};
//! let rng = Pcg64Mcg::from_os_rng();
//! # let _: Pcg64Mcg = rng;
//! ```
//! 3. **From a master generator.** This could be [`rand::thread_rng`]
//! (effectively a fresh seed without the need for a syscall on each usage)
//! or a deterministic generator such as [`rand_chacha::ChaCha8Rng`].
//! Beware that should a weak master generator be used, correlations may be
//! detectable between the outputs of its child generators.
//!
//! See also [Seeding RNGs] in the book.
//!
//! ## Generation
//!
//! Generators implement [`RngCore`], whose methods may be used directly to
//! generate unbounded integer or byte values.
//! ```
//! use rand_core::{SeedableRng, RngCore};
//! use rand_pcg::Pcg64Mcg;
//!
//! let mut rng = Pcg64Mcg::seed_from_u64(0);
//! let x: u32 = rng.next_u32();
//! let x = rng.next_u64();
//! assert_eq!(x, 0x5603f242407deca2);
//! ```
//!
//! The functionality of this crate is implemented using traits from the `rand_core` crate, but you may use the `rand`
//! crate for further functionality to initialize the generator from various sources and to generate random values:
//! It is often more convenient to use the [`rand::Rng`] trait, which provides
//! further functionality. See also the [Random Values] chapter in the book.
//!
//! ```ignore
//! use rand::{Rng, SeedableRng};
//! use rand_pcg::Pcg64Mcg;
//!
//! let mut rng = Pcg64Mcg::from_os_rng();
//! let x: f64 = rng.gen();
//! ```
//! [PCG generators]: https://www.pcg-random.org/
//! [Reproducibility]: https://rust-random.github.io/book/crate-reprod.html
//! [Seeding RNGs]: https://rust-random.github.io/book/guide-seeding.html
//! [Random Values]: https://rust-random.github.io/book/guide-values.html
//! [`RngCore`]: rand_core::RngCore
//! [`SeedableRng`]: rand_core::SeedableRng
//! [`rand::thread_rng`]: https://docs.rs/rand/latest/rand/fn.thread_rng.html
//! [`rand::Rng`]: https://docs.rs/rand/latest/rand/trait.Rng.html
//! [`rand_chacha::ChaCha8Rng`]: https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha8Rng.html
#![doc(
html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
@ -65,6 +95,8 @@ mod pcg128;
mod pcg128cm;
mod pcg64;
pub use rand_core;
pub use self::pcg128::{Lcg128Xsl64, Mcg128Xsl64, Pcg64, Pcg64Mcg};
pub use self::pcg128cm::{Lcg128CmDxsm64, Pcg64Dxsm};
pub use self::pcg64::{Lcg64Xsh32, Pcg32};