maps,slices: add //go:fix inline annotations for std namesakes

The tooling will not yet offer to inline calls to these functions
because it doesn't handle generics (golang/go#68236), but it
will soon.

Updates golang/go#32816

Change-Id: Ic19940efddab6267ca92f670ddc2f8029bc93402
Reviewed-on: https://go-review.googlesource.com/c/exp/+/653436
Auto-Submit: Alan Donovan <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: adonovan

constraints/constraints.go

@@ -6,6 +6,8 @@
 // with type parameters.
 package constraints
 
+import "cmp"
+
 // Signed is a constraint that permits any signed integer type.
 // If future releases of Go add new predeclared signed integer types,
 // this constraint will be modified to include them.
@@ -47,6 +49,6 @@ type Complex interface {
 // this constraint will be modified to include them.
 //
 // This type is redundant since Go 1.21 introduced [cmp.Ordered].
-type Ordered interface {
-	Integer | Float | ~string
-}
+//
+//go:fix inline
+type Ordered = cmp.Ordered

maps/maps.go

@@ -7,17 +7,13 @@ package maps
 
 import "maps"
 
-// TODO(adonovan): when https://go.dev/issue/32816 is accepted, all of
-// these functions except Keys and Values should be annotated
-// (provisionally with "//go:fix inline") so that tools can safely and
-// automatically replace calls to exp/maps with calls to std maps by
-// inlining them.
-
 // Keys returns the keys of the map m.
 // The keys will be in an indeterminate order.
+//
+// The simplest true equivalent using the standard library  is:
+//
+//	slices.AppendSeq(make([]K, 0, len(m)), maps.Keys(m))
 func Keys[M ~map[K]V, K comparable, V any](m M) []K {
-	// The simplest true equivalent using std is:
-	// return slices.AppendSeq(make([]K, 0, len(m)), maps.Keys(m)).
 
 	r := make([]K, 0, len(m))
 	for k := range m {
@@ -28,9 +24,11 @@ func Keys[M ~map[K]V, K comparable, V any](m M) []K {
 
 // Values returns the values of the map m.
 // The values will be in an indeterminate order.
+//
+// The simplest true equivalent using the standard library is:
+//
+//	slices.AppendSeq(make([]V, 0, len(m)), maps.Values(m))
 func Values[M ~map[K]V, K comparable, V any](m M) []V {
-	// The simplest true equivalent using std is:
-	// return slices.AppendSeq(make([]V, 0, len(m)), maps.Values(m)).
 
 	r := make([]V, 0, len(m))
 	for _, v := range m {
@@ -41,23 +39,31 @@ func Values[M ~map[K]V, K comparable, V any](m M) []V {
 
 // Equal reports whether two maps contain the same key/value pairs.
 // Values are compared using ==.
+//
+//go:fix inline
 func Equal[M1, M2 ~map[K]V, K, V comparable](m1 M1, m2 M2) bool {
 	return maps.Equal(m1, m2)
 }
 
 // EqualFunc is like Equal, but compares values using eq.
 // Keys are still compared with ==.
+//
+//go:fix inline
 func EqualFunc[M1 ~map[K]V1, M2 ~map[K]V2, K comparable, V1, V2 any](m1 M1, m2 M2, eq func(V1, V2) bool) bool {
 	return maps.EqualFunc(m1, m2, eq)
 }
 
 // Clear removes all entries from m, leaving it empty.
+//
+//go:fix inline
 func Clear[M ~map[K]V, K comparable, V any](m M) {
 	clear(m)
 }
 
 // Clone returns a copy of m.  This is a shallow clone:
 // the new keys and values are set using ordinary assignment.
+//
+//go:fix inline
 func Clone[M ~map[K]V, K comparable, V any](m M) M {
 	return maps.Clone(m)
 }
@@ -66,11 +72,15 @@ func Clone[M ~map[K]V, K comparable, V any](m M) M {
 // When a key in src is already present in dst,
 // the value in dst will be overwritten by the value associated
 // with the key in src.
+//
+//go:fix inline
 func Copy[M1 ~map[K]V, M2 ~map[K]V, K comparable, V any](dst M1, src M2) {
 	maps.Copy(dst, src)
 }
 
 // DeleteFunc deletes any key/value pairs from m for which del returns true.
+//
+//go:fix inline
 func DeleteFunc[M ~map[K]V, K comparable, V any](m M, del func(K, V) bool) {
 	maps.DeleteFunc(m, del)
 }

slices/slices.go

@@ -10,16 +10,13 @@ import (
 	"slices"
 )
 
-// TODO(adonovan): when https://go.dev/issue/32816 is accepted, all of
-// these functions should be annotated (provisionally with "//go:fix
-// inline") so that tools can safely and automatically replace calls
-// to exp/slices with calls to std slices by inlining them.
-
 // Equal reports whether two slices are equal: the same length and all
 // elements equal. If the lengths are different, Equal returns false.
 // Otherwise, the elements are compared in increasing index order, and the
 // comparison stops at the first unequal pair.
 // Floating point NaNs are not considered equal.
+//
+//go:fix inline
 func Equal[S ~[]E, E comparable](s1, s2 S) bool {
 	return slices.Equal(s1, s2)
 }
@@ -29,6 +26,8 @@ func Equal[S ~[]E, E comparable](s1, s2 S) bool {
 // EqualFunc returns false. Otherwise, the elements are compared in
 // increasing index order, and the comparison stops at the first index
 // for which eq returns false.
+//
+//go:fix inline
 func EqualFunc[S1 ~[]E1, S2 ~[]E2, E1, E2 any](s1 S1, s2 S2, eq func(E1, E2) bool) bool {
 	return slices.EqualFunc(s1, s2, eq)
 }
@@ -40,6 +39,8 @@ func EqualFunc[S1 ~[]E1, S2 ~[]E2, E1, E2 any](s1 S1, s2 S2, eq func(E1, E2) boo
 // If both slices are equal until one of them ends, the shorter slice is
 // considered less than the longer one.
 // The result is 0 if s1 == s2, -1 if s1 < s2, and +1 if s1 > s2.
+//
+//go:fix inline
 func Compare[S ~[]E, E cmp.Ordered](s1, s2 S) int {
 	return slices.Compare(s1, s2)
 }
@@ -49,29 +50,39 @@ func Compare[S ~[]E, E cmp.Ordered](s1, s2 S) int {
 // The result is the first non-zero result of cmp; if cmp always
 // returns 0 the result is 0 if len(s1) == len(s2), -1 if len(s1) < len(s2),
 // and +1 if len(s1) > len(s2).
+//
+//go:fix inline
 func CompareFunc[S1 ~[]E1, S2 ~[]E2, E1, E2 any](s1 S1, s2 S2, cmp func(E1, E2) int) int {
 	return slices.CompareFunc(s1, s2, cmp)
 }
 
 // Index returns the index of the first occurrence of v in s,
 // or -1 if not present.
+//
+//go:fix inline
 func Index[S ~[]E, E comparable](s S, v E) int {
 	return slices.Index(s, v)
 }
 
 // IndexFunc returns the first index i satisfying f(s[i]),
 // or -1 if none do.
+//
+//go:fix inline
 func IndexFunc[S ~[]E, E any](s S, f func(E) bool) int {
 	return slices.IndexFunc(s, f)
 }
 
 // Contains reports whether v is present in s.
+//
+//go:fix inline
 func Contains[S ~[]E, E comparable](s S, v E) bool {
 	return slices.Contains(s, v)
 }
 
 // ContainsFunc reports whether at least one
 // element e of s satisfies f(e).
+//
+//go:fix inline
 func ContainsFunc[S ~[]E, E any](s S, f func(E) bool) bool {
 	return slices.ContainsFunc(s, f)
 }
@@ -83,6 +94,8 @@ func ContainsFunc[S ~[]E, E any](s S, f func(E) bool) bool {
 // and r[i+len(v)] == value originally at r[i].
 // Insert panics if i is out of range.
 // This function is O(len(s) + len(v)).
+//
+//go:fix inline
 func Insert[S ~[]E, E any](s S, i int, v ...E) S {
 	return slices.Insert(s, i, v...)
 }
@@ -92,26 +105,34 @@ func Insert[S ~[]E, E any](s S, i int, v ...E) S {
 // Delete is O(len(s)-i), so if many items must be deleted, it is better to
 // make a single call deleting them all together than to delete one at a time.
 // Delete zeroes the elements s[len(s)-(j-i):len(s)].
+//
+//go:fix inline
 func Delete[S ~[]E, E any](s S, i, j int) S {
 	return slices.Delete(s, i, j)
 }
 
 // DeleteFunc removes any elements from s for which del returns true,
 // returning the modified slice.
 // DeleteFunc zeroes the elements between the new length and the original length.
+//
+//go:fix inline
 func DeleteFunc[S ~[]E, E any](s S, del func(E) bool) S {
 	return slices.DeleteFunc(s, del)
 }
 
 // Replace replaces the elements s[i:j] by the given v, and returns the
 // modified slice. Replace panics if s[i:j] is not a valid slice of s.
 // When len(v) < (j-i), Replace zeroes the elements between the new length and the original length.
+//
+//go:fix inline
 func Replace[S ~[]E, E any](s S, i, j int, v ...E) S {
 	return slices.Replace(s, i, j, v...)
 }
 
 // Clone returns a copy of the slice.
 // The elements are copied using assignment, so this is a shallow clone.
+//
+//go:fix inline
 func Clone[S ~[]E, E any](s S) S {
 	return slices.Clone(s)
 }
@@ -121,13 +142,17 @@ func Clone[S ~[]E, E any](s S) S {
 // Compact modifies the contents of the slice s and returns the modified slice,
 // which may have a smaller length.
 // Compact zeroes the elements between the new length and the original length.
+//
+//go:fix inline
 func Compact[S ~[]E, E comparable](s S) S {
 	return slices.Compact(s)
 }
 
 // CompactFunc is like [Compact] but uses an equality function to compare elements.
 // For runs of elements that compare equal, CompactFunc keeps the first one.
 // CompactFunc zeroes the elements between the new length and the original length.
+//
+//go:fix inline
 func CompactFunc[S ~[]E, E any](s S, eq func(E, E) bool) S {
 	return slices.CompactFunc(s, eq)
 }
@@ -136,16 +161,22 @@ func CompactFunc[S ~[]E, E any](s S, eq func(E, E) bool) S {
 // another n elements. After Grow(n), at least n elements can be appended
 // to the slice without another allocation. If n is negative or too large to
 // allocate the memory, Grow panics.
+//
+//go:fix inline
 func Grow[S ~[]E, E any](s S, n int) S {
 	return slices.Grow(s, n)
 }
 
 // Clip removes unused capacity from the slice, returning s[:len(s):len(s)].
+//
+//go:fix inline
 func Clip[S ~[]E, E any](s S) S {
 	return slices.Clip(s)
 }
 
 // Reverse reverses the elements of the slice in place.
+//
+//go:fix inline
 func Reverse[S ~[]E, E any](s S) {
 	slices.Reverse(s)
 }

slices/sort.go

@@ -9,11 +9,10 @@ import (
 	"slices"
 )
 
-// TODO(adonovan): add a "//go:fix inline" annotation to each function
-// in this file; see https://go.dev/issue/32816.
-
 // Sort sorts a slice of any ordered type in ascending order.
 // When sorting floating-point numbers, NaNs are ordered before other values.
+//
+//go:fix inline
 func Sort[S ~[]E, E cmp.Ordered](x S) {
 	slices.Sort(x)
 }
@@ -27,51 +26,67 @@ func Sort[S ~[]E, E cmp.Ordered](x S) {
 // SortFunc requires that cmp is a strict weak ordering.
 // See https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings.
 // To indicate 'uncomparable', return 0 from the function.
+//
+//go:fix inline
 func SortFunc[S ~[]E, E any](x S, cmp func(a, b E) int) {
 	slices.SortFunc(x, cmp)
 }
 
 // SortStableFunc sorts the slice x while keeping the original order of equal
 // elements, using cmp to compare elements in the same way as [SortFunc].
+//
+//go:fix inline
 func SortStableFunc[S ~[]E, E any](x S, cmp func(a, b E) int) {
 	slices.SortStableFunc(x, cmp)
 }
 
 // IsSorted reports whether x is sorted in ascending order.
+//
+//go:fix inline
 func IsSorted[S ~[]E, E cmp.Ordered](x S) bool {
 	return slices.IsSorted(x)
 }
 
 // IsSortedFunc reports whether x is sorted in ascending order, with cmp as the
 // comparison function as defined by [SortFunc].
+//
+//go:fix inline
 func IsSortedFunc[S ~[]E, E any](x S, cmp func(a, b E) int) bool {
 	return slices.IsSortedFunc(x, cmp)
 }
 
 // Min returns the minimal value in x. It panics if x is empty.
 // For floating-point numbers, Min propagates NaNs (any NaN value in x
 // forces the output to be NaN).
+//
+//go:fix inline
 func Min[S ~[]E, E cmp.Ordered](x S) E {
 	return slices.Min(x)
 }
 
 // MinFunc returns the minimal value in x, using cmp to compare elements.
 // It panics if x is empty. If there is more than one minimal element
 // according to the cmp function, MinFunc returns the first one.
+//
+//go:fix inline
 func MinFunc[S ~[]E, E any](x S, cmp func(a, b E) int) E {
 	return slices.MinFunc(x, cmp)
 }
 
 // Max returns the maximal value in x. It panics if x is empty.
 // For floating-point E, Max propagates NaNs (any NaN value in x
 // forces the output to be NaN).
+//
+//go:fix inline
 func Max[S ~[]E, E cmp.Ordered](x S) E {
 	return slices.Max(x)
 }
 
 // MaxFunc returns the maximal value in x, using cmp to compare elements.
 // It panics if x is empty. If there is more than one maximal element
 // according to the cmp function, MaxFunc returns the first one.
+//
+//go:fix inline
 func MaxFunc[S ~[]E, E any](x S, cmp func(a, b E) int) E {
 	return slices.MaxFunc(x, cmp)
 }
@@ -80,6 +95,8 @@ func MaxFunc[S ~[]E, E any](x S, cmp func(a, b E) int) E {
 // where target is found, or the position where target would appear in the
 // sort order; it also returns a bool saying whether the target is really found
 // in the slice. The slice must be sorted in increasing order.
+//
+//go:fix inline
 func BinarySearch[S ~[]E, E cmp.Ordered](x S, target E) (int, bool) {
 	return slices.BinarySearch(x, target)
 }
@@ -91,6 +108,8 @@ func BinarySearch[S ~[]E, E cmp.Ordered](x S, target E) (int, bool) {
 // or a positive number if the slice element follows the target.
 // cmp must implement the same ordering as the slice, such that if
 // cmp(a, t) < 0 and cmp(b, t) >= 0, then a must precede b in the slice.
+//
+//go:fix inline
 func BinarySearchFunc[S ~[]E, E, T any](x S, target T, cmp func(E, T) int) (int, bool) {
 	return slices.BinarySearchFunc(x, target, cmp)
 }