Handle nil child slots consistently

Treat nil child slots as empty in children? and siblings to avoid
phantom entries in binary trees. Add regression coverage and
note the behavior change in API-CHANGES.

Author: evolve75

API-CHANGES.md

@@ -7,6 +7,14 @@ _Note_: API changes are expected to reduce significantly after the `1.x`
 release. In most cases, an alternative will be provided to ensure relatively
 smooth transition to the new APIs.
 
+## Release 3.0.0 Changes
+
+* Minimum Ruby version is now 3.1 (support for 2.7 and 3.0 has been dropped).
+
+* [Tree::TreeNode#children?][children] and [Tree::TreeNode#siblings][siblings]
+  now treat `nil` child slots as empty, preventing binary trees with missing
+  children from reporting or yielding phantom siblings.
+
 ## Release 2.2.0 Changes
 
 * [Tree::TreeNode#add][add] now raises `ArgumentError` when attempting to add
@@ -29,10 +37,6 @@ smooth transition to the new APIs.
 * [Tree::TreeNode#each_level][each_level] now returns a level-wise enumerator
   when called without a block.
 
-## Release 3.0.0 Changes
-
-* Minimum Ruby version is now 3.1 (support for 2.7 and 3.0 has been dropped).
-
 ## Release 2.1.0 Changes
 
 * Minimum Ruby version has been bumped to 2.7 and above
@@ -165,6 +169,7 @@ smooth transition to the new APIs.
 [append]: rdoc-ref:Tree::TreeNode#<<
 [breadth_each]: rdoc-ref:Tree::TreeNode#breadth_each
 [btree_add]: rdoc-ref:Tree::BinaryTreeNode#add
+[children]: rdoc-ref:Tree::TreeNode#children?
 [depth]: rdoc-ref:Tree::Utils::TreeMetricsHandler#depth
 [detached_subtree_copy]: rdoc-ref:Tree::TreeNode#detached_subtree_copy
 [dup]: rdoc-ref:Tree::TreeNode#dup

lib/tree.rb

@@ -127,6 +127,9 @@ class TreeNode
     # Root node for the (sub)tree to which this node belongs.
     # A root node's root is itself.
     #
+    # @note This walks the parent chain each call; if this is on a hot path,
+    #       consider caching the result at the caller.
+    #
     # @return [Tree::TreeNode] Root of the (sub)tree.
     def root
       root = self
@@ -191,11 +194,13 @@ def parentage
     # @!attribute [r] children?
     # +true+ if the this node has any child node.
     #
+    # @note Nil child slots (e.g., in binary trees) do not count as children.
+    #
     # @return [Boolean] +true+ if child nodes exist.
     #
     # @see #leaf?
     def children?
-      !@children.empty?
+      @children.any?
     end
 
     alias has_children? children? # @todo: Aliased for eventual replacement
@@ -879,6 +884,8 @@ def last_sibling?
     # If a block is provided, yields each of the sibling nodes to the block.
     # The root always has +nil+ siblings.
     #
+    # @note Nil child slots (e.g., in binary trees) are skipped.
+    #
     # @yieldparam sibling [Tree::TreeNode] Each sibling node.
     #
     # @return [Array<Tree::TreeNode>] Array of siblings of this node. Will
@@ -890,13 +897,19 @@ def last_sibling?
     # @see #last_sibling
     def siblings
       if block_given?
-        parent.children.each { |sibling| yield sibling if sibling != self }
+        parent.children.each do |sibling|
+          next unless sibling
+          next if sibling == self
+
+          yield sibling
+        end
         self
       else
         return [] if root?
 
         siblings = []
         parent.children do |my_sibling|
+          next unless my_sibling
           siblings << my_sibling if my_sibling != self
         end
         siblings

test/test_binarytree.rb

@@ -236,6 +236,21 @@ def test_left_child_equals
       assert_nil(@root['A Child at Left'], 'Lookup by old left name should be nil')
     end
 
+    def test_nil_children_slots
+      @root << @left_child1
+      @root << @right_child1
+
+      @root.left_child = nil
+      assert(@root.children?, 'Root should still have a right child')
+
+      collected = []
+      @root.right_child.siblings { |sibling| collected << sibling }
+      assert_equal([], collected, 'Nil sibling slots should not be yielded')
+
+      @root.right_child = nil
+      assert(!@root.children?, 'Root should report no children once all slots are nil')
+    end
+
     # Test right_child= method.
     def test_right_child_equals
       @root << @left_child1