feat(datastructures, trees): threaded bst

Author: BrianLusina

datastructures/trees/__init__.py

@@ -1,4 +1,5 @@
-from datastructures.trees.tree import Tree, TreeNode, T
+from datastructures.trees.tree import Tree, TreeNode
 from datastructures.trees.binary import BinaryTree, BinaryTreeNode
+from datastructures.trees.types import T
 
-__all__ = ["Tree", "TreeNode", "BinaryTree", "BinaryTreeNode"]
+__all__ = ["Tree", "TreeNode", "BinaryTree", "BinaryTreeNode", "T"]

datastructures/trees/binary/__init__.py

@@ -5,6 +5,8 @@
     longest_uni_value_path,
 )
 from datastructures.trees.binary.node import BinaryTreeNode
+from datastructures.trees.binary.threaded import ThreadedBinarySearchTree
+from datastructures.trees.binary.search_tree import BinarySearchTree
 from datastructures.trees.binary.utils import (
     lowest_common_ancestor,
     lowest_common_ancestor_ptr,
@@ -24,4 +26,6 @@
     "connect_all_siblings",
     "connect_all_siblings_ptr",
     "mirror_binary_tree",
+    "ThreadedBinarySearchTree",
+    "BinarySearchTree",
 ]

datastructures/trees/binary/node.py

@@ -1,6 +1,7 @@
 from typing import Optional, List, Any
 
-from datastructures.trees.node import TreeNode, T
+from datastructures.trees.node import TreeNode
+from datastructures.trees.types import T
 
 
 class BinaryTreeNode(TreeNode):
@@ -21,6 +22,8 @@ def __init__(
         depth: Optional[int] = None,
         height: Optional[int] = None,
         degree: Optional[int] = None,
+        left_thread: Optional[bool] = False,
+        right_thread: Optional[bool] = False,
     ) -> None:
         """
         Constructor for BinaryTreeNode class. This will create a new node with the provided data and optional
@@ -38,7 +41,16 @@ def __init__(
             of the tree, then this is the next node on the next level starting from the left. If this is the last node
             in the tree, then this is None.
         """
-        super().__init__(data, key, parent, depth, height, degree)
+        super().__init__(
+            data,
+            key,
+            parent,
+            depth,
+            height,
+            degree,
+            left_thread=left_thread,
+            right_thread=right_thread,
+        )
         self.left: Optional[BinaryTreeNode] = left
         self.right: Optional[BinaryTreeNode] = right
         # Next is a pointer that connects this node to it's right sibling in the tree. If this node is the right most
@@ -188,11 +200,6 @@ def children(self) -> List["BinaryTreeNode"] | None:
         if not self.left and not self.right:
             return []
 
-    @property
-    def height(self) -> int:
-        """Height of a node is the number of edges from this node to the deepest node"""
-        pass
-
     def __repr__(self):
         parent_data = self.parent.data if self.parent else None
         next_data = self.next.data if self.next else None

datastructures/trees/binary/search_tree/binary_search_tree.py

@@ -3,8 +3,8 @@
 
 from datastructures.queues.fifo import FifoQueue
 from datastructures.stacks.dynamic import DynamicSizeStack
-from datastructures.trees import T
 from datastructures.trees.binary.tree import BinaryTree
+from datastructures.trees.types import T
 
 
 class BinarySearchTree(BinaryTree):

datastructures/trees/binary/threaded/README.md

@@ -0,0 +1,3 @@
+# Threaded Binary Tree
+
+This contains code that represents a threaded binary tree

datastructures/trees/binary/threaded/__init__.py

@@ -0,0 +1,6 @@
+from datastructures.trees.binary.threaded.threaded_binary_search_tree import (
+    ThreadedBinarySearchTree,
+)
+
+
+__all__ = ["ThreadedBinarySearchTree"]

datastructures/trees/binary/threaded/test_threaded_bst_inorder.py

@@ -0,0 +1,41 @@
+import unittest
+from typing import List
+from parameterized import parameterized
+from utils.test_utils import custom_test_name_func
+from datastructures.trees.binary.threaded.threaded_binary_search_tree import (
+    ThreadedBinarySearchTree,
+)
+
+THREADED_BST_INORDER_TESTCASES = [([4, 2, 6, 1, 3, 5, 7], [1, 2, 3, 4, 5, 6, 7])]
+
+THREADED_BST_REVERSE_INORDER_TESTCASES = [
+    ([4, 2, 6, 1, 3, 5, 7], [7, 6, 5, 4, 3, 2, 1])
+]
+
+
+class ThreadedBinarySearchTreeInorderTraversalTestCase(unittest.TestCase):
+    @parameterized.expand(
+        THREADED_BST_INORDER_TESTCASES, name_func=custom_test_name_func
+    )
+    def test_inorder_traversal(self, values: List[int], expected: List[int]):
+        tree = ThreadedBinarySearchTree()
+        for value in values:
+            tree.insert_node(value)
+
+        actual = tree.inorder_traversal()
+        self.assertEqual(expected, actual)
+
+    @parameterized.expand(
+        THREADED_BST_REVERSE_INORDER_TESTCASES, name_func=custom_test_name_func
+    )
+    def test_reverse_inorder_traversal(self, values: List[int], expected: List[int]):
+        tree = ThreadedBinarySearchTree()
+        for value in values:
+            tree.insert_node(value)
+
+        actual = tree.reverse_inorder_traversal()
+        self.assertEqual(expected, actual)
+
+
+if __name__ == "__main__":
+    unittest.main()

datastructures/trees/binary/threaded/threaded_binary_search_tree.py

