Iterators

Documentation

Overview

Package Iterators provides a set of types that allow iterating over collections of elements in a generic and procedural manner.

Package Iterators provides a set of types that allow iterating over collections of elements in a generic and procedural manner.

Package Iterators provides a set of types that allow iterating over collections of elements in a generic and procedural manner.

Index

• func SliceOf[T any](elem any) []T
• type Builder
  • func (b *Builder[T]) Add(element T)
  • func (b *Builder[T]) AddMany(elements []T)
  • func (b *Builder[T]) Build() *SimpleIterator[T]
  • func (b *Builder[T]) Clear()
• type DynamicIterator
  • func NewDynamicIterator[E, T any](source Iterater[E], f func(E) *SimpleIterator[T]) *DynamicIterator[E, T]
  • func (iter *DynamicIterator[E, T]) Consume() (T, error)
  • func (iter *DynamicIterator[E, T]) Restart()
  • func (iter *DynamicIterator[E, T]) Size() (count int)
• type ErrExhaustedIter
  • func NewErrExhaustedIter() *ErrExhaustedIter
  • func (e *ErrExhaustedIter) Error() string
• type ErrNotInitialized
  • func NewErrNotInitialized() *ErrNotInitialized
  • func (e *ErrNotInitialized) Error() string
• type Iterable
• type Iterater
  • func IteratorOf[T any](elem any) Iterater[T]
• type ProceduralIterator
  • func NewProceduralIterator[E Iterable[T], T any](source Iterater[E]) *ProceduralIterator[E, T]
  • func (iter *ProceduralIterator[E, T]) Consume() (T, error)
  • func (iter *ProceduralIterator[E, T]) Restart()
  • func (iter *ProceduralIterator[E, T]) Size() (count int)
• type SimpleIterator
  • func NewSimpleIterator[T any](values []T) *SimpleIterator[T]
  • func (iter *SimpleIterator[T]) Consume() (T, error)
  • func (iter *SimpleIterator[T]) Restart()
  • func (iter *SimpleIterator[T]) Size() int
• type Slicer

Functions

func SliceOf

func SliceOf[T any](elem any) []T

SliceOf converts any type to a slice of elements of the same type.

Parameters:

• elem: The element to convert to a slice.

Returns:

• []T: The slice representation of the element.

Behaviors:

• Nil elements are converted to nil slices.
• Slice elements are returned as is.
• Slicer elements have their Slice method called.
• Other elements are converted to slices containing a single element.

Types

type Builder

type Builder[T any] struct {
	// contains filtered or unexported fields
}

Builder is a struct that allows building iterators over a collection of elements.

func (*Builder[T]) Add

func (b *Builder[T]) Add(element T)

Add is a method of the Builder type that appends an element to the buffer.

Parameters:

• element: The element to append to the buffer.

func (*Builder[T]) AddMany

func (b *Builder[T]) AddMany(elements []T)

AddMany is a method of the Builder type that appends multiple elements to the buffer.

Parameters:

• elements: The elements to append to the buffer.

func (*Builder[T]) Build

func (b *Builder[T]) Build() *SimpleIterator[T]

Build creates a new iterator over the buffer of elements.

It clears the buffer after creating the iterator.

Returns:

• *SimpleIterator[T]: The new iterator.

func (*Builder[T]) Clear

func (b *Builder[T]) Clear()

Clear is a method of the Builder type that removes all elements from the buffer.

type DynamicIterator

type DynamicIterator[E, T any] struct {
	// contains filtered or unexported fields
}

DynamicIterator is a struct that allows iterating over a collection of iterators of type Iterater[T]. The major difference between this and the GenericIterator is that this iterator is designed to iterate over a collection of elements in a progressive manner; reducing the need to store the entire collection in memory.

func NewDynamicIterator

func NewDynamicIterator[E, T any](source Iterater[E], f func(E) *SimpleIterator[T]) *DynamicIterator[E, T]

IteratorFromIterator creates a new iterator over a collection of iterators of type Iterater[T]. It uses the input iterator to iterate over the collection of iterators and return the elements from each iterator in turn.

Parameters:

• source: The iterator over the collection of iterators to iterate over.
• f: The transition function that takes an element of type E and returns an iterator.

Return:

• *DynamicIterator[E, T]: The new iterator. Nil if f is nil.

func (*DynamicIterator[E, T]) Consume

func (iter *DynamicIterator[E, T]) Consume() (T, error)

Consume implements the Iterater interface.

func (*DynamicIterator[E, T]) Restart

func (iter *DynamicIterator[E, T]) Restart()

Restart implements the Iterater interface.

func (*DynamicIterator[E, T]) Size

func (iter *DynamicIterator[E, T]) Size() (count int)

Size implements the Iterater interface for the DynamicIterator type.

Size is evaluated by summing the sizes of the current iterator and the source iterator. Of course, this is just an estimate of the total number of elements in the collection.

type ErrExhaustedIter

type ErrExhaustedIter struct{}

ErrExhaustedIter is an error type that is returned when an iterator is exhausted (i.e., there are no more elements to consume).

func NewErrExhaustedIter

func NewErrExhaustedIter() *ErrExhaustedIter

