rand_pcg/lib.rs
1// Copyright 2018-2023 Developers of the Rand project.
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9//! The PCG random number generators.
10//!
11//! This is a native Rust implementation of a small selection of [PCG generators].
12//! The primary goal of this crate is simple, minimal, well-tested code; in
13//! other words it is explicitly not a goal to re-implement all of PCG.
14//!
15//! ## Generators
16//!
17//! This crate provides:
18//!
19//! - [`Pcg32`] aka [`Lcg64Xsh32`], officially known as `pcg32`, a general
20//! purpose RNG. This is a good choice on both 32-bit and 64-bit CPUs
21//! (for 32-bit output).
22//! - [`Pcg64`] aka [`Lcg128Xsl64`], officially known as `pcg64`, a general
23//! purpose RNG. This is a good choice on 64-bit CPUs.
24//! - [`Pcg64Mcg`] aka [`Mcg128Xsl64`], officially known as `pcg64_fast`,
25//! a general purpose RNG using 128-bit multiplications. This has poor
26//! performance on 32-bit CPUs but is a good choice on 64-bit CPUs for
27//! both 32-bit and 64-bit output.
28//!
29//! These generators are all deterministic and portable (see [Reproducibility]
30//! in the book), with testing against reference vectors.
31//!
32//! ## Seeding (construction)
33//!
34//! Generators implement the [`SeedableRng`] trait. All methods are suitable for
35//! seeding. Some suggestions:
36//!
37//! 1. To automatically seed with a unique seed, use [`SeedableRng::from_rng`]
38//! with a master generator (here [`rand::rng()`](https://docs.rs/rand/latest/rand/fn.rng.html)):
39//! ```ignore
40//! use rand_core::SeedableRng;
41//! use rand_pcg::Pcg64Mcg;
42//! let rng = Pcg64Mcg::from_rng(&mut rand::rng());
43//! # let _: Pcg64Mcg = rng;
44//! ```
45//! 2. Seed **from an integer** via `seed_from_u64`. This uses a hash function
46//! internally to yield a (typically) good seed from any input.
47//! ```
48//! # use {rand_core::SeedableRng, rand_pcg::Pcg64Mcg};
49//! let rng = Pcg64Mcg::seed_from_u64(1);
50//! # let _: Pcg64Mcg = rng;
51//! ```
52//!
53//! See also [Seeding RNGs] in the book.
54//!
55//! ## Generation
56//!
57//! Generators implement [`RngCore`], whose methods may be used directly to
58//! generate unbounded integer or byte values.
59//! ```
60//! use rand_core::{SeedableRng, RngCore};
61//! use rand_pcg::Pcg64Mcg;
62//!
63//! let mut rng = Pcg64Mcg::seed_from_u64(0);
64//! let x = rng.next_u64();
65//! assert_eq!(x, 0x5603f242407deca2);
66//! ```
67//!
68//! It is often more convenient to use the [`rand::Rng`] trait, which provides
69//! further functionality. See also the [Random Values] chapter in the book.
70//!
71//! [PCG generators]: https://www.pcg-random.org/
72//! [Reproducibility]: https://rust-random.github.io/book/crate-reprod.html
73//! [Seeding RNGs]: https://rust-random.github.io/book/guide-seeding.html
74//! [Random Values]: https://rust-random.github.io/book/guide-values.html
75//! [`RngCore`]: rand_core::RngCore
76//! [`SeedableRng`]: rand_core::SeedableRng
77//! [`SeedableRng::from_rng`]: rand_core::SeedableRng#method.from_rng
78//! [`rand::rng`]: https://docs.rs/rand/latest/rand/fn.rng.html
79//! [`rand::Rng`]: https://docs.rs/rand/latest/rand/trait.Rng.html
80//! [`rand_chacha::ChaCha8Rng`]: https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha8Rng.html
81
82#![doc(
83 html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
84 html_favicon_url = "https://www.rust-lang.org/favicon.ico",
85 html_root_url = "https://rust-random.github.io/rand/"
86)]
87#![forbid(unsafe_code)]
88#![deny(missing_docs)]
89#![deny(missing_debug_implementations)]
90#![no_std]
91
92mod pcg128;
93mod pcg128cm;
94mod pcg64;
95
96pub use rand_core;
97
98pub use self::pcg128::{Lcg128Xsl64, Mcg128Xsl64, Pcg64, Pcg64Mcg};
99pub use self::pcg128cm::{Lcg128CmDxsm64, Pcg64Dxsm};
100pub use self::pcg64::{Lcg64Xsh32, Pcg32};