exonware-xwnode 0.0.1.12__py3-none-any.whl

exonware/xwnode/strategies/nodes/trie.py

@@ -0,0 +1,274 @@
+"""
+Trie Node Strategy Implementation
+
+This module implements the TRIE strategy for efficient string prefix operations.
+"""
+
+from typing import Any, Iterator, Dict, List, Optional
+from .base import ANodeTreeStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class TrieNode:
+    """Node in the trie structure."""
+    
+    def __init__(self):
+        self.children: Dict[str, 'TrieNode'] = {}
+        self.is_end_of_word = False
+        self.value: Any = None
+
+
+class xTrieStrategy(ANodeTreeStrategy):
+    """
+    Trie node strategy for efficient string prefix operations.
+    
+    Optimized for prefix matching, autocomplete, and string searching.
+    """
+    
+    def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
+        """Initialize the trie strategy."""
+        super().__init__(data=None, **options)
+        self._mode = NodeMode.TRIE
+        self._traits = traits
+        self._root = TrieNode()
+        self._size = 0
+    
+    def get_supported_traits(self) -> NodeTrait:
+        """Get the traits supported by the trie strategy."""
+        return (NodeTrait.ORDERED | NodeTrait.HIERARCHICAL | NodeTrait.INDEXED)
+    
+    # ============================================================================
+    # CORE OPERATIONS
+    # ============================================================================
+    
+    def insert(self, key: Any, value: Any) -> None:
+        """Store a key-value pair (key should be string-like)."""
+        word = str(key)
+        node = self._root
+        
+        # Traverse/create path
+        for char in word:
+            if char not in node.children:
+                node.children[char] = TrieNode()
+            node = node.children[char]
+        
+        # Mark end of word and store value
+        if not node.is_end_of_word:
+            self._size += 1
+        node.is_end_of_word = True
+        node.value = value
+    
+    def find(self, key: Any) -> Any:
+        """Retrieve a value by key."""
+        word = str(key)
+        node = self._root
+        
+        # Traverse path
+        for char in word:
+            if char not in node.children:
+                return None
+            node = node.children[char]
+        
+        return node.value if node.is_end_of_word else None
+    
+    def delete(self, key: Any) -> bool:
+        """Remove a key-value pair."""
+        word = str(key)
+        return self._delete_helper(self._root, word, 0)
+    
+    def _delete_helper(self, node: TrieNode, word: str, index: int) -> bool:
+        """Helper method for deletion."""
+        if index == len(word):
+            if node.is_end_of_word:
+                node.is_end_of_word = False
+                node.value = None
+                self._size -= 1
+                return True
+            return False
+        
+        char = word[index]
+        if char not in node.children:
+            return False
+        
+        deleted = self._delete_helper(node.children[char], word, index + 1)
+        
+        # Clean up empty nodes
+        if deleted and not node.children[char].children and not node.children[char].is_end_of_word:
+            del node.children[char]
+        
+        return deleted
+    
+    def size(self) -> int:
+        """Get the number of items."""
+        return self._size
+    
+    def is_empty(self) -> bool:
+        """Check if the structure is empty."""
+        return self._size == 0
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert to native Python dictionary."""
+        result = {}
+        self._collect_words(self._root, "", result)
+        return result
+    
+    def _collect_words(self, node: TrieNode, prefix: str, result: Dict[str, Any]) -> None:
+        """Collect all words from trie."""
+        if node.is_end_of_word:
+            result[prefix] = node.value
+        
+        for char, child in node.children.items():
+            self._collect_words(child, prefix + char, result)
+    
+    # ============================================================================
+    # TREE STRATEGY METHODS
+    # ============================================================================
+    
+    def traverse(self, order: str = 'inorder') -> List[Any]:
+        """Traverse tree in specified order."""
+        result = []
+        self._collect_words(self._root, "", result)
+        return list(result.values())
+    
+    def get_min(self) -> Any:
+        """Get minimum key."""
+        # Find leftmost word
+        node = self._root
+        word = ""
+        while node.children:
+            char = min(node.children.keys())
+            word += char
+            node = node.children[char]
+        return word if node.is_end_of_word else None
+    
+    def get_max(self) -> Any:
+        """Get maximum key."""
+        # Find rightmost word
+        node = self._root
+        word = ""
+        while node.children:
+            char = max(node.children.keys())
+            word += char
+            node = node.children[char]
+        return word if node.is_end_of_word else None
+    
+    # ============================================================================
+    # AUTO-3 Phase 2 methods
+    # ============================================================================
+    
+    def as_trie(self):
+        """Provide Trie behavioral view."""
+        return self
+    
+    def as_heap(self):
+        """Provide Heap behavioral view."""
+        # TODO: Implement Heap view
+        return self
+    
+    def as_skip_list(self):
+        """Provide SkipList behavioral view."""
+        # TODO: Implement SkipList view
+        return self
+    
+    # ============================================================================
+    # TRIE SPECIFIC OPERATIONS
+    # ============================================================================
+    
+    def prefix_search(self, prefix: str) -> List[str]:
+        """Find all keys with given prefix."""
+        node = self._root
+        
+        # Navigate to prefix
+        for char in prefix:
+            if char not in node.children:
+                return []
+            node = node.children[char]
+        
+        # Collect all words with this prefix
+        result = []
+        self._collect_words(node, prefix, result)
+        return list(result.keys())
+    
+    def longest_common_prefix(self) -> str:
+        """Find longest common prefix of all keys."""
+        if not self._root.children:
+            return ""
+        
+        prefix = ""
+        node = self._root
+        
+        while len(node.children) == 1 and not node.is_end_of_word:
+            char = list(node.children.keys())[0]
+            prefix += char
+            node = node.children[char]
+        
+        return prefix
+    
+    def keys_with_prefix(self, prefix: str) -> List[str]:
+        """Get all keys with given prefix."""
+        return self.prefix_search(prefix)
+    
+    def keys_with_suffix(self, suffix: str) -> List[str]:
+        """Get all keys with given suffix."""
+        # TODO: Implement suffix search
+        return []
+    
+    # ============================================================================
+    # ITERATION
+    # ============================================================================
+    
+    def keys(self) -> Iterator[str]:
+        """Get all keys."""
+        result = {}
+        self._collect_words(self._root, "", result)
+        return iter(result.keys())
+    
+    def values(self) -> Iterator[Any]:
+        """Get all values."""
+        result = {}
+        self._collect_words(self._root, "", result)
+        return iter(result.values())
+    
+    def items(self) -> Iterator[tuple[str, Any]]:
+        """Get all key-value pairs."""
+        result = {}
+        self._collect_words(self._root, "", result)
+        return iter(result.items())
+    
+    # ============================================================================
+    # PERFORMANCE CHARACTERISTICS
+    # ============================================================================
+    
+    @property
+    def backend_info(self) -> Dict[str, Any]:
+        """Get backend implementation info."""
+        return {
+            'strategy': 'TRIE',
+            'backend': 'Trie tree',
+            'complexity': {
+                'insert': 'O(m)',
+                'search': 'O(m)',
+                'delete': 'O(m)',
+                'prefix_search': 'O(m + k)',
+                'space': 'O(ALPHABET_SIZE * N * M)'
+            }
+        }
+    
+    @property
+    def metrics(self) -> Dict[str, Any]:
+        """Get performance metrics."""
+        return {
+            'size': self._size,
+            'memory_usage': f"{self._size * 32} bytes (estimated)",
+            'height': self._get_height()
+        }
+    
+    def _get_height(self) -> int:
+        """Get height of trie."""
+        return self._height_helper(self._root)
+    
+    def _height_helper(self, node: TrieNode) -> int:
+        """Helper for height calculation."""
+        if not node.children:
+            return 0
+        return 1 + max(self._height_helper(child) for child in node.children.values())

exonware/xwnode/strategies/nodes/union_find.py

@@ -0,0 +1,283 @@
+"""
+Union-Find Node Strategy Implementation
+
+This module implements the UNION_FIND strategy for efficient set operations.
+"""
+
+from typing import Any, Iterator, Dict, List, Set
+from .base import ANodeGraphStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class UnionFind:
+    """Union-Find data structure."""
+    
+    def __init__(self):
+        self.parent: Dict[str, str] = {}
+        self.rank: Dict[str, int] = {}
+        self.values: Dict[str, Any] = {}
+    
+    def make_set(self, x: str, value: Any = None) -> None:
+        """Make a new set containing x."""
+        if x not in self.parent:
+            self.parent[x] = x
+            self.rank[x] = 0
+            self.values[x] = value
+    
+    def find(self, x: str) -> str:
+        """Find the root of the set containing x."""
+        if x not in self.parent:
+            return x
+        
+        if self.parent[x] != x:
+            self.parent[x] = self.find(self.parent[x])  # Path compression
+        return self.parent[x]
+    
+    def union(self, x: str, y: str) -> bool:
+        """Union the sets containing x and y."""
+        root_x = self.find(x)
+        root_y = self.find(y)
+        
+        if root_x == root_y:
+            return False  # Already in same set
+        
+        # Union by rank
+        if self.rank[root_x] < self.rank[root_y]:
+            self.parent[root_x] = root_y
+        elif self.rank[root_x] > self.rank[root_y]:
+            self.parent[root_y] = root_x
+        else:
+            self.parent[root_y] = root_x
+            self.rank[root_x] += 1
+        
+        return True
+    
+    def connected(self, x: str, y: str) -> bool:
+        """Check if x and y are in the same set."""
+        return self.find(x) == self.find(y)
+    
+    def get_set_members(self, x: str) -> Set[str]:
+        """Get all members of the set containing x."""
+        root = self.find(x)
+        return {member for member in self.parent.keys() if self.find(member) == root}
+    
+    def get_all_sets(self) -> List[Set[str]]:
+        """Get all disjoint sets."""
+        roots = set(self.find(x) for x in self.parent.keys())
+        return [self.get_set_members(root) for root in roots]
+    
+    def get_set_count(self) -> int:
+        """Get the number of disjoint sets."""
+        roots = set(self.find(x) for x in self.parent.keys())
+        return len(roots)
+    
+    def get_set_size(self, x: str) -> int:
+        """Get the size of the set containing x."""
+        return len(self.get_set_members(x))
+
+
+class xUnionFindStrategy(ANodeGraphStrategy):
+    """
+    Union-Find node strategy for efficient set operations.
+    
+    Optimized for union, find, and connected operations on disjoint sets.
+    """
+    
+    def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
+        """Initialize the union-find strategy."""
+        super().__init__(data=None, **options)
+        self._mode = NodeMode.UNION_FIND
+        self._traits = traits
+        self._union_find = UnionFind()
+        self._size = 0
+    
+    def get_supported_traits(self) -> NodeTrait:
+        """Get the traits supported by the union-find strategy."""
+        return (NodeTrait.SET_OPERATIONS | NodeTrait.HIERARCHICAL)
+    
+    # ============================================================================
+    # CORE OPERATIONS
+    # ============================================================================
+    
+    def insert(self, key: Any, value: Any) -> None:
+        """Store a key-value pair (creates a new set)."""
+        str_key = str(key)
+        if str_key not in self._union_find.parent:
+            self._size += 1
+        self._union_find.make_set(str_key, value)
+    
+    def find(self, key: Any) -> Any:
+        """Find the root of the set containing key."""
+        str_key = str(key)
+        root = self._union_find.find(str_key)
+        return self._union_find.values.get(root)
+    
+    def delete(self, key: Any) -> bool:
+        """Delete a key (not supported in union-find)."""
+        # Union-Find doesn't support deletion efficiently
+        return False
+    
+    def size(self) -> int:
+        """Get the number of elements."""
+        return self._size
+    
+    def is_empty(self) -> bool:
+        """Check if the structure is empty."""
+        return self._size == 0
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert to native Python dictionary."""
+        return self._union_find.values.copy()
+    
+    # ============================================================================
+    # GRAPH STRATEGY METHODS
+    # ============================================================================
+    
+    def add_edge(self, from_node: Any, to_node: Any, weight: float = 1.0) -> None:
+        """Add edge between nodes (union operation)."""
+        str_from = str(from_node)
+        str_to = str(to_node)
+        
+        # Make sure both nodes exist
+        if str_from not in self._union_find.parent:
+            self._union_find.make_set(str_from)
+            self._size += 1
+        if str_to not in self._union_find.parent:
+            self._union_find.make_set(str_to)
+            self._size += 1
+        
+        # Union the sets
+        self._union_find.union(str_from, str_to)
+    
+    def remove_edge(self, from_node: Any, to_node: Any) -> bool:
+        """Remove edge between nodes (not supported in union-find)."""
+        # Union-Find doesn't support edge removal efficiently
+        return False
+    
+    def has_edge(self, from_node: Any, to_node: Any) -> bool:
+        """Check if edge exists (connected operation)."""
+        str_from = str(from_node)
+        str_to = str(to_node)
+        
+        if str_from not in self._union_find.parent or str_to not in self._union_find.parent:
+            return False
+        
+        return self._union_find.connected(str_from, str_to)
+    
+    def find_path(self, start: Any, end: Any) -> List[Any]:
+        """Find path between nodes."""
+        if self.has_edge(start, end):
+            return [start, end]
+        return []
+    
+    def get_neighbors(self, node: Any) -> List[Any]:
+        """Get neighboring nodes (all nodes in same set)."""
+        str_node = str(node)
+        if str_node not in self._union_find.parent:
+            return []
+        
+        members = self._union_find.get_set_members(str_node)
+        return [member for member in members if member != str_node]
+    
+    def get_edge_weight(self, from_node: Any, to_node: Any) -> float:
+        """Get edge weight (always 1.0 for union-find)."""
+        return 1.0 if self.has_edge(from_node, to_node) else 0.0
+    
+    # ============================================================================
+    # AUTO-3 Phase 3&4 methods
+    # ============================================================================
+    
+    def as_union_find(self):
+        """Provide Union-Find behavioral view."""
+        return self
+    
+    def as_neural_graph(self):
+        """Provide Neural Graph behavioral view."""
+        # TODO: Implement Neural Graph view
+        return self
+    
+    def as_flow_network(self):
+        """Provide Flow Network behavioral view."""
+        # TODO: Implement Flow Network view
+        return self
+    
+    # ============================================================================
+    # UNION-FIND SPECIFIC OPERATIONS
+    # ============================================================================
+    
+    def make_set(self, element: str, value: Any = None) -> None:
+        """Make a new set containing element."""
+        if element not in self._union_find.parent:
+            self._size += 1
+        self._union_find.make_set(element, value)
+    
+    def find_root(self, element: str) -> str:
+        """Find the root of the set containing element."""
+        return self._union_find.find(element)
+    
+    def union_sets(self, element1: str, element2: str) -> bool:
+        """Union the sets containing element1 and element2."""
+        return self._union_find.union(element1, element2)
+    
+    def connected(self, element1: str, element2: str) -> bool:
+        """Check if element1 and element2 are in the same set."""
+        return self._union_find.connected(element1, element2)
+    
+    def get_set_members(self, element: str) -> Set[str]:
+        """Get all members of the set containing element."""
+        return self._union_find.get_set_members(element)
+    
+    def get_all_sets(self) -> List[Set[str]]:
+        """Get all disjoint sets."""
+        return self._union_find.get_all_sets()
+    
+    def get_set_count(self) -> int:
+        """Get the number of disjoint sets."""
+        return self._union_find.get_set_count()
+    
+    def get_set_size(self, element: str) -> int:
+        """Get the size of the set containing element."""
+        return self._union_find.get_set_size(element)
+    
+    # ============================================================================
+    # ITERATION
+    # ============================================================================
+    
+    def keys(self) -> Iterator[str]:
+        """Get all elements."""
+        return iter(self._union_find.parent.keys())
+    
+    def values(self) -> Iterator[Any]:
+        """Get all values."""
+        return iter(self._union_find.values.values())
+    
+    def items(self) -> Iterator[tuple[str, Any]]:
+        """Get all element-value pairs."""
+        return iter(self._union_find.values.items())
+    
+    # ============================================================================
+    # PERFORMANCE CHARACTERISTICS
+    # ============================================================================
+    
+    @property
+    def backend_info(self) -> Dict[str, Any]:
+        """Get backend implementation info."""
+        return {
+            'strategy': 'UNION_FIND',
+            'backend': 'Union-Find with path compression',
+            'complexity': {
+                'make_set': 'O(1)',
+                'find': 'O(α(n))',
+                'union': 'O(α(n))',
+                'connected': 'O(α(n))'
+            }
+        }
+    
+    @property
+    def metrics(self) -> Dict[str, Any]:
+        """Get performance metrics."""
+        return {
+            'elements': self._size,
+            'sets': self._union_find.get_set_count(),
+            'memory_usage': f"{self._size * 32} bytes (estimated)"
+        }