NAME
    Set::Hash - Hashes as objects with lots of handy methods (including set
    comparisons) and support for method chaining.

SYNOPSIS
    "use Set::Hash;"

    "my $sh1 = Set::Hash->new(name=>"dan",age=>33);"

    "my $sh2 = Set::Hash->new(qw/weight 185 height 72/);"

    "$sh1->length->print; # 2"

    "$sh1->push($sh2); # $sh1 now has weight=>185 and height=>72"

    "$sh1->length->print; # 4"

    "$sh2->values->join(",")->print(1); # 185, 72"

PREREQUISITES
    Perl 5.6 or later

    Set::Array .10 or later, by me. Available on CPAN.

    Want .05 or later, by Robin Houston. Available on CPAN.

DESCRIPTION
    Set::Hash allows you to create strings as objects and use OO-style
    methods on them. Many convenient methods are provided here that appear
    in the FAQ's, the Perl Cookbook or posts from comp.lang.perl.misc. In
    addition, there are Set methods with corresponding (overloaded)
    operators for the purpose of Set comparison, i.e. +, ==, etc.

    The purpose is to provide built-in methods for operations that people
    are always asking how to do, and which already exist in languages like
    Ruby. This should (hopefully) improve code readability and/or
    maintainability. The other advantage to this module is method-chaining
    by which any number of methods may be called on a single object in a
    single statement.

    Note that Set::Hash is a subclass of Set::Array, although most of the
    methods of Set::Array have been overloaded, so you'll want to check the
    documentation for what each method does exactly.

  OBJECT BEHAVIOR
    The exact behavior of the methods depends largely on the calling
    context.

    Here are the rules:

    * If a method is called in void context, the object itself is modified.

    * If the method called is not the last method in a chain (i.e. it's
    called in object context), the object itself is modified by that method
    regardless of the 'final' context or method call.

    * If a method is called in list or scalar context, a list or list
    refererence is returned, respectively. The object itself is NOT
    modified.

    Here are the exceptions:

    * Methods that report a value, such as boolean methods like *exists()*
    or other methods such as *equals()* or *not_equals()*, never modify the
    object.

    * The methods *clear()* and *delete()* will always modify the object. It
    seemed much too counterintuitive to call these methods in any context
    without actually deleting/clearing/substituting the items!

    * The methods *shift()* and *pop()* will modify the object AND return
    the key/value pair that was shifted or popped from the hash. Again, it
    seemed much too counterintuitive for something like "$val = $sh->shift"
    to return a value while leaving the object's list unchanged.

  INSTANCE METHODS
    delete(*keys*) - Deletes the specified *keys* from the hash. This method
    violates our normal context rules, in that it modifies the receiver,
    regardless of context.

    Returns an array or array reference of *values* that were deleted (not
    keys), in list or scalar context, respectively.

    exists(*keys*) - Returns 1 (true) if the specified key(s) exist, even if
    the corresponding value is undefined. Otherwise 0 (false) is returned.
    If multiple keys are specified, it returns true only if allkeys exist.

    keys - Returns an array of keys for the hash, or an array reference in
    scalar context.

    length - Returns the length of the hash, i.e. the number of pairs (not
    total elements).

    pop - An alias for *shift()*. This will change when support for ordered
    hashes is added.

    push(*args*) - Pushes a key/value pair onto the hash. If an odd number
    of elements is pushed, then the value for the odd key will be set to
    undef.

    Optionally, you may pass another *Set::Hash* object as the argument.

    reverse - Turns keys into values and values into keys. Returns a hash in
    list context, or a hash reference in scalar context.

    shift - Shifts a key/value pair off the hash. Returns a 2 element list
    in list context, or a hash reference in scalar context. You cannot
    predict the key/value pair that you will get in an unordered hash.

    Note that this rule violates our normal context rules. It always
    modifies the receiver, regardless of context.

    unshift - An alias for *push()*. This will change when support for
    ordered hashes is added.

    values - Returns an array of values for the hash, or an array reference
    in scalar context.

  OVERLOADED OPERATORS
    == or is_equal - Tests to see if the hashes have the same keys and the
    same values for those keys. Internal ordering is irrelevant for this
    test.

    Returns 0 on failure, 1 on success.

    != or not_equal - Opposite of *is_equal()*.

    Returns 0 on failure, 1 on success.

    - or difference(*object*) - Returns all the key/value pairs on the right
    side that aren't on the left side as a hash or hash reference, in list
    or scalar context, respectively.

    e.g.

    "my $sh1 = Set::Hash->new(qw/name dan age 33/);"

    "my $sh2 = Set::Hash->new(qw/name dan age 33 weight 185/);"

    "my $diff = $sh1->difference($sh2); # {weight => 185}"

    Note that both keys and values are used for this calcuation so {age=>33}
    is not the same as {age=>32}, for example.

    * or intersection(*object*) - Returns all they key/value pairs that are
    common to both hash objects. Returns a hash or hash reference in list or
    scalar context, respectively.

    + or union(*object*) - Returns the union of both sets. Since keys must
    be unique, keys of the right object will overwrite those on the left if
    they're identical.

    This is really an alias for the *push()* method.

KNOWN BUGS
    There is currently a bug in Want-0.05 that prevents use of most of the
    overloaded operators. However, the named version of those operators
    should work fine, e.g. "difference()" vs "-".

    Also, "==" and "!=" work fine.

FUTURE PLANS
    Optional ordered hash, using *Tie::IxHash*

    each()

    symmetric_difference()

    flatten()

    to_a()

AUTHOR
    Daniel J. Berger djberg96 at yahoo dot com

