Merge pull request #25532 from JuliaLang/nl/findn

Deprecate findn(x) in favor of find(!iszero, x), which now returns cartesian indices

Author: JeffBezanson

NEWS.md

@@ -364,8 +364,8 @@ 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::AbstractVector)` now returns a 1-tuple with the vector of indices, to be
-    consistent with higher order arrays ([#25365]).
+  * `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`,
     `AbstractDict`, `AbstractString`, `Tuple` and `NamedTuple` objects ([#24774]).
@@ -1191,3 +1191,4 @@ Command-line option changes
 [#25231]: https://github.com/JuliaLang/julia/issues/25231
 [#25365]: https://github.com/JuliaLang/julia/issues/25365
 [#25424]: https://github.com/JuliaLang/julia/issues/25424
+[#25532]: https://github.com/JuliaLang/julia/issues/25532

base/array.jl

@@ -1778,11 +1778,29 @@ _pairs(iter) = zip(OneTo(typemax(Int)), iter)  # safe for objects that don't imp
 """
     find(A)
 
-Return a vector of the linear indices of the `true` values in `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.
 To search for other kinds of values, pass a predicate as the first argument.
 
+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.
+
 # Examples
 ```jldoctest
+julia> A = [true, false, false, true]
+4-element Array{Bool,1}:
+  true
+ false
+ false
+  true
+
+julia> find(A)
+2-element Array{Int64,1}:
+ 1
+ 4
+
 julia> A = [true false; false true]
 2×2 Array{Bool,2}:
   true  false

base/bitarray.jl

@@ -1601,39 +1601,40 @@ end
 function find(B::BitArray)
     l = length(B)
     nnzB = count(B)
-    I = Vector{Int}(uninitialized, nnzB)
+    ind = first(keys(B))
+    I = Vector{typeof(ind)}(uninitialized, nnzB)
     nnzB == 0 && return I
     Bc = B.chunks
-    Bcount = 1
     Icount = 1
     for i = 1:length(Bc)-1
         u = UInt64(1)
         c = Bc[i]
         for j = 1:64
             if c & u != 0
-                I[Icount] = Bcount
+                I[Icount] = ind
                 Icount += 1
             end
-            Bcount += 1
+            ind = nextind(B, ind)
             u <<= 1
         end
     end
     u = UInt64(1)
     c = Bc[end]
     for j = 0:_mod64(l-1)
         if c & u != 0
-            I[Icount] = Bcount
+            I[Icount] = ind
             Icount += 1
         end
-        Bcount += 1
+        ind = nextind(B, ind)
         u <<= 1
     end
     return I
 end
 
-findn(B::BitVector) = find(B)
+# For performance
+find(::typeof(!iszero), B::BitArray) = find(B)
 
-function findn(B::BitMatrix)
+function findnz(B::BitMatrix)
     nnzB = count(B)
     I = Vector{Int}(uninitialized, nnzB)
     J = Vector{Int}(uninitialized, nnzB)
@@ -1645,11 +1646,6 @@ function findn(B::BitMatrix)
             cnt += 1
         end
     end
-    return I, J
-end
-
-function findnz(B::BitMatrix)
-    I, J = findn(B)
     return I, J, trues(length(I))
 end
 

base/deprecated.jl

@@ -2778,6 +2778,9 @@ end
 
 @deprecate findin(a, b) find(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))
 
 # END 0.7 deprecations
 

base/exports.jl

@@ -489,7 +489,6 @@ export
     findmin,
     findmin!,
     findmax!,
-    findn,
     findnext,
     findprev,
     findnz,

base/multidimensional.jl

@@ -687,51 +687,6 @@ end
 
 ##
 
-# small helper function since we cannot use a closure in a generated function
-_countnz(x) = x != 0
-
-"""
-    findn(A)
-
-Return one vector for each dimension containing indices giving the
-locations of the non-zeros in `A` (determined by `A[i] != 0`).
-
-# Examples
-```jldoctest
-julia> A = [1 2 0; 0 0 3; 0 4 0]
-3×3 Array{Int64,2}:
- 1  2  0
- 0  0  3
- 0  4  0
-
-julia> findn(A)
-([1, 1, 3, 2], [1, 2, 2, 3])
-
-julia> A = [0 0; 0 0]
-2×2 Array{Int64,2}:
- 0  0
- 0  0
-
-julia> findn(A)
-(Int64[], Int64[])
-```
-"""
-@generated function findn(A::AbstractArray{T,N}) where {T,N}
-    quote
-        nnzA = count(_countnz, A)
-        @nexprs $N d->(I_d = Vector{Int}(uninitialized, nnzA))
-        k = 1
-        @nloops $N i A begin
-            @inbounds if (@nref $N A i) != 0
-                @nexprs $N d->(I_d[k] = i_d)
-                k += 1
-            end
-        end
-        @ntuple $N I
-    end
-end
-
-
 # see discussion in #18364 ... we try not to widen type of the resulting array
 # from cumsum or cumprod, but in some cases (+, Bool) we may not have a choice.
 rcum_promote_type(op, ::Type{T}, ::Type{S}) where {T,S<:Number} = promote_op(op, T, S)
@@ -1597,25 +1552,6 @@ end
     end
 end
 
-## findn
-
-@generated function findn(B::BitArray{N}) where N
-    quote
-        nnzB = count(B)
-        I = ntuple(x->Vector{Int}(uninitialized, nnzB), Val($N))
-        if nnzB > 0
-            count = 1
-            @nloops $N i B begin
-                if (@nref $N B i) # TODO: should avoid bounds checking
-                    @nexprs $N d->(I[d][count] = i_d)
-                    count += 1
-                end
-            end
-        end
-        return I
-    end
-end
-
 ## isassigned
 
 @generated function isassigned(B::BitArray, I_0::Int, I::Int...)

doc/src/base/arrays.md

@@ -124,7 +124,6 @@ Base.circshift!
 Base.circcopy!
 Base.find(::Any)
 Base.find(::Function, ::Any)
-Base.findn
 Base.findnz
 Base.findfirst(::Any)
 Base.findfirst(::Function, ::Any)

stdlib/SparseArrays/docs/src/index.md

@@ -115,14 +115,19 @@ julia> R = sparsevec(I,V)
 
 The inverse of the [`sparse`](@ref) and [`sparsevec`](@ref) functions is
 [`findnz`](@ref), which retrieves the inputs used to create the sparse array.
-There is also a [`findn`](@ref) function which only returns the index vectors.
+[`find(!iszero, x)`](@ref) returns the cartesian indices of non-zero entries in `x`
+(including stored entries equal to zero).
 
 ```jldoctest sparse_function
 julia> findnz(S)
 ([1, 4, 5, 3], [4, 7, 9, 18], [1, 2, 3, -5])
 
