.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Heap 3pm"
.TH Heap 3pm "2016-03-23" "perl v5.22.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Heap \- Perl extensions for keeping data partially sorted
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Heap;
\&
\&  my $heap = Heap\->new;
\&  my $elem;
\&
\&  use Heap::Elem::Num(NumElem);
\&
\&  foreach $i ( 1..100 ) {
\&      $elem = NumElem( $i );
\&      $heap\->add( $elem );
\&  }
\&
\&  while( defined( $elem = $heap\->extract_top ) ) {
\&      print "Smallest is ", $elem\->val, "\en";
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Heap collection of modules provide routines that manage
a heap of elements.  A heap is a partially sorted structure
that is always able to easily extract the smallest of the
elements in the structure (or the largest if a reversed compare
routine is provided).
.PP
If the collection of elements is changing dynamically, the
heap has less overhead than keeping the collection fully
sorted.
.PP
The elements must be objects as described in \*(L"Heap::Elem\*(R"
and all elements inserted into one heap must be mutually
compatible \- either the same class exactly or else classes that
differ only in ways unrelated to the \fBHeap::Elem\fR interface.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$heap = \fIHeapClass::new()\fR; $heap2 = $heap1\->\fInew()\fR;" 4
.el .IP "\f(CW$heap\fR = \fIHeapClass::new()\fR; \f(CW$heap2\fR = \f(CW$heap1\fR\->\fInew()\fR;" 4
.IX Item "$heap = HeapClass::new(); $heap2 = $heap1->new();"
Returns a new heap object of the specified (sub\-)class.
This is often used as a subroutine instead of a method,
of course.
.ie n .IP "$heap\->\s-1DESTROY\s0" 4
.el .IP "\f(CW$heap\fR\->\s-1DESTROY\s0" 4
.IX Item "$heap->DESTROY"
Ensures that no internal circular data references remain.
Some variants of Heap ignore this (they have no such references).
Heap users normally need not worry about it, \s-1DESTROY\s0 is automatically
invoked when the heap reference goes out of scope.
.ie n .IP "$heap\->add($elem)" 4
.el .IP "\f(CW$heap\fR\->add($elem)" 4
.IX Item "$heap->add($elem)"
Add an element to the heap.
.ie n .IP "$elem = $heap\->top" 4
.el .IP "\f(CW$elem\fR = \f(CW$heap\fR\->top" 4
.IX Item "$elem = $heap->top"
Return the top element on the heap.  It is \fBnot\fR removed from
the heap but will remain at the top.  It will be the smallest
element on the heap (unless a reversed cmp function is being
used, in which case it will be the largest).  Returns \fIundef\fR
if the heap is empty.
.Sp
This method used to be called \*(L"minimum\*(R" instead of \*(L"top\*(R".  The
old name is still supported but is deprecated.  (It was confusing
to use the method \*(L"minimum\*(R" to get the maximum value on the heap
when a reversed cmp function was used for ordering elements.)
.ie n .IP "$elem = $heap\->extract_top" 4
.el .IP "\f(CW$elem\fR = \f(CW$heap\fR\->extract_top" 4
.IX Item "$elem = $heap->extract_top"
Delete the top element from the heap and return it.  Returns
\&\fIundef\fR if the heap was empty.
.Sp
This method used to be called \*(L"extract_minimum\*(R" instead of
\&\*(L"extract_top\*(R".  The old name is still supported but is deprecated.
(It was confusing to use the method \*(L"extract_minimum\*(R" to get the
maximum value on the heap when a reversed cmp function was used
for ordering elements.)
.ie n .IP "$heap1\->absorb($heap2)" 4
.el .IP "\f(CW$heap1\fR\->absorb($heap2)" 4
.IX Item "$heap1->absorb($heap2)"
Merge all of the elements from \fI\f(CI$heap2\fI\fR into \fI\f(CI$heap1\fI\fR.
This will leave \fI\f(CI$heap2\fI\fR empty.
.ie n .IP "$heap1\->decrease_key($elem)" 4
.el .IP "\f(CW$heap1\fR\->decrease_key($elem)" 4
.IX Item "$heap1->decrease_key($elem)"
The element will be moved closed to the top of the
heap if it is now smaller than any higher parent elements.
The user must have changed the value of \fI\f(CI$elem\fI\fR before
\&\fIdecrease_key\fR is called.  Only a decrease is permitted.
(This is a decrease according to the \fIcmp\fR function \- if it
is a reversed order comparison, then you are only permitted
to increase the value of the element.  To be pedantic, you
may only use \fIdecrease_key\fR if
\&\fI\f(CI$elem\fI\-\fRcmp($elem_original) <= 0> if \fI\f(CI$elem_original\fI\fR were
an elem with the value that \fI\f(CI$elem\fI\fR had before it was
\&\fIdecreased\fR.)
.ie n .IP "$elem = $heap\->delete($elem)" 4
.el .IP "\f(CW$elem\fR = \f(CW$heap\fR\->delete($elem)" 4
.IX Item "$elem = $heap->delete($elem)"
The element is removed from the heap (whether it is at
the top or not).
.SH "AUTHOR"
.IX Header "AUTHOR"
John Macdonald, john@perlwolf.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 1998\-2007, O'Reilly & Associates.
.PP
This code is distributed under the same copyright terms as perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIHeap::Elem\fR\|(3), \fIHeap::Binary\fR\|(3), \fIHeap::Binomial\fR\|(3), \fIHeap::Fibonacci\fR\|(3).