Define empty! for BinaryHeap and MutableBinaryHeap (#932)

Author: devmotion

docs/src/heaps.md

@@ -13,6 +13,8 @@ length(h)            # returns the number of elements
 
 isempty(h)           # returns whether the heap is empty
 
+empty!(h)            # reset the heap
+
 push!(h, v)          # add a value to the heap
 
 first(h)             # return the first (top) value of a heap

src/heaps.jl

@@ -20,6 +20,8 @@
 #   - isempty(h)          returns whether the heap is
 #                         empty
 #
+#   - empty!(h)           reset the heap
+#
 #   - push!(h, v)         add a value to the heap
 #
 #   - sizehint!(h, s)     set size hint to a heap

src/heaps/binary_heap.jl

@@ -106,6 +106,11 @@ Removes and returns the element at the top of the heap `h`.
 """
 Base.pop!(h::BinaryHeap) = heappop!(h.valtree, h.ordering)
 
+function Base.empty!(h::BinaryHeap)
+    empty!(h.valtree)
+    return h
+end
+
 # Suggest that heap `h` reserve capacity for at least `n` elements. This can improve performance.
 function Base.sizehint!(h::BinaryHeap, n::Integer)
     sizehint!(h.valtree, n)

src/heaps/mutable_binary_heap.jl

@@ -226,6 +226,12 @@ function Base.push!(h::MutableBinaryHeap{T}, v) where T
     return i
 end
 
+function Base.empty!(h::MutableBinaryHeap)
+    empty!(h.nodes)
+    empty!(h.node_map)
+    return h
+end
+
 function Base.sizehint!(h::MutableBinaryHeap, s::Integer)
     sizehint!(h.nodes, s)
     sizehint!(h.node_map, s)

test/test_binheap.jl

@@ -237,4 +237,19 @@
 
         @test isequal(h.valtree, [0.5, 5.0, 3.0, 10.1])
     end
+
+    @testset "empty!" begin
+        vs = [4, 1, 3, 2, 16, 9, 10, 14, 8, 7]
+        vs2 = collect(enumerate(vs))
+        ordering = Base.Order.By(last)
+
+        for h in (BinaryMinHeap(vs), BinaryMaxHeap(vs), BinaryHeap(ordering, vs2))
+            @test length(h) == length(vs)
+            @test !isempty(h)
+            ret = empty!(h)
+            @test ret === h
+            @test length(ret) == 0
+            @test isempty(ret)
+        end
+    end
 end # @testset BinaryHeap

test/test_mutable_binheap.jl

@@ -342,4 +342,20 @@ end
         update!(h, 2, 20)
         @test isequal(heap_values(h), [0.5, 10.1, 3.0, 20.0])
     end
+
+    @testset "empty!" begin
+        vs = [4, 1, 3, 2, 16, 9, 10, 14, 8, 7]
+        vs2 = collect(enumerate(vs))
+        ordering = Base.Order.By(last)
+
+        for h in (MutableBinaryMinHeap(vs), MutableBinaryMaxHeap(vs), MutableBinaryHeap(ordering, vs2))
+            @test length(h) == length(vs)
+            @test !isempty(h)
+            ret = empty!(h)
+            @test ret === h
+            @test length(ret) == 0
+            @test isempty(ret)
+            @test verify_heap(ret)
+        end
+    end
 end # @testset MutableBinheap