math/big: add floor and ceiling division to Int

Adds methods Floor/FloorMod for floor division and Ceil/CeilMod for
ceiling division.

Fixes #76821

Author: arminguenther

api/next/76821.txt

@@ -0,0 +1,4 @@
+pkg math/big, method (*Int) Floor(*Int, *Int) *Int #76821
+pkg math/big, method (*Int) FloorMod(*Int, *Int, *Int) (*Int, *Int) #76821
+pkg math/big, method (*Int) Ceil(*Int, *Int) *Int #76821
+pkg math/big, method (*Int) CeilMod(*Int, *Int, *Int) (*Int, *Int) #76821

doc/next/6-stdlib/99-minor/math/big/76821.md

@@ -0,0 +1,2 @@
+<!-- go.dev/issue/76821 -->
+[Int] now has [Int.Floor], [Int.FloorMod], [Int.Ceil] and [Int.CeilMod] methods.

src/math/big/int.go

@@ -1308,3 +1308,86 @@ func (z *Int) Sqrt(x *Int) *Int {
 	z.abs = z.abs.sqrt(nil, x.abs)
 	return z
 }
+
+// Floor sets z to ⌊x/y⌋ for y != 0 and returns z.
+// If y == 0, a division-by-zero run-time panic occurs.
+// Floor implements floor division (unlike Go); see [Int.FloorMod] for more details.
+func (z *Int) Floor(x, y *Int) *Int {
+	y0 := y // save y
+	if z == y || alias(z.abs, y.abs) {
+		y0 = new(Int).Set(y)
+	}
+	var m Int
+	z.DivMod(x, y, &m)
+	if len(m.abs) == 0 || !y0.neg {
+		return z
+	}
+	z.Sub(z, intOne)
+	return z
+
+}
+
+// FloorMod sets z to ⌊x/y⌋ and m to x mod y
+// for y != 0 and returns the pair (z, m).
+// If y == 0, a division-by-zero run-time panic occurs.
+//
+// FloorMod implements floor division and modulus (unlike Go):
+//
+//	q = ⌊x/y⌋    and
+//	m = x - y*q  where  0 <= |m| < |y|,  sgn(m) = sgn(y)
+//
+// See [Int.QuoRem] for T-division and modulus (like Go).
+func (z *Int) FloorMod(x, y, m *Int) (*Int, *Int) {
+	y0 := y // save y
+	if z == y || alias(z.abs, y.abs) {
+		y0 = new(Int).Set(y)
+	}
+	z.DivMod(x, y, m)
+	if len(m.abs) == 0 || !y0.neg {
+		return z, m
+	}
+	z.Sub(z, intOne)
+	m.Add(m, y0)
+	return z, m
+}
+
+// Ceil sets z to ⌈x/y⌉ for y != 0 and returns z.
+// If y == 0, a division-by-zero run-time panic occurs.
+// Ceil implements ceiling division (unlike Go); see [Int.CeilMod] for more details.
+func (z *Int) Ceil(x, y *Int) *Int {
+	y0 := y // save y
+	if z == y || alias(z.abs, y.abs) {
+		y0 = new(Int).Set(y)
+	}
+	var m Int
+	z.DivMod(x, y, &m)
+	if len(m.abs) == 0 || y0.neg {
+		return z
+	}
+	z.Add(z, intOne)
+	return z
+}
+
+// CeilMod sets z to ⌈x/y⌉ and m to x mod y
+// for y != 0 and returns the pair (z, m).
+// If y == 0, a division-by-zero run-time panic occurs.
+//
+// CeilMod implements ceiling division and modulus (unlike Go):
+//
+//	q = ⌈x/y⌉    and
+//	m = x - y*q  where  0 <= |m| < |y|,  sgn(m) = -sgn(y)
+//
+// See [Int.QuoRem] for T-division and modulus (like Go).
+func (z *Int) CeilMod(x, y, m *Int) (*Int, *Int) {
+	y0 := y // save y
+	if z == y || alias(z.abs, y.abs) {
+		y0 = new(Int).Set(y)
+	}
+	z.DivMod(x, y, m)
+	if len(m.abs) == 0 || y0.neg {
+		return z, m
+	}
+	z.Add(z, intOne)
+	m.Sub(m, y0)
+	return z, m
+}

src/math/big/int_test.go

@@ -2010,3 +2010,75 @@ func TestFloat64(t *testing.T) {
 		}
 	}
 }
+
+func TestIntFloorMod(t *testing.T) {
+	for i, test := range []struct {
+		x, y, q, m int64
+	}{
+		{0, 1, 0, 0},
+		{0, -1, 0, 0},
+		{1, 1, 1, 0},
+		{1, -1, -1, 0},
+		{-1, 1, -1, 0},
+		{-1, -1, 1, 0},
+		{1, 3, 0, 1},
+		{-1, 3, -1, 2},
+		{1, -3, -1, -2},
+		{-1, -3, 0, -1},
+		// examples from spec#Arithmetic_operators
+		{5, 3, 1, 2},
+		{-5, 3, -2, 1},
+		{5, -3, -2, -1},
+		{-5, -3, 1, -2},
+		{1, 2, 0, 1},
+		{8, 4, 2, 0},
+	} {
+		if test.q*test.y+test.m != test.x {
+			t.Errorf("#%v invalid test, q*y + m != x", i)
+		}
+		x := NewInt(test.x)
+		y := NewInt(test.y)
+		m := new(Int)
+		q, _ := x.FloorMod(x, y, m)
+		if q.Cmp(NewInt(test.q)) != 0 || m.Cmp(NewInt(test.m)) != 0 {
+			t.Errorf("#%v got q=%v m=%v, want q=%v m=%v", i, q, m, test.q, test.m)
+		}
+	}
+
+}
+
+func TestIntCeilMod(t *testing.T) {
+	for i, test := range []struct {
+		x, y, q, m int64
+	}{
+		{0, 1, 0, 0},
+		{0, -1, 0, 0},
+		{1, 1, 1, 0},
+		{1, -1, -1, 0},
+		{-1, 1, -1, 0},
+		{-1, -1, 1, 0},
+		{1, 3, 1, -2},
+		{-1, 3, 0, -1},
+		{1, -3, 0, 1},
+		{-1, -3, 1, 2},
+		// examples from spec#Arithmetic_operators
+		{5, 3, 2, -1},
+		{-5, 3, -1, -2},
+		{5, -3, -1, 2},
+		{-5, -3, 2, 1},
+		{1, 2, 1, -1},
+		{8, 4, 2, 0},
+	} {
+		if test.q*test.y+test.m != test.x {
+			t.Errorf("#%v invalid test, q*y + m != x", i)
+		}
+		x := NewInt(test.x)
+		y := NewInt(test.y)
+		m := new(Int)
+		q, _ := x.CeilMod(x, y, m)
+		if q.Cmp(NewInt(test.q)) != 0 || m.Cmp(NewInt(test.m)) != 0 {
+			t.Errorf("#%v got q=%v m=%v, want q=%v m=%v", i, q, m, test.q, test.m)
+		}
+	}
+
+}