gofront 1.8.0 → 1.9.1

package/stdlib/sort/sort.go

@@ -2,28 +2,50 @@
 
 //gofront:target both
 
-// Overlay on the emitter-backed sort package: Interface, Sort (pdqsort),
-// Stable, Reverse, IsSorted, Search*, and *Slice types.
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package sort provides primitives for sorting slices and user-defined collections.
 package sort
 
+import "slices"
+
 // An implementation of Interface can be sorted by the routines in this package.
+// The methods refer to elements of the underlying collection by integer index.
 type Interface interface {
+	// Len is the number of elements in the collection.
 	Len() int
+
+	// Less reports whether the element with index i
+	// must sort before the element with index j.
+	//
+	// If both Less(i, j) and Less(j, i) are false,
+	// then the elements at index i and j are considered equal.
+	// Sort may place equal elements in any order in the final result,
+	// while Stable preserves the original input order of equal elements.
+	//
+	// Less must describe a [Strict Weak Ordering]. For example:
+	//  - if both Less(i, j) and Less(j, k) are true, then Less(i, k) must be true as well.
+	//  - if both Less(i, j) and Less(j, k) are false, then Less(i, k) must be false as well.
+	//
+	// Note that floating-point comparison (the < operator on float32 or float64 values)
+	// is not a strict weak ordering when not-a-number (NaN) values are involved.
+	// See Float64Slice.Less for a correct implementation for floating-point values.
+	//
+	// [Strict Weak Ordering]: https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings
 	Less(i, j int) bool
-	Swap(i, j int)
-}
 
-func bitsLen(n uint) int {
-	var l int
-	for n > 0 {
-		l++
-		n >>= 1
-	}
-	return l
+	// Swap swaps the elements with indexes i and j.
+	Swap(i, j int)
 }
 
 // Sort sorts data in ascending order as determined by the Less method.
