iters

package
v0.4.118 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2023 License: ISC Imports: 8 Imported by: 2

Documentation

Index

Constants

View Source 
const FunctionIteratorCancel int = -1

when the iterator function receives this value, it means cancel

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 implements the DelegateAction[T] function required by Delegator[T]

func NewBaseIterator added in v0.4.117 

func NewBaseIterator[T any](
	invokeFn InvokeFunc[T],
	delegateActionReceiver *DelegateAction[T],
) (iterator *BaseIterator[T])

NewFunctionIterator returns a parli.Iterator based on a function. functionIterator is thread-safe and re-entrant.

func (BaseIterator) Cancel added in v0.4.117 

func (i BaseIterator) Cancel(errp ...*error) (err error)

Cancel release resources for this iterator. Not every iterator requires a Cancel invocation.

func (BaseIterator) Cond added in v0.4.118 

func (i BaseIterator) 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

type ConverterFunction added in v0.4.117 

type ConverterFunction[K constraints.Ordered, 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 ConverterIterator 

type ConverterIterator[K constraints.Ordered, V any] struct {

	// BaseIterator implements Cancel and the DelegateAction[T] function required by
	// Delegator[T]
	//	- receives invokeConverterFunction function
	//	- provides delegateAction function
	BaseIterator[V]
	// Delegator implements the value methods required by the [Iterator] interface
	//   - Next HasNext NextValue
	//     Same Has SameValue
	//   - receives DelegateAction[T] function
	Delegator[V]
	// contains filtered or unexported fields
}

ConverterIterator traverses another iterator and returns converted values. Thread-safe.

func (ConverterIterator) Cancel 

func (i ConverterIterator) Cancel(errp ...*error) (err error)

Cancel release resources for this iterator. Not every iterator requires a Cancel invocation.

func (ConverterIterator) Cond added in v0.4.118 

func (i ConverterIterator) 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

func (*ConverterIterator[K, T]) Init added in v0.4.118 

func (i *ConverterIterator[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

type Delegate 

type Delegate[T any] interface {
	// Next finds the next or the same value.
	// isSame indicates what value is sought.
	// value is the sought value or the T type’s zero-value if no value exists.
	// hasValue indicates whether value was assigned a T value.
	Action(isSame NextAction) (value T, hasValue bool)
	// Cancel indicates to the iterator implementation that iteration has concluded
	// and resources should be released.
	Cancel() (err error)
}

Delegate defines the methods that an iterator implementation must implement to use iterator.Delegator

  • Iterator methods: Next HasNext NextValue Same Has SameValue Cancel
  • Delegator Methods: Next HasNext NextValue Same Has SameValue
  • Delegate Methods Next Cancel

type DelegateAction added in v0.4.117 

type DelegateAction[T any] func(isSame NextAction) (value T, hasValue bool)

DelegateAction finds the next or the same value.

  • isSame == IsSame returns the same value again, finding the first value if a value has yet to be retrieved
  • isSame == IsNext find the next val;ue if one exists
  • value is the sought value or the T type’s zero-value if no value exists.
  • hasValue indicates whether value was assigned a T value.

type Delegator 

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

Delegator implements the value methods required by the Iterator interface

  • Next HasNext NextValue Same Has SameValue
  • the delegate provides DelegateAction[T] function
  • — delegate must be thread-safe
  • methods provided by Delegator: Has HasNext NextValue SameValue Same
  • delegate and Delegator combined fully implement the Iterator interface
  • Delegator is thread-safe

func NewDelegator 

func NewDelegator[T any](delegateAction DelegateAction[T]) (delegator *Delegator[T])

NewDelegator returns an Iterator based on a Delegate iterator implementation. Delegator is thread-safe if its delegate is thread-safe.

func (*Delegator[T]) Has 

func (d *Delegator[T]) Has() (hasValue bool)

Has returns true if Same() or SameValue will return items

  • If Next, FindNext or HasNext have not been invoked, Has first advances to the first item.

func (*Delegator[T]) HasNext 

func (d *Delegator[T]) HasNext() (hasValue bool)

HasNext advances to next item and returns hasValue true if this next item does exists.

func (*Delegator[T]) Next 

func (d *Delegator[T]) Next() (value T, hasValue bool)

Next advances to next item and returns it.

  • if the next item does exist, value is valid and hasValue is true.
  • if no next item exists, value is the data type zero-value and hasValue is false.

func (*Delegator[T]) NextValue 

func (d *Delegator[T]) NextValue() (value T)

NextValue advances to next item and returns it

  • If no next value exists, the data type zero-value is returned.

func (*Delegator[T]) Same 

func (d *Delegator[T]) Same() (value T, hasValue bool)

Same returns the same value again

  • If a value does exist, it is returned in value and hasValue is true.
  • If a value does not exist, the data type zero-value is returned and hasValue is false.
  • If Next, FindNext or HasNext have not been invoked, Same first advances to the first item.

func (*Delegator[T]) SameValue 

func (d *Delegator[T]) SameValue() (value T)

SameValue returns the same value again

  • If a value does not exist, the data type zero-value is returned.
  • If Next, FindNext or HasNext have not been invoked, SameValue first advances to the first item.

type EmptyIterator 

type EmptyIterator[T any] struct{}

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

func (*EmptyIterator[T]) Cancel 

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

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

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

func (*EmptyIterator[T]) Has 

func (i *EmptyIterator[T]) Has() (hasValue bool)

func (*EmptyIterator[T]) HasNext 

func (i *EmptyIterator[T]) HasNext() (ok bool)

func (*EmptyIterator[T]) Init added in v0.4.118 

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

func (*EmptyIterator[T]) Next 

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

func (*EmptyIterator[T]) NextValue 

func (i *EmptyIterator[T]) NextValue() (value T)

func (*EmptyIterator[T]) Same 

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

func (*EmptyIterator[T]) SameValue 

func (i *EmptyIterator[T]) SameValue() (value T)

type FunctionIterator 

type FunctionIterator[T any] struct {

	// BaseIterator implements the DelegateAction[T] function required by
	// Delegator[T] and Cancel
	//	- provides its delegateAction method to Delegator
	BaseIterator[T]
	// Delegator implements the value methods required by the [Iterator] interface
	//   - Next HasNext NextValue
	//     Same Has SameValue
	//   - Delegator obtains items using the provided DelegateAction[T] function
	Delegator[T]
	// contains filtered or unexported fields
}

FunctionIterator traverses a function generating values

func (FunctionIterator) Cancel 

func (i FunctionIterator) Cancel(errp ...*error) (err error)

Cancel release resources for this iterator. Not every iterator requires a Cancel invocation.

func (FunctionIterator) Cond added in v0.4.118 

func (i FunctionIterator) 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

func (*FunctionIterator[T]) Init added in v0.4.118 

func (i *FunctionIterator[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

type InvokeFunc added in v0.4.117 

type InvokeFunc[T any] func(isCancel bool) (
	value T,
	didCancel bool,
	isPanic bool,
	err error,
)

InvokeFunc is the signature used by NewBaseIterator

  • isCancel is a request to cancel iteration. No more invocations will occur. Iterator should release resources
  • value is valid if err is nil and isCancel was false and didCancel is false. otherwise, value is ignored
  • if err is non-nil an error occurred. parl.ErrEndCallbacks allows InvokeFunc to signal end of iteration values. parl.ErrEndCallbacks error is ignored.
  • if isCancel was false and didCancel is true, IncokeFunc took the initiative to cancel the iteration. No more invocations will occur
  • isPanic indicates that err is the result of a panic

type Iterator 

type Iterator[T any] interface {
	// Init implements the right-hand side of a short variable declaration in
	// the init statement for a Go “for” clause
	Init() (iterationVariable T, iterator Iterator[T])
	// 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
	Cond(iterationVariablep *T, errp ...*error) (condition bool)
	// Next advances to next item and returns it
	//	- if the next item does exist, value is valid and hasValue is true
	//	- if no next item exists, value is the data type zero-value and hasValue is false
	Next() (value T, hasValue bool)
	// Same returns the same value again.
	//	- If a value does exist, it is returned in value and hasValue is true
	//	- If a value does not exist, the data type zero-value is returned and hasValue is false
	//	- If Next or Cond has not been invoked, Same first advances to the first item
	Same() (value T, hasValue bool)
	// Cancel release resources for this iterator
	//	- returns the first error that occurred during iteration if any
	//	- Not every iterator requires a Cancel invocation
	Cancel(errp ...*error) (err error)
}

Iterator allows traversal of values.

Iterators in the iters package are thread-safe but generally, thread-safety depends on the iterator implementation used.

the ForIterator interface is optimized for use in the Go “for” clause

The iterators in parly.iterator are thread-safe and re-entrant, but generally, this depends on the iterator implementation used. 

// triple-expression works for Iterator that do not require Cancel
for iterator := NewIterator(); iterator.HasNext(); {
	v := iterator.SameValue()
}

// conditional expression can be used with all iterators
iterator := NewIterator()
for iterator.HasNext() {
	v := iterator.SameValue()
}
if err = iterator.Cancel(); …

ForIterator is an iterator optimized for the Init and Condition statements of a Go “for” clause

Usage: 

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

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

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

func NewConverterIterator 

func NewConverterIterator[K constraints.Ordered, V any](
	keyIterator Iterator[K],
	converterFunction ConverterFunction[K, V],
) (iterator Iterator[V])

NewConverterIterator returns a converting iterator.

  • ConverterIterator is thread-safe and re-entrant.

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],
) (iterator Iterator[T])

NewFunctionIterator returns an Iterator iterating over a function

  • thread-safe

func NewSliceIterator 

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

NewSliceIterator returns an empty iterator of values type T. sliceIterator is thread-safe.

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

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 uint8

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 = 0
	// IsNext indicates to Delegate.Next that
	// this is a Next-type incovation
	IsNext NextAction = 1
)

func (NextAction) String 

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

type SliceIterator 

type SliceIterator[T any] struct {

	// Delegator implements the value methods required by the [Iterator] interface
	//   - Next HasNext NextValue
	//     Same Has SameValue
	//   - the delegate provides DelegateAction[T] function
	Delegator[T]
	// contains filtered or unexported fields
}

SliceIterator traverses a slice container. thread-safe

func (*SliceIterator[T]) Cancel 

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

Cancel release resources for this iterator. Thread-safe

  • not every iterator requires a Cancel invocation

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

func (i *SliceIterator[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

func (*SliceIterator[T]) Init added in v0.4.118 

func (i *SliceIterator[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

type SlicePointerIterator added in v0.4.117 

type SlicePointerIterator[E any, T *E] struct {

	// Delegator implements the value methods required by the [Iterator] interface
	//   - Next HasNext NextValue
	//     Same Has SameValue
	//   - the delegate provides DelegateAction[T] function
	Delegator[T]
	// contains filtered or unexported fields
}

SlicePointerIterator 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 (*SlicePointerIterator[E, T]) Cancel added in v0.4.117 

func (i *SlicePointerIterator[E, T]) Cancel(errp ...*error) (err error)

Cancel release resources for this iterator. Thread-safe

  • not every iterator requires a Cancel invocation

func (*SlicePointerIterator[E, T]) Cond added in v0.4.118 

func (i *SlicePointerIterator[E, 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

func (*SlicePointerIterator[E, T]) Init added in v0.4.118 

func (i *SlicePointerIterator[E, 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

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.