iterator

Documentation

Overview

Package iterator describes a generic Iterator interface.

Index

• Variables
• 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 Interface
  • 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]

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 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.

Iterator is always closed at the end.

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 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 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 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.