<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from Tie/Hash/Indexed.rs. Do not edit. -->

```{index} single: Tie::Hash::Indexed
```

# Tie::Hash::Indexed

```{pperl-module-badges} Tie::Hash::Indexed
```

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

```perl
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

- [`Tie::Hash::Indexed::Iterator`](Indexed/Iterator)

## 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`.

```{toctree}
:hidden:
:maxdepth: 1

Indexed/Iterator
```