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

close() click to toggle source

@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;
}
count() click to toggle source

@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);
}
database() click to toggle source

@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;
}
delete(p1 = {}) click to toggle source

@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;
}
first() click to toggle source

@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));
}
get() click to toggle source

@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));
}
last() click to toggle source

@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));
}
next(p1 = v1) click to toggle source

@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));
}
next_range(p1) click to toggle source

@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;
        }
}
prev() click to toggle source

@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));
}
put(p1, p2, p3 = {}) click to toggle source

@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;
}
set(p1, p2 = v2) click to toggle source

@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));
}
set_range(p1) click to toggle source

@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));
}