slices2

README

slices2

Useful generic tools for Go slices.

Released under the MIT License.

See package documentation.

Documentation

Overview

Package slices2 contains slice related helpers missing in standard "slices" package.

To avoid conflicts with standard "slices" package the package named as slices2:

import (
	"github.com/Pilatuz/slices2"
)

Some helpers able to do "in-place" work, i.e. there is no memory allocation for result. Such functions usually have "InPlace" suffix in their names.

Filter and Reject are very similar but use inversed condition. Filter removes elements that DO NOT PASS condition while Reject removes elements that DO PASS condition. Both have option to modify input slice "in-place".

A few helpers allow to do operations on sets: SetAnd and SetOr calculates conjunction and disjunction. SetDiff finds difference: i.e. elements added/removed in another set.

Unique can work with unsorted input (opposite to standard `slices.Compact`) and returns result in new slice.

Index

• func Clone[S ~[]E, E any](s S) S
• func Filter[S ~[]E, E any](condFn func(E) bool, s S) S
• func FilterInPlace[S ~[]E, E any](condFn func(E) bool, s S) S
• func FromChannel[E any](ch <-chan E) []E
• func GroupBy[S ~[]E, E any, K comparable](byFn func(E) K, s S) map[K]S
• func Join[S ~[]E, E any](ss ...S) S
• func Reject[S ~[]E, E any](condFn func(E) bool, s S) S
• func RejectInPlace[S ~[]E, E any](condFn func(E) bool, s S) S
• func ReverseInPlace[S ~[]E, E any](s S)
• func Reversed[S ~[]E, E any](s S) S
• func SetAnd[S ~[]E, E comparable](s1 S, s2 S) S
• func SetAndBy[S ~[]E, E any, K comparable](byFn func(E) K, s1 S, s2 S) S
• func SetDiff[S ~[]E, E comparable](s1 S, s2 S) (out1 S, out2 S)
• func SetDiffBy[S ~[]E, E any, K comparable](byFn func(E) K, s1 S, s2 S) (out1 S, out2 S)
• func SetOr[S ~[]E, E comparable](ss ...S) S
• func SetOrBy[S ~[]E, E any, K comparable](byFn func(E) K, ss ...S) S
• func SetSub[S ~[]E, E comparable](s1 S, s2 S) S
• func SetSubBy[S ~[]E, E any, K comparable](byFn func(E) K, s1 S, s2 S) S
• func SortFuncInPlace[S ~[]E, E any](s S, cmp func(E, E) int)
• func SortInPlace[S ~[]E, E cmp.Ordered](s S)
• func Sorted[S ~[]E, E cmp.Ordered](s S) S
• func SortedFunc[S ~[]E, E any](s S, cmp func(E, E) int) S
• func ToChannel[S ~[]E, E any](s S, bufferSize int) <-chan E
• func Transform[S ~[]E, E any, T any](fn func(E) T, s S) []T
• func Unique[S ~[]E, E comparable](s S) S
• func UniqueBy[S ~[]E, K comparable, E any](byFn func(E) K, s S) S
• func UniqueInPlace[S ~[]E, E comparable](s S) S
• func UniqueInPlaceBy[S ~[]E, K comparable, E any](byFn func(E) K, s S) S

Examples

• Filter
• FromChannel
• Join
• Reject
• Reversed
• SetAnd
• SetDiff
• SetOr
• SetSub
• Sorted
• Transform
• Unique

Functions

func Clone

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

Clone makes copy of a slice.

func Filter

func Filter[S ~[]E, E any](condFn func(E) bool, s S) S

Filter removes elements that DO NOT PASS condition.

Returns new slice with elements removed.

Example

ExampleFilter an example for `Filter` function.

package main

import (
	"fmt"
	"unicode/utf8"

	"github.com/Pilatuz/slices2"
)

func main() {
	ss := []string{"foo", "barbaz"}
	cond := func(s string) bool {
		return utf8.RuneCountInString(s) > 3
	}
	fmt.Println(slices2.Filter(cond, ss))
}

Output:

[barbaz]

func FilterInPlace

func FilterInPlace[S ~[]E, E any](condFn func(E) bool, s S) S

FilterInPlace removes elements that DO NOT PASS condition.

Returns original slice with elements removed in-place.

func FromChannel

func FromChannel[E any](ch <-chan E) []E

FromChannel drains the channel ch into a slice.

It collects ALL the values from channel ch until the channel is closed.

Example

ExampleFromChannel an example for `FromChannel` function.

