NAME¶
Set::Tiny - Simple sets of strings
VERSION¶
Version 0.02
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.
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.
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
<
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