gollection

gollection

A generic generic collection library based on go's generic implementation.

Core Interfaces

type Iterable[T any] interface {
	Iter() Iterator[T]
}

type Iterator[T any] interface {
	Next() util.Opt[T]
}

gollection applies the iterator pattern design, the core interface consists of Iterator and Iterable.

Iterator is responsible for providing iterative functionality, Iterator is unidirectional and lazy, each call to next will only return one result.

Iterable is responsible for providing Iterator, the implementation type determines whether the provided Iterator is reusable.

The inert traversal feature allows the combination of higher-order functions without significant overhead and can provide a richer combination of functions.

Here is a simple example of direct traversal:

func printAll[T any](it Iterable[T]) {
	for iter = it.Iter(); true; {
		if v, ok := iter.Next().Get(); ok {
			println(v)
		} else {
			break
		}
	}
}

Streaming operations

gollection provides a rich set of stream manipulation functions that can be used in combination with any Iterable.

Here is an example of a simple combination used:

func foo() {
	show := func(i int) {
		println(i)
	}
	even := func(i int) bool {
		return i%2 == 0
	}
	square := func(i int) int {
		return i * i
	}
	ForEach(show, Map(square, Filter(even, Slice[int]([]int{1, 2, 3, 4, 5, 6, 7}).Iterator())))
    // Result:
    // 4
    // 16
    // 36
}

Transform Iterable

A series of conversion functions are provided to process one Iterable conversion to another Iterable. these conversions are not executed immediately and only act one at a time when iterating.

func Enumerate[T any](it Iterator[T]) Iterator[Pair[int, T]]
func Map[T any, R any](transform func(T) R, it Iterator[T]) Iterator[R]
func Filter[T any](predicate func(T) bool, it Iterator[T]) Iterator[T]
func Limit[T any](count int, it Iterator[T]) Iterator[T]
func Skip[T any](count int, it Iterator[T]) Iterator[T]
func Step[T any](count int, it Iterator[T]) Iterator[T]
func Concat[T any](left Iterator[T], right Iterator[T]) Iterator[T]
func Flatten[T Iterable[U], U any](it Iterator[T]) Iterator[U]
func Zip[T any, U any](left Iterator[T], right Iterator[U]) Iterator[util.Pair[T, U]]

Terminal Iterable

A set of functions that evaluate the Iterable and are executed immediately.

func Contains[T comparable](target T, it Iterator[T]) bool
func Sum[T Integer | Float](it Iterator[T]) T
func Product[T Integer | Float](it Iterator[T]) T
func Average[T Integer | Float](it Iterator[T]) float64
func Count[T any](it Iterator[T]) int
func Max[T Ordered](it Iterator[T]) util.Opt[T]
func Min[T Ordered](it Iterator[T]) util.Opt[T]
func MaxBy[T any](greater func(T, T) bool, it Iterator[T]) util.Opt[T]
func MinBy[T any](less func(T, T) bool, it Iterator[T]) util.Opt[T]
func ForEach[T any](action func(T), it Iterator[T])
func AllMatch[T any](predicate func(T) bool, it Iterator[T]) bool
func NoneMatch[T any](predicate func(T) bool, it Iterator[T]) bool
func AnyMatch[T any](predicate func(T) bool, it Iterator[T]) bool
func First[T any](it Iterator[T]) util.Opt[T]
func Last[T any](it Iterator[T]) util.Opt[T]
func At[T any](index int, it Iterator[T]) util.Opt[T]
func Reduce[T any](operation func(T, T) T, it Iterator[T]) util.Opt[T]
func Fold[T any, R any](initial R, operation func(T, R) R, it Iterator[T]) R
func Unzip[A any, B any](it Iterator[util.Pair[A, B]]) util.Pair[[]A, []B]
func Collect[T any, S any, R any](collector Collector[S, T, R], it Iterator[T]) R

ToString and ToSlice

In order to make go's native string and slice also iterable, we have introduced ToSlice and ToString to make these two types implement the interface.

var str = "Hello, world!"
var sli = []int{1, 2, 3}
Count(ToString(str).Iter()) // 13
Count(ToSlice(sli).Iter()) // 3

We also provide the version that gets the iterator directly.

Count(ToStringIter(str)) // 13
Count(ToSliceIter(sli)) // 3

Collection

We define a unified collection type interface to describe more information than iterators to facilitate performance optimization.

type Collection[T any] interface {
	Iterable[T]

	Count() int
}

func IsEmpty[T any](c Collection[T]) bool
func IsNotEmpty[T any](c Collection[T]) bool
func ToSlice[T any](c Collection[T]) Slice[T]

List

We provide the List interface, ForwardList interface, BackwardList interface and IndexList interface to describe the ordered sequences, and provide ArrayList and LinkedList as its implementation types.

package list

type List[T any] interface {
	iter.Collection[T]

	Peek() util.Ref[T]
	Push(element T)
	Pop() util.Opt[T]
	Clear()
}

