Class mdbx::cursor

Unmanaged cursor. More...

#include <mdbx.h++>

Inherited by the following classes: mdbx::cursor_managed

Classes

Type	Name
struct	estimate_result The result of a range estimation: the boundary key-value pair plus the approximate number of items.
struct	move_result The result of a cursor move/seek operation: the found key-value pair plus the success flag.

Public Types

Type	Name
enum	bunch_delete Modes for deleting bunches of neighboring items, see MDBX_bunch_action_t() . The EXCLUDING and INCLUDING suffixes mean correspondingly excluding and including deletion items in the current cursor position.
enum	move_operation Cursor positioning operations, mirrors MDBX_cursor_op .

Public Functions

Type	Name
cursor_managed	clone (void * your_context=nullptr) const Creates a new managed cursor with the same position and context.
move_result	current (bool throw_notfound=true) const Read the current key/data item without moving.
constexpr	cursor () noexcept Constructs an empty (null) cursor.
	cursor (const cursor &) noexcept Copy constructor.
	cursor (cursor_managed &&) = delete
ptrdiff_t	distance_from (const cursor from, unsigned deepness=42) const Estimates the distance from the given cursor position to this one.
ptrdiff_t	distance_from_first (unsigned deepness=42) const Estimates the distance from the first item of the table to this cursor position.
ptrdiff_t	distance_to (const cursor to, unsigned deepness=42) const Estimates the distance from this cursor position to the given one.
ptrdiff_t	distance_to_end (unsigned deepness=42) const Estimates the distance from this cursor position to the end of the table.
bool	erase (CHARS key, BOOL whole_multivalue=true) Overloads for C strings, which otherwise bind to the `bool` parameters above.
bool	erase (const slice & key, const char(&) value) Removes the particular multi-value entry given by C string literals.
bool	erase (const char(&) key, const char(&) value) Removes the particular multi-value entry given by C string literals.
bool	fullscan (CALLABLE_PREDICATE predicate, bool backward=false) Scans the whole table calling the predicate until it returns `true` .
move_result	get_multiple_samelength (bool throw_notfound=false) Returns a batch of same-length multi-values at the current key.
const MDBX_cursor *	handle () noexcept const Returns the underlying C handle (read-only).
MDBX_cursor *	handle () noexcept Returns the underlying C handle.
void	insert (const pair & kv) Inserts a new key-value pair; fails if the key already exists.
bool	is_after_than (const cursor & other, bool ignore_nested=false) const Checks whether this cursor is after the given one.
bool	is_before_than (const cursor & other, bool ignore_nested=false) const Checks whether this cursor is before the given one.
bool	is_same_or_after_than (const cursor & other, bool ignore_nested=false) const Checks whether this cursor is at the same position or after the given one.
bool	is_same_or_before_than (const cursor & other, bool ignore_nested=false) const Checks whether this cursor is at the same position or before the given one.
bool	is_same_position (const cursor & other, bool ignore_nested=false) const Checks whether this cursor is at the same position as the given one.
move_result	move (move_operation operation, bool throw_notfound) Performs the given positioning operation.
move_result	move (move_operation operation, const slice & key, bool throw_notfound) Performs the given positioning operation at the specified key.
move_result	move (move_operation operation, const slice & key, const slice & value, bool throw_notfound) Performs the given positioning operation at the specified key-value pair.
move_result	move (move_operation operation, const slice & key, const slice & value) = delete Deleted: `throw_notfound` must be specified explicitly to avoid accidental boolean conversions.
bool	move (move_operation operation, SLICE & key, SLICE & value, bool throw_notfound) Performs the given positioning operation updating the key and value slices.
move_result	next_multiple_samelength (bool throw_notfound=false) Moves to the next key and returns its batch of same-length multi-values.
constexpr	operator MDBX_cursor * () noexcept Returns the underlying C handle.
constexpr	operator const MDBX_cursor * () noexcept const Returns the underlying C handle (read-only).
	map_handle () const Converts the cursor to its table handle.
	txn () const Converts the cursor to its transaction.
