feat: add find_median_from_data_stream

Author: wislertt

.templates/leetcode/json/find_median_from_data_stream.json

@@ -0,0 +1,39 @@
+{
+    "problem_name": "find_median_from_data_stream",
+    "solution_class_name": "MedianFinder",
+    "problem_number": "295",
+    "problem_title": "Find Median from Data Stream",
+    "difficulty": "Hard",
+    "topics": "Two Pointers, Design, Sorting, Heap (Priority Queue), Data Stream",
+    "tags": ["grind-75"],
+    "readme_description": "The **median** is the middle value in an ordered integer list. If the size of the list is even, there is no middle value, and the median is the mean of the two middle values.\n\n- For example, for `arr = [2,3,4]`, the median is `3`.\n- For example, for `arr = [2,3]`, the median is `(2 + 3) / 2 = 2.5`.\n\nImplement the MedianFinder class:\n\n- `MedianFinder()` initializes the `MedianFinder` object.\n- `void addNum(int num)` adds the integer `num` from the data stream to the data structure.\n- `double findMedian()` returns the median of all elements so far. Answers within `10^-5` of the actual answer will be accepted.",
+    "readme_examples": [
+        {
+            "content": "```\nInput\n[\"MedianFinder\", \"addNum\", \"addNum\", \"findMedian\", \"addNum\", \"findMedian\"]\n[[], [1], [2], [], [3], []]\nOutput\n[null, null, null, 1.5, null, 2.0]\n```\n\n**Explanation:**\n```\nMedianFinder medianFinder = new MedianFinder();\nmedianFinder.addNum(1);    // arr = [1]\nmedianFinder.addNum(2);    // arr = [1, 2]\nmedianFinder.findMedian(); // return 1.5 (i.e., (1 + 2) / 2)\nmedianFinder.addNum(3);    // arr = [1, 2, 3]\nmedianFinder.findMedian(); // return 2.0\n```"
+        }
+    ],
+    "readme_constraints": "- `-10^5 <= num <= 10^5`\n- There will be at least one element in the data structure before calling `findMedian`.\n- At most `5 * 10^4` calls will be made to `addNum` and `findMedian`.",
+    "readme_additional": "**Follow up:**\n\n- If all integer numbers from the stream are in the range `[0, 100]`, how would you optimize your solution?\n- If `99%` of all integer numbers from the stream are in the range `[0, 100]`, how would you optimize your solution?",
+    "solution_imports": "",
+    "solution_methods": [
+        { "name": "__init__", "parameters": "", "return_type": "None", "dummy_return": "" },
+        { "name": "add_num", "parameters": "num: int", "return_type": "None", "dummy_return": "" },
+        { "name": "find_median", "parameters": "", "return_type": "float", "dummy_return": "0.0" }
+    ],
+    "test_imports": "import pytest\nfrom leetcode_py.test_utils import logged_test\nfrom .solution import MedianFinder",
+    "test_class_name": "FindMedianFromDataStream",
+    "test_helper_methods": [],
+    "test_methods": [
+        {
+            "name": "test_median_finder",
+            "parametrize": "operations, inputs, expected",
+            "parametrize_typed": "operations: list[str], inputs: list[list[int]], expected: list[float | None]",
+            "test_cases": "[([\"MedianFinder\", \"addNum\", \"addNum\", \"findMedian\", \"addNum\", \"findMedian\"], [[], [1], [2], [], [3], []], [None, None, None, 1.5, None, 2.0])]",
+            "body": "mf: MedianFinder | None = None\nresults: list[float | None] = []\nfor i, op in enumerate(operations):\n    if op == \"MedianFinder\":\n        mf = MedianFinder()\n        results.append(None)\n    elif op == \"addNum\" and mf is not None:\n        mf.add_num(inputs[i][0])\n        results.append(None)\n    elif op == \"findMedian\" and mf is not None:\n        results.append(mf.find_median())\nassert results == expected"
+        }
+    ],
+    "playground_imports": "from solution import MedianFinder",
+    "playground_test_case": "# Example test case\noperations = ['MedianFinder', 'addNum', 'addNum', 'findMedian', 'addNum', 'findMedian']\ninputs = [[], [1], [2], [], [3], []]\nexpected = [None, None, None, 1.5, None, 2.0]",
+    "playground_execution": "mf = None\nresults: list[float | None] = []\nfor i, op in enumerate(operations):\n    if op == 'MedianFinder':\n        mf = MedianFinder()\n        results.append(None)\n    elif op == 'addNum' and mf is not None:\n        mf.add_num(inputs[i][0])\n        results.append(None)\n    elif op == 'findMedian' and mf is not None:\n        results.append(mf.find_median())\nresults",
+    "playground_assertion": "assert results == expected"
+}

