safekeys¶

LIST = safekeys HASH¶

Like the builtin keys function, returns a list consisting of all the keys of the named hash, in the same order that the builtin function would return them in. Unlike "keys", calling "safekeys" does not reset the HASH's internal iterator (see each).

safevalues¶

LIST = safevalues HASH¶

Like the builtin values function, returns a list consisting of all the values of the named hash, in the same order that the builtin function would return them in. Unlike "values", calling "safevalues" does not reset the HASH's internal iterator (see each).

safecopy¶

LIST = safecopy HASH¶

In list context, returns a shallow copy of the named HASH without resetting the HASH's internal iterator. Usually, evaluating a HASH in list context implicitly uses the internal iterator, resetting any existing state

save_iterator_state¶

restore_iterator_state¶

HANDLE = save_iterator_state($hashref)¶

restore_iterator_state($hashref, HANDLE)¶

Low-level functions to manipulate the iterator of a hash reference. The use cases for directly using these functions are

1. Performance

The absolute fastest way to safely access the keys of a hash is:

    $handle = Hash::Safekeys::save_iterator_state( \%hash );
    @keys = keys %hash;
    Hash::Safekeys::restore_iterator_state( \%hash, $handle );
    

This is an improvement over "@keys = safekeys %hash" because it eliminates the O(n) list copy operation on return from the "safekeys" function.

2. Access to aliased values

The builtin "values" function returns aliases to the internal hash values, allowing you to modify the contents of the hash with constructions like

    s/foo/bar/g for values %hash
    

As "safevalues %hash" returns a copy of the hash values, "s/foo/bar/g for safevalues %hash" will not modify the contents of the hash.

To safely modify the values of the hash, a workaround with the low-level iterator functions is

    $handle = Hash::SafeKeys::save_iterator_state( \%hash );
    for (values %hash) { ... modify($_) ... }
    Hash::SafeKeys::restore_iterator_state( \%hash, $handle );
    

3. Nested each calls on the same hash

This construction will not work if $hash1 and $hash2 refer to the same hash:

    while (($key1,$val1) = each %$hash1) {
        while (($key2,$val2) = each %$hash2) { ... }
    }
    

but this construction is safe:

    while (($key1,$val1) = each %$hash1) {
        $handle = Hash::SafeKeys::save_iterator_state($hash2);
        while (($key2,$val2) = each %$hash2) { ... }
        Hash::SafeKeys::restore_iterator_state($hash2, $handle);
    }
    

The HANDLE that is returned by "save_iterator_state" and used as an input to "restore_iterator_state" is currently implemented as an integer that can be mapped internally to an original hash iterator. This implementation is subject to change in future releases and you should not rely on this value being an integer.

It is a grave error to provide a different hash reference with the handle to the "restore_iterator_state" call than you provided to the "save_iterator_state" call that created the handle.

Calling "save_iterator_state" without later calling "restore_iterator_state" will leak memory.