Merge pull request #800 from lfenzo/docs-revamp-deque

Improved Deque Documentation + docstrings

Author: oxinabox

docs/src/deque.md

@@ -1,29 +1,51 @@
 # Deque
 
-The `Deque` type implements a double-ended queue using a list of blocks.
-This data structure supports constant-time insertion/removal of elements
-at both ends of a sequence.
-
-Usage:
-
-```julia
-a = Deque{Int}()
-isempty(a)          # test whether the dequeue is empty
-length(a)           # get the number of elements
-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
-first(a)            # get the element at the front
-last(a)             # get the element at the back
-```
+A Deque (short for Double-ended Queue) is an abstract data type that generalizes
+a Queue for which elements can be added to or removed from both the front (head)
+and the back (tail) in $O(1)$ time complexity.
+
+The type `Deque` implements the Double-ended Queue as a list of fixed-size blocks
+using an [unrolled linked list](https://en.wikipedia.org/wiki/Unrolled_linked_list).
 
-*Note:* Julia's `Vector` type also provides this interface, and thus can
-be used as a deque. However, the `Deque` type in this package is
-implemented as a list of contiguous blocks (default size = 2K). As a
-deque grows, new blocks may be created and linked to existing blocks.
-This way avoids the copying when growing a vector.
+!!! note
+    Julia's `Vector` type also provides this interface, and thus can
+    be used as a deque. However, the `Deque` type in DataStructures.jl is
+    implemented as a list of contiguous blocks (default size = 1 kilo-byte). As a
+    Deque grows, new blocks are created and linked to existing blocks.
+    This apprach prevents copying operations that take place when growing a `Vector`.
 
 Benchmark shows that the performance of `Deque` is comparable to
-`Vector` on `push!`, and is noticeably faster on `pushfirst!` (by about
+`Vector` on `push!`, but is noticeably faster on `pushfirst!` (by about
 30% to 40%).
+
+
+## Constructors
+
+```@autodocs
+Modules = [DataStructures]
+Pages = ["src/deque.jl"]
+Order = [:type] # only types
+```
+
+## Usage
+
+The `Deque` implements the following methods:
+
+- [`==(x::Deque, y::Deque)`](@ref)
+- [`empty!(d::Deque{T}) where T`](@ref)
+- [`first(d::Deque)`](@ref)
+- [`isempty(d::Deque)`](@ref)
+- [`last(d::Deque)`](@ref)
+- [`length(d::Deque)`](@ref)
+- [`pop!(d::Deque{T}) where T`](@ref)
+- [`popfirst!(d::Deque{T}) where T`](@ref)
+- [`push!(d::Deque{T}, x) where T`](@ref)
+- [`pushfirst!(d::Deque{T}, x) where T`](@ref)
+
+-------
+
+```@autodocs
+Modules = [DataStructures]
+Pages = ["src/deque.jl"]
+Order = [:function] # only functions
+```

src/deque.jl

@@ -60,11 +60,16 @@ const DEFAULT_DEQUEUE_BLOCKSIZE = 1024
 
 """
     Deque{T}
+    Deque{T}(blksize::Int) where T
 
-The Deque type implements a double-ended queue using a list of blocks.
-This data structure supports constant-time insertion/removal
-of elements at both ends of a sequence.
+Constructs `Deque` object for elements of type `T`.
 
+Parameters
+----------
+
+`T::Type` Deque element data type.
+
+`blksize::Int` Deque block size (in bytes). Default = 1024.
 """
 mutable struct Deque{T}
     nblocks::Int
@@ -81,43 +86,54 @@ mutable struct Deque{T}
     Deque{T}() where {T} = Deque{T}(DEFAULT_DEQUEUE_BLOCKSIZE)
 end
 
-Base.isempty(q::Deque) = q.len == 0
-Base.length(q::Deque) = q.len
-num_blocks(q::Deque) = q.nblocks
+"""
+    isempty(d::Deque)
+
+Verifies if deque `d` is empty.
+"""
+Base.isempty(d::Deque) = d.len == 0
+
+"""
+    length(d::Deque) 
+
+Returns the number of elements in deque `d`.
+"""
+Base.length(d::Deque) = d.len
+num_blocks(d::Deque) = d.nblocks
 Base.eltype(::Type{Deque{T}}) where T = T
 
 """
-    first(q::Deque)
+    first(d::Deque)
 
-Returns the first element of the deque `q`.
+Returns the first element of the deque `d`.
 """
-function Base.first(q::Deque)
-    isempty(q) && throw(ArgumentError("Deque must be non-empty"))
-    blk = q.head
+function Base.first(d::Deque)
+    isempty(d) && throw(ArgumentError("Deque must be non-empty"))
+    blk = d.head
     return blk.data[blk.front]
 end
 
 """
-    last(q::Deque)
+    last(d::Deque)
 
-Returns the last element of the deque `q`.
+Returns the last element of the deque `d`.
 """
-function Base.last(q::Deque)
-    isempty(q) && throw(ArgumentError("Deque must be non-empty"))
-    blk = q.rear
+function Base.last(d::Deque)
+    isempty(d) && throw(ArgumentError("Deque must be non-empty"))
+    blk = d.rear
     return blk.data[blk.back]
 end
 
 
 # Iteration
 
 struct DequeIterator{T}
-    q::Deque{T}
+    d::Deque{T}
 end
 
-Base.last(qi::DequeIterator) = last(qi.q)
+Base.last(di::DequeIterator) = last(di.d)
 
-function Base.iterate(qi::DequeIterator{T}, (cb, i) = (qi.q.head, qi.q.head.front)) where T
+function Base.iterate(di::DequeIterator{T}, (cb, i) = (di.d.head, di.d.head.front)) where T
     i > cb.back && return nothing
     x = cb.data[i]
 
@@ -132,7 +148,7 @@ end
 
 # Backwards deque iteration
 
-function Base.iterate(qi::Iterators.Reverse{<:Deque}, (cb, i) = (qi.itr.rear, qi.itr.rear.back))
+function Base.iterate(di::Iterators.Reverse{<:Deque}, (cb, i) = (di.itr.rear, di.itr.rear.back))
     i < cb.front && return nothing
     x = cb.data[i]
 
@@ -146,21 +162,21 @@ function Base.iterate(qi::Iterators.Reverse{<:Deque}, (cb, i) = (qi.itr.rear, qi
     return (x, (cb, i))
 end
 
-Base.iterate(q::Deque{T}, s...) where {T} = iterate(DequeIterator{T}(q), s...)
+Base.iterate(d::Deque{T}, s...) where {T} = iterate(DequeIterator{T}(d), s...)
 
-Base.length(qi::DequeIterator{T}) where {T} = qi.q.len
+Base.length(di::DequeIterator{T}) where {T} = di.d.len
 
-Base.collect(q::Deque{T}) where {T} = T[x for x in q]
+Base.collect(d::Deque{T}) where {T} = T[x for x in d]
 
 # Showing
 
-function Base.show(io::IO, q::Deque)
-    print(io, "Deque [$(collect(q))]")
+function Base.show(io::IO, d::Deque)
+    print(io, "Deque [$(collect(d))]")
 end
 
-function Base.dump(io::IO, q::Deque)
-    println(io, "Deque (length = $(q.len), nblocks = $(q.nblocks))")
-    cb::DequeBlock = q.head
+function Base.dump(io::IO, d::Deque)
+    println(io, "Deque (length = $(d.len), nblocks = $(d.nblocks))")
+    cb::DequeBlock = d.head
     i = 1
     while true
         print(io, "block $i [$(cb.front):$(cb.back)] ==> ")
@@ -184,38 +200,38 @@ end
 # Manipulation
 
 """
-    empty!(q::Deque{T})
+    empty!(d::Deque{T}) where T
 
-Reset the deque.
+Reset the deque `d`.
 """
-function Base.empty!(q::Deque{T}) where T
+function Base.empty!(d::Deque{T}) where T
     # release all blocks except the head
-    if q.nblocks > 1
-        cb::DequeBlock{T} = q.rear
-        while cb != q.head
+    if d.nblocks > 1
+        cb::DequeBlock{T} = d.rear
+        while cb != d.head
             empty!(cb.data)
             cb = cb.prev
         end
     end
 
     # clean the head block (but retain the block itself)
-    reset!(q.head, 1)
+    reset!(d.head, 1)
 
     # reset queue fields
-    q.nblocks = 1
-    q.len = 0
-    q.rear = q.head
-    return q
+    d.nblocks = 1
+    d.len = 0
+    d.rear = d.head
+    return d
 end
 
 
 """
-    push!(q::Deque{T}, x)
+    push!(d::Deque{T}, x) where T
 
-Add an element to the back
+Add an element to the back of deque `d`.
 """
-function Base.push!(q::Deque{T}, x) where T
-    rear = q.rear
+function Base.push!(d::Deque{T}, x) where T
+    rear = d.rear
 
     if isempty(rear)
         rear.front = 1
@@ -225,24 +241,24 @@ function Base.push!(q::Deque{T}, x) where T
     if rear.back < rear.capa
         @inbounds rear.data[rear.back += 1] = convert(T, x)
     else
-        new_rear = rear_deque_block(T, q.blksize)
+        new_rear = rear_deque_block(T, d.blksize)
         new_rear.back = 1
         new_rear.data[1] = convert(T, x)
         new_rear.prev = rear
-        q.rear = rear.next = new_rear
-        q.nblocks += 1
+        d.rear = rear.next = new_rear
+        d.nblocks += 1
     end
-    q.len += 1
-    return q
+    d.len += 1
+    return d
 end
 
 """
-    pushfirst!(q::Deque{T}, x)
+    pushfirst!(d::Deque{T}, x) where T
 
-Add an element to the front
+Add an element to the front of deque `d`.
 """
-function Base.pushfirst!(q::Deque{T}, x) where T
-    head = q.head
+function Base.pushfirst!(d::Deque{T}, x) where T
+    head = d.head
 
     if isempty(head)
         n = head.capa
@@ -253,65 +269,65 @@ function Base.pushfirst!(q::Deque{T}, x) where T
     if head.front > 1
         @inbounds head.data[head.front -= 1] = convert(T, x)
     else
-        n::Int = q.blksize
+        n::Int = d.blksize
         new_head = head_deque_block(T, n)
         new_head.front = n
         new_head.data[n] = convert(T, x)
         new_head.next = head
-        q.head = head.prev = new_head
-        q.nblocks += 1
+        d.head = head.prev = new_head
+        d.nblocks += 1
     end
-    q.len += 1
-    return q
+    d.len += 1
+    return d
 end
 
 """
-    pop!(q::Deque{T})
+    pop!(d::Deque{T}) where T
 
-Remove the element at the back
+Remove the element at the back of deque `d`.
 """
-function Base.pop!(q::Deque{T}) where T
-    isempty(q) && throw(ArgumentError("Deque must be non-empty"))
-    rear = q.rear
+function Base.pop!(d::Deque{T}) where T
+    isempty(d) && throw(ArgumentError("Deque must be non-empty"))
+    rear = d.rear
     @assert rear.back >= rear.front
 
     @inbounds x = rear.data[rear.back]
     rear.back -= 1
     if rear.back < rear.front
-        if q.nblocks > 1
+        if d.nblocks > 1
             # release and detach the rear block
             empty!(rear.data)
-            q.rear = rear.prev::DequeBlock{T}
-            q.rear.next = q.rear
-            q.nblocks -= 1
+            d.rear = rear.prev::DequeBlock{T}
+            d.rear.next = d.rear
+            d.nblocks -= 1
         end
     end
-    q.len -= 1
+    d.len -= 1
     return x
 end
 
 """
-    popfirst!(q::Deque{T})
+    popfirst!(d::Deque{T}) where T
 
-Remove the element at the front
+Remove the element at the front of deque `d`.
 """
-function Base.popfirst!(q::Deque{T}) where T
-    isempty(q) && throw(ArgumentError("Deque must be non-empty"))
-    head = q.head
+function Base.popfirst!(d::Deque{T}) where T
+    isempty(d) && throw(ArgumentError("Deque must be non-empty"))
+    head = d.head
     @assert head.back >= head.front
 
     @inbounds x = head.data[head.front]
     head.front += 1
     if head.back < head.front
-        if q.nblocks > 1
+        if d.nblocks > 1
             # release and detach the head block
             empty!(head.data)
-            q.head = head.next::DequeBlock{T}
-            q.head.prev = q.head
-            q.nblocks -= 1
+            d.head = head.next::DequeBlock{T}
+            d.head.prev = d.head
+            d.nblocks -= 1
         end
     end
-    q.len -= 1
+    d.len -= 1
     return x
 end
 
@@ -324,6 +340,11 @@ function Base.hash(x::Deque, h::UInt)
     return h
 end
 
+"""
+    ==(x::Deque, y::Deque)
+
+Verify if the deques `x` and `y` are equal in terms of their contents.
+"""
 function Base.:(==)(x::Deque, y::Deque)
     length(x) != length(y) && return false
     for (i, j) in zip(x, y)