type ForwardList[T any] interface {
	List[T]

	PeekFront() util.Ref[T]
	PushFront(element T)
	PopFront() util.Opt[T]
}

type BackwardList[T any] interface {
	List[T]

	PeekBack() util.Ref[T]
	PopBack() util.Opt[T]
	PushBack(element T)
}

type IndexList[T any] interface {
	List[T]

	At(index int) util.Ref[T]
	Insert(index int, element T)
	Remove(index int) T
	RemoveRange(at iter.Range[int])
}

func ArrayListOf[T any](elements ...T) *ArrayList[T]
func MakeArrayList[T any](capacity int) *ArrayList[T]
func ArrayListFrom[T any](collection iter.Collection[T]) *ArrayList[T]

type ArrayList[T any] struct {}
func (a *ArrayList[T]) LastIndex() int
func (a *ArrayList[T]) Peek() util.Ref[T]
func (a *ArrayList[T]) Push(element T)
func (a *ArrayList[T]) PushAll(elements iter.Collection[T])
func (a *ArrayList[T]) Pop() util.Opt[T]
func (a *ArrayList[T]) PeekBack() util.Ref[T]
func (a *ArrayList[T]) PushBack(element T)
func (a *ArrayList[T]) PushBackAll(elements iter.Collection[T])
func (a *ArrayList[T]) PopBack() util.Opt[T]
func (a *ArrayList[T]) PeekFront() util.Ref[T]
func (a *ArrayList[T]) At(index int) util.Ref[T]
func (a *ArrayList[T]) Insert(index int, element T)
func (a *ArrayList[T]) InsertAll(index int, elements iter.Collection[T])
func (a *ArrayList[T]) Remove(index int) T
func (a *ArrayList[T]) RemoveRange(at iter.Range[int])
func (a *ArrayList[T]) Reserve(additional int)
func (a *ArrayList[T]) Count() int
func (a *ArrayList[T]) Capacity() int
func (a *ArrayList[T]) Iterator() iter.Iterator[T]
func (a *ArrayList[T]) Clone() *ArrayList[T]
func (a *ArrayList[T]) Clear()

func LinkedListOf[T any](elements ...T) *LinkedList[T]
func LinkedListFrom[T any](collection iter.Collection[T]) *LinkedList[T]

type LinkedList[T any] struct {}
func (a *LinkedList[T]) Peek() util.Ref[T]
func (a *LinkedList[T]) Push(element T)
func (a *LinkedList[T]) Pop() util.Opt[T]
func (a *LinkedList[T]) PeekFront() util.Ref[T]
func (a *LinkedList[T]) PushFront(element T)
func (a *LinkedList[T]) PopFront() util.Opt[T]
func (a *LinkedList[T]) PeekBack() util.Ref[T]
func (a *LinkedList[T]) PushBack(element T)
func (a *LinkedList[T]) PopBack() util.Opt[T]
func (a *LinkedList[T]) Count() int
func (a *LinkedList[T]) Iterator() iter.Iterator[T]
func (a *LinkedList[T]) Clone() *LinkedList[T]
func (a *LinkedList[T]) Clear()
func (a *LinkedList[T]) Front() *LinkedListNode[T]
func (a *LinkedList[T]) Back() *LinkedListNode[T]
func (a *LinkedList[T]) Remove(mark *LinkedListNode[T]) T
func (a *LinkedList[T]) InsertFront(newElement T) *LinkedListNode[T]
func (a *LinkedList[T]) InsertBack(newElement T) *LinkedListNode[T]
func (a *LinkedList[T]) InsertAfter(mark *LinkedListNode[T], newElement T) *LinkedListNode[T]
func (a *LinkedList[T]) InsertBefore(mark *LinkedListNode[T], newElement T) *LinkedListNode[T]

type LinkedListNode[T any] struct {
	Value T
}
func (a *LinkedListNode[T]) Next() *LinkedListNode[T]
func (a *LinkedListNode[T]) Prev() *LinkedListNode[T]

Dict

We provide the Dict interface to describe the mapping type, and provide HashMap as its implementation type.

package dict

type Dict[K any, V any] interface {
	iter.Collection[util.Pair[K, V]]

	Contains(key K) bool
	At(key K) util.Ref[V]
	Put(key K, value V) util.Opt[V]
	Remove(key K) util.Opt[V]
	Clear()
}

func Equals[K any, V comparable](l Dict[K, V], r Dict[K, V]) bool

func HashDictOf[K comparable, V any](elements ...util.Pair[K, V]) *HashDict[K, V]
func MakeHashDict[K comparable, V any](capacity int) *HashDict[K, V]
func MakeHashDictWithHasher[K comparable, V any](hasher func(K) uint64, capacity int) *HashDict[K, V]
func HashDictFrom[K comparable, V any](collection iter.Collection[util.Pair[K, V]]) *HashDict[K, V]

