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

exonware/xwnode/nodes/strategies/{node_red_black_tree.py → red_black_tree.py}

@@ -57,15 +57,80 @@ class RedBlackTreeNode:
 
 class RedBlackTreeStrategy(ANodeTreeStrategy):
     """
-    Red-black tree node strategy for self-balancing binary search trees.
-    
-    Provides guaranteed O(log n) height and operations through color-based
-    balanc
+    Red-Black Tree strategy for self-balancing binary search trees.
+    
+    WHY Red-Black Tree:
+    - Guaranteed O(log n) worst-case for insert, search, delete
+    - Simpler than AVL trees (less strict balancing = fewer rotations)
+    - Industry standard (used in Java TreeMap, C++ std::map, Linux kernel)
+    - Better insert/delete performance than AVL (relaxed balancing)
+    - Maintains sorted order with efficient range queries
+    
+    WHY this implementation:
+    - Color-based balancing rules (simpler than height-based AVL)
+    - Parent pointers enable bottom-up fixup after operations
+    - Case-based rotation logic handles all red-black violations
+    - Tracks rotations and statistics for performance monitoring
+    - Preserves BST property while maintaining logarithmic height
+    
+    Time Complexity:
+    - Insert: O(log n) guaranteed (at most 2 rotations)
+    - Search: O(log n) guaranteed
+    - Delete: O(log n) guaranteed (at most 3 rotations)
+    - Min/Max: O(log n) - leftmost/rightmost traversal
+    - Iteration: O(n) in sorted order
+    
+    Space Complexity: O(n) - one node per key + parent pointers + color bit
+    
+    Trade-offs:
+    - Advantage: Fewer rotations than AVL (better insert/delete performance)
+    - Advantage: Guaranteed O(log n) worst-case (unlike Skip List)
+    - Limitation: Slightly taller than AVL trees (height ≤ 2*log(n+1))
+    - Limitation: More complex than simple BST (color rules and rotations)
+    - Compared to AVL: Faster inserts/deletes, slightly slower searches
+    - Compared to B-Tree: Better for in-memory, worse for disk-based storage
+    
+    Best for:
+    - General-purpose sorted collections (maps, sets)
+    - When insert/delete and search performance matter equally
+    - Implementing associative containers (key-value stores)
+    - When guaranteed O(log n) worst-case is required
+    - In-memory databases and indices
+    
+    Not recommended for:
+    - Read-heavy workloads (AVL Tree is better)
+    - Disk-based storage (B-Tree is better)
+    - Simple, unsorted data (Hash Map is faster)
+    - Memory-constrained environments (overhead for parent pointers + color)
+    - When probabilistic guarantees suffice (Skip List is simpler)
+    
+    Following eXonware Priorities:
+    1. Usability: Self-balancing ensures consistent O(log n) performance
+    2. Maintainability: Industry-standard algorithm, well-documented
+    3. Performance: Optimized balance between insert and search operations
+    4. Extensibility: Can be enhanced with augmentation (order statistics, intervals)
+    5. Security: Input validation, bounded height prevents worst-case attacks
+    
+    Industry Best Practices:
+    - Follows Cormen CLRS textbook implementation
+    - Maintains 5 red-black properties:
+      1. Every node is red or black
+      2. Root is black
+      3. Leaves (NIL) are black
+      4. Red nodes have black children
+      5. All paths have same number of black nodes
+    - Uses case-based fixup (standard approach)
+    - Tracks performance statistics
+    
+    Performance Note:
+    Red-Black Trees provide GUARANTEED O(log n) in worst-case.
+    Height is at most 2*log(n+1), ensuring consistent performance
+    even with adversarial input patterns. This makes them ideal for
+    production systems requiring predictable latency.
+    """
     
     # Strategy type classification
     STRATEGY_TYPE = NodeType.TREE
