slices

package
v0.4.2 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2026 License: MIT Imports: 7 Imported by: 0

README

slices

import "github.com/gechr/x/slices"

Package slices provides slice helpers.

Index

func ContainedByAll

func ContainedByAll[S ~[]E, E comparable](target E, lists ...S) bool

ContainedByAll reports whether target occurs in every one of lists. It returns true when no lists are given.

Example

Every slice must contain the target; no slices reports true.

fmt.Println(xslices.ContainedByAll("a", []string{"a", "b"}, []string{"c", "a"}))
fmt.Println(xslices.ContainedByAll("b", []string{"a", "b"}, []string{"c", "a"}))
fmt.Println(xslices.ContainedByAll[[]string]("a"))

Output:

true
false
true

func ContainedByAny

func ContainedByAny[S ~[]E, E comparable](target E, lists ...S) bool

ContainedByAny reports whether target occurs in any one of lists.

Example

A single slice containing the target suffices; no slices reports false.

fmt.Println(xslices.ContainedByAny("b", []string{"a", "b"}, []string{"c", "d"}))
fmt.Println(xslices.ContainedByAny("z", []string{"a", "b"}, []string{"c", "d"}))
fmt.Println(xslices.ContainedByAny[[]string]("a"))

Output:

true
false
false

func ContainsAll

func ContainsAll[S ~[]E, E comparable](items S, targets ...E) bool

ContainsAll reports whether items contains every one of targets. It returns true when no targets are given.

Example

Every target must occur in the slice; no targets reports true.

fmt.Println(xslices.ContainsAll([]string{"a", "b", "c"}, "a", "c"))
fmt.Println(xslices.ContainsAll([]string{"a", "b", "c"}, "a", "z"))
fmt.Println(xslices.ContainsAll([]string{"a", "b", "c"}))

Output:

true
false
true

func ContainsAny

func ContainsAny[S ~[]E, E comparable](items S, targets ...E) bool

ContainsAny reports whether items contains any one of targets.

Example

A single matching target suffices; no targets reports false.

fmt.Println(xslices.ContainsAny([]string{"a", "b", "c"}, "b", "z"))
fmt.Println(xslices.ContainsAny([]string{"a", "b", "c"}, "x", "z"))
fmt.Println(xslices.ContainsAny([]string{"a", "b", "c"}))

Output:

true
false
false

func ContainsFold

func ContainsFold[S ~[]E, E ~string](items S, target E) bool

ContainsFold reports whether items contains target case-insensitively, using the same simple case-folding as strings.EqualFold.

Example 
tags := []string{"Latest", "Stable"}
fmt.Println(xslices.ContainsFold(tags, "latest"))
fmt.Println(xslices.ContainsFold(tags, "STABLE"))
fmt.Println(xslices.ContainsFold(tags, "beta"))

Output:

true
true
false

func Count

func Count[S ~[]E, E comparable](items S, target E) int

Count returns the number of elements in items equal to target.

Example 
fmt.Println(xslices.Count([]string{"a", "b", "a", "c", "a"}, "a"))
fmt.Println(xslices.Count([]string{"a", "b"}, "z"))

Output:

3
0

func CountFunc

func CountFunc[S ~[]E, E any](items S, match func(E) bool) int

CountFunc returns the number of elements in items satisfying match.

Example 
isEven := func(n int) bool { return n%2 == 0 }
fmt.Println(xslices.CountFunc([]int{1, 2, 3, 4, 5, 6}, isEven))

Output:

3

func Difference

func Difference[S ~[]E, E comparable](items S, others ...S) S

Difference returns the elements of items not present in any of others, preserving order and duplicates from items.

Example

Duplicates and order in the first slice are preserved.

fmt.Println(xslices.Difference([]int{1, 1, 2, 3}, []int{2}))
fmt.Println(xslices.Difference([]int{1, 2, 3}, []int{2}, []int{3}))

Output:

[1 1 3]
[1]

func Filter

func Filter[S ~[]E, E any](items S, keep func(E) bool) S

Filter returns the elements of items satisfying keep, preserving their original order.

Example 
items := []int{1, 2, 3, 4, 5, 6}
fmt.Println(xslices.Filter(items, func(n int) bool { return n%2 == 0 }))

