--- Array-Heap/Heap.pm	2009/07/26 04:50:02	1.2
+++ Array-Heap/Heap.pm	2015/07/14 23:28:10	1.8
@@ -1,6 +1,6 @@
 =head1 NAME
 
-Array::Heap - treat perl arrays as heaps (priority queues)
+Array::Heap - treat perl arrays as binary heaps/priority queues
 
 =head1 SYNOPSIS
 
@@ -13,9 +13,9 @@
 or less fancy datastructures that might well be what you are looking for.
 
 This module takes a different approach: It exports functions (i.e. no
-object orientation) that are loosely modeled after the C++ STL's heap
-functions. They all take an array as argument, just like perl's built-in
-functions C<push>, C<pop> etc.
+object orientation) that are loosely modeled after the C++ STL's binary
+heap functions. They all take an array as argument, just like perl's
+built-in functions C<push>, C<pop> etc.
 
 The implementation itself is in C for maximum speed.
 
@@ -30,7 +30,7 @@
 package Array::Heap;
 
 BEGIN {
-   $VERSION = '2.0';
+   $VERSION = 3.2;
 
    require XSLoader;
    XSLoader::load ("Array::Heap", $VERSION);
@@ -39,11 +39,11 @@
 use base Exporter;
 
 @EXPORT = qw(
-   make_heap   make_heap_lex   make_heap_cmp
-   push_heap   push_heap_lex   push_heap_cmp
-   pop_heap    pop_heap_lex    pop_heap_cmp
-   splice_heap splice_heap_lex splice_heap_cmp
-   adjust_heap adjust_heap_lex adjust_heap_cmp
+   make_heap   make_heap_lex   make_heap_cmp   make_heap_idx
+   push_heap   push_heap_lex   push_heap_cmp   push_heap_idx
+   pop_heap    pop_heap_lex    pop_heap_cmp    pop_heap_idx
+   splice_heap splice_heap_lex splice_heap_cmp splice_heap_idx
+   adjust_heap adjust_heap_lex adjust_heap_cmp adjust_heap_idx
 );
 
 =item make_heap @heap                                   (\@)
@@ -51,6 +51,10 @@
 Reorders the elements in the array so they form a heap, with the lowest
 value "on top" of the heap (corresponding to the first array element).
 
+=item make_heap_idx @heap                               (\@)
+
+Just like C<make_heap>, but updates the index (see INDEXED OPERATIONS).
+
 =item make_heap_lex @heap                               (\@)
 
 Just like C<make_heap>, but in string comparison order instead of numerical
@@ -64,6 +68,10 @@
 
 Adds the given element(s) to the heap.
 
+=item push_heap_idx @heap, $element, ...                (\@@)
+
+Just like C<push_heap>,  but updates the index (see INDEXED OPERATIONS).
+
 =item push_heap_lex @heap, $element, ...                (\@@)
 
 Just like C<push_heap>, but in string comparison order instead of numerical
@@ -77,6 +85,10 @@
 
 Removes the topmost (lowest) heap element and repairs the heap.
 
+=item pop_heap_idx @heap                                (\@)
+
+Just like C<pop_heap>, but updates the index (see INDEXED OPERATIONS).
+
 =item pop_heap_lex @heap                                (\@)
 
 Just like C<pop_heap>, but in string comparison order instead of numerical
@@ -91,6 +103,10 @@
 Similar to C<pop_heap>, but removes and returns the element at index
 C<$index>.
 
+=item splice_heap_idx @heap, $index                     (\@$)
+
+Just like C<splice_heap>, but updates the index (see INDEXED OPERATIONS).
+
 =item splice_heap_lex @heap, $index                     (\@$)
 
 Just like C<splice_heap>, but in string comparison order instead of
@@ -106,6 +122,10 @@
 heap again. Can be used to remove elements, replace elements, adjust the
 priority of elements and more.
 
+=item adjust_heap_idx @heap, $index                     (\@$)
+
+Just like C<adjust_heap>, but updates the index (see INDEXED OPERATIONS).
+
 =item adjust_heap_lex @heap, $index                     (\@$)
 
 Just like C<adjust_heap>, but in string comparison order instead of
@@ -142,7 +162,7 @@
 The custom comparison functions work similar to how C<sort> works: C<$a>
 and C<$b> are set to the elements to be compared, and the result should be
 greater than zero then $a is greater than $b, C<0> otherwise. This means
-that you cna use the same function as for sorting the array, but you could
+that you can use the same function as for sorting the array, but you could
 also use a simpler function that just does C<< $a > $b >>.
 
 The first example above corresponds to this comparison "function":
@@ -156,6 +176,17 @@
 Unlike C<sort>, the default sort is numerical and it is not possible to
 use normal subroutines.
 
+=head2 INDEXED OPERATIONS
+
+The functions whose names end in C<_idx> also "update the index". That
+means that all elements must be array refs, with the first element being
+the heap value, and the second value being the array index:
+
+  [$value, $index, ...]
+
+This allows you to quickly locate an element in the array when all you
+have is the array reference.
+
 =head1 BUGS
 
 =over 4
@@ -176,10 +207,10 @@
 
 =cut
 
-=head1 AUTHOR
+=head1 AUTHOR AND CONTACT INFORMATION
 
  Marc Lehmann <schmorp@schmorp.de>
- http://home.schmorp.de/
+ http://software.schmorp.de/pkg/Array-Heap
 
 =cut