cmp

cmp.Compare, Less, and Or, including the official NaN rules and the meaning of Or for zero values, checked on Go 1.24.0.

模块页正文目前为英文。

The cmp package, added in Go 1.21, provides Compare, Less, and Or for ordered or comparable values. It is the constraint used by slices.Sort and related helpers. This page documents Compare and Or; it does not rewrite the slices or sort pages.

Examples were run against Go 1.24.0.

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
cmp.Compare and cmp.LessCompare returns -1, 0, or +1. For floats, NaN equals NaN and is less than every non-NaN; -0.0 equals 0.0.
cmp.OrOr returns the first non-zero argument, or the zero value if every argument is zero.

Compare, Less, and NaN

Compare[T Ordered](x, y T) returns -1 if x is less than y, 0 if x equals y, and +1 if x is greater than y. Less reports whether x is less than y.

For floating-point types, official documentation defines a consistent order that ordinary < and == do not: 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. IEEE operators report false when comparing a NaN with any value, including another NaN. Use Compare when you need an ordering that includes NaNs.

cmp.Compare and cmp.Less

func Compare[T Ordered](x, y T) int
func Less[T Ordered](x, y T) bool
type Ordered interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
		~float32 | ~float64 |
		~string
}

Compare returns -1, 0, or +1. For floats, NaN equals NaN and is less than every non-NaN; -0.0 equals 0.0.

ParameterDescription
x, yValues of an Ordered type: signed and unsigned integers, floats, or strings, including named types whose underlying type is one of those.

Returns: Compare returns an int in {-1, 0, +1}. Less returns whether x is less than y under the same rules.

  • math.NaN() compared with 0.0 yields -1; 0.0 compared with NaN yields +1; two NaNs yield 0. math.Copysign(0, -1) compared with 0.0 yields 0.
go
package main

import (
	"cmp"
	"fmt"
	"math"
)

func main() {
	fmt.Println(cmp.Compare(1, 2), cmp.Compare(2, 2), cmp.Compare(3, 2))
	fmt.Println(cmp.Less(1, 2), cmp.Less(2, 1), cmp.Less(2, 2))
	nan := math.NaN()
	fmt.Println(cmp.Compare(nan, 0.0), cmp.Compare(0.0, nan), cmp.Compare(nan, nan))
	fmt.Println(cmp.Compare(math.Copysign(0, -1), 0.0))
}

Expected output

-1 0 1
true false false
-1 1 0
0

Related: slices.Sort, sort, Official cmp.Compare

Official documentation →

Or and the zero value

Or[T comparable](vals ...T) returns the first argument that is not equal to the zero value of T. If every argument is the zero value, it returns the zero value. For strings that zero is ""; for integers it is 0. This is a zero-value check, not a general "first present optional" for types that cannot be compared, and not a special error-handling helper.

An empty string is skipped even if it was intentionally supplied. The last print in the example shows cmp.Or("", "") as a blank field, and cmp.Or(0, 0, 0) as 0.

cmp.Or

func Or[T comparable](vals ...T) T

Or returns the first non-zero argument, or the zero value if every argument is zero.

ParameterDescription
valsZero or more comparable values. The first value that is not T's zero value is returned.

Returns: A value of type T. If the argument list is empty or all arguments are zero, the result is the zero value of T.

  • cmp.Or("beta", "alpha") returns "beta" because a non-empty string is already non-zero, even if a later argument might look preferable.
go
package main

import (
	"cmp"
	"fmt"
)

func main() {
	fmt.Println(cmp.Or("", "alpha"), cmp.Or("beta", "alpha"), cmp.Or("", ""))
	fmt.Println(cmp.Or(0, 0, 5), cmp.Or(0, 0, 0))
}

Expected output

alpha beta 
5 0

Related: cmp.Compare, Official cmp.Or

Official documentation →