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.

