Merge pull request #5 from gjbex/copilot/fix-de6b1cb0-cb4f-493a-81b2-b53907cdfd71

Fix critical bugs in intersection_tree.py: class variables, search algorithm, and validation

Author: gjbex

source_code/intersection_trees/intersection_tree.py

@@ -1,6 +1,20 @@
 '''
 Implementation of an intersection tree approach for efficiently finding
 intersections among a set of query intervals and a database intervals.
+
+This module provides:
+- Node: A tree node representing an interval with efficient intersection search
+- Utility functions for generating intervals, creating databases, and executing queries
+
+Note: The tree structure is a binary search tree ordered by interval start points.
+In worst case scenarios (e.g., with sorted input), the tree may become unbalanced
+and degrade to O(n) performance instead of the optimal O(log n).
+
+Example usage:
+    >>> from intersection_tree import create_db, create_queries, execute_queries
+    >>> db = create_db(size=100)
+    >>> queries = create_queries(size=10)
+    >>> results = execute_queries(queries, db)
 '''
 
 import random
@@ -12,19 +26,13 @@
 QueryResult: typing.TypeAlias = list[tuple[Interval, Interval]]
 
 class Node:
-    '''Class representting a node in an intersection tree.
+    '''Class representing a node in an intersection tree.
     
     Each node represents an interval in the dataset, so it has the start and the
     end of that interval.  It also contains a reference to its left and right child.
     For indexing purposes, it also contains the maximum end value over all its children.
     '''
 
-    _start: int
-    _end: int
-    _max_end: int
-    _left: 'Node' = None
-    _right: 'Node' = None
-
     def __init__(self, interval: Interval) -> None:
         '''Initialize node representing the interval [start, end).
 
@@ -33,9 +41,14 @@ def __init__(self, interval: Interval) -> None:
         interval: Interval
             the interval represented by this node
         '''
-        self._start = interval[0]
-        self._end = interval[1]
-        self._max_end = interval[1]
+        if interval[0] >= interval[1]:
+            raise ValueError(f"Invalid interval: start ({interval[0]}) must be less than end ({interval[1]})")
+        
+        self._start: int = interval[0]
+        self._end: int = interval[1]
+        self._max_end: int = interval[1]
+        self._left: 'Node | None' = None
+        self._right: 'Node | None' = None
 
     def insert(self, interval: Interval) -> None:
         '''Insert a new interval [start, end) in the tree.
@@ -44,7 +57,15 @@ def insert(self, interval: Interval) -> None:
         ----------
         interval: Interval
             the interval to insert
+            
+        Raises
+        ------
+        ValueError
+            if interval start is not less than end
         '''
+        if interval[0] >= interval[1]:
+            raise ValueError(f"Invalid interval: start ({interval[0]}) must be less than end ({interval[1]})")
+            
         if interval[0] < self._start:
             if self._left is None:
                 self._left = Node(interval)
@@ -72,7 +93,7 @@ def search(self, interval: Interval, results: list[Interval]) -> None:
             results.append((self._start, self._end))
         if self._left is not None and self._left._max_end >= interval[0]:
             self._left.search(interval, results)
-        if self._right is not None and self._start <= interval[1]:
+        if self._right is not None and self._right._max_end >= interval[0]:
             self._right.search(interval, results)
 
     def to_str(self, prefix: str = '') -> str:
@@ -127,10 +148,18 @@ def generate_interval(max_end: int = 1_000_000_000) -> Interval:
     Returns
     -------
     Interval
-        Tuple (start, end) such that end - start > 1
+        Tuple (start, end) such that end - start >= 1
+        
+    Raises
+    ------
+    ValueError
+        if max_end is less than 2
     '''
+    if max_end < 2:
+        raise ValueError(f"max_end must be at least 2, got {max_end}")
+    
     start = random.randint(0, max_end - 2)
-    end = random.randint(start + 2, max_end)
+    end = random.randint(start + 1, max_end)
     return start, end
 
 
@@ -142,7 +171,7 @@ def create_db(size: int, max_end: int = 1_000_000) -> Node:
     size: int
         number of intervals in the database
     max_end: int
-        largest end value of the interval, default value 1_000_000_000
+        largest end value of the interval, default value 1_000_000
 
     Returns
     -------
@@ -162,7 +191,7 @@ def execute_queries(queries: Queries, db: Node) -> QueryResult:
     ----------
     queries: Queries
         queries to be executed
-    db: Db
+    db: Node
         database to query
 
     Returns
@@ -186,7 +215,7 @@ def create_queries(size: int = 1_000, max_end: int = 1_000_000) -> Queries:
     size: int
         number of intervals in the query, default value 1_000
     max_end: int
-        largest end value of the interval, default value 1_000_000_000
+        largest end value of the interval, default value 1_000_000
 
     Returns
     -------