/ 
Set-Equivalence-0.003
River stage one • 1 direct dependent • 1 total dependent
/ Set::Equivalence

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 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:

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