Rename find() to findall() (#25545)

findall is more explicit and fits well in the series of findfirst/findlast and findnext/findprev.

NEWS.md

@@ -364,14 +364,15 @@ This section lists changes that do not have deprecation warnings.
     trait; see its documentation for details. Types which support subtraction (operator
     `-`) must now implement `widen` for hashing to work inside heterogeneous arrays.
 
-  * `findn(x::AbstractArray)` has been deprecated in favor of `find(!iszero, x)`, which
+  * `findn(x::AbstractArray)` has been deprecated in favor of `findall(!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`,
-    `AbstractDict`, `AbstractString`, `Tuple` and `NamedTuple` objects ([#24774]).
+  * `find` has been renamed to `findall`, and now returns the same type of indices
+    as `keys`/`pairs` for `AbstractArray`, `AbstractDict`, `AbstractString`, `Tuple`
+    and `NamedTuple` objects ([#24774], [#25545]).
     In particular, this means that it returns `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)[findall(f, a)]` 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
@@ -933,7 +934,7 @@ Deprecated or removed
     `similar(::Associative, ::Pair{K, V})` has been deprecated in favour of
     `empty(::Associative, K, V)` ([#24390]).
 
-  * `findin(a, b)` has been deprecated in favor of `find(occursin(b), a)` ([#24673]).
+  * `findin(a, b)` has been deprecated in favor of `findall(occursin(b), a)` ([#24673]).
 
   * The generic implementations of `strides(::AbstractArray)` and `stride(::AbstractArray, ::Int)`
      have been deprecated. Subtypes of `AbstractArray` that implement the newly introduced strided
@@ -1193,3 +1194,4 @@ Command-line option changes
 [#25365]: https://github.com/JuliaLang/julia/issues/25365
 [#25424]: https://github.com/JuliaLang/julia/issues/25424
 [#25532]: https://github.com/JuliaLang/julia/issues/25532
+[#25545]: https://github.com/JuliaLang/julia/issues/25545

base/abstractarray.jl

@@ -1052,7 +1052,7 @@ get(A::AbstractArray, I::Dims, default) = checkbounds(Bool, A, I...) ? A[I...] :
 
 function get!(X::AbstractVector{T}, A::AbstractVector, I::Union{AbstractRange,AbstractVector{Int}}, default::T) where T
     # 1d is not linear indexing
-    ind = find(occursin(indices1(A)), I)
+    ind = findall(occursin(indices1(A)), I)
     X[ind] = A[I[ind]]
     Xind = indices1(X)
     X[first(Xind):first(ind)-1] = default
@@ -1061,7 +1061,7 @@ function get!(X::AbstractVector{T}, A::AbstractVector, I::Union{AbstractRange,Ab
 end
 function get!(X::AbstractArray{T}, A::AbstractArray, I::Union{AbstractRange,AbstractVector{Int}}, default::T) where T
     # Linear indexing
-    ind = find(occursin(1:length(A)), I)
+    ind = findall(occursin(1:length(A)), I)
     X[ind] = A[I[ind]]
     X[1:first(ind)-1] = default
     X[last(ind)+1:length(X)] = default

base/array.jl

@@ -1718,7 +1718,7 @@ true
 findlast(testf::Function, A) = findprev(testf, A, endof(A))
 
 """
-    find(f::Function, A)
+    findall(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.
@@ -1736,7 +1736,7 @@ julia> x = [1, 3, 4]
  3
  4
 
-julia> find(isodd, x)
+julia> findall(isodd, x)
 2-element Array{Int64,1}:
  1
  2
@@ -1745,12 +1745,12 @@ julia> A = [1 2 0; 3 4 0]
 2×3 Array{Int64,2}:
  1  2  0
  3  4  0
-julia> find(isodd, A)
+julia> findall(isodd, A)
 2-element Array{CartesianIndex{2},1}:
  CartesianIndex(1, 1)
  CartesianIndex(2, 1)
 
-julia> find(!iszero, A)
+julia> findall(!iszero, A)
 4-element Array{CartesianIndex{2},1}:
  CartesianIndex(1, 1)
  CartesianIndex(2, 1)
@@ -1763,20 +1763,20 @@ Dict{Symbol,Int64} with 3 entries:
   :B => -1
   :C => 0
 
-julia> find(x -> x >= 0, d)
+julia> findall(x -> x >= 0, d)
 2-element Array{Symbol,1}:
  :A
  :C
 
 ```
 """
-find(testf::Function, A) = collect(first(p) for p in _pairs(A) if testf(last(p)))
+findall(testf::Function, A) = collect(first(p) for p in _pairs(A) if testf(last(p)))
 
 _pairs(A::Union{AbstractArray, AbstractDict, AbstractString, Tuple, NamedTuple}) = pairs(A)
 _pairs(iter) = zip(OneTo(typemax(Int)), iter)  # safe for objects that don't implement length
 
 """
-    find(A)
+    findall(A)
 
 Return a vector `I` of the `true` indices or keys of `A`.
 If there are no such elements of `A`, return an empty array.
@@ -1796,7 +1796,7 @@ julia> A = [true, false, false, true]
  false
   true
 
-julia> find(A)
+julia> findall(A)
 2-element Array{Int64,1}:
  1
  4
@@ -1806,25 +1806,25 @@ julia> A = [true false; false true]
   true  false
  false   true
 
-julia> find(A)
+julia> findall(A)
 2-element Array{Int64,1}:
  1
  4
 
-julia> find(falses(3))
+julia> findall(falses(3))
 0-element Array{Int64,1}
 ```
 """
-function find(A)
+function findall(A)
     if !(eltype(A) === Bool) && !all(x -> x isa Bool, A)
-        depwarn("In the future `find(A)` will only work on boolean collections. Use `find(x->x!=0, A)` instead.", :find)
+        depwarn("In the future `findall(A)` will only work on boolean collections. Use `findall(x->x!=0, A)` instead.", :find)
     end
     collect(first(p) for p in _pairs(A) if last(p) != 0)
 end
 
-find(x::Bool) = x ? [1] : Vector{Int}()
-find(testf::Function, x::Number) = !testf(x) ? Vector{Int}() : [1]
-find(p::OccursIn, x::Number) = x in p.x ? Vector{Int}() : [1]
+findall(x::Bool) = x ? [1] : Vector{Int}()
+findall(testf::Function, x::Number) = !testf(x) ? Vector{Int}() : [1]
+findall(p::OccursIn, x::Number) = x in p.x ? Vector{Int}() : [1]
 
 """
     findnz(A)
@@ -2076,7 +2076,7 @@ function _sortedfindin(v, w)
     return out
 end
 
-function find(pred::OccursIn{<:Union{Array{<:Real},Real}}, x::Array{<:Real})
+function findall(pred::OccursIn{<:Union{Array{<:Real},Real}}, x::Array{<:Real})
     if issorted(x, Sort.Forward) && issorted(pred.x, Sort.Forward)
         return _sortedfindin(x, pred.x)
     else
@@ -2085,7 +2085,7 @@ function find(pred::OccursIn{<:Union{Array{<:Real},Real}}, x::Array{<:Real})
 end
 # issorted fails for some element types so the method above has to be restricted
 # to element with isless/< defined.
-find(pred::OccursIn, x::Union{AbstractArray, Tuple}) = _findin(x, pred.x)
+findall(pred::OccursIn, x::Union{AbstractArray, Tuple}) = _findin(x, pred.x)
 
 # Copying subregions
 function indcopy(sz::Dims, I::Vector)

base/bitarray.jl

@@ -1598,7 +1598,7 @@ function findprev(testf::Function, B::BitArray, start::Integer)
 end
 #findlast(testf::Function, B::BitArray) = findprev(testf, B, 1)  ## defined in array.jl
 
-function find(B::BitArray)
+function findall(B::BitArray)
     l = length(B)
     nnzB = count(B)
     ind = first(keys(B))
@@ -1632,7 +1632,7 @@ function find(B::BitArray)
 end
 
 # For performance
-find(::typeof(!iszero), B::BitArray) = find(B)
+findall(::typeof(!iszero), B::BitArray) = findall(B)
 
 function findnz(B::BitMatrix)
     nnzB = count(B)

base/client.jl

@@ -254,7 +254,7 @@ try_include(mod::Module, path::AbstractString) = isfile(path) && include(mod, pa
 
 function process_options(opts::JLOptions)
     if !isempty(ARGS)
-        idxs = find(x -> x == "--", ARGS)
+        idxs = findall(x -> x == "--", ARGS)
         length(idxs) > 0 && deleteat!(ARGS, idxs[1])
     end
     quiet                 = (opts.quiet != 0)

base/deprecated.jl

@@ -1179,7 +1179,7 @@ end
 # (2) base/linalg/qr.jl
 # (3) base/linalg/lq.jl
 
-@deprecate find(x::Number)            find(!iszero, x)
+@deprecate find(x::Number)            findall(!iszero, x)
 @deprecate findnext(A, v, i::Integer) findnext(equalto(v), A, i)
 @deprecate findfirst(A, v)            findfirst(equalto(v), A)
 @deprecate findprev(A, v, i::Integer) findprev(equalto(v), A, i)
@@ -2783,11 +2783,13 @@ end
 
 @deprecate ismatch(r::Regex, s::AbstractString) contains(s, r)
 
-@deprecate findin(a, b) find(occursin(b), a)
+@deprecate findin(a, b) findall(occursin(b), a)
 
-@deprecate findn(a::AbstractVector) (find(!iszero, a),)
-@deprecate findn(x::AbstractMatrix) (I = find(!iszero, x); (getindex.(I, 1), getindex.(I, 2)))
-@deprecate findn(a::AbstractArray{T, N}) where {T, N} (I = find(!iszero, x); ntuple(i -> getindex.(I, i), N))
+@deprecate find findall
+
+@deprecate findn(x::AbstractVector) (findall(!iszero, x),)
+@deprecate findn(x::AbstractMatrix) (I = findall(!iszero, x); (getindex.(I, 1), getindex.(I, 2)))
+@deprecate findn(x::AbstractArray{T, N}) where {T, N} (I = findall(!iszero, x); ntuple(i -> getindex.(I, i), N))
 
 # issue #9053
 if Sys.iswindows()

base/exports.jl

@@ -482,7 +482,7 @@ export
     eachmatch,
     endswith,
     equalto,
-    find,
+    findall,
     findfirst,
     findlast,
     findmax,

base/libgit2/index.jl

@@ -178,7 +178,7 @@ function Base.getindex(idx::GitIndex, i::Integer)
     return elem
 end
 
-function Base.find(path::String, idx::GitIndex)
+function Base.findall(path::String, idx::GitIndex)
     pos_ref = Ref{Csize_t}(0)
     ret = ccall((:git_index_find, :libgit2), Cint,
                   (Ref{Csize_t}, Ptr{Cvoid}, Cstring), pos_ref, idx.ptr, path)

base/linalg/bidiag.jl

@@ -605,7 +605,7 @@ eigvals(M::Bidiagonal) = M.dv
 function eigvecs(M::Bidiagonal{T}) where T
     n = length(M.dv)
     Q = Matrix{T}(uninitialized, n,n)
-    blks = [0; find(x -> x == 0, M.ev); n]
+    blks = [0; findall(x -> x == 0, M.ev); n]
     v = zeros(T, n)
     if M.uplo == 'U'
         for idx_block = 1:length(blks) - 1, i = blks[idx_block] + 1:blks[idx_block + 1] #index of eigenvector

base/linalg/dense.jl

@@ -1295,7 +1295,7 @@ function pinv(A::StridedMatrix{T}, tol::Real) where T
     Sinv        = zeros(Stype, length(SVD.S))
     index       = SVD.S .> tol*maximum(SVD.S)
     Sinv[index] = one(Stype) ./ SVD.S[index]
-    Sinv[find(.!isfinite.(Sinv))] = zero(Stype)
+    Sinv[findall(.!isfinite.(Sinv))] = zero(Stype)
     return SVD.Vt' * (Diagonal(Sinv) * SVD.U')
 end
 function pinv(A::StridedMatrix{T}) where T

base/linalg/lapack.jl

@@ -3759,7 +3759,7 @@ for (stev, stebz, stegr, stein, elty) in
             chklapackerror(info[])
             if any(ifail .!= 0)
                 # TODO: better error message / type
-                error("failed to converge eigenvectors:\n$(find(!iszero, ifail))")
+                error("failed to converge eigenvectors:\n$(findall(!iszero, ifail))")
             end
             z
         end

base/pkg/read.jl

@@ -64,7 +64,7 @@ function isfixed(pkg::AbstractString, prepo::LibGit2.GitRepo, avail::Dict=availa
     LibGit2.isdirty(prepo) && return true
     LibGit2.isattached(prepo) && return true
     LibGit2.need_update(prepo)
-    if find("REQUIRE", LibGit2.GitIndex(prepo)) === nothing
+    if findall("REQUIRE", LibGit2.GitIndex(prepo)) === nothing
         isfile(pkg,"REQUIRE") && return true
     end
     head = string(LibGit2.head_oid(prepo))
@@ -185,7 +185,7 @@ function requires_path(pkg::AbstractString, avail::Dict=available(pkg))
     head = LibGit2.with(LibGit2.GitRepo, pkg) do repo
         LibGit2.isdirty(repo, "REQUIRE") && return pkgreq
         LibGit2.need_update(repo)
-        if find("REQUIRE", LibGit2.GitIndex(repo)) === nothing
+        if findall("REQUIRE", LibGit2.GitIndex(repo)) === nothing
             isfile(pkgreq) && return pkgreq
         end
         string(LibGit2.head_oid(repo))

base/pkg/resolve/interface.jl

@@ -354,7 +354,7 @@ function enforce_optimality!(sol::Vector{Int}, interface::Interface)
         staged = staged_next
     end
 
-    for p0 in find(uninst)
+    for p0 in findall(uninst)
         sol[p0] = spp[p0]
     end
 

base/pkg/resolve/maxsum.jl

@@ -390,7 +390,7 @@ function decimate1(p0::Int, graph::Graph, msgs::Messages)
     s0 = indmax(fld0)
     # only do the decimation if it is consistent with
     # the previously decimated nodes
-    for p1 in find(decimated)
+    for p1 in findall(decimated)
         haskey(adjdict[p0], p1) || continue
         s1 = indmax(fld[p1])
         j1 = adjdict[p0][p1]

base/tuple.jl

@@ -21,7 +21,7 @@ size(t::Tuple, d) = (d == 1) ? length(t) : throw(ArgumentError("invalid tuple di
 @eval getindex(t::Tuple, i::Int) = getfield(t, i, $(Expr(:boundscheck)))
 @eval getindex(t::Tuple, i::Real) = getfield(t, convert(Int, i), $(Expr(:boundscheck)))
 getindex(t::Tuple, r::AbstractArray{<:Any,1}) = ([t[ri] for ri in r]...,)
-getindex(t::Tuple, b::AbstractArray{Bool,1}) = length(b) == length(t) ? getindex(t, find(b)) : throw(BoundsError(t, b))
+getindex(t::Tuple, b::AbstractArray{Bool,1}) = length(b) == length(t) ? getindex(t, findall(b)) : throw(BoundsError(t, b))
 
 # returns new tuple; N.B.: becomes no-op if i is out-of-bounds
 setindex(x::Tuple, v, i::Integer) = (@_inline_meta; _setindex(v, i, x...))

doc/src/base/arrays.md

@@ -122,8 +122,8 @@ Base.flipdim
 Base.circshift
 Base.circshift!
 Base.circcopy!
-Base.find(::Any)
-Base.find(::Function, ::Any)
+Base.findall(::Any)
+Base.findall(::Function, ::Any)
 Base.findnz
 Base.findfirst(::Any)
 Base.findfirst(::Function, ::Any)

doc/src/manual/arrays.md

@@ -494,13 +494,13 @@ julia> A[CartesianIndex.(axes(A, 1), axes(A, 2)), :]
 Often referred to as logical indexing or indexing with a logical mask, indexing
 by a boolean array selects elements at the indices where its values are `true`.
 Indexing by a boolean vector `B` is effectively the same as indexing by the
-vector of integers that is returned by [`find(B)`](@ref). Similarly, indexing
+vector of integers that is returned by [`findall(B)`](@ref). Similarly, indexing
 by a `N`-dimensional boolean array is effectively the same as indexing by the
 vector of `CartesianIndex{N}`s where its values are `true`. A logical index
 must be a vector of the same length as the dimension it indexes into, or it
 must be the only index provided and match the size and dimensionality of the
 array it indexes into. It is generally more efficient to use boolean arrays as
-indices directly instead of first calling [`find`](@ref).
+indices directly instead of first calling [`findall`](@ref).
 
 ```jldoctest
 julia> x = reshape(1:16, 4, 4)