From 20548b153f05528c0c58347a817fb3a3eee6cd0c Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Fri, 2 Nov 2012 16:17:34 -0700 Subject: [PATCH] sort: make return value for 'not found' clearer in docs It was well-defined but easy to miss that the return value for "not found" is len(input) not -1 as many expect. Fixes #4205. R=golang-dev, dsymonds CC=golang-dev https://golang.org/cl/6820080 --- src/pkg/sort/search.go | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/pkg/sort/search.go b/src/pkg/sort/search.go index 66e6636446..1eb22fabeb 100644 --- a/src/pkg/sort/search.go +++ b/src/pkg/sort/search.go @@ -12,6 +12,8 @@ package sort // f is false for some (possibly empty) prefix of the input range [0, n) // and then true for the (possibly empty) remainder; Search returns // the first true index. If there is no such index, Search returns n. +// (Note that the "not found" return value is n, the length of the input, +// not -1 as in, for instance, strings.Index). // Search calls f(i) only for i in the range [0, n). // // A common use of Search is to find the index i for a value x in @@ -74,21 +76,24 @@ func Search(n int, f func(int) bool) int { // Convenience wrappers for common cases. // SearchInts searches for x in a sorted slice of ints and returns the index -// as specified by Search. The slice must be sorted in ascending order. +// as specified by Search. The return value is len(a) if x is not present. +// The slice must be sorted in ascending order. // func SearchInts(a []int, x int) int { return Search(len(a), func(i int) bool { return a[i] >= x }) } // SearchFloat64s searches for x in a sorted slice of float64s and returns the index -// as specified by Search. The slice must be sorted in ascending order. +// as specified by Search. The return value is len(a) if x is not present. +// The slice must be sorted in ascending order. // func SearchFloat64s(a []float64, x float64) int { return Search(len(a), func(i int) bool { return a[i] >= x }) } // SearchStrings searches for x in a sorted slice of strings and returns the index -// as specified by Search. The slice must be sorted in ascending order. +// as specified by Search. The return value is len(a) if x is not present. +// The slice must be sorted in ascending order. // func SearchStrings(a []string, x string) int { return Search(len(a), func(i int) bool { return a[i] >= x }) -- 2.48.1