put#

Store a value under a key, with flags that say where and whether.

Synopsis#

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

0 when the value was stored, 1 when R_NOOVERWRITE found the key already there, -1 for an error.

none - store the value, replacing the key’s; in an R_DUP database, add it after the key’s other values.
R_NOOVERWRITE - store only if the key is not there yet.
R_CURSOR - replace the value the database’s cursor stands on; the key given is ignored.
R_SETCURSOR - store, then set the cursor on the key (its first value, in an R_DUP database).
R_IAFTER, R_IBEFORE - put a new array element after or before element $key, the ones after it moving up; in an R_DUP database, a new value after or before the key’s first. $key must be a variable: the method writes it back.

print $db->put('a', 1);                   # 0
print $db->put('a', 2, R_NOOVERWRITE);    # 1, and 'a' is still 1

Insert into an array:

@lines = qw(one three);
my $i = 0;
$db->put($i, 'two', R_IAFTER);            # one two three

R_IAFTER and R_IBEFORE leave $key as it was; they return -1 for an element past the end or created empty, and in a hash database without R_DUP ($DB_File::Error then says the flag is illegal).
R_CURSOR with no cursor set yet returns -1. After a delete at the cursor, a $DB_HASH or $DB_BTREE database returns -30987 (Berkeley DB’s DB_NOTFOUND) and stores nothing, while an array gets the deleted element back with the new value.
A fixed-length array refuses a value longer than its records: -1, with $DB_File::Error giving both lengths.
On a database opened read-only it returns -1.

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