add running

README.md

@@ -172,6 +172,21 @@ zeros: Stream[int] = (
 assert list(zeros) == [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
 ```
 
+### "running map"
+
+> {TODO: add description}
+
+```python
+from streamable import running
+
+cumulative_sum: Stream[int] = (
+    integers
+    .map(running(lambda cumsum, i: cumsum + i, initial=0))
+)
+
+assert list(cumulative_sum) == [0, 1, 3, 6, 10, 15, 21, 28, 36, 45]
+```
+
 
 
 ## `.foreach`

streamable/__init__.py

@@ -1,2 +1,2 @@
 from streamable.stream import Stream
-from streamable.util.functiontools import star
+from streamable.util.functiontools import running, star

streamable/util/functiontools.py

@@ -114,3 +114,17 @@ def add(a: int, b: int) -> int:
     ```
     """
     return _Star(func)
+
+
+def running(func: Callable[[R, T], R], initial: R) -> Callable[[T], R]:
+    """
+    TODO
+    """
+    acc = initial
+
+    def _(elem: T) -> R:
+        nonlocal acc
+        acc = func(acc, elem)
+        return acc
+
+    return _

tests/test_readme.py

@@ -90,6 +90,16 @@ def test_starmap_example(self) -> None:
 
         assert list(zeros) == [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
 
+    def test_running_map_example(self) -> None:
+        from streamable import running
+
+        cumulative_sum: Stream[int] = (
+            integers
+            .map(running(lambda cumsum, i: cumsum + i, initial=0))
+        )
+
+        assert list(cumulative_sum) == [0, 1, 3, 6, 10, 15, 21, 28, 36, 45]
+
     def test_foreach_example(self) -> None:
         state: List[int] = []
         appending_integers: Stream[int] = integers.foreach(state.append)