NAME

Heap::Elem - Perl extension for elements to be put in Heaps

SYNOPSIS

use Heap::Elem::SomeInheritor;

use Heap::SomeHeapClass;

$elem = Heap::Elem::SomeInheritor->new( $value );
$heap = Heap::SomeHeapClass->new;

$heap->add($elem);

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.

METHODS

$elem = Heap::Elem::SomeInheritor->new( [args] );

Creates a new Elem.

$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.

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 - decrease_key and delete.

$elem1->cmp($elem2)

A routine to compare two elements. It must return a negative value if this element is less than $elem2, 0 if they are equal, or a positive value if this element is greater than $elem2. Just as with sort, you can negate the meaning to reverse the order - causing the heap to always return the largest element instead of the smallest. (That does make the Heap method names minimum, extract_minimum, and decrease_key counter-intuitive, though.)

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 kay of heap, leaving it unchanged for use by the heap routines, then the following implemetation will work.

package myObject;

require Exporter;

@ISA = qw(Heap::Elem);

sub new {
    my $self = shift;
    my $class = ref($self) || $self;

    my $self = SUPER::new($class);

    # set $self->{key} = $value;
}

sub cmp {
    my $self = shift;
    my $other = shift;

    $self->{key} cmp $other->{key};
}

# other methods for the rest of myObject's functionality

AUTHOR

John Macdonald, jmm@elegant.com

SEE ALSO

Heap(3), Heap::Elem::Num(3), Heap::Elem::NumRev(3), Heap::Elem::Str(3), Heap::Elem::StrRev(3).