make dims (previously sometimes called region) a keyword argument (…

…#25989)

base/array.jl

@@ -2013,7 +2013,9 @@ julia> findmax([1,7,7,NaN])
 (NaN, 4)
 ```
 """
-function findmax(a)
+findmax(a) = _findmax(a, :)
+
+function _findmax(a, ::Colon)
     if isempty(a)
         throw(ArgumentError("collection must be non-empty"))
     end
@@ -2054,7 +2056,9 @@ julia> findmin([7,1,1,NaN])
 (NaN, 4)
 ```
 """
-function findmin(a)
+findmin(a) = _findmin(a, :)
+
+function _findmin(a, ::Colon)
     if isempty(a)
         throw(ArgumentError("collection must be non-empty"))
     end

base/bitarray.jl

@@ -1639,8 +1639,8 @@ findall(::typeof(!iszero), B::BitArray) = findall(B)
 
 ## Reductions ##
 
-sum(A::BitArray, region) = reducedim(+, A, region)
-sum(B::BitArray) = count(B)
+_sum(A::BitArray, dims)    = reduce(+, A, dims=dims)
+_sum(B::BitArray, ::Colon) = count(B)
 
 function all(B::BitArray)
     isempty(B) && return true

base/deprecated.jl

@@ -296,9 +296,9 @@ export conv, conv2, deconv, filt, filt!, xcorr
 
 # PR #21709
 @deprecate cov(x::AbstractVector, corrected::Bool) cov(x, corrected=corrected)
-@deprecate cov(x::AbstractMatrix, vardim::Int, corrected::Bool) cov(x, vardim, corrected=corrected)
+@deprecate cov(x::AbstractMatrix, vardim::Int, corrected::Bool) cov(x, dims=vardim, corrected=corrected)
 @deprecate cov(X::AbstractVector, Y::AbstractVector, corrected::Bool) cov(X, Y, corrected=corrected)
-@deprecate cov(X::AbstractVecOrMat, Y::AbstractVecOrMat, vardim::Int, corrected::Bool) cov(X, Y, vardim, corrected=corrected)
+@deprecate cov(X::AbstractVecOrMat, Y::AbstractVecOrMat, vardim::Int, corrected::Bool) cov(X, Y, dims=vardim, corrected=corrected)
 
 # PR #22325
 # TODO: when this replace is removed from deprecated.jl:
@@ -781,8 +781,8 @@ findprev(pred::Function, A, i::Integer) = invoke(findprev, Tuple{Function, Any,
 # issue #20899
 # TODO: delete JULIA_HOME deprecation in src/init.c
 
-@deprecate cumsum(A::AbstractArray)     cumsum(A, 1)
-@deprecate cumprod(A::AbstractArray)    cumprod(A, 1)
+# cumsum and cumprod have deprecations in multidimensional.jl
+# when the message is removed, the `dims` keyword argument should become required.
 
 # issue #16307
 @deprecate finalizer(o, f::Function) finalizer(f, o)
@@ -1305,6 +1305,47 @@ export readandwrite
 @deprecate datatype_name(t::DataType) nameof(t) false
 @deprecate datatype_name(t::UnionAll) nameof(t) false
 
+# issue #25501
+@deprecate sum(a::AbstractArray, dims)        sum(a, dims=dims)
+@deprecate sum(f, a::AbstractArray, dims)     sum(f, a, dims=dims)
+@deprecate prod(a::AbstractArray, dims)       prod(a, dims=dims)
+@deprecate prod(f, a::AbstractArray, dims)    prod(f, a, dims=dims)
+@deprecate maximum(a::AbstractArray, dims)    maximum(a, dims=dims)
+@deprecate maximum(f, a::AbstractArray, dims) maximum(f, a, dims=dims)
+@deprecate minimum(a::AbstractArray, dims)    minimum(a, dims=dims)
+@deprecate minimum(f, a::AbstractArray, dims) minimum(f, a, dims=dims)
+@deprecate all(a::AbstractArray, dims)        all(a, dims=dims)
+@deprecate all(f, a::AbstractArray, dims)     all(f, a, dims=dims)
+@deprecate any(a::AbstractArray, dims)        any(a, dims=dims)
+@deprecate any(f, a::AbstractArray, dims)     any(f, a, dims=dims)
+@deprecate findmax(A::AbstractArray, dims)    findmax(A, dims=dims)
+@deprecate findmin(A::AbstractArray, dims)    findmin(A, dims=dims)
+
+@deprecate mean(A::AbstractArray, dims)                              mean(A, dims=dims)
+@deprecate varm(A::AbstractArray, m::AbstractArray, dims; kwargs...) varm(A, m; kwargs..., dims=dims)
+@deprecate var(A::AbstractArray, dims; kwargs...)                    var(A; kwargs..., dims=dims)
+@deprecate std(A::AbstractArray, dims; kwargs...)                    std(A; kwargs..., dims=dims)
+@deprecate cov(X::AbstractMatrix, dim::Int; kwargs...)               cov(X; kwargs..., dims=dim)
+@deprecate cov(x::AbstractVecOrMat, y::AbstractVecOrMat, dim::Int; kwargs...) cov(x, y; kwargs..., dims=dim)
+@deprecate cor(X::AbstractMatrix, dim::Int)                          cor(X, dims=dim)
+@deprecate cor(x::AbstractVecOrMat, y::AbstractVecOrMat, dim::Int)   cor(x, y, dims=dim)
+@deprecate median(A::AbstractArray, dims; kwargs...)                 median(A; kwargs..., dims=dims)
+
+@deprecate mapreducedim(f, op, A::AbstractArray, dims)     mapreduce(f, op, A, dims=dims)
+@deprecate mapreducedim(f, op, A::AbstractArray, dims, v0) mapreduce(f, op, v0, A, dims=dims)
+@deprecate reducedim(op, A::AbstractArray, dims)           reduce(op, A, dims=dims)
+@deprecate reducedim(op, A::AbstractArray, dims, v0)       reduce(op, v0, A, dims=dims)
+
+@deprecate sort(A::AbstractArray, dim::Integer; kwargs...) sort(A; kwargs..., dims=dim)
+
+@deprecate accumulate(op, A, dim::Integer)               accumulate(op, A, dims=dim)
+@deprecate accumulate!(op, B, A, dim::Integer)           accumulate!(op, B, A, dims=dim)
+@deprecate cumsum(A::AbstractArray, dim::Integer)        cumsum(A, dims=dim)
+@deprecate cumsum!(B, A, dim::Integer)                   cumsum!(B, A, dims=dim)
+@deprecate cumsum!(out, A::AbstractVector, dim::Integer) cumsum!(out, A, dims=dim)
+@deprecate cumprod(A::AbstractArray, dim::Integer)       cumprod(A, dims=dim)
+@deprecate cumprod!(B, A, dim::Integer)                  cumprod!(B, A, dims=dim)
+
 # PR #25196
 @deprecate_binding ObjectIdDict IdDict{Any,Any}
 

base/exports.jl

@@ -417,7 +417,6 @@ export
     prod,
     promote_shape,
     range,
-    reducedim,
     reshape,
     reverse!,
     reverse,
@@ -526,7 +525,6 @@ export
     mapfoldl,
     mapfoldr,
     mapreduce,
-    mapreducedim,
     merge!,
     merge,
     pairs,

base/multidimensional.jl

@@ -737,9 +737,9 @@ function accumulate_pairwise(op, v::AbstractVector{T}) where T
     return accumulate_pairwise!(op, out, v)
 end
 
-function cumsum!(out, v::AbstractVector, dim::Integer)
+function cumsum!(out, v::AbstractVector; dims::Integer=1)
     # we dispatch on the possibility of numerical stability issues
-    _cumsum!(out, v, dim, ArithmeticStyle(eltype(out)))
+    _cumsum!(out, v, dims, ArithmeticStyle(eltype(out)))
 end
 
 function _cumsum!(out, v, dim, ::ArithmeticRounds)
@@ -753,9 +753,9 @@ function _cumsum!(out, v, dim, ::ArithmeticStyle)
 end
 
 """
-    cumsum(A, dim::Integer)
+    cumsum(A; dims::Integer)
 
-Cumulative sum along the dimension `dim`. See also [`cumsum!`](@ref)
+Cumulative sum along the dimension `dims`. See also [`cumsum!`](@ref)
 to use a preallocated output array, both for performance and to control the precision of the
 output (e.g. to avoid overflow).
 
@@ -766,20 +766,24 @@ julia> a = [1 2 3; 4 5 6]
  1  2  3
  4  5  6
 
-julia> cumsum(a,1)
+julia> cumsum(a, dims=1)
 2×3 Array{Int64,2}:
  1  2  3
  5  7  9
 
-julia> cumsum(a,2)
+julia> cumsum(a, dims=2)
 2×3 Array{Int64,2}:
  1  3   6
  4  9  15
 ```
 """
-function cumsum(A::AbstractArray{T}, dim::Integer) where T
+function cumsum(A::AbstractArray{T}; dims::Union{Nothing,Integer}=nothing) where T
+    if dims === nothing
+        depwarn("`cumsum(A::AbstractArray)` is deprecated, use `cumsum(A, dims=1)` instead.", :cumsum)
+        dims = 1
+    end
     out = similar(A, rcum_promote_type(+, T))
-    cumsum!(out, A, dim)
+    cumsum!(out, A, dims=dims)
 end
 
 """
@@ -804,24 +808,17 @@ julia> cumsum([fill(1, 2) for i in 1:3])
  [3, 3]
 ```
 """
-cumsum(x::AbstractVector) = cumsum(x, 1)
-
-"""
-    cumsum!(B, A, dim::Integer)
+cumsum(x::AbstractVector) = cumsum(x, dims=1)
 
-Cumulative sum of `A` along the dimension `dim`, storing the result in `B`. See also [`cumsum`](@ref).
 """
-cumsum!(B, A, dim::Integer) = accumulate!(+, B, A, dim)
+    cumsum!(B, A; dims::Integer)
 
+Cumulative sum of `A` along the dimension `dims`, storing the result in `B`. See also [`cumsum`](@ref).
 """
-    cumsum!(y::AbstractVector, x::AbstractVector)
+cumsum!(B, A; dims::Integer) = accumulate!(+, B, A, dims=dims)
 
-Cumulative sum of a vector `x`, storing the result in `y`. See also [`cumsum`](@ref).
 """
-cumsum!(y::AbstractVector, x::AbstractVector) = cumsum!(y, x, 1)
-
-"""
-    cumprod(A, dim::Integer)
+    cumprod(A; dims::Integer)
 
 Cumulative product along the dimension `dim`. See also
 [`cumprod!`](@ref) to use a preallocated output array, both for performance and
@@ -834,18 +831,24 @@ julia> a = [1 2 3; 4 5 6]
  1  2  3
  4  5  6
 
-julia> cumprod(a,1)
+julia> cumprod(a, dims=1)
 2×3 Array{Int64,2}:
  1   2   3
  4  10  18
 
-julia> cumprod(a,2)
+julia> cumprod(a, dims=2)
 2×3 Array{Int64,2}:
  1   2    6
  4  20  120
 ```
 """
-cumprod(A::AbstractArray, dim::Integer) = accumulate(*, A, dim)
+function cumprod(A::AbstractArray; dims::Union{Nothing,Integer}=nothing)
+    if dims === nothing
+        depwarn("`cumprod(A::AbstractArray)` is deprecated, use `cumprod(A, dims=1)` instead.", :cumprod)
+        dims = 1
+    end
+    return accumulate(*, A, dims=dims)
+end
 
 """
     cumprod(x::AbstractVector)
@@ -869,51 +872,51 @@ julia> cumprod([fill(1//3, 2, 2) for i in 1:3])
  Rational{Int64}[4//27 4//27; 4//27 4//27]
 ```
 """
-cumprod(x::AbstractVector) = cumprod(x, 1)
+cumprod(x::AbstractVector) = cumprod(x, dims=1)
 
 """
-    cumprod!(B, A, dim::Integer)
+    cumprod!(B, A; dims::Integer)
 
-Cumulative product of `A` along the dimension `dim`, storing the result in `B`.
+Cumulative product of `A` along the dimension `dims`, storing the result in `B`.
 See also [`cumprod`](@ref).
 """
-cumprod!(B, A, dim::Integer) = accumulate!(*, B, A, dim)
+cumprod!(B, A; dims::Integer) = accumulate!(*, B, A, dims=dims)
 
 """
     cumprod!(y::AbstractVector, x::AbstractVector)
 
 Cumulative product of a vector `x`, storing the result in `y`.
 See also [`cumprod`](@ref).
 """
-cumprod!(y::AbstractVector, x::AbstractVector) = cumprod!(y, x, 1)
+cumprod!(y::AbstractVector, x::AbstractVector) = cumprod!(y, x, dims=1)
 
 """
-    accumulate(op, A, dim::Integer)
+    accumulate(op, A; dims::Integer)
 
-Cumulative operation `op` along the dimension `dim`. See also
+Cumulative operation `op` along the dimension `dims`. See also
 [`accumulate!`](@ref) to use a preallocated output array, both for performance and
 to control the precision of the output (e.g. to avoid overflow). For common operations
 there are specialized variants of `accumulate`, see:
 [`cumsum`](@ref), [`cumprod`](@ref)
 
 # Examples
 ```jldoctest
-julia> accumulate(+, fill(1, 3, 3), 1)
+julia> accumulate(+, fill(1, 3, 3), dims=1)
 3×3 Array{Int64,2}:
  1  1  1
  2  2  2
  3  3  3
 
-julia> accumulate(+, fill(1, 3, 3), 2)
+julia> accumulate(+, fill(1, 3, 3), dims=2)
 3×3 Array{Int64,2}:
  1  2  3
  1  2  3
  1  2  3
 ```
 """
-function accumulate(op, A, dim::Integer)
+function accumulate(op, A; dims::Integer)
     out = similar(A, rcum_promote_type(op, eltype(A)))
-    accumulate!(op, out, A, dim)
+    accumulate!(op, out, A, dims=dims)
 end
 
 """
@@ -940,12 +943,12 @@ julia> accumulate(*, [1,2,3])
  6
 ```
 """
-accumulate(op, x::AbstractVector) = accumulate(op, x, 1)
+accumulate(op, x::AbstractVector) = accumulate(op, x, dims=1)
 
 """
-    accumulate!(op, B, A, dim::Integer)
+    accumulate!(op, B, A; dims::Integer)
 
-Cumulative operation `op` on `A` along the dimension `dim`, storing the result in `B`.
+Cumulative operation `op` on `A` along the dimension `dims`, storing the result in `B`.
 See also [`accumulate`](@ref).
 
 # Examples
@@ -954,22 +957,23 @@ julia> A = [1 2; 3 4];
 
 julia> B = [0 0; 0 0];
 
-julia> accumulate!(-, B, A, 1);
+julia> accumulate!(-, B, A, dims=1);
 
 julia> B
 2×2 Array{Int64,2}:
   1   2
  -2  -2
 
-julia> accumulate!(-, B, A, 2);
+julia> accumulate!(-, B, A, dims=2);
 
 julia> B
 2×2 Array{Int64,2}:
  1  -1
  3  -1
 ```
 """
-function accumulate!(op, B, A, dim::Integer)
+function accumulate!(op, B, A; dims::Integer)
+    dim = dims
     dim > 0 || throw(ArgumentError("dim must be a positive integer"))
     inds_t = axes(A)
     axes(B) == inds_t || throw(DimensionMismatch("shape of B must match A"))

base/reduce.jl

@@ -353,11 +353,10 @@ function _mapreduce(f, op, ::IndexLinear, A::AbstractArray{T}) where T
     end
 end
 
-_mapreduce(f, op, ::IndexCartesian, A::AbstractArray) = mapfoldl(f, op, A)
-
-mapreduce(f, op, A::AbstractArray) = _mapreduce(f, op, IndexStyle(A), A)
 mapreduce(f, op, a::Number) = mapreduce_first(f, op, a)
 
+_mapreduce(f, op, ::IndexCartesian, A::AbstractArray) = mapfoldl(f, op, A)
+
 """
     reduce(op, v0, itr)
 
@@ -639,7 +638,9 @@ julia> any(i -> (println(i); i > 3), 1:10)
 true
 ```
 """
-function any(f, itr)
+any(f, itr) = _any(f, itr, :)
+
+function _any(f, itr, ::Colon)
     anymissing = false
     for x in itr
         v = f(x)
@@ -673,7 +674,9 @@ julia> all(i -> (println(i); i < 3), 1:10)
 false
 ```
 """
-function all(f, itr)
+all(f, itr) = _all(f, itr, :)
+
+function _all(f, itr, ::Colon)
     anymissing = false
     for x in itr
         v = f(x)