gogcoll

package module
v0.0.0-...-c17f90e Latest Latest
Warning

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

 Go to latest Published: Mar 30, 2022 License: GPL-3.0 Imports: 1 Imported by: 0

README

Golang Generic Collections - gogcoll

Build Status Coverage Status Go Reference Go Report Card

A small collection of useful generic Golang collections. There are two helpful collection interfaces. Iterator[T] is an eager iteration primitive, while Seq[T] is lazy. The full Seq[T] comes with some helpful methods, which implies a lot of extra burden to implement. The smallest possible sequence is defined by BasicSeq[T] which is quite easy to implement. You can use FullSeqFrom() to turn any BasicSeq[T] into a Seq[T].

The package implements a completely new data type, a Set[T]. This is derived from the built in dictionaries in Golang. On top of that, many helper types have been added to simplify working with different data types. For maps, the most important are Keys[K, V] and Values[K, V]. For slices, Slice[T] exists.

Finally, the package also supplies various function signatures to clarify what types are used in various places. These are divided up in three categories - procedures, functions and predicates. A procedure is a function that doesn't return a value. A function returns a value and a predicate is a function that returns a boolean. These types are Proc1, Proc2, and Proc3, FixedFunction, Func1, Func2, Func3 and FuncN, and Predicate, Predicate2 and Predicate3.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Append 

func Append[T any](vs []T, v T) []T

Append wraps the built in append, so that you can pass it around as a function object

func Filter 

func Filter[T any, R Adder[T]](values Iterator[T], p Predicate[T], result R) R

Filter takes an iterator of values and a predicate function and a result which can be added into. It will go through all values, and add the elements for which the predicate returns true to the result.

func FilterIntoSlice 

func FilterIntoSlice[T any](values Iterator[T], p Predicate[T]) []T

FilterIntoSlice uses Filter to add every element from the iterator where the predicate returns true to a slice, and return that slice.

func Map 

func Map[T any, U any, R Adder[U]](values Iterator[T], transform func(T) U, result R) R

Map will turn the values in the given iterator into values of another type, using the transform function, and then adding these resulting values to the given Adder, and returning it.

func MapIntoSlice 

func MapIntoSlice[T any, U any](values Iterator[T], transform func(T) U) []U

MapIntoSlice transforms the values given in the iterator using the transform function and returns a slice of these resulting values.

func Reduce 

func Reduce[T any, R any](values Iterator[T], initial R, f func(R, T) R) R

Reduce will iterate over the values in the iterator and chain the values together with the previous value generated by the function. The initial parameter will be the start of this chain, and the result of the last call will be the result of the Reduce function call. This function is sometimes known as Fold or Inject instead of Reduce.

Types

type Adder 

type Adder[T any] interface {
	// Add will take a value of the generic type T and add it to the underlying container.
	Add(T)
}

Adder is an interface that corresponds to a type that can mutably add an item to its underlying type. This type is used in places such as `Map` and `Reduce` in order to generically inject result data into arbitrary containers.

type AddingEntry 

type AddingEntry[K comparable, V any] map[K]V

AddingEntry is a wrapper type that allows you to use a map in a setting where you want a sequence or collection operation to add entries to a map, for example using Filter or Reduce.

func (AddingEntry[K, V]) Add 

func (m AddingEntry[K, V]) Add(e Entry[K, V])

Add will add the key with the specified value to the underlying map

type BasicSeq 

type BasicSeq[T any] interface {
	// Next returns the next possible element from the sequence. If the sequence has
	// reached its end, it will return the zero value for the generic type T.
	// Every call to Next will move the sequence forward one step.
	Next() T
	// HasNext returns true if there are more elements in the sequence, and false otherwise.
	// It is safe to call HasNext multiple times without calling Next inbetween.
	HasNext() bool
}

BasicSeq is the smallest possible lazy sequence interface. It allows you to pull the next element from the sequence, and check if there are more elements left in the sequence. BasicSeq is not defined to be concurrency safe and no implementation of it can be relied on to be concurrency safe, unless otherwise stated for that implementation.

type Entries 

type Entries[K comparable, V any] map[K]V

Entries allow you to wrap a map and iterate or sequence over the key-value pairs in it

func (Entries[K, V]) Each 

func (s Entries[K, V]) Each(f Proc1[Entry[K, V]])

Each will visit each entry in the map and yield it to the given function.

func (Entries[K, V]) Iter 

func (s Entries[K, V]) Iter() Iterator[Entry[K, V]]

Iter implements the Iterable interface

type Entry 

type Entry[K comparable, V any] struct {
	// Key is the key for the Entry
	Key K
	// Value is the value that the specific key maps to
	Value V
}

Entry is a data structure that can be used to understand pieces of a dictionary/map data structure. Each Entry will have its own key and value of given types.

type FixedFunction 

type FixedFunction[R any] func() R

FixedFunction is a function that doesn't take any arguments and returns one result

