diff options
Diffstat (limited to 'runtime/doc/builtin.txt')
| -rw-r--r-- | runtime/doc/builtin.txt | 45 |
1 files changed, 37 insertions, 8 deletions
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index f63525242f..57b45f33c1 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -4476,7 +4476,7 @@ len({expr}) The result is a Number, which is the length of the argument. When {expr} is a |Blob| the number of bytes is returned. When {expr} is a |Dictionary| the number of entries in the |Dictionary| is returned. - Otherwise an error is given. + Otherwise an error is given and returns zero. Can also be used as a |method|: > mylist->len() @@ -4563,6 +4563,7 @@ line({expr} [, {winid}]) *line()* |getpos()|. With the optional {winid} argument the values are obtained for that window instead of the current window. + Returns 0 for invalid values of {expr} and {winid}. Examples: > line(".") line number of the cursor line(".", winid) idem, in window "winid" @@ -4615,6 +4616,8 @@ list2str({list} [, {utf8}]) *list2str()* With UTF-8 composing characters work as expected: > list2str([97, 769]) returns "á" < + Returns an empty string on error. + Can also be used as a |method|: > GetList()->list2str() @@ -4627,6 +4630,7 @@ log({expr}) *log()* Return the natural logarithm (base e) of {expr} as a |Float|. {expr} must evaluate to a |Float| or a |Number| in the range (0, inf]. + Returns 0.0 if {expr} is not a |Float| or a |Number|. Examples: > :echo log(10) < 2.302585 > @@ -4639,6 +4643,7 @@ log({expr}) *log()* log10({expr}) *log10()* Return the logarithm of Float {expr} to base 10 as a |Float|. {expr} must evaluate to a |Float| or a |Number|. + Returns 0.0 if {expr} is not a |Float| or a |Number|. Examples: > :echo log10(1000) < 3.0 > @@ -4712,8 +4717,9 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* listing. When there is no mapping for {name}, an empty String is - returned. When the mapping for {name} is empty, then "<Nop>" - is returned. + returned if {dict} is FALSE, otherwise returns an empty Dict. + When the mapping for {name} is empty, then "<Nop>" is + returned. The {name} can have special key names, like in the ":map" command. @@ -4912,6 +4918,8 @@ matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) The number of matches is not limited, as it is the case with the |:match| commands. + Returns -1 on error. + Example: > :highlight MyGroup ctermbg=green guibg=green :let m = matchadd("MyGroup", "TODO") @@ -4954,6 +4962,8 @@ matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) The maximum number of positions in {pos} is 8. + Returns -1 on error. + Example: > :highlight MyGroup ctermbg=green guibg=green :let m = matchaddpos("MyGroup", [[23, 24], 34]) @@ -5457,6 +5467,7 @@ pathshorten({expr} [, {len}]) *pathshorten()* :echo pathshorten('~/.config/nvim/autoload/file2.vim', 2) < ~/.co/nv/au/file2.vim ~ It doesn't matter if the path exists or not. + Returns an empty string on error. Can also be used as a |method|: > GetDirectories()->pathshorten() @@ -5482,6 +5493,7 @@ perleval({expr}) *perleval()* pow({x}, {y}) *pow()* Return the power of {x} to the exponent {y} as a |Float|. {x} and {y} must evaluate to a |Float| or a |Number|. + Returns 0.0 if {x} or {y} is not a |Float| or a |Number|. Examples: > :echo pow(3, 3) < 27.0 > @@ -5852,6 +5864,7 @@ rand([{expr}]) *rand()* {expr} can be initialized by |srand()| and will be updated by rand(). If {expr} is omitted, an internal seed value is used and updated. + Returns -1 if {expr} is invalid. Examples: > :echo rand() @@ -5889,6 +5902,8 @@ readdir({directory} [, {expr}]) endfunction echo s:tree(".") < + Returns an empty List on error. + Can also be used as a |method|: > GetDirName()->readdir() < @@ -5977,7 +5992,7 @@ reltime([{start} [, {end}]]) *reltime()* and {end}. The {start} and {end} arguments must be values returned by - reltime(). + reltime(). Returns zero on error. Can also be used as a |method|: > GetStart()->reltime() @@ -6023,6 +6038,7 @@ remove({list}, {idx} [, {end}]) *remove()* item as {end} a list with one item is returned. When {end} points to an item before {idx} this is an error. See |list-index| for possible values of {idx} and {end}. + Returns zero on error. Example: > :echo "last item: " .. remove(mylist, -1) :call remove(mylist, 0, 9) @@ -6039,6 +6055,7 @@ remove({blob}, {idx} [, {end}]) return a |Blob| with these bytes. When {idx} points to the same byte as {end} a |Blob| with one byte is returned. When {end} points to a byte before {idx} this is an error. + Returns zero on error. Example: > :echo "last byte: " .. remove(myblob, -1) :call remove(mylist, 0, 9) @@ -6048,6 +6065,7 @@ remove({dict}, {key}) Example: > :echo "removed " .. remove(dict, "one") < If there is no {key} in {dict} this is an error. + Returns zero on error. rename({from}, {to}) *rename()* Rename the file by the name {from} to the name {to}. This @@ -6094,6 +6112,7 @@ reverse({object}) Reverse the order of items in {object} in-place. {object} can be a |List| or a |Blob|. Returns {object}. + Returns zero if {object} is not a List or a Blob. If you want an object to remain unmodified make a copy first: > :let revlist = reverse(copy(mylist)) < Can also be used as a |method|: > @@ -6104,6 +6123,7 @@ round({expr}) *round()* as a |Float|. If {expr} lies halfway between two integral values, then use the larger one (away from zero). {expr} must evaluate to a |Float| or a |Number|. + Returns 0.0 if {expr} is not a |Float| or a |Number|. Examples: > echo round(0.456) < 0.0 > @@ -6150,6 +6170,7 @@ screenattr({row}, {col}) *screenattr()* Like |screenchar()|, but return the attribute. This is a rather arbitrary number that can only be used to compare to the attribute at other positions. + Returns -1 when row or col is out of range. Can also be used as a |method|: > GetRow()->screenattr(col) @@ -6208,9 +6229,10 @@ screenpos({winid}, {lnum}, {col}) *screenpos()* a Tab it would be the same as "endcol", while for a double width character it would be the same as "col". The |conceal| feature is ignored here, the column numbers are - as if 'conceallevel' is zero. You can set the cursor to the - right position and use |screencol()| to get the value with - |conceal| taken into account. + as if 'conceallevel' is zero. You can set the cursor to the + right position and use |screencol()| to get the value with + |conceal| taken into account. + Returns an empty Dict if {winid} is invalid. Can also be used as a |method|: > GetWinid()->screenpos(lnum, col) @@ -7242,6 +7264,7 @@ simplify({filename}) *simplify()* sin({expr}) *sin()* Return the sine of {expr}, measured in radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. + Returns 0.0 if {expr} is not a |Float| or a |Number|. Examples: > :echo sin(100) < -0.506366 > @@ -7255,6 +7278,7 @@ sinh({expr}) *sinh()* Return the hyperbolic sine of {expr} 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 sinh(0.5) < 0.521095 > @@ -7455,7 +7479,8 @@ sqrt({expr}) *sqrt()* Return the non-negative square root of Float {expr} as a |Float|. {expr} must evaluate to a |Float| or a |Number|. When {expr} - is negative the result is NaN (Not a Number). + is negative the result is NaN (Not a Number). Returns 0.0 if + {expr} is not a |Float| or a |Number|. Examples: > :echo sqrt(100) < 10.0 > @@ -7543,6 +7568,8 @@ str2float({string} [, {quoted}]) *str2float()* |substitute()|: > let f = str2float(substitute(text, ',', '', 'g')) < + Returns 0.0 if the conversion fails. + Can also be used as a |method|: > let f = text->substitute(',', '', 'g')->str2float() @@ -7578,6 +7605,8 @@ str2nr({string} [, {base}]) *str2nr()* {base} is 2 a leading "0b" or "0B" is ignored. Text after the number is silently ignored. + Returns 0 if {string} is empty or on error. + Can also be used as a |method|: > GetText()->str2nr() |