collections

package module
v1.10.1 Latest Latest
Warning

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

 Go to latest Published: Jan 17, 2023 License: MIT Imports: 8 Imported by: 4

README

Go Collection Framework

Overview

This project provides a Go based framework containing generic interfaces and collection types for common high-level collections. It is meant to augment or replace the use of the native Go array, slice and map types.

For more information on this project click on the following links:

Getting Started

To include the Go packages for this module use the following import statement:

import (
	col "github.com/craterdog/go-collection-framework"
)

Contributing

Project contributors are always welcome. Check out the contributing guidelines here.

Documentation

Overview

This collections package defines a set of simple, pragmatic interfaces for collections of sequential values. It also provides efficient and compact implementations of the following collection types based on those interfaces:

  • array (native Go array)
  • list (a sortable list)
  • set (an ordered set)
  • map (native Go map)
  • catalog (a sortable map)
  • stack (LIFO)
  • queue (a blocking FIFO)

Additional implementations of these collection types can be defined and used seemlessly since the interface definitions only depend on other interfaces and native types; and the type implementations only depend on interfaces, not on each other. For a full description of this package see the wiki documentation at the github repository maintaining this package: 

https://github.com/craterdog/go-collection-framework/wiki

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CompareValues 

func CompareValues(first Value, second Value) bool

This function determines whether or not the specified values are equal using their natural comparison criteria.

func FormatValue 

func FormatValue(value Value) string

This function returns a string containing the canonical format for the specified value.

func FormatValueWithIndentation 

func FormatValueWithIndentation(value Value, indentation int) string

This function returns a string containing the canonical format for the specified value indented the specified number of levels.

func RankValues 

func RankValues(first Value, second Value) int

This function ranks the specified values based on their natural ordering.

func ReverseArray 

func ReverseArray[V Value](array []V)

This function reverses the order of the values in the specified array.

func ShuffleArray 

func ShuffleArray[V Value](array []V)

This function randomly shuffles the values in the specified array.

func SortArray 

func SortArray[V Value](array []V, rank RankingFunction)

This function sorts the values in the specified array using the specified ranking function.

Types

type Array 

type Array[V Value] []V

This type defines the structure and methods associated with a native array of values. Each value is associated with an implicit positive integer index. The array uses ORDINAL based indexing rather than ZERO based indexing (see the description of what this means in the Sequential interface definition). This type is parameterized as follows:

  • V is any type of value.

func (Array[V]) AsArray 

func (v Array[V]) AsArray() []V

This method returns all the values in this array. The values retrieved are in the same order as they are in the array.

func (Array[V]) ContainsAll 

func (v Array[V]) ContainsAll(values Sequential[V]) bool

This method determines whether or not this array contains ALL of the specified values.

func (Array[V]) ContainsAny 

func (v Array[V]) ContainsAny(values Sequential[V]) bool

This method determines whether or not this array contains ANY of the specified values.

func (Array[V]) ContainsValue 

func (v Array[V]) ContainsValue(value V) bool

This method determines whether or not this array contains the specified value.

func (Array[V]) GetIndex 

func (v Array[V]) GetIndex(value V) int

This method returns the index of the FIRST occurrence of the specified value in this array, or zero if this array does not contain the value.

func (Array[V]) GetSize 

func (v Array[V]) GetSize() int

This method returns the number of values contained in this array.

func (Array[V]) GetValue 

func (v Array[V]) GetValue(index int) V

This method retrieves from this array the value that is associated with the specified index.

func (Array[V]) GetValues 

func (v Array[V]) GetValues(first int, last int) Sequential[V]

This method retrieves from this array all values from the first index through the last index (inclusive).

func (Array[V]) GoIndex 

func (v Array[V]) GoIndex(index int) int

This method normalizes an index to match the Go (zero based) indexing. The following transformation is performed: 

[-length..-1] and [1..length] => [0..length)

Notice that the specified index cannot be zero since zero is not an ORDINAL.

func (Array[V]) IsEmpty 

func (v Array[V]) IsEmpty() bool

