Tie::Hash::Indexed#

📦 std

Tie::Hash::Indexed - a hash that keeps its keys in insertion order.

use Tie::Hash::Indexed;

tie my %h, 'Tie::Hash::Indexed';
%h = (one => 1, two => 2, three => 3);
print join(' ', keys %h), "\n";          # one two three

my $h = Tie::Hash::Indexed->new(a => 1, b => 2);
$h->push(c => 3);
$h->unshift(z => 0);
print join(' ', $h->keys), "\n";         # z a b c
my ($key, $value) = $h->pop;             # c 3

The module works as a tied hash and as an object. The object interface is the faster of the two: it has get, set, exists, delete and clear; keys, values and items (all of them, or those of the keys given); push, unshift, pop and shift for the two ends; merge and assign; and the in-place operators preinc, postinc, predec, postdec, add, subtract, multiply, divide, modulo, concat, or_assign and dor_assign.

Storing to a key that exists keeps its position; push and unshift move it to that end. Deleting a key takes the same time whatever the size of the hash.

iterator and reverse_iterator return an iterator object with next, prev, valid, key and value. An iterator dies with “invalid iterator access” once the hash was changed after it was made.

Objects can be frozen, thawed and cloned with Storable.

This is a native implementation of the CPAN module Tie::Hash::Indexed 0.08; its Indexed.pm is used unchanged.

Differences from upstream#

Three, each where perl 5.44 with the XS module reads memory it has freed or a null pointer:

  • pop or shift of the entry an each loop stands on: the loop continues with the next entry, as it does after delete.

  • clear, assign or %h = () in the middle of an each loop called through NEXTKEY directly: the loop ends.

  • NEXTKEY on an object FIRSTKEY was never called on returns the first key.

Modules#

Functions#

Other Functions#

new#

TIEHASH, new: a new hash holding the key/value pairs given.

get#

FETCH, get: the value of a key, undef if there is none.

set#

STORE, set: store a value. A new key goes to the end, an existing one keeps its place. set returns the value.

exists#

EXISTS, exists, has: whether the hash has the key.

Also available as Tie::Hash::Indexed::has.

delete#

DELETE, delete: remove a key and return its value, undef if there was none.

clear#

CLEAR, clear: remove everything. clear returns the object.

items#

items, as_list, keys, values: all entries in order, or those of the keys given (undef for a value that is not there). In scalar context the number of elements the list would have.

Also available as Tie::Hash::Indexed::as_list, Tie::Hash::Indexed::keys, Tie::Hash::Indexed::values.

merge#

merge, assign, push, unshift: store key/value pairs. merge leaves an existing key in place; assign clears the hash first; push and unshift put every pair at that end, moving a key that exists. Returns the number of keys.

Also available as Tie::Hash::Indexed::assign, Tie::Hash::Indexed::push, Tie::Hash::Indexed::unshift.

pop#

pop, shift: remove the last or the first entry. Returns its key and value in list context, its value otherwise, nothing when the hash is empty.

Also available as Tie::Hash::Indexed::shift.

iterator#

iterator, reverse_iterator: an iterator standing on the first, or the last, entry.

Also available as Tie::Hash::Indexed::reverse_iterator.

preinc#

preinc, predec, postinc, postdec: ++ and -- on the value of a key, which starts at 0 if the key is new.

Also available as Tie::Hash::Indexed::predec, Tie::Hash::Indexed::postinc, Tie::Hash::Indexed::postdec.

add#

add, subtract, multiply, divide, modulo, concat, dor_assign, or_assign (and dor_equals, or_equals): the assignment operator +=, -=, *=, /=, %=, .=, //=, ||= on the value of a key, which starts undefined if the key is new. Returns the new value.

Also available as Tie::Hash::Indexed::subtract, Tie::Hash::Indexed::multiply, Tie::Hash::Indexed::divide, Tie::Hash::Indexed::modulo, Tie::Hash::Indexed::concat, Tie::Hash::Indexed::dor_assign, Tie::Hash::Indexed::dor_equals, Tie::Hash::Indexed::or_assign, Tie::Hash::Indexed::or_equals.

STORABLE_freeze#

STORABLE_freeze: Storable’s hook. The frozen form is a six-byte header and a reference to every key and value, in order.

STORABLE_thaw#

STORABLE_thaw: Storable’s hook, the inverse of STORABLE_freeze.