From af8748054b40e9a1e529e42a0f83cc2c90a35af6 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Thu, 15 Oct 2020 12:09:56 -0400 Subject: sort: update comments - Describe requirements on Less more precisely. - Standardize on x for the variable name of the data being sorted (was variously a, p, slice). - Many other minor wording changes. Fixes #41951. Change-Id: Ic9e222a53ec035fcc3b5ddfc7f0eefbe1bb2890d Reviewed-on: https://go-review.googlesource.com/c/go/+/262657 Trust: Russ Cox Run-TryBot: Russ Cox Reviewed-by: Rob Pike --- src/sort/slice.go | 40 ++++++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 18 deletions(-) (limited to 'src/sort/slice.go') diff --git a/src/sort/slice.go b/src/sort/slice.go index 1f42c2a3fd..992ad1559d 100644 --- a/src/sort/slice.go +++ b/src/sort/slice.go @@ -4,34 +4,38 @@ package sort -// Slice sorts the provided slice given the provided less function. +// Slice sorts the slice x given the provided less function. +// It panics if x is not a slice. // -// The sort is not guaranteed to be stable. For a stable sort, use -// SliceStable. +// The sort is not guaranteed to be stable: equal elements +// may be reversed from their original order. +// For a stable sort, use SliceStable. // -// The function panics if the provided interface is not a slice. -func Slice(slice interface{}, less func(i, j int) bool) { - rv := reflectValueOf(slice) - swap := reflectSwapper(slice) +// The less function must satisfy the same requirements as +// the Interface type's Less method. +func Slice(x interface{}, less func(i, j int) bool) { + rv := reflectValueOf(x) + swap := reflectSwapper(x) length := rv.Len() quickSort_func(lessSwap{less, swap}, 0, length, maxDepth(length)) } -// SliceStable sorts the provided slice given the provided less -// function while keeping the original order of equal elements. +// SliceStable sorts the slice x using the provided less +// function, keeping equal elements in their original order. +// It panics if x is not a slice. // -// The function panics if the provided interface is not a slice. -func SliceStable(slice interface{}, less func(i, j int) bool) { - rv := reflectValueOf(slice) - swap := reflectSwapper(slice) +// The less function must satisfy the same requirements as +// the Interface type's Less method. +func SliceStable(x interface{}, less func(i, j int) bool) { + rv := reflectValueOf(x) + swap := reflectSwapper(x) stable_func(lessSwap{less, swap}, rv.Len()) } -// SliceIsSorted tests whether a slice is sorted. -// -// The function panics if the provided interface is not a slice. -func SliceIsSorted(slice interface{}, less func(i, j int) bool) bool { - rv := reflectValueOf(slice) +// SliceIsSorted reports whether the slice x is sorted according to the provided less function. +// It panics if x is not a slice. +func SliceIsSorted(x interface{}, less func(i, j int) bool) bool { + rv := reflectValueOf(x) n := rv.Len() for i := n - 1; i > 0; i-- { if less(i, i-1) { -- cgit v1.3