diff --git a/CHANGELOG.md b/CHANGELOG.md index 44603eeb537..5936d88bccd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,7 @@ You may also find the [Upgrade Guide](https://rust-random.github.io/book/update. - Rename `Rng::gen_range` to `random_range`, `gen_bool` to `random_bool`, `gen_ratio` to `random_ratio` (#1505) - Rename `Standard` to `StandardUniform` (#1526) - Remove impl of `Distribution>` for `Standard` (#1526) +- Rename `SmallRng::from_thread_rng` to `from_rand_rng` (#1531) ## [0.9.0-alpha.1] - 2024-03-18 - Add the `Slice::num_choices` method to the Slice distribution (#1402) diff --git a/benches/benches/generators.rs b/benches/benches/generators.rs index 95361cd203f..f003d513bb6 100644 --- a/benches/benches/generators.rs +++ b/benches/benches/generators.rs @@ -48,7 +48,7 @@ pub fn random_bytes(c: &mut Criterion) { bench(&mut g, "chacha12", ChaCha12Rng::from_os_rng()); bench(&mut g, "chacha20", ChaCha20Rng::from_os_rng()); bench(&mut g, "std", StdRng::from_os_rng()); - bench(&mut g, "small", SmallRng::from_thread_rng()); + bench(&mut g, "small", SmallRng::from_rand_rng()); bench(&mut g, "os", UnwrapErr(OsRng)); bench(&mut g, "thread", rand::rng()); @@ -77,7 +77,7 @@ pub fn random_u32(c: &mut Criterion) { bench(&mut g, "chacha12", ChaCha12Rng::from_os_rng()); bench(&mut g, "chacha20", ChaCha20Rng::from_os_rng()); bench(&mut g, "std", StdRng::from_os_rng()); - bench(&mut g, "small", SmallRng::from_thread_rng()); + bench(&mut g, "small", SmallRng::from_rand_rng()); bench(&mut g, "os", UnwrapErr(OsRng)); bench(&mut g, "thread", rand::rng()); @@ -106,7 +106,7 @@ pub fn random_u64(c: &mut Criterion) { bench(&mut g, "chacha12", ChaCha12Rng::from_os_rng()); bench(&mut g, "chacha20", ChaCha20Rng::from_os_rng()); bench(&mut g, "std", StdRng::from_os_rng()); - bench(&mut g, "small", SmallRng::from_thread_rng()); + bench(&mut g, "small", SmallRng::from_rand_rng()); bench(&mut g, "os", UnwrapErr(OsRng)); bench(&mut g, "thread", rand::rng()); diff --git a/src/rngs/small.rs b/src/rngs/small.rs index 1f9e7f5b8c9..4b31967b690 100644 --- a/src/rngs/small.rs +++ b/src/rngs/small.rs @@ -40,24 +40,20 @@ type Rng = super::xoshiro256plusplus::Xoshiro256PlusPlus; /// suitable for seeding, but note that, even with a fixed seed, output is not /// [portable]. 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. +/// 1. To automatically seed with a unique seed, use [`SmallRng::from_rand_rng`]: /// ``` -/// # use rand::{SeedableRng, rngs::SmallRng}; -/// let rng = SmallRng::seed_from_u64(1); -/// # let _: SmallRng = rng; +/// # use rand::rngs::SmallRng; +/// let rng = SmallRng::from_rand_rng(); /// ``` -/// 2. With a fresh seed, **direct from the OS** (implies a syscall): +/// 2. To use a deterministic integral seed, use `seed_from_u64`. This uses a +/// hash function internally to yield a (typically) good seed from any +/// input. /// ``` /// # use rand::{SeedableRng, rngs::SmallRng}; -/// let rng = SmallRng::from_os_rng(); +/// let rng = SmallRng::seed_from_u64(1); /// # let _: SmallRng = rng; /// ``` -/// 3. Via [`SmallRng::from_thread_rng`]: -/// ``` -/// # use rand::rngs::SmallRng; -/// let rng = SmallRng::from_thread_rng(); -/// ``` +/// 3. To seed deterministically from text or other input, use [`rand_seeder`]. /// /// See also [Seeding RNGs] in the book. /// @@ -74,6 +70,7 @@ type Rng = super::xoshiro256plusplus::Xoshiro256PlusPlus; /// [rand_pcg]: https://crates.io/crates/rand_pcg /// [rand_xoshiro]: https://crates.io/crates/rand_xoshiro /// [`rand_chacha::ChaCha8Rng`]: https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha8Rng.html +/// [`rand_seeder`]: https://docs.rs/rand_seeder/latest/rand_seeder/ #[derive(Clone, Debug, PartialEq, Eq)] pub struct SmallRng(Rng); @@ -114,15 +111,16 @@ impl RngCore for SmallRng { } impl SmallRng { - /// Construct an instance seeded from `rand::rng` + /// Construct an instance seeded from [`rand::rng`] /// /// # Panics /// - /// This method panics only if [`crate::rng()`] fails to - /// initialize. + /// This method panics only if [`rand::rng`] fails to initialize. + /// + /// [`rand::rng`]: crate::rng() #[cfg(all(feature = "std", feature = "std_rng", feature = "getrandom"))] #[inline(always)] - pub fn from_thread_rng() -> Self { + pub fn from_rand_rng() -> Self { let mut seed = ::Seed::default(); crate::rng().fill_bytes(seed.as_mut()); SmallRng(Rng::from_seed(seed))