.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Set::Tiny 3pm"
.TH Set::Tiny 3pm "2014-09-25" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Set::Tiny \- Simple sets of strings
.SH "VERSION"
.IX Header "VERSION"
Version 0.02
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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]);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
For a more complete implementation of mathematical set theory, see
Set::Scalar. For sets of arbitrary objects, see Set::Object.
.SS "Why Set::Tiny?"
.IX Subsection "Why Set::Tiny?"
.IP "Convenience" 4
.IX Item "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 \f(CW\*(C`for\*(C'\fR loops (in fact, that's exactly what Set::Tiny does).
.IP "Speed" 4
.IX Item "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 \fIexamples/benchmark.pl\fR for a (non-representative) comparison
between different \f(CW\*(C`Set::\*(C'\fR modules.
.IP "Ease of use" 4
.IX Item "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.
.SH "EXPORTABLE FUNCTIONS"
.IX Header "EXPORTABLE FUNCTIONS"
.SS "set( [\fIlist or arrayref\fP] )"
.IX Subsection "set( [list or arrayref] )"
If you request it, Set::Tiny can export a function \f(CW\*(C`set()\*(C'\fR, which lets you
create a Set::Tiny instance in a more compact form.
.PP
Unlike the constructor, this function also accepts the set elements as an array
reference.
.SH "METHODS"
.IX Header "METHODS"
Note that all methods that expect a \fIlist\fR of set elements stringify
their arguments before inserting them into the set.
.SS "new( [\fIlist\fP] )"
.IX Subsection "new( [list] )"
Class method. Returns a new Set::Tiny object, initialized with the strings in
\&\fIlist\fR, or the empty set if \fIlist\fR is empty.
.SS "clone"
.IX Subsection "clone"
.SS "copy"
.IX Subsection "copy"
Returns a new set with the same elements as this one.
.SS "insert( [\fIlist\fP] )"
.IX Subsection "insert( [list] )"
Inserts the elements in \fIlist\fR into the set.
.SS "delete( [\fIlist\fP] )"
.IX Subsection "delete( [list] )"
.SS "remove( [\fIlist\fP] )"
.IX Subsection "remove( [list] )"
Removes the elements in \fIlist\fR from the set. Elements that are not
members of the set are ignored.
.SS "invert( [\fIlist\fP] )"
.IX Subsection "invert( [list] )"
For each element in \fIlist\fR, if it is already a member of the set,
deletes it from the set, else insert it into the set.
.SS "clear"
.IX Subsection "clear"
Removes all elements from the set.
.SS "as_string"
.IX Subsection "as_string"
Returns a string representation of the set.
.SS "elements"
.IX Subsection "elements"
.SS "members"
.IX Subsection "members"
Returns the (unordered) list of elements.
.SS "size"
.IX Subsection "size"
Returns the number of elements.
.SS "has( [\fIlist\fP] )"
.IX Subsection "has( [list] )"
.SS "contains( [\fIlist\fP] )"
.IX Subsection "contains( [list] )"
Returns true if \fBall\fR of the elements in \fIlist\fR are members of the set. If
\&\fIlist\fR is empty, returns true.
.SS "element( [\fIstring\fP] )"
.IX Subsection "element( [string] )"
.SS "member( [\fIstring\fP] )"
.IX Subsection "member( [string] )"
Returns the string if it is contained in the set.
.SS "is_null"
.IX Subsection "is_null"
.SS "is_empty"
.IX Subsection "is_empty"
Returns true if the set is the empty set.
.SS "union( \fIset\fP )"
.IX Subsection "union( set )"
Returns a new set containing both the elements of this set and \fIset\fR.
.SS "intersection( \fIset\fP )"
.IX Subsection "intersection( set )"
Returns a new set containing the elements that are present in both this
set and \fIset\fR.
.SS "difference( \fIset\fP )"
.IX Subsection "difference( set )"
Returns a new set containing the elements of this set with the elements
of \fIset\fR removed.
.SS "unique( \fIset\fP )"
.IX Subsection "unique( set )"
.SS "symmetric_difference( \fIset\fP )"
.IX Subsection "symmetric_difference( set )"
Returns a new set containing the elements that are present in either this set
or \fIset\fR, but not in both.
.SS "is_equal( \fIset\fP )"
.IX Subsection "is_equal( set )"
Returns true if this set contains the same elements as \fIset\fR.
.SS "is_disjoint( \fIset\fP )"
.IX Subsection "is_disjoint( set )"
Returns true if this set has no elements in common with \fIset\fR. Note that the
empty set is disjoint to any other set.
.SS "is_properly_intersecting( \fIset\fP )"
.IX Subsection "is_properly_intersecting( set )"
Returns true if this set has elements in common with \fIset\fR, but both
also contain elements that they have not in common with each other.
.SS "is_proper_subset( \fIset\fP )"
.IX Subsection "is_proper_subset( set )"
Returns true if this set is a proper subset of \fIset\fR.
.SS "is_proper_superset( \fIset\fP )"
.IX Subsection "is_proper_superset( set )"
Returns true if this set is a proper superset of \fIset\fR.
.SS "is_subset( \fIset\fP )"
.IX Subsection "is_subset( set )"
Returns true if this set is a subset of \fIset\fR.
.SS "is_superset( \fIset\fP )"
.IX Subsection "is_superset( set )"
Returns true if this set is a superset of \fIset\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Stanis Trendelenburg, \f(CW\*(C`<trendels at cpan.org>\*(C'\fR
.SH "CREDITS"
.IX Header "CREDITS"
Thanks to Adam Kennedy for advice on how to make this module \f(CW\*(C`Tiny\*(C'\fR.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to \f(CW\*(C`bug\-set\-tiny at rt.cpan.org\*(C'\fR, 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.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2009 Stanis Trendelenburg, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Set::Scalar, Set::Object