collections

package
v1.35.0 Latest Latest
Warning

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

Go to latest
Published: Mar 22, 2026 License: MIT Imports: 6 Imported by: 3

Documentation

Overview

Collections provide interfaces of standardization for operations related to data structures. Standardizations defined within the collections package include:

Interfaces:

  • Collection: An interface for linear data structures.
  • Mapping: An interface for key-value pairs.
  • View: Interface for read-only data access.
  • Sized: Interface defining a data structure with a size.
  • Wrapper: Interface defining a data strucuture that can be converted and extracted from another.

Implementations:

Each of the implementations contain a concurrent-safe variant.

Collections also defines a few function iterators:

  • Enumerate: A python-like enumeration over a View.
  • In: A function to determine if a given element is contained within a View.
  • Reverse: Iterate over a View in reverse order.
  • Chain: Chain together a variadic View list.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Enumerate

func Enumerate[Type any](items View[Type]) func(func(gopolutils.Size, Type) bool)

Implementation of a python-like enumeration function iterator. Returns an enumerated function iterator.

func In added in v0.0.6

func In[Type comparable](items View[Type], item Type) bool

Determine if a given item is within a given slice of items. Returns true if the given item is present within the given slice of items.

func Reverse added in v1.17.0

func Reverse[Type any](items View[Type]) func(func(gopolutils.Size, Type) bool)

Implementation of a reverse function iterator. Returns a function iterator of a reversed view.

func Sum added in v1.34.0

func Sum[Type gopolutils.Number](values ...Type) Type

Sum given variadic gopolutils.Number values. Returns a gopolutils.Number of the sum of the given values.

Types

type Array

type Array[Type any] struct {
	// contains filtered or unexported fields
}

Implementation of a classical dynamic array.

func NewArray

func NewArray[Type any]() *Array[Type]

Construct a new array. Returns a pointer to a new empty array.

func (*Array[Type]) Append

func (array *Array[Type]) Append(item Type)

Append an item to the array.

func (Array[Type]) At

func (array Array[Type]) At(index gopolutils.Size) (*Type, *gopolutils.Exception)

Access the data stored in the array at a given index. Returns a pointer to the data in the collection at the given index. If the array is empty, a gopolutils.ValueError is returned with a nil data pointer. If the given index is greater than the size of the array, an gopolutils.OutOfRangeError is returned with a nil data pointer.

func (Array[Type]) Collect added in v1.0.0

func (array Array[Type]) Collect() []Type

Collect the data stored in the array as a slice. Returns a view into the data stored in the array.

func (*Array[Type]) Extend

func (array *Array[Type]) Extend(items View[Type])

Append multiple items to the array.

func (Array[_]) IsEmpty

func (array Array[_]) IsEmpty() bool

Determine if the array is empty. Returns true if the length of the data and the size of the array are equal to 0.

func (Array[Type]) Items

func (array Array[Type]) Items() *[]Type

Access the underlying data of the array. Returns a mutable pointer to the data stored in the array.

func (*Array[Type]) Remove

func (array *Array[Type]) Remove(index gopolutils.Size) *gopolutils.Exception

Remove the data stored in the array at a given index. If the array is empty, an gopolutils.ValueError is returned. If the given index is greater than the size of the array, an gopolutils.OutOfRangeError is returned. If an gopolutils.OutOfRangeError is returned, the array is not modified.

func (Array[_]) Size

func (array Array[_]) Size() gopolutils.Size

Access the size of the array. Returns the size of the array as an unsigned 64-bit integer.

func (*Array[Type]) Update added in v1.3.0

func (array *Array[Type]) Update(index gopolutils.Size, value Type) *gopolutils.Exception

Update a value within the collection. If the collection is empty, a gopolutils.ValueError is returned. If the given index is greater than the collection size, an gopolutils.OutOfRangeError is returned. If an gopolutils.OutOfRangeError is returned, the collection is not modified.

type Collection

