slices: clarify MinFunc/MaxFunc result for equal elements

They should return the first of equal elements. No such clarification
is required for Min/Max as for them equal elements are indistinguishable.

For golang#60091

Change-Id: Iad58115d482add852c811e993131702b5b3bec5e
Reviewed-on: https://go-review.googlesource.com/c/go/+/505796
Run-TryBot: Ian Lance Taylor <[email protected]>
Reviewed-by: Eli Bendersky <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
Auto-Submit: Ian Lance Taylor <[email protected]>

Author: ianlancetaylor

src/slices/sort.go

@@ -70,7 +70,8 @@ func Min[S ~[]E, E cmp.Ordered](x S) E {
 }
 
 // MinFunc returns the minimal value in x, using cmp to compare elements.
-// It panics if x is empty.
+// It panics if x is empty. If there is more than one minimal element
+// according to the cmp function, MinFunc returns the first one.
 func MinFunc[S ~[]E, E any](x S, cmp func(a, b E) int) E {
 	if len(x) < 1 {
 		panic("slices.MinFunc: empty list")
@@ -99,7 +100,8 @@ func Max[S ~[]E, E cmp.Ordered](x S) E {
 }
 
 // MaxFunc returns the maximal value in x, using cmp to compare elements.
-// It panics if x is empty.
+// It panics if x is empty. If there is more than one maximal element
+// according to the cmp function, MaxFunc returns the first one.
 func MaxFunc[S ~[]E, E any](x S, cmp func(a, b E) int) E {
 	if len(x) < 1 {
 		panic("slices.MaxFunc: empty list")

src/slices/sort_test.go

@@ -173,6 +173,15 @@ func TestStability(t *testing.T) {
 	}
 }
 
+type S struct {
+	a int
+	b string
+}
+
+func cmpS(s1, s2 S) int {
+	return cmp.Compare(s1.a, s2.a)
+}
+
 func TestMinMax(t *testing.T) {
 	intCmp := func(a, b int) int { return a - b }
 
@@ -214,6 +223,25 @@ func TestMinMax(t *testing.T) {
 			}
 		})
 	}
+
+	svals := []S{
+		{1, "a"},
+		{2, "a"},
+		{1, "b"},
+		{2, "b"},
+	}
+
+	gotMin := MinFunc(svals, cmpS)
+	wantMin := S{1, "a"}
+	if gotMin != wantMin {
+		t.Errorf("MinFunc(%v) = %v, want %v", svals, gotMin, wantMin)
+	}
+
+	gotMax := MaxFunc(svals, cmpS)
+	wantMax := S{2, "a"}
+	if gotMax != wantMax {
+		t.Errorf("MaxFunc(%v) = %v, want %v", svals, gotMax, wantMax)
+	}
 }
 
 func TestMinMaxNaNs(t *testing.T) {