Collections - craterdog/go-component-framework GitHub Wiki

Overview

The Go language and its native libraries do not provide any high-level data collections—only the low-level intrinsic array, slice and map primitives.

The collection package provides a generics-based collection framework on top of the Go intrinsic types. Higher level programming tasks often involve sequences of values that need to be manipulated is specific ways.

• Catalog (a sortable map of key-value associations)
• List (a sortable list)
• Queue (a blocking FIFO)
• Set (an ordered set)
• Stack (a LIFO)

These generics-based collection types are more intuitive and easier to use than the low level Go intrinsic types. Each collection type also implements the Go Stringer interface making logging and debugging easier.

The explicit sequence classes allow the traversal of their values using an iterator.

Ordinal Based Indexing

One could argue that cardinal (quantitative: 0, 1, 2, etc.) based indices might possibly have made sense 70 years ago when assembly languages were mapping directly to memory locations that included index offset amounts. We would argue, however, that even back then for programming languages it would have made more sense to use ordinal (positional: "first", "second", etc.) based indices and reserved the value 0 for an invalid index instead of -1. Alas, that is all "water under the bridge" as they say...

Regardless of where you stand on this debate, we think you will find our approach to indexing very intuitive and easy to use.

The various interfaces for the collection types provided by this framework support both positive and negative indices. And since they are ordinal based, the positive and negative indices are symmetrical. You can use an index of 1 to access the first value in a sequence and -1 to access the last value. The values can also be accessed sequentially using an Iterator[V].

Choosing a Collection Type

The following flowchart helps you determine which type of collection will best suit your programming needs.

To view the details of a particular collection class type click on the links listed in the side bar in the upper right corner ↗️ of this page.

Class Model

The following UML diagram shows the ClassLike interfaces (shown in blue) that are defined for each collection class. The ClassLike interfaces define the constructors that are used to create new instances of each class type.

The collections package itself defines global functions (shown in pink) for accessing each class interface. The global functions are the only concrete functions defined in the package—everything else is either an abstract type or an interface. This is in accordance with the Crater Dog Coding Conventions defined here.