Output:

[2 4 6]

func Format

func Format(format string, args ...any) []string

Format returns the result of applying fmt.Sprintf(format, ...) once per element of the shortest slice in args, substituting each slice argument with its i'th element while repeating non-slice arguments unchanged. If args contains no slices, it returns a single formatted string.

Byte slices ([]byte and named types with that underlying type) are treated as scalars rather than iterated, so they format as a single value.

Example

Scalar arguments repeat for every element; the shortest slice determines the result length.

names := []string{"Valentina", "Ander", "Olivia", "Sam"}
fmt.Println(xslices.Format("Hello, %s!", names))
fmt.Println(xslices.Format("%s, %s!", "Salutations", names))

Output:

[Hello, Valentina! Hello, Ander! Hello, Olivia! Hello, Sam!]
[Salutations, Valentina! Salutations, Ander! Salutations, Olivia! Salutations, Sam!]

func Intersect

func Intersect[S ~[]E, E comparable](items S, others ...S) S

Intersect returns the elements of items also present in every one of others, preserving order and duplicates from items.

Example 
fmt.Println(xslices.Intersect([]string{"a", "b", "c"}, []string{"c", "b", "d"}))
fmt.Println(xslices.Intersect([]int{1, 2, 3}, []int{2, 3}, []int{2}))

Output:

[b c]
[2]

func LastIndex

func LastIndex[S ~[]E, E comparable](items S, target E) int

LastIndex returns the index of the last occurrence of target in items, or -1 if not present.

Example 
fmt.Println(xslices.LastIndex([]string{"a", "b", "a", "c"}, "a"))
fmt.Println(xslices.LastIndex([]string{"a", "b"}, "z"))

Output:

2
-1

func LastIndexFunc

func LastIndexFunc[S ~[]E, E any](items S, match func(E) bool) int

LastIndexFunc returns the index of the last element of items satisfying match, or -1 if none do.

Example 
isEven := func(n int) bool { return n%2 == 0 }
fmt.Println(xslices.LastIndexFunc([]int{2, 3, 4, 5}, isEven))
fmt.Println(xslices.LastIndexFunc([]int{1, 3, 5}, isEven))

Output:

2
-1

func Map

func Map[S ~[]E, E, R any](items S, fn func(E) R) []R

Map returns a new slice containing the result of applying fn to each element of items, preserving order.

func Partition

func Partition[S ~[]E, E any](items S, match func(E) bool) (S, S)

Partition splits items into two slices: elements satisfying match, and elements that do not, preserving the original relative order in both.

Example 
isEven := func(n int) bool { return n%2 == 0 }
even, odd := xslices.Partition([]int{1, 2, 3, 4, 5, 6}, isEven)
fmt.Println(even)
fmt.Println(odd)

Output:

[2 4 6]
[1 3 5]

func SortNatural

func SortNatural[S ~[]E, E ~string](s S)

SortNatural sorts a string slice in place in natural order, so embedded numbers compare by value (item2 before item10) rather than lexically. See strings.CompareNatural.

Example

Embedded numbers compare by value, so "item2" sorts before "item10".

items := []string{"item10", "item2", "item1", "item20", "item3"}
xslices.SortNatural(items)
fmt.Println(items)

Output:

[item1 item2 item3 item10 item20]

func Trim

func Trim[S ~[]E, E comparable](items, cutset S) S

Trim returns items with all leading and trailing elements contained in cutset removed. The result is a subslice of items, sharing its backing array.

Example 
fmt.Println(xslices.Trim([]int{0, 0, 1, 2, 0}, []int{0}))
fmt.Println(xslices.Trim([]string{"a", "b", "c", "b", "a"}, []string{"a", "b"}))

Output:

[1 2]
[c]

func TrimLeft

func TrimLeft[S ~[]E, E comparable](items, cutset S) S

TrimLeft returns items with all leading elements contained in cutset removed. The result is a subslice of items, sharing its backing array.

Example 
fmt.Println(xslices.TrimLeft([]int{0, 0, 1, 2, 0}, []int{0}))

Output:

[1 2 0]

func TrimRight

func TrimRight[S ~[]E, E comparable](items, cutset S) S

