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.



924
925
926
927
928
929
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 924

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



1201
1202
1203
1204
1205
1206
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1201

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

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



1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1180

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



996
997
998
999
1000
1001
1002
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 996

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.



1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1095

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.



1011
1012
1013
1014
1015
1016
1017
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1011

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.



1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1044

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

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



1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1026

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



1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1143

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.



1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1061

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.



1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 1078

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