Clarify _buffer_index behavior

Author: jeremiahpslewis

src/CircularArrayBuffers.jl

@@ -76,24 +76,42 @@ capacity(cb::CircularArrayBuffer{T,N}) where {T,N} = size(cb.buffer, N)
 isfull(cb::CircularArrayBuffer) = cb.nframes == capacity(cb)
 Base.isempty(cb::CircularArrayBuffer) = cb.nframes == 0
 
+"""
+    _buffer_index(cb::CircularArrayBuffer, i::Int)
+
+    Return the index of the `i`-th element in the buffer.
+"""
 @inline function _buffer_index(cb::CircularArrayBuffer, i::Int)
-    ind = (cb.first - 1) * cb.step_size + i
-    if ind > length(cb.buffer)
-        ind - length(cb.buffer)
+    idx = (cb.first - 1) * cb.step_size + i
+    return wrap_index(idx, length(cb.buffer))
+end
+@inline _buffer_index(cb::CircularArrayBuffer, I::AbstractVector{<:Integer}) = map(Base.Fix1(_buffer_index, cb), I)
+
+"""
+    wrap_index(idx, n)
+
+    Return the index of the `idx`-th element in the buffer, if index is one past the size, return 1, else error.
+"""
+function wrap_index(idx, n)
+    if idx <= n
+        return idx
+    elseif idx <= 2n
+        return idx - n
     else
-        ind
+        @info "oops! idx $(idx) > 2n $(2n)"
+        return idx - n
     end
 end
-@inline _buffer_index(cb::CircularArrayBuffer, I::AbstractVector{<:Integer}) = map(Base.Fix1(_buffer_index, cb), I)
 
+"""
+    _buffer_frame(cb::CircularArrayBuffer, i::Int)
+
+    Return the index of the `i`-th frame in the buffer.
+"""
 @inline function _buffer_frame(cb::CircularArrayBuffer, i::Int)
     n = capacity(cb)
     idx = cb.first + i - 1
-    if idx > n
-        idx - n
-    else
-        idx
-    end
+    return wrap_index(idx, n)
 end
 
 _buffer_frame(cb::CircularArrayBuffer, I::CartesianIndex) = CartesianIndex(map(i->_buffer_frame(cb, i), Tuple(I)))

test/runtests.jl

@@ -231,7 +231,7 @@ if CUDA.functional()
             @test isempty(b) == true
             @test length(b) == 0
             @test size(b) == (0,)
-            # element must has the exact same length with the element of buffer
+            # element must have the exact same length with the element of buffer
             @test_throws Exception push!(b, [1, 2])
 
             for x in 1:3