Set::Scalar(3pm)

1Set::Scalar(3)        User Contributed Perl Documentation       Set::Scalar(3)
2
3
4

NAME

6       Set::Scalar - basic set operations
7

SYNOPSIS

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

DESCRIPTION

16   Creating
17           $s = Set::Scalar->new;
18           $s = Set::Scalar->new(@members);
19
20           $t = $s->clone;
21           $t = $s->copy;         # Clone of clone.
22           $t = $s->empty_clone;  # Like clone() but with no members.
23
24   Modifying
25           $s->insert(@members);
26           $s->delete(@members);
27           $s->invert(@members);  # Insert if hasn't, delete if has.
28
29           $s->clear;  # Removes all the elements.
30
31       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
34   Displaying
35           print $s, "\n";
36
37       The display format of a set is the members of the set separated by
38       spaces and enclosed in parentheses (), for example:
39
40          my $s = Set::Scalar->new();
41          $s->insert("a".."e");
42          print $s, "\n";
43
44       will output
45
46          a b c d e
47
48       You can even display recursive sets.
49
50       See "Customising Display" for customising the set display.
51
52   Querying
53       Assuming a set $s:
54
55           @members  = $s->members;
56           @elements = $s->elements;  # Alias for members.
57
58           @$s  # Overloaded alias for members.
59
60           $size = $s->size;  # The number of members.
61
62           $s->has($m)        # Return true if has that member.
63           $s->contains($m)   # Alias for has().
64
65           if ($s->has($member)) { ... }
66
67           $s->member($m)     # Returns the member if has that member.
68           $s->element($m)    # Alias for member.
69
70           $s->is_null        # Returns true if the set is empty.
71           $s->is_empty       # Alias for is_null.
72
73           $s->is_universal   # Returns true if the set is universal.
74
75           $s->null           # The null set.
76           $s->empty          # Alias for null.
77           $s->universe       # The universe of the set.
78
79   Deriving
80           $u = $s->union($t);
81           $i = $s->intersection($t);
82           $d = $s->difference($t);
83           $e = $s->symmetric_difference($t);
84           $v = $s->unique($t);
85           $c = $s->complement;
86
87       These methods have operator overloads:
88
89           $u = $s + $t;  # union
90           $i = $s * $t;  # intersection
91           $d = $s - $t;  # difference
92           $e = $s % $t;  # symmetric_difference
93           $v = $s / $t;  # unique
94           $c = -$s;      # complement
95
96       Both the "symmetric_difference" and "unique" are symmetric on all their
97       arguments.  For two sets they are identical but for more than two sets
98       beware: "symmetric_difference" returns true for elements that are in an
99       odd number (1, 3, 5, ...) of sets, "unique" returns true for elements
100       that are in one set.
101
102       Some examples of the various set differences below (the _ is just used
103       to align the elements):
104
105           set or difference                   value
106
107           $a                                  (a b c d e _ _ _ _)
108           $b                                  (_ _ c d e f g _ _)
109           $c                                  (_ _ _ _ e f g h i)
110
111           $a->difference($b)                  (a b _ _ _ _ _ _ _)
112           $a->symmetric_difference($b)        (a b _ _ _ f g _ _)
113           $a->unique($b)                      (a b _ _ _ f g _ _)
114
115           $b->difference($a)                  (_ _ _ _ _ f g _ _)
116           $b->symmetric_difference($a)        (a b _ _ _ f g _ _)
117           $b->unique($a)                      (a b _ _ _ f g _ _)
118
119           $a->difference($b, $c)              (a b _ _ _ _ _ _ _)
120           $a->symmetric_difference($b, $c)    (a b _ _ e _ _ h i)
121           $a->unique($b, $c)                  (a b _ _ _ _ _ h i)
122
123   Comparing
124           $eq = $s->is_equal($t);
125           $dj = $s->is_disjoint($t);
126           $pi = $s->is_properly_intersecting($t);
127           $ps = $s->is_proper_subset($t);
128           $pS = $s->is_proper_superset($t);
129           $is = $s->is_subset($t);
130           $iS = $s->is_superset($t);
131
132           $cmp = $s->compare($t);
133
134       The "compare" method returns a string from the following list: "equal",
135       "disjoint", "proper subset", "proper superset", "proper intersect", and
136       in future (once I get around implementing it), "disjoint universes".
137
138       These methods have operator overloads:
139
140           $eq = $s == $t;  # is_equal
141           $dj = $s != $t;  # is_disjoint
142           # No operator overload for is_properly_intersecting.
143           $ps = $s < $t;   # is_proper_subset
144           $pS = $s > $t;   # is_proper_superset
145           $is = $s <= $t;  # is_subset
146           $iS = $s >= $t;  # is_superset
147
148           $cmp = $s <=> $t;
149
150   Boolean contexts
151       In Boolean contexts such as
152
153           if ($set) { ... }
154           while ($set1 && $set2) { ... }
155
156       the size of the $set is tested, so empty sets test as false, and non-
157       empty sets as true.
158
159   Iterating
160           while (defined(my $e = $s->each)) { ... }
161
162       This is more memory-friendly than
163
164           for my $e ($s->elements) { ... }
165
166       which would first construct the full list of elements and then walk
167       through it: the "$s->each" handles one element at a time.
168
169       Analogously to using normal "each(%hash)" in scalar context, using
170       "$s->each" has the following caveats:
171
172       •   The elements are returned in (apparently) random order.  So don't
173           expect any particular order.
174
175       •   When no more elements remain "undef" is returned.  Since you may
176           one day have elements named 0 don't test just like this
177
178               while (my $e = $s->each) { ... }           # WRONG!
179
180           but instead like this
181
182               while (defined(my $e = $s->each)) { ... }  # Right.
183
184           (An "undef" as a set element doesn't really work, you get "".)
185
186       •   There is one iterator per one set which is shared by many element-
187           accessing interfaces-- using the following will reset the iterator:
188           "elements()", "insert()", "members()", "size()", "unique()".
189           "insert()" causes the iterator of the set being inserted (not the
190           set being the target of insertion) becoming reset.  "unique()"
191           causes the iterators of all the participant sets becoming reset.
192           The iterator getting reset most probably causes an endless loop. So
193           avoid doing that.
194
195           For "delete()" the story is a little bit more complex: it depends
196           on what element you are deleting and on the version of Perl.  On
197           modern Perls you can safely delete the element you just deleted.
198           But deleting random elements can affect the iterator, so beware.
199
200       •   Modifying the set during the iteration may cause elements to be
201           missed or duplicated, or in the worst case, an endless loop; so
202           don't do that, either.
203
204   Cartesian Product and Power Set
205       •   Cartesian product is a product of two or more sets.  For two sets,
206           it is the set consisting of ordered pairs of members from each set.
207           For example for the sets
208
209             (a b)
210             (c d e)
211
212           The Cartesian product of the above is the set
213
214             ([a, c] [a, d] [a, e] [b, c] [b, d] [b, e])
215
216           The [,] notation is for the ordered pairs, which sets are not.
217           This means two things: firstly, that [e, b] is not in the above
218           Cartesian product, and secondly, [b, b] is a possibility:
219
220             (a b)
221             (b c e)
222
223             ([a, b] [a, c] [a, e] [b, b] [b, c] [b, d])
224
225           For example:
226
227             my $a = Set::Scalar->new(1..2);
228             my $b = Set::Scalar->new(3..5);
229             my $c = $a->cartesian_product($b);  # As an object method.
230             my $d = Set::Scalar->cartesian_product($a, $b);  # As a class method.
231
232           The $c and $d will be of the same class as $a.  The members of $c
233           and $c in the above will be anonymous arrays (array references),
234           not sets, since sets wouldn't be able to represent the ordering or
235           that a member can be present more than once.  Also note that since
236           the members of the input sets are unordered, the ordered pairs
237           themselves are unlikely to be in any particular order.
238
239           If you don't want to construct the Cartesian product set, you can
240           construct an iterator and call it while it returns more members:
241
242              my $iter = Set::Scalar->cartesian_product_iterator($a, $b, $c);
243              while (my @m = $iter->()) {
244                process(@m);
245              }
246
247       •   Power set is the set of all the subsets of a set.  If the set has N
248           members, its power set has 2**N members.  For example for the set
249
250               (a b c)
251
252           size 3, its power set is
253
254               (() (a) (b) (c) (a b) (a c) (b c) (a b c))
255
256           size 8.  Note that since the elements of the power set are sets,
257           they are unordered, and therefore (b c) is equal to (c b).  For
258           example:
259
260               my $a = Set::Scalar->new(1..3);
261               my $b = $a->power_set;               # As an object method.
262               my $c = Set::Scalar->power_set($a);  # As a class method.
263
264           Even the empty set has a power set, of size one.
265
266           If you don't want to construct the power set, you can construct an
267           iterator and call it until it returns no more members:
268
269              my $iter = Set::Scalar->power_set_iterator($a);
270              my @m;
271              do {
272                @m = $iter->();
273                process(@m);
274              } while (@m);
275
276   Customising Display
277       If you want to customise the display routine you will have to modify
278       the "as_string" callback.  You can modify it either for all sets by
279       using "as_string_callback()" as a class method:
280
281           my $class_callback = sub { ... };
282
283           Set::Scalar->as_string_callback($class_callback);
284
285       or for specific sets by using "as_string_callback()" as an object
286       method:
287
288           my $callback = sub  { ... };
289
290           $s1->as_string_callback($callback);
291           $s2->as_string_callback($callback);
292
293       The anonymous subroutine gets as its first (and only) argument the set
294       to display as a string.  For example to display the set $s as
295       "a-b-c-d-e" instead of "(a b c d e)"
296
297           $s->as_string_callback(sub{join("-",sort $_[0]->elements)});
298
299       If called without an argument, the current callback is returned.
300
301       If called as a class method with undef as the only argument, the
302       original callback (the one returning "(a b c d e)") for all the sets is
303       restored, or if called for a single set the callback is removed (and
304       the callback for all the sets will be used).
305

CAVEATS

307       The first priority of Set::Scalar is to be a convenient interface to
308       sets.  While not designed to be slow or big, neither has it been
309       designed to be fast or compact.
310
311       Using references (or objects) as set members has not been extensively
312       tested.  The desired semantics are not always clear: what should happen
313       when the elements behind the references change? Especially unclear is
314       what should happen when the objects start having their own
315       stringification overloads.
316

AUTHOR

324       Jarkko Hietaniemi <jhi@iki.fi> David Oswald <davido@cpan.org> is the
325       current maintainer.  The GitHub repo is at
326       <https://github.com/daoswald/Set-Scalar>
327

COPYRIGHT AND LICENSE

329       Copyright 2001,2002,2003,2004,2005,2007,2009,2013 by Jarkko Hietaniemi
330
331       This library is free software; you can redistribute it and/or modify it
332       under the same terms as Perl itself.
333
334
335
336perl v5.34.0                      2022-01-21                    Set::Scalar(3)

NAME

SYNOPSIS

DESCRIPTION

CAVEATS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE