cmp: new package

The new cmp package provides types and functions related to
comparing ordered values.

For #59488

Change-Id: I43f4b2e6036f63b87c2152672d2b6fa18235cbeb
Reviewed-on: https://go-review.googlesource.com/c/go/+/496356
Run-TryBot: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Russ Cox <rsc@golang.org>
Reviewed-by: Eli Bendersky‎ <eliben@golang.org>
Auto-Submit: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Robert Griesemer <gri@google.com>

api/next/59488.txt

@@ -0,0 +1,3 @@
+pkg cmp, func Compare[$0 Ordered]($0, $0) int #59488
+pkg cmp, func Less[$0 Ordered]($0, $0) bool #59488
+pkg cmp, type Ordered interface {} #59488

src/cmp/cmp.go

@@ -0,0 +1,54 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package cmp provides types and functions related to comparing
+// ordered values.
+package cmp
+
+// Ordered is a constraint that permits any ordered type: any type
+// that supports the operators < <= >= >.
+// If future releases of Go add new ordered types,
+// this constraint will be modified to include them.
+type Ordered interface {
+	~int | ~int8 | ~int16 | ~int32 | ~int64 |
+		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
+		~float32 | ~float64 |
+		~string
+}
+
+// Less reports whether x is less than y.
+// For floating-point types, a NaN is considered less than any non-NaN,
+// and -0.0 is not less than (is equal to) 0.0.
+func Less[T Ordered](x, y T) bool {
+	return (isNaN(x) && !isNaN(y)) || x < y
+}
+
+// Compare returns
+//
+//	-1 if x is less than y,
+//	 0 if x equals y,
+//	+1 if x is greater than y.
+//
+// For floating-point types, a NaN is considered less than any non-NaN,
+// a NaN is considered equal to a NaN, and -0.0 is equal to 0.0.
+func Compare[T Ordered](x, y T) int {
+	xNaN := isNaN(x)
+	yNaN := isNaN(y)
+	if xNaN && yNaN {
+		return 0
+	}
+	if xNaN || x < y {
+		return -1
+	}
+	if yNaN || x > y {
+		return +1
+	}
+	return 0
+}
+
+// isNaN reports whether x is a NaN without requiring the math package.
+// This will always return false if T is not floating-point.
+func isNaN[T Ordered](x T) bool {
+	return x != x
+}

src/cmp/cmp_test.go

@@ -0,0 +1,95 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package cmp_test
+
+import (
+	"cmp"
+	"math"
+	"sort"
+	"testing"
+)
+
+var negzero = math.Copysign(0, -1)
+
+var tests = []struct {
+	x, y    any
+	compare int
+}{
+	{1, 2, -1},
+	{1, 1, 0},
+	{2, 1, +1},
+	{"a", "aa", -1},
+	{"a", "a", 0},
+	{"aa", "a", +1},
+	{1.0, 1.1, -1},
+	{1.1, 1.1, 0},
+	{1.1, 1.0, +1},
+	{math.Inf(1), math.Inf(1), 0},
+	{math.Inf(-1), math.Inf(-1), 0},
+	{math.Inf(-1), 1.0, -1},
+	{1.0, math.Inf(-1), +1},
+	{math.Inf(1), 1.0, +1},
+	{1.0, math.Inf(1), -1},
+	{math.NaN(), math.NaN(), 0},
+	{0.0, math.NaN(), +1},
+	{math.NaN(), 0.0, -1},
+	{math.NaN(), math.Inf(-1), -1},
+	{math.Inf(-1), math.NaN(), +1},
+	{0.0, 0.0, 0},
+	{negzero, negzero, 0},
+	{negzero, 0.0, 0},
+	{0.0, negzero, 0},
+	{negzero, 1.0, -1},
+	{negzero, -1.0, +1},
+}
+
+func TestLess(t *testing.T) {
+	for _, test := range tests {
+		var b bool
+		switch test.x.(type) {
+		case int:
+			b = cmp.Less(test.x.(int), test.y.(int))
+		case string:
+			b = cmp.Less(test.x.(string), test.y.(string))
+		case float64:
+			b = cmp.Less(test.x.(float64), test.y.(float64))
+		}
+		if b != (test.compare < 0) {
+			t.Errorf("Less(%v, %v) == %t, want %t", test.x, test.y, b, test.compare < 0)
+		}
+	}
+}
+
+func TestCompare(t *testing.T) {
+	for _, test := range tests {
+		var c int
+		switch test.x.(type) {
+		case int:
+			c = cmp.Compare(test.x.(int), test.y.(int))
+		case string:
+			c = cmp.Compare(test.x.(string), test.y.(string))
+		case float64:
+			c = cmp.Compare(test.x.(float64), test.y.(float64))
+		}
+		if c != test.compare {
+			t.Errorf("Compare(%v, %v) == %d, want %d", test.x, test.y, c, test.compare)
+		}
+	}
+}
+
+func TestSort(t *testing.T) {
+	// Test that our comparison function is consistent with
+	// sort.Float64s.
+	input := []float64{1.0, 0.0, negzero, math.Inf(1), math.Inf(-1), math.NaN()}
+	sort.Float64s(input)
+	for i := 0; i < len(input)-1; i++ {
+		if cmp.Less(input[i+1], input[i]) {
+			t.Errorf("Less sort mismatch at %d in %v", i, input)
+		}
+		if cmp.Compare(input[i], input[i+1]) > 0 {
+			t.Errorf("Compare sort mismatch at %d in %v", i, input)
+		}
+	}
+}

src/go/build/deps_test.go

@@ -39,7 +39,7 @@ import (
 var depsRules = `
 	# No dependencies allowed for any of these packages.
 	NONE
-	< constraints, container/list, container/ring,
+	< cmp, container/list, container/ring,
 	  internal/cfg, internal/coverage, internal/coverage/rtcov,
 	  internal/coverage/uleb128, internal/coverage/calloc,
 	  internal/cpu, internal/goarch, internal/godebugs,

src/go/doc/comment/std.go

@@ -10,6 +10,7 @@ package comment
 var stdPkgs = []string{
 	"bufio",
 	"bytes",
+	"cmp",
 	"context",
 	"crypto",
 	"embed",