Add in_place suffix for BigInteger methods

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Pending
 
 - [\#772](https://github.com/arkworks-rs/algebra/pull/772) (`ark-ff`) Implementation of `mul` method for `BigInteger`.
+- [\#782](https://github.com/arkworks-rs/algebra/pull/782) (`ark-ff`) Add `in_place` suffix for `BigInteger` methods (`add_with_carry_in_place`, `sub_with_borrow_in_place`, `mul2_in_place`, `muln_in_place`, `div2_in_place`, `divn_in_place`).
 
 ### Breaking changes
 
@@ -32,9 +33,9 @@
 
 ### Improvements
 
-- [\#736](https://github.com/arkworks-rs/algebra/pull/736) (`ark-ff`) Deprecate `divn()`, and use `core::ops::{Shr, ShrAssign}` instead.
-- [\#739](https://github.com/arkworks-rs/algebra/pull/739) (`ark-ff`) Deprecate `muln()`, and use `core::ops::{Shl, ShlAssign}` instead.
-- [\#771](https://github.com/arkworks-rs/algebra/pull/771) (`ark-ec`) Omit expensive  scalar multiplication in `is_in_correct_subgroup_assuming_on_curve()` for short Weierstrass curves of cofactor one.  
+- [\#736](https://github.com/arkworks-rs/algebra/pull/736) (`ark-ff`) Deprecate `divn_in_place()`, and use `core::ops::{Shr, ShrAssign}` instead.
+- [\#739](https://github.com/arkworks-rs/algebra/pull/739) (`ark-ff`) Deprecate `muln_in_place()`, and use `core::ops::{Shl, ShlAssign}` instead.
+- [\#771](https://github.com/arkworks-rs/algebra/pull/771) (`ark-ec`) Omit expensive  scalar multiplication in `is_in_correct_subgroup_assuming_on_curve()` for short Weierstrass curves of cofactor one.
 
 ### Bugfixes
 
@@ -91,7 +92,7 @@
     - Rename `Fp*Parameters` to `Fp*Config`.
     - Add `From<u32>`, `From<u16>`, and `From<u8>` `impl`s for `BigInt<N>`.
     - Remove `FftConfig`; move its contents to `FftField`.
-- [\#383](https://github.com/arkworks-rs/algebra/pull/383) (`ark-ff`) Rename `BigInteger::add_nocarry` to `add_with_carry` and `sub_noborrow` to `sub_with_borrow`.
+- [\#383](https://github.com/arkworks-rs/algebra/pull/383) (`ark-ff`) Rename `BigInteger::add_nocarry` to `add_with_carry_in_place` and `sub_noborrow` to `sub_with_borrow_in_place`.
 - [\#386](https://github.com/arkworks-rs/algebra/pull/386) (`ark-ff`) Remove `PrimeField::GENERATOR`, since it already exists on `FftField`.
 - [\#393](https://github.com/arkworks-rs/algebra/pull/393) (`ark-ec`, `ark-ff`) Rename `FpXParams` to `FpXConfig` and `FpXParamsWrapper` to `FpXConfigWrapper`.
 - [\#396](https://github.com/arkworks-rs/algebra/pull/396) (`ark-ec`) Remove `mul_bits` feature, and remove default implementations of `mul` and `mul_by_cofactor_to_projective`.

bench-templates/src/macros/field.rs

@@ -291,10 +291,10 @@ macro_rules! prime_field {
                     let mut tmp2 = BigInt::rand(&mut rng);
                     // Shave a few bits off to avoid overflow.
                     for _ in 0..3 {
-                        tmp1.div2();
-                        tmp2.div2();
+                        tmp1.div2_in_place();
+                        tmp2.div2_in_place();
                     }
-                    tmp2.div2();
+                    tmp2.div2_in_place();
                     (tmp1, tmp2)
                 })
                 .unzip();
@@ -304,31 +304,31 @@ macro_rules! prime_field {
                 b.iter(|| {
                     i = (i + 1) % SAMPLES;
                     let mut tmp = v1[i];
-                    (tmp, tmp.add_with_carry(&v2[i]))
+                    (tmp, tmp.add_with_carry_in_place(&v2[i]))
                 })
             });
             arithmetic.bench_function("Subtraction with borrow", |b| {
                 let mut i = 0;
                 b.iter(|| {
                     i = (i + 1) % SAMPLES;
                     let mut tmp = v1[i];
-                    (tmp, tmp.sub_with_borrow(&v2[i]))
+                    (tmp, tmp.sub_with_borrow_in_place(&v2[i]))
                 })
             });
             arithmetic.bench_function("Multiplication by 2", |b| {
                 let mut i = 0;
                 b.iter(|| {
                     i = (i + 1) % SAMPLES;
                     let mut tmp = v1[i];
-                    tmp.mul2()
+                    tmp.mul2_in_place()
                 })
             });
             arithmetic.bench_function("Division by 2", |b| {
                 let mut i = 0;
                 b.iter(|| {
                     i = (i + 1) % SAMPLES;
                     let mut tmp = v1[i];
-                    tmp.div2()
+                    tmp.div2_in_place()
                 })
             });
             arithmetic.finish();

curves/bls12_377/src/fields/tests.rs

@@ -49,7 +49,7 @@ fn test_fq_repr_num_bits() {
     a = BigInteger384::from(1u64);
     for i in 1..385 {
         assert_eq!(i, a.num_bits());
-        a.mul2();
+        a.mul2_in_place();
     }
     assert_eq!(0, a.num_bits());
 }

curves/bls12_381/src/fields/tests.rs

@@ -772,7 +772,7 @@ fn test_fq_repr_div2() {
         0x41f82777bd13fdb,
         0xf43944578f9b771b,
     ]);
-    a.div2();
+    a.div2_in_place();
     assert_eq!(
         a,
         BigInt::new([
@@ -785,7 +785,7 @@ fn test_fq_repr_div2() {
         ])
     );
     for _ in 0..10 {
-        a.div2();
+        a.div2_in_place();
     }
     assert_eq!(
         a,
@@ -799,21 +799,21 @@ fn test_fq_repr_div2() {
         ])
     );
     for _ in 0..300 {
-        a.div2();
+        a.div2_in_place();
     }
     assert_eq!(
         a,
         BigInt::new([0x7288af1f36ee3608, 0x1e8, 0x0, 0x0, 0x0, 0x0])
     );
     for _ in 0..50 {
-        a.div2();
+        a.div2_in_place();
     }
     assert_eq!(a, BigInt::new([0x7a1ca2, 0x0, 0x0, 0x0, 0x0, 0x0]));
     for _ in 0..22 {
-        a.div2();
+        a.div2_in_place();
     }
     assert_eq!(a, BigInt::new([0x1, 0x0, 0x0, 0x0, 0x0, 0x0]));
-    a.div2();
+    a.div2_in_place();
     assert!(a.is_zero());
 }
 
@@ -885,31 +885,31 @@ fn test_fq_repr_shr() {
 #[test]
 fn test_fq_repr_mul2() {
     let mut a = BigInteger384::from(23712937547u64);
-    a.mul2();
+    a.mul2_in_place();
     assert_eq!(a, BigInt::new([0xb0acd6c96, 0x0, 0x0, 0x0, 0x0, 0x0]));
     for _ in 0..60 {
-        a.mul2();
+        a.mul2_in_place();
     }
     assert_eq!(
         a,
         BigInt::new([0x6000000000000000, 0xb0acd6c9, 0x0, 0x0, 0x0, 0x0])
     );
     for _ in 0..300 {
-        a.mul2();
+        a.mul2_in_place();
     }
     assert_eq!(
         a,
         BigInt::new([0x0, 0x0, 0x0, 0x0, 0x0, 0xcd6c960000000000])
     );
     for _ in 0..17 {
-        a.mul2();
+        a.mul2_in_place();
     }
     assert_eq!(
         a,
         BigInt::new([0x0, 0x0, 0x0, 0x0, 0x0, 0x2c00000000000000])
     );
     for _ in 0..6 {
-        a.mul2();
+        a.mul2_in_place();
     }
     assert!(a.is_zero());
 }
@@ -921,7 +921,7 @@ fn test_fq_repr_num_bits() {
     a = BigInteger384::from(1u64);
     for i in 1..385 {
         assert_eq!(i, a.num_bits());
-        a.mul2();
+        a.mul2_in_place();
     }
     assert_eq!(0, a.num_bits());
 }
@@ -938,7 +938,7 @@ fn test_fq_repr_sub_noborrow() {
         0xad0eb3948a5c34fd,
         0xd56f7b5ab8b5ce8,
     ]);
-    t.sub_with_borrow(&BigInt::new([
+    t.sub_with_borrow_in_place(&BigInt::new([
         0xc7867917187ca02b,
         0x5d75679d4911ffef,
         0x8c5b3e48b1a71c15,
@@ -962,23 +962,23 @@ fn test_fq_repr_sub_noborrow() {
         a.0[5] >>= 30;
         let mut b = a;
         for _ in 0..10 {
-            b.mul2();
+            b.mul2_in_place();
         }
         let mut c = b;
         for _ in 0..10 {
-            c.mul2();
+            c.mul2_in_place();
         }
 
         assert!(a < b);
         assert!(b < c);
 
         let mut csub_ba = c;
-        csub_ba.sub_with_borrow(&b);
-        csub_ba.sub_with_borrow(&a);
+        csub_ba.sub_with_borrow_in_place(&b);
+        csub_ba.sub_with_borrow_in_place(&a);
 
         let mut csub_ab = c;
-        csub_ab.sub_with_borrow(&a);
-        csub_ab.sub_with_borrow(&b);
+        csub_ab.sub_with_borrow_in_place(&a);
+        csub_ab.sub_with_borrow_in_place(&b);
 
         assert_eq!(csub_ab, csub_ba);
     }
@@ -992,7 +992,7 @@ fn test_fq_repr_sub_noborrow() {
         0x4b1ba7b6434bacd7,
         0x1a0111ea397fe69a,
     ]);
-    qplusone.sub_with_borrow(&BigInt::new([
+    qplusone.sub_with_borrow_in_place(&BigInt::new([
         0xb9feffffffffaaac,
         0x1eabfffeb153ffff,
         0x6730d2a0f6b0f624,
@@ -1025,7 +1025,7 @@ fn test_fq_repr_add_nocarry() {
         0xad0eb3948a5c34fd,
         0xd56f7b5ab8b5ce8,
     ]);
-    t.add_with_carry(&BigInt::new([
+    t.add_with_carry_in_place(&BigInt::new([
         0xc7867917187ca02b,
         0x5d75679d4911ffef,
         0x8c5b3e48b1a71c15,
@@ -1056,28 +1056,28 @@ fn test_fq_repr_add_nocarry() {
         c.0[5] >>= 3;
 
         let mut abc = a;
-        abc.add_with_carry(&b);
-        abc.add_with_carry(&c);
+        abc.add_with_carry_in_place(&b);
+        abc.add_with_carry_in_place(&c);
 
         let mut acb = a;
-        acb.add_with_carry(&c);
-        acb.add_with_carry(&b);
+        acb.add_with_carry_in_place(&c);
+        acb.add_with_carry_in_place(&b);
 
         let mut bac = b;
-        bac.add_with_carry(&a);
-        bac.add_with_carry(&c);
+        bac.add_with_carry_in_place(&a);
+        bac.add_with_carry_in_place(&c);
 
         let mut bca = b;
-        bca.add_with_carry(&c);
-        bca.add_with_carry(&a);
+        bca.add_with_carry_in_place(&c);
+        bca.add_with_carry_in_place(&a);
 
         let mut cab = c;
-        cab.add_with_carry(&a);
-        cab.add_with_carry(&b);
+        cab.add_with_carry_in_place(&a);
+        cab.add_with_carry_in_place(&b);
 
         let mut cba = c;
-        cba.add_with_carry(&b);
-        cba.add_with_carry(&a);
+        cba.add_with_carry_in_place(&b);
+        cba.add_with_carry_in_place(&a);
 
         assert_eq!(abc, acb);
         assert_eq!(abc, bac);
@@ -1095,7 +1095,7 @@ fn test_fq_repr_add_nocarry() {
         0xffffffffffffffff,
         0xffffffffffffffff,
     ]);
-    x.add_with_carry(&BigInteger384::from(1u64));
+    x.add_with_carry_in_place(&BigInteger384::from(1u64));
     assert!(x.is_zero());
 }
 

curves/bn254/src/fields/tests.rs

@@ -48,7 +48,7 @@ fn test_fq_repr_num_bits() {
     a = BigInteger256::from(1u64);
     for i in 1..257 {
         assert_eq!(i, a.num_bits());
-        a.mul2();
+        a.mul2_in_place();
     }
     assert_eq!(0, a.num_bits());
 }

ff-macros/src/montgomery/double.rs

@@ -2,14 +2,14 @@ pub(super) fn double_in_place_impl(modulus_has_spare_bit: bool) -> proc_macro2::
     if modulus_has_spare_bit {
         quote::quote! {
             // This cannot exceed the backing capacity.
-            a.0.mul2();
+            a.0.mul2_in_place();
             // However, it may need to be reduced.
             __subtract_modulus(a);
         }
     } else {
         quote::quote! {
             // This cannot exceed the backing capacity.
-            let c = a.0.mul2();
+            let c = a.0.mul2_in_place();
             // However, it may need to be reduced.
             __subtract_modulus_with_carry(a, c);
         }

ff-macros/src/montgomery/mod.rs

@@ -69,8 +69,8 @@ pub fn mont_config_helper(
     };
     let modulus = quote::quote! { BigInt([ #( #modulus_limbs ),* ]) };
 
-    let add_with_carry = add_with_carry_impl(limbs);
-    let sub_with_borrow = sub_with_borrow_impl(limbs);
+    let add_with_carry_in_place = add_with_carry_impl(limbs);
+    let sub_with_borrow_in_place = sub_with_borrow_impl(limbs);
     let subtract_modulus = subtract_modulus_impl(&modulus);
     let add_assign = add_assign_impl(modulus_has_spare_bit);
     let double_in_place = double_in_place_impl(modulus_has_spare_bit);
@@ -165,9 +165,9 @@ pub fn mont_config_helper(
 
             #subtract_modulus
 
-            #add_with_carry
+            #add_with_carry_in_place
 
-            #sub_with_borrow
+            #sub_with_borrow_in_place
         }
     }
 }

ff/src/biginteger/arithmetic.rs

@@ -149,7 +149,7 @@ pub fn find_naf(num: &[u64]) -> Vec<i8> {
             carry = adc(a, b, carry);
         }
     };
-    let div2 = |num: &mut [u64]| {
+    let div2_in_place = |num: &mut [u64]| {
         let mut t = 0;
         for i in num.iter_mut().rev() {
             let t2 = *i << 63;
@@ -175,7 +175,7 @@ pub fn find_naf(num: &[u64]) -> Vec<i8> {
             z = 0;
         }
         res.push(z);
-        div2(&mut num);
+        div2_in_place(&mut num);
     }
 
     res