-ing rules and rotations.
-    """
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
         """Initialize the red-black tree strategy."""
@@ -267,98 +332,136 @@ ing rules and rotations.
         if not node:
             return False
         
-        # Find replacement node
+        # Store original color
+        original_color = node.color
+        
+        # Case 1: No left child
         if not node.left:
             replacement = node.right
+            self._transplant(node, node.right)
+        # Case 2: No right child
         elif not node.right:
             replacement = node.left
+            self._transplant(node, node.left)
+        # Case 3: Two children
         else:
-            replacement = self._find_min(node.right)
-            node.key = replacement.key
-            node.value = replacement.value
-            node = replacement
-        
-        # Remove node
-        if replacement:
-            replacement.parent = node.parent
-        
-        if not node.parent:
-            self._root = replacement
-        elif node == node.parent.left:
-            node.parent.left = replacement
-        else:
-            node.parent.right = replacement
+            # Find successor (minimum in right subtree)
+            successor = self._find_min(node.right)
+            original_color = successor.color
+            replacement = successor.right
+            
+            if successor.parent == node:
+                # Successor is direct right child
+                if replacement:
+                    replacement.parent = successor
+            else:
+                # Successor is deeper in tree
+                self._transplant(successor, successor.right)
+                successor.right = node.right
+                successor.right.parent = successor
+            
+            # Replace node with successor
+            self._transplant(node, successor)
+            successor.left = node.left
+            successor.left.parent = successor
+            successor.color = node.color
         
         # Fix red-black tree properties if needed
-        if node.is_black() and replacement:
+        if original_color == 'BLACK' and replacement:
             self._fix_deletion(replacement)
-        elif node.is_black():
-            self._fix_deletion(None)
         
         self._size -= 1
         self._total_deletions += 1
         return True
     
-    def _fix_deletion(self, node: Optional[RedBlackTreeNode]) -> None:
+    def _transplant(self, old_node: RedBlackTreeNode, new_node: Optional[RedBlackTreeNode]) -> None:
+        """Replace old_node with new_node in the tree."""
+        if not old_node.parent:
+            self._root = new_node
+        elif old_node == old_node.parent.left:
+            old_node.parent.left = new_node
+        else:
+            old_node.parent.right = new_node
+        
+        if new_node:
+            new_node.parent = old_node.parent
+    
+    def _fix_deletion(self, node: RedBlackTreeNode) -> None:
         """Fix red-black tree properties after deletion."""
-        while node != self._root and (not node or node.is_black()):
-            if node == node.parent.left:
-                sibling = node.parent.right
+        while node != self._root and node.is_black():
+            parent = node.parent
+            if not parent:
+                break
+                
+            if node == parent.left:
+                sibling = parent.right
                 if sibling and sibling.is_red():
                     # Case 1: Sibling is red
                     sibling.set_black()
-                    node.parent.set_red()
-                    self._rotate_left(node.parent)
-                    sibling = node.parent.right
+                    parent.set_red()
+                    self._rotate_left(parent)
+                    sibling = parent.right
                 
-                if (not sibling.left or sibling.left.is_black()) and \
-                   (not sibling.right or sibling.right.is_black()):
-                    # Case 2: Sibling and its children are black
-                    sibling.set_red()
-                    node = node.parent
-                else:
-                    if not sibling.right or sibling.right.is_black():
-                        # Case 3: Sibling's right child is black
-                        sibling.left.set_black()
+                if sibling:
+                    if ((not sibling.left or sibling.left.is_black()) and 
+                        (not sibling.right or sibling.right.is_black())):
+                        # Case 2: Sibling and its children are black
                         sibling.set_red()
-                        self._rotate_right(sibling)
-                        sibling = node.parent.right
-                    
-                    # Case 4: Sibling's right child is red
-                    sibling.color = node.parent.color
-                    node.parent.set_black()
-                    sibling.right.set_black()
-                    self._rotate_left(node.parent)
-                    node = self._root
+                        node = parent
+                    else:
+                        if not sibling.right or sibling.right.is_black():
+                            # Case 3: Sibling's right child is black
+                            if sibling.left:
+                                sibling.left.set_black()
+                            sibling.set_red()
+                            self._rotate_right(sibling)
+                            sibling = parent.right
+                        
+                        # Case 4: Sibling's right child is red
+                        if sibling:
+                            sibling.color = parent.color
+                            parent.set_black()
+                            if sibling.right:
+                                sibling.right.set_black()
+                            self._rotate_left(parent)
+                        node = self._root
+                else:
+                    break
             else:
                 # Mirror cases for right side
-                sibling = node.parent.left
+                sibling = parent.left
                 if sibling and sibling.is_red():
                     # Case 1: Sibling is red
                     sibling.set_black()
-                    node.parent.set_red()
-                    self._rotate_right(node.parent)
-                    sibling = node.parent.left
+                    parent.set_red()
+                    self._rotate_right(parent)
+                    sibling = parent.left
                 
-                if (not sibling.right or sibling.right.is_black()) and \
-                   (not sibling.left or sibling.left.is_black()):
-                    # Case 2: Sibling and its children are black
-                    sibling.set_red()
-                    node = node.parent
-                else:
-                    if not sibling.left or sibling.left.is_black():
-                        # Case 3: Sibling's left child is black
-                        sibling.right.set_black()
+                if sibling:
+                    if ((not sibling.right or sibling.right.is_black()) and 
+                        (not sibling.left or sibling.left.is_black())):
+                        # Case 2: Sibling and its children are black
                         sibling.set_red()
-                        self._rotate_left(sibling)
-                        sibling = node.parent.left
-                    
-                    # Case 4: Sibling's left child is red
-                    sibling.color = node.parent.color
-                    node.parent.set_black()
-                    sibling.left.set_black()
-                    self._rotate_right(node.parent)
-                    node = self._root
+                        node = parent
+                    else:
+                        if not sibling.left or sibling.left.is_black():
+                            # Case 3: Sibling's left child is black
+                            if sibling.right:
+                                sibling.right.set_black()
+                            sibling.set_red()
+                            self._rotate_left(sibling)
+                            sibling = parent.left
+                        
+                        # Case 4: Sibling's left child is red
+                        if sibling:
+                            sibling.color = parent.color
+                            parent.set_black()
+                            if sibling.left:
+                                sibling.left.set_black()
+                            self._rotate_right(parent)
+                        node = self._root
+                else:
+                    break
         
         if node:
             node.set_black()
@@ -412,6 +515,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_roaring_bitmap.py → roaring_bitmap.py}

@@ -1,8 +1,21 @@
 """
+#exonware/xwnode/src/exonware/xwnode/nodes/strategies/roaring_bitmap.py
+
 Roaring Bitmap Node Strategy Implementation
 
+Status: Production Ready ✅
+True Purpose: Highly compressed bitmap operations for sparse data
+Complexity: O(log n) arrays, O(1) bitmaps - hybrid approach
+Production Features: ✓ Hybrid Containers, ✓ Auto-conversion, ✓ Set Operations, ✓ Compression
+
 This module implements the ROARING_BITMAP strategy for highly compressed
 bitmap operations with excellent performance for sparse data.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.23
+Generation Date: October 12, 2025
 """
 
 from typing import Any, Iterator, List, Dict, Optional, Set, Tuple
@@ -394,9 +407,9 @@ ormance characteristics.
                 removed_count += 1
         return removed_count
     
-    def union(self, other: 'xRoaringBitmapStrategy') -> 'xRoaringBitmapStrategy':
+    def union(self, other: 'RoaringBitmapStrategy') -> 'RoaringBitmapStrategy':
         """Union with another roaring bitmap."""
-        result = xRoaringBitmapStrategy(traits=self._traits)
+        result = RoaringBitmapStrategy(traits=self.traits)
         
         # Union all containers
         all_highs = set(self._containers.keys()) | set(other._containers.keys())
@@ -417,9 +430,9 @@ ormance characteristics.
         
         return result
     
-    def intersection(self, other: 'xRoaringBitmapStrategy') -> 'xRoaringBitmapStrategy':
+    def intersection(self, other: 'RoaringBitmapStrategy') -> 'RoaringBitmapStrategy':
         """Intersection with another roaring bitmap."""
-        result = xRoaringBitmapStrategy(traits=self._traits)
+        result = RoaringBitmapStrategy(traits=self.traits)
         
         # Intersect only common containers
         common_highs = set(self._containers.keys()) & set(other._containers.keys())
@@ -436,9 +449,9 @@ ormance characteristics.
         
         return result
     
-    def difference(self, other: 'xRoaringBitmapStrategy') -> 'xRoaringBitmapStrategy':
+    def difference(self, other: 'RoaringBitmapStrategy') -> 'RoaringBitmapStrategy':
         """Difference with another roaring bitmap."""
-        result = xRoaringBitmapStrategy(traits=self._traits)
+        result = RoaringBitmapStrategy(traits=self.traits)
         
         for high, container in self._containers.items():
             self_values = set(container.to_array())