feat(api): implement nvim_buf_get_text (#15181)

nvim_buf_get_text is the mirror of nvim_buf_set_text. It differs from
nvim_buf_get_lines in that it allows retrieving only portions of lines.

While this can typically be done easily enough by API clients,
implementing this function provides symmetry between the get/set
text/lines APIs, and also provides a nice convenience that saves API
clients the work of having to slice the result of nvim_buf_get_lines
themselves.

1 files changed, 28 insertions, 0 deletions

diff --git a/test/functional/api/buffer_spec.lua b/test/functional/api/buffer_spec.lua
index 688f3abba5..dac3324a0f 100644
--- a/test/functional/api/buffer_spec.lua
+++ b/test/functional/api/buffer_spec.lua
@@ -537,6 +537,34 @@ describe('api/buf', function()
     end)
   end)
 
+  describe('nvim_buf_get_text', function()
+    local get_text = curbufmeths.get_text
+
+    it('works', function()
+      insert([[
+      hello foo!
+      text]])
+
+      eq({'hello'}, get_text(0, 0, 0, 5, {}))
+      eq({'hello foo!'}, get_text(0, 0, 0, 42, {}))
+      eq({'foo!'}, get_text(0, 6, 0, 10, {}))
+      eq({'foo!', 'tex'}, get_text(0, 6, 1, 3, {}))
+      eq({'foo!', 'tex'}, get_text(-2, 6, -1, 3, {}))
+      eq({''}, get_text(0, 18, 0, 20, {}))
+      eq({'ext'}, get_text(-1, 1, -1, 4, {}))
+    end)
+
+    it('errors on out-of-range', function()
+      eq(false, pcall(get_text, 2, 0, 3, 0, {}))
+      eq(false, pcall(get_text, 0, 0, 4, 0, {}))
+    end)
+
+    it('errors when start is greater than end', function()
+      eq(false, pcall(get_text, 1, 0, 0, 0, {}))
+      eq(false, pcall(get_text, 0, 1, 0, 0, {}))
+    end)
+  end)
+
   describe('nvim_buf_get_offset', function()
     local get_offset = curbufmeths.get_offset
     it('works', function()