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 woth a unique priority
  $list->insert(2,'World!');
  $list->insert(5,'Hello');
  $list->insert(3,' ');
  
  # Print
  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 hold 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

EXPORT

None. All interfaces are OO.

TODO

Well, I'm dangerously neglecting the testing bit...

AUTHOR

Eyal Udassin, <eyaludassin@hotmail.com>

SEE ALSO

Set::Scalar.