Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Heap::Elem.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 "Elem 3"
.TH Elem 3 "2003-12-04" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Heap::Elem \- Perl extension for elements to be put in Heaps
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Heap::Elem::SomeInheritor;
.Ve
.PP
.Vb 1
\&  use Heap::SomeHeapClass;
.Ve
.PP
.Vb 2
\&  $elem = Heap::Elem::SomeInheritor->new( $value );
\&  $heap = Heap::SomeHeapClass->new;
.Ve
.PP
.Vb 1
\&  $heap->add($elem);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is an inheritable class for Heap Elements.  It provides
the interface documentation and some inheritable methods.
Only a child classes can be used \- this class is not complete.
.SH "METHODS"
.IX Header "METHODS"
.IP "$elem = Heap::Elem::SomeInheritor\->new( [args] );" 4
.IX Item "$elem = Heap::Elem::SomeInheritor->new( [args] );"
Creates a new Elem.
.ie n .IP "$elem\->heap( $val\fR ); \f(CW$elem\->heap;" 4
.el .IP "$elem\->heap( \f(CW$val\fR ); \f(CW$elem\fR\->heap;" 4
.IX Item "$elem->heap( $val ); $elem->heap;"
Provides a method for use by the Heap processing routines.
If a value argument is provided, it will be saved.  The
new saved value is always returned.  If no value argument
is provided, the old saved value is returned.
.Sp
The Heap processing routines use this method to map an element
into its internal structure.  This is needed to support the
Heap methods that affect elements that are not are the top
of the heap \- \fIdecrease_key\fR and \fIdelete\fR.
.Sp
The Heap processing routines will ensure that this value is
undef when this elem is removed from a heap, and is not undef
after it is inserted into a heap.  This means that you can
check whether an element is currently contained within a heap
or not.  (It cannot be used to determine which heap an element
is contained in, if you have multiple heaps.  Keeping that
information accurate would make the operation of merging two
heaps into a single one take longer \- it would have to traverse
all of the elements in the merged heap to update them; for
Binomial and Fibonacci heaps that would turn an O(1) operation
into an O(n) one.)
.IP "$elem1\->cmp($elem2)" 4
.IX Item "$elem1->cmp($elem2)"
A routine to compare two elements.  It must return a negative
value if this element should go higher on the heap than \fI$elem2\fR,
0 if they are equal, or a positive value if this element should
go lower on the heap than \fI$elem2\fR.  Just as with sort, the
Perl operators <=> and cmp cause the smaller value to be returned
first; similarly you can negate the meaning to reverse the order
\&\- causing the heap to always return the largest element instead
of the smallest.
.SH "INHERITING"
.IX Header "INHERITING"
This class can be inherited to provide an oject with the
ability to be heaped.  If the object is implemented as
a hash, and if it can deal with a key of \fIheap\fR, leaving
it unchanged for use by the heap routines, then the following
implemetation will work.
.PP
.Vb 1
\&  package myObject;
.Ve
.PP
.Vb 1
\&  require Exporter;
.Ve
.PP
.Vb 1
\&  @ISA = qw(Heap::Elem);
.Ve
.PP
.Vb 3
\&  sub new {
\&      my $self = shift;
\&      my $class = ref($self) || $self;
.Ve
.PP
.Vb 1
\&      my $self = SUPER::new($class);
.Ve
.PP
.Vb 2
\&      # set $self->{key} = $value;
\&  }
.Ve
.PP
.Vb 3
\&  sub cmp {
\&      my $self = shift;
\&      my $other = shift;
.Ve
.PP
.Vb 2
\&      $self->{key} cmp $other->{key};
\&  }
.Ve
.PP
.Vb 1
\&  # other methods for the rest of myObject's functionality
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
John Macdonald, jmm@perlwolf.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 1998\-2003, O'Reilly & Associates.
.PP
This code is distributed under the same copyright terms as perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIHeap\fR\|(3), \fIHeap::Elem::Num\fR\|(3), \fIHeap::Elem::NumRev\fR\|(3),
\&\fIHeap::Elem::Str\fR\|(3), \fIHeap::Elem::StrRev\fR\|(3).