Change `iterator.flatten`'s type

3 files changed, 36 insertions, 9 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0913196..c4bf4d7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,8 @@
 
 - `list.flatten` is no longer deprecated and is kept as a synonym of
   `list.concat`
-- `flatten` has been renamed to `concat` in the `iterator` module. The old name
-  is still available as an alias and is deprecated.
+- The `iterator` module gains the `concat` function.
+- The type of `iterator.flatten` was changed to accept a list of iterators.
 
 ## v0.30.2 - 2023-08-31
 
diff --git a/src/gleam/iterator.gleam b/src/gleam/iterator.gleam
index db57fea..f4421a3 100644
--- a/src/gleam/iterator.gleam
+++ b/src/gleam/iterator.gleam
@@ -421,7 +421,7 @@ fn do_concat(flattened: fn() -> Action(Iterator(a))) -> Action(a) {
   }
 }
 
-/// Flattens an iterator of iterators, creating a new iterator.
+/// Joins an iterator of iterators into a single iterator.
 ///
 /// This function does not evaluate the elements of the iterator, the
 /// computation is performed when the iterator is later run.
@@ -442,11 +442,23 @@ pub fn concat(iterator: Iterator(Iterator(a))) -> Iterator(a) {
   |> Iterator
 }
 
-// TODO: Add deprecation attribute and then remove later.
-/// This function is deprecated, see `concat` instead.
-pub fn flatten(iterator: Iterator(Iterator(a))) -> Iterator(a) {
-  fn() { do_concat(iterator.continuation) }
-  |> Iterator
+/// Joins a list of iterators into a single iterator.
+///
+/// This function does not evaluate the elements of the iterator, the
+/// computation is performed when the iterator is later run.
+///
+/// ## Examples
+///
+/// ```gleam
+/// > [[1, 2], [3, 4]]
+/// > |> map(from_list)
+/// > |> flatten
+/// > |> to_list
+/// [1, 2, 3, 4]
+/// ```
+///
+pub fn flatten(iterators: List(Iterator(a))) -> Iterator(a) {
+  concat(from_list(iterators))
 }
 
 /// Creates an iterator from an existing iterator and a transformation function.
diff --git a/test/gleam/iterator_test.gleam b/test/gleam/iterator_test.gleam
index 8b7e01d..5d10cb2 100644
--- a/test/gleam/iterator_test.gleam
+++ b/test/gleam/iterator_test.gleam
@@ -193,7 +193,7 @@ pub fn append_test() {
   test([1, 2], [3, 4])
 }
 
-// a |> list.map(from_list) |> concat |> to_list == list.concat(a)
+// a |> list.map(from_list) |> from_list |> concat |> to_list == list.concat(a)
 pub fn concat_test() {
   let test = fn(lists) {
     lists
@@ -209,6 +209,21 @@ pub fn concat_test() {
   test([[1, 2], [3, 4]])
 }
 
+// a |> list.map(from_list) |> flatten |> to_list == list.concat(a)
+pub fn flatten_test() {
+  let test = fn(lists) {
+    lists
+    |> list.map(iterator.from_list)
+    |> iterator.flatten
+    |> iterator.to_list
+    |> should.equal(list.concat(lists))
+  }
+
+  test([[], []])
+  test([[1], [2]])
+  test([[1, 2], [3, 4]])
+}
+
 // a |> from_list |> filter(f) |> to_list == a |> list.filter(_, f)
 pub fn filter_test() {
   let test = fn(subject, f) {