class LMDB::Cursor
A Cursor
points to records in a database, and is used to iterate through the records in the database.
Cursors are created in the context of a transaction, and should only be used as long as that transaction is active. In other words, after you {Transaction#commit} or {Transaction#abort} a transaction, the cursors created while that transaction was active are no longer usable.
To create a cursor, call {Database#cursor} and pass it a block for that should be performed using the cursor.
@example Typical usage
env = LMDB.new "databasedir" db = env.database "databasename" db.cursor do |cursor| rl = cursor.last #=> content of the last record r1 = cursor.first #=> content of the first record r2 = cursor.next #=> content of the second record cursor.put "x", "y", current: true #=> replaces the second record with a new value "y" end
Public Instance Methods
@overload close
Close a cursor. The cursor must not be used again after this call.
static VALUE cursor_close(VALUE self) { CURSOR(self, cursor); mdb_cursor_close(cursor->cur); cursor->cur = 0; return Qnil; }
@overload count
Return count of duplicates for current key. This call is only valid on databases that support sorted duplicate data items +:dupsort+. @return [Number] count of duplicates
static VALUE cursor_count(VALUE self) { CURSOR(self, cursor); size_t count; check(mdb_cursor_count(cursor->cur, &count)); return SIZET2NUM(count); }
@overload cursor_db
@return [Database] the database which this cursor is iterating over.
static VALUE cursor_db(VALUE self) { CURSOR(self, cursor); return cursor->db; }
@overload delete(options)
Delete current key/data pair. This function deletes the key/data pair to which the cursor refers. @option options [Boolean] :nodupdata Delete all of the data items for the current key. This flag may only be specified if the database was opened with +:dupsort+.
static VALUE cursor_delete(int argc, VALUE *argv, VALUE self) { CURSOR(self, cursor); VALUE option_hash; #ifdef RB_SCAN_ARGS_KEYWORDS rb_scan_args_kw(RB_SCAN_ARGS_LAST_HASH_KEYWORDS, argc, argv, ":", &option_hash); #else rb_scan_args(argc, argv, ":", &option_hash); #endif int flags = 0; if (!NIL_P(option_hash)) rb_hash_foreach(option_hash, (int (*)(ANYARGS))cursor_delete_flags, (VALUE)&flags); check(mdb_cursor_del(cursor->cur, flags)); return Qnil; }
@overload first
Position the cursor to the first record in the database, and return its value. @return [Array,nil] The [key, value] pair for the first record, or nil if no record
static VALUE cursor_first(VALUE self) { CURSOR(self, cursor); MDB_val key, value; check(mdb_cursor_get(cursor->cur, &key, &value, MDB_FIRST)); return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size)); }
@overload get
Return the value of the record to which the cursor points. @return [Array] The [key, value] pair for the current record.
static VALUE cursor_get(VALUE self) { CURSOR(self, cursor); MDB_val key, value; int ret = mdb_cursor_get(cursor->cur, &key, &value, MDB_GET_CURRENT); if (ret == MDB_NOTFOUND) return Qnil; check(ret); return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size)); }
@overload last
Position the cursor to the last record in the database, and return its value. @return [Array,nil] The [key, value] pair for the last record, or nil if no record.
static VALUE cursor_last(VALUE self) { CURSOR(self, cursor); MDB_val key, value; check(mdb_cursor_get(cursor->cur, &key, &value, MDB_LAST)); return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size)); }
@overload next nodup = nil
Position the cursor to the next record in the database, and return its value. @param nodup [true, false] If true, skip over duplicate records. @return [Array,nil] The [key, value] pair for the next record, or nil if no next record.
static VALUE cursor_next(int argc, VALUE* argv, VALUE self) { CURSOR(self, cursor); VALUE nodup; MDB_val key, value; MDB_cursor_op op = MDB_NEXT; rb_scan_args(argc, argv, "01", &nodup); if (RTEST(nodup)) op = MDB_NEXT_NODUP; int ret = mdb_cursor_get(cursor->cur, &key, &value, op); if (ret == MDB_NOTFOUND) return Qnil; check(ret); return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size)); }
@overload next_range
Position the cursor to the next record in the database, and return its value if the record's key is less than or equal to the specified key, or nil otherwise. @param key [#to_s] The key to serve as the upper bound @return [Array,nil] The [key, value] pair for the next record, or nil if no next record or the next record is out of the range.
static VALUE cursor_next_range(VALUE self, VALUE upper_bound_key) { CURSOR(self, cursor); MDB_val key, value, ub_key; int ret = mdb_cursor_get(cursor->cur, &key, &value, MDB_NEXT); if (ret == MDB_NOTFOUND) return Qnil; check(ret); ub_key.mv_size = RSTRING_LEN(upper_bound_key); ub_key.mv_data = StringValuePtr(upper_bound_key); MDB_txn* txn = mdb_cursor_txn(cursor->cur); MDB_dbi dbi = mdb_cursor_dbi(cursor->cur); if (mdb_cmp(txn, dbi, &key, &ub_key) <= 0) { return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size)); } else { return Qnil; } }
@overload prev
Position the cursor to the previous record in the database, and return its value. @return [Array,nil] The [key, value] pair for the previous record, or nil if no previous record.
static VALUE cursor_prev(VALUE self) { CURSOR(self, cursor); MDB_val key, value; int ret = mdb_cursor_get(cursor->cur, &key, &value, MDB_PREV); if (ret == MDB_NOTFOUND) return Qnil; check(ret); return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size)); }
@overload put(key, value, options)
Store by cursor. This function stores key/data pairs into the database. If the function fails for any reason, the state of the cursor will be unchanged. If the function succeeds and an item is inserted into the database, the cursor is always positioned to refer to the newly inserted item. @return nil @param key The key of the record to set @param value The value to insert for this key @option options [Boolean] :current Overwrite the data of the key/data pair to which the cursor refers with the specified data item. The +key+ parameter is ignored. @option options [Boolean] :nodupdata Enter the new key/value pair only if it does not already appear in the database. This flag may only be specified if the database was opened with +:dupsort+. The function will raise an {Error} if the key/data pair already appears in the database. @option options [Boolean] :nooverwrite Enter the new key/value pair only if the key does not already appear in the database. The function will raise an {Error] if the key already appears in the database, even if the database supports duplicates (+:dupsort+). @option options [Boolean] :append Append the given key/data pair to the end of the database. No key comparisons are performed. This option allows fast bulk loading when keys are already known to be in the correct order. Loading unsorted keys with this flag will cause data corruption. @option options [Boolean] :appenddup As above, but for sorted dup data.
static VALUE cursor_put(int argc, VALUE* argv, VALUE self) { CURSOR(self, cursor); VALUE vkey, vval, option_hash; #ifdef RB_SCAN_ARGS_KEYWORDS rb_scan_args_kw(RB_SCAN_ARGS_LAST_HASH_KEYWORDS, argc, argv, "2:", &vkey, &vval, &option_hash); #else rb_scan_args(argc, argv, "2:", &vkey, &vval, &option_hash); #endif int flags = 0; if (!NIL_P(option_hash)) rb_hash_foreach(option_hash, (int (*)(ANYARGS))cursor_put_flags, (VALUE)&flags); vkey = StringValue(vkey); vval = StringValue(vval); MDB_val key, value; key.mv_size = RSTRING_LEN(vkey); key.mv_data = RSTRING_PTR(vkey); value.mv_size = RSTRING_LEN(vval); value.mv_data = RSTRING_PTR(vval); check(mdb_cursor_put(cursor->cur, &key, &value, flags)); return Qnil; }
@overload set(key, value = nil)
Set the cursor to a specified key, optionally at the specified value if the database was opened with +:dupsort+. @param key [#to_s] The key to which the cursor should be positioned @param value [nil, #to_s] The optional value (+:dupsort+ only) @return [Array] The +[key, value]+ pair to which the cursor now points.
static VALUE cursor_set(int argc, VALUE* argv, VALUE self) { CURSOR(self, cursor); VALUE vkey, vval; MDB_val key, value; MDB_cursor_op op = MDB_SET_KEY; int ret; rb_scan_args(argc, argv, "11", &vkey, &vval); key.mv_size = RSTRING_LEN(vkey); key.mv_data = StringValuePtr(vkey); if (!NIL_P(vval)) { op = MDB_GET_BOTH; value.mv_size = RSTRING_LEN(vval); value.mv_data = StringValuePtr(vval); } ret = mdb_cursor_get(cursor->cur, &key, &value, op); if (!NIL_P(vval) && ret == MDB_NOTFOUND) return Qnil; check(ret); return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size)); }
@overload set_range
(key)
Set the cursor at the first key greater than or equal to a specified key. @param key The key to which the cursor should be positioned @return [Array] The [key, value] pair to which the cursor now points.
static VALUE cursor_set_range(VALUE self, VALUE vkey) { CURSOR(self, cursor); MDB_val key, value; int ret; key.mv_size = RSTRING_LEN(vkey); key.mv_data = StringValuePtr(vkey); ret = mdb_cursor_get(cursor->cur, &key, &value, MDB_SET_RANGE); /* not sure why we were letting this throw an exception */ if (ret == MDB_NOTFOUND) return Qnil; check(ret); return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size)); }