Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Hash::Util

Native Rust implementation built into the interpreter. Runtime: PP. See original documentation for the full Perl reference.

Provides hash introspection and manipulation utilities. Implements the XS primitives and commonly-used pure-Perl wrappers for hash locking, key restriction, and bucket introspection.

Synopsis

use Hash::Util qw(lock_keys lock_hash hash_value);

my %h = (foo => 1, bar => 2);
lock_keys(%h);             # restrict to existing keys
lock_hash(%h);             # fully immutable

my $hval = hash_value("key");

Functions

_clear_placeholders

Removes placeholder (restricted-deleted) keys from a hash. No-op in this implementation.

use Hash::Util '_clear_placeholders';
_clear_placeholders(%hash);

all_keys

Populates two arrayrefs with visible and hidden (placeholder) keys, then returns a reference to the hash.

use Hash::Util 'all_keys';
all_keys(%hash, @visible, @hidden);

bucket_array

Returns an arrayref with one slot per bucket (undef for empty buckets). Simplified approximation of perl5’s internal layout.

use Hash::Util 'bucket_array';
my $aref = bucket_array(%hash);

bucket_info

Returns a 3-element list: (keys, total_buckets, used_buckets).

use Hash::Util 'bucket_info';
my ($keys, $total, $used) = bucket_info(%hash);

bucket_ratio

Returns a string “used/total” representing the bucket usage ratio of the hash. Total is the next power of 2 (minimum 8).

use Hash::Util 'bucket_ratio';
my $ratio = bucket_ratio(%hash);  # e.g. "3/8"

bucket_stats

Returns a 4-element list: (keys, total_buckets, used_buckets, quality_score). Quality is always 1.0 (ideal).

use Hash::Util 'bucket_stats';
my ($k, $t, $u, $q) = bucket_stats(%hash);

bucket_stats_formatted

Returns a human-readable string summarising bucket statistics.

use Hash::Util 'bucket_stats_formatted';
print bucket_stats_formatted(%hash);
# "keys: 3 buckets: 3/8 quality: 1.00"

hash_locked

Returns 1 if the hash has its keys locked (restricted), 0 otherwise.

use Hash::Util 'hash_locked';
if (hash_locked(%hash)) { ... }

hash_seed

Returns the hash seed used by the internal hash algorithm. Currently returns a fixed “0” string.

use Hash::Util 'hash_seed';
my $seed = hash_seed();

hash_traversal_mask

Returns the hash traversal randomisation mask. Always returns 0 (no randomisation).

use Hash::Util 'hash_traversal_mask';
my $mask = hash_traversal_mask();

hash_unlocked

Returns 1 if the hash does NOT have its keys locked, 0 otherwise. Inverse of hash_locked.

use Hash::Util 'hash_unlocked';
if (hash_unlocked(%hash)) { ... }

hash_value

Computes and returns the integer hash value for a given string using Rust’s DefaultHasher.

use Hash::Util 'hash_value';
my $h = hash_value("key");

hashref_locked

Returns 1 if the hash has its keys locked (restricted), 0 otherwise.

use Hash::Util 'hash_locked';
if (hash_locked(%hash)) { ... }

hashref_unlocked

Returns 1 if the hash does NOT have its keys locked, 0 otherwise. Inverse of hash_locked.

use Hash::Util 'hash_unlocked';
if (hash_unlocked(%hash)) { ... }

hidden_keys

Returns the list of hidden (placeholder) keys in a hash or hashref.

use Hash::Util 'hidden_keys';
my @hk = hidden_keys(%hash);

hidden_ref_keys

Returns the list of hidden (placeholder) keys in a hash or hashref.

use Hash::Util 'hidden_keys';
my @hk = hidden_keys(%hash);

hv_store

Stores a key/value pair directly in the hash, bypassing any key-restriction checks.

use Hash::Util 'hv_store';
hv_store(%hash, "key", "value");

Returns all legal keys (visible + hidden/restricted) for the hash.

use Hash::Util 'legal_keys';
my @lk = legal_keys(%hash);

Returns all legal keys (visible + hidden/restricted) for the hash.

use Hash::Util 'legal_keys';
my @lk = legal_keys(%hash);

lock_hash

Locks all keys AND all values of the hash. No new keys can be added, no existing values can be changed. Returns the hashref.

use Hash::Util 'lock_hash';
lock_hash(%hash);

lock_hash_recurse

Recursively locks the hash and all nested hash values. Returns the hashref.

use Hash::Util 'lock_hash_recurse';
lock_hash_recurse(%hash);

lock_hashref

Locks all keys AND all values of the hash. No new keys can be added, no existing values can be changed. Returns the hashref.

use Hash::Util 'lock_hash';
lock_hash(%hash);

lock_hashref_recurse

Recursively locks the hash and all nested hash values. Returns the hashref.

use Hash::Util 'lock_hash_recurse';
lock_hash_recurse(%hash);

lock_keys

Restricts a hash to its current keyset, or to an explicit list of allowed keys. Adding a key not in the set will die. Returns the hashref.

use Hash::Util 'lock_keys';
lock_keys(%hash);
lock_keys(%hash, @allowed);

lock_ref_keys

Like lock_keys but takes a hashref instead of a hash. Returns the hashref.

use Hash::Util 'lock_ref_keys';
lock_ref_keys($href);
lock_ref_keys($href, @allowed);

lock_ref_keys_plus

Locks the hashref’s keys to the union of its current keys and the supplied additional keys. Returns the hashref.

use Hash::Util 'lock_ref_keys_plus';
lock_ref_keys_plus($href, @extra_keys);

lock_ref_value

Makes a single hash value read-only. The key must already exist.

use Hash::Util 'lock_value';
lock_value(%hash, 'key');

lock_value

Makes a single hash value read-only. The key must already exist.

use Hash::Util 'lock_value';
lock_value(%hash, 'key');

num_buckets

Returns the total number of buckets allocated for the hash. Minimum is 8, then next power of 2 above the key count.

use Hash::Util 'num_buckets';
my $n = num_buckets(%hash);

unlock_hash

Unlocks all keys and values of a previously locked hash. Returns the hashref.

use Hash::Util 'unlock_hash';
unlock_hash(%hash);

unlock_hash_recurse

Recursively unlocks the hash and all nested hash values. Returns the hashref.

use Hash::Util 'unlock_hash_recurse';
unlock_hash_recurse(%hash);

unlock_hashref

Unlocks all keys and values of a previously locked hash. Returns the hashref.

use Hash::Util 'unlock_hash';
unlock_hash(%hash);

unlock_hashref_recurse

Recursively unlocks the hash and all nested hash values. Returns the hashref.

use Hash::Util 'unlock_hash_recurse';
unlock_hash_recurse(%hash);

unlock_keys

Removes the key restriction on a hash, allowing arbitrary keys again. Returns the hashref.

use Hash::Util 'unlock_keys';
unlock_keys(%hash);

unlock_ref_keys

Like unlock_keys but takes a hashref. Returns the hashref.

use Hash::Util 'unlock_ref_keys';
unlock_ref_keys($href);

unlock_ref_value

Makes a previously locked hash value writable again.

use Hash::Util 'unlock_value';
unlock_value(%hash, 'key');

unlock_value

Makes a previously locked hash value writable again.

use Hash::Util 'unlock_value';
unlock_value(%hash, 'key');

used_buckets

Returns the number of occupied buckets (approximated as the number of keys).

use Hash::Util 'used_buckets';
my $n = used_buckets(%hash);