Documentation ¶
Overview ¶
Package slices contains utility functions for working with slices. It encapsulates hard-to-remember idioms for inserting and removing elements; it adds the ability to index from the right end of a slice using negative integers (for example, Get(s, -1) is the same as s[len(s)-1]), and it includes Map, Filter, and a few other such functions for processing slice elements with callbacks.
This package is a drop-in replacement for the slices package added to the Go stdlib in Go 1.21 (https://golang.ir/doc/go1.21#slices). There is one difference: this version of slices allows the index value passed to `Insert`, `Delete`, and `Replace` to be negative for counting backward from the end of the slice.
Index ¶
- func Accum[S ~[]T, T any](s S, f func(T, T) T) T
- func Accumx[S ~[]T, T any](s S, f func(T, T) (T, error)) (T, error)
- func Append[S ~[]T, T any](s S, vals ...T) S
- func BinarySearch[E constraints.Ordered](x []E, target E) (int, bool)
- func BinarySearchFunc[E, T any](x []E, target T, cmp func(E, T) int) (int, bool)
- func Clip[S ~[]E, E any](s S) S
- func Clone[S ~[]E, E any](s S) S
- func Combinations[S ~[]T, T any](s S, n int) iter.Of[S]
- func CombinationsWithReplacement[S ~[]T, T any](s S, n int) iter.Of[S]
- func Compact[S ~[]E, E comparable](s S) S
- func CompactFunc[S ~[]E, E any](s S, eq func(E, E) bool) S
- func Compare[E constraints.Ordered](s1, s2 []E) int
- func CompareFunc[E1, E2 any](s1 []E1, s2 []E2, cmp func(E1, E2) int) int
- func Contains[E comparable](s []E, v E) bool
- func ContainsFunc[E any](s []E, f func(E) bool) bool
- func Delete[S ~[]E, E any](s S, i, j int) S
- func Each[S ~[]T, T any](s S, f func(T))
- func Eachx[S ~[]T, T any](s S, f func(int, T) error) error
- func Equal[E comparable](s1, s2 []E) bool
- func EqualFunc[E1, E2 any](s1 []E1, s2 []E2, eq func(E1, E2) bool) bool
- func Filter[S ~[]T, T any](s S, f func(T) bool) S
- func Filterx[S ~[]T, T any](s S, f func(T) (bool, error)) (S, error)
- func Get[S ~[]T, T any](s S, idx int) T
- func Group[S ~[]T, T any, K comparable](s S, f func(T) K) map[K]S
- func Groupx[S ~[]T, T any, K comparable](s S, f func(T) (K, error)) (map[K]S, error)
- func Grow[S ~[]E, E any](s S, n int) S
- func Index[E comparable](s []E, v E) int
- func IndexFunc[E any](s []E, f func(E) bool) int
- func Insert[S ~[]T, T any](s S, idx int, vals ...T) S
- func IsSorted[E constraints.Ordered](x []E) bool
- func IsSortedFunc[E any](x []E, less func(a, b E) bool) bool
- func KeyedSort[S ~[]T, T any](slice S, keys sort.Interface)
- func Map[S ~[]T, T, U any](s S, f func(T) U) []U
- func Mapx[S ~[]T, T, U any](s S, f func(int, T) (U, error)) ([]U, error)
- func Permutations[S ~[]T, T any](s S) iter.Of[S]
- func Prefix[S ~[]T, T any](s S, idx int) S
- func Put[S ~[]T, T any](s S, idx int, val T)
- func RemoveN[S ~[]T, T any](s S, idx, n int) S
- func RemoveTo[S ~[]T, T any](s S, from, to int) S
- func Replace[S ~[]E, E any](s S, i, j int, v ...E) S
- func ReplaceN[S ~[]T, T any](s S, idx, n int, vals ...T) S
- func ReplaceTo[S ~[]T, T any](s S, from, to int, vals ...T) S
- func Reverse[S ~[]T, T any](s S)
- func Rotate[S ~[]T, T any](s S, n int)
- func SliceN[S ~[]T, T any](s S, idx, n int) S
- func SliceTo[S ~[]T, T any](s S, from, to int) S
- func Sort[E constraints.Ordered](x []E)
- func SortFunc[E any](x []E, less func(a, b E) bool)
- func SortStableFunc[E any](x []E, less func(a, b E) bool)
- func Suffix[S ~[]T, T any](s S, idx int) S
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Accum ¶
func Accum[S ~[]T, T any](s S, f func(T, T) T) T
Accum accumulates the result of repeatedly applying a simple function to the elements of a slice.
If the slice has length 0, the result is the zero value of type T. If the slice has length 1, the result is s[0]. Otherwise, the result is R[len(s)-1], where R[0] is s[0] and R[n+1] = f(R[n], s[n+1]).
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { var ( s = []int{1, 2, 3, 4, 5} sum = slices.Accum(s, func(a, b int) int { return a + b }) ) fmt.Println(sum) }
Output: 15
func Accumx ¶
Accumx is the extended form of Accum. It accumulates the result of repeatedly applying a function to the elements of a slice.
If the slice has length 0, the result is the zero value of type T. If the slice has length 1, the result is s[0]. Otherwise, the result is R[len(s)-1], where R[0] is s[0] and R[n+1] = f(R[n], s[n+1]).
func Append ¶
func Append[S ~[]T, T any](s S, vals ...T) S
Append is the same as Go's builtin append and is included for completeness.
func BinarySearch ¶
func BinarySearch[E constraints.Ordered](x []E, target E) (int, bool)
BinarySearch searches for target in a sorted slice and returns the position 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.
func BinarySearchFunc ¶
BinarySearchFunc works like BinarySearch, but uses a custom comparison function. The slice must be sorted in increasing order, where "increasing" is defined by cmp. cmp(a, b) is expected to return an integer comparing the two parameters: 0 if a == b, a negative number if a < b and a positive number if a > b.
func Clip ¶
func Clip[S ~[]E, E any](s S) S
Clip removes unused capacity from the slice, returning s[:len(s):len(s)].
func Clone ¶
func Clone[S ~[]E, E any](s S) S
Clone returns a copy of the slice. The elements are copied using assignment, so this is a shallow clone.
func Combinations ¶
Combinations produces an iterator over all n-length combinations of distinct elements from s.
If s is [1 2 3] and n is 2, this function will produce:
[1 2] [1 3] [2 3]
func CombinationsWithReplacement ¶
CombinationsWithReplacement produces an iterator over all n-length combinations of possibly repeated elements from s.
If s is [1 2 3] and n is 2, this function will produce:
[1 1] [1 2] [1 3] [2 2] [2 3] [3 3]
func Compact ¶
func Compact[S ~[]E, E comparable](s S) S
Compact replaces consecutive runs of equal elements with a single copy. This is like the uniq command found on Unix. Compact modifies the contents of the slice s; it does not create a new slice. When Compact discards m elements in total, it might not modify the elements s[len(s)-m:len(s)]. If those elements contain pointers you might consider zeroing those elements so that objects they reference can be garbage collected.
func CompactFunc ¶
CompactFunc is like Compact but uses a comparison function.
func Compare ¶
func Compare[E constraints.Ordered](s1, s2 []E) int
Compare compares the elements of s1 and s2. The elements are compared sequentially, starting at index 0, until one element is not equal to the other. The result of comparing the first non-matching elements is returned. 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. Comparisons involving floating point NaNs are ignored.
func CompareFunc ¶
CompareFunc is like Compare but uses a comparison function on each pair of elements. The elements are compared in increasing index order, and the comparisons stop after the first time cmp returns non-zero. 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).
func Contains ¶
func Contains[E comparable](s []E, v E) bool
Contains reports whether v is present in s.
func ContainsFunc ¶
ContainsFunc reports whether at least one element e of s satisfies f(e).
func Delete ¶
Delete removes the elements s[i:j] from s, returning the modified slice. Delete panics if s[i:j] is not a valid slice of s. Delete modifies the contents of the slice s; it does not create a new slice. Delete is O(len(s)-j), 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 might not modify the elements s[len(s)-(j-i):len(s)]. If those elements contain pointers you might consider zeroing those elements so that objects they reference can be garbage collected.
If i < 0 it counts from the end of s. If j <= 0 it counts from the end of s. (This is a change from the behavior of "golang.org/x/exp/slices".Delete.)
func Each ¶
func Each[S ~[]T, T any](s S, f func(T))
Each runs a simple function on each item of a slice.
func Eachx ¶
Eachx is the extended form of Each. It runs a function on each item of a slice, passing the index and the item to the function. If any call to the function returns an error, Eachx stops looping and exits with the error.
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { s := []int{100, 200, 300} _ = slices.Eachx(s, func(idx, val int) error { fmt.Println(idx, val) return nil }) }
Output: 0 100 1 200 2 300
func Equal ¶
func Equal[E comparable](s1, s2 []E) bool
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.
func EqualFunc ¶
EqualFunc reports whether two slices are equal using a comparison function on each pair of elements. If the lengths are different, 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.
func Filter ¶
Filter calls a simple predicate for each element of a slice, returning a slice of those elements for which the predicate returned true.
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { var ( s = []int{1, 2, 3, 4, 5, 6, 7} evens = slices.Filter(s, func(val int) bool { return val%2 == 0 }) ) fmt.Println(evens) }
Output: [2 4 6]
func Filterx ¶
Filterx is the extended form of Filter. It calls a predicate for each element of a slice, returning a slice of those elements for which the predicate returned true.
func Get ¶
Get gets the idx'th element of s.
If idx < 0 it counts from the end of s.
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { var ( s = []int{1, 2, 3, 4} last = slices.Get(s, -1) ) fmt.Println(last) }
Output: 4
func Group ¶
func Group[S ~[]T, T any, K comparable](s S, f func(T) K) map[K]S
Group partitions the elements of a slice into groups. It does this by calling a simple grouping function on each element, which produces a grouping key. The result is a map of group keys to slices of elements having that key.
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { s := []int{1, 2, 3, 4, 5, 6, 7} groups := slices.Group(s, func(val int) string { if val%2 == 0 { return "even" } return "odd" }) for key, slice := range groups { fmt.Println(key, slice) } }
Output: even [2 4 6] odd [1 3 5 7]
func Groupx ¶
func Groupx[S ~[]T, T any, K comparable](s S, f func(T) (K, error)) (map[K]S, error)
Groupx is the extended form of Group. It partitions the elements of a slice into groups. It does this by calling a grouping function on each element, which produces a grouping key. The result is a map of group keys to slices of elements having that key.
func Grow ¶
Grow increases the slice's capacity, if necessary, to guarantee space for 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.
func Index ¶
func Index[E comparable](s []E, v E) int
Index returns the index of the first occurrence of v in s, or -1 if not present.
func Insert ¶
Insert inserts the given values at the idx'th location in s and returns the result. After the insert, the first new value has position idx.
If idx < 0, it counts from the end of s. (This is a change from the behavior of "golang.org/x/exp/slices".Insert.)
The input slice is modified.
Example: Insert([x, y, z], 1, a, b, c) -> [x, a, b, c, y, z]
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { var ( s1 = []int{10, 15, 16} s2 = slices.Insert(s1, 1, 11, 12, 13, 14) ) fmt.Println(s2) }
Output: [10 11 12 13 14 15 16]
func IsSorted ¶
func IsSorted[E constraints.Ordered](x []E) bool
IsSorted reports whether x is sorted in ascending order.
func IsSortedFunc ¶
IsSortedFunc reports whether x is sorted in ascending order, with less as the comparison function.
func KeyedSort ¶
KeyedSort sorts the given slice according to the ordering of the given keys, whose items must map 1:1 with the slice. It is an unchecked error if keys.Len() != len(slice).
Both arguments end up sorted in place: keys according to its Less method, and slice by mirroring the reordering that happens in keys.
Example ¶
package main import ( "fmt" "sort" "github.com/bobg/go-generics/v2/slices" ) func main() { var ( nums = []int{1, 2, 3, 4, 5} names = []string{"one", "two", "three", "four", "five"} ) // Sort the numbers in `nums` according to their names in `names`. slices.KeyedSort(nums, sort.StringSlice(names)) fmt.Println(nums) }
Output: [5 4 1 3 2]
func Map ¶
func Map[S ~[]T, T, U any](s S, f func(T) U) []U
Map runs a simple function on each item of a slice, accumulating results in a new slice.
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { var ( s1 = []int{1, 2, 3, 4, 5} s2 = slices.Map(s1, func(val int) string { return string([]byte{byte('a' + val - 1)}) }) ) fmt.Println(s2) }
Output: [a b c d e]
func Mapx ¶
Mapx is the extended form of Map. It runs a function on each item of a slice, accumulating results in a new slice. If any call to the function returns an error, Mapx stops looping and exits with the error.
func Permutations ¶
Permutations produces an iterator over all permutations of s. It uses Heap's Algorithm. See https://en.wikipedia.org/wiki/Heap%27s_algorithm.
If s is [1 2 3], this function will produce:
[1 2 3] [2 1 3] [3 1 2] [1 3 2] [2 3 1] [3 2 1]
func Prefix ¶
Prefix returns s up to but not including position idx.
If idx < 0 it counts from the end of s.
func Put ¶
Put puts a given value into the idx'th location in s.
If idx < 0 it counts from the end of s.
The input slice is modified.
func RemoveN ¶
RemoveN removes n items from s beginning at position idx and returns the result.
If idx < 0 it counts from the end of s.
The input slice is modified.
Example: RemoveN([a, b, c, d], 1, 2) -> [a, d]
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { var ( s1 = []int{1, 2, 3, 4, 5} s2 = slices.RemoveN(s1, -2, 2) ) fmt.Println(s2) }
Output: [1 2 3]
func RemoveTo ¶
RemoveTo removes items from s beginning at position from and ending before position to. It returns the result.
If from < 0 it counts from the end of s. If to <= 0 it counts from the end of s.
The input slice is modified.
Example: RemoveTo([a, b, c, d], 1, 3) -> [a, d]
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { var ( s1 = []int{1, 2, 3, 4, 5} s2 = slices.RemoveTo(s1, -2, 0) ) fmt.Println(s2) }
Output: [1 2 3]
func Replace ¶
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.
If i < 0 it counts from the end of s. If j <= 0 it counts from the end of s. (This is a change from the behavior of "golang.org/x/exp/slices".Replace.)
func ReplaceN ¶
ReplaceN replaces the n values of s beginning at position idx with the given values. After the replace, the first new value has position idx.
If idx < 0, it counts from the end of s.
The input slice is modified.
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { var ( s1 = []int{99, 0, 0, 0, 97} s2 = slices.ReplaceN(s1, 1, 3, 98) ) fmt.Println(s2) }
Output: [99 98 97]
func ReplaceTo ¶
ReplaceTo replaces the values of s beginning at from and ending before to with the given values. After the replace, the first new value has position from.
If from < 0 it counts from the end of s. If to <= 0 it counts from the end of s.
The input slice is modified.
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { var ( s1 = []int{99, 0, 0, 0, 97} s2 = slices.ReplaceTo(s1, 1, -1, 98) ) fmt.Println(s2) }
Output: [99 98 97]
func Rotate ¶
Rotate rotates a slice in place by n places to the right. (With negative n, it's to the left.) Example: Rotate([D, E, A, B, C], 3) -> [A, B, C, D, E]
Example ¶
package main import ( "fmt" "github.com/bobg/go-generics/v2/slices" ) func main() { s := []int{3, 4, 5, 1, 2} slices.Rotate(s, 2) fmt.Println(s) }
Output: [1 2 3 4 5]
func SliceN ¶
SliceN returns n elements of s beginning at position idx.
If idx < 0 it counts from the end of s.
func SliceTo ¶
SliceTo returns the elements of s beginning at position from and ending before position to.
If from < 0 it counts from the end of s. If to <= 0 it counts from the end of s.
func Sort ¶
func Sort[E constraints.Ordered](x []E)
Sort sorts a slice of any ordered type in ascending order. Sort may fail to sort correctly when sorting slices of floating-point numbers containing Not-a-number (NaN) values. Use slices.SortFunc(x, func(a, b float64) bool {return a < b || (math.IsNaN(a) && !math.IsNaN(b))}) instead if the input may contain NaNs.
func SortFunc ¶
SortFunc sorts the slice x in ascending order as determined by the less function. This sort is not guaranteed to be stable.
SortFunc requires that less is a strict weak ordering. See https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings.
func SortStableFunc ¶
SortStableFunc sorts the slice x while keeping the original order of equal elements, using less to compare elements.
Types ¶
This section is empty.