seq#

Move the database’s cursor and read the key and value it lands on: walk the database in order, or find the first key at or after a given one.

Synopsis#

my ($key, $value) = ('', '');
my $status = $db->seq($key, $value, R_FIRST);

What you get back#

0 with $key and $value set to where the cursor landed, 1 when there is nothing there (past either end, or no such key), -1 for an error. On 1 the cursor stays where it was. For an array, $key is an index.

Flags#

R_FIRST, R_LAST - the first or last key.
R_NEXT, R_PREV - the key after or before the cursor; from no cursor yet, the first or the last.
R_CURSOR - in a $DB_BTREE database the first key at or after $key; in a $DB_HASH database $key itself; in an array element $key.

Examples#

Walk a database in order:

my ($k, $v) = ('', '');
for (my $st = $db->seq($k, $v, R_FIRST); $st == 0; $st = $db->seq($k, $v, R_NEXT)) {
    print "$k=$v\n";
}

Find the first key starting with Wa in a $DB_BTREE database:

@h{qw(Smith Wall Walls)} = (1, 2, 3);
my ($k, $v) = ('Wa', '');
print "$k\n" if $db->seq($k, $v, R_CURSOR) == 0 and $k =~ /^Wa/;   # Wall

Edge cases#

$key and $value must be variables: the method writes them.
Array elements created empty are passed over; R_CURSOR on one returns -30995 (Berkeley DB’s DB_KEYEMPTY).
In an R_DUP database R_NEXT and R_PREV step through a key’s values one by one, in the order they were stored.
The tie interface (keys, each) moves the same cursor.

Differences from upstream#

Fully compatible with upstream. Covered by t/81-xs-native/DB_File/010-phenotype.t.