unexport lag and lead (#55)

* unexport lag and lead

* updated doctests

* update docs and remove unneeded section

* doc fixes

Author: piever

NEWS.md

@@ -1,22 +1,30 @@
+## ShiftedArrays 2.0.0 release notes
+
+### Breaking changes
+
+- Indexing out of bounds now gives a `BoundsError` (instead of returning the default value for `ShiftedArray` or the circularly shifted value for `CircShiftedArray`).
+- `lag` and `lead` are no longer exported (but still public API).
+- Calling `ShiftedArray(v::ShiftedArray, n)` or `CircShiftedArray(v::CircShiftedArray, n)` does not nest but rather combines the shifts additively.
+
 ## ShiftedArrays 1.0.0 release notes
 
 ### Breaking changes
 
-- Removed special `reduce, reduce_vec, mapreduce, mapreduce_vec` methods
-- Removed `to_array, to_offsetarray` methods
+- Removed special `reduce, reduce_vec, mapreduce, mapreduce_vec` methods.
+- Removed `to_array, to_offsetarray` methods.
 
 ## ShiftedArrays 0.5.1 release notes
 
 ### New features
 
-- Support for OffsetArrays v0.11
-- Support for RecursiveArrayTools v1
+- Support for OffsetArrays v0.11.
+- Support for RecursiveArrayTools v1.
 
 ## ShiftedArrays 0.5.0 release notes
 
 ### New features
 
-- Support for Julia 1
+- Support for Julia 1.
 
 ## ShiftedArrays 0.4 release notes
 
@@ -29,8 +37,8 @@
 
 ### New features
 
-- Allow custom default value with `default` keyword
-- Allow filtering in reduce-like functions with `filter` keyword
+- Allow custom default value with `default` keyword.
+- Allow filtering in reduce-like functions with `filter` keyword.
 
 ## ShiftedArrays 0.3 release notes
 
@@ -42,4 +50,4 @@
 ### New features
 
 - `CircShiftedArray` type to shift arrays circularly.
-- A lazy version of `circshift`: `ShiftedArray.circshift`
+- A lazy version of `circshift`: `ShiftedArray.circshift`.

docs/src/api.md

@@ -12,8 +12,8 @@ CircShiftedVector
 ## Shifting operations
 
 ```@docs
-lag
-lead
+ShiftedArrays.lag
+ShiftedArrays.lead
 ShiftedArrays.circshift
 ```
 

docs/src/index.md

@@ -8,25 +8,25 @@ A `ShiftedArray` is a lazy view of an Array, shifted on some or all of his index
 
 ```julia
 julia> v = reshape(1:16, 4, 4)
-4×4 Base.ReshapedArray{Int64,2,UnitRange{Int64},Tuple{}}:
+4×4 reshape(::UnitRange{Int64}, 4, 4) with eltype Int64:
  1  5   9  13
  2  6  10  14
  3  7  11  15
  4  8  12  16
 
- julia> s = ShiftedArray(v, (2, 0))
- 4×4 ShiftedArrays.ShiftedArray{Int64,2,Base.ReshapedArray{Int64,2,UnitRange{Int64},Tuple{}}}:
-   missing   missing    missing    missing
-   missing   missing    missing    missing
-  1         5          9         13       
-  2         6         10         14  
+julia> s = ShiftedArray(v, (2, 0))
+4×4 ShiftedArray{Int64, Missing, 2, Base.ReshapedArray{Int64, 2, UnitRange{Int64}, Tuple{}}}:
+  missing   missing    missing    missing
+  missing   missing    missing    missing
+ 1         5          9         13
+ 2         6         10         14 
 ```
 
 The parent Array as well as the amount of shifting can be recovered with `parent` and `shifts` respectively.
 
 ```julia
 julia> parent(s)
-4×4 Base.ReshapedArray{Int64,2,UnitRange{Int64},Tuple{}}:
+4×4 reshape(::UnitRange{Int64}, 4, 4) with eltype Int64:
  1  5   9  13
  2  6  10  14
  3  7  11  15
@@ -42,18 +42,18 @@ Use `copy` to collect the shifted data into an `Array`:
 
 ```julia
 julia> copy(s)
-4×4 Array{Union{Int64, Missing},2}:
+4×4 Matrix{Union{Missing, Int64}}:
   missing   missing    missing    missing
   missing   missing    missing    missing
- 1         5          9         13       
+ 1         5          9         13
  2         6         10         14   
 ```
 
 If you pass an integer, it will shift in the first dimension:
 
 ```julia
 julia> ShiftedArray(v, 1)
-4×4 ShiftedArrays.ShiftedArray{Int64,2,Base.ReshapedArray{Int64,2,UnitRange{Int64},Tuple{}}}:
+4×4 ShiftedArray{Int64, Missing, 2, Base.ReshapedArray{Int64, 2, UnitRange{Int64}, Tuple{}}}:
   missing   missing    missing    missing
  1         5          9         13
  2         6         10         14
@@ -64,25 +64,19 @@ A custom default value (other than `missing`) can be provided with the `default`
 
 ```julia
 julia> ShiftedArray([1.2, 3.1, 4.5], 1, default = NaN)
-3-element ShiftedArrays.ShiftedArray{Float64,Float64,1,Array{Float64,1}}:
+3-element ShiftedVector{Float64, Float64, Vector{Float64}}:
  NaN
    1.2
    3.1
 ```
 
 ### Out of bound indexes
 
-The bound check is performed only on the parent `Array`, not on the `ShiftedArray`, so for example:
+Accessing indexes outside the `ShiftedArray` give a `BoundsError`, even if the shifted index would have been valid in the parent array.
 
 ```julia
-julia> ShiftedArray([1.2, 3.1, 4.5], 1, default = NaN)[-2:3]
-6-element Array{Float64,1}:
- NaN
- NaN
- NaN
- NaN
-   1.2
-   3.1
+julia> ShiftedArray([1, 2, 3], 1)[4]
+ERROR: BoundsError: attempt to access 3-element ShiftedVector{Int64, Missing, Vector{Int64}} at index [4]
 ```
 
 ## Shifting the data
@@ -92,25 +86,25 @@ Using the `ShiftedArray` type, this package provides two operations for lazily s
 ```julia
 julia> v = [1, 3, 5, 4];
 
-julia> lag(v)
-4-element ShiftedArrays.ShiftedArray{Int64,1,Array{Int64,1}}:
+julia> ShiftedArrays.lag(v)
+4-element ShiftedVector{Int64, Missing, Vector{Int64}}:
   missing
- 1       
- 3       
+ 1
+ 3
  5       
 
-julia> v .- lag(v) # compute difference from previous element without unnecessary allocations
-4-element Array{Any,1}:
+julia> v .- ShiftedArrays.lag(v) # compute difference from previous element without unnecessary allocations
+4-element Vector{Union{Missing, Int64}}:
    missing
-  2       
-  2       
+  2
+  2
  -1       
 
-julia> s = lag(v, 2) # shift by more than one element
-4-element ShiftedArrays.ShiftedArray{Int64,1,Array{Int64,1}}:
+julia> s = ShiftedArrays.lag(v, 2) # shift by more than one element
+4-element ShiftedVector{Int64, Missing, Vector{Int64}}:
   missing
   missing
- 1       
+ 1
  3
 ```
 
@@ -119,11 +113,11 @@ julia> s = lag(v, 2) # shift by more than one element
 ```julia
 julia> v = [1, 3, 5, 4];
 
-julia> lead(v)
-4-element ShiftedArrays.ShiftedArray{Int64,1,Array{Int64,1}}:
- 3       
- 5       
- 4       
+julia> ShiftedArrays.lead(v)
+4-element ShiftedVector{Int64, Missing, Vector{Int64}}:
+ 3
+ 5
+ 4
   missing
 ```
 
@@ -140,7 +134,7 @@ Our implementation of `circshift` relies on them to avoid copying:
 julia> w = reshape(1:16, 4, 4);
 
 julia> s = ShiftedArrays.circshift(w, (1, -1))
-4×4 ShiftedArrays.CircShiftedArray{Int64,2,Base.ReshapedArray{Int64,2,UnitRange{Int64},Tuple{}}}:
+4×4 CircShiftedArray{Int64, 2, Base.ReshapedArray{Int64, 2, UnitRange{Int64}, Tuple{}}}:
  8  12  16  4
  5   9  13  1
  6  10  14  2
@@ -151,7 +145,7 @@ As usual, you can `copy` the result to have a normal `Array`:
 
 ```julia
 julia> copy(s)
-4×4 Array{Int64,2}:
+4×4 Matrix{Int64}:
  8  12  16  4
  5   9  13  1
  6  10  14  2

src/ShiftedArrays.jl

@@ -3,7 +3,6 @@ module ShiftedArrays
 import Base: checkbounds, getindex, setindex!, parent, size, axes
 export ShiftedArray, ShiftedVector, shifts, default
 export CircShiftedArray, CircShiftedVector
-export lag, lead
 
 include("shiftedarray.jl")
 include("circshiftedarray.jl")

src/lag.jl

@@ -12,7 +12,7 @@ remaining dimensions is assumed to be `0`.
 ```jldoctest lag
 julia> v = [1, 3, 5, 4];
 
-julia> lag(v)
+julia> ShiftedArrays.lag(v)
 4-element ShiftedVector{Int64, Missing, Vector{Int64}}:
   missing
  1
@@ -22,7 +22,7 @@ julia> lag(v)
 julia> w = 1:2:9
 1:2:9
 
-julia> s = lag(w, 2)
+julia> s = ShiftedArrays.lag(w, 2)
 5-element ShiftedVector{Int64, Missing, StepRange{Int64, Int64}}:
   missing
   missing
@@ -40,7 +40,7 @@ julia> copy(s)
 
 julia> v = reshape(1:16, 4, 4);
 
-julia> s = lag(v, (0, 2))
+julia> s = ShiftedArrays.lag(v, (0, 2))
 4×4 ShiftedArray{Int64, Missing, 2, Base.ReshapedArray{Int64, 2, UnitRange{Int64}, Tuple{}}}:
  missing  missing  1  5
  missing  missing  2  6
@@ -66,7 +66,7 @@ remaining dimensions is assumed to be `0`.
 ```jldoctest lead
 julia> v = [1, 3, 5, 4];
 
-julia> lead(v)
+julia> ShiftedArrays.lead(v)
 4-element ShiftedVector{Int64, Missing, Vector{Int64}}:
  3
  5
@@ -76,7 +76,7 @@ julia> lead(v)
 julia> w = 1:2:9
 1:2:9
 
-julia> s = lead(w, 2)
+julia> s = ShiftedArrays.lead(w, 2)
 5-element ShiftedVector{Int64, Missing, StepRange{Int64, Int64}}:
  5
  7
@@ -94,7 +94,7 @@ julia> copy(s)
 
 julia> v = reshape(1:16, 4, 4);
 
-julia> s = lead(v, (0, 2))
+julia> s = ShiftedArrays.lead(v, (0, 2))
 4×4 ShiftedArray{Int64, Missing, 2, Base.ReshapedArray{Int64, 2, UnitRange{Int64}, Tuple{}}}:
   9  13  missing  missing
  10  14  missing  missing

test/runtests.jl

@@ -163,22 +163,22 @@ end
 
 @testset "laglead" begin
     v = [1, 3, 8, 12]
-    diff = v .- lag(v)
+    diff = v .- ShiftedArrays.lag(v)
     @test isequal(diff, [missing, 2, 5, 4])
 
-    diff2 = v .- lag(v, 2)
+    diff2 = v .- ShiftedArrays.lag(v, 2)
     @test isequal(diff2, [missing, missing, 7, 9])
 
-    @test all(lag(v, 2, default = -100) .== coalesce.(lag(v, 2), -100))
+    @test all(ShiftedArrays.lag(v, 2, default = -100) .== coalesce.(ShiftedArrays.lag(v, 2), -100))
 
-    diff = v .- lead(v)
+    diff = v .- ShiftedArrays.lead(v)
     @test isequal(diff, [-2, -5, -4, missing])
 
-    diff2 = v .- lead(v, 2)
+    diff2 = v .- ShiftedArrays.lead(v, 2)
     @test isequal(diff2, [-7, -9, missing, missing])
 
-    @test all(lead(v, 2, default = -100) .== coalesce.(lead(v, 2), -100))
+    @test all(ShiftedArrays.lead(v, 2, default = -100) .== coalesce.(ShiftedArrays.lead(v, 2), -100))
 
-    @test lag(lag(v, 1), 2) === lag(v, 3)
-    @test lead(lead(v, 1), 2) === lead(v, 3)
+    @test ShiftedArrays.lag(ShiftedArrays.lag(v, 1), 2) === ShiftedArrays.lag(v, 3)
+    @test ShiftedArrays.lead(ShiftedArrays.lead(v, 1), 2) === ShiftedArrays.lead(v, 3)
 end