API clean

and export `extrema!`

fix doc

Update collections.md

drop sparsearray change

Co-Authored-By: Takafumi Arakaki <29282+tkf@users.noreply.github.com>

Author: N5N3

base/compiler/compiler.jl

@@ -55,24 +55,6 @@ include("operators.jl")
 include("pointer.jl")
 include("refvalue.jl")
 
-# required for bootstrap
-extrema(itr) = extrema(identity, itr)
-function extrema(f, itr)
-    y = iterate(itr)
-    y === nothing && throw(ArgumentError("collection must be non-empty"))
-    (v, s) = y
-    vmin = vmax = f(v)
-    while true
-        y = iterate(itr, s)
-        y === nothing && break
-        (x, s) = y
-        fx = f(x)
-        vmax = max(fx, vmax)
-        vmin = min(fx, vmin)
-    end
-    return (vmin, vmax)
-end
-
 # checked arithmetic
 const checked_add = +
 const checked_sub = -
@@ -149,6 +131,19 @@ include("compiler/abstractinterpretation.jl")
 include("compiler/typeinfer.jl")
 include("compiler/optimize.jl") # TODO: break this up further + extract utilities
 
+# required for bootstrap
+# TODO: find why this is needed and remove it.
+function extrema(x::Array)
+    isempty(x) && throw(ArgumentError("collection must be non-empty"))
+    vmin = vmax = x[1]
+    for i in 2:length(x)
+        xi = x[i]
+        vmax = max(vmax, xi)
+        vmin = min(vmin, xi)
+    end
+    return vmin, vmax
+end
+
 include("compiler/bootstrap.jl")
 ccall(:jl_set_typeinf_func, Cvoid, (Any,), typeinf_ext_toplevel)
 

base/exports.jl

@@ -385,6 +385,7 @@ export
     eachindex,
     eachrow,
     eachslice,
+    extrema!,
     extrema,
     fill!,
     fill,

base/mpfr.jl

@@ -706,6 +706,17 @@ function min(x::BigFloat, y::BigFloat)
     return z
 end
 
+# We don't want allocations during `extrema`.
+# TODO: avoid allocations in `min/max`
+function Base._extrema_rf(x::NTuple{2,BigFloat}, y::NTuple{2,BigFloat})
+    (x1, x2), (y1, y2) = x, y
+    isnan(x1) && return x
+    isnan(y1) && return y
+    z1 = x1 < y1 || signbit(x1) > signbit(y1) ? x1 : y1
+    z2 = x2 < y2 || signbit(x2) > signbit(y2) ? y2 : x2
+    z1, z2
+end
+
 function modf(x::BigFloat)
     zint = BigFloat()
     zfloat = BigFloat()

base/multidimensional.jl

@@ -1702,82 +1702,6 @@ _unique_dims(A::AbstractArray, dims::Colon) = invoke(unique, Tuple{Any}, A)
     end
 end
 
