collection

Documentation

Overview

Package collection provides type-safe utility methods for slice and map types.

Index

• func Append[K comparable, V any](mps ...map[K]V) (mp map[K]V)
• func AsAny[T any](slice []T) []any
• func Deduplicate[T comparable, S ~[]T](slice S) S
• func First[T any](slice []T, test func(T) bool) T
• func IterateSorted[K cmp.Ordered, V any](M map[K]V, f func(k K, v V) bool) bool
• func KeepFunc[T any, S ~[]T](slice S, filter func(T) bool) S
• func KeepFuncClone[T any, S ~[]T](slice S, filter func(T) bool) (results S)
• func MapSlice[T1 any, S1 ~[]T1, T2 any](slice S1, f func(T1) T2) []T2
• func MapValues[K comparable, V1, V2 any](M map[K]V1, f func(K, V1) V2) map[K]V2
• func NonSequential[T cmp.Ordered, S ~[]T](slice S, test func(prev, current T) bool) S
• func Partition[T any, S ~[]T, P comparable](slice S, f func(T) P) map[P]S

Examples

• Append
• First
• IterateSorted
• IterateSorted (Early)
• KeepFunc
• KeepFunc (AllFalse)
• KeepFunc (AllTrue)
• KeepFuncClone
• KeepFuncClone (Order)
• MapSlice
• MapValues
• NonSequential
• Partition

Functions

func Append

func Append[K comparable, V any](mps ...map[K]V) (mp map[K]V)

Append adds elements from all other maps into the first map. If the first map is nil, a new empty map is used instead.

It is the map equivalent of the built-in append for slices.

Example

// append to the first map
fmt.Println(Append(map[string]string{
	"hello": "world",
}, map[string]string{
	"answer": "42",
}))

// append to the first non-nil map
fmt.Println(Append(nil, nil, nil, map[string]string{
	"hello": "world",
}, map[string]string{
	"answer": "42",
}))

// appending nothing results in an empty map
fmt.Println(Append[string, string]())

// appending to the nil map results in an empty map
fmt.Println(Append[string, string](nil))

Output:

map[answer:42 hello:world]
map[answer:42 hello:world]
map[]
map[]

func AsAny

func AsAny[T any](slice []T) []any

AsAny returns a new slice containing the same elements as slice, but as any.

func Deduplicate

func Deduplicate[T comparable, S ~[]T](slice S) S

Deduplicate removes duplicates from the given slice in place. Elements are not reordered.

func First

func First[T any](slice []T, test func(T) bool) T

First returns the first value in slice for which test returns true. When no such value exists, returns the zero value of T.

To find the index of such an element, use slices.IndexFunc.

Example

values := []int{-1, 0, 1}
fmt.Println(
	First(values, func(v int) bool {
		return v > 0
	}),
)

fmt.Println(
	First(values, func(v int) bool {
		return v > 2 // no such value exists
	}),
)

Output:

1
0

func IterateSorted

func IterateSorted[K cmp.Ordered, V any](M map[K]V, f func(k K, v V) bool) bool

IterateSorted iterates over the map, calling f for each element. Iteration is performed in ascending order of the keys.

If f returns false, iteration is stopped early. IterateSorted returns false if the iteration was stopped early, and true otherwise.

Example

m := map[int]string{
	0: "hello",
	1: "world",
}

IterateSorted(m, func(k int, v string) bool {
	fmt.Printf("%d: %v\n", k, v)
	return true
})

Output:

0: hello
1: world

Example (Early)

Demonstrates how to stop an iteration early.

m := map[int]string{
	0: "hello",
	1: "world",
	2: "i",
	3: "like",
	4: "you",
}

IterateSorted(m, func(k int, v string) bool {
	fmt.Printf("%d: %v\n", k, v)
	// We return false to stop the iteration.
	// Here this happens at k = 1.
	return k < 1
})

Output:

0: hello
1: world

func KeepFunc

func KeepFunc[T any, S ~[]T](slice S, filter func(T) bool) S