This method determines whether or not this array is empty.

func (Array[V]) SetValue 

func (v Array[V]) SetValue(index int, value V)

This method sets the value in this array that is associated with the specified index to be the specified value.

func (Array[V]) SetValues 

func (v Array[V]) SetValues(index int, values Sequential[V])

This method sets the values in this array starting with the specified index to the specified values.

func (Array[V]) String 

func (v Array[V]) String() string

This method is used by Go to generate a string from an array.

type ArrayLike 

type ArrayLike[V Value] interface {
	Sequential[V]
	Indexed[V]
	Searchable[V]
	Updatable[V]
}

This interface consolidates all the interfaces supported by native array-like sequences.

type AssociationLike 

type AssociationLike[K Key, V Value] interface {
	Binding[K, V]
}

This interface defines the methods supported by all association-like types. An association binds a key with a value.

func Association 

func Association[K Key, V Value](key K, value V) AssociationLike[K, V]

This constructor creates a new association with the specified key and value.

type Associative 

type Associative[K Key, V Value] interface {
	AddAssociation(association Binding[K, V])
	AddAssociations(associations Sequential[Binding[K, V]])
	GetKeys() Sequential[K]
	GetValues(keys Sequential[K]) Sequential[V]
	GetValue(key K) V
	SetValue(key K, value V)
	RemoveValue(key K) V
	RemoveValues(keys Sequential[K]) Sequential[V]
	RemoveAll()
}

This interface defines the methods supported by all associative sequences whose values consist of key-value pair associations.

type Binding 

type Binding[K Key, V Value] interface {
	GetKey() K
	GetValue() V
	SetValue(value V)
}

This interface defines the methods supported by all binding associations. It binds a readonly key with a setable value.

type Canonical 

type Canonical interface {
	GetIndentation() int
	FormatValue(value Value)
	AppendString(s string)
	AppendNewline()
	GetResult() string
}

This interface defines the methods supported by all canonical agents that can format any value in a standard way.

type CatalogLike 

type CatalogLike[K Key, V Value] interface {
	Sequential[Binding[K, V]]
	Associative[K, V]
	Sortable[Binding[K, V]]
}

This interface consolidates all the interfaces supported by catalog-like sequences.

func Catalog 

func Catalog[K Key, V Value]() CatalogLike[K, V]

This constructor creates a new empty catalog.

func CatalogFromArray added in v1.8.0 

func CatalogFromArray[K Key, V Value](array []Binding[K, V]) CatalogLike[K, V]

This constructor creates a new catalog from the specified array of associations.

func CatalogFromSequence 

func CatalogFromSequence[K Key, V Value](sequence Sequential[Binding[K, V]]) CatalogLike[K, V]

This constructor creates a new catalog from the specified sequence of associations.

func Extract 

func Extract[K Key, V Value](catalog CatalogLike[K, V], keys Sequential[K]) CatalogLike[K, V]

This function returns a new catalog containing only the associations that are in the specified catalog that have the specified keys. The associations in the resulting catalog will be in the same order as the specified keys.

func Merge 

func Merge[K Key, V Value](first, second CatalogLike[K, V]) CatalogLike[K, V]

This function returns a new catalog containing all of the associations that are in the specified catalogs in the order that they appear in each catalog.

type CollatorLike 

type CollatorLike interface {
	Discerning
}

This interface defines the methods supported by all collator-like types.

func Collator 

func Collator() CollatorLike

This constructor creates a new instance of a collator that can be used to compare or rank any two values.

type ComparisonFunction 

type ComparisonFunction func(first Value, second Value) bool

This type defines the function signature for any function that can determine whether or not two specified values are equal to each other.

type Discerning 

type Discerning interface {
	CompareValues(first Value, second Value) bool
	RankValues(first Value, second Value) int
}

This interface defines the methods supported by all discerning agent types that can compare and rank two values.

type FIFO 

type FIFO[V Value] interface {
	GetCapacity() int
	AddValue(value V)
	AddValues(values Sequential[V])
	RemoveHead() (head V, ok bool)
	CloseQueue()
}

