Add a RandomBits distribution

RELEASES.md

@@ -11,7 +11,8 @@
 - [`BigInt` now supports assignment operators][41] like `AddAssign`.
 - [`BigInt` and `BigUint` now support conversions with `i128` and `u128`][44],
   if sufficient compiler support is detected.
-- [`BigInt` and `BigUint` now implement rand's `SampleUniform` trait][48].
+- [`BigInt` and `BigUint` now implement rand's `SampleUniform` trait][48], and
+  [a custom `RandomBits` distribution samples by bit size][49].
 - The release also includes other miscellaneous improvements to performance.
 
 ### Breaking Changes
@@ -44,6 +45,7 @@
 [44]: https://github.com/rust-num/num-bigint/pull/44
 [46]: https://github.com/rust-num/num-bigint/pull/46
 [48]: https://github.com/rust-num/num-bigint/pull/48
+[49]: https://github.com/rust-num/num-bigint/pull/49
 
 # Release 0.1.44
 

src/bigrand.rs

@@ -1,6 +1,6 @@
 //! Randomization of big integers
 
-use rand::Rng;
+use rand::prelude::*;
 use rand::distributions::uniform::{SampleUniform, UniformSampler};
 
 use BigInt;
@@ -118,6 +118,7 @@ pub struct UniformBigUint {
 impl UniformSampler for UniformBigUint {
     type X = BigUint;
 
+    #[inline]
     fn new(low: Self::X, high: Self::X) -> Self {
         assert!(low < high);
         UniformBigUint {
@@ -126,15 +127,18 @@ impl UniformSampler for UniformBigUint {
         }
     }
 
+    #[inline]
     fn new_inclusive(low: Self::X, high: Self::X) -> Self {
         assert!(low <= high);
         Self::new(low, high + 1u32)
     }
 
+    #[inline]
     fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X {
         &self.base + rng.gen_biguint_below(&self.len)
     }
 
+    #[inline]
     fn sample_single<R: Rng + ?Sized>(low: Self::X, high: Self::X, rng: &mut R) -> Self::X {
         rng.gen_biguint_range(&low, &high)
     }
@@ -155,6 +159,7 @@ pub struct UniformBigInt {
 impl UniformSampler for UniformBigInt {
     type X = BigInt;
 
+    #[inline]
     fn new(low: Self::X, high: Self::X) -> Self {
         assert!(low < high);
         UniformBigInt {
@@ -163,15 +168,18 @@ impl UniformSampler for UniformBigInt {
         }
     }
 
+    #[inline]
     fn new_inclusive(low: Self::X, high: Self::X) -> Self {
         assert!(low <= high);
         Self::new(low, high + 1u32)
     }
 
+    #[inline]
     fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X {
         &self.base + BigInt::from(rng.gen_biguint_below(&self.len))
     }
 
+    #[inline]
     fn sample_single<R: Rng + ?Sized>(low: Self::X, high: Self::X, rng: &mut R) -> Self::X {
         rng.gen_bigint_range(&low, &high)
     }
@@ -180,3 +188,30 @@ impl UniformSampler for UniformBigInt {
 impl SampleUniform for BigInt {
     type Sampler = UniformBigInt;
 }
+
+/// A random distribution for `BigUint` and `BigInt` values of a particular bit size.
+#[derive(Clone, Copy, Debug)]
+pub struct RandomBits {
+    bits: usize,
+}
+
+impl RandomBits {
+    #[inline]
+    pub fn new(bits: usize) -> RandomBits {
+        RandomBits { bits }
+    }
+}
+
+impl Distribution<BigUint> for RandomBits {
+    #[inline]
+    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> BigUint {
+        rng.gen_biguint(self.bits)
+    }
+}
+
+impl Distribution<BigInt> for RandomBits {
+    #[inline]
+    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> BigInt {
+        rng.gen_bigint(self.bits)
+    }
+}

src/lib.rs

@@ -164,7 +164,7 @@ pub use bigint::BigInt;
 pub use bigint::ToBigInt;
 
 #[cfg(feature = "rand")]
-pub use bigrand::{RandBigInt, UniformBigUint, UniformBigInt};
+pub use bigrand::{RandBigInt, RandomBits, UniformBigUint, UniformBigInt};
 
 mod big_digit {
     /// A `BigDigit` is a `BigUint`'s composing element.

tests/rand.rs

@@ -5,7 +5,7 @@ extern crate num_traits;
 extern crate rand;
 
 mod biguint {
-    use num_bigint::{BigUint, RandBigInt};
+    use num_bigint::{BigUint, RandBigInt, RandomBits};
     use num_traits::Zero;
     use rand::thread_rng;
     use rand::Rng;
@@ -14,10 +14,20 @@ mod biguint {
     #[test]
     fn test_rand() {
         let mut rng = thread_rng();
-        let _n: BigUint = rng.gen_biguint(137);
+        let n: BigUint = rng.gen_biguint(137);
+        assert!(n.bits() <= 137);
         assert!(rng.gen_biguint(0).is_zero());
     }
 
+    #[test]
+    fn test_rand_bits() {
+        let mut rng = thread_rng();
+        let n: BigUint = rng.sample(&RandomBits::new(137));
+        assert!(n.bits() <= 137);
+        let z: BigUint = rng.sample(&RandomBits::new(0));
+        assert!(z.is_zero());
+    }
+
     #[test]
     fn test_rand_range() {
         let mut rng = thread_rng();
@@ -82,7 +92,7 @@ mod biguint {
 }
 
 mod bigint {
-    use num_bigint::{BigInt, RandBigInt};
+    use num_bigint::{BigInt, RandBigInt, RandomBits};
     use num_traits::Zero;
     use rand::thread_rng;
     use rand::Rng;
@@ -91,10 +101,20 @@ mod bigint {
     #[test]
     fn test_rand() {
         let mut rng = thread_rng();
-        let _n: BigInt = rng.gen_bigint(137);
+        let n: BigInt = rng.gen_bigint(137);
+        assert!(n.bits() <= 137);
         assert!(rng.gen_bigint(0).is_zero());
     }
 
+    #[test]
+    fn test_rand_bits() {
+        let mut rng = thread_rng();
+        let n: BigInt = rng.sample(&RandomBits::new(137));
+        assert!(n.bits() <= 137);
+        let z: BigInt = rng.sample(&RandomBits::new(0));
+        assert!(z.is_zero());
+    }
+
     #[test]
     fn test_rand_range() {
         let mut rng = thread_rng();