Merge pull request #27578 from zeertzjq/vim-9.1.0120

vim-patch:9.1.{0120,0126,0127): add getregion() function

1 files changed, 42 insertions, 0 deletions

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 224cecf144..623ce2bc0f 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3525,6 +3525,48 @@ function vim.fn.getreg(regname, list) end
 --- @return table
 function vim.fn.getreginfo(regname) end
 
+--- Returns the list of strings from {pos1} to {pos2} as if it's
+--- selected in visual mode of {type}.
+--- For possible values of {pos1} and {pos2} see |line()|.
+--- {type} is the selection type:
+---   "v" for |charwise| mode
+---   "V" for |linewise| mode
+---   "<CTRL-V>" for |blockwise-visual| mode
+--- You can get the last selection type by |visualmode()|.
+--- If Visual mode is active, use |mode()| to get the Visual mode
+--- (e.g., in a |:vmap|).
+--- This function uses the line and column number from the
+--- specified position.
+--- It is useful to get text starting and ending in different
+--- columns, such as |charwise-visual| selection.
+---
+--- Note that:
+--- - Order of {pos1} and {pos2} doesn't matter, it will always
+---   return content from the upper left position to the lower
+---   right position.
+--- - If 'virtualedit' is enabled and selection is past the end of
+---   line, resulting lines are filled with blanks.
+--- - If the selection starts or ends in the middle of a multibyte
+---   character, it is not included but its selected part is
+---   substituted with spaces.
+--- - If {pos1} or {pos2} equals "v" (see |line()|) and it is not in
+---   |visual-mode|, an empty list is returned.
+--- - If {pos1}, {pos2} or {type} is an invalid string, an empty
+---   list is returned.
+--- - If {pos1} or {pos2} is a mark in different buffer, an empty
+---   list is returned.
+---
+--- Examples: >
+---   :xnoremap <CR>
+---   \ <Cmd>echom getregion('v', '.', mode())<CR>
+--- <
+---
+--- @param pos1 string
+--- @param pos2 string
+--- @param type string
+--- @return string[]
+function vim.fn.getregion(pos1, pos2, type) end
+
 --- The result is a String, which is type of register {regname}.
 --- The value will be one of:
 ---     "v"      for |charwise| text