deprecate flipdim to reverse with a dims keyword argument

Author: JeffBezanson

base/abstractarraymath.jl

@@ -126,9 +126,9 @@ julia> selectdim(A, 2, 3)
 end
 
 """
-    flipdim(A, d::Integer)
+    reverse(A; dims::Integer)
 
-Reverse `A` in dimension `d`.
+Reverse `A` in dimension `dims`.
 
 # Examples
 ```jldoctest
@@ -137,14 +137,14 @@ julia> b = [1 2; 3 4]
  1  2
  3  4
 
-julia> flipdim(b,2)
+julia> reverse(b, dims=2)
 2×2 Array{Int64,2}:
  2  1
  4  3
 ```
 """
-function flipdim(A::AbstractArray, d::Integer)
-    nd = ndims(A)
+function reverse(A::AbstractArray; dims::Integer)
+    nd = ndims(A); d = dims
     1 ≤ d ≤ nd || throw(ArgumentError("dimension $d is not 1 ≤ $d ≤ $nd"))
     if isempty(A)
         return copy(A)
@@ -160,7 +160,7 @@ function flipdim(A::AbstractArray, d::Integer)
     indsd = inds[d]
     sd = first(indsd)+last(indsd)
     if nnd==nd
-        # flip along the only non-singleton dimension
+        # reverse along the only non-singleton dimension
         for i in indsd
             B[i] = A[sd-i]
         end

base/array.jl

