Remove the deprecation notice from `list.flatten`

3 files changed, 33 insertions, 2 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3fe36be..0913196 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- `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.
+
 ## v0.30.2 - 2023-08-31
 
 - Fixed a bug where `base.decode64` could crash on the Erlang target.
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index 90ca12a..4836f92 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -680,8 +680,18 @@ pub fn concat(lists: List(List(a))) -> List(a) {
   do_concat(lists, [])
 }
 
-// TODO: Add deprecation attribute and then remove later.
-/// This function is deprecated, see `concat` instead.
+/// This is the same as `concat`: it joins a list of lists into a single
+/// list.
+/// 
+/// This function traverses all elements twice.
+/// 
+/// ## Examples
+/// 
+/// ```gleam
+/// > flatten([[1], [2, 3], []])
+/// [1, 2, 3]
+/// ```
+/// 
 pub fn flatten(lists: List(List(a))) -> List(a) {
   do_concat(lists, [])
 }
diff --git a/test/gleam/list_test.gleam b/test/gleam/list_test.gleam
index c4305f5..321f5a4 100644
--- a/test/gleam/list_test.gleam
+++ b/test/gleam/list_test.gleam
@@ -306,6 +306,20 @@ pub fn concat_test() {
   // }
 }
 
+pub fn flatten_test() {
+  list.flatten([])
+  |> should.equal([])
+
+  list.flatten([[]])
+  |> should.equal([])
+
+  list.flatten([[], [], []])
+  |> should.equal([])
+
+  list.flatten([[1, 2], [], [3, 4]])
+  |> should.equal([1, 2, 3, 4])
+}
+
 pub fn flat_map_test() {
   list.flat_map([1, 10, 20], fn(x) { [x, x + 1] })
   |> should.equal([1, 2, 10, 11, 20, 21])