Deprecate diff(::AbstractMatrix), require a dim argument (#25457)

* Deprecate diff(::AbstractMatrix), require a dim argument

Akin to `cumsum`, `diff` now requires a `dim` argument in cases where the array has more than one dimension. Final piece of #20041 for the 1.0 milestone.

* Add reference to this PR in NEWS.md

NEWS.md

@@ -856,8 +856,9 @@ Deprecated or removed
   * `workspace` is discontinued, check out [Revise.jl](https://github.com/timholy/Revise.jl)
     for an alternative workflow ([#25046]).
 
-  * `cumsum`, `cumprod`, `accumulate`, and their mutating versions now require a `dim`
-    argument instead of defaulting to using the first dimension ([#24684]).
+  * `cumsum`, `cumprod`, `accumulate`, their mutating versions, and `diff` all now require a `dim`
+    argument instead of defaulting to using the first dimension unless there is only
+    one dimension ([#24684], [#25457]).
 
   * The `sum_kbn` and `cumsum_kbn` functions have been moved to the
     [KahanSummation](https://github.com/JuliaMath/KahanSummation.jl) package ([#24869]).

base/deprecated.jl

@@ -1382,6 +1382,8 @@ end
 
 @deprecate cumsum(A::AbstractArray)     cumsum(A, 1)
 @deprecate cumprod(A::AbstractArray)    cumprod(A, 1)
+import .LinAlg: diff
+@deprecate diff(A::AbstractMatrix) diff(A, 1)
 
 # issue #16307
 @deprecate finalizer(o, f::Function) finalizer(f, o)

base/linalg/generic.jl

@@ -243,10 +243,11 @@ tril!(M::AbstractMatrix) = tril!(M,0)
 diff(a::AbstractVector) = [ a[i+1] - a[i] for i=1:length(a)-1 ]
 
 """
-    diff(A, [dim::Integer=1])
+    diff(A::AbstractVector)
+    diff(A::AbstractMatrix, dim::Integer)
 
 Finite difference operator of matrix or vector `A`. If `A` is a matrix,
-compute the finite difference over a dimension `dim` (default `1`).
+specify the dimension over which to operate with the `dim` argument.
 
 # Examples
 ```jldoctest
@@ -259,9 +260,15 @@ julia> diff(a,2)
 2×1 Array{Int64,2}:
   2
  10
+
+julia> diff(vec(a))
+3-element Array{Int64,1}:
+  4
+ -2
+ 12
 ```
 """
-function diff(A::AbstractMatrix, dim::Integer=1)
+function diff(A::AbstractMatrix, dim::Integer)
     if dim == 1
         [A[i+1,j] - A[i,j] for i=1:size(A,1)-1, j=1:size(A,2)]
     elseif dim == 2

test/bitarray.jl

@@ -1406,7 +1406,8 @@ timesofar("cat")
     @check_bit_operation diff(b1) Vector{Int}
 
     b1 = bitrand(n1, n2)
-    @check_bit_operation diff(b1) Matrix{Int}
+    @check_bit_operation diff(b1, 1) Matrix{Int}
+    @check_bit_operation diff(b1, 2) Matrix{Int}
 
     b1 = bitrand(n1, n1)
     @check_bit_operation svd(b1)

test/linalg/lapack.jl

@@ -203,7 +203,7 @@ end
         Bvs = eigvecs(B)
         Avs = eigvecs(A)
         Bvs = LAPACK.gebak!('S','R',ilo,ihi,scale,Bvs)
-        @test norm(diff(Avs ./ Bvs)) < 100 * eps(abs(float(one(elty))))
+        @test norm(diff(Avs ./ Bvs, 1)) < 100 * eps(abs(float(one(elty))))
     end
 end