1Set::Scalar(3) User Contributed Perl Documentation Set::Scalar(3)
2
6 Set::Scalar - basic set operations
7
9 use Set::Scalar;
10 $s = Set::Scalar->new;
11 $s->insert('a', 'b');
12 $s->delete('b');
13 $t = Set::Scalar->new('x', 'y', $z);
14
16 Creating
17 $s = Set::Scalar->new;
18 $s = Set::Scalar->new(@members);
19 $t = $s->clone;
21 $t = $s->copy; # Clone of clone.
22 $t = $s->empty_clone; # Like clone() but with no members.
23 Modifying
25 $s->insert(@members);
26 $s->delete(@members);
27 $s->invert(@members); # Insert if hasn't, delete if has.
28 $s->clear; # Removes all the elements.
30 Note that clear() only releases the memory used by the set to be reused
32 by Perl; it will not reduce the overall memory use.
33 Displaying
35 print $s, "\n";
36 The display format of a set is the members of the set separated by
38 spaces and enclosed in parentheses ().
39 You can even display recursive sets.
41 See "Customising Display" for customising the set display.
43 Querying
45 Assuming a set $s:
46 @members = $s->members;
48 @elements = $s->elements; # Alias for members.
49 @$s # Overloaded alias for members.
51 $size = $s->size; # The number of members.
53 $s->has($m) # Return true if has that member.
55 $s->contains($m) # Alias for has().
56 if ($s->has($member)) { ... }
58 $s->member($m) # Returns the member if has that member.
60 $s->element($m) # Alias for member.
61 $s->is_null # Returns true if the set is empty.
63 $s->is_empty # Alias for is_null.
64 $s->is_universal # Returns true if the set is universal.
66 $s->null # The null set.
68 $s->empty # Alias for null.
69 $s->universe # The universe of the set.
70 Deriving
72 $u = $s->union($t);
73 $i = $s->intersection($t);
74 $d = $s->difference($t);
75 $e = $s->symmetric_difference($t);
76 $v = $s->unique($t);
77 $c = $s->complement;
78 These methods have operator overloads:
80 $u = $s + $t; # union
82 $i = $s * $t; # intersection
83 $d = $s - $t; # difference
84 $e = $s % $t; # symmetric_difference
85 $v = $s / $t; # unique
86 $c = -$s; # complement
87 Both the "symmetric_difference" and "unique" are symmetric on all their
89 arguments. For two sets they are identical but for more than two sets
90 beware: "symmetric_difference" returns true for elements that are in an
91 odd number (1, 3, 5, ...) of sets, "unique" returns true for elements
92 that are in one set.
93 Some examples of the various set differences:
95 set or difference value
97 $a (a b c d e)
99 $b (c d e f g)
100 $c (e f g h i)
101 $a->difference($b) (a b)
103 $a->symmetric_difference($b) (a b f g)
104 $a->unique($b) (a b f g)
105 $b->difference($a) (f g)
107 $b->symmetric_difference($a) (a b f g)
108 $b->unique($a) (a b f g)
109 $a->difference($b, $c) (a b)
111 $a->symmetric_difference($b, $c) (a b e h i)
112 $a->unique($b, $c) (a b h i)
113 Comparing
115 $eq = $s->is_equal($t);
116 $dj = $s->is_disjoint($t);
117 $pi = $s->is_properly_intersecting($t);
118 $ps = $s->is_proper_subset($t);
119 $pS = $s->is_proper_superset($t);
120 $is = $s->is_subset($t);
121 $iS = $s->is_superset($t);
122 $cmp = $s->compare($t);
124 The "compare" method returns a string from the following list: "equal",
126 "disjoint", "proper subset", "proper superset", "proper intersect", and
127 in future (once I get around implementing it), "disjoint universes".
128 These methods have operator overloads:
130 $eq = $s == $t; # is_equal
132 $dj = $s != $t; # is_disjoint
133 # No operator overload for is_properly_intersecting.
134 $ps = $s < $t; # is_proper_subset
135 $pS = $s > $t; # is_proper_superset
136 $is = $s <= $t; # is_subset
137 $iS = $s >= $t; # is_superset
138 $cmp = $s <=> $t;
140 Boolean contexts
142 In Boolean contexts such as
143 if ($set) { ... }
145 while ($set1 && $set2) { ... }
146 the size of the $set is tested, so empty sets test as false, and non-
148 empty sets as true.
149 Iterating
151 while (defined(my $e = $s->each)) { ... }
152 This is more memory-friendly than
154 for my $e ($s->elements) { ... }
156 which would first construct the full list of elements and then walk
158 through it: the "$s->each" handles one element at a time.
159 Analogously to using normal "each(%hash)" in scalar context, using
161 "$s->each" has the following caveats:
162 · The elements are returned in (apparently) random order. So don't
164 expect any particular order.
165 · When no more elements remain "undef" is returned. Since you may
167 one day have elements named 0 don't test just like this
168 while (my $e = $s->each) { ... } # WRONG!
170 but instead like this
172 while (defined(my $e = $s->each)) { ... } # Right.
174 (An "undef" as a set element doesn't really work, you get "".)
176 · There is one iterator per one set which is shared by many element-
178 accessing interfaces-- using the following will reset the iterator:
179 elements(), insert(), members(), size(), unique(). insert() causes
180 the iterator of the set being inserted (not the set being the
181 target of insertion) becoming reset. unique() causes the iterators
182 of all the participant sets becoming reset. The iterator getting
183 reset most probably causes an endless loop. So avoid doing that.
184 · Modifying the set during the iteration may cause elements to be
186 missed or duplicated, or in the worst case, an endless loop; so
187 don't do that, either.
188 Cartesian Product and Power Set
190 · Cartesian product is a product of two or more sets. For two sets,
191 it is the set consisting of ordered pairs of members from each set.
192 For example for the sets
193 (a b)
195 (c d e)
196 The Cartesian product of the above is the set
198 ([a, c] [a, d] [a, e] [b, c] [b, d] [b, e])
200 The [,] notation is for the ordered pairs, which sets are are not.
202 This means two things: firstly, that [e, b] is not in the above
203 Cartesian product, and secondly, [b, b] is a possibility:
204 (a b)
206 (b c e)
207 ([a, b] [a, c] [a, e] [b, b] [b, c] [b, d])
209 For example:
211 my $a = Set::Scalar->new(1..2);
213 my $b = Set::Scalar->new(3..5);
214 my $c = $a->cartesian_product($b); # As an object method.
215 my $d = Set::Scalar->cartesian_product($a, $b); # As a class method.
216 The $c and $d will be of the same class as $a. The members of $c
218 and $c in the above will be anonymous arrays (array references),
219 not sets, since sets wouldn't be able to represent the ordering or
220 that a member can be present more than once. Also note that since
221 the members of the input sets are unordered, the ordered pairs
222 themselves are unlikely to be in any particular order.
223 If you don't want to construct the Cartesian product set, you can
225 construct an iterator and call it while it returns more members:
226 my $iter = Set::Scalar->cartesian_product_iterator($a, $b, $c);
228 while (my @m = $iter->()) {
229 process(@m);
230 }
231 · Power set is the set of all the subsets of a set. If the set has N
233 members, its power set has 2**N members. For example for the set
234 (a b c)
236 size 3, its power set is
238 (() (a) (b) (c) (a b) (a c) (b c) (a b c))
240 size 8. Note that since the elements of the power set are sets,
242 they are unordered, and therefore (b c) is equal to (c b). For
243 example:
244 my $a = Set::Scalar->new(1..3);
246 my $b = $a->power_set; # As an object method.
247 my $c = Set::Scalar->power_set($a); # As a class method.
248 Even the empty set has a power set, of size one.
250 If you don't want to construct the power set, you can construct an
252 iterator and call it until it returns no more members:
253 my $iter = Set::Scalar->power_set($a);
255 my @m;
256 do {
257 @m = $iter->();
258 process(@m);
259 } while (@m);
260 Customising Display
262 If you want to customise the display routine you will have to modify
263 the "as_string" callback. You can modify it either for all sets by
264 using "as_string_callback()" as a class method:
265 my $class_callback = sub { ... };
267 Set::Scalar->as_string_callback($class_callback);
269 or for specific sets by using "as_string_callback()" as an object
271 method:
272 my $callback = sub { ... };
274 $s1->as_string_callback($callback);
276 $s2->as_string_callback($callback);
277 The anonymous subroutine gets as its first (and only) argument the set
279 to display as a string. For example to display the set $s as
280 "a-b-c-d-e" instead of "(a b c d e)"
281 $s->as_string_callback(sub{join("-",sort $_[0]->elements)});
283 If called without an argument, the current callback is returned.
285 If called as a class method with undef as the only argument, the
287 original callback (the one returning "(a b c d e)") for all the sets is
288 restored, or if called for a single set the callback is removed (and
289 the callback for all the sets will be used).
290
292 The first priority of Set::Scalar is to be a convenient interface to
293 sets. While not designed to be slow or big, neither has it been
294 designed to be fast or compact.
295 Using references (or objects) as set members has not been extensively
297 tested. The desired semantics are not always clear: what should happen
298 when the elements behind the references change? Especially unclear is
299 what should happen when the objects start having their own
300 stringification overloads.
301
303 Set::Bag for bags (multisets, counted sets), and Bit::Vector for fast
304 set operations (you have to take care of the element name to bit number
305 and back mappings yourself), or Set::Infinite for sets of intervals,
306 and many more. CPAN is your friend.
307
309 Jarkko Hietaniemi <jhi@iki.fi>
310
312 Copyright 2001,2002,2003,2004,2005,2007,2009 by Jarkko Hietaniemi
313 This library is free software; you can redistribute it and/or modify it
315 under the same terms as Perl itself.
316perl v5.12.0 2009-12-27 Set::Scalar(3)