type Func1 

type Func1[A, R any] func(A) R

Func1 is a function of one argument to one result

func Compose 

func Compose[A1, R1, R2 any](f1 Func1[A1, R1], f2 Func1[R1, R2]) Func1[A1, R2]

Compose allows you to chain methods making the order of application slightly cleaner. The idea is that instead of doing f2(f1(arg)) you can do Compose(f1, f2)(arg). This is similar to the . operator in Haskell, for example.

func (Func1[A, R]) Partial 

func (f Func1[A, R]) Partial(v A) FixedFunction[R]

Partial allows you to partially apply the function, returning a new function with one less argument than the function previously took. The return function will always receive the fixed value as it's return

type Func2 

type Func2[A1, A2, R any] func(A1, A2) R

Func2 is a function of two arguments to one result

func (Func2[A1, A2, R]) Partial 

func (f Func2[A1, A2, R]) Partial(v A1) Func1[A2, R]

Partial allows you to partially apply the function, returning a new function with one less argument than the function previously took. The return function will always receive the fixed value as it's return. For example, imagine you have: ```func add(left, right int) int { return left + right }``` You can partially apply it: ```add42 := Func2(add).Partial(42)``` and then use it as a unary function: ```add42(5) // => 47```

type Func3 

type Func3[A1, A2, A3, R any] func(A1, A2, A3) R

Func3 is a function of three arguments to one result

func (Func3[A1, A2, A3, R]) Partial 

func (f Func3[A1, A2, A3, R]) Partial(v A1) Func2[A2, A3, R]

Partial allows you to partially apply the function, returning a new function with one less argument than the function previously took. The return function will always receive the fixed value as it's return

type FuncN 

type FuncN[A, R any] func(...A) R

FuncN is a function of a variable number of arguments to one result

func (FuncN[A, R]) Partial 

func (f FuncN[A, R]) Partial(v A) FuncN[A, R]

Partial allows you to partially apply the function, returning a new function with one less argument than the function previously took. The return function will always receive the fixed value as it's return

type Iterable 

type Iterable[T any] interface {
	// Iter returns an Iterator for the type of the collection
	Iter() Iterator[T]
}

Iterable represents an object that can create an iterator

type Iterator 

type Iterator[T any] interface {
	// Each will call the given procedure once for every element in the collection,
	// giving the element as an argument to the procedure.
	Each(Proc1[T])
}

Iterator represents an object that has the capacity to visit each elements. THis interface does not guarantee an ordered visit - only that each element will be visited once.

type Keys 

type Keys[K comparable, V any] map[K]V

Keys allow you to wrap a map and use the keys in the map as an Iterator or Seq.

func (Keys[K, V]) Adder 

func (s Keys[K, V]) Adder(fixed V) Adder[K]

Adder takes a fixed value and returns an implementation of Adder that will add new keys to the underlying map with the same fixed value.

func (Keys[K, V]) Each 

func (s Keys[K, V]) Each(f Proc1[K])

Each will visit each key in the underlying map and yield the key to the procedure. The order of iteration is not defined.

func (Keys[K, V]) Iter 

func (s Keys[K, V]) Iter() Iterator[K]

Iter implements the Iterable interface

func (Keys[K, V]) Seq 

func (s Keys[K, V]) Seq() Seq[K]

Seq returns a lazy sequence over the keys in the underlying map

type Predicate 

type Predicate[A any] Func1[A, bool]

Predicate is a function that takes one argument and returns true or false

func (Predicate[A]) And 

func (p Predicate[A]) And(p2 Predicate[A]) Predicate[A]

And will return a new Predicate that is only true if both given Predicates return true for the argument given

func (Predicate[A]) Not 

func (p Predicate[A]) Not() Predicate[A]

Not returns a new Predicate that gives the inverse response for the given argument that the original predicate would have given.

func (Predicate[A]) Or 

func (p Predicate[A]) Or(p2 Predicate[A]) Predicate[A]

Or will return a new Predicate that is only true if at least one of the given Predicates return true for the argument given

func (Predicate[A]) Xor 

func (p Predicate[A]) Xor(p2 Predicate[A]) Predicate[A]

Xor will return a new Predicate that is only true if exactly one of the given Predicates return true for the argument given

type Predicate2 

type Predicate2[A1, A2 any] Func2[A1, A2, bool]

Predicate2 is a function that takes two arguments and returns true or false

func (Predicate2[A1, A2]) And 

func (p Predicate2[A1, A2]) And(p2 Predicate2[A1, A2]) Predicate2[A1, A2]

And will return a new Predicate that is only true if both given Predicates return true for the arguments given

func (Predicate2[A1, A2]) Not 

func (p Predicate2[A1, A2]) Not() Predicate2[A1, A2]

Not returns a new Predicate that gives the inverse response for the given arguments that the original predicate would have given.

func (Predicate2[A1, A2]) Or 

