Merge pull request #110 from rust-random/export-xoshiro-state

rand_xoshiro: Add `state()` for serde-free state export

Author: vks

Cargo.lock

@@ -4,11 +4,18 @@ 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).
 
-## [Unreleased]
+## [0.8.1] - 2026-05-16
+### Added
+- `state()` method on every RNG type returning the internal state as a value
+  matching `SeedableRng::Seed`, allowing reproduction via `from_seed` without
+  the `serde` feature ([#110]).
+
 ### Changed
 - Shrink the code size of the all-zero-seed fallback by replacing the per-RNG
   `SplitMix64::seed_from_u64(0)` call with a single shared constant.
 
+[#110]: https://github.com/rust-random/rngs/pull/110
+
 ## [0.8.0] - 2026-02-01
 ### Changes
 - Use Edition 2024 and MSRV 1.85 ([#73])

rand_xoshiro/CHANGELOG.md

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

rand_xoshiro/Cargo.toml

@@ -222,6 +222,89 @@ macro_rules! impl_xoshiro_large {
     };
 }
 
+/// Implement `state` for an RNG with two word-sized fields `s0` and `s1`.
+macro_rules! impl_state_pair {
+    ($type:ident, $word:ty) => {
+        impl $type {
+            /// Return the internal state of the generator as little-endian
+            /// bytes that can be passed to [`SeedableRng::from_seed`] to
+            /// reconstruct an identical generator.
+            ///
+            /// The all-zero state is unreachable from any non-zero seed, so
+            /// the round-trip is exact for any generator obtained via the
+            /// usual constructors. (An all-zero input to `from_seed` is
+            /// remapped to `seed_from_u64(0)`.)
+            ///
+            /// [`SeedableRng::from_seed`]: rand_core::SeedableRng::from_seed
+            pub fn state(&self) -> [u8; 2 * core::mem::size_of::<$word>()] {
+                const N: usize = core::mem::size_of::<$word>();
+                const {
+                    assert!(core::mem::size_of::<Self>() == 2 * N);
+                }
+                let mut out = [0u8; 2 * N];
+                out[..N].copy_from_slice(&self.s0.to_le_bytes());
+                out[N..].copy_from_slice(&self.s1.to_le_bytes());
+                out
+            }
+        }
+    };
+}
+
+/// Implement `state` for an RNG with an `s: [WORD; 4]` field.
+macro_rules! impl_state_array_of_four {
+    ($type:ident, $word:ty) => {
+        impl $type {
+            /// Return the internal state of the generator as little-endian
+            /// bytes that can be passed to [`SeedableRng::from_seed`] to
+            /// reconstruct an identical generator.
+            ///
+            /// The all-zero state is unreachable from any non-zero seed, so
+            /// the round-trip is exact for any generator obtained via the
+            /// usual constructors. (An all-zero input to `from_seed` is
+            /// remapped to `seed_from_u64(0)`.)
+            ///
+            /// [`SeedableRng::from_seed`]: rand_core::SeedableRng::from_seed
+            pub fn state(&self) -> [u8; 4 * core::mem::size_of::<$word>()] {
+                const N: usize = core::mem::size_of::<$word>();
+                const {
+                    assert!(core::mem::size_of::<Self>() == 4 * N);
+                }
+                let mut out = [0u8; 4 * N];
+                out[..N].copy_from_slice(&self.s[0].to_le_bytes());
+                out[N..2 * N].copy_from_slice(&self.s[1].to_le_bytes());
+                out[2 * N..3 * N].copy_from_slice(&self.s[2].to_le_bytes());
+                out[3 * N..].copy_from_slice(&self.s[3].to_le_bytes());
+                out
+            }
+        }
+    };
+}
+
+/// Implement `state` for a 512-bit RNG (`s: [u64; 8]`), returning a [`Seed512`].
+macro_rules! impl_state_seed512 {
+    ($type:ident) => {
+        impl $type {
+            /// Return the internal state of the generator as a [`Seed512`]
+            /// that can be passed to [`SeedableRng::from_seed`] to reconstruct
+            /// an identical generator.
+            ///
+            /// The all-zero state is unreachable from any non-zero seed, so
+            /// the round-trip is exact for any generator obtained via the
+            /// usual constructors. (An all-zero input to `from_seed` is
+            /// remapped to `seed_from_u64(0)`.)
+            ///
+            /// [`SeedableRng::from_seed`]: rand_core::SeedableRng::from_seed
+            pub fn state(&self) -> crate::Seed512 {
+                let mut out = [0u8; 64];
+                for (i, word) in self.s.iter().enumerate() {
+                    out[i * 8..(i + 1) * 8].copy_from_slice(&word.to_le_bytes());
+                }
+                crate::Seed512(out)
+            }
+        }
+    };
+}
+
 /// Fallback seed used when `from_seed` is called with an all-zero input.
 ///
 /// Equal to the first 64 bytes of `SplitMix64::seed_from_u64(0)`'s output.

rand_xoshiro/src/common.rs

@@ -60,6 +60,17 @@ impl TryRng for SplitMix64 {
     }
 }
 
+impl SplitMix64 {
+    /// Return the internal state of the generator as little-endian bytes
+    /// that can be passed to [`SeedableRng::from_seed`] to reconstruct an
+    /// identical generator.
+    ///
+    /// [`SeedableRng::from_seed`]: rand_core::SeedableRng::from_seed
+    pub fn state(&self) -> [u8; 8] {
+        self.x.to_le_bytes()
+    }
+}
+
 impl SeedableRng for SplitMix64 {
     type Seed = [u8; 8];
 
@@ -142,6 +153,13 @@ mod tests {
         }
     }
 
+    #[test]
+    fn state_roundtrip() {
+        let rng = SplitMix64::seed_from_u64(42);
+        let clone = SplitMix64::from_seed(rng.state());
+        assert_eq!(clone, rng);
+    }
+
     #[test]
     fn next_u32() {
         let mut rng = SplitMix64::seed_from_u64(10);

rand_xoshiro/src/splitmix64.rs

@@ -80,6 +80,8 @@ impl TryRng for Xoroshiro128Plus {
         utils::fill_bytes_via_next_word(dest, || self.try_next_u64())
     }
 }
+impl_state_pair!(Xoroshiro128Plus, u64);
+
 impl SeedableRng for Xoroshiro128Plus {
     type Seed = [u8; 16];
 
@@ -129,4 +131,11 @@ mod tests {
         let from_sm0 = Xoroshiro128Plus::seed_from_u64(0);
         assert_eq!(from_zero, from_sm0);
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let rng = Xoroshiro128Plus::seed_from_u64(42);
+        let clone = Xoroshiro128Plus::from_seed(rng.state());
+        assert_eq!(clone, rng);
+    }
 }

rand_xoshiro/src/xoroshiro128plus.rs

@@ -78,6 +78,8 @@ impl TryRng for Xoroshiro128PlusPlus {
     }
 }
 
+impl_state_pair!(Xoroshiro128PlusPlus, u64);
+
 impl SeedableRng for Xoroshiro128PlusPlus {
     type Seed = [u8; 16];
 
@@ -128,4 +130,11 @@ mod tests {
         let from_sm0 = Xoroshiro128PlusPlus::seed_from_u64(0);
         assert_eq!(from_zero, from_sm0);
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let rng = Xoroshiro128PlusPlus::seed_from_u64(42);
+        let clone = Xoroshiro128PlusPlus::from_seed(rng.state());
+        assert_eq!(clone, rng);
+    }
 }

rand_xoshiro/src/xoroshiro128plusplus.rs

@@ -78,6 +78,8 @@ impl TryRng for Xoroshiro128StarStar {
     }
 }
 
+impl_state_pair!(Xoroshiro128StarStar, u64);
+
 impl SeedableRng for Xoroshiro128StarStar {
     type Seed = [u8; 16];
 
@@ -128,4 +130,11 @@ mod tests {
         let from_sm0 = Xoroshiro128StarStar::seed_from_u64(0);
         assert_eq!(from_zero, from_sm0);
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let rng = Xoroshiro128StarStar::seed_from_u64(42);
+        let clone = Xoroshiro128StarStar::from_seed(rng.state());
+        assert_eq!(clone, rng);
+    }
 }

rand_xoshiro/src/xoroshiro128starstar.rs

@@ -49,6 +49,8 @@ impl TryRng for Xoroshiro64Star {
     }
 }
 
+impl_state_pair!(Xoroshiro64Star, u32);
+
 impl SeedableRng for Xoroshiro64Star {
     type Seed = [u8; 8];
 
@@ -97,4 +99,11 @@ mod tests {
         let from_sm0 = Xoroshiro64Star::seed_from_u64(0);
         assert_eq!(from_zero, from_sm0);
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let rng = Xoroshiro64Star::seed_from_u64(42);
+        let clone = Xoroshiro64Star::from_seed(rng.state());
+        assert_eq!(clone, rng);
+    }
 }

rand_xoshiro/src/xoroshiro64star.rs

@@ -48,6 +48,8 @@ impl TryRng for Xoroshiro64StarStar {
     }
 }
 
+impl_state_pair!(Xoroshiro64StarStar, u32);
+
 impl SeedableRng for Xoroshiro64StarStar {
     type Seed = [u8; 8];
 
@@ -96,4 +98,11 @@ mod tests {
         let from_sm0 = Xoroshiro64StarStar::seed_from_u64(0);
         assert_eq!(from_zero, from_sm0);
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let rng = Xoroshiro64StarStar::seed_from_u64(42);
+        let clone = Xoroshiro64StarStar::from_seed(rng.state());
+        assert_eq!(clone, rng);
+    }
 }