Makefile

@@ -1,5 +1,5 @@
 PYTHON_VERSION = 3.13
-PROBLEM ?= serialize_and_deserialize_binary_tree
+PROBLEM ?= find_median_from_data_stream
 FORCE ?= 0
 COMMA := ,
 

leetcode/find_median_from_data_stream/README.md

@@ -0,0 +1,54 @@
+# Find Median from Data Stream
+
+**Difficulty:** Hard
+**Topics:** Two Pointers, Design, Sorting, Heap (Priority Queue), Data Stream
+**Tags:** grind-75
+
+**LeetCode:** [Problem 295](https://leetcode.com/problems/find-median-from-data-stream/description/)
+
+## Problem Description
+
+The **median** is the middle value in an ordered integer list. If the size of the list is even, there is no middle value, and the median is the mean of the two middle values.
+
+- For example, for `arr = [2,3,4]`, the median is `3`.
+- For example, for `arr = [2,3]`, the median is `(2 + 3) / 2 = 2.5`.
+
+Implement the MedianFinder class:
+
+- `MedianFinder()` initializes the `MedianFinder` object.
+- `void addNum(int num)` adds the integer `num` from the data stream to the data structure.
+- `double findMedian()` returns the median of all elements so far. Answers within `10^-5` of the actual answer will be accepted.
+
+## Examples
+
+### Example 1:
+
+```
+Input
+["MedianFinder", "addNum", "addNum", "findMedian", "addNum", "findMedian"]
+[[], [1], [2], [], [3], []]
+Output
+[null, null, null, 1.5, null, 2.0]
+```
+
+**Explanation:**
+
+```
+MedianFinder medianFinder = new MedianFinder();
+medianFinder.addNum(1);    // arr = [1]
+medianFinder.addNum(2);    // arr = [1, 2]
+medianFinder.findMedian(); // return 1.5 (i.e., (1 + 2) / 2)
+medianFinder.addNum(3);    // arr = [1, 2, 3]
+medianFinder.findMedian(); // return 2.0
+```
+
+## Constraints
+
+- `-10^5 <= num <= 10^5`
+- There will be at least one element in the data structure before calling `findMedian`.
+- At most `5 * 10^4` calls will be made to `addNum` and `findMedian`.
+
+**Follow up:**
+
+- If all integer numbers from the stream are in the range `[0, 100]`, how would you optimize your solution?
+- If `99%` of all integer numbers from the stream are in the range `[0, 100]`, how would you optimize your solution?

leetcode/find_median_from_data_stream/__init__.py

@@ -0,0 +1,79 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "imports",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from solution import MedianFinder"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "setup",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example test case\n",
+    "operations = [\"MedianFinder\", \"addNum\", \"addNum\", \"findMedian\", \"addNum\", \"findMedian\"]\n",
+    "inputs = [[], [1], [2], [], [3], []]\n",
+    "expected = [None, None, None, 1.5, None, 2.0]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "execute",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mf = None\n",
+    "results: list[float | None] = []\n",
+    "for i, op in enumerate(operations):\n",
+    "    if op == \"MedianFinder\":\n",
+    "        mf = MedianFinder()\n",
+    "        results.append(None)\n",
+    "    elif op == \"addNum\" and mf is not None:\n",
+    "        mf.add_num(inputs[i][0])\n",
+    "        results.append(None)\n",
+    "    elif op == \"findMedian\" and mf is not None:\n",
+    "        results.append(mf.find_median())\n",
+    "results"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "test",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "assert results == expected"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "leetcode-py-py3.13",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python3",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

leetcode/find_median_from_data_stream/playground.ipynb

@@ -0,0 +1,115 @@
+import heapq
+
+
+class MedianFinder:
+    # Two balanced heaps approach for general streaming median
+    # Time: O(1) init
+    # Space: O(n)
+    def __init__(self) -> None:
+        self.small: list[int] = []  # max heap (negated)
+        self.large: list[int] = []  # min heap
+
+    # Time: O(log n)
+    # Space: O(1)
+    def add_num(self, num: int) -> None:
+        heapq.heappush(self.small, -num)
+
+        if self.small and self.large and (-self.small[0] > self.large[0]):
+            heapq.heappush(self.large, -heapq.heappop(self.small))
+
+        if len(self.small) > len(self.large) + 1:
+            heapq.heappush(self.large, -heapq.heappop(self.small))
+        if len(self.large) > len(self.small) + 1:
+            heapq.heappush(self.small, -heapq.heappop(self.large))
+
+    # Time: O(1)
+    # Space: O(1)
+    def find_median(self) -> float:
+        if len(self.small) > len(self.large):
+            return -self.small[0]
+        if len(self.large) > len(self.small):
+            return self.large[0]
+        return (-self.small[0] + self.large[0]) / 2.0
+
+
+class MedianFinderHybrid:
+    # Hybrid counting array + heaps for bounded ranges with outliers
+    # Time: O(1) init
+    # Space: O(R + k) where R = range_size, k = outliers
+    def __init__(self, min_val: int = 0, max_val: int = 100) -> None:
+        self.min_val = min_val
+        self.max_val = max_val
+        self.counts = [0] * (max_val - min_val + 1)
+        self.outliers_small: list[int] = []  # max heap for < min_val
+        self.outliers_large: list[int] = []  # min heap for > max_val
+        self.total = 0
+
+    # Time: O(1) for range, O(log k) for outliers
+    # Space: O(1)
+    def add_num(self, num: int) -> None:
+        if self.min_val <= num <= self.max_val:
+            self.counts[num - self.min_val] += 1
+        elif num < self.min_val:
+            heapq.heappush(self.outliers_small, -num)
+        else:
+            heapq.heappush(self.outliers_large, num)
+        self.total += 1
+
+    # Time: O(R + k log k) worst case, O(R) typical, O(1) if R constant
+    # Space: O(k) for sorting outliers
+    def find_median(self) -> float:
+        target = self.total // 2
+        count = 0
+
+        # Count outliers < 0
+        outliers_small_count = len(self.outliers_small)
+        if count + outliers_small_count > target:
+            sorted_small = sorted([-x for x in self.outliers_small])
+            if self.total % 2 == 1:
+                return sorted_small[target - count]
+            else:
+                if target - count == 0:
+                    return (sorted_small[0] + self._get_next_value(0)) / 2.0
+                return (sorted_small[target - count - 1] + sorted_small[target - count]) / 2.0
+        count += outliers_small_count
+
+        # Count [min_val, max_val] range
+        for i in range(len(self.counts)):
+            if count + self.counts[i] > target:
+                val = i + self.min_val
+                if self.total % 2 == 1:
+                    return val
+                else:
+                    if target == count:
+                        return (self._get_prev_value(count - 1) + val) / 2.0
+                    return val
+            count += self.counts[i]
+
+        # Must be in outliers > 100
+        sorted_large = sorted(self.outliers_large)
+        idx = target - count
+        if self.total % 2 == 1:
+            return sorted_large[idx]
+        else:
+            if idx == 0:
+                return (self._get_prev_value(count - 1) + sorted_large[0]) / 2.0
+            return (sorted_large[idx - 1] + sorted_large[idx]) / 2.0
+
+    def _get_prev_value(self, pos: int) -> int:
+        count = 0
+        # Check outliers < 0
+        if pos < len(self.outliers_small):
+            return sorted([-x for x in self.outliers_small])[pos]
+        count += len(self.outliers_small)
+
+        # Check [min_val, max_val] range
+        for i in range(len(self.counts)):
+            if count + self.counts[i] > pos:
+                return i + self.min_val
+            count += self.counts[i]
+
+        # Must be in outliers > 100
+        return sorted(self.outliers_large)[pos - count]
+
+    def _get_next_value(self, pos: int) -> int:
+        return self._get_prev_value(pos + 1)

leetcode/find_median_from_data_stream/solution.py

@@ -0,0 +1,71 @@
+import pytest
+
+from leetcode_py.test_utils import logged_test
+
+from .solution import MedianFinder, MedianFinderHybrid
+
+
+class TestFindMedianFromDataStream:
+    @pytest.mark.parametrize(
+        "finder_class, operations, inputs, expected",
+        [
+            (
+                MedianFinder,
+                ["MedianFinder", "addNum", "addNum", "findMedian", "addNum", "findMedian"],
+                [[], [1], [2], [], [3], []],
+                [None, None, None, 1.5, None, 2.0],
+            ),
+            (
+                MedianFinderHybrid,
+                ["MedianFinder", "addNum", "addNum", "findMedian", "addNum", "findMedian"],
+                [[], [1], [2], [], [3], []],
+                [None, None, None, 1.5, None, 2.0],
+            ),
+            (
+                MedianFinder,
+                ["MedianFinder", "addNum", "findMedian"],
+                [[], [5], []],
+                [None, None, 5.0],
+            ),
+            (
+                MedianFinderHybrid,
+                ["MedianFinder", "addNum", "findMedian"],
+                [[], [5], []],
+                [None, None, 5.0],
+            ),
+            (
+                MedianFinder,
+                ["MedianFinder", "addNum", "addNum", "addNum", "addNum", "findMedian"],
+                [[], [1], [3], [2], [4], []],
+                [None, None, None, None, None, 2.5],
+            ),
+            (
+                MedianFinderHybrid,
+                ["MedianFinder", "addNum", "addNum", "addNum", "addNum", "findMedian"],
+                [[], [1], [3], [2], [4], []],
+                [None, None, None, None, None, 2.5],
+            ),
+            (
+                MedianFinderHybrid,
+                ["MedianFinder", "addNum", "addNum", "addNum", "findMedian"],
+                [[], [-1], [50], [101], []],
+                [None, None, None, None, 50.0],
+            ),
+        ],
+    )
+    @logged_test
+    def test_median_finder(
+        self, finder_class, operations: list[str], inputs: list[list[int]], expected: list[float | None]
+    ):
+        mf = None
+        results: list[float | None] = []
+        for i, op in enumerate(operations):
+            if op == "MedianFinder":
+                mf = finder_class()
+                results.append(None)
+            elif op == "addNum" and mf is not None:
+                mf.add_num(inputs[i][0])
+                results.append(None)
+            elif op == "findMedian" and mf is not None:
+                results.append(mf.find_median())
+        assert results == expected

leetcode/find_median_from_data_stream/tests.py

@@ -5,6 +5,9 @@ def ladder_length(self, begin_word: str, end_word: str, word_list: list[str]) ->
         if end_word not in word_list:
             return 0
 
+        if begin_word == end_word:
+            return 1
+
         word_set = set(word_list)
         begin_set = {begin_word}
         end_set = {end_word}