Add indmin/indmax

NEWS.md

@@ -31,6 +31,7 @@ Build system changes
 New library functions
 ---------------------
 
+ * `indmax(f, col)` and `indmin(f, col)` have been added, returning the index maximizing/minimizing a given function (or `identity`, if none is given) over an indexable collection.
 
 New library features
 --------------------

base/exports.jl

@@ -469,6 +469,8 @@ export
     searchsortedlast,
     insorted,
     startswith,
+    indmax,
+    indmin,
 
 # linear algebra
     var"'", # to enable syntax a' for adjoint

base/reduce.jl

@@ -768,7 +768,7 @@ Inf
 """
 minimum(a; kw...) = mapreduce(identity, min, a; kw...)
 
-## findmax, findmin, argmax & argmin
+## findmax, findmin, argmax, argmin, indmax & indmin
 
 """
     findmax(f, domain) -> (f(x), index)
@@ -990,6 +990,118 @@ julia> argmin([7, 1, 1, NaN])
 """
 argmin(itr) = findmin(itr)[2]
 
+"""
+    indmin(itr) -> idx
+
+Return the index of the minimal element of the collection `itr`.
+If there are multiple minimal elements, then the first index will be returned.
+`NaN` is treated as less than all other values except `missing`.
+
+!!! compat "Julia 1.8"
+    This method requires Julia 1.8 or later.
+
+See also: [`indmax`](@ref), [`findmin`](@ref).
+
+# Examples
+```jldoctest
+julia> indmin([8, 0.1, -9, pi])
+3
+
+julia> indmin([1, 7, 7, 6])
+1
+
+julia> indmin([1, 7, 7, NaN])
+4
+```
+"""
+indmin(itr) = findmin(itr)[2]
+
+"""
+    indmin(f, itr) -> idx
+
+Return the index of an `x` of the collection `itr` such that `f(x)` is minimised.
+If there are multiple minimal elements, then the first index will be returned.
+`NaN` is treated as less than all other values except `missing`.
+
+!!! compat "Julia 1.8"
+    This method requires Julia 1.8 or later.
+
+See also: [`indmax`](@ref), [`findmin`](@ref).
+
+# Examples
+```jldoctest
+julia> indmin(identity, 5:9)
+1
+
+julia> indmin(-, 1:10)
+10
+
+julia> indmin(first, [(2, :a), (2, :b), (3, :c)])
+1
+
+julia> indmin(cos, 0:π/2:2π)
+3
+```
+"""
+indmin(f, itr) = findmin(f, itr)[2]
+
+"""
+    indmax(itr) -> idx
+
+Return the index of the maximal element of the collection `itr`.
+If there are multiple maximal elements, then the first index will be returned.
+
+Values are compared using `isless`.
+
+!!! compat "Julia 1.8"
+    This method requires Julia 1.8 or later.
+
+See also: [`indmin`](@ref), [`findmax`](@ref).
+
+# Examples
+```jldoctest
+julia> indmax([8, 0.1, -9, pi])
+1
+
+julia> indmax([1, 7, 7, 6])
+2
+
+julia> indmax([1, 7, 7, NaN])
+4
+```
+"""
+indmax(itr) = findmax(itr)[2]
+
+"""
+    indmax(f, itr) -> idx
+
+Return the index of an `x` of the collection `itr` such that `f(x)` is maximised.
+If there are multiple maximal elements, then the first index will be returned.
+
+Values are compared using `isless`.
+
+!!! compat "Julia 1.8"
+    This method requires Julia 1.8 or later.
+
+See also: [`indmin`](@ref), [`findmax`](@ref).
+
+# Examples
+```jldoctest
+julia> indmax(identity, 5:9)
+5
+
+julia> indmax(-, 1:10)
+1
+
+julia> indmax(first, [(1, :a), (3, :b), (3, :c)])
+2
+
+julia> indmax(cos, 0:π/2:2π)
+1
+```
+"""
+indmax(f, itr) = findmax(f, itr)[2]
+
 ## all & any
 
 """

test/reduce.jl

@@ -387,7 +387,7 @@ A = circshift(reshape(1:24,2,3,4), (0,1,1))
     end
 end
 
-# findmin, findmax, argmin, argmax
+# findmin, findmax, argmin, argmax, indmin, indmax
 
 @testset "findmin(f, domain)" begin
     @test findmin(-, 1:10) == (-10, 10)
@@ -397,6 +397,7 @@ end
     @test findmin(identity, [1, NaN, 3]) === (NaN, 2)
     @test findmin(identity, [1, 3, NaN]) === (NaN, 3)
     @test findmin(cos, 0:π/2:2π) == (-1.0, 3)
+    @test findmin(sum, Iterators.product(1:5, 1:5) |> collect) == (2, CartesianIndex(1, 1))
 end
 
 @testset "findmax(f, domain)" begin
@@ -407,6 +408,7 @@ end
     @test findmax(identity, [1, NaN, 3]) === (NaN, 2)
     @test findmax(identity, [1, 3, NaN]) === (NaN, 3)
     @test findmax(cos, 0:π/2:2π) == (1.0, 1)
+    @test findmax(sum, Iterators.product(1:5, 1:5) |> collect) == (10, CartesianIndex(5, 5))
 end
 
 @testset "argmin(f, domain)" begin
@@ -419,6 +421,28 @@ end
     @test argmax(sum, Iterators.product(1:5, 1:5)) == (5, 5)
 end
 
+@testset "indmin(f, itr)" begin
+    @test indmin(-, 1:10) == 10
+    @test indmin(cos, 0:π/2:2π) == 3
+    @test indmin(identity, [1, 2, 3, missing]) === 4
+
+    prodtest = collect(Iterators.product(1:5, 1:5))
+    @test indmin(sum, prodtest) == CartesianIndex(1, 1)
+    @test indmin(identity, prodtest) == indmin(prodtest)
+    @test indmin(identity, prodtest) == CartesianIndex(1, 1)
+end
+
+@testset "indmax(f, itr)" begin
+    @test indmax(-, 1:10) == 1
+    @test indmax(cos, 0:π/2:2π) == 1
+    @test indmax(identity, [1, 2, 3, missing]) == 4
+
+    prodtest = collect(Iterators.product(1:5, 1:5))
+    @test indmax(sum, prodtest) == CartesianIndex(5, 5)
+    @test indmax(identity, prodtest) == indmax(prodtest)
+    @test indmax(identity, prodtest) == CartesianIndex(5, 5)
+end
+
 # any & all
 
 @test @inferred any([]) == false