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)