-julia> findn(S)
-([1, 4, 5, 3], [4, 7, 9, 18])
+julia> find(!iszero, S)
+4-element Array{CartesianIndex{2},1}:
+ CartesianIndex(1, 4)
+ CartesianIndex(4, 7)
+ CartesianIndex(5, 9)
+ CartesianIndex(3, 18)
 
 julia> findnz(R)
 ([1, 3, 4, 5], [1, -5, 2, 3])

stdlib/SparseArrays/src/SparseArrays.jl

@@ -17,7 +17,7 @@ import Base.LinAlg: mul!, ldiv!, rdiv!
 import Base: @get!, acos, acosd, acot, acotd, acsch, asech, asin, asind, asinh,
     atan, atand, atanh, broadcast!, chol, conj!, cos, cosc, cosd, cosh, cospi, cot,
     cotd, coth, count, csc, cscd, csch, adjoint!, diag, diff, done, dot, eig,
-    exp10, exp2, findn, findprev, findnext, floor, hash, indmin, inv,
+    exp10, exp2, findprev, findnext, floor, hash, indmin, inv,
     issymmetric, istril, istriu, log10, log2, lu, next, sec, secd, sech, show,
     sin, sinc, sind, sinh, sinpi, squeeze, start, sum, summary, tan,
     tand, tanh, trace, transpose!, tril!, triu!, trunc, vecnorm, abs, abs2,

stdlib/SparseArrays/src/sparsematrix.jl

@@ -1274,31 +1274,22 @@ function find(p::Function, S::SparseMatrixCSC)
     if p(zero(eltype(S)))
         return invoke(find, Tuple{Function, Any}, p, S)
     end
-    sz = size(S)
-    I, J = _findn(p, S)
-    return CartesianIndex.(I, J)
-end
-find(p::Base.OccursIn, x::SparseMatrixCSC) =
-    invoke(find, Tuple{Base.OccursIn, AbstractArray}, p, x)
-
-findn(S::SparseMatrixCSC{Tv,Ti}) where {Tv,Ti} = _findn(x->true, S)
 
-function _findn(p::Function, S::SparseMatrixCSC{Tv,Ti}) where {Tv,Ti}
     numnz = nnz(S)
-    I = Vector{Ti}(uninitialized, numnz)
-    J = Vector{Ti}(uninitialized, numnz)
+    inds = Vector{CartesianIndex{2}}(uninitialized, numnz)
 
     count = 1
     @inbounds for col = 1 : S.n, k = S.colptr[col] : (S.colptr[col+1]-1)
         if p(S.nzval[k])
-            I[count] = S.rowval[k]
-            J[count] = col
+            inds[count] = CartesianIndex(S.rowval[k], col)
             count += 1
         end
     end
 
-    return (I, J)
+    return inds
 end
+find(p::Base.OccursIn, x::SparseMatrixCSC) =
+    invoke(find, Tuple{Base.OccursIn, AbstractArray}, p, x)
 
 function findnz(S::SparseMatrixCSC{Tv,Ti}) where {Tv,Ti}
     numnz = nnz(S)