/ 
Hash-Util-Set-0.07
/ Hash::Util::Set

NAME

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

SYNOPSIS

%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.

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

This module automatically uses the XS implementation 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.