Add `list.map3`

3 files changed, 51 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0b2e66b..f1b9910 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Unreleased
 
 - The `list` module gains the `list.map2` function.
+- The `list` module gains the `list.map3` function.
 
 ## v0.29.2 - 2023-06-21
 
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index b1acb74..dce703b 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -412,6 +412,33 @@ fn do_map2(
   }
 }
 
+/// Combines three lists into a single list using the given function.
+///
+/// If a list is longer than the others the extra elements are dropped.
+///
+pub fn map3(
+  list1: List(a),
+  list2: List(b),
+  list3: List(c),
+  with fun: fn(a, b, c) -> d,
+) -> List(d) {
+  do_map3(list1, list2, list3, fun, [])
+}
+
+fn do_map3(
+  list1: List(a),
+  list2: List(b),
+  list3: List(c),
+  fun: fn(a, b, c) -> d,
+  acc: List(d),
+) -> List(d) {
+  case list1, list2, list3 {
+    [], _, _ | _, [], _ | _, _, [] -> reverse(acc)
+    [a, ..as_], [b, ..bs], [c, ..cs] ->
+      do_map3(as_, bs, cs, fun, [fun(a, b, c), ..acc])
+  }
+}
+
 /// Similar to `map` but also lets you pass around an accumulated value.
 ///
 /// ## Examples
diff --git a/test/gleam/list_test.gleam b/test/gleam/list_test.gleam
index b44c53c..0e3f8a1 100644
--- a/test/gleam/list_test.gleam
+++ b/test/gleam/list_test.gleam
@@ -189,6 +189,29 @@ pub fn map2_test() {
   list.map2(list, list, int.add)
 }
 
+pub fn map3_test() {
+  let add3 = fn(x, y, z) { x + y + z }
+
+  list.map3([], [1, 2, 3], [4, 5, 6], add3)
+  |> should.equal([])
+
+  list.map3([1, 2, 3], [], [4, 5, 6], add3)
+  |> should.equal([])
+
+  list.map3([1, 2, 3], [4, 5, 6], [], add3)
+  |> should.equal([])
+
+  list.map3([1, 2, 3], [4, 5], [6], add3)
+  |> should.equal([11])
+
+  list.map3([1, 2, 3], [4, 5, 6], [7, 8, 9], add3)
+  |> should.equal([12, 15, 18])
+
+  // TCO test
+  let list = list.repeat(0, recursion_test_cycles)
+  list.map3(list, list, list, add3)
+}
+
 pub fn map_fold_test() {
   [1, 2, 3, 4]
   |> list.map_fold(from: 0, with: fn(acc, i) { #(acc + i, i * 2) })