cursor &	operator= (const cursor &) noexcept Copy assignment operator.
cursor &	operator= (cursor_managed &&) = delete
move_result	previous_multiple_samelength (bool throw_notfound=false) Moves to the previous key and returns its batch of same-length multi-values.
void	put (const pair & kv, put_mode mode) Stores a key-value pair in the given mode.
size_t	put_multiple_samelength (const slice & key, const VALUE * values_array, size_t values_count, put_mode mode, bool allow_partial=false) Stores a bunch of same-length multi-values for the given key.
void	put_multiple_samelength (const slice & key, const ::std::vector< VALUE > & vector, put_mode mode) Stores a bunch of same-length multi-values for the given key.
slice	reserve_current (size_t value_length) Reserves and returns the space for storing a value associated with a key at the current cursor position.
slice	reverse_current (size_t value_length) Deprecated misspelling of reserve_current() .
bool	scan_until (CALLABLE_PREDICATE predicate, move_operation start=first, move_operation turn=next) Scans items calling the predicate until it returns `true` .
bool	scan_until_from (CALLABLE_PREDICATE predicate, slice & from, move_operation start=key_greater_or_equal, move_operation turn=next) Scans items starting from the given key, calling the predicate until it returns `true` .
bool	scan_until_from (CALLABLE_PREDICATE predicate, pair & from, move_operation start=pair_greater_or_equal, move_operation turn=next) Scans items starting from the given key-value pair, calling the predicate until it returns `true` .
move_result	seek_multiple_samelength (const slice & key, bool throw_notfound=true) Seeks and returns a batch of same-length multi-values of the given key.
move_result	to_current_first_multi (bool throw_notfound=true) Position the cursor at the first multi-value of the current key.
move_result	to_current_last_multi (bool throw_notfound=true) Position the cursor at the last multi-value of the current key.
move_result	to_current_next_multi (bool throw_notfound=true) Position the cursor at the next multi-value of the current key.
move_result	to_current_prev_multi (bool throw_notfound=true) Position the cursor at the previous multi-value of the current key.
move_result	to_exact_key_value_equal (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the exact key and the multi-value equal to the given one.
move_result	to_exact_key_value_greater_or_equal (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the exact key and the multi-value greater than or equal to the given one.
move_result	to_exact_key_value_greater_than (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the exact key and the multi-value greater than the given one.
move_result	to_exact_key_value_lesser_or_equal (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the exact key and the multi-value lesser than or equal to the given one.
move_result	to_exact_key_value_lesser_than (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the exact key and the multi-value lesser than the given one.
move_result	to_first (bool throw_notfound=true) Position the cursor at the first key/data item.
move_result	to_key_equal (const slice & key, bool throw_notfound=true) Position the cursor at the key equal to the given one.
move_result	to_key_exact (const slice & key, bool throw_notfound=true) Position the cursor at the key exactly matching the given one.
move_result	to_key_greater_or_equal (const slice & key, bool throw_notfound=true) Position the cursor at the key greater than or equal to the given one.
move_result	to_key_greater_than (const slice & key, bool throw_notfound=true) Position the cursor at the key greater than the given one.
move_result	to_key_lesser_or_equal (const slice & key, bool throw_notfound=true) Position the cursor at the key lesser than or equal to the given one.
move_result	to_key_lesser_than (const slice & key, bool throw_notfound=true) Position the cursor at the key lesser than the given one.
move_result	to_last (bool throw_notfound=true) Position the cursor at the last key/data item.
move_result	to_next (bool throw_notfound=true) Position the cursor at the next key/data item.
move_result	to_next_first_multi (bool throw_notfound=true) Position the cursor at the first multi-value of the next key.
move_result	to_pair_equal (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the key-value pair equal to the given one.
move_result	to_pair_exact (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the key-value pair exactly matching the given one.
move_result	to_pair_greater_or_equal (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the key-value pair greater than or equal to the given one.
move_result	to_pair_greater_than (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the key-value pair greater than the given one.
move_result	to_pair_lesser_or_equal (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the key-value pair lesser than or equal to the given one.
move_result	to_pair_lesser_than (const slice & key, const slice & value, bool throw_notfound=true) Position the cursor at the key-value pair lesser than the given one.
move_result	to_previous (bool throw_notfound=true) Position the cursor at the previous key/data item.
move_result	to_previous_last_multi (bool throw_notfound=true) Position the cursor at the last multi-value of the previous key.
value_result	try_insert (const pair & kv) Tries to insert a new key-value pair without throwing on a duplicate.
void	update_current (const slice & value) Updates value associated with a key at the current cursor position.
void	upsert (const pair & kv) Inserts or updates the value for the given key.

Protected Attributes

Type	Name
MDBX_cursor *	handle_ = `{nullptr}` The underlying C cursor handle, null for an empty instance.

Detailed Description

Like other unmanaged classes, cursor allows copying and assignment for handles as a values, but does not manage nor destroys the represented underlying object from the own class destructor.

See also: mdbx_cursor_create()

See also: mdbx_cursor_bind()

See also: mdbx_cursor_close()

Public Types Documentation

enum bunch_delete

Modes for deleting bunches of neighboring items, see MDBX_bunch_action_t() . The EXCLUDING and INCLUDING suffixes mean correspondingly excluding and including deletion items in the current cursor position.

enum mdbx::cursor::bunch_delete {
    delete_current_value = MDBX_DELETE_CURRENT_VALUE,
    delete_current_multival_before_excluding = MDBX_DELETE_CURRENT_MULTIVAL_BEFORE_EXCLUDING,
    delete_current_multival_before_including = MDBX_DELETE_CURRENT_MULTIVAL_BEFORE_INCLUDING,
    delete_current_multival_after_including = MDBX_DELETE_CURRENT_MULTIVAL_AFTER_INCLUDING,
    delete_current_multival_after_excluding = MDBX_DELETE_CURRENT_MULTIVAL_AFTER_EXCLUDING,
    delete_current_multival_all = MDBX_DELETE_CURRENT_MULTIVAL_ALL,
    delete_before_excluding = MDBX_DELETE_BEFORE_EXCLUDING,
    delete_before_including = MDBX_DELETE_BEFORE_INCLUDING,
    delete_after_including = MDBX_DELETE_AFTER_INCLUDING,
    delete_after_excluding = MDBX_DELETE_AFTER_EXCLUDING,
    delete_whole = MDBX_DELETE_WHOLE
};

enum move_operation

Cursor positioning operations, mirrors MDBX_cursor_op .

enum mdbx::cursor::move_operation {
    first = MDBX_FIRST,
    last = MDBX_LAST,
    next = MDBX_NEXT,
    previous = MDBX_PREV,
    get_current = MDBX_GET_CURRENT,
    multi_prevkey_lastvalue = MDBX_PREV_NODUP,
    multi_currentkey_firstvalue = MDBX_FIRST_DUP,
    multi_currentkey_prevvalue = MDBX_PREV_DUP,
    multi_currentkey_nextvalue = MDBX_NEXT_DUP,
    multi_currentkey_lastvalue = MDBX_LAST_DUP,
    multi_nextkey_firstvalue = MDBX_NEXT_NODUP,
    multi_find_pair = MDBX_GET_BOTH,
    multi_exactkey_lowerboundvalue = MDBX_GET_BOTH_RANGE,
    seek_key = MDBX_SET,
    key_exact = MDBX_SET_KEY,
    key_lowerbound = MDBX_SET_RANGE,
    key_lesser_than = MDBX_TO_KEY_LESSER_THAN,
    key_lesser_or_equal = MDBX_TO_KEY_LESSER_OR_EQUAL,
    key_equal = MDBX_TO_KEY_EQUAL,
    key_greater_or_equal = MDBX_TO_KEY_GREATER_OR_EQUAL,
    key_greater_than = MDBX_TO_KEY_GREATER_THAN,
    multi_exactkey_value_lesser_than = MDBX_TO_EXACT_KEY_VALUE_LESSER_THAN,
    multi_exactkey_value_lesser_or_equal = MDBX_TO_EXACT_KEY_VALUE_LESSER_OR_EQUAL,
    multi_exactkey_value_equal = MDBX_TO_EXACT_KEY_VALUE_EQUAL,
    multi_exactkey_value_greater_or_equal = MDBX_TO_EXACT_KEY_VALUE_GREATER_OR_EQUAL,
    multi_exactkey_value_greater = MDBX_TO_EXACT_KEY_VALUE_GREATER_THAN,
    pair_lesser_than = MDBX_TO_PAIR_LESSER_THAN,
    pair_lesser_or_equal = MDBX_TO_PAIR_LESSER_OR_EQUAL,
    pair_equal = MDBX_TO_PAIR_EQUAL,
    pair_exact = pair_equal,
    pair_greater_or_equal = MDBX_TO_PAIR_GREATER_OR_EQUAL,
    pair_greater_than = MDBX_TO_PAIR_GREATER_THAN,
    batch_samelength = MDBX_GET_MULTIPLE,
    batch_samelength_next = MDBX_NEXT_MULTIPLE,
    batch_samelength_previous = MDBX_PREV_MULTIPLE,
    seek_and_batch_samelength = MDBX_SEEK_AND_GET_MULTIPLE
};

Public Functions Documentation

function clone

Creates a new managed cursor with the same position and context.

cursor_managed mdbx::cursor::clone (
    void * your_context=nullptr
) const

Parameters:

your_context An application context to be associated with the clone.

Returns:

The new cursor_managed instance.

Exception:

mdbx::error on failure.

function current

Read the current key/data item without moving.

inline move_result mdbx::cursor::current (
    bool throw_notfound=true
) const

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function cursor [1/3]

Constructs an empty (null) cursor.

constexpr mdbx::cursor::cursor () noexcept

function cursor [2/3]

Copy constructor.

mdbx::cursor::cursor (
    const cursor &
) noexcept

function cursor [3/3]

mdbx::cursor::cursor (
    cursor_managed &&
) = delete

function distance_from

Estimates the distance from the given cursor position to this one.

inline ptrdiff_t mdbx::cursor::distance_from (
    const cursor from,
    unsigned deepness=42
) const

Parameters:

from The cursor at the "from" position, null means the table start.
deepness The maximum depth of the B+tree inspection.

Returns:

The approximate distance.

function distance_from_first

Estimates the distance from the first item of the table to this cursor position.

inline ptrdiff_t mdbx::cursor::distance_from_first (
    unsigned deepness=42
) const

Parameters:

deepness The maximum depth of the B+tree inspection.

Returns:

The approximate distance.

function distance_to

Estimates the distance from this cursor position to the given one.

inline ptrdiff_t mdbx::cursor::distance_to (
    const cursor to,
    unsigned deepness=42
) const

Parameters:

to The cursor at the "to" position, null means the table end.
deepness The maximum depth of the B+tree inspection.

Returns:

The approximate distance.

function distance_to_end

Estimates the distance from this cursor position to the end of the table.

inline ptrdiff_t mdbx::cursor::distance_to_end (
    unsigned deepness=42
) const

Parameters:

deepness The maximum depth of the B+tree inspection.

Returns:

The approximate distance.

function erase [1/3]

Overloads for C strings, which otherwise bind to the bool parameters above.

template<typename CHARS, typename BOOL, typename std::enable_if<(std::is_same< CHARS, const char * >::value||std::is_same< CHARS, char * >::value) &&std::is_same< BOOL, bool >::value, int >::type>
inline bool mdbx::cursor::erase (
    CHARS key,
    BOOL whole_multivalue=true
)

Parameters:

key The key to remove.
whole_multivalue Remove all multi-values of the key.

Returns:

true if the key was found and removed.

function erase [2/3]

Removes the particular multi-value entry given by C string literals.

template<size_t SIZE>
inline bool mdbx::cursor::erase (
    const slice & key,
    const char(&) value
)

Parameters:

key The key of the entry.
value The multi-value to remove.

Returns:

true if the key-value pair was found and removed.

function erase [3/3]

Removes the particular multi-value entry given by C string literals.

template<size_t KEY_SIZE, size_t VALUE_SIZE>
inline bool mdbx::cursor::erase (
    const char(&) key,
    const char(&) value
)

Parameters:

key The key of the entry.
value The multi-value to remove.

Returns:

true if the key-value pair was found and removed.

function fullscan

Scans the whole table calling the predicate until it returns true .

template<typename CALLABLE_PREDICATE>
inline bool mdbx::cursor::fullscan (
    CALLABLE_PREDICATE predicate,
    bool backward=false
)

Parameters:

predicate The callable invoked for each key-value pair; returning true stops the scan.
backward Scan in the reverse order.

Returns:

true if the predicate returned true for some item.

Exception:

The captured predicate exception, if any.

function get_multiple_samelength

Returns a batch of same-length multi-values at the current key.

inline move_result mdbx::cursor::get_multiple_samelength (
    bool throw_notfound=false
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the batch and the success flag.

function handle [1/2]

Returns the underlying C handle (read-only).

inline const MDBX_cursor * mdbx::cursor::handle () noexcept const

Returns:

The constant pointer to the MDBX_cursor object.

function handle [2/2]

Returns the underlying C handle.

inline MDBX_cursor * mdbx::cursor::handle () noexcept

Returns:

The mutable pointer to the MDBX_cursor object.

function insert

Inserts a new key-value pair; fails if the key already exists.

inline void mdbx::cursor::insert (
    const pair & kv
)

Parameters:

kv The key-value pair to insert.

function is_after_than

Checks whether this cursor is after the given one.

inline bool mdbx::cursor::is_after_than (
    const cursor & other,
    bool ignore_nested=false
) const

Parameters:

other The cursor to compare the position with.
ignore_nested Ignore the position within a nested (dupsort) tree.

Returns:

true if this cursor position is greater than the other one.

Exception:

std::logic_error if the cursors are incomparable.

function is_before_than

Checks whether this cursor is before the given one.

inline bool mdbx::cursor::is_before_than (
    const cursor & other,
    bool ignore_nested=false
) const

Parameters:

other The cursor to compare the position with.
ignore_nested Ignore the position within a nested (dupsort) tree.

Returns:

true if this cursor position is less than the other one.

Exception:

std::logic_error if the cursors are incomparable.

function is_same_or_after_than

Checks whether this cursor is at the same position or after the given one.

inline bool mdbx::cursor::is_same_or_after_than (
    const cursor & other,
    bool ignore_nested=false
) const

Parameters:

other The cursor to compare the position with.
ignore_nested Ignore the position within a nested (dupsort) tree.

Returns:

true if this cursor position is greater than or equal to the other one.

Exception:

std::logic_error if the cursors are incomparable.

function is_same_or_before_than

Checks whether this cursor is at the same position or before the given one.

inline bool mdbx::cursor::is_same_or_before_than (
    const cursor & other,
    bool ignore_nested=false
) const

Parameters:

other The cursor to compare the position with.
ignore_nested Ignore the position within a nested (dupsort) tree.

Returns:

true if this cursor position is less than or equal to the other one.

Exception:

std::logic_error if the cursors are incomparable.

function is_same_position

Checks whether this cursor is at the same position as the given one.

inline bool mdbx::cursor::is_same_position (
    const cursor & other,
    bool ignore_nested=false
) const

Parameters:

other The cursor to compare the position with.
ignore_nested Ignore the position within a nested (dupsort) tree.

Returns:

true if this cursor position is equal to the other one.

Exception:

std::logic_error if the cursors are incomparable.

function move [1/5]

Performs the given positioning operation.

inline move_result mdbx::cursor::move (
    move_operation operation,
    bool throw_notfound
)

Parameters:

operation The positioning operation.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function move [2/5]

Performs the given positioning operation at the specified key.

inline move_result mdbx::cursor::move (
    move_operation operation,
    const slice & key,
    bool throw_notfound
)

Parameters:

operation The positioning operation.
key The key to position at.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function move [3/5]

Performs the given positioning operation at the specified key-value pair.

inline move_result mdbx::cursor::move (
    move_operation operation,
    const slice & key,
    const slice & value,
    bool throw_notfound
)

Parameters:

operation The positioning operation.
key The key to position at.
value The value to position at (for dupsort tables).
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function move [4/5]

Deleted: throw_notfound must be specified explicitly to avoid accidental boolean conversions.

move_result mdbx::cursor::move (
    move_operation operation,
    const slice & key,
    const slice & value
) = delete

function move [5/5]

Performs the given positioning operation updating the key and value slices.

template<class SLICE, typename ::std::enable_if<::std::is_same< SLICE, slice >::value, int >::type>
inline bool mdbx::cursor::move (
    move_operation operation,
    SLICE & key,
    SLICE & value,
    bool throw_notfound
)

Parameters:

operation The positioning operation.
key The key slice to be updated with the found key.
value The value slice to be updated with the found value.
throw_notfound Throw mdbx::not_found instead of returning false.

Returns:

true if the cursor was positioned successfully.

function next_multiple_samelength

Moves to the next key and returns its batch of same-length multi-values.

inline move_result mdbx::cursor::next_multiple_samelength (
    bool throw_notfound=false
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the batch and the success flag.

function operator MDBX_cursor *

Returns the underlying C handle.

inline constexpr mdbx::cursor::operator MDBX_cursor * () noexcept

Returns:

The mutable pointer to the MDBX_cursor object.

function operator const MDBX_cursor *

Returns the underlying C handle (read-only).

inline constexpr mdbx::cursor::operator const MDBX_cursor * () noexcept const

Returns:

The constant pointer to the MDBX_cursor object.

function map_handle

Converts the cursor to its table handle.

inline mdbx::cursor::map_handle () const

Returns:

The map_handle the cursor is associated with.

function txn

Converts the cursor to its transaction.

inline mdbx::cursor::txn () const

Returns:

The transaction the cursor belongs to.

function operator=

Copy assignment operator.

cursor & mdbx::cursor::operator= (
    const cursor &
) noexcept

Returns:

A reference to this instance.

function operator=

cursor & mdbx::cursor::operator= (
    cursor_managed &&
) = delete

function previous_multiple_samelength

Moves to the previous key and returns its batch of same-length multi-values.

inline move_result mdbx::cursor::previous_multiple_samelength (
    bool throw_notfound=false
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the batch and the success flag.

function put

Stores a key-value pair in the given mode.

inline void mdbx::cursor::put (
    const pair & kv,
    put_mode mode
)

Parameters:

kv The key-value pair.
mode The put_mode (insert/upsert/update).

function put_multiple_samelength [1/2]

Stores a bunch of same-length multi-values for the given key.

template<typename VALUE>
inline size_t mdbx::cursor::put_multiple_samelength (
    const slice & key,
    const VALUE * values_array,
    size_t values_count,
    put_mode mode,
    bool allow_partial=false
)

Parameters:

key The key of the multi-value hive.
values_array The array of standard-layout values.
values_count The number of values in the array.
mode The put_mode.
allow_partial Allow partial store when some values are rejected.

Returns:

The number of stored values.

function put_multiple_samelength [2/2]

Stores a bunch of same-length multi-values for the given key.

template<typename VALUE>
inline void mdbx::cursor::put_multiple_samelength (
    const slice & key,
    const ::std::vector< VALUE > & vector,
    put_mode mode
)

Parameters:

key The key of the multi-value hive.
vector The vector of standard-layout values.
mode The put_mode.

function reserve_current

Reserves and returns the space for storing a value associated with a key at the current cursor position.

slice mdbx::cursor::reserve_current (
    size_t value_length
)

Parameters:

value_length The length of the value to reserve.

Returns:

The writable slice for the reserved value.

function reverse_current

Deprecated misspelling of reserve_current() .

inline slice mdbx::cursor::reverse_current (
    size_t value_length
)

Parameters:

value_length The length of the value to reserve.

Returns:

The writable slice for the reserved value.

function scan_until

Scans items calling the predicate until it returns true .

template<typename CALLABLE_PREDICATE>
inline bool mdbx::cursor::scan_until (
    CALLABLE_PREDICATE predicate,
    move_operation start=first,
    move_operation turn=next
)

Parameters:

predicate The callable invoked for each key-value pair; returning true stops the scan.
start The initial positioning operation.
turn The operation for each next step.

Returns:

true if the predicate returned true for some item.

Exception:

The captured predicate exception, if any.

function scan_until_from [1/2]

Scans items starting from the given key, calling the predicate until it returns true .

template<typename CALLABLE_PREDICATE>
inline bool mdbx::cursor::scan_until_from (
    CALLABLE_PREDICATE predicate,
    slice & from,
    move_operation start=key_greater_or_equal,
    move_operation turn=next
)

Parameters:

predicate The callable invoked for each key-value pair; returning true stops the scan.
from The starting key; updated to the position where the scan stopped.
start The initial positioning operation.
turn The operation for each next step.

Returns:

true if the predicate returned true for some item.

Exception:

The captured predicate exception, if any.

function scan_until_from [2/2]

Scans items starting from the given key-value pair, calling the predicate until it returns true .

template<typename CALLABLE_PREDICATE>
inline bool mdbx::cursor::scan_until_from (
    CALLABLE_PREDICATE predicate,
    pair & from,
    move_operation start=pair_greater_or_equal,
    move_operation turn=next
)

Parameters:

predicate The callable invoked for each key-value pair; returning true stops the scan.
from The starting pair; updated to the position where the scan stopped.
start The initial positioning operation.
turn The operation for each next step.

Returns:

true if the predicate returned true for some item.

Exception:

The captured predicate exception, if any.

function seek_multiple_samelength

Seeks and returns a batch of same-length multi-values of the given key.

inline move_result mdbx::cursor::seek_multiple_samelength (
    const slice & key,
    bool throw_notfound=true
)

Parameters:

key The key of the multi-value hive.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the batch and the success flag.

function to_current_first_multi

Position the cursor at the first multi-value of the current key.

inline move_result mdbx::cursor::to_current_first_multi (
    bool throw_notfound=true
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_current_last_multi

Position the cursor at the last multi-value of the current key.

inline move_result mdbx::cursor::to_current_last_multi (
    bool throw_notfound=true
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_current_next_multi

Position the cursor at the next multi-value of the current key.

inline move_result mdbx::cursor::to_current_next_multi (
    bool throw_notfound=true
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_current_prev_multi

Position the cursor at the previous multi-value of the current key.

inline move_result mdbx::cursor::to_current_prev_multi (
    bool throw_notfound=true
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_exact_key_value_equal

Position the cursor at the exact key and the multi-value equal to the given one.

inline move_result mdbx::cursor::to_exact_key_value_equal (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The exact key to position at.
value The multi-value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_exact_key_value_greater_or_equal

Position the cursor at the exact key and the multi-value greater than or equal to the given one.

inline move_result mdbx::cursor::to_exact_key_value_greater_or_equal (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The exact key to position at.
value The multi-value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_exact_key_value_greater_than

Position the cursor at the exact key and the multi-value greater than the given one.

inline move_result mdbx::cursor::to_exact_key_value_greater_than (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The exact key to position at.
value The multi-value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_exact_key_value_lesser_or_equal

Position the cursor at the exact key and the multi-value lesser than or equal to the given one.

inline move_result mdbx::cursor::to_exact_key_value_lesser_or_equal (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The exact key to position at.
value The multi-value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_exact_key_value_lesser_than

Position the cursor at the exact key and the multi-value lesser than the given one.

inline move_result mdbx::cursor::to_exact_key_value_lesser_than (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The exact key to position at.
value The multi-value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_first

Position the cursor at the first key/data item.

inline move_result mdbx::cursor::to_first (
    bool throw_notfound=true
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_key_equal

Position the cursor at the key equal to the given one.

inline move_result mdbx::cursor::to_key_equal (
    const slice & key,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_key_exact

Position the cursor at the key exactly matching the given one.

inline move_result mdbx::cursor::to_key_exact (
    const slice & key,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_key_greater_or_equal

Position the cursor at the key greater than or equal to the given one.

inline move_result mdbx::cursor::to_key_greater_or_equal (
    const slice & key,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_key_greater_than

Position the cursor at the key greater than the given one.

inline move_result mdbx::cursor::to_key_greater_than (
    const slice & key,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_key_lesser_or_equal

Position the cursor at the key lesser than or equal to the given one.

inline move_result mdbx::cursor::to_key_lesser_or_equal (
    const slice & key,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_key_lesser_than

Position the cursor at the key lesser than the given one.

inline move_result mdbx::cursor::to_key_lesser_than (
    const slice & key,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_last

Position the cursor at the last key/data item.

inline move_result mdbx::cursor::to_last (
    bool throw_notfound=true
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_next

Position the cursor at the next key/data item.

inline move_result mdbx::cursor::to_next (
    bool throw_notfound=true
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_next_first_multi

Position the cursor at the first multi-value of the next key.

inline move_result mdbx::cursor::to_next_first_multi (
    bool throw_notfound=true
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_pair_equal

Position the cursor at the key-value pair equal to the given one.

inline move_result mdbx::cursor::to_pair_equal (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
value The value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_pair_exact

Position the cursor at the key-value pair exactly matching the given one.

inline move_result mdbx::cursor::to_pair_exact (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
value The value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_pair_greater_or_equal

Position the cursor at the key-value pair greater than or equal to the given one.

inline move_result mdbx::cursor::to_pair_greater_or_equal (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
value The value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_pair_greater_than

Position the cursor at the key-value pair greater than the given one.

inline move_result mdbx::cursor::to_pair_greater_than (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
value The value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_pair_lesser_or_equal

Position the cursor at the key-value pair lesser than or equal to the given one.

inline move_result mdbx::cursor::to_pair_lesser_or_equal (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
value The value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_pair_lesser_than

Position the cursor at the key-value pair lesser than the given one.

inline move_result mdbx::cursor::to_pair_lesser_than (
    const slice & key,
    const slice & value,
    bool throw_notfound=true
)

Parameters:

key The key to position against.
value The value to position against.
throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_previous

Position the cursor at the previous key/data item.

inline move_result mdbx::cursor::to_previous (
    bool throw_notfound=true
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function to_previous_last_multi

Position the cursor at the last multi-value of the previous key.

inline move_result mdbx::cursor::to_previous_last_multi (
    bool throw_notfound=true
)

Parameters:

throw_notfound Throw mdbx::not_found instead of returning an unsuccessful result.

Returns:

The move_result with the found pair and the success flag.

function try_insert

Tries to insert a new key-value pair without throwing on a duplicate.

inline value_result mdbx::cursor::try_insert (
    const pair & kv
)

Parameters:

kv The key-value pair to insert.

Returns:

The value_result with the success flag.

function update_current

Updates value associated with a key at the current cursor position.

void mdbx::cursor::update_current (
    const slice & value
)

Parameters:

value The new value.

function upsert

Inserts or updates the value for the given key.

inline void mdbx::cursor::upsert (
    const pair & kv
)

Parameters:

kv The key-value pair to store.

Protected Attributes Documentation

variable handle_

The underlying C cursor handle, null for an empty instance.

MDBX_cursor* mdbx::cursor::handle_;

Friends Documentation

friend compare_position

Compares the positions of two cursors.

inline int mdbx::cursor::compare_position (
    const cursor & left,
    const cursor & right,
    bool ignore_nested=false
)

Parameters:

left The left-hand cursor.
right The right-hand cursor.
ignore_nested Ignore the position within a nested (dupsort) tree.

Returns:

A negative value if left is before right, a positive value if after, zero if at the same position.

Exception:

std::logic_error if the cursors are incomparable.

friend compare_position_nothrow

Compares the positions of two cursors without throwing.

inline int mdbx::cursor::compare_position_nothrow (
    const cursor & left,
    const cursor & right,
    bool ignore_nested=false
)

Parameters:

left The left-hand cursor.
right The right-hand cursor.
ignore_nested Ignore the position within a nested (dupsort) tree.

Returns:

A negative value if left is before right, a positive value if after, zero if at the same position, or MDBX_RESULT_TRUE when the cursors are incomparable.

friend operator!=

inline bool mdbx::cursor::operator!= (
    const cursor & a,
    const cursor & b
) noexcept

friend operator==

inline bool mdbx::cursor::operator== (
    const cursor & a,
    const cursor & b
) noexcept

The documentation for this class was generated from the following file mdbx.h++