diff --git a/api/next/59488.txt b/api/next/59488.txt new file mode 100644 index 00000000000..b94a4646f12 --- /dev/null +++ b/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 diff --git a/src/cmp/cmp.go b/src/cmp/cmp.go new file mode 100644 index 00000000000..3da8ff45705 --- /dev/null +++ b/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 +} diff --git a/src/cmp/cmp_test.go b/src/cmp/cmp_test.go new file mode 100644 index 00000000000..b0c0dc3fbde --- /dev/null +++ b/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) + } + } +} diff --git a/src/go/build/deps_test.go b/src/go/build/deps_test.go index 89c7035d356..056c9667f23 100644 --- a/src/go/build/deps_test.go +++ b/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, diff --git a/src/go/doc/comment/std.go b/src/go/doc/comment/std.go index 7548619cbcd..fd8c8ce3c23 100644 --- a/src/go/doc/comment/std.go +++ b/src/go/doc/comment/std.go @@ -10,6 +10,7 @@ package comment var stdPkgs = []string{ "bufio", "bytes", + "cmp", "context", "crypto", "embed",