1Set::Object(3) User Contributed Perl Documentation Set::Object(3)
2
6 Set::Object - set of objects and strings
7
9 use Set::Object;
10 my $set = set(); # or Set::Object->new()
12 $set->insert(@thingies);
14 $set->remove(@thingies);
15 @items = @$set; # or $set->members;
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 occurence 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 size
121 Return the number of elements in the "Set::Object".
122 remove( [list] )
124 delete( [list] )
125 Remove objects from a "Set::Object".
126 Removing the same object more than once, or removing an object absent
128 from the "Set::Object" is not an error.
129 Returns the number of elements that were actually removed.
131 As of Set::Object 1.23, removing "undef" is safe (but having an "undef"
133 in the passed in list does not increase the return value, because it
134 could never be in the set)
135 weaken
137 Makes all the references in the set "weak" - that is, they do not
138 increase the reference count of the object they point to, just like
139 Scalar::Util's "weaken" function.
140 This was introduced with Set::Object 1.16, and uses a brand new type of
142 magic. Use with caution. If you get segfaults when you use "weaken",
143 please reduce your problem to a test script before submission.
144 New: as of Set::Object 1.19, you may use the "weak_set" function to
146 make weak sets, or "Set::Object::Weak->new", or import the "set"
147 constructor from "Set::Object::Weak" instead. See Set::Object::Weak
148 for more.
149 Note to people sub-classing "Set::Object": this method re-blesses the
151 invocant to "Set::Object::Weak". Override the method "weak_pkg" in
152 your sub-class to control this behaviour.
153 is_weak
155 Returns a true value if this set is a weak set.
156 strengthen
158 Turns a weak set back into a normal one.
159 Note to people sub-classing "Set::Object": this method re-blesses the
161 invocant to "Set::Object". Override the method "strong_pkg" in your
162 sub-class to control this behaviour.
163 invert( [list] )
165 For each item in list, it either removes it or adds it to the set, so
166 that a change is always made.
167 Also available as the overloaded operator "/", in which case it expects
169 another set (or a single scalar element), and returns a new set that is
170 the original set with all the second set's items inverted.
171 clear
173 Empty this "Set::Object".
174 as_string
176 Return a textual Smalltalk-ish representation of the "Set::Object".
177 Also available as overloaded operator "".
178 equal( set )
180 Returns a true value if set contains exactly the same members as the
181 invocant.
182 Also available as overloaded operator "==" (or "eq").
184 not_equal( set )
186 Returns a false value if set contains exactly the same members as the
187 invocant.
188 Also available as overloaded operator "!=" (or "ne").
190 intersection( [list] )
192 Return a new "Set::Object" containing the intersection of the
193 "Set::Object"s passed as arguments.
194 Also available as overloaded operator "*".
196 union( [list] )
198 Return a new "Set::Object" containing the union of the "Set::Object"s
199 passed as arguments.
200 Also available as overloaded operator "+".
202 difference ( set )
204 Return a new "Set::Object" containing the members of the first
205 (invocant) set with the passed "Set::Object"s' elements removed.
206 Also available as overloaded operator "-".
208 unique ( set )
210 symmetric_difference ( set )
211 Return a new "Set::Object" containing the members of all passed sets
212 (including the invocant), with common elements removed. This will be
213 the opposite (complement) of the intersection of the two sets.
214 Also available as overloaded operator "%".
216 subset( set )
218 Return "true" if this "Set::Object" is a subset of set.
219 Also available as operator "<=".
221 proper_subset( set )
223 Return "true" if this "Set::Object" is a proper subset of set Also
224 available as operator "<".
225 superset( set )
227 Return "true" if this "Set::Object" is a superset of set. Also
228 available as operator ">=".
229 proper_superset( set )
231 Return "true" if this "Set::Object" is a proper superset of set Also
232 available as operator ">".
233 is_null( set )
235 Returns a true value if this set does not contain any members, that is,
236 if its size is zero.
237
239 By and large, Set::Object is not and probably never will be feature-
240 compatible with Set::Scalar; however the following functions are
241 provided anyway.
242 compare( set )
244 returns one of:
245 "proper intersect"
247 "proper subset"
248 "proper superset"
249 "equal"
250 "disjoint"
251 is_disjoint( set )
253 Returns a true value if the two sets have no common items.
254 as_string_callback( set )
256 Allows you to define a custom stringify function. This is only a class
257 method. If you want anything fancier than this, you should sub-class
258 Set::Object.
259
261 The following functions are defined by the Set::Object XS code for
262 convenience; they are largely identical to the versions in the
263 Scalar::Util module, but there are a couple that provide functions not
264 catered to by that module.
265 Please use the versions in Scalar::Util in preference to these
267 functions.
268 blessed
270 Returns a true value if the passed reference (RV) is blessed. See
271 also Acme::Holy.
272 reftype
274 A bit like the perl built-in "ref" function, but returns the type
275 of reference; ie, if the reference is blessed then it returns what
276 "ref" would have if it were not blessed. Useful for "seeing
277 through" blessed references.
278 refaddr
280 Returns the memory address of a scalar. Warning: this is not
281 guaranteed to be unique for scalars created in a program; memory
282 might get re-used!
283 is_int, is_string, is_double
285 A quick way of checking the three bits on scalars - IOK (is_int),
286 NOK (is_double) and POK (is_string). Note that the exact behaviour
287 of when these bits get set is not defined by the perl API.
288 This function returns the "p" versions of the macro (SvIOKp, etc);
290 use with caution.
291 is_overloaded
293 A quick way to check if an object has overload magic on it.
294 ish_int
296 This function returns true, if the value it is passed looks like it
297 already is a representation of an integer. This is so that you can
298 decide whether the value passed is a hash key or an array index.
299 is_key
301 This function returns true, if the value it is passed looks more
302 like an index to a collection than a value of a collection.
303 But wait, you say - Set::Object has no indices, one of the
305 fundamental properties of a Set is that it is an unordered
306 collection. Which means no indices. Well, if this module were
307 ever to be derived to be a more general multi-purpose collection,
308 then this (and "ish_int") might be a good function to use to
309 distinguish different types of indexes from values.
310 get_magic
312 Pass to a scalar, and get the magick wand ("mg_obj") used by the
313 weak set implementation. The return will be a list of integers
314 which are pointers to the actual "ISET" structure. Whatever you do
315 don't change the array :). This is used only by the test suite,
316 and if you find it useful for something then you should probably
317 conjure up a test suite and send it to me, otherwise it could get
318 pulled.
319
321 These class methods are probably only interesting to those sub-classing
322 "Set::Object".
323 strong_pkg
325 When a set that was already weak is strengthened using
326 "->strengthen", it gets re-blessed into this package.
327 weak_pkg
329 When a set that was NOT already weak is weakened using "->weaken",
330 it gets re-blessed into this package.
331 tie_array_pkg
333 When the object is accessed as an array, tie the array into this
334 package.
335 tie_hash_pkg
337 When the object is accessed as a hash, tie the hash into this
338 package.
339
341 It is possible to serialize "Set::Object" objects via Storable and
342 duplicate via "dclone"; such support was added in release 1.04. As of
343 "Set::Object" version 1.15, it is possible to freeze scalar items, too.
344 However, the support for freezing scalar items introduced a backwards
346 incompatibility. Earlier versions than 1.15 will "thaw" sets frozen
347 using Set::Object 1.15 and later as a set with one item - an array that
348 contains the actual members.
349 Additionally, version 1.15 had a bug that meant that it would not
351 detect "freeze" protocol upgrades, instead reverting to pre-1.15
352 behaviour.
353 "Set::Object" 1.16 and above are capable of dealing correctly with all
355 serialized forms, as well as correctly aborting if a "newer" "freeze"
356 protocol is detected during "thaw".
357
359 The following benchmark compares "Set::Object" with using a hash to
360 emulate a set-like collection (this is an old benchmark, but still
361 holds true):
362 use Set::Object;
364 package Obj;
366 sub new { bless { } }
367 @els = map { Obj->new() } 1..1000;
369 require Benchmark;
371 Benchmark::timethese(100, {
373 'Control' => sub { },
374 'H insert' => sub { my %h = (); @h{@els} = @els; },
375 'S insert' => sub { my $s = Set::Object->new(); $s->insert(@els) },
376 } );
377 %gh = ();
379 @gh{@els} = @els;
380 $gs = Set::Object->new(@els);
382 $el = $els[33];
383 Benchmark::timethese(100_000, {
385 'H lookup' => sub { exists $gh{33} },
386 'S lookup' => sub { $gs->includes($el) }
387 } );
388 On my computer the results are:
390 Benchmark: timing 100 iterations of Control, H insert, S insert...
392 Control: 0 secs ( 0.01 usr 0.00 sys = 0.01 cpu)
393 (warning: too few iterations for a reliable count)
394 H insert: 68 secs (67.81 usr 0.00 sys = 67.81 cpu)
395 S insert: 9 secs ( 8.81 usr 0.00 sys = 8.81 cpu)
396 Benchmark: timing 100000 iterations of H lookup, S lookup...
397 H lookup: 7 secs ( 7.14 usr 0.00 sys = 7.14 cpu)
398 S lookup: 6 secs ( 5.94 usr 0.00 sys = 5.94 cpu)
399
401 This module has none.
402
404 Original Set::Object module by Jean-Louis Leroy, <jll@skynet.be>
405 Set::Scalar compatibility, XS debugging, weak references support and
407 general maintainership courtesy of Sam Vilain, <samv@cpan.org>.
408 Maximum respect to those who send me test scripts, enhancements, etc as
409 patches against my git tree, browsable at
410 http://utsl.gen.nz/gitweb/?p=Set-Object
411 <http://utsl.gen.nz/gitweb/?p=Set-Object>.
412
414 Copyright (c) 1998-1999, Jean-Louis Leroy. All Rights Reserved. This
415 module is free software. It may be used, redistributed and/or modified
416 under the terms of the Perl Artistic License
417 Portions Copyright (c) 2003 - 2005, Sam Vilain. Same license.
419 Portions Copyright (c) 2006, 2007, Catalyst IT (NZ) Limited. Same
421 license.
422
424 perl(1), perltie(1), Set::Scalar, overload.pm
425perl v5.12.0 2008-10-12 Set::Object(3)