package main

import (
	"fmt"
	"sync"

	"github.com/Pilatuz/slices2"
)

func main() {
	wg := &sync.WaitGroup{}
	errCh := make(chan error)

	wg.Add(3)
	go func() {
		defer wg.Done()
		errCh <- nil
	}()
	go func() {
		defer wg.Done()
		errCh <- nil
	}()
	go func() {
		defer wg.Done()
		errCh <- nil
	}()

	go func() {
		wg.Wait()
		close(errCh)
	}()

	res := slices2.FromChannel(errCh)
	fmt.Println(res)
}

Output:

[<nil> <nil> <nil>]

func GroupBy

func GroupBy[S ~[]E, E any, K comparable](byFn func(E) K, s S) map[K]S

GroupBy splits an input slice s by some key.

func Join

func Join[S ~[]E, E any](ss ...S) S

Join joins multiple slices.

Example

ExampleJoin an example for `Join` function.

package main

import (
	"fmt"

	"github.com/Pilatuz/slices2"
)

func main() {
	s := slices2.Join(
		[]string{"foo", "bar"},
		[]string{"baz"})
	fmt.Println(s)
}

Output:

[foo bar baz]

func Reject

func Reject[S ~[]E, E any](condFn func(E) bool, s S) S

Reject removes elements that DO PASS condition.

Returns new slice with elements removed.

Example

ExampleReject an example for `Reject` function.

package main

import (
	"fmt"
	"unicode/utf8"

	"github.com/Pilatuz/slices2"
)

func main() {
	ss := []string{"foo", "barbaz"}
	cond := func(s string) bool {
		return utf8.RuneCountInString(s) > 3
	}
	fmt.Println(slices2.Reject(cond, ss))
}

Output:

[foo]

func RejectInPlace

func RejectInPlace[S ~[]E, E any](condFn func(E) bool, s S) S

RejectInPlace removes elements that DO PASS condition.

Returns original slice with elements removed in-place.

func ReverseInPlace

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

ReverseInPlace reverses elements of a slice (in place).

func Reversed

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

Reversed returns new slice with elements of input slice s reversed. As opposite to ReverseInPlace this function always allocates new array.

Example

ExampleReversed an example for `Reversed` function.

package main

import (
	"fmt"

	"github.com/Pilatuz/slices2"
)

func main() {
	s := []int{1, 2, 3}
	r := slices2.Reversed(s)
	fmt.Println(s)
	fmt.Println(r)
}

Output:

[1 2 3]
[3 2 1]

func SetAnd

func SetAnd[S ~[]E, E comparable](s1 S, s2 S) S

SetAnd returns the intersection between two sets. I.e. elements presented in both slices.

Example

ExampleSetAnd an example for `SetAnd` function.

package main

import (
	"fmt"

	"github.com/Pilatuz/slices2"
)

func main() {
	a := []string{"foo", "bar"}
	b := []string{"bar", "baz"}

	c := slices2.SetAnd(a, b)
	fmt.Println(a, "&", b, "=", c)
}

Output:

[foo bar] & [bar baz] = [bar]

func SetAndBy

func SetAndBy[S ~[]E, E any, K comparable](byFn func(E) K, s1 S, s2 S) S

SetAndBy returns the intersection between two sets by custom key. I.e. elements presented in both slices.

func SetDiff

func SetDiff[S ~[]E, E comparable](s1 S, s2 S) (out1 S, out2 S)

SetDiff returns the difference between two sets. Where out1 - elements presented in s1 but missing in s2. And out2 - elements presented in s2 but missing in s1.

Example

ExampleSetDiff an example for `SetDiff` function.

package main

import (
	"fmt"

	"github.com/Pilatuz/slices2"
)

func main() {
	a := []string{"foo", "bar"}
	b := []string{"bar", "baz"}

	removed, added := slices2.SetDiff(a, b)
	fmt.Println(a, "diff", b)
	fmt.Println("added:", added)
	fmt.Println("removed:", removed)
}

Output:

[foo bar] diff [bar baz]
added: [baz]
removed: [foo]

func SetDiffBy

func SetDiffBy[S ~[]E, E any, K comparable](byFn func(E) K, s1 S, s2 S) (out1 S, out2 S)

SetDiffBy returns the difference between two slices by custom key. Where out1 - elements presented in s1 but missing in s2. And out2 - elements presented in s2 but missing in s1.

func SetOr

func SetOr[S ~[]E, E comparable](ss ...S) S

