iters

package
v0.4.188 Latest Latest
Warning

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

 Go to latest Published: Jun 24, 2024 License: ISC Imports: 7 Imported by: 2

Documentation

Overview

Package iters provides thread-safe iterators usable with Go’s for statement

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BaseIterator added in v0.4.117 

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

BaseIterator is a type enclosed in iterator implementations implementing:

  • Iterator methods [Iterator.Cond] [Iterator.Next] [Iterator.Cancel]
  • consumer must:
  • — implement [Iterator.Init] since it returns the enclosing type
  • — provide IteratorAction

func NewBaseIterator added in v0.4.117 

func NewBaseIterator[T any](
	iteratorAction IteratorAction[T],
	asyncCancel ...func(),
) (iterator *BaseIterator[T])

NewBaseIterator returns an implementation of Cond Next Cancel methods part of iters.Iterator

  • asyncCancel is used if function or converter iterators are blocking. asyncCancel indicates that a Cancel invocation has occurred. ayncCancel may close a blocking Reader thereby asynchorously ending iteration

func (*BaseIterator[T]) Cancel added in v0.4.117 

func (i *BaseIterator[T]) Cancel(errp ...*error) (err error)

Cancel stops an iteration

  • after Cancel invocation, Cond, Next and Same indicate no value available
  • Cancel returns the first error that occurred during iteration, if any
  • an iterator implementation may require Cancel invocation to release resources
  • Cancel is deferrable

func (*BaseIterator[T]) Cond added in v0.4.118 

func (i *BaseIterator[T]) Cond(iterationVariablep *T, errp ...*error) (condition bool)

Cond implements the condition statement of a Go “for” clause

  • condition is true if iterationVariable was assigned a value and the iteration should continue
  • the iterationVariable is updated by being provided as a pointer. iterationVariable is only updated when condition is true. iterationVariable cannot be nil
  • errp is an optional error pointer receiving any errors during iterator execution. errp is only updated when condition is false and an error has occurred

Usage: 

for i, iterator := iters.NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
  // i is pointer to slice element

func (*BaseIterator[T]) Next added in v0.4.135 

func (i *BaseIterator[T]) Next() (value T, hasValue bool)

Next advances to next item and returns it

  • if hasValue true, value contains the next value
  • otherwise, no more items exist and value is the data type zero-value

type Converter added in v0.4.135 

type Converter[K any, V any] struct {
	*BaseIterator[V]
	// contains filtered or unexported fields
}

Converter traverses another iterator and returns converted values

func (*Converter[K, T]) Init added in v0.4.135 

func (i *Converter[K, T]) Init() (iterationVariable T, iterator Iterator[T])

Init implements the right-hand side of a short variable declaration in the init statement for a Go “for” clause

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

type ConverterFunction added in v0.4.117 

type ConverterFunction[K any, V any] func(key K, isCancel bool) (value V, err error)

ConverterFunction is the signature used by NewConverterIterator

  • ConverterFunction receives a key and returns the corresponding value.
  • if isCancel true, it means this is the last invocation of ConverterFunction and ConverterFunction should release any resources. Any returned value is not used
  • ConverterFunction signals end of values by returning parl.ErrEndCallbacks. Any returned value is not used
  • if ConverterFunction returns error, it will not be invoked again. Any returned value is not used
  • ConverterFunction must be thread-safe
  • ConverterFunction is invoked by at most one thread at a time

type Empty added in v0.4.135 

type Empty[T any] struct{}

Empty is an iterator with no values. thread-safe.

func (*Empty[T]) Cancel added in v0.4.135 

func (i *Empty[T]) Cancel(errp ...*error) (err error)

func (*Empty[T]) Cond added in v0.4.135 

func (i *Empty[T]) Cond(iterationVariablep *T, errp ...*error) (condition bool)

func (*Empty[T]) Init added in v0.4.135 

func (i *Empty[T]) Init() (iterationVariable T, iterator Iterator[T])

func (*Empty[T]) Next added in v0.4.135 

func (i *Empty[T]) Next() (value T, hasValue bool)

func (*Empty[T]) Same added in v0.4.135 

func (i *Empty[T]) Same() (value T, hasValue bool)

