Database.LevelDB.Iterator

Iterating over key ranges.

Documentation

data Iterator

Iterator handle

Note that an Iterator requires external synchronization if it is shared between multiple threads which mutate it's state. See examples/iterforkio.hs for a simple example of how to do that.

Instances

Eq Iterator

createIter :: MonadIO m => DB -> ReadOptions -> m Iterator

Create an Iterator.

The iterator should be released with releaseIter.

Note that an Iterator creates a snapshot of the database implicitly, so updates written after the iterator was created are not visible. You may, however, specify an older Snapshot in the ReadOptions.

iterEntry :: MonadIO m => Iterator -> m (Maybe (ByteString, ByteString))

Return the current entry as a pair, if the iterator is currently positioned at an entry, ie. iterValid.

iterFirst :: MonadIO m => Iterator -> m ()

Position at the first key in the source. The iterator is valid after this call iff the source is not empty.

iterGetError :: MonadIO m => Iterator -> m (Maybe ByteString)

Check for errors

Note that this captures somewhat severe errors such as a corrupted database.

iterItems :: (Functor m, MonadIO m) => Iterator -> m [(ByteString, ByteString)]

Return a list of key and value tuples from an iterator. The iterator should be put in the right position prior to calling this with the iterator.

See strictness remarks on mapIter.

iterKey :: MonadIO m => Iterator -> m (Maybe ByteString)

Return the key for the current entry if the iterator is currently positioned at an entry, ie. iterValid.

iterKeys :: (Functor m, MonadIO m) => Iterator -> m [ByteString]

Return a list of key from an iterator. The iterator should be put in the right position prior to calling this with the iterator.

See strictness remarks on mapIter

iterLast :: MonadIO m => Iterator -> m ()

Position at the last key in the source. The iterator is valid after this call iff the source is not empty.

iterNext :: MonadIO m => Iterator -> m ()

Moves to the next entry in the source. After this call, iterValid is true iff the iterator was not positioned at the last entry in the source.

If the iterator is not valid, this function does nothing. Note that this is a shortcoming of the C API: an iterPrev might still be possible, but we can't determine if we're at the last or first entry.

iterPrev :: MonadIO m => Iterator -> m ()

Moves to the previous entry in the source. After this call, iterValid is true iff the iterator was not positioned at the first entry in the source.

If the iterator is not valid, this function does nothing. Note that this is a shortcoming of the C API: an iterNext might still be possible, but we can't determine if we're at the last or first entry.

iterSeek :: MonadIO m => Iterator -> ByteString -> m ()

Position at the first key in the source that is at or past target. The iterator is valid after this call iff the source contains an entry that comes at or past target.

iterValid :: MonadIO m => Iterator -> m Bool

An iterator is either positioned at a key/value pair, or not valid. This function returns true iff the iterator is valid.

iterValue :: MonadIO m => Iterator -> m (Maybe ByteString)

Return the value for the current entry if the iterator is currently positioned at an entry, ie. iterValid.

iterValues :: (Functor m, MonadIO m) => Iterator -> m [ByteString]

Return a list of values from an iterator. The iterator should be put in the right position prior to calling this with the iterator.

See strictness remarks on mapIter

mapIter :: MonadIO m => (Iterator -> m a) -> Iterator -> m [a]

Map a function over an iterator, advancing the iterator forward and returning the value. The iterator should be put in the right position prior to calling the function.

Note that this function accumulates the result strictly, ie. it reads all values into memory until the iterator is exhausted. This is most likely not what you want for large ranges. You may consider using conduits instead, for an example see: https://gist.github.com/adc8ec348f03483446a5

releaseIter :: MonadIO m => Iterator -> m ()

Release an Iterator.

The handle will be invalid after calling this action and should no longer be used. Calling this function with an already released Iterator will cause a double-free error!

withIter :: MonadIO m => DB -> ReadOptions -> (Iterator -> IO a) -> m a

Run an action with an Iterator