Deprecate Base.peek(::PriorityQueue) in favor of Base.first

This also changes the error for empty queues from an `ArgumentError` to
a `BoundsError`, so this is technically a breaking change. Previously,
`Base.first` has been defined based on the `AbstractArray` interface via
`iterate`. This commit defines a shortcut, thereby changing the error
type.

Author: jonas-schulze

src/DataStructures.jl

@@ -102,7 +102,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

@@ -16,3 +16,9 @@ Base.@deprecate_binding IntDisjointSets IntDisjointSet
 @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

@@ -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]

test/test_deprecations.jl

@@ -83,7 +83,7 @@ end
 
     @test length(s) == 0
     @test isempty(s)
-    @test_throws ArgumentError first(s)
+    @test_throws BoundsError first(s)
     @test_throws BoundsError dequeue!(s)
 
     for i = 1 : n
@@ -99,9 +99,20 @@ end
         if i < n
             @test first(s) == (i+1 => i+1)
         else
-            @test_throws ArgumentError first(s)
+            @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

test/test_priority_queue.jl

@@ -77,17 +77,17 @@ import Base.Order.Reverse
         @testset "construction from pairs" begin
             @testset "pq9" begin
                 pq9 = PriorityQueue('a'=>1, 'b'=>2)
-                @test peek(pq9) == ('a'=>1)
+                @test first(pq9) == ('a'=>1)
             end
 
             @testset "pq10" begin
                 pq10 = PriorityQueue(Reverse, 'a'=>1, 'b'=>2)
-                @test peek(pq10) == ('b'=>2)
+                @test first(pq10) == ('b'=>2)
             end
 
             @testset "pq11" begin
                 pq11 = PriorityQueue(Pair{Char}['a'=>1,'b'=>2])
-                @test peek(pq11) == ('a'=>1)
+                @test first(pq11) == ('a'=>1)
             end
         end
 
@@ -110,15 +110,15 @@ import Base.Order.Reverse
     @testset "PriorityQueueMethods" begin
         pq1 = PriorityQueue('a'=>1, 'b'=>2)
 
-        @testset "peek/get/popfirst!/get!" begin
-            @test peek(pq1) == ('a'=>1)
+        @testset "first/get/popfirst!/get!" begin
+            @test first(pq1) == ('a'=>1)
             @test get(pq1, 'a', 0) == 1
             @test get(pq1, 'c', 0) == 0
             @test get!(pq1, 'b', 20) == 2
             @test popfirst!(pq1).first == 'a'
             @test popfirst!(pq1).first == 'b'
             @test get!(pq1, 'c', 0) == 0
-            @test peek(pq1) == ('c'=>0)
+            @test first(pq1) == ('c'=>0)
             @test get!(pq1, 'c', 3) == 0
         end
 
@@ -127,10 +127,10 @@ import Base.Order.Reverse
         ks, vs = 1:n, rand(1:pmax, n)
         priorities = Dict(zip(ks, vs))
 
-        @testset "peek" begin
+        @testset "first" begin
             pq1 = PriorityQueue(priorities)
             lowpri = findmin(vs)
-            @test peek(pq1)[2] == pq1[ks[lowpri[2]]]
+            @test first(pq1)[2] == pq1[ks[lowpri[2]]]
         end
 
         @testset "enqueue error throw" begin