KeepFunc modifies slice in-place to those elements where filter returns true. KeepFunc never re-allocates, invalidating the previous value of slice. Values in the old slice, but no longer referenced by the new slice are zeroed out.

KeepFunc guarantees that the filter function is called in element order. KeepFunc guarantees that the return value is non-nil if and only if slice is non-nil.

To create a new slice instead, use [FilterClone].

Example

values := []string{"hello", "world", "how", "are", "you"}
valuesF := KeepFunc(values, func(s string) bool {
	return s != "how"
})
fmt.Printf("%#v\n%#v\n", values, valuesF)

Output:

[]string{"hello", "world", "are", "you", ""}
[]string{"hello", "world", "are", "you"}

Example (AllFalse)

values := []string{"hello", "world", "how", "are", "you"}
valuesF := KeepFunc(values, func(s string) bool { return false })
fmt.Printf("%#v\n%#v\n", values, valuesF)

Output:

[]string{"", "", "", "", ""}
[]string{}

Example (AllTrue)

values := []string{"hello", "world", "how", "are", "you"}
valuesF := KeepFunc(values, func(s string) bool { return true })
fmt.Printf("%#v\n%#v\n", values, valuesF)

Output:

[]string{"hello", "world", "how", "are", "you"}
[]string{"hello", "world", "how", "are", "you"}

func KeepFuncClone

func KeepFuncClone[T any, S ~[]T](slice S, filter func(T) bool) (results S)

KeepFuncClone behaves like KeepFunc, except that it generates a new slice and keeps the original slice valid.

Example

values := []string{"hello", "world", "how", "are", "you"}
valuesF := KeepFuncClone(values, func(s string) bool {
	return s != "how"
})
fmt.Printf("%#v\n%#v\n", values, valuesF)

Output:

[]string{"hello", "world", "how", "are", "you"}
[]string{"hello", "world", "are", "you"}

Example (Order)

values := []string{"hello", "world", "how", "are", "you"}

// the KeepFunc function is guaranteed to be called in order
index := 0
valuesF := KeepFuncClone(values, func(s string) bool {
	// KeepFunc every even element
	res := index%2 == 0
	index++
	return res
})
fmt.Printf("%#v\n%#v\n", values, valuesF)

Output:

[]string{"hello", "world", "how", "are", "you"}
[]string{"hello", "how", "you"}

func MapSlice

func MapSlice[T1 any, S1 ~[]T1, T2 any](slice S1, f func(T1) T2) []T2

MapSlice generates a new slice by passing each element of S through f.

Example

values := []int{-1, 0, 1}
fmt.Println(
	MapSlice(values, func(v int) float64 {
		return float64(v) / 2
	}),
)

Output:

[-0.5 0 0.5]

func MapValues

func MapValues[K comparable, V1, V2 any](M map[K]V1, f func(K, V1) V2) map[K]V2

MapValues creates a new map which has the same keys as M. The values of the map are determined by passing the old key and values into f.

Example

m := map[int]string{
	0: "hi",
	1: "world",
}
m2 := MapValues(m, func(k int, v string) int {
	return len(v)
})
fmt.Println(m2)

Output:

map[0:2 1:5]

func NonSequential

func NonSequential[T cmp.Ordered, S ~[]T](slice S, test func(prev, current T) bool) S

NonSequential sorts slice, and then removes sequential elements for which test() returns true. NonSequential does not re-allocate, but uses the existing slice.

Example

values := []string{"a", "aa", "b", "bb", "c"}
fmt.Println(
	NonSequential(values, func(prev, current string) bool {
		return strings.HasPrefix(current, prev)
	}),
)

Output:

[a b c]

func Partition

func Partition[T any, S ~[]T, P comparable](slice S, f func(T) P) map[P]S

Partition partitions elements of s into sub-slices by passing them through f. Order of elements within sub-slices is preserved.

Example

values := []int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
fmt.Println(
	Partition(values, func(v int) int {
		return v % 3
	}),
)

Output:

map[0:[0 3 6 9] 1:[1 4 7 10] 2:[2 5 8]]