Merge pull request #771 from jonas-schulze/priorityqueue-push-popfirst

Deprecate enqueue!, dequeue! and peek for PriorityQueue

Author: oxinabox

docs/src/priority-queue.md

@@ -14,11 +14,9 @@ Usage:
 ```julia
 PriorityQueue{K, V}()     # construct a new priority queue with keys of type K and priorities of type V (forward ordering by default)
 PriorityQueue{K, V}(ord)  # construct a new priority queue with the given types and ordering ord (Base.Order.Forward or Base.Order.Reverse)
-enqueue!(pq, k, v)        # insert the key k into pq with priority v
-enqueue!(pq, k=>v)        # (same, using Pairs)
-dequeue!(pq)              # remove and return the lowest priority key
-dequeue_pair!(pq)         # remove and return the lowest priorty key and value
-peek(pq)                  # return the lowest priority key and value without removing it
+push!(pq, k=>v)           # insert the key k into pq with priority v
+popfirst!(pq)             # remove and return the lowest priority key and value
+first(pq)                 # return the lowest priority key and value without removing it
 delete!(pq, k)            # delete the mapping for the given key in a priority queue, and return the priority queue.
 ```
 
@@ -28,8 +26,7 @@ inserted and priorities accessed or changed using indexing notation.
 Examples:
 
 ```jldoctest
-julia> # Julia code
-       pq = PriorityQueue();
+julia> pq = PriorityQueue();
 
 julia> # Insert keys with associated priorities
        pq["a"] = 10; pq["b"] = 5; pq["c"] = 15; pq
@@ -45,7 +42,9 @@ PriorityQueue{Any, Any, Base.Order.ForwardOrdering} with 3 entries:
   "b" => 5
   "c" => 15
 ```
-It is also possible to iterate over the priorities and elements of the queue in sorted order. 
+
+It is also possible to iterate over the priorities and elements of the queue in sorted order.
+
 ```jldoctest
 julia> pq = PriorityQueue("a"=>2, "b"=>1, "c"=>3)
 PriorityQueue{String, Int64, Base.Order.ForwardOrdering} with 3 entries:
@@ -67,6 +66,7 @@ b
 a
 c
 ```
+
 ```@meta
 DocTestSetup = nothing
 ```

src/DataStructures.jl

@@ -5,6 +5,9 @@ module DataStructures
                 isbitsunion, isiterable, dict_with_eltype, KeySet, Callable, _tablesz,
                 findnextnot, unsafe_getindex, unsafe_setindex!, peek
 
+    # Exports for old version of julia where Base doesn't export this
+    export peek
+    export popat!
 
     using Compat # Provides Base.Order.ReverseOrdering(). May remove this line with julia 1.4
     using OrderedCollections
@@ -15,7 +18,6 @@ module DataStructures
     export complement, complement!
 
     export Deque, Stack, Queue, CircularDeque
-    export enqueue!, dequeue!, dequeue_pair!, update!
     export capacity, num_blocks, top_with_handle, sizehint!
 
     export Accumulator, counter, reset!, inc!, dec!
@@ -27,6 +29,7 @@ module DataStructures
     export MutableBinaryHeap, MutableBinaryMinHeap, MutableBinaryMaxHeap
     export heapify!, heapify, heappop!, heappush!, isheap
     export BinaryMinMaxHeap, popmin!, popmax!, popall!
+    export update!
 
     export Trie, subtrie, keys_with_prefix, partial_path, find_prefixes
 
@@ -100,7 +103,7 @@ module DataStructures
     export status
     export deref_key, deref_value, deref, advance, regress
 
-    export PriorityQueue, peek
+    export PriorityQueue
 
     include("priorityqueue.jl")
     include("sparse_int_set.jl")

src/deprecations.jl

@@ -9,4 +9,16 @@ Base.@deprecate_binding IntDisjointSets IntDisjointSet
 @deprecate DisjointSets(xs...) DisjointSet(xs)
 # Enqueue and dequeue deprecations
 @deprecate enqueue!(q::Queue, x) Base.push!(q, x)
+@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).first # maybe better: `val, _ = popfirst!(pq)`
+@deprecate dequeue!(q::PriorityQueue, x) popat!(q, x).first
+@deprecate dequeue_pair!(q::PriorityQueue) Base.popfirst!(q)
+@deprecate dequeue_pair!(q::PriorityQueue, key) popat!(q, key)
+
+function Base.peek(q::PriorityQueue)
+    Expr(:meta, :noinline)
+    Base.depwarn("`peek(q::PriorityQueue)` is deprecated, use `first(q)` instead.", :peek)
+    first(q)
+end

src/priorityqueue.jl

@@ -7,13 +7,13 @@
     PriorityQueue{K, V}([ord])
 
 Construct a new [`PriorityQueue`](@ref), with keys of type
-`K` and values/priorites of type `V`.
+`K` and values/priorities of type `V`.
 If an order is not given, the priority queue is min-ordered using
 the default comparison for `V`.
 
 A `PriorityQueue` acts like a `Dict`, mapping values to their
