1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
NAME
Set::Tiny - Simple sets of strings
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".
SEE ALSO
* Set::Scalar
BUGS
Please report any bugs or feature requests on the bugtracker website
<https://github.com/haarg/Set-Tiny/issues>
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.
CONTRIBUTORS
* Alberto Manuel Brandão Simões <ambs@cpan.org>
* Alceu Rodrigues de Freitas Junior <glasswalk3r@yahoo.com.br>
* brian greenfield <briang@cpan.org>
* Graham Knop <haarg@haarg.org>
* Ricky Morse <remorse@mgh.harvard.edu>
* Stanis Trendelenburg <stanis.trendelenburg@gmail.com>
AUTHOR
Stanis Trendelenburg <trendels@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2024 by Stanis Trendelenburg.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
|
