diff options
Diffstat (limited to 'runtime/doc/builtin.txt')
| -rw-r--r-- | runtime/doc/builtin.txt | 54 |
1 files changed, 45 insertions, 9 deletions
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 0b32b3a420..43c1f80fd6 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -7618,6 +7618,8 @@ strcharpart({src}, {start} [, {len}]) *strcharpart()* strcharpart('abc', -1, 2) < results in 'a'. + Returns an empty string on error. + Can also be used as a |method|: > GetText()->strcharpart(5) @@ -7627,6 +7629,9 @@ strchars({string} [, {skipcc}]) *strchars()* When {skipcc} is omitted or zero, composing characters are counted separately. When {skipcc} set to 1, Composing characters are ignored. + + Returns zero on error. + Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. {skipcc} is only available after 7.4.755. For backward @@ -7659,6 +7664,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|: > @@ -7690,6 +7696,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|: > @@ -7748,7 +7755,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()|. @@ -7779,6 +7786,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) @@ -7838,6 +7847,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() @@ -7847,6 +7858,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|: > @@ -7872,6 +7884,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', '') @@ -7922,7 +7936,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()* @@ -7976,6 +7992,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") < @@ -8018,6 +8036,8 @@ synIDattr({synID}, {what} [, {mode}]) *synIDattr()* cursor): > :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg") < + Returns an empty string on error. + Can also be used as a |method|: > :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") @@ -8027,6 +8047,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") @@ -8071,7 +8093,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. @@ -8170,6 +8192,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}. {tabarg} specifies the number of tab page to be used. @@ -8262,6 +8286,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 > @@ -8275,6 +8300,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 > @@ -8338,6 +8364,8 @@ timer_start({time}, {callback} [, {options}]) If the timer causes an error three times in a row the repeat is cancelled. + Returns -1 on error. + Example: > func MyHandler(timer) echo 'Handler called' @@ -8367,7 +8395,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() @@ -8375,7 +8403,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() @@ -8388,6 +8416,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" > @@ -8410,6 +8440,8 @@ trim({text} [, {mask} [, {dir}]]) *trim()* 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" > @@ -8427,6 +8459,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 > @@ -8533,12 +8566,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() @@ -8667,7 +8703,7 @@ win_gettype([{nr}]) *win_gettype()* "command" command-line window |cmdwin| (empty) normal window "loclist" |location-list-window| - "popup" popup window |popup| + "popup" floating window |api-floatwin| "preview" preview window |preview-window| "quickfix" |quickfix-window| "unknown" window {nr} not found @@ -8676,9 +8712,7 @@ win_gettype([{nr}]) *win_gettype()* When {nr} is given return the type of this window by number or |window-ID|. - Also see the 'buftype' option. When running a terminal in a - popup window then 'buftype' is "terminal" and win_gettype() - returns "popup". + Also see the 'buftype' option. Can also be used as a |method|: > GetWinid()->win_gettype() @@ -8717,6 +8751,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) |