math.big: rework function naming and documentation (#18890)

Author: phoebe

vlib/crypto/ed25519/internal/edwards25519/element_test.v

@@ -364,7 +364,7 @@ fn (mut v Element) to_big_integer() big.Integer {
 
 // from_big_integer sets v = n, and returns v. The bit length of n must not exceed 256.
 fn (mut v Element) from_big_integer(n big.Integer) !Element {
-	if n.binary_str().len > 32 * 8 {
+	if n.bin_str().len > 32 * 8 {
 		return error('invalid edwards25519 element input size')
 	}
 	mut bytes, _ := n.bytes()

vlib/crypto/ed25519/internal/edwards25519/scalar_test.v

@@ -119,7 +119,7 @@ fn test_scalar_set_uniform_bytes() {
 	// mod, _ := new(big.Integer).SetString("27742317777372353535851937790883648493", 10)
 	mut mod := big.integer_from_string('27742317777372353535851937790883648493')!
 	// mod.Add(mod, new(big.Integer).Lsh(big.NewInt(1), 252))
-	mod = mod + big.integer_from_i64(1).lshift(252)
+	mod = mod + big.integer_from_i64(1).left_shift(252)
 
 	mut sc := generate_scalar(100)!
 	inp := rand.bytes(64)!

vlib/math/big/big.js.v

@@ -88,7 +88,7 @@ pub fn (a &Number) % (b &Number) Number {
 	return c
 }*/
 
-pub fn divmod(a &Number, b &Number) (Number, Number) {
+pub fn div_mod(a &Number, b &Number) (Number, Number) {
 	c := Number{}
 	d := Number{}
 	#c.value = a.val.value / b.val.value
@@ -97,6 +97,11 @@ pub fn divmod(a &Number, b &Number) (Number, Number) {
 	return c, d
 }
 
+[deprecated: 'use div_mod(a, b) instead']
+pub fn divmod(a &Number, b &Number) (Number, Number) {
+	return div_mod(a, b)
+}
+
 pub fn cmp(a &Number, b &Number) int {
 	res := 0
 
@@ -137,37 +142,62 @@ pub fn (a &Number) isqrt() Number {
 	return b
 }
 
+[deprecated: 'use bitwise_and(a, b) instead']
 pub fn b_and(a &Number, b &Number) Number {
+	return bitwise_and(a, b)
+}
+
+[deprecated: 'use bitwise_or(a, b) instead']
+pub fn b_or(a &Number, b &Number) Number {
+	return bitwise_or(a, b)
+}
+
+[deprecated: 'use bitwise_xor(a, b) instead']
+pub fn b_xor(a &Number, b &Number) Number {
+	return bitwise_xor(a, b)
+}
+
+pub fn bitwise_and(a &Number, b &Number) Number {
 	c := Number{}
 	#c.value = a.val.value & b.val.value
 
 	return c
 }
 
-pub fn b_or(a &Number, b &Number) Number {
+pub fn bitwise_or(a &Number, b &Number) Number {
 	c := Number{}
 	#c.value = a.val.value | b.val.value
 
 	return c
 }
 
-pub fn b_xor(a &Number, b &Number) Number {
+pub fn bitwise_xor(a &Number, b &Number) Number {
 	c := Number{}
 	#c.value = a.val.value ^ b.val.value
 
 	return c
 }
 
-pub fn (a &Number) lshift(nbits int) Number {
+[deprecated: 'use a.left_shift(amount) instead']
+pub fn (a &Number) lshift(amount int) Number {
+	return a.left_shift(amount)
+}
+
+[deprecated: 'use a.right_shift(amount) instead']
+pub fn (a &Number) rshift(amount int) Number {
+	return a.right_shift(amount)
+}
+
+pub fn (a &Number) left_shift(amount int) Number {
 	c := Number{}
-	#c.value = a.val.value << BigInt(+nbits)
+	#c.value = a.val.value << BigInt(+amount)
 
 	return c
 }
 
-pub fn (a &Number) rshift(nbits int) Number {
+pub fn (a &Number) right_shift(amount int) Number {
 	c := Number{}
-	#c.value = a.val.value << BigInt(+nbits)
+	#c.value = a.val.value << BigInt(+amount)
 
 	return c
 }
@@ -193,6 +223,11 @@ pub fn factorial(nn &Number) Number {
 	return a
 }
 
+[deprecated: 'use factorial_int instead']
 pub fn fact(n int) Number {
+	return factorial_int(n)
+}
+
+pub fn factorial_int(n int) Number {
 	return factorial(from_int(n))
 }

vlib/math/big/big_test.v

@@ -389,15 +389,15 @@ const factorial_test_data = [
 ]
 // vfmt on
 
-// for lshift and rshift
+// for left_shift and right_shift
 struct ShiftTest {
 	base     TestInteger
 	amount   u32
 	expected TestInteger
 }
 
 // vfmt off
-const lshift_test_data = [
+const left_shift_test_data = [
 	ShiftTest{ 45, 2, 45 * 4 },
 	ShiftTest{ 45, 3, 45 * 8 },
 	ShiftTest{ 45, 4, 45 * 16 },
@@ -406,7 +406,7 @@ const lshift_test_data = [
 	ShiftTest{ [u8(1), 1, 1], 56, [u8(1), 1, 1, 0, 0, 0, 0, 0, 0, 0] },
 ]
 
-const rshift_test_data = [
+const right_shift_test_data = [
 	ShiftTest{ 45, 3, 5 },
 	ShiftTest{ 0x13374956, 16, 0x1337 },
 	ShiftTest{ [u8(1), 1, 1, 0, 0, 0, 0, 0, 0, 0], 56, [u8(1), 1, 1] },
@@ -435,7 +435,7 @@ const bit_len_test_data = [
 	BitLenTest{ big.zero_int, 0 },
 	BitLenTest{ big.one_int, 1 },
 	BitLenTest{ u32(0xffffffff), 32 },
-	BitLenTest{ big.one_int.lshift(1239), 1240 },
+	BitLenTest{ big.one_int.left_shift(1239), 1240 },
 	BitLenTest{ '4338476092346017364013796407961305761039463198075691378460917856', 212 },
 ]
 // vfmt on
@@ -639,15 +639,15 @@ fn test_inc_and_dec() {
 	assert b == c
 }
 
-fn test_lshift() {
-	for t in lshift_test_data {
-		assert t.base.parse().lshift(t.amount) == t.expected.parse()
+fn test_left_shift() {
+	for t in left_shift_test_data {
+		assert t.base.parse().left_shift(t.amount) == t.expected.parse()
 	}
 }
 
-fn test_rshift() {
-	for t in rshift_test_data {
-		assert t.base.parse().rshift(t.amount) == t.expected.parse()
+fn test_right_shift() {
+	for t in right_shift_test_data {
+		assert t.base.parse().right_shift(t.amount) == t.expected.parse()
 	}
 }
 
@@ -693,7 +693,7 @@ fn test_isqrt() {
 }
 
 fn test_bitwise_ops() {
-	a := big.integer_from_int(1).lshift(512)
+	a := big.integer_from_int(1).left_shift(512)
 	b := a - big.one_int
 	assert a.bitwise_and(b) == big.zero_int
 	assert b.bitwise_xor(b) == big.zero_int
@@ -732,7 +732,7 @@ fn test_set_bit() {
 	a.set_bit(3, true)
 	assert a.int() == 40
 	a.set_bit(50, true)
-	assert a == big.one_int.lshift(50) + big.integer_from_int(40)
+	assert a == big.one_int.left_shift(50) + big.integer_from_int(40)
 	b := a
 	a.set_bit(100, false)
 	assert a == b

vlib/math/big/division_array_ops.v

@@ -34,9 +34,9 @@ fn binary_divide_array_by_array(operand_a []u32, operand_b []u32, mut quotient [
 
 	// align
 	if lead_zer_remainder < lead_zer_divisor {
-		lshift_in_place(mut divisor, lead_zer_divisor - lead_zer_remainder)
+		left_shift_in_place(mut divisor, lead_zer_divisor - lead_zer_remainder)
 	} else if lead_zer_remainder > lead_zer_divisor {
-		lshift_in_place(mut remainder, lead_zer_remainder - lead_zer_divisor)
+		left_shift_in_place(mut remainder, lead_zer_remainder - lead_zer_divisor)
 	}
 
 	$if debug {
@@ -47,13 +47,13 @@ fn binary_divide_array_by_array(operand_a []u32, operand_b []u32, mut quotient [
 			bit_set(mut quotient, bit_idx)
 			subtract_align_last_byte_in_place(mut remainder, divisor)
 		}
-		rshift_in_place(mut divisor, 1)
+		right_shift_in_place(mut divisor, 1)
 	}
 
 	// adjust
 	if lead_zer_remainder > lead_zer_divisor {
-		// rshift_in_place(mut quotient, lead_zer_remainder - lead_zer_divisor)
-		rshift_in_place(mut remainder, lead_zer_remainder - lead_zer_divisor)
+		// right_shift_in_place(mut quotient, lead_zer_remainder - lead_zer_divisor)
+		right_shift_in_place(mut remainder, lead_zer_remainder - lead_zer_divisor)
 	}
 	shrink_tail_zeros(mut remainder)
 	shrink_tail_zeros(mut quotient)
@@ -115,7 +115,7 @@ fn subtract_align_last_byte_in_place(mut a []u32, b []u32) {
 // there is no overflow. We know that the last bits are zero
 // and that n <= 32
 [direct_array_access; inline]
-fn lshift_in_place(mut a []u32, n u32) {
+fn left_shift_in_place(mut a []u32, n u32) {
 	mut carry := u32(0)
 	mut prec_carry := u32(0)
 	mask := ((u32(1) << n) - 1) << (32 - n)
@@ -130,7 +130,7 @@ fn lshift_in_place(mut a []u32, n u32) {
 // logical right shift without control because these digits have already been
 // shift left before
 [direct_array_access; inline]
-fn rshift_in_place(mut a []u32, n u32) {
+fn right_shift_in_place(mut a []u32, n u32) {
 	mut carry := u32(0)
 	mut prec_carry := u32(0)
 	mask := u32((1 << n) - 1)

vlib/math/big/division_array_ops_test.v

@@ -2,35 +2,35 @@ module big
 
 import rand
 
-fn test_lshift_in_place() {
+fn test_left_shift_in_place() {
 	mut a := [u32(1), 1, 1, 1, 1]
-	lshift_in_place(mut a, 1)
+	left_shift_in_place(mut a, 1)
 	assert a == [u32(2), 2, 2, 2, 2]
-	lshift_in_place(mut a, 7)
+	left_shift_in_place(mut a, 7)
 	assert a == [u32(256), 256, 256, 256, 256]
 	mut b := [u32(0x80000001), 0xc0000000, 0x80000000, 0x7fffffff]
-	lshift_in_place(mut b, 1)
+	left_shift_in_place(mut b, 1)
 	assert b == [u32(2), 0x80000001, 1, 0xffffffff]
 	mut c := [u32(0x00ffffff), 0xf0f0f0f0, 1, 0x3fffffff, 1]
-	lshift_in_place(mut c, 2)
+	left_shift_in_place(mut c, 2)
 	assert c == [u32(0x3fffffc), 0xc3c3c3c0, 7, 0xfffffffc, 4]
 }
 
-fn test_rshift_in_place() {
+fn test_right_shift_in_place() {
 	mut a := [u32(2), 2, 2, 2, 2]
-	rshift_in_place(mut a, 1)
+	right_shift_in_place(mut a, 1)
 	assert a == [u32(1), 1, 1, 1, 1]
 	a = [u32(256), 256, 256, 256, 256]
-	rshift_in_place(mut a, 7)
+	right_shift_in_place(mut a, 7)
 	assert a == [u32(2), 2, 2, 2, 2]
 	a = [u32(0), 0, 1]
-	rshift_in_place(mut a, 1)
+	right_shift_in_place(mut a, 1)
 	assert a == [u32(0), 0x80000000, 0]
 	mut b := [u32(3), 0x80000001, 1, 0xffffffff]
-	rshift_in_place(mut b, 1)
+	right_shift_in_place(mut b, 1)
 	assert b == [u32(0x80000001), 0xc0000000, 0x80000000, 0x7fffffff]
 	mut c := [u32(0x03ffffff), 0xc3c3c3c0, 7, 0xfffffffc, 4]
-	rshift_in_place(mut c, 2)
+	right_shift_in_place(mut c, 2)
 	assert c == [u32(0x00ffffff), 0xf0f0f0f0, 1, 0x3fffffff, 1]
 }
 

vlib/math/big/exponentiation.v

@@ -29,8 +29,8 @@ fn (m Integer) montgomery() MontgomeryContext {
 		// ri := multiplicative inverse of r in the ring Z/nZ
 		// ri * r == 1 (mod n)
 		// ni = ((ri * 2^(log_2(n))) - 1) / n
-		ni: (one_int.lshift(b).mod_inv(n).lshift(b) - one_int) / n
-		rr: one_int.lshift(b * 2) % n
+		ni: (one_int.left_shift(b).mod_inv(n).left_shift(b) - one_int) / n
+		rr: one_int.left_shift(b * 2) % n
 	}
 }
 
@@ -164,7 +164,7 @@ fn (a Integer) mont_even(x Integer, m Integer) Integer {
 	}
 
 	m1, j := m.rsh_to_set_bit()
-	m2 := one_int.lshift(j)
+	m2 := one_int.left_shift(j)
 
 	$if debug {
 		assert m1 * m2 == m
@@ -321,7 +321,7 @@ fn (a Integer) to_mont(ctx MontgomeryContext) Integer {
 fn (a Integer) from_mont(ctx MontgomeryContext) Integer {
 	log2n := u32(ctx.n.bit_len())
 
-	r := (a + ((a.mask_bits(log2n) * ctx.ni).mask_bits(log2n) * ctx.n)).rshift(log2n)
+	r := (a + ((a.mask_bits(log2n) * ctx.ni).mask_bits(log2n) * ctx.n)).right_shift(log2n)
 
 	return if r.abs_cmp(ctx.n) >= 0 {
 		r - ctx.n