rename findleaf() into Base.findfirst()

It better matches what the method does.
Add basic findfirst() tests.
Fix isequal_rtree() so if key=nothing is supplied for trees with ids,
the key is not checked.

Author: alyst

src/rtree/bulk.jl

@@ -97,7 +97,7 @@ function omt_subtree(elems::AbstractVector, tree::RTree,
             child = omt_subtree(elems, tree, lev - 1, nslices, nsubtrees,
                                 leaf_fill, branch_fill)
             node = _attach!(acquire(tree, Branch, lev), child, tree)
-            tree.nnodes_perlevel[lev-1] += 1
+            tree.nnodes_perlevel[lev - 1] += 1
             return node
         end
     end

src/rtree/delete.jl

@@ -6,7 +6,7 @@ Deletes the value identified by `br` bounding box (or point `pt`) and
 the `id` (if tree elements support `HasID` trait) from the `tree`.
 """
 function Base.delete!(tree::RTree{T,N}, br::Rect{T,N}, id::Any = nothing) where {T,N}
-    leafx = findleaf(tree, br, id)
+    leafx = findfirst(tree, br, id)
     leafx === nothing && __spatial_keyerror(eltype(tree), br, id)
     _detach!(leafx[1], leafx[2], tree)
     tmpdetached = Vector{nodetype(tree)}() # FIXME use pool, Union{Leaf,Branch} ?

src/rtree/node.jl

@@ -40,6 +40,10 @@ isequal_rtree(el::Any, reg::Region, id::Any = nothing) =
 isequal_rtree(::Type{<:HasID}, el::Any, reg::Region, key::Any) =
     isequal(id(el), convert(idtype(idtrait(typeof(el))), key)) && (mbr(el) == reg)
 
+# if the tree has IDs but `nothing` supplied, skip ID check
+isequal_rtree(::Type{<:HasID}, el::Any, reg::Region, ::Nothing = nothing) =
+    (mbr(el) == reg)
+
 isequal_rtree(::Type{HasNoID}, el::Any, reg::Region, ::Nothing = nothing) =
     (mbr(el) == reg)
 

src/rtree/query.jl

@@ -1,9 +1,4 @@
-"""
-Find `Leaf` in the `node` subtree by the `id` and `br` MBR of one of its `Elem`s.
-
-Returns the tuple of `Leaf` and element position or `nothing`.
-"""
-function findleaf(node::Leaf{T,N}, reg::Region{T,N}, id::Any) where {T,N}
+function Base.findfirst(node::Leaf{T,N}, reg::Region{T,N}, id::Any) where {T,N}
     for (i, el) in enumerate(children(node))
         if isequal_rtree(el, reg, id)
             return (node, i)
@@ -12,10 +7,10 @@ function findleaf(node::Leaf{T,N}, reg::Region{T,N}, id::Any) where {T,N}
     return nothing
 end
 
-function findleaf(node::Branch{T,N,V}, reg::Region{T,N}, id::Any) where {T,N,V}
+function Base.findfirst(node::Branch{T,N,V}, reg::Region{T,N}, id::Any) where {T,N,V}
     for child in children(node)
         if contains(mbr(child), reg)
-            res = findleaf(child, reg, id)
+            res = findfirst(child, reg, id)
             if res !== nothing
                 return res::Tuple{Leaf{T,N,V}, Int}
             end
@@ -24,8 +19,16 @@ function findleaf(node::Branch{T,N,V}, reg::Region{T,N}, id::Any) where {T,N,V}
     return nothing
 end
 
-findleaf(rtree::RTree{T,N}, reg::Region{T,N}, id::Any = nothing) where {T,N} =
-    findleaf(rtree.root, reg, id)
+"""
+    findfirst(tree::RTree{T,N}, reg::Region{T,N}, [id]) where {T,N}
+
+Find the element in the `tree` by its region (`reg`) and, optionally, its `id`.
+The region (MBR) of the element and `reg` should match exactly.
+
+Returns the tuple of `Leaf` and position of the element or `nothing`.
+"""
+Base.findfirst(tree::RTree{T,N}, reg::Region{T,N}, id::Any = nothing) where {T,N} =
+    findfirst(tree.root, reg, id)
 
 # FIXME: currently isempty() doesn't allow specifying how
 #        to treat overlapping elements (inside or not), currently treated as outside

test/rtree.jl

@@ -84,6 +84,22 @@ end
         @test length(collect(intersects_with(tree, SI.Rect((0.0, 0.0), (0.6, 0.6))))) == 2
         @test length(collect(contained_in(tree, SI.Rect((0.0, 0.0), (0.55, 0.55))))) == 1 # a only
         @test length(collect(intersects_with(tree, SI.Rect((0.0, 0.0), (0.55, 0.55))))) == 2 # a and c
+
+        @testset "findfirst()" begin
+            @test findfirst(tree, ambr, 2) === nothing
+            @test_throws MethodError findfirst(tree, ambr, "1") # wrong key type
+            @test_throws MethodError findfirst(tree, SI.empty(SI.Rect{Int,2}()))
+            @test findfirst(tree, ambr, 1) == (tree.root, 2)
+            @test findfirst(tree, ambr) == (tree.root, 2) # search without id ignores it
+            @test findfirst(tree, bmbr, 1) === nothing
+            @test findfirst(tree, bmbr, 2) == (tree.root, 1)
+            @test findfirst(tree, bmbr) == (tree.root, 1)
+            @test findfirst(tree, cmbr, 2) === nothing
+            @test findfirst(tree, cmbr, 3) == (tree.root, 3)
+            @test findfirst(tree, cmbr) == (tree.root, 3)
+            @test findfirst(tree, SI.combine(ambr, cmbr)) === nothing
+            @test findfirst(tree, SI.empty(SI.mbrtype(tree))) === nothing
+        end
     end
 
     @testset "RTree{Int,3,String,Nothing}(variant=$tree_var) (no id)" for tree_var in tree_vars
@@ -130,6 +146,20 @@ end
         @test delete!(tree, bmbr) === tree
         @test length(tree) == 1
         @test SI.check(tree)
+        @test insert!(tree, bmbr, "4") === tree
+        @test length(tree) == 2
+        @test SI.check(tree)
+
+        @testset "findfirst()" begin
+            @test_throws MethodError findfirst(tree, ambr, 2) # no key
+            @test_throws MethodError findfirst(tree, ambr, "1")
+            @test_throws MethodError findfirst(tree, SI.empty(SI.Rect{Int,2}()))
+            @test_throws MethodError findfirst(tree, SI.empty(SI.Rect{Float64,3}()))
+            @test findfirst(tree, ambr) == (tree.root, 1)
+            @test findfirst(tree, bmbr) == (tree.root, 2)
+            @test findfirst(tree, SI.combine(ambr, bmbr)) === nothing
+            @test findfirst(tree, SI.empty(SI.mbrtype(tree))) === nothing
+        end
     end
 end
 
@@ -157,10 +187,10 @@ end
         #@show SI.height(tree)
         #@show tree.nnodes_perlevel
 
-        @testset "findleaf" begin
+        @testset "findfirst()" begin
             # check that the elements can be found
             for i in 1:length(tree)
-                node_ix = SI.findleaf(tree.root, mbrs[i], i)
+                node_ix = findfirst(tree.root, mbrs[i], i)
                 @test node_ix !== nothing
                 if node_ix !== nothing
                     node, ix = node_ix
@@ -201,10 +231,10 @@ end
         @test_throws ArgumentError SI.load!(tree, enumerate(mbrs), method=:OMT,
                                             getid = x -> x[1], getmbr = x -> x[2], getval = x -> string(x[1]))
 
-        @testset "findleaf" begin
+        @testset "findfirst()" begin
             # check that the elements can be found
             for i in 1:length(tree)
-                node_ix = SI.findleaf(tree.root, mbrs[i], i)
+                node_ix = findfirst(tree.root, mbrs[i], i)
                 @test node_ix !== nothing
                 if node_ix !== nothing
                     node, ix = node_ix
@@ -235,7 +265,7 @@ end
         @test length(tree) == 3
         @test tree.nelem_deletions == 4
         for i in [3, 4, 7] # check that the correct points stayed in the tree
-            @test SI.findleaf(tree.root, SI.Rect(pts[i], pts[i]), i) !== nothing
+            @test findfirst(tree.root, SI.Rect(pts[i], pts[i]), i) !== nothing
         end
     end