rand_xoshiro: Add state() for serde-free state export (#109)

Add a `state()` method to all 15 RNG types in `rand_xoshiro`, returning
the internal state as a value matching the type's `SeedableRng::Seed`.
This lets callers persist and reload generator state without enabling
the `serde` feature: `Self::from_seed(rng.state())` reconstructs an
identical generator.

Return type per RNG matches its `Seed`:

| RNG                                                       | `state()`   |
| --------------------------------------------------------- | ----------- |
| `SplitMix64`, `Xoroshiro64Star`, `Xoroshiro64StarStar`    | `[u8; 8]`   |
| `Xoroshiro128*`, `Xoshiro128*`                            | `[u8; 16]`  |
| `Xoshiro256*`                                             | `[u8; 32]`  |
| `Xoshiro512*`                                             | `Seed512`   |

The all-zero state is unreachable from any non-zero seed for these
algorithms, so the round-trip is exact for any generator obtained via
the usual constructors. (`from_seed` remaps an all-zero input to
`seed_from_u64(0)`; this is documented on each `state()`.)

Implementation lives in four small macros in `common.rs`
(`impl_state_scalar!`, `impl_state_pair!`, `impl_state_array!`,
`impl_state_seed512!`); each RNG file gets one macro invocation and one
`state_roundtrip` test.

Fixes #109, #64.

Author: vks

rand_xoshiro/CHANGELOG.md

@@ -4,6 +4,15 @@ 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]
+### 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 ([#109], [#64]).
+
+[[#109]: https://github.com/rust-random/rngs/issues/109
+[[#64]: https://github.com/rust-random/rngs/issues/64
+
 ## [0.8.0] - 2026-02-01
 ### Changes
 - Use Edition 2024 and MSRV 1.85 ([#73])

rand_xoshiro/src/common.rs

@@ -222,6 +222,99 @@ macro_rules! impl_xoshiro_large {
     };
 }
 
+/// Implement `state`, returning the internal state of a single-word RNG as
+/// little-endian bytes that round-trip through [`SeedableRng::from_seed`].
+macro_rules! impl_state_scalar {
+    ($type:ident) => {
+        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.
+            ///
+            /// [`SeedableRng::from_seed`]: rand_core::SeedableRng::from_seed
+            pub fn state(&self) -> [u8; 8] {
+                self.x.to_le_bytes()
+            }
+        }
+    };
+}
+
+/// Implement `state` for an RNG with two word-sized fields `s0` and `s1`.
+macro_rules! impl_state_pair {
+    ($type:ident, $word:ty, $bytes:literal) => {
+        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; $bytes] {
+                let mut out = [0u8; $bytes];
+                let n = core::mem::size_of::<$word>();
+                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 a `s: [WORD; N]` field.
+macro_rules! impl_state_array {
+    ($type:ident, $word:ty, $bytes:literal) => {
+        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; $bytes] {
+                let mut out = [0u8; $bytes];
+                let n = core::mem::size_of::<$word>();
+                for (i, word) in self.s.iter().enumerate() {
+                    out[i * n..(i + 1) * n].copy_from_slice(&word.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)
+            }
+        }
+    };
+}
+
 /// Map an all-zero seed to a different one.
 macro_rules! deal_with_zero_seed {
     ($seed:expr, $Self:ident, $bytes:expr) => {

rand_xoshiro/src/splitmix64.rs

@@ -60,6 +60,8 @@ impl TryRng for SplitMix64 {
     }
 }
 
+impl_state_scalar!(SplitMix64);
+
 impl SeedableRng for SplitMix64 {
     type Seed = [u8; 8];
 
@@ -142,6 +144,18 @@ mod tests {
         }
     }
 
+    #[test]
+    fn state_roundtrip() {
+        let mut rng = SplitMix64::seed_from_u64(42);
+        for _ in 0..10 {
+            rng.next_u64();
+        }
+        let mut clone = SplitMix64::from_seed(rng.state());
+        for _ in 0..10 {
+            assert_eq!(rng.next_u64(), clone.next_u64());
+        }
+    }
+
     #[test]
     fn next_u32() {
         let mut rng = SplitMix64::seed_from_u64(10);

rand_xoshiro/src/xoroshiro128plus.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, 16);
+
 impl SeedableRng for Xoroshiro128Plus {
     type Seed = [u8; 16];
 
@@ -123,4 +125,16 @@ mod tests {
             assert_eq!(rng.next_u64(), e);
         }
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let mut rng = Xoroshiro128Plus::seed_from_u64(42);
+        for _ in 0..10 {
+            rng.next_u64();
+        }
+        let mut clone = Xoroshiro128Plus::from_seed(rng.state());
+        for _ in 0..10 {
+            assert_eq!(rng.next_u64(), clone.next_u64());
+        }
+    }
 }

rand_xoshiro/src/xoroshiro128plusplus.rs

@@ -78,6 +78,8 @@ impl TryRng for Xoroshiro128PlusPlus {
     }
 }
 
+impl_state_pair!(Xoroshiro128PlusPlus, u64, 16);
+
 impl SeedableRng for Xoroshiro128PlusPlus {
     type Seed = [u8; 16];
 
@@ -122,4 +124,16 @@ mod tests {
             assert_eq!(rng.next_u64(), e);
         }
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let mut rng = Xoroshiro128PlusPlus::seed_from_u64(42);
+        for _ in 0..10 {
+            rng.next_u64();
+        }
+        let mut clone = Xoroshiro128PlusPlus::from_seed(rng.state());
+        for _ in 0..10 {
+            assert_eq!(rng.next_u64(), clone.next_u64());
+        }
+    }
 }

rand_xoshiro/src/xoroshiro128starstar.rs

@@ -78,6 +78,8 @@ impl TryRng for Xoroshiro128StarStar {
     }
 }
 
+impl_state_pair!(Xoroshiro128StarStar, u64, 16);
+
 impl SeedableRng for Xoroshiro128StarStar {
     type Seed = [u8; 16];
 
@@ -122,4 +124,16 @@ mod tests {
             assert_eq!(rng.next_u64(), e);
         }
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let mut rng = Xoroshiro128StarStar::seed_from_u64(42);
+        for _ in 0..10 {
+            rng.next_u64();
+        }
+        let mut clone = Xoroshiro128StarStar::from_seed(rng.state());
+        for _ in 0..10 {
+            assert_eq!(rng.next_u64(), clone.next_u64());
+        }
+    }
 }

rand_xoshiro/src/xoroshiro64star.rs

@@ -49,6 +49,8 @@ impl TryRng for Xoroshiro64Star {
     }
 }
 
