vim-patch:9.0.0916: getbufline() is inefficient for getting a single line

Problem:    getbufline() is inefficient for getting a single line.
Solution:   Add getbufoneline().

https://github.com/vim/vim/commit/ce30ccc06af7f2c03762e5b18dde37b26ea6ec42

Cherry-pick part of usr_41.txt from patch 8.1.1628.

Co-authored-by: Bram Moolenaar <Bram@vim.org>

5 files changed, 42 insertions, 9 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index a6eafbf2b9..fdee409639 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -170,6 +170,7 @@ get({func}, {what})		any	get property of funcref/partial {func}
 getbufinfo([{buf}])		List	information about buffers
 getbufline({buf}, {lnum} [, {end}])
 				List	lines {lnum} to {end} of buffer {buf}
+getbufoneline({buf}, {lnum})	String	line {lnum} of buffer {buf}
 getbufvar({buf}, {varname} [, {def}])
 				any	variable {varname} in buffer {buf}
 getchangelist([{buf}])		List	list of change list items
@@ -2685,11 +2686,13 @@ getbufinfo([{dict}])
 		Can also be used as a |method|: >
 			GetBufnr()->getbufinfo()
 <
+
 							*getbufline()*
 getbufline({buf}, {lnum} [, {end}])
 		Return a |List| with the lines starting from {lnum} to {end}
 		(inclusive) in the buffer {buf}.  If {end} is omitted, a
-		|List| with only the line {lnum} is returned.
+		|List| with only the line {lnum} is returned.  See
+		`getbufoneline()` for only getting the line.
 
 		For the use of {buf}, see |bufname()| above.
 
@@ -2712,6 +2715,11 @@ getbufline({buf}, {lnum} [, {end}])
 
 <		Can also be used as a |method|: >
 			GetBufnr()->getbufline(lnum)
+<
+							*getbufoneline()*
+getbufoneline({buf}, {lnum})
+		Just like `getbufline()` but only get one line and return it
+		as a string.
 
 getbufvar({buf}, {varname} [, {def}])				*getbufvar()*
 		The result is the value of option or local buffer variable
@@ -3199,7 +3207,8 @@ getline({lnum} [, {end}])
 <		Can also be used as a |method|: >
 			ComputeLnum()->getline()
 
-<		To get lines from another buffer see |getbufline()|
+<		To get lines from another buffer see |getbufline()| and
+		|getbufoneline()|
 
 getloclist({nr} [, {what}])				*getloclist()*
 		Returns a |List| with all the entries in the location list for
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 067ad6648c..226bd029a3 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -785,6 +785,13 @@ Working with text in the current buffer:		*text-functions*
 	getcharsearch()		return character search information
 	setcharsearch()		set character search information
 
+Working with text in another buffer:
+	getbufline()		get a list of lines from the specified buffer
+	getbufoneline()		get a one line from the specified buffer
+	setbufline()		replace a line in the specified buffer
+	appendbufline()		append a list of lines in the specified buffer
+	deletebufline()		delete lines from a specified buffer
+
 					*system-functions* *file-functions*
 System functions and manipulation of files:
 	glob()			expand wildcards
@@ -838,8 +845,10 @@ Buffers, windows and the argument list:
 	argidx()		current position in the argument list
 	arglistid()		get id of the argument list
 	argv()			get one entry from the argument list
+	bufadd()		add a file to the list of buffers
 	bufexists()		check if a buffer exists
 	buflisted()		check if a buffer exists and is listed
+	bufload()		ensure a buffer is loaded
 	bufloaded()		check if a buffer exists and is loaded
 	bufname()		get the name of a specific buffer
 	bufnr()			get the buffer number of a specific buffer
@@ -850,10 +859,6 @@ Buffers, windows and the argument list:
 	bufwinid()		get the window ID of a specific buffer
 	bufwinnr()		get the window number of a specific buffer
 	winbufnr()		get the buffer number of a specific window