type Collection[Type any] interface {
	// Append an item to the collection.
	Append(item Type)
	// Append multiple items to the collection.
	Extend(items View[Type])
	// Access an item within the collection at a given index.
	// Returns a pointer to the data in the collection at the given index.
	// If the collection is empty, a [gopolutils.ValueError] is returned with a nil data pointer.
	// If the given index is greater than the size of the collection, an [gopolutils.OutOfRangeError] is returned with a nil data pointer.
	At(index gopolutils.Size) (*Type, *gopolutils.Exception)
	// Update a value within the collection.
	// If the collection is empty, an [gopolutils.OutOfRangeError] is returned.
	// If the given index is greater than the collection size, an [gopolutils.OutOfRangeError] is returned.
	// If an [gopolutils.OutOfRangeError] is returned, the collection is not modified.
	Update(index gopolutils.Size, value Type) *gopolutils.Exception
	// Remove the data in the collection at a given index.
	// If the collection is empty, a [gopolutils.ValueError] is returned.
	// If the given index is greater than the size of the collection, an [gopolutils.OutOfRangeError] is returned.
	// If an [gopolutils.OutOfRangeError] is returned, the collection is not modified.
	Remove(index gopolutils.Size) *gopolutils.Exception
	// Access a pointer to a slice of the data within the collection.
	// This method is called when the data stored in the collection is determined to be internally mutable, or a mutable pointer is needed to access the data.
	// Returns a mutable pointer to the underlying data within the collection.
	Items() *[]Type
	View[Type]
}

Interface to standardize a linear data structure.

func Chain added in v1.17.0

func Chain[Type any](views ...View[Type]) Collection[Type]

Chain a variadic list of views together. Returns a new collection of the combination of each of the passed in views.

type Iterator added in v1.30.0

type Iterator[Value any] struct {
	// contains filtered or unexported fields
}

Standardization of the iterator pattern.

func From added in v1.30.0

func From[Value any](source View[Value]) *Iterator[Value]

Construct a new iterator from a given View. Returns a new iterator from a given View.

func (*Iterator[Value]) Collect added in v1.30.0

func (iterator *Iterator[Value]) Collect() []Value

Collect the iterator into a slice. Returns a slice of the values of the iterator.

func (*Iterator[Value]) Filter added in v1.30.0

func (iterator *Iterator[Value]) Filter(predicate func(Value) bool) *Iterator[Value]

Filter an interator based on a given predicate. Returns a new iterator with each of the values of the iterator filtered by the given predicate.

func (*Iterator[Value]) ForEach added in v1.30.0

func (iterator *Iterator[Value]) ForEach(callback func(Value))

Call a given callback on each of the values of the iterator.

func (*Iterator[_]) IsEmpty added in v1.30.0

func (iterator *Iterator[_]) IsEmpty() bool

Determine if the iterator is empty. Returns true if the size of the iterator is zero, else false.

func (*Iterator[Value]) Map added in v1.30.0

func (iterator *Iterator[Value]) Map(callback func(Value) Value) *Iterator[Value]

Map a given callback to each item in an iterator. Returns a new iterator with each of the items in the iterator transformed mapped to the callback.

func (*Iterator[View]) Size added in v1.30.0

func (iterator *Iterator[View]) Size() gopolutils.Size

Obtain the size of the iterator. Returns the size of the iterator.

type Map

type Map[Key comparable, Value any] struct {
	// contains filtered or unexported fields
}

A collection of key-value pairs.

func NewMap

func NewMap[Key comparable, Value any]() *Map[Key, Value]

Consruct a new map. Returns a pointer to a new empty map.

func (Map[Key, Value]) At

func (mapping Map[Key, Value]) At(key Key) (*Value, *gopolutils.Exception)

Access an element at a given key within the map. Returns a pointer to the data stored at the given key. If the map is empty, a gopolutils.ValueError is returned with a nil data pointer. If the key is not in the map, a gopolutils.KeyError is returned with a nil data pointer.

func (Map[Key, Value]) Collect added in v1.9.0

func (mapping Map[Key, Value]) Collect() []Pair[Key, Value]

Collect a map into a view. Returns a slice containing each of the key-value pairs within the map.

func (Map[Key, _]) HasKey

func (mapping Map[Key, _]) HasKey(key Key) bool

Determine if a given key is stored in the map. Returns true if the key is stored in the map.

func (*Map[Key, Value]) Insert

func (mapping *Map[Key, Value]) Insert(key Key, value Value) *gopolutils.Exception

Insert a key-value pair into the map. If the key is already in the map, instead of just quietly not inserting into the map, a gopolutils.KeyEror is retruned. If a gopolutils.KeyError is returned, the mapping is not modified.

