Skip to content

Commit

Permalink
Document the kind of indices returned by findmin/findmax/argmin
Browse files Browse the repository at this point in the history
…/`argmax`

This is the sentence used for `find*` functions, introduced by #25577.

Also change "the domain of `f`" to "`domain`" as the domain of `f`
can be a superset of the passed `domain`.
  • Loading branch information
nalimilan authored Sep 11, 2022
1 parent 5d9807d commit 8158eac
Showing 1 changed file with 22 additions and 4 deletions.
26 changes: 22 additions & 4 deletions base/reduce.jl
Original file line number Diff line number Diff line change
Expand Up @@ -870,12 +870,15 @@ end
"""
findmax(f, domain) -> (f(x), index)
Returns a pair of a value in the codomain (outputs of `f`) and the index of
Returns a pair of a value in the codomain (outputs of `f`) and the index or key of
the corresponding value in the `domain` (inputs to `f`) such that `f(x)` is maximised.
If there are multiple maximal points, then the first one will be returned.
`domain` must be a non-empty iterable.
Indices are of the same type as those returned by [`keys(domain)`](@ref)
and [`pairs(domain)`](@ref).
Values are compared with `isless`.
!!! compat "Julia 1.7"
Expand Down Expand Up @@ -908,6 +911,9 @@ Return the maximal element of the collection `itr` and its index or key.
If there are multiple maximal elements, then the first one will be returned.
Values are compared with `isless`.
Indices are of the same type as those returned by [`keys(itr)`](@ref)
and [`pairs(itr)`](@ref).
See also: [`findmin`](@ref), [`argmax`](@ref), [`maximum`](@ref).
# Examples
Expand All @@ -929,12 +935,15 @@ _findmax(a, ::Colon) = findmax(identity, a)
"""
findmin(f, domain) -> (f(x), index)
Returns a pair of a value in the codomain (outputs of `f`) and the index of
Returns a pair of a value in the codomain (outputs of `f`) and the index or key of
the corresponding value in the `domain` (inputs to `f`) such that `f(x)` is minimised.
If there are multiple minimal points, then the first one will be returned.
`domain` must be a non-empty iterable.
Indices are of the same type as those returned by [`keys(domain)`](@ref)
and [`pairs(domain)`](@ref).
`NaN` is treated as less than all other values except `missing`.
!!! compat "Julia 1.7"
Expand Down Expand Up @@ -968,6 +977,9 @@ Return the minimal element of the collection `itr` and its index or key.
If there are multiple minimal elements, then the first one will be returned.
`NaN` is treated as less than all other values except `missing`.
Indices are of the same type as those returned by [`keys(itr)`](@ref)
and [`pairs(itr)`](@ref).
See also: [`findmax`](@ref), [`argmin`](@ref), [`minimum`](@ref).
# Examples
Expand All @@ -989,7 +1001,7 @@ _findmin(a, ::Colon) = findmin(identity, a)
"""
argmax(f, domain)
Return a value `x` in the domain of `f` for which `f(x)` is maximised.
Return a value `x` in `domain` for which `f(x)` is maximised.
If there are multiple maximal values for `f(x)` then the first one will be found.
`domain` must be a non-empty iterable.
Expand Down Expand Up @@ -1020,6 +1032,9 @@ If there are multiple maximal elements, then the first one will be returned.
The collection must not be empty.
Indices are of the same type as those returned by [`keys(itr)`](@ref)
and [`pairs(itr)`](@ref).
Values are compared with `isless`.
See also: [`argmin`](@ref), [`findmax`](@ref).
Expand All @@ -1041,7 +1056,7 @@ argmax(itr) = findmax(itr)[2]
"""
argmin(f, domain)
Return a value `x` in the domain of `f` for which `f(x)` is minimised.
Return a value `x` in `domain` for which `f(x)` is minimised.
If there are multiple minimal values for `f(x)` then the first one will be found.
`domain` must be a non-empty iterable.
Expand Down Expand Up @@ -1075,6 +1090,9 @@ If there are multiple minimal elements, then the first one will be returned.
The collection must not be empty.
Indices are of the same type as those returned by [`keys(itr)`](@ref)
and [`pairs(itr)`](@ref).
`NaN` is treated as less than all other values except `missing`.
See also: [`argmax`](@ref), [`findmin`](@ref).
Expand Down

0 comments on commit 8158eac

Please sign in to comment.