diff options
Diffstat (limited to 'runtime/doc/builtin.txt')
| -rw-r--r-- | runtime/doc/builtin.txt | 50 |
1 files changed, 44 insertions, 6 deletions
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index b2e276e5c1..455fd96805 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({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()* 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 @@ strchars({string} [, {skipcc}]) *strchars()* 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 @@ strdisplaywidth({string} [, {col}]) *strdisplaywidth()* '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 @@ strgetchar({str}, {index}) *strgetchar()* 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 @@ 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()|. @@ -8971,6 +8977,8 @@ strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* 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 @@ strtrans({string}) *strtrans()* < 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 @@ strwidth({string}) *strwidth()* 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 @@ submatch({nr} [, {list}]) *submatch()* *E935* 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 @@ substitute({string}, {pat}, {sub}, {flags}) *substitute()* |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 @@ synID({lnum}, {col}, {trans}) *synID()* 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 @@ synIDattr({synID}, {what} [, {mode}]) *synIDattr()* "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 @@ synIDtrans({synID}) *synIDtrans()* 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 @@ synstack({lnum}, {col}) *synstack()* 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 @@ tabpagenr([{arg}]) *tabpagenr()* 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 @@ 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 > @@ -9469,6 +9493,7 @@ 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 > @@ -9598,6 +9623,8 @@ timer_start({time}, {callback} [, {options}]) Vim becomes unusable because of all the error messages. + Returns -1 on error. + Example: > func MyHandler(timer) echo 'Handler called' @@ -9633,7 +9660,7 @@ timer_stopall() *timer_stopall()* 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 @@ tolower({expr}) *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() @@ -9654,6 +9681,8 @@ tr({src}, {fromstr}, {tostr}) *tr()* 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 @@ trim({text} [, {mask} [, {dir}]]) *trim()* 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 @@ 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 > @@ -9815,12 +9846,15 @@ uniq({list} [, {func} [, {dict}]]) *uniq()* *E882* < 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 @@ win_gettype([{nr}]) *win_gettype()* 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 @@ win_move_separator({nr}, {offset}) *win_move_separator()* 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) |