-	getbufline()		get a list of lines from the specified buffer
-	setbufline()		replace a line in the specified buffer
-	appendbufline()		append a list of lines in the specified buffer
-	deletebufline()		delete lines from a specified buffer
 	win_findbuf()		find windows containing a buffer
 	win_getid()		get window ID of a window
 	win_gettype()		get type of window
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index dd30f51eb4..14be6aba73 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -146,6 +146,7 @@ return {
     get={args={2, 3}, base=1},
     getbufinfo={args={0, 1}, base=1},
     getbufline={args={2, 3}, base=1},
+    getbufoneline={args=2, base=1},
     getbufvar={args={2, 3}, base=1},
     getchangelist={args={0, 1}, base=1},
     getchar={args={0, 1}},
diff --git a/src/nvim/eval/funcs.c b/src/nvim/eval/funcs.c
index 12568ec965..8666aa4f35 100644
--- a/src/nvim/eval/funcs.c
+++ b/src/nvim/eval/funcs.c
@@ -2671,8 +2671,9 @@ static void get_buffer_lines(buf_T *buf, linenr_T start, linenr_T end, int retli
   }
 }
 
-/// "getbufline()" function
-static void f_getbufline(typval_T *argvars, typval_T *rettv, EvalFuncData fptr)
+/// @param retlist  true: "getbufline()" function
+///                 false: "getbufoneline()" function
+static void getbufline(typval_T *argvars, typval_T *rettv, bool retlist)
 {
   const int did_emsg_before = did_emsg;
   buf_T *const buf = tv_get_buf_from_arg(&argvars[0]);
@@ -2684,7 +2685,19 @@ static void f_getbufline(typval_T *argvars, typval_T *rettv, EvalFuncData fptr)
                         ? lnum
                         : tv_get_lnum_buf(&argvars[2], buf));
 
-  get_buffer_lines(buf, lnum, end, true, rettv);
+  get_buffer_lines(buf, lnum, end, retlist, rettv);
+}
+
+/// "getbufline()" function
+static void f_getbufline(typval_T *argvars, typval_T *rettv, EvalFuncData fptr)
+{
+  getbufline(argvars, rettv, true);
+}
+
+/// "getbufoneline()" function
+static void f_getbufoneline(typval_T *argvars, typval_T *rettv, EvalFuncData fptr)
+{
+  getbufline(argvars, rettv, false);
 }
 
 /// "getchangelist()" function
diff --git a/src/nvim/testdir/test_bufline.vim b/src/nvim/testdir/test_bufline.vim
index 9c4e48734a..d4dee38620 100644
--- a/src/nvim/testdir/test_bufline.vim
+++ b/src/nvim/testdir/test_bufline.vim
@@ -11,7 +11,9 @@ func Test_setbufline_getbufline()
   hide
   call assert_equal(0, setbufline(b, 1, ['foo', 'bar']))
   call assert_equal(['foo'], getbufline(b, 1))
+  call assert_equal('foo', getbufoneline(b, 1))
   call assert_equal(['bar'], getbufline(b, '$'))
+  call assert_equal('bar', getbufoneline(b, '$'))
   call assert_equal(['foo', 'bar'], getbufline(b, 1, 2))
   exe "bd!" b
   call assert_equal([], getbufline(b, 1, 2))
@@ -35,8 +37,11 @@ func Test_setbufline_getbufline()
 
   call assert_equal(0, setbufline(b, 4, ['d', 'e']))
   call assert_equal(['c'], b->getbufline(3))
+  call assert_equal('c', b->getbufoneline(3))
   call assert_equal(['d'], getbufline(b, 4))
+  call assert_equal('d', getbufoneline(b, 4))
   call assert_equal(['e'], getbufline(b, 5))
+  call assert_equal('e', getbufoneline(b, 5))
   call assert_equal([], getbufline(b, 6))
   call assert_equal([], getbufline(b, 2, 1))