Stacks: MinStack

Author: tomaslink

README.md

@@ -12,6 +12,7 @@
 
 [Arrays and Strings]: docs/arrays-and-strings.md
 [Linked Lists]: docs/linked-lists.md
+[Stacks and Queues]: docs/stacks-and-queues.md
 
 Collection of pure python algorithm implementations to solve computational problems.
 
@@ -24,6 +25,7 @@ The goal is for these implementations to be:
 ## List of problems
    - [Arrays and Strings]
    - [Linked Lists]
+   - [Stacks and Queues]
 
 **References**:
 - The book [Cracking the Coding Interview, 6th Edition].

docs/stacks-and-queues.md

@@ -0,0 +1,7 @@
+<h1 align="center" style="border-bottom: none;"> Stacks and Queues </h1>
+
+[Stack Min]: ../src/algorithmic/stacks.py#L70
+
+1. **[Stack Min]**: How would you design a stack which, in addition to push and pop, has a function min
+which returns the minimum element? Push, pop and min should all operate in 0(1) time.
+

src/algorithmic/stacks.py

@@ -0,0 +1,100 @@
+from typing import Any
+
+
+class EmptyStackException(Exception):
+    pass
+
+
+class Node:
+    """Represents a node of a stack.
+
+    Args:
+        data: the data to save in the node.
+    """
+    def __init__(self, data: Any) -> None:
+        self.data = data
+        self.next = None
+
+    def __repr__(self) -> str:
+        return str(self.data)
+
+
+class Stack:
+    """Represents a Stack data structure."""
+
+    def __init__(self) -> None:
+        self._top = None
+
+    def pop(self) -> Any:
+        """Returns and removes the top of the stack.
+
+        Complexity:
+            - Time: O(1).
+            - Space: O(1).
+        """
+        if self.is_empty():
+            raise EmptyStackException()
+
+        data = self._top.data
+        self._top = self._top.next
+
+        return data
+
+    def peek(self) -> Any:
+        """Returns the top of the stack.
+
+        Complexity:
+            - Time: O(1).
+            - Space: O(1).
+        """
+        if self.is_empty():
+            raise EmptyStackException()
+
+        return self._top.data
+
+    def push(self, data: Any) -> None:
+        """Adds data to the top of the stack.
+
+        Complexity:
+            - Time: O(1).
+            - Space: O(1).
+        """
+        new_top = Node(data)
+        new_top.next = self._top
+        self._top = new_top
+
+    def is_empty(self) -> bool:
+        return self._top is None
+
+
+class StackMin(Stack):
+    """Implements a Stack with a min method that returns the minimum."""
+
+    def push(self, data: Any) -> None:
+        """Adds data to the top of the stack.
+
+        Complexity:
+            - Time: O(1).
+            - Space: O(1).
+        """
+        new_top = Node(data)
+        new_top.substack_min = data
+
+        if not self.is_empty():
+            if self._top.substack_min < new_top.substack_min:
+                new_top.substack_min = self._top.substack_min
+
+        new_top.next = self._top
+        self._top = new_top
+
+    def min(self) -> Any:
+        """Returns the minimum of the stack.
+
+        Complexity:
+            - Time: O(1).
+            - Space: O(1).
+        """
+        if self.is_empty():
+            raise EmptyStackException()
+
+        return self._top.substack_min

tests/test_stacks.py

@@ -0,0 +1,41 @@
+import pytest
+
+from algorithmic import stacks
+
+
+def test_stack():
+
+    assert repr(stacks.Node(3)) == '3'
+
+    stack = stacks.Stack()
+    stack.push(7)
+    stack.push(10)
+
+    assert stack.pop() == 10
+    assert stack.peek() == 7
+    assert stack.pop() == 7
+
+    with pytest.raises(stacks.EmptyStackException):
+        stack.pop()
+
+    with pytest.raises(stacks.EmptyStackException):
+        stack.peek()
+
+
+def test_stack_min():
+    stack = stacks.StackMin()
+    stack.push(7)
+    stack.push(3)
+    stack.push(5)
+
+    assert stack.min() == 3
+
+    stack.pop()
+    assert stack.min() == 3
+
+    stack.pop()
+    assert stack.min() == 7
+
+    stack.pop()
+    with pytest.raises(stacks.EmptyStackException):
+        stack.min()