Repository: neovim
Issue: eliminate (most) tbl_xx, list_xx functions
Labels: enhancement,lua,architecture

# Problem

[vim.iter](https://neovim.io/doc/user/lua.html#vim.iter) is a general-purpose abstraction around all [iterable](https://neovim.io/doc/user/lua.html#iterable) concepts, so the old `vim.tbl_*` functions are mostly redundant.

- many of them can/should be addressed by `vim.iter`
- the rest are fundamental ("language-level") functions which can "graduate" by simply dropping the `tbl_` prefix

Notes from @clason https://github.com/neovim/neovim/issues/23913#issuecomment-1576530394 : 

> * Anything that reasonably applies to **generic** iterators should go to `vim.iter`: `isempty`, `contains`, `count`, `spairs()` (as a flag to `vim.iter(table)`?), and all `list_*` methods.
> * Anything that is specific for general (not purely list-like) tables should go to `vim.table` ... especially functions that _modify_ (increase) the table: `isarray`, `[deep_]extend`, `[deep_]copy` (clone), `keys`, `values`, `get`. 
>    * There's an efficient `insert` and `remove` functions from `treesitter/_fold` we could add (lewis6991), the former possibly replacing `list_extend`.
> * `vim.table.pack` ... extend the whole `table` module so you can just do `local table = vim.table` and not worry about it?



# Proposal

## Graduate

- [x] `vim.tbl_isarray()`: ([unreleased](https://github.com/neovim/neovim/commit/7caf0eafd83b5a92f2ff219b3a64ffae4174b9af)) rename to `vim.isarray(it: table|Iter)`
- [x] `vim.tbl_islist()`: rename to `vim.islist()`
- [ ] `vim.tbl_isempty()`: add `vim.empty(o: any)`
    - Note: `Iter:next()` already works, but `tbl_isempty` is sugar for that...
- [ ] `vim.tbl_get()`: add `vim.get(it: table|Iter)` [#24597](https://github.com/neovim/neovim/pull/24597)
    - Note: works like `vim.get(t).a.b.c` instead of old `tbl_get(t, 'a', 'b', 'c')`
- [ ] `vim.tbl_count()`: add `vim.len(o: any)`
    - Note: `it:fold(0, function(acc,i) return acc + 1 end)`
    - Note: do we need `Iter:__len()` ?

## Remove

- [x] `vim.tbl_add_reverse_lookup()`: [#24564](https://github.com/neovim/neovim/pull/24564) [#27639](https://github.com/neovim/neovim/pull/27639)
- [x] `vim.tbl_flatten()`: [#28450](https://github.com/neovim/neovim/pull/28450)
- [ ] `vim.tbl_map()`: redundant with `vim.iter():map():totable()`
- [ ] `vim.tbl_filter()`: redundant with `vim.iter():filter():totable()`
- [ ] `vim.tbl_contains()`: use `Iter:any()` instead.
    - TODO: overload `Iter:any()` to accept a value instead of a predicate.
- [ ] `vim.tbl_extend()` AND `vim.tbl_deep_extend()`: replace with `vim.merge(opt: nil|{deep=boolean, behavior=string}, ...)`
    - https://github.com/neovim/neovim/pull/15124, improved [merge() in lazy.nvim](https://github.com/folke/lazy.nvim/blob/48b52b5cfcf8f88ed0aff8fde573a5cc20b1306d/lua/lazy/core/util.lua#L451)

## Open questions

- [ ] `vim.list_extend()`, `vim.tbl_extend()`: TBD, see also [#14544](https://github.com/neovim/neovim/issues/14544), improved [merge() in lazy.nvim](https://github.com/folke/lazy.nvim/blob/48b52b5cfcf8f88ed0aff8fde573a5cc20b1306d/lua/lazy/core/util.lua#L451)

Controversial / debatable:

- [ ] `vim.tbl_keys()`: add `vim.keys(o: table|Iter)` ~~(or Iter:tolist('keys')?~~ [related](https://github.com/neovim/neovim/pull/24564#issuecomment-1666481111)
- [ ] `vim.tbl_values()`: add `vim.values(o: table|Iter)` ~~(or Iter:tolist('values'))?~~

# Plan

- 0.10: soft deprecation: mark (most) `tbl_xx` functions as deprecated
- 0.11: hard deprecation: `vim.deprecate` with one-time _warning_
- 0.12: vim.deprecate w/ error