exonware-xwnode 0.0.1.12__py3-none-any.whl

exonware/xwnode/strategies/nodes/queue.py

@@ -0,0 +1,161 @@
+"""
+Queue Strategy Implementation
+
+Implements a FIFO (First In, First Out) data structure using Python's deque.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.12
+Generation Date: 07-Sep-2025
+"""
+
+from typing import Any, Iterator, Optional, Dict, Union
+from collections import deque
+from .base import ANodeLinearStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class QueueStrategy(ANodeLinearStrategy):
+    """
+    Queue node strategy for FIFO (First In, First Out) operations.
+    
+    Provides O(1) enqueue and dequeue operations with efficient memory usage
+    for queue-based algorithms and breadth-first search.
+    """
+    
+    def __init__(self):
+        """Initialize an empty queue."""
+        super().__init__()
+        self._queue: deque = deque()
+        self._mode = NodeMode.QUEUE
+        self._traits = {NodeTrait.FIFO, NodeTrait.FAST_INSERT, NodeTrait.FAST_DELETE}
+    
+    def insert(self, key: str, value: Any) -> None:
+        """Enqueue an item into the queue."""
+        self._queue.append((key, value))
+        self._record_access("enqueue")
+    
+    def find(self, key: str) -> Optional[Any]:
+        """Find an item in the queue (O(n) operation)."""
+        for k, v in self._queue:
+            if k == key:
+                self._record_access("find")
+                return v
+        return None
+    
+    def delete(self, key: str) -> bool:
+        """Remove an item from the queue."""
+        for i, (k, v) in enumerate(self._queue):
+            if k == key:
+                del self._queue[i]
+                self._record_access("delete")
+                return True
+        return False
+    
+    def size(self) -> int:
+        """Get the number of items in the queue."""
+        return len(self._queue)
+    
+    def is_empty(self) -> bool:
+        """Check if the queue is empty."""
+        return len(self._queue) == 0
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert queue to native dictionary format."""
+        return dict(self._queue)
+    
+    def from_native(self, data: Dict[str, Any]) -> None:
+        """Load queue from native dictionary format."""
+        self._queue = deque(data.items())
+    
+    def enqueue(self, value: Any) -> None:
+        """Enqueue a value into the queue."""
+        key = f"item_{len(self._queue)}"
+        self.insert(key, value)
+    
+    def dequeue(self) -> Optional[Any]:
+        """Dequeue and return the front item from the queue."""
+        if self.is_empty():
+            return None
+        key, value = self._queue.popleft()
+        self._record_access("dequeue")
+        return value
+    
+    def front(self) -> Optional[Any]:
+        """Get the front item without removing it."""
+        if self.is_empty():
+            return None
+        key, value = self._queue[0]
+        self._record_access("front")
+        return value
+    
+    def back(self) -> Optional[Any]:
+        """Get the back item without removing it."""
+        if self.is_empty():
+            return None
+        key, value = self._queue[-1]
+        self._record_access("back")
+        return value
+    
+    def clear(self) -> None:
+        """Clear all items from the queue."""
+        self._queue.clear()
+        self._record_access("clear")
+    
+    def get_at_index(self, index: int) -> Optional[Any]:
+        """Get item at specific index (0 = front of queue)."""
+        if 0 <= index < len(self._queue):
+            key, value = self._queue[index]
+            self._record_access("get_at_index")
+            return value
+        return None
+    
+    def push_front(self, value: Any) -> None:
+        """Push to front of queue."""
+        self._queue.appendleft((f"item_{len(self._queue)}", value))
+        self._record_access("push_front")
+    
+    def push_back(self, value: Any) -> None:
+        """Push to back of queue."""
+        self.enqueue(value)
+    
+    def __iter__(self) -> Iterator[Any]:
+        """Iterate through queue items (front to back)."""
+        for key, value in self._queue:
+            yield value
+    
+    def __repr__(self) -> str:
+        """String representation of the queue."""
+        return f"QueueStrategy(size={len(self._queue)}, front={self.front()})"
+    
+    # Required abstract methods from base classes
+    def pop_front(self) -> Any:
+        """Remove element from front (same as dequeue for queue)."""
+        return self.dequeue()
+    
+    def pop_back(self) -> Any:
+        """Remove element from back (not applicable for queue)."""
+        raise NotImplementedError("Queue doesn't support pop_back")
+    
+    def set_at_index(self, index: int, value: Any) -> None:
+        """Set element at index (not recommended for queue)."""
+        if 0 <= index < len(self._queue):
+            key, old_value = self._queue[index]
+            self._queue[index] = (key, value)
+    
+    def as_linked_list(self):
+        """Provide LinkedList behavioral view."""
+        return self
+    
+    def as_stack(self):
+        """Provide Stack behavioral view (not recommended)."""
+        raise NotImplementedError("Queue cannot behave as Stack")
+    
+    def as_queue(self):
+        """Provide Queue behavioral view."""
+        return self
+    
+    def as_deque(self):
+        """Provide Deque behavioral view."""
+        return self

exonware/xwnode/strategies/nodes/sparse_matrix.py

@@ -0,0 +1,206 @@
+"""
+Sparse Matrix Strategy Implementation
+
+Implements a sparse matrix using coordinate format (COO) for memory efficiency.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.12
+Generation Date: 07-Sep-2025
+"""
+
+from typing import Any, Iterator, List, Optional, Dict, Union, Tuple
+from .base import ANodeMatrixStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class SparseMatrixStrategy(ANodeMatrixStrategy):
+    """
+    Sparse Matrix node strategy for memory-efficient matrix operations.
+    
+    Uses coordinate format (COO) to store only non-zero elements,
+    providing excellent memory efficiency for sparse matrices.
+    """
+    
+    def __init__(self):
+        """Initialize an empty sparse matrix."""
+        super().__init__()
+        self._data: List[Tuple[int, int, Any]] = []  # (row, col, value)
+        self._rows = 0
+        self._cols = 0
+        self._mode = NodeMode.SPARSE_MATRIX
+        self._traits = {NodeTrait.SPARSE, NodeTrait.MEMORY_EFFICIENT, NodeTrait.MATRIX_OPS}
+    
+    def insert(self, key: str, value: Any) -> None:
+        """Insert a value using key as coordinate (e.g., '1,2' for row 1, col 2)."""
+        try:
+            row, col = map(int, key.split(','))
+            self.set_at_position(row, col, value)
+        except ValueError:
+            raise ValueError(f"Key must be in format 'row,col', got: {key}")
+    
+    def find(self, key: str) -> Optional[Any]:
+        """Find a value using key as coordinate."""
+        try:
+            row, col = map(int, key.split(','))
+            return self.get_at_position(row, col)
+        except ValueError:
+            return None
+    
+    def delete(self, key: str) -> bool:
+        """Delete a value using key as coordinate."""
+        try:
+            row, col = map(int, key.split(','))
+            return self.set_at_position(row, col, 0) is not None
+        except ValueError:
+            return False
+    
+    def size(self) -> int:
+        """Get the number of non-zero elements."""
+        return len(self._data)
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert sparse matrix to native dictionary format."""
+        result = {}
+        for row, col, value in self._data:
+            result[f"{row},{col}"] = value
+        return result
+    
+    def from_native(self, data: Dict[str, Any]) -> None:
+        """Load sparse matrix from native dictionary format."""
+        self._data.clear()
+        for key, value in data.items():
+            try:
+                row, col = map(int, key.split(','))
+                if value != 0:  # Only store non-zero values
+                    self._data.append((row, col, value))
+                    self._rows = max(self._rows, row + 1)
+                    self._cols = max(self._cols, col + 1)
+            except ValueError:
+                continue
+    
+    def get_dimensions(self) -> Tuple[int, int]:
+        """Get matrix dimensions (rows, cols)."""
+        return (self._rows, self._cols)
+    
+    def get_at_position(self, row: int, col: int) -> Any:
+        """Get value at specific position."""
+        for r, c, value in self._data:
+            if r == row and c == col:
+                return value
+        return 0  # Default to 0 for sparse matrix
+    
+    def set_at_position(self, row: int, col: int, value: Any) -> None:
+        """Set value at specific position."""
+        # Remove existing entry if it exists
+        self._data = [(r, c, v) for r, c, v in self._data if not (r == row and c == col)]
+        
+        # Add new entry if value is not zero
+        if value != 0:
+            self._data.append((row, col, value))
+        
+        # Update dimensions
+        self._rows = max(self._rows, row + 1)
+        self._cols = max(self._cols, col + 1)
+    
+    def get_row(self, row: int) -> List[Any]:
+        """Get entire row as list."""
+        result = [0] * self._cols
+        for r, c, value in self._data:
+            if r == row:
+                result[c] = value
+        return result
+    
+    def get_column(self, col: int) -> List[Any]:
+        """Get entire column as list."""
+        result = [0] * self._rows
+        for r, c, value in self._data:
+            if c == col:
+                result[r] = value
+        return result
+    
+    def transpose(self) -> 'SparseMatrixStrategy':
+        """Return transposed matrix."""
+        transposed = SparseMatrixStrategy()
+        for row, col, value in self._data:
+            transposed.set_at_position(col, row, value)
+        return transposed
+    
+    def multiply(self, other: 'SparseMatrixStrategy') -> 'SparseMatrixStrategy':
+        """Multiply with another sparse matrix."""
+        result = SparseMatrixStrategy()
+        other_dict = {}
+        for r, c, v in other._data:
+            other_dict[(r, c)] = v
+        
+        for r1, c1, v1 in self._data:
+            for c2 in range(other._cols):
+                if (c1, c2) in other_dict:
+                    v2 = other_dict[(c1, c2)]
+                    current = result.get_at_position(r1, c2)
+                    result.set_at_position(r1, c2, current + v1 * v2)
+        
+        return result
+    
+    def add(self, other: 'SparseMatrixStrategy') -> 'SparseMatrixStrategy':
+        """Add another sparse matrix."""
+        result = SparseMatrixStrategy()
+        
+        # Add all elements from self
+        for r, c, v in self._data:
+            result.set_at_position(r, c, v)
+        
+        # Add all elements from other
+        for r, c, v in other._data:
+            current = result.get_at_position(r, c)
+            result.set_at_position(r, c, current + v)
+        
+        return result
+    
+    def as_adjacency_matrix(self):
+        """Convert to adjacency matrix format."""
+        return self
+    
+    def as_incidence_matrix(self):
+        """Convert to incidence matrix format."""
+        return self
+    
+    def as_sparse_matrix(self):
+        """Return self as sparse matrix."""
+        return self
+    
+    def density(self) -> float:
+        """Calculate matrix density (non-zero elements / total elements)."""
+        total_elements = self._rows * self._cols
+        if total_elements == 0:
+            return 0.0
+        return len(self._data) / total_elements
+    
+    def clear(self) -> None:
+        """Clear all elements."""
+        self._data.clear()
+        self._rows = 0
+        self._cols = 0
+    
+    def __iter__(self) -> Iterator[Tuple[int, int, Any]]:
+        """Iterate through non-zero elements."""
+        for row, col, value in self._data:
+            yield (row, col, value)
+    
+    def __repr__(self) -> str:
+        """String representation of the sparse matrix."""
+        return f"SparseMatrixStrategy({self._rows}x{self._cols}, {len(self._data)} non-zero)"
+    
+    # Required abstract methods from base classes
+    def as_adjacency_matrix(self):
+        """Provide Adjacency Matrix behavioral view."""
+        return self
+    
+    def as_incidence_matrix(self):
+        """Provide Incidence Matrix behavioral view."""
+        return self
+    
+    def as_sparse_matrix(self):
+        """Provide Sparse Matrix behavioral view."""
+        return self

