exonware-xwnode 0.0.1.21__py3-none-any.whl → 0.0.1.23__py3-none-any.whl

exonware/xwnode/nodes/strategies/{node_avl_tree.py → avl_tree.py}

@@ -40,15 +40,78 @@ class AVLTreeNode:
 
 class AVLTreeStrategy(ANodeTreeStrategy):
     """
-    AVL tree node strategy for strictly balanced binary search trees.
-    
-    Provides guaranteed O(log n) height and operations through height-based
-    balanc
+    AVL Tree strategy for strictly balanced binary search trees.
+    
+    WHY AVL Tree:
+    - Strictest height guarantee: height ≤ 1.44 * log₂(n)
+    - Fastest searches among all balanced trees
+    - Guaranteed O(log n) worst-case for all operations
+    - Height-based balancing (simpler than weight-based)
+    - Maintains sorted order with optimal search performance
+    
+    WHY this implementation:
+    - Height-based balance factor (simpler than red-black color rules)
+    - Balance factor ∈ {-1, 0, 1} maintained after every operation
+    - Four rotation types (LL, LR, RR, RL) handle all imbalances
+    - Height stored in each node for O(1) balance computation
+    - Parent-free implementation (simpler, less memory overhead)
+    
+    Time Complexity:
+    - Insert: O(log n) guaranteed (at most 2 rotations, O(log n) retracing)
+    - Search: O(log n) guaranteed (strictly balanced tree)
+    - Delete: O(log n) guaranteed (at most log n rotations)
+    - Min/Max: O(log n) - leftmost/rightmost traversal
+    - Iteration: O(n) in sorted order
+    
+    Space Complexity: O(n) - one node per key + height field
+    
+    Trade-offs:
+    - Advantage: Fastest searches (stricter height balance than RB-tree)
+    - Advantage: Simpler than Red-Black (only heights, no colors)
+    - Limitation: More rotations on insert/delete than Red-Black Tree
+    - Limitation: Delete can trigger O(log n) rotations (RB-tree has O(1))
+    - Compared to Red-Black: Better searches, slower writes
+    - Compared to Skip List: Deterministic (no randomness), but more complex
+    
+    Best for:
+    - Read-heavy workloads (95%+ reads)
+    - When search performance is critical
+    - Sorted data structures requiring fast lookups
+    - Databases and indices optimized for queries
+    - When strict height guarantees are needed
+    
+    Not recommended for:
+    - Write-heavy workloads (Red-Black Tree is better)
+    - Disk-based storage (B-Tree is better)
+    - Simple, unsorted data (Hash Map is faster)
+    - When insert/delete performance matters more than search
+    - Memory-constrained environments (height overhead)
+    
+    Following eXonware Priorities:
+    1. Usability: Strictest balancing ensures predictable O(log n) performance
+    2. Maintainability: Height-based balancing is easier to understand than colors
+    3. Performance: Optimal search performance among all balanced trees
+    4. Extensibility: Can be enhanced with augmentation (order statistics, intervals)
+    5. Security: Input validation, bounded height prevents worst-case attacks
+    
+    Industry Best Practices:
+    - Follows Adelson-Velsky and Landis original paper (1962)
+    - Maintains balance factor invariant: |bf| ≤ 1
+    - Uses four rotation types: LL (single right), RR (single left), 
+      LR (left-right double), RL (right-left double)
+    - Height updated after every structural change
+    - Tracks performance statistics
+    
+    Performance Note:
+    AVL Trees provide the STRICTEST height guarantee (≤ 1.44 * log₂(n))
+    among all balanced binary search trees. This makes them ideal for
+    read-heavy workloads where search performance is paramount.
+    For write-heavy workloads, Red-Black Trees are preferred due to
+    fewer rotations (at most 2 for insert vs O(log n) for AVL delete).
+    """
     
     # Strategy type classification
     STRATEGY_TYPE = NodeType.TREE
-ing rules and rotations.
-    """
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
         """Initialize the AVL tree strategy."""
@@ -291,6 +354,14 @@ ing rules and rotations.
         """Get number of key-value pairs."""
         return self._size
     
+    def __len__(self) -> int:
+        """Get number of key-value pairs."""
+        return self._size
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert to native Python dict."""
+        return dict(self.items())
+    
     def is_empty(self) -> bool:
         """Check if tree is empty."""
         return self._root is None

exonware/xwnode/nodes/strategies/{node_b_plus_tree.py → b_plus_tree.py}

