/ 
HAMT-0.03
/ HAMT::Map::Transient

NAME

HAMT::Map::Transient - a map opened for a batch of updates

VERSION

Version 0.03

SYNOPSIS

use HAMT::Map;

my $m = HAMT::Map->new(a => 1);

my $t = $m->transient;
$t->set("key$_" => $_) for 1 .. 100_000;
$t->delete('a');
my $m2 = $t->persistent;

$m->count;      # 1: the map it was opened from is unchanged
$m2->count;     # 100000

DESCRIPTION

A HAMT::Map pays for never changing: each update makes a new map, and a loop of a hundred thousand updates makes a hundred thousand of them, all but the last thrown away at once.

A transient is the same map with that promise suspended for a while. It is made by "transient" in HAMT::Map, it is changed by "set" and "delete", and "persistent" turns it back into an ordinary map that never changes again. The map it was opened from is not affected by any of it, and neither is any other map or transient opened from the same one.

Use one where a piece of code builds or reworks a map in several steps and nobody else needs to see the steps in between. HAMT::Map->new, from_hash and a set or delete with several arguments already work this way inside, so a transient is for the loops those cannot express.

Differences from a map

"set" and "delete" return the transient itself, and do not warn in void context.

A transient has no keys, each, merge or equals. Call "persistent" first; it costs nothing, and "transient" in HAMT::Map on the result opens another.

A value that is replaced or deleted is let go at once, unless some map still holds it.

METHODS

set

$t->set($key => $value);
$t->set(a => 1, b => 2)->set(c => 3);

Stores the pairs in the transient and returns the transient. Keys and values are treated exactly as "set" in HAMT::Map treats them.

delete

$t->delete($key);
$t->delete(@keys);

Removes the keys from the transient and returns the transient. A key that is not there is ignored.

get

my $value = $t->get($key);

The value stored under the key, or undef when there is none.

exists

if ($t->exists($key)) { ... }

True when the key is in the transient.

count

my $n = $t->count;

The number of keys.

persistent

my $m = $t->persistent;

An ordinary map holding what the transient holds, of the class of the map the transient was opened from. This does not copy anything.

The transient is closed by it. Every method called on a closed transient dies with this transient is closed, including a second persistent.

THREADS

A transient belongs to the interpreter that made it and is not inherited by a new thread.

AUTHOR

LNATION, <email at lnation.org>

BUGS

Please report any bugs or feature requests to bug-hamt at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=HAMT.

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under the Artistic License 2.0.