NAME Set::Equivalence - a set of objects or scalars with no duplicates and a user-configurable equivalence relation SYNOPSIS 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 DESCRIPTION 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 <http://en.wikipedia.org/wiki/Set_(mathematics)> is an unordered collection of zero or more members. In computer science, this translates to a set data type <http://en.wikipedia.org/wiki/Set_(abstract_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 <http://en.wikipedia.org/wiki/Equivalence_relation> and may act unexpectedly if it is not. In particular, it expects: * Reflexivity. In other words for any $x, `$equiv->($x, $x)` is always true. * Symmetry. In other words for any $x and $y, `$equiv->($x, $y)` implies `$equiv->($y, $x)`. * Transitivity. In other words for any $x, $y and $z, `$equiv->($x, $y) && $equiv->($y, $z)` implies `$equiv->($x, $z)`. * Determinism. For any $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. Constructors 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: *members* An initial collection of members to add to the set, provided as an arrayref. Optional; defaults to none. *mutable* Boolean, indicating whether the set should be mutable. Optional; defaults to true. *equivalence_relation* Coderef accepting to arguments. Optional; defaults to a coderef that checks string equality, but treats `undef` differently to "", and handles overloaded objects properly. *type_constraint* A type constraint for set members. Optional; accepts Type::Tiny and MooseX::Types type constraints (or indeed any object implementing Type::API::Constraint). *coerce* 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.) Accessors 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). Predicates 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. Mutators 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. Comparison 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. Arithmetic 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. Miscellaneous Methods `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. Overloaded Operators '""' => '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 }, BUGS Please report any bugs to <http://rt.cpan.org/Dist/Display.html?Queue=Set-Equivalence>. SEE ALSO Types::Set. Set::Object, Set::Scalar, Set::Tiny. List::Objects::WithUtils. AUTHOR Toby Inkster <tobyink@cpan.org>. COPYRIGHT AND LICENCE 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. DISCLAIMER OF WARRANTIES 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.