/ 
Set-Object-1.00
River stage three • 47 direct dependents • 254 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 >.

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

Jean-Louis Leroy, jll@skynet.be

LICENCE

Copyright (c) 1998, 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

SEE ALSO

perl(1). overload.pm