func (Map[_, _]) IsEmpty added in v0.0.9

func (mapping Map[_, _]) IsEmpty() bool

Determine if the map is empty. Returns true if the length of the underlying data and the size of the map is equal to 0.

func (Map[Key, _]) Keys

func (mapping Map[Key, _]) Keys() []Key

Access a slice of unique keys within the map. Returns a slice of unique keys within the map.

func (*Map[Key, _]) Remove

func (mapping *Map[Key, _]) Remove(key Key) *gopolutils.Exception

Remove an item stored at a given key within the map. If the map is empty, a gopolutils.ValueError is returned. If the given key is not stored in the map, a gopolutils.KeyError is returned. If a gopolutils.ValueError or a gopolutils.KeyError is returned, the mapping is not modified.

func (Map[_, _]) Size

func (mapping Map[_, _]) Size() gopolutils.Size

Acces the size of the map. Returns the size of the map as an unsigned 64-bit integer.

func (Map[Key, Value]) Update added in v1.2.0

func (mapping Map[Key, Value]) Update(key Key, value Value) *gopolutils.Exception

Update a value within the mapping. If the map is empty, a gopolutils.ValueError is returned with a nil data pointer. If the key does not exist in the mapping, a gopolutils.KeyError is returned. If a gopolutils.ValueError or a gopolutils.KeyError is returned, the mapping is not modified.

func (Map[_, Value]) Values

func (mapping Map[_, Value]) Values() []Value

Access a slice of unique values within the map. Returns a slice of unique values within the map.

type Mapping

type Mapping[Key, Value any] interface {
	// Insert a key-value pair into the mapping.
	// If the key is already in the mapping, instead of just quietly not inserting into the mapping, a [gopolutils.KeyError] is returned.
	// If a [gopolutils.KeyError] is returned, the mapping is not modified.
	Insert(key Key, value Value) *gopolutils.Exception
	// Access an element at a given key within the mapping.
	// Returns a pointer to the data stored at the given key.
	// If the mapping is empty, a [gopolutils.ValueError] is returned with a nil data pointer.
	// If the key is not in the mapping, a [gopolutils.KeyError] is returned with a nil data pointer.
	At(key Key) (*Value, *gopolutils.Exception)
	// Update a value within the mapping.
	// If the mapping is empty, a [gopolutils.ValueError] is returned with a nil data pointer.
	// If the key does not exist in the mapping, a [gopolutils.KeyError] is returned.
	// If a [gopolutils.ValueError] or a [gopolutils.KeyError] is returned, the mapping is not modified.
	Update(key Key, value Value) *gopolutils.Exception
	// Access a slice of unique keys within the mapping.
	// Returns a slice of unique keys within the mapping.
	Keys() []Key
	// Access a slice of unique values within the mapping.
	// Returns a slice of unique values within the mapping.
	Values() []Value
	// Remove an item stored at a given key within the mapping.
	// If the map is empty, a [gopolutils.ValueError] is returned.
	// If the given key is not stored in the map, a [gopolutils.KeyError] is returned.
	// If a [gopolutils.ValueError] or a [gopolutils.KeyError] is returned, the mapping is not modified.
	Remove(key Key) *gopolutils.Exception
	// Determine if a given key is located within the mapping.
	// Returns true if the given key is found.
	HasKey(key Key) bool
	View[Pair[Key, Value]]
}

Interface to standardize a key-value pair mapping.

type Pair added in v0.0.8

type Pair[First any, Second any] struct {
	// contains filtered or unexported fields
}

Representation of a pair — or de facto tuple — structure.

func NewPair added in v0.0.8

func NewPair[First any, Second any](first First, second Second) *Pair[First, Second]

Construct a new pair given two arguments of each respective type variables. This constructor resturns a pointer to a newly constructed pair.

func (Pair[First, _]) First added in v0.0.8

func (pair Pair[First, _]) First() *First

Return a pointer to the first property of the pair.

func (*Pair[First, Second]) Flip added in v1.14.0

func (pair *Pair[First, Second]) Flip() *Pair[Second, First]

Flip the values of a pair. Returns a new pair where the first value of the original pair is second and the second value of the original pair is first.

func (Pair[First, Second]) Items added in v1.8.0

func (pair Pair[First, Second]) Items() (*First, *Second)

Get a tuple of each of the properties in the pair. Returns a pointer to each of the properties in the pair.

func (Pair[_, Second]) Second added in v0.0.8

func (pair Pair[_, Second]) Second() *Second

Return a pointer to the second property of the pair.

func (*Pair[First, Second]) Set added in v1.32.0

func (pair *Pair[First, Second]) Set(first First, second Second)

Set each of the properties of the pair.

func (*Pair[First, _]) SetFirst added in v1.32.0

func (pair *Pair[First, _]) SetFirst(first First)

Set the first property of the pair.

func (*Pair[_, Second]) SetSecond added in v1.32.0

func (pair *Pair[_, Second]) SetSecond(second Second)

Set the second property of the pair.

func (*Pair[First, Second]) Swap added in v0.0.8

func (pair *Pair[First, Second]) Swap(operand *Pair[First, Second])

Swap two pairs with the same types. Both the original pair and the operand passed into the function will be modified.

type Queue

type Queue[Type any] struct {
	// contains filtered or unexported fields
}

Implementation of a queue data structure.

func NewQueue

func NewQueue[Type any]() *Queue[Type]

Construct a new queue. Returns a pointer to a new queue.

func (*Queue[Type]) Append

func (queue *Queue[Type]) Append(item Type)

Append an item to the queue.

func (Queue[Type]) At

func (queue Queue[Type]) At(index gopolutils.Size) (*Type, *gopolutils.Exception)

Access the data stored in the queue at a given index. Returns a pointer to data stored in the queue at the given index. If the queue is empty, a gopolutils.ValueError is returned with a nil data pointer. If the index is greater than the size of the queue, an gopolutils.OutOfRangeError is returned with a nil data pointer.

func (Queue[Type]) Collect added in v1.0.0

func (queue Queue[Type]) Collect() []Type

Collect the data stored in the queue as a slice. Returns a view into the data stored in the queue.

func (*Queue[Type]) Dequeue

func (queue *Queue[Type]) Dequeue() (*Type, *gopolutils.Exception)

Dequeue the first item in the queue.

This is the implementation of a "Fist In First Out" data structure. Returns a pointer to the first item in the queue. Like the name suggests, when an item is dequeued, the item is removed from the queue. If the queue is evaluated to be empty, a gopolutils.ValueError is returned with a nil data pointer. If a gopolutils.ValueError is returned, the queue is not modified.

func (*Queue[Type]) Extend

func (queue *Queue[Type]) Extend(items View[Type])

Append multiple items to the queue.

func (Queue[_]) IsEmpty

func (queue Queue[_]) IsEmpty() bool

Determine if the queue is empty. Returns true if the length of the underlying data and the size of the queue is equal to 0.

func (Queue[Type]) Items

func (queue Queue[Type]) Items() *[]Type

Get a pointer to the slice of the queue. Returns a mutable pointer to the underlying data within the queue.

func (*Queue[Type]) Peek

func (queue *Queue[Type]) Peek() (*Type, *gopolutils.Exception)

Access the first element in the queue. Returns a pointer to the first item in the queue. If the queue is evaluated to be empty, a gopolutils.ValueError is returned with a nil data pointer.

func (*Queue[_]) Remove

func (queue *Queue[_]) Remove(index gopolutils.Size) *gopolutils.Exception

Remove the data stored in the queue at a given index. If the queue is empty, a gopolutils.ValueError is returned. If the given index is greater than the size of the queue, an gopolutils.OutOfRangeError is returned. If a gopolutils.ValueError or an gopolutils.OutOfRangeError is returned, the queue is not modified.

func (Queue[_]) Size

func (queue Queue[_]) Size() gopolutils.Size

Access the size of the queue. Returns the size of the queue as an unsigned 64-bit integer.

func (*Queue[Type]) Update added in v1.3.0

func (queue *Queue[Type]) Update(index gopolutils.Size, value Type) *gopolutils.Exception

Update a value within the queue. If the queue is empty, a gopolutils.ValueError is returned. If the given index is greater than the queue size, an gopolutils.OutOfRangeError is returned. If a gopolutils.ValueError or an gopolutils.OutOfRangeError is returned, the queue is not modified.

