feat(lua)!: add stricter vim.tbl_islist() and rename old one to vim.tbl_isarray() (#16440)

feat(lua)!: add stricter vim.tbl_islist(), rename vim.tbl_isarray()

Problem: `vim.tbl_islist` allows gaps in tables with integer keys
("arrays").

Solution: Rename `vim.tbl_islist` to `vim.tbl_isarray`, add new
`vim.tbl.islist` that checks for consecutive integer keys that start
from 1.

2 files changed, 24 insertions, 4 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index f39adf4f8d..6fdf3775f6 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1928,6 +1928,20 @@ tbl_get({o}, {...})                                            *vim.tbl_get()*
     Return: ~
         any Nested value indexed by key (if it exists), else nil
 
+tbl_isarray({t})                                           *vim.tbl_isarray()*
+    Tests if a Lua table can be treated as an array (a table indexed by
+    integers).
+
+    Empty table `{}` is assumed to be an array, unless it was created by
+    |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
+    for example from |rpcrequest()| or |vim.fn|.
+
+    Parameters: ~
+      • {t}  (table)
+
+    Return: ~
+        (boolean) `true` if array-like table, else `false`.
+
 tbl_isempty({t})                                           *vim.tbl_isempty()*
     Checks if a table is empty.
 
@@ -1941,17 +1955,18 @@ tbl_isempty({t})                                           *vim.tbl_isempty()*
       • https://github.com/premake/premake-core/blob/master/src/base/table.lua
 
 tbl_islist({t})                                             *vim.tbl_islist()*
-    Tests if a Lua table can be treated as an array.
+    Tests if a Lua table can be treated as a list (a table indexed by
+    consecutive integers starting from 1).
 
-    Empty table `{}` is assumed to be an array, unless it was created by
+    Empty table `{}` is assumed to be an list, unless it was created by
     |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
     for example from |rpcrequest()| or |vim.fn|.
 
     Parameters: ~
-      • {t}  (table) Table
+      • {t}  (table)
 
     Return: ~
-        (boolean) `true` if array-like table, else `false`
+        (boolean) `true` if list-like table, else `false`.
 
 tbl_keys({t})                                                 *vim.tbl_keys()*
     Return a list of all keys used in a table. However, the order of the
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index aff1a4a24e..6697b3018a 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -15,6 +15,11 @@ BREAKING CHANGES                                                *news-breaking*
 
 The following changes may require adaptations in user config or plugins.
 
+• |vim.tbl_islist()| now checks whether a table is actually list-like (i.e.,
+  has integer keys without gaps and starting from 1). For the previous
+  behavior (only check for integer keys, allow gaps or not starting with 1),
+  use |vim.tbl_isarray()|.
+
 • "#" followed by a digit no longer stands for a function key at the start of
   the lhs of a mapping.