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.



1166
1167
1168
1169
1170
1171
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1166

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



1541
1542
1543
1544
1545
1546
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1541

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.



1529
1530
1531
1532
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1529

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.



1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1505

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



1247
1248
1249
1250
1251
1252
1253
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1247

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.



1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1414

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.



1262
1263
1264
1265
1266
1267
1268
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1262

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(nodup = nil) ⇒ Array?

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

Parameters:

  • nodup (true, false) (defaults to: nil) —

    If true, skip over duplicate records.

Returns:

  • (Array, nil) —

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



1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1296

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

Parameters:

  • key (#to_s) —

    The key to serve as the upper bound

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.



1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1324

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.



1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1277

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



1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1462

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(key, value = nil) ⇒ Array

Set the cursor to a specified key, optionally at the specified value if the database was opened with :dupsort.

Parameters:

  • key (#to_s) —

    The key to which the cursor should be positioned

  • value (nil, #to_s) (defaults to: nil) —

    The optional value (:dupsort only)

Returns:

  • (Array) —

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



1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1354

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



1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1389

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