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 bits by their order of importance, this one's for you.

Logic: Precedence to highest priority object. If more than one object holds the highest priority, FIFO is king.

Duplicate objects are currently not allowed.

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 - Constructor

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

new is the constructor for List::Priority objects

Arguments:

- Accepts an Key-Value list with the list attributes.

Key: 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.

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

insert - List insertion

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

Inserts the scalar to the list

Arguments:

1. Priority must be numeric.
2. Scalar can be any scalar, including references (objects)

Return value:

1 on success, a string describing the error upon failure

pop - List extraction

  $object = $p_list->pop();
	  

Extracts the scalar from the list according to the specified logic.

Arguments:

- Optional - The specific priority value to pop from, instead of the most important one.

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

Return value:

The object on success, undef upon failure

shift - Reversed list extraction

  $object = $p_list->shift();
	  

Extracts the scalar from the list according to the reversed specified logic (least worthy first).

Arguments:

- Optional - The specific priority value to shift from, instead of the least important one.

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

Return value:

The object on success, undef upon failure

size - The number of elements in the list

$num_elts = $p_list->size();

Arguments:

None.

Return value:

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

Set::Scalar, List::PriorityQueue, Hash::PriorityQueue, POE::Queue, Timeout::Queue, Data::PrioQ::SkewBinomial.