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.



1233
1234
1235
1236
1237
1238
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1233

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



1622
1623
1624
1625
1626
1627
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1622

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.



1610
1611
1612
1613
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1610

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.



1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1586

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



1314
1315
1316
1317
1318
1319
1320
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1314

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.



1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1495

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.



1329
1330
1331
1332
1333
1334
1335
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1329

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.



1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1363

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.



1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1391

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.



1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1344

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



1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1543

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.



1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1422

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

         /*
           XXX TODO: this was a nasty segfault: the key (and any
           non-nil value) should be asserted to be strings, but then
           if the database is `integerkeys` then perhaps we should
           coerce?
         */

         if (TYPE(vkey) != T_STRING)
           rb_raise(rb_eArgError, "key must be a string");

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

         if (!NIL_P(vval)) {
           if (TYPE(vval) != T_STRING)
             rb_raise(rb_eArgError, "non-nil value must be a string");

           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.



1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1470

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