iterator

Documentation

Overview

Package iterator describes a generic Iterator interface and related utilities.

Index

• Variables
• func ConsumeCount[K, V any](iter Interface[K, V]) (int, error)
• func ConsumeValues[K, V any](iter Interface[K, V]) ([]V, error)
• func ConsumeValuesN[K, V any](iter Interface[K, V], n int) ([]V, error)
• type Closer
• type CloserFunc
  • func (cf CloserFunc) Close()
• type Interface
  • func ForFunc[K, V any](f NextFunc[K, V]) Interface[K, V]
  • func ForSlice[V any](s []V) Interface[int, V]
  • func Values[K, V any](iter Interface[K, V]) Interface[struct{}, V]
  • func WithClose[K, V any](iter Interface[K, V], close func()) Interface[K, V]
• type MultiCloser
  • func NewMultiCloser(closers ...Closer) *MultiCloser
  • func (mc *MultiCloser) Add(closers ...Closer)
  • func (mc *MultiCloser) Close()
• type NextFunc

Variables

var ErrIteratorDone = errors.New("iterator is read to the end or closed")

ErrIteratorDone is returned when the iterator is read to the end or closed.

Functions

func ConsumeCount

func ConsumeCount[K, V any](iter Interface[K, V]) (int, error)

ConsumeCount returns the number of elements in the iterator. ErrIteratorDone error is returned as nil; any other error is returned as-is.

It always closes the iterator.

func ConsumeValues

func ConsumeValues[K, V any](iter Interface[K, V]) ([]V, error)

ConsumeValues consumes all values from iterator until it is done. ErrIteratorDone error is returned as nil; any other error is returned as-is.

It always closes the iterator.

func ConsumeValuesN

func ConsumeValuesN[K, V any](iter Interface[K, V], n int) ([]V, error)

ConsumeValuesN consumes up to n values from iterator or until it is done. ErrIteratorDone error is returned as nil; any other error is returned as-is.

Iterator is closed when it is done or on any error. Simply consuming n values does not close the iterator.

Consuming already done iterator returns (nil, nil). The same result is returned for n = 0.

Types

type Closer

type Closer interface {
	Close()
}

Closer is a part of Interface for closing iterators.

type CloserFunc

type CloserFunc func()

CloserFunc converts a function (such as context.CancelFunc) to a Closer.

func (CloserFunc) Close

func (cf CloserFunc) Close()

Close implements Closer.

type Interface

type Interface[K, V any] interface {
	// Next returns the next key/value pair, where the key is a slice index, map key, document number, etc,
	// and the value is the slice or map value, next document, etc.
	//
	// Returned error could be (possibly wrapped) ErrIteratorDone or some fatal error
	// like (possibly wrapped) context.Canceled.
	// In any case, even if iterator was read to the end, and Next returned ErrIteratorDone,
	// or Next returned fatal error,
	// Close method still should be called.
	//
	// Next should return either key/value pair or error, not both and not neither.
	// For example, single-value iterators should not return (key, value, ErrIteratorDone).
	//
	// Next should not be called concurrently with other Next calls,
	// but it can be called concurrently with Close.
	Next() (K, V, error)

	// Close indicates that the iterator will no longer be used.
	// After Close is called, future calls to Next must return ErrIteratorDone,
	// even if previous call returned a different error.
	//
	// Close must be called.
	// If it wasn't, the iterator might leak resources or panic later.
	//
	// Close must be concurrency-safe and may be called multiple times.
	// All calls after the first should have no observable effect.
	Close()
}

Interface is an iterator interface.

func ForFunc

func ForFunc[K, V any](f NextFunc[K, V]) Interface[K, V]

ForFunc returns an iterator for the given function.

func ForSlice

func ForSlice[V any](s []V) Interface[int, V]

ForSlice returns an iterator over a slice.

func Values

func Values[K, V any](iter Interface[K, V]) Interface[struct{}, V]

Values returns an iterator over values of another iterator.

Close method closes the underlying iterator. For that reason, there is no need to track both iterators.

func WithClose

func WithClose[K, V any](iter Interface[K, V], close func()) Interface[K, V]

WithClose wraps an iterator with a custom close function.

That function should call Close() method of the wrapped iterator.

type MultiCloser

type MultiCloser struct {
	// contains filtered or unexported fields
}

MultiCloser is a helper for closing multiple closers.

func NewMultiCloser

func NewMultiCloser(closers ...Closer) *MultiCloser

NewMultiCloser returns a new MultiCloser for non-nil closers.

func (*MultiCloser) Add

func (mc *MultiCloser) Add(closers ...Closer)

Add adds non-nil closers to the MultiCloser.

func (*MultiCloser) Close

func (mc *MultiCloser) Close()

Close closes all added closers.

type NextFunc

type NextFunc[K, V any] func() (K, V, error)

NextFunc is a part of Interface for the Next method.