package db

import "io"

// Provides functionality to iterate over a database's key/value pairs in ascending order.

// It must be closed after use. A single iterator cannot be used concurrently. Multiple iterators can be used

// concurrently.

type Iterator interface {

io.Closer

// Valid returns true if the iterator is positioned at a valid key/value pair.

Valid() bool

// First moves the iterator to the first key/value pair. Returns true

// if the iterator is pointing at a valid entry and false otherwise.

First() bool

// Prev moves the iterator to the previous key/value pair. Returns true

// if the iterator is pointing at a valid entry and false otherwise.

Prev() bool

// Next moves the iterator to the next key/value pair. It returns whether the

// iterator is valid after the call. Once invalid, the iterator remains

// invalid.

Next() bool

// Key returns the key at the current position.

Key() []byte

// Value returns the value at the current position.

Value() ([]byte, error)

// DO NOT USE this unless the value is consumed immediately.

//

// UncopiedValue returns the value at the current position without copying it.

// The returned slice is invalidated by the next call to [Next], [Prev], or [Seek].

// Callers must copy the value if it needs to outlive the current iteration.

//

// This is intended for immediate unmarshalling to avoid an extra allocation.

UncopiedValue() ([]byte, error)

// Seek would seek to the provided key if present. If absent, it would seek to the next

// key in lexicographical order. Returns true if the iterator is pointing at a valid entry

// and false otherwise.

Seek(key []byte) bool

}