Mercurial > vim

diff runtime/doc/builtin.txt @ 31004:eb145a4d6bf8 v9.0.0837

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 9.0.0837: append() reports failure when not appending anything Commit: https://github.com/vim/vim/commit/cd9c8d400c1eb9cbb4ff6a33be02f91a30ab13b2 Author: Bram Moolenaar <Bram@vim.org> Date: Sat Nov 5 23:46:43 2022 +0000 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 https://github.com/vim/vim/issues/11498)
author Bram Moolenaar <Bram@vim.org>
date Sun, 06 Nov 2022 01:00:04 +0100
parents eb2638f278bf
children 5acd6f02ea35
line wrap: on
line diff
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -806,8 +806,10 @@ 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.  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 @@ appendbufline({buf}, {lnum}, {text})			*
 		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 @@ autocmd_add({acmds})					*autocmd_add()*
 			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 @@ setbufline({buf}, {lnum}, {text})			*set
 		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 @@ 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.