/ 
Hash-Util-Set-0.06
/ Hash::Util::Set

NAME

Hash::Util::Set - Set operations on hash keys

SYNOPSIS

use Hash::Util::Set qw(:all);

%x = (a => 1, b => 2, c => 3);
%y = (b => 4, c => 5, d => 6);

# Set operations
@keys = keys_union %x, %y;                 # (a, b, c, d)
@keys = keys_intersection %x, %y;          # (b, c)
@keys = keys_difference %x, %y;            # (a)
@keys = keys_symmetric_difference %x, %y;  # (a, d)

# Set predicates
$bool = keys_disjoint %x, %y;              # no common keys?
$bool = keys_equal %x, %y;                 # same keys?
$bool = keys_subset %x, %y;                # x ⊆ y?
$bool = keys_proper_subset %x, %y;         # x ⊂ y?
$bool = keys_superset %x, %y;              # x ⊇ y?
$bool = keys_proper_superset %x, %y;       # x ⊃ y?

# Key membership tests
$bool = keys_any  %x, 'a', 'z';            # at least one exists?
$bool = keys_all  %x, 'a', 'b', 'c';       # all exist?
$bool = keys_none %x, 'x', 'y', 'z';       # none exist?

# Combined operations
@sets = keys_partition %x, %y;             # A \ B, A ∩ B, B \ A

DESCRIPTION

Hash::Util::Set provides set operations on hash keys. It treats the keys of a hash as a set and provides common set operations (union, intersection, difference), set predicates, and membership tests.

All operations work only on keys; values are ignored.

This module automatically uses the XS implementation if available, falling back to pure Perl otherwise.

FUNCTIONS

Set Operations

Order of keys is unspecified for all set operations.

keys_union

@keys = keys_union %x, %y;

Returns all keys present in either hash (A ∪ B).

keys_intersection

@keys = keys_intersection %x, %y;

Returns keys present in both hashes (A ∩ B).

keys_difference

@keys = keys_difference %x, %y;

Returns keys in %x but not in %y (A \ B).

keys_symmetric_difference

@keys = keys_symmetric_difference %x, %y;

Returns keys in either hash but not both (A △ B).

Set Predicates

keys_disjoint

$bool = keys_disjoint %x, %y;

True if hashes have no common keys (A ∩ B = ∅).

keys_equal

$bool = keys_equal %x, %y;

True if hashes have exactly the same keys (A = B).

keys_subset

$bool = keys_subset %x, %y;

True if all keys in %x are in %y (A ⊆ B).

keys_proper_subset

$bool = keys_proper_subset %x, %y;

True if %x ⊂ %y and they're not equal (A ⊂ B where A ≠ B).

keys_superset

$bool = keys_superset %x, %y;

True if %x contains all keys from %y (A ⊇ B).

keys_proper_superset

$bool = keys_proper_superset %x, %y;

True if %x ⊃ %y and they're not equal (A ⊃ B where A ≠ B).

Key Membership Tests

These functions test whether specific keys exist in a hash.

keys_any

$bool = keys_any %x, LIST;

True if at least one key in LIST exists in %x. Returns false for empty LIST.

keys_all

$bool = keys_all %x, LIST;

True if all keys in LIST exist in %x. Returns true for empty LIST.

keys_none

$bool = keys_none %x, LIST;

True if none of the keys in LIST exist in %x. Returns true for empty LIST.

Combined Operations

keys_partition

my ($only_x, $both, $only_y) = keys_partition %x, %y;

Partitions the union of keys from both hashes into three disjoint sets: keys only in %x (A \ B), keys in both hashes (A ∩ B), and keys only in %y (B \ A).

Returns a list with three array references.

ALIASES

Shorter aliases:

keys_or   =>  keys_union
keys_and  =>  keys_intersection
keys_sub  =>  keys_difference
keys_xor  =>  keys_symmetric_difference

EXPORTS

Nothing is exported by default. Functions can be imported individually or by category:

use Hash::Util::Set qw(keys_union keys_intersection);  # individual functions
use Hash::Util::Set qw(:all);                          # all functions
use Hash::Util::Set qw(:operations);                   # set operations only
use Hash::Util::Set qw(:predicates);                   # predicates only
use Hash::Util::Set qw(:membership);                   # membership tests only
use Hash::Util::Set qw(:aliases);                      # short aliases only

Export Tags

:all

All functions including operations, predicates, membership tests, and aliases.

:operations

Set operations: keys_union, keys_intersection, keys_difference, keys_symmetric_difference, keys_partition.

:predicates

Set predicates: keys_disjoint, keys_equal, keys_subset, keys_proper_subset, keys_superset, keys_proper_superset.

:membership

Membership tests: keys_any, keys_all, keys_none.

:aliases

Short aliases: keys_or, keys_and, keys_sub, keys_xor.

IMPLEMENTATION

Automatically uses Hash::Util::Set::XS if available, otherwise falls back to Hash::Util::Set::PP.

SEE ALSO

Hash::Util, List::Util, Set::Scalar, Set::Object

AUTHOR

Christian Hansen <chansen@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2026 Christian Hansen

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.