Set::Object(3) User Contributed Perl Documentation Set::Object(3)NAMESet::Object - set of objects and strings
SYNOPSIS
use Set::Object;
my $set = set(); # or Set::Object->new()
$set->insert(@thingies);
$set->remove(@thingies);
@items = @$set; # or $set->members;
$union = $set1 + $set2;
$intersection = $set1 * $set2;
$difference = $set1 - $set2;
$symmetric_difference = $set1 % $set2;
print "set1 is a proper subset of set2"
if $set1 < $set2;
print "set1 is a subset of set2"
if $set1 <= $set2;
# common idiom - iterate over any pure Perl structure
use Set::Objectqw(reftype);
my @stack = $root;
my $seen = Set::Object->new(@stack);
while (my $object = pop @stack) {
if (reftype $object eq "HASH") {
# do something with hash members
# add the new nodes to the stack
push @stack, grep { ref $_ && $seen->insert($_) }
values %$object;
}
elsif (reftype $object eq "ARRAY") {
# do something with array members
# add the new nodes to the stack
push @stack, grep { ref $_ && $seen->insert($_) }
@$object;
}
elsif (reftype $object =~ /SCALAR|REF/) {
push @stack, $$object
if ref $$object && $seen->insert($$object);
}
}
DESCRIPTION
This modules implements a set of objects, that is, an unordered
collection of objects without duplication.
The term objects is applied loosely - for the sake of Set::Object,
anything that is a reference is considered an object.
Set::Object 1.09 and later includes support for inserting scalars
(including the empty string, but excluding "undef") as well as objects.
This can be thought of as (and is currently implemented as) a
degenerate hash that only has keys and no values. Unlike objects
placed into a Set::Object, scalars that are inserted will be flattened
into strings, so will lose any magic (eg, tie) or other special bits
that they went in with; only strings come out.
CONSTRUCTORS
Set::Object->new( [list] )
Return a new "Set::Object" containing the elements passed in list.
"set(@members)"
Return a new "Set::Object" filled with @members. You have to
explicitly import this method.
New in Set::Object 1.22: this function is now called as a method to
return new sets the various methods that return a new set, such as
"->intersection", "->union", etc and their overloaded counterparts.
The default method always returns "Set::Object" objects, preserving
previous behaviour and not second guessing the nature of your derived
Set::Object class.
"weak_set()"
Return a new "Set::Object::Weak", filled with @members. You have to
explicitly import this method.
INSTANCE METHODS
insert( [list] )
Add items to the "Set::Object".
Adding the same object several times is not an error, but any
"Set::Object" will contain at most one occurence of the same object.
Returns the number of elements that were actually added. As of
Set::Object 1.23, "undef" will not insert.
includes( [list] )
has( [list] )
contains( [list] )
Return "true" if all the objects in list are members of the
"Set::Object". list may be empty, in which case "true" is always
returned.
As of Set::Object 1.23, "undef" will never appear to be present in any
set (even if the set contains the empty string). Prior to 1.23, there
would have been a run-time warning.
member( [item] )
element( [item] )
Like "includes", but takes a single item to check and returns that item
if the value is found, rather than just a true value.
members
elements
Return the objects contained in the "Set::Object" in random (hash)
order.
size
Return the number of elements in the "Set::Object".
remove( [list] )
delete( [list] )
Remove objects from a "Set::Object".
Removing the same object more than once, or removing an object absent
from the "Set::Object" is not an error.
Returns the number of elements that were actually removed.
As of Set::Object 1.23, removing "undef" is safe (but having an "undef"
in the passed in list does not increase the return value, because it
could never be in the set)
weaken
Makes all the references in the set "weak" - that is, they do not
increase the reference count of the object they point to, just like
Scalar::Util's "weaken" function.
This was introduced with Set::Object 1.16, and uses a brand new type of
magic. Use with caution. If you get segfaults when you use "weaken",
please reduce your problem to a test script before submission.
New: as of Set::Object 1.19, you may use the "weak_set" function to
make weak sets, or "Set::Object::Weak->new", or import the "set"
constructor from "Set::Object::Weak" instead. See Set::Object::Weak
for more.
Note to people sub-classing "Set::Object": this method re-blesses the
invocant to "Set::Object::Weak". Override the method "weak_pkg" in
your sub-class to control this behaviour.
is_weak
Returns a true value if this set is a weak set.
strengthen
Turns a weak set back into a normal one.
Note to people sub-classing "Set::Object": this method re-blesses the
invocant to "Set::Object". Override the method "strong_pkg" in your
sub-class to control this behaviour.
invert( [list] )
For each item in list, it either removes it or adds it to the set, so
that a change is always made.
Also available as the overloaded operator "/", in which case it expects
another set (or a single scalar element), and returns a new set that is
the original set with all the second set's items inverted.
clear
Empty this "Set::Object".
as_string
Return a textual Smalltalk-ish representation of the "Set::Object".
Also available as overloaded operator "".
equal( set )
Returns a true value if set contains exactly the same members as the
invocant.
Also available as overloaded operator "==" (or "eq").
not_equal( set )
Returns a false value if set contains exactly the same members as the
invocant.
Also available as overloaded operator "!=" (or "ne").
intersection( [list] )
Return a new "Set::Object" containing the intersection of the
"Set::Object"s passed as arguments.
Also available as overloaded operator "*".
union( [list] )
Return a new "Set::Object" containing the union of the "Set::Object"s
passed as arguments.
Also available as overloaded operator "+".
difference ( set )
Return a new "Set::Object" containing the members of the first
(invocant) set with the passed "Set::Object"s' elements removed.
Also available as overloaded operator "-".
unique ( set )
symmetric_difference ( set )
Return a new "Set::Object" containing the members of all passed sets
(including the invocant), with common elements removed. This will be
the opposite (complement) of the intersection of the two sets.
Also available as overloaded operator "%".
subset( set )
Return "true" if this "Set::Object" is a subset of set.
Also available as operator "<=".
proper_subset( set )
Return "true" if this "Set::Object" is a proper subset of set Also
available as operator "<".
superset( set )
Return "true" if this "Set::Object" is a superset of set. Also
available as operator ">=".
proper_superset( set )
Return "true" if this "Set::Object" is a proper superset of set Also
available as operator ">".
is_null( set )
Returns a true value if this set does not contain any members, that is,
if its size is zero.
Set::Scalar compatibility methods
By and large, Set::Object is not and probably never will be feature-
compatible with Set::Scalar; however the following functions are
provided anyway.
compare( set )
returns one of:
"proper intersect"
"proper subset"
"proper superset"
"equal"
"disjoint"
is_disjoint( set )
Returns a true value if the two sets have no common items.
as_string_callback( set )
Allows you to define a custom stringify function. This is only a class
method. If you want anything fancier than this, you should sub-class
Set::Object.
FUNCTIONS
The following functions are defined by the Set::Object XS code for
convenience; they are largely identical to the versions in the
Scalar::Util module, but there are a couple that provide functions not
catered to by that module.
Please use the versions in Scalar::Util in preference to these
functions.
blessed
Returns a true value if the passed reference (RV) is blessed. See
also Acme::Holy.
reftype
A bit like the perl built-in "ref" function, but returns the type
of reference; ie, if the reference is blessed then it returns what
"ref" would have if it were not blessed. Useful for "seeing
through" blessed references.
refaddr
Returns the memory address of a scalar. Warning: this is not
guaranteed to be unique for scalars created in a program; memory
might get re-used!
is_int, is_string, is_double
A quick way of checking the three bits on scalars - IOK (is_int),
NOK (is_double) and POK (is_string). Note that the exact behaviour
of when these bits get set is not defined by the perl API.
This function returns the "p" versions of the macro (SvIOKp, etc);
use with caution.
is_overloaded
A quick way to check if an object has overload magic on it.
ish_int
This function returns true, if the value it is passed looks like it
already is a representation of an integer. This is so that you can
decide whether the value passed is a hash key or an array index.
is_key
This function returns true, if the value it is passed looks more
like an index to a collection than a value of a collection.
But wait, you say - Set::Object has no indices, one of the
fundamental properties of a Set is that it is an unordered
collection. Which means no indices. Well, if this module were
ever to be derived to be a more general multi-purpose collection,
then this (and "ish_int") might be a good function to use to
distinguish different types of indexes from values.
get_magic
Pass to a scalar, and get the magick wand ("mg_obj") used by the
weak set implementation. The return will be a list of integers
which are pointers to the actual "ISET" structure. Whatever you do
don't change the array :). This is used only by the test suite,
and if you find it useful for something then you should probably
conjure up a test suite and send it to me, otherwise it could get
pulled.
CLASS METHODS
These class methods are probably only interesting to those sub-classing
"Set::Object".
strong_pkg
When a set that was already weak is strengthened using
"->strengthen", it gets re-blessed into this package.
weak_pkg
When a set that was NOT already weak is weakened using "->weaken",
it gets re-blessed into this package.
tie_array_pkg
When the object is accessed as an array, tie the array into this
package.
tie_hash_pkg
When the object is accessed as a hash, tie the hash into this
package.
SERIALIZATION
It is possible to serialize "Set::Object" objects via Storable and
duplicate via "dclone"; such support was added in release 1.04. As of
"Set::Object" version 1.15, it is possible to freeze scalar items, too.
However, the support for freezing scalar items introduced a backwards
incompatibility. Earlier versions than 1.15 will "thaw" sets frozen
using Set::Object 1.15 and later as a set with one item - an array that
contains the actual members.
Additionally, version 1.15 had a bug that meant that it would not
detect "freeze" protocol upgrades, instead reverting to pre-1.15
behaviour.
"Set::Object" 1.16 and above are capable of dealing correctly with all
serialized forms, as well as correctly aborting if a "newer" "freeze"
protocol is detected during "thaw".
PERFORMANCE
The following benchmark compares "Set::Object" with using a hash to
emulate a set-like collection (this is an old benchmark, but still
holds true):
use Set::Object;
package Obj;
sub new { bless { } }
@els = map { Obj->new() } 1..1000;
require Benchmark;
Benchmark::timethese(100, {
'Control' => sub { },
'H insert' => sub { my %h = (); @h{@els} = @els; },
'S insert' => sub { my $s = Set::Object->new(); $s->insert(@els) },
} );
%gh = ();
@gh{@els} = @els;
$gs = Set::Object->new(@els);
$el = $els[33];
Benchmark::timethese(100_000, {
'H lookup' => sub { exists $gh{33} },
'S lookup' => sub { $gs->includes($el) }
} );
On my computer the results are:
Benchmark: timing 100 iterations of Control, H insert, S insert...
Control: 0 secs ( 0.01 usr 0.00 sys = 0.01 cpu)
(warning: too few iterations for a reliable count)
H insert: 68 secs (67.81 usr 0.00 sys = 67.81 cpu)
S insert: 9 secs ( 8.81 usr 0.00 sys = 8.81 cpu)
Benchmark: timing 100000 iterations of H lookup, S lookup...
H lookup: 7 secs ( 7.14 usr 0.00 sys = 7.14 cpu)
S lookup: 6 secs ( 5.94 usr 0.00 sys = 5.94 cpu)
THREAD SAFETY
This module has none.
AUTHOR
Original Set::Object module by Jean-Louis Leroy, <jll@skynet.be>
Set::Scalar compatibility, XS debugging, weak references support and
general maintainership courtesy of Sam Vilain, <samv@cpan.org>.
Maximum respect to those who send me test scripts, enhancements, etc as
patches against my git tree, browsable at
http://utsl.gen.nz/gitweb/?p=Set-Object
<http://utsl.gen.nz/gitweb/?p=Set-Object>.
LICENCE
Copyright (c) 1998-1999, Jean-Louis Leroy. All Rights Reserved. This
module is free software. It may be used, redistributed and/or modified
under the terms of the Perl Artistic License
Portions Copyright (c) 2003 - 2005, Sam Vilain. Same license.
Portions Copyright (c) 2006, 2007, Catalyst IT (NZ) Limited. Same
license.
SEE ALSOperl(1), perltie(1), Set::Scalar, overload.pm
perl v5.14.1 2008-10-12 Set::Object(3)