-priorities, with the addition of a `dequeue!` function to remove the
-lowest priority element.
+priorities. New elements are added using `push!` and retrieved
+using `popfirst!` or `popat!` based on their priority.
 
 ```jldoctest
 julia> PriorityQueue(Base.Order.Forward, "a" => 2, "b" => 3, "c" => 1)
@@ -117,12 +117,12 @@ Base.isempty(pq::PriorityQueue) = isempty(pq.xs)
 Base.haskey(pq::PriorityQueue, key) = haskey(pq.index, key)
 
 """
-    peek(pq)
+    first(pq)
 
 Return the lowest priority key and value from a priority queue without removing that
-key from the queue.
+pair from the queue.
 """
-Base.peek(pq::PriorityQueue) = pq.xs[1]
+Base.first(pq::PriorityQueue) = first(pq.xs)
 
 function percolate_down!(pq::PriorityQueue, i::Integer)
     x = pq.xs[i]
@@ -183,14 +183,14 @@ end
 function Base.get!(pq::PriorityQueue, key, default)
     i = get(pq.index, key, 0)
     if i == 0
-        enqueue!(pq, key, default)
+        push!(pq, key=>default)
         return default
     else
         return pq.xs[i].second
     end
 end
 
-# Change the priority of an existing element, or equeue it if it isn't present.
+# Change the priority of an existing element, or enqueue it if it isn't present.
 function Base.setindex!(pq::PriorityQueue{K, V}, value, key) where {K,V}
     i = get(pq.index, key, 0)
     if i != 0
@@ -202,32 +202,32 @@ function Base.setindex!(pq::PriorityQueue{K, V}, value, key) where {K,V}
             percolate_up!(pq, i)
         end
     else
-        enqueue!(pq, key, value)
+        push!(pq, key=>value)
     end
     return value
 end
 
 """
-    enqueue!(pq, k=>v)
+    push!(pq, k=>v)
 
 Insert the a key `k` into a priority queue `pq` with priority `v`.
 
 ```jldoctest
-julia> a = PriorityQueue(PriorityQueue("a"=>1, "b"=>2, "c"=>3))
+julia> a = PriorityQueue("a"=>1, "b"=>2, "c"=>3)
 PriorityQueue{String, Int64, Base.Order.ForwardOrdering} with 3 entries:
   "a" => 1
   "b" => 2
   "c" => 3
 
-julia> enqueue!(a, "d"=>4)
+julia> push!(a, "d"=>4)
 PriorityQueue{String, Int64, Base.Order.ForwardOrdering} with 4 entries:
   "a" => 1
   "b" => 2
   "c" => 3
   "d" => 4
 ```
 """
-function enqueue!(pq::PriorityQueue{K,V}, pair::Pair{K,V}) where {K,V}
+function Base.push!(pq::PriorityQueue{K,V}, pair::Pair{K,V}) where {K,V}
     key = pair.first
     if haskey(pq, key)
         throw(ArgumentError("PriorityQueue keys must be unique"))
@@ -239,44 +239,12 @@ function enqueue!(pq::PriorityQueue{K,V}, pair::Pair{K,V}) where {K,V}
     return pq
 end
 
-"""
-    enqueue!(pq, k, v)
-
-Insert the a key `k` into a priority queue `pq` with priority `v`.
+Base.push!(pq::PriorityQueue{K,V}, kv::Pair) where {K,V} = push!(pq, Pair{K,V}(kv.first, kv.second))
 
 """
-enqueue!(pq::PriorityQueue, key, value) = enqueue!(pq, key=>value)
-enqueue!(pq::PriorityQueue{K,V}, kv) where {K,V} = enqueue!(pq, Pair{K,V}(kv.first, kv.second))
+    popfirst!(pq)
 
-"""
-    dequeue!(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> dequeue!(a)
-"c"
-
-julia> a
-PriorityQueue{String, Int64, Base.Order.ForwardOrdering} with 2 entries:
-  "a" => 2
-  "b" => 3
-```
-"""
-dequeue!(pq::PriorityQueue) = dequeue_pair!(pq).first
-
-dequeue!(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)
@@ -285,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
@@ -294,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)
@@ -306,10 +274,14 @@ function dequeue_pair!(pq::PriorityQueue)
     return x
 end
 
-function dequeue_pair!(pq::PriorityQueue, key)
+if isdefined(Base, :popat!)  # We will overload if it is defined, else we define on our own
+    import Base: popat!
+end
+
+function popat!(pq::PriorityQueue, key)
     idx = pq.index[key]
     force_up!(pq, idx)
-    dequeue_pair!(pq)
+    popfirst!(pq)
 end
 
 """
@@ -330,7 +302,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
 
@@ -386,15 +358,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_deprecations.jl

@@ -42,7 +42,7 @@ end
     end
 end
 
-@testset "enqueue! dequeue!" begin
+@testset "Queue enqueue! dequeue!" begin
     s = Queue{Int}(5)
     n = 100
 
@@ -76,3 +76,43 @@ end
         @test length(s) == n - i
     end
 end
+
+@testset "PriorityQueue enqueue! dequeue!" begin
+    s = PriorityQueue{Int,Int}()
+    n = 100
+
+    @test length(s) == 0
+    @test isempty(s)
+    @test_throws BoundsError first(s)
+    @test_throws BoundsError dequeue!(s)
+
+    for i = 1 : n
+        enqueue!(s, i=>i)
+        @test first(s) == (1=>1)
+        @test !isempty(s)
+        @test length(s) == i
+    end
+
+    for i = 1 : n
+        x = dequeue!(s)
+        @test x == i
+        if i < n
+            @test first(s) == (i+1 => i+1)
+        else
+            @test_throws BoundsError first(s)
+        end
+        @test isempty(s) == (i == n)
+        @test length(s) == n - i
+    end
+end
+
+@testset "peek" begin
+    pq = PriorityQueue{Int,Int}()
+    push!(pq, 1 => 1)
+    push!(pq, 2 => 2)
+    @test peek(pq) == (1=>1)
+    pq = PriorityQueue{Int,Int}()
+    push!(pq, 2 => 2)
+    push!(pq, 1 => 1)
+    @test peek(pq) == (1=>1)
+end