TrimRight returns items with all trailing elements contained in cutset removed. The result is a subslice of items, sharing its backing array.

Example 
fmt.Println(xslices.TrimRight([]int{0, 0, 1, 2, 0}, []int{0}))

Output:

[0 0 1 2]

func Union

func Union[S ~[]E, E comparable](items S, others ...S) S

Union returns the elements of items followed by the elements of others, in first-seen order with duplicates removed.

Example 
fmt.Println(xslices.Union([]int{1, 2}, []int{2, 3}, []int{3, 4, 1}))

Output:

[1 2 3 4]

func Unique

func Unique[S ~[]E, E comparable](items S) S

Unique returns items in first-seen order with duplicates removed.

Example 
fmt.Println(xslices.Unique([]string{"a", "b", "a", "A", "c", "b"}))

Output:

[a b A c]

func UniqueFold

func UniqueFold[S ~[]E, E ~string](items S) S

UniqueFold returns strings in first-seen order with duplicates removed case-insensitively, using the same simple case-folding as strings.EqualFold.

Example

The first-seen spelling wins; folding matches strings.EqualFold, so Greek final sigma "ς", medial "σ", and capital "Σ" are duplicates.

fmt.Println(xslices.UniqueFold([]string{"Go", "GO", "go", "Rust"}))
fmt.Println(xslices.UniqueFold([]string{"ς", "σ", "Σ"}))

Output:

[Go Rust]
[ς]

func UniqueFunc

func UniqueFunc[S ~[]E, E any, K comparable](items S, key func(E) K) S

UniqueFunc returns items in first-seen order with duplicates removed, where two items are duplicates when key reports the same value for both.

Example

The first-seen item wins for each key.

type user struct {
    name string
    age  int
}
users := []user{{"alice", 30}, {"bob", 25}, {"alice", 40}}
fmt.Println(xslices.UniqueFunc(users, func(u user) string { return u.name }))

Output:

[{alice 30} {bob 25}]

Documentation

Overview

Package slices provides slice helpers.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func ContainedByAll added in v0.3.7 

func ContainedByAll[S ~[]E, E comparable](target E, lists ...S) bool

ContainedByAll reports whether `target` occurs in every one of `lists`. It returns true when no `lists` are given.

Example

Every slice must contain the target; no slices reports true. 

package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.ContainedByAll("a", []string{"a", "b"}, []string{"c", "a"}))
	fmt.Println(xslices.ContainedByAll("b", []string{"a", "b"}, []string{"c", "a"}))
	fmt.Println(xslices.ContainedByAll[[]string]("a"))
}

Output:
true
false
true

func ContainedByAny added in v0.3.7 

func ContainedByAny[S ~[]E, E comparable](target E, lists ...S) bool

ContainedByAny reports whether `target` occurs in any one of `lists`.

Example

A single slice containing the target suffices; no slices reports false. 

package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.ContainedByAny("b", []string{"a", "b"}, []string{"c", "d"}))
	fmt.Println(xslices.ContainedByAny("z", []string{"a", "b"}, []string{"c", "d"}))
	fmt.Println(xslices.ContainedByAny[[]string]("a"))
}

Output:
true
false
false

func ContainsAll 

func ContainsAll[S ~[]E, E comparable](items S, targets ...E) bool

ContainsAll reports whether `items` contains every one of `targets`. It returns true when no `targets` are given.

Example

Every target must occur in the slice; no targets reports true. 

package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.ContainsAll([]string{"a", "b", "c"}, "a", "c"))
	fmt.Println(xslices.ContainsAll([]string{"a", "b", "c"}, "a", "z"))
	fmt.Println(xslices.ContainsAll([]string{"a", "b", "c"}))
}

Output:
true
false
true

func ContainsAny 

func ContainsAny[S ~[]E, E comparable](items S, targets ...E) bool

ContainsAny reports whether `items` contains any one of `targets`.

Example

A single matching target suffices; no targets reports false. 

package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.ContainsAny([]string{"a", "b", "c"}, "b", "z"))
	fmt.Println(xslices.ContainsAny([]string{"a", "b", "c"}, "x", "z"))
	fmt.Println(xslices.ContainsAny([]string{"a", "b", "c"}))
}

