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.

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() Iterater[T]
  • func (b *Builder[T]) Clear()
• type ErrExhaustedIter
  • func NewErrExhaustedIter() *ErrExhaustedIter
  • func (e *ErrExhaustedIter) Error() string
• type ErrNotInitialized
  • func NewErrNotInitialized() *ErrNotInitialized
  • func (e *ErrNotInitialized) Error() string
• type GenericIterator
  • func NewGenericIterator[T any](values []T) *GenericIterator[T]
  • func (iter *GenericIterator[T]) Consume() (T, error)
  • func (iter *GenericIterator[T]) Restart()
• type Iterable
• type Iterater
  • func IteratorOf[T any](elem any) Iterater[T]
• type ProceduralIterator
  • func NewProceduralIterator[E, T any](source Iterater[E], f func(E) Iterater[T]) (*ProceduralIterator[E, T], error)
  • func (iter *ProceduralIterator[E, T]) Consume() (T, error)
  • func (iter *ProceduralIterator[E, T]) Restart()
• 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() Iterater[T]

Build creates a new iterator over the buffer of elements.

It clears the buffer after creating the iterator.

Returns:

• Iterater[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 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 is a method of the error interface that returns the error message.

Returns:

• string: The error message.

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 is a method of the error interface that returns the error message.

Returns:

• string: The error message.

type GenericIterator

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

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

func NewGenericIterator

func NewGenericIterator[T any](values []T) *GenericIterator[T]

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

Parameters:

• values: The slice of elements to iterate over.

Return:

• *GenericIterator[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 (*GenericIterator[T]) Consume

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

Consume is a method of the GenericIterator type that advances the iterator to the next element in the collection and returns the current element.

Errors:

• *ErrNotInitialized: If the iterator is not initialized.
• *ErrExhaustedIter: If the iterator is exhausted.

Returns:

• T: The current element in the collection.
• error: An error if it is not possible to consume the next element.

func (*GenericIterator[T]) Restart

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

Restart is a method of the GenericIterator type that resets the iterator to the beginning of the collection.

type Iterable

type Iterable[T any] interface {
	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 {
	// 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.
	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, 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, T any](source Iterater[E], f func(E) Iterater[T]) (*ProceduralIterator[E, T], error)

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:

• Iterater[T]: The new iterator over the collection of elements.
• error: An error of type *ers.ErrInvalidParameter if the transition function is nil.

func (*ProceduralIterator[E, T]) Consume

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

Consume is a method of the ProceduralIterator type that advances the iterator to the next element in the collection and returns the current element.

Errors:

• *ErrNotInitialized: If the iterator is not initialized.
• *ErrExhaustedIter: If the iterator is exhausted.

Returns:

• T: The current element in the collection.
• error: An error if it is not possible to consume the next element.

func (*ProceduralIterator[E, T]) Restart

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

Restart is a method of the ProceduralIterator type that resets the iterator to the beginning of the collection.

type Slicer

type Slicer[T any] interface {
	// The Slice method returns 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.