gollections

A collection of collections!

Table of Contents

• Overview
  • Usage
  • Go Type Interop
• Packages
  • pkg/collection
  • pkg/dict
  • pkg/dll
  • pkg/hashmap
  • pkg/iterator
  • pkg/list
  • pkg/queue
  • pkg/slice
  • pkg/sll
  • pkg/stack

Overview

gollections is a collection of generic data structures, written with Go 1.18. The purpose of this package is to provide a flexible system of generic collections and lazily- executed iterators for use in a variety of applications

Usage

Each of the collections resides in its own module, located under the pkg/ directory. Currently, only the following concrete data structures are implemented:

• pkg/dll: Doubly-linked list
• pkg/hashmap: A basic hash map
• pkg/slice: Go slice wrapper
• pkg/sll: Singly-linked list

The remaining packages in this repository provide interfaces dedicated to more specific data structures (e.g. pkg/stack, pkg/queue, etc.), and iterators (see pkg/iterator)

Go Type Interop

Go slices are used as the underlying type for the pkg/slice collection, and can be coerced as follows:

package main

import "github.com/bdreece/gollections/pkg/slice"

func main() {
    s := slice.Marshal([]int{1, 2, 3})

    /*
        s.Get(2)
        v := s.First()
        ...
    */

}

Packages

Collection

The pkg/collection module provides the base interface for all collection interfaces in this repository.

A collection.Collection[TItem] provides the following methods:

• Concat(iterator.IntoIterator[TItem]) Collection[TItem]
• Collect(iterator.Iterator[TItem]) Collection[TItem]
• Append(TItem) Collection[TItem]
• Count() int

The collection.Collection[TItem] interface also implements the iterator.IntoIterator[TItem] interface.

Dictionary

The pkg/dict module provides the dict.Dict[TKey, TValue] interface, which is a thin wrapper over the primitive Go map; as well as the dict.Pair[TKey, TValue] struct, which represents a key-value pair.

A dict.Dict[TKey, TValue] provides the following methods:

• Unmarshal() map[TKey]TValue
• Get(TKey) *TValue
• Set(TKey, TValue)
• Remove(TKey) *TValue

A dict.Dict[TKey, TValue] also implements the following interfaces:

• collection.Collection[dict.Pair[TKey, TValue]]
• iterator.IntoIterator[dict.Pair[TKey, TValue]]

Doubly-Linked List

The pkg/dll module provides the dll.DLL[TItem] interface, which is implemented as a doubly-linked list of nodes.

A dll.DLL[TItem] implements the following interfaces:

• stack.Stack[TItem]
• queue.Queue[TItem]
• collection.Collection[TItem]
• iterator.IntoIterator[TItem]

Hash Map

The pkg/hashmap module provides the hashmap.HashMap[TKey, TValue] interface, which is implemented as a hash map data structure.

A hashmap.HashMap[TKey, TValue] provides the following methods:

• Get(TKey) (*TValue, error)
• Set(TKey, TValue) error
• Remove(TKey) (*TValue, error)

A hashmap.HashMap[TKey, TValue] also implements the following interfaces:

• collection.Collection[dict.Pair[TKey, TValue]]
• iterator.IntoIterator[dict.Pair[TKey, TValue]]

Iterator

The pkg/iterator module provides iterator interfaces and related functions for lazily-iterating over collections.

The following functions can be used to operate over an iterator.Iterator[TItem]:

• Chain[TItem](iterator.Iterator[TItem], iterator.Iterator[TItem]) iterator.Iterator[TItem]
• Empty[TItem]() iterator.Iterator[TItem]
• Enumerate[TItem](iterator.Iterator[TItem], EnumerateFunc[TItem])
  • type EnumerateFunc[TItem] func(TItem, int)
• Filter[TItem](iterator.Iterator[TItem], FilterFunc[TItem])
  • type FilterFunc[TItem] func(TItem) bool
• Find[TItem](iterator.Iterator[TItem], FindFunc[TItem])
  • type FindFunc[TItem] func(TItem) bool
• FlatMap[TInput, TOutput](iterator.Iterator[TInput], FlatMapFunc[TInput, TOutput])
  • type FlatMapFunc[TInput, TOutput] func(TInput) iterator.IntoIterator[TOutput]
• ForEach[TItem](iterator.Iterator, ForEachFunc[TItem])
  • type ForEachFunc[TItem] func(TItem)
• Map[TInput, TOutput](iterator.Iterator[TInput], MapFunc[TInput, TOutput])
  • type MapFunc[TInput, TOutput] func(TInput) TOutput
• Reduce[TItem, TAggregate](iterator.Iterator[TItem], ReduceFunc[TItem, TAggregate], TAggregate)
  • type ReduceFunc[TItem, TAggregate] func(TAggregate, TItem) TAggregate
• Take[TItem](iterator.Iterator[TItem], int) iterator.Iterator[TItem]

The pkg/iterator module also provides the iterator.IntoIterator[TItem] interface, which provides the following method:

• Iter[TItem]() iterator.Iterator[TItem]

List

The pkg/list module provides the list.List[TItem] interface, which represents a basic enumerable list.

A list.List[TItem] implements the following interfaces:

• slice.Slice[TItem]
• collection.Collection[TItem]
• iterator.IntoIterator[TItem]

Queue

The pkg/queue module provides the queue.Queue[TItem] interface, which represents a FIFO buffer.

A queue.Queue[TItem] provides the following methods:

• Enqueue(TItem)
• Dequeue() *TItem

A queue.Queue[TItem] also implements the following interfaces:

• collection.Collection[TItem]
• iterator.IntoIterator[TItem]

Slice

The pkg/slice module provides the slice.Slice[TItem] interface, which is implemented as a thin wrapper around the primitive Go slice.

A slice.Slice[TItem] provides the following methods:

• Unmarshal() []TItem
• First() *TItem
• Last() *TItem
• Add(TItem)
• Get(int) (*TItem, error)
• Set(int, TItem) error
• Insert(int, TItem) error
• Remove(int) (*TItem, error)

A slice.Slice[TItem] also implements the following interfaces:

• collection.Collection[TItem]
• iterator.IntoIterator[TItem]

Singly-Linked List

The pkg/sll module provides the sll.SLL[TItem] interface, which is implemented as a singly-linked list of nodes.

A sll.SLL[TItem] implements the following interfaces:

• stack.Stack[TItem]
• queue.Queue[TItem]
• collection.Collection[TItem]
• iterator.IntoIterator[TItem]

Stack

The pkg/stack modules provides the stack.Stack[TItem] interface, which represents a FILO buffer

A stack.Stack[TItem] provides the following methods:

• Push(TItem)
• Pop() *TItem
• Peek() *TItem

A stack.Stack[TItem] also implements the following interfaces:

• collection.Collection[TItem]
• iterator.IntoIterator[TItem]