-"""
-    extrema([f,] A::AbstractArray; dims, [init]) -> Array{Tuple}
-
-Compute the minimum and maximum elements of `A` over dimensions `dims`.
-If `f` is provided, return the minimum and maximum elements after applying `f` to them.
-
-!!! compat "Julia 1.2"
-    The `extrema(f, A)` method requires Julia 1.2 or later.
-
-# Examples
-```jldoctest
-julia> A = reshape(Vector(1:2:16), (2,2,2))
-2×2×2 Array{Int64, 3}:
-[:, :, 1] =
- 1  5
- 3  7
-
-[:, :, 2] =
-  9  13
- 11  15
-
-julia> extrema(A, dims = (1,2))
-1×1×2 Array{Tuple{Int64, Int64}, 3}:
-[:, :, 1] =
- (1, 7)
-
-[:, :, 2] =
- (9, 15)
-```
-"""
-extrema(f::F, A::AbstractArray; dims=:, init=_InitialValue()) where {F} =
-    _extrema_dims(f, A, dims, init)
-
-_extrema_dims(f::F, A::AbstractArray, ::Colon, init) where {F} =
-    mapreduce(_DupY(f), _extrema_rf, A; init = init)
-_extrema_dims(f::F, A::AbstractArray, ::Colon, ::_InitialValue) where {F} =
-    mapreduce(_DupY(f), _extrema_rf, A)
-# Note: not passing `init = _InitialValue()` since user-defined
-# `reduce`/`foldl` cannot be aware of `Base._InitialValue` that is an
-# internal implementation detail.
-
-_extrema_dims(f::F, A::AbstractArray, dims, init) where {F} =
-    mapreduce(_DupY(f), _extrema_rf, A; dims = dims, init = init)
-function _extrema_dims(f::F, A::AbstractArray, dims, ::_InitialValue) where {F}
-    sz = size(A)
-    for d in dims
-        sz = setindex(sz, 1, d)
-    end
-    T = promote_op(f, eltype(A))
-    B = Array{Tuple{T,T}}(undef, sz...)
-    return extrema!(f, B, A)
-end
-
-@noinline function extrema!(f, B, A)
-    require_one_based_indexing(B, A)
-    sA = size(A)
-    sB = size(B)
-    for I in CartesianIndices(sB)
-        fAI = f(A[I])
-        B[I] = (fAI, fAI)
-    end
-    Bmax = CartesianIndex(sB)
-    @inbounds @simd for I in CartesianIndices(sA)
-        J = min(Bmax,I)
-        BJ = B[J]
-        fAI = f(A[I])
-        if fAI < BJ[1]
-            B[J] = (fAI, BJ[2])
-        elseif fAI > BJ[2]
-            B[J] = (BJ[1], fAI)
-        end
-    end
-    return B
-end
-extrema!(B, A) = extrema!(identity, B, A)
-
 # Show for pairs() with Cartesian indices. Needs to be here rather than show.jl for bootstrap order
 function Base.showarg(io::IO, r::Iterators.Pairs{<:Integer, <:Any, <:Any, T}, toplevel) where T <: Union{AbstractVector, Tuple}
     print(io, "pairs(::$T)")

base/reduce.jl

