1Set::Object(3) User Contributed Perl Documentation Set::Object(3)
2
6 Set::Object - set of objects and strings
7
9 use Set::Object qw(set);
10 my $set = set(); # or Set::Object->new()
12 $set->insert(@thingies);
14 $set->remove(@thingies);
15 @items = @$set; # or $set->members for the unsorted array
17 $union = $set1 + $set2;
19 $intersection = $set1 * $set2;
20 $difference = $set1 - $set2;
21 $symmetric_difference = $set1 % $set2;
22 print "set1 is a proper subset of set2"
24 if $set1 < $set2;
25 print "set1 is a subset of set2"
27 if $set1 <= $set2;
28 # common idiom - iterate over any pure Perl structure
30 use Set::Object qw(reftype);
31 my @stack = $root;
32 my $seen = Set::Object->new(@stack);
33 while (my $object = pop @stack) {
34 if (reftype $object eq "HASH") {
35 # do something with hash members
36 # add the new nodes to the stack
38 push @stack, grep { ref $_ && $seen->insert($_) }
39 values %$object;
40 }
41 elsif (reftype $object eq "ARRAY") {
42 # do something with array members
43 # add the new nodes to the stack
45 push @stack, grep { ref $_ && $seen->insert($_) }
46 @$object;
47 }
49 elsif (reftype $object =~ /SCALAR|REF/) {
50 push @stack, $$object
51 if ref $$object && $seen->insert($$object);
52 }
53 }
54
56 This modules implements a set of objects, that is, an unordered
57 collection of objects without duplication.
58 The term objects is applied loosely - for the sake of Set::Object,
60 anything that is a reference is considered an object.
61 Set::Object 1.09 and later includes support for inserting scalars
63 (including the empty string, but excluding "undef") as well as objects.
64 This can be thought of as (and is currently implemented as) a
65 degenerate hash that only has keys and no values. Unlike objects
66 placed into a Set::Object, scalars that are inserted will be flattened
67 into strings, so will lose any magic (eg, tie) or other special bits
68 that they went in with; only strings come out.
69
71 Set::Object->new( [list] )
72 Return a new "Set::Object" containing the elements passed in list.
73 set(@members)
75 Return a new "Set::Object" filled with @members. You have to
76 explicitly import this method.
77 New in Set::Object 1.22: this function is now called as a method to
79 return new sets the various methods that return a new set, such as
80 "->intersection", "->union", etc and their overloaded counterparts.
81 The default method always returns "Set::Object" objects, preserving
82 previous behaviour and not second guessing the nature of your derived
83 Set::Object class.
84 weak_set()
86 Return a new "Set::Object::Weak", filled with @members. You have to
87 explicitly import this method.
88
90 insert( [list] )
91 Add items to the "Set::Object".
92 Adding the same object several times is not an error, but any
94 "Set::Object" will contain at most one occurrence of the same object.
95 Returns the number of elements that were actually added. As of
97 Set::Object 1.23, "undef" will not insert.
98 includes( [list] )
100 has( [list] )
101 contains( [list] )
102 Return "true" if all the objects in list are members of the
103 "Set::Object". list may be empty, in which case "true" is always
104 returned.
105 As of Set::Object 1.23, "undef" will never appear to be present in any
107 set (even if the set contains the empty string). Prior to 1.23, there
108 would have been a run-time warning.
109 member( [item] )
111 element( [item] )
112 Like "includes", but takes a single item to check and returns that item
113 if the value is found, rather than just a true value.
114 members
116 elements
117 Return the objects contained in the "Set::Object" in random (hash)
118 order.
119 Note that the elements of a "Set::Object" in list context are returned
121 sorted - @$set - so using the "members" method is much faster.
122 size
124 Return the number of elements in the "Set::Object".
125 remove( [list] )
127 delete( [list] )
128 Remove objects from a "Set::Object".
129 Removing the same object more than once, or removing an object absent
131 from the "Set::Object" is not an error.
132 Returns the number of elements that were actually removed.
134 As of Set::Object 1.23, removing "undef" is safe (but having an "undef"
136 in the passed in list does not increase the return value, because it
137 could never be in the set)
138 weaken
140 Makes all the references in the set "weak" - that is, they do not
141 increase the reference count of the object they point to, just like
142 Scalar::Util's "weaken" function.
143 This was introduced with Set::Object 1.16, and uses a brand new type of
145 magic. Use with caution. If you get segfaults when you use "weaken",
146 please reduce your problem to a test script before submission.
147 New: as of Set::Object 1.19, you may use the "weak_set" function to
149 make weak sets, or "Set::Object::Weak->new", or import the "set"
150 constructor from "Set::Object::Weak" instead. See Set::Object::Weak
151 for more.
152 Note to people sub-classing "Set::Object": this method re-blesses the
154 invocant to "Set::Object::Weak". Override the method "weak_pkg" in
155 your sub-class to control this behaviour.
156 is_weak
158 Returns a true value if this set is a weak set.
159 strengthen
161 Turns a weak set back into a normal one.
162 Note to people sub-classing "Set::Object": this method re-blesses the
164 invocant to "Set::Object". Override the method "strong_pkg" in your
165 sub-class to control this behaviour.
166 invert( [list] )
168 For each item in list, it either removes it or adds it to the set, so
169 that a change is always made.
170 Also available as the overloaded operator "/", in which case it expects
172 another set (or a single scalar element), and returns a new set that is
173 the original set with all the second set's items inverted.
174 clear
176 Empty this "Set::Object".
177 as_string
179 Return a textual Smalltalk-ish representation of the "Set::Object".
180 Also available as overloaded operator "".
181 equal( set )
183 Returns a true value if set contains exactly the same members as the
184 invocant.
185 Also available as overloaded operator "==" (or "eq").
187 not_equal( set )
189 Returns a false value if set contains exactly the same members as the
190 invocant.
191 Also available as overloaded operator "!=" (or "ne").
193 intersection( [list] )
195 Return a new "Set::Object" containing the intersection of the
196 "Set::Object"s passed as arguments.
197 Also available as overloaded operator "*".
199 union( [list] )
201 Return a new "Set::Object" containing the union of the "Set::Object"s
202 passed as arguments.
203 Also available as overloaded operator "+".
205 difference ( set )
207 Return a new "Set::Object" containing the members of the first
208 (invocant) set with the passed "Set::Object"s' elements removed.
209 Also available as overloaded operator "-".
211 unique ( set )
213 symmetric_difference ( set )
214 Return a new "Set::Object" containing the members of all passed sets
215 (including the invocant), with common elements removed. This will be
216 the opposite (complement) of the intersection of the two sets.
217 Also available as overloaded operator "%".
219 subset( set )
221 Return "true" if this "Set::Object" is a subset of set.
222 Also available as operator "<=".
224 proper_subset( set )
226 Return "true" if this "Set::Object" is a proper subset of set Also
227 available as operator "<".
228 superset( set )
230 Return "true" if this "Set::Object" is a superset of set. Also
231 available as operator ">=".
232 proper_superset( set )
234 Return "true" if this "Set::Object" is a proper superset of set Also
235 available as operator ">".
236 is_null( set )
238 Returns a true value if this set does not contain any members, that is,
239 if its size is zero.
240
242 By and large, Set::Object is not and probably never will be feature-
243 compatible with Set::Scalar; however the following functions are
244 provided anyway.
245 compare( set )
247 returns one of:
248 "proper intersect"
250 "proper subset"
251 "proper superset"
252 "equal"
253 "disjoint"
254 is_disjoint( set )
256 Returns a true value if the two sets have no common items.
257 as_string_callback( set )
259 Allows you to define a custom stringify function. This is only a class
260 method. If you want anything fancier than this, you should sub-class
261 Set::Object.
262
264 The following functions are defined by the Set::Object XS code for
265 convenience; they are largely identical to the versions in the
266 Scalar::Util module, but there are a couple that provide functions not
267 catered to by that module.
268 Please use the versions in Scalar::Util in preference to these
270 functions. In fact, if you use these functions in your production code
271 then you may have to rewrite it some day. They are retained only
272 because they are "mostly harmless".
273 blessed
275 Do not use in production code
276 Returns a true value if the passed reference (RV) is blessed. See
278 also Acme::Holy.
279 reftype
281 Do not use in production code
282 A bit like the perl built-in "ref" function, but returns the type
284 of reference; ie, if the reference is blessed then it returns what
285 "ref" would have if it were not blessed. Useful for "seeing
286 through" blessed references.
287 refaddr
289 Do not use in production code
290 Returns the memory address of a scalar. Warning: this is not
292 guaranteed to be unique for scalars created in a program; memory
293 might get re-used!
294 is_int, is_string, is_double
296 Do not use in production code
297 A quick way of checking the three bits on scalars - IOK (is_int),
299 NOK (is_double) and POK (is_string). Note that the exact behaviour
300 of when these bits get set is not defined by the perl API.
301 This function returns the "p" versions of the macro (SvIOKp, etc);
303 use with caution.
304 is_overloaded
306 Do not use in production code
307 A quick way to check if an object has overload magic on it.
309 ish_int
311 Deprecated and will be removed in 2014
312 This function returns true, if the value it is passed looks like it
314 already is a representation of an integer. This is so that you can
315 decide whether the value passed is a hash key or an array index.
316 is_key
318 Deprecated and will be removed in 2014
319 This function returns true, if the value it is passed looks more
321 like an index to a collection than a value of a collection.
322 Similar to the looks_like_number internal function, but weird.
323 Avoid.
324 get_magic
326 Do not use in production code
327 Pass to a scalar, and get the magick wand ("mg_obj") used by the
329 weak set implementation. The return will be a list of integers
330 which are pointers to the actual "ISET" structure. Whatever you do
331 don't change the array :). This is used only by the test suite,
332 and if you find it useful for something then you should probably
333 conjure up a test suite and send it to me, otherwise it could get
334 pulled.
335
337 These class methods are probably only interesting to those sub-classing
338 "Set::Object".
339 strong_pkg
341 When a set that was already weak is strengthened using
342 "->strengthen", it gets re-blessed into this package.
343 weak_pkg
345 When a set that was NOT already weak is weakened using "->weaken",
346 it gets re-blessed into this package.
347 tie_array_pkg
349 When the object is accessed as an array, tie the array into this
350 package.
351 tie_hash_pkg
353 When the object is accessed as a hash, tie the hash into this
354 package.
355
357 It is possible to serialize "Set::Object" objects via Storable and
358 duplicate via "dclone"; such support was added in release 1.04. As of
359 "Set::Object" version 1.15, it is possible to freeze scalar items, too.
360 However, the support for freezing scalar items introduced a backwards
362 incompatibility. Earlier versions than 1.15 will "thaw" sets frozen
363 using Set::Object 1.15 and later as a set with one item - an array that
364 contains the actual members.
365 Additionally, version 1.15 had a bug that meant that it would not
367 detect "freeze" protocol upgrades, instead reverting to pre-1.15
368 behaviour.
369 "Set::Object" 1.16 and above are capable of dealing correctly with all
371 serialized forms, as well as correctly aborting if a "newer" "freeze"
372 protocol is detected during "thaw".
373
375 The following benchmark compares "Set::Object" with using a hash to
376 emulate a set-like collection (this is an old benchmark, but still
377 holds true):
378 use Set::Object;
380 package Obj;
382 sub new { bless { } }
383 @els = map { Obj->new() } 1..1000;
385 require Benchmark;
387 Benchmark::timethese(100, {
389 'Control' => sub { },
390 'H insert' => sub { my %h = (); @h{@els} = @els; },
391 'S insert' => sub { my $s = Set::Object->new(); $s->insert(@els) },
392 } );
393 %gh = ();
395 @gh{@els} = @els;
396 $gs = Set::Object->new(@els);
398 $el = $els[33];
399 Benchmark::timethese(100_000, {
401 'H lookup' => sub { exists $gh{33} },
402 'S lookup' => sub { $gs->includes($el) }
403 } );
404 On my computer the results are:
406 Benchmark: timing 100 iterations of Control, H insert, S insert...
408 Control: 0 secs ( 0.01 usr 0.00 sys = 0.01 cpu)
409 (warning: too few iterations for a reliable count)
410 H insert: 68 secs (67.81 usr 0.00 sys = 67.81 cpu)
411 S insert: 9 secs ( 8.81 usr 0.00 sys = 8.81 cpu)
412 Benchmark: timing 100000 iterations of H lookup, S lookup...
413 H lookup: 7 secs ( 7.14 usr 0.00 sys = 7.14 cpu)
414 S lookup: 6 secs ( 5.94 usr 0.00 sys = 5.94 cpu)
415 This benchmark compares the unsorted members method, against the sorted
417 @$ list context.
418 perl -MBenchmark -mList::Util -mSet::Object -e'
420 $set = Set::Object::set (List::Util::shuffle(1..1000));
421 Benchmark::timethese(-3, {
422 "Slow \@\$set " => sub { $i++ for @$set; },
423 "Fast set->members" => sub { $i++ for $set->members(); },
424 });'
425 Benchmark: running Fast set->members, Slow @$set for at least 3 CPU seconds...
427 Fast set->members: 4 wallclock secs ( 3.17 usr + 0.00 sys = 3.17 CPU) @ 9104.42/s (n=28861)
428 Slow @$set : 4 wallclock secs ( 3.23 usr + 0.00 sys = 3.23 CPU) @ 1689.16/s (n=5456)
429
431 This module is not thread-safe.
432
434 Original Set::Object module by Jean-Louis Leroy, <jll@skynet.be>
435 Set::Scalar compatibility, XS debugging, weak references support
437 courtesy of Sam Vilain, <samv@cpan.org>.
438 New maintainer is Reini Urban <rurban@cpan.org>. Patches against
440 <https://github.com/rurban/Set-Object/> please. Tickets at RT
441 <https://rt.cpan.org/Public/Dist/Display.html?Name=Set-Object>
442
444 Copyright (c) 1998-1999, Jean-Louis Leroy. All Rights Reserved. This
445 module is free software. It may be used, redistributed and/or modified
446 under the terms of the Perl Artistic License, either the original, or
447 at your option, any later version.
448 Portions Copyright (c) 2003 - 2005, Sam Vilain. Same license.
450 Portions Copyright (c) 2006, 2007, Catalyst IT (NZ) Limited. This
452 module is free software. It may be used, redistributed and/or modified
453 under the terms of the Perl Artistic License
454 Portions Copyright (c) 2013, cPanel. Same license. Portions Copyright
456 (c) 2020, Reini Urban. Same license.
457
459 perl(1), perltie(1), Set::Scalar, overload
460perl v5.36.0 2023-01-20 Set::Object(3)