1 // Copyright 2021 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 5 // Package slices defines various functions useful with slices of any type.
6 package slices
7 8 import (
9 "cmp"
10 "slices"
11 )
12 13 // Equal reports whether two slices are equal: the same length and all
14 // elements equal. If the lengths are different, Equal returns false.
15 // Otherwise, the elements are compared in increasing index order, and the
16 // comparison stops at the first unequal pair.
17 // Floating point NaNs are not considered equal.
18 //
19 //go:fix inline
20 func Equal[S ~[]E, E comparable](s1, s2 S) bool {
21 return slices.Equal(s1, s2)
22 }
23 24 // EqualFunc reports whether two slices are equal using an equality
25 // function on each pair of elements. If the lengths are different,
26 // EqualFunc returns false. Otherwise, the elements are compared in
27 // increasing index order, and the comparison stops at the first index
28 // for which eq returns false.
29 //
30 //go:fix inline
31 func EqualFunc[S1 ~[]E1, S2 ~[]E2, E1, E2 any](s1 S1, s2 S2, eq func(E1, E2) bool) bool {
32 return slices.EqualFunc(s1, s2, eq)
33 }
34 35 // Compare compares the elements of s1 and s2, using [cmp.Compare] on each pair
36 // of elements. The elements are compared sequentially, starting at index 0,
37 // until one element is not equal to the other.
38 // The result of comparing the first non-matching elements is returned.
39 // If both slices are equal until one of them ends, the shorter slice is
40 // considered less than the longer one.
41 // The result is 0 if s1 == s2, -1 if s1 < s2, and +1 if s1 > s2.
42 //
43 //go:fix inline
44 func Compare[S ~[]E, E cmp.Ordered](s1, s2 S) int {
45 return slices.Compare(s1, s2)
46 }
47 48 // CompareFunc is like [Compare] but uses a custom comparison function on each
49 // pair of elements.
50 // The result is the first non-zero result of cmp; if cmp always
51 // returns 0 the result is 0 if len(s1) == len(s2), -1 if len(s1) < len(s2),
52 // and +1 if len(s1) > len(s2).
53 //
54 //go:fix inline
55 func CompareFunc[S1 ~[]E1, S2 ~[]E2, E1, E2 any](s1 S1, s2 S2, cmp func(E1, E2) int) int {
56 return slices.CompareFunc(s1, s2, cmp)
57 }
58 59 // Index returns the index of the first occurrence of v in s,
60 // or -1 if not present.
61 //
62 //go:fix inline
63 func Index[S ~[]E, E comparable](s S, v E) int {
64 return slices.Index(s, v)
65 }
66 67 // IndexFunc returns the first index i satisfying f(s[i]),
68 // or -1 if none do.
69 //
70 //go:fix inline
71 func IndexFunc[S ~[]E, E any](s S, f func(E) bool) int {
72 return slices.IndexFunc(s, f)
73 }
74 75 // Contains reports whether v is present in s.
76 //
77 //go:fix inline
78 func Contains[S ~[]E, E comparable](s S, v E) bool {
79 return slices.Contains(s, v)
80 }
81 82 // ContainsFunc reports whether at least one
83 // element e of s satisfies f(e).
84 //
85 //go:fix inline
86 func ContainsFunc[S ~[]E, E any](s S, f func(E) bool) bool {
87 return slices.ContainsFunc(s, f)
88 }
89 90 // Insert inserts the values v... into s at index i,
91 // returning the modified slice.
92 // The elements at s[i:] are shifted up to make room.
93 // In the returned slice r, r[i] == v[0],
94 // and r[i+len(v)] == value originally at r[i].
95 // Insert panics if i is out of range.
96 // This function is O(len(s) + len(v)).
97 //
98 //go:fix inline
99 func Insert[S ~[]E, E any](s S, i int, v ...E) S {
100 return slices.Insert(s, i, v...)
101 }
102 103 // Delete removes the elements s[i:j] from s, returning the modified slice.
104 // Delete panics if j > len(s) or s[i:j] is not a valid slice of s.
105 // Delete is O(len(s)-i), so if many items must be deleted, it is better to
106 // make a single call deleting them all together than to delete one at a time.
107 // Delete zeroes the elements s[len(s)-(j-i):len(s)].
108 //
109 //go:fix inline
110 func Delete[S ~[]E, E any](s S, i, j int) S {
111 return slices.Delete(s, i, j)
112 }
113 114 // DeleteFunc removes any elements from s for which del returns true,
115 // returning the modified slice.
116 // DeleteFunc zeroes the elements between the new length and the original length.
117 //
118 //go:fix inline
119 func DeleteFunc[S ~[]E, E any](s S, del func(E) bool) S {
120 return slices.DeleteFunc(s, del)
121 }
122 123 // Replace replaces the elements s[i:j] by the given v, and returns the
124 // modified slice. Replace panics if s[i:j] is not a valid slice of s.
125 // When len(v) < (j-i), Replace zeroes the elements between the new length and the original length.
126 //
127 //go:fix inline
128 func Replace[S ~[]E, E any](s S, i, j int, v ...E) S {
129 return slices.Replace(s, i, j, v...)
130 }
131 132 // Clone returns a copy of the slice.
133 // The elements are copied using assignment, so this is a shallow clone.
134 //
135 //go:fix inline
136 func Clone[S ~[]E, E any](s S) S {
137 return slices.Clone(s)
138 }
139 140 // Compact replaces consecutive runs of equal elements with a single copy.
141 // This is like the uniq command found on Unix.
142 // Compact modifies the contents of the slice s and returns the modified slice,
143 // which may have a smaller length.
144 // Compact zeroes the elements between the new length and the original length.
145 //
146 //go:fix inline
147 func Compact[S ~[]E, E comparable](s S) S {
148 return slices.Compact(s)
149 }
150 151 // CompactFunc is like [Compact] but uses an equality function to compare elements.
152 // For runs of elements that compare equal, CompactFunc keeps the first one.
153 // CompactFunc zeroes the elements between the new length and the original length.
154 //
155 //go:fix inline
156 func CompactFunc[S ~[]E, E any](s S, eq func(E, E) bool) S {
157 return slices.CompactFunc(s, eq)
158 }
159 160 // Grow increases the slice's capacity, if necessary, to guarantee space for
161 // another n elements. After Grow(n), at least n elements can be appended
162 // to the slice without another allocation. If n is negative or too large to
163 // allocate the memory, Grow panics.
164 //
165 //go:fix inline
166 func Grow[S ~[]E, E any](s S, n int) S {
167 return slices.Grow(s, n)
168 }
169 170 // Clip removes unused capacity from the slice, returning s[:len(s):len(s)].
171 //
172 //go:fix inline
173 func Clip[S ~[]E, E any](s S) S {
174 return slices.Clip(s)
175 }
176 177 // Reverse reverses the elements of the slice in place.
178 //
179 //go:fix inline
180 func Reverse[S ~[]E, E any](s S) {
181 slices.Reverse(s)
182 }
183