1- *builtin.txt* For Vim version 8.2. Last change: 2022 Jun 05
1+ *builtin.txt* For Vim version 8.2. Last change: 2022 Jun 16
22
33
44 VIM REFERENCE MANUAL by Bram Moolenaar
@@ -5899,6 +5899,8 @@ matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
58995899 matchseq When this item is present return only matches
59005900 that contain the characters in {str} in the
59015901 given sequence.
5902+ limit Maximum number of matches in {list} to be
5903+ returned. Zero means no limit.
59025904
59035905 If {list} is a list of dictionaries, then the optional {dict}
59045906 argument supports the following additional items:
@@ -5910,8 +5912,6 @@ matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
59105912 This should accept a dictionary item as the
59115913 argument and return the text for that item to
59125914 use for fuzzy matching.
5913- limit Maximum number of matches in {list} to be
5914- returned. Zero means no limit.
59155915
59165916 {str} is treated as a literal string and regular expression
59175917 matching is NOT supported. The maximum supported {str} length
@@ -8809,6 +8809,8 @@ strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
88098809 strcharpart('abc', -1, 2)
88108810< results in 'a'.
88118811
8812+ Returns an empty string on error.
8813+
88128814 Can also be used as a | method | : >
88138815 GetText()->strcharpart(5)
88148816
@@ -8821,6 +8823,8 @@ strchars({string} [, {skipcc}]) *strchars()*
88218823 When {skipcc} set to 1, Composing characters are ignored.
88228824 | strcharlen() | always does this.
88238825
8826+ Returns zero on error.
8827+
88248828 Also see | strlen() | , | strdisplaywidth() | and | strwidth() | .
88258829
88268830 {skipcc} is only available after 7.4.755. For backward
@@ -8853,6 +8857,7 @@ strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
88538857 'tabstop' and 'display' .
88548858 When {string} contains characters with East Asian Width Class
88558859 Ambiguous, this function's return value depends on 'ambiwidth' .
8860+ Returns zero on error.
88568861 Also see | strlen() | , | strwidth() | and | strchars() | .
88578862
88588863 Can also be used as a | method | : >
@@ -8886,6 +8891,7 @@ strgetchar({str}, {index}) *strgetchar()*
88868891 index. Composing characters are considered separate
88878892 characters here. Use | nr2char() | to convert the Number to a
88888893 String.
8894+ Returns -1 if {index} is invalid.
88898895 Also see | strcharpart() | and | strchars() | .
88908896
88918897 Can also be used as a | method | : >
@@ -8940,7 +8946,7 @@ strlen({string}) *strlen()*
89408946 The result is a Number, which is the length of the String
89418947 {string} in bytes.
89428948 If the argument is a Number it is first converted to a String.
8943- For other types an error is given.
8949+ For other types an error is given and zero is returned .
89448950 If you want to count the number of multibyte characters use
89458951 | strchars() | .
89468952 Also see | len() | , | strdisplaywidth() | and | strwidth() | .
@@ -8971,6 +8977,8 @@ strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
89718977 example, to get the character under the cursor: >
89728978 strpart(getline("."), col(".") - 1, 1, v:true)
89738979<
8980+ Returns an empty string on error.
8981+
89748982 Can also be used as a | method | : >
89758983 GetText()->strpart(5)
89768984
@@ -9033,6 +9041,8 @@ strtrans({string}) *strtrans()*
90339041< This displays a newline in register a as "^@" instead of
90349042 starting a new line.
90359043
9044+ Returns an empty string on error.
9045+
90369046 Can also be used as a | method | : >
90379047 GetString()->strtrans()
90389048
@@ -9042,6 +9052,7 @@ strwidth({string}) *strwidth()*
90429052 cell, alternatively use | strdisplaywidth() | .
90439053 When {string} contains characters with East Asian Width Class
90449054 Ambiguous, this function's return value depends on 'ambiwidth' .
9055+ Returns zero on error.
90459056 Also see | strlen() | , | strdisplaywidth() | and | strchars() | .
90469057
90479058 Can also be used as a | method | : >
@@ -9067,6 +9078,8 @@ submatch({nr} [, {list}]) *submatch()* *E935*
90679078 When substitute() is used recursively only the submatches in
90689079 the current (deepest) call can be obtained.
90699080
9081+ Returns an empty string or list on error.
9082+
90709083 Examples: >
90719084 :s/\d\+/\=submatch(0) + 1/
90729085 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
@@ -9117,7 +9130,9 @@ substitute({string}, {pat}, {sub}, {flags}) *substitute()*
91179130 | submatch() | returns. Example: >
91189131 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
91199132
9120- < Can also be used as a | method | : >
9133+ < Returns an empty string on error.
9134+
9135+ Can also be used as a | method | : >
91219136 GetString()->substitute(pat, sub, flags)
91229137
91239138 swapinfo({fname} ) *swapinfo()*
@@ -9172,6 +9187,8 @@ synID({lnum}, {col}, {trans}) *synID()*
91729187 Warning: This function can be very slow. Best speed is
91739188 obtained by going through the file in forward direction.
91749189
9190+ Returns zero on error.
9191+
91759192 Example (echoes the name of the syntax item under the cursor): >
91769193 :echo synIDattr(synID(line("."), col("."), 1), "name")
91779194<
@@ -9209,6 +9226,8 @@ synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
92099226 "undercurl" "1" if undercurled
92109227 "strike" "1" if strikethrough
92119228
9229+ Returns an empty string on error.
9230+
92129231 Example (echoes the color of the syntax item under the
92139232 cursor): >
92149233 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
@@ -9223,6 +9242,8 @@ synIDtrans({synID}) *synIDtrans()*
92239242 highlight the character. Highlight links given with
92249243 ":highlight link" are followed.
92259244
9245+ Returns zero on error.
9246+
92269247 Can also be used as a | method | : >
92279248 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
92289249
@@ -9267,7 +9288,7 @@ synstack({lnum}, {col}) *synstack()*
92679288 echo synIDattr(id, "name")
92689289 endfor
92699290< When the position specified with {lnum} and {col} is invalid
9270- nothing is returned. The position just after the last
9291+ an empty List is returned. The position just after the last
92719292 character in a line and the first column in an empty line are
92729293 valid positions.
92739294
@@ -9381,6 +9402,8 @@ tabpagenr([{arg}]) *tabpagenr()*
93819402 previous tab page 0 is returned.
93829403 The number can be used with the | :tab | command.
93839404
9405+ Returns zero on error.
9406+
93849407
93859408tabpagewinnr({tabarg} [, {arg} ]) *tabpagewinnr()*
93869409 Like | winnr() | but for tab page {tabarg} .
@@ -9453,6 +9476,7 @@ tan({expr}) *tan()*
94539476 Return the tangent of {expr} , measured in radians, as a | Float |
94549477 in the range [-inf, inf].
94559478 {expr} must evaluate to a | Float | or a | Number | .
9479+ Returns 0.0 if {expr} is not a | Float | or a | Number | .
94569480 Examples: >
94579481 :echo tan(10)
94589482< 0.648361 >
@@ -9469,6 +9493,7 @@ tanh({expr}) *tanh()*
94699493 Return the hyperbolic tangent of {expr} as a | Float | in the
94709494 range [-1, 1].
94719495 {expr} must evaluate to a | Float | or a | Number | .
9496+ Returns 0.0 if {expr} is not a | Float | or a | Number | .
94729497 Examples: >
94739498 :echo tanh(0.5)
94749499< 0.462117 >
@@ -9598,6 +9623,8 @@ timer_start({time}, {callback} [, {options}])
95989623 Vim becomes unusable because of all the error
95999624 messages.
96009625
9626+ Returns -1 on error.
9627+
96019628 Example: >
96029629 func MyHandler(timer)
96039630 echo 'Handler called'
@@ -9633,15 +9660,15 @@ timer_stopall() *timer_stopall()*
96339660tolower({expr} ) *tolower()*
96349661 The result is a copy of the String given, with all uppercase
96359662 characters turned into lowercase (just like applying | gu | to
9636- the string).
9663+ the string). Returns an empty string on error.
96379664
96389665 Can also be used as a | method | : >
96399666 GetText()->tolower()
96409667
96419668 toupper({expr} ) *toupper()*
96429669 The result is a copy of the String given, with all lowercase
96439670 characters turned into uppercase (just like applying | gU | to
9644- the string).
9671+ the string). Returns an empty string on error.
96459672
96469673 Can also be used as a | method | : >
96479674 GetText()->toupper()
@@ -9654,6 +9681,8 @@ tr({src}, {fromstr}, {tostr}) *tr()*
96549681 and so on. Exactly like the unix "tr" command.
96559682 This code also deals with multibyte characters properly.
96569683
9684+ Returns an empty string on error.
9685+
96579686 Examples: >
96589687 echo tr("hello there", "ht", "HT")
96599688< returns "Hello THere" >
@@ -9679,6 +9708,7 @@ trim({text} [, {mask} [, {dir}]]) *trim()*
96799708 When omitted both ends are trimmed.
96809709
96819710 This function deals with multibyte characters properly.
9711+ Returns an empty string on error.
96829712
96839713 Examples: >
96849714 echo trim(" some text ")
@@ -9697,6 +9727,7 @@ trunc({expr}) *trunc()*
96979727 Return the largest integral value with magnitude less than or
96989728 equal to {expr} as a | Float | (truncate towards zero).
96999729 {expr} must evaluate to a | Float | or a | Number | .
9730+ Returns 0.0 if {expr} is not a | Float | or a | Number | .
97009731 Examples: >
97019732 echo trunc(1.456)
97029733< 1.0 >
@@ -9815,12 +9846,15 @@ uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
98159846< The default compare function uses the string representation of
98169847 each item. For the use of {func} and {dict} see | sort() | .
98179848
9849+ Returns zero if {list} is not a | List | .
9850+
98189851 Can also be used as a | method | : >
98199852 mylist->uniq()
98209853
98219854 values({dict} ) *values()*
98229855 Return a | List | with all the values of {dict} . The | List | is
98239856 in arbitrary order. Also see | items() | and | keys() | .
9857+ Returns zero if {dict} is not a | Dict | .
98249858
98259859 Can also be used as a | method | : >
98269860 mydict->values()
@@ -9988,6 +10022,8 @@ win_gettype([{nr}]) *win_gettype()*
998810022 popup window then 'buftype' is "terminal" and win_gettype()
998910023 returns "popup".
999010024
10025+ Return an empty string if the window cannot be found.
10026+
999110027 Can also be used as a | method | : >
999210028 GetWinid()->win_gettype()
999310029<
@@ -10025,6 +10061,8 @@ win_move_separator({nr}, {offset}) *win_move_separator()*
1002510061 specified (e.g., as a consequence of maintaining
1002610062 'winminwidth' ). Returns TRUE if the window can be found and
1002710063 FALSE otherwise.
10064+ This will fail for the rightmost window and a full-width
10065+ window, since it has no separator on the right.
1002810066
1002910067 Can also be used as a | method | : >
1003010068 GetWinnr()->win_move_separator(offset)
0 commit comments