NewErrExhaustedIter creates a new ErrExhaustedIter error.

Returns:

• *ErrExhaustedIter: A pointer to the new error.

func (*ErrExhaustedIter) Error

func (e *ErrExhaustedIter) Error() string

Error implements the error interface.

Message: "iterator is exhausted"

type ErrNotInitialized

type ErrNotInitialized struct{}

ErrNotInitialized is an error type that is returned when an iterator is not initialized.

func NewErrNotInitialized

func NewErrNotInitialized() *ErrNotInitialized

NewErrNotInitialized creates a new ErrNotInitialized error.

Returns:

• *ErrNotInitialized: A pointer to the new error.

func (*ErrNotInitialized) Error

func (e *ErrNotInitialized) Error() string

Error implements the error interface.

Message: "iterator is not initialized"

type Iterable

type Iterable[T any] interface {
	// Iterator returns an iterator over the collection of elements.
	//
	// Returns:
	//   - Iterater[T]: An iterator over the collection of elements.
	Iterator() Iterater[T]
}

Iterable is an interface that defines a method to get an iterator over a collection of elements of type T. It is implemented by data structures that can be iterated over.

type Iterater

type Iterater[T any] interface {
	// Size returns the number of elements in the collection.
	//
	// Returns:
	//  - count: The number of elements in the collection.
	Size() (count int)

	// The Consume method advances the iterator to the next element in the
	// collection and returns the current element.
	//
	// Returns:
	//  - T: The current element in the collection.
	//  - error: An error if the iterator is exhausted or if an error occurred
	//    while consuming the element.
	Consume() (T, error)

	// The Restart method resets the iterator to the beginning of the
	// collection.
	Restart()
}

Iterater is an interface that defines methods for an iterator over a collection of elements of type T.

func IteratorOf

func IteratorOf[T any](elem any) Iterater[T]

IteratorOf converts any type to an iterator over elements of the same type.

Parameters:

• elem: The element to convert to an iterator.

Returns:

• Iterater[T]: The iterator over the element.

Behaviors:

• IF elem is nil, an empty iterator is returned.
• IF elem -implements-> Iterater[T], the element is returned as is.
• IF elem -implements-> Iterable[T], the element's Iterator method is called.
• IF elem -implements-> []T, a new iterator over the slice is created.
• ELSE, a new iterator over a single-element collection is created.

type ProceduralIterator

type ProceduralIterator[E Iterable[T], T any] struct {
	// contains filtered or unexported fields
}

ProceduralIterator is a struct that allows iterating over a collection of iterators of type Iterater[T]. The major difference between this and the GenericIterator is that this iterator is designed to iterate over a collection of elements in a progressive manner; reducing the need to store the entire collection in memory.

func NewProceduralIterator

func NewProceduralIterator[E Iterable[T], T any](source Iterater[E]) *ProceduralIterator[E, T]

IteratorFromIterator creates a new iterator over a collection of iterators of type Iterater[T]. It uses the input iterator to iterate over the collection of iterators and return the elements from each iterator in turn.

Parameters:

• source: The iterator over the collection of iterators to iterate over.

Return:

• *ProceduralIterator[E, T]: The new iterator over the collection of elements.

func (*ProceduralIterator[E, T]) Consume

func (iter *ProceduralIterator[E, T]) Consume() (T, error)

Consume implements the Iterater interface.

Panics if E is not convertible to *SimpleIterator[T].

func (*ProceduralIterator[E, T]) Restart

func (iter *ProceduralIterator[E, T]) Restart()

Restart implements the Iterater interface.

func (*ProceduralIterator[E, T]) Size

func (iter *ProceduralIterator[E, T]) Size() (count int)

Size implements the Iterater interface.

Size is evaluated by summing the sizes of the current iterator and the source iterator. Of course, this is just an estimate of the total number of elements in the collection.

type SimpleIterator

type SimpleIterator[T any] struct {
	// contains filtered or unexported fields
}

SimpleIterator is a struct that allows iterating over a slice of elements of any type.

func NewSimpleIterator

func NewSimpleIterator[T any](values []T) *SimpleIterator[T]

NewSimpleIterator creates a new iterator over a slice of elements of type T.

Parameters:

• values: The slice of elements to iterate over.

Return:

• *SimpleIterator[T]: A new iterator over the given slice of elements.

Behaviors:

• If values is nil, the iterator is initialized with an empty slice.
• Modifications to the slice of elements after creating the iterator will affect the values seen by the iterator.

func (*SimpleIterator[T]) Consume

func (iter *SimpleIterator[T]) Consume() (T, error)

Consume implements the Iterater interface.

func (*SimpleIterator[T]) Restart

func (iter *SimpleIterator[T]) Restart()

Restart implements the Iterater interface.

func (*SimpleIterator[T]) Size

func (iter *SimpleIterator[T]) Size() int

Size implements the Iterater interface.

type Slicer

type Slicer[T any] interface {
	// Slice returns a slice containing all the elements in the data structure.
	//
	// Returns:
	//   - []T: A slice containing all the elements in the data structure.
	Slice() []T

	Iterable[T]
}

Slicer is an interface that provides a method to convert a data structure to a slice.