slice

README

The missing slice package

A Go-generics (Go 1.18) based functional library with no side-effects that adds the following functions to a slice package:

• Unique(): removes duplicate items from a slice
• SortedUnique(): removes duplicate items from a sorted slice. Fast!
• Sort(): Sorts a slice
• SortBy(): Sorts a slice by arbitrary criteria
• Compare(): Iterates two slices comparing them together
• Subtract(): subtract one slice from another
• Map(): map over a slice and transform it
• Reduce(): reduce a slice to a single value
• Index(): return the index of an element
• SortedIndex(): return the index of an element in a sorted list. Fast!
• First(): return the first element
• Last(): return the last element
• Select(): select all elements matching some specified criteria
• Contains(): returns true if the slice contains an element
• SortedContains(): returns true if the sorted slice contains an element. Fast!
• Pop(): pop the last element off the list
• Shift(): shift the first element off the list
• Unshift(): shift an element into the first place (prepend)
• Find(): find the first element in a slice that matches some criteria

Method signatures:

(where T is almost any type)

• slice.Unique([]T) []T
• slice.SortedUnique([]T) []T
• slice.Sort([]T) []T
• slice.SortBy([]T, sortFunc func(slice []T, i, j int) bool) []T
• slice.Compare(s1, s2 []T, left, equal, right func(elem T))
• slice.Subtract(s1, s2 []T) []T
• slice.Map([]T, func(i int, elem T) T) []T
• slice.Reduce(items []T, initialAccumulator T, f AccumulatorFunc[T]) T
• slice.Index([]T, elem T) int
• slice.SortedIndex([]T, elem T) int
• slice.First([]T) (T, bool)
• slice.Last([]T) (T, bool)
• slice.Select([]T, func(i int, elem T) T) []T
• slice.Contains([]T, elem T) bool
• slice.SortedContains([]T, elem T) bool
• slice.Pop([]T) (T, []T)
• slice.Shift([]T) (T, []T)
• slice.Unshift([]T, elem T) []T
• slice.Find([]T, func(i int, elem T) T) (elem T, found bool)

Note the AccumulatorFunc signature is func(acc T, i int, elem T) T

Examples

See tests for more examples. Here are a few:

  // sum function implemented with Reduce
  input := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
	result := slice.Reduce(input, 0, func(acc int, i int, elem int) string {
		return acc + elem
	})
  // result == 55

map from complex structs to string slices

type Group struct {
	Name string
}
groups := []Group{{Name: "users"}, {Name: "admins"}}
names := slice.Map[Group, string](groups, func(group Group) string {
	return group.Name
})
fmt.Println(names) // outputs ["users", "admins"]

Documentation

Index

• func Compare[T Ordered](s1, s2 []T, left, equal, right func(s T))
• func Contains[T comparable](ss []T, s T) bool
• func Find[T any, F FindFunc[T]](ss []T, funcInterface F) (elem T, found bool)
• func First[T any](ss []T) (T, bool)
• func Index[T comparable](ss []T, s T) int
• func Last[T any](ss []T) (T, bool)
• func Map[T any, R any, F MapFunc[T, R]](ss []T, funcInterface F) []R
• func Pop[T any](ss []T) (T, []T)
• func Reduce[T any](items []T, initialAccumulator T, f AccumulatorFunc[T]) T
• func Select[T any, F SelectFunc[T]](ss []T, funcInterface F) []T
• func Shift[T any](ss []T) (T, []T)
• func Sort[T Ordered](ss []T) []T
• func SortBy[T Ordered](ss []T, sortFunc func(slice []T, i, j int) bool) []T
• func SortedContains[T Ordered](ss []T, s T) bool
• func SortedIndex[T Ordered](ss []T, s T) int
• func SortedUnique[T Ordered](ss []T) []T
• func Subtract[T Ordered](s1, s2 []T) []T
• func Unique[T Ordered](ss []T) []T
• func Unshift[T any](ss []T, elem T) []T
• type AccumulatorFunc
• type FindFunc
• type MapFunc
• type Ordered
• type SelectFunc

