github.com/insionng/yougam@v0.0.0-20170714101924-2bc18d833463/libraries/syndtr/goleveldb/leveldb/iterator/iter.go (about)

     1  // Copyright (c) 2012, Suryandaru Triandana <syndtr@gmail.com>
     2  // All rights reserved.
     3  //
     4  // Use of this source code is governed by a BSD-style license that can be
     5  // found in the LICENSE file.
     6  
     7  // Package iterator provides interface and implementation to traverse over
     8  // contents of a database.
     9  package iterator
    10  
    11  import (
    12  	"errors"
    13  
    14  	"github.com/insionng/yougam/libraries/syndtr/goleveldb/leveldb/util"
    15  )
    16  
    17  var (
    18  	ErrIterReleased = errors.New("leveldb/iterator: iterator released")
    19  )
    20  
    21  // IteratorSeeker is the interface that wraps the 'seeks method'.
    22  type IteratorSeeker interface {
    23  	// First moves the iterator to the first key/value pair. If the iterator
    24  	// only contains one key/value pair then First and Last whould moves
    25  	// to the same key/value pair.
    26  	// It returns whether such pair exist.
    27  	First() bool
    28  
    29  	// Last moves the iterator to the last key/value pair. If the iterator
    30  	// only contains one key/value pair then First and Last whould moves
    31  	// to the same key/value pair.
    32  	// It returns whether such pair exist.
    33  	Last() bool
    34  
    35  	// Seek moves the iterator to the first key/value pair whose key is greater
    36  	// than or equal to the given key.
    37  	// It returns whether such pair exist.
    38  	//
    39  	// It is safe to modify the contents of the argument after Seek returns.
    40  	Seek(key []byte) bool
    41  
    42  	// Next moves the iterator to the next key/value pair.
    43  	// It returns whether the iterator is exhausted.
    44  	Next() bool
    45  
    46  	// Prev moves the iterator to the previous key/value pair.
    47  	// It returns whether the iterator is exhausted.
    48  	Prev() bool
    49  }
    50  
    51  // CommonIterator is the interface that wraps common interator methods.
    52  type CommonIterator interface {
    53  	IteratorSeeker
    54  
    55  	// util.Releaser is the interface that wraps basic Release method.
    56  	// When called Release will releases any resources associated with the
    57  	// iterator.
    58  	util.Releaser
    59  
    60  	// util.ReleaseSetter is the interface that wraps the basic SetReleaser
    61  	// method.
    62  	util.ReleaseSetter
    63  
    64  	// TODO: Remove this when ready.
    65  	Valid() bool
    66  
    67  	// Error returns any accumulated error. Exhausting all the key/value pairs
    68  	// is not considered to be an error.
    69  	Error() error
    70  }
    71  
    72  // Iterator iterates over a DB's key/value pairs in key order.
    73  //
    74  // When encouter an error any 'seeks method' will return false and will
    75  // yield no key/value pairs. The error can be queried by calling the Error
    76  // method. Calling Release is still necessary.
    77  //
    78  // An iterator must be released after use, but it is not necessary to read
    79  // an iterator until exhaustion.
    80  // Also, an iterator is not necessarily goroutine-safe, but it is safe to use
    81  // multiple iterators concurrently, with each in a dedicated goroutine.
    82  type Iterator interface {
    83  	CommonIterator
    84  
    85  	// Key returns the key of the current key/value pair, or nil if done.
    86  	// The caller should not modify the contents of the returned slice, and
    87  	// its contents may change on the next call to any 'seeks method'.
    88  	Key() []byte
    89  
    90  	// Value returns the key of the current key/value pair, or nil if done.
    91  	// The caller should not modify the contents of the returned slice, and
    92  	// its contents may change on the next call to any 'seeks method'.
    93  	Value() []byte
    94  }
    95  
    96  // ErrorCallbackSetter is the interface that wraps basic SetErrorCallback
    97  // method.
    98  //
    99  // ErrorCallbackSetter implemented by indexed and merged iterator.
   100  type ErrorCallbackSetter interface {
   101  	// SetErrorCallback allows set an error callback of the coresponding
   102  	// iterator. Use nil to clear the callback.
   103  	SetErrorCallback(f func(err error))
   104  }
   105  
   106  type emptyIterator struct {
   107  	util.BasicReleaser
   108  	err error
   109  }
   110  
   111  func (i *emptyIterator) rErr() {
   112  	if i.err == nil && i.Released() {
   113  		i.err = ErrIterReleased
   114  	}
   115  }
   116  
   117  func (*emptyIterator) Valid() bool            { return false }
   118  func (i *emptyIterator) First() bool          { i.rErr(); return false }
   119  func (i *emptyIterator) Last() bool           { i.rErr(); return false }
   120  func (i *emptyIterator) Seek(key []byte) bool { i.rErr(); return false }
   121  func (i *emptyIterator) Next() bool           { i.rErr(); return false }
   122  func (i *emptyIterator) Prev() bool           { i.rErr(); return false }
   123  func (*emptyIterator) Key() []byte            { return nil }
   124  func (*emptyIterator) Value() []byte          { return nil }
   125  func (i *emptyIterator) Error() error         { return i.err }
   126  
   127  // NewEmptyIterator creates an empty iterator. The err parameter can be
   128  // nil, but if not nil the given err will be returned by Error method.
   129  func NewEmptyIterator(err error) Iterator {
   130  	return &emptyIterator{err: err}
   131  }