get#

Look up a key and put its value in a variable, returning a status instead of the value - so a missing key and a stored undef can be told apart.

Synopsis#

my $value;
my $status = $db->get($key, $value);

What you get back#

0 with $value set when the key is stored, 1 when it is not (leaving $value alone), -1 for an error. In an R_DUP database $value is the key’s first value. For an array, $key is the element’s index.

Examples#

$h{colour} = 'blue';
my $v;
print $db->get('colour', $v), " $v";   # 0 blue
print $db->get('size', $v);            # 1

Edge cases#

  • An array element created empty returns -30995 (Berkeley DB’s DB_KEYEMPTY) and leaves $value alone.

  • The value passes through a filter_fetch_value filter, and the key through filter_store_key, as with the tied hash.

  • A flags argument other than 0 returns -1.

Differences from upstream#

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

See also#

  • put - stores a value

  • seq - looks up the first key at or after one, and walks on

  • get_dup - all the values of a key