# 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

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

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

```none
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).

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

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

## used_buckets

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

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

## bucket_info

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

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

```none
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).

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

## bucket_stats_formatted

Returns a human-readable string summarising bucket statistics.

```none
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).

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

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

## hv_store

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

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

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

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

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

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

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

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

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

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

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

## unlock_value / unlock_ref_value

Makes a previously locked hash value writable again.

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

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

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

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

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

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

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