refactor(vim.iter)!: remove vim.iter.map/filter/totable #26138

Problem:
The use-case for the convenience functions vim.iter.map(),
vim.iter.filter(), vim.iter.totable() is not clear.

Solution:
Drop them for now. We can revisit after 0.10 release.

3 files changed, 2 insertions, 103 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index fdc50082d3..dc1a4bb35d 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -3871,27 +3871,6 @@ Examples: >lua
     -- { "a", "b" }
 <
 
-In addition to the |vim.iter()| function, the |vim.iter| module provides
-convenience functions like |vim.iter.filter()| and |vim.iter.totable()|.
-
-
-filter({f}, {src})                                         *vim.iter.filter()*
-    Filters a table or other |iterable|. >lua
-        -- Equivalent to:
-        vim.iter(src):filter(f):totable()
-<
-
-    Parameters: ~
-      • {f}    (`fun(...):boolean`) Filter function. Accepts the current
-               iterator or table values as arguments and returns true if those
-               values should be kept in the final table
-      • {src}  (`table|function`) Table or iterator function to filter
-
-    Return: ~
-        (`table`)
-
-    See also: ~
-      • |Iter:filter()|
 
 Iter:all({pred})                                                  *Iter:all()*
     Returns true if all items in the iterator match the given predicate.
@@ -4319,36 +4298,6 @@ Iter:totable()                                                *Iter:totable()*
     Return: ~
         (`table`)
 
-map({f}, {src})                                               *vim.iter.map()*
-    Maps a table or other |iterable|. >lua
-        -- Equivalent to:
-        vim.iter(src):map(f):totable()
-<
-
-    Parameters: ~
-      • {f}    (`fun(...): any?`) Map function. Accepts the current iterator
-               or table values as arguments and returns one or more new
-               values. Nil values are removed from the final table.
-      • {src}  (`table|function`) Table or iterator function to filter
-
-    Return: ~
-        (`table`)
-
-    See also: ~
-      • |Iter:map()|
-
-totable({f})                                              *vim.iter.totable()*
-    Collects an |iterable| into a table. >lua
-        -- Equivalent to:
-        vim.iter(f):totable()
-<
-
-    Parameters: ~
-      • {f}  (`function`) Iterator function
-
-    Return: ~
-        (`table`)
-
 
 ==============================================================================
 Lua module: vim.snippet                                          *vim.snippet*
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index e580d5a2b7..29b728b013 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -153,6 +153,8 @@ unreleased features on Nvim HEAD.
 
 • Changed the signature of `vim.diagnostic.enable()`.
 
+• Removed vim.iter.map(), vim.iter.filter(), vim.iter.totable().
+
 ==============================================================================
 NEW FEATURES                                                    *news-features*
 
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 2f2c21aee8..302463b136 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -60,9 +60,6 @@
 --- vim.iter(rb):totable()
 --- -- { "a", "b" }
 --- ```
----
---- In addition to the |vim.iter()| function, the |vim.iter| module provides
---- convenience functions like |vim.iter.filter()| and |vim.iter.totable()|.
 
 --- LuaLS is bad at generics which this module mostly deals with
 --- @diagnostic disable:no-unknown
@@ -1092,55 +1089,6 @@ function ListIter.new(t)
   return it
 end
 
---- Collects an |iterable| into a table.
----
---- ```lua
---- -- Equivalent to:
---- vim.iter(f):totable()
---- ```
----
----@param f function Iterator function
----@return table
-function M.totable(f, ...)
-  return Iter.new(f, ...):totable()
-end
-
---- Filters a table or other |iterable|.
----
---- ```lua
---- -- Equivalent to:
---- vim.iter(src):filter(f):totable()
---- ```
----
----@see |Iter:filter()|
----
----@param f fun(...):boolean Filter function. Accepts the current iterator or table values as
----                       arguments and returns true if those values should be kept in the
----                       final table
----@param src table|function Table or iterator function to filter
----@return table
-function M.filter(f, src, ...)
-  return Iter.new(src, ...):filter(f):totable()
-end
-
---- Maps a table or other |iterable|.
----
---- ```lua
---- -- Equivalent to:
---- vim.iter(src):map(f):totable()
---- ```
----
----@see |Iter:map()|
----
----@param f fun(...): any? Map function. Accepts the current iterator or table values as
----                        arguments and returns one or more new values. Nil values are removed
----                        from the final table.
----@param src table|function Table or iterator function to filter
----@return table
-function M.map(f, src, ...)
-  return Iter.new(src, ...):map(f):totable()
-end
-
 return setmetatable(M, {
   __call = function(_, ...)
     return Iter.new(...)