diff --git a/NEWS.md b/NEWS.md index d653b72..1fc241d 100644 --- a/NEWS.md +++ b/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`. diff --git a/docs/src/api.md b/docs/src/api.md index 0ce5e97..d2bd672 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -12,8 +12,8 @@ CircShiftedVector ## Shifting operations ```@docs -lag -lead +ShiftedArrays.lag +ShiftedArrays.lead ShiftedArrays.circshift ``` diff --git a/docs/src/index.md b/docs/src/index.md index 2245371..bc1d27d 100644 --- a/docs/src/index.md +++ b/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,10 +42,10 @@ 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 ``` @@ -53,7 +53,7 @@ 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,7 +64,7 @@ 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 @@ -72,17 +72,11 @@ julia> ShiftedArray([1.2, 3.1, 4.5], 1, default = NaN) ### 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 diff --git a/src/ShiftedArrays.jl b/src/ShiftedArrays.jl index fe1c765..20b6f82 100644 --- a/src/ShiftedArrays.jl +++ b/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") diff --git a/src/lag.jl b/src/lag.jl index 899f384..6dde9f3 100644 --- a/src/lag.jl +++ b/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 diff --git a/test/runtests.jl b/test/runtests.jl index 78288e4..4415ed5 100644 --- a/test/runtests.jl +++ b/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