This interface defines the methods supported by all sequences whose values are accessed using first-in-first-out (FIFO) semantics.

func Join 

func Join[V Value](wg *syn.WaitGroup, inputs Sequential[FIFO[V]]) FIFO[V]

This function connects the outputs of the specified sequence of input queues with a new output queue returns the new output queue. Each value removed from each input queue will automatically be added to the output queue. This pattern is useful when the results of the processing with a Split() function need to be consolicated into a single queue.

type Flexible 

type Flexible[V Value] interface {
	AddValue(value V)
	AddValues(values Sequential[V])
	RemoveValue(value V)
	RemoveValues(values Sequential[V])
	RemoveAll()
}

This interface defines the methods supported by all sequences of values that allow values to be added and removed.

type FormatterLike 

type FormatterLike interface {
	Canonical
}

This interface defines the methods supported by all sorter-like types.

func Formatter 

func Formatter(indentation int) FormatterLike

This constructor creates a new instance of a formatter that can be used to format any value using the specified number of levels of indentation.

type Indexed 

type Indexed[V Value] interface {
	GetValue(index int) V
	GetValues(first int, last int) Sequential[V]
	GetIndex(value V) int
}

This interface defines the methods supported by all sequences whose values can be indexed. The indices of an indexed sequence are ORDINAL rather than ZERO based (which is "SO last century"). This allows for positive indices starting at the beginning of the sequence, and negative indices starting at the end of the sequence as follows: 

    1           2           3             N
[value 1] . [value 2] . [value 3] ... [value N]
   -N        -(N-1)      -(N-2)          -1

Notice that because the indices are ordinal based, the positive and negative indices are symmetrical.

type IteratorLike 

type IteratorLike[V Value] interface {
	Ratcheted[V]
}

This interface defines the methods supported by all iterator-like types.

func Iterator 

func Iterator[V Value](sequence Sequential[V]) IteratorLike[V]

This constructor creates a new instance of an iterator that can be used to traverse the values in the specified sequence.

type Key 

type Key any

type LIFO 

type LIFO[V Value] interface {
	GetCapacity() int
	AddValue(value V)
	AddValues(values Sequential[V])
	GetTop() V
	RemoveTop() V
	RemoveAll()
}

This interface defines the methods supported by all sequences whose values are accessed using last-in-first-out (LIFO) semantics.

type ListLike 

type ListLike[V Value] interface {
	Sequential[V]
	Indexed[V]
	Searchable[V]
	Updatable[V]
	Malleable[V]
	Sortable[V]
}

This interface consolidates all the interfaces supported by list-like sequences.

func Concatenate 

func Concatenate[V Value](first, second ListLike[V]) ListLike[V]

This function returns the concatenation of the two specified lists.

func List 

func List[V Value]() ListLike[V]

This constructor creates a new empty list that uses the natural compare function.

func ListFromArray 

func ListFromArray[V Value](array []V) ListLike[V]

This constructor creates a new list from the specified array. The list uses the natural compare function.

func ListFromSequence 

func ListFromSequence[V Value](sequence Sequential[V]) ListLike[V]

This constructor creates a new list from the specified sequence. The list uses the natural compare function.

func ListWithComparer 

func ListWithComparer[V Value](compare ComparisonFunction) ListLike[V]

This constructor creates a new empty list that uses the specified compare function.

type Malleable 

type Malleable[V Value] interface {
	AddValue(value V)
	AddValues(values Sequential[V])
	InsertValue(slot int, value V)
	InsertValues(slot int, values Sequential[V])
	RemoveValue(index int) V
	RemoveValues(first int, last int) Sequential[V]
	RemoveAll()
}

This interface defines the methods supported by all sequences whose values may be modified, inserted, removed, or reordered.

type Map 

type Map[K comparable, V Value] map[K]V

This type defines the structure and methods associated with a native map of key-value pair associations. This type is parameterized as follows:

  • K is a primitive type of key.
  • V is any type of entity.

func (Map[K, V]) AddAssociation 