type Set

type Set[Type comparable] struct {
	// contains filtered or unexported fields
}

Implementation of a set.

func NewSet

func NewSet[Type comparable]() *Set[Type]

Construct a new set. Returns a pointer to a new empty set.

func (*Set[Type]) Append

func (set *Set[Type]) Append(item Type)

Append an item to the set. If the set can not insert the item, this is a critical error that should not happen in most cicumstances, so — as a precaution — an error is printed to standard error and the programme exists.

func (Set[Type]) At added in v1.0.0

func (set Set[Type]) At(index gopolutils.Size) (*Type, *gopolutils.Exception)

This method is not yet implemented. Access the data stored at a given index within the set. If the set is empty, a gopolutils.ValueError is returned. If the index is greater than the size of the set, an gopolutils.OutOfRangeError is returned with a nil data pointer.

func (Set[Type]) Collect added in v1.0.0

func (set Set[Type]) Collect() []Type

Access a slice of the data within the set. Returns a view of the data within the set.

func (Set[Type]) Contains

func (set Set[Type]) Contains(item Type) bool

Determine if the given item is contained within the set. Returns true if the item is found within the set.

func (Set[Type]) Difference

func (set Set[Type]) Difference(other Set[Type]) *Set[Type]

Determine the difference between set and a given set operand. Returns a pointer to a new set that contains all the unique items that were contained within operand but not the original set.

func (*Set[Type]) Discard

func (set *Set[Type]) Discard(item Type)

Remove an item within the set without an exception. If the set is evaluated to be empty, the method will return without modifying the set. If the item is not in the set, the method will return without modifying the set.

func (*Set[Type]) Extend

func (set *Set[Type]) Extend(items View[Type])

Append multiple items to the set. If the set can not insert the item, this is a critical error that should not happen in most cicumstances, so — as a precaution — an error is printed to standard error and the programme exists.

func (*Set[Type]) From added in v1.21.0

func (set *Set[Type]) From(collection Collection[Type])

Convert a collection into a set.

func (Set[Type]) Intersection

func (set Set[Type]) Intersection(other Set[Type]) *Set[Type]

Determine the intersection between the set and a given set operand. Returns a pointer to a new set that contains all the unique items that were contained within both the original set and the operand.

func (Set[Type]) Into added in v1.21.0

func (set Set[Type]) Into() Collection[Type]

Transfer the data within the set to a linear array. Returns a collection containing all the elements within the set.

func (Set[_]) IsEmpty added in v0.0.9

func (set Set[_]) IsEmpty() bool

Determine if the set is empty. Returns true if the length of the underlying data stored in the set and the size of the set is equal to 0.

func (Set[Type]) Items

func (set Set[Type]) Items() *[]Type

Access the underlying data of the set. Returns a mutable pointer to a map representing the underlying data of the set.

func (*Set[Type]) Remove

func (set *Set[Type]) Remove(index gopolutils.Size) *gopolutils.Exception

Remove an item in the set at a given index. If the set is evaluated to be empty, a gopolutils.ValueError is returned. If the given index is greater than the size of the set, an gopolutils.OutOfRangeError is returned. If no item can be found at the given index, an gopolutils.IndexError is returned. if a gopolutils.ValueError or an gopolutils.OutOfRangeError is returned, the set will not be modified.

func (Set[_]) Size

func (set Set[_]) Size() gopolutils.Size

Access the size of the set. Returns the size of the set as an unsigned 64-bit integer.

func (Set[Type]) String added in v1.34.0

func (set Set[Type]) String() string

Render a string representation of the set. Returns a string representation of the set.

func (*Set[Type]) Update added in v1.3.0

func (set *Set[Type]) Update(index gopolutils.Size, value Type) *gopolutils.Exception

Update a value within the set. This method is not yet implemented. If the given index is greater than the set size, an gopolutils.OutOfRangeError is returned. If the set is empty, an gopolutils.OutOfRangeError is returned. If an gopolutils.OutOfRangeError is returned, the set is not modified.

type Sized added in v0.0.9

type Sized interface {
	// Retrieve the size of the structure.
	// Returns the size of the structure as an unsigned 64-bit integer.
	Size() gopolutils.Size
	// Determine if the structure is empty.
	// Returns true if the length of the underlying data stored in the structure and the size of the structure is equal to 0.
	IsEmpty() bool
}