@@ -1396,6 +1396,10 @@ function reverse(A::AbstractVector, s=first(linearindices(A)), n=last(linearindi
     end
     return B
 end
+
+# to resolve ambiguity with reverse(A; dims)
+reverse(A::Vector) = invoke(reverse, Tuple{AbstractVector}, A)
+
 function reverseind(a::AbstractVector, i::Integer)
     li = linearindices(a)
     first(li) + last(li) - i

base/arraymath.jl

@@ -58,8 +58,8 @@ end
 
 ## data movement ##
 
-function flipdim(A::Array{T}, d::Integer) where T
-    nd = ndims(A)
+function reverse(A::Array{T}; dims::Integer) where T
+    nd = ndims(A); d = dims
     1 ≤ d ≤ nd || throw(ArgumentError("dimension $d is not 1 ≤ $d ≤ $nd"))
     sd = size(A, d)
     if sd == 1 || isempty(A)
@@ -73,7 +73,7 @@ function flipdim(A::Array{T}, d::Integer) where T
         nnd += Int(size(A,i)==1 || i==d)
     end
     if nnd==nd
-        # flip along the only non-singleton dimension
+        # reverse along the only non-singleton dimension
         for i = 1:sd
             B[i] = A[sd+1-i]
         end

base/bitarray.jl

@@ -1205,8 +1205,8 @@ end
 
 # TODO some of this could be optimized
 
-function flipdim(A::BitArray, d::Integer)
-    nd = ndims(A)
+function reverse(A::BitArray; dims::Integer)
+    nd = ndims(A); d = dims
     1 ≤ d ≤ nd || throw(ArgumentError("dimension $d is not 1 ≤ $d ≤ $nd"))
     sd = size(A, d)
     sd == 1 && return copy(A)
@@ -1218,7 +1218,7 @@ function flipdim(A::BitArray, d::Integer)
         nnd += Int(size(A,i)==1 || i==d)
     end
     if nnd == nd
-        # flip along the only non-singleton dimension
+        # reverse along the only non-singleton dimension
         for i = 1:sd
             B[i] = A[sd+1-i]
         end

base/deprecated.jl

@@ -1338,6 +1338,8 @@ export readandwrite
 @deprecate cumprod(A::AbstractArray, dim::Integer)       cumprod(A, dims=dim)
 @deprecate cumprod!(B, A, dim::Integer)                  cumprod!(B, A, dims=dim)
 
+@deprecate flipdim(A, d) reverse(A, dims=d)
+
 # PR #25196
 @deprecate_binding ObjectIdDict IdDict{Any,Any}
 

base/exports.jl

@@ -382,7 +382,6 @@ export
     fill!,
     fill,
     first,
-    flipdim,
     hcat,
     hvcat,
     indexin,

doc/src/base/arrays.md

@@ -115,7 +115,6 @@ Base.vcat
 Base.hcat
 Base.hvcat
 Base.vect
-Base.flipdim
 Base.circshift
 Base.circshift!
 Base.circcopy!

test/abstractarray.jl

@@ -765,8 +765,8 @@ end
     end
 end
 
-@testset "flipdim on empty" begin
-    @test flipdim(Diagonal([]),1) == Diagonal([])
+@testset "reverse dim on empty" begin
+    @test reverse(Diagonal([]),dims=1) == Diagonal([])
 end
 
 @testset "ndims and friends" begin

test/arrayops.jl

@@ -1337,20 +1337,20 @@ end
     @test reverse!(Any[]) == Any[]
 end
 
-@testset "flipdim" begin
-    @test isequal(flipdim([2,3,1], 1), [1,3,2])
-    @test_throws ArgumentError flipdim([2,3,1], 2)
-    @test isequal(flipdim([2 3 1], 1), [2 3 1])
-    @test isequal(flipdim([2 3 1], 2), [1 3 2])
-    @test_throws ArgumentError flipdim([2,3,1], -1)
-    @test isequal(flipdim(1:10, 1), 10:-1:1)
-    @test_throws ArgumentError flipdim(1:10, 2)
-    @test_throws ArgumentError flipdim(1:10, -1)
-    @test isequal(flipdim(Matrix{Int}(undef, 0,0),1), Matrix{Int}(undef, 0,0))  # issue #5872
+@testset "reverse dim" begin
+    @test isequal(reverse([2,3,1], dims=1), [1,3,2])
+    @test_throws ArgumentError reverse([2,3,1], dims=2)
+    @test isequal(reverse([2 3 1], dims=1), [2 3 1])
+    @test isequal(reverse([2 3 1], dims=2), [1 3 2])
+    @test_throws ArgumentError reverse([2,3,1], dims=-1)
+    @test isequal(reverse(1:10, dims=1), 10:-1:1)
+    @test_throws ArgumentError reverse(1:10, dims=2)
+    @test_throws ArgumentError reverse(1:10, dims=-1)
+    @test isequal(reverse(Matrix{Int}(undef, 0,0),dims=1), Matrix{Int}(undef, 0,0))  # issue #5872
 
     a = rand(5,3)
-    @test flipdim(flipdim(a,2),2) == a
-    @test_throws ArgumentError flipdim(a,3)
+    @test reverse(reverse(a,dims=2),dims=2) == a
+    @test_throws ArgumentError reverse(a,dims=3)
 end
 
 @testset "isdiag, istril, istriu" begin
@@ -1954,8 +1954,8 @@ copyto!(S, A)
 @test mapslices(sort, A, 1) == mapslices(sort, B, 1) == mapslices(sort, S, 1)
 @test mapslices(sort, A, 2) == mapslices(sort, B, 2) == mapslices(sort, S, 2)
 
-@test flipdim(A, 1) == flipdim(B, 1) == flipdim(S, 2)
-@test flipdim(A, 2) == flipdim(B, 2) == flipdim(S, 2)
+@test reverse(A, dims=1) == reverse(B, dims=1) == reverse(S, dims=2)
+@test reverse(A, dims=2) == reverse(B, dims=2) == reverse(S, dims=2)
 
 @test A .+ 1 == B .+ 1 == S .+ 1
 @test 2*A == 2*B == 2*S

test/bitarray.jl

@@ -1036,9 +1036,9 @@ timesofar("binary comparison")
         #for j = 1 : size(b1, d)
             @check_bit_operation selectdim(b1, d, j) SubArray{Bool, 3, BitArray{4}}
         #end
-        @check_bit_operation flipdim(b1, d) BitArray{4}
+        @check_bit_operation reverse(b1, dims=d) BitArray{4}
     end
-    @test_throws ArgumentError flipdim(b1, 5)
+    @test_throws ArgumentError reverse(b1, dims=5)
 
     b1 = bitrand(n1, n2)
     for k = 1:4

test/offsetarray.jl

@@ -420,8 +420,8 @@ v = OffsetArray(rand(8), (-2,))
 
 @test rotl90(A) == OffsetArray(rotl90(parent(A)), A.offsets[[2,1]])
 @test rotr90(A) == OffsetArray(rotr90(parent(A)), A.offsets[[2,1]])
-@test flipdim(A, 1) == OffsetArray(flipdim(parent(A), 1), A.offsets)
-@test flipdim(A, 2) == OffsetArray(flipdim(parent(A), 2), A.offsets)
+@test reverse(A, dims=1) == OffsetArray(reverse(parent(A), dims=1), A.offsets)
+@test reverse(A, dims=2) == OffsetArray(reverse(parent(A), dims=2), A.offsets)
 
 @test A .+ 1 == OffsetArray(parent(A) .+ 1, A.offsets)
 @test 2*A == OffsetArray(2*parent(A), A.offsets)

test/subarray.jl

@@ -577,7 +577,7 @@ let
 end
 
 # ref issue #17351
-@test @inferred(flipdim(view([1 2; 3 4], :, 1), 1)) == [3, 1]
+@test @inferred(reverse(view([1 2; 3 4], :, 1), dims=1)) == [3, 1]
 
 let
     s = view(reshape(1:6, 2, 3), 1:2, 1:2)