Peta::LMDB::Cursor

📦 std

A cursor: a position in a database that walks its keys in order, finds the first key at or after a given one, and writes or deletes where it stands.

$txn->cursor($db) opens one. Every move returns the key and value it lands on as a two-element list, or an empty list when there is nothing there, so a loop reads naturally:

my $c = $txn->cursor($db);
while (my ($k, $v) = $c->next) { print "$k=$v\n" }

A new cursor stands nowhere: next starts at the first key, prev at the last. In an MDB_DUPSORT database the cursor visits every value of a key; the _dup moves stay within the current key and the _nodup moves skip to the next key.

A cursor ends with its transaction. A read transaction’s cursor can move on to another read transaction with renew.

Functions

Moving

get

Move the cursor by any of LMDB’s cursor operations: $c->get($op), $c->get($op, $key), $c->get($op, $key, $value), with $op an MDB_* constant of the :cursor_ops tag (MDB_SET_RANGE and the like). The key and value it lands on, or an empty list. The named moves below do the same more readably.

first

To the first key (and its first value): ($k, $v) = $c->first.

last

To the last key (and its last value).

next

To the next item - the next value of the key in an MDB_DUPSORT database, else the next key; from a new cursor, the first. An empty list after the last.

prev

To the previous item; from a new cursor, the last. An empty list before the first.

first_dup

To the current key’s first value (MDB_DUPSORT databases).

last_dup

To the current key’s last value (MDB_DUPSORT databases).

next_dup

To the current key’s next value; an empty list after its last (MDB_DUPSORT databases).

prev_dup

To the current key’s previous value; an empty list before its first (MDB_DUPSORT databases).

next_nodup

To the first value of the next key, skipping the current key’s other values.

prev_nodup

To the last value of the previous key.

current

The key and value the cursor stands on, without moving.

set

To the key itself: ($k, $v) = $c->set($key). An empty list when the key is not stored.

set_range

To the first key at or after the one given, in the database’s order: ($k, $v) = $c->set_range('ab') finds ab, or the first key after it - the start of a range or prefix walk. An empty list when no key follows.

get_both

To a key holding a given value: $c->get_both($key, $value) (MDB_DUPSORT databases). An empty list when the key does not hold it.

get_both_range

To a key’s first value at or after the one given: $c->get_both_range($key, $value) (MDB_DUPSORT databases).

count

How many values the current key holds (MDB_DUPSORT databases).

Writing

put

Store a key and value and leave the cursor on them: $c->put($key, $value). $c->put($key, $value, MDB_CURRENT) replaces the value the cursor stands on (the key must be the cursor’s). The flags MDB_NOOVERWRITE, MDB_NODUPDATA, MDB_APPEND and MDB_APPENDDUP work as for $txn->put. True when stored, false when MDB_NOOVERWRITE or MDB_NODUPDATA refused. MDB_RESERVE and MDB_MULTIPLE croak.

del

Delete the item the cursor stands on: $c->del. In an MDB_DUPSORT database, $c->del(MDB_NODUPDATA) deletes all the key’s values. The next next returns the item after the deleted one.

Ending

renew

Move a read transaction’s cursor to another read transaction: $c->renew($txn), cheaper than opening a new cursor. It then stands nowhere. A write transaction croaks renew needs a read transaction.

close

Close the cursor now, rather than when it goes out of scope or its transaction ends. Using it afterwards croaks the cursor is closed or its transaction has ended.