vim-patch:9.0.0837: append() reports failure when not appending anything

Problem:    append() reports failure when not appending anything.
Solution:   Only report failure when appending something. (closes vim/vim#11498)

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

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

6 files changed, 49 insertions, 31 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 079052b658..75f6cd4313 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -73,7 +73,8 @@ append({lnum}, {text})                                                *append()*
 		{lnum} can be zero to insert a line before the first one.
 		{lnum} is used like with |getline()|.
 		Returns 1 for failure ({lnum} out of range or out of memory),
-		0 for success.  Example: >vim
+		0 for success.  When {text} is an empty list zero is returned,
+		no matter the value of {lnum}.  Example: >vim
 			let failed = append(line('$'), "# THE END")
 			let failed = append(0, ["Chapter 1", "the beginning"])
 <
@@ -96,7 +97,8 @@ appendbufline({buf}, {lnum}, {text})                           *appendbufline()*
 		If {buf} is not a valid buffer or {lnum} is not valid, an
 		error message is given. Example: >vim
 			let failed = appendbufline(13, 0, "# THE START")
-<
+<		However, when {text} is an empty list then no error is given
+		for an invalid {lnum}, since {lnum} isn't actually used.
 
 argc([{winid}])                                                         *argc()*
 		The result is the number of files in the argument list.  See
@@ -6213,9 +6215,10 @@ setbufline({buf}, {lnum}, {text})                                 *setbufline()*
 
 		To insert lines use |appendbufline()|.
 
-		{text} can be a string to set one line, or a list of strings
-		to set multiple lines.  If the list extends below the last
-		line then those lines are added.
+		{text} can be a string to set one line, or a List of strings
+		to set multiple lines.  If the List extends below the last
+		line then those lines are added.  If the List is empty then
+		nothing is changed and zero is returned.
 
 		For the use of {buf}, see |bufname()| above.
 
@@ -6374,7 +6377,8 @@ setline({lnum}, {text})                                              *setline()*
 		When {lnum} is just below the last line the {text} will be
 		added below the last line.
 		{text} can be any type or a List of any type, each item is
-		converted to a String.
+		converted to a String.  When {text} is an empty List then
+		nothing is changed and FALSE is returned.
 
 		If this succeeds, FALSE is returned.  If this fails (most likely
 		because {lnum} is invalid) TRUE is returned.
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index e393844724..126abb29ac 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -79,7 +79,8 @@ function vim.fn.api_info() end
 --- {lnum} can be zero to insert a line before the first one.
 --- {lnum} is used like with |getline()|.
 --- Returns 1 for failure ({lnum} out of range or out of memory),
---- 0 for success.  Example: >vim
+--- 0 for success.  When {text} is an empty list zero is returned,
+--- no matter the value of {lnum}.  Example: >vim
 ---   let failed = append(line('$'), "# THE END")
 ---   let failed = append(0, ["Chapter 1", "the beginning"])
 --- <
@@ -106,7 +107,8 @@ function vim.fn.append(lnum, text) end
 --- If {buf} is not a valid buffer or {lnum} is not valid, an
 --- error message is given. Example: >vim
 ---   let failed = appendbufline(13, 0, "# THE START")
---- <
+--- <However, when {text} is an empty list then no error is given
+--- for an invalid {lnum}, since {lnum} isn't actually used.
 ---
 --- @param buf any
 --- @param lnum integer
@@ -7398,9 +7400,10 @@ function vim.fn.serverstop(address) end
 ---
 --- To insert lines use |appendbufline()|.
 ---
---- {text} can be a string to set one line, or a list of strings
---- to set multiple lines.  If the list extends below the last
---- line then those lines are added.
+--- {text} can be a string to set one line, or a List of strings
+--- to set multiple lines.  If the List extends below the last
+--- line then those lines are added.  If the List is empty then
+--- nothing is changed and zero is returned.
 ---
 --- For the use of {buf}, see |bufname()| above.
 ---
@@ -7602,7 +7605,8 @@ function vim.fn.setfperm(fname, mode) end
 --- When {lnum} is just below the last line the {text} will be
 --- added below the last line.
 --- {text} can be any type or a List of any type, each item is
---- converted to a String.
+--- converted to a String.  When {text} is an empty List then
+--- nothing is changed and FALSE is returned.
 ---
 --- If this succeeds, FALSE is returned.  If this fails (most likely
 --- because {lnum} is invalid) TRUE is returned.
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index f6ccc803c0..886887dedb 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -141,7 +141,8 @@ M.funcs = {
       {lnum} can be zero to insert a line before the first one.
       {lnum} is used like with |getline()|.
       Returns 1 for failure ({lnum} out of range or out of memory),
-      0 for success.  Example: >vim
+      0 for success.  When {text} is an empty list zero is returned,
+      no matter the value of {lnum}.  Example: >vim
       	let failed = append(line('$'), "# THE END")
       	let failed = append(0, ["Chapter 1", "the beginning"])
       <
@@ -173,7 +174,8 @@ M.funcs = {
       If {buf} is not a valid buffer or {lnum} is not valid, an
       error message is given. Example: >vim
       	let failed = appendbufline(13, 0, "# THE START")
-      <
+      <However, when {text} is an empty list then no error is given
+      for an invalid {lnum}, since {lnum} isn't actually used.
 
     ]=],
     name = 'appendbufline',
@@ -8871,9 +8873,10 @@ M.funcs = {
 
       To insert lines use |appendbufline()|.
 
-      {text} can be a string to set one line, or a list of strings
-      to set multiple lines.  If the list extends below the last
-      line then those lines are added.
+      {text} can be a string to set one line, or a List of strings
+      to set multiple lines.  If the List extends below the last
+      line then those lines are added.  If the List is empty then
+      nothing is changed and zero is returned.
 
       For the use of {buf}, see |bufname()| above.
 
@@ -9117,7 +9120,8 @@ M.funcs = {
       When {lnum} is just below the last line the {text} will be
       added below the last line.
       {text} can be any type or a List of any type, each item is
-      converted to a String.
+      converted to a String.  When {text} is an empty List then
+      nothing is changed and FALSE is returned.
 
       If this succeeds, FALSE is returned.  If this fails (most likely
       because {lnum} is invalid) TRUE is returned.
diff --git a/src/nvim/eval/buffer.c b/src/nvim/eval/buffer.c
index 0fe3f5444c..256adfd44f 100644
--- a/src/nvim/eval/buffer.c
+++ b/src/nvim/eval/buffer.c
@@ -160,10 +160,7 @@ static void set_buffer_lines(buf_T *buf, linenr_T lnum_arg, bool append, typval_
   if (lines->v_type == VAR_LIST) {
     l = lines->vval.v_list;
     if (l == NULL || tv_list_len(l) == 0) {
-      // set proper return code
-      if (lnum > curbuf->b_ml.ml_line_count) {
-        rettv->vval.v_number = 1;       // FAIL
-      }
+      // not appending anything always succeeds
       goto cleanup;
     }
     li = tv_list_first(l);
diff --git a/test/old/testdir/test_bufline.vim b/test/old/testdir/test_bufline.vim
index bbf1d02079..29ec46a606 100644
--- a/test/old/testdir/test_bufline.vim
+++ b/test/old/testdir/test_bufline.vim
@@ -25,8 +25,8 @@ func Test_setbufline_getbufline()
 
   call assert_equal(1, setbufline(b, 5, 'x'))
   call assert_equal(1, setbufline(b, 5, ['x']))
-  call assert_equal(1, setbufline(b, 5, []))
-  call assert_equal(1, setbufline(b, 5, v:_null_list))
+  call assert_equal(0, setbufline(b, 5, []))
+  call assert_equal(0, setbufline(b, 5, v:_null_list))
 
   call assert_equal(1, 'x'->setbufline(bufnr('$') + 1, 1))
   call assert_equal(1, ['x']->setbufline(bufnr('$') + 1, 1))
@@ -91,6 +91,11 @@ func Test_setline_startup()
   sleep 50m
   call assert_equal(['Hello'], readfile('Xtest'))
 
+  call assert_equal(0, setline(1, []))
+  call assert_equal(0, setline(1, v:_null_list))
+  call assert_equal(0, setline(5, []))
+  call assert_equal(0, setline(6, v:_null_list))
+
   call delete('Xtest')
 endfunc
 
@@ -130,8 +135,8 @@ func Test_appendbufline()
 
   call assert_equal(1, appendbufline(b, 4, 'x'))
   call assert_equal(1, appendbufline(b, 4, ['x']))
-  call assert_equal(1, appendbufline(b, 4, []))
-  call assert_equal(1, appendbufline(b, 4, v:_null_list))
+  call assert_equal(0, appendbufline(b, 4, []))
+  call assert_equal(0, appendbufline(b, 4, v:_null_list))
 
   call assert_equal(1, appendbufline(1234, 1, 'x'))
   call assert_equal(1, appendbufline(1234, 1, ['x']))
@@ -140,8 +145,8 @@ func Test_appendbufline()
 
   call assert_equal(0, appendbufline(b, 1, []))
   call assert_equal(0, appendbufline(b, 1, v:_null_list))
-  call assert_equal(1, appendbufline(b, 3, []))
-  call assert_equal(1, appendbufline(b, 3, v:_null_list))
+  call assert_equal(0, appendbufline(b, 3, []))
+  call assert_equal(0, appendbufline(b, 3, v:_null_list))
 
   call assert_equal(['a', 'b', 'c'], getbufline(b, 1, '$'))
 
diff --git a/test/old/testdir/test_functions.vim b/test/old/testdir/test_functions.vim
index 2672e70dc5..ca0066efca 100644
--- a/test/old/testdir/test_functions.vim
+++ b/test/old/testdir/test_functions.vim
@@ -835,9 +835,13 @@ endfunc
 func Test_append()
   enew!
   split
-  call append(0, ["foo"])
-  call append(1, [])
-  call append(1, v:_null_list)
+  call assert_equal(0, append(1, []))
+  call assert_equal(0, append(1, v:_null_list))
+  call assert_equal(0, append(0, ["foo"]))
+  call assert_equal(0, append(1, []))
+  call assert_equal(0, append(1, v:_null_list))
+  call assert_equal(0, append(8, []))
+  call assert_equal(0, append(9, v:_null_list))
   call assert_equal(['foo', ''], getline(1, '$'))
   split
   only