func (v Map[K, V]) AddAssociation(association Binding[K, V])

This method appends the specified association to the end of this map.

func (Map[K, V]) AddAssociations 

func (v Map[K, V]) AddAssociations(associations Sequential[Binding[K, V]])

This method appends the specified associations to the end of this map.

func (Map[K, V]) AsArray 

func (v Map[K, V]) AsArray() []Binding[K, V]

This method returns all the associations that are in this map. The associations retrieved are in the same order as they are in the map.

func (Map[K, V]) GetKeys 

func (v Map[K, V]) GetKeys() Sequential[K]

This method returns the keys for this map.

func (Map[K, V]) GetSize 

func (v Map[K, V]) GetSize() int

This method returns the number of values contained in this map.

func (Map[K, V]) GetValue 

func (v Map[K, V]) GetValue(key K) V

This method returns the value that is associated with the specified key in this map.

func (Map[K, V]) GetValues 

func (v Map[K, V]) GetValues(keys Sequential[K]) Sequential[V]

This method returns the values associated with the specified keys for this map. The values are returned in the same order as the keys in the map.

func (Map[K, V]) IsEmpty 

func (v Map[K, V]) IsEmpty() bool

This method determines whether or not this map is empty.

func (Map[K, V]) RemoveAll 

func (v Map[K, V]) RemoveAll()

This method removes all associations from this map.

func (Map[K, V]) RemoveValue 

func (v Map[K, V]) RemoveValue(key K) V

This method removes the association associated with the specified key from the map and returns it.

func (Map[K, V]) RemoveValues 

func (v Map[K, V]) RemoveValues(keys Sequential[K]) Sequential[V]

This method removes the associations associated with the specified keys from the map and returns the removed values.

func (Map[K, V]) SetValue 

func (v Map[K, V]) SetValue(key K, value V)

This method sets the value associated with the specified key to the specified value.

func (Map[K, V]) String 

func (v Map[K, V]) String() string

type MapLike 

type MapLike[K Key, V Value] interface {
	Sequential[Binding[K, V]]
	Associative[K, V]
}

This interface consolidates all the interfaces supported by native map-like sequences. Note, that the order of the key-value pairs on a native map is random, even for two maps containing the same keys.

type QueueLike 

type QueueLike[V Value] interface {
	Sequential[V]
	FIFO[V]
}

This interface consolidates all of the interfaces supported by queue-like sequences.

func Queue 

func Queue[V Value]() QueueLike[V]

This constructor creates a new empty queue with the default capacity. The default capacity is 16 values.

func QueueWithCapacity 

func QueueWithCapacity[V Value](capacity int) QueueLike[V]

This constructor creates a new empty queue with the specified capacity.

type RankingFunction 

type RankingFunction func(first Value, second Value) int

This type defines the function signature for any function that can determine the relative ordering of two specified values. The result must be one of the following:

  • -1: The first value is less than the second value.
  • 0: The first value is equal to the second value.
  • 1: The first value is more than the second value.

type Ratcheted 

type Ratcheted[V Value] interface {
	GetSlot() int
	ToSlot(slot int)
	ToStart()
	ToEnd()
	HasPrevious() bool
	GetPrevious() V
	HasNext() bool
	GetNext() V
}

This interface defines the methods supported by all ratcheted agents that are capable of moving forward and backward over the values in a sequence. It is used to implement the GoF Iterator Pattern:

A ratcheted agent locks into the slots that reside between each value in the sequence: 

    [value 1] . [value 2] . [value 3] ... [value N]
  ^           ^           ^                         ^
slot 0      slot 1      slot 2                    slot N

It moves from slot to slot and has access to the values (if they exist) on each side of the slot.

type Searchable 

type Searchable[V Value] interface {
	ContainsValue(value V) bool
	ContainsAny(values Sequential[V]) bool
	ContainsAll(values Sequential[V]) bool
}

This interface defines the methods supported by all searchable sequences of values.

type Sequential 

type Sequential[V Value] interface {
	IsEmpty() bool
	GetSize() int
	AsArray() []V
}

