Package sort

Overview ▹

Overview ▾

This is a copy of the Go standard library's sort package with the
addition of some helpers for sorting slices and using func literals
to sort, rather than having to create a sorter type. See the
additional MakeInterface, SliceSorter, and Slice functions.
Discussion of moving such helpers into the standard library is
at:

ExampleMultiKeys demonstrates a technique for sorting a struct type using different
sets of multiple fields in the comparison. We chain together "Less" functions, each of
which compares a single field.

Examples

Package files

Internal call graph ▹

Internal call graph ▾

In the call graph viewer below, each node
is a function belonging to this package
and its children are the functions it
calls—perhaps dynamically.

The root nodes are the entry points of the
package: functions that may be called from
outside the package.
There may be non-exported or anonymous
functions among them if they are called
dynamically from another package.

Click a node to visit that function's source code.
From there you can visit its callers by
clicking its declaring func
token.

Functions may be omitted if they were
determined to be unreachable in the
particular programs or tests that were
analyzed.

Search uses binary search to find and return the smallest index i
in [0, n) at which f(i) is true, assuming that on the range [0, n),
f(i) == true implies f(i+1) == true. That is, Search requires that
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 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
a sorted, indexable data structure such as an array or slice.
In this case, the argument f, typically a closure, captures the value
to be searched for, and how the data structure is indexed and
ordered.

For instance, given a slice data sorted in ascending order,
the call Search(len(data), func(i int) bool { return data[i] >= 23 })
returns the smallest index i such that data[i] >= 23. If the caller
wants to find whether 23 is in the slice, it must test data[i] == 23
separately.

Searching data sorted in descending order would use the <=
operator instead of the >= operator.

To complete the example above, the following code tries to find the value
x in an integer slice data sorted in ascending order:

x := 23
i := sort.Search(len(data), func(i int) bool { return data[i] >= x })
if i < len(data) && data[i] == x {
// x is present at data[i]
} else {
// x is not present in data,
// but i is the index where it would be inserted.
}

SearchFloat64s searches for x in a sorted slice of float64s and returns the index
as specified by Search. The return value is the index to insert x if x is not
present (it could be len(a)).
The slice must be sorted in ascending order.

SearchInts searches for x in a sorted slice of ints and returns the index
as specified by Search. The return value is the index to insert x if x is
not present (it could be len(a)).
The slice must be sorted in ascending order.

SearchStrings searches for x in a sorted slice of strings and returns the index
as specified by Search. The return value is the index to insert x if x is not
present (it could be len(a)).
The slice must be sorted in ascending order.

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.

type Interface interface {
// Len is the number of elements in the collection.
Len() int
// Less reports whether the element with// index i should sort before the element with index j.
Less(i, j int) bool
// Swap swaps the elements with indexes i and j.
Swap(i, j int)
}