[rand_pcg v0.10.2] Add internal state fetching and construction (#108)

Author: kaathewisegit

Cargo.lock

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.10.2 - 2026-04-11
+### Changed
+- Add methods to get the internal state of the generators (`state` and
+  `stream` except for `Mcg128Xsl64`) and constructors to reproducibly
+  restore them from that state (#108).
+
 ## 0.10.1 - 2026-02-10
 ### Changed
 - The crate is moved from [`rust-random/rand`] to [`rust-random/rngs`].

rand_pcg/CHANGELOG.md

@@ -1,6 +1,6 @@
 [package]
 name = "rand_pcg"
-version = "0.10.1"
+version = "0.10.2"
 authors = ["The Rand Project Developers"]
 license = "MIT OR Apache-2.0"
 readme = "README.md"

rand_pcg/Cargo.toml

@@ -96,3 +96,42 @@ pub use rand_core;
 pub use self::pcg64::{Lcg64Xsh32, Pcg32};
 pub use self::pcg128::{Lcg128Xsl64, Mcg128Xsl64, Pcg64, Pcg64Mcg};
 pub use self::pcg128cm::{Lcg128CmDxsm64, Pcg64Dxsm};
+
+mod macros {
+    macro_rules! impl_state_stream {
+        ($type:ident, $int:ty) => {
+            impl $type {
+                /// Current state of the generator
+                pub fn state(&self) -> $int {
+                    self.state
+                }
+
+                /// Stream parameter of the generator
+                ///
+                /// Note that PCG only stores an increment, which is always odd.
+                /// [`Self::from_state`] discards the highest bit from the
+                /// stream by shifting it to the left, so this method shifts the
+                /// increment by one bit to the right.
+                pub fn stream(&self) -> $int {
+                    self.increment >> 1
+                }
+
+                /// Construct an instance using a pre-initialized `state`
+                ///
+                /// Unlike [`Self::new`], this method does not mutate `state`.
+                /// It may therefore be used with [`Self::state`] and
+                /// [`Self::stream`] to reconstruct an RNG.
+                ///
+                /// Note that the highest bit of the `stream` parameter is
+                /// discarded to simplify upholding internal invariants.
+                pub fn from_state(state: $int, stream: $int) -> Self {
+                    // The increment must be odd, hence we discard one bit:
+                    let increment = (stream << 1) | 1;
+                    $type { state, increment }
+                }
+            }
+        };
+    }
+
+    pub(crate) use impl_state_stream;
+}

rand_pcg/src/lib.rs

@@ -113,6 +113,8 @@ impl Lcg128Xsl64 {
     }
 }
 
+crate::macros::impl_state_stream!(Lcg128Xsl64, u128);
+
 // Custom Debug implementation that does not expose the internal state
 impl fmt::Debug for Lcg128Xsl64 {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
@@ -217,6 +219,13 @@ impl Mcg128Xsl64 {
         // Force low bit to 1, as in C version (C++ uses `state | 3` instead).
         Mcg128Xsl64 { state: state | 1 }
     }
+
+    /// Current state of the generator
+    ///
+    /// Will always be odd.
+    pub fn state(&self) -> u128 {
+        self.state
+    }
 }
 
 // Custom Debug implementation that does not expose the internal state

rand_pcg/src/pcg128.rs

@@ -118,6 +118,8 @@ impl Lcg128CmDxsm64 {
     }
 }
 
+crate::macros::impl_state_stream!(Lcg128CmDxsm64, u128);
+
 // Custom Debug implementation that does not expose the internal state
 impl fmt::Debug for Lcg128CmDxsm64 {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {

rand_pcg/src/pcg128cm.rs

@@ -114,6 +114,8 @@ impl Lcg64Xsh32 {
     }
 }
 
+crate::macros::impl_state_stream!(Lcg64Xsh32, u64);
+
 // Custom Debug implementation that does not expose the internal state
 impl fmt::Debug for Lcg64Xsh32 {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {

rand_pcg/src/pcg64.rs

@@ -54,6 +54,23 @@ fn test_lcg128cmdxsm64_reference() {
     assert_eq!(results, expected);
 }
 
+#[test]
+fn test_lcg128cmdxsm64_advancing_restore() {
+    let mut rng_orig = Lcg128CmDxsm64::new(1234, 567);
+
+    for _ in 0..100 {
+        rng_orig.next_u64();
+    }
+
+    let state = rng_orig.state();
+    let stream = rng_orig.stream();
+    let mut rng_copy = Lcg128CmDxsm64::from_state(state, stream);
+
+    for _ in 0..1_000 {
+        assert_eq!(rng_copy.next_u64(), rng_orig.next_u64());
+    }
+}
+
 #[cfg(feature = "serde")]
 #[test]
 fn test_lcg128cmdxsm64_serde() {

rand_pcg/tests/lcg128cmdxsm64.rs

@@ -54,6 +54,23 @@ fn test_lcg128xsl64_reference() {
     assert_eq!(results, expected);
 }
 
+#[test]
+fn test_lcg128xsl64_advancing_restore() {
+    let mut rng_orig = Lcg128Xsl64::new(1234, 567);
+
+    for _ in 0..100 {
+        rng_orig.next_u64();
+    }
+
+    let state = rng_orig.state();
+    let stream = rng_orig.stream();
+    let mut rng_copy = Lcg128Xsl64::from_state(state, stream);
+
+    for _ in 0..1_000 {
+        assert_eq!(rng_copy.next_u64(), rng_orig.next_u64());
+    }
+}
+
 #[cfg(feature = "serde")]
 #[test]
 fn test_lcg128xsl64_serde() {

rand_pcg/tests/lcg128xsl64.rs

@@ -47,6 +47,23 @@ fn test_lcg64xsh32_reference() {
     assert_eq!(results, expected);
 }
 
+#[test]
+fn test_lcg64xsh32_advancing_restore() {
+    let mut rng_orig = Lcg64Xsh32::new(1234, 567);
+
+    for _ in 0..100 {
+        rng_orig.next_u64();
+    }
+
+    let state = rng_orig.state();
+    let stream = rng_orig.stream();
+    let mut rng_copy = Lcg64Xsh32::from_state(state, stream);
+
+    for _ in 0..1_000 {
+        assert_eq!(rng_copy.next_u64(), rng_orig.next_u64());
+    }
+}
+
 #[cfg(feature = "serde")]
 #[test]
 fn test_lcg64xsh32_serde() {