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 #11498)
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 98fd138..1ee2dcb 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -806,8 +806,10 @@
{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. In |Vim9| script an invalid argument or
- negative number results in an error. Example: >
+ 0 for success. When {text} is an empty list zero is returned,
+ no matter the value of {lnum}.
+ In |Vim9| script an invalid argument or negative number
+ results in an error. Example: >
:let failed = append(line('$'), "# THE END")
:let failed = append(0, ["Chapter 1", "the beginning"])
@@ -835,7 +837,9 @@
If {buf} is not a valid buffer or {lnum} is not valid, an
error message is given. Example: >
: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.
+
Can also be used as a |method| after a List, the base is
passed as the second argument: >
mylist->appendbufline(buf, lnum)
@@ -981,7 +985,7 @@
let acmd.bufnr = 5
let acmd.cmd = 'call BufEnterFunc()'
call autocmd_add([acmd])
-
+<
Can also be used as a |method|: >
GetAutocmdList()->autocmd_add()
<
@@ -7873,9 +7877,10 @@
To insert lines use |appendbufline()|.
Any text properties in {lnum} are cleared.
- {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.
@@ -8060,7 +8065,8 @@
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.