Change findfirst/findlast/findnext/findprev to return the same index type as keys()

This is consistent with find(). We need to check whether the iterator is
empty first, since calling first(keys(A)) may throw an error. Also
add needed last(::EachStringIndex) and prevind(::AbstractArray, ::CartesianIndex) methods.

Author: nalimilan

NEWS.md

@@ -367,11 +367,12 @@ This section lists changes that do not have deprecation warnings.
   * `findn(x::AbstractArray)` has been deprecated in favor of `find(!iszero, x)`, which
     now returns cartesian indices for multidimensional arrays (see below, [#25532]).
 
-  * `find` now returns the same type of indices as `keys`/`pairs` for `AbstractArray`,
+  * `find`, `findfirst`, `findlast`, `findnext` and `findprev` now take and/or return
+    the same type of indices as `keys`/`pairs` for `AbstractArray`,
     `AbstractDict`, `AbstractString`, `Tuple` and `NamedTuple` objects ([#24774]).
-    In particular, this means that it returns `CartesianIndex` objects for matrices
+    In particular, this means that they return `CartesianIndex` objects for matrices
     and higher-dimensional arrays instead of linear indices as was previously the case.
-    Use `LinearIndices(a)[find(f, a)]` to compute linear indices.
+    Use `LinearIndices(a)[find(f, a)]` and similar constructs to compute linear indices.
 
  * `AbstractSet` objects are now considered equal by `==` and `isequal` if all of their
     elements are equal ([#25368]). This has required changing the hashing algorithm

base/array.jl

@@ -1497,21 +1497,35 @@ cat(n::Integer, x::Integer...) = reshape([x...], (ntuple(x->1, n-1)..., length(x
 
 Find the next linear index >= `i` of a `true` element of `A`, or `nothing` if not found.
 
+Indices are of the same type as those returned by [`keys(A)`](@ref)
+and [`pairs(A)`](@ref).
+
 # Examples
 ```jldoctest
+julia> A = [false, false, true, false]
+4-element Array{Bool,1}:
+ false
+ false
+  true
+ false
+
+julia> findnext(A, 1)
+3
+
+julia> findnext(A, 4) == nothing
+true
+
 julia> A = [false false; true false]
 2×2 Array{Bool,2}:
  false  false
   true  false
 
-julia> findnext(A, 1)
-2
-
-julia> findnext(A, 3)
+julia> findnext(A, CartesianIndex(1, 1))
+CartesianIndex(2, 1)
 ```
 """
-function findnext(A, start::Integer)
-    l = endof(A)
+function findnext(A, start)
+    l = last(keys(A))
     i = start
     warned = false
     while i <= l
@@ -1531,48 +1545,74 @@ end
 """
     findfirst(A)
 
-Return the linear index of the first `true` value in `A`.
+Return the index of the first `true` value in `A`.
 Return `nothing` if no such value is found.
 To search for other kinds of values, pass a predicate as the first argument.
 
+Indices are of the same type as those returned by [`keys(A)`](@ref)
+and [`pairs(A)`](@ref).
+
 # Examples
 ```jldoctest
+julia> A = [false, false, true, false]
+4-element Array{Bool,1}:
+ false
+ false
+  true
+ false
+
+julia> findfirst(A)
+3
+
+julia> findfirst(falses(3)) == nothing
+true
+
 julia> A = [false false; true false]
 2×2 Array{Bool,2}:
  false  false
   true  false
 
 julia> findfirst(A)
-2
-
-julia> findfirst(falses(3)) == nothing
-true
+CartesianIndex(2, 1)
 ```
 """
-findfirst(A) = findnext(A, 1)
+findfirst(A) = isempty(A) ? nothing : findnext(A, first(keys(A)))
 
 """
-    findnext(predicate::Function, A, i::Integer)
+    findnext(predicate::Function, A, i)
 
-Find the next linear index >= `i` of an element of `A` for which `predicate` returns `true`,
+Find the next index >= `i` of an element of `A` for which `predicate` returns `true`,
 or `nothing` if not found.
 
+Indices are of the same type as those returned by [`keys(A)`](@ref)
+and [`pairs(A)`](@ref).
+
 # Examples
 ```jldoctest
-julia> A = [1 4; 2 2]
-2×2 Array{Int64,2}:
- 1  4
- 2  2
+A = [1, 4, 2, 2]
+4-element Array{Int64,1}:
+ 1
+ 4
+ 2
+ 2
 
 julia> findnext(isodd, A, 1)
 1
 
 julia> findnext(isodd, A, 2) == nothing
 true
+
+julia> A = [1 4; 2 2]
+2×2 Array{Int64,2}:
+ 1  4
+ 2  2
+
+julia> findnext(isodd, A, CartesianIndex(1, 1))
+CartesianIndex(1, 1)
 ```
 """
-function findnext(testf::Function, A, start::Integer)
-    l = endof(A)
+function findnext(testf::Function, A, start)
+    l = last(keys(A))
     i = start
     while i <= l
         if testf(A[i])
@@ -1586,15 +1626,20 @@ end
 """
     findfirst(predicate::Function, A)
 
-Return the linear index of the first element of `A` for which `predicate` returns `true`.
+Return the index of the first element of `A` for which `predicate` returns `true`.
 Return `nothing` if there is no such element.
 
+Indices are of the same type as those returned by [`keys(A)`](@ref)
+and [`pairs(A)`](@ref).
+
 # Examples
 ```jldoctest
-julia> A = [1 4; 2 2]
-2×2 Array{Int64,2}:
- 1  4
- 2  2
+julia> A = [1, 4, 2, 2]
+4-element Array{Int64,1}:
+ 1
+ 4
+ 2
+ 2
 
 julia> findfirst(iseven, A)
 2
@@ -1603,34 +1648,55 @@ julia> findfirst(x -> x>10, A) == nothing
 true
 
 julia> findfirst(equalto(4), A)
-3
+2
+
+julia> A = [1 4; 2 2]
+2×2 Array{Int64,2}:
+ 1  4
+ 2  2
+
+julia> findfirst(iseven, A)
+CartesianIndex(2, 1)
 ```
 """
-findfirst(testf::Function, A) = findnext(testf, A, 1)
+findfirst(testf::Function, A) = isempty(A) ? nothing : findnext(testf, A, first(keys(A)))
 
 """
-    findprev(A, i::Integer)
+    findprev(A, i)
+
+Find the previous index <= `i` of a `true` element of `A`, or `nothing` if not found.
 
-Find the previous linear index <= `i` of a `true` element of `A`, or `nothing` if not found.
+Indices are of the same type as those returned by [`keys(A)`](@ref)
+and [`pairs(A)`](@ref).
 
 # Examples
 ```jldoctest
+julia> A = [false, false, true, true]
+4-element Array{Bool,1}:
+ false
+ false
+  true
+  true
+
+julia> findprev(A, 3)
+3
+
+julia> findprev(A, 1) == nothing
+true
+
 julia> A = [false false; true true]
 2×2 Array{Bool,2}:
  false  false
   true   true
 
-julia> findprev(A,2)
-2
-
-julia> findprev(A,1) == nothing
-true
+julia> findprev(A, CartesianIndex(2, 1))
+CartesianIndex(2, 1)
 ```
 """
-function findprev(A, start::Integer)
+function findprev(A, start)
     i = start
     warned = false
-    while i >= 1
+    while i >= first(keys(A))
         a = A[i]
         if !warned && !(a isa Bool)
             depwarn("In the future `findprev` will only work on boolean collections. Use `findprev(x->x!=0, A, start)` instead.", :findprev)
@@ -1645,50 +1711,76 @@ end
 """
     findlast(A)
 
-Return the linear index of the last `true` value in `A`.
+Return the index of the last `true` value in `A`.
 Return `nothing` if there is no `true` value in `A`.
 
+Indices are of the same type as those returned by [`keys(A)`](@ref)
+and [`pairs(A)`](@ref).
+
 # Examples
 ```jldoctest
-julia> A = [true false; true false]
-2×2 Array{Bool,2}:
- true  false
- true  false
+julia> A = [true, false, true, false]
+4-element Array{Bool,1}:
+  true
+ false
+  true
+ false
 
 julia> findlast(A)
-2
+3
 
 julia> A = falses(2,2);
 
 julia> findlast(A) == nothing
 true
+
+julia> A = [true false; true false]
+2×2 Array{Bool,2}:
+ true  false
+ true  false
+
+julia> findlast(A)
+CartesianIndex(2, 1)
 ```
 """
-findlast(A) = findprev(A, endof(A))
+findlast(A) = isempty(A) ? nothing : findprev(A, last(keys(A)))
 
 """
-    findprev(predicate::Function, A, i::Integer)
+    findprev(predicate::Function, A, i)
 
-Find the previous linear index <= `i` of an element of `A` for which `predicate` returns `true`, or
+Find the previous index <= `i` of an element of `A` for which `predicate` returns `true`, or
 `nothing` if not found.
 
+Indices are of the same type as those returned by [`keys(A)`](@ref)
+and [`pairs(A)`](@ref).
+
 # Examples
 ```jldoctest
-julia> A = [4 6; 1 2]
-2×2 Array{Int64,2}:
- 4  6
- 1  2
+julia> A = [4, 6, 1, 2]
+4-element Array{Int64,1}:
+ 4
+ 6
+ 1
+ 2
 
 julia> findprev(isodd, A, 1) == nothing
 true
 
 julia> findprev(isodd, A, 3)
-2
+3
+
+julia> A = [4 6; 1 2]
+2×2 Array{Int64,2}:
+ 4  6
+ 1  2
+
+julia> findprev(isodd, A, CartesianIndex(1, 2))
+CartesianIndex(2, 1)
 ```
 """
-function findprev(testf::Function, A, start::Integer)
+function findprev(testf::Function, A, start)
     i = start
-    while i >= 1
+    while i >= first(keys(A))
         testf(A[i]) && return i
         i = prevind(A, i)
     end
@@ -1698,35 +1790,46 @@ end
 """
     findlast(predicate::Function, A)
 
-Return the linear index of the last element of `A` for which `predicate` returns `true`.
+Return the index of the last element of `A` for which `predicate` returns `true`.
 Return `nothing` if there is no such element.
 
+Indices are of the same type as those returned by [`keys(A)`](@ref)
+and [`pairs(A)`](@ref).
+
 # Examples
 ```jldoctest
+julia> A = [1, 2, 3, 4]
+4-element Array{Int64,1}:
+ 1
+ 2
+ 3
+ 4
+
+julia> findlast(isodd, A)
+3
+
+julia> findlast(x -> x > 5, A) == nothing
+true
+
 julia> A = [1 2; 3 4]
 2×2 Array{Int64,2}:
  1  2
  3  4
 
 julia> findlast(isodd, A)
-2
-
-julia> findlast(x -> x > 5, A) == nothing
-true
+CartesianIndex(2, 1)
 ```
 """
-findlast(testf::Function, A) = findprev(testf, A, endof(A))
+findlast(testf::Function, A) = isempty(A) ? nothing : findprev(testf, A, last(keys(A)))
 
 """
     find(f::Function, A)
 
 Return a vector `I` of the indices or keys of `A` where `f(A[I])` returns `true`.
 If there are no such elements of `A`, return an empty array.
 
-Indices or keys are of the same type as those returned by [`keys(A)`](@ref)
-and [`pairs(A)`](@ref) for `AbstractArray`, `AbstractDict`, `AbstractString`
-`Tuple` and `NamedTuple` objects, and are linear indices starting at `1`
-for other iterables.
+Indices are of the same type as those returned by [`keys(A)`](@ref)
+and [`pairs(A)`](@ref).
 
 # Examples
 ```jldoctest

base/deprecated.jl

@@ -1184,6 +1184,9 @@ end
 @deprecate findfirst(A, v)            findfirst(equalto(v), A)
 @deprecate findprev(A, v, i::Integer) findprev(equalto(v), A, i)
 @deprecate findlast(A, v)             findlast(equalto(v), A)
+# to fix ambiguities introduced by deprecations
+findnext(pred::Function, A, i::Integer) = invoke(findnext, Tuple{Function, Any, Any}, pred, A, i)
+findprev(pred::Function, A, i::Integer) = invoke(findprev, Tuple{Function, Any, Any}, pred, A, i)
 # also remove deprecation warnings in find* functions in array.jl, sparse/sparsematrix.jl,
 # and sparse/sparsevector.jl.