vim: runtime/doc/builtin.txt comparison

comparison runtime/doc/builtin.txt @ 29193:1e9e9d89f0ee

Update runtime files Commit: https://github.com/vim/vim/commit/d592deb336523a5448779ee3d4bba80334cff1f7 Author: Bram Moolenaar <Bram@vim.org> Date: Fri Jun 17 15:42:40 2022 +0100 Update runtime files

author	Bram Moolenaar <Bram@vim.org>
date	Fri, 17 Jun 2022 16:45:04 +0200
parents	2a1f9b4a5ac9
children	f92f658585e6

comparison

equal deleted inserted replaced

-:e4488cf0eff9
+:1e9e9d89f0ee
-*builtin.txt*	For Vim version 8.2.  Last change: 2022 Jun 05
+*builtin.txt*	For Vim version 8.2.  Last change: 2022 Jun 16
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
 		exist it is omitted and counted as one character.  For
 		example: >
 			strcharpart('abc', -1, 2)
 <		results in 'a'.
+		Returns an empty string on error.
 		Can also be used as a |method|: >
 			GetText()->strcharpart(5)
 strchars({string} [, {skipcc}])					*strchars()*
 		in String {string}.
 		When {skipcc} is omitted or zero, composing characters are
 		counted separately.
 		When {skipcc} set to 1, Composing characters are ignored.
 		|strcharlen()| always does this.
+		Returns zero on error.
 		Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
 		{skipcc} is only available after 7.4.755.  For backward
 		compatibility, you can define a wrapper function: >
 		The option settings of the current window are used.  This
 		matters for anything that's displayed differently, such as
 		'tabstop' and 'display'.
 		When {string} contains characters with East Asian Width Class
 		Ambiguous, this function's return value depends on 'ambiwidth'.
+		Returns zero on error.
 		Also see |strlen()|, |strwidth()| and |strchars()|.
 		Can also be used as a |method|: >
 			GetText()->strdisplaywidth()
 		Get a Number corresponding to the character at {index} in
 		{str}.  This uses a zero-based character index, not a byte
 		index.  Composing characters are considered separate
 		characters here.  Use |nr2char()| to convert the Number to a
 		String.
+		Returns -1 if {index} is invalid.
 		Also see |strcharpart()| and |strchars()|.
 		Can also be used as a |method|: >
 			GetText()->strgetchar(5)
 strlen({string})						*strlen()*
 		The result is a Number, which is the length of the String
 		{string} in bytes.
 		If the argument is a Number it is first converted to a String.
-		For other types an error is given.
+		For other types an error is given and zero is returned.
 		If you want to count the number of multibyte characters use
 		|strchars()|.
 		Also see |len()|, |strdisplaywidth()| and |strwidth()|.
 		Can also be used as a |method|: >
 <		Note: To get the first character, {start} must be 0.  For
 		example, to get the character under the cursor: >
 			strpart(getline("."), col(".") - 1, 1, v:true)
 <
+		Returns an empty string on error.
 		Can also be used as a |method|: >
 			GetText()->strpart(5)
 strptime({format}, {timestring})				*strptime()*
 		The result is a Number, which is a unix timestamp representing
 		Like they are shown in a window.  Example: >
 			echo strtrans(@a)
 <		This displays a newline in register a as "^@" instead of
 		starting a new line.
+		Returns an empty string on error.
 		Can also be used as a |method|: >
 			GetString()->strtrans()
 strwidth({string})					*strwidth()*
 		The result is a Number, which is the number of display cells
 		String {string} occupies.  A Tab character is counted as one
 		cell, alternatively use |strdisplaywidth()|.
 		When {string} contains characters with East Asian Width Class
 		Ambiguous, this function's return value depends on 'ambiwidth'.
+		Returns zero on error.
 		Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
 		Can also be used as a |method|: >
 			GetString()->strwidth()
 		items, since there are no real line breaks.
 		When substitute() is used recursively only the submatches in
 		the current (deepest) call can be obtained.
+		Returns an empty string or list on error.
 		Examples: >
 			:s/\d\+/\=submatch(0) + 1/
 			:echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
 <		This finds the first number in the line and adds one to it.
 		A line break is included as a newline character.
 <		The optional argument is a list which contains the whole
 		matched string and up to nine submatches, like what
 		|submatch()| returns.  Example: >
 		   :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
-<		Can also be used as a |method|: >
+<		Returns an empty string on error.
+		Can also be used as a |method|: >
 			GetString()->substitute(pat, sub, flags)
 swapinfo({fname})					*swapinfo()*
 		The result is a dictionary, which holds information about the
 		swapfile {fname}. The available fields are:
 		the effective color.  When {trans} is |FALSE|, the transparent
 		item is returned.  This is useful when wanting to know which
 		syntax item is effective (e.g. inside parens).
 		Warning: This function can be very slow.  Best speed is
 		obtained by going through the file in forward direction.
+		Returns zero on error.
 		Example (echoes the name of the syntax item under the cursor): >
 			:echo synIDattr(synID(line("."), col("."), 1), "name")
 <
 		"standout"	"1" if standout
 		"underline"	"1" if underlined
 		"undercurl"	"1" if undercurled
 		"strike"	"1" if strikethrough
+		Returns an empty string on error.
 		Example (echoes the color of the syntax item under the
 		cursor): >
 	:echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
 <
 		Can also be used as a |method|: >
 synIDtrans({synID})					*synIDtrans()*
 		The result is a Number, which is the translated syntax ID of
 		{synID}.  This is the syntax group ID of what is being used to
 		highlight the character.  Highlight links given with
 		":highlight link" are followed.