SetOr returns the union between two (or more) sets. I.e. unique elements presented in at least one slice.

Example

ExampleSetOr an example for `SetOr` function.

package main

import (
	"fmt"

	"github.com/Pilatuz/slices2"
)

func main() {
	a := []string{"foo", "bar"}
	b := []string{"bar", "baz"}

	c := slices2.SetOr(a, b)
	fmt.Println(a, "|", b, "=", c)
}

Output:

[foo bar] | [bar baz] = [foo bar baz]

func SetOrBy

func SetOrBy[S ~[]E, E any, K comparable](byFn func(E) K, ss ...S) S

SetOrBy returns the union between two (or more) sets by custom key. I.e. unique elements presented in at least one slice.

func SetSub

func SetSub[S ~[]E, E comparable](s1 S, s2 S) S

SetSub returns set where all s2 elements removed from s1. I.e. all elements presented in s1 and missing in s2.

Example

ExampleSetSub an example for `SetSub` function.

package main

import (
	"fmt"

	"github.com/Pilatuz/slices2"
)

func main() {
	a := []string{"foo", "bar"}
	b := []string{"bar", "baz"}

	c := slices2.SetSub(a, b)
	fmt.Println(a, "-", b, "=", c)
}

Output:

[foo bar] - [bar baz] = [foo]

func SetSubBy

func SetSubBy[S ~[]E, E any, K comparable](byFn func(E) K, s1 S, s2 S) S

SetSubBy returns set where all s2 elements removed from s1 by custom key. I.e. all elements presented in s1 and missing in s2.

func SortFuncInPlace

func SortFuncInPlace[S ~[]E, E any](s S, cmp func(E, E) int)

SortFuncInPlace sorts input slice s of any type in ascending order using the cmp function. This sort is not guaranteed to be stable.

func SortInPlace

func SortInPlace[S ~[]E, E cmp.Ordered](s S)

SortInPlace sorts an input slice s of any ordered type in ascending order (in place). This sort is not guaranteed to be stable.

func Sorted

func Sorted[S ~[]E, E cmp.Ordered](s S) S

Sorted returns new slice with elements of input slice s sorted. As opposite to SortInPlace this function always allocates new array.

Example

ExampleSorted an example for `Sorted` function.

package main

import (
	"fmt"

	"github.com/Pilatuz/slices2"
)

func main() {
	s := []int{3, 1, 2}
	r := slices2.Sorted(s)
	fmt.Println(s)
	fmt.Println(r)
}

Output:

[3 1 2]
[1 2 3]

func SortedFunc

func SortedFunc[S ~[]E, E any](s S, cmp func(E, E) int) S

SortedFunc returns new slice with elements of input slice s sorted using the cmp function. As opposite to SortFuncInPlace this function always allocates new array.

func ToChannel

func ToChannel[S ~[]E, E any](s S, bufferSize int) <-chan E

ToChannel converts a slice to read-only channel.

All values from slice s will be sent to new channel.

func Transform

func Transform[S ~[]E, E any, T any](fn func(E) T, s S) []T

Transform transforms each element of slice.

Example

ExampleTransform an example for `Transform` function.

package main

import (
	"fmt"
	"strconv"

	"github.com/Pilatuz/slices2"
)

func main() {
	fromStr := func(s string) int {
		out, _ := strconv.Atoi(s)
		return out
	}
	ss := []string{"123", "456"}
	ii := slices2.Transform(fromStr, ss)
	fmt.Println(ii)
}

Output:

[123 456]

func Unique

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

Unique gets only unique elements.

Returns new slice with duplicates removed.

Example

ExampleUnique an example for `Unique` function.

package main

import (
	"fmt"

	"github.com/Pilatuz/slices2"
)

func main() {
	s := []int{4, 1, 2, 1, 2, 3, 2, 1}
	fmt.Println(slices2.Unique(s))
}

Output:

[4 1 2 3]

func UniqueBy

func UniqueBy[S ~[]E, K comparable, E any](byFn func(E) K, s S) S

UniqueBy gets only unique elements by custom key.

Returns new slice with duplicates removed.

func UniqueInPlace

func UniqueInPlace[S ~[]E, E comparable](s S) S

UniqueInPlace gets only unique elements.

Returns original slice with duplicates removed in-place.

func UniqueInPlaceBy

func UniqueInPlaceBy[S ~[]E, K comparable, E any](byFn func(E) K, s S) S

UniqueInPlaceBy gets only unique elements by custom key.

Returns original slice with duplicates removed in-place.