@@ -0,0 +1,96 @@
+from typing import Optional, List
+from datastructures.trees.binary.search_tree import BinarySearchTree
+from datastructures.trees.binary.node import BinaryTreeNode
+from datastructures.trees.types import T
+
+
+class ThreadedBinarySearchTree(BinarySearchTree):
+    """
+    A fully (double-)threaded binary search tree.
+
+    Every node's left/right pointer is EITHER a real child link OR a "thread" -
+    a shortcut straight to that node's inorder predecessor / successor. Which
+    one it is gets tracked with a boolean flag per side. This lets us traverse
+    the whole tree in sorted order with O(1) extra space: no recursion, no
+    explicit stack.
+    """
+
+    def insert_node(self, value: Optional[T]) -> None:
+        if self.root is None:
+            self.root = BinaryTreeNode(value)
+            return None
+        current = self.root
+
+        while True:
+            # No duplicates
+            if value == current.data:
+                return None
+            if value < current.data:
+                if not current.left_thread and current.left is not None:
+                    current = current.left
+                    continue
+
+                new_node = BinaryTreeNode(value)
+                new_node.left = current.left  # inherit current's predecessor
+                new_node.left_thread = True
+                new_node.right = current  # current is the new successor
+                new_node.right_thread = True
+                current.left = new_node
+                current.left_thread = False
+                return None
+            else:
+                if not current.right_thread and current.right is not None:
+                    current = current.right
+                    continue
+                new_node = BinaryTreeNode(value)
+                new_node.right = current.right  # inherit current's successor
+                new_node.right_thread = True
+                new_node.left = current  # current is the new predecessor
+                new_node.left_thread = True
+                current.right = new_node
+                current.right_thread = False
+                return None
+
+    @staticmethod
+    def _leftmost(node: Optional[BinaryTreeNode]) -> Optional[BinaryTreeNode]:
+        if node is None:
+            return None
+        while not node.left_thread and node.left is not None:
+            node = node.left
+        return node
+
+    @staticmethod
+    def _rightmost(node: Optional[BinaryTreeNode]) -> Optional[BinaryTreeNode]:
+        if node is None:
+            return None
+        while not node.right_thread and node.right is not None:
+            node = node.right
+        return node
+
+    def successor(self, node: BinaryTreeNode) -> Optional[BinaryTreeNode]:
+        if node.right_thread:
+            return node.right
+        return self._leftmost(node.right)
+
+    def predecessor(self, node: BinaryTreeNode) -> Optional[BinaryTreeNode]:
+        if node.left_thread:
+            return node.left
+        return self._rightmost(node.left)
+
+    def inorder_traversal(self) -> List[T]:
+        """Iterative inorder traversal using threads only - no stack needed."""
+        result = []
+        cur = self._leftmost(self.root)
+        while cur is not None:
+            result.append(cur.data)
+            cur = self.successor(cur)
+        return result
+
+    def reverse_inorder_traversal(self) -> List[T]:
+        """Same idea, walking predecessor threads right-to-left."""
+        result = []
+        cur = self._rightmost(self.root)
+        while cur is not None:
+            result.append(cur.data)
+            cur = self.predecessor(cur)
+        return result

datastructures/trees/binary/tree/binary_tree.py

@@ -4,7 +4,8 @@
 from itertools import chain
 
 from datastructures.stacks.dynamic import DynamicSizeStack
-from datastructures.trees.tree import Tree, T
+from datastructures.trees.tree import Tree
+from datastructures.trees.types import T
 from datastructures.trees.node import TreeNode
 from datastructures.trees.binary.node import BinaryTreeNode
 from datastructures.trees.binary.tree.binary_tree_utils import longest_uni_value_path
@@ -66,7 +67,7 @@ def height_helper(current_node: BinaryTreeNode) -> int:
     def has_next(self) -> bool:
         pass
 
-    def increasing_order_traversal(self) -> TreeNode:
+    def increasing_order_traversal(self) -> BinaryTreeNode:
         pass
 
     def get_depth(self) -> int:

datastructures/trees/node.py

@@ -1,6 +1,5 @@
-from typing import Generic, TypeVar, Any, Optional
-
-T = TypeVar("T", bound=Any)
+from typing import Generic, Any, Optional
+from datastructures.trees.types import T
 
 
 class TreeNode(Generic[T]):
@@ -20,6 +19,8 @@ def __init__(
         depth: Optional[int] = None,
         height: Optional[int] = None,
         degree: Optional[int] = None,
+        left_thread: Optional[bool] = False,
+        right_thread: Optional[bool] = False,
     ):
         """
         Initialises a tree node with a value, key and a parent node.
@@ -32,6 +33,10 @@ def __init__(
             depth (int): The depth of the current node.
             height (int): The height of the current node.
             degree (int): The degree of the current node.
+            left_thread (bool): Whether this node has a thread pointer to its inorder predecessor. Defaults to False. If
+                True, the pointer is a thread (predecessor). False indicates the pointer is a real child link or None
+            right_thread (bool): Whether this node has a thread pointer to its successor. Defaulted to False. If True, the
+                pointer is a thread to the inorder successor.
 
         Notes:
             The key is used to identify the node in the tree. If not key is provided, a hash of the data is used.
@@ -42,9 +47,14 @@ def __init__(
         self.depth = depth
         self.height = height
         self.degree = degree
+        self.left_thread = left_thread
+        self.right_thread = right_thread
 
     def __repr__(self):
-        return f"TreeNode(data={self.data}, key={self.key}, depth={self.depth}, height={self.height}, degree={self.degree})"
+        return (
+            f"TreeNode(data={self.data}, key={self.key}, depth={self.depth}, height={self.height}, degree={self.degree}, "
+            f"left_thread={self.left_thread}, right_thread={self.right_thread})"
+        )
 
     def __eq__(self, other: "TreeNode[T]") -> bool:
         """Checks if this node is equal to another node based on the data they contain