+impl_state_pair!(Xoroshiro64Star, u32, 8);
+
 impl SeedableRng for Xoroshiro64Star {
     type Seed = [u8; 8];
 
@@ -91,4 +93,16 @@ mod tests {
         let mut rng = Xoroshiro64Star::seed_from_u64(0);
         assert_ne!(rng.next_u64(), 0);
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let mut rng = Xoroshiro64Star::seed_from_u64(42);
+        for _ in 0..10 {
+            rng.next_u32();
+        }
+        let mut clone = Xoroshiro64Star::from_seed(rng.state());
+        for _ in 0..10 {
+            assert_eq!(rng.next_u32(), clone.next_u32());
+        }
+    }
 }

rand_xoshiro/src/xoroshiro64starstar.rs

@@ -48,6 +48,8 @@ impl TryRng for Xoroshiro64StarStar {
     }
 }
 
+impl_state_pair!(Xoroshiro64StarStar, u32, 8);
+
 impl SeedableRng for Xoroshiro64StarStar {
     type Seed = [u8; 8];
 
@@ -90,4 +92,16 @@ mod tests {
         let mut rng = Xoroshiro64StarStar::seed_from_u64(0);
         assert_ne!(rng.next_u64(), 0);
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let mut rng = Xoroshiro64StarStar::seed_from_u64(42);
+        for _ in 0..10 {
+            rng.next_u32();
+        }
+        let mut clone = Xoroshiro64StarStar::from_seed(rng.state());
+        for _ in 0..10 {
+            assert_eq!(rng.next_u32(), clone.next_u32());
+        }
+    }
 }

rand_xoshiro/src/xoshiro128plus.rs

@@ -56,6 +56,8 @@ impl Xoshiro128Plus {
     }
 }
 
+impl_state_array!(Xoshiro128Plus, u32, 16);
+
 impl SeedableRng for Xoshiro128Plus {
     type Seed = [u8; 16];
 
@@ -137,4 +139,16 @@ mod tests {
         assert_eq!(rng.s[2], 966769569);
         assert_eq!(rng.s[3], 3193880526);
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let mut rng = Xoshiro128Plus::seed_from_u64(42);
+        for _ in 0..10 {
+            rng.next_u32();
+        }
+        let mut clone = Xoshiro128Plus::from_seed(rng.state());
+        for _ in 0..10 {
+            assert_eq!(rng.next_u32(), clone.next_u32());
+        }
+    }
 }

rand_xoshiro/src/xoshiro128plusplus.rs

@@ -55,6 +55,8 @@ impl Xoshiro128PlusPlus {
     }
 }
 
+impl_state_array!(Xoshiro128PlusPlus, u32, 16);
+
 impl SeedableRng for Xoshiro128PlusPlus {
     type Seed = [u8; 16];
 
@@ -139,4 +141,16 @@ mod tests {
         assert_eq!(rng.s[2], 966769569);
         assert_eq!(rng.s[3], 3193880526);
     }
+
+    #[test]
+    fn state_roundtrip() {
+        let mut rng = Xoshiro128PlusPlus::seed_from_u64(42);
+        for _ in 0..10 {
+            rng.next_u32();
+        }
+        let mut clone = Xoshiro128PlusPlus::from_seed(rng.state());
+        for _ in 0..10 {
+            assert_eq!(rng.next_u32(), clone.next_u32());
+        }
+    }
 }