feat(lua): vim.tbl_contains supports general tables and predicates (#23040)

* feat(lua): vim.tbl_contains supports general tables and predicates

Problem: `vim.tbl_contains` only works for list-like tables (integer
keys without gaps) and primitive values (in particular, not for nested
tables).

Solution: Rename `vim.tbl_contains` to `vim.list_contains` and add new
`vim.tbl_contains` that works for general tables and optionally allows
`value` to be a predicate function that is checked for every key.

runtime/doc/lua.txt

@@ -1698,6 +1698,19 @@ is_callable({f})                                           *vim.is_callable()*
     Return: ~
         (boolean) `true` if `f` is callable, else `false`
 
+list_contains({t}, {value})                              *vim.list_contains()*
+    Checks if a list-like table (integer keys without gaps) contains `value`.
+
+    Parameters: ~
+      • {t}      (table) Table to check (must be list-like, not validated)
+      • {value}  any Value to compare
+
+    Return: ~
+        (boolean) `true` if `t` contains `value`
+
+    See also: ~
+      • |vim.tbl_contains()| for checking values in general tables
+
 list_extend({dst}, {src}, {start}, {finish})               *vim.list_extend()*
     Extends a list-like table with the values of another list-like table.
 
@@ -1797,16 +1810,31 @@ tbl_add_reverse_lookup({o})                     *vim.tbl_add_reverse_lookup()*
     Return: ~
         (table) o
 
-tbl_contains({t}, {value})                                *vim.tbl_contains()*
-    Checks if a list-like (vector) table contains `value`.
+tbl_contains({t}, {value}, {opts})                        *vim.tbl_contains()*
+    Checks if a table contains a given value, specified either directly or via
+    a predicate that is checked for each value.
+
+    Example: >lua
+
+      vim.tbl_contains({ 'a', { 'b', 'c' } }, function(v)
+        return vim.deep_equal(v, { 'b', 'c' })
+      end, { predicate = true })
+      -- true
+<
 
     Parameters: ~
       • {t}      (table) Table to check
-      • {value}  any Value to compare
+      • {value}  any Value to compare or predicate function reference
+      • {opts}   (table|nil) Keyword arguments |kwargs|:
+                 • predicate: (boolean) `value` is a function reference to be
+                   checked (default false)
 
     Return: ~
         (boolean) `true` if `t` contains `value`
 
+    See also: ~
+      • |vim.list_contains()| for checking values in list-like tables
+
 tbl_count({t})                                               *vim.tbl_count()*
     Counts the number of non-nil values in table `t`.
 

runtime/doc/news.txt

@@ -37,6 +37,10 @@ CHANGED FEATURES                                                 *news-changed*
 
 The following changes to existing APIs or features add new behavior.
 
+• |vim.tbl_contains()| now works for general tables and allows specifying a
+  predicate function that is checked for each value. (Use |vim.list_contains()|
+  for checking list-like tables (integer keys without gaps) for literal values.)
+
 • |vim.region()| can use a string accepted by |getpos()| as position.
 
 ==============================================================================
@@ -44,8 +48,6 @@ REMOVED FEATURES                                                 *news-removed*
 
 The following deprecated functions or APIs were removed.
 
-• ...
-
 • Vimball support is removed.
   - :Vimuntar command removed.