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.



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

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



1663
1664
1665
1666
1667
1668
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1663

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.



1651
1652
1653
1654
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1651

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.



1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1627

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



1355
1356
1357
1358
1359
1360
1361
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1355

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.



1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1536

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.



1370
1371
1372
1373
1374
1375
1376
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1370

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.



1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1404

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.



1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1432

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.



1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1385

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



1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1584

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.



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
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1463

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.



1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1511

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