Add UnwrappingSysRng

CHANGELOG.md

@@ -9,13 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - `RawOsError` type alias [#739]
 - `SysRng` behind new feature `sys_rng` [#751]
+- `UnwrappingSysRng` behind new feature `sys_rng` [#754]
 
 ### Changed
 - Use Edition 2024 and MSRV 1.85 [#749]
 
 [#739]: https://github.com/rust-random/getrandom/pull/739
 [#749]: https://github.com/rust-random/getrandom/pull/749
 [#751]: https://github.com/rust-random/getrandom/pull/751
+[#754]: https://github.com/rust-random/getrandom/pull/754
 
 ## [0.3.4] - 2025-10-14
 

src/lib.rs

@@ -46,7 +46,7 @@ mod sys_rng;
 #[cfg(feature = "sys_rng")]
 pub use rand_core;
 #[cfg(feature = "sys_rng")]
-pub use sys_rng::SysRng;
+pub use sys_rng::{SysRng, UnwrappingSysRng};
 
 pub use crate::error::{Error, RawOsError};
 

src/sys_rng.rs

@@ -1,34 +1,32 @@
 use crate::Error;
-use rand_core::{TryCryptoRng, TryRngCore};
+use rand_core::{CryptoRng, RngCore, TryCryptoRng, TryRngCore};
 
-/// A [`TryRngCore`] interface over the system's preferred random number source
+/// A [`TryRngCore`] interface over the system's preferred random number source.
 ///
 /// This is a zero-sized struct. It can be freely constructed with just `SysRng`.
 ///
-/// This struct is also available as [`rand::rngs::SysRng`] when using [rand].
+/// This struct is also available as [`rand::rngs::SysRng`] when using [`rand`].
+///
+/// If you don't care about potential (but extremely unlikely in practice) errors,
+/// you can use [`UnwrappingSysRng`] instead.
 ///
 /// # Usage example
 ///
 /// `SysRng` implements [`TryRngCore`]:
 /// ```
 /// use getrandom::{rand_core::TryRngCore, SysRng};
 ///
+/// # fn main() -> Result<(), getrandom::Error> {
 /// let mut key = [0u8; 32];
-/// SysRng.try_fill_bytes(&mut key).unwrap();
-/// ```
-///
-/// Using it as an [`RngCore`] is possible using [`TryRngCore::unwrap_err`]:
-/// ```
-/// use getrandom::rand_core::{TryRngCore, RngCore};
-/// use getrandom::SysRng;
+/// SysRng.try_fill_bytes(&mut key)?;
 ///
-/// let mut rng = SysRng.unwrap_err();
-/// let random_u64 = rng.next_u64();
+/// let x: u32 = SysRng.try_next_u32()?;
+/// let y: u64 = SysRng.try_next_u64()?;
+/// # Ok(()) }
 /// ```
 ///
-/// [rand]: https://crates.io/crates/rand
+/// [`rand`]: https://crates.io/crates/rand
 /// [`rand::rngs::SysRng`]: https://docs.rs/rand/latest/rand/rngs/struct.SysRng.html
-/// [`RngCore`]: rand_core::RngCore
 #[derive(Clone, Copy, Debug, Default)]
 pub struct SysRng;
 
@@ -52,3 +50,49 @@ impl TryRngCore for SysRng {
 }
 
 impl TryCryptoRng for SysRng {}
+
+/// A potentially-panicking [`RngCore`] interface over the system's preferred random number source.
+///
+/// This is a zero-sized struct. It can be freely constructed with just `UnwrappingSysRng`.
+///
+/// If possible, we recommend to use [`SysRng`] instead and to properly handle potential errors.
+///
+/// This struct is also available as [`rand::rngs::UnwrappingSysRng`] when using [`rand`].
+///
+/// # Usage example
+///
+/// `UnwrappingSysRng` implements [`RngCore`]:
+/// ```
+/// use getrandom::{rand_core::RngCore, UnwrappingSysRng};
+///
+/// let mut key = [0u8; 32];
+/// UnwrappingSysRng.fill_bytes(&mut key);
+///
+/// let x: u32 = UnwrappingSysRng.next_u32();
+/// let y: u64 = UnwrappingSysRng.next_u64();
+/// ```
+///
+/// [`rand`]: https://crates.io/crates/rand
+/// [`rand::rngs::UnwrappingSysRng`]: https://docs.rs/rand/latest/rand/rngs/struct.UnwrappingSysRng.html
+/// [`RngCore`]: rand_core::RngCore
+#[derive(Clone, Copy, Debug, Default)]
+pub struct UnwrappingSysRng;
+
+impl RngCore for UnwrappingSysRng {
+    #[inline]
+    fn next_u32(&mut self) -> u32 {
+        crate::u32().unwrap()
+    }
+
+    #[inline]
+    fn next_u64(&mut self) -> u64 {
+        crate::u64().unwrap()
+    }
+
+    #[inline]
+    fn fill_bytes(&mut self, dest: &mut [u8]) {
+        crate::fill(dest).unwrap()
+    }
+}
+
+impl CryptoRng for UnwrappingSysRng {}

tests/sys_rng.rs

@@ -1,17 +1,57 @@
 #![cfg(feature = "sys_rng")]
 
-use getrandom::SysRng;
-use getrandom::rand_core::TryRngCore;
+use core::array::from_fn;
+use getrandom::{
+    SysRng, UnwrappingSysRng,
+    rand_core::{RngCore, TryRngCore},
+};
+
+const N: usize = 32;
 
 #[test]
 fn test_sys_rng() {
-    let x = SysRng.try_next_u64().unwrap();
-    let y = SysRng.try_next_u64().unwrap();
-    assert!(x != 0);
+    let x: [u64; N] = from_fn(|_| SysRng.try_next_u64().unwrap());
+    let y: [u64; N] = from_fn(|_| SysRng.try_next_u64().unwrap());
+    assert!(x.iter().all(|&val| val != 0));
+    assert!(y.iter().all(|&val| val != 0));
+    assert!(x != y);
+
+    let x: [u32; N] = from_fn(|_| SysRng.try_next_u32().unwrap());
+    let y: [u32; N] = from_fn(|_| SysRng.try_next_u32().unwrap());
+    assert!(x.iter().all(|&val| val != 0));
+    assert!(y.iter().all(|&val| val != 0));
+    assert!(x != y);
+
+    let mut x = [0u8; N];
+    SysRng.try_fill_bytes(&mut x).unwrap();
+    let mut y = [0u8; N];
+    SysRng.try_fill_bytes(&mut y).unwrap();
+
+    assert_ne!(x, [0; N]);
+    assert_ne!(y, [0; N]);
     assert!(x != y);
 }
 
 #[test]
-fn test_construction() {
-    assert!(SysRng.try_next_u64().unwrap() != 0);
+fn test_unwrapping_sys_rng() {
+    let x: [u64; N] = from_fn(|_| UnwrappingSysRng.next_u64());
+    let y: [u64; N] = from_fn(|_| UnwrappingSysRng.next_u64());
+    assert!(x.iter().all(|&val| val != 0));
+    assert!(y.iter().all(|&val| val != 0));
+    assert!(x != y);
+
+    let x: [u32; N] = from_fn(|_| UnwrappingSysRng.next_u32());
+    let y: [u32; N] = from_fn(|_| UnwrappingSysRng.next_u32());
+    assert!(x.iter().all(|&val| val != 0));
+    assert!(y.iter().all(|&val| val != 0));
+    assert!(x != y);
+
+    let mut x = [0u8; N];
+    UnwrappingSysRng.fill_bytes(&mut x);
+    let mut y = [0u8; N];
+    UnwrappingSysRng.fill_bytes(&mut y);
+
+    assert_ne!(x, [0; N]);
+    assert_ne!(y, [0; N]);
+    assert!(x != y);
 }