Use first and last, rather than front, back, top etc (#565)

* Replaced front and back with first and last respectively * Update src/circ_deque.jl Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update src/circ_deque.jl Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update docs/src/circ_deque.md Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update docs/src/circ_deque.md Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update docs/src/circ_deque.md Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update docs/src/circ_deque.md Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update docs/src/circ_deque.md Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update docs/src/circ_deque.md Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update src/circ_deque.jl Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Changes made to queue and deque * Revert "Changes made to queue and deque" This reverts commit 27486fd. * Changes to queue and dequeue(2) * Commented wrongly added deprecate function * Changed back to last in stack * Added deprecations file * Bump package version to 0.18.0 * Bump version to 0.17.7 Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update src/circ_deque.jl Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update src/stack.jl Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Updated for new version * update top/first docstring * Update src/circ_deque.jl Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update src/circ_deque.jl Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update src/circ_deque.jl Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> * Update src/circ_deque.jl Co-Authored-By: Lyndon White <oxinabox@ucc.asn.au> Co-authored-by: Lyndon White <oxinabox@ucc.asn.au>
JuliaCollections · Jan 3, 2020 · 54af1eb · 54af1eb · oxinabox · Jan 3, 2020
1 parent 685d33d
commit 54af1eb
Show file tree

Hide file tree

Showing 14 changed files with 87 additions and 82 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "DataStructures"
 uuid = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
-version = "0.17.6"
+version = "0.17.7"
 
 [deps]
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"

diff --git a/docs/src/circ_deque.md b/docs/src/circ_deque.md
@@ -12,12 +12,12 @@ isempty(a)          # test whether the deque is empty
 empty!(a)           # reset the deque
 capacity(a)         # return capacity
 length(a)           # get the number of elements currently in the deque
-push!(a, 10)        # add an element to the back
+push!(a, 10)        # add an element to the front
 pop!(a)             # remove an element from the back
 pushfirst!(a, 20)   # add an element to the front
-popfirst!(a)        # remove an element from the front
-front(a)            # get the element at the front
-back(a)             # get the element at the back
+popfirst!(a)        # remove an element from the first
+first(a)            # get the element at the front
+last(a)             # get the element at the back
 eltype(a)           # return type of items
 ```
 

diff --git a/docs/src/deque.md b/docs/src/deque.md
@@ -14,8 +14,8 @@ push!(a, 10)        # add an element to the back
 pop!(a)             # remove an element from the back
 pushfirst!(a, 20)   # add an element to the front
 popfirst!(a)        # remove an element from the front
-front(a)            # get the element at the front
-back(a)             # get the element at the back
+first(a)            # get the element at the front
+last(a)             # get the element at the back
 ```
 
 *Note:* Julia's `Vector` type also provides this interface, and thus can

diff --git a/docs/src/stack_and_queue.md b/docs/src/stack_and_queue.md
@@ -1,3 +1,4 @@
+
 # Stack and Queue
 
 The `Stack` and `Queue` types are a light-weight wrapper of a deque
@@ -11,7 +12,7 @@ isempty(s)                  # check whether the stack is empty
 length(s)                   # get the number of elements
 eltype(s)                   # get the type of elements
 push!(s, 1)                 # push back a item
-top(s)                      # get a first item
+first(s)                    # get an item from the top of stack
 pop!(s)                     # get and remove a first item
 empty!(s)                   # make a stack empty
 iterate(s::Stack)           # Get a LIFO iterator of a stack
@@ -24,8 +25,8 @@ Usage of Queue:
 ```julia
 q = Queue{Int}()
 enqueue!(q, x)
-x = front(q)
-x = back(q)
+x = first(q)
+x = last(q)
 x = dequeue!(q)
 ```
 

diff --git a/src/DataStructures.jl b/src/DataStructures.jl
@@ -22,7 +22,7 @@ module DataStructures
 
     export Deque, Stack, Queue, CircularDeque
     export deque, enqueue!, dequeue!, dequeue_pair!, update!, reverse_iter
-    export capacity, num_blocks, front, back, top, top_with_handle, sizehint!
+    export capacity, num_blocks, top_with_handle, sizehint!
 
     export Accumulator, counter, reset!, inc!, dec!
 
@@ -59,6 +59,7 @@ module DataStructures
 
     export findkey
 
+    include("deprecations.jl")
     include("delegate.jl")
 
     include("deque.jl")

diff --git a/src/circ_deque.jl b/src/circ_deque.jl
@@ -33,21 +33,21 @@ end
 Base.isempty(D::CircularDeque) = D.n == 0
 
 """
-    front(D::CircularDeque)
+    first(D::CircularDeque)
 
-Add an element to the front
+Get the item at the front of the queue.
 """
-@inline function front(D::CircularDeque)
+@inline function first(D::CircularDeque)
     @boundscheck D.n > 0 || throw(BoundsError())
     D.buffer[D.first]
 end
 
 """
-    back(D::CircularDeque)
+    last(D::CircularDeque)
 
-Add an element to the back
+Get the item from the back of the queue.
 """
-@inline function back(D::CircularDeque)
+@inline function last(D::CircularDeque)
     @boundscheck D.n > 0 || throw(BoundsError())
     D.buffer[D.last]
 end
@@ -62,7 +62,7 @@ end
 end
 
 @inline function Base.pop!(D::CircularDeque)
-    v = back(D)
+    v = last(D)
     D.n -= 1
     tmp = D.last - 1
     D.last = ifelse(tmp < 1, D.capacity, tmp)
@@ -72,7 +72,7 @@ end
 """
     pushfirst!(D::CircularDeque, v)
 
-Add an element to the front
+Add an element to the front.
 """
 @inline function pushfirst!(D::CircularDeque, v)
     @boundscheck D.n < D.capacity || throw(BoundsError())
@@ -84,12 +84,12 @@ Add an element to the front
 end
 
 """
-    pushfirst!(D::CircularDeque)
+    popfirst!(D::CircularDeque)
 
-Remove the element at the front
+Remove the element at the front.
 """
 @inline function popfirst!(D::CircularDeque)
-    v = front(D)
+    v = first(D)
     D.n -= 1
     tmp = D.first + 1
     D.first = ifelse(tmp > D.capacity, 1, tmp)

diff --git a/src/deprecations.jl b/src/deprecations.jl
@@ -0,0 +1,3 @@
+@deprecate front(x) first(x)
+@deprecate back(x) last(x)
+@deprecate top(x) first(x)
diff --git a/src/deque.jl b/src/deque.jl
@@ -98,7 +98,7 @@ Base.eltype(::Type{Deque{T}}) where T = T
 
 Returns the first element of the deque `q`.
 """
-function front(q::Deque)
+function first(q::Deque)
     isempty(q) && throw(ArgumentError("Deque must be non-empty"))
     blk = q.head
     blk.data[blk.front]
@@ -109,7 +109,7 @@ end
 
 Returns the last element of the deque `q`.
 """
-function back(q::Deque)
+function last(q::Deque)
     isempty(q) && throw(ArgumentError("Deque must be non-empty"))
     blk = q.rear
     blk.data[blk.back]

diff --git a/src/queue.jl b/src/queue.jl
@@ -16,8 +16,8 @@ isempty(s::Queue) = isempty(s.store)
 length(s::Queue) = length(s.store)
 Base.eltype(::Type{Queue{T}}) where T = T
 
-front(s::Queue) = front(s.store)
-back(s::Queue) = back(s.store)
+first(s::Queue) = first(s.store)
+last(s::Queue) = last(s.store)
 
 """
     enqueue!(s::Queue, x)

diff --git a/src/stack.jl b/src/stack.jl
@@ -36,11 +36,11 @@ length(s::Stack) = length(s.store)
 Base.eltype(::Type{Stack{T}}) where T = T
 
 """
-    top(s::Stack)
+    first(s::Stack)
 
-Get a top item from a stack
+Get the top item from the stack. Sometimes called peek.
 """
-top(s::Stack) = back(s.store)
+first(s::Stack) = last(s.store)
 
 function push!(s::Stack, x)
     push!(s.store, x)

diff --git a/test/test_circ_deque.jl b/test/test_circ_deque.jl
@@ -7,35 +7,35 @@
         @test capacity(D) == 5
         @test length(D) == 0
         @test isempty(D)
-        @test_throws BoundsError front(D)
-        @test_throws BoundsError back(D)
+        @test_throws BoundsError first(D)
+        @test_throws BoundsError last(D)
         push!(D, 1)
-        @test front(D) === back(D) === 1
+        @test first(D) === last(D) === 1
         push!(D, 2)
-        @test front(D) === 1
-        @test back(D)  === 2
+        @test first(D) === 1
+        @test last(D)  === 2
         @test length(D) == 2
         for i = 3:5
             push!(D, i)
         end
         @test_throws BoundsError push!(D, 6)
         @test popfirst!(D) === 1
-        @test front(D) === 2
-        @test back(D) === 5
+        @test first(D) === 2
+        @test last(D) === 5
         io = IOBuffer()
         print(io, Int)
         intstr = String(take!(io))
         print(io, D)
         @test String(take!(io)) == "CircularDeque{$intstr}([2,3,4,5])"
         push!(D, 6)
-        @test front(D) === 2
-        @test back(D) === 6
+        @test first(D) === 2
+        @test last(D) === 6
         @test pop!(D) === 6
-        @test front(D) === 2
-        @test back(D) === 5
+        @test first(D) === 2
+        @test last(D) === 5
         pushfirst!(D, 7)
-        @test front(D) === 7
-        @test back(D) === 5
+        @test first(D) === 7
+        @test last(D) === 5
         @test_throws BoundsError pushfirst!(D, 8)
         @test popfirst!(D) === 7
         @test popfirst!(D) === 2
@@ -49,31 +49,31 @@
         @test !isempty(D)
         empty!(D)
         @test isempty(D)
-        @test_throws BoundsError front(D)
+        @test_throws BoundsError first(D)
         push!(D, 20)
-        @test front(D) == back(D) == 20
+        @test first(D) == last(D) == 20
         empty!(D)
         for i = 1:5
             push!(D, i)
         end
         @test popfirst!(D) == 1
         push!(D, 6)
         for i = 2:6
-            @test back(D) === 6
+            @test last(D) === 6
             @test D[1] === i
             @test D[7-i] === 6
             @test popfirst!(D) === i
         end
     end
 
     @testset "pushfirst! works on an empty deque" begin
-        # Test that pushfirst! works on an empty deque, and that front/back give the right answer
+        # Test that pushfirst! works on an empty deque, and that first/last give the right answer
         D = CircularDeque{Int}(5)
         pushfirst!(D, 30)
-        @test front(D) == back(D) == 30
+        @test first(D) == last(D) == 30
         empty!(D)
         pushfirst!(D, 40)
-        @test front(D) == back(D) == 40
+        @test first(D) == last(D) == 40
     end
 
     @testset "iteration over loop" begin

diff --git a/test/test_deque.jl b/test/test_deque.jl
@@ -7,8 +7,8 @@
             @test eltype(q) == Int
             @test eltype(typeof(q)) == Int
             @test q.blksize == DataStructures.DEFAULT_DEQUEUE_BLOCKSIZE
-            @test_throws ArgumentError front(q)
-            @test_throws ArgumentError back(q)
+            @test_throws ArgumentError first(q)
+            @test_throws ArgumentError last(q)
             @test length(sprint(dump,q)) >= 0
         end
 
@@ -30,8 +30,8 @@
             @test isempty(q)
             @test q.blksize == 3
             @test num_blocks(q) == 1
-            @test_throws ArgumentError front(q)
-            @test_throws ArgumentError back(q)
+            @test_throws ArgumentError first(q)
+            @test_throws ArgumentError last(q)
             @test isa(collect(q), Vector{Int})
             @test collect(q) == Int[]
         end
@@ -40,18 +40,18 @@
     @testset "Core Functionality" begin
         n = 10
 
-        @testset "push back / pop back" begin
+        @testset "push last / pop last" begin
             q = Deque{Int}(3)
 
-            @testset "push back" begin
+            @testset "push last" begin
                 for i = 1 : n
                     push!(q, i)
                     @test length(q) == i
                     @test isempty(q) == false
                     @test num_blocks(q) == div(i-1, 3) + 1
 
-                    @test front(q) == 1
-                    @test back(q) == i
+                    @test first(q) == 1
+                    @test last(q) == i
 
                     k = 1
                     for j in q
@@ -65,7 +65,7 @@
                 end
             end
 
-            @testset "pop back" begin
+            @testset "pop last" begin
                 for i = 1 : n
                     x = pop!(q)
                     @test length(q) == n - i
@@ -74,11 +74,11 @@
                     @test x == n - i + 1
 
                     if !isempty(q)
-                        @test front(q) == 1
-                        @test back(q) == n - i
+                        @test first(q) == 1
+                        @test last(q) == n - i
                     else
-                        @test_throws ArgumentError front(q)
-                        @test_throws ArgumentError back(q)
+                        @test_throws ArgumentError first(q)
+                        @test_throws ArgumentError last(q)
                     end
 
                     cq = collect(q)
@@ -87,26 +87,26 @@
             end
         end
 
-        @testset "push front / pop front" begin
+        @testset "push first / pop first" begin
             q = Deque{Int}(3)
 
-            @testset "push front" begin
+            @testset "push first" begin
                 for i = 1 : n
                     pushfirst!(q, i)
                     @test length(q) == i
                     @test isempty(q) == false
                     @test num_blocks(q) == div(i-1, 3) + 1
 
-                    @test front(q) == i
-                    @test back(q) == 1
+                    @test first(q) == i
+                    @test last(q) == 1
 
                     cq = collect(q)
                     @test isa(cq, Vector{Int})
                     @test cq == collect(i:-1:1)
                 end
             end
 
-            @testset "pop front" begin
+            @testset "pop first" begin
                 for i = 1 : n
                     x = popfirst!(q)
                     @test length(q) == n - i
@@ -115,11 +115,11 @@
                     @test x == n - i + 1
 
                     if !isempty(q)
-                        @test front(q) == n - i
-                        @test back(q) == 1
+                        @test first(q) == n - i
+                        @test last(q) == 1
                     else
-                        @test_throws ArgumentError front(q)
-                        @test_throws ArgumentError back(q)
+                        @test_throws ArgumentError first(q)
+                        @test_throws ArgumentError last(q)
                     end
 
                     cq = collect(q)