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;
19 $s = Set::Scalar->new(@members);
20 $t = $s->clone;
22 $t = $s->copy; # clone of clone
23 Modifying
25 $s->insert(@members);
27 $s->delete(@members);
28 $s->invert(@members); # insert if hasn't, delete if has
29 $s->clear; # removes all the elements
31 Note that clear() only releases the memory used by the set to be reused
33 by Perl; it will not reduce the overall memory use.
34 Displaying
36 print $s, "\n";
38 The display format of a set is the members of the set separated by spa‐
40 ces and enclosed in parentheses ().
41 You can even display recursive sets.
43 See "Customising Display" for customising the set display.
45 Querying
47 @members = $s->members;
49 @elements = $s->elements; # alias for members
50 $size = $s->size; # the number of members
52 $s->has($m) # return true if has that member
54 $s->contains($m) # alias for has
55 if ($s->has($member)) { ... }
57 $s->member($m) # returns the member if has that member
59 $s->element($m) # alias for member
60 $s->is_null # returns true if the set is empty
62 $s->is_empty # alias for is_null
63 $s->is_universal # returns true if the set is universal
64 $s->null # the null set
66 $s->empty # alias for null
67 $s->universe # the universe of the set
68 Deriving
70 $u = $s->union($t);
72 $i = $s->intersection($t);
73 $d = $s->difference($t);
74 $e = $s->symmetric_difference($t);
75 $v = $s->unique($t);
76 $c = $s->complement;
77 These methods have operator overloads:
79 $u = $s + $t; # union
81 $i = $s * $t; # intersection
82 $d = $s - $t; # difference
83 $e = $s % $t; # symmetric_difference
84 $v = $s / $t; # unique
85 $c = -$s; # complement
86 Both the "symmetric_difference" and "unique" are symmetric on all their
88 arguments. For two sets they are identical but for more than two sets
89 beware: "symmetric_difference" returns true for elements that are in an
90 odd number (1, 3, 5, ...) of sets, "unique" returns true for elements
91 that are in one set.
92 Some examples of the various set differences:
94 set or difference value
96 $a (a b c d e)
98 $b (c d e f g)
99 $c (e f g h i)
100 $a->difference($b) (a b)
102 $a->symmetric_difference($b) (a b f g)
103 $a->unique($b) (a b f g)
104 $b->difference($a) (f g)
106 $b->symmetric_difference($a) (a b f g)
107 $b->unique($a) (a b f g)
108 $a->difference($b, $c) (a b)
110 $a->symmetric_difference($b, $c) (a b e h i)
111 $a->unique($b, $c) (a b h i)
112 Comparing
114 $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
144 if ($set) { ... }
146 while ($set1 && $set2) { ... }
147 the size of the $set is tested, so empty sets test as false, and non-
149 empty sets as true.
150 Iterating
152 while (defined(my $e = $s->each)) { ... }
154 This is more memory-friendly than
156 for my $e ($s->elements) { ... }
158 which would first construct the full list of elements and then walk
160 through it: the "$s->each" handles one element at a time.
161 Analogously to using normal "each(%hash)" in scalar context, using
163 "$s->each" has the following caveats:
164 · The elements are returned in (apparently) random order. So don't
166 expect any particular order.
167 · When no more elements remain "undef" is returned. Since you may
169 one day have elements named 0 don't test just like this
170 while (my $e = $s->each) { ... } # WRONG
172 but instead like this
174 while (defined(my $e = $s->each)) { ... } # right
176 (An "undef" as a set element doesn't really work, you get "".)
178 · There is one iterator per one set which is shared by many element-
180 accessing interfaces-- using the following will reset the iterator:
181 elements(), insert(), members(), size(), unique(). insert() causes
182 the iterator of the set being inserted (not the set being the tar‐
183 get of insertion) becoming reset. unique() causes the iterators of
184 all the participant sets becoming reset. The iterator getting
185 reset most probably causes an endless loop. So avoid doing that.
186 · Modifying the set during the iteration may cause elements to be
188 missed or duplicated, or in the worst case, an endless loop; so
189 don't do that, either.
190 Customising Display
192 If you want to customise the display routine you will have to modify
194 the "as_string" callback. You can modify it either for all sets by
195 using "as_string_callback()" as a class method:
196 my $class_callback = sub { ... };
198 Set::Scalar->as_string_callback($class_callback);
200 or for specific sets by using "as_string_callback()" as an object
202 method:
203 my $callback = sub { ... };
205 $s1->as_string_callback($callback);
207 $s2->as_string_callback($callback);
208 The anonymous subroutine gets as its first (and only) argument the set
210 to display as a string. For example to display the set $s as
211 "a-b-c-d-e" instead of "(a b c d e)"
212 $s->as_string_callback(sub{join("-",sort $_[0]->elements)});
214 If called without an argument, the current callback is returned.
216 If called as a class method with undef as the only argument, the origi‐
218 nal callback (the one returning "(a b c d e)") for all the sets is
219 restored, or if called for a single set the callback is removed (and
220 the callback for all the sets will be used).
221
223 The first priority of Set::Scalar is to be a convenient interface to
224 sets. While not designed to be slow or big, neither has it been
225 designed to be fast or compact.
226 Using references (or objects) as set members has not been extensively
228 tested. The desired semantics are not always clear: what should happen
229 when the elements behind the references change? Especially unclear is
230 what should happen when the objects start having their own stringifica‐
231 tion overloads.
232
234 Set::Bag for bags (multisets, counted sets), and Bit::Vector for fast
235 set operations (you have to take care of the element name to bit number
236 and back mappings yourself), or Set::Infinite for sets of intervals,
237 and many more. CPAN is your friend.
238
240 Jarkko Hietaniemi <jhi@iki.fi>
241
243 Copyright 2001,2002,2003,2004 by Jarkko Hietaniemi
244 This library is free software; you can redistribute it and/or modify it
246 under the same terms as Perl itself.
247perl v5.8.8 2001-10-22 Set::Scalar(3)