exonware/xwnode/strategies/nodes/stack.py

@@ -0,0 +1,152 @@
+"""
+Stack Strategy Implementation
+
+Implements a LIFO (Last In, First Out) data structure using Python's list.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.12
+Generation Date: 07-Sep-2025
+"""
+
+from typing import Any, Iterator, List, Optional, Dict, Union
+from .base import ANodeLinearStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class StackStrategy(ANodeLinearStrategy):
+    """
+    Stack node strategy for LIFO (Last In, First Out) operations.
+    
+    Provides O(1) push and pop operations with efficient memory usage
+    for stack-based algorithms and recursive function simulation.
+    """
+    
+    def __init__(self):
+        """Initialize an empty stack."""
+        super().__init__()
+        self._stack: List[Any] = []
+        self._mode = NodeMode.STACK
+        self._traits = {NodeTrait.LIFO, NodeTrait.FAST_INSERT, NodeTrait.FAST_DELETE}
+    
+    def insert(self, key: str, value: Any) -> None:
+        """Push an item onto the stack."""
+        self._stack.append((key, value))
+        self._record_access("push")
+    
+    def find(self, key: str) -> Optional[Any]:
+        """Find an item in the stack (O(n) operation)."""
+        for k, v in reversed(self._stack):
+            if k == key:
+                self._record_access("find")
+                return v
+        return None
+    
+    def delete(self, key: str) -> bool:
+        """Remove an item from the stack."""
+        for i, (k, v) in enumerate(self._stack):
+            if k == key:
+                self._stack.pop(i)
+                self._record_access("delete")
+                return True
+        return False
+    
+    def size(self) -> int:
+        """Get the number of items in the stack."""
+        return len(self._stack)
+    
+    def is_empty(self) -> bool:
+        """Check if the stack is empty."""
+        return len(self._stack) == 0
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert stack to native dictionary format."""
+        return dict(reversed(self._stack))
+    
+    def from_native(self, data: Dict[str, Any]) -> None:
+        """Load stack from native dictionary format."""
+        self._stack = [(k, v) for k, v in data.items()]
+    
+    def push(self, value: Any) -> None:
+        """Push a value onto the stack."""
+        key = f"item_{len(self._stack)}"
+        self.insert(key, value)
+    
+    def pop(self) -> Optional[Any]:
+        """Pop and return the top item from the stack."""
+        if self.is_empty():
+            return None
+        key, value = self._stack.pop()
+        self._record_access("pop")
+        return value
+    
+    def peek(self) -> Optional[Any]:
+        """Peek at the top item without removing it."""
+        if self.is_empty():
+            return None
+        key, value = self._stack[-1]
+        self._record_access("peek")
+        return value
+    
+    def clear(self) -> None:
+        """Clear all items from the stack."""
+        self._stack.clear()
+        self._record_access("clear")
+    
+    def get_at_index(self, index: int) -> Optional[Any]:
+        """Get item at specific index (0 = top of stack)."""
+        if 0 <= index < len(self._stack):
+            key, value = self._stack[-(index + 1)]
+            self._record_access("get_at_index")
+            return value
+        return None
+    
+    def push_front(self, value: Any) -> None:
+        """Push to front (bottom) of stack."""
+        self._stack.insert(0, (f"item_{len(self._stack)}", value))
+        self._record_access("push_front")
+    
+    def push_back(self, value: Any) -> None:
+        """Push to back (top) of stack."""
+        self.push(value)
+    
+    def __iter__(self) -> Iterator[Any]:
+        """Iterate through stack items (top to bottom)."""
+        for key, value in reversed(self._stack):
+            yield value
+    
+    def __repr__(self) -> str:
+        """String representation of the stack."""
+        return f"StackStrategy(size={len(self._stack)}, top={self.peek()})"
+    
+    # Required abstract methods from base classes
+    def pop_front(self) -> Any:
+        """Remove element from front (same as pop for stack)."""
+        return self.pop()
+    
+    def pop_back(self) -> Any:
+        """Remove element from back (not applicable for stack)."""
+        raise NotImplementedError("Stack doesn't support pop_back")
+    
+    def set_at_index(self, index: int, value: Any) -> None:
+        """Set element at index (not recommended for stack)."""
+        if 0 <= index < len(self._stack):
+            key, old_value = self._stack[-(index + 1)]
+            self._stack[-(index + 1)] = (key, value)
+    
+    def as_linked_list(self):
+        """Provide LinkedList behavioral view."""
+        return self
+    
+    def as_stack(self):
+        """Provide Stack behavioral view."""
+        return self
+    
+    def as_queue(self):
+        """Provide Queue behavioral view (not recommended)."""
+        raise NotImplementedError("Stack cannot behave as Queue")
+    
+    def as_deque(self):
+        """Provide Deque behavioral view."""
+        return self