type Function added in v0.4.135 

type Function[T any] struct {

	// BaseIterator implements the DelegateAction[T] function required by
	// Delegator[T] and Cancel
	//	- provides its delegateAction method to Delegator
	*BaseIterator[T]
	// contains filtered or unexported fields
}

Function traverses a function generating values

func (*Function[T]) Init added in v0.4.135 

func (i *Function[T]) Init() (iterationVariable T, iterator Iterator[T])

Init implements the right-hand side of a short variable declaration in the init statement for a Go “for” clause

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

type IntegerIterator added in v0.4.135 

type IntegerIterator[T constraints.Integer] struct {
	// contains filtered or unexported fields
}

func (*IntegerIterator[T]) Cancel added in v0.4.135 

func (i *IntegerIterator[T]) Cancel(errp ...*error) (err error)

Cancel stops an iteration

  • after Cancel invocation, Cond, Next and Same indicate no value available
  • Cancel returns the first error that occurred during iteration, if any
  • an iterator implementation may require Cancel invocation to release resources
  • Cancel is deferrable

func (*IntegerIterator[T]) Cond added in v0.4.135 

func (i *IntegerIterator[T]) Cond(iterationVariablep *T, errp ...*error) (condition bool)

Cond implements the condition statement of a Go “for” clause

  • condition is true if iterationVariable was assigned a value and the iteration should continue
  • the iterationVariable is updated by being provided as a pointer. iterationVariable cannot be nil
  • errp is an optional error pointer receiving any errors during iterator execution

Usage: 

for i, iterator := iters.NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
  // i is pointer to slice element

func (*IntegerIterator[T]) Init added in v0.4.135 

func (i *IntegerIterator[T]) Init() (iterationVariable T, iterator Iterator[T])

Init implements the right-hand side of a short variable declaration in the init statement of a Go “for” clause 

	for i, iterator := iters.NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

func (*IntegerIterator[T]) Next added in v0.4.135 

func (i *IntegerIterator[T]) Next() (value T, hasValue bool)

Next advances to next item and returns it

  • if hasValue true, value contains the next value
  • otherwise, no more items exist and value is the data type zero-value

func (*IntegerIterator[T]) Same added in v0.4.135 

func (i *IntegerIterator[T]) Same() (value T, hasValue bool)

Same returns the same value again

  • if hasValue true, value is valid
  • otherwise, no more items exist and value is the data type zero-value
  • If Next or Cond has not been invoked, Same first advances to the first item

type Iterator 

type Iterator[T any] interface {
	// Init implements the right-hand side of a short variable declaration in
	// the init statement of a Go “for” clause
	//
	//		for i, iterator := iters.NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
	//	   // i is pointer to slice element
	Init() (iterationVariable T, iterator Iterator[T])
	// Cond implements the condition statement of a Go “for” clause
	//   - condition is true if iterationVariable was assigned a value and the iteration should continue
	//   - the iterationVariable is updated by being provided as a pointer.
	//     iterationVariable cannot be nil
	//   - errp is an optional error pointer receiving any errors during iterator execution
	//
	// Usage:
	//
	//  for i, iterator := iters.NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
	//    // i is pointer to slice element
	Cond(iterationVariablep *T, errp ...*error) (condition bool)
	// Next advances to next item and returns it
	//	- if hasValue true, value contains the next value
	//	- otherwise, no more items exist and value is the data type zero-value
	Next() (value T, hasValue bool)
	// Cancel stops an iteration
	//	- after Cancel invocation, Cond and Next indicate no value available
	//	- Cancel returns the first error that occurred during iteration, if any
	//	- an iterator implementation may require Cancel invocation
	//		to release resources
	//	- Cancel is deferrable
	Cancel(errp ...*error) (err error)
}

Iterator allows traversal of values.

  • iterate over an unimported type using an iterator returning a derived value such as an interface type
  • convert a slice value-by-value, ie. return interface-type values from a struct slice
  • iterate over pointers to slice values
  • iterate over function
  • obtain errors occurring in the iterator or release iterator resources

The iterator interface is optimized for use in the Go “for” clause. Iterators in the iters package are thread-safe but thread-safety depends on iterator implementation.