Functions

func Compare

func Compare[T Ordered](s1, s2 []T, left, equal, right func(s T))

Compare sorts and iterates s1 and s2. calling left() if the element is only in s1, right() if the element is only in s2, and equal() if it's in both. this is used as the speedy basis for other set operations.

func Contains

func Contains[T comparable](ss []T, s T) bool

Contains returns true if the string is in the slice.

func Find

func Find[T any, F FindFunc[T]](ss []T, funcInterface F) (elem T, found bool)

Find and return the first element that matches. returns false if none found.

func First

func First[T any](ss []T) (T, bool)

First returns the First element, or "" if there are no elements in the slice. First will also return an "ok" bool value that will be false if there were no elements to select from

func Index

func Index[T comparable](ss []T, s T) int

Index returns the index of string in the slice, otherwise -1 if the string is not found.

func Last

func Last[T any](ss []T) (T, bool)

Last returns the Last element, or "" if there are no elements in the slice. Last will also return an "ok" bool value that will be false if there were no elements to select from

func Map

func Map[T any, R any, F MapFunc[T, R]](ss []T, funcInterface F) []R

Map over each element in the slice and perform an operation on it. the result of the operation will replace the element value. Normal func structure is func(i int, s string) string. Also accepts func structure func(s string) string

func Pop

func Pop[T any](ss []T) (T, []T)

Pop pops the last element off a slice and returns the popped element and the remaining slice (note that the original slice is not modified)

func Reduce

func Reduce[T any](items []T, initialAccumulator T, f AccumulatorFunc[T]) T

Reduce (aka inject) iterates over the slice of items and calls the accumulator function for each pass, storing the state in the acc variable through each pass.

func Select

func Select[T any, F SelectFunc[T]](ss []T, funcInterface F) []T

func Shift

func Shift[T any](ss []T) (T, []T)

Shift returns the first element and the remaining slice

func Sort

func Sort[T Ordered](ss []T) []T

Sort returns a new slice that is the sorted copy of the slice it was called on. Unlike sort.Strings, it does not mutate the original slice

func SortBy

func SortBy[T Ordered](ss []T, sortFunc func(slice []T, i, j int) bool) []T

SortBy returns a new, slice that is the sorted copy of the slice it was called on, using sortFunc to interpret the string as a sortable integer value. It does not mutate the original slice

func SortedContains

func SortedContains[T Ordered](ss []T, s T) bool

SortedContains returns true if the string is in an already sorted slice. it's faster than Contains for large slices

func SortedIndex

func SortedIndex[T Ordered](ss []T, s T) int

SortedIndex returns the index of string in the slice, otherwise -1 if the string is not found. this function will do a log2(n) binary search through the list, which is much faster for large lists. The slice must be sorted in ascending order.

func SortedUnique

func SortedUnique[T Ordered](ss []T) []T

func Subtract

func Subtract[T Ordered](s1, s2 []T) []T

Subtract is a set operation that returns the elements from s1 that are not in s2.

func Unique

func Unique[T Ordered](ss []T) []T

Unique returns a new slice that is sorted with all the duplicate strings removed.

func Unshift

func Unshift[T any](ss []T, elem T) []T

Unshift prepends the element in front of the first value

Types

type AccumulatorFunc

type AccumulatorFunc[T any] func(acc T, i int, s T) T

type FindFunc

type FindFunc[T any] interface {
	~func(T) bool | ~func(int, T) bool
}

type MapFunc

type MapFunc[T any, R any] interface {
	~func(int, T) R | ~func(T) R
}

type Ordered

type Ordered interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr | ~float32 | ~float64 | ~string
}

type SelectFunc

type SelectFunc[T any] interface {
	~func(int, T) bool | ~func(T) bool
}