Repository: JuliaCollections/DataStructures.jl
Pull request #565 (2020-01-02 14:14:17)

Use first and last, rather than front, back, top etc
Changes made in docs,src and test folders

codecov[bot]: # [Codecov](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/565?src=pr&el=h1) Report
> Merging [#565](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/565?src=pr&el=desc) into [master](https://codecov.io/gh/JuliaCollections/DataStructures.jl/commit/685d33d4863e66c6e4d2b4b8eda1c2cce823d41e?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/565/graphs/tree.svg?width=650&token=7FHvoCSQ7k&height=150&src=pr)](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/565?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master     #565   +/-   ##
=======================================
  Coverage   87.82%   87.82%           
=======================================
  Files          32       32           
  Lines        2087     2087           
=======================================
  Hits         1833     1833           
  Misses        254      254
```


| [Impacted Files](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/565?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [src/circ\_deque.jl](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/565/diff?src=pr&el=tree#diff-c3JjL2NpcmNfZGVxdWUuamw=) | `100% <100%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/565?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/565?src=pr&el=footer). Last update [685d33d...983f8e7](https://codecov.io/gh/JuliaCollections/DataStructures.jl/pull/565?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

krish8484: @oxinabox will the @deprecate come in the src folder of each data structure namely; queue.jl, dequeue.jl and circ-queue.jl, right?
krish8484: @oxinabox there was a back function in stack as well, which was causing the build tests to fail, replaced that, now it's fine
oxinabox: If you add a `src/deprecations.jl` file I think that would be best.
The deprecation belongs to all of them but you only need to implement it once.
oxinabox: Remaining:

- [ ] update docstring and tests and deprecation for `top`
- [ ] `include(...)` the deprecation file in the main `src/DataStructures.jl`
- [ ] remove the exports of the deprecated names. (`@deprecate` does export automatically)
oxinabox: I changed the name back.
Note that we have automatic release notes that say what was in a release.
https://github.com/JuliaCollections/DataStructures.jl/releases
krish8484: I reckon, that should be it! @oxinabox 
krish8484: I reckon, we are done!

Patch:
diff --git a/Project.toml b/Project.toml
index 79f4203..4f6b945 100644
--- 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
index 8ed5472..f87b38f 100644
--- 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
index ed13afa..34d95a1 100644
--- 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
index cc805be..da3f284 100644
--- 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
index cad5f76..8f73447 100644
--- 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
index 59d1319..750f2f7 100644
--- 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
new file mode 100644
index 0000000..6740785
--- /dev/null
+++ b/src/deprecations.jl
@@ -0,0 +1,3 @@
+@deprecate front(x) first(x)
+@deprecate back(x) last(x)
+@deprecate top(x) first(x)
\ No newline at end of file
diff --git a/src/deque.jl b/src/deque.jl
index 364d90c..16b4c1a 100644
--- 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
index 5fe6606..8bc8ebb 100644
--- 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
index 8259ca9..25c54f4 100644
--- 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)


Test patch:
diff --git a/test/test_circ_deque.jl b/test/test_circ_deque.jl
index 90f96ee..adf3ddd 100644
--- 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,9 +49,9 @@
         @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)
@@ -59,7 +59,7 @@
         @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
@@ -67,13 +67,13 @@
     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
index b651091..62d4015 100644
--- 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,18 +87,18 @@
             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})
@@ -106,7 +106,7 @@
                 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)
diff --git a/test/test_queue.jl b/test/test_queue.jl
index 146155e..a1c421b 100644
--- a/test/test_queue.jl
+++ b/test/test_queue.jl
@@ -16,14 +16,14 @@
         @test eltype(s) == Int
         @test eltype(typeof(s)) == Int
         @test isempty(s)
-        @test_throws ArgumentError front(s)
-        @test_throws ArgumentError back(s)
+        @test_throws ArgumentError first(s)
+        @test_throws ArgumentError last(s)
         @test_throws ArgumentError dequeue!(s)
 
         for i = 1 : n
             enqueue!(s, i)
-            @test front(s) == 1
-            @test back(s) == i
+            @test first(s) == 1
+            @test last(s) == i
             @test !isempty(s)
             @test length(s) == i
         end
@@ -32,11 +32,11 @@
             x = dequeue!(s)
             @test x == i
             if i < n
-                @test front(s) == i + 1
-                @test back(s) == n
+                @test first(s) == i + 1
+                @test last(s) == n
             else
-                @test_throws ArgumentError front(s)
-                @test_throws ArgumentError back(s)
+                @test_throws ArgumentError first(s)
+                @test_throws ArgumentError last(s)
             end
             @test isempty(s) == (i == n)
             @test length(s) == n - i
diff --git a/test/test_stack.jl b/test/test_stack.jl
index 9963c54..448675f 100644
--- a/test/test_stack.jl
+++ b/test/test_stack.jl
@@ -17,12 +17,12 @@
         @test isempty(s)
         @test eltype(s) == Int
         @test eltype(typeof(s)) == Int
-        @test_throws ArgumentError top(s)
+        @test_throws ArgumentError first(s)
         @test_throws ArgumentError pop!(s)
 
         for i = 1 : n
             push!(s, i)
-            @test top(s) == i
+            @test first(s) == i
             @test !isempty(s)
             @test length(s) == i
         end
@@ -31,9 +31,9 @@
             x = pop!(s)
             @test x == n - i + 1
             if i < n
-                @test top(s) == n - i
+                @test first(s) == n - i
             else
-                @test_throws ArgumentError top(s)
+                @test_throws ArgumentError first(s)
             end
             @test isempty(s) == (i == n)
             @test length(s) == n - i