slices

package
v4.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 14, 2025 License: MIT Imports: 4 Imported by: 3

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://go.dev/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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Accum 

func Accum[T any, S ~[]T](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/v4/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 

func Accumx[T any, S ~[]T](s S, f func(T, T) (T, error)) (T, error)

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 All 

func All[Slice ~[]E, E any](s Slice) iter.Seq2[int, E]

All returns an iterator over index-value pairs in the slice in the usual order.

func Append 

func Append[T any, S ~[]T](s S, vals ...T) S

Append is the same as Go's builtin append and is included for completeness.

func AppendSeq 

func AppendSeq[Slice ~[]E, E any](s Slice, seq iter.Seq[E]) Slice

AppendSeq appends the values from seq to the slice and returns the extended slice.

func Backward 

func Backward[Slice ~[]E, E any](s Slice) iter.Seq2[int, E]

Backward returns an iterator over index-value pairs in the slice, traversing it backward with descending indices.

func BinarySearch 

func BinarySearch[S ~[]E, E cmp.Ordered](x S, 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[S ~[]E, E, T any](x S, target T, cmp func(E, T) 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 should return 0 if the slice element matches the target, a negative number if the slice element precedes the target, 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.

func Chunk 

func Chunk[Slice ~[]E, E any](s Slice, n int) iter.Seq[Slice]

Chunk returns an iterator over consecutive sub-slices of up to n elements of s. All but the last sub-slice will have size n. All sub-slices are clipped to have no capacity beyond the length. If s is empty, the sequence is empty: there is no empty slice in the sequence. Chunk panics if n is less than 1.

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 Collect 

func Collect[E any](seq iter.Seq[E]) []E

Collect collects values from seq into a new slice and returns it.

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 and returns the modified slice, which may have a smaller length. 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 

func CompactFunc[S ~[]E, E any](s S, eq func(E, E) bool) 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.

func Compare 

func Compare[S ~[]E, E cmp.Ordered](s1, s2 S) int

Compare compares the elements of s1 and s2, using cmp.Compare on each pair of elements. 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.

func CompareFunc 

func CompareFunc[S1 ~[]E1, S2 ~[]E2, E1, E2 any](s1 S1, s2 S2, cmp func(E1, E2) int) int

CompareFunc is like Compare but uses a custom comparison function on each pair of elements. 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 Concat 

func Concat[S ~[]E, E any](s ...S) S

Concat returns a new slice concatenating the passed in slices.

func Contains 

func Contains[S ~[]E, E comparable](s S, v E) bool

Contains reports whether v is present in s.

func ContainsFunc 

func ContainsFunc[S ~[]E, E any](s S, f func(E) bool) bool

ContainsFunc reports whether at least one element e of s satisfies f(e).

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 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 Go's standard slices.Delete.)

func DeleteFunc 

func DeleteFunc[S ~[]E, E any](s S, del func(E) bool) S

DeleteFunc removes any elements from s for which del returns true, returning the modified slice. When DeleteFunc removes m elements, 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 Each 

func Each[T any, S ~[]T](s S, f func(T))

Each runs a simple function on each item of a slice.

func Eachx 

func Eachx[T any, S ~[]T](s S, f func(int, T) error) error

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/v4/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[S ~[]E, E comparable](s1, s2 S) 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[S1 ~[]E1, S2 ~[]E2, E1, E2 any](s1 S1, s2 S2, eq func(E1, E2) bool) bool

EqualFunc reports whether two slices are equal using an equality 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 

func Filter[T any, S ~[]T](s S, f func(T) bool) S

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/v4/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 

func Filterx[T any, S ~[]T](s S, f func(T) (bool, error)) (S, error)

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 

func Get[T any, S ~[]T](s S, idx int) T

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/v4/slices"
)

func main() {
	var (
		s    = []int{1, 2, 3, 4}
		last = slices.Get(s, -1)
	)
	fmt.Println(last)
}

Output:

4

func Group 

func Group[T any, K comparable, S ~[]T](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/v4/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[T any, K comparable, S ~[]T](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 

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[S ~[]E, E comparable](s S, v E) int

Index returns the index of the first occurrence of v in s, or -1 if not present.

func IndexFunc 

func IndexFunc[S ~[]E, E any](s S, 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, idx int, vals ...E) S

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 Go's standard 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/v4/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[S ~[]E, E cmp.Ordered](x S) bool

IsSorted reports whether x is sorted in ascending order.

func IsSortedFunc 

func IsSortedFunc[S ~[]E, E any](x S, cmp func(a, b E) int) bool

IsSortedFunc reports whether x is sorted in ascending order, with cmp as the comparison function as defined by SortFunc.

func KeyedSort 

func KeyedSort[T any, S ~[]T](slice S, keys sort.Interface)

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/v4/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[T, U any, S ~[]T](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/v4/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 

func Mapx[T, U any, S ~[]T](s S, f func(int, T) (U, error)) ([]U, error)

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 Max 

func Max[S ~[]E, E cmp.Ordered](x S) E

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).

func MaxFunc 

func MaxFunc[S ~[]E, E any](x S, cmp func(a, b E) int) E

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.

func Min 

func Min[S ~[]E, E cmp.Ordered](x S) E

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).

func MinFunc 

func MinFunc[S ~[]E, E any](x S, cmp func(a, b E) int) E

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.

func NonNil 

func NonNil[T any, S ~[]T](s S) S

NonNil converts a nil slice to a non-nil empty slice. It returns other slices unchanged.

A nil slice is usually preferable, since it is equivalent to an empty slice in almost every way and does not have the overhead of an allocation. (See https://dave.cheney.net/2018/07/12/slices-from-the-ground-up.) However, there are some corner cases where the difference matters, notably when marshaling to JSON, where an empty slice marshals as the array [] but a nil slice marshals as the non-array `null`.

func Prefix 

func Prefix[T any, S ~[]T](s S, idx int) S

Prefix returns s up to but not including position idx.

If idx < 0 it counts from the end of s.

func Put 

func Put[T any, S ~[]T](s S, idx int, val T)

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 

func RemoveN[T any, S ~[]T](s S, idx, n int) S

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/v4/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 

func RemoveTo[T any, S ~[]T](s S, from, to int) S

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/v4/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 

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.

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 Go's standard slices.Replace.)

func ReplaceN 

func ReplaceN[T any, S ~[]T](s S, idx, n int, vals ...T) S

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/v4/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 

func ReplaceTo[T any, S ~[]T](s S, from, to int, vals ...T) S

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/v4/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 Reverse 

func Reverse[S ~[]E, E any](s S)

Reverse reverses the elements of the slice in place.

func Rotate 

func Rotate[T any, S ~[]T](s S, n int)

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/v4/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 

func SliceN[T any, S ~[]T](s S, idx, n int) S

SliceN returns n elements of s beginning at position idx.

If idx < 0 it counts from the end of s.

func SliceTo 

func SliceTo[T any, S ~[]T](s S, from, to int) S

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[S ~[]E, E cmp.Ordered](x S)

Sort sorts a slice of any ordered type in ascending order. When sorting floating-point numbers, NaNs are ordered before other values.

func SortFunc 

func SortFunc[S ~[]E, E any](x S, cmp func(a, b E) int)

SortFunc sorts the slice x in ascending order as determined by the cmp function. This sort is not guaranteed to be stable. cmp(a, b) should return a negative number when a < b, a positive number when a > b and zero when a == b.

SortFunc requires that cmp is a strict weak ordering. See https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings.

func SortStableFunc 

func SortStableFunc[S ~[]E, E any](x S, cmp func(a, b E) int)

SortStableFunc sorts the slice x while keeping the original order of equal elements, using cmp to compare elements in the same way as SortFunc.

func Sorted 

func Sorted[E cmp.Ordered](seq iter.Seq[E]) []E

Sorted collects values from seq into a new slice, sorts the slice, and returns it.

func SortedFunc 

func SortedFunc[E any](seq iter.Seq[E], cmp func(E, E) int) []E

SortedFunc collects values from seq into a new slice, sorts the slice using the comparison function, and returns it.

func SortedStableFunc 

func SortedStableFunc[E any](seq iter.Seq[E], cmp func(E, E) int) []E

SortedStableFunc collects values from seq into a new slice. It then sorts the slice while keeping the original order of equal elements, using the comparison function to compare elements. It returns the new slice.

func Suffix 

func Suffix[T any, S ~[]T](s S, idx int) S

Suffix returns s excluding elements before position idx.

If idx < 0 it counts from the end of s.

func Values 

func Values[Slice ~[]E, E any](s Slice) iter.Seq[E]

Values returns an iterator that yields the slice elements in order.

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.