---
name: Hash::Util
runtime: pp
source: src/native/Hash/Util/pp.rs
---
```{index} single: Hash::Util; Perl module (pp runtime)
```

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

## legal_keys / legal_ref_keys

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

    use Hash::Util 'legal_keys';
    my @lk = legal_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)) { ... }