NAME

List::Priority - Perl extension for a list that manipulates objects by their priority

SYNOPSIS

use List::Priority;

# Create an instance
my $list = List::Priority->new();

# Insert some elements, each with a unique priority
$list->insert(2,'World!');
$list->insert(5,'Hello');
$list->insert(3,' ');

# Print
print $list->size()			# prints 3
while (my $element = $list->pop()) {
	  print $element;
}

DESCRIPTION

If you want to handle multiple data items by their order of importance, this one's for you.

You may retrieve the highest-priority item from the list using pop(), or the lowest-priority item from the list using shift(). If two items have the same priority, they are returned in first-in, first-out order. New items are inserted using insert().

You can constrain the capacity of the list using the SIZE parameter at construction time. Low-priority items are automatically evicted once the specified capacity is exceeded. By default the list's capacity is unlimited.

It is currently not allowed to insert the same object (determined by eq) twice with the same priority.

I'd like to thank Joseph N. Hall and Randal L. Schwartz for their excellent book "Effective Perl Programming" for one of the code hacks.

METHODS

new

$p_list = List::Priority->new();

new is the constructor for List::Priority objects. It accepts a key-value list with the list attributes.

• SIZE

  The maximum size of the list.

  Inserting after the size is reached will result either in a no-op, or the removal of the most recent lowest priority objects, according to the insert()'s priority.

  $list = List::Priority->new(SIZE => 10);

insert

$result = $p_list->insert($priority, $scalar);

Inserts the scalar to the list.

$priority must be numeric.

$scalar can be any scalar, including references (objects).

Returns 1 on success, and a string describing the error upon failure.

pop

$object = $p_list->pop();

Extracts the highest-priority scalar from the list. As an optional argument, takes the specific priority value to pop from, instead of the most important one.

$best_object_p3 = $list->pop(3);

Returns the object on success, undef upon failure.

shift

$object = $p_list->shift();

Extracts the lowest-priority scalar from the list.

As an optional argument, takes the specific priority value to shift from, instead of the least important one.

$worst_object_p3 = $list->shift(3);

Returns the object on success, undef upon failure.

size

$num_elts = $p_list->size();

Takes no arguments. Returns the number of elements in the priority queue.

EXPORT

None. All interfaces are OO.

TODO

More tests.

AUTHOR

Eyal Udassin, <eyaludassin@hotmail.com>

Currently maintained by Miles Gould, <miles@assyrian.org.uk>

Thanks to Maik Hentsche for bugfixes.

CONTRIBUTING

You can find the Git repository at http://github.com/pozorvlak/List-Priority.

SEE ALSO

Heap::Priority, List::PriorityQueue, Hash::PriorityQueue, POE::Queue, Timeout::Queue, Data::PrioQ::SkewBinomial.