math.big: add mod_euclid() and mod_euclid_checked, similar to libgmp's mpz_mod(), add tests (#24764)

Author: tankf33der

vlib/math/big/big_test.v

@@ -300,6 +300,21 @@ const div_test_data = [
 ]
 // vfmt on
 
+struct ModEuclidTest {
+	dividend TestInteger
+	divisor  TestInteger
+	modulus  TestInteger
+}
+
+// vfmt off
+const mod_euclid_test_data = [
+	ModEuclidTest{-7, 3, 2},
+	ModEuclidTest{7, 3, 1},
+	ModEuclidTest{7, -3, 1},
+	ModEuclidTest{-7, -3, 2},
+]
+// vfmt on
+
 enum Comparison {
 	less    = -1
 	equal   = 0
@@ -655,6 +670,12 @@ fn test_mod() {
 	}
 }
 
+fn test_mod_euclid() {
+	for t in mod_euclid_test_data {
+		assert t.dividend.parse().mod_euclid(t.divisor.parse()) == t.modulus.parse()
+	}
+}
+
 fn test_mod_sign() {
 	for a in -10 .. 10 {
 		for b in -10 .. 10 {

vlib/math/big/integer.v

@@ -513,6 +513,33 @@ pub fn (dividend Integer) mod_checked(divisor Integer) !Integer {
 	return r
 }
 
+// modulo_euclid returns the result of mathematical modulus.
+// The result is always non-negative for positive `divisor`.
+//
+// WARNING: this method will panic if `divisor == 0`.
+@[inline]
+pub fn (dividend Integer) mod_euclid(divisor Integer) Integer {
+	r := dividend % divisor
+	if r < zero_int {
+		return r + divisor.abs()
+	} else {
+		return r
+	}
+}
+
+// mod_euclid_checked returns the result of mathematical modulus.
+// The result is always non-negative for positive `divisor`
+// or an error if `divisor == 0`.
+@[inline]
+pub fn (dividend Integer) mod_euclid_checked(divisor Integer) !Integer {
+	r := dividend.mod_checked(divisor)!
+	if r < zero_int {
+		return r + divisor.abs()
+	} else {
+		return r
+	}
+}
+
 // mask_bits is the equivalent of `a % 2^n` (only when `a >= 0`), however doing a full division
 // run for this would be a lot of work when we can simply "cut off" all bits to the left of
 // the `n`th bit.