Set::Equivalence - a set of objects or scalars with no duplicates and a user-configurable equivalence relation
use v5.12; use Set::Equivalence qw(set); my $numbers = set(1..4) + set(2, 4, 6, 8); say for $numbers->members; # 1, 2, 3, 4, 6, 8
If you're familiar with Set::Object or Set::Scalar, then you should be right at home with Set::Equivalence.
In mathematical terms, a set is an unordered collection of zero or more members. In computer science, this translates to a set data type which is much like an array or list, but without ordering and without duplicates. (Adding an item to a set that is already a member of the set is a no-op.)
Like Set::Object and Set::Scalar, Set::Equivalence sets are mutable by default; that is, it's possible to add and remove items after constructing the set. However, it is possible to mark sets as being immutable; after doing so, any attempts to modify the set will throw an exception.
The main distinguishing feature of Set::Equivalence is that it is possible to define an equivalence relation (a coderef taking two arguments) which will be used to judge whether two set members are considered duplicates.
Set::Equivalence expects your coderef to act as a true equivalence relation and may act unexpectedly if it is not. In particular, it expects:
$x
, $equiv->($x, $x)
is always true.$x
and $y
, $equiv->($x, $y)
implies $equiv->($y, $x)
.$x
, $y
and $z
, $equiv->($x, $y) && $equiv->($y, $z)
implies $equiv->($x, $z)
.$x
and $y
, $equiv->($x, $y)
will always return the same thing, at least for the lifetime of the set object. (If $x
and $y
are mutable objects, then it's easy for an equivalence function to become non-deterministic.)This approach to implementing a set is unavoidably slow, because it means we can't use a hash of incoming values to detect duplicates; instead the equivalence relation needs to be called on each pair of members. However, performance is generally tolerable for sets of a few dozen members.
The API documented below is roughly compatible with Set::Object and Set::Tiny.
A methods and a function for creating a new set from nothing.
new(%attrs)
Standard Moose-style constructor function (though this module does not use Moose). Valid attributes are:
An initial collection of members to add to the set, provided as an arrayref. Optional; defaults to none.
Boolean, indicating whether the set should be mutable. Optional; defaults to true.
Coderef accepting to arguments. Optional; defaults to a coderef that checks string equality, but treats undef
differently to ""
, and handles overloaded objects properly.
A type constraint for set members. Optional; accepts Type::Tiny and MooseX::Types type constraints (or indeed any object implementing Type::API::Constraint).
Boolean; whether type coercion should be attempted. Optional; defaults to false. Ignored unless the set has a type constraint which has coercions.
set(@members)
, typed_set($constraint, @members)
Exportable functions (i.e. not a method) that act as shortcuts for new
.
Note that this module uses Exporter::Tiny, which allows exported functions to be renamed.
clone
Returns a shallow clone of an existing set, with the same members and the same equivalence function. (The clone will be mutable.)
A methods for accessing the set's data.
members
Returns all members of the set, as a list.
Alias: elements
.
size
Returns the set cardinality (i.e. a count of the members).
member($member)
Returns $member if it is a member of the set; returns undef otherwise. (Of course, undef may be a member of the set!) In list context, returns an empty list if the member is not a member of the set.
Alias: element
.
equivalence_relation
Returns the equivalence relation coderef.
type_constraint
Returns the type constraint (if any).
Methods returning booleans.
is_mutable
Returns true iff the set is mutable.
Negated: is_immutable
.
is_null
Returns true iff the set is empty.
Alias: is_empty
.
is_weak
Implemented for compatibility with Set::Object. Always returns false.
contains(@members)
Returns a boolean indicating whether all @members
are members of the set.
Alias: includes
, has
.
should_coerce
Returns true iff this set will attempt type coercion of incoming members.
Methods that alter the contents or behaviour of the set.
insert(@members)
Adds members to the set. Returns the number of new members added (i.e. that were not already members).
Throws an exception if the set is immutable.
remove(@members)
Removes members from the set. Returns the number of members removed. Any members not found in the set are ignored.
Throws an exception if the set is immutable.
Alias: delete
.
invert(@members)
For each argument: if it already exists in the set, removes it; otherwise, adds it.
Throws an exception if the set is immutable.
clear
Empties the set. Significantly faster than remove
.
Throws an exception if the set is immutable.
pop
Removes an arbitrary member from the set and returns it.
Throws an exception if the set is immutable.
make_immutable
Converts the set to an immutable one.
Returns the invocant, which means this method is suitable for chaining.
my $even_primes = set(2)->make_immutable;
weaken
Unimplemented.
strengthen
Ignored.
The following methods can be called as object methods with a single parameter, or class methods with two parameters:
$set1->equal($set2); # or: 'Set::Equivalent'->equal($set1, $set2);
equal($set1, $set2)
Returns true iff all members of $set1
occur in $set2
and all members of $set2
occur in $set1
.
Negated: not_equal
.
subset($set1, $set2)
Returns true iff all members of $set1
occur in $set2
. That is, if $set1
is a subset of $set2
.
superset($set1, $set2)
Returns true iff all members of $set2
occur in $set1
. That is, if $set2
is a subset of $set1
.
proper_subset($set1, $set2)
, proper_superset($set1, $set2)
Sets that are equal are trivially subsets and supersets of each other. These methods return false if the sets are equal, but otherwise return the same as subset
and superset
.
is_disjoint($set1, $set2)
Returns true iff the sets have no elements in common.
compare
Unimplemented.
The following methods can be called as object methods with a single parameter, or class methods with two parameters:
$set1->union($set2); # or: 'Set::Equivalent'->union($set1, $set2);
They all return mutable sets. If called as an object method, the returned sets have the same equivalence relation and type constraint as the set given in the first argument; if called as a class method, the returned sets have the default equivalence relation and no type constraint.
intersection($set1, $set2)
Returns the set which is the largest common subset of both sets.
union($set1, $set2)
Returns the set which is the smallest common superset of both sets.
difference($set1, $set2)
Returns a copy of $set1
with all members of $set2
removed.
symmetric_difference($set1, $set2)
Returns a copy of the union with all members of the intersection removed.
map($set1, $coderef)
Returns a new set created by passing each member of $set1
through a coderef.
See also map
in perlfunc.
grep($set1, $coderef)
Returns a new set created by filtering each member of $set1
by a coderef that should return a boolean.
See also grep
in perlfunc.
part($set1, $coderef)
Returns a list of sets created by partitioning $set1
by a coderef that should return an integer.
See also part
in List::MoreUtils.
as_string
A basic string representation of the set.
as_string_callback
Unimplemented.
as_array
Returns a reference to a tied array that can be used to iterate through the set members, push
new members onto, and pop
members off.
The order of members in the array is arbitrary.
Set::Equivalent::_Tie does not implement the entire Tie::Array interface, so some bits will crash. In particular, STORE operations are not implemented, so you can't do $set->as_array->[1] = 42
. splice
, exists
and delete
will probably also fail. (But exists
and delete
on array elements are insane anyway.)
iterator
Returns an iterator that will walk through the current members of the set.
reduce($set, $coderef)
Reduces the set to a single value.
See also reduce
in List::Util.
'""' => 'as_string', '+' => 'union', '*' => 'intersection', '%' => 'symmetric_difference', '-' => 'difference', '==' => 'equal', 'eq' => 'equal', '!=' => 'not_equal', 'ne' => 'not_equal', '<' => 'proper_subset', '>' => 'proper_superset', '<=' => 'subset', '>=' => 'superset', '@{}' => 'as_array', 'bool' => sub { 1 },
Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Set-Equivalence.
Set::Object, Set::Scalar, Set::Tiny.
Toby Inkster <tobyink@cpan.org>.
This software is copyright (c) 2013 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.