github.com/codysnider/go-ethereum@v1.10.18-0.20220420071915-14f4ae99222a/ethdb/iterator.go (about)

     1  // Copyright 2018 The go-ethereum Authors
     2  // This file is part of the go-ethereum library.
     3  //
     4  // The go-ethereum library is free software: you can redistribute it and/or modify
     5  // it under the terms of the GNU Lesser General Public License as published by
     6  // the Free Software Foundation, either version 3 of the License, or
     7  // (at your option) any later version.
     8  //
     9  // The go-ethereum library is distributed in the hope that it will be useful,
    10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    12  // GNU Lesser General Public License for more details.
    13  //
    14  // You should have received a copy of the GNU Lesser General Public License
    15  // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
    16  
    17  package ethdb
    18  
    19  // Iterator iterates over a database's key/value pairs in ascending key order.
    20  //
    21  // When it encounters an error any seek will return false and will yield no key/
    22  // value pairs. The error can be queried by calling the Error method. Calling
    23  // Release is still necessary.
    24  //
    25  // An iterator must be released after use, but it is not necessary to read an
    26  // iterator until exhaustion. An iterator is not safe for concurrent use, but it
    27  // is safe to use multiple iterators concurrently.
    28  type Iterator interface {
    29  	// Next moves the iterator to the next key/value pair. It returns whether the
    30  	// iterator is exhausted.
    31  	Next() bool
    32  
    33  	// Error returns any accumulated error. Exhausting all the key/value pairs
    34  	// is not considered to be an error.
    35  	Error() error
    36  
    37  	// Key returns the key of the current key/value pair, or nil if done. The caller
    38  	// should not modify the contents of the returned slice, and its contents may
    39  	// change on the next call to Next.
    40  	Key() []byte
    41  
    42  	// Value returns the value of the current key/value pair, or nil if done. The
    43  	// caller should not modify the contents of the returned slice, and its contents
    44  	// may change on the next call to Next.
    45  	Value() []byte
    46  
    47  	// Release releases associated resources. Release should always succeed and can
    48  	// be called multiple times without causing error.
    49  	Release()
    50  }
    51  
    52  // Iteratee wraps the NewIterator methods of a backing data store.
    53  type Iteratee interface {
    54  	// NewIterator creates a binary-alphabetical iterator over a subset
    55  	// of database content with a particular key prefix, starting at a particular
    56  	// initial key (or after, if it does not exist).
    57  	//
    58  	// Note: This method assumes that the prefix is NOT part of the start, so there's
    59  	// no need for the caller to prepend the prefix to the start
    60  	NewIterator(prefix []byte, start []byte) Iterator
    61  }