refactor: deprecate vim.region() #28416

Problem:
`vim.region()` is redundant with `getregionpos()`.

Solution:
Deprecate `vim.region()`.

5 files changed, 7 insertions, 26 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 646ba72bd8..be220fc307 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -19,6 +19,8 @@ API
 - nvim_subscribe()	Plugins must maintain their own "multicast" channels list.
 - nvim_unsubscribe()	Plugins must maintain their own "multicast" channels list.
 
+LUA
+- vim.region()		Use |getregionpos()| instead.
 
 ------------------------------------------------------------------------------
 DEPRECATED IN 0.10					*deprecated-0.10*
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index fd0cd3252f..36d6e0d41e 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1708,30 +1708,6 @@ vim.print({...})                                                 *vim.print()*
       • |vim.inspect()|
       • |:=|
 
-                                                                *vim.region()*
-vim.region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})
-    Gets a dict of line segment ("chunk") positions for the region from `pos1`
-    to `pos2`.
-
-    Input and output positions are byte positions, (0,0)-indexed. "End of
-    line" column position (for example, |linewise| visual selection) is
-    returned as |v:maxcol| (big number).
-
-    Parameters: ~
-      • {bufnr}      (`integer`) Buffer number, or 0 for current buffer
-      • {pos1}       (`integer[]|string`) Start of region as a (line, column)
-                     tuple or |getpos()|-compatible string
-      • {pos2}       (`integer[]|string`) End of region as a (line, column)
-                     tuple or |getpos()|-compatible string
-      • {regtype}    (`string`) |setreg()|-style selection type
-      • {inclusive}  (`boolean`) Controls whether the ending column is
-                     inclusive (see also 'selection').
-
-    Return: ~
-        (`table`) region Dict of the form `{linenr = {startcol,endcol}}`.
-        `endcol` is exclusive, and whole lines are returned as
-        `{startcol,endcol} = {0,-1}`.
-
 vim.schedule_wrap({fn})                                  *vim.schedule_wrap()*
     Returns a function which calls {fn} via |vim.schedule()|.
 
diff --git a/runtime/doc/news-0.10.txt b/runtime/doc/news-0.10.txt
index 8a0e7e92e7..d611eee242 100644
--- a/runtime/doc/news-0.10.txt
+++ b/runtime/doc/news-0.10.txt
@@ -307,7 +307,7 @@ The following new features were added.
     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.
+  • vim.region() can use a string accepted by |getpos()| as position.
 
 • Options:
   • 'winfixbuf' keeps a window focused onto a specific buffer
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 5e9be509c8..9f952db4fc 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -494,6 +494,7 @@ do
   vim.t = make_dict_accessor('t')
 end
 
+--- @deprecated
 --- Gets a dict of line segment ("chunk") positions for the region from `pos1` to `pos2`.
 ---
 --- Input and output positions are byte positions, (0,0)-indexed. "End of line" column
@@ -507,6 +508,8 @@ end
 ---@return table region Dict of the form `{linenr = {startcol,endcol}}`. `endcol` is exclusive, and
 ---whole lines are returned as `{startcol,endcol} = {0,-1}`.
 function vim.region(bufnr, pos1, pos2, regtype, inclusive)
+  vim.deprecate('vim.region', 'vim.fn.getregionpos()', '0.13')
+
   if not vim.api.nvim_buf_is_loaded(bufnr) then
     vim.fn.bufload(bufnr)
   end
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index 49833eaeec..299b68e134 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -135,7 +135,7 @@ end
 ---@param mode "v"|"V"
 ---@return table {start={row,col}, end={row,col}} using (1, 0) indexing
 local function range_from_selection(bufnr, mode)
-  -- TODO: Use `vim.region()` instead https://github.com/neovim/neovim/pull/13896
+  -- TODO: Use `vim.fn.getregionpos()` instead.
 
   -- [bufnum, lnum, col, off]; both row and column 1-indexed
   local start = vim.fn.getpos('v')