README
¶
slices
import "github.com/fufuok/utils/generic/slices"
Package slices defines various functions useful with slices of any type. Unless otherwise specified, these functions all apply to the elements of a slice at index 0 <= i < len(s).
Note that the less function in IsSortedFunc, SortFunc, SortStableFunc requires a strict weak ordering (https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings), or the sorting may fail to sort correctly. A common case is when sorting slices of floating-point numbers containing NaN values.
Index
- func BinarySearch[E constraints.Ordered](x []E, target E) (int, bool)
- func BinarySearchFunc[E any](x []E, target E, cmp func(E, E) int) (int, bool)
- func Clip[S ~[]E, E any](s S) S
- func Clone[S ~[]E, E any](s S) 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 Delete[S ~[]E, E any](s S, i, j int) S
- func Equal[E comparable](s1, s2 []E) bool
- func EqualFunc[E1, E2 any](s1 []E1, s2 []E2, eq func(E1, E2) bool) bool
- 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 ~[]E, E any](s S, i int, v ...E) S
- func IsSorted[E constraints.Ordered](x []E) bool
- func IsSortedFunc[E any](x []E, less func(a, b E) bool) bool
- func Replace[S ~[]E, E any](s S, i, j int, v ...E) 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 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
func BinarySearchFunc[E any](x []E, target E, cmp func(E, E) int) (int, bool)
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 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.
func CompactFunc
func CompactFunc[S ~[]E, E any](s S, eq func(E, E) bool) S
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
func CompareFunc[E1, E2 any](s1 []E1, s2 []E2, cmp func(E1, E2) int) int
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 Delete
func Delete[S ~[]E, E any](s S, i, j int) S
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.
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
func EqualFunc[E1, E2 any](s1 []E1, s2 []E2, eq func(E1, E2) bool) bool
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 Grow
func Grow[S ~[]E, E any](s S, n int) S
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 IndexFunc
func IndexFunc[E any](s []E, f func(E) bool) int
IndexFunc returns the first index i satisfying f(s[i]), or -1 if none do.
func Insert
func Insert[S ~[]E, E any](s S, i int, v ...E) S
Insert inserts the values v... into s at index i, returning the modified slice. In the returned slice r, r[i] == v[0]. Insert panics if i is out of range. This function is O(len(s) + len(v)).
func IsSorted
func IsSorted[E constraints.Ordered](x []E) bool
IsSorted reports whether x is sorted in ascending order.
func IsSortedFunc
func IsSortedFunc[E any](x []E, less func(a, b E) bool) bool
IsSortedFunc reports whether x is sorted in ascending order, with less as the comparison function.
func Replace
func Replace[S ~[]E, E any](s S, i, j int, v ...E) S
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.
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
func SortFunc[E any](x []E, less func(a, b E) bool)
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
func SortStableFunc[E any](x []E, less func(a, b E) bool)
SortStableFunc sorts the slice x while keeping the original order of equal elements, using less to compare elements.
Generated by gomarkdoc
Documentation
¶
Overview ¶
Package slices defines various functions useful with slices of any type. Unless otherwise specified, these functions all apply to the elements of a slice at index 0 <= i < len(s).
Note that the less function in IsSortedFunc, SortFunc, SortStableFunc requires a strict weak ordering (https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings), or the sorting may fail to sort correctly. A common case is when sorting slices of floating-point numbers containing NaN values.
Index ¶
- func BinarySearch[E constraints.Ordered](x []E, target E) (int, bool)
- func BinarySearchFunc[E any](x []E, target E, cmp func(E, E) int) (int, bool)
- func Clip[S ~[]E, E any](s S) S
- func Clone[S ~[]E, E any](s S) 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 Delete[S ~[]E, E any](s S, i, j int) S
- func Equal[E comparable](s1, s2 []E) bool
- func EqualFunc[E1, E2 any](s1 []E1, s2 []E2, eq func(E1, E2) bool) bool
- 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 ~[]E, E any](s S, i int, v ...E) S
- func IsSorted[E constraints.Ordered](x []E) bool
- func IsSortedFunc[E any](x []E, less func(a, b E) bool) bool
- func Replace[S ~[]E, E any](s S, i, j int, v ...E) 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)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 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.
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 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.
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 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 values v... into s at index i, returning the modified slice. In the returned slice r, r[i] == v[0]. Insert panics if i is out of range. This function is O(len(s) + len(v)).
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 Replace ¶ added in v0.8.0
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.
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.
Source Files