```{index} single: Peta::LMDB::Cursor ``` # Peta::LMDB::Cursor ```{pperl-module-badges} Peta::LMDB::Cursor ``` 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: ```perl 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`.