+		Returns zero on error.
 		Can also be used as a |method|: >
 	:echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
 synconcealed({lnum}, {col})				*synconcealed()*
 		Example that shows the syntax stack under the cursor: >
 			for id in synstack(line("."), col("."))
 			   echo synIDattr(id, "name")
 			endfor
 <		When the position specified with {lnum} and {col} is invalid
-		nothing is returned.  The position just after the last
+		an empty List is returned.  The position just after the last
 		character in a line and the first column in an empty line are
 		valid positions.
 system({expr} [, {input}])				*system()* *E677*
 		Get the output of the shell command {expr} as a |String|.  See
 				count).
 			#	the number of the last accessed tab page
 				(where |g<Tab>| goes to). if there is no
 				previous tab page 0 is returned.
 		The number can be used with the |:tab| command.
+		Returns zero on error.
 tabpagewinnr({tabarg} [, {arg}])			*tabpagewinnr()*
 		Like |winnr()| but for tab page {tabarg}.
 		{tabarg} specifies the number of tab page to be used.
 tan({expr})						*tan()*
 		Return the tangent of {expr}, measured in radians, as a |Float|
 		in the range [-inf, inf].
 		{expr} must evaluate to a |Float| or a |Number|.
+		Returns 0.0 if {expr} is not a |Float| or a |Number|.
 		Examples: >
 			:echo tan(10)
 <			0.648361 >
 			:echo tan(-4.01)
 <			-1.181502
 tanh({expr})						*tanh()*
 		Return the hyperbolic tangent of {expr} as a |Float| in the
 		range [-1, 1].
 		{expr} must evaluate to a |Float| or a |Number|.
+		Returns 0.0 if {expr} is not a |Float| or a |Number|.
 		Examples: >
 			:echo tanh(0.5)
 <			0.462117 >
 			:echo tanh(-1)
 <			-0.761594
 				If the timer causes an error three times in a
 				row the repeat is cancelled.  This avoids that
 				Vim becomes unusable because of all the error
 				messages.
+		Returns -1 on error.
 		Example: >
 			func MyHandler(timer)
 			  echo 'Handler called'
 			endfunc
 			let timer = timer_start(500, 'MyHandler',
 		{only available when compiled with the |+timers| feature}
 tolower({expr})						*tolower()*
 		The result is a copy of the String given, with all uppercase
 		characters turned into lowercase (just like applying |gu| to
-		the string).
+		the string).  Returns an empty string on error.
 		Can also be used as a |method|: >
 			GetText()->tolower()
 toupper({expr})						*toupper()*
 		The result is a copy of the String given, with all lowercase
 		characters turned into uppercase (just like applying |gU| to
-		the string).
+		the string).  Returns an empty string on error.
 		Can also be used as a |method|: >
 			GetText()->toupper()
 tr({src}, {fromstr}, {tostr})				*tr()*
 		position in the {tostr} string.  Thus the first character in
 		{fromstr} is translated into the first character in {tostr}
 		and so on.  Exactly like the unix "tr" command.
 		This code also deals with multibyte characters properly.
+		Returns an empty string on error.
 		Examples: >
 			echo tr("hello there", "ht", "HT")
 <		returns "Hello THere" >
 			echo tr("<blob>", "<>", "{}")
 <		returns "{blob}"
 			1	remove only at the beginning of {text}
 			2	remove only at the end of {text}
 		When omitted both ends are trimmed.
 		This function deals with multibyte characters properly.
+		Returns an empty string on error.
 		Examples: >
 			echo trim("   some text ")
 <		returns "some text" >
 			echo trim("  \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
 trunc({expr})							*trunc()*
 		Return the largest integral value with magnitude less than or
 		equal to {expr} as a |Float| (truncate towards zero).
 		{expr} must evaluate to a |Float| or a |Number|.
+		Returns 0.0 if {expr} is not a |Float| or a |Number|.
 		Examples: >
 			echo trunc(1.456)
 <			1.0  >
 			echo trunc(-5.456)
 <			-5.0  >
 		to remain unmodified make a copy first: >
 			:let newlist = uniq(copy(mylist))
 <		The default compare function uses the string representation of
 		each item.  For the use of {func} and {dict} see |sort()|.
+		Returns zero if {list} is not a |List|.
 		Can also be used as a |method|: >
 			mylist->uniq()
 values({dict})						*values()*
 		Return a |List| with all the values of {dict}.  The |List| is
 		in arbitrary order.  Also see |items()| and |keys()|.
+		Returns zero if {dict} is not a |Dict|.
 		Can also be used as a |method|: >
 			mydict->values()
 virtcol({expr} [, {list}])				*virtcol()*
 		Also see the 'buftype' option.  When running a terminal in a
 		popup window then 'buftype' is "terminal" and win_gettype()
 		returns "popup".
+		Return an empty string if the window cannot be found.
 		Can also be used as a |method|: >
 			GetWinid()->win_gettype()
 <
 win_gotoid({expr})					*win_gotoid()*
 		Go to window with ID {expr}.  This may also change the current
 		window and the width of other windows adjacent to the vertical
 		separator. The magnitude of movement may be smaller than
 		specified (e.g., as a consequence of maintaining
 		'winminwidth'). Returns TRUE if the window can be found and
 		FALSE otherwise.
+		This will fail for the rightmost window and a full-width
+		window, since it has no separator on the right.
 		Can also be used as a |method|: >
 			GetWinnr()->win_move_separator(offset)
 win_move_statusline({nr}, {offset})			*win_move_statusline()*

Mercurial > vim

comparison runtime/doc/builtin.txt @ 29193:1e9e9d89f0ee