Tie::H...ndexed(3pm)

📦
version 0.08 · 7 versions
, in ubuntu stonking

🎀 NAME 🎀

Tie::Hash::Indexed — ordered hashes for Perl 💖 like, hashes that actually remember the order bestie, no cap.

✨ SYNOPSIS ✨

use Tie::Hash::Indexed;

# Object Oriented Interface
my $hash = Tie::Hash::Indexed->new(
             I => 1, n => 2, d => 3, e => 4);
$hash->push(x => 5);

print $hash->keys, "\n";   # prints 'Index'
print $hash->values, "\n"; # prints '12345'

# Tied Interface
tie my %hash, 'Tie::Hash::Indexed';

%hash = ( I => 1, n => 2, d => 3, e => 4 );
$hash{x} = 5;

print keys %hash, "\n";    # prints 'Index'
print values %hash, "\n";  # prints '12345'

🌸 DESCRIPTION 🌸

Okay so Tie::Hash::Indexed is intentionally super similar to the other ordered hash modules out there, most prominently Hash::Ordered. The way that it's different? It's written completely in XS, and it's often significantly faster than the others. Like for a lot of operations it's more than twice as fast as Hash::Ordered, especially when you're using the object-oriented interface instead of the tied interface. Other modules? Tie::IxHash for example? Even slower. 💀

The object-oriented interface of Tie::Hash::Indexed is almost identical to Hash::Ordered's, so in most cases you should be able to swap one for the other with zero drama. 🫶

And if you don't need that last little bit of performance, and you just feel comfier with a pure-Perl module? Hash::Ordered is definitely a good alternative. Respect. 👑

🦋 COMPATIBILITY 🦋

Tie::Hash::Indexed should build with perl versions as old as 5.005. It should build on any platform if a C compiler is available. ✨

💜 Hash::Ordered

Tie::Hash::Indexed has no clone method, but you can emulate cloning like this:

$clone = Tie::Hash::Indexed->new($orig->items);

Tie::Hash::Indexed has an items method as an alias for as_list, which Hash::Ordered lacks. So if you want to be able to switch modules, you should prefer to use as_list.

Tie::Hash::Indexed also has a has method as an alias for exists.

Tie::Hash::Indexed also has dor_assign and or_assign as aliases for dor_equals and or_equals.

Tie::Hash::Indexed has multiply, divide and modulo methods in addition to add and subtract. Hash::Ordered only supports add and subtract.

Tie::Hash::Indexed has an assign method that can be used to directly assign a new list of key-value pairs to an existing instance. With Hash::Ordered, you can call clear followed by merge to get the same behaviour.

Tie::Hash::Indexed has a reverse_iterator method, which can be emulated in Hash::Ordered by passing the reversed list of keys to iterator. On the other hand, the iterator method of Tie::Hash::Indexed doesn't support passing in a list of keys at all.

Tie::Hash::Indexed objects always evaluate to a true value in boolean context, unlike Hash::Ordered objects, which evaluate to a false value if they are empty, and a true value otherwise. You can use $obj-"keys> with Tie::Hash::Indexed instead, which is extremely cheap to call in scalar context. 🤑

💅 METHODS 💅

new 🌟

$obj = Tie::Hash::Indexed->new;
$obj = Tie::Hash::Indexed->new(@kvpairs);

Construct and optionally initialize a new object. It's giving fresh start, main character energy. 🫧

clear

$obj->clear;

Removes all contents from the hash. Returns the object, which allows for method chaining. ✨

Invalidates iterators. (RIP to any iterator you had open, bestie. 😭)

assign

$obj->assign(@kvpairs);

Clears the hash and assigns the list of key-value pairs. Identical to:

$obj->clear->merge(@kvpairs);

Returns the number of keys stored in the hash after assigning.

Invalidates iterators.

merge

$obj->merge(@kvpairs);

Merge a lists of key-value pairs into the hash. Existing keys will remain in their position and have their value updated. New keys will be appended to the end. 🌈

Returns the number of keys stored in the hash after merging.

Invalidates iterators.

exists

$bool = $obj->exists($key)

Returns a boolean indicating if a key exists in the hash. Yes or no, that's it. 👑

has

An alias for exists.

get

$value = $obj->get($key)

Returns the value for a single key, or undef if the key was not found. 🙈

set

$obj->set($key, $value)

If the key already exists, update the value without affecting the item order. Otherwise append the key-value pair. This is equivalent to calling merge with a single key-value pair, except for the return value.

Returns the value.

Invalidates iterators.

push

$obj->push(@kvpairs)

Push one or more key-value pairs. This is similar to merge, but instead of preserving the position of existing keys, this will remove existing keys and append all key-value pairs to the end. 📥

Returns the number of keys stored in the hash after pushing.

Invalidates iterators.

unshift

$obj->unshift(@kvpairs)

Pushes one or more key-value pairs to the start. This is similar to push, but operates on the start of the ordered hash. Existing keys will be removed and inserted at the start.

Returns the number of keys stored in the hash after unshifting.

