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 IsExhaustedIter(err error) bool
• 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], error)
  • func (iter *DynamicIterator[E, T]) Consume() (T, error)
  • func (iter *DynamicIterator[E, T]) Restart()
  • func (iter *DynamicIterator[E, T]) Size() 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() 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 IsExhaustedIter

func IsExhaustedIter(err error) bool

IsExhaustedIter checks if an error is an *ErrExhaustedIter error.

Parameters:

• err: The error to check.

Returns:

• bool: True if the error is an *ErrExhaustedIter error, false otherwise.

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], 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 (*DynamicIterator[E, T]) Consume

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

Consume is a method of the DynamicIterator 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 (*DynamicIterator[E, T]) Restart

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

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

func (*DynamicIterator[E, T]) Size

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

Size is a method of the DynamicIterator type that returns the number of elements in the collection.

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.

Returns:

• int: The 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 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 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 {
	// Size returns the number of elements in the collection.
	//
	// Returns:
	//  - int: The number of elements in the collection.
	Size() 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.
	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:

• Iterater[T]: The new iterator over the collection of elements.

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.

func (*ProceduralIterator[E, T]) Size

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

Size is a method of the ProceduralIterator type that returns the number of elements in the collection.

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.

Returns:

• int: The 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:

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

func (iter *SimpleIterator[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 (*SimpleIterator[T]) Restart

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

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

func (*SimpleIterator[T]) Size

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

Size is a method of the GenericIterator type that returns the number of elements in the collection.

Returns:

• int: The number of elements in 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.