comparison runtime/doc/builtin.txt @ 26777:629e7046ef63 v8.2.3917

patch 8.2.3917: the eval.txt help file is way too big Commit: https://github.com/vim/vim/commit/1cae5a0a034d0545360387407a7a409310f1efe2 Author: Bram Moolenaar <Bram@vim.org> Date: Mon Dec 27 21:28:34 2021 +0000 patch 8.2.3917: the eval.txt help file is way too big Problem: The eval.txt help file is way too big. Solution: Move the builtin function details to a separate file.
author Bram Moolenaar <Bram@vim.org>
date Mon, 27 Dec 2021 22:30:02 +0100
parents
children b7b82279426f
comparison
equal deleted inserted replaced
26776:7560ecdb2a6e 26777:629e7046ef63
1 *builtin.txt* For Vim version 8.2. Last change: 2021 Dec 27
2
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7 Builtin functions *builtin-functions*
8
9 Note: Expression evaluation can be disabled at compile time. If this has been
10 done, the builtin functions are not available. See |+eval| and
11 |no-eval-feature|.
12
13 1. Overview |builtin-function-list|
14 2. Details |builtin-function-details|
15 3. Feature list |feature-list|
16 4. Matching a pattern in a String |string-match|
17
18 ==============================================================================
19 1. Overview *builtin-function-list*
20
21 Use CTRL-] on the function name to jump to the full explanation.
22
23 USAGE RESULT DESCRIPTION ~
24
25 abs({expr}) Float or Number absolute value of {expr}
26 acos({expr}) Float arc cosine of {expr}
27 add({object}, {item}) List/Blob append {item} to {object}
28 and({expr}, {expr}) Number bitwise AND
29 append({lnum}, {text}) Number append {text} below line {lnum}
30 appendbufline({expr}, {lnum}, {text})
31 Number append {text} below line {lnum}
32 in buffer {expr}
33 argc([{winid}]) Number number of files in the argument list
34 argidx() Number current index in the argument list
35 arglistid([{winnr} [, {tabnr}]]) Number argument list id
36 argv({nr} [, {winid}]) String {nr} entry of the argument list
37 argv([-1, {winid}]) List the argument list
38 asin({expr}) Float arc sine of {expr}
39 assert_beeps({cmd}) Number assert {cmd} causes a beep
40 assert_equal({exp}, {act} [, {msg}])
41 Number assert {exp} is equal to {act}
42 assert_equalfile({fname-one}, {fname-two} [, {msg}])
43 Number assert file contents are equal
44 assert_exception({error} [, {msg}])
45 Number assert {error} is in v:exception
46 assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])
47 Number assert {cmd} fails
48 assert_false({actual} [, {msg}])
49 Number assert {actual} is false
50 assert_inrange({lower}, {upper}, {actual} [, {msg}])
51 Number assert {actual} is inside the range
52 assert_match({pat}, {text} [, {msg}])
53 Number assert {pat} matches {text}
54 assert_nobeep({cmd}) Number assert {cmd} does not cause a beep
55 assert_notequal({exp}, {act} [, {msg}])
56 Number assert {exp} is not equal {act}
57 assert_notmatch({pat}, {text} [, {msg}])
58 Number assert {pat} not matches {text}
59 assert_report({msg}) Number report a test failure
60 assert_true({actual} [, {msg}]) Number assert {actual} is true
61 atan({expr}) Float arc tangent of {expr}
62 atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
63 balloon_gettext() String current text in the balloon
64 balloon_show({expr}) none show {expr} inside the balloon
65 balloon_split({msg}) List split {msg} as used for a balloon
66 blob2list({blob}) List convert {blob} into a list of numbers
67 browse({save}, {title}, {initdir}, {default})
68 String put up a file requester
69 browsedir({title}, {initdir}) String put up a directory requester
70 bufadd({name}) Number add a buffer to the buffer list
71 bufexists({buf}) Number |TRUE| if buffer {buf} exists
72 buflisted({buf}) Number |TRUE| if buffer {buf} is listed
73 bufload({buf}) Number load buffer {buf} if not loaded yet
74 bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
75 bufname([{buf}]) String Name of the buffer {buf}
76 bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
77 bufwinid({buf}) Number window ID of buffer {buf}
78 bufwinnr({buf}) Number window number of buffer {buf}
79 byte2line({byte}) Number line number at byte count {byte}
80 byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
81 byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
82 call({func}, {arglist} [, {dict}])
83 any call {func} with arguments {arglist}
84 ceil({expr}) Float round {expr} up
85 ch_canread({handle}) Number check if there is something to read
86 ch_close({handle}) none close {handle}
87 ch_close_in({handle}) none close in part of {handle}
88 ch_evalexpr({handle}, {expr} [, {options}])
89 any evaluate {expr} on JSON {handle}
90 ch_evalraw({handle}, {string} [, {options}])
91 any evaluate {string} on raw {handle}
92 ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
93 ch_getjob({channel}) Job get the Job of {channel}
94 ch_info({handle}) String info about channel {handle}
95 ch_log({msg} [, {handle}]) none write {msg} in the channel log file
96 ch_logfile({fname} [, {mode}]) none start logging channel activity
97 ch_open({address} [, {options}])
98 Channel open a channel to {address}
99 ch_read({handle} [, {options}]) String read from {handle}
100 ch_readblob({handle} [, {options}])
101 Blob read Blob from {handle}
102 ch_readraw({handle} [, {options}])
103 String read raw from {handle}
104 ch_sendexpr({handle}, {expr} [, {options}])
105 any send {expr} over JSON {handle}
106 ch_sendraw({handle}, {expr} [, {options}])
107 any send {expr} over raw {handle}
108 ch_setoptions({handle}, {options})
109 none set options for {handle}
110 ch_status({handle} [, {options}])
111 String status of channel {handle}
112 changenr() Number current change number
113 char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
114 charclass({string}) Number character class of {string}
115 charcol({expr}) Number column number of cursor or mark
116 charidx({string}, {idx} [, {countcc}])
117 Number char index of byte {idx} in {string}
118 chdir({dir}) String change current working directory
119 cindent({lnum}) Number C indent for line {lnum}
120 clearmatches([{win}]) none clear all matches
121 col({expr}) Number column byte index of cursor or mark
122 complete({startcol}, {matches}) none set Insert mode completion
123 complete_add({expr}) Number add completion match
124 complete_check() Number check for key typed during completion
125 complete_info([{what}]) Dict get current completion information
126 confirm({msg} [, {choices} [, {default} [, {type}]]])
127 Number number of choice picked by user
128 copy({expr}) any make a shallow copy of {expr}
129 cos({expr}) Float cosine of {expr}
130 cosh({expr}) Float hyperbolic cosine of {expr}
131 count({comp}, {expr} [, {ic} [, {start}]])
132 Number count how many {expr} are in {comp}
133 cscope_connection([{num}, {dbpath} [, {prepend}]])
134 Number checks existence of cscope connection
135 cursor({lnum}, {col} [, {off}])
136 Number move cursor to {lnum}, {col}, {off}
137 cursor({list}) Number move cursor to position in {list}
138 debugbreak({pid}) Number interrupt process being debugged
139 deepcopy({expr} [, {noref}]) any make a full copy of {expr}
140 delete({fname} [, {flags}]) Number delete the file or directory {fname}
141 deletebufline({buf}, {first} [, {last}])
142 Number delete lines from buffer {buf}
143 did_filetype() Number |TRUE| if FileType autocmd event used
144 diff_filler({lnum}) Number diff filler lines about {lnum}
145 diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
146 digraph_get({chars}) String get the |digraph| of {chars}
147 digraph_getlist([{listall}]) List get all |digraph|s
148 digraph_set({chars}, {digraph}) Boolean register |digraph|
149 digraph_setlist({digraphlist}) Boolean register multiple |digraph|s
150 echoraw({expr}) none output {expr} as-is
151 empty({expr}) Number |TRUE| if {expr} is empty
152 environ() Dict return environment variables
153 escape({string}, {chars}) String escape {chars} in {string} with '\'
154 eval({string}) any evaluate {string} into its value
155 eventhandler() Number |TRUE| if inside an event handler
156 executable({expr}) Number 1 if executable {expr} exists
157 execute({command}) String execute {command} and get the output
158 exepath({expr}) String full path of the command {expr}
159 exists({expr}) Number |TRUE| if {expr} exists
160 exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
161 exp({expr}) Float exponential of {expr}
162 expand({expr} [, {nosuf} [, {list}]])
163 any expand special keywords in {expr}
164 expandcmd({expr}) String expand {expr} like with `:edit`
165 extend({expr1}, {expr2} [, {expr3}])
166 List/Dict insert items of {expr2} into {expr1}
167 extendnew({expr1}, {expr2} [, {expr3}])
168 List/Dict like |extend()| but creates a new
169 List or Dictionary
170 feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
171 filereadable({file}) Number |TRUE| if {file} is a readable file
172 filewritable({file}) Number |TRUE| if {file} is a writable file
173 filter({expr1}, {expr2}) List/Dict/Blob/String
174 remove items from {expr1} where
175 {expr2} is 0
176 finddir({name} [, {path} [, {count}]])
177 String find directory {name} in {path}
178 findfile({name} [, {path} [, {count}]])
179 String find file {name} in {path}
180 flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
181 flattennew({list} [, {maxdepth}])
182 List flatten a copy of {list}
183 float2nr({expr}) Number convert Float {expr} to a Number
184 floor({expr}) Float round {expr} down
185 fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
186 fnameescape({fname}) String escape special characters in {fname}
187 fnamemodify({fname}, {mods}) String modify file name
188 foldclosed({lnum}) Number first line of fold at {lnum} if closed
189 foldclosedend({lnum}) Number last line of fold at {lnum} if closed
190 foldlevel({lnum}) Number fold level at {lnum}
191 foldtext() String line displayed for closed fold
192 foldtextresult({lnum}) String text for closed fold at {lnum}
193 foreground() Number bring the Vim window to the foreground
194 fullcommand({name}) String get full command from {name}
195 funcref({name} [, {arglist}] [, {dict}])
196 Funcref reference to function {name}
197 function({name} [, {arglist}] [, {dict}])
198 Funcref named reference to function {name}
199 garbagecollect([{atexit}]) none free memory, breaking cyclic references
200 get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
201 get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
202 get({func}, {what}) any get property of funcref/partial {func}
203 getbufinfo([{buf}]) List information about buffers
204 getbufline({buf}, {lnum} [, {end}])
205 List lines {lnum} to {end} of buffer {buf}
206 getbufvar({buf}, {varname} [, {def}])
207 any variable {varname} in buffer {buf}
208 getchangelist([{buf}]) List list of change list items
209 getchar([expr]) Number or String
210 get one character from the user
211 getcharmod() Number modifiers for the last typed character
212 getcharpos({expr}) List position of cursor, mark, etc.
213 getcharsearch() Dict last character search
214 getcharstr([expr]) String get one character from the user
215 getcmdline() String return the current command-line
216 getcmdpos() Number return cursor position in command-line
217 getcmdtype() String return current command-line type
218 getcmdwintype() String return current command-line window type
219 getcompletion({pat}, {type} [, {filtered}])
220 List list of cmdline completion matches
221 getcurpos([{winnr}]) List position of the cursor
222 getcursorcharpos([{winnr}]) List character position of the cursor
223 getcwd([{winnr} [, {tabnr}]]) String get the current working directory
224 getenv({name}) String return environment variable
225 getfontname([{name}]) String name of font being used
226 getfperm({fname}) String file permissions of file {fname}
227 getfsize({fname}) Number size in bytes of file {fname}
228 getftime({fname}) Number last modification time of file
229 getftype({fname}) String description of type of file {fname}
230 getimstatus() Number |TRUE| if the IME status is active
231 getjumplist([{winnr} [, {tabnr}]])
232 List list of jump list items
233 getline({lnum}) String line {lnum} of current buffer
234 getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
235 getloclist({nr}) List list of location list items
236 getloclist({nr}, {what}) Dict get specific location list properties
237 getmarklist([{buf}]) List list of global/local marks
238 getmatches([{win}]) List list of current matches
239 getmousepos() Dict last known mouse position
240 getpid() Number process ID of Vim
241 getpos({expr}) List position of cursor, mark, etc.
242 getqflist() List list of quickfix items
243 getqflist({what}) Dict get specific quickfix list properties
244 getreg([{regname} [, 1 [, {list}]]])
245 String or List contents of a register
246 getreginfo([{regname}]) Dict information about a register
247 getregtype([{regname}]) String type of a register
248 gettabinfo([{expr}]) List list of tab pages
249 gettabvar({nr}, {varname} [, {def}])
250 any variable {varname} in tab {nr} or {def}
251 gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
252 any {name} in {winnr} in tab page {tabnr}
253 gettagstack([{nr}]) Dict get the tag stack of window {nr}
254 gettext({text}) String lookup translation of {text}
255 getwininfo([{winid}]) List list of info about each window
256 getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
257 getwinposx() Number X coord in pixels of the Vim window
258 getwinposy() Number Y coord in pixels of the Vim window
259 getwinvar({nr}, {varname} [, {def}])
260 any variable {varname} in window {nr}
261 glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
262 any expand file wildcards in {expr}
263 glob2regpat({expr}) String convert a glob pat into a search pat
264 globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
265 String do glob({expr}) for all dirs in {path}
266 has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
267 has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
268 haslocaldir([{winnr} [, {tabnr}]])
269 Number |TRUE| if the window executed |:lcd|
270 or |:tcd|
271 hasmapto({what} [, {mode} [, {abbr}]])
272 Number |TRUE| if mapping to {what} exists
273 histadd({history}, {item}) Number add an item to a history
274 histdel({history} [, {item}]) Number remove an item from a history
275 histget({history} [, {index}]) String get the item {index} from a history
276 histnr({history}) Number highest index of a history
277 hlID({name}) Number syntax ID of highlight group {name}
278 hlexists({name}) Number |TRUE| if highlight group {name} exists
279 hlget([{name} [, {resolve}]]) List get highlight group attributes
280 hlset({list}) Number set highlight group attributes
281 hostname() String name of the machine Vim is running on
282 iconv({expr}, {from}, {to}) String convert encoding of {expr}
283 indent({lnum}) Number indent of line {lnum}
284 index({object}, {expr} [, {start} [, {ic}]])
285 Number index in {object} where {expr} appears
286 input({prompt} [, {text} [, {completion}]])
287 String get input from the user
288 inputdialog({prompt} [, {text} [, {completion}]])
289 String like input() but in a GUI dialog
290 inputlist({textlist}) Number let the user pick from a choice list
291 inputrestore() Number restore typeahead
292 inputsave() Number save and clear typeahead
293 inputsecret({prompt} [, {text}]) String like input() but hiding the text
294 insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
295 interrupt() none interrupt script execution
296 invert({expr}) Number bitwise invert
297 isdirectory({directory}) Number |TRUE| if {directory} is a directory
298 isinf({expr}) Number determine if {expr} is infinity value
299 (positive or negative)
300 islocked({expr}) Number |TRUE| if {expr} is locked
301 isnan({expr}) Number |TRUE| if {expr} is NaN
302 items({dict}) List key-value pairs in {dict}
303 job_getchannel({job}) Channel get the channel handle for {job}
304 job_info([{job}]) Dict get information about {job}
305 job_setoptions({job}, {options}) none set options for {job}
306 job_start({command} [, {options}])
307 Job start a job
308 job_status({job}) String get the status of {job}
309 job_stop({job} [, {how}]) Number stop {job}
310 join({list} [, {sep}]) String join {list} items into one String
311 js_decode({string}) any decode JS style JSON
312 js_encode({expr}) String encode JS style JSON
313 json_decode({string}) any decode JSON
314 json_encode({expr}) String encode JSON
315 keys({dict}) List keys in {dict}
316 len({expr}) Number the length of {expr}
317 libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
318 libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
319 line({expr} [, {winid}]) Number line nr of cursor, last line or mark
320 line2byte({lnum}) Number byte count of line {lnum}
321 lispindent({lnum}) Number Lisp indent for line {lnum}
322 list2blob({list}) Blob turn {list} of numbers into a Blob
323 list2str({list} [, {utf8}]) String turn {list} of numbers into a String
324 listener_add({callback} [, {buf}])
325 Number add a callback to listen to changes
326 listener_flush([{buf}]) none invoke listener callbacks
327 listener_remove({id}) none remove a listener callback
328 localtime() Number current time
329 log({expr}) Float natural logarithm (base e) of {expr}
330 log10({expr}) Float logarithm of Float {expr} to base 10
331 luaeval({expr} [, {expr}]) any evaluate |Lua| expression
332 map({expr1}, {expr2}) List/Dict/Blob/String
333 change each item in {expr1} to {expr2}
334 maparg({name} [, {mode} [, {abbr} [, {dict}]]])
335 String or Dict
336 rhs of mapping {name} in mode {mode}
337 mapcheck({name} [, {mode} [, {abbr}]])
338 String check for mappings matching {name}
339 mapnew({expr1}, {expr2}) List/Dict/Blob/String
340 like |map()| but creates a new List or
341 Dictionary
342 mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
343 match({expr}, {pat} [, {start} [, {count}]])
344 Number position where {pat} matches in {expr}
345 matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
346 Number highlight {pattern} with {group}
347 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
348 Number highlight positions with {group}
349 matcharg({nr}) List arguments of |:match|
350 matchdelete({id} [, {win}]) Number delete match identified by {id}
351 matchend({expr}, {pat} [, {start} [, {count}]])
352 Number position where {pat} ends in {expr}
353 matchfuzzy({list}, {str} [, {dict}])
354 List fuzzy match {str} in {list}
355 matchfuzzypos({list}, {str} [, {dict}])
356 List fuzzy match {str} in {list}
357 matchlist({expr}, {pat} [, {start} [, {count}]])
358 List match and submatches of {pat} in {expr}
359 matchstr({expr}, {pat} [, {start} [, {count}]])
360 String {count}'th match of {pat} in {expr}
361 matchstrpos({expr}, {pat} [, {start} [, {count}]])
362 List {count}'th match of {pat} in {expr}
363 max({expr}) Number maximum value of items in {expr}
364 menu_info({name} [, {mode}]) Dict get menu item information
365 min({expr}) Number minimum value of items in {expr}
366 mkdir({name} [, {path} [, {prot}]])
367 Number create directory {name}
368 mode([expr]) String current editing mode
369 mzeval({expr}) any evaluate |MzScheme| expression
370 nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
371 nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
372 or({expr}, {expr}) Number bitwise OR
373 pathshorten({expr} [, {len}]) String shorten directory names in a path
374 perleval({expr}) any evaluate |Perl| expression
375 popup_atcursor({what}, {options}) Number create popup window near the cursor
376 popup_beval({what}, {options}) Number create popup window for 'ballooneval'
377 popup_clear() none close all popup windows
378 popup_close({id} [, {result}]) none close popup window {id}
379 popup_create({what}, {options}) Number create a popup window
380 popup_dialog({what}, {options}) Number create a popup window used as a dialog
381 popup_filter_menu({id}, {key}) Number filter for a menu popup window
382 popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
383 popup_findinfo() Number get window ID of info popup window
384 popup_findpreview() Number get window ID of preview popup window
385 popup_getoptions({id}) Dict get options of popup window {id}
386 popup_getpos({id}) Dict get position of popup window {id}
387 popup_hide({id}) none hide popup menu {id}
388 popup_list() List get a list of window IDs of all popups
389 popup_locate({row}, {col}) Number get window ID of popup at position
390 popup_menu({what}, {options}) Number create a popup window used as a menu
391 popup_move({id}, {options}) none set position of popup window {id}
392 popup_notification({what}, {options})
393 Number create a notification popup window
394 popup_setoptions({id}, {options})
395 none set options for popup window {id}
396 popup_settext({id}, {text}) none set the text of popup window {id}
397 popup_show({id}) none unhide popup window {id}
398 pow({x}, {y}) Float {x} to the power of {y}
399 prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
400 printf({fmt}, {expr1}...) String format text
401 prompt_getprompt({buf}) String get prompt text
402 prompt_setcallback({buf}, {expr}) none set prompt callback function
403 prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
404 prompt_setprompt({buf}, {text}) none set prompt text
405 prop_add({lnum}, {col}, {props}) none add one text property
406 prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
407 none add multiple text properties
408 prop_clear({lnum} [, {lnum-end} [, {props}]])
409 none remove all text properties
410 prop_find({props} [, {direction}])
411 Dict search for a text property
412 prop_list({lnum} [, {props}]) List text properties in {lnum}
413 prop_remove({props} [, {lnum} [, {lnum-end}]])
414 Number remove a text property
415 prop_type_add({name}, {props}) none define a new property type
416 prop_type_change({name}, {props})
417 none change an existing property type
418 prop_type_delete({name} [, {props}])
419 none delete a property type
420 prop_type_get({name} [, {props}])
421 Dict get property type values
422 prop_type_list([{props}]) List get list of property types
423 pum_getpos() Dict position and size of pum if visible
424 pumvisible() Number whether popup menu is visible
425 py3eval({expr}) any evaluate |python3| expression
426 pyeval({expr}) any evaluate |Python| expression
427 pyxeval({expr}) any evaluate |python_x| expression
428 rand([{expr}]) Number get pseudo-random number
429 range({expr} [, {max} [, {stride}]])
430 List items from {expr} to {max}
431 readblob({fname}) Blob read a |Blob| from {fname}
432 readdir({dir} [, {expr} [, {dict}]])
433 List file names in {dir} selected by {expr}
434 readdirex({dir} [, {expr} [, {dict}]])
435 List file info in {dir} selected by {expr}
436 readfile({fname} [, {type} [, {max}]])
437 List get list of lines from file {fname}
438 reduce({object}, {func} [, {initial}])
439 any reduce {object} using {func}
440 reg_executing() String get the executing register name
441 reg_recording() String get the recording register name
442 reltime([{start} [, {end}]]) List get time value
443 reltimefloat({time}) Float turn the time value into a Float
444 reltimestr({time}) String turn time value into a String
445 remote_expr({server}, {string} [, {idvar} [, {timeout}]])
446 String send expression
447 remote_foreground({server}) Number bring Vim server to the foreground
448 remote_peek({serverid} [, {retvar}])
449 Number check for reply string
450 remote_read({serverid} [, {timeout}])
451 String read reply string
452 remote_send({server}, {string} [, {idvar}])
453 String send key sequence
454 remote_startserver({name}) none become server {name}
455 remove({list}, {idx} [, {end}]) any/List
456 remove items {idx}-{end} from {list}
457 remove({blob}, {idx} [, {end}]) Number/Blob
458 remove bytes {idx}-{end} from {blob}
459 remove({dict}, {key}) any remove entry {key} from {dict}
460 rename({from}, {to}) Number rename (move) file from {from} to {to}
461 repeat({expr}, {count}) String repeat {expr} {count} times
462 resolve({filename}) String get filename a shortcut points to
463 reverse({list}) List reverse {list} in-place
464 round({expr}) Float round off {expr}
465 rubyeval({expr}) any evaluate |Ruby| expression
466 screenattr({row}, {col}) Number attribute at screen position
467 screenchar({row}, {col}) Number character at screen position
468 screenchars({row}, {col}) List List of characters at screen position
469 screencol() Number current cursor column
470 screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
471 screenrow() Number current cursor row
472 screenstring({row}, {col}) String characters at screen position
473 search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
474 Number search for {pattern}
475 searchcount([{options}]) Dict get or update search stats
476 searchdecl({name} [, {global} [, {thisblock}]])
477 Number search for variable declaration
478 searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
479 Number search for other end of start/end pair
480 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
481 List search for other end of start/end pair
482 searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
483 List search for {pattern}
484 server2client({clientid}, {string})
485 Number send reply string
486 serverlist() String get a list of available servers
487 setbufline({expr}, {lnum}, {text})
488 Number set line {lnum} to {text} in buffer
489 {expr}
490 setbufvar({buf}, {varname}, {val})
491 none set {varname} in buffer {buf} to {val}
492 setcellwidths({list}) none set character cell width overrides
493 setcharpos({expr}, {list}) Number set the {expr} position to {list}
494 setcharsearch({dict}) Dict set character search from {dict}
495 setcmdpos({pos}) Number set cursor position in command-line
496 setcursorcharpos({list}) Number move cursor to position in {list}
497 setenv({name}, {val}) none set environment variable
498 setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
499 setline({lnum}, {line}) Number set line {lnum} to {line}
500 setloclist({nr}, {list} [, {action}])
501 Number modify location list using {list}
502 setloclist({nr}, {list}, {action}, {what})
503 Number modify specific location list props
504 setmatches({list} [, {win}]) Number restore a list of matches
505 setpos({expr}, {list}) Number set the {expr} position to {list}
506 setqflist({list} [, {action}]) Number modify quickfix list using {list}
507 setqflist({list}, {action}, {what})
508 Number modify specific quickfix list props
509 setreg({n}, {v} [, {opt}]) Number set register to value and type
510 settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
511 settabwinvar({tabnr}, {winnr}, {varname}, {val})
512 none set {varname} in window {winnr} in tab
513 page {tabnr} to {val}
514 settagstack({nr}, {dict} [, {action}])
515 Number modify tag stack using {dict}
516 setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
517 sha256({string}) String SHA256 checksum of {string}
518 shellescape({string} [, {special}])
519 String escape {string} for use as shell
520 command argument
521 shiftwidth([{col}]) Number effective value of 'shiftwidth'
522 sign_define({name} [, {dict}]) Number define or update a sign
523 sign_define({list}) List define or update a list of signs
524 sign_getdefined([{name}]) List get a list of defined signs
525 sign_getplaced([{buf} [, {dict}]])
526 List get a list of placed signs
527 sign_jump({id}, {group}, {buf})
528 Number jump to a sign
529 sign_place({id}, {group}, {name}, {buf} [, {dict}])
530 Number place a sign
531 sign_placelist({list}) List place a list of signs
532 sign_undefine([{name}]) Number undefine a sign
533 sign_undefine({list}) List undefine a list of signs
534 sign_unplace({group} [, {dict}])
535 Number unplace a sign
536 sign_unplacelist({list}) List unplace a list of signs
537 simplify({filename}) String simplify filename as much as possible
538 sin({expr}) Float sine of {expr}
539 sinh({expr}) Float hyperbolic sine of {expr}
540 slice({expr}, {start} [, {end}]) String, List or Blob
541 slice of a String, List or Blob
542 sort({list} [, {func} [, {dict}]])
543 List sort {list}, using {func} to compare
544 sound_clear() none stop playing all sounds
545 sound_playevent({name} [, {callback}])
546 Number play an event sound
547 sound_playfile({path} [, {callback}])
548 Number play sound file {path}
549 sound_stop({id}) none stop playing sound {id}
550 soundfold({word}) String sound-fold {word}
551 spellbadword() String badly spelled word at cursor
552 spellsuggest({word} [, {max} [, {capital}]])
553 List spelling suggestions
554 split({expr} [, {pat} [, {keepempty}]])
555 List make |List| from {pat} separated {expr}
556 sqrt({expr}) Float square root of {expr}
557 srand([{expr}]) List get seed for |rand()|
558 state([{what}]) String current state of Vim
559 str2float({expr} [, {quoted}]) Float convert String to Float
560 str2list({expr} [, {utf8}]) List convert each character of {expr} to
561 ASCII/UTF-8 value
562 str2nr({expr} [, {base} [, {quoted}]])
563 Number convert String to Number
564 strcharlen({expr}) Number character length of the String {expr}
565 strcharpart({str}, {start} [, {len} [, {skipcc}]])
566 String {len} characters of {str} at
567 character {start}
568 strchars({expr} [, {skipcc}]) Number character count of the String {expr}
569 strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
570 strftime({format} [, {time}]) String format time with a specified format
571 strgetchar({str}, {index}) Number get char {index} from {str}
572 stridx({haystack}, {needle} [, {start}])
573 Number index of {needle} in {haystack}
574 string({expr}) String String representation of {expr} value
575 strlen({expr}) Number length of the String {expr}
576 strpart({str}, {start} [, {len} [, {chars}]])
577 String {len} bytes/chars of {str} at
578 byte {start}
579 strptime({format}, {timestring})
580 Number Convert {timestring} to unix timestamp
581 strridx({haystack}, {needle} [, {start}])
582 Number last index of {needle} in {haystack}
583 strtrans({expr}) String translate string to make it printable
584 strwidth({expr}) Number display cell length of the String {expr}
585 submatch({nr} [, {list}]) String or List
586 specific match in ":s" or substitute()
587 substitute({expr}, {pat}, {sub}, {flags})
588 String all {pat} in {expr} replaced with {sub}
589 swapinfo({fname}) Dict information about swap file {fname}
590 swapname({buf}) String swap file of buffer {buf}
591 synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
592 synIDattr({synID}, {what} [, {mode}])
593 String attribute {what} of syntax ID {synID}
594 synIDtrans({synID}) Number translated syntax ID of {synID}
595 synconcealed({lnum}, {col}) List info about concealing
596 synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
597 system({expr} [, {input}]) String output of shell command/filter {expr}
598 systemlist({expr} [, {input}]) List output of shell command/filter {expr}
599 tabpagebuflist([{arg}]) List list of buffer numbers in tab page
600 tabpagenr([{arg}]) Number number of current or last tab page
601 tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
602 tagfiles() List tags files used
603 taglist({expr} [, {filename}]) List list of tags matching {expr}
604 tan({expr}) Float tangent of {expr}
605 tanh({expr}) Float hyperbolic tangent of {expr}
606 tempname() String name for a temporary file
607 term_dumpdiff({filename}, {filename} [, {options}])
608 Number display difference between two dumps
609 term_dumpload({filename} [, {options}])
610 Number displaying a screen dump
611 term_dumpwrite({buf}, {filename} [, {options}])
612 none dump terminal window contents
613 term_getaltscreen({buf}) Number get the alternate screen flag
614 term_getansicolors({buf}) List get ANSI palette in GUI color mode
615 term_getattr({attr}, {what}) Number get the value of attribute {what}
616 term_getcursor({buf}) List get the cursor position of a terminal
617 term_getjob({buf}) Job get the job associated with a terminal
618 term_getline({buf}, {row}) String get a line of text from a terminal
619 term_getscrolled({buf}) Number get the scroll count of a terminal
620 term_getsize({buf}) List get the size of a terminal
621 term_getstatus({buf}) String get the status of a terminal
622 term_gettitle({buf}) String get the title of a terminal
623 term_gettty({buf}, [{input}]) String get the tty name of a terminal
624 term_list() List get the list of terminal buffers
625 term_scrape({buf}, {row}) List get row of a terminal screen
626 term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
627 term_setansicolors({buf}, {colors})
628 none set ANSI palette in GUI color mode
629 term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
630 term_setkill({buf}, {how}) none set signal to stop job in terminal
631 term_setrestore({buf}, {command}) none set command to restore terminal
632 term_setsize({buf}, {rows}, {cols})
633 none set the size of a terminal
634 term_start({cmd} [, {options}]) Number open a terminal window and run a job
635 term_wait({buf} [, {time}]) Number wait for screen to be updated
636 terminalprops() Dict properties of the terminal
637 test_alloc_fail({id}, {countdown}, {repeat})
638 none make memory allocation fail
639 test_autochdir() none enable 'autochdir' during startup
640 test_feedinput({string}) none add key sequence to input buffer
641 test_garbagecollect_now() none free memory right now for testing
642 test_garbagecollect_soon() none free memory soon for testing
643 test_getvalue({string}) any get value of an internal variable
644 test_gui_drop_files({list}, {row}, {col}, {mods})
645 none drop a list of files in a window
646 test_gui_mouse_event({button}, {row}, {col}, {repeated}, {mods})
647 none add a mouse event to the input buffer
648 test_ignore_error({expr}) none ignore a specific error
649 test_null_blob() Blob null value for testing
650 test_null_channel() Channel null value for testing
651 test_null_dict() Dict null value for testing
652 test_null_function() Funcref null value for testing
653 test_null_job() Job null value for testing
654 test_null_list() List null value for testing
655 test_null_partial() Funcref null value for testing
656 test_null_string() String null value for testing
657 test_option_not_set({name}) none reset flag indicating option was set
658 test_override({expr}, {val}) none test with Vim internal overrides
659 test_refcount({expr}) Number get the reference count of {expr}
660 test_scrollbar({which}, {value}, {dragging})
661 none scroll in the GUI for testing
662 test_setmouse({row}, {col}) none set the mouse position for testing
663 test_settime({expr}) none set current time for testing
664 test_srand_seed([seed]) none set seed for testing srand()
665 test_unknown() any unknown value for testing
666 test_void() any void value for testing
667 timer_info([{id}]) List information about timers
668 timer_pause({id}, {pause}) none pause or unpause a timer
669 timer_start({time}, {callback} [, {options}])
670 Number create a timer
671 timer_stop({timer}) none stop a timer
672 timer_stopall() none stop all timers
673 tolower({expr}) String the String {expr} switched to lowercase
674 toupper({expr}) String the String {expr} switched to uppercase
675 tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
676 to chars in {tostr}
677 trim({text} [, {mask} [, {dir}]])
678 String trim characters in {mask} from {text}
679 trunc({expr}) Float truncate Float {expr}
680 type({expr}) Number type of value {expr}
681 typename({expr}) String representation of the type of {expr}
682 undofile({name}) String undo file name for {name}
683 undotree() List undo file tree
684 uniq({list} [, {func} [, {dict}]])
685 List remove adjacent duplicates from a list
686 values({dict}) List values in {dict}
687 virtcol({expr}) Number screen column of cursor or mark
688 visualmode([expr]) String last visual mode used
689 wildmenumode() Number whether 'wildmenu' mode is active
690 win_execute({id}, {command} [, {silent}])
691 String execute {command} in window {id}
692 win_findbuf({bufnr}) List find windows containing {bufnr}
693 win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
694 win_gettype([{nr}]) String type of window {nr}
695 win_gotoid({expr}) Number go to window with ID {expr}
696 win_id2tabwin({expr}) List get tab and window nr from window ID
697 win_id2win({expr}) Number get window nr from window ID
698 win_screenpos({nr}) List get screen position of window {nr}
699 win_splitmove({nr}, {target} [, {options}])
700 Number move window {nr} to split of {target}
701 winbufnr({nr}) Number buffer number of window {nr}
702 wincol() Number window column of the cursor
703 windowsversion() String MS-Windows OS version
704 winheight({nr}) Number height of window {nr}
705 winlayout([{tabnr}]) List layout of windows in tab {tabnr}
706 winline() Number window line of the cursor
707 winnr([{expr}]) Number number of current window
708 winrestcmd() String returns command to restore window sizes
709 winrestview({dict}) none restore view of current window
710 winsaveview() Dict save view of current window
711 winwidth({nr}) Number width of window {nr}
712 wordcount() Dict get byte/char/word statistics
713 writefile({object}, {fname} [, {flags}])
714 Number write |Blob| or |List| of lines to file
715 xor({expr}, {expr}) Number bitwise XOR
716
717 ==============================================================================
718 2. Details *builtin-function-details*
719
720 Not all functions are here, some have been moved to a help file covering the
721 specific functionality.
722
723 abs({expr}) *abs()*
724 Return the absolute value of {expr}. When {expr} evaluates to
725 a |Float| abs() returns a |Float|. When {expr} can be
726 converted to a |Number| abs() returns a |Number|. Otherwise
727 abs() gives an error message and returns -1.
728 Examples: >
729 echo abs(1.456)
730 < 1.456 >
731 echo abs(-5.456)
732 < 5.456 >
733 echo abs(-4)
734 < 4
735
736 Can also be used as a |method|: >
737 Compute()->abs()
738
739 < {only available when compiled with the |+float| feature}
740
741
742 acos({expr}) *acos()*
743 Return the arc cosine of {expr} measured in radians, as a
744 |Float| in the range of [0, pi].
745 {expr} must evaluate to a |Float| or a |Number| in the range
746 [-1, 1].
747 Examples: >
748 :echo acos(0)
749 < 1.570796 >
750 :echo acos(-0.5)
751 < 2.094395
752
753 Can also be used as a |method|: >
754 Compute()->acos()
755
756 < {only available when compiled with the |+float| feature}
757
758
759 add({object}, {expr}) *add()*
760 Append the item {expr} to |List| or |Blob| {object}. Returns
761 the resulting |List| or |Blob|. Examples: >
762 :let alist = add([1, 2, 3], item)
763 :call add(mylist, "woodstock")
764 < Note that when {expr} is a |List| it is appended as a single
765 item. Use |extend()| to concatenate |Lists|.
766 When {object} is a |Blob| then {expr} must be a number.
767 Use |insert()| to add an item at another position.
768
769 Can also be used as a |method|: >
770 mylist->add(val1)->add(val2)
771
772
773 and({expr}, {expr}) *and()*
774 Bitwise AND on the two arguments. The arguments are converted
775 to a number. A List, Dict or Float argument causes an error.
776 Example: >
777 :let flag = and(bits, 0x80)
778 < Can also be used as a |method|: >
779 :let flag = bits->and(0x80)
780
781
782 append({lnum}, {text}) *append()*
783 When {text} is a |List|: Append each item of the |List| as a
784 text line below line {lnum} in the current buffer.
785 Otherwise append {text} as one text line below line {lnum} in
786 the current buffer.
787 Any type of item is accepted and converted to a String.
788 {lnum} can be zero to insert a line before the first one.
789 {lnum} is used like with |getline()|.
790 Returns 1 for failure ({lnum} out of range or out of memory),
791 0 for success. In |Vim9| script an invalid argument or
792 negative number results in an error. Example: >
793 :let failed = append(line('$'), "# THE END")
794 :let failed = append(0, ["Chapter 1", "the beginning"])
795
796 < Can also be used as a |method| after a List, the base is
797 passed as the second argument: >
798 mylist->append(lnum)
799
800
801 appendbufline({buf}, {lnum}, {text}) *appendbufline()*
802 Like |append()| but append the text in buffer {buf}.
803
804 This function works only for loaded buffers. First call
805 |bufload()| if needed.
806
807 For the use of {buf}, see |bufname()|.
808
809 {lnum} is used like with |append()|. Note that using |line()|
810 would use the current buffer, not the one appending to.
811 Use "$" to append at the end of the buffer.
812
813 On success 0 is returned, on failure 1 is returned.
814 In |Vim9| script an error is given for an invalid {lnum}.
815
816 If {buf} is not a valid buffer or {lnum} is not valid, an
817 error message is given. Example: >
818 :let failed = appendbufline(13, 0, "# THE START")
819 <
820 Can also be used as a |method| after a List, the base is
821 passed as the second argument: >
822 mylist->appendbufline(buf, lnum)
823
824
825 argc([{winid}]) *argc()*
826 The result is the number of files in the argument list. See
827 |arglist|.
828 If {winid} is not supplied, the argument list of the current
829 window is used.
830 If {winid} is -1, the global argument list is used.
831 Otherwise {winid} specifies the window of which the argument
832 list is used: either the window number or the window ID.
833 Returns -1 if the {winid} argument is invalid.
834
835 *argidx()*
836 argidx() The result is the current index in the argument list. 0 is
837 the first file. argc() - 1 is the last one. See |arglist|.
838
839 *arglistid()*
840 arglistid([{winnr} [, {tabnr}]])
841 Return the argument list ID. This is a number which
842 identifies the argument list being used. Zero is used for the
843 global argument list. See |arglist|.
844 Returns -1 if the arguments are invalid.
845
846 Without arguments use the current window.
847 With {winnr} only use this window in the current tab page.
848 With {winnr} and {tabnr} use the window in the specified tab
849 page.
850 {winnr} can be the window number or the |window-ID|.
851
852 *argv()*
853 argv([{nr} [, {winid}]])
854 The result is the {nr}th file in the argument list. See
855 |arglist|. "argv(0)" is the first one. Example: >
856 :let i = 0
857 :while i < argc()
858 : let f = escape(fnameescape(argv(i)), '.')
859 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
860 : let i = i + 1
861 :endwhile
862 < Without the {nr} argument, or when {nr} is -1, a |List| with
863 the whole |arglist| is returned.
864
865 The {winid} argument specifies the window ID, see |argc()|.
866 For the Vim command line arguments see |v:argv|.
867
868 asin({expr}) *asin()*
869 Return the arc sine of {expr} measured in radians, as a |Float|
870 in the range of [-pi/2, pi/2].
871 {expr} must evaluate to a |Float| or a |Number| in the range
872 [-1, 1].
873 Examples: >
874 :echo asin(0.8)
875 < 0.927295 >
876 :echo asin(-0.5)
877 < -0.523599
878
879 Can also be used as a |method|: >
880 Compute()->asin()
881 <
882 {only available when compiled with the |+float| feature}
883
884
885 assert_ functions are documented here: |assert-functions-details|
886
887
888
889 atan({expr}) *atan()*
890 Return the principal value of the arc tangent of {expr}, in
891 the range [-pi/2, +pi/2] radians, as a |Float|.
892 {expr} must evaluate to a |Float| or a |Number|.
893 Examples: >
894 :echo atan(100)
895 < 1.560797 >
896 :echo atan(-4.01)
897 < -1.326405
898
899 Can also be used as a |method|: >
900 Compute()->atan()
901 <
902 {only available when compiled with the |+float| feature}
903
904
905 atan2({expr1}, {expr2}) *atan2()*
906 Return the arc tangent of {expr1} / {expr2}, measured in
907 radians, as a |Float| in the range [-pi, pi].
908 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
909 Examples: >
910 :echo atan2(-1, 1)
911 < -0.785398 >
912 :echo atan2(1, -1)
913 < 2.356194
914
915 Can also be used as a |method|: >
916 Compute()->atan2(1)
917 <
918 {only available when compiled with the |+float| feature}
919
920 balloon_gettext() *balloon_gettext()*
921 Return the current text in the balloon. Only for the string,
922 not used for the List.
923
924 balloon_show({expr}) *balloon_show()*
925 Show {expr} inside the balloon. For the GUI {expr} is used as
926 a string. For a terminal {expr} can be a list, which contains
927 the lines of the balloon. If {expr} is not a list it will be
928 split with |balloon_split()|.
929 If {expr} is an empty string any existing balloon is removed.
930
931 Example: >
932 func GetBalloonContent()
933 " ... initiate getting the content
934 return ''
935 endfunc
936 set balloonexpr=GetBalloonContent()
937
938 func BalloonCallback(result)
939 call balloon_show(a:result)
940 endfunc
941 < Can also be used as a |method|: >
942 GetText()->balloon_show()
943 <
944 The intended use is that fetching the content of the balloon
945 is initiated from 'balloonexpr'. It will invoke an
946 asynchronous method, in which a callback invokes
947 balloon_show(). The 'balloonexpr' itself can return an
948 empty string or a placeholder.
949
950 When showing a balloon is not possible nothing happens, no
951 error message.
952 {only available when compiled with the |+balloon_eval| or
953 |+balloon_eval_term| feature}
954
955 balloon_split({msg}) *balloon_split()*
956 Split String {msg} into lines to be displayed in a balloon.
957 The splits are made for the current window size and optimize
958 to show debugger output.
959 Returns a |List| with the split lines.
960 Can also be used as a |method|: >
961 GetText()->balloon_split()->balloon_show()
962
963 < {only available when compiled with the |+balloon_eval_term|
964 feature}
965
966 blob2list({blob}) *blob2list()*
967 Return a List containing the number value of each byte in Blob
968 {blob}. Examples: >
969 blob2list(0z0102.0304) returns [1, 2, 3, 4]
970 blob2list(0z) returns []
971 < Returns an empty List on error. |list2blob()| does the
972 opposite.
973
974 Can also be used as a |method|: >
975 GetBlob()->blob2list()
976
977 *browse()*
978 browse({save}, {title}, {initdir}, {default})
979 Put up a file requester. This only works when "has("browse")"
980 returns |TRUE| (only in some GUI versions).
981 The input fields are:
982 {save} when |TRUE|, select file to write
983 {title} title for the requester
984 {initdir} directory to start browsing in
985 {default} default file name
986 An empty string is returned when the "Cancel" button is hit,
987 something went wrong, or browsing is not possible.
988
989 *browsedir()*
990 browsedir({title}, {initdir})
991 Put up a directory requester. This only works when
992 "has("browse")" returns |TRUE| (only in some GUI versions).
993 On systems where a directory browser is not supported a file
994 browser is used. In that case: select a file in the directory
995 to be used.
996 The input fields are:
997 {title} title for the requester
998 {initdir} directory to start browsing in
999 When the "Cancel" button is hit, something went wrong, or
1000 browsing is not possible, an empty string is returned.
1001
1002 bufadd({name}) *bufadd()*
1003 Add a buffer to the buffer list with String {name}.
1004 If a buffer for file {name} already exists, return that buffer
1005 number. Otherwise return the buffer number of the newly
1006 created buffer. When {name} is an empty string then a new
1007 buffer is always created.
1008 The buffer will not have 'buflisted' set and not be loaded
1009 yet. To add some text to the buffer use this: >
1010 let bufnr = bufadd('someName')
1011 call bufload(bufnr)
1012 call setbufline(bufnr, 1, ['some', 'text'])
1013 < Can also be used as a |method|: >
1014 let bufnr = 'somename'->bufadd()
1015
1016 bufexists({buf}) *bufexists()*
1017 The result is a Number, which is |TRUE| if a buffer called
1018 {buf} exists.
1019 If the {buf} argument is a number, buffer numbers are used.
1020 Number zero is the alternate buffer for the current window.
1021
1022 If the {buf} argument is a string it must match a buffer name
1023 exactly. The name can be:
1024 - Relative to the current directory.
1025 - A full path.
1026 - The name of a buffer with 'buftype' set to "nofile".
1027 - A URL name.
1028 Unlisted buffers will be found.
1029 Note that help files are listed by their short name in the
1030 output of |:buffers|, but bufexists() requires using their
1031 long name to be able to find them.
1032 bufexists() may report a buffer exists, but to use the name
1033 with a |:buffer| command you may need to use |expand()|. Esp
1034 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1035 Use "bufexists(0)" to test for the existence of an alternate
1036 file name.
1037
1038 Can also be used as a |method|: >
1039 let exists = 'somename'->bufexists()
1040 <
1041 Obsolete name: buffer_exists(). *buffer_exists()*
1042
1043 buflisted({buf}) *buflisted()*
1044 The result is a Number, which is |TRUE| if a buffer called
1045 {buf} exists and is listed (has the 'buflisted' option set).
1046 The {buf} argument is used like with |bufexists()|.
1047
1048 Can also be used as a |method|: >
1049 let listed = 'somename'->buflisted()
1050
1051 bufload({buf}) *bufload()*
1052 Ensure the buffer {buf} is loaded. When the buffer name
1053 refers to an existing file then the file is read. Otherwise
1054 the buffer will be empty. If the buffer was already loaded
1055 then there is no change.
1056 If there is an existing swap file for the file of the buffer,
1057 there will be no dialog, the buffer will be loaded anyway.
1058 The {buf} argument is used like with |bufexists()|.
1059
1060 Can also be used as a |method|: >
1061 eval 'somename'->bufload()
1062
1063 bufloaded({buf}) *bufloaded()*
1064 The result is a Number, which is |TRUE| if a buffer called
1065 {buf} exists and is loaded (shown in a window or hidden).
1066 The {buf} argument is used like with |bufexists()|.
1067
1068 Can also be used as a |method|: >
1069 let loaded = 'somename'->bufloaded()
1070
1071 bufname([{buf}]) *bufname()*
1072 The result is the name of a buffer. Mostly as it is displayed
1073 by the `:ls` command, but not using special names such as
1074 "[No Name]".
1075 If {buf} is omitted the current buffer is used.
1076 If {buf} is a Number, that buffer number's name is given.
1077 Number zero is the alternate buffer for the current window.
1078 If {buf} is a String, it is used as a |file-pattern| to match
1079 with the buffer names. This is always done like 'magic' is
1080 set and 'cpoptions' is empty. When there is more than one
1081 match an empty string is returned.
1082 "" or "%" can be used for the current buffer, "#" for the
1083 alternate buffer.
1084 A full match is preferred, otherwise a match at the start, end
1085 or middle of the buffer name is accepted. If you only want a
1086 full match then put "^" at the start and "$" at the end of the
1087 pattern.
1088 Listed buffers are found first. If there is a single match
1089 with a listed buffer, that one is returned. Next unlisted
1090 buffers are searched for.
1091 If the {buf} is a String, but you want to use it as a buffer
1092 number, force it to be a Number by adding zero to it: >
1093 :echo bufname("3" + 0)
1094 < Can also be used as a |method|: >
1095 echo bufnr->bufname()
1096
1097 < If the buffer doesn't exist, or doesn't have a name, an empty
1098 string is returned. >
1099 bufname("#") alternate buffer name
1100 bufname(3) name of buffer 3
1101 bufname("%") name of current buffer
1102 bufname("file2") name of buffer where "file2" matches.
1103 < *buffer_name()*
1104 Obsolete name: buffer_name().
1105
1106 *bufnr()*
1107 bufnr([{buf} [, {create}]])
1108 The result is the number of a buffer, as it is displayed by
1109 the `:ls` command. For the use of {buf}, see |bufname()|
1110 above.
1111
1112 If the buffer doesn't exist, -1 is returned. Or, if the
1113 {create} argument is present and TRUE, a new, unlisted,
1114 buffer is created and its number is returned. Example: >
1115 let newbuf = bufnr('Scratch001', 1)
1116 < Using an empty name uses the current buffer. To create a new
1117 buffer with an empty name use |bufadd()|.
1118
1119 bufnr("$") is the last buffer: >
1120 :let last_buffer = bufnr("$")
1121 < The result is a Number, which is the highest buffer number
1122 of existing buffers. Note that not all buffers with a smaller
1123 number necessarily exist, because ":bwipeout" may have removed
1124 them. Use bufexists() to test for the existence of a buffer.
1125
1126 Can also be used as a |method|: >
1127 echo bufref->bufnr()
1128 <
1129 Obsolete name: buffer_number(). *buffer_number()*
1130 *last_buffer_nr()*
1131 Obsolete name for bufnr("$"): last_buffer_nr().
1132
1133 bufwinid({buf}) *bufwinid()*
1134 The result is a Number, which is the |window-ID| of the first
1135 window associated with buffer {buf}. For the use of {buf},
1136 see |bufname()| above. If buffer {buf} doesn't exist or
1137 there is no such window, -1 is returned. Example: >
1138
1139 echo "A window containing buffer 1 is " . (bufwinid(1))
1140 <
1141 Only deals with the current tab page.
1142
1143 Can also be used as a |method|: >
1144 FindBuffer()->bufwinid()
1145
1146 bufwinnr({buf}) *bufwinnr()*
1147 Like |bufwinid()| but return the window number instead of the
1148 |window-ID|.
1149 If buffer {buf} doesn't exist or there is no such window, -1
1150 is returned. Example: >
1151
1152 echo "A window containing buffer 1 is " . (bufwinnr(1))
1153
1154 < The number can be used with |CTRL-W_w| and ":wincmd w"
1155 |:wincmd|.
1156
1157 Can also be used as a |method|: >
1158 FindBuffer()->bufwinnr()
1159
1160 byte2line({byte}) *byte2line()*
1161 Return the line number that contains the character at byte
1162 count {byte} in the current buffer. This includes the
1163 end-of-line character, depending on the 'fileformat' option
1164 for the current buffer. The first character has byte count
1165 one.
1166 Also see |line2byte()|, |go| and |:goto|.
1167
1168 Can also be used as a |method|: >
1169 GetOffset()->byte2line()
1170
1171 < {not available when compiled without the |+byte_offset|
1172 feature}
1173
1174 byteidx({expr}, {nr}) *byteidx()*
1175 Return byte index of the {nr}'th character in the String
1176 {expr}. Use zero for the first character, it then returns
1177 zero.
1178 If there are no multibyte characters the returned value is
1179 equal to {nr}.
1180 Composing characters are not counted separately, their byte
1181 length is added to the preceding base character. See
1182 |byteidxcomp()| below for counting composing characters
1183 separately.
1184 Example : >
1185 echo matchstr(str, ".", byteidx(str, 3))
1186 < will display the fourth character. Another way to do the
1187 same: >
1188 let s = strpart(str, byteidx(str, 3))
1189 echo strpart(s, 0, byteidx(s, 1))
1190 < Also see |strgetchar()| and |strcharpart()|.
1191
1192 If there are less than {nr} characters -1 is returned.
1193 If there are exactly {nr} characters the length of the string
1194 in bytes is returned.
1195
1196 Can also be used as a |method|: >
1197 GetName()->byteidx(idx)
1198
1199 byteidxcomp({expr}, {nr}) *byteidxcomp()*
1200 Like byteidx(), except that a composing character is counted
1201 as a separate character. Example: >
1202 let s = 'e' . nr2char(0x301)
1203 echo byteidx(s, 1)
1204 echo byteidxcomp(s, 1)
1205 echo byteidxcomp(s, 2)
1206 < The first and third echo result in 3 ('e' plus composing
1207 character is 3 bytes), the second echo results in 1 ('e' is
1208 one byte).
1209 Only works differently from byteidx() when 'encoding' is set
1210 to a Unicode encoding.
1211
1212 Can also be used as a |method|: >
1213 GetName()->byteidxcomp(idx)
1214
1215 call({func}, {arglist} [, {dict}]) *call()* *E699*
1216 Call function {func} with the items in |List| {arglist} as
1217 arguments.
1218 {func} can either be a |Funcref| or the name of a function.
1219 a:firstline and a:lastline are set to the cursor line.
1220 Returns the return value of the called function.
1221 {dict} is for functions with the "dict" attribute. It will be
1222 used to set the local variable "self". |Dictionary-function|
1223
1224 Can also be used as a |method|: >
1225 GetFunc()->call([arg, arg], dict)
1226
1227 ceil({expr}) *ceil()*
1228 Return the smallest integral value greater than or equal to
1229 {expr} as a |Float| (round up).
1230 {expr} must evaluate to a |Float| or a |Number|.
1231 Examples: >
1232 echo ceil(1.456)
1233 < 2.0 >
1234 echo ceil(-5.456)
1235 < -5.0 >
1236 echo ceil(4.0)
1237 < 4.0
1238
1239 Can also be used as a |method|: >
1240 Compute()->ceil()
1241 <
1242 {only available when compiled with the |+float| feature}
1243
1244
1245 ch_ functions are documented here: |channel-functions-details|
1246
1247
1248 changenr() *changenr()*
1249 Return the number of the most recent change. This is the same
1250 number as what is displayed with |:undolist| and can be used
1251 with the |:undo| command.
1252 When a change was made it is the number of that change. After
1253 redo it is the number of the redone change. After undo it is
1254 one less than the number of the undone change.
1255
1256 char2nr({string} [, {utf8}]) *char2nr()*
1257 Return number value of the first char in {string}.
1258 Examples: >
1259 char2nr(" ") returns 32
1260 char2nr("ABC") returns 65
1261 < When {utf8} is omitted or zero, the current 'encoding' is used.
1262 Example for "utf-8": >
1263 char2nr("á") returns 225
1264 char2nr("á"[0]) returns 195
1265 < When {utf8} is TRUE, always treat as UTF-8 characters.
1266 A combining character is a separate character.
1267 |nr2char()| does the opposite.
1268 To turn a string into a list of character numbers: >
1269 let str = "ABC"
1270 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1271 < Result: [65, 66, 67]
1272
1273 Can also be used as a |method|: >
1274 GetChar()->char2nr()
1275
1276
1277 charclass({string}) *charclass()*
1278 Return the character class of the first character in {string}.
1279 The character class is one of:
1280 0 blank
1281 1 punctuation
1282 2 word character
1283 3 emoji
1284 other specific Unicode class
1285 The class is used in patterns and word motions.
1286
1287
1288 charcol({expr}) *charcol()*
1289 Same as |col()| but returns the character index of the column
1290 position given with {expr} instead of the byte position.
1291
1292 Example:
1293 With the cursor on '세' in line 5 with text "여보세요": >
1294 charcol('.') returns 3
1295 col('.') returns 7
1296
1297 < Can also be used as a |method|: >
1298 GetPos()->col()
1299 <
1300 *charidx()*
1301 charidx({string}, {idx} [, {countcc}])
1302 Return the character index of the byte at {idx} in {string}.
1303 The index of the first character is zero.
1304 If there are no multibyte characters the returned value is
1305 equal to {idx}.
1306 When {countcc} is omitted or |FALSE|, then composing characters
1307 are not counted separately, their byte length is
1308 added to the preceding base character.
1309 When {countcc} is |TRUE|, then composing characters are
1310 counted as separate characters.
1311 Returns -1 if the arguments are invalid or if {idx} is greater
1312 than the index of the last byte in {string}. An error is
1313 given if the first argument is not a string, the second
1314 argument is not a number or when the third argument is present
1315 and is not zero or one.
1316 See |byteidx()| and |byteidxcomp()| for getting the byte index
1317 from the character index.
1318 Examples: >
1319 echo charidx('áb́ć', 3) returns 1
1320 echo charidx('áb́ć', 6, 1) returns 4
1321 echo charidx('áb́ć', 16) returns -1
1322 <
1323 Can also be used as a |method|: >
1324 GetName()->charidx(idx)
1325
1326 chdir({dir}) *chdir()*
1327 Change the current working directory to {dir}. The scope of
1328 the directory change depends on the directory of the current
1329 window:
1330 - If the current window has a window-local directory
1331 (|:lcd|), then changes the window local directory.
1332 - Otherwise, if the current tabpage has a local
1333 directory (|:tcd|) then changes the tabpage local
1334 directory.
1335 - Otherwise, changes the global directory.
1336 {dir} must be a String.
1337 If successful, returns the previous working directory. Pass
1338 this to another chdir() to restore the directory.
1339 On failure, returns an empty string.
1340
1341 Example: >
1342 let save_dir = chdir(newdir)
1343 if save_dir != ""
1344 " ... do some work
1345 call chdir(save_dir)
1346 endif
1347
1348 < Can also be used as a |method|: >
1349 GetDir()->chdir()
1350 <
1351 cindent({lnum}) *cindent()*
1352 Get the amount of indent for line {lnum} according the C
1353 indenting rules, as with 'cindent'.
1354 The indent is counted in spaces, the value of 'tabstop' is
1355 relevant. {lnum} is used just like in |getline()|.
1356 When {lnum} is invalid or Vim was not compiled the |+cindent|
1357 feature, -1 is returned.
1358 See |C-indenting|.
1359
1360 Can also be used as a |method|: >
1361 GetLnum()->cindent()
1362
1363 clearmatches([{win}]) *clearmatches()*
1364 Clears all matches previously defined for the current window
1365 by |matchadd()| and the |:match| commands.
1366 If {win} is specified, use the window with this number or
1367 window ID instead of the current window.
1368
1369 Can also be used as a |method|: >
1370 GetWin()->clearmatches()
1371 <
1372 *col()*
1373 col({expr}) The result is a Number, which is the byte index of the column
1374 position given with {expr}. The accepted positions are:
1375 . the cursor position
1376 $ the end of the cursor line (the result is the
1377 number of bytes in the cursor line plus one)
1378 'x position of mark x (if the mark is not set, 0 is
1379 returned)
1380 v In Visual mode: the start of the Visual area (the
1381 cursor is the end). When not in Visual mode
1382 returns the cursor position. Differs from |'<| in
1383 that it's updated right away.
1384 Additionally {expr} can be [lnum, col]: a |List| with the line
1385 and column number. Most useful when the column is "$", to get
1386 the last column of a specific line. When "lnum" or "col" is
1387 out of range then col() returns zero.
1388 To get the line number use |line()|. To get both use
1389 |getpos()|.
1390 For the screen column position use |virtcol()|. For the
1391 character position use |charcol()|.
1392 Note that only marks in the current file can be used.
1393 Examples: >
1394 col(".") column of cursor
1395 col("$") length of cursor line plus one
1396 col("'t") column of mark t
1397 col("'" . markname) column of mark markname
1398 < The first column is 1. 0 is returned for an error.
1399 For an uppercase mark the column may actually be in another
1400 buffer.
1401 For the cursor position, when 'virtualedit' is active, the
1402 column is one higher if the cursor is after the end of the
1403 line. This can be used to obtain the column in Insert mode: >
1404 :imap <F2> <C-O>:let save_ve = &ve<CR>
1405 \<C-O>:set ve=all<CR>
1406 \<C-O>:echo col(".") . "\n" <Bar>
1407 \let &ve = save_ve<CR>
1408
1409 < Can also be used as a |method|: >
1410 GetPos()->col()
1411 <
1412
1413 complete({startcol}, {matches}) *complete()* *E785*
1414 Set the matches for Insert mode completion.
1415 Can only be used in Insert mode. You need to use a mapping
1416 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1417 or with an expression mapping.
1418 {startcol} is the byte offset in the line where the completed
1419 text start. The text up to the cursor is the original text
1420 that will be replaced by the matches. Use col('.') for an
1421 empty string. "col('.') - 1" will replace one character by a
1422 match.
1423 {matches} must be a |List|. Each |List| item is one match.
1424 See |complete-items| for the kind of items that are possible.
1425 "longest" in 'completeopt' is ignored.
1426 Note that the after calling this function you need to avoid
1427 inserting anything that would cause completion to stop.
1428 The match can be selected with CTRL-N and CTRL-P as usual with
1429 Insert mode completion. The popup menu will appear if
1430 specified, see |ins-completion-menu|.
1431 Example: >
1432 inoremap <F5> <C-R>=ListMonths()<CR>
1433
1434 func! ListMonths()
1435 call complete(col('.'), ['January', 'February', 'March',
1436 \ 'April', 'May', 'June', 'July', 'August', 'September',
1437 \ 'October', 'November', 'December'])
1438 return ''
1439 endfunc
1440 < This isn't very useful, but it shows how it works. Note that
1441 an empty string is returned to avoid a zero being inserted.
1442
1443 Can also be used as a |method|, the base is passed as the
1444 second argument: >
1445 GetMatches()->complete(col('.'))
1446
1447 complete_add({expr}) *complete_add()*
1448 Add {expr} to the list of matches. Only to be used by the
1449 function specified with the 'completefunc' option.
1450 Returns 0 for failure (empty string or out of memory),
1451 1 when the match was added, 2 when the match was already in
1452 the list.
1453 See |complete-functions| for an explanation of {expr}. It is
1454 the same as one item in the list that 'omnifunc' would return.
1455
1456 Can also be used as a |method|: >
1457 GetMoreMatches()->complete_add()
1458
1459 complete_check() *complete_check()*
1460 Check for a key typed while looking for completion matches.
1461 This is to be used when looking for matches takes some time.
1462 Returns |TRUE| when searching for matches is to be aborted,
1463 zero otherwise.
1464 Only to be used by the function specified with the
1465 'completefunc' option.
1466
1467
1468 complete_info([{what}]) *complete_info()*
1469 Returns a |Dictionary| with information about Insert mode
1470 completion. See |ins-completion|.
1471 The items are:
1472 mode Current completion mode name string.
1473 See |complete_info_mode| for the values.
1474 pum_visible |TRUE| if popup menu is visible.
1475 See |pumvisible()|.
1476 items List of completion matches. Each item is a
1477 dictionary containing the entries "word",
1478 "abbr", "menu", "kind", "info" and "user_data".
1479 See |complete-items|.
1480 selected Selected item index. First index is zero.
1481 Index is -1 if no item is selected (showing
1482 typed text only, or the last completion after
1483 no item is selected when using the <Up> or
1484 <Down> keys)
1485 inserted Inserted string. [NOT IMPLEMENT YET]
1486
1487 *complete_info_mode*
1488 mode values are:
1489 "" Not in completion mode
1490 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1491 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1492 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1493 |i_CTRL-X_CTRL-Y|
1494 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1495 "files" File names |i_CTRL-X_CTRL-F|
1496 "tags" Tags |i_CTRL-X_CTRL-]|
1497 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1498 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1499 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1500 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1501 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1502 "function" User defined completion |i_CTRL-X_CTRL-U|
1503 "omni" Omni completion |i_CTRL-X_CTRL-O|
1504 "spell" Spelling suggestions |i_CTRL-X_s|
1505 "eval" |complete()| completion
1506 "unknown" Other internal modes
1507
1508 If the optional {what} list argument is supplied, then only
1509 the items listed in {what} are returned. Unsupported items in
1510 {what} are silently ignored.
1511
1512 To get the position and size of the popup menu, see
1513 |pum_getpos()|. It's also available in |v:event| during the
1514 |CompleteChanged| event.
1515
1516 Examples: >
1517 " Get all items
1518 call complete_info()
1519 " Get only 'mode'
1520 call complete_info(['mode'])
1521 " Get only 'mode' and 'pum_visible'
1522 call complete_info(['mode', 'pum_visible'])
1523
1524 < Can also be used as a |method|: >
1525 GetItems()->complete_info()
1526 <
1527 *confirm()*
1528 confirm({msg} [, {choices} [, {default} [, {type}]]])
1529 confirm() offers the user a dialog, from which a choice can be
1530 made. It returns the number of the choice. For the first
1531 choice this is 1.
1532 Note: confirm() is only supported when compiled with dialog
1533 support, see |+dialog_con| and |+dialog_gui|.
1534
1535 {msg} is displayed in a |dialog| with {choices} as the
1536 alternatives. When {choices} is missing or empty, "&OK" is
1537 used (and translated).
1538 {msg} is a String, use '\n' to include a newline. Only on
1539 some systems the string is wrapped when it doesn't fit.
1540
1541 {choices} is a String, with the individual choices separated
1542 by '\n', e.g. >
1543 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1544 < The letter after the '&' is the shortcut key for that choice.
1545 Thus you can type 'c' to select "Cancel". The shortcut does
1546 not need to be the first letter: >
1547 confirm("file has been modified", "&Save\nSave &All")
1548 < For the console, the first letter of each choice is used as
1549 the default shortcut key. Case is ignored.
1550
1551 The optional {default} argument is the number of the choice
1552 that is made if the user hits <CR>. Use 1 to make the first
1553 choice the default one. Use 0 to not set a default. If
1554 {default} is omitted, 1 is used.
1555
1556 The optional {type} String argument gives the type of dialog.
1557 This is only used for the icon of the GTK, Mac, Motif and
1558 Win32 GUI. It can be one of these values: "Error",
1559 "Question", "Info", "Warning" or "Generic". Only the first
1560 character is relevant. When {type} is omitted, "Generic" is
1561 used.
1562
1563 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1564 or another valid interrupt key, confirm() returns 0.
1565
1566 An example: >
1567 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
1568 :if choice == 0
1569 : echo "make up your mind!"
1570 :elseif choice == 3
1571 : echo "tasteful"
1572 :else
1573 : echo "I prefer bananas myself."
1574 :endif
1575 < In a GUI dialog, buttons are used. The layout of the buttons
1576 depends on the 'v' flag in 'guioptions'. If it is included,
1577 the buttons are always put vertically. Otherwise, confirm()
1578 tries to put the buttons in one horizontal line. If they
1579 don't fit, a vertical layout is used anyway. For some systems
1580 the horizontal layout is always used.
1581
1582 Can also be used as a |method|in: >
1583 BuildMessage()->confirm("&Yes\n&No")
1584 <
1585 *copy()*
1586 copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1587 different from using {expr} directly.
1588 When {expr} is a |List| a shallow copy is created. This means
1589 that the original |List| can be changed without changing the
1590 copy, and vice versa. But the items are identical, thus
1591 changing an item changes the contents of both |Lists|.
1592 A |Dictionary| is copied in a similar way as a |List|.
1593 Also see |deepcopy()|.
1594 Can also be used as a |method|: >
1595 mylist->copy()
1596
1597 cos({expr}) *cos()*
1598 Return the cosine of {expr}, measured in radians, as a |Float|.
1599 {expr} must evaluate to a |Float| or a |Number|.
1600 Examples: >
1601 :echo cos(100)
1602 < 0.862319 >
1603 :echo cos(-4.01)
1604 < -0.646043
1605
1606 Can also be used as a |method|: >
1607 Compute()->cos()
1608 <
1609 {only available when compiled with the |+float| feature}
1610
1611
1612 cosh({expr}) *cosh()*
1613 Return the hyperbolic cosine of {expr} as a |Float| in the range
1614 [1, inf].
1615 {expr} must evaluate to a |Float| or a |Number|.
1616 Examples: >
1617 :echo cosh(0.5)
1618 < 1.127626 >
1619 :echo cosh(-0.5)
1620 < -1.127626
1621
1622 Can also be used as a |method|: >
1623 Compute()->cosh()
1624 <
1625 {only available when compiled with the |+float| feature}
1626
1627
1628 count({comp}, {expr} [, {ic} [, {start}]]) *count()*
1629 Return the number of times an item with value {expr} appears
1630 in |String|, |List| or |Dictionary| {comp}.
1631
1632 If {start} is given then start with the item with this index.
1633 {start} can only be used with a |List|.
1634
1635 When {ic} is given and it's |TRUE| then case is ignored.
1636
1637 When {comp} is a string then the number of not overlapping
1638 occurrences of {expr} is returned. Zero is returned when
1639 {expr} is an empty string.
1640
1641 Can also be used as a |method|: >
1642 mylist->count(val)
1643 <
1644 *cscope_connection()*
1645 cscope_connection([{num} , {dbpath} [, {prepend}]])
1646 Checks for the existence of a |cscope| connection. If no
1647 parameters are specified, then the function returns:
1648 0, if cscope was not available (not compiled in), or
1649 if there are no cscope connections;
1650 1, if there is at least one cscope connection.
1651
1652 If parameters are specified, then the value of {num}
1653 determines how existence of a cscope connection is checked:
1654
1655 {num} Description of existence check
1656 ----- ------------------------------
1657 0 Same as no parameters (e.g., "cscope_connection()").
1658 1 Ignore {prepend}, and use partial string matches for
1659 {dbpath}.
1660 2 Ignore {prepend}, and use exact string matches for
1661 {dbpath}.
1662 3 Use {prepend}, use partial string matches for both
1663 {dbpath} and {prepend}.
1664 4 Use {prepend}, use exact string matches for both
1665 {dbpath} and {prepend}.
1666
1667 Note: All string comparisons are case sensitive!
1668
1669 Examples. Suppose we had the following (from ":cs show"): >
1670
1671 # pid database name prepend path
1672 0 27664 cscope.out /usr/local
1673 <
1674 Invocation Return Val ~
1675 ---------- ---------- >
1676 cscope_connection() 1
1677 cscope_connection(1, "out") 1
1678 cscope_connection(2, "out") 0
1679 cscope_connection(3, "out") 0
1680 cscope_connection(3, "out", "local") 1
1681 cscope_connection(4, "out") 0
1682 cscope_connection(4, "out", "local") 0
1683 cscope_connection(4, "cscope.out", "/usr/local") 1
1684 <
1685 cursor({lnum}, {col} [, {off}]) *cursor()*
1686 cursor({list})
1687 Positions the cursor at the column (byte count) {col} in the
1688 line {lnum}. The first column is one.
1689
1690 When there is one argument {list} this is used as a |List|
1691 with two, three or four item:
1692 [{lnum}, {col}]
1693 [{lnum}, {col}, {off}]
1694 [{lnum}, {col}, {off}, {curswant}]
1695 This is like the return value of |getpos()| or |getcurpos()|,
1696 but without the first item.
1697
1698 To position the cursor using the character count, use
1699 |setcursorcharpos()|.
1700
1701 Does not change the jumplist.
1702 {lnum} is used like with |getline()|.
1703 If {lnum} is greater than the number of lines in the buffer,
1704 the cursor will be positioned at the last line in the buffer.
1705 If {lnum} is zero, the cursor will stay in the current line.
1706 If {col} is greater than the number of bytes in the line,
1707 the cursor will be positioned at the last character in the
1708 line.
1709 If {col} is zero, the cursor will stay in the current column.
1710 If {curswant} is given it is used to set the preferred column
1711 for vertical movement. Otherwise {col} is used.
1712
1713 When 'virtualedit' is used {off} specifies the offset in
1714 screen columns from the start of the character. E.g., a
1715 position within a <Tab> or after the last character.
1716 Returns 0 when the position could be set, -1 otherwise.
1717
1718 Can also be used as a |method|: >
1719 GetCursorPos()->cursor()
1720
1721 debugbreak({pid}) *debugbreak()*
1722 Specifically used to interrupt a program being debugged. It
1723 will cause process {pid} to get a SIGTRAP. Behavior for other
1724 processes is undefined. See |terminal-debugger|.
1725 {only available on MS-Windows}
1726
1727 Can also be used as a |method|: >
1728 GetPid()->debugbreak()
1729
1730 deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
1731 Make a copy of {expr}. For Numbers and Strings this isn't
1732 different from using {expr} directly.
1733 When {expr} is a |List| a full copy is created. This means
1734 that the original |List| can be changed without changing the
1735 copy, and vice versa. When an item is a |List| or
1736 |Dictionary|, a copy for it is made, recursively. Thus
1737 changing an item in the copy does not change the contents of
1738 the original |List|.
1739 A |Dictionary| is copied in a similar way as a |List|.
1740
1741 When {noref} is omitted or zero a contained |List| or
1742 |Dictionary| is only copied once. All references point to
1743 this single copy. With {noref} set to 1 every occurrence of a
1744 |List| or |Dictionary| results in a new copy. This also means
1745 that a cyclic reference causes deepcopy() to fail.
1746 *E724*
1747 Nesting is possible up to 100 levels. When there is an item
1748 that refers back to a higher level making a deep copy with
1749 {noref} set to 1 will fail.
1750 Also see |copy()|.
1751
1752 Can also be used as a |method|: >
1753 GetObject()->deepcopy()
1754
1755 delete({fname} [, {flags}]) *delete()*
1756 Without {flags} or with {flags} empty: Deletes the file by the
1757 name {fname}. This also works when {fname} is a symbolic link.
1758
1759 When {flags} is "d": Deletes the directory by the name
1760 {fname}. This fails when directory {fname} is not empty.
1761
1762 When {flags} is "rf": Deletes the directory by the name
1763 {fname} and everything in it, recursively. BE CAREFUL!
1764 Note: on MS-Windows it is not possible to delete a directory
1765 that is being used.
1766
1767 A symbolic link itself is deleted, not what it points to.
1768
1769 The result is a Number, which is 0/false if the delete
1770 operation was successful and -1/true when the deletion failed
1771 or partly failed.
1772
1773 Use |remove()| to delete an item from a |List|.
1774 To delete a line from the buffer use |:delete| or
1775 |deletebufline()|.
1776
1777 Can also be used as a |method|: >
1778 GetName()->delete()
1779
1780 deletebufline({buf}, {first} [, {last}]) *deletebufline()*
1781 Delete lines {first} to {last} (inclusive) from buffer {buf}.
1782 If {last} is omitted then delete line {first} only.
1783 On success 0 is returned, on failure 1 is returned.
1784
1785 This function works only for loaded buffers. First call
1786 |bufload()| if needed.
1787
1788 For the use of {buf}, see |bufname()| above.
1789
1790 {first} and {last} are used like with |getline()|. Note that
1791 when using |line()| this refers to the current buffer. Use "$"
1792 to refer to the last line in buffer {buf}.
1793
1794 Can also be used as a |method|: >
1795 GetBuffer()->deletebufline(1)
1796 <
1797 *did_filetype()*
1798 did_filetype() Returns |TRUE| when autocommands are being executed and the
1799 FileType event has been triggered at least once. Can be used
1800 to avoid triggering the FileType event again in the scripts
1801 that detect the file type. |FileType|
1802 Returns |FALSE| when `:setf FALLBACK` was used.
1803 When editing another file, the counter is reset, thus this
1804 really checks if the FileType event has been triggered for the
1805 current buffer. This allows an autocommand that starts
1806 editing another buffer to set 'filetype' and load a syntax
1807 file.
1808
1809 diff_filler({lnum}) *diff_filler()*
1810 Returns the number of filler lines above line {lnum}.
1811 These are the lines that were inserted at this point in
1812 another diff'ed window. These filler lines are shown in the
1813 display but don't exist in the buffer.
1814 {lnum} is used like with |getline()|. Thus "." is the current
1815 line, "'m" mark m, etc.
1816 Returns 0 if the current window is not in diff mode.
1817
1818 Can also be used as a |method|: >
1819 GetLnum()->diff_filler()
1820
1821 diff_hlID({lnum}, {col}) *diff_hlID()*
1822 Returns the highlight ID for diff mode at line {lnum} column
1823 {col} (byte index). When the current line does not have a
1824 diff change zero is returned.
1825 {lnum} is used like with |getline()|. Thus "." is the current
1826 line, "'m" mark m, etc.
1827 {col} is 1 for the leftmost column, {lnum} is 1 for the first
1828 line.
1829 The highlight ID can be used with |synIDattr()| to obtain
1830 syntax information about the highlighting.
1831
1832 Can also be used as a |method|: >
1833 GetLnum()->diff_hlID(col)
1834 <
1835
1836 digraph_get({chars}) *digraph_get()* *E1214*
1837 Return the digraph of {chars}. This should be a string with
1838 exactly two characters. If {chars} are not just two
1839 characters, or the digraph of {chars} does not exist, an error
1840 is given and an empty string is returned.
1841
1842 The character will be converted from Unicode to 'encoding'
1843 when needed. This does require the conversion to be
1844 available, it might fail.
1845
1846 Also see |digraph_getlist()|.
1847
1848 Examples: >
1849 " Get a built-in digraph
1850 :echo digraph_get('00') " Returns '∞'
1851
1852 " Get a user-defined digraph
1853 :call digraph_set('aa', 'あ')
1854 :echo digraph_get('aa') " Returns 'あ'
1855 <
1856 Can also be used as a |method|: >
1857 GetChars()->digraph_get()
1858 <
1859 This function works only when compiled with the |+digraphs|
1860 feature. If this feature is disabled, this function will
1861 display an error message.
1862
1863
1864 digraph_getlist([{listall}]) *digraph_getlist()*
1865 Return a list of digraphs. If the {listall} argument is given
1866 and it is TRUE, return all digraphs, including the default
1867 digraphs. Otherwise, return only user-defined digraphs.
1868
1869 The characters will be converted from Unicode to 'encoding'
1870 when needed. This does require the conservation to be
1871 available, it might fail.
1872
1873 Also see |digraph_get()|.
1874
1875 Examples: >
1876 " Get user-defined digraphs
1877 :echo digraph_getlist()
1878
1879 " Get all the digraphs, including default digraphs
1880 :echo digraph_getlist(1)
1881 <
1882 Can also be used as a |method|: >
1883 GetNumber()->digraph_getlist()
1884 <
1885 This function works only when compiled with the |+digraphs|
1886 feature. If this feature is disabled, this function will
1887 display an error message.
1888
1889
1890 digraph_set({chars}, {digraph}) *digraph_set()* *E1205*
1891 Add digraph {chars} to the list. {chars} must be a string
1892 with two characters. {digraph} is a string with one UTF-8
1893 encoded character. Be careful, composing characters are NOT
1894 ignored. This function is similar to |:digraphs| command, but
1895 useful to add digraphs start with a white space.
1896
1897 The function result is v:true if |digraph| is registered. If
1898 this fails an error message is given and v:false is returned.
1899
1900 If you want to define multiple digraphs at once, you can use
1901 |digraph_setlist()|.
1902
1903 Example: >
1904 call digraph_set(' ', 'あ')
1905 <
1906 Can be used as a |method|: >
1907 GetString()->digraph_set('あ')
1908 <
1909 This function works only when compiled with the |+digraphs|
1910 feature. If this feature is disabled, this function will
1911 display an error message.
1912
1913
1914 digraph_setlist({digraphlist}) *digraph_setlist()*
1915 Similar to |digraph_set()| but this function can add multiple
1916 digraphs at once. {digraphlist} is a list composed of lists,
1917 where each list contains two strings with {chars} and
1918 {digraph} as in |digraph_set()|.
1919 Example: >
1920 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
1921 <
1922 It is similar to the following: >
1923 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
1924 call digraph_set(chars, digraph)
1925 endfor
1926 < Except that the function returns after the first error,
1927 following digraphs will not be added.
1928
1929 Can be used as a |method|: >
1930 GetList()->digraph_setlist()
1931 <
1932 This function works only when compiled with the |+digraphs|
1933 feature. If this feature is disabled, this function will
1934 display an error message.
1935
1936
1937 echoraw({string}) *echoraw()*
1938 Output {string} as-is, including unprintable characters.
1939 This can be used to output a terminal code. For example, to
1940 disable modifyOtherKeys: >
1941 call echoraw(&t_TE)
1942 < and to enable it again: >
1943 call echoraw(&t_TI)
1944 < Use with care, you can mess up the terminal this way.
1945
1946
1947 empty({expr}) *empty()*
1948 Return the Number 1 if {expr} is empty, zero otherwise.
1949 - A |List| or |Dictionary| is empty when it does not have any
1950 items.
1951 - A |String| is empty when its length is zero.
1952 - A |Number| and |Float| are empty when their value is zero.
1953 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
1954 - A |Job| is empty when it failed to start.
1955 - A |Channel| is empty when it is closed.
1956 - A |Blob| is empty when its length is zero.
1957
1958 For a long |List| this is much faster than comparing the
1959 length with zero.
1960
1961 Can also be used as a |method|: >
1962 mylist->empty()
1963
1964 environ() *environ()*
1965 Return all of environment variables as dictionary. You can
1966 check if an environment variable exists like this: >
1967 :echo has_key(environ(), 'HOME')
1968 < Note that the variable name may be CamelCase; to ignore case
1969 use this: >
1970 :echo index(keys(environ()), 'HOME', 0, 1) != -1
1971
1972 escape({string}, {chars}) *escape()*
1973 Escape the characters in {chars} that occur in {string} with a
1974 backslash. Example: >
1975 :echo escape('c:\program files\vim', ' \')
1976 < results in: >
1977 c:\\program\ files\\vim
1978 < Also see |shellescape()| and |fnameescape()|.
1979
1980 Can also be used as a |method|: >
1981 GetText()->escape(' \')
1982 <
1983 *eval()*
1984 eval({string}) Evaluate {string} and return the result. Especially useful to
1985 turn the result of |string()| back into the original value.
1986 This works for Numbers, Floats, Strings, Blobs and composites
1987 of them. Also works for |Funcref|s that refer to existing
1988 functions.
1989
1990 Can also be used as a |method|: >
1991 argv->join()->eval()
1992
1993 eventhandler() *eventhandler()*
1994 Returns 1 when inside an event handler. That is that Vim got
1995 interrupted while waiting for the user to type a character,
1996 e.g., when dropping a file on Vim. This means interactive
1997 commands cannot be used. Otherwise zero is returned.
1998
1999 executable({expr}) *executable()*
2000 This function checks if an executable with the name {expr}
2001 exists. {expr} must be the name of the program without any
2002 arguments.
2003 executable() uses the value of $PATH and/or the normal
2004 searchpath for programs. *PATHEXT*
2005 On MS-Windows the ".exe", ".bat", etc. can optionally be
2006 included. Then the extensions in $PATHEXT are tried. Thus if
2007 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2008 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2009 by itself can be used in $PATHEXT to try using the name
2010 without an extension. When 'shell' looks like a Unix shell,
2011 then the name is also tried without adding an extension.
2012 On MS-Windows it only checks if the file exists and is not a
2013 directory, not if it's really executable.
2014 On MS-Windows an executable in the same directory as Vim is
2015 always found. Since this directory is added to $PATH it
2016 should also work to execute it |win32-PATH|.
2017 The result is a Number:
2018 1 exists
2019 0 does not exist
2020 -1 not implemented on this system
2021 |exepath()| can be used to get the full path of an executable.
2022
2023 Can also be used as a |method|: >
2024 GetCommand()->executable()
2025
2026 execute({command} [, {silent}]) *execute()*
2027 Execute an Ex command or commands and return the output as a
2028 string.
2029 {command} can be a string or a List. In case of a List the
2030 lines are executed one by one.
2031 This is equivalent to: >
2032 redir => var
2033 {command}
2034 redir END
2035 <
2036 The optional {silent} argument can have these values:
2037 "" no `:silent` used
2038 "silent" `:silent` used
2039 "silent!" `:silent!` used
2040 The default is "silent". Note that with "silent!", unlike
2041 `:redir`, error messages are dropped. When using an external
2042 command the screen may be messed up, use `system()` instead.
2043 *E930*
2044 It is not possible to use `:redir` anywhere in {command}.
2045
2046 To get a list of lines use |split()| on the result: >
2047 split(execute('args'), "\n")
2048
2049 < To execute a command in another window than the current one
2050 use `win_execute()`.
2051
2052 When used recursively the output of the recursive call is not
2053 included in the output of the higher level call.
2054
2055 Can also be used as a |method|: >
2056 GetCommand()->execute()
2057
2058 exepath({expr}) *exepath()*
2059 If {expr} is an executable and is either an absolute path, a
2060 relative path or found in $PATH, return the full path.
2061 Note that the current directory is used when {expr} starts
2062 with "./", which may be a problem for Vim: >
2063 echo exepath(v:progpath)
2064 < If {expr} cannot be found in $PATH or is not executable then
2065 an empty string is returned.
2066
2067 Can also be used as a |method|: >
2068 GetCommand()->exepath()
2069 <
2070 *exists()*
2071 exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
2072 zero otherwise.
2073
2074 Note: In a compiled |:def| function the evaluation is done at
2075 runtime. Use `exists_compiled()` to evaluate the expression
2076 at compile time.
2077
2078 For checking for a supported feature use |has()|.
2079 For checking if a file exists use |filereadable()|.
2080
2081 The {expr} argument is a string, which contains one of these:
2082 &option-name Vim option (only checks if it exists,
2083 not if it really works)
2084 +option-name Vim option that works.
2085 $ENVNAME environment variable (could also be
2086 done by comparing with an empty
2087 string)
2088 *funcname built-in function (see |functions|)
2089 or user defined function (see
2090 |user-functions|) that is implemented.
2091 Also works for a variable that is a
2092 Funcref.
2093 ?funcname built-in function that could be
2094 implemented; to be used to check if
2095 "funcname" is valid
2096 varname internal variable (see
2097 |internal-variables|). Also works
2098 for |curly-braces-names|, |Dictionary|
2099 entries, |List| items, etc.
2100 Does not work for local variables in a
2101 compiled `:def` function.
2102 Beware that evaluating an index may
2103 cause an error message for an invalid
2104 expression. E.g.: >
2105 :let l = [1, 2, 3]
2106 :echo exists("l[5]")
2107 < 0 >
2108 :echo exists("l[xx]")
2109 < E121: Undefined variable: xx
2110 0
2111 :cmdname Ex command: built-in command, user
2112 command or command modifier |:command|.
2113 Returns:
2114 1 for match with start of a command
2115 2 full match with a command
2116 3 matches several user commands
2117 To check for a supported command
2118 always check the return value to be 2.
2119 :2match The |:2match| command.
2120 :3match The |:3match| command.
2121 #event autocommand defined for this event
2122 #event#pattern autocommand defined for this event and
2123 pattern (the pattern is taken
2124 literally and compared to the
2125 autocommand patterns character by
2126 character)
2127 #group autocommand group exists
2128 #group#event autocommand defined for this group and
2129 event.
2130 #group#event#pattern
2131 autocommand defined for this group,
2132 event and pattern.
2133 ##event autocommand for this event is
2134 supported.
2135
2136 Examples: >
2137 exists("&shortname")
2138 exists("$HOSTNAME")
2139 exists("*strftime")
2140 exists("*s:MyFunc")
2141 exists("bufcount")
2142 exists(":Make")
2143 exists("#CursorHold")
2144 exists("#BufReadPre#*.gz")
2145 exists("#filetypeindent")
2146 exists("#filetypeindent#FileType")
2147 exists("#filetypeindent#FileType#*")
2148 exists("##ColorScheme")
2149 < There must be no space between the symbol (&/$/*/#) and the
2150 name.
2151 There must be no extra characters after the name, although in
2152 a few cases this is ignored. That may become more strict in
2153 the future, thus don't count on it!
2154 Working example: >
2155 exists(":make")
2156 < NOT working example: >
2157 exists(":make install")
2158
2159 < Note that the argument must be a string, not the name of the
2160 variable itself. For example: >
2161 exists(bufcount)
2162 < This doesn't check for existence of the "bufcount" variable,
2163 but gets the value of "bufcount", and checks if that exists.
2164
2165 Can also be used as a |method|: >
2166 Varname()->exists()
2167 <
2168
2169 exists_compiled({expr}) *exists_compiled()*
2170 Like `exists()` but evaluated at compile time. This is useful
2171 to skip a block where a function is used that would otherwise
2172 give an error: >
2173 if exists_compiled('*ThatFunction')
2174 ThatFunction('works')
2175 endif
2176 < If `exists()` were used then a compilation error would be
2177 given if ThatFunction() is not defined.
2178
2179 {expr} must be a literal string. *E1232*
2180 Can only be used in a |:def| function. *E1233*
2181 This does not work to check for arguments or local variables.
2182
2183
2184 exp({expr}) *exp()*
2185 Return the exponential of {expr} as a |Float| in the range
2186 [0, inf].
2187 {expr} must evaluate to a |Float| or a |Number|.
2188 Examples: >
2189 :echo exp(2)
2190 < 7.389056 >
2191 :echo exp(-1)
2192 < 0.367879
2193
2194 Can also be used as a |method|: >
2195 Compute()->exp()
2196 <
2197 {only available when compiled with the |+float| feature}
2198
2199
2200 expand({string} [, {nosuf} [, {list}]]) *expand()*
2201 Expand wildcards and the following special keywords in
2202 {string}. 'wildignorecase' applies.
2203
2204 If {list} is given and it is |TRUE|, a List will be returned.
2205 Otherwise the result is a String and when there are several
2206 matches, they are separated by <NL> characters. [Note: in
2207 version 5.0 a space was used, which caused problems when a
2208 file name contains a space]
2209
2210 If the expansion fails, the result is an empty string. A name
2211 for a non-existing file is not included, unless {string} does
2212 not start with '%', '#' or '<', see below.
2213
2214 When {string} starts with '%', '#' or '<', the expansion is
2215 done like for the |cmdline-special| variables with their
2216 associated modifiers. Here is a short overview:
2217
2218 % current file name
2219 # alternate file name
2220 #n alternate file name n
2221 <cfile> file name under the cursor
2222 <afile> autocmd file name
2223 <abuf> autocmd buffer number (as a String!)
2224 <amatch> autocmd matched name
2225 <cexpr> C expression under the cursor
2226 <sfile> sourced script file or function name
2227 <slnum> sourced script line number or function
2228 line number
2229 <sflnum> script file line number, also when in
2230 a function
2231 <SID> "<SNR>123_" where "123" is the
2232 current script ID |<SID>|
2233 <stack> call stack
2234 <cword> word under the cursor
2235 <cWORD> WORD under the cursor
2236 <client> the {clientid} of the last received
2237 message |server2client()|
2238 Modifiers:
2239 :p expand to full path
2240 :h head (last path component removed)
2241 :t tail (last path component only)
2242 :r root (one extension removed)
2243 :e extension only
2244
2245 Example: >
2246 :let &tags = expand("%:p:h") . "/tags"
2247 < Note that when expanding a string that starts with '%', '#' or
2248 '<', any following text is ignored. This does NOT work: >
2249 :let doesntwork = expand("%:h.bak")
2250 < Use this: >
2251 :let doeswork = expand("%:h") . ".bak"
2252 < Also note that expanding "<cfile>" and others only returns the
2253 referenced file name without further expansion. If "<cfile>"
2254 is "~/.cshrc", you need to do another expand() to have the
2255 "~/" expanded into the path of the home directory: >
2256 :echo expand(expand("<cfile>"))
2257 <
2258 There cannot be white space between the variables and the
2259 following modifier. The |fnamemodify()| function can be used
2260 to modify normal file names.
2261
2262 When using '%' or '#', and the current or alternate file name
2263 is not defined, an empty string is used. Using "%:p" in a
2264 buffer with no name, results in the current directory, with a
2265 '/' added.
2266
2267 When {string} does not start with '%', '#' or '<', it is
2268 expanded like a file name is expanded on the command line.
2269 'suffixes' and 'wildignore' are used, unless the optional
2270 {nosuf} argument is given and it is |TRUE|.
2271 Names for non-existing files are included. The "**" item can
2272 be used to search in a directory tree. For example, to find
2273 all "README" files in the current directory and below: >
2274 :echo expand("**/README")
2275 <
2276 expand() can also be used to expand variables and environment
2277 variables that are only known in a shell. But this can be
2278 slow, because a shell may be used to do the expansion. See
2279 |expr-env-expand|.
2280 The expanded variable is still handled like a list of file
2281 names. When an environment variable cannot be expanded, it is
2282 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2283 "$FOOBAR".
2284
2285 See |glob()| for finding existing files. See |system()| for
2286 getting the raw output of an external command.
2287
2288 Can also be used as a |method|: >
2289 Getpattern()->expand()
2290
2291 expandcmd({string}) *expandcmd()*
2292 Expand special items in String {string} like what is done for
2293 an Ex command such as `:edit`. This expands special keywords,
2294 like with |expand()|, and environment variables, anywhere in
2295 {string}. "~user" and "~/path" are only expanded at the
2296 start.
2297 Returns the expanded string. Example: >
2298 :echo expandcmd('make %<.o')
2299
2300 < Can also be used as a |method|: >
2301 GetCommand()->expandcmd()
2302 <
2303 extend({expr1}, {expr2} [, {expr3}]) *extend()*
2304 {expr1} and {expr2} must be both |Lists| or both
2305 |Dictionaries|.
2306
2307 If they are |Lists|: Append {expr2} to {expr1}.
2308 If {expr3} is given insert the items of {expr2} before the
2309 item with index {expr3} in {expr1}. When {expr3} is zero
2310 insert before the first item. When {expr3} is equal to
2311 len({expr1}) then {expr2} is appended.
2312 Examples: >
2313 :echo sort(extend(mylist, [7, 5]))
2314 :call extend(mylist, [2, 3], 1)
2315 < When {expr1} is the same List as {expr2} then the number of
2316 items copied is equal to the original length of the List.
2317 E.g., when {expr3} is 1 you get N new copies of the first item
2318 (where N is the original length of the List).
2319 Use |add()| to concatenate one item to a list. To concatenate
2320 two lists into a new list use the + operator: >
2321 :let newlist = [1, 2, 3] + [4, 5]
2322 <
2323 If they are |Dictionaries|:
2324 Add all entries from {expr2} to {expr1}.
2325 If a key exists in both {expr1} and {expr2} then {expr3} is
2326 used to decide what to do:
2327 {expr3} = "keep": keep the value of {expr1}
2328 {expr3} = "force": use the value of {expr2}
2329 {expr3} = "error": give an error message *E737*
2330 When {expr3} is omitted then "force" is assumed.
2331
2332 {expr1} is changed when {expr2} is not empty. If necessary
2333 make a copy of {expr1} first.
2334 {expr2} remains unchanged.
2335 When {expr1} is locked and {expr2} is not empty the operation
2336 fails.
2337 Returns {expr1}.
2338
2339 Can also be used as a |method|: >
2340 mylist->extend(otherlist)
2341
2342
2343 extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2344 Like |extend()| but instead of adding items to {expr1} a new
2345 List or Dictionary is created and returned. {expr1} remains
2346 unchanged. Items can still be changed by {expr2}, if you
2347 don't want that use |deepcopy()| first.
2348
2349
2350 feedkeys({string} [, {mode}]) *feedkeys()*
2351 Characters in {string} are queued for processing as if they
2352 come from a mapping or were typed by the user.
2353
2354 By default the string is added to the end of the typeahead
2355 buffer, thus if a mapping is still being executed the
2356 characters come after them. Use the 'i' flag to insert before
2357 other characters, they will be executed next, before any
2358 characters from a mapping.
2359
2360 The function does not wait for processing of keys contained in
2361 {string}.
2362
2363 To include special keys into {string}, use double-quotes
2364 and "\..." notation |expr-quote|. For example,
2365 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2366 feedkeys('\<CR>') pushes 5 characters.
2367 A special code that might be useful is <Ignore>, it exits the
2368 wait for a character without doing anything. *<Ignore>*
2369
2370 {mode} is a String, which can contain these character flags:
2371 'm' Remap keys. This is default. If {mode} is absent,
2372 keys are remapped.
2373 'n' Do not remap keys.
2374 't' Handle keys as if typed; otherwise they are handled as
2375 if coming from a mapping. This matters for undo,
2376 opening folds, etc.
2377 'L' Lowlevel input. Only works for Unix or when using the
2378 GUI. Keys are used as if they were coming from the
2379 terminal. Other flags are not used. *E980*
2380 When a CTRL-C interrupts and 't' is included it sets
2381 the internal "got_int" flag.
2382 'i' Insert the string instead of appending (see above).
2383 'x' Execute commands until typeahead is empty. This is
2384 similar to using ":normal!". You can call feedkeys()
2385 several times without 'x' and then one time with 'x'
2386 (possibly with an empty {string}) to execute all the
2387 typeahead. Note that when Vim ends in Insert mode it
2388 will behave as if <Esc> is typed, to avoid getting
2389 stuck, waiting for a character to be typed before the
2390 script continues.
2391 Note that if you manage to call feedkeys() while
2392 executing commands, thus calling it recursively, then
2393 all typeahead will be consumed by the last call.
2394 '!' When used with 'x' will not end Insert mode. Can be
2395 used in a test when a timer is set to exit Insert mode
2396 a little later. Useful for testing CursorHoldI.
2397
2398 Return value is always 0.
2399
2400 Can also be used as a |method|: >
2401 GetInput()->feedkeys()
2402
2403 filereadable({file}) *filereadable()*
2404 The result is a Number, which is |TRUE| when a file with the
2405 name {file} exists, and can be read. If {file} doesn't exist,
2406 or is a directory, the result is |FALSE|. {file} is any
2407 expression, which is used as a String.
2408 If you don't care about the file being readable you can use
2409 |glob()|.
2410 {file} is used as-is, you may want to expand wildcards first: >
2411 echo filereadable('~/.vimrc')
2412 0
2413 echo filereadable(expand('~/.vimrc'))
2414 1
2415
2416 < Can also be used as a |method|: >
2417 GetName()->filereadable()
2418 < *file_readable()*
2419 Obsolete name: file_readable().
2420
2421
2422 filewritable({file}) *filewritable()*
2423 The result is a Number, which is 1 when a file with the
2424 name {file} exists, and can be written. If {file} doesn't
2425 exist, or is not writable, the result is 0. If {file} is a
2426 directory, and we can write to it, the result is 2.
2427
2428 Can also be used as a |method|: >
2429 GetName()->filewritable()
2430
2431
2432 filter({expr1}, {expr2}) *filter()*
2433 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
2434 For each item in {expr1} evaluate {expr2} and when the result
2435 is zero or false remove the item from the |List| or
2436 |Dictionary|. Similarly for each byte in a |Blob| and each
2437 charactor in a |String|.
2438
2439 {expr2} must be a |string| or |Funcref|.
2440
2441 If {expr2} is a |string|, inside {expr2} |v:val| has the value
2442 of the current item. For a |Dictionary| |v:key| has the key
2443 of the current item and for a |List| |v:key| has the index of
2444 the current item. For a |Blob| |v:key| has the index of the
2445 current byte. For a |String| |v:key| has the index of the
2446 current character.
2447 Examples: >
2448 call filter(mylist, 'v:val !~ "OLD"')
2449 < Removes the items where "OLD" appears. >
2450 call filter(mydict, 'v:key >= 8')
2451 < Removes the items with a key below 8. >
2452 call filter(var, 0)
2453 < Removes all the items, thus clears the |List| or |Dictionary|.
2454
2455 Note that {expr2} is the result of expression and is then
2456 used as an expression again. Often it is good to use a
2457 |literal-string| to avoid having to double backslashes.
2458
2459 If {expr2} is a |Funcref| it must take two arguments:
2460 1. the key or the index of the current item.
2461 2. the value of the current item.
2462 The function must return |TRUE| if the item should be kept.
2463 Example that keeps the odd items of a list: >
2464 func Odd(idx, val)
2465 return a:idx % 2 == 1
2466 endfunc
2467 call filter(mylist, function('Odd'))
2468 < It is shorter when using a |lambda|: >
2469 call filter(myList, {idx, val -> idx * val <= 42})
2470 < If you do not use "val" you can leave it out: >
2471 call filter(myList, {idx -> idx % 2 == 1})
2472 <
2473 In |Vim9| script the result must be true, false, zero or one.
2474 Other values will result in a type error.
2475
2476 For a |List| and a |Dictionary| the operation is done
2477 in-place. If you want it to remain unmodified make a copy
2478 first: >
2479 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2480
2481 < Returns {expr1}, the |List| or |Dictionary| that was filtered,
2482 or a new |Blob| or |String|.
2483 When an error is encountered while evaluating {expr2} no
2484 further items in {expr1} are processed.
2485 When {expr2} is a Funcref errors inside a function are ignored,
2486 unless it was defined with the "abort" flag.
2487
2488 Can also be used as a |method|: >
2489 mylist->filter(expr2)
2490
2491 finddir({name} [, {path} [, {count}]]) *finddir()*
2492 Find directory {name} in {path}. Supports both downwards and
2493 upwards recursive directory searches. See |file-searching|
2494 for the syntax of {path}.
2495
2496 Returns the path of the first found match. When the found
2497 directory is below the current directory a relative path is
2498 returned. Otherwise a full path is returned.
2499 If {path} is omitted or empty then 'path' is used.
2500
2501 If the optional {count} is given, find {count}'s occurrence of
2502 {name} in {path} instead of the first one.
2503 When {count} is negative return all the matches in a |List|.
2504
2505 This is quite similar to the ex-command `:find`.
2506 {only available when compiled with the |+file_in_path|
2507 feature}
2508
2509 Can also be used as a |method|: >
2510 GetName()->finddir()
2511
2512 findfile({name} [, {path} [, {count}]]) *findfile()*
2513 Just like |finddir()|, but find a file instead of a directory.
2514 Uses 'suffixesadd'.
2515 Example: >
2516 :echo findfile("tags.vim", ".;")
2517 < Searches from the directory of the current file upwards until
2518 it finds the file "tags.vim".
2519
2520 Can also be used as a |method|: >
2521 GetName()->findfile()
2522
2523 flatten({list} [, {maxdepth}]) *flatten()*
2524 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
2525 the result is a |List| without nesting, as if {maxdepth} is
2526 a very large number.
2527 The {list} is changed in place, use |flattennew()| if you do
2528 not want that.
2529 In Vim9 script flatten() cannot be used, you must always use
2530 |flattennew()|.
2531 *E900*
2532 {maxdepth} means how deep in nested lists changes are made.
2533 {list} is not modified when {maxdepth} is 0.
2534 {maxdepth} must be positive number.
2535
2536 If there is an error the number zero is returned.
2537
2538 Example: >
2539 :echo flatten([1, [2, [3, 4]], 5])
2540 < [1, 2, 3, 4, 5] >
2541 :echo flatten([1, [2, [3, 4]], 5], 1)
2542 < [1, 2, [3, 4], 5]
2543
2544 Can also be used as a |method|: >
2545 mylist->flatten()
2546 <
2547 flattennew({list} [, {maxdepth}]) *flattennew()*
2548 Like |flatten()| but first make a copy of {list}.
2549
2550
2551 float2nr({expr}) *float2nr()*
2552 Convert {expr} to a Number by omitting the part after the
2553 decimal point.
2554 {expr} must evaluate to a |Float| or a Number.
2555 When the value of {expr} is out of range for a |Number| the
2556 result is truncated to 0x7fffffff or -0x7fffffff (or when
2557 64-bit Number support is enabled, 0x7fffffffffffffff or
2558 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
2559 64-bit Number support is enabled, -0x8000000000000000).
2560 Examples: >
2561 echo float2nr(3.95)
2562 < 3 >
2563 echo float2nr(-23.45)
2564 < -23 >
2565 echo float2nr(1.0e100)
2566 < 2147483647 (or 9223372036854775807) >
2567 echo float2nr(-1.0e150)
2568 < -2147483647 (or -9223372036854775807) >
2569 echo float2nr(1.0e-100)
2570 < 0
2571
2572 Can also be used as a |method|: >
2573 Compute()->float2nr()
2574 <
2575 {only available when compiled with the |+float| feature}
2576
2577
2578 floor({expr}) *floor()*
2579 Return the largest integral value less than or equal to
2580 {expr} as a |Float| (round down).
2581 {expr} must evaluate to a |Float| or a |Number|.
2582 Examples: >
2583 echo floor(1.856)
2584 < 1.0 >
2585 echo floor(-5.456)
2586 < -6.0 >
2587 echo floor(4.0)
2588 < 4.0
2589
2590 Can also be used as a |method|: >
2591 Compute()->floor()
2592 <
2593 {only available when compiled with the |+float| feature}
2594
2595
2596 fmod({expr1}, {expr2}) *fmod()*
2597 Return the remainder of {expr1} / {expr2}, even if the
2598 division is not representable. Returns {expr1} - i * {expr2}
2599 for some integer i such that if {expr2} is non-zero, the
2600 result has the same sign as {expr1} and magnitude less than
2601 the magnitude of {expr2}. If {expr2} is zero, the value
2602 returned is zero. The value returned is a |Float|.
2603 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
2604 Examples: >
2605 :echo fmod(12.33, 1.22)
2606 < 0.13 >
2607 :echo fmod(-12.33, 1.22)
2608 < -0.13
2609
2610 Can also be used as a |method|: >
2611 Compute()->fmod(1.22)
2612 <
2613 {only available when compiled with |+float| feature}
2614
2615
2616 fnameescape({string}) *fnameescape()*
2617 Escape {string} for use as file name command argument. All
2618 characters that have a special meaning, such as '%' and '|'
2619 are escaped with a backslash.
2620 For most systems the characters escaped are
2621 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2622 appears in a filename, it depends on the value of 'isfname'.
2623 A leading '+' and '>' is also escaped (special after |:edit|
2624 and |:write|). And a "-" by itself (special after |:cd|).
2625 Example: >
2626 :let fname = '+some str%nge|name'
2627 :exe "edit " . fnameescape(fname)
2628 < results in executing: >
2629 edit \+some\ str\%nge\|name
2630 <
2631 Can also be used as a |method|: >
2632 GetName()->fnameescape()
2633
2634 fnamemodify({fname}, {mods}) *fnamemodify()*
2635 Modify file name {fname} according to {mods}. {mods} is a
2636 string of characters like it is used for file names on the
2637 command line. See |filename-modifiers|.
2638 Example: >
2639 :echo fnamemodify("main.c", ":p:h")
2640 < results in: >
2641 /home/mool/vim/vim/src
2642 < If {mods} is empty then {fname} is returned.
2643 Note: Environment variables don't work in {fname}, use
2644 |expand()| first then.
2645
2646 Can also be used as a |method|: >
2647 GetName()->fnamemodify(':p:h')
2648
2649 foldclosed({lnum}) *foldclosed()*
2650 The result is a Number. If the line {lnum} is in a closed
2651 fold, the result is the number of the first line in that fold.
2652 If the line {lnum} is not in a closed fold, -1 is returned.
2653 {lnum} is used like with |getline()|. Thus "." is the current
2654 line, "'m" mark m, etc.
2655
2656 Can also be used as a |method|: >
2657 GetLnum()->foldclosed()
2658
2659 foldclosedend({lnum}) *foldclosedend()*
2660 The result is a Number. If the line {lnum} is in a closed
2661 fold, the result is the number of the last line in that fold.
2662 If the line {lnum} is not in a closed fold, -1 is returned.
2663 {lnum} is used like with |getline()|. Thus "." is the current
2664 line, "'m" mark m, etc.
2665
2666 Can also be used as a |method|: >
2667 GetLnum()->foldclosedend()
2668
2669 foldlevel({lnum}) *foldlevel()*
2670 The result is a Number, which is the foldlevel of line {lnum}
2671 in the current buffer. For nested folds the deepest level is
2672 returned. If there is no fold at line {lnum}, zero is
2673 returned. It doesn't matter if the folds are open or closed.
2674 When used while updating folds (from 'foldexpr') -1 is
2675 returned for lines where folds are still to be updated and the
2676 foldlevel is unknown. As a special case the level of the
2677 previous line is usually available.
2678 {lnum} is used like with |getline()|. Thus "." is the current
2679 line, "'m" mark m, etc.
2680
2681 Can also be used as a |method|: >
2682 GetLnum()->foldlevel()
2683 <
2684 *foldtext()*
2685 foldtext() Returns a String, to be displayed for a closed fold. This is
2686 the default function used for the 'foldtext' option and should
2687 only be called from evaluating 'foldtext'. It uses the
2688 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2689 The returned string looks like this: >
2690 +-- 45 lines: abcdef
2691 < The number of leading dashes depends on the foldlevel. The
2692 "45" is the number of lines in the fold. "abcdef" is the text
2693 in the first non-blank line of the fold. Leading white space,
2694 "//" or "/*" and the text from the 'foldmarker' and
2695 'commentstring' options is removed.
2696 When used to draw the actual foldtext, the rest of the line
2697 will be filled with the fold char from the 'fillchars'
2698 setting.
2699 {not available when compiled without the |+folding| feature}
2700
2701 foldtextresult({lnum}) *foldtextresult()*
2702 Returns the text that is displayed for the closed fold at line
2703 {lnum}. Evaluates 'foldtext' in the appropriate context.
2704 When there is no closed fold at {lnum} an empty string is
2705 returned.
2706 {lnum} is used like with |getline()|. Thus "." is the current
2707 line, "'m" mark m, etc.
2708 Useful when exporting folded text, e.g., to HTML.
2709 {not available when compiled without the |+folding| feature}
2710
2711
2712 Can also be used as a |method|: >
2713 GetLnum()->foldtextresult()
2714 <
2715 *foreground()*
2716 foreground() Move the Vim window to the foreground. Useful when sent from
2717 a client to a Vim server. |remote_send()|
2718 On Win32 systems this might not work, the OS does not always
2719 allow a window to bring itself to the foreground. Use
2720 |remote_foreground()| instead.
2721 {only in the Win32, Athena, Motif and GTK GUI versions and the
2722 Win32 console version}
2723
2724 fullcommand({name}) *fullcommand()*
2725 Get the full command name from a short abbreviated command
2726 name; see |20.2| for details on command abbreviations.
2727
2728 The string argument {name} may start with a `:` and can
2729 include a [range], these are skipped and not returned.
2730 Returns an empty string if a command doesn't exist or if it's
2731 ambiguous (for user-defined commands).
2732
2733 For example `fullcommand('s')`, `fullcommand('sub')`,
2734 `fullcommand(':%substitute')` all return "substitute".
2735
2736 Can also be used as a |method|: >
2737 GetName()->fullcommand()
2738 <
2739 *funcref()*
2740 funcref({name} [, {arglist}] [, {dict}])
2741 Just like |function()|, but the returned Funcref will lookup
2742 the function by reference, not by name. This matters when the
2743 function {name} is redefined later.
2744
2745 Unlike |function()|, {name} must be an existing user function.
2746 Also for autoloaded functions. {name} cannot be a builtin
2747 function.
2748
2749 Can also be used as a |method|: >
2750 GetFuncname()->funcref([arg])
2751 <
2752 *function()* *partial* *E700* *E922* *E923*
2753 function({name} [, {arglist}] [, {dict}])
2754 Return a |Funcref| variable that refers to function {name}.
2755 {name} can be the name of a user defined function or an
2756 internal function.
2757
2758 {name} can also be a Funcref or a partial. When it is a
2759 partial the dict stored in it will be used and the {dict}
2760 argument is not allowed. E.g.: >
2761 let FuncWithArg = function(dict.Func, [arg])
2762 let Broken = function(dict.Func, [arg], dict)
2763 <
2764 When using the Funcref the function will be found by {name},
2765 also when it was redefined later. Use |funcref()| to keep the
2766 same function.
2767
2768 When {arglist} or {dict} is present this creates a partial.
2769 That means the argument list and/or the dictionary is stored in
2770 the Funcref and will be used when the Funcref is called.
2771
2772 The arguments are passed to the function in front of other
2773 arguments, but after any argument from |method|. Example: >
2774 func Callback(arg1, arg2, name)
2775 ...
2776 let Partial = function('Callback', ['one', 'two'])
2777 ...
2778 call Partial('name')
2779 < Invokes the function as with: >
2780 call Callback('one', 'two', 'name')
2781
2782 < With a |method|: >
2783 func Callback(one, two, three)
2784 ...
2785 let Partial = function('Callback', ['two'])
2786 ...
2787 eval 'one'->Partial('three')
2788 < Invokes the function as with: >
2789 call Callback('one', 'two', 'three')
2790
2791 < The function() call can be nested to add more arguments to the
2792 Funcref. The extra arguments are appended to the list of
2793 arguments. Example: >
2794 func Callback(arg1, arg2, name)
2795 ...
2796 let Func = function('Callback', ['one'])
2797 let Func2 = function(Func, ['two'])
2798 ...
2799 call Func2('name')
2800 < Invokes the function as with: >
2801 call Callback('one', 'two', 'name')
2802
2803 < The Dictionary is only useful when calling a "dict" function.
2804 In that case the {dict} is passed in as "self". Example: >
2805 function Callback() dict
2806 echo "called for " . self.name
2807 endfunction
2808 ...
2809 let context = {"name": "example"}
2810 let Func = function('Callback', context)
2811 ...
2812 call Func() " will echo: called for example
2813 < The use of function() is not needed when there are no extra
2814 arguments, these two are equivalent: >
2815 let Func = function('Callback', context)
2816 let Func = context.Callback
2817
2818 < The argument list and the Dictionary can be combined: >
2819 function Callback(arg1, count) dict
2820 ...
2821 let context = {"name": "example"}
2822 let Func = function('Callback', ['one'], context)
2823 ...
2824 call Func(500)
2825 < Invokes the function as with: >
2826 call context.Callback('one', 500)
2827 <
2828 Can also be used as a |method|: >
2829 GetFuncname()->function([arg])
2830
2831
2832 garbagecollect([{atexit}]) *garbagecollect()*
2833 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
2834 that have circular references.
2835
2836 There is hardly ever a need to invoke this function, as it is
2837 automatically done when Vim runs out of memory or is waiting
2838 for the user to press a key after 'updatetime'. Items without
2839 circular references are always freed when they become unused.
2840 This is useful if you have deleted a very big |List| and/or
2841 |Dictionary| with circular references in a script that runs
2842 for a long time.
2843
2844 When the optional {atexit} argument is one, garbage
2845 collection will also be done when exiting Vim, if it wasn't
2846 done before. This is useful when checking for memory leaks.
2847
2848 The garbage collection is not done immediately but only when
2849 it's safe to perform. This is when waiting for the user to
2850 type a character. To force garbage collection immediately use
2851 |test_garbagecollect_now()|.
2852
2853 get({list}, {idx} [, {default}]) *get()*
2854 Get item {idx} from |List| {list}. When this item is not
2855 available return {default}. Return zero when {default} is
2856 omitted.
2857 Preferably used as a |method|: >
2858 mylist->get(idx)
2859 get({blob}, {idx} [, {default}])
2860 Get byte {idx} from |Blob| {blob}. When this byte is not
2861 available return {default}. Return -1 when {default} is
2862 omitted.
2863 Preferably used as a |method|: >
2864 myblob->get(idx)
2865 get({dict}, {key} [, {default}])
2866 Get item with key {key} from |Dictionary| {dict}. When this
2867 item is not available return {default}. Return zero when
2868 {default} is omitted. Useful example: >
2869 let val = get(g:, 'var_name', 'default')
2870 < This gets the value of g:var_name if it exists, and uses
2871 'default' when it does not exist.
2872 Preferably used as a |method|: >
2873 mydict->get(key)
2874 get({func}, {what})
2875 Get an item with from Funcref {func}. Possible values for
2876 {what} are:
2877 "name" The function name
2878 "func" The function
2879 "dict" The dictionary
2880 "args" The list with arguments
2881 Preferably used as a |method|: >
2882 myfunc->get(what)
2883 <
2884 *getbufinfo()*
2885 getbufinfo([{buf}])
2886 getbufinfo([{dict}])
2887 Get information about buffers as a List of Dictionaries.
2888
2889 Without an argument information about all the buffers is
2890 returned.
2891
2892 When the argument is a |Dictionary| only the buffers matching
2893 the specified criteria are returned. The following keys can
2894 be specified in {dict}:
2895 buflisted include only listed buffers.
2896 bufloaded include only loaded buffers.
2897 bufmodified include only modified buffers.
2898
2899 Otherwise, {buf} specifies a particular buffer to return
2900 information for. For the use of {buf}, see |bufname()|
2901 above. If the buffer is found the returned List has one item.
2902 Otherwise the result is an empty list.
2903
2904 Each returned List item is a dictionary with the following
2905 entries:
2906 bufnr Buffer number.
2907 changed TRUE if the buffer is modified.
2908 changedtick Number of changes made to the buffer.
2909 hidden TRUE if the buffer is hidden.
2910 lastused Timestamp in seconds, like
2911 |localtime()|, when the buffer was
2912 last used.
2913 {only with the |+viminfo| feature}
2914 listed TRUE if the buffer is listed.
2915 lnum Line number used for the buffer when
2916 opened in the current window.
2917 Only valid if the buffer has been
2918 displayed in the window in the past.
2919 If you want the line number of the
2920 last known cursor position in a given
2921 window, use |line()|: >
2922 :echo line('.', {winid})
2923 <
2924 linecount Number of lines in the buffer (only
2925 valid when loaded)
2926 loaded TRUE if the buffer is loaded.
2927 name Full path to the file in the buffer.
2928 signs List of signs placed in the buffer.
2929 Each list item is a dictionary with
2930 the following fields:
2931 id sign identifier
2932 lnum line number
2933 name sign name
2934 variables A reference to the dictionary with
2935 buffer-local variables.
2936 windows List of |window-ID|s that display this
2937 buffer
2938 popups List of popup |window-ID|s that
2939 display this buffer
2940
2941 Examples: >
2942 for buf in getbufinfo()
2943 echo buf.name
2944 endfor
2945 for buf in getbufinfo({'buflisted':1})
2946 if buf.changed
2947 ....
2948 endif
2949 endfor
2950 <
2951 To get buffer-local options use: >
2952 getbufvar({bufnr}, '&option_name')
2953 <
2954 Can also be used as a |method|: >
2955 GetBufnr()->getbufinfo()
2956 <
2957
2958 *getbufline()*
2959 getbufline({buf}, {lnum} [, {end}])
2960 Return a |List| with the lines starting from {lnum} to {end}
2961 (inclusive) in the buffer {buf}. If {end} is omitted, a
2962 |List| with only the line {lnum} is returned.
2963
2964 For the use of {buf}, see |bufname()| above.
2965
2966 For {lnum} and {end} "$" can be used for the last line of the
2967 buffer. Otherwise a number must be used.
2968
2969 When {lnum} is smaller than 1 or bigger than the number of
2970 lines in the buffer, an empty |List| is returned.
2971
2972 When {end} is greater than the number of lines in the buffer,
2973 it is treated as {end} is set to the number of lines in the
2974 buffer. When {end} is before {lnum} an empty |List| is
2975 returned.
2976
2977 This function works only for loaded buffers. For unloaded and
2978 non-existing buffers, an empty |List| is returned.
2979
2980 Example: >
2981 :let lines = getbufline(bufnr("myfile"), 1, "$")
2982
2983 < Can also be used as a |method|: >
2984 GetBufnr()->getbufline(lnum)
2985
2986 getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
2987 The result is the value of option or local buffer variable
2988 {varname} in buffer {buf}. Note that the name without "b:"
2989 must be used.
2990 The {varname} argument is a string.
2991 When {varname} is empty returns a |Dictionary| with all the
2992 buffer-local variables.
2993 When {varname} is equal to "&" returns a |Dictionary| with all
2994 the buffer-local options.
2995 Otherwise, when {varname} starts with "&" returns the value of
2996 a buffer-local option.
2997 This also works for a global or buffer-local option, but it
2998 doesn't work for a global variable, window-local variable or
2999 window-local option.
3000 For the use of {buf}, see |bufname()| above.
3001 When the buffer or variable doesn't exist {def} or an empty
3002 string is returned, there is no error message.
3003 Examples: >
3004 :let bufmodified = getbufvar(1, "&mod")
3005 :echo "todo myvar = " . getbufvar("todo", "myvar")
3006
3007 < Can also be used as a |method|: >
3008 GetBufnr()->getbufvar(varname)
3009 <
3010 getchangelist([{buf}]) *getchangelist()*
3011 Returns the |changelist| for the buffer {buf}. For the use
3012 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3013 exist, an empty list is returned.
3014
3015 The returned list contains two entries: a list with the change
3016 locations and the current position in the list. Each
3017 entry in the change list is a dictionary with the following
3018 entries:
3019 col column number
3020 coladd column offset for 'virtualedit'
3021 lnum line number
3022 If buffer {buf} is the current buffer, then the current
3023 position refers to the position in the list. For other
3024 buffers, it is set to the length of the list.
3025
3026 Can also be used as a |method|: >
3027 GetBufnr()->getchangelist()
3028
3029 getchar([expr]) *getchar()*
3030 Get a single character from the user or input stream.
3031 If [expr] is omitted, wait until a character is available.
3032 If [expr] is 0, only get a character when one is available.
3033 Return zero otherwise.
3034 If [expr] is 1, only check if a character is available, it is
3035 not consumed. Return zero if no character available.
3036 If you prefer always getting a string use |getcharstr()|.
3037
3038 Without [expr] and when [expr] is 0 a whole character or
3039 special key is returned. If it is a single character, the
3040 result is a number. Use nr2char() to convert it to a String.
3041 Otherwise a String is returned with the encoded character.
3042 For a special key it's a String with a sequence of bytes
3043 starting with 0x80 (decimal: 128). This is the same value as
3044 the String "\<Key>", e.g., "\<Left>". The returned value is
3045 also a String when a modifier (shift, control, alt) was used
3046 that is not included in the character.
3047
3048 When [expr] is 0 and Esc is typed, there will be a short delay
3049 while Vim waits to see if this is the start of an escape
3050 sequence.
3051
3052 When [expr] is 1 only the first byte is returned. For a
3053 one-byte character it is the character itself as a number.
3054 Use nr2char() to convert it to a String.
3055
3056 Use getcharmod() to obtain any additional modifiers.
3057
3058 When the user clicks a mouse button, the mouse event will be
3059 returned. The position can then be found in |v:mouse_col|,
3060 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3061 |getmousepos()| can also be used. Mouse move events will be
3062 ignored.
3063 This example positions the mouse as it would normally happen: >
3064 let c = getchar()
3065 if c == "\<LeftMouse>" && v:mouse_win > 0
3066 exe v:mouse_win . "wincmd w"
3067 exe v:mouse_lnum
3068 exe "normal " . v:mouse_col . "|"
3069 endif
3070 <
3071 When using bracketed paste only the first character is
3072 returned, the rest of the pasted text is dropped.
3073 |xterm-bracketed-paste|.
3074
3075 There is no prompt, you will somehow have to make clear to the
3076 user that a character has to be typed. The screen is not
3077 redrawn, e.g. when resizing the window. When using a popup
3078 window it should work better with a |popup-filter|.
3079
3080 There is no mapping for the character.
3081 Key codes are replaced, thus when the user presses the <Del>
3082 key you get the code for the <Del> key, not the raw character
3083 sequence. Examples: >
3084 getchar() == "\<Del>"
3085 getchar() == "\<S-Left>"
3086 < This example redefines "f" to ignore case: >
3087 :nmap f :call FindChar()<CR>
3088 :function FindChar()
3089 : let c = nr2char(getchar())
3090 : while col('.') < col('$') - 1
3091 : normal l
3092 : if getline('.')[col('.') - 1] ==? c
3093 : break
3094 : endif
3095 : endwhile
3096 :endfunction
3097 <
3098 You may also receive synthetic characters, such as
3099 |<CursorHold>|. Often you will want to ignore this and get
3100 another character: >
3101 :function GetKey()
3102 : let c = getchar()
3103 : while c == "\<CursorHold>"
3104 : let c = getchar()
3105 : endwhile
3106 : return c
3107 :endfunction
3108
3109 getcharmod() *getcharmod()*
3110 The result is a Number which is the state of the modifiers for
3111 the last obtained character with getchar() or in another way.
3112 These values are added together:
3113 2 shift
3114 4 control
3115 8 alt (meta)
3116 16 meta (when it's different from ALT)
3117 32 mouse double click
3118 64 mouse triple click
3119 96 mouse quadruple click (== 32 + 64)
3120 128 command (Macintosh only)
3121 Only the modifiers that have not been included in the
3122 character itself are obtained. Thus Shift-a results in "A"
3123 without a modifier.
3124
3125 *getcharpos()*
3126 getcharpos({expr})
3127 Get the position for String {expr}. Same as |getpos()| but the
3128 column number in the returned List is a character index
3129 instead of a byte index.
3130 If |getpos()| returns a very large column number, such as
3131 2147483647, then getcharpos() will return the character index
3132 of the last character.
3133
3134 Example:
3135 With the cursor on '세' in line 5 with text "여보세요": >
3136 getcharpos('.') returns [0, 5, 3, 0]
3137 getpos('.') returns [0, 5, 7, 0]
3138 <
3139 Can also be used as a |method|: >
3140 GetMark()->getcharpos()
3141
3142 getcharsearch() *getcharsearch()*
3143 Return the current character search information as a {dict}
3144 with the following entries:
3145
3146 char character previously used for a character
3147 search (|t|, |f|, |T|, or |F|); empty string
3148 if no character search has been performed
3149 forward direction of character search; 1 for forward,
3150 0 for backward
3151 until type of character search; 1 for a |t| or |T|
3152 character search, 0 for an |f| or |F|
3153 character search
3154
3155 This can be useful to always have |;| and |,| search
3156 forward/backward regardless of the direction of the previous
3157 character search: >
3158 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3159 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3160 < Also see |setcharsearch()|.
3161
3162
3163 getcharstr([expr]) *getcharstr()*
3164 Get a single character from the user or input stream as a
3165 string.
3166 If [expr] is omitted, wait until a character is available.
3167 If [expr] is 0 or false, only get a character when one is
3168 available. Return an empty string otherwise.
3169 If [expr] is 1 or true, only check if a character is
3170 available, it is not consumed. Return an empty string
3171 if no character is available.
3172 Otherwise this works like |getchar()|, except that a number
3173 result is converted to a string.
3174
3175
3176 getcmdline() *getcmdline()*
3177 Return the current command-line. Only works when the command
3178 line is being edited, thus requires use of |c_CTRL-\_e| or
3179 |c_CTRL-R_=|.
3180 Example: >
3181 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
3182 < Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
3183 Returns an empty string when entering a password or using
3184 |inputsecret()|.
3185
3186 getcmdpos() *getcmdpos()*
3187 Return the position of the cursor in the command line as a
3188 byte count. The first column is 1.
3189 Only works when editing the command line, thus requires use of
3190 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3191 Returns 0 otherwise.
3192 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3193
3194 getcmdtype() *getcmdtype()*
3195 Return the current command-line type. Possible return values
3196 are:
3197 : normal Ex command
3198 > debug mode command |debug-mode|
3199 / forward search command
3200 ? backward search command
3201 @ |input()| command
3202 - |:insert| or |:append| command
3203 = |i_CTRL-R_=|
3204 Only works when editing the command line, thus requires use of
3205 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3206 Returns an empty string otherwise.
3207 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3208
3209 getcmdwintype() *getcmdwintype()*
3210 Return the current |command-line-window| type. Possible return
3211 values are the same as |getcmdtype()|. Returns an empty string
3212 when not in the command-line window.
3213
3214 getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
3215 Return a list of command-line completion matches. The String
3216 {type} argument specifies what for. The following completion
3217 types are supported:
3218
3219 arglist file names in argument list
3220 augroup autocmd groups
3221 buffer buffer names
3222 behave :behave suboptions
3223 color color schemes
3224 command Ex command
3225 cmdline |cmdline-completion| result
3226 compiler compilers
3227 cscope |:cscope| suboptions
3228 diff_buffer |:diffget| and |:diffput| completion
3229 dir directory names
3230 environment environment variable names
3231 event autocommand events
3232 expression Vim expression
3233 file file and directory names
3234 file_in_path file and directory names in |'path'|
3235 filetype filetype names |'filetype'|
3236 function function name
3237 help help subjects
3238 highlight highlight groups
3239 history :history suboptions
3240 locale locale names (as output of locale -a)
3241 mapclear buffer argument
3242 mapping mapping name
3243 menu menus
3244 messages |:messages| suboptions
3245 option options
3246 packadd optional package |pack-add| names
3247 shellcmd Shell command
3248 sign |:sign| suboptions
3249 syntax syntax file names |'syntax'|
3250 syntime |:syntime| suboptions
3251 tag tags
3252 tag_listfiles tags, file names
3253 user user names
3254 var user variables
3255
3256 If {pat} is an empty string, then all the matches are
3257 returned. Otherwise only items matching {pat} are returned.
3258 See |wildcards| for the use of special characters in {pat}.
3259
3260 If the optional {filtered} flag is set to 1, then 'wildignore'
3261 is applied to filter the results. Otherwise all the matches
3262 are returned. The 'wildignorecase' option always applies.
3263
3264 If {type} is "cmdline", then the |cmdline-completion| result is
3265 returned. For example, to complete the possible values after
3266 a ":call" command: >
3267 echo getcompletion('call ', 'cmdline')
3268 <
3269 If there are no matches, an empty list is returned. An
3270 invalid value for {type} produces an error.
3271
3272 Can also be used as a |method|: >
3273 GetPattern()->getcompletion('color')
3274 <
3275 *getcurpos()*
3276 getcurpos([{winid}])
3277 Get the position of the cursor. This is like getpos('.'), but
3278 includes an extra "curswant" item in the list:
3279 [0, lnum, col, off, curswant] ~
3280 The "curswant" number is the preferred column when moving the
3281 cursor vertically. Also see |getcursorcharpos()| and
3282 |getpos()|.
3283 The first "bufnum" item is always zero. The byte position of
3284 the cursor is returned in 'col'. To get the character
3285 position, use |getcursorcharpos()|.
3286
3287 The optional {winid} argument can specify the window. It can
3288 be the window number or the |window-ID|. The last known
3289 cursor position is returned, this may be invalid for the
3290 current value of the buffer if it is not the current window.
3291 If {winid} is invalid a list with zeroes is returned.
3292
3293 This can be used to save and restore the cursor position: >
3294 let save_cursor = getcurpos()
3295 MoveTheCursorAround
3296 call setpos('.', save_cursor)
3297 < Note that this only works within the window. See
3298 |winrestview()| for restoring more state.
3299
3300 Can also be used as a |method|: >
3301 GetWinid()->getcurpos()
3302 <
3303 *getcursorcharpos()*
3304 getcursorcharpos([{winid}])
3305 Same as |getcurpos()| but the column number in the returned
3306 List is a character index instead of a byte index.
3307
3308 Example:
3309 With the cursor on '보' in line 3 with text "여보세요": >
3310 getcursorcharpos() returns [0, 3, 2, 0, 3]
3311 getcurpos() returns [0, 3, 4, 0, 3]
3312 <
3313 Can also be used as a |method|: >
3314 GetWinid()->getcursorcharpos()
3315
3316 < *getcwd()*
3317 getcwd([{winnr} [, {tabnr}]])
3318 The result is a String, which is the name of the current
3319 working directory. 'autochdir' is ignored.
3320
3321 With {winnr} return the local current directory of this window
3322 in the current tab page. {winnr} can be the window number or
3323 the |window-ID|.
3324 If {winnr} is -1 return the name of the global working
3325 directory. See also |haslocaldir()|.
3326
3327 With {winnr} and {tabnr} return the local current directory of
3328 the window in the specified tab page. If {winnr} is -1 return
3329 the working directory of the tabpage.
3330 If {winnr} is zero use the current window, if {tabnr} is zero
3331 use the current tabpage.
3332 Without any arguments, return the actual working directory of
3333 the current window.
3334 Return an empty string if the arguments are invalid.
3335
3336 Examples: >
3337 " Get the working directory of the current window
3338 :echo getcwd()
3339 :echo getcwd(0)
3340 :echo getcwd(0, 0)
3341 " Get the working directory of window 3 in tabpage 2
3342 :echo getcwd(3, 2)
3343 " Get the global working directory
3344 :echo getcwd(-1)
3345 " Get the working directory of tabpage 3
3346 :echo getcwd(-1, 3)
3347 " Get the working directory of current tabpage
3348 :echo getcwd(-1, 0)
3349
3350 < Can also be used as a |method|: >
3351 GetWinnr()->getcwd()
3352
3353 getenv({name}) *getenv()*
3354 Return the value of environment variable {name}. The {name}
3355 argument is a string, without a leading '$'. Example: >
3356 myHome = getenv('HOME')
3357
3358 < When the variable does not exist |v:null| is returned. That
3359 is different from a variable set to an empty string, although
3360 some systems interpret the empty value as the variable being
3361 deleted. See also |expr-env|.
3362
3363 Can also be used as a |method|: >
3364 GetVarname()->getenv()
3365
3366 getfontname([{name}]) *getfontname()*
3367 Without an argument returns the name of the normal font being
3368 used. Like what is used for the Normal highlight group
3369 |hl-Normal|.
3370 With an argument a check is done whether String {name} is a
3371 valid font name. If not then an empty string is returned.
3372 Otherwise the actual font name is returned, or {name} if the
3373 GUI does not support obtaining the real name.
3374 Only works when the GUI is running, thus not in your vimrc or
3375 gvimrc file. Use the |GUIEnter| autocommand to use this
3376 function just after the GUI has started.
3377 Note that the GTK GUI accepts any font name, thus checking for
3378 a valid name does not work.
3379
3380 getfperm({fname}) *getfperm()*
3381 The result is a String, which is the read, write, and execute
3382 permissions of the given file {fname}.
3383 If {fname} does not exist or its directory cannot be read, an
3384 empty string is returned.
3385 The result is of the form "rwxrwxrwx", where each group of
3386 "rwx" flags represent, in turn, the permissions of the owner
3387 of the file, the group the file belongs to, and other users.
3388 If a user does not have a given permission the flag for this
3389 is replaced with the string "-". Examples: >
3390 :echo getfperm("/etc/passwd")
3391 :echo getfperm(expand("~/.vimrc"))
3392 < This will hopefully (from a security point of view) display
3393 the string "rw-r--r--" or even "rw-------".
3394
3395 Can also be used as a |method|: >
3396 GetFilename()->getfperm()
3397 <
3398 For setting permissions use |setfperm()|.
3399
3400 getfsize({fname}) *getfsize()*
3401 The result is a Number, which is the size in bytes of the
3402 given file {fname}.
3403 If {fname} is a directory, 0 is returned.
3404 If the file {fname} can't be found, -1 is returned.
3405 If the size of {fname} is too big to fit in a Number then -2
3406 is returned.
3407
3408 Can also be used as a |method|: >
3409 GetFilename()->getfsize()
3410
3411 getftime({fname}) *getftime()*
3412 The result is a Number, which is the last modification time of
3413 the given file {fname}. The value is measured as seconds
3414 since 1st Jan 1970, and may be passed to strftime(). See also
3415 |localtime()| and |strftime()|.
3416 If the file {fname} can't be found -1 is returned.
3417
3418 Can also be used as a |method|: >
3419 GetFilename()->getftime()
3420
3421 getftype({fname}) *getftype()*
3422 The result is a String, which is a description of the kind of
3423 file of the given file {fname}.
3424 If {fname} does not exist an empty string is returned.
3425 Here is a table over different kinds of files and their
3426 results:
3427 Normal file "file"
3428 Directory "dir"
3429 Symbolic link "link"
3430 Block device "bdev"
3431 Character device "cdev"
3432 Socket "socket"
3433 FIFO "fifo"
3434 All other "other"
3435 Example: >
3436 getftype("/home")
3437 < Note that a type such as "link" will only be returned on
3438 systems that support it. On some systems only "dir" and
3439 "file" are returned. On MS-Windows a symbolic link to a
3440 directory returns "dir" instead of "link".
3441
3442 Can also be used as a |method|: >
3443 GetFilename()->getftype()
3444
3445 getimstatus() *getimstatus()*
3446 The result is a Number, which is |TRUE| when the IME status is
3447 active.
3448 See 'imstatusfunc'.
3449
3450 getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
3451 Returns the |jumplist| for the specified window.
3452
3453 Without arguments use the current window.
3454 With {winnr} only use this window in the current tab page.
3455 {winnr} can also be a |window-ID|.
3456 With {winnr} and {tabnr} use the window in the specified tab
3457 page.
3458
3459 The returned list contains two entries: a list with the jump
3460 locations and the last used jump position number in the list.
3461 Each entry in the jump location list is a dictionary with
3462 the following entries:
3463 bufnr buffer number
3464 col column number
3465 coladd column offset for 'virtualedit'
3466 filename filename if available
3467 lnum line number
3468
3469 Can also be used as a |method|: >
3470 GetWinnr()->getjumplist()
3471
3472 < *getline()*
3473 getline({lnum} [, {end}])
3474 Without {end} the result is a String, which is line {lnum}
3475 from the current buffer. Example: >
3476 getline(1)
3477 < When {lnum} is a String that doesn't start with a
3478 digit, |line()| is called to translate the String into a Number.
3479 To get the line under the cursor: >
3480 getline(".")
3481 < When {lnum} is a number smaller than 1 or bigger than the
3482 number of lines in the buffer, an empty string is returned.
3483
3484 When {end} is given the result is a |List| where each item is
3485 a line from the current buffer in the range {lnum} to {end},
3486 including line {end}.
3487 {end} is used in the same way as {lnum}.
3488 Non-existing lines are silently omitted.
3489 When {end} is before {lnum} an empty |List| is returned.
3490 Example: >
3491 :let start = line('.')
3492 :let end = search("^$") - 1
3493 :let lines = getline(start, end)
3494
3495 < Can also be used as a |method|: >
3496 ComputeLnum()->getline()
3497
3498 < To get lines from another buffer see |getbufline()|
3499
3500 getloclist({nr} [, {what}]) *getloclist()*
3501 Returns a |List| with all the entries in the location list for
3502 window {nr}. {nr} can be the window number or the |window-ID|.
3503 When {nr} is zero the current window is used.
3504
3505 For a location list window, the displayed location list is
3506 returned. For an invalid window number {nr}, an empty list is
3507 returned. Otherwise, same as |getqflist()|.
3508
3509 If the optional {what} dictionary argument is supplied, then
3510 returns the items listed in {what} as a dictionary. Refer to
3511 |getqflist()| for the supported items in {what}.
3512
3513 In addition to the items supported by |getqflist()| in {what},
3514 the following item is supported by |getloclist()|:
3515
3516 filewinid id of the window used to display files
3517 from the location list. This field is
3518 applicable only when called from a
3519 location list window. See
3520 |location-list-file-window| for more
3521 details.
3522
3523 Returns a |Dictionary| with default values if there is no
3524 location list for the window {nr}.
3525 Returns an empty Dictionary if window {nr} does not exist.
3526
3527 Examples (See also |getqflist-examples|): >
3528 :echo getloclist(3, {'all': 0})
3529 :echo getloclist(5, {'filewinid': 0})
3530
3531
3532 getmarklist([{buf}]) *getmarklist()*
3533 Without the {buf} argument returns a |List| with information
3534 about all the global marks. |mark|
3535
3536 If the optional {buf} argument is specified, returns the
3537 local marks defined in buffer {buf}. For the use of {buf},
3538 see |bufname()|.
3539
3540 Each item in the returned List is a |Dict| with the following:
3541 mark name of the mark prefixed by "'"
3542 pos a |List| with the position of the mark:
3543 [bufnum, lnum, col, off]
3544 Refer to |getpos()| for more information.
3545 file file name
3546
3547 Refer to |getpos()| for getting information about a specific
3548 mark.
3549
3550 Can also be used as a |method|: >
3551 GetBufnr()->getmarklist()
3552
3553 getmatches([{win}]) *getmatches()*
3554 Returns a |List| with all matches previously defined for the
3555 current window by |matchadd()| and the |:match| commands.
3556 |getmatches()| is useful in combination with |setmatches()|,
3557 as |setmatches()| can restore a list of matches saved by
3558 |getmatches()|.
3559 If {win} is specified, use the window with this number or
3560 window ID instead of the current window.
3561 Example: >
3562 :echo getmatches()
3563 < [{'group': 'MyGroup1', 'pattern': 'TODO',
3564 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3565 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3566 :let m = getmatches()
3567 :call clearmatches()
3568 :echo getmatches()
3569 < [] >
3570 :call setmatches(m)
3571 :echo getmatches()
3572 < [{'group': 'MyGroup1', 'pattern': 'TODO',
3573 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3574 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3575 :unlet m
3576 <
3577 getmousepos() *getmousepos()*
3578 Returns a |Dictionary| with the last known position of the
3579 mouse. This can be used in a mapping for a mouse click or in
3580 a filter of a popup window. The items are:
3581 screenrow screen row
3582 screencol screen column
3583 winid Window ID of the click
3584 winrow row inside "winid"
3585 wincol column inside "winid"
3586 line text line inside "winid"
3587 column text column inside "winid"
3588 All numbers are 1-based.
3589
3590 If not over a window, e.g. when in the command line, then only
3591 "screenrow" and "screencol" are valid, the others are zero.
3592
3593 When on the status line below a window or the vertical
3594 separator right of a window, the "line" and "column" values
3595 are zero.
3596
3597 When the position is after the text then "column" is the
3598 length of the text in bytes plus one.
3599
3600 If the mouse is over a popup window then that window is used.
3601
3602 When using |getchar()| the Vim variables |v:mouse_lnum|,
3603 |v:mouse_col| and |v:mouse_winid| also provide these values.
3604
3605 *getpid()*
3606 getpid() Return a Number which is the process ID of the Vim process.
3607 On Unix and MS-Windows this is a unique number, until Vim
3608 exits.
3609
3610 *getpos()*
3611 getpos({expr}) Get the position for String {expr}. For possible values of
3612 {expr} see |line()|. For getting the cursor position see
3613 |getcurpos()|.
3614 The result is a |List| with four numbers:
3615 [bufnum, lnum, col, off]
3616 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3617 is the buffer number of the mark.
3618 "lnum" and "col" are the position in the buffer. The first
3619 column is 1.
3620 The "off" number is zero, unless 'virtualedit' is used. Then
3621 it is the offset in screen columns from the start of the
3622 character. E.g., a position within a <Tab> or after the last
3623 character.
3624 Note that for '< and '> Visual mode matters: when it is "V"
3625 (visual line mode) the column of '< is zero and the column of
3626 '> is a large number.
3627 The column number in the returned List is the byte position
3628 within the line. To get the character position in the line,
3629 use |getcharpos()|.
3630 The column number can be very large, e.g. 2147483647, in which
3631 case it means "after the end of the line".
3632 This can be used to save and restore the position of a mark: >
3633 let save_a_mark = getpos("'a")
3634 ...
3635 call setpos("'a", save_a_mark)
3636 < Also see |getcharpos()|, |getcurpos()| and |setpos()|.
3637
3638 Can also be used as a |method|: >
3639 GetMark()->getpos()
3640
3641 getqflist([{what}]) *getqflist()*
3642 Returns a |List| with all the current quickfix errors. Each
3643 list item is a dictionary with these entries:
3644 bufnr number of buffer that has the file name, use
3645 bufname() to get the name
3646 module module name
3647 lnum line number in the buffer (first line is 1)
3648 end_lnum
3649 end of line number if the item is multiline
3650 col column number (first column is 1)
3651 end_col end of column number if the item has range
3652 vcol |TRUE|: "col" is visual column
3653 |FALSE|: "col" is byte index
3654 nr error number
3655 pattern search pattern used to locate the error
3656 text description of the error
3657 type type of the error, 'E', '1', etc.
3658 valid |TRUE|: recognized error message
3659
3660 When there is no error list or it's empty, an empty list is
3661 returned. Quickfix list entries with a non-existing buffer
3662 number are returned with "bufnr" set to zero (Note: some
3663 functions accept buffer number zero for the alternate buffer,
3664 you may need to explicitly check for zero).
3665
3666 Useful application: Find pattern matches in multiple files and
3667 do something with them: >
3668 :vimgrep /theword/jg *.c
3669 :for d in getqflist()
3670 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3671 :endfor
3672 <
3673 If the optional {what} dictionary argument is supplied, then
3674 returns only the items listed in {what} as a dictionary. The
3675 following string items are supported in {what}:
3676 changedtick get the total number of changes made
3677 to the list |quickfix-changedtick|
3678 context get the |quickfix-context|
3679 efm errorformat to use when parsing "lines". If
3680 not present, then the 'errorformat' option
3681 value is used.
3682 id get information for the quickfix list with
3683 |quickfix-ID|; zero means the id for the
3684 current list or the list specified by "nr"
3685 idx get information for the quickfix entry at this
3686 index in the list specified by 'id' or 'nr'.
3687 If set to zero, then uses the current entry.
3688 See |quickfix-index|
3689 items quickfix list entries
3690 lines parse a list of lines using 'efm' and return
3691 the resulting entries. Only a |List| type is
3692 accepted. The current quickfix list is not
3693 modified. See |quickfix-parse|.
3694 nr get information for this quickfix list; zero
3695 means the current quickfix list and "$" means
3696 the last quickfix list
3697 qfbufnr number of the buffer displayed in the quickfix
3698 window. Returns 0 if the quickfix buffer is
3699 not present. See |quickfix-buffer|.
3700 size number of entries in the quickfix list
3701 title get the list title |quickfix-title|
3702 winid get the quickfix |window-ID|
3703 all all of the above quickfix properties
3704 Non-string items in {what} are ignored. To get the value of a
3705 particular item, set it to zero.
3706 If "nr" is not present then the current quickfix list is used.
3707 If both "nr" and a non-zero "id" are specified, then the list
3708 specified by "id" is used.
3709 To get the number of lists in the quickfix stack, set "nr" to
3710 "$" in {what}. The "nr" value in the returned dictionary
3711 contains the quickfix stack size.
3712 When "lines" is specified, all the other items except "efm"
3713 are ignored. The returned dictionary contains the entry
3714 "items" with the list of entries.
3715
3716 The returned dictionary contains the following entries:
3717 changedtick total number of changes made to the
3718 list |quickfix-changedtick|
3719 context quickfix list context. See |quickfix-context|
3720 If not present, set to "".
3721 id quickfix list ID |quickfix-ID|. If not
3722 present, set to 0.
3723 idx index of the quickfix entry in the list. If not
3724 present, set to 0.
3725 items quickfix list entries. If not present, set to
3726 an empty list.
3727 nr quickfix list number. If not present, set to 0
3728 qfbufnr number of the buffer displayed in the quickfix
3729 window. If not present, set to 0.
3730 size number of entries in the quickfix list. If not
3731 present, set to 0.
3732 title quickfix list title text. If not present, set
3733 to "".
3734 winid quickfix |window-ID|. If not present, set to 0
3735
3736 Examples (See also |getqflist-examples|): >
3737 :echo getqflist({'all': 1})
3738 :echo getqflist({'nr': 2, 'title': 1})
3739 :echo getqflist({'lines' : ["F1:10:L10"]})
3740 <
3741 getreg([{regname} [, 1 [, {list}]]]) *getreg()*
3742 The result is a String, which is the contents of register
3743 {regname}. Example: >
3744 :let cliptext = getreg('*')
3745 < When register {regname} was not set the result is an empty
3746 string.
3747 The {regname} argument must be a string.
3748
3749 getreg('=') returns the last evaluated value of the expression
3750 register. (For use in maps.)
3751 getreg('=', 1) returns the expression itself, so that it can
3752 be restored with |setreg()|. For other registers the extra
3753 argument is ignored, thus you can always give it.
3754
3755 If {list} is present and |TRUE|, the result type is changed
3756 to |List|. Each list item is one text line. Use it if you care
3757 about zero bytes possibly present inside register: without
3758 third argument both NLs and zero bytes are represented as NLs
3759 (see |NL-used-for-Nul|).
3760 When the register was not set an empty list is returned.
3761
3762 If {regname} is "", the unnamed register '"' is used.
3763 If {regname} is not specified, |v:register| is used.
3764 In |Vim9-script| {regname} must be one character.
3765
3766 Can also be used as a |method|: >
3767 GetRegname()->getreg()
3768
3769 getreginfo([{regname}]) *getreginfo()*
3770 Returns detailed information about register {regname} as a
3771 Dictionary with the following entries:
3772 regcontents List of lines contained in register
3773 {regname}, like
3774 |getreg|({regname}, 1, 1).
3775 regtype the type of register {regname}, as in
3776 |getregtype()|.
3777 isunnamed Boolean flag, v:true if this register
3778 is currently pointed to by the unnamed
3779 register.
3780 points_to for the unnamed register, gives the
3781 single letter name of the register
3782 currently pointed to (see |quotequote|).
3783 For example, after deleting a line
3784 with `dd`, this field will be "1",
3785 which is the register that got the
3786 deleted text.
3787
3788 The {regname} argument is a string. If {regname} is invalid
3789 or not set, an empty Dictionary will be returned.
3790 If {regname} is "" or "@", the unnamed register '"' is used.
3791 If {regname} is not specified, |v:register| is used.
3792 The returned Dictionary can be passed to |setreg()|.
3793 In |Vim9-script| {regname} must be one character.
3794
3795 Can also be used as a |method|: >
3796 GetRegname()->getreginfo()
3797
3798 getregtype([{regname}]) *getregtype()*
3799 The result is a String, which is type of register {regname}.
3800 The value will be one of:
3801 "v" for |characterwise| text
3802 "V" for |linewise| text
3803 "<CTRL-V>{width}" for |blockwise-visual| text
3804 "" for an empty or unknown register
3805 <CTRL-V> is one character with value 0x16.
3806 The {regname} argument is a string. If {regname} is "", the
3807 unnamed register '"' is used. If {regname} is not specified,
3808 |v:register| is used.
3809 In |Vim9-script| {regname} must be one character.
3810
3811 Can also be used as a |method|: >
3812 GetRegname()->getregtype()
3813
3814 gettabinfo([{tabnr}]) *gettabinfo()*
3815 If {tabnr} is not specified, then information about all the
3816 tab pages is returned as a |List|. Each List item is a
3817 |Dictionary|. Otherwise, {tabnr} specifies the tab page
3818 number and information about that one is returned. If the tab
3819 page does not exist an empty List is returned.
3820
3821 Each List item is a |Dictionary| with the following entries:
3822 tabnr tab page number.
3823 variables a reference to the dictionary with
3824 tabpage-local variables
3825 windows List of |window-ID|s in the tab page.
3826
3827 Can also be used as a |method|: >
3828 GetTabnr()->gettabinfo()
3829
3830 gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
3831 Get the value of a tab-local variable {varname} in tab page
3832 {tabnr}. |t:var|
3833 Tabs are numbered starting with one.
3834 The {varname} argument is a string. When {varname} is empty a
3835 dictionary with all tab-local variables is returned.
3836 Note that the name without "t:" must be used.
3837 When the tab or variable doesn't exist {def} or an empty
3838 string is returned, there is no error message.
3839
3840 Can also be used as a |method|: >
3841 GetTabnr()->gettabvar(varname)
3842
3843 gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
3844 Get the value of window-local variable {varname} in window
3845 {winnr} in tab page {tabnr}.
3846 The {varname} argument is a string. When {varname} is empty a
3847 dictionary with all window-local variables is returned.
3848 When {varname} is equal to "&" get the values of all
3849 window-local options in a |Dictionary|.
3850 Otherwise, when {varname} starts with "&" get the value of a
3851 window-local option.
3852 Note that {varname} must be the name without "w:".
3853 Tabs are numbered starting with one. For the current tabpage
3854 use |getwinvar()|.
3855 {winnr} can be the window number or the |window-ID|.
3856 When {winnr} is zero the current window is used.
3857 This also works for a global option, buffer-local option and
3858 window-local option, but it doesn't work for a global variable
3859 or buffer-local variable.
3860 When the tab, window or variable doesn't exist {def} or an
3861 empty string is returned, there is no error message.
3862 Examples: >
3863 :let list_is_on = gettabwinvar(1, 2, '&list')
3864 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
3865 <
3866 To obtain all window-local variables use: >
3867 gettabwinvar({tabnr}, {winnr}, '&')
3868
3869 < Can also be used as a |method|: >
3870 GetTabnr()->gettabwinvar(winnr, varname)
3871
3872 gettagstack([{winnr}]) *gettagstack()*
3873 The result is a Dict, which is the tag stack of window {winnr}.
3874 {winnr} can be the window number or the |window-ID|.
3875 When {winnr} is not specified, the current window is used.
3876 When window {winnr} doesn't exist, an empty Dict is returned.
3877
3878 The returned dictionary contains the following entries:
3879 curidx Current index in the stack. When at
3880 top of the stack, set to (length + 1).
3881 Index of bottom of the stack is 1.
3882 items List of items in the stack. Each item
3883 is a dictionary containing the
3884 entries described below.
3885 length Number of entries in the stack.
3886
3887 Each item in the stack is a dictionary with the following
3888 entries:
3889 bufnr buffer number of the current jump
3890 from cursor position before the tag jump.
3891 See |getpos()| for the format of the
3892 returned list.
3893 matchnr current matching tag number. Used when
3894 multiple matching tags are found for a
3895 name.
3896 tagname name of the tag
3897
3898 See |tagstack| for more information about the tag stack.
3899
3900 Can also be used as a |method|: >
3901 GetWinnr()->gettagstack()
3902
3903
3904 gettext({text}) *gettext()*
3905 Translate String {text} if possible.
3906 This is mainly for use in the distributed Vim scripts. When
3907 generating message translations the {text} is extracted by
3908 xgettext, the translator can add the translated message in the
3909 .po file and Vim will lookup the translation when gettext() is
3910 called.
3911 For {text} double quoted strings are preferred, because
3912 xgettext does not understand escaping in single quoted
3913 strings.
3914
3915
3916 getwininfo([{winid}]) *getwininfo()*
3917 Returns information about windows as a |List| with Dictionaries.
3918
3919 If {winid} is given Information about the window with that ID
3920 is returned, as a |List| with one item. If the window does not
3921 exist the result is an empty list.
3922
3923 Without {winid} information about all the windows in all the
3924 tab pages is returned.
3925
3926 Each List item is a |Dictionary| with the following entries:
3927 botline last complete displayed buffer line
3928 bufnr number of buffer in the window
3929 height window height (excluding winbar)
3930 loclist 1 if showing a location list
3931 {only with the +quickfix feature}
3932 quickfix 1 if quickfix or location list window
3933 {only with the +quickfix feature}
3934 terminal 1 if a terminal window
3935 {only with the +terminal feature}
3936 tabnr tab page number
3937 topline first displayed buffer line
3938 variables a reference to the dictionary with
3939 window-local variables
3940 width window width
3941 winbar 1 if the window has a toolbar, 0
3942 otherwise
3943 wincol leftmost screen column of the window;
3944 "col" from |win_screenpos()|
3945 textoff number of columns occupied by any
3946 'foldcolumn', 'signcolumn' and line
3947 number in front of the text
3948 winid |window-ID|
3949 winnr window number
3950 winrow topmost screen line of the window;
3951 "row" from |win_screenpos()|
3952
3953 Can also be used as a |method|: >
3954 GetWinnr()->getwininfo()
3955
3956 getwinpos([{timeout}]) *getwinpos()*
3957 The result is a |List| with two numbers, the result of
3958 |getwinposx()| and |getwinposy()| combined:
3959 [x-pos, y-pos]
3960 {timeout} can be used to specify how long to wait in msec for
3961 a response from the terminal. When omitted 100 msec is used.
3962 Use a longer time for a remote terminal.
3963 When using a value less than 10 and no response is received
3964 within that time, a previously reported position is returned,
3965 if available. This can be used to poll for the position and
3966 do some work in the meantime: >
3967 while 1
3968 let res = getwinpos(1)
3969 if res[0] >= 0
3970 break
3971 endif
3972 " Do some work here
3973 endwhile
3974 <
3975
3976 Can also be used as a |method|: >
3977 GetTimeout()->getwinpos()
3978 <
3979 *getwinposx()*
3980 getwinposx() The result is a Number, which is the X coordinate in pixels of
3981 the left hand side of the GUI Vim window. Also works for an
3982 xterm (uses a timeout of 100 msec).
3983 The result will be -1 if the information is not available.
3984 The value can be used with `:winpos`.
3985
3986 *getwinposy()*
3987 getwinposy() The result is a Number, which is the Y coordinate in pixels of
3988 the top of the GUI Vim window. Also works for an xterm (uses
3989 a timeout of 100 msec).
3990 The result will be -1 if the information is not available.
3991 The value can be used with `:winpos`.
3992
3993 getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
3994 Like |gettabwinvar()| for the current tabpage.
3995 Examples: >
3996 :let list_is_on = getwinvar(2, '&list')
3997 :echo "myvar = " . getwinvar(1, 'myvar')
3998
3999 < Can also be used as a |method|: >
4000 GetWinnr()->getwinvar(varname)
4001 <
4002 glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
4003 Expand the file wildcards in {expr}. See |wildcards| for the
4004 use of special characters.
4005
4006 Unless the optional {nosuf} argument is given and is |TRUE|,
4007 the 'suffixes' and 'wildignore' options apply: Names matching
4008 one of the patterns in 'wildignore' will be skipped and
4009 'suffixes' affect the ordering of matches.
4010 'wildignorecase' always applies.
4011
4012 When {list} is present and it is |TRUE| the result is a |List|
4013 with all matching files. The advantage of using a List is,
4014 you also get filenames containing newlines correctly.
4015 Otherwise the result is a String and when there are several
4016 matches, they are separated by <NL> characters.
4017
4018 If the expansion fails, the result is an empty String or List.
4019
4020 You can also use |readdir()| if you need to do complicated
4021 things, such as limiting the number of matches.
4022
4023 A name for a non-existing file is not included. A symbolic
4024 link is only included if it points to an existing file.
4025 However, when the {alllinks} argument is present and it is
4026 |TRUE| then all symbolic links are included.
4027
4028 For most systems backticks can be used to get files names from
4029 any external command. Example: >
4030 :let tagfiles = glob("`find . -name tags -print`")
4031 :let &tags = substitute(tagfiles, "\n", ",", "g")
4032 < The result of the program inside the backticks should be one
4033 item per line. Spaces inside an item are allowed.
4034
4035 See |expand()| for expanding special Vim variables. See
4036 |system()| for getting the raw output of an external command.
4037
4038 Can also be used as a |method|: >
4039 GetExpr()->glob()
4040
4041 glob2regpat({string}) *glob2regpat()*
4042 Convert a file pattern, as used by glob(), into a search
4043 pattern. The result can be used to match with a string that
4044 is a file name. E.g. >
4045 if filename =~ glob2regpat('Make*.mak')
4046 < This is equivalent to: >
4047 if filename =~ '^Make.*\.mak$'
4048 < When {string} is an empty string the result is "^$", match an
4049 empty string.
4050 Note that the result depends on the system. On MS-Windows
4051 a backslash usually means a path separator.
4052
4053 Can also be used as a |method|: >
4054 GetExpr()->glob2regpat()
4055 < *globpath()*
4056 globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
4057 Perform glob() for String {expr} on all directories in {path}
4058 and concatenate the results. Example: >
4059 :echo globpath(&rtp, "syntax/c.vim")
4060 <
4061 {path} is a comma-separated list of directory names. Each
4062 directory name is prepended to {expr} and expanded like with
4063 |glob()|. A path separator is inserted when needed.
4064 To add a comma inside a directory name escape it with a
4065 backslash. Note that on MS-Windows a directory may have a
4066 trailing backslash, remove it if you put a comma after it.
4067 If the expansion fails for one of the directories, there is no
4068 error message.
4069
4070 Unless the optional {nosuf} argument is given and is |TRUE|,
4071 the 'suffixes' and 'wildignore' options apply: Names matching
4072 one of the patterns in 'wildignore' will be skipped and
4073 'suffixes' affect the ordering of matches.
4074
4075 When {list} is present and it is |TRUE| the result is a |List|
4076 with all matching files. The advantage of using a List is, you
4077 also get filenames containing newlines correctly. Otherwise
4078 the result is a String and when there are several matches,
4079 they are separated by <NL> characters. Example: >
4080 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4081 <
4082 {alllinks} is used as with |glob()|.
4083
4084 The "**" item can be used to search in a directory tree.
4085 For example, to find all "README.txt" files in the directories
4086 in 'runtimepath' and below: >
4087 :echo globpath(&rtp, "**/README.txt")
4088 < Upwards search and limiting the depth of "**" is not
4089 supported, thus using 'path' will not always work properly.
4090
4091 Can also be used as a |method|, the base is passed as the
4092 second argument: >
4093 GetExpr()->globpath(&rtp)
4094 <
4095 *has()*
4096 has({feature} [, {check}])
4097 When {check} is omitted or is zero: The result is a Number,
4098 which is 1 if the feature {feature} is supported, zero
4099 otherwise. The {feature} argument is a string, case is
4100 ignored. See |feature-list| below.
4101
4102 When {check} is present and not zero: The result is a Number,
4103 which is 1 if the feature {feature} could ever be supported,
4104 zero otherwise. This is useful to check for a typo in
4105 {feature} and to detect dead code. Keep in mind that an older
4106 Vim version will not know about a feature added later and
4107 features that have been abandoned will not be known by the
4108 current Vim version.
4109
4110 Also see |exists()| and |exists_compiled()|.
4111
4112 Note that to skip code that has a syntax error when the
4113 feature is not available, Vim may skip the rest of the line
4114 and miss a following `endif`. Therefore put the `endif` on a
4115 separate line: >
4116 if has('feature')
4117 let x = this->breaks->without->the->feature
4118 endif
4119 < If the `endif` would be moved to the second line as "| endif" it
4120 would not be found.
4121
4122
4123 has_key({dict}, {key}) *has_key()*
4124 The result is a Number, which is TRUE if |Dictionary| {dict}
4125 has an entry with key {key}. FALSE otherwise. The {key}
4126 argument is a string.
4127
4128 Can also be used as a |method|: >
4129 mydict->has_key(key)
4130
4131 haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4132 The result is a Number:
4133 1 when the window has set a local directory via |:lcd|
4134 2 when the tab-page has set a local directory via |:tcd|
4135 0 otherwise.
4136
4137 Without arguments use the current window.
4138 With {winnr} use this window in the current tab page.
4139 With {winnr} and {tabnr} use the window in the specified tab
4140 page.
4141 {winnr} can be the window number or the |window-ID|.
4142 If {winnr} is -1 it is ignored and only the tabpage is used.
4143 Return 0 if the arguments are invalid.
4144 Examples: >
4145 if haslocaldir() == 1
4146 " window local directory case
4147 elseif haslocaldir() == 2
4148 " tab-local directory case
4149 else
4150 " global directory case
4151 endif
4152
4153 " current window
4154 :echo haslocaldir()
4155 :echo haslocaldir(0)
4156 :echo haslocaldir(0, 0)
4157 " window n in current tab page
4158 :echo haslocaldir(n)
4159 :echo haslocaldir(n, 0)
4160 " window n in tab page m
4161 :echo haslocaldir(n, m)
4162 " tab page m
4163 :echo haslocaldir(-1, m)
4164 <
4165 Can also be used as a |method|: >
4166 GetWinnr()->haslocaldir()
4167
4168 hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
4169 The result is a Number, which is TRUE if there is a mapping
4170 that contains {what} in somewhere in the rhs (what it is
4171 mapped to) and this mapping exists in one of the modes
4172 indicated by {mode}.
4173 The arguments {what} and {mode} are strings.
4174 When {abbr} is there and it is |TRUE| use abbreviations
4175 instead of mappings. Don't forget to specify Insert and/or
4176 Command-line mode.
4177 Both the global mappings and the mappings local to the current
4178 buffer are checked for a match.
4179 If no matching mapping is found FALSE is returned.
4180 The following characters are recognized in {mode}:
4181 n Normal mode
4182 v Visual and Select mode
4183 x Visual mode
4184 s Select mode
4185 o Operator-pending mode
4186 i Insert mode
4187 l Language-Argument ("r", "f", "t", etc.)
4188 c Command-line mode
4189 When {mode} is omitted, "nvo" is used.
4190
4191 This function is useful to check if a mapping already exists
4192 to a function in a Vim script. Example: >
4193 :if !hasmapto('\ABCdoit')
4194 : map <Leader>d \ABCdoit
4195 :endif
4196 < This installs the mapping to "\ABCdoit" only if there isn't
4197 already a mapping to "\ABCdoit".
4198
4199 Can also be used as a |method|: >
4200 GetRHS()->hasmapto()
4201
4202 histadd({history}, {item}) *histadd()*
4203 Add the String {item} to the history {history} which can be
4204 one of: *hist-names*
4205 "cmd" or ":" command line history
4206 "search" or "/" search pattern history
4207 "expr" or "=" typed expression history
4208 "input" or "@" input line history
4209 "debug" or ">" debug command history
4210 empty the current or last used history
4211 The {history} string does not need to be the whole name, one
4212 character is sufficient.
4213 If {item} does already exist in the history, it will be
4214 shifted to become the newest entry.
4215 The result is a Number: TRUE if the operation was successful,
4216 otherwise FALSE is returned.
4217
4218 Example: >
4219 :call histadd("input", strftime("%Y %b %d"))
4220 :let date=input("Enter date: ")
4221 < This function is not available in the |sandbox|.
4222
4223 Can also be used as a |method|, the base is passed as the
4224 second argument: >
4225 GetHistory()->histadd('search')
4226
4227 histdel({history} [, {item}]) *histdel()*
4228 Clear {history}, i.e. delete all its entries. See |hist-names|
4229 for the possible values of {history}.
4230
4231 If the parameter {item} evaluates to a String, it is used as a
4232 regular expression. All entries matching that expression will
4233 be removed from the history (if there are any).
4234 Upper/lowercase must match, unless "\c" is used |/\c|.
4235 If {item} evaluates to a Number, it will be interpreted as
4236 an index, see |:history-indexing|. The respective entry will
4237 be removed if it exists.
4238
4239 The result is TRUE for a successful operation, otherwise FALSE
4240 is returned.
4241
4242 Examples:
4243 Clear expression register history: >
4244 :call histdel("expr")
4245 <
4246 Remove all entries starting with "*" from the search history: >
4247 :call histdel("/", '^\*')
4248 <
4249 The following three are equivalent: >
4250 :call histdel("search", histnr("search"))
4251 :call histdel("search", -1)
4252 :call histdel("search", '^'.histget("search", -1).'$')
4253 <
4254 To delete the last search pattern and use the last-but-one for
4255 the "n" command and 'hlsearch': >
4256 :call histdel("search", -1)
4257 :let @/ = histget("search", -1)
4258 <
4259 Can also be used as a |method|: >
4260 GetHistory()->histdel()
4261
4262 histget({history} [, {index}]) *histget()*
4263 The result is a String, the entry with Number {index} from
4264 {history}. See |hist-names| for the possible values of
4265 {history}, and |:history-indexing| for {index}. If there is
4266 no such entry, an empty String is returned. When {index} is
4267 omitted, the most recent item from the history is used.
4268
4269 Examples:
4270 Redo the second last search from history. >
4271 :execute '/' . histget("search", -2)
4272
4273 < Define an Ex command ":H {num}" that supports re-execution of
4274 the {num}th entry from the output of |:history|. >
4275 :command -nargs=1 H execute histget("cmd", 0+<args>)
4276 <
4277 Can also be used as a |method|: >
4278 GetHistory()->histget()
4279
4280 histnr({history}) *histnr()*
4281 The result is the Number of the current entry in {history}.
4282 See |hist-names| for the possible values of {history}.
4283 If an error occurred, -1 is returned.
4284
4285 Example: >
4286 :let inp_index = histnr("expr")
4287
4288 < Can also be used as a |method|: >
4289 GetHistory()->histnr()
4290 <
4291 hlexists({name}) *hlexists()*
4292 The result is a Number, which is TRUE if a highlight group
4293 called {name} exists. This is when the group has been
4294 defined in some way. Not necessarily when highlighting has
4295 been defined for it, it may also have been used for a syntax
4296 item.
4297 *highlight_exists()*
4298 Obsolete name: highlight_exists().
4299
4300 Can also be used as a |method|: >
4301 GetName()->hlexists()
4302 <
4303 hlget([{name} [, {resolve}]]) *hlget()*
4304 Returns a List of all the highlight group attributes. If the
4305 optional {name} is specified, then returns a List with only
4306 the attributes of the specified highlight group. Returns an
4307 empty List if the highlight group {name} is not present.
4308
4309 If the optional {resolve} argument is set to v:true and the
4310 highlight group {name} is linked to another group, then the
4311 link is resolved recursively and the attributes of the
4312 resolved highlight group are returned.
4313
4314 Each entry in the returned List is a Dictionary with the
4315 following items:
4316 cleared boolean flag, set to v:true if the highlight
4317 group attributes are cleared or not yet
4318 specified. See |highlight-clear|.
4319 cterm cterm attributes. See |highlight-cterm|.
4320 ctermbg cterm background color.
4321 See |highlight-ctermbg|.
4322 ctermfg cterm foreground color.
4323 See |highlight-ctermfg|.
4324 ctermul cterm underline color. See |highlight-ctermul|.
4325 default boolean flag, set to v:true if the highlight
4326 group link is a default link. See
4327 |highlight-default|.
4328 font highlight group font. See |highlight-font|.
4329 gui gui attributes. See |highlight-gui|.
4330 guibg gui background color. See |highlight-guibg|.
4331 guifg gui foreground color. See |highlight-guifg|.
4332 guisp gui special color. See |highlight-guisp|.
4333 id highlight group ID.
4334 linksto linked highlight group name.
4335 See |:highlight-link|.
4336 name highlight group name. See |group-name|.
4337 start start terminal keycode. See |highlight-start|.
4338 stop stop terminal keycode. See |highlight-stop|.
4339 term term attributes. See |highlight-term|.
4340
4341 The 'term', 'cterm' and 'gui' items in the above Dictionary
4342 have a dictionary value with the following optional boolean
4343 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
4344 'reverse', 'inverse' and 'strikethrough'.
4345
4346 Example(s): >
4347 :echo hlget()
4348 :echo hlget('ModeMsg')
4349 :echo hlget('Number', v:true)
4350 <
4351 Can also be used as a |method|: >
4352 GetName()->hlget()
4353 <
4354 hlset({list}) *hlset()*
4355 Creates or modifies the attributes of a List of highlight
4356 groups. Each item in {list} is a dictionary containing the
4357 attributes of a highlight group. See |hlget()| for the list of
4358 supported items in this dictionary.
4359
4360 In addition to the items described in |hlget()|, the following
4361 additional items are supported in the dictionary:
4362
4363 force boolean flag to force the creation of
4364 a link for an existing highlight group
4365 with attributes.
4366
4367 The highlight group is identified using the 'name' item and
4368 the 'id' item (if supplied) is ignored. If a highlight group
4369 with a specified name doesn't exist, then it is created.
4370 Otherwise the attributes of an existing highlight group are
4371 modified.
4372
4373 If an empty dictionary value is used for the 'term' or 'cterm'
4374 or 'gui' entries, then the corresponding attributes are
4375 cleared. If the 'cleared' item is set to v:true, then all the
4376 attributes of the highlight group are cleared.
4377
4378 The 'linksto' item can be used to link a highlight group to
4379 another highlight group. See |:highlight-link|.
4380
4381 Returns zero for success, -1 for failure.
4382
4383 Example(s): >
4384 " add bold attribute to the Visual highlight group
4385 :call hlset([#{name: 'Visual',
4386 \ term: #{reverse: 1 , bold: 1}}])
4387 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
4388 :let l = hlget()
4389 :call hlset(l)
4390 " clear the Search highlight group
4391 :call hlset([#{name: 'Search', cleared: v:true}])
4392 " clear the 'term' attributes for a highlight group
4393 :call hlset([#{name: 'Title', term: {}}])
4394 " create the MyHlg group linking it to DiffAdd
4395 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
4396 " remove the MyHlg group link
4397 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
4398 " clear the attributes and a link
4399 :call hlset([#{name: 'MyHlg', cleared: v:true,
4400 \ linksto: 'NONE'}])
4401 <
4402 Can also be used as a |method|: >
4403 GetAttrList()->hlset()
4404 <
4405 *hlID()*
4406 hlID({name}) The result is a Number, which is the ID of the highlight group
4407 with name {name}. When the highlight group doesn't exist,
4408 zero is returned.
4409 This can be used to retrieve information about the highlight
4410 group. For example, to get the background color of the
4411 "Comment" group: >
4412 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4413 < *highlightID()*
4414 Obsolete name: highlightID().
4415
4416 Can also be used as a |method|: >
4417 GetName()->hlID()
4418
4419 hostname() *hostname()*
4420 The result is a String, which is the name of the machine on
4421 which Vim is currently running. Machine names greater than
4422 256 characters long are truncated.
4423
4424 iconv({string}, {from}, {to}) *iconv()*
4425 The result is a String, which is the text {string} converted
4426 from encoding {from} to encoding {to}.
4427 When the conversion completely fails an empty string is
4428 returned. When some characters could not be converted they
4429 are replaced with "?".
4430 The encoding names are whatever the iconv() library function
4431 can accept, see ":!man 3 iconv".
4432 Most conversions require Vim to be compiled with the |+iconv|
4433 feature. Otherwise only UTF-8 to latin1 conversion and back
4434 can be done.
4435 This can be used to display messages with special characters,
4436 no matter what 'encoding' is set to. Write the message in
4437 UTF-8 and use: >
4438 echo iconv(utf8_str, "utf-8", &enc)
4439 < Note that Vim uses UTF-8 for all Unicode encodings, conversion
4440 from/to UCS-2 is automatically changed to use UTF-8. You
4441 cannot use UCS-2 in a string anyway, because of the NUL bytes.
4442
4443 Can also be used as a |method|: >
4444 GetText()->iconv('latin1', 'utf-8')
4445 <
4446 *indent()*
4447 indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4448 current buffer. The indent is counted in spaces, the value
4449 of 'tabstop' is relevant. {lnum} is used just like in
4450 |getline()|.
4451 When {lnum} is invalid -1 is returned. In |Vim9| script an
4452 error is given.
4453
4454 Can also be used as a |method|: >
4455 GetLnum()->indent()
4456
4457 index({object}, {expr} [, {start} [, {ic}]]) *index()*
4458 If {object} is a |List| return the lowest index where the item
4459 has a value equal to {expr}. There is no automatic
4460 conversion, so the String "4" is different from the Number 4.
4461 And the number 4 is different from the Float 4.0. The value
4462 of 'ignorecase' is not used here, case always matters.
4463
4464 If {object} is |Blob| return the lowest index where the byte
4465 value is equal to {expr}.
4466
4467 If {start} is given then start looking at the item with index
4468 {start} (may be negative for an item relative to the end).
4469 When {ic} is given and it is |TRUE|, ignore case. Otherwise
4470 case must match.
4471 -1 is returned when {expr} is not found in {object}.
4472 Example: >
4473 :let idx = index(words, "the")
4474 :if index(numbers, 123) >= 0
4475
4476 < Can also be used as a |method|: >
4477 GetObject()->index(what)
4478
4479 input({prompt} [, {text} [, {completion}]]) *input()*
4480 The result is a String, which is whatever the user typed on
4481 the command-line. The {prompt} argument is either a prompt
4482 string, or a blank string (for no prompt). A '\n' can be used
4483 in the prompt to start a new line.
4484 The highlighting set with |:echohl| is used for the prompt.
4485 The input is entered just like a command-line, with the same
4486 editing commands and mappings. There is a separate history
4487 for lines typed for input().
4488 Example: >
4489 :if input("Coffee or beer? ") == "beer"
4490 : echo "Cheers!"
4491 :endif
4492 <
4493 If the optional {text} argument is present and not empty, this
4494 is used for the default reply, as if the user typed this.
4495 Example: >
4496 :let color = input("Color? ", "white")
4497
4498 < The optional {completion} argument specifies the type of
4499 completion supported for the input. Without it completion is
4500 not performed. The supported completion types are the same as
4501 that can be supplied to a user-defined command using the
4502 "-complete=" argument. Refer to |:command-completion| for
4503 more information. Example: >
4504 let fname = input("File: ", "", "file")
4505 <
4506 NOTE: This function must not be used in a startup file, for
4507 the versions that only run in GUI mode (e.g., the Win32 GUI).
4508 Note: When input() is called from within a mapping it will
4509 consume remaining characters from that mapping, because a
4510 mapping is handled like the characters were typed.
4511 Use |inputsave()| before input() and |inputrestore()|
4512 after input() to avoid that. Another solution is to avoid
4513 that further characters follow in the mapping, e.g., by using
4514 |:execute| or |:normal|.
4515
4516 Example with a mapping: >
4517 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
4518 :function GetFoo()
4519 : call inputsave()
4520 : let g:Foo = input("enter search pattern: ")
4521 : call inputrestore()
4522 :endfunction
4523
4524 < Can also be used as a |method|: >
4525 GetPrompt()->input()
4526
4527 inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
4528 Like |input()|, but when the GUI is running and text dialogs
4529 are supported, a dialog window pops up to input the text.
4530 Example: >
4531 :let n = inputdialog("value for shiftwidth", shiftwidth())
4532 :if n != ""
4533 : let &sw = n
4534 :endif
4535 < When the dialog is cancelled {cancelreturn} is returned. When
4536 omitted an empty string is returned.
4537 Hitting <Enter> works like pressing the OK button. Hitting
4538 <Esc> works like pressing the Cancel button.
4539 NOTE: Command-line completion is not supported.
4540
4541 Can also be used as a |method|: >
4542 GetPrompt()->inputdialog()
4543
4544 inputlist({textlist}) *inputlist()*
4545 {textlist} must be a |List| of strings. This |List| is
4546 displayed, one string per line. The user will be prompted to
4547 enter a number, which is returned.
4548 The user can also select an item by clicking on it with the
4549 mouse, if the mouse is enabled in the command line ('mouse' is
4550 "a" or includes "c"). For the first string 0 is returned.
4551 When clicking above the first item a negative number is
4552 returned. When clicking on the prompt one more than the
4553 length of {textlist} is returned.
4554 Make sure {textlist} has less than 'lines' entries, otherwise
4555 it won't work. It's a good idea to put the entry number at
4556 the start of the string. And put a prompt in the first item.
4557 Example: >
4558 let color = inputlist(['Select color:', '1. red',
4559 \ '2. green', '3. blue'])
4560
4561 < Can also be used as a |method|: >
4562 GetChoices()->inputlist()
4563
4564 inputrestore() *inputrestore()*
4565 Restore typeahead that was saved with a previous |inputsave()|.
4566 Should be called the same number of times inputsave() is
4567 called. Calling it more often is harmless though.
4568 Returns TRUE when there is nothing to restore, FALSE otherwise.
4569
4570 inputsave() *inputsave()*
4571 Preserve typeahead (also from mappings) and clear it, so that
4572 a following prompt gets input from the user. Should be
4573 followed by a matching inputrestore() after the prompt. Can
4574 be used several times, in which case there must be just as
4575 many inputrestore() calls.
4576 Returns TRUE when out of memory, FALSE otherwise.
4577
4578 inputsecret({prompt} [, {text}]) *inputsecret()*
4579 This function acts much like the |input()| function with but
4580 two exceptions:
4581 a) the user's response will be displayed as a sequence of
4582 asterisks ("*") thereby keeping the entry secret, and
4583 b) the user's response will not be recorded on the input
4584 |history| stack.
4585 The result is a String, which is whatever the user actually
4586 typed on the command-line in response to the issued prompt.
4587 NOTE: Command-line completion is not supported.
4588
4589 Can also be used as a |method|: >
4590 GetPrompt()->inputsecret()
4591
4592 insert({object}, {item} [, {idx}]) *insert()*
4593 When {object} is a |List| or a |Blob| insert {item} at the start
4594 of it.
4595
4596 If {idx} is specified insert {item} before the item with index
4597 {idx}. If {idx} is zero it goes before the first item, just
4598 like omitting {idx}. A negative {idx} is also possible, see
4599 |list-index|. -1 inserts just before the last item.
4600
4601 Returns the resulting |List| or |Blob|. Examples: >
4602 :let mylist = insert([2, 3, 5], 1)
4603 :call insert(mylist, 4, -1)
4604 :call insert(mylist, 6, len(mylist))
4605 < The last example can be done simpler with |add()|.
4606 Note that when {item} is a |List| it is inserted as a single
4607 item. Use |extend()| to concatenate |Lists|.
4608
4609 Can also be used as a |method|: >
4610 mylist->insert(item)
4611
4612 interrupt() *interrupt()*
4613 Interrupt script execution. It works more or less like the
4614 user typing CTRL-C, most commands won't execute and control
4615 returns to the user. This is useful to abort execution
4616 from lower down, e.g. in an autocommand. Example: >
4617 :function s:check_typoname(file)
4618 : if fnamemodify(a:file, ':t') == '['
4619 : echomsg 'Maybe typo'
4620 : call interrupt()
4621 : endif
4622 :endfunction
4623 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
4624
4625 invert({expr}) *invert()*
4626 Bitwise invert. The argument is converted to a number. A
4627 List, Dict or Float argument causes an error. Example: >
4628 :let bits = invert(bits)
4629 < Can also be used as a |method|: >
4630 :let bits = bits->invert()
4631
4632 isdirectory({directory}) *isdirectory()*
4633 The result is a Number, which is |TRUE| when a directory
4634 with the name {directory} exists. If {directory} doesn't
4635 exist, or isn't a directory, the result is |FALSE|. {directory}
4636 is any expression, which is used as a String.
4637
4638 Can also be used as a |method|: >
4639 GetName()->isdirectory()
4640
4641 isinf({expr}) *isinf()*
4642 Return 1 if {expr} is a positive infinity, or -1 a negative
4643 infinity, otherwise 0. >
4644 :echo isinf(1.0 / 0.0)
4645 < 1 >
4646 :echo isinf(-1.0 / 0.0)
4647 < -1
4648
4649 Can also be used as a |method|: >
4650 Compute()->isinf()
4651 <
4652 {only available when compiled with the |+float| feature}
4653
4654 islocked({expr}) *islocked()* *E786*
4655 The result is a Number, which is |TRUE| when {expr} is the
4656 name of a locked variable.
4657 The string argument {expr} must be the name of a variable,
4658 |List| item or |Dictionary| entry, not the variable itself!
4659 Example: >
4660 :let alist = [0, ['a', 'b'], 2, 3]
4661 :lockvar 1 alist
4662 :echo islocked('alist') " 1
4663 :echo islocked('alist[1]') " 0
4664
4665 < When {expr} is a variable that does not exist you get an error
4666 message. Use |exists()| to check for existence.
4667 In Vim9 script it does not work for local variables.
4668
4669 Can also be used as a |method|: >
4670 GetName()->islocked()
4671
4672 isnan({expr}) *isnan()*
4673 Return |TRUE| if {expr} is a float with value NaN. >
4674 echo isnan(0.0 / 0.0)
4675 < 1
4676
4677 Can also be used as a |method|: >
4678 Compute()->isnan()
4679 <
4680 {only available when compiled with the |+float| feature}
4681
4682 items({dict}) *items()*
4683 Return a |List| with all the key-value pairs of {dict}. Each
4684 |List| item is a list with two items: the key of a {dict}
4685 entry and the value of this entry. The |List| is in arbitrary
4686 order. Also see |keys()| and |values()|.
4687 Example: >
4688 for [key, value] in items(mydict)
4689 echo key . ': ' . value
4690 endfor
4691
4692 < Can also be used as a |method|: >
4693 mydict->items()
4694
4695 job_ functions are documented here: |job-functions-details|
4696
4697
4698 join({list} [, {sep}]) *join()*
4699 Join the items in {list} together into one String.
4700 When {sep} is specified it is put in between the items. If
4701 {sep} is omitted a single space is used.
4702 Note that {sep} is not added at the end. You might want to
4703 add it there too: >
4704 let lines = join(mylist, "\n") . "\n"
4705 < String items are used as-is. |Lists| and |Dictionaries| are
4706 converted into a string like with |string()|.
4707 The opposite function is |split()|.
4708
4709 Can also be used as a |method|: >
4710 mylist->join()
4711
4712 js_decode({string}) *js_decode()*
4713 This is similar to |json_decode()| with these differences:
4714 - Object key names do not have to be in quotes.
4715 - Strings can be in single quotes.
4716 - Empty items in an array (between two commas) are allowed and
4717 result in v:none items.
4718
4719 Can also be used as a |method|: >
4720 ReadObject()->js_decode()
4721
4722 js_encode({expr}) *js_encode()*
4723 This is similar to |json_encode()| with these differences:
4724 - Object key names are not in quotes.
4725 - v:none items in an array result in an empty item between
4726 commas.
4727 For example, the Vim object:
4728 [1,v:none,{"one":1},v:none] ~
4729 Will be encoded as:
4730 [1,,{one:1},,] ~
4731 While json_encode() would produce:
4732 [1,null,{"one":1},null] ~
4733 This encoding is valid for JavaScript. It is more efficient
4734 than JSON, especially when using an array with optional items.
4735
4736 Can also be used as a |method|: >
4737 GetObject()->js_encode()
4738
4739 json_decode({string}) *json_decode()*
4740 This parses a JSON formatted string and returns the equivalent
4741 in Vim values. See |json_encode()| for the relation between
4742 JSON and Vim values.
4743 The decoding is permissive:
4744 - A trailing comma in an array and object is ignored, e.g.
4745 "[1, 2, ]" is the same as "[1, 2]".
4746 - Integer keys are accepted in objects, e.g. {1:2} is the
4747 same as {"1":2}.
4748 - More floating point numbers are recognized, e.g. "1." for
4749 "1.0", or "001.2" for "1.2". Special floating point values
4750 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
4751 are accepted.
4752 - Leading zeroes in integer numbers are ignored, e.g. "012"
4753 for "12" or "-012" for "-12".
4754 - Capitalization is ignored in literal names null, true or
4755 false, e.g. "NULL" for "null", "True" for "true".
4756 - Control characters U+0000 through U+001F which are not
4757 escaped in strings are accepted, e.g. " " (tab
4758 character in string) for "\t".
4759 - An empty JSON expression or made of only spaces is accepted
4760 and results in v:none.
4761 - Backslash in an invalid 2-character sequence escape is
4762 ignored, e.g. "\a" is decoded as "a".
4763 - A correct surrogate pair in JSON strings should normally be
4764 a 12 character sequence such as "\uD834\uDD1E", but
4765 json_decode() silently accepts truncated surrogate pairs
4766 such as "\uD834" or "\uD834\u"
4767 *E938*
4768 A duplicate key in an object, valid in rfc7159, is not
4769 accepted by json_decode() as the result must be a valid Vim
4770 type, e.g. this fails: {"a":"b", "a":"c"}
4771
4772 Can also be used as a |method|: >
4773 ReadObject()->json_decode()
4774
4775 json_encode({expr}) *json_encode()*
4776 Encode {expr} as JSON and return this as a string.
4777 The encoding is specified in:
4778 https://tools.ietf.org/html/rfc7159.html
4779 Vim values are converted as follows:
4780 |Number| decimal number
4781 |Float| floating point number
4782 Float nan "NaN"
4783 Float inf "Infinity"
4784 Float -inf "-Infinity"
4785 |String| in double quotes (possibly null)
4786 |Funcref| not possible, error
4787 |List| as an array (possibly null); when
4788 used recursively: []
4789 |Dict| as an object (possibly null); when
4790 used recursively: {}
4791 |Blob| as an array of the individual bytes
4792 v:false "false"
4793 v:true "true"
4794 v:none "null"
4795 v:null "null"
4796 Note that NaN and Infinity are passed on as values. This is
4797 missing in the JSON standard, but several implementations do
4798 allow it. If not then you will get an error.
4799
4800 Can also be used as a |method|: >
4801 GetObject()->json_encode()
4802
4803 keys({dict}) *keys()*
4804 Return a |List| with all the keys of {dict}. The |List| is in
4805 arbitrary order. Also see |items()| and |values()|.
4806
4807 Can also be used as a |method|: >
4808 mydict->keys()
4809
4810 < *len()* *E701*
4811 len({expr}) The result is a Number, which is the length of the argument.
4812 When {expr} is a String or a Number the length in bytes is
4813 used, as with |strlen()|.
4814 When {expr} is a |List| the number of items in the |List| is
4815 returned.
4816 When {expr} is a |Blob| the number of bytes is returned.
4817 When {expr} is a |Dictionary| the number of entries in the
4818 |Dictionary| is returned.
4819 Otherwise an error is given.
4820
4821 Can also be used as a |method|: >
4822 mylist->len()
4823
4824 < *libcall()* *E364* *E368*
4825 libcall({libname}, {funcname}, {argument})
4826 Call function {funcname} in the run-time library {libname}
4827 with single argument {argument}.
4828 This is useful to call functions in a library that you
4829 especially made to be used with Vim. Since only one argument
4830 is possible, calling standard library functions is rather
4831 limited.
4832 The result is the String returned by the function. If the
4833 function returns NULL, this will appear as an empty string ""
4834 to Vim.
4835 If the function returns a number, use libcallnr()!
4836 If {argument} is a number, it is passed to the function as an
4837 int; if {argument} is a string, it is passed as a
4838 null-terminated string.
4839 This function will fail in |restricted-mode|.
4840
4841 libcall() allows you to write your own 'plug-in' extensions to
4842 Vim without having to recompile the program. It is NOT a
4843 means to call system functions! If you try to do so Vim will
4844 very probably crash.
4845
4846 For Win32, the functions you write must be placed in a DLL
4847 and use the normal C calling convention (NOT Pascal which is
4848 used in Windows System DLLs). The function must take exactly
4849 one parameter, either a character pointer or a long integer,
4850 and must return a character pointer or NULL. The character
4851 pointer returned must point to memory that will remain valid
4852 after the function has returned (e.g. in static data in the
4853 DLL). If it points to allocated memory, that memory will
4854 leak away. Using a static buffer in the function should work,
4855 it's then freed when the DLL is unloaded.
4856
4857 WARNING: If the function returns a non-valid pointer, Vim may
4858 crash! This also happens if the function returns a number,
4859 because Vim thinks it's a pointer.
4860 For Win32 systems, {libname} should be the filename of the DLL
4861 without the ".DLL" suffix. A full path is only required if
4862 the DLL is not in the usual places.
4863 For Unix: When compiling your own plugins, remember that the
4864 object code must be compiled as position-independent ('PIC').
4865 {only in Win32 and some Unix versions, when the |+libcall|
4866 feature is present}
4867 Examples: >
4868 :echo libcall("libc.so", "getenv", "HOME")
4869
4870 < Can also be used as a |method|, the base is passed as the
4871 third argument: >
4872 GetValue()->libcall("libc.so", "getenv")
4873 <
4874 *libcallnr()*
4875 libcallnr({libname}, {funcname}, {argument})
4876 Just like |libcall()|, but used for a function that returns an
4877 int instead of a string.
4878 {only in Win32 on some Unix versions, when the |+libcall|
4879 feature is present}
4880 Examples: >
4881 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
4882 :call libcallnr("libc.so", "printf", "Hello World!\n")
4883 :call libcallnr("libc.so", "sleep", 10)
4884 <
4885 Can also be used as a |method|, the base is passed as the
4886 third argument: >
4887 GetValue()->libcallnr("libc.so", "printf")
4888 <
4889
4890 line({expr} [, {winid}]) *line()*
4891 The result is a Number, which is the line number of the file
4892 position given with {expr}. The {expr} argument is a string.
4893 The accepted positions are:
4894 . the cursor position
4895 $ the last line in the current buffer
4896 'x position of mark x (if the mark is not set, 0 is
4897 returned)
4898 w0 first line visible in current window (one if the
4899 display isn't updated, e.g. in silent Ex mode)
4900 w$ last line visible in current window (this is one
4901 less than "w0" if no lines are visible)
4902 v In Visual mode: the start of the Visual area (the
4903 cursor is the end). When not in Visual mode
4904 returns the cursor position. Differs from |'<| in
4905 that it's updated right away.
4906 Note that a mark in another file can be used. The line number
4907 then applies to another buffer.
4908 To get the column number use |col()|. To get both use
4909 |getpos()|.
4910 With the optional {winid} argument the values are obtained for
4911 that window instead of the current window.
4912 Examples: >
4913 line(".") line number of the cursor
4914 line(".", winid) idem, in window "winid"
4915 line("'t") line number of mark t
4916 line("'" . marker) line number of mark marker
4917 <
4918 To jump to the last known position when opening a file see
4919 |last-position-jump|.
4920
4921 Can also be used as a |method|: >
4922 GetValue()->line()
4923
4924 line2byte({lnum}) *line2byte()*
4925 Return the byte count from the start of the buffer for line
4926 {lnum}. This includes the end-of-line character, depending on
4927 the 'fileformat' option for the current buffer. The first
4928 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
4929 This can also be used to get the byte count for the line just
4930 below the last line: >
4931 line2byte(line("$") + 1)
4932 < This is the buffer size plus one. If 'fileencoding' is empty
4933 it is the file size plus one. {lnum} is used like with
4934 |getline()|. When {lnum} is invalid, or the |+byte_offset|
4935 feature has been disabled at compile time, -1 is returned.
4936 Also see |byte2line()|, |go| and |:goto|.
4937
4938 Can also be used as a |method|: >
4939 GetLnum()->line2byte()
4940
4941 lispindent({lnum}) *lispindent()*
4942 Get the amount of indent for line {lnum} according the lisp
4943 indenting rules, as with 'lisp'.
4944 The indent is counted in spaces, the value of 'tabstop' is
4945 relevant. {lnum} is used just like in |getline()|.
4946 When {lnum} is invalid or Vim was not compiled the
4947 |+lispindent| feature, -1 is returned. In |Vim9| script an
4948 error is given.
4949
4950 Can also be used as a |method|: >
4951 GetLnum()->lispindent()
4952
4953 list2blob({list}) *list2blob()*
4954 Return a Blob concatenating all the number values in {list}.
4955 Examples: >
4956 list2blob([1, 2, 3, 4]) returns 0z01020304
4957 list2blob([]) returns 0z
4958 < Returns an empty Blob on error. If one of the numbers is
4959 negative or more than 255 error *E1239* is given.
4960
4961 |blob2list()| does the opposite.
4962
4963 Can also be used as a |method|: >
4964 GetList()->list2blob()
4965
4966 list2str({list} [, {utf8}]) *list2str()*
4967 Convert each number in {list} to a character string can
4968 concatenate them all. Examples: >
4969 list2str([32]) returns " "
4970 list2str([65, 66, 67]) returns "ABC"
4971 < The same can be done (slowly) with: >
4972 join(map(list, {nr, val -> nr2char(val)}), '')
4973 < |str2list()| does the opposite.
4974
4975 When {utf8} is omitted or zero, the current 'encoding' is used.
4976 When {utf8} is TRUE, always return UTF-8 characters.
4977 With UTF-8 composing characters work as expected: >
4978 list2str([97, 769]) returns "á"
4979 <
4980 Can also be used as a |method|: >
4981 GetList()->list2str()
4982
4983 listener_add({callback} [, {buf}]) *listener_add()*
4984 Add a callback function that will be invoked when changes have
4985 been made to buffer {buf}.
4986 {buf} refers to a buffer name or number. For the accepted
4987 values, see |bufname()|. When {buf} is omitted the current
4988 buffer is used.
4989 Returns a unique ID that can be passed to |listener_remove()|.
4990
4991 The {callback} is invoked with five arguments:
4992 a:bufnr the buffer that was changed
4993 a:start first changed line number
4994 a:end first line number below the change
4995 a:added number of lines added, negative if lines were
4996 deleted
4997 a:changes a List of items with details about the changes
4998
4999 Example: >
5000 func Listener(bufnr, start, end, added, changes)
5001 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
5002 endfunc
5003 call listener_add('Listener', bufnr)
5004
5005 < The List cannot be changed. Each item in a:changes is a
5006 dictionary with these entries:
5007 lnum the first line number of the change
5008 end the first line below the change
5009 added number of lines added; negative if lines were
5010 deleted
5011 col first column in "lnum" that was affected by
5012 the change; one if unknown or the whole line
5013 was affected; this is a byte index, first
5014 character has a value of one.
5015 When lines are inserted the values are:
5016 lnum line above which the new line is added
5017 end equal to "lnum"
5018 added number of lines inserted
5019 col 1
5020 When lines are deleted the values are:
5021 lnum the first deleted line
5022 end the line below the first deleted line, before
5023 the deletion was done
5024 added negative, number of lines deleted
5025 col 1
5026 When lines are changed:
5027 lnum the first changed line
5028 end the line below the last changed line
5029 added 0
5030 col first column with a change or 1
5031
5032 The entries are in the order the changes were made, thus the
5033 most recent change is at the end. The line numbers are valid
5034 when the callback is invoked, but later changes may make them
5035 invalid, thus keeping a copy for later might not work.
5036
5037 The {callback} is invoked just before the screen is updated,
5038 when |listener_flush()| is called or when a change is being
5039 made that changes the line count in a way it causes a line
5040 number in the list of changes to become invalid.
5041
5042 The {callback} is invoked with the text locked, see
5043 |textlock|. If you do need to make changes to the buffer, use
5044 a timer to do this later |timer_start()|.
5045
5046 The {callback} is not invoked when the buffer is first loaded.
5047 Use the |BufReadPost| autocmd event to handle the initial text
5048 of a buffer.
5049 The {callback} is also not invoked when the buffer is
5050 unloaded, use the |BufUnload| autocmd event for that.
5051
5052 Can also be used as a |method|, the base is passed as the
5053 second argument: >
5054 GetBuffer()->listener_add(callback)
5055
5056 listener_flush([{buf}]) *listener_flush()*
5057 Invoke listener callbacks for buffer {buf}. If there are no
5058 pending changes then no callbacks are invoked.
5059
5060 {buf} refers to a buffer name or number. For the accepted
5061 values, see |bufname()|. When {buf} is omitted the current
5062 buffer is used.
5063
5064 Can also be used as a |method|: >
5065 GetBuffer()->listener_flush()
5066
5067 listener_remove({id}) *listener_remove()*
5068 Remove a listener previously added with listener_add().
5069 Returns FALSE when {id} could not be found, TRUE when {id} was
5070 removed.
5071
5072 Can also be used as a |method|: >
5073 GetListenerId()->listener_remove()
5074
5075 localtime() *localtime()*
5076 Return the current time, measured as seconds since 1st Jan
5077 1970. See also |strftime()|, |strptime()| and |getftime()|.
5078
5079
5080 log({expr}) *log()*
5081 Return the natural logarithm (base e) of {expr} as a |Float|.
5082 {expr} must evaluate to a |Float| or a |Number| in the range
5083 (0, inf].
5084 Examples: >
5085 :echo log(10)
5086 < 2.302585 >
5087 :echo log(exp(5))
5088 < 5.0
5089
5090 Can also be used as a |method|: >
5091 Compute()->log()
5092 <
5093 {only available when compiled with the |+float| feature}
5094
5095
5096 log10({expr}) *log10()*
5097 Return the logarithm of Float {expr} to base 10 as a |Float|.
5098 {expr} must evaluate to a |Float| or a |Number|.
5099 Examples: >
5100 :echo log10(1000)
5101 < 3.0 >
5102 :echo log10(0.01)
5103 < -2.0
5104
5105 Can also be used as a |method|: >
5106 Compute()->log10()
5107 <
5108 {only available when compiled with the |+float| feature}
5109
5110 luaeval({expr} [, {expr}]) *luaeval()*
5111 Evaluate Lua expression {expr} and return its result converted
5112 to Vim data structures. Second {expr} may hold additional
5113 argument accessible as _A inside first {expr}.
5114 Strings are returned as they are.
5115 Boolean objects are converted to numbers.
5116 Numbers are converted to |Float| values if vim was compiled
5117 with |+float| and to numbers otherwise.
5118 Dictionaries and lists obtained by vim.eval() are returned
5119 as-is.
5120 Other objects are returned as zero without any errors.
5121 See |lua-luaeval| for more details.
5122 Note that in a `:def` function local variables are not visible
5123 to {expr}.
5124
5125 Can also be used as a |method|: >
5126 GetExpr()->luaeval()
5127
5128 < {only available when compiled with the |+lua| feature}
5129
5130 map({expr1}, {expr2}) *map()*
5131 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
5132 When {expr1} is a |List|| or |Dictionary|, replace each
5133 item in {expr1} with the result of evaluating {expr2}.
5134 For a |Blob| each byte is replaced.
5135 For a |String|, each character, including composing
5136 characters, is replaced.
5137 If the item type changes you may want to use |mapnew()| to
5138 create a new List or Dictionary. This is required when using
5139 Vim9 script.
5140
5141 {expr2} must be a |String| or |Funcref|.
5142
5143 If {expr2} is a |String|, inside {expr2} |v:val| has the value
5144 of the current item. For a |Dictionary| |v:key| has the key
5145 of the current item and for a |List| |v:key| has the index of
5146 the current item. For a |Blob| |v:key| has the index of the
5147 current byte. For a |String| |v:key| has the index of the
5148 current character.
5149 Example: >
5150 :call map(mylist, '"> " . v:val . " <"')
5151 < This puts "> " before and " <" after each item in "mylist".
5152
5153 Note that {expr2} is the result of an expression and is then
5154 used as an expression again. Often it is good to use a
5155 |literal-string| to avoid having to double backslashes. You
5156 still have to double ' quotes
5157
5158 If {expr2} is a |Funcref| it is called with two arguments:
5159 1. The key or the index of the current item.
5160 2. the value of the current item.
5161 The function must return the new value of the item. Example
5162 that changes each value by "key-value": >
5163 func KeyValue(key, val)
5164 return a:key . '-' . a:val
5165 endfunc
5166 call map(myDict, function('KeyValue'))
5167 < It is shorter when using a |lambda|: >
5168 call map(myDict, {key, val -> key . '-' . val})
5169 < If you do not use "val" you can leave it out: >
5170 call map(myDict, {key -> 'item: ' . key})
5171 < If you do not use "key" you can use a short name: >
5172 call map(myDict, {_, val -> 'item: ' . val})
5173 <
5174 The operation is done in-place for a |List| and |Dictionary|.
5175 If you want it to remain unmodified make a copy first: >
5176 :let tlist = map(copy(mylist), ' v:val . "\t"')
5177
5178 < Returns {expr1}, the |List| or |Dictionary| that was filtered,
5179 or a new |Blob| or |String|.
5180 When an error is encountered while evaluating {expr2} no
5181 further items in {expr1} are processed.
5182 When {expr2} is a Funcref errors inside a function are ignored,
5183 unless it was defined with the "abort" flag.
5184
5185 Can also be used as a |method|: >
5186 mylist->map(expr2)
5187
5188
5189 maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
5190 When {dict} is omitted or zero: Return the rhs of mapping
5191 {name} in mode {mode}. The returned String has special
5192 characters translated like in the output of the ":map" command
5193 listing.
5194
5195 When there is no mapping for {name}, an empty String is
5196 returned. When the mapping for {name} is empty, then "<Nop>"
5197 is returned.
5198
5199 The {name} can have special key names, like in the ":map"
5200 command.
5201
5202 {mode} can be one of these strings:
5203 "n" Normal
5204 "v" Visual (including Select)
5205 "o" Operator-pending
5206 "i" Insert
5207 "c" Cmd-line
5208 "s" Select
5209 "x" Visual
5210 "l" langmap |language-mapping|
5211 "t" Terminal-Job
5212 "" Normal, Visual and Operator-pending
5213 When {mode} is omitted, the modes for "" are used.
5214
5215 When {abbr} is there and it is |TRUE| use abbreviations
5216 instead of mappings.
5217
5218 When {dict} is there and it is |TRUE| return a dictionary
5219 containing all the information of the mapping with the
5220 following items:
5221 "lhs" The {lhs} of the mapping as it would be typed
5222 "lhsraw" The {lhs} of the mapping as raw bytes
5223 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
5224 form, only present when it differs from "lhsraw"
5225 "rhs" The {rhs} of the mapping as typed.
5226 "silent" 1 for a |:map-silent| mapping, else 0.
5227 "noremap" 1 if the {rhs} of the mapping is not remappable.
5228 "script" 1 if mapping was defined with <script>.
5229 "expr" 1 for an expression mapping (|:map-<expr>|).
5230 "buffer" 1 for a buffer local mapping (|:map-local|).
5231 "mode" Modes for which the mapping is defined. In
5232 addition to the modes mentioned above, these
5233 characters will be used:
5234 " " Normal, Visual and Operator-pending
5235 "!" Insert and Commandline mode
5236 (|mapmode-ic|)
5237 "sid" The script local ID, used for <sid> mappings
5238 (|<SID>|).
5239 "lnum" The line number in "sid", zero if unknown.
5240 "nowait" Do not wait for other, longer mappings.
5241 (|:map-<nowait>|).
5242
5243 The dictionary can be used to restore a mapping with
5244 |mapset()|.
5245
5246 The mappings local to the current buffer are checked first,
5247 then the global mappings.
5248 This function can be used to map a key even when it's already
5249 mapped, and have it do the original mapping too. Sketch: >
5250 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
5251
5252 < Can also be used as a |method|: >
5253 GetKey()->maparg('n')
5254
5255 mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
5256 Check if there is a mapping that matches with {name} in mode
5257 {mode}. See |maparg()| for {mode} and special names in
5258 {name}.
5259 When {abbr} is there and it is |TRUE| use abbreviations
5260 instead of mappings.
5261 A match happens with a mapping that starts with {name} and
5262 with a mapping which is equal to the start of {name}.
5263
5264 matches mapping "a" "ab" "abc" ~
5265 mapcheck("a") yes yes yes
5266 mapcheck("abc") yes yes yes
5267 mapcheck("ax") yes no no
5268 mapcheck("b") no no no
5269
5270 The difference with maparg() is that mapcheck() finds a
5271 mapping that matches with {name}, while maparg() only finds a
5272 mapping for {name} exactly.
5273 When there is no mapping that starts with {name}, an empty
5274 String is returned. If there is one, the RHS of that mapping
5275 is returned. If there are several mappings that start with
5276 {name}, the RHS of one of them is returned. This will be
5277 "<Nop>" if the RHS is empty.
5278 The mappings local to the current buffer are checked first,
5279 then the global mappings.
5280 This function can be used to check if a mapping can be added
5281 without being ambiguous. Example: >
5282 :if mapcheck("_vv") == ""
5283 : map _vv :set guifont=7x13<CR>
5284 :endif
5285 < This avoids adding the "_vv" mapping when there already is a
5286 mapping for "_v" or for "_vvv".
5287
5288 Can also be used as a |method|: >
5289 GetKey()->mapcheck('n')
5290
5291
5292 mapnew({expr1}, {expr2}) *mapnew()*
5293 Like |map()| but instead of replacing items in {expr1} a new
5294 List or Dictionary is created and returned. {expr1} remains
5295 unchanged. Items can still be changed by {expr2}, if you
5296 don't want that use |deepcopy()| first.
5297
5298
5299 mapset({mode}, {abbr}, {dict}) *mapset()*
5300 Restore a mapping from a dictionary returned by |maparg()|.
5301 {mode} and {abbr} should be the same as for the call to
5302 |maparg()|. *E460*
5303 {mode} is used to define the mode in which the mapping is set,
5304 not the "mode" entry in {dict}.
5305 Example for saving and restoring a mapping: >
5306 let save_map = maparg('K', 'n', 0, 1)
5307 nnoremap K somethingelse
5308 ...
5309 call mapset('n', 0, save_map)
5310 < Note that if you are going to replace a map in several modes,
5311 e.g. with `:map!`, you need to save the mapping for all of
5312 them, since they can differ.
5313
5314
5315 match({expr}, {pat} [, {start} [, {count}]]) *match()*
5316 When {expr} is a |List| then this returns the index of the
5317 first item where {pat} matches. Each item is used as a
5318 String, |Lists| and |Dictionaries| are used as echoed.
5319
5320 Otherwise, {expr} is used as a String. The result is a
5321 Number, which gives the index (byte offset) in {expr} where
5322 {pat} matches.
5323
5324 A match at the first character or |List| item returns zero.
5325 If there is no match -1 is returned.
5326
5327 For getting submatches see |matchlist()|.
5328 Example: >
5329 :echo match("testing", "ing") " results in 4
5330 :echo match([1, 'x'], '\a') " results in 1
5331 < See |string-match| for how {pat} is used.
5332 *strpbrk()*
5333 Vim doesn't have a strpbrk() function. But you can do: >
5334 :let sepidx = match(line, '[.,;: \t]')
5335 < *strcasestr()*
5336 Vim doesn't have a strcasestr() function. But you can add
5337 "\c" to the pattern to ignore case: >
5338 :let idx = match(haystack, '\cneedle')
5339 <
5340 If {start} is given, the search starts from byte index
5341 {start} in a String or item {start} in a |List|.
5342 The result, however, is still the index counted from the
5343 first character/item. Example: >
5344 :echo match("testing", "ing", 2)
5345 < result is again "4". >
5346 :echo match("testing", "ing", 4)
5347 < result is again "4". >
5348 :echo match("testing", "t", 2)
5349 < result is "3".
5350 For a String, if {start} > 0 then it is like the string starts
5351 {start} bytes later, thus "^" will match at {start}. Except
5352 when {count} is given, then it's like matches before the
5353 {start} byte are ignored (this is a bit complicated to keep it
5354 backwards compatible).
5355 For a String, if {start} < 0, it will be set to 0. For a list
5356 the index is counted from the end.
5357 If {start} is out of range ({start} > strlen({expr}) for a
5358 String or {start} > len({expr}) for a |List|) -1 is returned.
5359
5360 When {count} is given use the {count}'th match. When a match
5361 is found in a String the search for the next one starts one
5362 character further. Thus this example results in 1: >
5363 echo match("testing", "..", 0, 2)
5364 < In a |List| the search continues in the next item.
5365 Note that when {count} is added the way {start} works changes,
5366 see above.
5367
5368 See |pattern| for the patterns that are accepted.
5369 The 'ignorecase' option is used to set the ignore-caseness of
5370 the pattern. 'smartcase' is NOT used. The matching is always
5371 done like 'magic' is set and 'cpoptions' is empty.
5372 Note that a match at the start is preferred, thus when the
5373 pattern is using "*" (any number of matches) it tends to find
5374 zero matches at the start instead of a number of matches
5375 further down in the text.
5376
5377 Can also be used as a |method|: >
5378 GetText()->match('word')
5379 GetList()->match('word')
5380 <
5381 *matchadd()* *E798* *E799* *E801* *E957*
5382 matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
5383 Defines a pattern to be highlighted in the current window (a
5384 "match"). It will be highlighted with {group}. Returns an
5385 identification number (ID), which can be used to delete the
5386 match using |matchdelete()|. The ID is bound to the window.
5387 Matching is case sensitive and magic, unless case sensitivity
5388 or magicness are explicitly overridden in {pattern}. The
5389 'magic', 'smartcase' and 'ignorecase' options are not used.
5390 The "Conceal" value is special, it causes the match to be
5391 concealed.
5392
5393 The optional {priority} argument assigns a priority to the
5394 match. A match with a high priority will have its
5395 highlighting overrule that of a match with a lower priority.
5396 A priority is specified as an integer (negative numbers are no
5397 exception). If the {priority} argument is not specified, the
5398 default priority is 10. The priority of 'hlsearch' is zero,
5399 hence all matches with a priority greater than zero will
5400 overrule it. Syntax highlighting (see 'syntax') is a separate
5401 mechanism, and regardless of the chosen priority a match will
5402 always overrule syntax highlighting.
5403
5404 The optional {id} argument allows the request for a specific
5405 match ID. If a specified ID is already taken, an error
5406 message will appear and the match will not be added. An ID
5407 is specified as a positive integer (zero excluded). IDs 1, 2
5408 and 3 are reserved for |:match|, |:2match| and |:3match|,
5409 respectively. If the {id} argument is not specified or -1,
5410 |matchadd()| automatically chooses a free ID.
5411
5412 The optional {dict} argument allows for further custom
5413 values. Currently this is used to specify a match specific
5414 conceal character that will be shown for |hl-Conceal|
5415 highlighted matches. The dict can have the following members:
5416
5417 conceal Special character to show instead of the
5418 match (only for |hl-Conceal| highlighted
5419 matches, see |:syn-cchar|)
5420 window Instead of the current window use the
5421 window with this number or window ID.
5422
5423 The number of matches is not limited, as it is the case with
5424 the |:match| commands.
5425
5426 Example: >
5427 :highlight MyGroup ctermbg=green guibg=green
5428 :let m = matchadd("MyGroup", "TODO")
5429 < Deletion of the pattern: >
5430 :call matchdelete(m)
5431
5432 < A list of matches defined by |matchadd()| and |:match| are
5433 available from |getmatches()|. All matches can be deleted in
5434 one operation by |clearmatches()|.
5435
5436 Can also be used as a |method|: >
5437 GetGroup()->matchadd('TODO')
5438 <
5439 *matchaddpos()*
5440 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
5441 Same as |matchadd()|, but requires a list of positions {pos}
5442 instead of a pattern. This command is faster than |matchadd()|
5443 because it does not require to handle regular expressions and
5444 sets buffer line boundaries to redraw screen. It is supposed
5445 to be used when fast match additions and deletions are
5446 required, for example to highlight matching parentheses.
5447
5448 {pos} is a list of positions. Each position can be one of
5449 these:
5450 - A number. This whole line will be highlighted. The first
5451 line has number 1.
5452 - A list with one number, e.g., [23]. The whole line with this
5453 number will be highlighted.
5454 - A list with two numbers, e.g., [23, 11]. The first number is
5455 the line number, the second one is the column number (first
5456 column is 1, the value must correspond to the byte index as
5457 |col()| would return). The character at this position will
5458 be highlighted.
5459 - A list with three numbers, e.g., [23, 11, 3]. As above, but
5460 the third number gives the length of the highlight in bytes.
5461
5462 The maximum number of positions in {pos} is 8.
5463
5464 Example: >
5465 :highlight MyGroup ctermbg=green guibg=green
5466 :let m = matchaddpos("MyGroup", [[23, 24], 34])
5467 < Deletion of the pattern: >
5468 :call matchdelete(m)
5469
5470 < Matches added by |matchaddpos()| are returned by
5471 |getmatches()|.
5472
5473 Can also be used as a |method|: >
5474 GetGroup()->matchaddpos([23, 11])
5475
5476 matcharg({nr}) *matcharg()*
5477 Selects the {nr} match item, as set with a |:match|,
5478 |:2match| or |:3match| command.
5479 Return a |List| with two elements:
5480 The name of the highlight group used
5481 The pattern used.
5482 When {nr} is not 1, 2 or 3 returns an empty |List|.
5483 When there is no match item set returns ['', ''].
5484 This is useful to save and restore a |:match|.
5485 Highlighting matches using the |:match| commands are limited
5486 to three matches. |matchadd()| does not have this limitation.
5487
5488 Can also be used as a |method|: >
5489 GetMatch()->matcharg()
5490
5491 matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
5492 Deletes a match with ID {id} previously defined by |matchadd()|
5493 or one of the |:match| commands. Returns 0 if successful,
5494 otherwise -1. See example for |matchadd()|. All matches can
5495 be deleted in one operation by |clearmatches()|.
5496 If {win} is specified, use the window with this number or
5497 window ID instead of the current window.
5498
5499 Can also be used as a |method|: >
5500 GetMatch()->matchdelete()
5501
5502 matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
5503 Same as |match()|, but return the index of first character
5504 after the match. Example: >
5505 :echo matchend("testing", "ing")
5506 < results in "7".
5507 *strspn()* *strcspn()*
5508 Vim doesn't have a strspn() or strcspn() function, but you can
5509 do it with matchend(): >
5510 :let span = matchend(line, '[a-zA-Z]')
5511 :let span = matchend(line, '[^a-zA-Z]')
5512 < Except that -1 is returned when there are no matches.
5513
5514 The {start}, if given, has the same meaning as for |match()|. >
5515 :echo matchend("testing", "ing", 2)
5516 < results in "7". >
5517 :echo matchend("testing", "ing", 5)
5518 < result is "-1".
5519 When {expr} is a |List| the result is equal to |match()|.
5520
5521 Can also be used as a |method|: >
5522 GetText()->matchend('word')
5523
5524
5525 matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
5526 If {list} is a list of strings, then returns a |List| with all
5527 the strings in {list} that fuzzy match {str}. The strings in
5528 the returned list are sorted based on the matching score.
5529
5530 The optional {dict} argument always supports the following
5531 items:
5532 matchseq When this item is present and {str} contains
5533 multiple words separated by white space, then
5534 returns only matches that contain the words in
5535 the given sequence.
5536
5537 If {list} is a list of dictionaries, then the optional {dict}
5538 argument supports the following additional items:
5539 key key of the item which is fuzzy matched against
5540 {str}. The value of this item should be a
5541 string.
5542 text_cb |Funcref| that will be called for every item
5543 in {list} to get the text for fuzzy matching.
5544 This should accept a dictionary item as the
5545 argument and return the text for that item to
5546 use for fuzzy matching.
5547
5548 {str} is treated as a literal string and regular expression
5549 matching is NOT supported. The maximum supported {str} length
5550 is 256.
5551
5552 When {str} has multiple words each separated by white space,
5553 then the list of strings that have all the words is returned.
5554
5555 If there are no matching strings or there is an error, then an
5556 empty list is returned. If length of {str} is greater than
5557 256, then returns an empty list.
5558
5559 Refer to |fuzzy-match| for more information about fuzzy
5560 matching strings.
5561
5562 Example: >
5563 :echo matchfuzzy(["clay", "crow"], "cay")
5564 < results in ["clay"]. >
5565 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
5566 < results in a list of buffer names fuzzy matching "ndl". >
5567 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
5568 < results in a list of buffer information dicts with buffer
5569 names fuzzy matching "ndl". >
5570 :echo getbufinfo()->matchfuzzy("spl",
5571 \ {'text_cb' : {v -> v.name}})
5572 < results in a list of buffer information dicts with buffer
5573 names fuzzy matching "spl". >
5574 :echo v:oldfiles->matchfuzzy("test")
5575 < results in a list of file names fuzzy matching "test". >
5576 :let l = readfile("buffer.c")->matchfuzzy("str")
5577 < results in a list of lines in "buffer.c" fuzzy matching "str". >
5578 :echo ['one two', 'two one']->matchfuzzy('two one')
5579 < results in ['two one', 'one two']. >
5580 :echo ['one two', 'two one']->matchfuzzy('two one',
5581 \ {'matchseq': 1})
5582 < results in ['two one'].
5583
5584 matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
5585 Same as |matchfuzzy()|, but returns the list of matched
5586 strings, the list of character positions where characters
5587 in {str} matches and a list of matching scores. You can
5588 use |byteidx()| to convert a character position to a byte
5589 position.
5590
5591 If {str} matches multiple times in a string, then only the
5592 positions for the best match is returned.
5593
5594 If there are no matching strings or there is an error, then a
5595 list with three empty list items is returned.
5596
5597 Example: >
5598 :echo matchfuzzypos(['testing'], 'tsg')
5599 < results in [['testing'], [[0, 2, 6]], [99]] >
5600 :echo matchfuzzypos(['clay', 'lacy'], 'la')
5601 < results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
5602 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
5603 < results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
5604
5605 matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
5606 Same as |match()|, but return a |List|. The first item in the
5607 list is the matched string, same as what matchstr() would
5608 return. Following items are submatches, like "\1", "\2", etc.
5609 in |:substitute|. When an optional submatch didn't match an
5610 empty string is used. Example: >
5611 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
5612 < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
5613 When there is no match an empty list is returned.
5614
5615 You can pass in a List, but that is not very useful.
5616
5617 Can also be used as a |method|: >
5618 GetText()->matchlist('word')
5619
5620 matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
5621 Same as |match()|, but return the matched string. Example: >
5622 :echo matchstr("testing", "ing")
5623 < results in "ing".
5624 When there is no match "" is returned.
5625 The {start}, if given, has the same meaning as for |match()|. >
5626 :echo matchstr("testing", "ing", 2)
5627 < results in "ing". >
5628 :echo matchstr("testing", "ing", 5)
5629 < result is "".
5630 When {expr} is a |List| then the matching item is returned.
5631 The type isn't changed, it's not necessarily a String.
5632
5633 Can also be used as a |method|: >
5634 GetText()->matchstr('word')
5635
5636 matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
5637 Same as |matchstr()|, but return the matched string, the start
5638 position and the end position of the match. Example: >
5639 :echo matchstrpos("testing", "ing")
5640 < results in ["ing", 4, 7].
5641 When there is no match ["", -1, -1] is returned.
5642 The {start}, if given, has the same meaning as for |match()|. >
5643 :echo matchstrpos("testing", "ing", 2)
5644 < results in ["ing", 4, 7]. >
5645 :echo matchstrpos("testing", "ing", 5)
5646 < result is ["", -1, -1].
5647 When {expr} is a |List| then the matching item, the index
5648 of first item where {pat} matches, the start position and the
5649 end position of the match are returned. >
5650 :echo matchstrpos([1, '__x'], '\a')
5651 < result is ["x", 1, 2, 3].
5652 The type isn't changed, it's not necessarily a String.
5653
5654 Can also be used as a |method|: >
5655 GetText()->matchstrpos('word')
5656 <
5657
5658 *max()*
5659 max({expr}) Return the maximum value of all items in {expr}. Example: >
5660 echo max([apples, pears, oranges])
5661
5662 < {expr} can be a |List| or a |Dictionary|. For a Dictionary,
5663 it returns the maximum of all values in the Dictionary.
5664 If {expr} is neither a List nor a Dictionary, or one of the
5665 items in {expr} cannot be used as a Number this results in
5666 an error. An empty |List| or |Dictionary| results in zero.
5667
5668 Can also be used as a |method|: >
5669 mylist->max()
5670
5671
5672 menu_info({name} [, {mode}]) *menu_info()*
5673 Return information about the specified menu {name} in
5674 mode {mode}. The menu name should be specified without the
5675 shortcut character ('&'). If {name} is "", then the top-level
5676 menu names are returned.
5677
5678 {mode} can be one of these strings:
5679 "n" Normal
5680 "v" Visual (including Select)
5681 "o" Operator-pending
5682 "i" Insert
5683 "c" Cmd-line
5684 "s" Select
5685 "x" Visual
5686 "t" Terminal-Job
5687 "" Normal, Visual and Operator-pending
5688 "!" Insert and Cmd-line
5689 When {mode} is omitted, the modes for "" are used.
5690
5691 Returns a |Dictionary| containing the following items:
5692 accel menu item accelerator text |menu-text|
5693 display display name (name without '&')
5694 enabled v:true if this menu item is enabled
5695 Refer to |:menu-enable|
5696 icon name of the icon file (for toolbar)
5697 |toolbar-icon|
5698 iconidx index of a built-in icon
5699 modes modes for which the menu is defined. In
5700 addition to the modes mentioned above, these
5701 characters will be used:
5702 " " Normal, Visual and Operator-pending
5703 name menu item name.
5704 noremenu v:true if the {rhs} of the menu item is not
5705 remappable else v:false.
5706 priority menu order priority |menu-priority|
5707 rhs right-hand-side of the menu item. The returned
5708 string has special characters translated like
5709 in the output of the ":menu" command listing.
5710 When the {rhs} of a menu item is empty, then
5711 "<Nop>" is returned.
5712 script v:true if script-local remapping of {rhs} is
5713 allowed else v:false. See |:menu-script|.
5714 shortcut shortcut key (character after '&' in
5715 the menu name) |menu-shortcut|
5716 silent v:true if the menu item is created
5717 with <silent> argument |:menu-silent|
5718 submenus |List| containing the names of
5719 all the submenus. Present only if the menu
5720 item has submenus.
5721
5722 Returns an empty dictionary if the menu item is not found.
5723
5724 Examples: >
5725 :echo menu_info('Edit.Cut')
5726 :echo menu_info('File.Save', 'n')
5727
5728 " Display the entire menu hierarchy in a buffer
5729 func ShowMenu(name, pfx)
5730 let m = menu_info(a:name)
5731 call append(line('$'), a:pfx .. m.display)
5732 for child in m->get('submenus', [])
5733 call ShowMenu(a:name .. '.' .. escape(child, '.'),
5734 \ a:pfx .. ' ')
5735 endfor
5736 endfunc
5737 new
5738 for topmenu in menu_info('').submenus
5739 call ShowMenu(topmenu, '')
5740 endfor
5741 <
5742 Can also be used as a |method|: >
5743 GetMenuName()->menu_info('v')
5744
5745
5746 < *min()*
5747 min({expr}) Return the minimum value of all items in {expr}. Example: >
5748 echo min([apples, pears, oranges])
5749
5750 < {expr} can be a |List| or a |Dictionary|. For a Dictionary,
5751 it returns the minimum of all values in the Dictionary.
5752 If {expr} is neither a List nor a Dictionary, or one of the
5753 items in {expr} cannot be used as a Number this results in
5754 an error. An empty |List| or |Dictionary| results in zero.
5755
5756 Can also be used as a |method|: >
5757 mylist->min()
5758
5759 < *mkdir()* *E739*
5760 mkdir({name} [, {path} [, {prot}]])
5761 Create directory {name}.
5762
5763 If {path} is "p" then intermediate directories are created as
5764 necessary. Otherwise it must be "".
5765
5766 If {prot} is given it is used to set the protection bits of
5767 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
5768 the user, readable for others). Use 0o700 to make it
5769 unreadable for others. This is only used for the last part of
5770 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
5771 created with 0o755.
5772 Example: >
5773 :call mkdir($HOME . "/tmp/foo/bar", "p", 0o700)
5774
5775 < This function is not available in the |sandbox|.
5776
5777 There is no error if the directory already exists and the "p"
5778 flag is passed (since patch 8.0.1708). However, without the
5779 "p" option the call will fail.
5780
5781 The function result is a Number, which is TRUE if the call was
5782 successful or FALSE if the directory creation failed or partly
5783 failed.
5784
5785 Not available on all systems. To check use: >
5786 :if exists("*mkdir")
5787
5788 < Can also be used as a |method|: >
5789 GetName()->mkdir()
5790 <
5791 *mode()*
5792 mode([expr]) Return a string that indicates the current mode.
5793 If [expr] is supplied and it evaluates to a non-zero Number or
5794 a non-empty String (|non-zero-arg|), then the full mode is
5795 returned, otherwise only the first letter is returned.
5796 Also see |state()|.
5797
5798 n Normal
5799 no Operator-pending
5800 nov Operator-pending (forced characterwise |o_v|)
5801 noV Operator-pending (forced linewise |o_V|)
5802 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
5803 CTRL-V is one character
5804 niI Normal using |i_CTRL-O| in |Insert-mode|
5805 niR Normal using |i_CTRL-O| in |Replace-mode|
5806 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
5807 nt Terminal-Normal (insert goes to Terminal-Job mode)
5808 v Visual by character
5809 vs Visual by character using |v_CTRL-O| in Select mode
5810 V Visual by line
5811 Vs Visual by line using |v_CTRL-O| in Select mode
5812 CTRL-V Visual blockwise
5813 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
5814 s Select by character
5815 S Select by line
5816 CTRL-S Select blockwise
5817 i Insert
5818 ic Insert mode completion |compl-generic|
5819 ix Insert mode |i_CTRL-X| completion
5820 R Replace |R|
5821 Rc Replace mode completion |compl-generic|
5822 Rx Replace mode |i_CTRL-X| completion
5823 Rv Virtual Replace |gR|
5824 Rvc Virtual Replace mode completion |compl-generic|
5825 Rvx Virtual Replace mode |i_CTRL-X| completion
5826 c Command-line editing
5827 cv Vim Ex mode |gQ|
5828 ce Normal Ex mode |Q|
5829 r Hit-enter prompt
5830 rm The -- more -- prompt
5831 r? A |:confirm| query of some sort
5832 ! Shell or external command is executing
5833 t Terminal-Job mode: keys go to the job
5834
5835 This is useful in the 'statusline' option or when used
5836 with |remote_expr()| In most other places it always returns
5837 "c" or "n".
5838 Note that in the future more modes and more specific modes may
5839 be added. It's better not to compare the whole string but only
5840 the leading character(s).
5841 Also see |visualmode()|.
5842
5843 Can also be used as a |method|: >
5844 DoFull()->mode()
5845
5846 mzeval({expr}) *mzeval()*
5847 Evaluate MzScheme expression {expr} and return its result
5848 converted to Vim data structures.
5849 Numbers and strings are returned as they are.
5850 Pairs (including lists and improper lists) and vectors are
5851 returned as Vim |Lists|.
5852 Hash tables are represented as Vim |Dictionary| type with keys
5853 converted to strings.
5854 All other types are converted to string with display function.
5855 Examples: >
5856 :mz (define l (list 1 2 3))
5857 :mz (define h (make-hash)) (hash-set! h "list" l)
5858 :echo mzeval("l")
5859 :echo mzeval("h")
5860 <
5861 Note that in a `:def` function local variables are not visible
5862 to {expr}.
5863
5864 Can also be used as a |method|: >
5865 GetExpr()->mzeval()
5866 <
5867 {only available when compiled with the |+mzscheme| feature}
5868
5869 nextnonblank({lnum}) *nextnonblank()*
5870 Return the line number of the first line at or below {lnum}
5871 that is not blank. Example: >
5872 if getline(nextnonblank(1)) =~ "Java"
5873 < When {lnum} is invalid or there is no non-blank line at or
5874 below it, zero is returned.
5875 {lnum} is used like with |getline()|.
5876 See also |prevnonblank()|.
5877
5878 Can also be used as a |method|: >
5879 GetLnum()->nextnonblank()
5880
5881 nr2char({expr} [, {utf8}]) *nr2char()*
5882 Return a string with a single character, which has the number
5883 value {expr}. Examples: >
5884 nr2char(64) returns "@"
5885 nr2char(32) returns " "
5886 < When {utf8} is omitted or zero, the current 'encoding' is used.
5887 Example for "utf-8": >
5888 nr2char(300) returns I with bow character
5889 < When {utf8} is TRUE, always return UTF-8 characters.
5890 Note that a NUL character in the file is specified with
5891 nr2char(10), because NULs are represented with newline
5892 characters. nr2char(0) is a real NUL and terminates the
5893 string, thus results in an empty string.
5894 To turn a list of character numbers into a string: >
5895 let list = [65, 66, 67]
5896 let str = join(map(list, {_, val -> nr2char(val)}), '')
5897 < Result: "ABC"
5898
5899 Can also be used as a |method|: >
5900 GetNumber()->nr2char()
5901
5902 or({expr}, {expr}) *or()*
5903 Bitwise OR on the two arguments. The arguments are converted
5904 to a number. A List, Dict or Float argument causes an error.
5905 Example: >
5906 :let bits = or(bits, 0x80)
5907 < Can also be used as a |method|: >
5908 :let bits = bits->or(0x80)
5909
5910
5911 pathshorten({path} [, {len}]) *pathshorten()*
5912 Shorten directory names in the path {path} and return the
5913 result. The tail, the file name, is kept as-is. The other
5914 components in the path are reduced to {len} letters in length.
5915 If {len} is omitted or smaller than 1 then 1 is used (single
5916 letters). Leading '~' and '.' characters are kept. Examples: >
5917 :echo pathshorten('~/.vim/autoload/myfile.vim')
5918 < ~/.v/a/myfile.vim ~
5919 >
5920 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
5921 < ~/.vi/au/myfile.vim ~
5922 It doesn't matter if the path exists or not.
5923
5924 Can also be used as a |method|: >
5925 GetDirectories()->pathshorten()
5926
5927 perleval({expr}) *perleval()*
5928 Evaluate Perl expression {expr} in scalar context and return
5929 its result converted to Vim data structures. If value can't be
5930 converted, it is returned as a string Perl representation.
5931 Note: If you want an array or hash, {expr} must return a
5932 reference to it.
5933 Example: >
5934 :echo perleval('[1 .. 4]')
5935 < [1, 2, 3, 4]
5936
5937 Note that in a `:def` function local variables are not visible
5938 to {expr}.
5939
5940 Can also be used as a |method|: >
5941 GetExpr()->perleval()
5942
5943 < {only available when compiled with the |+perl| feature}
5944
5945
5946 popup_ functions are documented here: |popup-functions|
5947
5948
5949 pow({x}, {y}) *pow()*
5950 Return the power of {x} to the exponent {y} as a |Float|.
5951 {x} and {y} must evaluate to a |Float| or a |Number|.
5952 Examples: >
5953 :echo pow(3, 3)
5954 < 27.0 >
5955 :echo pow(2, 16)
5956 < 65536.0 >
5957 :echo pow(32, 0.20)
5958 < 2.0
5959
5960 Can also be used as a |method|: >
5961 Compute()->pow(3)
5962 <
5963 {only available when compiled with the |+float| feature}
5964
5965 prevnonblank({lnum}) *prevnonblank()*
5966 Return the line number of the first line at or above {lnum}
5967 that is not blank. Example: >
5968 let ind = indent(prevnonblank(v:lnum - 1))
5969 < When {lnum} is invalid or there is no non-blank line at or
5970 above it, zero is returned.
5971 {lnum} is used like with |getline()|.
5972 Also see |nextnonblank()|.
5973
5974 Can also be used as a |method|: >
5975 GetLnum()->prevnonblank()
5976
5977 printf({fmt}, {expr1} ...) *printf()*
5978 Return a String with {fmt}, where "%" items are replaced by
5979 the formatted form of their respective arguments. Example: >
5980 printf("%4d: E%d %.30s", lnum, errno, msg)
5981 < May result in:
5982 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
5983
5984 When used as a |method| the base is passed as the second
5985 argument: >
5986 Compute()->printf("result: %d")
5987
5988 < Often used items are:
5989 %s string
5990 %6S string right-aligned in 6 display cells
5991 %6s string right-aligned in 6 bytes
5992 %.9s string truncated to 9 bytes
5993 %c single byte
5994 %d decimal number
5995 %5d decimal number padded with spaces to 5 characters
5996 %x hex number
5997 %04x hex number padded with zeros to at least 4 characters
5998 %X hex number using upper case letters
5999 %o octal number
6000 %08b binary number padded with zeros to at least 8 chars
6001 %f floating point number as 12.23, inf, -inf or nan
6002 %F floating point number as 12.23, INF, -INF or NAN
6003 %e floating point number as 1.23e3, inf, -inf or nan
6004 %E floating point number as 1.23E3, INF, -INF or NAN
6005 %g floating point number, as %f or %e depending on value
6006 %G floating point number, as %F or %E depending on value
6007 %% the % character itself
6008
6009 Conversion specifications start with '%' and end with the
6010 conversion type. All other characters are copied unchanged to
6011 the result.
6012
6013 The "%" starts a conversion specification. The following
6014 arguments appear in sequence:
6015
6016 % [flags] [field-width] [.precision] type
6017
6018 flags
6019 Zero or more of the following flags:
6020
6021 # The value should be converted to an "alternate
6022 form". For c, d, and s conversions, this option
6023 has no effect. For o conversions, the precision
6024 of the number is increased to force the first
6025 character of the output string to a zero (except
6026 if a zero value is printed with an explicit
6027 precision of zero).
6028 For b and B conversions, a non-zero result has
6029 the string "0b" (or "0B" for B conversions)
6030 prepended to it.
6031 For x and X conversions, a non-zero result has
6032 the string "0x" (or "0X" for X conversions)
6033 prepended to it.
6034
6035 0 (zero) Zero padding. For all conversions the converted
6036 value is padded on the left with zeros rather
6037 than blanks. If a precision is given with a
6038 numeric conversion (d, b, B, o, x, and X), the 0
6039 flag is ignored.
6040
6041 - A negative field width flag; the converted value
6042 is to be left adjusted on the field boundary.
6043 The converted value is padded on the right with
6044 blanks, rather than on the left with blanks or
6045 zeros. A - overrides a 0 if both are given.
6046
6047 ' ' (space) A blank should be left before a positive
6048 number produced by a signed conversion (d).
6049
6050 + A sign must always be placed before a number
6051 produced by a signed conversion. A + overrides
6052 a space if both are used.
6053
6054 field-width
6055 An optional decimal digit string specifying a minimum
6056 field width. If the converted value has fewer bytes
6057 than the field width, it will be padded with spaces on
6058 the left (or right, if the left-adjustment flag has
6059 been given) to fill out the field width. For the S
6060 conversion the count is in cells.
6061
6062 .precision
6063 An optional precision, in the form of a period '.'
6064 followed by an optional digit string. If the digit
6065 string is omitted, the precision is taken as zero.
6066 This gives the minimum number of digits to appear for
6067 d, o, x, and X conversions, the maximum number of
6068 bytes to be printed from a string for s conversions,
6069 or the maximum number of cells to be printed from a
6070 string for S conversions.
6071 For floating point it is the number of digits after
6072 the decimal point.
6073
6074 type
6075 A character that specifies the type of conversion to
6076 be applied, see below.
6077
6078 A field width or precision, or both, may be indicated by an
6079 asterisk '*' instead of a digit string. In this case, a
6080 Number argument supplies the field width or precision. A
6081 negative field width is treated as a left adjustment flag
6082 followed by a positive field width; a negative precision is
6083 treated as though it were missing. Example: >
6084 :echo printf("%d: %.*s", nr, width, line)
6085 < This limits the length of the text used from "line" to
6086 "width" bytes.
6087
6088 The conversion specifiers and their meanings are:
6089
6090 *printf-d* *printf-b* *printf-B* *printf-o*
6091 *printf-x* *printf-X*
6092 dbBoxX The Number argument is converted to signed decimal
6093 (d), unsigned binary (b and B), unsigned octal (o), or
6094 unsigned hexadecimal (x and X) notation. The letters
6095 "abcdef" are used for x conversions; the letters
6096 "ABCDEF" are used for X conversions.
6097 The precision, if any, gives the minimum number of
6098 digits that must appear; if the converted value
6099 requires fewer digits, it is padded on the left with
6100 zeros.
6101 In no case does a non-existent or small field width
6102 cause truncation of a numeric field; if the result of
6103 a conversion is wider than the field width, the field
6104 is expanded to contain the conversion result.
6105 The 'h' modifier indicates the argument is 16 bits.
6106 The 'l' modifier indicates the argument is 32 bits.
6107 The 'L' modifier indicates the argument is 64 bits.
6108 Generally, these modifiers are not useful. They are
6109 ignored when type is known from the argument.
6110
6111 i alias for d
6112 D alias for ld
6113 U alias for lu
6114 O alias for lo
6115
6116 *printf-c*
6117 c The Number argument is converted to a byte, and the
6118 resulting character is written.
6119
6120 *printf-s*
6121 s The text of the String argument is used. If a
6122 precision is specified, no more bytes than the number
6123 specified are used.
6124 If the argument is not a String type, it is
6125 automatically converted to text with the same format
6126 as ":echo".
6127 *printf-S*
6128 S The text of the String argument is used. If a
6129 precision is specified, no more display cells than the
6130 number specified are used.
6131
6132 *printf-f* *E807*
6133 f F The Float argument is converted into a string of the
6134 form 123.456. The precision specifies the number of
6135 digits after the decimal point. When the precision is
6136 zero the decimal point is omitted. When the precision
6137 is not specified 6 is used. A really big number
6138 (out of range or dividing by zero) results in "inf"
6139 or "-inf" with %f (INF or -INF with %F).
6140 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
6141 Example: >
6142 echo printf("%.2f", 12.115)
6143 < 12.12
6144 Note that roundoff depends on the system libraries.
6145 Use |round()| when in doubt.
6146
6147 *printf-e* *printf-E*
6148 e E The Float argument is converted into a string of the
6149 form 1.234e+03 or 1.234E+03 when using 'E'. The
6150 precision specifies the number of digits after the
6151 decimal point, like with 'f'.
6152
6153 *printf-g* *printf-G*
6154 g G The Float argument is converted like with 'f' if the
6155 value is between 0.001 (inclusive) and 10000000.0
6156 (exclusive). Otherwise 'e' is used for 'g' and 'E'
6157 for 'G'. When no precision is specified superfluous
6158 zeroes and '+' signs are removed, except for the zero
6159 immediately after the decimal point. Thus 10000000.0
6160 results in 1.0e7.
6161
6162 *printf-%*
6163 % A '%' is written. No argument is converted. The
6164 complete conversion specification is "%%".
6165
6166 When a Number argument is expected a String argument is also
6167 accepted and automatically converted.
6168 When a Float or String argument is expected a Number argument
6169 is also accepted and automatically converted.
6170 Any other argument type results in an error message.
6171
6172 *E766* *E767*
6173 The number of {exprN} arguments must exactly match the number
6174 of "%" items. If there are not sufficient or too many
6175 arguments an error is given. Up to 18 arguments can be used.
6176
6177
6178 prompt_getprompt({buf}) *prompt_getprompt()*
6179 Returns the effective prompt text for buffer {buf}. {buf} can
6180 be a buffer name or number. See |prompt-buffer|.
6181
6182 If the buffer doesn't exist or isn't a prompt buffer, an empty
6183 string is returned.
6184
6185 Can also be used as a |method|: >
6186 GetBuffer()->prompt_getprompt()
6187
6188 < {only available when compiled with the |+channel| feature}
6189
6190
6191 prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
6192 Set prompt callback for buffer {buf} to {expr}. When {expr}
6193 is an empty string the callback is removed. This has only
6194 effect if {buf} has 'buftype' set to "prompt".
6195
6196 The callback is invoked when pressing Enter. The current
6197 buffer will always be the prompt buffer. A new line for a
6198 prompt is added before invoking the callback, thus the prompt
6199 for which the callback was invoked will be in the last but one
6200 line.
6201 If the callback wants to add text to the buffer, it must
6202 insert it above the last line, since that is where the current
6203 prompt is. This can also be done asynchronously.
6204 The callback is invoked with one argument, which is the text
6205 that was entered at the prompt. This can be an empty string
6206 if the user only typed Enter.
6207 Example: >
6208 call prompt_setcallback(bufnr(), function('s:TextEntered'))
6209 func s:TextEntered(text)
6210 if a:text == 'exit' || a:text == 'quit'
6211 stopinsert
6212 close
6213 else
6214 call append(line('$') - 1, 'Entered: "' . a:text . '"')
6215 " Reset 'modified' to allow the buffer to be closed.
6216 set nomodified
6217 endif
6218 endfunc
6219
6220 < Can also be used as a |method|: >
6221 GetBuffer()->prompt_setcallback(callback)
6222
6223 < {only available when compiled with the |+channel| feature}
6224
6225 prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
6226 Set a callback for buffer {buf} to {expr}. When {expr} is an
6227 empty string the callback is removed. This has only effect if
6228 {buf} has 'buftype' set to "prompt".
6229
6230 This callback will be invoked when pressing CTRL-C in Insert
6231 mode. Without setting a callback Vim will exit Insert mode,
6232 as in any buffer.
6233
6234 Can also be used as a |method|: >
6235 GetBuffer()->prompt_setinterrupt(callback)
6236
6237 < {only available when compiled with the |+channel| feature}
6238
6239 prompt_setprompt({buf}, {text}) *prompt_setprompt()*
6240 Set prompt for buffer {buf} to {text}. You most likely want
6241 {text} to end in a space.
6242 The result is only visible if {buf} has 'buftype' set to
6243 "prompt". Example: >
6244 call prompt_setprompt(bufnr(), 'command: ')
6245 <
6246 Can also be used as a |method|: >
6247 GetBuffer()->prompt_setprompt('command: ')
6248
6249 < {only available when compiled with the |+channel| feature}
6250
6251 prop_ functions are documented here: |text-prop-functions|
6252
6253 pum_getpos() *pum_getpos()*
6254 If the popup menu (see |ins-completion-menu|) is not visible,
6255 returns an empty |Dictionary|, otherwise, returns a
6256 |Dictionary| with the following keys:
6257 height nr of items visible
6258 width screen cells
6259 row top screen row (0 first row)
6260 col leftmost screen column (0 first col)
6261 size total nr of items
6262 scrollbar |TRUE| if scrollbar is visible
6263
6264 The values are the same as in |v:event| during
6265 |CompleteChanged|.
6266
6267 pumvisible() *pumvisible()*
6268 Returns non-zero when the popup menu is visible, zero
6269 otherwise. See |ins-completion-menu|.
6270 This can be used to avoid some things that would remove the
6271 popup menu.
6272
6273 py3eval({expr}) *py3eval()*
6274 Evaluate Python expression {expr} and return its result
6275 converted to Vim data structures.
6276 Numbers and strings are returned as they are (strings are
6277 copied though, Unicode strings are additionally converted to
6278 'encoding').
6279 Lists are represented as Vim |List| type.
6280 Dictionaries are represented as Vim |Dictionary| type with
6281 keys converted to strings.
6282 Note that in a `:def` function local variables are not visible
6283 to {expr}.
6284
6285 Can also be used as a |method|: >
6286 GetExpr()->py3eval()
6287
6288 < {only available when compiled with the |+python3| feature}
6289
6290 *E858* *E859*
6291 pyeval({expr}) *pyeval()*
6292 Evaluate Python expression {expr} and return its result
6293 converted to Vim data structures.
6294 Numbers and strings are returned as they are (strings are
6295 copied though).
6296 Lists are represented as Vim |List| type.
6297 Dictionaries are represented as Vim |Dictionary| type,
6298 non-string keys result in error.
6299 Note that in a `:def` function local variables are not visible
6300 to {expr}.
6301
6302 Can also be used as a |method|: >
6303 GetExpr()->pyeval()
6304
6305 < {only available when compiled with the |+python| feature}
6306
6307 pyxeval({expr}) *pyxeval()*
6308 Evaluate Python expression {expr} and return its result
6309 converted to Vim data structures.
6310 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
6311 See also: |pyeval()|, |py3eval()|
6312
6313 Can also be used as a |method|: >
6314 GetExpr()->pyxeval()
6315
6316 < {only available when compiled with the |+python| or the
6317 |+python3| feature}
6318
6319 rand([{expr}]) *rand()* *random*
6320 Return a pseudo-random Number generated with an xoshiro128**
6321 algorithm using seed {expr}. The returned number is 32 bits,
6322 also on 64 bits systems, for consistency.
6323 {expr} can be initialized by |srand()| and will be updated by
6324 rand(). If {expr} is omitted, an internal seed value is used
6325 and updated.
6326
6327 Examples: >
6328 :echo rand()
6329 :let seed = srand()
6330 :echo rand(seed)
6331 :echo rand(seed) % 16 " random number 0 - 15
6332 <
6333
6334 *E726* *E727*
6335 range({expr} [, {max} [, {stride}]]) *range()*
6336 Returns a |List| with Numbers:
6337 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
6338 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
6339 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
6340 {max}] (increasing {expr} with {stride} each time, not
6341 producing a value past {max}).
6342 When the maximum is one before the start the result is an
6343 empty list. When the maximum is more than one before the
6344 start this is an error.
6345 Examples: >
6346 range(4) " [0, 1, 2, 3]
6347 range(2, 4) " [2, 3, 4]
6348 range(2, 9, 3) " [2, 5, 8]
6349 range(2, -2, -1) " [2, 1, 0, -1, -2]
6350 range(0) " []
6351 range(2, 0) " error!
6352 <
6353 Can also be used as a |method|: >
6354 GetExpr()->range()
6355 <
6356
6357 readblob({fname}) *readblob()*
6358 Read file {fname} in binary mode and return a |Blob|.
6359 When the file can't be opened an error message is given and
6360 the result is an empty |Blob|.
6361 Also see |readfile()| and |writefile()|.
6362
6363
6364 readdir({directory} [, {expr} [, {dict}]]) *readdir()*
6365 Return a list with file and directory names in {directory}.
6366 You can also use |glob()| if you don't need to do complicated
6367 things, such as limiting the number of matches.
6368 The list will be sorted (case sensitive), see the {dict}
6369 argument below for changing the sort order.
6370
6371 When {expr} is omitted all entries are included.
6372 When {expr} is given, it is evaluated to check what to do:
6373 If {expr} results in -1 then no further entries will
6374 be handled.
6375 If {expr} results in 0 then this entry will not be
6376 added to the list.
6377 If {expr} results in 1 then this entry will be added
6378 to the list.
6379 The entries "." and ".." are always excluded.
6380 Each time {expr} is evaluated |v:val| is set to the entry name.
6381 When {expr} is a function the name is passed as the argument.
6382 For example, to get a list of files ending in ".txt": >
6383 readdir(dirname, {n -> n =~ '.txt$'})
6384 < To skip hidden and backup files: >
6385 readdir(dirname, {n -> n !~ '^\.\|\~$'})
6386
6387 < The optional {dict} argument allows for further custom
6388 values. Currently this is used to specify if and how sorting
6389 should be performed. The dict can have the following members:
6390
6391 sort How to sort the result returned from the system.
6392 Valid values are:
6393 "none" do not sort (fastest method)
6394 "case" sort case sensitive (byte value of
6395 each character, technically, using
6396 strcmp()) (default)
6397 "icase" sort case insensitive (technically
6398 using strcasecmp())
6399 "collate" sort using the collation order
6400 of the "POSIX" or "C" |locale|
6401 (technically using strcoll())
6402 Other values are silently ignored.
6403
6404 For example, to get a list of all files in the current
6405 directory without sorting the individual entries: >
6406 readdir('.', '1', #{sort: 'none'})
6407 < If you want to get a directory tree: >
6408 function! s:tree(dir)
6409 return {a:dir : map(readdir(a:dir),
6410 \ {_, x -> isdirectory(x) ?
6411 \ {x : s:tree(a:dir . '/' . x)} : x})}
6412 endfunction
6413 echo s:tree(".")
6414 <
6415 Can also be used as a |method|: >
6416 GetDirName()->readdir()
6417 <
6418 readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
6419 Extended version of |readdir()|.
6420 Return a list of Dictionaries with file and directory
6421 information in {directory}.
6422 This is useful if you want to get the attributes of file and
6423 directory at the same time as getting a list of a directory.
6424 This is much faster than calling |readdir()| then calling
6425 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
6426 each file and directory especially on MS-Windows.
6427 The list will by default be sorted by name (case sensitive),
6428 the sorting can be changed by using the optional {dict}
6429 argument, see |readdir()|.
6430
6431 The Dictionary for file and directory information has the
6432 following items:
6433 group Group name of the entry. (Only on Unix)
6434 name Name of the entry.
6435 perm Permissions of the entry. See |getfperm()|.
6436 size Size of the entry. See |getfsize()|.
6437 time Timestamp of the entry. See |getftime()|.
6438 type Type of the entry.
6439 On Unix, almost same as |getftype()| except:
6440 Symlink to a dir "linkd"
6441 Other symlink "link"
6442 On MS-Windows:
6443 Normal file "file"
6444 Directory "dir"
6445 Junction "junction"
6446 Symlink to a dir "linkd"
6447 Other symlink "link"
6448 Other reparse point "reparse"
6449 user User name of the entry's owner. (Only on Unix)
6450 On Unix, if the entry is a symlink, the Dictionary includes
6451 the information of the target (except the "type" item).
6452 On MS-Windows, it includes the information of the symlink
6453 itself because of performance reasons.
6454
6455 When {expr} is omitted all entries are included.
6456 When {expr} is given, it is evaluated to check what to do:
6457 If {expr} results in -1 then no further entries will
6458 be handled.
6459 If {expr} results in 0 then this entry will not be
6460 added to the list.
6461 If {expr} results in 1 then this entry will be added
6462 to the list.
6463 The entries "." and ".." are always excluded.
6464 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
6465 of the entry.
6466 When {expr} is a function the entry is passed as the argument.
6467 For example, to get a list of files ending in ".txt": >
6468 readdirex(dirname, {e -> e.name =~ '.txt$'})
6469 <
6470 For example, to get a list of all files in the current
6471 directory without sorting the individual entries: >
6472 readdirex(dirname, '1', #{sort: 'none'})
6473
6474 <
6475 Can also be used as a |method|: >
6476 GetDirName()->readdirex()
6477 <
6478
6479 *readfile()*
6480 readfile({fname} [, {type} [, {max}]])
6481 Read file {fname} and return a |List|, each line of the file
6482 as an item. Lines are broken at NL characters. Macintosh
6483 files separated with CR will result in a single long line
6484 (unless a NL appears somewhere).
6485 All NUL characters are replaced with a NL character.
6486 When {type} contains "b" binary mode is used:
6487 - When the last line ends in a NL an extra empty list item is
6488 added.
6489 - No CR characters are removed.
6490 Otherwise:
6491 - CR characters that appear before a NL are removed.
6492 - Whether the last line ends in a NL or not does not matter.
6493 - When 'encoding' is Unicode any UTF-8 byte order mark is
6494 removed from the text.
6495 When {max} is given this specifies the maximum number of lines
6496 to be read. Useful if you only want to check the first ten
6497 lines of a file: >
6498 :for line in readfile(fname, '', 10)
6499 : if line =~ 'Date' | echo line | endif
6500 :endfor
6501 < When {max} is negative -{max} lines from the end of the file
6502 are returned, or as many as there are.
6503 When {max} is zero the result is an empty list.
6504 Note that without {max} the whole file is read into memory.
6505 Also note that there is no recognition of encoding. Read a
6506 file into a buffer if you need to.
6507 Deprecated (use |readblob()| instead): When {type} contains
6508 "B" a |Blob| is returned with the binary data of the file
6509 unmodified.
6510 When the file can't be opened an error message is given and
6511 the result is an empty list.
6512 Also see |writefile()|.
6513
6514 Can also be used as a |method|: >
6515 GetFileName()->readfile()
6516
6517 reduce({object}, {func} [, {initial}]) *reduce()* *E998*
6518 {func} is called for every item in {object}, which can be a
6519 |String|, |List| or a |Blob|. {func} is called with two
6520 arguments: the result so far and current item. After
6521 processing all items the result is returned.
6522
6523 {initial} is the initial result. When omitted, the first item
6524 in {object} is used and {func} is first called for the second
6525 item. If {initial} is not given and {object} is empty no
6526 result can be computed, an E998 error is given.
6527
6528 Examples: >
6529 echo reduce([1, 3, 5], { acc, val -> acc + val })
6530 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
6531 echo reduce(0z1122, { acc, val -> 2 * acc + val })
6532 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
6533 <
6534 Can also be used as a |method|: >
6535 echo mylist->reduce({ acc, val -> acc + val }, 0)
6536
6537
6538 reg_executing() *reg_executing()*
6539 Returns the single letter name of the register being executed.
6540 Returns an empty string when no register is being executed.
6541 See |@|.
6542
6543 reg_recording() *reg_recording()*
6544 Returns the single letter name of the register being recorded.
6545 Returns an empty string when not recording. See |q|.
6546
6547 reltime([{start} [, {end}]]) *reltime()*
6548 Return an item that represents a time value. The item is a
6549 list with items that depend on the system. In Vim 9 script
6550 list<any> can be used.
6551 The item can be passed to |reltimestr()| to convert it to a
6552 string or |reltimefloat()| to convert to a Float.
6553
6554 Without an argument reltime() returns the current time.
6555 With one argument is returns the time passed since the time
6556 specified in the argument.
6557 With two arguments it returns the time passed between {start}
6558 and {end}.
6559
6560 The {start} and {end} arguments must be values returned by
6561 reltime(). If there is an error zero is returned in legacy
6562 script, in Vim9 script an error is given.
6563
6564 Can also be used as a |method|: >
6565 GetStart()->reltime()
6566 <
6567 {only available when compiled with the |+reltime| feature}
6568
6569 reltimefloat({time}) *reltimefloat()*
6570 Return a Float that represents the time value of {time}.
6571 Example: >
6572 let start = reltime()
6573 call MyFunction()
6574 let seconds = reltimefloat(reltime(start))
6575 < See the note of reltimestr() about overhead.
6576 Also see |profiling|.
6577 If there is an error 0.0 is returned in legacy script, in Vim9
6578 script an error is given.
6579
6580 Can also be used as a |method|: >
6581 reltime(start)->reltimefloat()
6582
6583 < {only available when compiled with the |+reltime| feature}
6584
6585 reltimestr({time}) *reltimestr()*
6586 Return a String that represents the time value of {time}.
6587 This is the number of seconds, a dot and the number of
6588 microseconds. Example: >
6589 let start = reltime()
6590 call MyFunction()
6591 echo reltimestr(reltime(start))
6592 < Note that overhead for the commands will be added to the time.
6593 The accuracy depends on the system.
6594 Leading spaces are used to make the string align nicely. You
6595 can use split() to remove it. >
6596 echo split(reltimestr(reltime(start)))[0]
6597 < Also see |profiling|.
6598 If there is an error an empty string is returned in legacy
6599 script, in Vim9 script an error is given.
6600
6601 Can also be used as a |method|: >
6602 reltime(start)->reltimestr()
6603
6604 < {only available when compiled with the |+reltime| feature}
6605
6606 *remote_expr()* *E449*
6607 remote_expr({server}, {string} [, {idvar} [, {timeout}]])
6608 Send the {string} to {server}. The string is sent as an
6609 expression and the result is returned after evaluation.
6610 The result must be a String or a |List|. A |List| is turned
6611 into a String by joining the items with a line break in
6612 between (not at the end), like with join(expr, "\n").
6613 If {idvar} is present and not empty, it is taken as the name
6614 of a variable and a {serverid} for later use with
6615 |remote_read()| is stored there.
6616 If {timeout} is given the read times out after this many
6617 seconds. Otherwise a timeout of 600 seconds is used.
6618 See also |clientserver| |RemoteReply|.
6619 This function is not available in the |sandbox|.
6620 {only available when compiled with the |+clientserver| feature}
6621 Note: Any errors will cause a local error message to be issued
6622 and the result will be the empty string.
6623
6624 Variables will be evaluated in the global namespace,
6625 independent of a function currently being active. Except
6626 when in debug mode, then local function variables and
6627 arguments can be evaluated.
6628
6629 Examples: >
6630 :echo remote_expr("gvim", "2+2")
6631 :echo remote_expr("gvim1", "b:current_syntax")
6632 <
6633 Can also be used as a |method|: >
6634 ServerName()->remote_expr(expr)
6635
6636 remote_foreground({server}) *remote_foreground()*
6637 Move the Vim server with the name {server} to the foreground.
6638 The {server} argument is a string.
6639 This works like: >
6640 remote_expr({server}, "foreground()")
6641 < Except that on Win32 systems the client does the work, to work
6642 around the problem that the OS doesn't always allow the server
6643 to bring itself to the foreground.
6644 Note: This does not restore the window if it was minimized,
6645 like foreground() does.
6646 This function is not available in the |sandbox|.
6647
6648 Can also be used as a |method|: >
6649 ServerName()->remote_foreground()
6650
6651 < {only in the Win32, Athena, Motif and GTK GUI versions and the
6652 Win32 console version}
6653
6654
6655 remote_peek({serverid} [, {retvar}]) *remote_peek()*
6656 Returns a positive number if there are available strings
6657 from {serverid}. Copies any reply string into the variable
6658 {retvar} if specified. {retvar} must be a string with the
6659 name of a variable.
6660 Returns zero if none are available.
6661 Returns -1 if something is wrong.
6662 See also |clientserver|.
6663 This function is not available in the |sandbox|.
6664 {only available when compiled with the |+clientserver| feature}
6665 Examples: >
6666 :let repl = ""
6667 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
6668
6669 < Can also be used as a |method|: >
6670 ServerId()->remote_peek()
6671
6672 remote_read({serverid}, [{timeout}]) *remote_read()*
6673 Return the oldest available reply from {serverid} and consume
6674 it. Unless a {timeout} in seconds is given, it blocks until a
6675 reply is available.
6676 See also |clientserver|.
6677 This function is not available in the |sandbox|.
6678 {only available when compiled with the |+clientserver| feature}
6679 Example: >
6680 :echo remote_read(id)
6681
6682 < Can also be used as a |method|: >
6683 ServerId()->remote_read()
6684 <
6685 *remote_send()* *E241*
6686 remote_send({server}, {string} [, {idvar}])
6687 Send the {string} to {server}. The string is sent as input
6688 keys and the function returns immediately. At the Vim server
6689 the keys are not mapped |:map|.
6690 If {idvar} is present, it is taken as the name of a variable
6691 and a {serverid} for later use with remote_read() is stored
6692 there.
6693 See also |clientserver| |RemoteReply|.
6694 This function is not available in the |sandbox|.
6695 {only available when compiled with the |+clientserver| feature}
6696
6697 Note: Any errors will be reported in the server and may mess
6698 up the display.
6699 Examples: >
6700 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
6701 \ remote_read(serverid)
6702
6703 :autocmd NONE RemoteReply *
6704 \ echo remote_read(expand("<amatch>"))
6705 :echo remote_send("gvim", ":sleep 10 | echo ".
6706 \ 'server2client(expand("<client>"), "HELLO")<CR>')
6707 <
6708 Can also be used as a |method|: >
6709 ServerName()->remote_send(keys)
6710 <
6711 *remote_startserver()* *E941* *E942*
6712 remote_startserver({name})
6713 Become the server {name}. This fails if already running as a
6714 server, when |v:servername| is not empty.
6715
6716 Can also be used as a |method|: >
6717 ServerName()->remote_startserver()
6718
6719 < {only available when compiled with the |+clientserver| feature}
6720
6721 remove({list}, {idx} [, {end}]) *remove()*
6722 Without {end}: Remove the item at {idx} from |List| {list} and
6723 return the item.
6724 With {end}: Remove items from {idx} to {end} (inclusive) and
6725 return a |List| with these items. When {idx} points to the same
6726 item as {end} a list with one item is returned. When {end}
6727 points to an item before {idx} this is an error.
6728 See |list-index| for possible values of {idx} and {end}.
6729 Example: >
6730 :echo "last item: " . remove(mylist, -1)
6731 :call remove(mylist, 0, 9)
6732 <
6733 Use |delete()| to remove a file.
6734
6735 Can also be used as a |method|: >
6736 mylist->remove(idx)
6737
6738 remove({blob}, {idx} [, {end}])
6739 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
6740 return the byte.
6741 With {end}: Remove bytes from {idx} to {end} (inclusive) and
6742 return a |Blob| with these bytes. When {idx} points to the same
6743 byte as {end} a |Blob| with one byte is returned. When {end}
6744 points to a byte before {idx} this is an error.
6745 Example: >
6746 :echo "last byte: " . remove(myblob, -1)
6747 :call remove(mylist, 0, 9)
6748
6749 remove({dict}, {key})
6750 Remove the entry from {dict} with key {key} and return it.
6751 Example: >
6752 :echo "removed " . remove(dict, "one")
6753 < If there is no {key} in {dict} this is an error.
6754
6755 rename({from}, {to}) *rename()*
6756 Rename the file by the name {from} to the name {to}. This
6757 should also work to move files across file systems. The
6758 result is a Number, which is 0 if the file was renamed
6759 successfully, and non-zero when the renaming failed.
6760 NOTE: If {to} exists it is overwritten without warning.
6761 This function is not available in the |sandbox|.
6762
6763 Can also be used as a |method|: >
6764 GetOldName()->rename(newname)
6765
6766 repeat({expr}, {count}) *repeat()*
6767 Repeat {expr} {count} times and return the concatenated
6768 result. Example: >
6769 :let separator = repeat('-', 80)
6770 < When {count} is zero or negative the result is empty.
6771 When {expr} is a |List| the result is {expr} concatenated
6772 {count} times. Example: >
6773 :let longlist = repeat(['a', 'b'], 3)
6774 < Results in ['a', 'b', 'a', 'b', 'a', 'b'].
6775
6776 Can also be used as a |method|: >
6777 mylist->repeat(count)
6778
6779 resolve({filename}) *resolve()* *E655*
6780 On MS-Windows, when {filename} is a shortcut (a .lnk file),
6781 returns the path the shortcut points to in a simplified form.
6782 When {filename} is a symbolic link or junction point, return
6783 the full path to the target. If the target of junction is
6784 removed, return {filename}.
6785 On Unix, repeat resolving symbolic links in all path
6786 components of {filename} and return the simplified result.
6787 To cope with link cycles, resolving of symbolic links is
6788 stopped after 100 iterations.
6789 On other systems, return the simplified {filename}.
6790 The simplification step is done as by |simplify()|.
6791 resolve() keeps a leading path component specifying the
6792 current directory (provided the result is still a relative
6793 path name) and also keeps a trailing path separator.
6794
6795 Can also be used as a |method|: >
6796 GetName()->resolve()
6797
6798 reverse({object}) *reverse()*
6799 Reverse the order of items in {object} in-place.
6800 {object} can be a |List| or a |Blob|.
6801 Returns {object}.
6802 If you want an object to remain unmodified make a copy first: >
6803 :let revlist = reverse(copy(mylist))
6804 < Can also be used as a |method|: >
6805 mylist->reverse()
6806
6807 round({expr}) *round()*
6808 Round off {expr} to the nearest integral value and return it
6809 as a |Float|. If {expr} lies halfway between two integral
6810 values, then use the larger one (away from zero).
6811 {expr} must evaluate to a |Float| or a |Number|.
6812 Examples: >
6813 echo round(0.456)
6814 < 0.0 >
6815 echo round(4.5)
6816 < 5.0 >
6817 echo round(-4.5)
6818 < -5.0
6819
6820 Can also be used as a |method|: >
6821 Compute()->round()
6822 <
6823 {only available when compiled with the |+float| feature}
6824
6825 rubyeval({expr}) *rubyeval()*
6826 Evaluate Ruby expression {expr} and return its result
6827 converted to Vim data structures.
6828 Numbers, floats and strings are returned as they are (strings
6829 are copied though).
6830 Arrays are represented as Vim |List| type.
6831 Hashes are represented as Vim |Dictionary| type.
6832 Other objects are represented as strings resulted from their
6833 "Object#to_s" method.
6834 Note that in a `:def` function local variables are not visible
6835 to {expr}.
6836
6837 Can also be used as a |method|: >
6838 GetRubyExpr()->rubyeval()
6839
6840 < {only available when compiled with the |+ruby| feature}
6841
6842 screenattr({row}, {col}) *screenattr()*
6843 Like |screenchar()|, but return the attribute. This is a rather
6844 arbitrary number that can only be used to compare to the
6845 attribute at other positions.
6846
6847 Can also be used as a |method|: >
6848 GetRow()->screenattr(col)
6849
6850 screenchar({row}, {col}) *screenchar()*
6851 The result is a Number, which is the character at position
6852 [row, col] on the screen. This works for every possible
6853 screen position, also status lines, window separators and the
6854 command line. The top left position is row one, column one
6855 The character excludes composing characters. For double-byte
6856 encodings it may only be the first byte.
6857 This is mainly to be used for testing.
6858 Returns -1 when row or col is out of range.
6859
6860 Can also be used as a |method|: >
6861 GetRow()->screenchar(col)
6862
6863 screenchars({row}, {col}) *screenchars()*
6864 The result is a |List| of Numbers. The first number is the same
6865 as what |screenchar()| returns. Further numbers are
6866 composing characters on top of the base character.
6867 This is mainly to be used for testing.
6868 Returns an empty List when row or col is out of range.
6869
6870 Can also be used as a |method|: >
6871 GetRow()->screenchars(col)
6872
6873 screencol() *screencol()*
6874 The result is a Number, which is the current screen column of
6875 the cursor. The leftmost column has number 1.
6876 This function is mainly used for testing.
6877
6878 Note: Always returns the current screen column, thus if used
6879 in a command (e.g. ":echo screencol()") it will return the
6880 column inside the command line, which is 1 when the command is
6881 executed. To get the cursor position in the file use one of
6882 the following mappings: >
6883 nnoremap <expr> GG ":echom ".screencol()."\n"
6884 nnoremap <silent> GG :echom screencol()<CR>
6885 nnoremap GG <Cmd>echom screencol()<CR>
6886 <
6887 screenpos({winid}, {lnum}, {col}) *screenpos()*
6888 The result is a Dict with the screen position of the text
6889 character in window {winid} at buffer line {lnum} and column
6890 {col}. {col} is a one-based byte index.
6891 The Dict has these members:
6892 row screen row
6893 col first screen column
6894 endcol last screen column
6895 curscol cursor screen column
6896 If the specified position is not visible, all values are zero.
6897 The "endcol" value differs from "col" when the character
6898 occupies more than one screen cell. E.g. for a Tab "col" can
6899 be 1 and "endcol" can be 8.
6900 The "curscol" value is where the cursor would be placed. For
6901 a Tab it would be the same as "endcol", while for a double
6902 width character it would be the same as "col".
6903 The |conceal| feature is ignored here, the column numbers are
6904 as if 'conceallevel' is zero. You can set the cursor to the
6905 right position and use |screencol()| to get the value with
6906 |conceal| taken into account.
6907
6908 Can also be used as a |method|: >
6909 GetWinid()->screenpos(lnum, col)
6910
6911 screenrow() *screenrow()*
6912 The result is a Number, which is the current screen row of the
6913 cursor. The top line has number one.
6914 This function is mainly used for testing.
6915 Alternatively you can use |winline()|.
6916
6917 Note: Same restrictions as with |screencol()|.
6918
6919 screenstring({row}, {col}) *screenstring()*
6920 The result is a String that contains the base character and
6921 any composing characters at position [row, col] on the screen.
6922 This is like |screenchars()| but returning a String with the
6923 characters.
6924 This is mainly to be used for testing.
6925 Returns an empty String when row or col is out of range.
6926
6927 Can also be used as a |method|: >
6928 GetRow()->screenstring(col)
6929 <
6930 *search()*
6931 search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
6932 Search for regexp pattern {pattern}. The search starts at the
6933 cursor position (you can use |cursor()| to set it).
6934
6935 When a match has been found its line number is returned.
6936 If there is no match a 0 is returned and the cursor doesn't
6937 move. No error message is given.
6938
6939 {flags} is a String, which can contain these character flags:
6940 'b' search Backward instead of forward
6941 'c' accept a match at the Cursor position
6942 'e' move to the End of the match
6943 'n' do Not move the cursor
6944 'p' return number of matching sub-Pattern (see below)
6945 's' Set the ' mark at the previous location of the cursor
6946 'w' Wrap around the end of the file
6947 'W' don't Wrap around the end of the file
6948 'z' start searching at the cursor column instead of zero
6949 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
6950
6951 If the 's' flag is supplied, the ' mark is set, only if the
6952 cursor is moved. The 's' flag cannot be combined with the 'n'
6953 flag.
6954
6955 'ignorecase', 'smartcase' and 'magic' are used.
6956
6957 When the 'z' flag is not given, forward searching always
6958 starts in column zero and then matches before the cursor are
6959 skipped. When the 'c' flag is present in 'cpo' the next
6960 search starts after the match. Without the 'c' flag the next
6961 search starts one column further. This matters for
6962 overlapping matches.
6963 When searching backwards and the 'z' flag is given then the
6964 search starts in column zero, thus no match in the current
6965 line will be found (unless wrapping around the end of the
6966 file).
6967
6968 When the {stopline} argument is given then the search stops
6969 after searching this line. This is useful to restrict the
6970 search to a range of lines. Examples: >
6971 let match = search('(', 'b', line("w0"))
6972 let end = search('END', '', line("w$"))
6973 < When {stopline} is used and it is not zero this also implies
6974 that the search does not wrap around the end of the file.
6975 A zero value is equal to not giving the argument.
6976
6977 When the {timeout} argument is given the search stops when
6978 more than this many milliseconds have passed. Thus when
6979 {timeout} is 500 the search stops after half a second.
6980 The value must not be negative. A zero value is like not
6981 giving the argument.
6982 {only available when compiled with the |+reltime| feature}
6983
6984 If the {skip} expression is given it is evaluated with the
6985 cursor positioned on the start of a match. If it evaluates to
6986 non-zero this match is skipped. This can be used, for
6987 example, to skip a match in a comment or a string.
6988 {skip} can be a string, which is evaluated as an expression, a
6989 function reference or a lambda.
6990 When {skip} is omitted or empty, every match is accepted.
6991 When evaluating {skip} causes an error the search is aborted
6992 and -1 returned.
6993 *search()-sub-match*
6994 With the 'p' flag the returned value is one more than the
6995 first sub-match in \(\). One if none of them matched but the
6996 whole pattern did match.
6997 To get the column number too use |searchpos()|.
6998
6999 The cursor will be positioned at the match, unless the 'n'
7000 flag is used.
7001
7002 Example (goes over all files in the argument list): >
7003 :let n = 1
7004 :while n <= argc() " loop over all files in arglist
7005 : exe "argument " . n
7006 : " start at the last char in the file and wrap for the
7007 : " first search to find match at start of file
7008 : normal G$
7009 : let flags = "w"
7010 : while search("foo", flags) > 0
7011 : s/foo/bar/g
7012 : let flags = "W"
7013 : endwhile
7014 : update " write the file if modified
7015 : let n = n + 1
7016 :endwhile
7017 <
7018 Example for using some flags: >
7019 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7020 < This will search for the keywords "if", "else", and "endif"
7021 under or after the cursor. Because of the 'p' flag, it
7022 returns 1, 2, or 3 depending on which keyword is found, or 0
7023 if the search fails. With the cursor on the first word of the
7024 line:
7025 if (foo == 0) | let foo = foo + 1 | endif ~
7026 the function returns 1. Without the 'c' flag, the function
7027 finds the "endif" and returns 3. The same thing happens
7028 without the 'e' flag if the cursor is on the "f" of "if".
7029 The 'n' flag tells the function not to move the cursor.
7030
7031 Can also be used as a |method|: >
7032 GetPattern()->search()
7033
7034 searchcount([{options}]) *searchcount()*
7035 Get or update the last search count, like what is displayed
7036 without the "S" flag in 'shortmess'. This works even if
7037 'shortmess' does contain the "S" flag.
7038
7039 This returns a |Dictionary|. The dictionary is empty if the
7040 previous pattern was not set and "pattern" was not specified.
7041
7042 key type meaning ~
7043 current |Number| current position of match;
7044 0 if the cursor position is
7045 before the first match
7046 exact_match |Boolean| 1 if "current" is matched on
7047 "pos", otherwise 0
7048 total |Number| total count of matches found
7049 incomplete |Number| 0: search was fully completed
7050 1: recomputing was timed out
7051 2: max count exceeded
7052
7053 For {options} see further down.
7054
7055 To get the last search count when |n| or |N| was pressed, call
7056 this function with `recompute: 0` . This sometimes returns
7057 wrong information because |n| and |N|'s maximum count is 99.
7058 If it exceeded 99 the result must be max count + 1 (100). If
7059 you want to get correct information, specify `recompute: 1`: >
7060
7061 " result == maxcount + 1 (100) when many matches
7062 let result = searchcount(#{recompute: 0})
7063
7064 " Below returns correct result (recompute defaults
7065 " to 1)
7066 let result = searchcount()
7067 <
7068 The function is useful to add the count to |statusline|: >
7069 function! LastSearchCount() abort
7070 let result = searchcount(#{recompute: 0})
7071 if empty(result)
7072 return ''
7073 endif
7074 if result.incomplete ==# 1 " timed out
7075 return printf(' /%s [?/??]', @/)
7076 elseif result.incomplete ==# 2 " max count exceeded
7077 if result.total > result.maxcount &&
7078 \ result.current > result.maxcount
7079 return printf(' /%s [>%d/>%d]', @/,
7080 \ result.current, result.total)
7081 elseif result.total > result.maxcount
7082 return printf(' /%s [%d/>%d]', @/,
7083 \ result.current, result.total)
7084 endif
7085 endif
7086 return printf(' /%s [%d/%d]', @/,
7087 \ result.current, result.total)
7088 endfunction
7089 let &statusline .= '%{LastSearchCount()}'
7090
7091 " Or if you want to show the count only when
7092 " 'hlsearch' was on
7093 " let &statusline .=
7094 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
7095 <
7096 You can also update the search count, which can be useful in a
7097 |CursorMoved| or |CursorMovedI| autocommand: >
7098
7099 autocmd CursorMoved,CursorMovedI *
7100 \ let s:searchcount_timer = timer_start(
7101 \ 200, function('s:update_searchcount'))
7102 function! s:update_searchcount(timer) abort
7103 if a:timer ==# s:searchcount_timer
7104 call searchcount(#{
7105 \ recompute: 1, maxcount: 0, timeout: 100})
7106 redrawstatus
7107 endif
7108 endfunction
7109 <
7110 This can also be used to count matched texts with specified
7111 pattern in the current buffer using "pattern": >
7112
7113 " Count '\<foo\>' in this buffer
7114 " (Note that it also updates search count)
7115 let result = searchcount(#{pattern: '\<foo\>'})
7116
7117 " To restore old search count by old pattern,
7118 " search again
7119 call searchcount()
7120 <
7121 {options} must be a |Dictionary|. It can contain:
7122 key type meaning ~
7123 recompute |Boolean| if |TRUE|, recompute the count
7124 like |n| or |N| was executed.
7125 otherwise returns the last
7126 computed result (when |n| or
7127 |N| was used when "S" is not
7128 in 'shortmess', or this
7129 function was called).
7130 (default: |TRUE|)
7131 pattern |String| recompute if this was given
7132 and different with |@/|.
7133 this works as same as the
7134 below command is executed
7135 before calling this function >
7136 let @/ = pattern
7137 < (default: |@/|)
7138 timeout |Number| 0 or negative number is no
7139 timeout. timeout milliseconds
7140 for recomputing the result
7141 (default: 0)
7142 maxcount |Number| 0 or negative number is no
7143 limit. max count of matched
7144 text while recomputing the
7145 result. if search exceeded
7146 total count, "total" value
7147 becomes `maxcount + 1`
7148 (default: 99)
7149 pos |List| `[lnum, col, off]` value
7150 when recomputing the result.
7151 this changes "current" result
7152 value. see |cursor()|,
7153 |getpos()|
7154 (default: cursor's position)
7155
7156 Can also be used as a |method|: >
7157 GetSearchOpts()->searchcount()
7158 <
7159 searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
7160 Search for the declaration of {name}.
7161
7162 With a non-zero {global} argument it works like |gD|, find
7163 first match in the file. Otherwise it works like |gd|, find
7164 first match in the function.
7165
7166 With a non-zero {thisblock} argument matches in a {} block
7167 that ends before the cursor position are ignored. Avoids
7168 finding variable declarations only valid in another scope.
7169
7170 Moves the cursor to the found match.
7171 Returns zero for success, non-zero for failure.
7172 Example: >
7173 if searchdecl('myvar') == 0
7174 echo getline('.')
7175 endif
7176 <
7177 Can also be used as a |method|: >
7178 GetName()->searchdecl()
7179 <
7180 *searchpair()*
7181 searchpair({start}, {middle}, {end} [, {flags} [, {skip}
7182 [, {stopline} [, {timeout}]]]])
7183 Search for the match of a nested start-end pair. This can be
7184 used to find the "endif" that matches an "if", while other
7185 if/endif pairs in between are ignored.
7186 The search starts at the cursor. The default is to search
7187 forward, include 'b' in {flags} to search backward.
7188 If a match is found, the cursor is positioned at it and the
7189 line number is returned. If no match is found 0 or -1 is
7190 returned and the cursor doesn't move. No error message is
7191 given.
7192
7193 {start}, {middle} and {end} are patterns, see |pattern|. They
7194 must not contain \( \) pairs. Use of \%( \) is allowed. When
7195 {middle} is not empty, it is found when searching from either
7196 direction, but only when not in a nested start-end pair. A
7197 typical use is: >
7198 searchpair('\<if\>', '\<else\>', '\<endif\>')
7199 < By leaving {middle} empty the "else" is skipped.
7200
7201 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
7202 |search()|. Additionally:
7203 'r' Repeat until no more matches found; will find the
7204 outer pair. Implies the 'W' flag.
7205 'm' Return number of matches instead of line number with
7206 the match; will be > 1 when 'r' is used.
7207 Note: it's nearly always a good idea to use the 'W' flag, to
7208 avoid wrapping around the end of the file.
7209
7210 When a match for {start}, {middle} or {end} is found, the
7211 {skip} expression is evaluated with the cursor positioned on
7212 the start of the match. It should return non-zero if this
7213 match is to be skipped. E.g., because it is inside a comment
7214 or a string.
7215 When {skip} is omitted or empty, every match is accepted.
7216 When evaluating {skip} causes an error the search is aborted
7217 and -1 returned.
7218 {skip} can be a string, a lambda, a funcref or a partial.
7219 Anything else makes the function fail.
7220 In a `:def` function when the {skip} argument is a string
7221 constant it is compiled into instructions.
7222
7223 For {stopline} and {timeout} see |search()|.
7224
7225 The value of 'ignorecase' is used. 'magic' is ignored, the
7226 patterns are used like it's on.
7227
7228 The search starts exactly at the cursor. A match with
7229 {start}, {middle} or {end} at the next character, in the
7230 direction of searching, is the first one found. Example: >
7231 if 1
7232 if 2
7233 endif 2
7234 endif 1
7235 < When starting at the "if 2", with the cursor on the "i", and
7236 searching forwards, the "endif 2" is found. When starting on
7237 the character just before the "if 2", the "endif 1" will be
7238 found. That's because the "if 2" will be found first, and
7239 then this is considered to be a nested if/endif from "if 2" to
7240 "endif 2".
7241 When searching backwards and {end} is more than one character,
7242 it may be useful to put "\zs" at the end of the pattern, so
7243 that when the cursor is inside a match with the end it finds
7244 the matching start.
7245
7246 Example, to find the "endif" command in a Vim script: >
7247
7248 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
7249 \ 'getline(".") =~ "^\\s*\""')
7250
7251 < The cursor must be at or after the "if" for which a match is
7252 to be found. Note that single-quote strings are used to avoid
7253 having to double the backslashes. The skip expression only
7254 catches comments at the start of a line, not after a command.
7255 Also, a word "en" or "if" halfway a line is considered a
7256 match.
7257 Another example, to search for the matching "{" of a "}": >
7258
7259 :echo searchpair('{', '', '}', 'bW')
7260
7261 < This works when the cursor is at or before the "}" for which a
7262 match is to be found. To reject matches that syntax
7263 highlighting recognized as strings: >
7264
7265 :echo searchpair('{', '', '}', 'bW',
7266 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
7267 <
7268 *searchpairpos()*
7269 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
7270 [, {stopline} [, {timeout}]]]])
7271 Same as |searchpair()|, but returns a |List| with the line and
7272 column position of the match. The first element of the |List|
7273 is the line number and the second element is the byte index of
7274 the column position of the match. If no match is found,
7275 returns [0, 0]. >
7276
7277 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
7278 <
7279 See |match-parens| for a bigger and more useful example.
7280
7281 *searchpos()*
7282 searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7283 Same as |search()|, but returns a |List| with the line and
7284 column position of the match. The first element of the |List|
7285 is the line number and the second element is the byte index of
7286 the column position of the match. If no match is found,
7287 returns [0, 0].
7288 Example: >
7289 :let [lnum, col] = searchpos('mypattern', 'n')
7290
7291 < When the 'p' flag is given then there is an extra item with
7292 the sub-pattern match number |search()-sub-match|. Example: >
7293 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
7294 < In this example "submatch" is 2 when a lowercase letter is
7295 found |/\l|, 3 when an uppercase letter is found |/\u|.
7296
7297 Can also be used as a |method|: >
7298 GetPattern()->searchpos()
7299
7300 server2client({clientid}, {string}) *server2client()*
7301 Send a reply string to {clientid}. The most recent {clientid}
7302 that sent a string can be retrieved with expand("<client>").
7303 {only available when compiled with the |+clientserver| feature}
7304 Returns zero for success, -1 for failure.
7305 Note:
7306 This id has to be stored before the next command can be
7307 received. I.e. before returning from the received command and
7308 before calling any commands that waits for input.
7309 See also |clientserver|.
7310 Example: >
7311 :echo server2client(expand("<client>"), "HELLO")
7312
7313 < Can also be used as a |method|: >
7314 GetClientId()->server2client(string)
7315 <
7316 serverlist() *serverlist()*
7317 Return a list of available server names, one per line.
7318 When there are no servers or the information is not available
7319 an empty string is returned. See also |clientserver|.
7320 {only available when compiled with the |+clientserver| feature}
7321 Example: >
7322 :echo serverlist()
7323 <
7324 setbufline({buf}, {lnum}, {text}) *setbufline()*
7325 Set line {lnum} to {text} in buffer {buf}. This works like
7326 |setline()| for the specified buffer.
7327
7328 This function works only for loaded buffers. First call
7329 |bufload()| if needed.
7330
7331 To insert lines use |appendbufline()|.
7332 Any text properties in {lnum} are cleared.
7333
7334 {text} can be a string to set one line, or a list of strings
7335 to set multiple lines. If the list extends below the last
7336 line then those lines are added.
7337
7338 For the use of {buf}, see |bufname()| above.
7339
7340 {lnum} is used like with |setline()|.
7341 Use "$" to refer to the last line in buffer {buf}.
7342 When {lnum} is just below the last line the {text} will be
7343 added below the last line.
7344
7345 When {buf} is not a valid buffer, the buffer is not loaded or
7346 {lnum} is not valid then 1 is returned. In |Vim9| script an
7347 error is given.
7348 On success 0 is returned.
7349
7350 Can also be used as a |method|, the base is passed as the
7351 third argument: >
7352 GetText()->setbufline(buf, lnum)
7353
7354 setbufvar({buf}, {varname}, {val}) *setbufvar()*
7355 Set option or local variable {varname} in buffer {buf} to
7356 {val}.
7357 This also works for a global or local window option, but it
7358 doesn't work for a global or local window variable.
7359 For a local window option the global value is unchanged.
7360 For the use of {buf}, see |bufname()| above.
7361 The {varname} argument is a string.
7362 Note that the variable name without "b:" must be used.
7363 Examples: >
7364 :call setbufvar(1, "&mod", 1)
7365 :call setbufvar("todo", "myvar", "foobar")
7366 < This function is not available in the |sandbox|.
7367
7368 Can also be used as a |method|, the base is passed as the
7369 third argument: >
7370 GetValue()->setbufvar(buf, varname)
7371
7372
7373 setcellwidths({list}) *setcellwidths()*
7374 Specify overrides for cell widths of character ranges. This
7375 tells Vim how wide characters are, counted in screen cells.
7376 This overrides 'ambiwidth'. Example: >
7377 setcellwidths([[0xad, 0xad, 1],
7378 \ [0x2194, 0x2199, 2]])
7379
7380 < *E1109* *E1110* *E1111* *E1112* *E1113*
7381 The {list} argument is a list of lists with each three
7382 numbers. These three numbers are [low, high, width]. "low"
7383 and "high" can be the same, in which case this refers to one
7384 character. Otherwise it is the range of characters from "low"
7385 to "high" (inclusive). "width" is either 1 or 2, indicating
7386 the character width in screen cells.
7387 An error is given if the argument is invalid, also when a
7388 range overlaps with another.
7389 Only characters with value 0x100 and higher can be used.
7390
7391 If the new value causes 'fillchars' or 'listchars' to become
7392 invalid it is rejected and an error is given.
7393
7394 To clear the overrides pass an empty list: >
7395 setcellwidths([]);
7396 < You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
7397 the effect for known emoji characters.
7398
7399 setcharpos({expr}, {list}) *setcharpos()*
7400 Same as |setpos()| but uses the specified column number as the
7401 character index instead of the byte index in the line.
7402
7403 Example:
7404 With the text "여보세요" in line 8: >
7405 call setcharpos('.', [0, 8, 4, 0])
7406 < positions the cursor on the fourth character '요'. >
7407 call setpos('.', [0, 8, 4, 0])
7408 < positions the cursor on the second character '보'.
7409
7410 Can also be used as a |method|: >
7411 GetPosition()->setcharpos('.')
7412
7413 setcharsearch({dict}) *setcharsearch()*
7414 Set the current character search information to {dict},
7415 which contains one or more of the following entries:
7416
7417 char character which will be used for a subsequent
7418 |,| or |;| command; an empty string clears the
7419 character search
7420 forward direction of character search; 1 for forward,
7421 0 for backward
7422 until type of character search; 1 for a |t| or |T|
7423 character search, 0 for an |f| or |F|
7424 character search
7425
7426 This can be useful to save/restore a user's character search
7427 from a script: >
7428 :let prevsearch = getcharsearch()
7429 :" Perform a command which clobbers user's search
7430 :call setcharsearch(prevsearch)
7431 < Also see |getcharsearch()|.
7432
7433 Can also be used as a |method|: >
7434 SavedSearch()->setcharsearch()
7435
7436 setcmdpos({pos}) *setcmdpos()*
7437 Set the cursor position in the command line to byte position
7438 {pos}. The first position is 1.
7439 Use |getcmdpos()| to obtain the current position.
7440 Only works while editing the command line, thus you must use
7441 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
7442 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
7443 set after the command line is set to the expression. For
7444 |c_CTRL-R_=| it is set after evaluating the expression but
7445 before inserting the resulting text.
7446 When the number is too big the cursor is put at the end of the
7447 line. A number smaller than one has undefined results.
7448 Returns FALSE when successful, TRUE when not editing the
7449 command line.
7450
7451 Can also be used as a |method|: >
7452 GetPos()->setcmdpos()
7453
7454 setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
7455 setcursorcharpos({list})
7456 Same as |cursor()| but uses the specified column number as the
7457 character index instead of the byte index in the line.
7458
7459 Example:
7460 With the text "여보세요" in line 4: >
7461 call setcursorcharpos(4, 3)
7462 < positions the cursor on the third character '세'. >
7463 call cursor(4, 3)
7464 < positions the cursor on the first character '여'.
7465
7466 Can also be used as a |method|: >
7467 GetCursorPos()->setcursorcharpos()
7468
7469
7470 setenv({name}, {val}) *setenv()*
7471 Set environment variable {name} to {val}. Example: >
7472 call setenv('HOME', '/home/myhome')
7473
7474 < When {val} is |v:null| the environment variable is deleted.
7475 See also |expr-env|.
7476
7477 Can also be used as a |method|, the base is passed as the
7478 second argument: >
7479 GetPath()->setenv('PATH')
7480
7481 setfperm({fname}, {mode}) *setfperm()* *chmod*
7482 Set the file permissions for {fname} to {mode}.
7483 {mode} must be a string with 9 characters. It is of the form
7484 "rwxrwxrwx", where each group of "rwx" flags represent, in
7485 turn, the permissions of the owner of the file, the group the
7486 file belongs to, and other users. A '-' character means the
7487 permission is off, any other character means on. Multi-byte
7488 characters are not supported.
7489
7490 For example "rw-r-----" means read-write for the user,
7491 readable by the group, not accessible by others. "xx-x-----"
7492 would do the same thing.
7493
7494 Returns non-zero for success, zero for failure.
7495
7496 Can also be used as a |method|: >
7497 GetFilename()->setfperm(mode)
7498 <
7499 To read permissions see |getfperm()|.
7500
7501
7502 setline({lnum}, {text}) *setline()*
7503 Set line {lnum} of the current buffer to {text}. To insert
7504 lines use |append()|. To set lines in another buffer use
7505 |setbufline()|. Any text properties in {lnum} are cleared.
7506
7507 {lnum} is used like with |getline()|.
7508 When {lnum} is just below the last line the {text} will be
7509 added below the last line.
7510 {text} can be any type or a List of any type, each item is
7511 converted to a String.
7512
7513 If this succeeds, FALSE is returned. If this fails (most likely
7514 because {lnum} is invalid) TRUE is returned.
7515 In |Vim9| script an error is given if {lnum} is invalid.
7516
7517 Example: >
7518 :call setline(5, strftime("%c"))
7519
7520 < When {text} is a |List| then line {lnum} and following lines
7521 will be set to the items in the list. Example: >
7522 :call setline(5, ['aaa', 'bbb', 'ccc'])
7523 < This is equivalent to: >
7524 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
7525 : call setline(n, l)
7526 :endfor
7527
7528 < Note: The '[ and '] marks are not set.
7529
7530 Can also be used as a |method|, the base is passed as the
7531 second argument: >
7532 GetText()->setline(lnum)
7533
7534 setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
7535 Create or replace or add to the location list for window {nr}.
7536 {nr} can be the window number or the |window-ID|.
7537 When {nr} is zero the current window is used.
7538
7539 For a location list window, the displayed location list is
7540 modified. For an invalid window number {nr}, -1 is returned.
7541 Otherwise, same as |setqflist()|.
7542 Also see |location-list|.
7543
7544 For {action} see |setqflist-action|.
7545
7546 If the optional {what} dictionary argument is supplied, then
7547 only the items listed in {what} are set. Refer to |setqflist()|
7548 for the list of supported keys in {what}.
7549
7550 Can also be used as a |method|, the base is passed as the
7551 second argument: >
7552 GetLoclist()->setloclist(winnr)
7553
7554 setmatches({list} [, {win}]) *setmatches()*
7555 Restores a list of matches saved by |getmatches()| for the
7556 current window. Returns 0 if successful, otherwise -1. All
7557 current matches are cleared before the list is restored. See
7558 example for |getmatches()|.
7559 If {win} is specified, use the window with this number or
7560 window ID instead of the current window.
7561
7562 Can also be used as a |method|: >
7563 GetMatches()->setmatches()
7564 <
7565 *setpos()*
7566 setpos({expr}, {list})
7567 Set the position for String {expr}. Possible values:
7568 . the cursor
7569 'x mark x
7570
7571 {list} must be a |List| with four or five numbers:
7572 [bufnum, lnum, col, off]
7573 [bufnum, lnum, col, off, curswant]
7574
7575 "bufnum" is the buffer number. Zero can be used for the
7576 current buffer. When setting an uppercase mark "bufnum" is
7577 used for the mark position. For other marks it specifies the
7578 buffer to set the mark in. You can use the |bufnr()| function
7579 to turn a file name into a buffer number.
7580 For setting the cursor and the ' mark "bufnum" is ignored,
7581 since these are associated with a window, not a buffer.
7582 Does not change the jumplist.
7583
7584 "lnum" and "col" are the position in the buffer. The first
7585 column is 1. Use a zero "lnum" to delete a mark. If "col" is
7586 smaller than 1 then 1 is used. To use the character count
7587 instead of the byte count, use |setcharpos()|.
7588
7589 The "off" number is only used when 'virtualedit' is set. Then
7590 it is the offset in screen columns from the start of the
7591 character. E.g., a position within a <Tab> or after the last
7592 character.
7593
7594 The "curswant" number is only used when setting the cursor
7595 position. It sets the preferred column for when moving the
7596 cursor vertically. When the "curswant" number is missing the
7597 preferred column is not set. When it is present and setting a
7598 mark position it is not used.
7599
7600 Note that for '< and '> changing the line number may result in
7601 the marks to be effectively be swapped, so that '< is always
7602 before '>.
7603
7604 Returns 0 when the position could be set, -1 otherwise.
7605 An error message is given if {expr} is invalid.
7606
7607 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
7608
7609 This does not restore the preferred column for moving
7610 vertically; if you set the cursor position with this, |j| and
7611 |k| motions will jump to previous columns! Use |cursor()| to
7612 also set the preferred column. Also see the "curswant" key in
7613 |winrestview()|.
7614
7615 Can also be used as a |method|: >
7616 GetPosition()->setpos('.')
7617
7618 setqflist({list} [, {action} [, {what}]]) *setqflist()*
7619 Create or replace or add to the quickfix list.
7620
7621 If the optional {what} dictionary argument is supplied, then
7622 only the items listed in {what} are set. The first {list}
7623 argument is ignored. See below for the supported items in
7624 {what}.
7625 *setqflist-what*
7626 When {what} is not present, the items in {list} are used. Each
7627 item must be a dictionary. Non-dictionary items in {list} are
7628 ignored. Each dictionary item can contain the following
7629 entries:
7630
7631 bufnr buffer number; must be the number of a valid
7632 buffer
7633 filename name of a file; only used when "bufnr" is not
7634 present or it is invalid.
7635 module name of a module; if given it will be used in
7636 quickfix error window instead of the filename.
7637 lnum line number in the file
7638 pattern search pattern used to locate the error
7639 col column number
7640 vcol when non-zero: "col" is visual column
7641 when zero: "col" is byte index
7642 nr error number
7643 text description of the error
7644 type single-character error type, 'E', 'W', etc.
7645 valid recognized error message
7646
7647 The "col", "vcol", "nr", "type" and "text" entries are
7648 optional. Either "lnum" or "pattern" entry can be used to
7649 locate a matching error line.
7650 If the "filename" and "bufnr" entries are not present or
7651 neither the "lnum" or "pattern" entries are present, then the
7652 item will not be handled as an error line.
7653 If both "pattern" and "lnum" are present then "pattern" will
7654 be used.
7655 If the "valid" entry is not supplied, then the valid flag is
7656 set when "bufnr" is a valid buffer or "filename" exists.
7657 If you supply an empty {list}, the quickfix list will be
7658 cleared.
7659 Note that the list is not exactly the same as what
7660 |getqflist()| returns.
7661
7662 {action} values: *setqflist-action* *E927*
7663 'a' The items from {list} are added to the existing
7664 quickfix list. If there is no existing list, then a
7665 new list is created.
7666
7667 'r' The items from the current quickfix list are replaced
7668 with the items from {list}. This can also be used to
7669 clear the list: >
7670 :call setqflist([], 'r')
7671 <
7672 'f' All the quickfix lists in the quickfix stack are
7673 freed.
7674
7675 If {action} is not present or is set to ' ', then a new list
7676 is created. The new quickfix list is added after the current
7677 quickfix list in the stack and all the following lists are
7678 freed. To add a new quickfix list at the end of the stack,
7679 set "nr" in {what} to "$".
7680
7681 The following items can be specified in dictionary {what}:
7682 context quickfix list context. See |quickfix-context|
7683 efm errorformat to use when parsing text from
7684 "lines". If this is not present, then the
7685 'errorformat' option value is used.
7686 See |quickfix-parse|
7687 id quickfix list identifier |quickfix-ID|
7688 idx index of the current entry in the quickfix
7689 list specified by 'id' or 'nr'. If set to '$',
7690 then the last entry in the list is set as the
7691 current entry. See |quickfix-index|
7692 items list of quickfix entries. Same as the {list}
7693 argument.
7694 lines use 'errorformat' to parse a list of lines and
7695 add the resulting entries to the quickfix list
7696 {nr} or {id}. Only a |List| value is supported.
7697 See |quickfix-parse|
7698 nr list number in the quickfix stack; zero
7699 means the current quickfix list and "$" means
7700 the last quickfix list.
7701 quickfixtextfunc
7702 function to get the text to display in the
7703 quickfix window. The value can be the name of
7704 a function or a funcref or a lambda. Refer to
7705 |quickfix-window-function| for an explanation
7706 of how to write the function and an example.
7707 title quickfix list title text. See |quickfix-title|
7708 Unsupported keys in {what} are ignored.
7709 If the "nr" item is not present, then the current quickfix list
7710 is modified. When creating a new quickfix list, "nr" can be
7711 set to a value one greater than the quickfix stack size.
7712 When modifying a quickfix list, to guarantee that the correct
7713 list is modified, "id" should be used instead of "nr" to
7714 specify the list.
7715
7716 Examples (See also |setqflist-examples|): >
7717 :call setqflist([], 'r', {'title': 'My search'})
7718 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
7719 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
7720 <
7721 Returns zero for success, -1 for failure.
7722
7723 This function can be used to create a quickfix list
7724 independent of the 'errorformat' setting. Use a command like
7725 `:cc 1` to jump to the first position.
7726
7727 Can also be used as a |method|, the base is passed as the
7728 second argument: >
7729 GetErrorlist()->setqflist()
7730 <
7731 *setreg()*
7732 setreg({regname}, {value} [, {options}])
7733 Set the register {regname} to {value}.
7734 If {regname} is "" or "@", the unnamed register '"' is used.
7735 The {regname} argument is a string. In |Vim9-script|
7736 {regname} must be one character.
7737
7738 {value} may be any value returned by |getreg()| or
7739 |getreginfo()|, including a |List| or |Dict|.
7740 If {options} contains "a" or {regname} is upper case,
7741 then the value is appended.
7742
7743 {options} can also contain a register type specification:
7744 "c" or "v" |characterwise| mode
7745 "l" or "V" |linewise| mode
7746 "b" or "<CTRL-V>" |blockwise-visual| mode
7747 If a number immediately follows "b" or "<CTRL-V>" then this is
7748 used as the width of the selection - if it is not specified
7749 then the width of the block is set to the number of characters
7750 in the longest line (counting a <Tab> as 1 character).
7751
7752 If {options} contains no register settings, then the default
7753 is to use character mode unless {value} ends in a <NL> for
7754 string {value} and linewise mode for list {value}. Blockwise
7755 mode is never selected automatically.
7756 Returns zero for success, non-zero for failure.
7757
7758 *E883*
7759 Note: you may not use |List| containing more than one item to
7760 set search and expression registers. Lists containing no
7761 items act like empty strings.
7762
7763 Examples: >
7764 :call setreg(v:register, @*)
7765 :call setreg('*', @%, 'ac')
7766 :call setreg('a', "1\n2\n3", 'b5')
7767 :call setreg('"', { 'points_to': 'a'})
7768
7769 < This example shows using the functions to save and restore a
7770 register: >
7771 :let var_a = getreginfo()
7772 :call setreg('a', var_a)
7773 < or: >
7774 :let var_a = getreg('a', 1, 1)
7775 :let var_amode = getregtype('a')
7776 ....
7777 :call setreg('a', var_a, var_amode)
7778 < Note: you may not reliably restore register value
7779 without using the third argument to |getreg()| as without it
7780 newlines are represented as newlines AND Nul bytes are
7781 represented as newlines as well, see |NL-used-for-Nul|.
7782
7783 You can also change the type of a register by appending
7784 nothing: >
7785 :call setreg('a', '', 'al')
7786
7787 < Can also be used as a |method|, the base is passed as the
7788 second argument: >
7789 GetText()->setreg('a')
7790
7791 settabvar({tabnr}, {varname}, {val}) *settabvar()*
7792 Set tab-local variable {varname} to {val} in tab page {tabnr}.
7793 |t:var|
7794 The {varname} argument is a string.
7795 Note that autocommands are blocked, side effects may not be
7796 triggered, e.g. when setting 'filetype'.
7797 Note that the variable name without "t:" must be used.
7798 Tabs are numbered starting with one.
7799 This function is not available in the |sandbox|.
7800
7801 Can also be used as a |method|, the base is passed as the
7802 third argument: >
7803 GetValue()->settabvar(tab, name)
7804
7805 settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
7806 Set option or local variable {varname} in window {winnr} to
7807 {val}.
7808 Tabs are numbered starting with one. For the current tabpage
7809 use |setwinvar()|.
7810 {winnr} can be the window number or the |window-ID|.
7811 When {winnr} is zero the current window is used.
7812 Note that autocommands are blocked, side effects may not be
7813 triggered, e.g. when setting 'filetype' or 'syntax'.
7814 This also works for a global or local buffer option, but it
7815 doesn't work for a global or local buffer variable.
7816 For a local buffer option the global value is unchanged.
7817 Note that the variable name without "w:" must be used.
7818 Examples: >
7819 :call settabwinvar(1, 1, "&list", 0)
7820 :call settabwinvar(3, 2, "myvar", "foobar")
7821 < This function is not available in the |sandbox|.
7822
7823 Can also be used as a |method|, the base is passed as the
7824 fourth argument: >
7825 GetValue()->settabwinvar(tab, winnr, name)
7826
7827 settagstack({nr}, {dict} [, {action}]) *settagstack()*
7828 Modify the tag stack of the window {nr} using {dict}.
7829 {nr} can be the window number or the |window-ID|.
7830
7831 For a list of supported items in {dict}, refer to
7832 |gettagstack()|. "curidx" takes effect before changing the tag
7833 stack.
7834 *E962*
7835 How the tag stack is modified depends on the {action}
7836 argument:
7837 - If {action} is not present or is set to 'r', then the tag
7838 stack is replaced.
7839 - If {action} is set to 'a', then new entries from {dict} are
7840 pushed (added) onto the tag stack.
7841 - If {action} is set to 't', then all the entries from the
7842 current entry in the tag stack or "curidx" in {dict} are
7843 removed and then new entries are pushed to the stack.
7844
7845 The current index is set to one after the length of the tag
7846 stack after the modification.
7847
7848 Returns zero for success, -1 for failure.
7849
7850 Examples (for more examples see |tagstack-examples|):
7851 Empty the tag stack of window 3: >
7852 call settagstack(3, {'items' : []})
7853
7854 < Save and restore the tag stack: >
7855 let stack = gettagstack(1003)
7856 " do something else
7857 call settagstack(1003, stack)
7858 unlet stack
7859 <
7860 Can also be used as a |method|, the base is passed as the
7861 second argument: >
7862 GetStack()->settagstack(winnr)
7863
7864 setwinvar({winnr}, {varname}, {val}) *setwinvar()*
7865 Like |settabwinvar()| for the current tab page.
7866 Examples: >
7867 :call setwinvar(1, "&list", 0)
7868 :call setwinvar(2, "myvar", "foobar")
7869
7870 < Can also be used as a |method|, the base is passed as the
7871 third argument: >
7872 GetValue()->setwinvar(winnr, name)
7873
7874 sha256({string}) *sha256()*
7875 Returns a String with 64 hex characters, which is the SHA256
7876 checksum of {string}.
7877
7878 Can also be used as a |method|: >
7879 GetText()->sha256()
7880
7881 < {only available when compiled with the |+cryptv| feature}
7882
7883 shellescape({string} [, {special}]) *shellescape()*
7884 Escape {string} for use as a shell command argument.
7885 When the 'shell' contains powershell (MS-Windows) or pwsh
7886 (MS-Windows, Linux, and MacOS) then it will enclose {string}
7887 in single quotes and will double up all internal single
7888 quotes.
7889 On MS-Windows, when 'shellslash' is not set, it will enclose
7890 {string} in double quotes and double all double quotes within
7891 {string}.
7892 Otherwise it will enclose {string} in single quotes and
7893 replace all "'" with "'\''".
7894
7895 When the {special} argument is present and it's a non-zero
7896 Number or a non-empty String (|non-zero-arg|), then special
7897 items such as "!", "%", "#" and "<cword>" will be preceded by
7898 a backslash. This backslash will be removed again by the |:!|
7899 command.
7900
7901 The "!" character will be escaped (again with a |non-zero-arg|
7902 {special}) when 'shell' contains "csh" in the tail. That is
7903 because for csh and tcsh "!" is used for history replacement
7904 even when inside single quotes.
7905
7906 With a |non-zero-arg| {special} the <NL> character is also
7907 escaped. When 'shell' containing "csh" in the tail it's
7908 escaped a second time.
7909
7910 The "\" character will be escaped when 'shell' contains "fish"
7911 in the tail. That is because for fish "\" is used as an escape
7912 character inside single quotes.
7913
7914 Example of use with a |:!| command: >
7915 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
7916 < This results in a directory listing for the file under the
7917 cursor. Example of use with |system()|: >
7918 :call system("chmod +w -- " . shellescape(expand("%")))
7919 < See also |::S|.
7920
7921 Can also be used as a |method|: >
7922 GetCommand()->shellescape()
7923
7924 shiftwidth([{col}]) *shiftwidth()*
7925 Returns the effective value of 'shiftwidth'. This is the
7926 'shiftwidth' value unless it is zero, in which case it is the
7927 'tabstop' value. This function was introduced with patch
7928 7.3.694 in 2012, everybody should have it by now (however it
7929 did not allow for the optional {col} argument until 8.1.542).
7930
7931 When there is one argument {col} this is used as column number
7932 for which to return the 'shiftwidth' value. This matters for the
7933 'vartabstop' feature. If the 'vartabstop' setting is enabled and
7934 no {col} argument is given, column 1 will be assumed.
7935
7936 Can also be used as a |method|: >
7937 GetColumn()->shiftwidth()
7938
7939 sign_ functions are documented here: |sign-functions-details|
7940
7941
7942 simplify({filename}) *simplify()*
7943 Simplify the file name as much as possible without changing
7944 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
7945 Unix) are not resolved. If the first path component in
7946 {filename} designates the current directory, this will be
7947 valid for the result as well. A trailing path separator is
7948 not removed either. On Unix "//path" is unchanged, but
7949 "///path" is simplified to "/path" (this follows the Posix
7950 standard).
7951 Example: >
7952 simplify("./dir/.././/file/") == "./file/"
7953 < Note: The combination "dir/.." is only removed if "dir" is
7954 a searchable directory or does not exist. On Unix, it is also
7955 removed when "dir" is a symbolic link within the same
7956 directory. In order to resolve all the involved symbolic
7957 links before simplifying the path name, use |resolve()|.
7958
7959 Can also be used as a |method|: >
7960 GetName()->simplify()
7961
7962 sin({expr}) *sin()*
7963 Return the sine of {expr}, measured in radians, as a |Float|.
7964 {expr} must evaluate to a |Float| or a |Number|.
7965 Examples: >
7966 :echo sin(100)
7967 < -0.506366 >
7968 :echo sin(-4.01)
7969 < 0.763301
7970
7971 Can also be used as a |method|: >
7972 Compute()->sin()
7973 <
7974 {only available when compiled with the |+float| feature}
7975
7976
7977 sinh({expr}) *sinh()*
7978 Return the hyperbolic sine of {expr} as a |Float| in the range
7979 [-inf, inf].
7980 {expr} must evaluate to a |Float| or a |Number|.
7981 Examples: >
7982 :echo sinh(0.5)
7983 < 0.521095 >
7984 :echo sinh(-0.9)
7985 < -1.026517
7986
7987 Can also be used as a |method|: >
7988 Compute()->sinh()
7989 <
7990 {only available when compiled with the |+float| feature}
7991
7992
7993 slice({expr}, {start} [, {end}]) *slice()*
7994 Similar to using a |slice| "expr[start : end]", but "end" is
7995 used exclusive. And for a string the indexes are used as
7996 character indexes instead of byte indexes, like in
7997 |vim9script|. Also, composing characters are not counted.
7998 When {end} is omitted the slice continues to the last item.
7999 When {end} is -1 the last item is omitted.
8000
8001 Can also be used as a |method|: >
8002 GetList()->slice(offset)
8003
8004
8005 sort({list} [, {func} [, {dict}]]) *sort()* *E702*
8006 Sort the items in {list} in-place. Returns {list}.
8007
8008 If you want a list to remain unmodified make a copy first: >
8009 :let sortedlist = sort(copy(mylist))
8010
8011 < When {func} is omitted, is empty or zero, then sort() uses the
8012 string representation of each item to sort on. Numbers sort
8013 after Strings, |Lists| after Numbers. For sorting text in the
8014 current buffer use |:sort|.
8015
8016 When {func} is given and it is '1' or 'i' then case is
8017 ignored.
8018
8019 When {func} is given and it is 'l' then the current collation
8020 locale is used for ordering. Implementation details: strcoll()
8021 is used to compare strings. See |:language| check or set the
8022 collation locale. |v:collate| can also be used to check the
8023 current locale. Sorting using the locale typically ignores
8024 case. Example: >
8025 " ö is sorted similarly to o with English locale.
8026 :language collate en_US.UTF8
8027 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8028 < ['n', 'o', 'O', 'ö', 'p', 'z'] ~
8029 >
8030 " ö is sorted after z with Swedish locale.
8031 :language collate sv_SE.UTF8
8032 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8033 < ['n', 'o', 'O', 'p', 'z', 'ö'] ~
8034 This does not work properly on Mac.
8035
8036 When {func} is given and it is 'n' then all items will be
8037 sorted numerical (Implementation detail: this uses the
8038 strtod() function to parse numbers, Strings, Lists, Dicts and
8039 Funcrefs will be considered as being 0).
8040
8041 When {func} is given and it is 'N' then all items will be
8042 sorted numerical. This is like 'n' but a string containing
8043 digits will be used as the number they represent.
8044
8045 When {func} is given and it is 'f' then all items will be
8046 sorted numerical. All values must be a Number or a Float.
8047
8048 When {func} is a |Funcref| or a function name, this function
8049 is called to compare items. The function is invoked with two
8050 items as argument and must return zero if they are equal, 1 or
8051 bigger if the first one sorts after the second one, -1 or
8052 smaller if the first one sorts before the second one.
8053
8054 {dict} is for functions with the "dict" attribute. It will be
8055 used to set the local variable "self". |Dictionary-function|
8056
8057 The sort is stable, items which compare equal (as number or as
8058 string) will keep their relative position. E.g., when sorting
8059 on numbers, text strings will sort next to each other, in the
8060 same order as they were originally.
8061
8062 Can also be used as a |method|: >
8063 mylist->sort()
8064
8065 < Also see |uniq()|.
8066
8067 Example: >
8068 func MyCompare(i1, i2)
8069 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8070 endfunc
8071 eval mylist->sort("MyCompare")
8072 < A shorter compare version for this specific simple case, which
8073 ignores overflow: >
8074 func MyCompare(i1, i2)
8075 return a:i1 - a:i2
8076 endfunc
8077 < For a simple expression you can use a lambda: >
8078 eval mylist->sort({i1, i2 -> i1 - i2})
8079 <
8080 sound_clear() *sound_clear()*
8081 Stop playing all sounds.
8082
8083 On some Linux systems you may need the libcanberra-pulse
8084 package, otherwise sound may not stop.
8085
8086 {only available when compiled with the |+sound| feature}
8087
8088 *sound_playevent()*
8089 sound_playevent({name} [, {callback}])
8090 Play a sound identified by {name}. Which event names are
8091 supported depends on the system. Often the XDG sound names
8092 are used. On Ubuntu they may be found in
8093 /usr/share/sounds/freedesktop/stereo. Example: >
8094 call sound_playevent('bell')
8095 < On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
8096 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
8097 SystemStart, SystemWelcome, etc.
8098
8099 When {callback} is specified it is invoked when the sound is
8100 finished. The first argument is the sound ID, the second
8101 argument is the status:
8102 0 sound was played to the end
8103 1 sound was interrupted
8104 2 error occurred after sound started
8105 Example: >
8106 func Callback(id, status)
8107 echomsg "sound " .. a:id .. " finished with " .. a:status
8108 endfunc
8109 call sound_playevent('bell', 'Callback')
8110
8111 < MS-Windows: {callback} doesn't work for this function.
8112
8113 Returns the sound ID, which can be passed to `sound_stop()`.
8114 Returns zero if the sound could not be played.
8115
8116 Can also be used as a |method|: >
8117 GetSoundName()->sound_playevent()
8118
8119 < {only available when compiled with the |+sound| feature}
8120
8121 *sound_playfile()*
8122 sound_playfile({path} [, {callback}])
8123 Like `sound_playevent()` but play sound file {path}. {path}
8124 must be a full path. On Ubuntu you may find files to play
8125 with this command: >
8126 :!find /usr/share/sounds -type f | grep -v index.theme
8127
8128 < Can also be used as a |method|: >
8129 GetSoundPath()->sound_playfile()
8130
8131 < {only available when compiled with the |+sound| feature}
8132
8133
8134 sound_stop({id}) *sound_stop()*
8135 Stop playing sound {id}. {id} must be previously returned by
8136 `sound_playevent()` or `sound_playfile()`.
8137
8138 On some Linux systems you may need the libcanberra-pulse
8139 package, otherwise sound may not stop.
8140
8141 On MS-Windows, this does not work for event sound started by
8142 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
8143
8144 Can also be used as a |method|: >
8145 soundid->sound_stop()
8146
8147 < {only available when compiled with the |+sound| feature}
8148
8149 *soundfold()*
8150 soundfold({word})
8151 Return the sound-folded equivalent of {word}. Uses the first
8152 language in 'spelllang' for the current window that supports
8153 soundfolding. 'spell' must be set. When no sound folding is
8154 possible the {word} is returned unmodified.
8155 This can be used for making spelling suggestions. Note that
8156 the method can be quite slow.
8157
8158 Can also be used as a |method|: >
8159 GetWord()->soundfold()
8160 <
8161 *spellbadword()*
8162 spellbadword([{sentence}])
8163 Without argument: The result is the badly spelled word under
8164 or after the cursor. The cursor is moved to the start of the
8165 bad word. When no bad word is found in the cursor line the
8166 result is an empty string and the cursor doesn't move.
8167
8168 With argument: The result is the first word in {sentence} that
8169 is badly spelled. If there are no spelling mistakes the
8170 result is an empty string.
8171
8172 The return value is a list with two items:
8173 - The badly spelled word or an empty string.
8174 - The type of the spelling error:
8175 "bad" spelling mistake
8176 "rare" rare word
8177 "local" word only valid in another region
8178 "caps" word should start with Capital
8179 Example: >
8180 echo spellbadword("the quik brown fox")
8181 < ['quik', 'bad'] ~
8182
8183 The spelling information for the current window and the value
8184 of 'spelllang' are used.
8185
8186 Can also be used as a |method|: >
8187 GetText()->spellbadword()
8188 <
8189 *spellsuggest()*
8190 spellsuggest({word} [, {max} [, {capital}]])
8191 Return a |List| with spelling suggestions to replace {word}.
8192 When {max} is given up to this number of suggestions are
8193 returned. Otherwise up to 25 suggestions are returned.
8194
8195 When the {capital} argument is given and it's non-zero only
8196 suggestions with a leading capital will be given. Use this
8197 after a match with 'spellcapcheck'.
8198
8199 {word} can be a badly spelled word followed by other text.
8200 This allows for joining two words that were split. The
8201 suggestions also include the following text, thus you can
8202 replace a line.
8203
8204 {word} may also be a good word. Similar words will then be
8205 returned. {word} itself is not included in the suggestions,
8206 although it may appear capitalized.
8207
8208 The spelling information for the current window is used. The
8209 values of 'spelllang' and 'spellsuggest' are used.
8210
8211 Can also be used as a |method|: >
8212 GetWord()->spellsuggest()
8213
8214 split({string} [, {pattern} [, {keepempty}]]) *split()*
8215 Make a |List| out of {string}. When {pattern} is omitted or
8216 empty each white-separated sequence of characters becomes an
8217 item.
8218 Otherwise the string is split where {pattern} matches,
8219 removing the matched characters. 'ignorecase' is not used
8220 here, add \c to ignore case. |/\c|
8221 When the first or last item is empty it is omitted, unless the
8222 {keepempty} argument is given and it's non-zero.
8223 Other empty items are kept when {pattern} matches at least one
8224 character or when {keepempty} is non-zero.
8225 Example: >
8226 :let words = split(getline('.'), '\W\+')
8227 < To split a string in individual characters: >
8228 :for c in split(mystring, '\zs')
8229 < If you want to keep the separator you can also use '\zs' at
8230 the end of the pattern: >
8231 :echo split('abc:def:ghi', ':\zs')
8232 < ['abc:', 'def:', 'ghi'] ~
8233 Splitting a table where the first element can be empty: >
8234 :let items = split(line, ':', 1)
8235 < The opposite function is |join()|.
8236
8237 Can also be used as a |method|: >
8238 GetString()->split()
8239
8240 sqrt({expr}) *sqrt()*
8241 Return the non-negative square root of Float {expr} as a
8242 |Float|.
8243 {expr} must evaluate to a |Float| or a |Number|. When {expr}
8244 is negative the result is NaN (Not a Number).
8245 Examples: >
8246 :echo sqrt(100)
8247 < 10.0 >
8248 :echo sqrt(-4.01)
8249 < nan
8250 "nan" may be different, it depends on system libraries.
8251
8252 Can also be used as a |method|: >
8253 Compute()->sqrt()
8254 <
8255 {only available when compiled with the |+float| feature}
8256
8257
8258 srand([{expr}]) *srand()*
8259 Initialize seed used by |rand()|:
8260 - If {expr} is not given, seed values are initialized by
8261 reading from /dev/urandom, if possible, or using time(NULL)
8262 a.k.a. epoch time otherwise; this only has second accuracy.
8263 - If {expr} is given it must be a Number. It is used to
8264 initialize the seed values. This is useful for testing or
8265 when a predictable sequence is intended.
8266
8267 Examples: >
8268 :let seed = srand()
8269 :let seed = srand(userinput)
8270 :echo rand(seed)
8271
8272 state([{what}]) *state()*
8273 Return a string which contains characters indicating the
8274 current state. Mostly useful in callbacks that want to do
8275 work that may not always be safe. Roughly this works like:
8276 - callback uses state() to check if work is safe to do.
8277 Yes: then do it right away.
8278 No: add to work queue and add a |SafeState| and/or
8279 |SafeStateAgain| autocommand (|SafeState| triggers at
8280 toplevel, |SafeStateAgain| triggers after handling
8281 messages and callbacks).
8282 - When SafeState or SafeStateAgain is triggered and executes
8283 your autocommand, check with `state()` if the work can be
8284 done now, and if yes remove it from the queue and execute.
8285 Remove the autocommand if the queue is now empty.
8286 Also see |mode()|.
8287
8288 When {what} is given only characters in this string will be
8289 added. E.g, this checks if the screen has scrolled: >
8290 if state('s') == ''
8291 " screen has not scrolled
8292 <
8293 These characters indicate the state, generally indicating that
8294 something is busy:
8295 m halfway a mapping, :normal command, feedkeys() or
8296 stuffed command
8297 o operator pending, e.g. after |d|
8298 a Insert mode autocomplete active
8299 x executing an autocommand
8300 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
8301 ch_readraw() when reading json
8302 S not triggering SafeState or SafeStateAgain, e.g. after
8303 |f| or a count
8304 c callback invoked, including timer (repeats for
8305 recursiveness up to "ccc")
8306 s screen has scrolled for messages
8307
8308 str2float({string} [, {quoted}]) *str2float()*
8309 Convert String {string} to a Float. This mostly works the
8310 same as when using a floating point number in an expression,
8311 see |floating-point-format|. But it's a bit more permissive.
8312 E.g., "1e40" is accepted, while in an expression you need to
8313 write "1.0e40". The hexadecimal form "0x123" is also
8314 accepted, but not others, like binary or octal.
8315 When {quoted} is present and non-zero then embedded single
8316 quotes before the dot are ignored, thus "1'000.0" is a
8317 thousand.
8318 Text after the number is silently ignored.
8319 The decimal point is always '.', no matter what the locale is
8320 set to. A comma ends the number: "12,345.67" is converted to
8321 12.0. You can strip out thousands separators with
8322 |substitute()|: >
8323 let f = str2float(substitute(text, ',', '', 'g'))
8324 <
8325 Can also be used as a |method|: >
8326 let f = text->substitute(',', '', 'g')->str2float()
8327 <
8328 {only available when compiled with the |+float| feature}
8329
8330 str2list({string} [, {utf8}]) *str2list()*
8331 Return a list containing the number values which represent
8332 each character in String {string}. Examples: >
8333 str2list(" ") returns [32]
8334 str2list("ABC") returns [65, 66, 67]
8335 < |list2str()| does the opposite.
8336
8337 When {utf8} is omitted or zero, the current 'encoding' is used.
8338 When {utf8} is TRUE, always treat the String as UTF-8
8339 characters. With UTF-8 composing characters are handled
8340 properly: >
8341 str2list("á") returns [97, 769]
8342
8343 < Can also be used as a |method|: >
8344 GetString()->str2list()
8345
8346
8347 str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
8348 Convert string {string} to a number.
8349 {base} is the conversion base, it can be 2, 8, 10 or 16.
8350 When {quoted} is present and non-zero then embedded single
8351 quotes are ignored, thus "1'000'000" is a million.
8352
8353 When {base} is omitted base 10 is used. This also means that
8354 a leading zero doesn't cause octal conversion to be used, as
8355 with the default String to Number conversion. Example: >
8356 let nr = str2nr('0123')
8357 <
8358 When {base} is 16 a leading "0x" or "0X" is ignored. With a
8359 different base the result will be zero. Similarly, when
8360 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
8361 {base} is 2 a leading "0b" or "0B" is ignored.
8362 Text after the number is silently ignored.
8363
8364 Can also be used as a |method|: >
8365 GetText()->str2nr()
8366
8367
8368 strcharlen({string}) *strcharlen()*
8369 The result is a Number, which is the number of characters
8370 in String {string}. Composing characters are ignored.
8371 |strchars()| can count the number of characters, counting
8372 composing characters separately.
8373
8374 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8375
8376 Can also be used as a |method|: >
8377 GetText()->strcharlen()
8378
8379
8380 strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
8381 Like |strpart()| but using character index and length instead
8382 of byte index and length.
8383 When {skipcc} is omitted or zero, composing characters are
8384 counted separately.
8385 When {skipcc} set to 1, Composing characters are ignored,
8386 similar to |slice()|.
8387 When a character index is used where a character does not
8388 exist it is omitted and counted as one character. For
8389 example: >
8390 strcharpart('abc', -1, 2)
8391 < results in 'a'.
8392
8393 Can also be used as a |method|: >
8394 GetText()->strcharpart(5)
8395
8396
8397 strchars({string} [, {skipcc}]) *strchars()*
8398 The result is a Number, which is the number of characters
8399 in String {string}.
8400 When {skipcc} is omitted or zero, composing characters are
8401 counted separately.
8402 When {skipcc} set to 1, Composing characters are ignored.
8403 |strcharlen()| always does this.
8404
8405 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8406
8407 {skipcc} is only available after 7.4.755. For backward
8408 compatibility, you can define a wrapper function: >
8409 if has("patch-7.4.755")
8410 function s:strchars(str, skipcc)
8411 return strchars(a:str, a:skipcc)
8412 endfunction
8413 else
8414 function s:strchars(str, skipcc)
8415 if a:skipcc
8416 return strlen(substitute(a:str, ".", "x", "g"))
8417 else
8418 return strchars(a:str)
8419 endif
8420 endfunction
8421 endif
8422 <
8423 Can also be used as a |method|: >
8424 GetText()->strchars()
8425
8426 strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
8427 The result is a Number, which is the number of display cells
8428 String {string} occupies on the screen when it starts at {col}
8429 (first column is zero). When {col} is omitted zero is used.
8430 Otherwise it is the screen column where to start. This
8431 matters for Tab characters.
8432 The option settings of the current window are used. This
8433 matters for anything that's displayed differently, such as
8434 'tabstop' and 'display'.
8435 When {string} contains characters with East Asian Width Class
8436 Ambiguous, this function's return value depends on 'ambiwidth'.
8437 Also see |strlen()|, |strwidth()| and |strchars()|.
8438
8439 Can also be used as a |method|: >
8440 GetText()->strdisplaywidth()
8441
8442 strftime({format} [, {time}]) *strftime()*
8443 The result is a String, which is a formatted date and time, as
8444 specified by the {format} string. The given {time} is used,
8445 or the current time if no time is given. The accepted
8446 {format} depends on your system, thus this is not portable!
8447 See the manual page of the C function strftime() for the
8448 format. The maximum length of the result is 80 characters.
8449 See also |localtime()|, |getftime()| and |strptime()|.
8450 The language can be changed with the |:language| command.
8451 Examples: >
8452 :echo strftime("%c") Sun Apr 27 11:49:23 1997
8453 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
8454 :echo strftime("%y%m%d %T") 970427 11:53:55
8455 :echo strftime("%H:%M") 11:55
8456 :echo strftime("%c", getftime("file.c"))
8457 Show mod time of file.c.
8458 < Not available on all systems. To check use: >
8459 :if exists("*strftime")
8460
8461 < Can also be used as a |method|: >
8462 GetFormat()->strftime()
8463
8464 strgetchar({str}, {index}) *strgetchar()*
8465 Get character {index} from {str}. This uses a character
8466 index, not a byte index. Composing characters are considered
8467 separate characters here.
8468 Also see |strcharpart()| and |strchars()|.
8469
8470 Can also be used as a |method|: >
8471 GetText()->strgetchar(5)
8472
8473 stridx({haystack}, {needle} [, {start}]) *stridx()*
8474 The result is a Number, which gives the byte index in
8475 {haystack} of the first occurrence of the String {needle}.
8476 If {start} is specified, the search starts at index {start}.
8477 This can be used to find a second match: >
8478 :let colon1 = stridx(line, ":")
8479 :let colon2 = stridx(line, ":", colon1 + 1)
8480 < The search is done case-sensitive.
8481 For pattern searches use |match()|.
8482 -1 is returned if the {needle} does not occur in {haystack}.
8483 See also |strridx()|.
8484 Examples: >
8485 :echo stridx("An Example", "Example") 3
8486 :echo stridx("Starting point", "Start") 0
8487 :echo stridx("Starting point", "start") -1
8488 < *strstr()* *strchr()*
8489 stridx() works similar to the C function strstr(). When used
8490 with a single character it works similar to strchr().
8491
8492 Can also be used as a |method|: >
8493 GetHaystack()->stridx(needle)
8494 <
8495 *string()*
8496 string({expr}) Return {expr} converted to a String. If {expr} is a Number,
8497 Float, String, Blob or a composition of them, then the result
8498 can be parsed back with |eval()|.
8499 {expr} type result ~
8500 String 'string' (single quotes are doubled)
8501 Number 123
8502 Float 123.123456 or 1.123456e8
8503 Funcref function('name')
8504 Blob 0z00112233.44556677.8899
8505 List [item, item]
8506 Dictionary {key: value, key: value}
8507
8508 When a |List| or |Dictionary| has a recursive reference it is
8509 replaced by "[...]" or "{...}". Using eval() on the result
8510 will then fail.
8511
8512 Can also be used as a |method|: >
8513 mylist->string()
8514
8515 < Also see |strtrans()|.
8516
8517
8518 strlen({string}) *strlen()*
8519 The result is a Number, which is the length of the String
8520 {string} in bytes.
8521 If the argument is a Number it is first converted to a String.
8522 For other types an error is given.
8523 If you want to count the number of multibyte characters use
8524 |strchars()|.
8525 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
8526
8527 Can also be used as a |method|: >
8528 GetString()->strlen()
8529
8530 strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
8531 The result is a String, which is part of {src}, starting from
8532 byte {start}, with the byte length {len}.
8533 When {chars} is present and TRUE then {len} is the number of
8534 characters positions (composing characters are not counted
8535 separately, thus "1" means one base character and any
8536 following composing characters).
8537 To count {start} as characters instead of bytes use
8538 |strcharpart()|.
8539
8540 When bytes are selected which do not exist, this doesn't
8541 result in an error, the bytes are simply omitted.
8542 If {len} is missing, the copy continues from {start} till the
8543 end of the {src}. >
8544 strpart("abcdefg", 3, 2) == "de"
8545 strpart("abcdefg", -2, 4) == "ab"
8546 strpart("abcdefg", 5, 4) == "fg"
8547 strpart("abcdefg", 3) == "defg"
8548
8549 < Note: To get the first character, {start} must be 0. For
8550 example, to get the character under the cursor: >
8551 strpart(getline("."), col(".") - 1, 1, v:true)
8552 <
8553 Can also be used as a |method|: >
8554 GetText()->strpart(5)
8555
8556 strptime({format}, {timestring}) *strptime()*
8557 The result is a Number, which is a unix timestamp representing
8558 the date and time in {timestring}, which is expected to match
8559 the format specified in {format}.
8560
8561 The accepted {format} depends on your system, thus this is not
8562 portable! See the manual page of the C function strptime()
8563 for the format. Especially avoid "%c". The value of $TZ also
8564 matters.
8565
8566 If the {timestring} cannot be parsed with {format} zero is
8567 returned. If you do not know the format of {timestring} you
8568 can try different {format} values until you get a non-zero
8569 result.
8570
8571 See also |strftime()|.
8572 Examples: >
8573 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
8574 < 862156163 >
8575 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
8576 < Sun Apr 27 11:53:55 1997 >
8577 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
8578 < Sun Apr 27 12:53:55 1997
8579
8580 Can also be used as a |method|: >
8581 GetFormat()->strptime(timestring)
8582 <
8583 Not available on all systems. To check use: >
8584 :if exists("*strptime")
8585
8586 strridx({haystack}, {needle} [, {start}]) *strridx()*
8587 The result is a Number, which gives the byte index in
8588 {haystack} of the last occurrence of the String {needle}.
8589 When {start} is specified, matches beyond this index are
8590 ignored. This can be used to find a match before a previous
8591 match: >
8592 :let lastcomma = strridx(line, ",")
8593 :let comma2 = strridx(line, ",", lastcomma - 1)
8594 < The search is done case-sensitive.
8595 For pattern searches use |match()|.
8596 -1 is returned if the {needle} does not occur in {haystack}.
8597 If the {needle} is empty the length of {haystack} is returned.
8598 See also |stridx()|. Examples: >
8599 :echo strridx("an angry armadillo", "an") 3
8600 < *strrchr()*
8601 When used with a single character it works similar to the C
8602 function strrchr().
8603
8604 Can also be used as a |method|: >
8605 GetHaystack()->strridx(needle)
8606
8607 strtrans({string}) *strtrans()*
8608 The result is a String, which is {string} with all unprintable
8609 characters translated into printable characters |'isprint'|.
8610 Like they are shown in a window. Example: >
8611 echo strtrans(@a)
8612 < This displays a newline in register a as "^@" instead of
8613 starting a new line.
8614
8615 Can also be used as a |method|: >
8616 GetString()->strtrans()
8617
8618 strwidth({string}) *strwidth()*
8619 The result is a Number, which is the number of display cells
8620 String {string} occupies. A Tab character is counted as one
8621 cell, alternatively use |strdisplaywidth()|.
8622 When {string} contains characters with East Asian Width Class
8623 Ambiguous, this function's return value depends on 'ambiwidth'.
8624 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
8625
8626 Can also be used as a |method|: >
8627 GetString()->strwidth()
8628
8629 submatch({nr} [, {list}]) *submatch()* *E935*
8630 Only for an expression in a |:substitute| command or
8631 substitute() function.
8632 Returns the {nr}'th submatch of the matched text. When {nr}
8633 is 0 the whole matched text is returned.
8634 Note that a NL in the string can stand for a line break of a
8635 multi-line match or a NUL character in the text.
8636 Also see |sub-replace-expression|.
8637
8638 If {list} is present and non-zero then submatch() returns
8639 a list of strings, similar to |getline()| with two arguments.
8640 NL characters in the text represent NUL characters in the
8641 text.
8642 Only returns more than one item for |:substitute|, inside
8643 |substitute()| this list will always contain one or zero
8644 items, since there are no real line breaks.
8645
8646 When substitute() is used recursively only the submatches in
8647 the current (deepest) call can be obtained.
8648
8649 Examples: >
8650 :s/\d\+/\=submatch(0) + 1/
8651 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
8652 < This finds the first number in the line and adds one to it.
8653 A line break is included as a newline character.
8654
8655 Can also be used as a |method|: >
8656 GetNr()->submatch()
8657
8658 substitute({string}, {pat}, {sub}, {flags}) *substitute()*
8659 The result is a String, which is a copy of {string}, in which
8660 the first match of {pat} is replaced with {sub}.
8661 When {flags} is "g", all matches of {pat} in {string} are
8662 replaced. Otherwise {flags} should be "".
8663
8664 This works like the ":substitute" command (without any flags).
8665 But the matching with {pat} is always done like the 'magic'
8666 option is set and 'cpoptions' is empty (to make scripts
8667 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
8668 if you want to ignore or match case and ignore 'ignorecase'.
8669 'smartcase' is not used. See |string-match| for how {pat} is
8670 used.
8671
8672 A "~" in {sub} is not replaced with the previous {sub}.
8673 Note that some codes in {sub} have a special meaning
8674 |sub-replace-special|. For example, to replace something with
8675 "\n" (two characters), use "\\\\n" or '\\n'.
8676
8677 When {pat} does not match in {string}, {string} is returned
8678 unmodified.
8679
8680 Example: >
8681 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
8682 < This removes the last component of the 'path' option. >
8683 :echo substitute("testing", ".*", "\\U\\0", "")
8684 < results in "TESTING".
8685
8686 When {sub} starts with "\=", the remainder is interpreted as
8687 an expression. See |sub-replace-expression|. Example: >
8688 :echo substitute(s, '%\(\x\x\)',
8689 \ '\=nr2char("0x" . submatch(1))', 'g')
8690
8691 < When {sub} is a Funcref that function is called, with one
8692 optional argument. Example: >
8693 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
8694 < The optional argument is a list which contains the whole
8695 matched string and up to nine submatches, like what
8696 |submatch()| returns. Example: >
8697 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g')
8698
8699 < Can also be used as a |method|: >
8700 GetString()->substitute(pat, sub, flags)
8701
8702 swapinfo({fname}) *swapinfo()*
8703 The result is a dictionary, which holds information about the
8704 swapfile {fname}. The available fields are:
8705 version Vim version
8706 user user name
8707 host host name
8708 fname original file name
8709 pid PID of the Vim process that created the swap
8710 file
8711 mtime last modification time in seconds
8712 inode Optional: INODE number of the file
8713 dirty 1 if file was modified, 0 if not
8714 Note that "user" and "host" are truncated to at most 39 bytes.
8715 In case of failure an "error" item is added with the reason:
8716 Cannot open file: file not found or in accessible
8717 Cannot read file: cannot read first block
8718 Not a swap file: does not contain correct block ID
8719 Magic number mismatch: Info in first block is invalid
8720
8721 Can also be used as a |method|: >
8722 GetFilename()->swapinfo()
8723
8724 swapname({buf}) *swapname()*
8725 The result is the swap file path of the buffer {expr}.
8726 For the use of {buf}, see |bufname()| above.
8727 If buffer {buf} is the current buffer, the result is equal to
8728 |:swapname| (unless there is no swap file).
8729 If buffer {buf} has no swap file, returns an empty string.
8730
8731 Can also be used as a |method|: >
8732 GetBufname()->swapname()
8733
8734 synID({lnum}, {col}, {trans}) *synID()*
8735 The result is a Number, which is the syntax ID at the position
8736 {lnum} and {col} in the current window.
8737 The syntax ID can be used with |synIDattr()| and
8738 |synIDtrans()| to obtain syntax information about text.
8739
8740 {col} is 1 for the leftmost column, {lnum} is 1 for the first
8741 line. 'synmaxcol' applies, in a longer line zero is returned.
8742 Note that when the position is after the last character,
8743 that's where the cursor can be in Insert mode, synID() returns
8744 zero. {lnum} is used like with |getline()|.
8745
8746 When {trans} is |TRUE|, transparent items are reduced to the
8747 item that they reveal. This is useful when wanting to know
8748 the effective color. When {trans} is |FALSE|, the transparent
8749 item is returned. This is useful when wanting to know which
8750 syntax item is effective (e.g. inside parens).
8751 Warning: This function can be very slow. Best speed is
8752 obtained by going through the file in forward direction.
8753
8754 Example (echoes the name of the syntax item under the cursor): >
8755 :echo synIDattr(synID(line("."), col("."), 1), "name")
8756 <
8757
8758 synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
8759 The result is a String, which is the {what} attribute of
8760 syntax ID {synID}. This can be used to obtain information
8761 about a syntax item.
8762 {mode} can be "gui", "cterm" or "term", to get the attributes
8763 for that mode. When {mode} is omitted, or an invalid value is
8764 used, the attributes for the currently active highlighting are
8765 used (GUI, cterm or term).
8766 Use synIDtrans() to follow linked highlight groups.
8767 {what} result
8768 "name" the name of the syntax item
8769 "fg" foreground color (GUI: color name used to set
8770 the color, cterm: color number as a string,
8771 term: empty string)
8772 "bg" background color (as with "fg")
8773 "font" font name (only available in the GUI)
8774 |highlight-font|
8775 "sp" special color for the GUI (as with "fg")
8776 |highlight-guisp|
8777 "ul" underline color for cterm: number as a string
8778 "fg#" like "fg", but for the GUI and the GUI is
8779 running the name in "#RRGGBB" form
8780 "bg#" like "fg#" for "bg"
8781 "sp#" like "fg#" for "sp"
8782 "bold" "1" if bold
8783 "italic" "1" if italic
8784 "reverse" "1" if reverse
8785 "inverse" "1" if inverse (= reverse)
8786 "standout" "1" if standout
8787 "underline" "1" if underlined
8788 "undercurl" "1" if undercurled
8789 "strike" "1" if strikethrough
8790
8791 Example (echoes the color of the syntax item under the
8792 cursor): >
8793 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
8794 <
8795 Can also be used as a |method|: >
8796 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
8797
8798
8799 synIDtrans({synID}) *synIDtrans()*
8800 The result is a Number, which is the translated syntax ID of
8801 {synID}. This is the syntax group ID of what is being used to
8802 highlight the character. Highlight links given with
8803 ":highlight link" are followed.
8804
8805 Can also be used as a |method|: >
8806 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
8807
8808 synconcealed({lnum}, {col}) *synconcealed()*
8809 The result is a |List| with currently three items:
8810 1. The first item in the list is 0 if the character at the
8811 position {lnum} and {col} is not part of a concealable
8812 region, 1 if it is. {lnum} is used like with |getline()|.
8813 2. The second item in the list is a string. If the first item
8814 is 1, the second item contains the text which will be
8815 displayed in place of the concealed text, depending on the
8816 current setting of 'conceallevel' and 'listchars'.
8817 3. The third and final item in the list is a number
8818 representing the specific syntax region matched in the
8819 line. When the character is not concealed the value is
8820 zero. This allows detection of the beginning of a new
8821 concealable region if there are two consecutive regions
8822 with the same replacement character. For an example, if
8823 the text is "123456" and both "23" and "45" are concealed
8824 and replaced by the character "X", then:
8825 call returns ~
8826 synconcealed(lnum, 1) [0, '', 0]
8827 synconcealed(lnum, 2) [1, 'X', 1]
8828 synconcealed(lnum, 3) [1, 'X', 1]
8829 synconcealed(lnum, 4) [1, 'X', 2]
8830 synconcealed(lnum, 5) [1, 'X', 2]
8831 synconcealed(lnum, 6) [0, '', 0]
8832
8833
8834 synstack({lnum}, {col}) *synstack()*
8835 Return a |List|, which is the stack of syntax items at the
8836 position {lnum} and {col} in the current window. {lnum} is
8837 used like with |getline()|. Each item in the List is an ID
8838 like what |synID()| returns.
8839 The first item in the List is the outer region, following are
8840 items contained in that one. The last one is what |synID()|
8841 returns, unless not the whole item is highlighted or it is a
8842 transparent item.
8843 This function is useful for debugging a syntax file.
8844 Example that shows the syntax stack under the cursor: >
8845 for id in synstack(line("."), col("."))
8846 echo synIDattr(id, "name")
8847 endfor
8848 < When the position specified with {lnum} and {col} is invalid
8849 nothing is returned. The position just after the last
8850 character in a line and the first column in an empty line are
8851 valid positions.
8852
8853 system({expr} [, {input}]) *system()* *E677*
8854 Get the output of the shell command {expr} as a |String|. See
8855 |systemlist()| to get the output as a |List|.
8856
8857 When {input} is given and is a |String| this string is written
8858 to a file and passed as stdin to the command. The string is
8859 written as-is, you need to take care of using the correct line
8860 separators yourself.
8861 If {input} is given and is a |List| it is written to the file
8862 in a way |writefile()| does with {binary} set to "b" (i.e.
8863 with a newline between each list item with newlines inside
8864 list items converted to NULs).
8865 When {input} is given and is a number that is a valid id for
8866 an existing buffer then the content of the buffer is written
8867 to the file line by line, each line terminated by a NL and
8868 NULs characters where the text has a NL.
8869
8870 Pipes are not used, the 'shelltemp' option is not used.
8871
8872 When prepended by |:silent| the terminal will not be set to
8873 cooked mode. This is meant to be used for commands that do
8874 not need the user to type. It avoids stray characters showing
8875 up on the screen which require |CTRL-L| to remove. >
8876 :silent let f = system('ls *.vim')
8877 <
8878 Note: Use |shellescape()| or |::S| with |expand()| or
8879 |fnamemodify()| to escape special characters in a command
8880 argument. Newlines in {expr} may cause the command to fail.
8881 The characters in 'shellquote' and 'shellxquote' may also
8882 cause trouble.
8883 This is not to be used for interactive commands.
8884
8885 The result is a String. Example: >
8886 :let files = system("ls " . shellescape(expand('%:h')))
8887 :let files = system('ls ' . expand('%:h:S'))
8888
8889 < To make the result more system-independent, the shell output
8890 is filtered to replace <CR> with <NL> for Macintosh, and
8891 <CR><NL> with <NL> for DOS-like systems.
8892 To avoid the string being truncated at a NUL, all NUL
8893 characters are replaced with SOH (0x01).
8894
8895 The command executed is constructed using several options:
8896 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
8897 ({tmp} is an automatically generated file name).
8898 For Unix, braces are put around {expr} to allow for
8899 concatenated commands.
8900
8901 The command will be executed in "cooked" mode, so that a
8902 CTRL-C will interrupt the command (on Unix at least).
8903
8904 The resulting error code can be found in |v:shell_error|.
8905 This function will fail in |restricted-mode|.
8906
8907 Note that any wrong value in the options mentioned above may
8908 make the function fail. It has also been reported to fail
8909 when using a security agent application.
8910 Unlike ":!cmd" there is no automatic check for changed files.
8911 Use |:checktime| to force a check.
8912
8913 Can also be used as a |method|: >
8914 :echo GetCmd()->system()
8915
8916
8917 systemlist({expr} [, {input}]) *systemlist()*
8918 Same as |system()|, but returns a |List| with lines (parts of
8919 output separated by NL) with NULs transformed into NLs. Output
8920 is the same as |readfile()| will output with {binary} argument
8921 set to "b", except that there is no extra empty item when the
8922 result ends in a NL.
8923 Note that on MS-Windows you may get trailing CR characters.
8924
8925 To see the difference between "echo hello" and "echo -n hello"
8926 use |system()| and |split()|: >
8927 echo system('echo hello')->split('\n', 1)
8928 <
8929 Returns an empty string on error.
8930
8931 Can also be used as a |method|: >
8932 :echo GetCmd()->systemlist()
8933
8934
8935 tabpagebuflist([{arg}]) *tabpagebuflist()*
8936 The result is a |List|, where each item is the number of the
8937 buffer associated with each window in the current tab page.
8938 {arg} specifies the number of the tab page to be used. When
8939 omitted the current tab page is used.
8940 When {arg} is invalid the number zero is returned.
8941 To get a list of all buffers in all tabs use this: >
8942 let buflist = []
8943 for i in range(tabpagenr('$'))
8944 call extend(buflist, tabpagebuflist(i + 1))
8945 endfor
8946 < Note that a buffer may appear in more than one window.
8947
8948 Can also be used as a |method|: >
8949 GetTabpage()->tabpagebuflist()
8950
8951 tabpagenr([{arg}]) *tabpagenr()*
8952 The result is a Number, which is the number of the current
8953 tab page. The first tab page has number 1.
8954
8955 The optional argument {arg} supports the following values:
8956 $ the number of the last tab page (the tab page
8957 count).
8958 # the number of the last accessed tab page
8959 (where |g<Tab>| goes to). if there is no
8960 previous tab page 0 is returned.
8961 The number can be used with the |:tab| command.
8962
8963
8964 tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
8965 Like |winnr()| but for tab page {tabarg}.
8966 {tabarg} specifies the number of tab page to be used.
8967 {arg} is used like with |winnr()|:
8968 - When omitted the current window number is returned. This is
8969 the window which will be used when going to this tab page.
8970 - When "$" the number of windows is returned.
8971 - When "#" the previous window nr is returned.
8972 Useful examples: >
8973 tabpagewinnr(1) " current window of tab page 1
8974 tabpagewinnr(4, '$') " number of windows in tab page 4
8975 < When {tabarg} is invalid zero is returned.
8976
8977 Can also be used as a |method|: >
8978 GetTabpage()->tabpagewinnr()
8979 <
8980 *tagfiles()*
8981 tagfiles() Returns a |List| with the file names used to search for tags
8982 for the current buffer. This is the 'tags' option expanded.
8983
8984
8985 taglist({expr} [, {filename}]) *taglist()*
8986 Returns a |List| of tags matching the regular expression {expr}.
8987
8988 If {filename} is passed it is used to prioritize the results
8989 in the same way that |:tselect| does. See |tag-priority|.
8990 {filename} should be the full path of the file.
8991
8992 Each list item is a dictionary with at least the following
8993 entries:
8994 name Name of the tag.
8995 filename Name of the file where the tag is
8996 defined. It is either relative to the
8997 current directory or a full path.
8998 cmd Ex command used to locate the tag in
8999 the file.
9000 kind Type of the tag. The value for this
9001 entry depends on the language specific
9002 kind values. Only available when
9003 using a tags file generated by
9004 Exuberant ctags or hdrtag.
9005 static A file specific tag. Refer to
9006 |static-tag| for more information.
9007 More entries may be present, depending on the content of the
9008 tags file: access, implementation, inherits and signature.
9009 Refer to the ctags documentation for information about these
9010 fields. For C code the fields "struct", "class" and "enum"
9011 may appear, they give the name of the entity the tag is
9012 contained in.
9013
9014 The ex-command "cmd" can be either an ex search pattern, a
9015 line number or a line number followed by a byte number.
9016
9017 If there are no matching tags, then an empty list is returned.
9018
9019 To get an exact tag match, the anchors '^' and '$' should be
9020 used in {expr}. This also make the function work faster.
9021 Refer to |tag-regexp| for more information about the tag
9022 search regular expression pattern.
9023
9024 Refer to |'tags'| for information about how the tags file is
9025 located by Vim. Refer to |tags-file-format| for the format of
9026 the tags file generated by the different ctags tools.
9027
9028 Can also be used as a |method|: >
9029 GetTagpattern()->taglist()
9030
9031 tan({expr}) *tan()*
9032 Return the tangent of {expr}, measured in radians, as a |Float|
9033 in the range [-inf, inf].
9034 {expr} must evaluate to a |Float| or a |Number|.
9035 Examples: >
9036 :echo tan(10)
9037 < 0.648361 >
9038 :echo tan(-4.01)
9039 < -1.181502
9040
9041 Can also be used as a |method|: >
9042 Compute()->tan()
9043 <
9044 {only available when compiled with the |+float| feature}
9045
9046
9047 tanh({expr}) *tanh()*
9048 Return the hyperbolic tangent of {expr} as a |Float| in the
9049 range [-1, 1].
9050 {expr} must evaluate to a |Float| or a |Number|.
9051 Examples: >
9052 :echo tanh(0.5)
9053 < 0.462117 >
9054 :echo tanh(-1)
9055 < -0.761594
9056
9057 Can also be used as a |method|: >
9058 Compute()->tanh()
9059 <
9060 {only available when compiled with the |+float| feature}
9061
9062
9063 tempname() *tempname()* *temp-file-name*
9064 The result is a String, which is the name of a file that
9065 doesn't exist. It can be used for a temporary file. The name
9066 is different for at least 26 consecutive calls. Example: >
9067 :let tmpfile = tempname()
9068 :exe "redir > " . tmpfile
9069 < For Unix, the file will be in a private directory |tempfile|.
9070 For MS-Windows forward slashes are used when the 'shellslash'
9071 option is set, or when 'shellcmdflag' starts with '-' and
9072 'shell' does not contain powershell or pwsh.
9073
9074
9075 term_ functions are documented here: |terminal-function-details|
9076
9077
9078 terminalprops() *terminalprops()*
9079 Returns a |Dictionary| with properties of the terminal that Vim
9080 detected from the response to |t_RV| request. See
9081 |v:termresponse| for the response itself. If |v:termresponse|
9082 is empty most values here will be 'u' for unknown.
9083 cursor_style whether sending |t_RS| works **
9084 cursor_blink_mode whether sending |t_RC| works **
9085 underline_rgb whether |t_8u| works **
9086 mouse mouse type supported
9087
9088 ** value 'u' for unknown, 'y' for yes, 'n' for no
9089
9090 If the |+termresponse| feature is missing then the result is
9091 an empty dictionary.
9092
9093 If "cursor_style" is 'y' then |t_RS| will be sent to request the
9094 current cursor style.
9095 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
9096 request the cursor blink status.
9097 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
9098 is not empty, Vim will detect the working of sending |t_RS|
9099 and |t_RC| on startup.
9100
9101 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
9102 This avoids sending it to xterm, which would clear the colors.
9103
9104 For "mouse" the value 'u' is unknown
9105
9106 Also see:
9107 - 'ambiwidth' - detected by using |t_u7|.
9108 - |v:termstyleresp| and |v:termblinkresp| for the response to
9109 |t_RS| and |t_RC|.
9110
9111
9112 test_ functions are documented here: |test-functions-details|
9113
9114
9115 *timer_info()*
9116 timer_info([{id}])
9117 Return a list with information about timers.
9118 When {id} is given only information about this timer is
9119 returned. When timer {id} does not exist an empty list is
9120 returned.
9121 When {id} is omitted information about all timers is returned.
9122
9123 For each timer the information is stored in a |Dictionary| with
9124 these items:
9125 "id" the timer ID
9126 "time" time the timer was started with
9127 "remaining" time until the timer fires
9128 "repeat" number of times the timer will still fire;
9129 -1 means forever
9130 "callback" the callback
9131 "paused" 1 if the timer is paused, 0 otherwise
9132
9133 Can also be used as a |method|: >
9134 GetTimer()->timer_info()
9135
9136 < {only available when compiled with the |+timers| feature}
9137
9138 timer_pause({timer}, {paused}) *timer_pause()*
9139 Pause or unpause a timer. A paused timer does not invoke its
9140 callback when its time expires. Unpausing a timer may cause
9141 the callback to be invoked almost immediately if enough time
9142 has passed.
9143
9144 Pausing a timer is useful to avoid the callback to be called
9145 for a short time.
9146
9147 If {paused} evaluates to a non-zero Number or a non-empty
9148 String, then the timer is paused, otherwise it is unpaused.
9149 See |non-zero-arg|.
9150
9151 Can also be used as a |method|: >
9152 GetTimer()->timer_pause(1)
9153
9154 < {only available when compiled with the |+timers| feature}
9155
9156 *timer_start()* *timer* *timers*
9157 timer_start({time}, {callback} [, {options}])
9158 Create a timer and return the timer ID.
9159
9160 {time} is the waiting time in milliseconds. This is the
9161 minimum time before invoking the callback. When the system is
9162 busy or Vim is not waiting for input the time will be longer.
9163
9164 {callback} is the function to call. It can be the name of a
9165 function or a |Funcref|. It is called with one argument, which
9166 is the timer ID. The callback is only invoked when Vim is
9167 waiting for input.
9168 If you want to show a message look at |popup_notification()|
9169 to avoid interfering with what the user is doing.
9170
9171 {options} is a dictionary. Supported entries:
9172 "repeat" Number of times to repeat calling the
9173 callback. -1 means forever. When not present
9174 the callback will be called once.
9175 If the timer causes an error three times in a
9176 row the repeat is cancelled. This avoids that
9177 Vim becomes unusable because of all the error
9178 messages.
9179
9180 Example: >
9181 func MyHandler(timer)
9182 echo 'Handler called'
9183 endfunc
9184 let timer = timer_start(500, 'MyHandler',
9185 \ {'repeat': 3})
9186 < This will invoke MyHandler() three times at 500 msec
9187 intervals.
9188
9189 Can also be used as a |method|: >
9190 GetMsec()->timer_start(callback)
9191
9192 < Not available in the |sandbox|.
9193 {only available when compiled with the |+timers| feature}
9194
9195 timer_stop({timer}) *timer_stop()*
9196 Stop a timer. The timer callback will no longer be invoked.
9197 {timer} is an ID returned by timer_start(), thus it must be a
9198 Number. If {timer} does not exist there is no error.
9199
9200 Can also be used as a |method|: >
9201 GetTimer()->timer_stop()
9202
9203 < {only available when compiled with the |+timers| feature}
9204
9205 timer_stopall() *timer_stopall()*
9206 Stop all timers. The timer callbacks will no longer be
9207 invoked. Useful if a timer is misbehaving. If there are no
9208 timers there is no error.
9209
9210 {only available when compiled with the |+timers| feature}
9211
9212 tolower({expr}) *tolower()*
9213 The result is a copy of the String given, with all uppercase
9214 characters turned into lowercase (just like applying |gu| to
9215 the string).
9216
9217 Can also be used as a |method|: >
9218 GetText()->tolower()
9219
9220 toupper({expr}) *toupper()*
9221 The result is a copy of the String given, with all lowercase
9222 characters turned into uppercase (just like applying |gU| to
9223 the string).
9224
9225 Can also be used as a |method|: >
9226 GetText()->toupper()
9227
9228 tr({src}, {fromstr}, {tostr}) *tr()*
9229 The result is a copy of the {src} string with all characters
9230 which appear in {fromstr} replaced by the character in that
9231 position in the {tostr} string. Thus the first character in
9232 {fromstr} is translated into the first character in {tostr}
9233 and so on. Exactly like the unix "tr" command.
9234 This code also deals with multibyte characters properly.
9235
9236 Examples: >
9237 echo tr("hello there", "ht", "HT")
9238 < returns "Hello THere" >
9239 echo tr("<blob>", "<>", "{}")
9240 < returns "{blob}"
9241
9242 Can also be used as a |method|: >
9243 GetText()->tr(from, to)
9244
9245 trim({text} [, {mask} [, {dir}]]) *trim()*
9246 Return {text} as a String where any character in {mask} is
9247 removed from the beginning and/or end of {text}.
9248
9249 If {mask} is not given, {mask} is all characters up to 0x20,
9250 which includes Tab, space, NL and CR, plus the non-breaking
9251 space character 0xa0.
9252
9253 The optional {dir} argument specifies where to remove the
9254 characters:
9255 0 remove from the beginning and end of {text}
9256 1 remove only at the beginning of {text}
9257 2 remove only at the end of {text}
9258 When omitted both ends are trimmed.
9259
9260 This function deals with multibyte characters properly.
9261
9262 Examples: >
9263 echo trim(" some text ")
9264 < returns "some text" >
9265 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL"
9266 < returns "RESERVE_TAIL" >
9267 echo trim("rm<Xrm<>X>rrm", "rm<>")
9268 < returns "Xrm<>X" (characters in the middle are not removed) >
9269 echo trim(" vim ", " ", 2)
9270 < returns " vim"
9271
9272 Can also be used as a |method|: >
9273 GetText()->trim()
9274
9275 trunc({expr}) *trunc()*
9276 Return the largest integral value with magnitude less than or
9277 equal to {expr} as a |Float| (truncate towards zero).
9278 {expr} must evaluate to a |Float| or a |Number|.
9279 Examples: >
9280 echo trunc(1.456)
9281 < 1.0 >
9282 echo trunc(-5.456)
9283 < -5.0 >
9284 echo trunc(4.0)
9285 < 4.0
9286
9287 Can also be used as a |method|: >
9288 Compute()->trunc()
9289 <
9290 {only available when compiled with the |+float| feature}
9291
9292 *type()*
9293 type({expr}) The result is a Number representing the type of {expr}.
9294 Instead of using the number directly, it is better to use the
9295 v:t_ variable that has the value:
9296 Number: 0 |v:t_number|
9297 String: 1 |v:t_string|
9298 Funcref: 2 |v:t_func|
9299 List: 3 |v:t_list|
9300 Dictionary: 4 |v:t_dict|
9301 Float: 5 |v:t_float|
9302 Boolean: 6 |v:t_bool| (v:false and v:true)
9303 None: 7 |v:t_none| (v:null and v:none)
9304 Job: 8 |v:t_job|
9305 Channel: 9 |v:t_channel|
9306 Blob: 10 |v:t_blob|
9307 For backward compatibility, this method can be used: >
9308 :if type(myvar) == type(0)
9309 :if type(myvar) == type("")
9310 :if type(myvar) == type(function("tr"))
9311 :if type(myvar) == type([])
9312 :if type(myvar) == type({})
9313 :if type(myvar) == type(0.0)
9314 :if type(myvar) == type(v:false)
9315 :if type(myvar) == type(v:none)
9316 < To check if the v:t_ variables exist use this: >
9317 :if exists('v:t_number')
9318
9319 < Can also be used as a |method|: >
9320 mylist->type()
9321
9322
9323 typename({expr}) *typename()*
9324 Return a string representation of the type of {expr}.
9325 Example: >
9326 echo typename([1, 2, 3])
9327 list<number>
9328
9329
9330 undofile({name}) *undofile()*
9331 Return the name of the undo file that would be used for a file
9332 with name {name} when writing. This uses the 'undodir'
9333 option, finding directories that exist. It does not check if
9334 the undo file exists.
9335 {name} is always expanded to the full path, since that is what
9336 is used internally.
9337 If {name} is empty undofile() returns an empty string, since a
9338 buffer without a file name will not write an undo file.
9339 Useful in combination with |:wundo| and |:rundo|.
9340 When compiled without the |+persistent_undo| option this always
9341 returns an empty string.
9342
9343 Can also be used as a |method|: >
9344 GetFilename()->undofile()
9345
9346 undotree() *undotree()*
9347 Return the current state of the undo tree in a dictionary with
9348 the following items:
9349 "seq_last" The highest undo sequence number used.
9350 "seq_cur" The sequence number of the current position in
9351 the undo tree. This differs from "seq_last"
9352 when some changes were undone.
9353 "time_cur" Time last used for |:earlier| and related
9354 commands. Use |strftime()| to convert to
9355 something readable.
9356 "save_last" Number of the last file write. Zero when no
9357 write yet.
9358 "save_cur" Number of the current position in the undo
9359 tree.
9360 "synced" Non-zero when the last undo block was synced.
9361 This happens when waiting from input from the
9362 user. See |undo-blocks|.
9363 "entries" A list of dictionaries with information about
9364 undo blocks.
9365
9366 The first item in the "entries" list is the oldest undo item.
9367 Each List item is a |Dictionary| with these items:
9368 "seq" Undo sequence number. Same as what appears in
9369 |:undolist|.
9370 "time" Timestamp when the change happened. Use
9371 |strftime()| to convert to something readable.
9372 "newhead" Only appears in the item that is the last one
9373 that was added. This marks the last change
9374 and where further changes will be added.
9375 "curhead" Only appears in the item that is the last one
9376 that was undone. This marks the current
9377 position in the undo tree, the block that will
9378 be used by a redo command. When nothing was
9379 undone after the last change this item will
9380 not appear anywhere.
9381 "save" Only appears on the last block before a file
9382 write. The number is the write count. The
9383 first write has number 1, the last one the
9384 "save_last" mentioned above.
9385 "alt" Alternate entry. This is again a List of undo
9386 blocks. Each item may again have an "alt"
9387 item.
9388
9389 uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
9390 Remove second and succeeding copies of repeated adjacent
9391 {list} items in-place. Returns {list}. If you want a list
9392 to remain unmodified make a copy first: >
9393 :let newlist = uniq(copy(mylist))
9394 < The default compare function uses the string representation of
9395 each item. For the use of {func} and {dict} see |sort()|.
9396
9397 Can also be used as a |method|: >
9398 mylist->uniq()
9399
9400 values({dict}) *values()*
9401 Return a |List| with all the values of {dict}. The |List| is
9402 in arbitrary order. Also see |items()| and |keys()|.
9403
9404 Can also be used as a |method|: >
9405 mydict->values()
9406
9407 virtcol({expr}) *virtcol()*
9408 The result is a Number, which is the screen column of the file
9409 position given with {expr}. That is, the last screen position
9410 occupied by the character at that position, when the screen
9411 would be of unlimited width. When there is a <Tab> at the
9412 position, the returned Number will be the column at the end of
9413 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
9414 set to 8, it returns 8. |conceal| is ignored.
9415 For the byte position use |col()|.
9416 For the use of {expr} see |col()|.
9417 When 'virtualedit' is used {expr} can be [lnum, col, off], where
9418 "off" is the offset in screen columns from the start of the
9419 character. E.g., a position within a <Tab> or after the last
9420 character. When "off" is omitted zero is used.
9421 When Virtual editing is active in the current mode, a position
9422 beyond the end of the line can be returned. |'virtualedit'|
9423 The accepted positions are:
9424 . the cursor position
9425 $ the end of the cursor line (the result is the
9426 number of displayed characters in the cursor line
9427 plus one)
9428 'x position of mark x (if the mark is not set, 0 is
9429 returned)
9430 v In Visual mode: the start of the Visual area (the
9431 cursor is the end). When not in Visual mode
9432 returns the cursor position. Differs from |'<| in
9433 that it's updated right away.
9434 Note that only marks in the current file can be used.
9435 Examples: >
9436 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
9437 virtcol("$") with text "foo^Lbar", returns 9
9438 virtcol("'t") with text " there", with 't at 'h', returns 6
9439 < The first column is 1. 0 is returned for an error.
9440 A more advanced example that echoes the maximum length of
9441 all lines: >
9442 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
9443
9444 < Can also be used as a |method|: >
9445 GetPos()->virtcol()
9446
9447
9448 visualmode([{expr}]) *visualmode()*
9449 The result is a String, which describes the last Visual mode
9450 used in the current buffer. Initially it returns an empty
9451 string, but once Visual mode has been used, it returns "v",
9452 "V", or "<CTRL-V>" (a single CTRL-V character) for
9453 character-wise, line-wise, or block-wise Visual mode
9454 respectively.
9455 Example: >
9456 :exe "normal " . visualmode()
9457 < This enters the same Visual mode as before. It is also useful
9458 in scripts if you wish to act differently depending on the
9459 Visual mode that was used.
9460 If Visual mode is active, use |mode()| to get the Visual mode
9461 (e.g., in a |:vmap|).
9462 If {expr} is supplied and it evaluates to a non-zero Number or
9463 a non-empty String, then the Visual mode will be cleared and
9464 the old value is returned. See |non-zero-arg|.
9465
9466 wildmenumode() *wildmenumode()*
9467 Returns |TRUE| when the wildmenu is active and |FALSE|
9468 otherwise. See 'wildmenu' and 'wildmode'.
9469 This can be used in mappings to handle the 'wildcharm' option
9470 gracefully. (Makes only sense with |mapmode-c| mappings).
9471
9472 For example to make <c-j> work like <down> in wildmode, use: >
9473 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
9474 <
9475 (Note, this needs the 'wildcharm' option set appropriately).
9476
9477 win_execute({id}, {command} [, {silent}]) *win_execute()*
9478 Like `execute()` but in the context of window {id}.
9479 The window will temporarily be made the current window,
9480 without triggering autocommands or changing directory. When
9481 executing {command} autocommands will be triggered, this may
9482 have unexpected side effects. Use |:noautocmd| if needed.
9483 Example: >
9484 call win_execute(winid, 'set syntax=python')
9485 < Doing the same with `setwinvar()` would not trigger
9486 autocommands and not actually show syntax highlighting.
9487
9488 *E994*
9489 Not all commands are allowed in popup windows.
9490 When window {id} does not exist then no error is given and
9491 an empty string is returned.
9492
9493 Can also be used as a |method|, the base is passed as the
9494 second argument: >
9495 GetCommand()->win_execute(winid)
9496
9497 win_findbuf({bufnr}) *win_findbuf()*
9498 Returns a |List| with |window-ID|s for windows that contain
9499 buffer {bufnr}. When there is none the list is empty.
9500
9501 Can also be used as a |method|: >
9502 GetBufnr()->win_findbuf()
9503
9504 win_getid([{win} [, {tab}]]) *win_getid()*
9505 Get the |window-ID| for the specified window.
9506 When {win} is missing use the current window.
9507 With {win} this is the window number. The top window has
9508 number 1.
9509 Without {tab} use the current tab, otherwise the tab with
9510 number {tab}. The first tab has number one.
9511 Return zero if the window cannot be found.
9512
9513 Can also be used as a |method|: >
9514 GetWinnr()->win_getid()
9515
9516
9517 win_gettype([{nr}]) *win_gettype()*
9518 Return the type of the window:
9519 "autocmd" autocommand window. Temporary window
9520 used to execute autocommands.
9521 "command" command-line window |cmdwin|
9522 (empty) normal window
9523 "loclist" |location-list-window|
9524 "popup" popup window |popup|
9525 "preview" preview window |preview-window|
9526 "quickfix" |quickfix-window|
9527 "unknown" window {nr} not found
9528
9529 When {nr} is omitted return the type of the current window.
9530 When {nr} is given return the type of this window by number or
9531 |window-ID|.
9532
9533 Also see the 'buftype' option. When running a terminal in a
9534 popup window then 'buftype' is "terminal" and win_gettype()
9535 returns "popup".
9536
9537 Can also be used as a |method|: >
9538 GetWinid()->win_gettype()
9539 <
9540 win_gotoid({expr}) *win_gotoid()*
9541 Go to window with ID {expr}. This may also change the current
9542 tabpage.
9543 Return TRUE if successful, FALSE if the window cannot be found.
9544
9545 Can also be used as a |method|: >
9546 GetWinid()->win_gotoid()
9547
9548 win_id2tabwin({expr}) *win_id2tabwin()*
9549 Return a list with the tab number and window number of window
9550 with ID {expr}: [tabnr, winnr].
9551 Return [0, 0] if the window cannot be found.
9552
9553 Can also be used as a |method|: >
9554 GetWinid()->win_id2tabwin()
9555
9556 win_id2win({expr}) *win_id2win()*
9557 Return the window number of window with ID {expr}.
9558 Return 0 if the window cannot be found in the current tabpage.
9559
9560 Can also be used as a |method|: >
9561 GetWinid()->win_id2win()
9562
9563 win_screenpos({nr}) *win_screenpos()*
9564 Return the screen position of window {nr} as a list with two
9565 numbers: [row, col]. The first window always has position
9566 [1, 1], unless there is a tabline, then it is [2, 1].
9567 {nr} can be the window number or the |window-ID|. Use zero
9568 for the current window.
9569 Returns [0, 0] if the window cannot be found in the current
9570 tabpage.
9571
9572 Can also be used as a |method|: >
9573 GetWinid()->win_screenpos()
9574 <
9575 win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
9576 Move the window {nr} to a new split of the window {target}.
9577 This is similar to moving to {target}, creating a new window
9578 using |:split| but having the same contents as window {nr}, and
9579 then closing {nr}.
9580
9581 Both {nr} and {target} can be window numbers or |window-ID|s.
9582 Both must be in the current tab page.
9583
9584 Returns zero for success, non-zero for failure.
9585
9586 {options} is a |Dictionary| with the following optional entries:
9587 "vertical" When TRUE, the split is created vertically,
9588 like with |:vsplit|.
9589 "rightbelow" When TRUE, the split is made below or to the
9590 right (if vertical). When FALSE, it is done
9591 above or to the left (if vertical). When not
9592 present, the values of 'splitbelow' and
9593 'splitright' are used.
9594
9595 Can also be used as a |method|: >
9596 GetWinid()->win_splitmove(target)
9597 <
9598
9599 *winbufnr()*
9600 winbufnr({nr}) The result is a Number, which is the number of the buffer
9601 associated with window {nr}. {nr} can be the window number or
9602 the |window-ID|.
9603 When {nr} is zero, the number of the buffer in the current
9604 window is returned.
9605 When window {nr} doesn't exist, -1 is returned.
9606 Example: >
9607 :echo "The file in the current window is " . bufname(winbufnr(0))
9608 <
9609 Can also be used as a |method|: >
9610 FindWindow()->winbufnr()->bufname()
9611 <
9612 *wincol()*
9613 wincol() The result is a Number, which is the virtual column of the
9614 cursor in the window. This is counting screen cells from the
9615 left side of the window. The leftmost column is one.
9616
9617 *windowsversion()*
9618 windowsversion()
9619 The result is a String. For MS-Windows it indicates the OS
9620 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
9621 Windows XP is "5.1". For non-MS-Windows systems the result is
9622 an empty string.
9623
9624 winheight({nr}) *winheight()*
9625 The result is a Number, which is the height of window {nr}.
9626 {nr} can be the window number or the |window-ID|.
9627 When {nr} is zero, the height of the current window is
9628 returned. When window {nr} doesn't exist, -1 is returned.
9629 An existing window always has a height of zero or more.
9630 This excludes any window toolbar line.
9631 Examples: >
9632 :echo "The current window has " . winheight(0) . " lines."
9633
9634 < Can also be used as a |method|: >
9635 GetWinid()->winheight()
9636 <
9637 winlayout([{tabnr}]) *winlayout()*
9638 The result is a nested List containing the layout of windows
9639 in a tabpage.
9640
9641 Without {tabnr} use the current tabpage, otherwise the tabpage
9642 with number {tabnr}. If the tabpage {tabnr} is not found,
9643 returns an empty list.
9644
9645 For a leaf window, it returns:
9646 ['leaf', {winid}]
9647 For horizontally split windows, which form a column, it
9648 returns:
9649 ['col', [{nested list of windows}]]
9650 For vertically split windows, which form a row, it returns:
9651 ['row', [{nested list of windows}]]
9652
9653 Example: >
9654 " Only one window in the tab page
9655 :echo winlayout()
9656 ['leaf', 1000]
9657 " Two horizontally split windows
9658 :echo winlayout()
9659 ['col', [['leaf', 1000], ['leaf', 1001]]]
9660 " The second tab page, with three horizontally split
9661 " windows, with two vertically split windows in the
9662 " middle window
9663 :echo winlayout(2)
9664 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
9665 ['leaf', 1001]]], ['leaf', 1000]]]
9666 <
9667 Can also be used as a |method|: >
9668 GetTabnr()->winlayout()
9669 <
9670 *winline()*
9671 winline() The result is a Number, which is the screen line of the cursor
9672 in the window. This is counting screen lines from the top of
9673 the window. The first line is one.
9674 If the cursor was moved the view on the file will be updated
9675 first, this may cause a scroll.
9676
9677 *winnr()*
9678 winnr([{arg}]) The result is a Number, which is the number of the current
9679 window. The top window has number 1.
9680 Returns zero for a popup window.
9681
9682 The optional argument {arg} supports the following values:
9683 $ the number of the last window (the window
9684 count).
9685 # the number of the last accessed window (where
9686 |CTRL-W_p| goes to). If there is no previous
9687 window or it is in another tab page 0 is
9688 returned.
9689 {N}j the number of the Nth window below the
9690 current window (where |CTRL-W_j| goes to).
9691 {N}k the number of the Nth window above the current
9692 window (where |CTRL-W_k| goes to).
9693 {N}h the number of the Nth window left of the
9694 current window (where |CTRL-W_h| goes to).
9695 {N}l the number of the Nth window right of the
9696 current window (where |CTRL-W_l| goes to).
9697 The number can be used with |CTRL-W_w| and ":wincmd w"
9698 |:wincmd|.
9699 Also see |tabpagewinnr()| and |win_getid()|.
9700 Examples: >
9701 let window_count = winnr('$')
9702 let prev_window = winnr('#')
9703 let wnum = winnr('3k')
9704
9705 < Can also be used as a |method|: >
9706 GetWinval()->winnr()
9707 <
9708 *winrestcmd()*
9709 winrestcmd() Returns a sequence of |:resize| commands that should restore
9710 the current window sizes. Only works properly when no windows
9711 are opened or closed and the current window and tab page is
9712 unchanged.
9713 Example: >
9714 :let cmd = winrestcmd()
9715 :call MessWithWindowSizes()
9716 :exe cmd
9717 <
9718 *winrestview()*
9719 winrestview({dict})
9720 Uses the |Dictionary| returned by |winsaveview()| to restore
9721 the view of the current window.
9722 Note: The {dict} does not have to contain all values, that are
9723 returned by |winsaveview()|. If values are missing, those
9724 settings won't be restored. So you can use: >
9725 :call winrestview({'curswant': 4})
9726 <
9727 This will only set the curswant value (the column the cursor
9728 wants to move on vertical movements) of the cursor to column 5
9729 (yes, that is 5), while all other settings will remain the
9730 same. This is useful, if you set the cursor position manually.
9731
9732 If you have changed the values the result is unpredictable.
9733 If the window size changed the result won't be the same.
9734
9735 Can also be used as a |method|: >
9736 GetView()->winrestview()
9737 <
9738 *winsaveview()*
9739 winsaveview() Returns a |Dictionary| that contains information to restore
9740 the view of the current window. Use |winrestview()| to
9741 restore the view.
9742 This is useful if you have a mapping that jumps around in the
9743 buffer and you want to go back to the original view.
9744 This does not save fold information. Use the 'foldenable'
9745 option to temporarily switch off folding, so that folds are
9746 not opened when moving around. This may have side effects.
9747 The return value includes:
9748 lnum cursor line number
9749 col cursor column (Note: the first column
9750 zero, as opposed to what getpos()
9751 returns)
9752 coladd cursor column offset for 'virtualedit'
9753 curswant column for vertical movement
9754 topline first line in the window
9755 topfill filler lines, only in diff mode
9756 leftcol first column displayed; only used when
9757 'wrap' is off
9758 skipcol columns skipped
9759 Note that no option values are saved.
9760
9761
9762 winwidth({nr}) *winwidth()*
9763 The result is a Number, which is the width of window {nr}.
9764 {nr} can be the window number or the |window-ID|.
9765 When {nr} is zero, the width of the current window is
9766 returned. When window {nr} doesn't exist, -1 is returned.
9767 An existing window always has a width of zero or more.
9768 Examples: >
9769 :echo "The current window has " . winwidth(0) . " columns."
9770 :if winwidth(0) <= 50
9771 : 50 wincmd |
9772 :endif
9773 < For getting the terminal or screen size, see the 'columns'
9774 option.
9775
9776 Can also be used as a |method|: >
9777 GetWinid()->winwidth()
9778
9779
9780 wordcount() *wordcount()*
9781 The result is a dictionary of byte/chars/word statistics for
9782 the current buffer. This is the same info as provided by
9783 |g_CTRL-G|
9784 The return value includes:
9785 bytes Number of bytes in the buffer
9786 chars Number of chars in the buffer
9787 words Number of words in the buffer
9788 cursor_bytes Number of bytes before cursor position
9789 (not in Visual mode)
9790 cursor_chars Number of chars before cursor position
9791 (not in Visual mode)
9792 cursor_words Number of words before cursor position
9793 (not in Visual mode)
9794 visual_bytes Number of bytes visually selected
9795 (only in Visual mode)
9796 visual_chars Number of chars visually selected
9797 (only in Visual mode)
9798 visual_words Number of words visually selected
9799 (only in Visual mode)
9800
9801
9802 *writefile()*
9803 writefile({object}, {fname} [, {flags}])
9804 When {object} is a |List| write it to file {fname}. Each list
9805 item is separated with a NL. Each list item must be a String
9806 or Number.
9807 When {flags} contains "b" then binary mode is used: There will
9808 not be a NL after the last list item. An empty item at the
9809 end does cause the last line in the file to end in a NL.
9810
9811 When {object} is a |Blob| write the bytes to file {fname}
9812 unmodified.
9813
9814 When {flags} contains "a" then append mode is used, lines are
9815 appended to the file: >
9816 :call writefile(["foo"], "event.log", "a")
9817 :call writefile(["bar"], "event.log", "a")
9818 <
9819 When {flags} contains "s" then fsync() is called after writing
9820 the file. This flushes the file to disk, if possible. This
9821 takes more time but avoids losing the file if the system
9822 crashes.
9823 When {flags} does not contain "S" or "s" then fsync() is
9824 called if the 'fsync' option is set.
9825 When {flags} contains "S" then fsync() is not called, even
9826 when 'fsync' is set.
9827
9828 All NL characters are replaced with a NUL character.
9829 Inserting CR characters needs to be done before passing {list}
9830 to writefile().
9831 An existing file is overwritten, if possible.
9832 When the write fails -1 is returned, otherwise 0. There is an
9833 error message if the file can't be created or when writing
9834 fails.
9835 Also see |readfile()|.
9836 To copy a file byte for byte: >
9837 :let fl = readfile("foo", "b")
9838 :call writefile(fl, "foocopy", "b")
9839
9840 < Can also be used as a |method|: >
9841 GetText()->writefile("thefile")
9842
9843
9844 xor({expr}, {expr}) *xor()*
9845 Bitwise XOR on the two arguments. The arguments are converted
9846 to a number. A List, Dict or Float argument causes an error.
9847 Example: >
9848 :let bits = xor(bits, 0x80)
9849 <
9850 Can also be used as a |method|: >
9851 :let bits = bits->xor(0x80)
9852 <
9853
9854 ==============================================================================
9855 3. Feature list *feature-list*
9856
9857 There are three types of features:
9858 1. Features that are only supported when they have been enabled when Vim
9859 was compiled |+feature-list|. Example: >
9860 :if has("cindent")
9861 < *gui_running*
9862 2. Features that are only supported when certain conditions have been met.
9863 Example: >
9864 :if has("gui_running")
9865 < *has-patch*
9866 3. Beyond a certain version or at a certain version and including a specific
9867 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
9868 later, or it is version 7.4 and patch 248 was included. Example: >
9869 :if has("patch-7.4.248")
9870 < Note that it's possible for patch 248 to be omitted even though 249 is
9871 included. Only happens when cherry-picking patches.
9872 Note that this form only works for patch 7.4.237 and later, before that
9873 you need to check for the patch and the v:version. Example (checking
9874 version 6.2.148 or later): >
9875 :if v:version > 602 || (v:version == 602 && has("patch148"))
9876
9877 Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
9878 use: `if exists('+shellslash')`
9879
9880
9881 acl Compiled with |ACL| support.
9882 all_builtin_terms Compiled with all builtin terminals enabled.
9883 amiga Amiga version of Vim.
9884 arabic Compiled with Arabic support |Arabic|.
9885 arp Compiled with ARP support (Amiga).
9886 autocmd Compiled with autocommand support. (always true)
9887 autochdir Compiled with support for 'autochdir'
9888 autoservername Automatically enable |clientserver|
9889 balloon_eval Compiled with |balloon-eval| support.
9890 balloon_multiline GUI supports multiline balloons.
9891 beos BeOS version of Vim.
9892 browse Compiled with |:browse| support, and browse() will
9893 work.
9894 browsefilter Compiled with support for |browsefilter|.
9895 bsd Compiled on an OS in the BSD family (excluding macOS).
9896 builtin_terms Compiled with some builtin terminals.
9897 byte_offset Compiled with support for 'o' in 'statusline'
9898 channel Compiled with support for |channel| and |job|
9899 cindent Compiled with 'cindent' support.
9900 clientserver Compiled with remote invocation support |clientserver|.
9901 clipboard Compiled with 'clipboard' support.
9902 clipboard_working Compiled with 'clipboard' support and it can be used.
9903 cmdline_compl Compiled with |cmdline-completion| support.
9904 cmdline_hist Compiled with |cmdline-history| support.
9905 cmdline_info Compiled with 'showcmd' and 'ruler' support.
9906 comments Compiled with |'comments'| support.
9907 compatible Compiled to be very Vi compatible.
9908 conpty Platform where |ConPTY| can be used.
9909 cryptv Compiled with encryption support |encryption|.
9910 cscope Compiled with |cscope| support.
9911 cursorbind Compiled with |'cursorbind'| (always true)
9912 debug Compiled with "DEBUG" defined.
9913 dialog_con Compiled with console dialog support.
9914 dialog_gui Compiled with GUI dialog support.
9915 diff Compiled with |vimdiff| and 'diff' support.
9916 digraphs Compiled with support for digraphs.
9917 directx Compiled with support for DirectX and 'renderoptions'.
9918 dnd Compiled with support for the "~ register |quote_~|.
9919 drop_file Compiled with |drop_file| support.
9920 ebcdic Compiled on a machine with ebcdic character set.
9921 emacs_tags Compiled with support for Emacs tags.
9922 eval Compiled with expression evaluation support. Always
9923 true, of course!
9924 ex_extra |+ex_extra| (always true)
9925 extra_search Compiled with support for |'incsearch'| and
9926 |'hlsearch'|
9927 farsi Support for Farsi was removed |farsi|.
9928 file_in_path Compiled with support for |gf| and |<cfile>|
9929 filterpipe When 'shelltemp' is off pipes are used for shell
9930 read/write/filter commands
9931 find_in_path Compiled with support for include file searches
9932 |+find_in_path|.
9933 float Compiled with support for |Float|.
9934 fname_case Case in file names matters (for Amiga and MS-Windows
9935 this is not present).
9936 folding Compiled with |folding| support.
9937 footer Compiled with GUI footer support. |gui-footer|
9938 fork Compiled to use fork()/exec() instead of system().
9939 gettext Compiled with message translation |multi-lang|
9940 gui Compiled with GUI enabled.
9941 gui_athena Compiled with Athena GUI.
9942 gui_gnome Compiled with Gnome support (gui_gtk is also defined).
9943 gui_gtk Compiled with GTK+ GUI (any version).
9944 gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
9945 gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
9946 gui_haiku Compiled with Haiku GUI.
9947 gui_mac Compiled with Macintosh GUI.
9948 gui_motif Compiled with Motif GUI.
9949 gui_photon Compiled with Photon GUI.
9950 gui_running Vim is running in the GUI, or it will start soon.
9951 gui_win32 Compiled with MS-Windows Win32 GUI.
9952 gui_win32s idem, and Win32s system being used (Windows 3.1)
9953 haiku Haiku version of Vim.
9954 hangul_input Compiled with Hangul input support. |hangul|
9955 hpux HP-UX version of Vim.
9956 iconv Can use iconv() for conversion.
9957 insert_expand Compiled with support for CTRL-X expansion commands in
9958 Insert mode. (always true)
9959 job Compiled with support for |channel| and |job|
9960 ipv6 Compiled with support for IPv6 networking in |channel|.
9961 jumplist Compiled with |jumplist| support.
9962 keymap Compiled with 'keymap' support.
9963 lambda Compiled with |lambda| support.
9964 langmap Compiled with 'langmap' support.
9965 libcall Compiled with |libcall()| support.
9966 linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
9967 'breakindent' support.
9968 linux Linux version of Vim.
9969 lispindent Compiled with support for lisp indenting.
9970 listcmds Compiled with commands for the buffer list |:files|
9971 and the argument list |arglist|.
9972 localmap Compiled with local mappings and abbr. |:map-local|
9973 lua Compiled with Lua interface |Lua|.
9974 mac Any Macintosh version of Vim cf. osx
9975 macunix Synonym for osxdarwin
9976 menu Compiled with support for |:menu|.
9977 mksession Compiled with support for |:mksession|.
9978 modify_fname Compiled with file name modifiers. |filename-modifiers|
9979 (always true)
9980 mouse Compiled with support for mouse.
9981 mouse_dec Compiled with support for Dec terminal mouse.
9982 mouse_gpm Compiled with support for gpm (Linux console mouse)
9983 mouse_gpm_enabled GPM mouse is working
9984 mouse_netterm Compiled with support for netterm mouse.
9985 mouse_pterm Compiled with support for qnx pterm mouse.
9986 mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
9987 mouse_sgr Compiled with support for sgr mouse.
9988 mouse_urxvt Compiled with support for urxvt mouse.
9989 mouse_xterm Compiled with support for xterm mouse.
9990 mouseshape Compiled with support for 'mouseshape'.
9991 multi_byte Compiled with support for 'encoding' (always true)
9992 multi_byte_encoding 'encoding' is set to a multibyte encoding.
9993 multi_byte_ime Compiled with support for IME input method.
9994 multi_lang Compiled with support for multiple languages.
9995 mzscheme Compiled with MzScheme interface |mzscheme|.
9996 nanotime Compiled with sub-second time stamp checks.
9997 netbeans_enabled Compiled with support for |netbeans| and connected.
9998 netbeans_intg Compiled with support for |netbeans|.
9999 num64 Compiled with 64-bit |Number| support.
10000 ole Compiled with OLE automation support for Win32.
10001 osx Compiled for macOS cf. mac
10002 osxdarwin Compiled for macOS, with |mac-darwin-feature|
10003 packages Compiled with |packages| support.
10004 path_extra Compiled with up/downwards search in 'path' and 'tags'
10005 perl Compiled with Perl interface.
10006 persistent_undo Compiled with support for persistent undo history.
10007 postscript Compiled with PostScript file printing.
10008 printer Compiled with |:hardcopy| support.
10009 profile Compiled with |:profile| support.
10010 python Python 2.x interface available. |has-python|
10011 python_compiled Compiled with Python 2.x interface. |has-python|
10012 python_dynamic Python 2.x interface is dynamically loaded. |has-python|
10013 python3 Python 3.x interface available. |has-python|
10014 python3_compiled Compiled with Python 3.x interface. |has-python|
10015 python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
10016 pythonx Python 2.x and/or 3.x interface available. |python_x|
10017 qnx QNX version of Vim.
10018 quickfix Compiled with |quickfix| support.
10019 reltime Compiled with |reltime()| support.
10020 rightleft Compiled with 'rightleft' support.
10021 ruby Compiled with Ruby interface |ruby|.
10022 scrollbind Compiled with 'scrollbind' support. (always true)
10023 showcmd Compiled with 'showcmd' support.
10024 signs Compiled with |:sign| support.
10025 smartindent Compiled with 'smartindent' support.
10026 sodium Compiled with libsodium for better crypt support
10027 sound Compiled with sound support, e.g. `sound_playevent()`
10028 spell Compiled with spell checking support |spell|.
10029 startuptime Compiled with |--startuptime| support.
10030 statusline Compiled with support for 'statusline', 'rulerformat'
10031 and special formats of 'titlestring' and 'iconstring'.
10032 sun SunOS version of Vim.
10033 sun_workshop Support for Sun |workshop| has been removed.
10034 syntax Compiled with syntax highlighting support |syntax|.
10035 syntax_items There are active syntax highlighting items for the
10036 current buffer.
10037 system Compiled to use system() instead of fork()/exec().
10038 tag_binary Compiled with binary searching in tags files
10039 |tag-binary-search|.
10040 tag_old_static Support for old static tags was removed, see
10041 |tag-old-static|.
10042 tcl Compiled with Tcl interface.
10043 termguicolors Compiled with true color in terminal support.
10044 terminal Compiled with |terminal| support.
10045 terminfo Compiled with terminfo instead of termcap.
10046 termresponse Compiled with support for |t_RV| and |v:termresponse|.
10047 textobjects Compiled with support for |text-objects|.
10048 textprop Compiled with support for |text-properties|.
10049 tgetent Compiled with tgetent support, able to use a termcap
10050 or terminfo file.
10051 timers Compiled with |timer_start()| support.
10052 title Compiled with window title support |'title'|.
10053 toolbar Compiled with support for |gui-toolbar|.
10054 ttyin input is a terminal (tty)
10055 ttyout output is a terminal (tty)
10056 unix Unix version of Vim. *+unix*
10057 unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
10058 user_commands User-defined commands. (always true)
10059 vartabs Compiled with variable tabstop support |'vartabstop'|.
10060 vcon Win32: Virtual console support is working, can use
10061 'termguicolors'. Also see |+vtp|.
10062 vertsplit Compiled with vertically split windows |:vsplit|.
10063 (always true)
10064 vim_starting True while initial source'ing takes place. |startup|
10065 *vim_starting*
10066 viminfo Compiled with viminfo support.
10067 vimscript-1 Compiled Vim script version 1 support
10068 vimscript-2 Compiled Vim script version 2 support
10069 vimscript-3 Compiled Vim script version 3 support
10070 virtualedit Compiled with 'virtualedit' option. (always true)
10071 visual Compiled with Visual mode. (always true)
10072 visualextra Compiled with extra Visual mode commands. (always
10073 true) |blockwise-operators|.
10074 vms VMS version of Vim.
10075 vreplace Compiled with |gR| and |gr| commands. (always true)
10076 vtp Compiled for vcon support |+vtp| (check vcon to find
10077 out if it works in the current console).
10078 wildignore Compiled with 'wildignore' option.
10079 wildmenu Compiled with 'wildmenu' option.
10080 win16 old version for MS-Windows 3.1 (always false)
10081 win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
10082 64 bits)
10083 win32unix Win32 version of Vim, using Unix files (Cygwin)
10084 win64 Win64 version of Vim (MS-Windows 64 bit).
10085 win95 Win32 version for MS-Windows 95/98/ME (always false)
10086 winaltkeys Compiled with 'winaltkeys' option.
10087 windows Compiled with support for more than one window.
10088 (always true)
10089 writebackup Compiled with 'writebackup' default on.
10090 xfontset Compiled with X fontset support |xfontset|.
10091 xim Compiled with X input method support |xim|.
10092 xpm Compiled with pixmap support.
10093 xpm_w32 Compiled with pixmap support for Win32. (Only for
10094 backward compatibility. Use "xpm" instead.)
10095 xsmp Compiled with X session management support.
10096 xsmp_interact Compiled with interactive X session management support.
10097 xterm_clipboard Compiled with support for xterm clipboard.
10098 xterm_save Compiled with support for saving and restoring the
10099 xterm screen.
10100 x11 Compiled with X11 support.
10101
10102
10103 ==============================================================================
10104 4. Matching a pattern in a String *string-match*
10105
10106 This is common between several functions. A regexp pattern as explained at
10107 |pattern| is normally used to find a match in the buffer lines. When a
10108 pattern is used to find a match in a String, almost everything works in the
10109 same way. The difference is that a String is handled like it is one line.
10110 When it contains a "\n" character, this is not seen as a line break for the
10111 pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
10112 >
10113 :let a = "aaaa\nxxxx"
10114 :echo matchstr(a, "..\n..")
10115 aa
10116 xx
10117 :echo matchstr(a, "a.x")
10118 a
10119 x
10120
10121 Don't forget that "^" will only match at the first character of the String and
10122 "$" at the last character of the string. They don't match after or before a
10123 "\n".
10124
10125 vim:tw=78:ts=8:noet:ft=help:norl: