`iterator.each` (#431)

3 files changed, 33 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 29bcde5..eb6712e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- The `iterator` module gains the `each` function.
+
 ## v0.28.0 - 2023-03-26
 
 - `regex.scan` now behaves consistently across both targets when a capture group does not capture anything.
diff --git a/src/gleam/iterator.gleam b/src/gleam/iterator.gleam
index 1486ae3..65e3e29 100644
--- a/src/gleam/iterator.gleam
+++ b/src/gleam/iterator.gleam
@@ -1417,3 +1417,26 @@ pub fn length(over iterator: Iterator(e)) -> Int {
   iterator.continuation
   |> do_length(0)
 }
+
+/// Traverse an iterator, calling a function on each element.
+///
+/// ## Examples
+///
+/// ```gleam
+/// > empty() |> each(io.println)
+/// Nil
+/// ```
+///
+/// ```gleam
+/// > from_list(["Tom", "Malory", "Louis"]) |> each(io.println)
+/// // -> Tom
+/// // -> Malory
+/// // -> Louis
+/// Nil
+/// ```
+///
+pub fn each(over iterator: Iterator(a), with f: fn(a) -> b) -> Nil {
+  iterator
+  |> map(f)
+  |> run
+}
diff --git a/test/gleam/iterator_test.gleam b/test/gleam/iterator_test.gleam
index 81c790e..5348183 100644
--- a/test/gleam/iterator_test.gleam
+++ b/test/gleam/iterator_test.gleam
@@ -584,3 +584,9 @@ pub fn length_test() {
   |> iterator.length
   |> should.equal(0)
 }
+
+pub fn each_test() {
+  use it <- iterator.each(iterator.from_list([1]))
+  it
+  |> should.equal(1)
+}