1// Copyright 2022 The Go Authors. All rights reserved.
  2// Use of this source code is governed by a BSD-style
  3// license that can be found in the LICENSE file.
  4
  5package slices
  6
  7import (
  8	"cmp"
  9	"slices"
 10)
 11
 12// Sort sorts a slice of any ordered type in ascending order.
 13// When sorting floating-point numbers, NaNs are ordered before other values.
 14//
 15//go:fix inline
 16func Sort[S ~[]E, E cmp.Ordered](x S) {
 17	slices.Sort(x)
 18}
 19
 20// SortFunc sorts the slice x in ascending order as determined by the cmp
 21// function. This sort is not guaranteed to be stable.
 22// cmp(a, b) should return a negative number when a < b, a positive number when
 23// a > b and zero when a == b or when a is not comparable to b in the sense
 24// of the formal definition of Strict Weak Ordering.
 25//
 26// SortFunc requires that cmp is a strict weak ordering.
 27// See https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings.
 28// To indicate 'uncomparable', return 0 from the function.
 29//
 30//go:fix inline
 31func SortFunc[S ~[]E, E any](x S, cmp func(a, b E) int) {
 32	slices.SortFunc(x, cmp)
 33}
 34
 35// SortStableFunc sorts the slice x while keeping the original order of equal
 36// elements, using cmp to compare elements in the same way as [SortFunc].
 37//
 38//go:fix inline
 39func SortStableFunc[S ~[]E, E any](x S, cmp func(a, b E) int) {
 40	slices.SortStableFunc(x, cmp)
 41}
 42
 43// IsSorted reports whether x is sorted in ascending order.
 44//
 45//go:fix inline
 46func IsSorted[S ~[]E, E cmp.Ordered](x S) bool {
 47	return slices.IsSorted(x)
 48}
 49
 50// IsSortedFunc reports whether x is sorted in ascending order, with cmp as the
 51// comparison function as defined by [SortFunc].
 52//
 53//go:fix inline
 54func IsSortedFunc[S ~[]E, E any](x S, cmp func(a, b E) int) bool {
 55	return slices.IsSortedFunc(x, cmp)
 56}
 57
 58// Min returns the minimal value in x. It panics if x is empty.
 59// For floating-point numbers, Min propagates NaNs (any NaN value in x
 60// forces the output to be NaN).
 61//
 62//go:fix inline
 63func Min[S ~[]E, E cmp.Ordered](x S) E {
 64	return slices.Min(x)
 65}
 66
 67// MinFunc returns the minimal value in x, using cmp to compare elements.
 68// It panics if x is empty. If there is more than one minimal element
 69// according to the cmp function, MinFunc returns the first one.
 70//
 71//go:fix inline
 72func MinFunc[S ~[]E, E any](x S, cmp func(a, b E) int) E {
 73	return slices.MinFunc(x, cmp)
 74}
 75
 76// Max returns the maximal value in x. It panics if x is empty.
 77// For floating-point E, Max propagates NaNs (any NaN value in x
 78// forces the output to be NaN).
 79//
 80//go:fix inline
 81func Max[S ~[]E, E cmp.Ordered](x S) E {
 82	return slices.Max(x)
 83}
 84
 85// MaxFunc returns the maximal value in x, using cmp to compare elements.
 86// It panics if x is empty. If there is more than one maximal element
 87// according to the cmp function, MaxFunc returns the first one.
 88//
 89//go:fix inline
 90func MaxFunc[S ~[]E, E any](x S, cmp func(a, b E) int) E {
 91	return slices.MaxFunc(x, cmp)
 92}
 93
 94// BinarySearch searches for target in a sorted slice and returns the position
 95// where target is found, or the position where target would appear in the
 96// sort order; it also returns a bool saying whether the target is really found
 97// in the slice. The slice must be sorted in increasing order.
 98//
 99//go:fix inline
100func BinarySearch[S ~[]E, E cmp.Ordered](x S, target E) (int, bool) {
101	return slices.BinarySearch(x, target)
102}
103
104// BinarySearchFunc works like [BinarySearch], but uses a custom comparison
105// function. The slice must be sorted in increasing order, where "increasing"
106// is defined by cmp. cmp should return 0 if the slice element matches
107// the target, a negative number if the slice element precedes the target,
108// or a positive number if the slice element follows the target.
109// cmp must implement the same ordering as the slice, such that if
110// cmp(a, t) < 0 and cmp(b, t) >= 0, then a must precede b in the slice.
111//
112//go:fix inline
113func BinarySearchFunc[S ~[]E, E, T any](x S, target T, cmp func(E, T) int) (int, bool) {
114	return slices.BinarySearchFunc(x, target, cmp)
115}