/ 
Set-Object-1.05
River stage three • 48 direct dependents • 316 total dependents
/ Set::Object

NAME

Set::Object - set of objects

SYNOPSIS

use Set::Object;
$set = Set::Object->new();

DESCRIPTION

This modules implements a set of objects, that is, an unordered collection of objects without duplication.

CLASS METHODS

new( [list] )

Return a new Set::Object containing the elements passed in list. The elements must be objects.

INSTANCE METHODS

insert( [list] )

Add objects 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.

includes( [list] )

Return true if all the objects in list are members of the Set::Object. list may be empty, in which case true is returned.

members

Return the objects contained in the Set::Object.

size

Return the number of elements in the Set::Object.

remove( [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.

clear

Empty this Set::Object.

as_string

Return a textual Smalltalk-ish representation of the Set::Object. Also available as overloaded operator "".

intersection( [list] )

Return a new Set::Object containing the intersection of the Set::Objects passed as arguments. Also available as overloaded operator *.

union( [list] )

Return a new Set::Object containing the union of the Set::Objects passed as arguments. 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 >.

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.

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... <devious grin>.

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. Stay tuned for the answer.

INSTALLATION

This module is partly written in C, so you'll need a C compiler to install it. Use the familiar sequence:

perl Makefile.PL
make
make test
make install

This module was developed on Windows NT 4.0, using the Visual C++ compiler with Service Pack 2. It was also tested on AIX using IBM's xlc compiler.

PERFORMANCE

The following benchmark compares Set::Object with using a hash to emulate a set-like collection:

   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)

AUTHOR

Original Set::Object module by Jean-Louis Leroy, <jll@skynet.be>

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, Sam Vilain. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License

SEE ALSO

perl(1), perltie(1), overload.pm