Update runtime files
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index b2e276e..455fd96 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*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
@@ -8809,6 +8809,8 @@
strcharpart('abc', -1, 2)
< results in 'a'.
+ Returns an empty string on error.
+
Can also be used as a |method|: >
GetText()->strcharpart(5)
@@ -8821,6 +8823,8 @@
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
@@ -8853,6 +8857,7 @@
'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|: >
@@ -8886,6 +8891,7 @@
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|: >
@@ -8940,7 +8946,7 @@
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()|.
@@ -8971,6 +8977,8 @@
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)
@@ -9033,6 +9041,8 @@
< 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()
@@ -9042,6 +9052,7 @@
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|: >
@@ -9067,6 +9078,8 @@
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', '')
@@ -9117,7 +9130,9 @@
|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()*
@@ -9172,6 +9187,8 @@
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")
<
@@ -9209,6 +9226,8 @@
"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")
@@ -9223,6 +9242,8 @@
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")
@@ -9267,7 +9288,7 @@
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.
@@ -9381,6 +9402,8 @@
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}.
@@ -9453,6 +9476,7 @@
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 >
@@ -9469,6 +9493,7 @@
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 >
@@ -9598,6 +9623,8 @@
Vim becomes unusable because of all the error
messages.
+ Returns -1 on error.
+
Example: >
func MyHandler(timer)
echo 'Handler called'
@@ -9633,7 +9660,7 @@
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()
@@ -9641,7 +9668,7 @@
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()
@@ -9654,6 +9681,8 @@
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" >
@@ -9679,6 +9708,7 @@
When omitted both ends are trimmed.
This function deals with multibyte characters properly.
+ Returns an empty string on error.
Examples: >
echo trim(" some text ")
@@ -9697,6 +9727,7 @@
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 >
@@ -9815,12 +9846,15 @@
< 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()
@@ -9988,6 +10022,8 @@
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()
<
@@ -10025,6 +10061,8 @@
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)