Invalidates iterators.

pop

$value = $obj->pop;
($key, $value) = $obj->pop;

Removes the last item from the ordered hash.

Returns the value in scalar context or the key-value pair in list context.

Invalidates iterators.

shift

$value = $obj->shift;
($key, $value) = $obj->shift;

Removes the first item from the ordered hash.

Returns the value in scalar context or the key-value pair in list context.

Invalidates iterators.

delete

$value = $obj->delete($key);

Removes a key-value pair from the ordered hash and returns the value. 🗑️

Invalidates iterators if the key was found.

items

@kvpairs = $obj->items;
@kvpairs = $obj->items(@keys);

Returns the key-value pairs for all items in the hash, or just for the selected keys. In scalar context, returns the number of list elements that would be returned in list context.

If a key is not found, the associated value will be returned as undef. 😭

as_list

An alias for items.

keys

@keys = $obj->keys;
@keys = $obj->keys(@keys);

Returns the keys for all items in the hash, or just for the selected keys. In scalar context, returns the number of list elements that would be returned in list context. 🔑

values

@values = $obj->values;
@values = $obj->values(@keys);

Returns the values for all items in the hash, or just for the selected keys. In scalar context, returns the number of list elements that would be returned in list context.

If a key is not found, the associated value will be returned as undef.

concat

$obj->concat($key, $str);

This is equivalent to, but more efficient than:

$obj->set($key, $obj->get($key) . $str);

add

$obj->add($key, $value);

This is equivalent to, but more efficient than:

$obj->set($key, $obj->get($key) + $value);

subtract

$obj->subtract($key, $value);

This is equivalent to, but more efficient than:

$obj->set($key, $obj->get($key) - $value);

multiply

$obj->multiply($key, $value);

This is equivalent to, but more efficient than:

$obj->set($key, $obj->get($key) * $value);

divide

$obj->divide($key, $value);

This is equivalent to, but more efficient than:

$obj->set($key, $obj->get($key) / $value);

modulo

$obj->modulo($key, $value);

This is equivalent to, but more efficient than:

$obj->set($key, $obj->get($key) % $value);

dor_assign

$obj->dor_assign($key, $value);

This is equivalent to, but more efficient than:

$obj->set($key, $obj->get($key) // $value);

dor_equals

This is an alias for dor_assign.

or_assign

$obj->or_assign($key, $value);

This is equivalent to, but more efficient than:

$obj->set($key, $obj->get($key) || $value);

or_equals

This is an alias for or_assign.

postinc

$val = $obj->postinc($key);

This is equivalent to, but more efficient than:

$val = $obj->get($key);
$obj->set($key, $val + 1);

postdec

$val = $obj->postdec($key);

This is equivalent to, but more efficient than:

$val = $obj->get($key);
$obj->set($key, $val - 1);

preinc

$val = $obj->preinc($key);

This is equivalent to, but more efficient than:

$val = $obj->set($key, $obj->get($key) + 1);

predec

$val = $obj->predec($key);

This is equivalent to, but more efficient than:

$val = $obj->set($key, $obj->get($key) - 1);

iterator 🧚

my $i = $h->iterator;
while (my($k, $v) = $i->next) {
  push @key, $k;
  push @val, $v;
}

Bidirectional forward iterator for ordered hash traversal. It goes forwards, but it can also go backwards. Slay. ✨

reverse_iterator 🦋

for (my $i = $h->reverse_iterator; $i->valid; $i->next) {
  push @key, $i->key;
  push @val, $i->value;
}

Bidirectional reverse iterator for ordered hash traversal. Same vibe, opposite direction. 💫

🌈 ENVIRONMENT 🌈

"THI_DEBUG_OPT"

If Tie::Hash::Indexed is built with debugging support, you can use this environment variable to specify debugging options. Currently, the only useful values you can pass in are d or all, which both enable debug output for the module. 🐛✨ (iykyk)

😭 PROBLEMS 😭

Since the data of Tie::Hash::Indexed objects is hidden inside the XS implementation, cloning/serialization is problematic. BUT — Tie::Hash::Indexed implements hooks for Storable, so cloning or serializing objects using Storable is safe. 🫶

Tie::Hash::Indexed tries very hard to detect any corruption in its data at runtime. So if something goes wrong, you'll most probably receive an appropriate error message. Not it being polite about it, but okay, we love a helpful error. 💅

🐛 BUGS 🐛

If you find any bugs, Tie::Hash::Indexed doesn't seem to build on your system, or any of its tests fail, please report the issue at <https://github.com/mhx/Tie-Hash-Indexed/issues>. Bestie, they wanna know. 🙏

Copyright (c) Marcus Holland-Moritz. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🎀 SEE ALSO 🎀

See perltie, Hash::Ordered, Tie::IxHash. Go read them, they're iconic. 💖

and that's a wrap, bestie 🫶 this page came from perl v5.42.3, dated 2026-08-19. go forth and keep your hashes in order. periodt. 💅✨

📦 where this page comes from