Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document the kind of indices returned by findmin/findmax/argmin/argmax #46705

Merged
merged 3 commits into from
Oct 31, 2023
Merged

Document the kind of indices returned by findmin/findmax/argmin/argmax #46705

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8158eac
Document the kind of indices returned by `findmin`/`findmax`/`argmin`…
nalimilan Sep 11, 2022
ac78611
Merge branch 'master' into nl/find
vtjnash Oct 30, 2023
ef06442
Apply suggestions from code review
vtjnash Oct 30, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions base/reduce.jl
View file
Open in desktop
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the index vs key difference explained or at least mentioned anywhere in the docs? I've always seen them used interchangeably in julia and package docs.
Is there any difference at all?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indicies are a special case of keys. For Arrays they are the same, but Dicts have keys but not indices. If we just mentioned keys here, that would be correct but obtuse because folks shouldn't need to know that Arrays as have keys to understand findmax(::Function, ::Array).

I'm not sure if the difference is explicitly mentioned or explained elsewhere, but I don't think this PR is the place for it.

Copy link
Contributor

@aplavin aplavin Oct 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Arrays they are the same, but Dicts have keys but not indices.

Interesting, I've always thought they are synonyms! Why getindex and not getkey then?
UPD: getkey exists but does a very different operation.

(of course not for this PR specifically, but in general)

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).
vtjnash marked this conversation as resolved.
Show resolved Hide resolved

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
vtjnash marked this conversation as resolved.
Show resolved Hide resolved
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.
vtjnash marked this conversation as resolved.
Show resolved Hide resolved
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.
vtjnash marked this conversation as resolved.
Show resolved Hide resolved
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