NAME

       Set::Tiny - Simple sets of strings

VERSION

       Version 0.04

SYNOPSIS

           use Set::Tiny;

           my $s1 = Set::Tiny->new(qw( a b c ));
           my $s2 = Set::Tiny->new(qw( b c d ));

           my $u  = $s1->union($s2);
           my $i  = $s1->intersection($s2);
           my $s  = $s1->symmetric_difference($s2);

           print $u->as_string; # (a b c d)
           print $i->as_string; # (b c)
           print $s->as_string; # (a d)

           print "i is a subset of s1"   if $i->is_subset($s1);
           print "u is a superset of s1" if $u->is_superset($s1);

           # or using the shorter initializer:

           use Set::Tiny qw( set );

           my $s1 = set(qw( a b c ));
           my $s2 = set([1, 2, 3]);

DESCRIPTION

       Set::Tiny is a thin wrapper around regular Perl hashes to perform often needed set
       operations, such as testing two sets of strings for equality, or checking whether one is
       contained within the other.

       For a more complete implementation of mathematical set theory, see Set::Scalar. For sets
       of arbitrary objects, see Set::Object.

   Why Set::Tiny?
       Convenience
           Set::Tiny aims to provide a convenient interface to commonly used set operations,
           which you would usually implement using regular hashes and a couple of "for" loops (in
           fact, that's exactly what Set::Tiny does).

       Speed
           The price in performance you pay for this convenience when using a full-featured set
           implementation like Set::Scalar is way too high if you don't actually need the
           advanced functionality it offers.  Run examples/benchmark.pl for a (non-
           representative) comparison between different "Set::" modules.

       Ease of use
           Set::Object offers better performance than Set::Scalar, but needs a C compiler to
           install. Set::Tiny has no dependencies and contains no C code.

EXPORTABLE FUNCTIONS

   set( [list or arrayref] )
       If you request it, Set::Tiny can export a function "set()", which lets you create a
       Set::Tiny instance in a more compact form.

       Unlike the constructor, this function also accepts the set elements as an array reference.

       If you pass an existing Set::Tiny to the initializer, it creates a clone of the set and
       returns that.

METHODS

       Note that all methods that expect a list of set elements stringify their arguments before
       inserting them into the set.

   new( [list] )
       Class method. Returns a new Set::Tiny object, initialized with the strings in list, or the
       empty set if list is empty.

   clone
   copy
       Returns a new set with the same elements as this one.

   insert( [list] )
       Inserts the elements in list into the set.

   delete( [list] )
   remove( [list] )
       Removes the elements in list from the set. Elements that are not members of the set are
       ignored.

   invert( [list] )
       For each element in list, if it is already a member of the set, deletes it from the set,
       else insert it into the set.

   clear
       Removes all elements from the set.

   as_string
       Returns a string representation of the set.

   elements
   members
       Returns the (unordered) list of elements.

   size
       Returns the number of elements.

   has( [list] )
   contains( [list] )
       Returns true if all of the elements in list are members of the set. If list is empty,
       returns true.

   element( [string] )
   member( [string] )
       Returns the string if it is contained in the set.

   is_null
   is_empty
       Returns true if the set is the empty set.

   union( set )
       Returns a new set containing both the elements of this set and set.

   intersection( set )
       Returns a new set containing the elements that are present in both this set and set.

   intersection2( set )
       Like "intersection()", but orders the sets by size before comparing their elements. This
       results in a small overhead for small, evenly sized sets, but a large speedup when
       comparing bigger (~ 100 elements) and very unevenly sized sets.

   difference( set )
       Returns a new set containing the elements of this set with the elements of set removed.

   unique( set )
   symmetric_difference( set )
       Returns a new set containing the elements that are present in either this set or set, but
       not in both.

   is_equal( set )
       Returns true if this set contains the same elements as set.

   is_disjoint( set )
       Returns true if this set has no elements in common with set. Note that the empty set is
       disjoint to any other set.

   is_properly_intersecting( set )
       Returns true if this set has elements in common with set, but both also contain elements
       that they have not in common with each other.

   is_proper_subset( set )
       Returns true if this set is a proper subset of set.

   is_proper_superset( set )
       Returns true if this set is a proper superset of set.

   is_subset( set )
       Returns true if this set is a subset of set.

   is_superset( set )
       Returns true if this set is a superset of set.

AUTHOR

       Stanis Trendelenburg, "<trendels at cpan.org>"

CREDITS

       Thanks to Adam Kennedy for advice on how to make this module "Tiny".

BUGS

       Please report any bugs or feature requests to "bug-set-tiny at rt.cpan.org", or through
       the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Set-Tiny>.  I will be
       notified, and then you'll automatically be notified of progress on your bug as I make
       changes.

COPYRIGHT & LICENSE

       Copyright 2009 Stanis Trendelenburg, all rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SEE ALSO

       Set::Scalar, Set::Object