Class: LMDB::Cursor

Inherits:
Object
  • Object
show all
Defined in:
ext/lmdb_ext/lmdb_ext.c,
ext/lmdb_ext/lmdb_ext.c

Overview

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.

Examples:

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

Instance Method Summary collapse

Instance Method Details

#close ⇒ Object

Close a cursor. The cursor must not be used again after this call.



962
963
964
965
966
967
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 962

static VALUE cursor_close(VALUE self) {
        CURSOR(self, cursor);
        mdb_cursor_close(cursor->cur);
        cursor->cur = 0;
        return Qnil;
}

#count ⇒ Number

Return count of duplicates for current key. This call is only valid on databases that support sorted duplicate data items :dupsort.

Returns:

  • (Number) —

    count of duplicates



1287
1288
1289
1290
1291
1292
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1287

static VALUE cursor_count(VALUE self) {
        CURSOR(self, cursor);
        size_t count;
        check(mdb_cursor_count(cursor->cur, &count));
        return SIZET2NUM(count);
}

#cursor_db ⇒ Database

Returns the database which this cursor is iterating over.

Returns:

  • (Database) —

    the database which this cursor is iterating over.



1275
1276
1277
1278
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1275

static VALUE cursor_db(VALUE self) {
        CURSOR(self, cursor);
        return cursor->db;
}

#delete(options) ⇒ Object

Delete current key/data pair. This function deletes the key/data pair to which the cursor refers.

Options Hash (options):

  • :nodupdata (Boolean) —

    Delete all of the data items for the current key. This flag may only be specified if the database was opened with :dupsort.



1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1257

static VALUE cursor_delete(int argc, VALUE *argv, VALUE self) {
        CURSOR(self, cursor);

        VALUE option_hash;
        rb_scan_args(argc, argv, ":", &option_hash);

        int flags = 0;
        if (!NIL_P(option_hash))
                rb_hash_foreach(option_hash, cursor_delete_flags, (VALUE)&flags);

        check(mdb_cursor_del(cursor->cur, flags));
        return Qnil;
}

#first ⇒ Array?

Position the cursor to the first record in the database, and return its value.

Returns:

  • (Array, nil) —

    The [key, value] pair for the first record, or nil if no record



1043
1044
1045
1046
1047
1048
1049
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1043

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 ⇒ Array

Return the value of the record to which the cursor points.

Returns:

  • (Array) —

    The [key, value] pair for the current record.



1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1172

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 ⇒ Array?

Position the cursor to the last record in the database, and return its value.

Returns:

  • (Array, nil) —

    The [key, value] pair for the last record, or nil if no record.



1058
1059
1060
1061
1062
1063
1064
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1058

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 ⇒ Array?

Position the cursor to the next record in the database, and return its value.

Returns:

  • (Array, nil) —

    The [key, value] pair for the next record, or nil if no next record.



1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1091

static VALUE cursor_next(VALUE self) {
        CURSOR(self, cursor);
        MDB_val key, value;

        int ret = mdb_cursor_get(cursor->cur, &key, &value, MDB_NEXT);
        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 ⇒ Array?

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.

Returns:

  • (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.



1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1110

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 ⇒ Array?

Position the cursor to the previous record in the database, and return its value.

Returns:

  • (Array, nil) —

    The [key, value] pair for the previous record, or nil if no previous record.



1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1073

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(key, value, options) ⇒ Object

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.

Parameters:

  • key —

    The key of the record to set

  • value —

    The value to insert for this key

Options Hash (options):

  • :current (Boolean) —

    Overwrite the data of the key/data pair to which the cursor refers with the specified data item. The key parameter is ignored.

  • :nodupdata (Boolean) —

    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.

  • :nooverwrite (Boolean) —

    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).

  • :append (Boolean) —

    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.

  • :appenddup (Boolean) —

    As above, but for sorted dup data.

Returns:

  • nil



1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1220

static VALUE cursor_put(int argc, VALUE* argv, VALUE self) {
        CURSOR(self, cursor);

        VALUE vkey, vval, option_hash;
        rb_scan_args(argc, argv, "2:", &vkey, &vval, &option_hash);

        int flags = 0;
        if (!NIL_P(option_hash))
                rb_hash_foreach(option_hash, 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(key) ⇒ Array

Set the cursor to a specified key

Parameters:

  • key —

    The key to which the cursor should be positioned

Returns:

  • (Array) —

    The [key, value] pair to which the cursor now points.



1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1138

static VALUE cursor_set(VALUE self, VALUE vkey) {
        CURSOR(self, cursor);
        MDB_val key, value;

        key.mv_size = RSTRING_LEN(vkey);
        key.mv_data = StringValuePtr(vkey);

        check(mdb_cursor_get(cursor->cur, &key, &value, MDB_SET_KEY));
        return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size));
}

#set_range(key) ⇒ Array

Set the cursor at the first key greater than or equal to a specified key.

Parameters:

  • key —

    The key to which the cursor should be positioned

Returns:

  • (Array) —

    The [key, value] pair to which the cursor now points.



1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1155

static VALUE cursor_set_range(VALUE self, VALUE vkey) {
        CURSOR(self, cursor);
        MDB_val key, value;

        key.mv_size = RSTRING_LEN(vkey);
        key.mv_data = StringValuePtr(vkey);

        check(mdb_cursor_get(cursor->cur, &key, &value, MDB_SET_RANGE));
        return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size));
}