Hash::Util#

Native implementation of Hash::Util

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

Perl equivalent: Hash::Util

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#

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_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");

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"

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);

used_buckets#

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

use Hash::Util 'used_buckets';
my $n = used_buckets(%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_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_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_traversal_mask#

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

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

_clear_placeholders#

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

use Hash::Util '_clear_placeholders';
_clear_placeholders(%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");

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);

hidden_keys / 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);

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);

unlock_keys#

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

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

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);

unlock_ref_keys#

Like unlock_keys but takes a hashref. Returns the hashref.

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

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_value / lock_ref_value#

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

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

unlock_value / unlock_ref_value#

Makes a previously locked hash value writable again.

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

lock_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);

unlock_hash / unlock_hashref#

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

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

lock_hash_recurse / 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);

unlock_hash_recurse / 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);

hash_locked / hashref_locked#

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

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

hash_unlocked / 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)) { ... }