iterator

package
v1.21.0 Latest Latest
Warning

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

Go to latest
Published: Mar 20, 2024 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package iterator describes a generic Iterator interface and related utilities.

Index

Constants

This section is empty.

Variables

View Source
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 added in v1.1.0

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 added in v1.0.0

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 added in v1.0.0

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 added in v1.1.0

type Closer interface {
	Close()
}

Closer is a part of Interface for closing iterators.

type CloserFunc added in v1.5.0

type CloserFunc func()

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

func (CloserFunc) Close added in v1.5.0

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 added in v1.1.0

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

ForFunc returns an iterator for the given function.

func ForSlice added in v1.0.0

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

ForSlice returns an iterator over a slice.

func Values added in v0.9.0

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 added in v0.9.1

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 added in v1.1.0

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

MultiCloser is a helper for closing multiple closers.

func NewMultiCloser added in v1.1.0

func NewMultiCloser(closers ...Closer) *MultiCloser

NewMultiCloser returns a new MultiCloser for non-nil closers.

func (*MultiCloser) Add added in v1.1.0

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

Add adds non-nil closers to the MultiCloser.

func (*MultiCloser) Close added in v1.1.0

func (mc *MultiCloser) Close()

Close closes all added closers.

type NextFunc added in v1.1.0

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

NextFunc is a part of Interface for the Next method.

Directories

Path Synopsis
Package testiterator provides a helper for checking iterator implementations.
Package testiterator provides a helper for checking iterator implementations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL