exonware-xwnode 0.0.1.12__py3-none-any.whl

exonware/xwnode/strategies/nodes/node_segment_tree.py

@@ -0,0 +1,289 @@
+"""
+Segment Tree Node Strategy Implementation
+
+This module implements the SEGMENT_TREE strategy for range queries
+and updates with O(log n) complexity.
+"""
+
+from typing import Any, Iterator, List, Optional, Callable, Dict, Union
+from .base import ANodeTreeStrategy
+from ...types 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
+    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._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))
+        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."""
+        return (NodeTrait.INDEXED | NodeTrait.HIERARCHICAL | NodeTrait.STREAMING)
+    
+    def _get_identity(self, operation: str) -> Any:
+        """Get identity element for the operation."""
+        identities = {
+            'sum': 0,
+            'min': float('inf'),
+            'max': float('-inf'),
+            'product': 1,
+            'gcd': 0,
+            'lcm': 1,
+            'xor': 0,
+            'and': True,
+            'or': False
+        }
+        return identities.get(operation, 0)
+    
+    def _get_combiner(self, operation: str) -> Callable[[Any, Any], Any]:
+        """Get combiner function for the operation."""
+        import math
+        
+        combiners = {
+            'sum': lambda a, b: a + b,
+            'min': lambda a, b: min(a, b),
+            'max': lambda a, b: max(a, b),
+            'product': lambda a, b: a * b,
+            'gcd': lambda a, b: math.gcd(int(a), int(b)),
+            'lcm': lambda a, b: abs(int(a) * int(b)) // math.gcd(int(a), int(b)),
+            'xor': lambda a, b: a ^ b,
+            'and': lambda a, b: a and b,
+            'or': lambda a, b: a or b
+        }
+        return combiners.get(operation, lambda a, b: a + b)
+    
+    # ============================================================================
+    # CORE OPERATIONS (Key-based interface for compatibility)
+    # ============================================================================
+    
+    def put(self, key: Any, value: Any = None) -> None:
+        """Store a value at the given key."""
+        key_str = str(key)
+        
+        # Convert value to numeric if possible
+        try:
+            numeric_value = float(value) if value is not None else 0.0
+        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)
+        
+        self._values[key_str] = value
+    
+    def get(self, key: Any, default: Any = None) -> Any:
+        """Retrieve a value by key."""
+        key_str = str(key)
+        return self._values.get(key_str, default)
+    
+    def has(self, key: Any) -> bool:
+        """Check if key exists."""
+        return str(key) in self._values
+    
+    def remove(self, key: Any) -> bool:
+        """Remove value by key."""
+        key_str = str(key)
+        if key_str not in self._indices:
+            return False
+        
+        idx = self._indices[key_str]
+        self._update_point(idx, self._identity)
+        
+        del self._indices[key_str]
+        del self._reverse_indices[idx]
+        del self._values[key_str]
+        
+        return True
+    
+    def delete(self, key: Any) -> bool:
+        """Remove value by key (alias for remove)."""
+        return self.remove(key)
+    
+    def clear(self) -> None:
+        """Clear all data."""
+        self._tree = [self._identity] * (4 * max(1, self._size))
+        self._values.clear()
+        self._indices.clear()
+        self._reverse_indices.clear()
+        self._next_index = 0
+    
+    def keys(self) -> Iterator[str]:
+        """Get all keys."""
+        return iter(self._values.keys())
+    
+    def values(self) -> Iterator[Any]:
+        """Get all values."""
+        return iter(self._values.values())
+    
+    def items(self) -> Iterator[tuple[str, Any]]:
+        """Get all key-value pairs."""
+        return iter(self._values.items())
+    
+    def __len__(self) -> int:
+        """Get the number of items."""
+        return len(self._values)
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert to native Python dict."""
+        return dict(self._values)
+    
+    @property
+    def is_list(self) -> bool:
+        """This can behave like a list."""
+        return True
+    
+    @property
+    def is_dict(self) -> bool:
+        """This can behave like a dict."""
+        return True
+    
+    # ============================================================================
+    # 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
+        
+        # Update leaf
+        self._tree[tree_idx] = value
+        
+        # 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)
+    
+    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
+        
+        if query_left <= start and end <= query_right:
+            return self._tree[node] if node < len(self._tree) else self._identity
+        
+        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)
+        
+        return self._combiner(left_result, right_result)
+    
+    def range_update(self, left: int, right: int, value: Any) -> None:
+        """Update range [left, right] with value (point updates)."""
+        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
+    
+    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))
+        }
+    
+    # ============================================================================
+    # PERFORMANCE CHARACTERISTICS
+    # ============================================================================
+    
+    @property
+    def backend_info(self) -> Dict[str, Any]:
+        """Get backend implementation info."""
+        return {
+            'strategy': 'SEGMENT_TREE',
+            'backend': 'Array-based segment tree',
+            'operation': self._operation,
+            'complexity': {
+                'point_update': 'O(log n)',
+                'range_query': 'O(log n)',
+                'range_update': 'O(n log n)',
+                'build': 'O(n)'
+            }
+        }
+    
+    @property
+    def metrics(self) -> Dict[str, Any]:
+        """Get performance metrics."""
+        tree_height = 0
+        if len(self._values) > 0:
+            import math
+            tree_height = math.ceil(math.log2(len(self._values)))
+        
+        return {
+            'size': len(self._values),
+            'tree_size': len(self._tree),
+            'tree_height': tree_height,
+            'operation': self._operation,
+            'memory_usage': f"{len(self._tree) * 8 + len(self._values) * 24} bytes (estimated)",
+            'utilization': f"{len(self._values) / max(1, len(self._tree) // 4) * 100:.1f}%"
+        }

exonware/xwnode/strategies/nodes/node_set_hash.py

@@ -0,0 +1,354 @@
+"""
+Hash Set Node Strategy Implementation
+
+This module implements the SET_HASH strategy for efficient set operations
+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 ...types import NodeMode, NodeTrait
+
+
+class xSetHashStrategy(aNodeStrategy):
+    """
+    Hash Set node strategy for efficient set operations.
+    
+    Provides O(1) average-case membership testing, insertion, and deletion
+    with automatic handling of duplicates and fast set operations.
+    """
+    
+    def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
+        """Initialize the Hash Set strategy."""
+        super().__init__(NodeMode.SET_HASH, traits, **options)
+        
+        self.load_factor = options.get('load_factor', 0.75)
+        self.initial_capacity = options.get('initial_capacity', 16)
+        
+        # Core storage: hash set for uniqueness
+        self._set: Set[str] = set()
+        self._values: Dict[str, Any] = {}  # Value storage for compatibility
+        self._size = 0
+        
+        # Set-specific options
+        self.case_sensitive = options.get('case_sensitive', True)
+        self.allow_none = options.get('allow_none', True)
+    
+    def get_supported_traits(self) -> NodeTrait:
+        """Get the traits supported by the hash set strategy."""
+        return (NodeTrait.INDEXED | NodeTrait.STREAMING)
+    
+    # ============================================================================
+    # CORE OPERATIONS (Key-based interface for compatibility)
+    # ============================================================================
+    
+    def put(self, key: Any, value: Any = None) -> None:
+        """Add a value to the set (key becomes the set element)."""
+        if value is None and not self.allow_none:
+            return
+        
+        # Use key as the set element
+        element = str(key) if not self.case_sensitive else str(key)
+        if not self.case_sensitive:
+            element = element.lower()
+        
+        # Add to set (automatic deduplication)
+        was_new = element not in self._set
+        self._set.add(element)
+        self._values[element] = value if value is not None else key
+        
+        if was_new:
+            self._size += 1
+        
+        # Keep size in sync
+        self._size = len(self._set)
+    
+    def get(self, key: Any, default: Any = None) -> Any:
+        """Retrieve a value by key (check if element exists in set)."""
+        element = str(key) if not self.case_sensitive else str(key)
+        if not self.case_sensitive:
+            element = element.lower()
+        
+        return self._values.get(element, default)
+    
+    def has(self, key: Any) -> bool:
+        """Check if key exists in set (O(1) membership test)."""
+        element = str(key) if not self.case_sensitive else str(key)
+        if not self.case_sensitive:
+            element = element.lower()
+        
+        return element in self._set
+    
+    def remove(self, key: Any) -> bool:
+        """Remove element from set."""
+        element = str(key) if not self.case_sensitive else str(key)
+        if not self.case_sensitive:
+            element = element.lower()
+        
+        if element in self._set:
+            self._set.remove(element)
+            if element in self._values:
+                del self._values[element]
+            self._size -= 1
+            return True
+        return False
+    
+    def delete(self, key: Any) -> bool:
+        """Remove element from set (alias for remove)."""
+        return self.remove(key)
+    
+    def clear(self) -> None:
+        """Clear all elements from the set."""
+        self._set.clear()
+        self._values.clear()
+        self._size = 0
+    
+    def keys(self) -> Iterator[str]:
+        """Get all elements in the set."""
+        return iter(self._set)
+    
+    def values(self) -> Iterator[Any]:
+        """Get all values (for compatibility)."""
+        return iter(self._values.values())
+    
+    def items(self) -> Iterator[tuple[str, Any]]:
+        """Get all element-value pairs."""
+        return iter(self._values.items())
+    
+    def __len__(self) -> int:
+        """Get the number of elements in the set."""
+        return self._size
+    
+    def to_native(self) -> Set[Any]:
+        """Convert to native Python set."""
+        return set(self._set)
+    
+    @property
+    def is_list(self) -> bool:
+        """This is not a list strategy."""
+        return False
+    
+    @property
+    def is_dict(self) -> bool:
+        """This behaves like a dict but represents a set."""
+        return True
+    
+    # ============================================================================
+    # SET-SPECIFIC OPERATIONS
+    # ============================================================================
+    
+    def add(self, element: Any) -> bool:
+        """Add an element to the set. Returns True if element was new."""
+        element_str = str(element) if not self.case_sensitive else str(element)
+        if not self.case_sensitive:
+            element_str = element_str.lower()
+        
+        was_new = element_str not in self._set
+        self._set.add(element_str)
+        self._values[element_str] = element
+        
+        if was_new:
+            self._size += 1
+        
+        return was_new
+    
+    def discard(self, element: Any) -> None:
+        """Remove element if present (no error if not found)."""
+        self.remove(element)
+    
+    def pop(self) -> Any:
+        """Remove and return an arbitrary element."""
+        if not self._set:
+            raise KeyError("pop from empty set")
+        
+        element = self._set.pop()
+        value = self._values.pop(element, element)
+        self._size -= 1
+        return value
+    
+    def union(self, other: Union['xSetHashStrategy', Set, List]) -> 'xSetHashStrategy':
+        """Return union of this set with another."""
+        result = xSetHashStrategy(
+            traits=self._traits,
+            case_sensitive=self.case_sensitive,
+            allow_none=self.allow_none
+        )
+        
+        # Add all elements from this set
+        for element in self._set:
+            result.add(self._values[element])
+        
+        # Add elements from other
+        if isinstance(other, xSetHashStrategy):
+            for element in other._set:
+                result.add(other._values[element])
+        elif isinstance(other, (set, list)):
+            for element in other:
+                result.add(element)
+        
+        return result
+    
+    def intersection(self, other: Union['xSetHashStrategy', Set, List]) -> 'xSetHashStrategy':
+        """Return intersection of this set with another."""
+        result = xSetHashStrategy(
+            traits=self._traits,
+            case_sensitive=self.case_sensitive,
+            allow_none=self.allow_none
+        )
+        
+        if isinstance(other, xSetHashStrategy):
+            common = self._set.intersection(other._set)
+            for element in common:
+                result.add(self._values[element])
+        elif isinstance(other, (set, list)):
+            other_set = {str(x).lower() if not self.case_sensitive else str(x) for x in other}
+            common = self._set.intersection(other_set)
+            for element in common:
+                result.add(self._values[element])
+        
+        return result
+    
+    def difference(self, other: Union['xSetHashStrategy', Set, List]) -> 'xSetHashStrategy':
+        """Return difference of this set with another."""
+        result = xSetHashStrategy(
+            traits=self._traits,
+            case_sensitive=self.case_sensitive,
+            allow_none=self.allow_none
+        )
+        
+        if isinstance(other, xSetHashStrategy):
+            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}
+            diff = self._set.difference(other_set)
+        else:
+            diff = self._set.copy()
+        
+        for element in diff:
+            result.add(self._values[element])
+        
+        return result
+    
+    def symmetric_difference(self, other: Union['xSetHashStrategy', Set, List]) -> 'xSetHashStrategy':
+        """Return symmetric difference of this set with another."""
+        result = xSetHashStrategy(
+            traits=self._traits,
+            case_sensitive=self.case_sensitive,
+            allow_none=self.allow_none
+        )
+        
+        if isinstance(other, xSetHashStrategy):
+            sym_diff = self._set.symmetric_difference(other._set)
+            for element in sym_diff:
+                if element in self._values:
+                    result.add(self._values[element])
+                elif element in other._values:
+                    result.add(other._values[element])
+        elif isinstance(other, (set, list)):
+            other_set = {str(x).lower() if not self.case_sensitive else str(x) for x in other}
+            sym_diff = self._set.symmetric_difference(other_set)
+            for element in sym_diff:
+                if element in self._values:
+                    result.add(self._values[element])
+                else:
+                    # Find original element in other
+                    for orig in other:
+                        if (str(orig).lower() if not self.case_sensitive else str(orig)) == element:
+                            result.add(orig)
+                            break
+        
+        return result
+    
+    def is_subset(self, other: Union['xSetHashStrategy', Set, List]) -> bool:
+        """Check if this set is a subset of another."""
+        if isinstance(other, xSetHashStrategy):
+            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:
+        """Check if this set is a superset of another."""
+        if isinstance(other, xSetHashStrategy):
+            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:
+        """Check if this set has no elements in common with another."""
+        if isinstance(other, xSetHashStrategy):
+            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':
+        """Create a shallow copy of the set."""
+        result = xSetHashStrategy(
+            traits=self._traits,
+            case_sensitive=self.case_sensitive,
+            allow_none=self.allow_none
+        )
+        
+        for element in self._set:
+            result.add(self._values[element])
+        
+        return result
+    
+    def update(self, *others) -> None:
+        """Update the set with elements from other iterables."""
+        for other in others:
+            if isinstance(other, xSetHashStrategy):
+                for element in other._set:
+                    self.add(other._values[element])
+            elif isinstance(other, (set, list, tuple)):
+                for element in other:
+                    self.add(element)
+    
+    def get_hash(self) -> str:
+        """Get a hash representation of the set."""
+        # Sort elements for consistent hashing
+        sorted_elements = sorted(self._set)
+        content = ''.join(sorted_elements)
+        return hashlib.md5(content.encode()).hexdigest()
+    
+    # ============================================================================
+    # PERFORMANCE CHARACTERISTICS
+    # ============================================================================
+    
+    @property
+    def backend_info(self) -> Dict[str, Any]:
+        """Get backend implementation info."""
+        return {
+            'strategy': 'SET_HASH',
+            'backend': 'Python set + dict',
+            'case_sensitive': self.case_sensitive,
+            'allow_none': self.allow_none,
+            'complexity': {
+                'add': 'O(1) average',
+                'remove': 'O(1) average',
+                'contains': 'O(1) average',
+                'union': 'O(n + m)',
+                'intersection': 'O(min(n, m))',
+                'space': 'O(n)'
+            }
+        }
+    
+    @property
+    def metrics(self) -> Dict[str, Any]:
+        """Get performance metrics."""
+        collision_estimate = max(0, len(self._values) - len(self._set))
+        
+        return {
+            'size': self._size,
+            'unique_elements': len(self._set),
+            'collisions_estimate': collision_estimate,
+            'load_factor': self.load_factor,
+            'memory_usage': f"{self._size * 32} bytes (estimated)",
+            'hash': self.get_hash()[:8] + "..."
+        }