type HashDict[K comparable, V any] struct
func (a *HashDict[K, V]) Count() int
func (a *HashDict[K, V]) Contains(key K) bool
func (a *HashDict[K, V]) At(key K) util.Ref[V]
func (a *HashDict[K, V]) Put(key K, value V) util.Opt[V]
func (a *HashDict[K, V]) Remove(key K) util.Opt[V]
func (a *HashDict[K, V]) Iterator() iter.Iterator[util.Pair[K, V]]
func (a *HashDict[K, V]) Clone() *HashDict[K, V]
func (a *HashDict[K, V]) Clear()

Set

We provide the Set interface to describe the element-unique collection type, and we provide HashSet as its implementation type.

package set

type Set[T any] interface {
	iter.Collection[T]

	Contains(element T) bool
	Put(element T) bool
	Remove(element T) util.Opt[T]
	Clear()
}

func HashSetOf[T comparable](elements ...T) *HashSet[T]
func MakeHashSet[T comparable](capacity int) *HashSet[T]
func MakeHashSetWithHasher[T comparable](hasher func(data T) uint64, capacity int) *HashSet[T]
func HashSetFrom[T comparable](collection iter.Collection[T]) *HashSet[T]

type HashSet[T comparable] dict.HashDict[T, util.Void]
func (a *HashSet[T]) Count() int
func (a *HashSet[T]) Put(element T) bool
func (a *HashSet[T]) Remove(element T) util.Opt[T]
func (a *HashSet[T]) Contains(element T) bool
func (a *HashSet[T]) Iterator() iter.Iterator[T]
func (a *HashSet[T]) Clone() *HashSet[T]
func (a *HashSet[T]) Clear()

Stack

We provide the Stack interface to describe the stack data structure and provide ArrayStack and LinkedStack as its implementation types.

package stack

type Stack[T any] interface {
	iter.Collection[T]

	Push(element T)
	Pop() util.Opt[T]
	Peek() util.Ref[T]
	Clear()
}

func ArrayStackOf[T any](elements ...T) *ArrayStack[T]
func MakeArrayStack[T any](capacity int) *ArrayStack[T]
func ArrayStackFrom[T any](collection iter.Collection[T]) *ArrayStack[T]

type ArrayStack[T any] struct {}
func (a *ArrayStack[T]) Count() int
func (a *ArrayStack[T]) Push(element T)
func (a *ArrayStack[T]) PushAll(elements iter.Collection[T])
func (a *ArrayStack[T]) Pop() util.Opt[T]
func (a *ArrayStack[T]) Peek() util.Ref[T]
func (a *ArrayStack[T]) Iterator() iter.Iterator[T]
func (a *ArrayStack[T]) Clone() *ArrayStack[T]
func (a *ArrayStack[T]) Reserve(additional int)
func (a *ArrayStack[T]) Capacity() int
func (a *ArrayStack[T]) Clear()

func LinkedStackOf[T any](elements ...T) *LinkedStack[T]
func LinkedStackFrom[T any](collection iter.Collection[T]) *LinkedStack[T]

type LinkedStack[T any] struct {}
func (a *LinkedStack[T]) Count() int
func (a *LinkedStack[T]) Push(element T)
func (a *LinkedStack[T]) Pop() util.Opt[T]
func (a *LinkedStack[T]) Peek() util.Ref[T]
func (a *LinkedStack[T]) Iterator() iter.Iterator[T]
func (a *LinkedStack[T]) Clone() *ArrayStack[T]
func (a *LinkedStack[T]) Clear()

Util

We have also introduced several convenient util types for use, and indeed gollection uses them as well. Including Void, Pair, Ref, Opt, Result.

package util

type Void struct{}

func PairOf[T1 any, T2 any](f T1, s T2) Pair[T1, T2]

type Pair[T1 any, T2 any] struct {
	First  T1
	Second T2
}
func (a Pair[T1, T2]) Val() (T1, T2)

func RefOf[T any](v *T) Ref[T]

type Ref[T any] struct {}
func (a Ref[T]) Val() (v T, ok bool)
func (a Ref[T]) Get() T 
func (a Ref[T]) Set(v T) T
func (a Ref[T]) IsNil() bool
func (a Ref[T]) IsNotNil() bool

func Some[T any](a T) Opt[T]
func None[T any]() Opt[T]

type Opt[T any] struct {}
func (a Opt[T]) Val() (value T, ok bool)
func (a Opt[T]) Or(value T) T
func (a Opt[T]) OrDefault() T
func (a Opt[T]) OrPanic() T
func (a Opt[T]) IsSome() bool
func (a Opt[T]) IsNone() bool
func (a Opt[T]) IfSome(action func(value T))
func (a Opt[T]) IfNone(action func())
func (a Opt[T]) Next() Opt[T]

func Ok[T any](a T) Result[T]
func Err[T any](a error) Result[T]

type Result[T any] struct {}
func (a Result[T]) Val() (value T, err error)
func (a Result[T]) Or(value T) T
func (a Result[T]) OrDefault() (v T)
func (a Result[T]) OrPanic() T
func (a Result[T]) IsOk() bool
func (a Result[T]) IsErr() bool
func (a Result[T]) IfOk(action func(value T))
func (a Result[T]) IfErr(action func(err error))