@@ -42,15 +42,70 @@ class BPlusTreeNode:
 
 class BPlusTreeStrategy(ANodeTreeStrategy):
     """
-    B+ Tree node strategy for database-friendly operations.
-    
-    Provides efficient range queries, sequential access, and balanced
-    tree operations optimized for dis
+    B+ Tree strategy for database-friendly operations and range queries.
+    
+    WHY B+ Tree:
+    - All data stored in leaves (efficient sequential scans)
+    - Leaf nodes linked for O(k) range queries after O(log n) seek
+    - Higher fanout than B-Tree (more keys per internal node)
+    - Optimal for disk-based databases (fewer disk reads)
+    
+    WHY this implementation:
+    - Maintains linked list of leaves for fast range scans
+    - Internal nodes store only keys (no values)
+    - All values at leaf level for consistent access
+    - Standard B+ Tree algorithm used in most databases
+    
+    Time Complexity:
+    - Insert: O(log n) - Tree traversal to leaf
+    - Search: O(log n) - Guaranteed by tree height
+    - Delete: O(log n) - May require merging
+    - Range query: O(log n + k) where k = results (B+ Tree strength)
+    - Sequential scan: O(n) via linked leaves (very fast)
+    
+    Space Complexity: O(n)
+    
+    WHY O(log n) and not O(1):
+    - Sorted order maintenance requires tree traversal
+    - Balanced structure is essential for consistency
+    - Trade-off enables extremely fast range queries
+    
+    Trade-offs:
+    - Advantage: Exceptional range query performance
+    - Advantage: Sequential access via linked leaves
+    - Advantage: Higher fanout = shorter tree
+    - Limitation: O(log n) for single-key operations
+    - Compared to B-Tree: Better for range scans, similar point queries
+    - Compared to Hash Map: Slower lookups, but supports ranges
+    
+    Best for:
+    - Database indexes (PostgreSQL, MySQL use B+ Trees)
+    - File system indexes
+    - Range queries and interval lookups
+    - Sequential scans of large datasets
+    - Disk-based storage systems
+    
+    Not recommended for:
+    - Random single-key lookups only (use HASH_MAP)
+    - Small datasets (< 100 items)
+    - Write-heavy workloads (use LSM_TREE)
+    - In-memory with no range queries (use HASH_MAP)
+    
+    Following eXonware Priorities:
+    1. Security: Predictable O(log n) performance
+    2. Usability: Sorted iteration, range queries
+    3. Maintainability: Well-known database algorithm
+    4. Performance: Optimal for range queries and scans
+    5. Extensibility: Can add bulk loading, concurrent access
+    
+    Performance Note:
+    B+ Tree O(log n) is CORRECT and NECESSARY for sorted order.
+    The algorithm's strength is range queries, not point lookups.
+    For O(1) operations, use HASH_MAP.
+    """
     
     # Strategy type classification
     STRATEGY_TYPE = NodeType.TREE
-k-based storage systems.
-    """
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
         """Initialize the B+ Tree strategy."""
@@ -97,7 +152,17 @@ k-based storage systems.
         
         current = self._root
         while not current.is_leaf:
-            child_index = current.find_child_index(key)
+            child_index = 0
+            # Find correct child to traverse
+            for i, k in enumerate(current.keys):
+                if key < k:
+                    break
+                child_index = i + 1
+            
+            # Bounds check
+            if child_index >= len(current.children):
+                child_index = len(current.children) - 1
+            
             current = current.children[child_index]
         
         return current
@@ -230,50 +295,26 @@ k-based storage systems.
     # CORE OPERATIONS
     # ============================================================================
     
+    def find(self, key: Any) -> Optional[Any]:
+        """Find value by key (implements base class abstract method)."""
+        key_str = str(key)
+        return self._search_key(key_str)
+    
     def put(self, key: Any, value: Any = None) -> None:
         """Add key-value pair to B+ tree."""
         key_str = str(key)
-        normalized_key = self._normalize_key(key_str)
-        self._insert_key(normalized_key, value)
+        # Store original key, not normalized (for case-sensitive mode)
+        self._insert_key(key_str, value)
     
     def get(self, key: Any, default: Any = None) -> Any:
         """Get value by key."""
         key_str = str(key)
-        
-        if key_str == "tree_info":
-            return {
-                'size': self._size,
-                'height': self._height,
-                'total_nodes': self._total_nodes,
-                'order': self.order,
-                'case_sensitive': self.case_sensitive,
-                'total_splits': self._total_splits
-            }
-        elif key_str == "first_key":
-            return self.first_key()
-        elif key_str == "last_key":
-            return self.last_key()
-        elif key_str.isdigit():
-            # Access by index
-            index = int(key_str)
-            return self.get_at_index(index)
-        
-        normalized_key = self._normalize_key(key_str)
-        result = self._search_key(normalized_key)
+        result = self.find(key_str)
         return result if result is not None else default
     
     def has(self, key: Any) -> bool:
         """Check if key exists."""
-        key_str = str(key)
-        
-        if key_str in ["tree_info", "first_key", "last_key"]:
-            return True
-        elif key_str.isdigit():
-            index = int(key_str)
-            return 0 <= index < self._size
-        
-        normalized_key = self._normalize_key(key_str)
-        return self._search_key(normalized_key) is not None
+        return self.find(str(key)) is not None
     
     def remove(self, key: Any) -> bool:
         """Remove key from tree (simplified implementation)."""

exonware/xwnode/nodes/strategies/{node_btree.py → b_tree.py}

@@ -71,10 +71,18 @@ class BTreeNode:
         full_child = self.children[i]
         new_child = BTreeNode(full_child.degree, full_child.is_leaf)
         
-        # Move half of the keys/values to new child
+        # Calculate middle index
         mid = self.degree - 1
+        
+        # Store middle key and value to promote
+        mid_key = full_child.keys[mid]
+        mid_value = full_child.values[mid]
+        
+        # Move right half to new child (excluding middle)
         new_child.keys = full_child.keys[mid + 1:]
         new_child.values = full_child.values[mid + 1:]
+        
+        # Keep left half in full_child (excluding middle)
         full_child.keys = full_child.keys[:mid]
         full_child.values = full_child.values[:mid]
         
@@ -85,21 +93,77 @@ class BTreeNode:
         
         # Insert new child and promote middle key
         self.children.insert(i + 1, new_child)
-        self.keys.insert(i, full_child.keys[mid])
-        self.values.insert(i, full_child.values[mid])
+        self.keys.insert(i, mid_key)
+        self.values.insert(i, mid_value)
 
 
 class BTreeStrategy(ANodeTreeStrategy):
     """
-    B-Tree node strategy for efficient sorted operations and range queries.
-    
-    Provides O(log n) search, insert, and delete operations with excellent
-    cache perfor
+    B-Tree strategy for efficient sorted operations and range queries.
+    
+    WHY B-Tree:
+    - Self-balancing ensures consistent O(log n) performance
+    - High branching factor reduces tree height (better than binary trees)
+    - Minimizes disk I/O by grouping keys in pages/blocks
+    - Excellent for range queries and sequential scans
+    
+    WHY this implementation:
+    - Uses standard B-Tree algorithm (Knuth, TAOCP Vol 3)
+    - Proactive node splitting (split-on-insert strategy)
+    - Maintains 2t-1 max keys per node (t = degree)
+    - Keeps all leaves at same depth (perfect balance)
+    
+    Time Complexity:
+    - Insert: O(log n) - REQUIRED for maintaining sorted order
+    - Search: O(log n) - Tree height determines this
+    - Delete: O(log n) - May require merging/borrowing
+    - Range query: O(k + log n) where k = results
+    - Iteration: O(n) sorted order guaranteed
+    
+    Space Complexity: O(n)
+    
+    WHY O(log n) and not O(1):
+    - Maintaining sorted order requires tree traversal
+    - Balancing operations are essential to B-Tree correctness
+    - This trade-off enables efficient range queries
+    - Self-balancing prevents degradation to O(n)
+    
+    Trade-offs:
+    - Advantage: Excellent for range queries (k + log n)
+    - Advantage: Guaranteed balanced (no worst-case degradation)
+    - Limitation: Higher memory per node vs binary trees
+    - Limitation: More complex insertion/deletion logic
+    - Compared to Hash Map: Slower single lookups, but supports ranges
+    - Compared to Binary Tree: Better cache performance, lower height
+    
+    Best for:
+    - Database indexes (primary use case)
+    - File systems (directory structures)
+    - Range queries and sorted iteration
+    - Disk-based storage (page-oriented)
+    - Large datasets with sorted access
+    
+    Not recommended for:
+    - Random single-key lookups only (use HASH_MAP)
+    - Small datasets (< 100 items, overhead not worth it)
+    - Write-heavy workloads (use LSM_TREE)
+    - In-memory only with no range queries (use HASH_MAP)
+    
+    Following eXonware Priorities:
+    1. Security: Predictable performance (no worst-case degradation)
+    2. Usability: Sorted iteration, range queries, familiar tree semantics
+    3. Maintainability: Well-established algorithm, clear split/merge logic
+    4. Performance: O(log n) guaranteed, optimal for disk I/O
+    5. Extensibility: Can add concurrent access, bulk loading
+    
+    Performance Note:
+    This is the CORRECT complexity for a B-Tree. The O(log n) overhead
+    enables sorted order and range queries. If you need O(1) operations
+    without ordering, use HASH_MAP instead.
+    """
     
     # Strategy type classification
     STRATEGY_TYPE = NodeType.TREE
-mance for range queries.
-    """
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
         """Initialize the B-tree strategy."""
@@ -241,6 +305,11 @@ mance for range queries.
         """Get the number of items."""
         return self._size
     
+    @property
+    def is_empty(self) -> bool:
+        """Check if B-Tree is empty."""
+        return self._size == 0
+    
     def to_native(self) -> Dict[str, Any]:
         """Convert to native Python dict."""
         return dict(self.items())
@@ -360,3 +429,4 @@ mance for range queries.
             'memory_usage': f"{self._size * (24 + 16)} bytes (estimated)",
             'is_sorted': True
         }
+