Output:
true
false
false

func ContainsFold 

func ContainsFold[S ~[]E, E ~string](items S, target E) bool

ContainsFold reports whether `items` contains `target` case-insensitively, using the same simple case-folding as strings.EqualFold.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	tags := []string{"Latest", "Stable"}
	fmt.Println(xslices.ContainsFold(tags, "latest"))
	fmt.Println(xslices.ContainsFold(tags, "STABLE"))
	fmt.Println(xslices.ContainsFold(tags, "beta"))
}

Output:
true
true
false

func Count 

func Count[S ~[]E, E comparable](items S, target E) int

Count returns the number of elements in `items` equal to `target`.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.Count([]string{"a", "b", "a", "c", "a"}, "a"))
	fmt.Println(xslices.Count([]string{"a", "b"}, "z"))
}

Output:
3
0

func CountFunc 

func CountFunc[S ~[]E, E any](items S, match func(E) bool) int

CountFunc returns the number of elements in `items` satisfying `match`.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	isEven := func(n int) bool { return n%2 == 0 }
	fmt.Println(xslices.CountFunc([]int{1, 2, 3, 4, 5, 6}, isEven))
}

Output:
3

func Difference 

func Difference[S ~[]E, E comparable](items S, others ...S) S

Difference returns the elements of `items` not present in any of `others`, preserving order and duplicates from `items`.

Example

Duplicates and order in the first slice are preserved. 

package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.Difference([]int{1, 1, 2, 3}, []int{2}))
	fmt.Println(xslices.Difference([]int{1, 2, 3}, []int{2}, []int{3}))
}

Output:
[1 1 3]
[1]

func Filter added in v0.3.6 

func Filter[S ~[]E, E any](items S, keep func(E) bool) S

Filter returns the elements of `items` satisfying `keep`, preserving their original order.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	items := []int{1, 2, 3, 4, 5, 6}
	fmt.Println(xslices.Filter(items, func(n int) bool { return n%2 == 0 }))
}

Output:
[2 4 6]

func Format added in v0.3.9 

func Format(format string, args ...any) []string

Format returns the result of applying fmt.Sprintf(format, ...) once per element of the shortest slice in args, substituting each slice argument with its i'th element while repeating non-slice arguments unchanged. If args contains no slices, it returns a single formatted string.

Byte slices ([]byte and named types with that underlying type) are treated as scalars rather than iterated, so they format as a single value.

Example

Scalar arguments repeat for every element; the shortest slice determines the result length. 

package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	names := []string{"Valentina", "Ander", "Olivia", "Sam"}
	fmt.Println(xslices.Format("Hello, %s!", names))
	fmt.Println(xslices.Format("%s, %s!", "Salutations", names))
}

Output:
[Hello, Valentina! Hello, Ander! Hello, Olivia! Hello, Sam!]
[Salutations, Valentina! Salutations, Ander! Salutations, Olivia! Salutations, Sam!]

func Intersect 

func Intersect[S ~[]E, E comparable](items S, others ...S) S

Intersect returns the elements of `items` also present in every one of `others`, preserving order and duplicates from `items`.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.Intersect([]string{"a", "b", "c"}, []string{"c", "b", "d"}))
	fmt.Println(xslices.Intersect([]int{1, 2, 3}, []int{2, 3}, []int{2}))
}

Output:
[b c]
[2]

func LastIndex 

func LastIndex[S ~[]E, E comparable](items S, target E) int

LastIndex returns the index of the last occurrence of `target` in `items`, or -1 if not present.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.LastIndex([]string{"a", "b", "a", "c"}, "a"))
	fmt.Println(xslices.LastIndex([]string{"a", "b"}, "z"))
}

Output:
2
-1

func LastIndexFunc 

func LastIndexFunc[S ~[]E, E any](items S, match func(E) bool) int

LastIndexFunc returns the index of the last element of `items` satisfying `match`, or -1 if none do.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	isEven := func(n int) bool { return n%2 == 0 }
	fmt.Println(xslices.LastIndexFunc([]int{2, 3, 4, 5}, isEven))
	fmt.Println(xslices.LastIndexFunc([]int{1, 3, 5}, isEven))
}

