From fbf62beb4ed00bd4f93cf64316757be065c4249b Mon Sep 17 00:00:00 2001
From: alandonovan <adonovan@google.com>
Date: Tue, 13 Oct 2020 16:22:29 -0400
Subject: [PATCH] sort: document requirements of Less relation
Fixes #34915
Change-Id: Ia62ff3b6f198ddcd79e8afc7b4f5514a44f2442c
Reviewed-on: https://go-review.googlesource.com/c/go/+/261959
Reviewed-by: Rob Pike <r@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Akhil Indurti <aindurti@gmail.com>
Trust: Alberto Donizetti <alb.donizetti@gmail.com>
---
src/sort/sort.go | 11 +++++++++--
1 file changed, 9 insertions(+), 2 deletions(-)
diff --git a/src/sort/sort.go b/src/sort/sort.go
index dd5bb3762e3..4b3916e8a5a 100644
--- a/src/sort/sort.go
+++ b/src/sort/sort.go
@@ -11,6 +11,12 @@ package sort
// A type, typically a collection, that satisfies sort.Interface can be
// sorted by the routines in this package. The methods require that the
// elements of the collection be enumerated by an integer index.
+//
+// The sort routines require that the Less method implements a strict weak
+// ordering; see https://en.wikipedia.org/wiki/Weak_ordering.
+// The < operations on ints and strings are examples of such an ordering,
+// whereas the < operation on floating-point numbers is not, due to the
+// behavior of not-a-number (NaN) values.
type Interface interface {
// Len is the number of elements in the collection.
Len() int
@@ -275,8 +281,9 @@ func (p IntSlice) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
// Sort is a convenience method.
func (p IntSlice) Sort() { Sort(p) }
-// Float64Slice attaches the methods of Interface to []float64, sorting in increasing order
-// (not-a-number values are treated as less than other values).
+// Float64Slice attaches the methods of Interface to []float64, sorting in increasing order.
+// In order to satisfy the ordering requirements of the Less method, not-a-number (NaN)
+// values are treated as less than other values.
type Float64Slice []float64
func (p Float64Slice) Len() int { return len(p) }
--
GitLab