@@ -842,17 +842,25 @@ julia> extrema(sin, Real[]; init = (1.0, -1.0))  # good, since -1 ≤ sin(::Real
 (1.0, -1.0)
 ```
 """
-extrema(f, itr; kw...) = mapreduce(_DupY(f), _extrema_rf, itr; kw...)
+extrema(f, itr; kw...) = mapreduce(ExtremaMap(f), _extrema_rf, itr; kw...)
 
 # Not using closure since `extrema(type, itr)` is a very likely use-case and it's better
 # to avoid type-instability (#23618).
-struct _DupY{F} <: Function
+struct ExtremaMap{F} <: Function
     f::F
 end
-_DupY(f::Type{T}) where {T} = _DupY{Type{T}}(f)
-@inline (f::_DupY)(x) = (y = f.f(x); (y, y))
+ExtremaMap(::Type{T}) where {T} = ExtremaMap{Type{T}}(T)
+@inline (f::ExtremaMap)(x) = (y = f.f(x); (y, y))
 
 @inline _extrema_rf((min1, max1), (min2, max2)) = (min(min1, min2), max(max1, max2))
+# optimization for AbstractFloat
+function _extrema_rf(x::NTuple{2,T}, y::NTuple{2,T}) where {T<:AbstractFloat}
+    (x1, x2), (y1, y2) = x, y
+    anynan = isnan(x1)|isnan(y1)
+    z1 = ifelse(anynan, x1-y1, ifelse(signbit(x1-y1), x1, y1))
+    z2 = ifelse(anynan, x1-y1, ifelse(signbit(x2-y2), y2, x2))
+    z1, z2
+end
 
 ## findmax, findmin, argmax & argmin
 

base/reducedim.jl

@@ -77,15 +77,15 @@ end
 ## initialization
 # initarray! is only called by sum!, prod!, etc.
 for (Op, initfun) in ((:(typeof(add_sum)), :zero), (:(typeof(mul_prod)), :one))
-    @eval initarray!(a::AbstractArray{T}, ::$(Op), init::Bool, src::AbstractArray) where {T} = (init && fill!(a, $(initfun)(T)); a)
+    @eval initarray!(a::AbstractArray{T}, ::Any, ::$(Op), init::Bool, src::AbstractArray) where {T} = (init && fill!(a, $(initfun)(T)); a)
 end
 
-for Op in (:(typeof(max)), :(typeof(min)))
-    @eval initarray!(a::AbstractArray{T}, ::$(Op), init::Bool, src::AbstractArray) where {T} = (init && copyfirst!(a, src); a)
-end
+# for min/max copyfirst is not correct for initialization, use `mapfirst!` instead
+initarray!(a::AbstractArray{T}, f, ::Union{typeof(min),typeof(max),typeof(_extrema_rf)},
+    init::Bool, src::AbstractArray) where {T} = (init && mapfirst!(f, a, src); a)
 
 for (Op, initval) in ((:(typeof(&)), true), (:(typeof(|)), false))
-    @eval initarray!(a::AbstractArray, ::$(Op), init::Bool, src::AbstractArray) = (init && fill!(a, $initval); a)
+    @eval initarray!(a::AbstractArray, ::Any, ::$(Op), init::Bool, src::AbstractArray) = (init && fill!(a, $initval); a)
 end
 
 # reducedim_initarray is called by
@@ -435,7 +435,7 @@ julia> count!(<=(2), [1; 1], A)
 """
 count!(r::AbstractArray, A::AbstractArrayOrBroadcasted; init::Bool=true) = count!(identity, r, A; init=init)
 count!(f, r::AbstractArray, A::AbstractArrayOrBroadcasted; init::Bool=true) =
-    mapreducedim!(_bool(f), add_sum, initarray!(r, add_sum, init, A), A)
+    mapreducedim!(_bool(f), add_sum, initarray!(r, f, add_sum, init, A), A)
 
 """
     sum(A::AbstractArray; dims)
@@ -737,6 +737,74 @@ julia> minimum!([1 1], A)
 """
 minimum!(r, A)
 
+"""
+    extrema(A::AbstractArray; dims) -> Array{Tuple}
+
+Compute the minimum and maximum elements of an array over the given dimensions.
+
+See also: [`minimum`](@ref), [`maximum`](@ref), [`extrema!`](@ref).
+
+# Examples
+```jldoctest
+julia> A = reshape(Vector(1:2:16), (2,2,2))
+2×2×2 Array{Int64, 3}:
+[:, :, 1] =
+ 1  5
+ 3  7
+
+[:, :, 2] =
+  9  13
+ 11  15
+
+julia> extrema(A, dims = (1,2))
+1×1×2 Array{Tuple{Int64, Int64}, 3}:
+[:, :, 1] =
+ (1, 7)
+
+[:, :, 2] =
+ (9, 15)
+```
+"""
+extrema(A::AbstractArray; dims)
+
+"""
+    extrema(f, A::AbstractArray; dims) -> Array{Tuple}
+
+Compute the minimum and maximum of `f` applied to each element in the given dimensions
+of `A`.
+
+!!! compat "Julia 1.2"
+    This method requires Julia 1.2 or later.
+"""
+extrema(f, A::AbstractArray; dims)
+
+"""
+    extrema!(r, A)
+
+Compute the minimum and maximum value of `A` over the singleton dimensions of `r`, and write results to `r`.
+
+!!! compat "Julia 1.8"
+    This method requires Julia 1.8 or later.
+
+# Examples
+```jldoctest
+julia> A = [1 2; 3 4]
+2×2 Matrix{Int64}:
+ 1  2
+ 3  4
+
+julia> extrema!([(1, 1); (1, 1)], A)
+2-element Vector{Tuple{Int64, Int64}}:
+ (1, 2)
+ (3, 4)
+
+julia> extrema!([(1, 1);; (1, 1)], A)
+1×2 Matrix{Tuple{Int64, Int64}}:
+ (1, 3)  (2, 4)
+```
+"""
+extrema!(r, A)
+
 """
     all(A; dims)
 
@@ -883,15 +951,17 @@ julia> any!([1 1], A)
 any!(r, A)
 
 for (fname, _fname, op) in [(:sum,     :_sum,     :add_sum), (:prod,    :_prod,    :mul_prod),
-                            (:maximum, :_maximum, :max),     (:minimum, :_minimum, :min)]
+                            (:maximum, :_maximum, :max),     (:minimum, :_minimum, :min),
+                            (:extrema, :_extrema, :_extrema_rf)]
+    mapf = fname === :extrema ? :(ExtremaMap(f)) : :f
     @eval begin
         # User-facing methods with keyword arguments
         @inline ($fname)(a::AbstractArray; dims=:, kw...) = ($_fname)(a, dims; kw...)
         @inline ($fname)(f, a::AbstractArray; dims=:, kw...) = ($_fname)(f, a, dims; kw...)
 
         # Underlying implementations using dispatch
         ($_fname)(a, ::Colon; kw...) = ($_fname)(identity, a, :; kw...)
-        ($_fname)(f, a, ::Colon; kw...) = mapreduce(f, $op, a; kw...)
+        ($_fname)(f, a, ::Colon; kw...) = mapreduce($mapf, $op, a; kw...)
     end
 end
 
@@ -904,16 +974,18 @@ _all(a, ::Colon)                           = _all(identity, a, :)
 
 for (fname, op) in [(:sum, :add_sum), (:prod, :mul_prod),
                     (:maximum, :max), (:minimum, :min),
-                    (:all, :&),       (:any, :|)]
+                    (:all, :&),       (:any, :|),
+                    (:extrema, :_extrema_rf)]
     fname! = Symbol(fname, '!')
     _fname = Symbol('_', fname)
+    mapf = fname === :extrema ? :(ExtremaMap(f)) : :f
     @eval begin
         $(fname!)(f::Function, r::AbstractArray, A::AbstractArray; init::Bool=true) =
-            mapreducedim!(f, $(op), initarray!(r, $(op), init, A), A)
+            mapreducedim!($mapf, $(op), initarray!(r, $mapf, $(op), init, A), A)
         $(fname!)(r::AbstractArray, A::AbstractArray; init::Bool=true) = $(fname!)(identity, r, A; init=init)
 
         $(_fname)(A, dims; kw...)    = $(_fname)(identity, A, dims; kw...)
-        $(_fname)(f, A, dims; kw...) = mapreduce(f, $(op), A; dims=dims, kw...)
+        $(_fname)(f, A, dims; kw...) = mapreduce($mapf, $(op), A; dims=dims, kw...)
     end
 end
 

doc/src/base/collections.md

@@ -102,6 +102,7 @@ Base.maximum!
 Base.minimum
 Base.minimum!
 Base.extrema
+Base.extrema!
 Base.argmax
 Base.argmin
 Base.findmax

stdlib/SparseArrays/test/higherorderfns.jl

@@ -709,8 +709,8 @@ end
     @test extrema(f, x) == extrema(f, y)
     @test extrema(spzeros(n, n)) == (0.0, 0.0)
     @test extrema(spzeros(n)) == (0.0, 0.0)
-    @test_throws "reducing over an empty" extrema(spzeros(0, 0))
-    @test_throws "reducing over an empty" extrema(spzeros(0))
+    @test_throws ArgumentError extrema(spzeros(0, 0))
+    @test_throws ArgumentError extrema(spzeros(0))
     @test extrema(sparse(ones(n, n))) == (1.0, 1.0)
     @test extrema(sparse(ones(n))) == (1.0, 1.0)
     @test extrema(A; dims=:) == extrema(B; dims=:)

test/reduce.jl

@@ -258,7 +258,6 @@ prod2(itr) = invoke(prod, Tuple{Any}, itr)
 @test minimum(5) == 5
 @test extrema(5) == (5, 5)
 @test extrema(abs2, 5) == (25, 25)
-@test Core.Compiler.extrema(abs2, 5) == (25, 25)
 
 let x = [4,3,5,2]
     @test maximum(x) == 5
@@ -269,7 +268,6 @@ let x = [4,3,5,2]
     @test maximum(abs2, x) == 25
     @test minimum(abs2, x) == 4
     @test extrema(abs2, x) == (4, 25)
-    @test Core.Compiler.extrema(abs2, x) == (4, 25)
 end
 
 @test maximum([-0.,0.]) === 0.0