Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Set::Object.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Object 3"
.TH Object 3 "2003-09-02" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Set::Object \- set of objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Set::Object;
\&  $set = Set::Object->new();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This modules implements a set of objects, that is, an unordered
collection of objects without duplication.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.Sh "new( [\fIlist\fP] )"
.IX Subsection "new( [list] )"
Return a new \f(CW\*(C`Set::Object\*(C'\fR containing the elements passed in \fIlist\fR.
The elements must be objects.
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.Sh "insert( [\fIlist\fP] )"
.IX Subsection "insert( [list] )"
Add objects to the \f(CW\*(C`Set::Object\*(C'\fR.
Adding the same object several times is not an error,
but any \f(CW\*(C`Set::Object\*(C'\fR will contain at most one occurence of the
same object.
Returns the number of elements that were actually added.
.Sh "includes( [\fIlist\fP] )"
.IX Subsection "includes( [list] )"
Return \f(CW\*(C`true\*(C'\fR if all the objects in \fIlist\fR are members of the \f(CW\*(C`Set::Object\*(C'\fR.
\&\fIlist\fR may be empty, in which case \f(CW\*(C`true\*(C'\fR is returned.
.Sh "members"
.IX Subsection "members"
Return the objects contained in the \f(CW\*(C`Set::Object\*(C'\fR.
.Sh "size"
.IX Subsection "size"
Return the number of elements in the \f(CW\*(C`Set::Object\*(C'\fR.
.Sh "remove( [\fIlist\fP] )"
.IX Subsection "remove( [list] )"
Remove objects from a \f(CW\*(C`Set::Object\*(C'\fR.
Removing the same object more than once, or removing an object
absent from the \f(CW\*(C`Set::Object\*(C'\fR is not an error.
Returns the number of elements that were actually removed.
.Sh "clear"
.IX Subsection "clear"
Empty this \f(CW\*(C`Set::Object\*(C'\fR.
.Sh "as_string"
.IX Subsection "as_string"
Return a textual Smalltalk-ish representation of the \f(CW\*(C`Set::Object\*(C'\fR.
Also available as overloaded operator "".
.Sh "intersection( [\fIlist\fP] )"
.IX Subsection "intersection( [list] )"
Return a new \f(CW\*(C`Set::Object\*(C'\fR containing the intersection of the 
\&\f(CW\*(C`Set::Object\*(C'\fRs passed as arguments.
Also available as overloaded operator *.
.Sh "union( [\fIlist\fP] )"
.IX Subsection "union( [list] )"
Return a new \f(CW\*(C`Set::Object\*(C'\fR containing the union of the 
\&\f(CW\*(C`Set::Object\*(C'\fRs passed as arguments.
Also available as overloaded operator +.
.Sh "subset( \fIset\fP )"
.IX Subsection "subset( set )"
Return \f(CW\*(C`true\*(C'\fR if this \f(CW\*(C`Set::Object\*(C'\fR is a subset of \fIset\fR.
Also available as operator <=.
.Sh "proper_subset( \fIset\fP )"
.IX Subsection "proper_subset( set )"
Return \f(CW\*(C`true\*(C'\fR if this \f(CW\*(C`Set::Object\*(C'\fR is a proper subset of \fIset\fR
Also available as operator <.
.Sh "superset( \fIset\fP )"
.IX Subsection "superset( set )"
Return \f(CW\*(C`true\*(C'\fR if this \f(CW\*(C`Set::Object\*(C'\fR is a superset of \fIset\fR.
Also available as operator >=.
.Sh "proper_superset( \fIset\fP )"
.IX Subsection "proper_superset( set )"
Return \f(CW\*(C`true\*(C'\fR if this \f(CW\*(C`Set::Object\*(C'\fR is a proper superset of \fIset\fR
Also available as operator >.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
The following functions are defined by the Set::Object \s-1XS\s0 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.
.IP "\fBblessed\fR" 4
.IX Item "blessed"
Returns a true value if the passed reference (\s-1RV\s0) is blessed.  See
also Acme::Holy.
.IP "\fBreftype\fR" 4
.IX Item "reftype"
A bit like the perl built-in \f(CW\*(C`ref\*(C'\fR function, but returns the \fItype\fR
of reference; ie, if the reference is blessed then it returns what
\&\f(CW\*(C`ref\*(C'\fR would have if it were not blessed.  Useful for \*(L"seeing through\*(R"
blessed references.
.IP "\fBrefaddr\fR" 4
.IX Item "refaddr"
Returns the memory address of a scalar.  \fBWarning\fR: this is \fInot\fR
guaranteed to be unique for scalars created in a program; memory might
get re\-used!
.IP "\fBis_int\fR, \fBis_string\fR, \fBis_double\fR" 4
.IX Item "is_int, is_string, is_double"
A quick way of checking the three bits on scalars \- \s-1IOK\s0 (is_int), \s-1NOK\s0
(is_double) and \s-1POK\s0 (is_string).  Note that the exact behaviour of
when these bits get set is not defined by the perl \s-1API\s0.
.Sp
This function returns the \*(L"p\*(R" versions of the macro (SvIOKp, etc); use
with caution.
.IP "\fBis_overloaded\fR" 4
.IX Item "is_overloaded"
A quick way to check if an object has overload magic on it.
.IP "\fBish_int\fR" 4
.IX Item "ish_int"
This function returns true, if the value it is passed looks like it
\&\fIalready is\fR a representation of an \fIinteger\fR.  This is so that you
can decide whether the value passed is a hash key or an array
index... <devious grin>.
.IP "\fBis_key\fR" 4
.IX Item "is_key"
This function returns true, if the value it is passed looks more like
an \fIindex\fR to a collection than a \fIvalue\fR of a collection.
.Sp
But wait, you say \- Set::Object has no indices, one of the fundamental
properties of a Set is that it is an \fIunordered collection\fR.  Which
means \fIno indices\fR.  Stay tuned for the answer.
.SH "INSTALLATION"
.IX Header "INSTALLATION"
This module is partly written in C, so you'll need a C compiler to
install it.  Use the familiar sequence:
.PP
.Vb 4
\&   perl Makefile.PL
\&   make
\&   make test
\&   make install
.Ve
.PP
This module was developed on Windows \s-1NT\s0 4.0, using the Visual \*(C+
compiler with Service Pack 2. It was also tested on \s-1AIX\s0 using \s-1IBM\s0's
xlc compiler.
.SH "PERFORMANCE"
.IX Header "PERFORMANCE"
The following benchmark compares \f(CW\*(C`Set::Object\*(C'\fR with using a hash to
emulate a set-like collection:
.PP
.Vb 1
\&   use Set::Object;
.Ve
.PP
.Vb 2
\&   package Obj;
\&   sub new { bless { } }
.Ve
.PP
.Vb 1
\&   @els = map { Obj->new() } 1..1000;
.Ve
.PP
.Vb 1
\&   require Benchmark;
.Ve
.PP
.Vb 5
\&   Benchmark::timethese(100, {
\&      'Control' => sub { },
\&      'H insert' => sub { my %h = (); @h{@els} = @els; },
\&      'S insert' => sub { my $s = Set::Object->new(); $s->insert(@els) },
\&      } );
.Ve
.PP
.Vb 2
\&   %gh = ();
\&   @gh{@els} = @els;
.Ve
.PP
.Vb 2
\&   $gs = Set::Object->new(@els);
\&   $el = $els[33];
.Ve
.PP
.Vb 4
\&   Benchmark::timethese(100_000, {
\&           'H lookup' => sub { exists $gh{33} },
\&           'S lookup' => sub { $gs->includes($el) }
\&      } );
.Ve
.PP
On my computer the results are:
.PP
.Vb 8
\&   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)
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Original Set::Object module by Jean-Louis Leroy, <jll@skynet.be>
.SH "LICENCE"
.IX Header "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
.PP
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
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \fIperltie\fR\|(1), overload.pm