empty!() for CircularDeque, add it to docs, add some other missing th…

…ings to docs (#317)

* Add empty!() for CircularBuffer. Add circ_buffer.rst to docs. Add circ_buffer.rst and missing priority-queue.rst to index.rst
* Add missing CircularDeque functions to docs.
* Move * Priority Queue to under * Queue
* empty!(cb) = cb.first = 1; empty!(cb.buffer)
* Add empty!(cb) test

README.rst

@@ -28,6 +28,8 @@ DataStructures.jl
 This package implements a variety of data structures, including
 
 * Deque (based on block-list)
+* CircularBuffer
+* CircularDeque
 * Stack
 * Queue
 * Accumulators and Counters

doc/source/circ_buffer.rst

@@ -0,0 +1,24 @@
+.. _ref-circular_buffer:
+
+--------------
+CircularBuffer
+--------------
+
+The ``CircularBuffer`` type implements a circular buffer of fixed ``capacity`` where new items are pushed to the back of the list, overwriting values in a circular fashion.
+
+Usage::
+
+  a = CircularBuffer{Int}(n)   # allocate an Int buffer with maximum capacity n
+  isfull(a)           # test whether the buffer is full
+  isempty(a)          # test whether the buffer is empty
+  empty!(a)           # reset the buffer
+  capacity(a)         # return capacity
+  length(a)           # get the number of elements currently in the buffer
+  size(a)             # same as length(a)
+  push!(a, 10)        # add an element to the back and overwrite front if full
+  unshift!(a, 10)     # add an element to the front and overwrite back if full
+  append!(a, [1, 2, 3, 4])    # push at most last `capacity` items
+  convert(Vector{Float64}, a) # convert items to type Float64
+  eltype(a)           # return type of items
+  a[1]                # get the element at the front
+  a[end]              # get the element at the back

doc/source/circ_deque.rst

@@ -10,13 +10,16 @@ Usage::
 
   a = CircularDeque{Int}(n)   # allocate a deque with maximum capacity n
   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
   pop!(a)             # remove an element from the back
   unshift!(a, 20)     # add an element to the front
   shift!(a)           # remove an element from the front
   front(a)            # get the element at the front
   back(a)             # get the element at the back
+  eltype(a)           # return type of items
 
 *Note:* Julia's ``Vector`` type also provides this interface, and thus can be used as a deque. However, the ``CircularDeque`` type in this package is implemented as a circular buffer, and thus avoids copying elements when modifications are made to the front of the vector.
 

doc/source/index.rst

@@ -4,9 +4,11 @@ DataStructures.jl
 This package implements a variety of data structures, including
 
 * Deque (based on block-list)
+* CircularBuffer
 * CircularDeque (based on a circular buffer)
 * Stack
 * Queue
+* Priority Queue
 * Accumulators and Counters
 * Disjoint Sets
 * Binary Heap
@@ -24,8 +26,10 @@ Contents:
    :maxdepth: 2
 
    deque.rst
+   circ_buffer.rst
    circ_deque.rst
    stack_and_queue.rst
+   priority-queue.rst
    accumulators.rst
    disjoint_sets.rst
    heaps.rst
@@ -43,4 +47,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

src/circular_buffer.jl

@@ -9,6 +9,11 @@ type CircularBuffer{T} <: AbstractVector{T}
     (::Type{CircularBuffer{T}}){T}(capacity::Int) = new{T}(capacity, 1, T[])
 end
 
+function Base.empty!(cb::CircularBuffer)
+    cb.first = 1
+    empty!(cb.buffer)
+end
+
 function _buffer_index(cb::CircularBuffer, i::Int)
     n = length(cb)
     if i < 1 || i > n
@@ -54,7 +59,7 @@ function Base.unshift!(cb::CircularBuffer, data)
 end
 
 function Base.append!(cb::CircularBuffer, datavec::AbstractVector)
-    # push at most `capacity` items
+    # push at most last `capacity` items
     n = length(datavec)
     for i in max(1, n-capacity(cb)+1):n
         push!(cb, datavec[i])

test/test_circular_buffer.jl

@@ -43,4 +43,7 @@ using Base.Test
     for (idx, n) in enumerate(5:1)
         @test arr[idx] == n
     end
+
+    # test empty!(cb)
+    @test length(empty!(cb)) == 0
 end