Output:
2
-1

func Map added in v0.2.17 

func Map[S ~[]E, E, R any](items S, fn func(E) R) []R

Map returns a new slice containing the result of applying `fn` to each element of `items`, preserving order.

func Partition 

func Partition[S ~[]E, E any](items S, match func(E) bool) (S, S)

Partition splits `items` into two slices: elements satisfying `match`, and elements that do not, preserving the original relative order in both.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	isEven := func(n int) bool { return n%2 == 0 }
	even, odd := xslices.Partition([]int{1, 2, 3, 4, 5, 6}, isEven)
	fmt.Println(even)
	fmt.Println(odd)
}

Output:
[2 4 6]
[1 3 5]

func SortNatural 

func SortNatural[S ~[]E, E ~string](s S)

SortNatural sorts a string slice in place in natural order, so embedded numbers compare by value (`item2` before `item10`) rather than lexically. See github.com/gechr/x/strings.CompareNatural.

Example

Embedded numbers compare by value, so "item2" sorts before "item10". 

package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	items := []string{"item10", "item2", "item1", "item20", "item3"}
	xslices.SortNatural(items)
	fmt.Println(items)
}

Output:
[item1 item2 item3 item10 item20]

func Trim 

func Trim[S ~[]E, E comparable](items, cutset S) S

Trim returns `items` with all leading and trailing elements contained in `cutset` removed. The result is a subslice of `items`, sharing its backing array.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.Trim([]int{0, 0, 1, 2, 0}, []int{0}))
	fmt.Println(xslices.Trim([]string{"a", "b", "c", "b", "a"}, []string{"a", "b"}))
}

Output:
[1 2]
[c]

func TrimLeft 

func TrimLeft[S ~[]E, E comparable](items, cutset S) S

TrimLeft returns `items` with all leading elements contained in `cutset` removed. The result is a subslice of `items`, sharing its backing array.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.TrimLeft([]int{0, 0, 1, 2, 0}, []int{0}))
}

Output:
[1 2 0]

func TrimRight 

func TrimRight[S ~[]E, E comparable](items, cutset S) S

TrimRight returns `items` with all trailing elements contained in `cutset` removed. The result is a subslice of `items`, sharing its backing array.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.TrimRight([]int{0, 0, 1, 2, 0}, []int{0}))
}

Output:
[0 0 1 2]

func Union 

func Union[S ~[]E, E comparable](items S, others ...S) S

Union returns the elements of `items` followed by the elements of `others`, in first-seen order with duplicates removed.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.Union([]int{1, 2}, []int{2, 3}, []int{3, 4, 1}))
}

Output:
[1 2 3 4]

func Unique 

func Unique[S ~[]E, E comparable](items S) S

Unique returns `items` in first-seen order with duplicates removed.

Example 
package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.Unique([]string{"a", "b", "a", "A", "c", "b"}))
}

Output:
[a b A c]

func UniqueFold 

func UniqueFold[S ~[]E, E ~string](items S) S

UniqueFold returns strings in first-seen order with duplicates removed case-insensitively, using the same simple case-folding as strings.EqualFold.

Example

The first-seen spelling wins; folding matches strings.EqualFold, so Greek final sigma "ς", medial "σ", and capital "Σ" are duplicates. 

package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	fmt.Println(xslices.UniqueFold([]string{"Go", "GO", "go", "Rust"}))
	fmt.Println(xslices.UniqueFold([]string{"ς", "σ", "Σ"}))
}

Output:
[Go Rust]
[ς]

func UniqueFunc 

func UniqueFunc[S ~[]E, E any, K comparable](items S, key func(E) K) S

UniqueFunc returns `items` in first-seen order with duplicates removed, where two items are duplicates when `key` reports the same value for both.

Example

The first-seen item wins for each key. 

package main

import (
	"fmt"

	xslices "github.com/gechr/x/slices"
)

func main() {
	type user struct {
		name string
		age  int
	}
	users := []user{{"alice", 30}, {"bob", 25}, {"alice", 40}}
	fmt.Println(xslices.UniqueFunc(users, func(u user) string { return u.name }))
}

Output:
[{alice 30} {bob 25}]

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.