This interface defines the methods supported by all sequences of values.

func Fork 

func Fork[V Value](wg *syn.WaitGroup, input FIFO[V], size int) Sequential[FIFO[V]]

This function connects the output of the specified input queue with a number of new output queues specified by the size parameter and returns a sequence of the new output queues. Each value added to the input queue will be added automatically to ALL of the output queues. This pattern is useful when a set of DIFFERENT operations needs to occur for every value and each operation can be done in parallel.

func Split 

func Split[V Value](wg *syn.WaitGroup, input FIFO[V], size int) Sequential[FIFO[V]]

This function connects the output of the specified input queue with the number of output queues specified by the size parameter and returns a sequence of the new output queues. Each value added to the input queue will be added automatically to ONE of the output queues. This pattern is useful when a SINGLE operation needs to occur for each value and the operation can be done on the values in parallel. The results can then be consolidated later on using the Join() function.

type SetLike 

type SetLike[V Value] interface {
	Sequential[V]
	Indexed[V]
	Searchable[V]
	Flexible[V]
}

This interface consolidates all the interfaces supported by set-like sequences.

func And 

func And[V Value](first, second SetLike[V]) SetLike[V]

This function returns the logical conjunction of the specified sets.

func Not 

func Not[V Value](set SetLike[V]) SetLike[V]

This function returns the logical inverse of the specified set.

func Or 

func Or[V Value](first, second SetLike[V]) SetLike[V]

This function returns the logical disjunction of the specified sets.

func Sans 

func Sans[V Value](first, second SetLike[V]) SetLike[V]

This function returns the logical material non-implication of the specified sets.

func Set 

func Set[V Value]() SetLike[V]

This constructor creates a new empty set that uses the natural rank function.

func SetFromArray 

func SetFromArray[V Value](array []V) SetLike[V]

This constructor creates a new set from the specified array. The set uses the natural rank function.

func SetFromSequence 

func SetFromSequence[V Value](sequence Sequential[V]) SetLike[V]

This constructor creates a new set from the specified sequence. The set uses the natural rank function.

func SetWithRanker 

func SetWithRanker[V Value](rank RankingFunction) SetLike[V]

This constructor creates a new empty set that uses the specified rank function.

func Xor 

func Xor[V Value](first, second SetLike[V]) SetLike[V]

This function returns the logical exclusive disjunction of the specified sets.

type Sort 

type Sort[V Value] func(array []V, rank RankingFunction)

This type defines the function signature for any function that can sort an array of values using a ranking function.

type Sortable 

type Sortable[V Value] interface {
	SortValues()
	SortValuesWithRanker(rank RankingFunction)
	ReverseValues()
	ShuffleValues()
}

This interface defines the methods supported by all sequences whose values may be sorted using various sorting algorithms.

type SorterLike 

type SorterLike[V Value] interface {
	Systematic[V]
}

This interface defines the methods supported by all sorter-like types.

func Sorter 

func Sorter[V Value](rank RankingFunction) SorterLike[V]

This constructor creates a new instance of a sorter that can be used to sort an array using a specific ranking function.

type StackLike 

type StackLike[V Value] interface {
	Sequential[V]
	LIFO[V]
}

This interface consolidates all the interfaces supported by stack-like sequences.

func Stack 

func Stack[V Value]() StackLike[V]

This constructor creates a new empty stack with the default capacity. The default capacity is 16 values.

func StackWithCapacity 

func StackWithCapacity[V Value](capacity int) StackLike[V]

This constructor creates a new empty stack with the specified capacity.

type Systematic 

type Systematic[V Value] interface {
	ReverseArray(array []V)
	ShuffleArray(array []V)
	SortArray(array []V)
}

This interface defines the methods supported by all systematic agents that can shuffle or sort an array of values using a ranking function.

type Updatable 

type Updatable[V Value] interface {
	SetValue(index int, value V)
	SetValues(index int, values Sequential[V])
}

This interface defines the methods supported by all updatable sequences of values.

type Value 

type Value any

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.