Refactor popfirst!(::PriorityQueue)

`PriorityQueue` has been introduced as "acting like a `Dict`".
Therefore, it may be considered as a collection of `key => priority`
pairs, as indicated by `first(pq)` or iteration over it. However,
`popfirst!(pq)` has returned only the key but not the pair, such that
the return type of `popfirst!` did not match `eltype(pq)`. This commit
fixes that by replacing `popfirst!` with `dequeue_pair!`.

This is a breaking change.

Author: jonas-schulze

src/DataStructures.jl

@@ -15,7 +15,7 @@ module DataStructures
     export complement, complement!
 
     export Deque, Stack, Queue, CircularDeque
-    export dequeue_pair!, update!
+    export update!
     export capacity, num_blocks, top_with_handle, sizehint!
 
     export Accumulator, counter, reset!, inc!, dec!

src/deprecations.jl

@@ -12,5 +12,7 @@ Base.@deprecate_binding IntDisjointSets IntDisjointSet
 @deprecate enqueue!(q::PriorityQueue, x) Base.push!(q, x)
 @deprecate enqueue!(q::PriorityQueue, k, v) Base.push!(q, k=>v)
 @deprecate dequeue!(q::Queue) Base.popfirst!(q)
-@deprecate dequeue!(q::PriorityQueue) Base.popfirst!(q)
-@deprecate dequeue!(q::PriorityQueue, x) Base.popat!(q, x)
+@deprecate dequeue!(q::PriorityQueue) Base.popfirst!(q).first # maybe better: `val, _ = popfirst!(pq)`
+@deprecate dequeue!(q::PriorityQueue, x) Base.popat!(q, x).first
+@deprecate dequeue_pair!(q::PriorityQueue) Base.popfirst!(q)
+@deprecate dequeue_pair!(q::PriorityQueue, key) Base.popat!(q, key)

src/priorityqueue.jl

@@ -244,32 +244,7 @@ Base.push!(pq::PriorityQueue{K,V}, kv::Pair) where {K,V} = push!(pq, Pair{K,V}(k
 """
     popfirst!(pq)
 
-Remove and return the lowest priority key from a priority queue.
-
-```jldoctest
-julia> a = PriorityQueue(Base.Order.Forward, ["a" => 2, "b" => 3, "c" => 1])
-PriorityQueue{String, Int64, Base.Order.ForwardOrdering} with 3 entries:
-  "c" => 1
-  "a" => 2
-  "b" => 3
-
-julia> popfirst!(a)
-"c"
-
-julia> a
-PriorityQueue{String, Int64, Base.Order.ForwardOrdering} with 2 entries:
-  "a" => 2
-  "b" => 3
-```
-"""
-Base.popfirst!(pq::PriorityQueue) = dequeue_pair!(pq).first
-
-Base.popat!(pq::PriorityQueue, key) = dequeue_pair!(pq, key).first
-
-"""
-    dequeue_pair!(pq)
-
-Remove and return a the lowest priority key and value from a priority queue as a pair.
+Remove and return the lowest priority key and value from a priority queue as a pair.
 
 ```jldoctest
 julia> a = PriorityQueue(Base.Order.Forward, "a" => 2, "b" => 3, "c" => 1)
@@ -278,7 +253,7 @@ PriorityQueue{String, Int64, Base.Order.ForwardOrdering} with 3 entries:
   "a" => 2
   "b" => 3
 
-julia> dequeue_pair!(a)
+julia> popfirst!(a)
 "c" => 1
 
 julia> a
@@ -287,7 +262,7 @@ PriorityQueue{String, Int64, Base.Order.ForwardOrdering} with 2 entries:
   "b" => 3
 ```
 """
-function dequeue_pair!(pq::PriorityQueue)
+function Base.popfirst!(pq::PriorityQueue)
     x = pq.xs[1]
     y = pop!(pq.xs)
     if !isempty(pq)
@@ -299,10 +274,10 @@ function dequeue_pair!(pq::PriorityQueue)
     return x
 end
 
-function dequeue_pair!(pq::PriorityQueue, key)
+function Base.popat!(pq::PriorityQueue, key)
     idx = pq.index[key]
     force_up!(pq, idx)
-    dequeue_pair!(pq)
+    popfirst!(pq)
 end
 
 """
@@ -323,7 +298,7 @@ PriorityQueue{String, Int64, Base.Order.ForwardOrdering} with 2 entries:
 ```
 """
 function Base.delete!(pq::PriorityQueue, key)
-    dequeue_pair!(pq, key)
+    popat!(pq, key)
     return pq
 end
 
@@ -379,15 +354,15 @@ function Base.iterate(pq::PriorityQueue, ordered::Bool=true)
     if ordered
         isempty(pq) && return nothing
         state = _PQIteratorState(PriorityQueue(copy(pq.xs), pq.o, copy(pq.index)))
-        return dequeue_pair!(state.pq), state
+        return popfirst!(state.pq), state
     else
         _iterate(pq, iterate(pq.index))
     end
 end
 
 function Base.iterate(pq::PriorityQueue, state::_PQIteratorState)
     isempty(state.pq) && return nothing
-    return dequeue_pair!(state.pq), state
+    return popfirst!(state.pq), state
 end
 
 Base.iterate(pq::PriorityQueue, i) = _iterate(pq, iterate(pq.index, i))

test/test_priority_queue.jl

@@ -7,9 +7,9 @@ import Base.Order.Reverse
 
     # Test dequeing in sorted order.
     function test_issorted!(pq::PriorityQueue, priorities, rev=false)
-        last = popfirst!(pq)
+        last, _ = popfirst!(pq)
         while !isempty(pq)
-            value = popfirst!(pq)
+            value, _ = popfirst!(pq)
             if !rev
                 @test priorities[last] <= priorities[value]
             else
@@ -23,7 +23,7 @@ import Base.Order.Reverse
         i = 0
         while !isempty(pq)
             krqst =  keys[i+=1]
-            krcvd = popat!(pq, krqst)
+            krcvd, _ = popat!(pq, krqst)
             @test krcvd == krqst
         end
     end
@@ -115,8 +115,8 @@ import Base.Order.Reverse
             @test get(pq1, 'a', 0) == 1
             @test get(pq1, 'c', 0) == 0
             @test get!(pq1, 'b', 20) == 2
-            @test popfirst!(pq1) == 'a'
-            @test popfirst!(pq1) == 'b'
+            @test popfirst!(pq1).first == 'a'
+            @test popfirst!(pq1).first == 'b'
             @test get!(pq1, 'c', 0) == 0
             @test peek(pq1) == ('c'=>0)
             @test get!(pq1, 'c', 3) == 0
@@ -192,21 +192,22 @@ import Base.Order.Reverse
             pq = PriorityQueue(priorities)
             @test_throws KeyError popat!(pq, 0)
 
-            @test 10 == popat!(pq, 10)
+            v, _ = popat!(pq, 10)
+            @test v == 10
             while !isempty(pq)
-                @test 10 != popfirst!(pq)
+                v, _ = popfirst!(pq)
+                @test v != 10
             end
 
             pq = PriorityQueue(1.0 => 1)
-            @test popat!(pq, 1.0f0) isa Float64
-        end
+            @test popat!(pq, 1.0f0) isa eltype(pq)
+            @test eltype(pq) == Pair{Float64, Int64}
 
-        @testset "dequeuing pair" begin
             priorities2 = Dict(zip('a':'e', 5:-1:1))
             pq = PriorityQueue(priorities2)
-            @test_throws KeyError dequeue_pair!(pq, 'g')
-            @test dequeue_pair!(pq) == ('e'=> 1)
-            @test dequeue_pair!(pq, 'b') == ('b'=>4)
+            @test_throws KeyError popat!(pq, 'g')
+            @test popfirst!(pq) == ('e'=> 1)
+            @test popat!(pq, 'b') == ('b'=>4)
             @test length(pq) == 3
         end