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

NAME

6       Set::Object - set of objects and strings
7

SYNOPSIS

9         use Set::Object qw(set);
10
11         my $set = set();            # or Set::Object->new()
12
13         $set->insert(@thingies);
14         $set->remove(@thingies);
15
16         @items = @$set;             # or $set->members for the unsorted array
17
18         $union = $set1 + $set2;
19         $intersection = $set1 * $set2;
20         $difference = $set1 - $set2;
21         $symmetric_difference = $set1 % $set2;
22
23         print "set1 is a proper subset of set2"
24             if $set1 < $set2;
25
26         print "set1 is a subset of set2"
27             if $set1 <= $set2;
28
29         # 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
37                 # 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
44                 # add the new nodes to the stack
45                 push @stack, grep { ref $_ && $seen->insert($_) }
46                     @$object;
47
48             }
49             elsif (reftype $object =~ /SCALAR|REF/) {
50                 push @stack, $$object
51                     if ref $$object && $seen->insert($$object);
52             }
53         }
54

DESCRIPTION

56       This modules implements a set of objects, that is, an unordered
57       collection of objects without duplication.
58
59       The term objects is applied loosely - for the sake of Set::Object,
60       anything that is a reference is considered an object.
61
62       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

CONSTRUCTORS

71   Set::Object->new( [list] )
72       Return a new "Set::Object" containing the elements passed in list.
73
74   set(@members)
75       Return a new "Set::Object" filled with @members.  You have to
76       explicitly import this method.
77
78       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
85   weak_set()
86       Return a new "Set::Object::Weak", filled with @members.  You have to
87       explicitly import this method.
88

INSTANCE METHODS

90   insert( [list] )
91       Add items to the "Set::Object".
92
93       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
96       Returns the number of elements that were actually added.  As of
97       Set::Object 1.23, "undef" will not insert.
98
99   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
106       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
110   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
115   members
116   elements
117       Return the objects contained in the "Set::Object" in random (hash)
118       order.
119
120       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
123   size
124       Return the number of elements in the "Set::Object".
125
126   remove( [list] )
127   delete( [list] )
128       Remove objects from a "Set::Object".
129
130       Removing the same object more than once, or removing an object absent
131       from the "Set::Object" is not an error.
132
133       Returns the number of elements that were actually removed.
134
135       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
139   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
144       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
148       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
153       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
157   is_weak
158       Returns a true value if this set is a weak set.
159
160   strengthen
161       Turns a weak set back into a normal one.
162
163       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
167   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
171       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
175   clear
176       Empty this "Set::Object".
177
178   as_string
179       Return a textual Smalltalk-ish representation of the "Set::Object".
180       Also available as overloaded operator "".
181
182   equal( set )
183       Returns a true value if set contains exactly the same members as the
184       invocant.
185
186       Also available as overloaded operator "==" (or "eq").
187
188   not_equal( set )
189       Returns a false value if set contains exactly the same members as the
190       invocant.
191
192       Also available as overloaded operator "!=" (or "ne").
193
194   intersection( [list] )
195       Return a new "Set::Object" containing the intersection of the
196       "Set::Object"s passed as arguments.
197
198       Also available as overloaded operator "*".
199
200   union( [list] )
201       Return a new "Set::Object" containing the union of the "Set::Object"s
202       passed as arguments.
203
204       Also available as overloaded operator "+".
205
206   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
210       Also available as overloaded operator "-".
211
212   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
218       Also available as overloaded operator "%".
219
220   subset( set )
221       Return "true" if this "Set::Object" is a subset of set.
222
223       Also available as operator "<=".
224
225   proper_subset( set )
226       Return "true" if this "Set::Object" is a proper subset of set Also
227       available as operator "<".
228
229   superset( set )
230       Return "true" if this "Set::Object" is a superset of set.  Also
231       available as operator ">=".
232
233   proper_superset( set )
234       Return "true" if this "Set::Object" is a proper superset of set Also
235       available as operator ">".
236
237   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

Set::Scalar compatibility methods

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
246   compare( set )
247       returns one of:
248
249         "proper intersect"
250         "proper subset"
251         "proper superset"
252         "equal"
253         "disjoint"
254
255   is_disjoint( set )
256       Returns a true value if the two sets have no common items.
257
258   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

FUNCTIONS

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
269       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
274       blessed
275           Do not use in production code
276
277           Returns a true value if the passed reference (RV) is blessed.  See
278           also Acme::Holy.
279
280       reftype
281           Do not use in production code
282
283           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
288       refaddr
289           Do not use in production code
290
291           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
295       is_int, is_string, is_double
296           Do not use in production code
297
298           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
302           This function returns the "p" versions of the macro (SvIOKp, etc);
303           use with caution.
304
305       is_overloaded
306           Do not use in production code
307
308           A quick way to check if an object has overload magic on it.
309
310       ish_int
311           Deprecated and will be removed in 2014
312
313           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
317       is_key
318           Deprecated and will be removed in 2014
319
320           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
325       get_magic
326           Do not use in production code
327
328           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

CLASS METHODS

337       These class methods are probably only interesting to those sub-classing
338       "Set::Object".
339
340       strong_pkg
341           When a set that was already weak is strengthened using
342           "->strengthen", it gets re-blessed into this package.
343
344       weak_pkg
345           When a set that was NOT already weak is weakened using "->weaken",
346           it gets re-blessed into this package.
347
348       tie_array_pkg
349           When the object is accessed as an array, tie the array into this
350           package.
351
352       tie_hash_pkg
353           When the object is accessed as a hash, tie the hash into this
354           package.
355

SERIALIZATION

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
361       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
366       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
370       "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

PERFORMANCE

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
379          use Set::Object;
380
381          package Obj;
382          sub new { bless { } }
383
384          @els = map { Obj->new() } 1..1000;
385
386          require Benchmark;
387
388          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
394          %gh = ();
395          @gh{@els} = @els;
396
397          $gs = Set::Object->new(@els);
398          $el = $els[33];
399
400          Benchmark::timethese(100_000, {
401                  'H lookup' => sub { exists $gh{33} },
402                  'S lookup' => sub { $gs->includes($el) }
403             } );
404
405       On my computer the results are:
406
407          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
416       This benchmark compares the unsorted members method, against the sorted
417       @$ list context.
418
419          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
426           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

THREAD SAFETY

431       This module is not thread-safe.
432

AUTHOR

434       Original Set::Object module by Jean-Louis Leroy, <jll@skynet.be>
435
436       Set::Scalar compatibility, XS debugging, weak references support
437       courtesy of Sam Vilain, <samv@cpan.org>.
438
439       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

LICENCE

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
449       Portions Copyright (c) 2003 - 2005, Sam Vilain.  Same license.
450
451       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
455       Portions Copyright (c) 2013, cPanel.  Same license.  Portions Copyright
456       (c) 2020, Reini Urban.  Same license.
457

SEE ALSO

459       perl(1), perltie(1), Set::Scalar, overload
460
461
462
463perl v5.36.0                      2023-01-20                    Set::Object(3)
Impressum