func (p Predicate2[A1, A2]) Or(p2 Predicate2[A1, A2]) Predicate2[A1, A2]

Or will return a new Predicate that is only true if at least one of the given Predicates return true for the arguments given

func (Predicate2[A1, A2]) Xor 

func (p Predicate2[A1, A2]) Xor(p2 Predicate2[A1, A2]) Predicate2[A1, A2]

Xor will return a new Predicate that is only true if exactly one of the given Predicates return true for the arguments given

type Predicate3 

type Predicate3[A1, A2, A3 any] Func3[A1, A2, A3, bool]

Predicate3 is a function that takes three arguments and returns true or false

type Proc1 

type Proc1[A any] func(A)

Proc1 is a procedure that takes one argument and doesn't return any result

type Proc2 

type Proc2[A1, A2 any] func(A1, A2)

Proc2 is a procedure that takes two arguments and doesn't return any result

type Proc3 

type Proc3[A1, A2, A3 any] func(A1, A2, A3)

Proc3 is a procedure that takes three arguments and doesn't return any result

type Seq 

type Seq[T any] interface {
	Iterator[T]
	BasicSeq[T]

	// Into will evaluate the full sequence and add it into the given adder
	Into(Adder[T])
	// IntoSlice will evaluate the full sequence and generate a slice of the result
	IntoSlice() []T
	// Filter will take the given predicate and return a new lazy sequence that
	// only yields values for which the predicate returns true.
	Filter(Predicate[T]) Seq[T]
}

Seq represents a lazy sequence that can also do some basic filtering and generating operations

func FullSeqFrom 

func FullSeqFrom[T any](s BasicSeq[T]) Seq[T]

FullSeqFrom takes a BasicSeq and returns a full Seq implementation using only the methods defined in BasicSeq

func LazyMap 

func LazyMap[T, U any](values BasicSeq[T], f Func1[T, U]) Seq[U]

LazyMap returns a new sequence that will yield values transformed by the function given

func ToSeq 

func ToSeq[T any](i Iterator[T]) Seq[T]

ToSeq will create a sequence from any iterator. This method uses goroutines and channels to turn the iteration into a sequence, and is thus not extremely efficient.

type Seqable 

type Seqable[T any] interface {
	// Seq returns a sequence for this type
	Seq() Seq[T]
}

Seqable represents a type that can be lazily iterated over by generating a Seq from it

type Set 

type Set[T comparable] interface {
	Iterable[T]
	Iterator[T]

	// Add will add the given element to the set. If the element already is in the set,
	// this method doesn't do anything.
	Add(T)
	// AddAll adds all the given arguments to the set, using the same logic as Add
	AddAll(...T)
	// Intersection returns a new Set that represents the intersection between this
	// set and the argument
	Intersection(Set[T]) Set[T]
	// Union returns a new Set that represents the union of this set and the argument
	Union(Set[T]) Set[T]
	// Difference returns a new Set containing only the elements from the receiver that
	// are not in the argument set
	Difference(Set[T]) Set[T]
	// SubSetOf returns true if the receiver Set is a sub set of the argument set
	SubSetOf(Set[T]) bool
	// Equal returns true if the receiver contains the same elements as the argument set
	Equal(Set[T]) bool
	// Contains returns true if the given argument is in the set
	Contains(T) bool
	// Size returns the number of elements in the set
	Size() int
	// Empty returns true if this is the empty set
	Empty() bool
	// ToSlice will return a slice with each element, in an undefined order
	ToSlice() []T
}

Set represents an unordered collection of objects. Sets can be compared for equality, and the elements manipulated in the expected ways

func NewSet 

func NewSet[T comparable]() Set[T]

NewSet creates a new empty set

func SetFrom 

func SetFrom[T comparable](values ...T) Set[T]

SetFrom will create a set containing the given values

type Slice 

type Slice[T any] []T

Slice wraps a slice so that you can iterate or sequence over it

func (Slice[T]) Each 

func (s Slice[T]) Each(f Proc1[T])

Each implements the Iterator interface for Slice

func (Slice[T]) Iter 

func (s Slice[T]) Iter() Iterator[T]

Iter implements the Iterable interface for a Slice

func (Slice[T]) Seq 

func (s Slice[T]) Seq() Seq[T]

Seq implements the Seqable interface for Slice

type Values 

type Values[K comparable, V any] map[K]V

Values allow you to wrap a map and iterate or sequence over the values in it

func (Values[K, V]) Each 

func (s Values[K, V]) Each(f Proc1[V])

Each will visit each value in the map and yield it to the given function If the map contains the same value more than once, the function will receive it once for every time it is available in the map

func (Values[K, V]) Iter 

func (s Values[K, V]) Iter() Iterator[V]

Iter implements the Iterable interface

func (Values[K, V]) Seq 

func (s Values[K, V]) Seq() Seq[V]

Seq returns a lazy sequence over the values in the underlying map

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.