Usage in Go “for” clause: 

for i, iterator := NewIterator().Init(); iterator.Cond(&i); {
  println(i)

var err error
for i, iterator := NewIterator().Init(); iterator.Cond(&i, &err); {
  println(i)
}
if err != nil {

var err error
var iterator = NewIterator()
for i := 0; iterator.Cond(&i); {
  println(i)
}
if err = iterator.Cancel(); err != nil {

func NewConverterIterator 

func NewConverterIterator[K any, V any](
	keyIterator Iterator[K],
	converter ConverterFunction[K, V],
	asyncCancel ...func(),
) (iterator Iterator[V])

NewConverterIterator returns a converting iterator.

  • converterFunction receives cancel and can return error
  • ConverterIterator is thread-safe and re-entrant.
  • stores self-referencing pointers

func NewEmptyIterator 

func NewEmptyIterator[T any]() (iterator Iterator[T])

NewEmptyIterator returns an empty iterator of values type T.

  • EmptyIterator is thread-safe.

func NewFunctionIterator 

func NewFunctionIterator[T any](
	iteratorFunction IteratorFunction[T],
	asyncCancel ...func(),
) (iterator Iterator[T])

NewFunctionIterator returns an Iterator iterating over a function

  • thread-safe

func NewIntegerIterator added in v0.4.135 

func NewIntegerIterator[T constraints.Integer](firstValue, lastValue T) (iterator Iterator[T])

func NewSimpleConverterIterator added in v0.4.135 

func NewSimpleConverterIterator[K any, V any](
	keyIterator Iterator[K],
	simpleConverter SimpleConverter[K, V],
	asyncCancel ...func(),
) (iterator Iterator[V])

NewConverterIterator returns a converting iterator.

  • converterFunction receives cancel and can return error
  • ConverterIterator is thread-safe and re-entrant.
  • stores self-referencing pointers

func NewSimpleFunctionIterator added in v0.4.135 

func NewSimpleFunctionIterator[T any](
	iteratorFunction SimpleIteratorFunc[T],
	asyncCancel ...func(),
) (iterator Iterator[T])

NewFunctionIterator returns an Iterator iterating over a function

  • thread-safe

func NewSlice1Iterator added in v0.4.143 

func NewSlice1Iterator[T any](slice []T) (iterator Iterator[T])

NewSliceIterator returns an iterator iterating over slice T values

  • thread-safe
  • uses non-pointer atomics

func NewSliceInterfaceIterator added in v0.4.125 

func NewSliceInterfaceIterator[I any, E any](slice []E) (iterator Iterator[I])

NewSliceInterfaceIterator returns an iterator over slice []E returning those elements as interface I values

  • [I ~*E, E any] as an expression of interface I implemented by &E does not actually hold true at compile time. The check whether I is an interface implemented by &E has to take place at runtime
  • uses self-referencing pointers

func NewSliceIterator 

func NewSliceIterator[T any](slice []T) (iterator Iterator[T])

NewSliceIterator returns an iterator iterating over slice T values

  • thread-safe
  • uses non-pointer atomics

func NewSlicePointerIterator added in v0.4.117 

func NewSlicePointerIterator[E any](slice []E) (iterator Iterator[*E])

NewSlicePointerIterator returns an iterator of pointers to T

  • the difference is that:
  • instead of copying a value from the slice,
  • a pointer to the slice value is returned
  • the returned Iterator value cannot be copied, the pointer value must be used
  • uses self-referencing pointers

func NewSlicePointerIteratorField added in v0.4.125 

func NewSlicePointerIteratorField[E any](fieldp *SlicePointer[E], slice []E) (iterator Iterator[*E])

type IteratorAction added in v0.4.135 

type IteratorAction[T any] func(isCancel bool) (value T, err error)

IteratorAction is a delegated request from iters.BaseIterator

  • isCancel true: consumer requests cancel of iterator. No further IteratorAction invocations will occur. The iterator should release resources. The iterator may return an error
  • otherwise, the iterator can:
  • — return the next value, with err nil, continuing iteration
  • — return an error. No further invocations will occur, value is not used
  • — return err == parl.ErrEndCallbacks requesting an end to iterations without error. No further invocations will occur. ErrEndCallbacks error is not returned to the consumer
  • value is used if:
  • — returned err is nil and not ErrEndCallbacks and
  • — provided isCancel was false

type IteratorFunction added in v0.4.117 

type IteratorFunction[T any] func(isCancel bool) (value T, err error)

IteratorFunction is the signature used by NewFunctionIterator

  • if isCancel true, it means this is the last invocation of IteratorFunction and IteratorFunction should release any resources. Any returned value is not used
  • IteratorFunction signals end of values by returning parl.ErrEndCallbacks. Any returned value is not used
  • if IteratorFunction returns error, it will not be invoked again. Any returned value is not used
  • IteratorFunction must be thread-safe
  • IteratorFunction is invoked by at most one thread at a time

type NextAction 

type NextAction bool

NextAction is a unique named type that indicates whether the next or the same value again is sought by Delegate.Next

  • IsSame IsNext
const (
	// IsSame indicates to Delegate.Next that
	// this is a Same-type incovation
	IsSame NextAction = false
	// IsNext indicates to Delegate.Next that
	// this is a Next-type incovation
	IsNext NextAction = true
)

func (NextAction) String 

func (a NextAction) String() (s string)

type Simple added in v0.4.135 

type Simple[K any, V any] struct {

	// BaseIterator implements Cancel and the DelegateAction[T] function required by
	// Delegator[T]
	//	- receives invokeConverterFunction function
	//	- provides delegateAction function
	BaseIterator[V]
	// contains filtered or unexported fields
}

Converter traverses another iterator and returns converted values

func (*Simple[K, T]) Init added in v0.4.135 

func (i *Simple[K, T]) Init() (iterationVariable T, iterator Iterator[T])

Init implements the right-hand side of a short variable declaration in the init statement for a Go “for” clause

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

type SimpleConverter added in v0.4.135 

type SimpleConverter[K any, V any] func(key K) (value V)

type SimpleFunc added in v0.4.135 

type SimpleFunc[T any] struct {

	// BaseIterator implements the DelegateAction[T] function required by
	// Delegator[T] and Cancel
	//	- provides its delegateAction method to Delegator
	*BaseIterator[T]
	// contains filtered or unexported fields
}

Function traverses a function generating values

func (*SimpleFunc[T]) Init added in v0.4.135 

func (i *SimpleFunc[T]) Init() (iterationVariable T, iterator Iterator[T])

Init implements the right-hand side of a short variable declaration in the init statement for a Go “for” clause

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

type SimpleIteratorFunc added in v0.4.135 

type SimpleIteratorFunc[T any] func() (value T, hasValue bool)

type Slice added in v0.4.135 

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

Slice traverses a slice container. thread-safe

func (*Slice[T]) Cancel added in v0.4.135 

func (i *Slice[T]) Cancel(errp ...*error) (err error)

Cancel release resources for this iterator. Thread-safe

  • not every iterator requires a Cancel invocation

func (*Slice[T]) Cond added in v0.4.135 

func (i *Slice[T]) Cond(iterationVariablep *T, errp ...*error) (condition bool)

Cond implements the condition statement of a Go “for” clause

  • the iterationVariable is updated by being provided as a pointer. iterationVariable cannot be nil
  • errp is an optional error pointer receiving any errors during iterator execution
  • condition is true if iterationVariable was assigned a value and the iteration should continue

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

func (*Slice[T]) Init added in v0.4.135 

func (i *Slice[T]) Init() (iterationVariable T, iterator Iterator[T])

Init implements the right-hand side of a short variable declaration in the init statement for a Go “for” clause

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

func (*Slice[T]) Next added in v0.4.135 

func (i *Slice[T]) Next() (value T, hasValue bool)

Next advances to next item and returns it

  • if hasValue true, value contains the next value
  • otherwise, no more items exist and value is the data type zero-value

type Slice1 added in v0.4.143 

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

Slice traverses a slice container. thread-safe

func (*Slice1[T]) Cancel added in v0.4.143 

func (i *Slice1[T]) Cancel(errp ...*error) (err error)

Cancel release resources for this iterator. Thread-safe

  • not every iterator requires a Cancel invocation

func (*Slice1[T]) Cond added in v0.4.143 

func (i *Slice1[T]) Cond(iterationVariablep *T, errp ...*error) (condition bool)

Cond implements the condition statement of a Go “for” clause

  • the iterationVariable is updated by being provided as a pointer. iterationVariable cannot be nil
  • errp is an optional error pointer receiving any errors during iterator execution
  • condition is true if iterationVariable was assigned a value and the iteration should continue

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

func (*Slice1[T]) Init added in v0.4.143 

func (i *Slice1[T]) Init() (iterationVariable T, iterator Iterator[T])

Init implements the right-hand side of a short variable declaration in the init statement for a Go “for” clause

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

func (*Slice1[T]) Next added in v0.4.143 

func (i *Slice1[T]) Next() (value T, hasValue bool)

Next advances to next item and returns it

  • if hasValue true, value contains the next value
  • otherwise, no more items exist and value is the data type zero-value

type SliceInterface added in v0.4.135 

type SliceInterface[I any, E any] struct {
	SlicePointer[E]
}

func (*SliceInterface[I, E]) Cond added in v0.4.135 

func (i *SliceInterface[I, E]) Cond(iterationVariablep *I, errp ...*error) (condition bool)

Cond updates I interface pointers

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

func (*SliceInterface[I, E]) Init added in v0.4.135 

func (i *SliceInterface[I, E]) Init() (iterationVariable I, iterator Iterator[I])

Init initializes I interface values and returns an I iterator

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

func (*SliceInterface[I, E]) Next added in v0.4.135 

func (i *SliceInterface[I, E]) Next() (value I, hasValue bool)

Next advances to next item and returns it

  • if hasValue true, value contains the next value
  • otherwise, no more items exist and value is the data type zero-value

func (*SliceInterface[I, E]) Same added in v0.4.135 

func (i *SliceInterface[I, E]) Same() (value I, hasValue bool)

Same returns the same value again

  • if hasValue true, value is valid
  • otherwise, no more items exist and value is the data type zero-value
  • If Next or Cond has not been invoked, Same first advances to the first item

type SlicePointer added in v0.4.135 

type SlicePointer[E any] struct {
	// contains filtered or unexported fields
}

SlicePointer traverses a slice container using pointers to value. thread-safe.

  • the difference is that:
  • instead of copying a value from the slice,
  • a pointer to the slice value is returned

func (*SlicePointer[E]) Cancel added in v0.4.135 

func (i *SlicePointer[E]) Cancel(errp ...*error) (err error)

Cancel release resources for this iterator. Thread-safe

  • not every iterator requires a Cancel invocation

func (*SlicePointer[E]) Cond added in v0.4.135 

func (i *SlicePointer[E]) Cond(iterationVariablep **E, errp ...*error) (condition bool)

Cond implements the condition statement of a Go “for” clause

  • the iterationVariable is updated by being provided as a pointer. iterationVariable cannot be nil
  • errp is an optional error pointer receiving any errors during iterator execution
  • condition is true if iterationVariable was assigned a value and the iteration should continue

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

func (*SlicePointer[E]) Init added in v0.4.135 

func (i *SlicePointer[E]) Init() (iterationVariable *E, iterator Iterator[*E])

Init implements the right-hand side of a short variable declaration in the init statement for a Go “for” clause

Usage: 

	for i, iterator := NewSlicePointerIterator(someSlice).Init(); iterator.Cond(&i); {
   // i is pointer to slice element

func (*SlicePointer[T]) Next added in v0.4.135 

func (i *SlicePointer[T]) Next() (value *T, hasValue bool)

Next advances to next item and returns it

  • if hasValue true, value contains the next value
  • otherwise, no more items exist and value is the data type zero-value

func (*SlicePointer[T]) Same added in v0.4.135 

func (i *SlicePointer[T]) Same() (value *T, hasValue bool)

Same returns the same value again

  • if hasValue true, value is valid
  • otherwise, no more items exist and value is the data type zero-value
  • If Next or Cond has not been invoked, Same first advances to the first item

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.