Use verbs instead of nouns for prime-generation functions

Author: fjarri

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `MillerRabin::new()` and `test_random_base()` will panic if the input is invalid. ([#22])
 - `MillerRabin::check()` renamed to `test()`. ([#22])
 - Prime-generating function take `Option<usize>` instead of `usize`, where `None` means the full size of the `Uint`. ([#19])
+- Renamed `prime()` to `generate_prime()`, `safe_prime()` to `generate_safe_prime()`, `prime_with_rng()` to `generate_prime_with_rng()`, `safe_prime_with_rng()` to `generate_safe_prime_with_rng()`. ([#24])
 
 
 ### Added
@@ -29,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#19]: https://github.com/nucypher/rust-umbral/pull/19
 [#20]: https://github.com/nucypher/rust-umbral/pull/20
 [#22]: https://github.com/nucypher/rust-umbral/pull/22
+[#24]: https://github.com/nucypher/rust-umbral/pull/24
 
 
 ## [0.2.0] - 2023-03-06

benches/bench.rs

@@ -10,11 +10,12 @@ use rug::{integer::Order, Integer};
 use openssl::bn::BigNum;
 
 use crypto_primes::{
+    generate_prime_with_rng, generate_safe_prime_with_rng,
     hazmat::{
         lucas_test, random_odd_uint, AStarBase, BruteForceBase, LucasCheck, MillerRabin,
         SelfridgeBase, Sieve,
     },
-    is_prime_with_rng, is_safe_prime_with_rng, prime_with_rng, safe_prime_with_rng,
+    is_prime_with_rng, is_safe_prime_with_rng,
 };
 
 fn make_rng() -> ChaCha8Rng {
@@ -207,23 +208,23 @@ fn bench_presets(c: &mut Criterion) {
 
     let mut rng = make_rng();
     group.bench_function("(U128) Random prime", |b| {
-        b.iter(|| prime_with_rng::<{ nlimbs!(128) }>(&mut rng, None))
+        b.iter(|| generate_prime_with_rng::<{ nlimbs!(128) }>(&mut rng, None))
     });
 
     let mut rng = make_rng();
     group.bench_function("(U1024) Random prime", |b| {
-        b.iter(|| prime_with_rng::<{ nlimbs!(1024) }>(&mut rng, None))
+        b.iter(|| generate_prime_with_rng::<{ nlimbs!(1024) }>(&mut rng, None))
     });
 
     let mut rng = make_rng();
     group.bench_function("(U128) Random safe prime", |b| {
-        b.iter(|| safe_prime_with_rng::<{ nlimbs!(128) }>(&mut rng, None))
+        b.iter(|| generate_safe_prime_with_rng::<{ nlimbs!(128) }>(&mut rng, None))
     });
 
     group.sample_size(20);
     let mut rng = make_rng();
     group.bench_function("(U1024) Random safe prime", |b| {
-        b.iter(|| safe_prime_with_rng::<{ nlimbs!(1024) }>(&mut rng, None))
+        b.iter(|| generate_safe_prime_with_rng::<{ nlimbs!(1024) }>(&mut rng, None))
     });
 
     group.finish();
@@ -233,19 +234,19 @@ fn bench_presets(c: &mut Criterion) {
 
     let mut rng = make_rng();
     group.bench_function("(U128) Random safe prime", |b| {
-        b.iter(|| safe_prime_with_rng::<{ nlimbs!(128) }>(&mut rng, None))
+        b.iter(|| generate_safe_prime_with_rng::<{ nlimbs!(128) }>(&mut rng, None))
     });
 
     // The performance should scale with the prime size, not with the Uint size.
     // So we should strive for this test's result to be as close as possible
     // to that of the previous one and as far away as possible from the next one.
     group.bench_function("(U256) Random 128 bit safe prime", |b| {
-        b.iter(|| safe_prime_with_rng::<{ nlimbs!(256) }>(&mut rng, Some(128)))
+        b.iter(|| generate_safe_prime_with_rng::<{ nlimbs!(256) }>(&mut rng, Some(128)))
     });
 
     // The upper bound for the previous test.
     group.bench_function("(U256) Random 256 bit safe prime", |b| {
-        b.iter(|| safe_prime_with_rng::<{ nlimbs!(256) }>(&mut rng, None))
+        b.iter(|| generate_safe_prime_with_rng::<{ nlimbs!(256) }>(&mut rng, None))
     });
 
     group.finish();

src/lib.rs

@@ -19,8 +19,11 @@ pub mod hazmat;
 mod presets;
 mod traits;
 
-pub use presets::{is_prime_with_rng, is_safe_prime_with_rng, prime_with_rng, safe_prime_with_rng};
+pub use presets::{
+    generate_prime_with_rng, generate_safe_prime_with_rng, is_prime_with_rng,
+    is_safe_prime_with_rng,
+};
 pub use traits::RandomPrimeWithRng;
 
 #[cfg(feature = "default-rng")]
-pub use presets::{is_prime, is_safe_prime, prime, safe_prime};
+pub use presets::{generate_prime, generate_safe_prime, is_prime, is_safe_prime};

src/presets.rs

@@ -13,8 +13,8 @@ use crate::hazmat::{
 ///
 /// See [`is_prime_with_rng`] for details about the performed checks.
 #[cfg(feature = "default-rng")]
-pub fn prime<const L: usize>(bit_length: Option<usize>) -> Uint<L> {
-    prime_with_rng(&mut OsRng, bit_length)
+pub fn generate_prime<const L: usize>(bit_length: Option<usize>) -> Uint<L> {
+    generate_prime_with_rng(&mut OsRng, bit_length)
 }
 
 /// Returns a random safe prime (that is, such that `(n - 1) / 2` is also prime)
@@ -23,8 +23,8 @@ pub fn prime<const L: usize>(bit_length: Option<usize>) -> Uint<L> {
 ///
 /// See [`is_prime_with_rng`] for details about the performed checks.
 #[cfg(feature = "default-rng")]
-pub fn safe_prime<const L: usize>(bit_length: Option<usize>) -> Uint<L> {
-    safe_prime_with_rng(&mut OsRng, bit_length)
+pub fn generate_safe_prime<const L: usize>(bit_length: Option<usize>) -> Uint<L> {
+    generate_safe_prime_with_rng(&mut OsRng, bit_length)
 }
 
 /// Checks probabilistically if the given number is prime using [`OsRng`] as the RNG.
@@ -51,7 +51,7 @@ pub fn is_safe_prime<const L: usize>(num: &Uint<L>) -> bool {
 /// Panics if `bit_length` is less than 2, or greater than the bit size of the target `Uint`.
 ///
 /// See [`is_prime_with_rng`] for details about the performed checks.
-pub fn prime_with_rng<const L: usize>(
+pub fn generate_prime_with_rng<const L: usize>(
     rng: &mut impl CryptoRngCore,
     bit_length: Option<usize>,
 ) -> Uint<L> {
@@ -77,7 +77,7 @@ pub fn prime_with_rng<const L: usize>(
 /// Panics if `bit_length` is less than 3, or is greater than the bit size of the target `Uint`.
 ///
 /// See [`is_prime_with_rng`] for details about the performed checks.
-pub fn safe_prime_with_rng<const L: usize>(
+pub fn generate_safe_prime_with_rng<const L: usize>(
     rng: &mut impl CryptoRngCore,
     bit_length: Option<usize>,
 ) -> Uint<L> {
@@ -178,7 +178,10 @@ mod tests {
     use num_prime::nt_funcs::is_prime64;
     use rand_core::OsRng;
 
-    use super::{is_prime, is_safe_prime, prime, prime_with_rng, safe_prime, safe_prime_with_rng};
+    use super::{
+        generate_prime, generate_prime_with_rng, generate_safe_prime, generate_safe_prime_with_rng,
+        is_prime, is_safe_prime,
+    };
     use crate::hazmat::{primes, pseudoprimes};
 
     fn test_large_primes<const L: usize>(nums: &[Uint<L>]) {
@@ -247,18 +250,18 @@ mod tests {
     }
 
     #[test]
-    fn generate_prime() {
+    fn prime_generation() {
         for bit_length in (28..=128).step_by(10) {
-            let p: U128 = prime(Some(bit_length));
+            let p: U128 = generate_prime(Some(bit_length));
             assert!(p.bits_vartime() == bit_length);
             assert!(is_prime(&p));
         }
     }
 
     #[test]
-    fn generate_safe_prime() {
+    fn safe_prime_generation() {
         for bit_length in (28..=128).step_by(10) {
-            let p: U128 = safe_prime(Some(bit_length));
+            let p: U128 = generate_safe_prime(Some(bit_length));
             assert!(p.bits_vartime() == bit_length);
             assert!(is_safe_prime(&p));
         }
@@ -291,25 +294,25 @@ mod tests {
     #[test]
     #[should_panic(expected = "`bit_length` must be 2 or greater")]
     fn generate_prime_too_few_bits() {
-        let _p: U64 = prime_with_rng(&mut OsRng, Some(1));
+        let _p: U64 = generate_prime_with_rng(&mut OsRng, Some(1));
     }
 
     #[test]
     #[should_panic(expected = "`bit_length` must be 3 or greater")]
     fn generate_safe_prime_too_few_bits() {
-        let _p: U64 = safe_prime_with_rng(&mut OsRng, Some(2));
+        let _p: U64 = generate_safe_prime_with_rng(&mut OsRng, Some(2));
     }
 
     #[test]
     #[should_panic(expected = "The requested bit length (65) is larger than the chosen Uint size")]
     fn generate_prime_too_many_bits() {
-        let _p: U64 = prime_with_rng(&mut OsRng, Some(65));
+        let _p: U64 = generate_prime_with_rng(&mut OsRng, Some(65));
     }
 
     #[test]
     #[should_panic(expected = "The requested bit length (65) is larger than the chosen Uint size")]
     fn generate_safe_prime_too_many_bits() {
-        let _p: U64 = safe_prime_with_rng(&mut OsRng, Some(65));
+        let _p: U64 = generate_safe_prime_with_rng(&mut OsRng, Some(65));
     }
 
     fn is_prime_ref(num: Word) -> bool {
@@ -320,7 +323,7 @@ mod tests {
     fn corner_cases_generate_prime() {
         for bits in 2usize..5 {
             for _ in 0..100 {
-                let p: U64 = prime(Some(bits));
+                let p: U64 = generate_prime(Some(bits));
                 let p_word = p.as_words()[0];
                 assert!(is_prime_ref(p_word));
             }
@@ -331,7 +334,7 @@ mod tests {
     fn corner_cases_generate_safe_prime() {
         for bits in 3usize..5 {
             for _ in 0..100 {
-                let p: U64 = safe_prime(Some(bits));
+                let p: U64 = generate_safe_prime(Some(bits));
                 let p_word = p.as_words()[0];
                 assert!(is_prime_ref(p_word) && is_prime_ref(p_word / 2));
             }
@@ -348,7 +351,7 @@ mod tests_openssl {
     use openssl::bn::{BigNum, BigNumContext};
     use rand_core::OsRng;
 
-    use super::{is_prime, prime};
+    use super::{generate_prime, is_prime};
     use crate::hazmat::random_odd_uint;
 
     fn openssl_is_prime(num: &BigNum, ctx: &mut BigNumContext) -> bool {
@@ -369,7 +372,7 @@ mod tests_openssl {
 
         // Generate primes, let OpenSSL check them
         for _ in 0..100 {
-            let p: U128 = prime(Some(128));
+            let p: U128 = generate_prime(Some(128));
             let p_bn = to_openssl(&p);
             assert!(
                 openssl_is_prime(&p_bn, &mut ctx),
@@ -409,7 +412,7 @@ mod tests_gmp {
         Integer,
     };
 
-    use super::{is_prime, prime};
+    use super::{generate_prime, is_prime};
     use crate::hazmat::random_odd_uint;
 
     fn gmp_is_prime(num: &Integer) -> bool {
@@ -428,7 +431,7 @@ mod tests_gmp {
     fn gmp_cross_check() {
         // Generate primes, let GMP check them
         for _ in 0..100 {
-            let p: U128 = prime(Some(128));
+            let p: U128 = generate_prime(Some(128));
             let p_bn = to_gmp(&p);
             assert!(gmp_is_prime(&p_bn), "GMP reports {p} as composite");
         }

src/traits.rs

@@ -1,7 +1,10 @@
 use crypto_bigint::Uint;
 use rand_core::CryptoRngCore;
 
-use crate::{is_prime_with_rng, is_safe_prime_with_rng, prime_with_rng, safe_prime_with_rng};
+use crate::{
+    generate_prime_with_rng, generate_safe_prime_with_rng, is_prime_with_rng,
+    is_safe_prime_with_rng,
+};
 
 /// Provides a generic way to access methods for random prime number generation
 /// and primality checking, wrapping the standalone functions ([`is_prime_with_rng`] etc).
@@ -12,7 +15,7 @@ pub trait RandomPrimeWithRng {
     /// Panics if `bit_length` is less than 2, or greater than the bit size of the target `Uint`.
     ///
     /// See [`is_prime_with_rng`] for details about the performed checks.
-    fn prime_with_rng(rng: &mut impl CryptoRngCore, bit_length: Option<usize>) -> Self;
+    fn generate_prime_with_rng(rng: &mut impl CryptoRngCore, bit_length: Option<usize>) -> Self;
 
     /// Returns a random safe prime (that is, such that `(n - 1) / 2` is also prime)
     /// of size `bit_length` using the provided RNG.
@@ -21,7 +24,10 @@ pub trait RandomPrimeWithRng {
     /// Panics if `bit_length` is less than 3, or greater than the bit size of the target `Uint`.
     ///
     /// See [`is_prime_with_rng`] for details about the performed checks.
-    fn safe_prime_with_rng(rng: &mut impl CryptoRngCore, bit_length: Option<usize>) -> Self;
+    fn generate_safe_prime_with_rng(
+        rng: &mut impl CryptoRngCore,
+        bit_length: Option<usize>,
+    ) -> Self;
 
     /// Checks probabilistically if the given number is prime using the provided RNG.
     ///
@@ -35,11 +41,14 @@ pub trait RandomPrimeWithRng {
 }
 
 impl<const L: usize> RandomPrimeWithRng for Uint<L> {
-    fn prime_with_rng(rng: &mut impl CryptoRngCore, bit_length: Option<usize>) -> Self {
-        prime_with_rng(rng, bit_length)
+    fn generate_prime_with_rng(rng: &mut impl CryptoRngCore, bit_length: Option<usize>) -> Self {
+        generate_prime_with_rng(rng, bit_length)
     }
-    fn safe_prime_with_rng(rng: &mut impl CryptoRngCore, bit_length: Option<usize>) -> Self {
-        safe_prime_with_rng(rng, bit_length)
+    fn generate_safe_prime_with_rng(
+        rng: &mut impl CryptoRngCore,
+        bit_length: Option<usize>,
+    ) -> Self {
+        generate_safe_prime_with_rng(rng, bit_length)
     }
     fn is_prime_with_rng(&self, rng: &mut impl CryptoRngCore) -> bool {
         is_prime_with_rng(rng, self)
@@ -64,7 +73,8 @@ mod tests {
         assert!(!U64::from(13u32).is_safe_prime_with_rng(&mut OsRng));
         assert!(U64::from(11u32).is_safe_prime_with_rng(&mut OsRng));
 
-        assert!(U64::prime_with_rng(&mut OsRng, Some(10)).is_prime_with_rng(&mut OsRng));
-        assert!(U64::safe_prime_with_rng(&mut OsRng, Some(10)).is_safe_prime_with_rng(&mut OsRng));
+        assert!(U64::generate_prime_with_rng(&mut OsRng, Some(10)).is_prime_with_rng(&mut OsRng));
+        assert!(U64::generate_safe_prime_with_rng(&mut OsRng, Some(10))
+            .is_safe_prime_with_rng(&mut OsRng));
     }
 }