Interface to define a sized structure.

type Stack

type Stack[Type any] struct {
	// contains filtered or unexported fields
}

Implementation of a stack.

func NewStack

func NewStack[Type any]() *Stack[Type]

Construct a new stack. Returns a pointer to a new stack.

func (*Stack[Type]) Append

func (stack *Stack[Type]) Append(item Type)

Append an item to the stack.

func (Stack[Type]) At

func (stack Stack[Type]) At(index gopolutils.Size) (*Type, *gopolutils.Exception)

Access the data stored on the stack at a given index. Returns a pointer to the data stored on the stack at the given index. If the stack is evaluated to be empty, a gopolutils.ValueError is returned with a nil data pointer. If the index is greater than the size of the stack, an gopolutils.OutOfRangeError is returned with a nil data pointer.

func (Stack[Type]) Collect added in v1.0.0

func (stack Stack[Type]) Collect() []Type

Collect the data stored in the stack as a slice. Returns a view into the data stored in the stack.

func (*Stack[Type]) Extend

func (stack *Stack[Type]) Extend(items View[Type])

Append multiple items to the stack.

func (Stack[_]) IsEmpty

func (stack Stack[_]) IsEmpty() bool

Determine if the stack is empty. Returns true if the length of the underlying data and the size of the stack is equal to 0.

func (Stack[Type]) Items

func (stack Stack[Type]) Items() *[]Type

Get a pointer to a slice of the data within stack. Returns a mutable pointer to the underlying data within the stack.

func (*Stack[Type]) Peek

func (stack *Stack[Type]) Peek() (*Type, *gopolutils.Exception)

Peek at the last appended item from the stack.

This is the implementation of a "First In Last Out" data structure. Unlike pop, this method accesses the data on the stack without modifying the stack itself. Returns a pointer to the last item in the stack. If the stack is evaluated to be empty, a gopolutils.ValueError is returned with a nil data pointer.

func (*Stack[Type]) Pop

func (stack *Stack[Type]) Pop() (*Type, *gopolutils.Exception)

Pop the last appended item from the stack.

This is the implementation of a "First In Last Out" data structure. As the name suggests, when the last item is popped off the stack, it is also removed from the stack. Returns a pointer to the last item in the stack. If the stack is evaluated to be empty, a gopolutils.ValueError is returned with a nil data pointer. If a gopolutils.ValueError is returned, the stack is not modified.

func (*Stack[_]) Remove

func (stack *Stack[_]) Remove(index gopolutils.Size) *gopolutils.Exception

Remove the data stored on the stack at a given index. If the stack is empty, a gopolutils.ValuError is returned. If the given index is greater than the size of the stack, an gopolutils.OutOfRangeError is returned. If a gopolutils.ValueError or an gopolutils.OutOfRangeError is returned, the stack is not modified.

func (Stack[_]) Size

func (stack Stack[_]) Size() gopolutils.Size

Access the size of the stack. Returns the size of the stack as an unsigned 64-bit integer.

func (*Stack[Type]) Update added in v1.3.0

func (stack *Stack[Type]) Update(index gopolutils.Size, value Type) *gopolutils.Exception

Update a value within the stack. If the stack is empty, a gopolutils.ValueError is returned. If the given index is greater than the stack size, an gopolutils.OutOfRangeError is returned. If a gopolutils.ValueError or an gopolutils.OutOfRangeError is returned, the stack is not modified.

type View added in v1.0.0

type View[Type any] interface {
	// Collect the structure into a view.
	// Returns a slice of the type of the structure.
	Collect() []Type
	Sized
}

Interface to define a read only sized view into a structure.

type Wrapper added in v1.21.0

type Wrapper[Type any] interface {
	// Convert a wrapper into a collection.
	// Returns a collection data type contatining all the elements from the wrapped collection.
	Into() Collection[Type]
	// Convert a collection into a wrapper.
	From(collection View[Type])
	View[Type]
}

Implementation of a wrapper around a collection.

Directories

Path Synopsis
Safe provides interfaces of standardization for operations related to concurrent safe data structures.
Safe provides interfaces of standardization for operations related to concurrent safe data structures.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL