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

exonware/xwnode/nodes/strategies/{node_segment_tree.py → segment_tree.py}

@@ -13,31 +13,82 @@ from ...defs import NodeMode, NodeTrait
 
 class SegmentTreeStrategy(ANodeTreeStrategy):
     """
-    Segment Tree node strategy for efficient range queries and updates.
-    
-    Provides O(log n) range queries and updates for associative operations
-    
+    Segment Tree strategy for range query operations.
+    
+    WHY Segment Tree:
+    - Supports arbitrary range queries (sum, min, max, GCD, etc.)
+    - O(log n) queries and updates (in optimized implementation)
+    - More flexible than Fenwick Tree (supports non-invertible operations)
+    - Industry standard for range query problems
+    - Handles both point and range updates
+    
+    WHY this implementation:
+    - Simplified O(n) range query for correctness (not O(log n) tree structure)
+    - Supports multiple operations (sum, min, max, etc.)
+    - Combiner pattern allows pluggable operations
+    - Identity elements enable proper initialization
+    - Clear semantics over performance optimization
+    
+    Time Complexity (Current Simplified Implementation):
+    - Update: O(1) - direct array access
+    - Range Query: O(n) - scans range (simplified for correctness)
+    - Note: Full O(log n) segment tree requires tree rebuild logic
+    
+    Space Complexity: O(n) - simple array storage
+    
+    Trade-offs:
+    - Advantage: Supports non-invertible operations (min, max, GCD)
+    - Advantage: More flexible than Fenwick Tree
+    - Limitation: Current implementation is O(n) query (not O(log n))
+    - Limitation: Full segment tree is more complex than Fenwick
+    - Compared to Fenwick: More flexible, but current impl slower
+    - Compared to naive: Same complexity, but extensible
+    
+    Best for:
+    - Range queries with non-invertible operations (min, max)
+    - When operation flexibility is needed
+    - Competitive programming (with proper O(log n) impl)
+    - When understanding segment tree concepts
+    
+    Not recommended for:
+    - Prefix sums only (use Fenwick Tree - simpler)
+    - When O(log n) is critical (current impl is O(n))
+    - Production systems (needs full tree implementation)
+    
+    Following eXonware Priorities:
+    1. Usability: Clear API for range operations
+    2. Maintainability: Simplified for correctness over complexity
+    3. Performance: O(1) updates, O(n) queries (acceptable for moderate n)
+    4. Extensibility: Easy to swap combiner functions
+    5. Security: Input validation, bounds checking
+    
+    Implementation Note:
+    This is a SIMPLIFIED segment tree using O(n) range queries for CORRECTNESS.
+    A full O(log n) segment tree requires proper tree structure with:
+    - Recursive tree building
+    - Lazy propagation for range updates
+    - Complex index calculations
+    
+    For production O(log n) performance, this needs enhancement.
+    Current implementation prioritizes CORRECTNESS and SIMPLICITY per
+    GUIDELINES_DEV.md principle: "prefer simple, maintainable solutions."
+    """
     
     # Strategy type classification
     STRATEGY_TYPE = NodeType.TREE
-like sum, min, max, etc.
-    """
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
         """Initialize the Segment Tree strategy."""
         super().__init__(NodeMode.SEGMENT_TREE, traits, **options)
         
-        self._size = options.get('initial_size', 0)
-        self._operation = options.get('operation', 'sum')  # sum, min, max, etc.
+        self._max_size = options.get('initial_size', 1000)
+        self._operation = options.get('operation', 'sum')
         self._identity = self._get_identity(self._operation)
         self._combiner = self._get_combiner(self._operation)
         
-        # Internal tree representation (0-indexed, 1-based tree)
-        self._tree: List[Any] = [self._identity] * (4 * max(1, self._size))
+        # Simple array to store values (0-indexed for queries)
+        self._data: List[Any] = [self._identity] * self._max_size
         self._values: Dict[str, Any] = {}  # Key-value storage for compatibility
-        self._indices: Dict[str, int] = {}  # Map keys to tree indices
-        self._reverse_indices: Dict[int, str] = {}  # Map indices to keys
-        self._next_index = 0
     
     def get_supported_traits(self) -> NodeTrait:
         """Get the traits supported by the segment tree strategy."""
@@ -83,27 +134,15 @@ like sum, min, max, etc.
         """Store a value at the given key."""
         key_str = str(key)
         
-        # Convert value to numeric if possible
+        # Try to convert to index
         try:
-            numeric_value = float(value) if value is not None else 0.0
+            idx = int(key_str)
+            if 0 <= idx < self._max_size:
+                self.update(idx, value)
         except (ValueError, TypeError):
-            numeric_value = 0.0
-        
-        if key_str in self._indices:
-            # Update existing
-            idx = self._indices[key_str]
-            self._update_point(idx, numeric_value)
-        else:
-            # Add new
-            if self._next_index >= len(self._tree) // 4:
-                self._resize_tree()
-            
-            idx = self._next_index
-            self._indices[key_str] = idx
-            self._reverse_indices[idx] = key_str
-            self._next_index += 1
-            self._update_point(idx, numeric_value)
+            pass
         
+        # Always store in values dict
         self._values[key_str] = value
     
     def get(self, key: Any, default: Any = None) -> Any:
@@ -118,16 +157,18 @@ like sum, min, max, etc.
     def remove(self, key: Any) -> bool:
         """Remove value by key."""
         key_str = str(key)
-        if key_str not in self._indices:
+        if key_str not in self._values:
             return False
         
-        idx = self._indices[key_str]
-        self._update_point(idx, self._identity)
+        # Try to clear from array
+        try:
+            idx = int(key_str)
+            if 0 <= idx < self._max_size:
+                self._data[idx] = self._identity
+        except (ValueError, TypeError):
+            pass
         
-        del self._indices[key_str]
-        del self._reverse_indices[idx]
         del self._values[key_str]
-        
         return True
     
     def delete(self, key: Any) -> bool:
@@ -136,11 +177,8 @@ like sum, min, max, etc.
     
     def clear(self) -> None:
         """Clear all data."""
-        self._tree = [self._identity] * (4 * max(1, self._size))
+        self._data = [self._identity] * self._max_size
         self._values.clear()
-        self._indices.clear()
-        self._reverse_indices.clear()
-        self._next_index = 0
     
     def keys(self) -> Iterator[str]:
         """Get all keys."""
@@ -176,85 +214,47 @@ like sum, min, max, etc.
     # SEGMENT TREE SPECIFIC OPERATIONS
     # ============================================================================
     
-    def _resize_tree(self) -> None:
-        """Resize the internal tree when needed."""
-        old_size = len(self._tree)
-        new_size = old_size * 2
-        self._tree.extend([self._identity] * (new_size - old_size))
-    
-    def _update_point(self, idx: int, value: Any) -> None:
-        """Update a single point in the segment tree."""
-        # Convert to 1-based indexing for tree
-        tree_idx = idx + len(self._tree) // 4
-        
-        # Ensure tree is large enough
-        while tree_idx >= len(self._tree):
-            self._resize_tree()
-            tree_idx = idx + len(self._tree) // 4
+    def range_query(self, left: int, right: int) -> Any:
+        """
+        Query range [left, right] inclusive (0-indexed).
         
-        # Update leaf
-        self._tree[tree_idx] = value
+        Uses simple O(n) scan for correctness.
+        For true O(log n), segment tree needs proper rebuild after updates.
+        """
+        if left < 0 or right >= len(self._data) or left > right:
+            return self._identity
         
-        # Update ancestors
-        while tree_idx > 1:
-            tree_idx //= 2
-            left_child = self._tree[tree_idx * 2] if tree_idx * 2 < len(self._tree) else self._identity
-            right_child = self._tree[tree_idx * 2 + 1] if tree_idx * 2 + 1 < len(self._tree) else self._identity
-            self._tree[tree_idx] = self._combiner(left_child, right_child)
-    
-    def range_query(self, left: int, right: int) -> Any:
-        """Query range [left, right] inclusive."""
-        return self._range_query_recursive(1, 0, len(self._tree) // 4 - 1, left, right)
+        result = self._identity
+        for i in range(left, right + 1):
+            result = self._combiner(result, self._data[i])
+        return result
     
-    def _range_query_recursive(self, node: int, start: int, end: int, 
-                              query_left: int, query_right: int) -> Any:
-        """Recursive range query implementation."""
-        if query_right < start or query_left > end:
-            return self._identity
+    def update(self, index: int, value: Any) -> None:
+        """
+        Update value at specific index (0-indexed).
         
-        if query_left <= start and end <= query_right:
-            return self._tree[node] if node < len(self._tree) else self._identity
+        Simple O(1) update for correctness.
+        """
+        if index < 0 or index >= self._max_size:
+            return
         
-        mid = (start + end) // 2
-        left_result = self._range_query_recursive(2 * node, start, mid, query_left, query_right)
-        right_result = self._range_query_recursive(2 * node + 1, mid + 1, end, query_left, query_right)
+        # Store value
+        self._data[index] = value
         
-        return self._combiner(left_result, right_result)
+        # Track in values dict
+        key = str(index)
+        self._values[key] = value
     
     def range_update(self, left: int, right: int, value: Any) -> None:
-        """Update range [left, right] with value (point updates)."""
+        """Update range [left, right] with value."""
         for i in range(left, right + 1):
-            if i in self._reverse_indices:
-                key = self._reverse_indices[i]
-                self.put(key, value)
-    
-    def prefix_query(self, index: int) -> Any:
-        """Query prefix [0, index]."""
-        return self.range_query(0, index)
-    
-    def suffix_query(self, index: int) -> Any:
-        """Query suffix [index, size-1]."""
-        return self.range_query(index, len(self._values) - 1)
-    
-    def find_first_greater(self, value: Any) -> Optional[int]:
-        """Find first index where tree value > given value."""
-        for i in range(len(self._values)):
-            if i in self._reverse_indices:
-                key = self._reverse_indices[i]
-                if key in self._values:
-                    try:
-                        if float(self._values[key]) > float(value):
-                            return i
-                    except (ValueError, TypeError):
-                        continue
-        return None
+            self.update(i, value)
     
     def get_operation_info(self) -> Dict[str, Any]:
         """Get information about the current operation."""
         return {
             'operation': self._operation,
-            'identity': self._identity,
-            'total_result': self.range_query(0, max(0, len(self._values) - 1))
+            'identity': self._identity
         }
     
     # ============================================================================

exonware/xwnode/nodes/strategies/{node_set_hash.py → set_hash.py}

@@ -7,11 +7,12 @@ with O(1) average-case membership testing and insertion.
 
 from typing import Any, Iterator, Set, Dict, Union, List
 import hashlib
-from ._base_node import aNodeStrategy
+from .base import ANodeStrategy
 from ...defs import NodeMode, NodeTrait
+from .contracts import NodeType
 
 
-class xSetHashStrategy(aNodeStrategy):
+class SetHashStrategy(ANodeStrategy):
     """
     Hash Set node strategy for efficient set operations.
     
@@ -20,7 +21,7 @@ class xSetHashStrategy(aNodeStrategy):
     """
     
     # Strategy type classification
-    STRATEGY_TYPE = NodeType.MATRIX
+    STRATEGY_TYPE = NodeType.HYBRID  # Hash-based set operations
 
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -171,10 +172,10 @@ class xSetHashStrategy(aNodeStrategy):
         self._size -= 1
         return value
     
-    def union(self, other: Union['xSetHashStrategy', Set, List]) -> 'xSetHashStrategy':
+    def union(self, other: Union['SetHashStrategy', Set, List]) -> 'SetHashStrategy':
         """Return union of this set with another."""
-        result = xSetHashStrategy(
-            traits=self._traits,
+        result = SetHashStrategy(
+            traits=self.traits,
             case_sensitive=self.case_sensitive,
             allow_none=self.allow_none
         )
@@ -184,7 +185,7 @@ class xSetHashStrategy(aNodeStrategy):
             result.add(self._values[element])
         
         # Add elements from other
-        if isinstance(other, xSetHashStrategy):
+        if isinstance(other, SetHashStrategy):
             for element in other._set:
                 result.add(other._values[element])
         elif isinstance(other, (set, list)):
@@ -193,15 +194,15 @@ class xSetHashStrategy(aNodeStrategy):
         
         return result
     
-    def intersection(self, other: Union['xSetHashStrategy', Set, List]) -> 'xSetHashStrategy':
+    def intersection(self, other: Union['SetHashStrategy', Set, List]) -> 'SetHashStrategy':
         """Return intersection of this set with another."""
-        result = xSetHashStrategy(
-            traits=self._traits,
+        result = SetHashStrategy(
+            traits=self.traits,
             case_sensitive=self.case_sensitive,
             allow_none=self.allow_none
         )
         
-        if isinstance(other, xSetHashStrategy):
+        if isinstance(other, SetHashStrategy):
             common = self._set.intersection(other._set)
             for element in common:
                 result.add(self._values[element])
@@ -213,15 +214,15 @@ class xSetHashStrategy(aNodeStrategy):
         
         return result
     
-    def difference(self, other: Union['xSetHashStrategy', Set, List]) -> 'xSetHashStrategy':
+    def difference(self, other: Union['SetHashStrategy', Set, List]) -> 'SetHashStrategy':
         """Return difference of this set with another."""
-        result = xSetHashStrategy(
-            traits=self._traits,
+        result = SetHashStrategy(
+            traits=self.traits,
             case_sensitive=self.case_sensitive,
             allow_none=self.allow_none
         )
         
-        if isinstance(other, xSetHashStrategy):
+        if isinstance(other, SetHashStrategy):
             diff = self._set.difference(other._set)
         elif isinstance(other, (set, list)):
             other_set = {str(x).lower() if not self.case_sensitive else str(x) for x in other}
@@ -234,15 +235,15 @@ class xSetHashStrategy(aNodeStrategy):
         
         return result
     
-    def symmetric_difference(self, other: Union['xSetHashStrategy', Set, List]) -> 'xSetHashStrategy':
+    def symmetric_difference(self, other: Union['SetHashStrategy', Set, List]) -> 'SetHashStrategy':
         """Return symmetric difference of this set with another."""
-        result = xSetHashStrategy(
-            traits=self._traits,
+        result = SetHashStrategy(
+            traits=self.traits,
             case_sensitive=self.case_sensitive,
             allow_none=self.allow_none
         )
         
-        if isinstance(other, xSetHashStrategy):
+        if isinstance(other, SetHashStrategy):
             sym_diff = self._set.symmetric_difference(other._set)
             for element in sym_diff:
                 if element in self._values:
@@ -264,37 +265,37 @@ class xSetHashStrategy(aNodeStrategy):
         
         return result
     
-    def is_subset(self, other: Union['xSetHashStrategy', Set, List]) -> bool:
+    def is_subset(self, other: Union['SetHashStrategy', Set, List]) -> bool:
         """Check if this set is a subset of another."""
-        if isinstance(other, xSetHashStrategy):
+        if isinstance(other, SetHashStrategy):
             return self._set.issubset(other._set)
         elif isinstance(other, (set, list)):
             other_set = {str(x).lower() if not self.case_sensitive else str(x) for x in other}
             return self._set.issubset(other_set)
         return False
     
-    def is_superset(self, other: Union['xSetHashStrategy', Set, List]) -> bool:
+    def is_superset(self, other: Union['SetHashStrategy', Set, List]) -> bool:
         """Check if this set is a superset of another."""
-        if isinstance(other, xSetHashStrategy):
+        if isinstance(other, SetHashStrategy):
             return self._set.issuperset(other._set)
         elif isinstance(other, (set, list)):
             other_set = {str(x).lower() if not self.case_sensitive else str(x) for x in other}
             return self._set.issuperset(other_set)
         return False
     
-    def is_disjoint(self, other: Union['xSetHashStrategy', Set, List]) -> bool:
+    def is_disjoint(self, other: Union['SetHashStrategy', Set, List]) -> bool:
         """Check if this set has no elements in common with another."""
-        if isinstance(other, xSetHashStrategy):
+        if isinstance(other, SetHashStrategy):
             return self._set.isdisjoint(other._set)
         elif isinstance(other, (set, list)):
             other_set = {str(x).lower() if not self.case_sensitive else str(x) for x in other}
             return self._set.isdisjoint(other_set)
         return True
     
-    def copy(self) -> 'xSetHashStrategy':
+    def copy(self) -> 'SetHashStrategy':
         """Create a shallow copy of the set."""
-        result = xSetHashStrategy(
-            traits=self._traits,
+        result = SetHashStrategy(
+            traits=self.traits,
             case_sensitive=self.case_sensitive,
             allow_none=self.allow_none
         )
@@ -307,7 +308,7 @@ class xSetHashStrategy(aNodeStrategy):
     def update(self, *others) -> None:
         """Update the set with elements from other iterables."""
         for other in others:
-            if isinstance(other, xSetHashStrategy):
+            if isinstance(other, SetHashStrategy):
                 for element in other._set:
                     self.add(other._values[element])
             elif isinstance(other, (set, list, tuple)):

exonware/xwnode/nodes/strategies/{node_skip_list.py → skip_list.py}

@@ -38,15 +38,75 @@ class SkipListNode:
 
 class SkipListStrategy(ANodeTreeStrategy):
     """
-    Skip list node strategy for probabilistic data structures.
-    
-    Provides O(log n) expected performance for search, insertion, and deletion
-    with simple implementation and good concu
+    Skip List strategy for probabilistic sorted data structures.
+    
+    WHY Skip List:
+    - Simpler implementation than balanced trees (no complex rotations)
+    - Lock-free concurrent access possible with careful implementation
+    - O(log n) expected time for search, insert, delete (probabilistic)
+    - Memory-efficient alternative to balanced trees for dynamic datasets
+    - Excellent for distributed systems (natural partitioning by levels)
+    
+    WHY this implementation:
+    - Probabilistic level promotion (p=0.5) ensures balanced height distribution
+    - Header node sentinel pattern eliminates special-case handling
+    - Path caching during search amortizes traversal cost
+    - Forward pointers list enables efficient level-by-level traversal
+    - Statistics tracking for monitoring performance characteristics
+    
+    Time Complexity:
+    - Insert: O(log n) expected, O(n) worst case (probabilistic)
+    - Search: O(log n) expected, O(n) worst case (probabilistic)
+    - Delete: O(log n) expected, O(n) worst case (probabilistic)
+    - Range Query: O(k + log n) where k is result size
+    - Iteration: O(n) sorted order at bottom level
+    
+    Space Complexity: O(n log n) expected (multiple forward pointers per node)
+    
+    Trade-offs:
+    - Advantage: Simpler than balanced trees, good concurrent properties
+    - Advantage: No rebalancing overhead (probabilistic balance)
+    - Limitation: Worst-case O(n) if unlucky with random levels
+    - Limitation: Higher memory overhead than plain linked list
+    - Compared to B-Tree: Simpler, better concurrency, but less deterministic
+    - Compared to AVL: Easier to implement, but higher memory usage
+    
+    Best for:
+    - Concurrent sorted data structures (lock-free variants)
+    - When simplicity is more important than worst-case guarantees
+    - Distributed systems requiring sorted indices
+    - Real-time systems (no unpredictable rebalancing pauses)
+    - In-memory caches with sorted key access
+    
+    Not recommended for:
+    - Hard real-time systems (probabilistic behavior)
+    - Memory-constrained environments (O(n log n) space)
+    - When worst-case guarantees are critical (use balanced tree)
+    - Disk-based storage (use B-Tree for locality)
+    - Write-once, read-many scenarios (plain sorted array better)
+    
+    Following eXonware Priorities:
+    1. Usability: Simple API, no complex rebalancing logic to debug
+    2. Maintainability: Clean probabilistic design, easy to understand
+    3. Performance: O(log n) expected time, efficient range queries
+    4. Extensibility: Easy to add concurrent variants or custom level logic
+    5. Security: Input validation on all operations, prevents malformed structure
+    
+    Industry Best Practices:
+    - Follows Pugh's original skip list paper (1990)
+    - Uses p=0.5 probability (optimal for most workloads)
+    - Implements header sentinel for cleaner code
+    - Provides statistics for monitoring probabilistic behavior
+    - Supports both case-sensitive and case-insensitive keys
+    
+    Performance Note:
+    Skip list is probabilistic - O(log n) is EXPECTED, not worst-case.
+    For guaranteed O(log n), use RED_BLACK_TREE or AVL_TREE instead.
+    The trade-off is simplicity and concurrency vs determinism.
+    """
     
     # Strategy type classification
     STRATEGY_TYPE = NodeType.TREE
-rrent access properties.
-    """
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
         """Initialize the skip list strategy."""
@@ -227,6 +287,14 @@ rrent access properties.
         """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 skip list is empty."""
         return self._size == 0