add center/centered helpers (#242)

Author: johnnychen94

docs/src/index.md

@@ -63,6 +63,20 @@ OffsetArray(A, OffsetArrays.Origin(-1, -1))
 OffsetArray(OA, OffsetArrays.Origin(-1, -1))
 ```
 
+Sometimes, it will be convenient to shift the center coordinate of the given array to `(0, 0, ...)`,
+`OffsetArrays.centered` is a helper for this very purpose:
+
+```@repl index
+Ao = OffsetArrays.centered(A)
+Ao[0, 0] == 8.0
+```
+
+and `OffsetArrays.center` tells you the center coordinate of given array:
+
+```@repl index
+c = OffsetArrays.center(A)
+A[c...] == 8.0
+```
 
 ## Example: Relativistic Notation
 

src/OffsetArrays.jl

@@ -626,6 +626,75 @@ _no_offset_view(::Tuple{<:Base.OneTo,Vararg{<:Base.OneTo}}, A::AbstractUnitRange
 _no_offset_view(::Any, A::AbstractArray) = OffsetArray(A, Origin(1))
 _no_offset_view(::Any, A::AbstractUnitRange) = UnitRange(A)
 
+#####
+# center/centered
+# These two helpers are deliberately not exported; their meaning can be very different in
+# other scenarios and will be very likely to cause name conflicts if exported.
+#####
+"""
+    center(A, [r::RoundingMode=RoundDown])::Dims
+
+Return the center coordinate of given array `A`. If `size(A, k)` is even,
+a rounding procedure will be applied with mode `r`.
+
+!!! compat "OffsetArrays 1.9"
+    This method requires at least OffsetArrays 1.9.
+
+# Examples
+
+```jldoctest; setup=:(using OffsetArrays)
+A = reshape(collect(1:9), 3, 3)
+c = OffsetArrays.center(A) # (2, 2)
+A[c...] == 5 # true
+
+Ao = OffsetArray(A, -2, -2)
+c = OffsetArrays.center(Ao) # (0, 0)
+Ao[c...] == 5 # true
+
+# output
+true
+```
+
+To shift the center coordinate of the given array to `(0, 0, ...)`, you
+can use [`centered`](@ref OffsetArrays.centered).
+"""
+function center(A::AbstractArray, r::RoundingMode=RoundDown)
+    map(axes(A)) do inds
+        round(Int, (length(inds)-1)/2, r) + first(inds)
+    end
+end
+
+"""
+    centered(A, r::RoundingMode=RoundDown) -> Ao
+
+Shift the center coordinate of array `A` to `(0, 0, ...)`. If `size(A, k)`
+is even, a rounding procedure will be applied with mode `r`.
+
+!!! compat "OffsetArrays 1.9"
+    This method requires at least OffsetArrays 1.9.
+
+# Examples
+
+```jldoctest; setup=:(using OffsetArrays)
+A = reshape(collect(1:9), 3, 3)
+Ao = OffsetArrays.centered(A)
+Ao[0, 0] == 5 # true
+
+A = reshape(collect(1:9), 3, 3)
+Ao = OffsetArray(A, OffsetArrays.Origin(0))
+Aoo = OffsetArrays.centered(Ao)
+Aoo[0, 0] == 5 # true
+
+# output
+true
+```
+
+To query the center coordinate of the given array, you can
+instead use [`center`](@ref OffsetArrays.center).
+"""
+centered(A::AbstractArray, r::RoundingMode=RoundDown) = OffsetArray(A, .-center(A, r))
+
+
 ####
 # work around for segfault in searchsorted*
 #  https://github.com/JuliaLang/julia/issues/33977

test/runtests.jl

@@ -2408,4 +2408,53 @@ end
     @test_throws MethodError convert(OffsetArray{Float64, 3, Array{Float64,3}}, A)
 end
 
+@testset "center/centered" begin
+    @testset "center" begin
+        A = reshape(collect(1:9), 3, 3)
+        c = OffsetArrays.center(A)
+        @test c == (2, 2)
+        @test A[c...] == 5
+        @test OffsetArrays.center(A, RoundDown) == OffsetArrays.center(A, RoundUp)
+
+        A = reshape(collect(1:6), 2, 3)
+        c = OffsetArrays.center(A)
+        @test OffsetArrays.center(A, RoundDown) == c
+        @test c == (1, 2)
+        @test A[c...] == 3
+        c = OffsetArrays.center(A, RoundUp)
+        @test c == (2, 2)
+        @test A[c...] == 4
+    end
+
+    @testset "centered" begin
+        A = reshape(collect(1:9), 3, 3)
+        Ao = OffsetArrays.centered(A)
+        @test typeof(Ao) <: OffsetArray
+        @test parent(Ao) === A
+        @test Ao.offsets == (-2, -2)
+        @test Ao[0, 0] == 5
+        @test OffsetArrays.centered(A, RoundDown) == OffsetArrays.centered(A, RoundUp)
+
+        A = reshape(collect(1:6), 2, 3)
+        Ao = OffsetArrays.centered(A)
+        @test OffsetArrays.centered(A, RoundDown) == Ao
+        @test typeof(Ao) <: OffsetArray
+        @test parent(Ao) === A
+        @test Ao.offsets == (-1, -2)
+        @test Ao[0, 0] == 3
+        Ao = OffsetArrays.centered(A, RoundUp)
+        @test typeof(Ao) <: OffsetArray
+        @test parent(Ao) === A
+        @test Ao.offsets == (-2, -2)
+        @test Ao[0, 0] == 4
+
+        A = reshape(collect(1:9), 3, 3)
+        Ao = OffsetArray(A, -1, -1)
+        Aoo = OffsetArrays.centered(Ao)
+        @test parent(Aoo) === A # there will be only one OffsetArray wrapper
+        @test Aoo.offsets == (-2, -2)
+        @test Aoo[0, 0] == 5
+    end
+end
+
 include("origin.jl")