Merge pull request #262 from JuliaLang/cb/tophandle

Add top_with_handle(::MutableBinaryHeap) function

doc/source/heaps.rst

@@ -23,9 +23,11 @@ All heaps in this package are derived from ``AbstractHeap``, and provide the fol
 Mutable heaps (values can be changed after being pushed to a heap) are derived from
 ``AbstractMutableHeap <: AbstractHeap``, and additionally provides the following interface::
 
-  i = push!(h, v)       # adds a value to the heap and and returns a handle to v
+  i = push!(h, v)              # adds a value to the heap and and returns a handle to v
 
-  update!(h, i, v)      # updates the value of an element (referred to by the handle i)
+  update!(h, i, v)             # updates the value of an element (referred to by the handle i)
+
+  v, i = top_with_handle(h)    # returns the top value of a heap and its handle
 
 
 Currently, both min/max versions of binary heap (type ``BinaryHeap``) and mutable binary heap (type ``MutableBinaryHeap``) have been implemented.

src/DataStructures.jl

@@ -20,7 +20,7 @@ module DataStructures
 
     export Deque, Stack, Queue, CircularDeque
     export deque, enqueue!, dequeue!, update!, reverse_iter
-    export capacity, num_blocks, front, back, top, sizehint!
+    export capacity, num_blocks, front, back, top, top_with_handle, sizehint!
 
     export Accumulator, counter
     export ClassifiedCollections

src/heaps.jl

@@ -15,27 +15,31 @@
 #   functions. Here, let h be a heap, i be a handle, and
 #   v be a value.
 #
-#   - length(h)         returns the number of elements
+#   - length(h)           returns the number of elements
 #
-#   - isempty(h)        returns whether the heap is
-#                       empty
+#   - isempty(h)          returns whether the heap is
+#                         empty
 #
-#   - push!(h, v)       add a value to the heap
+#   - push!(h, v)         add a value to the heap
 #
-#   - sizehint!(h)       set size hint to a heap
+#   - sizehint!(h)         set size hint to a heap
 #
-#   - top(h)            return the top value of a heap
+#   - top(h)              return the top value of a heap
 #
-#   - pop!(h)           removes the top value, and
-#                       returns it
+#   - pop!(h)             removes the top value, and
+#                         returns it
 #
 #  For mutable heaps, it should also support
 #
-#   - push!(h, v)       adds a value to the heap and
-#                       returns a handle to v
+#   - push!(h, v)         adds a value to the heap and
+#                         returns a handle to v
+#
+#   - update!(h, i, v)    updates the value of an element
+#                         (referred to by the handle i)
+#
+#   - top_with_handle(h)  return the top value of a heap
+#                         and its handle
 #
-#   - update!(h, i, v)  updates the value of an element
-#                       (referred to by the handle i)
 #
 ###########################################################
 

src/heaps/mutable_binary_heap.jl

@@ -210,6 +210,16 @@ end
 
 top(h::MutableBinaryHeap) = h.nodes[1].value
 
+"""
+    top_with_handle(h::MutableBinaryHeap)
+
+Returns the element at the top of the heap `h` and its handle.
+"""
+function top_with_handle(h::MutableBinaryHeap)
+    el = h.nodes[1]
+    return el.value, el.handle
+end
+
 pop!{T}(h::MutableBinaryHeap{T}) = _binary_heap_pop!(h.comparer, h.nodes, h.node_map)
 
 """

test/test_mutable_binheap.jl

@@ -155,27 +155,42 @@ push!(h, 2)
 @test isequal(list_values(h), [10, 7])
 
 
-# test update!
-
-xs = rand(100)
-hmin = mutable_binary_minheap(xs)
-hmax = mutable_binary_maxheap(xs)
-
-@test length(hmin) == 100
-@test length(hmax) == 100
-@test verify_heap(hmin)
-@test verify_heap(hmax)
-
-for t = 1 : 1000
-    i = rand(1:100)
-    v = rand()
-    xs[i] = v
-    update!(hmin, i, v)
-    update!(hmax, i, v)
-    @test length(hmin) == 100
-    @test length(hmax) == 100
-    @test verify_heap(hmin)
-    @test verify_heap(hmax)
-    @test isequal(list_values(hmin), xs)
-    @test isequal(list_values(hmax), xs)
+# test update! and top_with_handle
+for (hf,m) = [(mutable_binary_minheap,-2.0), (mutable_binary_maxheap,2.0)]
+    xs = rand(100)
+    h = hf(xs)
+    @test length(h) == 100
+    @test verify_heap(h)
+
+    for t = 1:1000
+        i = rand(1:100)
+        v = rand()
+        xs[i] = v
+        update!(h, i, v)
+        @test length(h) == 100
+        @test verify_heap(h)
+        @test isequal(list_values(h), xs)
+
+        v, i = top_with_handle(h)
+        update!(h, i, m)
+        xs[i] = m
+        @test length(h) == 100
+        @test verify_heap(h)
+        @test isequal(list_values(h), xs)
+        @test top_with_handle(h) == (m, i)
+
+        update!(h, i, -m)
+        xs[i] = -m
+        @test length(h) == 100
+        @test verify_heap(h)
+        @test isequal(list_values(h), xs)
+        @test top_with_handle(h)[2] ≠ i
+
+        update!(h, i, v)
+        xs[i] = v
+        @test length(h) == 100
+        @test verify_heap(h)
+        @test isequal(list_values(h), xs)
+        @test top_with_handle(h) == (v, i)
+    end
 end