-// It uses pattern-defeating quicksort (pdqsort) so equal-element order matches Go.
+// It makes one call to data.Len to determine n and O(n*log(n)) calls to
+// data.Less and data.Swap. The sort is not guaranteed to be stable.
+//
+// Note: in many situations, the newer [slices.SortFunc] function is more
+// ergonomic and runs faster.
 func Sort(data Interface) {
 	n := data.Len()
 	if n <= 1 {
@@ -33,45 +55,7 @@ func Sort(data Interface) {
 	pdqsort(data, 0, n, limit)
 }
 
-// Stable sorts data in ascending order as determined by the Less method,
-// while keeping the original order of equal elements.
-func Stable(data Interface) {
-	stable(data, data.Len())
-}
-
-// IsSorted reports whether data is sorted.
-func IsSorted(data Interface) bool {
-	n := data.Len()
-	for i := n - 1; i > 0; i-- {
-		if data.Less(i, i-1) {
-			return false
-		}
-	}
-	return true
-}
-
-type reverse struct {
-	data Interface
-}
-
-func (r *reverse) Len() int {
-	return r.data.Len()
-}
-
-func (r *reverse) Less(i, j int) bool {
-	return r.data.Less(j, i)
-}
-
-func (r *reverse) Swap(i, j int) {
-	r.data.Swap(i, j)
-}
-
-// Reverse returns the reverse order for data.
-func Reverse(data Interface) Interface {
-	return &reverse{data: data}
-}
-
-type sortedHint int
+type sortedHint int // hint for pdqsort when choosing the pivot
 
 const (
 	unknownHint sortedHint = iota
@@ -79,14 +63,7 @@ const (
 	decreasingHint
 )
 
-const (
-	maxInsertion     = 12
-	maxSteps         = 5
-	shortestShifting = 50
-	shortestNinther  = 50
-	maxSwaps         = 4 * 3
-)
-
+// xorshift paper: https://www.jstatsoft.org/article/view/v008i14/xorshift.pdf
 type xorshift uint64
 
 func (r *xorshift) Next() uint64 {
@@ -96,466 +73,428 @@ func (r *xorshift) Next() uint64 {
 	return uint64(*r)
 }
 
-func nextPowerOfTwo(length int) uint {
-	shift := uint(bitsLen(uint(length)))
-	return uint(1 << shift)
-}
-
-func insertionSort(data Interface, a, b int) {
-	for i := a + 1; i < b; i++ {
-		for j := i; j > a && data.Less(j, j-1); j-- {
-			data.Swap(j, j-1)
-		}
+// bitsLen is math/bits.Len for a uint.
+func bitsLen(n uint) int {
+	var l int
+	for n > 0 {
+		l++
+		n >>= 1
 	}
+	return l
 }
 
-func siftDown(data Interface, lo, hi, first int) {
-	root := lo
-	for {
-		child := 2*root + 1
-		if child >= hi {
-			break
-		}
-		if child+1 < hi && data.Less(first+child, first+child+1) {
-			child++
-		}
-		if !data.Less(first+root, first+child) {
-			return
-		}
-		data.Swap(first+root, first+child)
-		root = child
-	}
+func nextPowerOfTwo(length int) uint {
+	shift := uint(bitsLen(uint(length)))
+	return uint(1 << shift)
 }
 
-func heapSort(data Interface, a, b int) {
-	first := a
-	lo := 0
-	hi := b - a
-
-	for i := (hi - 1) / 2; i >= 0; i-- {
-		siftDown(data, i, hi, first)
-	}
-
-	for i := hi - 1; i >= 0; i-- {
-		data.Swap(first, first+i)
-		siftDown(data, lo, i, first)
-	}
+// lessSwap is a pair of Less and Swap function for use with the
+// auto-generated func-optimized variant of sort.go in
+// zfuncversion.go.
+type lessSwap struct {
+	Less func(i, j int) bool
+	Swap func(i, j int)
 }
 
-func pdqsort(data Interface, a, b, limit int) {
-	var (
-		wasBalanced    = true
-		wasPartitioned = true
-	)
-
-	for {
-		length := b - a
-
-		if length <= maxInsertion {
-			insertionSort(data, a, b)
-			return
-		}
-
-		if limit == 0 {
-			heapSort(data, a, b)
-			return
-		}
-
-		if !wasBalanced {
-			breakPatterns(data, a, b)
-			limit--
-		}
-
-		pivot, hint := choosePivot(data, a, b)
-		if hint == decreasingHint {
-			reverseRange(data, a, b)
-			pivot = (b - 1) - (pivot - a)
-			hint = increasingHint
-		}
-
-		if wasBalanced && wasPartitioned && hint == increasingHint {
-			if partialInsertionSort(data, a, b) {
-				return
-			}
-		}
-
-		if a > 0 && !data.Less(a-1, pivot) {
-			mid := partitionEqual(data, a, b, pivot)
-			a = mid
-			continue
-		}
-
-		mid, alreadyPartitioned := partition(data, a, b, pivot)
-		wasPartitioned = alreadyPartitioned
-
-		leftLen, rightLen := mid-a, b-mid
-		balanceThreshold := length / 8
-		if leftLen < rightLen {
-			wasBalanced = leftLen >= balanceThreshold
-			pdqsort(data, a, mid, limit)
-			a = mid + 1
-		} else {
-			wasBalanced = rightLen >= balanceThreshold
-			pdqsort(data, mid+1, b, limit)
-			b = mid
-		}
-	}
+type reverse struct {
+	// This embedded Interface permits Reverse to use the methods of
+	// another Interface implementation.
+	data Interface
 }
 
-func partition(data Interface, a, b, pivot int) (newpivot int, alreadyPartitioned bool) {
-	data.Swap(a, pivot)
-	i, j := a+1, b-1
-
-	for i <= j && data.Less(i, a) {
-		i++
-	}
-	for i <= j && !data.Less(j, a) {
-		j--
-	}
-	if i > j {
-		data.Swap(j, a)
-		return j, true
-	}
-	data.Swap(i, j)
-	i++
-	j--
+// Len is the number of elements in the collection.
+func (r *reverse) Len() int { return r.data.Len() }
 
-	for {
-		for i <= j && data.Less(i, a) {
-			i++
-		}
-		for i <= j && !data.Less(j, a) {
-			j--
-		}
-		if i > j {
-			break
-		}
-		data.Swap(i, j)
-		i++
-		j--
-	}
-	data.Swap(j, a)
-	return j, false
+// Less returns the opposite of the embedded implementation's Less method.
+func (r *reverse) Less(i, j int) bool {
+	return r.data.Less(j, i)
 }
 
-func partitionEqual(data Interface, a, b, pivot int) (newpivot int) {
-	data.Swap(a, pivot)
-	i, j := a+1, b-1
+// Swap swaps the elements with indexes i and j.
+func (r *reverse) Swap(i, j int) { r.data.Swap(i, j) }
 
-	for {
-		for i <= j && !data.Less(a, i) {
-			i++
-		}
-		for i <= j && data.Less(a, j) {
-			j--
-		}
-		if i > j {
-			break
-		}
-		data.Swap(i, j)
-		i++
-		j--
-	}
-	return i
+// Reverse returns the reverse order for data.
+func Reverse(data Interface) Interface {
+	return &reverse{data: data}
 }
 
-func partialInsertionSort(data Interface, a, b int) bool {
-	i := a + 1
-	for j := 0; j < maxSteps; j++ {
-		for i < b && !data.Less(i, i-1) {
-			i++
-		}
-
-		if i == b {
-			return true
-		}
-
-		if b-a < shortestShifting {
+// IsSorted reports whether data is sorted.
+//
+// Note: in many situations, the newer [slices.IsSortedFunc] function is more
+// ergonomic and runs faster.
+func IsSorted(data Interface) bool {
+	n := data.Len()
+	for i := n - 1; i > 0; i-- {
+		if data.Less(i, i-1) {
 			return false
 		}
-
-		data.Swap(i, i-1)
-
-		if i-a >= 2 {
-			for j := i - 1; j >= 1; j-- {
-				if !data.Less(j, j-1) {
-					break
-				}
-				data.Swap(j, j-1)
-			}
-		}
-		if b-i >= 2 {
-			for j := i + 1; j < b; j++ {
-				if !data.Less(j, j-1) {
-					break
-				}
-				data.Swap(j, j-1)
-			}
-		}
-	}
-	return false
-}
-
-func breakPatterns(data Interface, a, b int) {
-	length := b - a
-	if length >= 8 {
-		random := xorshift(length)
-		modulus := nextPowerOfTwo(length)
-
-		for idx := a + (length/4)*2 - 1; idx <= a+(length/4)*2+1; idx++ {
-			other := int(uint(random.Next()) & (modulus - 1))
-			if other >= length {
-				other -= length
-			}
-			data.Swap(idx, a+other)
-		}
 	}
+	return true
 }
 
-func choosePivot(data Interface, a, b int) (pivot int, hint sortedHint) {
-	l := b - a
-
-	var (
-		swaps int
-		i     = a + l/4*1
-		j     = a + l/4*2
-		k     = a + l/4*3
-	)
-
-	if l >= 8 {
-		if l >= shortestNinther {
-			i = medianAdjacent(data, i, &swaps)
-			j = medianAdjacent(data, j, &swaps)
-			k = medianAdjacent(data, k, &swaps)
-		}
-		j = median(data, i, j, k, &swaps)
-	}
+// Convenience types for common cases
 
-	switch swaps {
-	case 0:
-		return j, increasingHint
-	case maxSwaps:
-		return j, decreasingHint
-	default:
-		return j, unknownHint
-	}
-}
+// IntSlice attaches the methods of Interface to []int, sorting in increasing order.
+type IntSlice []int
 
-func order2(data Interface, a, b int, swaps *int) (int, int) {
-	if data.Less(b, a) {
-		*swaps++
-		return b, a
-	}
-	return a, b
-}
+func (x IntSlice) Len() int           { return len(x) }
+func (x IntSlice) Less(i, j int) bool { return x[i] < x[j] }
+func (x IntSlice) Swap(i, j int)      { x[i], x[j] = x[j], x[i] }
 
-func median(data Interface, a, b, c int, swaps *int) int {
-	a, b = order2(data, a, b, swaps)
-	b, c = order2(data, b, c, swaps)
-	a, b = order2(data, a, b, swaps)
-	return b
-}
+// Sort is a convenience method: x.Sort() calls Sort(x).
+func (x IntSlice) Sort() { Sort(x) }
 
-func medianAdjacent(data Interface, a int, swaps *int) int {
-	return median(data, a-1, a, a+1, swaps)
-}
+// Float64Slice implements Interface for a []float64, sorting in increasing order,
+// with not-a-number (NaN) values ordered before other values.
+type Float64Slice []float64
 
-func reverseRange(data Interface, a, b int) {
-	i := a
-	j := b - 1
-	for i < j {
-		data.Swap(i, j)
-		i++
-		j--
-	}
-}
+func (x Float64Slice) Len() int { return len(x) }
 
-func swapRange(data Interface, a, b, n int) {
-	for i := 0; i < n; i++ {
-		data.Swap(a+i, b+i)
-	}
-}
+// Less reports whether x[i] should be ordered before x[j], as required by the sort Interface.
+// Note that floating-point comparison by itself is not a transitive relation: it does not
+// report a consistent ordering for not-a-number (NaN) values.
+// This implementation of Less places NaN values before any others, by using:
+//
+//	x[i] < x[j] || (math.IsNaN(x[i]) && !math.IsNaN(x[j]))
+func (x Float64Slice) Less(i, j int) bool { return x[i] < x[j] || (isNaN(x[i]) && !isNaN(x[j])) }
+func (x Float64Slice) Swap(i, j int)      { x[i], x[j] = x[j], x[i] }
 
-func stable(data Interface, n int) {
-	blockSize := 20
-	a, b := 0, blockSize
-	for b <= n {
-		insertionSort(data, a, b)
-		a = b
-		b += blockSize
-	}
-	insertionSort(data, a, n)
-
-	for blockSize < n {
-		a, b = 0, 2*blockSize
-		for b <= n {
-			symMerge(data, a, a+blockSize, b)
-			a = b
-			b += 2 * blockSize
-		}
-		if m := a + blockSize; m < n {
-			symMerge(data, a, m, n)
-		}
-		blockSize *= 2
-	}
+// isNaN is a copy of math.IsNaN to avoid a dependency on the math package.
+func isNaN(f float64) bool {
+	return f != f
 }
 
-func symMergeBase(data Interface, a, m, b int) bool {
-	if m-a == 1 {
-		i := m
-		j := b
-		for i < j {
-			h := int(uint(i+j) >> 1)
-			if data.Less(h, a) {
-				i = h + 1
-			} else {
-				j = h
-			}
-		}
-		for k := a; k < i-1; k++ {
-			data.Swap(k, k+1)
-		}
-		return true
-	}
-
-	if b-m == 1 {
-		i := a
-		j := m
-		for i < j {
-			h := int(uint(i+j) >> 1)
-			if !data.Less(m, h) {
-				i = h + 1
-			} else {
-				j = h
-			}
-		}
-		for k := m; k > i; k-- {
-			data.Swap(k, k-1)
-		}
-		return true
-	}
-	return false
-}
+// Sort is a convenience method: x.Sort() calls Sort(x).
+func (x Float64Slice) Sort() { Sort(x) }
 
-func symMerge(data Interface, a, m, b int) {
-	if symMergeBase(data, a, m, b) {
-		return
-	}
+// StringSlice attaches the methods of Interface to []string, sorting in increasing order.
+type StringSlice []string
 
-	mid := int(uint(a+b) >> 1)
-	n := mid + m
-	var start, r int
-	if m > mid {
-		start = n - b
-		r = mid
-	} else {
-		start = a
-		r = m
-	}
-	p := n - 1
+func (x StringSlice) Len() int           { return len(x) }
+func (x StringSlice) Less(i, j int) bool { return x[i] < x[j] }
+func (x StringSlice) Swap(i, j int)      { x[i], x[j] = x[j], x[i] }
 
-	for start < r {
-		c := int(uint(start+r) >> 1)
-		if !data.Less(p-c, c) {
-			start = c + 1
-		} else {
-			r = c
-		}
-	}
+// Sort is a convenience method: x.Sort() calls Sort(x).
+func (x StringSlice) Sort() { Sort(x) }
+
+// Convenience wrappers for common cases
+
+// Ints sorts a slice of ints in increasing order.
+//
+// Note: as of Go 1.22, this function simply calls [slices.Sort].
+//gofront:native sort.Ints
+func Ints(x []int) { slices.Sort(x) }
+
+// Float64s sorts a slice of float64s in increasing order.
+// Not-a-number (NaN) values are ordered before other values.
+//
+// Note: as of Go 1.22, this function simply calls [slices.Sort].
+func Float64s(x []float64) { slices.Sort(x) }
+
+// Strings sorts a slice of strings in increasing order.
+//
+// Note: as of Go 1.22, this function simply calls [slices.Sort].
+//gofront:native sort.Strings
+func Strings(x []string) { slices.Sort(x) }
+
+// IntsAreSorted reports whether the slice x is sorted in increasing order.
+//
+// Note: as of Go 1.22, this function simply calls [slices.IsSorted].
+func IntsAreSorted(x []int) bool { return slices.IsSorted(x) }
+
+// Float64sAreSorted reports whether the slice x is sorted in increasing order,
+// with not-a-number (NaN) values before any other values.
+//
+// Note: as of Go 1.22, this function simply calls [slices.IsSorted].
+func Float64sAreSorted(x []float64) bool { return slices.IsSorted(x) }
+
+// StringsAreSorted reports whether the slice x is sorted in increasing order.
+//
+// Note: as of Go 1.22, this function simply calls [slices.IsSorted].
+func StringsAreSorted(x []string) bool { return slices.IsSorted(x) }
+
+// Notes on stable sorting:
+// The used algorithms are simple and provably correct on all input and use
+// only logarithmic additional stack space. They perform well if compared
+// experimentally to other stable in-place sorting algorithms.
+//
+// Remarks on other algorithms evaluated:
+//  - GCC's 4.6.3 stable_sort with merge_without_buffer from libstdc++:
+//    Not faster.
+//  - GCC's __rotate for block rotations: Not faster.
+//  - "Practical in-place mergesort" from  Jyrki Katajainen, Tomi A. Pasanen
+//    and Jukka Teuhola; Nordic Journal of Computing 3,1 (1996), 27-40:
+//    The given algorithms are in-place, number of Swap and Assignments
+//    grow as n log n but the algorithm is not stable.
+//  - "Fast Stable In-Place Sorting with O(n) Data Moves" J.I. Munro and
+//    V. Raman in Algorithmica (1996) 16, 115-160:
+//    This algorithm either needs additional 2n bits or works only if there
+//    are enough different elements available to encode some permutations
+//    which have to be undone later (so not stable on any input).
+//  - All the optimal in-place sorting/merging algorithms I found are either
+//    unstable or rely on enough different elements in each step to encode the
+//    performed block rearrangements. See also "In-Place Merging Algorithms",
+//    Denham Coates-Evely, Department of Computer Science, Kings College,
+//    January 2004 and the references in there.
+//  - Often "optimal" algorithms are optimal in the number of assignments
+//    but Interface has only Swap as operation.
 
-	end := n - start
-	if start < m && m < end {
-		rotate(data, start, m, end)
-	}
-	if a < start && start < mid {
-		symMerge(data, a, start, mid)
-	}
-	if mid < end && end < b {
-		symMerge(data, mid, end, b)
-	}
+// Stable sorts data in ascending order as determined by the Less method,
+// while keeping the original order of equal elements.
+//
+// It makes one call to data.Len to determine n, O(n*log(n)) calls to
+// data.Less and O(n*log(n)*log(n)) calls to data.Swap.
+//
+// Note: in many situations, the newer slices.SortStableFunc function is more
+// ergonomic and runs faster.
+func Stable(data Interface) {
+	stable(data, data.Len())
 }
 
-func rotate(data Interface, a, m, b int) {
-	i := m - a
-	j := b - m
-
-	for i != j {
-		if i > j {
-			swapRange(data, m-i, m, j)
-			i -= j
+/*
+Complexity of Stable Sorting
+
+
+Complexity of block swapping rotation
+
+Each Swap puts one new element into its correct, final position.
+Elements which reach their final position are no longer moved.
+Thus block swapping rotation needs |u|+|v| calls to Swaps.
+This is best possible as each element might need a move.
+
+Pay attention when comparing to other optimal algorithms which
+typically count the number of assignments instead of swaps:
+E.g. the optimal algorithm of Dudzinski and Dydek for in-place
+rotations uses O(u + v + gcd(u,v)) assignments which is
+better than our O(3 * (u+v)) as gcd(u,v) <= u.
+
+
+Stable sorting by SymMerge and BlockSwap rotations
+
+SymMerg complexity for same size input M = N:
+Calls to Less:  O(M*log(N/M+1)) = O(N*log(2)) = O(N)
+Calls to Swap:  O((M+N)*log(M)) = O(2*N*log(N)) = O(N*log(N))
+
+(The following argument does not fuzz over a missing -1 or
+other stuff which does not impact the final result).
+
+Let n = data.Len(). Assume n = 2^k.
+
+Plain merge sort performs log(n) = k iterations.
+On iteration i the algorithm merges 2^(k-i) blocks, each of size 2^i.
+
+Thus iteration i of merge sort performs:
+Calls to Less  O(2^(k-i) * 2^i) = O(2^k) = O(2^log(n)) = O(n)
+Calls to Swap  O(2^(k-i) * 2^i * log(2^i)) = O(2^k * i) = O(n*i)
+
+In total k = log(n) iterations are performed; so in total:
+Calls to Less O(log(n) * n)
+Calls to Swap O(n + 2*n + 3*n + ... + (k-1)*n + k*n)
+   = O((k/2) * k * n) = O(n * k^2) = O(n * log^2(n))
+
+
+Above results should generalize to arbitrary n = 2^k + p
+and should not be influenced by the initial insertion sort phase:
+Insertion sort is O(n^2) on Swap and Less, thus O(bs^2) per block of
+size bs at n/bs blocks:  O(bs*n) Swaps and Less during insertion sort.
+Merge sort iterations start at i = log(bs). With t = log(bs) constant:
+Calls to Less O((log(n)-t) * n + bs*n) = O(log(n)*n + (bs-t)*n)
+   = O(n * log(n))
+Calls to Swap O(n * log^2(n) - (t^2+t)/2*n) = O(n * log^2(n))
+
+*/
+
+// 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.
+//	}
+//
+// As a more whimsical example, this program guesses your number:
+//
+//	func GuessingGame() {
+//		var s string
+//		fmt.Printf("Pick an integer from 0 to 100.\n")
+//		answer := sort.Search(100, func(i int) bool {
+//			fmt.Printf("Is your number <= %d? ", i)
+//			fmt.Scanf("%s", &s)
+//			return s != "" && s[0] == 'y'
+//		})
+//		fmt.Printf("Your number is %d.\n", answer)
+//	}
+func Search(n int, f func(int) bool) int {
+	// Define f(-1) == false and f(n) == true.
+	// Invariant: f(i-1) == false, f(j) == true.
+	i, j := 0, n
+	for i < j {
+		h := int(uint(i+j) >> 1) // avoid overflow when computing h
+		// i ≤ h < j
+		if !f(h) {
+			i = h + 1 // preserves f(i-1) == false
 		} else {
-			swapRange(data, m-i, m+j-i, i)
-			j -= i
+			j = h // preserves f(j) == true
 		}
 	}
-	swapRange(data, m-i, m, i)
+	// i == j, f(i-1) == false, and f(j) (= f(i)) == true  =>  answer is i.
+	return i
 }
 
 // Find uses binary search to find and return the smallest index i in [0, n)
 // at which cmp(i) <= 0. If there is no such index i, Find returns i = n.
 // The found result is true if i < n and cmp(i) == 0.
 // Find calls cmp(i) only for i in the range [0, n).
+//
+// To permit binary search, Find requires that cmp(i) > 0 for a leading
+// prefix of the range, cmp(i) == 0 in the middle, and cmp(i) < 0 for
+// the final suffix of the range. (Each subrange could be empty.)
+// The usual way to establish this condition is to interpret cmp(i)
+// as a comparison of a desired target value t against entry i in an
+// underlying indexed data structure x, returning <0, 0, and >0
+// when t < x[i], t == x[i], and t > x[i], respectively.
+//
+// For example, to look for a particular string in a sorted, random-access
+// list of strings:
+//
+//	i, found := sort.Find(x.Len(), func(i int) int {
+//	    return strings.Compare(target, x.At(i))
+//	})
+//	if found {
+//	    fmt.Printf("found %s at entry %d\n", target, i)
+//	} else {
+//	    fmt.Printf("%s not found, would insert at %d", target, i)
+//	}
 func Find(n int, cmp func(int) int) (i int, found bool) {
+	// The invariants here are similar to the ones in Search.
+	// Define cmp(-1) > 0 and cmp(n) <= 0
+	// Invariant: cmp(i-1) > 0, cmp(j) <= 0
 	i, j := 0, n
 	for i < j {
-		h := int(uint(i+j) >> 1)
+		h := int(uint(i+j) >> 1) // avoid overflow when computing h
+		// i ≤ h < j
 		if cmp(h) > 0 {
-			i = h + 1
+			i = h + 1 // preserves cmp(i-1) > 0
 		} else {
-			j = h
+			j = h // preserves cmp(j) <= 0
 		}
 	}
+	// i == j, cmp(i-1) > 0 and cmp(j) <= 0
 	return i, i < n && cmp(i) == 0
 }
 
+// Convenience wrappers for common cases.
+
 // SearchInts searches for x in a sorted slice of ints and returns the index
-// as specified by Search.
+// 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.
 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.
+// 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.
 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.
+// 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.
 func SearchStrings(a []string, x string) int {
 	return Search(len(a), func(i int) bool { return a[i] >= x })
 }
 
-func isNaN(f float64) bool {
-	return f != f
-}
-
-// IntSlice attaches the methods of Interface to []int, sorting in increasing order.
-type IntSlice []int
-
-func (x IntSlice) Len() int           { return len(x) }
-func (x IntSlice) Less(i, j int) bool { return x[i] < x[j] }
-func (x IntSlice) Swap(i, j int)      { x[i], x[j] = x[j], x[i] }
-func (x IntSlice) Sort()              { Sort(x) }
-func (x IntSlice) Search(target int) int { return SearchInts(x, target) }
-
-// StringSlice attaches the methods of Interface to []string, sorting in increasing order.
-type StringSlice []string
-
-func (x StringSlice) Len() int           { return len(x) }
-func (x StringSlice) Less(i, j int) bool { return x[i] < x[j] }
-func (x StringSlice) Swap(i, j int)      { x[i], x[j] = x[j], x[i] }
-func (x StringSlice) Sort()              { Sort(x) }
-func (x StringSlice) Search(target string) int { return SearchStrings(x, target) }
-
-// Float64Slice attaches the methods of Interface to []float64, sorting in increasing order,
-// with not-a-number (NaN) values ordered before other values.
-type Float64Slice []float64
-
-func (x Float64Slice) Len() int { return len(x) }
-func (x Float64Slice) Less(i, j int) bool {
-	return x[i] < x[j] || (isNaN(x[i]) && !isNaN(x[j]))
+// Search returns the result of applying [SearchInts] to the receiver and x.
+func (p IntSlice) Search(x int) int { return SearchInts(p, x) }
+
+// Search returns the result of applying [SearchFloat64s] to the receiver and x.
+func (p Float64Slice) Search(x float64) int { return SearchFloat64s(p, x) }
+
+// Search returns the result of applying [SearchStrings] to the receiver and x.
+func (p StringSlice) Search(x string) int { return SearchStrings(p, x) }
+
+// Slice, SliceStable and SliceIsSorted take the slice as a type parameter
+// (S ~[]E) where Go takes `x any` and swaps through package reflect, which
+// GoFront does not have.  Every call that is valid in Go (a slice argument)
+// infers the same way; an interface value holding a slice is not accepted.
+
+// 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: equal elements
+// may be reversed from their original order.
+// For a stable sort, use [SliceStable].
+//
+// The less function must satisfy the same requirements as
+// the Interface type's Less method.
+//
+// Note: in many situations, the newer [slices.SortFunc] function is more
+// ergonomic and runs faster.
+func Slice[S ~[]E, E any](x S, less func(i, j int) bool) {
+	swap := func(i, j int) { x[i], x[j] = x[j], x[i] }
+	length := len(x)
+	limit := bitsLen(uint(length))
+	pdqsort_func(lessSwap{less, swap}, 0, length, limit)
+}
+
+// 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 less function must satisfy the same requirements as
+// the Interface type's Less method.
+//
+// Note: in many situations, the newer [slices.SortStableFunc] function is more
+// ergonomic and runs faster.
+func SliceStable[S ~[]E, E any](x S, less func(i, j int) bool) {
+	swap := func(i, j int) { x[i], x[j] = x[j], x[i] }
+	stable_func(lessSwap{less, swap}, len(x))
+}
+
+// SliceIsSorted reports whether the slice x is sorted according to the provided less function.
+// It panics if x is not a slice.
+//
+// Note: in many situations, the newer [slices.IsSortedFunc] function is more
+// ergonomic and runs faster.
+func SliceIsSorted[S ~[]E, E any](x S, less func(i, j int) bool) bool {
+	for i := len(x) - 1; i > 0; i-- {
+		if less(i, i-1) {
+			return false
+		}
+	}
+	return true
 }
-func (x Float64Slice) Swap(i, j int) { x[i], x[j] = x[j], x[i] }
-func (x Float64Slice) Sort()         { Sort(x) }
-func (x Float64Slice) Search(target float64) int { return SearchFloat64s(x, target) }