blob: 786f9dee23fac3807f85bc1e23013035ed5a0e5e [file] [log] [blame]
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00001*builtin.txt* For Vim version 8.2. Last change: 2022 Jan 08
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Builtin functions *builtin-functions*
8
9Note: Expression evaluation can be disabled at compile time. If this has been
10done, the builtin functions are not available. See |+eval| and
11|no-eval-feature|.
12
131. Overview |builtin-function-list|
142. Details |builtin-function-details|
153. Feature list |feature-list|
164. Matching a pattern in a String |string-match|
17
18==============================================================================
191. Overview *builtin-function-list*
20
21Use CTRL-] on the function name to jump to the full explanation.
22
23USAGE RESULT DESCRIPTION ~
24
25abs({expr}) Float or Number absolute value of {expr}
26acos({expr}) Float arc cosine of {expr}
27add({object}, {item}) List/Blob append {item} to {object}
28and({expr}, {expr}) Number bitwise AND
29append({lnum}, {text}) Number append {text} below line {lnum}
30appendbufline({expr}, {lnum}, {text})
31 Number append {text} below line {lnum}
32 in buffer {expr}
33argc([{winid}]) Number number of files in the argument list
34argidx() Number current index in the argument list
35arglistid([{winnr} [, {tabnr}]]) Number argument list id
36argv({nr} [, {winid}]) String {nr} entry of the argument list
37argv([-1, {winid}]) List the argument list
38asin({expr}) Float arc sine of {expr}
39assert_beeps({cmd}) Number assert {cmd} causes a beep
40assert_equal({exp}, {act} [, {msg}])
41 Number assert {exp} is equal to {act}
42assert_equalfile({fname-one}, {fname-two} [, {msg}])
43 Number assert file contents are equal
44assert_exception({error} [, {msg}])
45 Number assert {error} is in v:exception
46assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])
47 Number assert {cmd} fails
48assert_false({actual} [, {msg}])
49 Number assert {actual} is false
50assert_inrange({lower}, {upper}, {actual} [, {msg}])
51 Number assert {actual} is inside the range
52assert_match({pat}, {text} [, {msg}])
53 Number assert {pat} matches {text}
54assert_nobeep({cmd}) Number assert {cmd} does not cause a beep
55assert_notequal({exp}, {act} [, {msg}])
56 Number assert {exp} is not equal {act}
57assert_notmatch({pat}, {text} [, {msg}])
58 Number assert {pat} not matches {text}
59assert_report({msg}) Number report a test failure
60assert_true({actual} [, {msg}]) Number assert {actual} is true
61atan({expr}) Float arc tangent of {expr}
62atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
63balloon_gettext() String current text in the balloon
64balloon_show({expr}) none show {expr} inside the balloon
65balloon_split({msg}) List split {msg} as used for a balloon
66blob2list({blob}) List convert {blob} into a list of numbers
67browse({save}, {title}, {initdir}, {default})
68 String put up a file requester
69browsedir({title}, {initdir}) String put up a directory requester
70bufadd({name}) Number add a buffer to the buffer list
71bufexists({buf}) Number |TRUE| if buffer {buf} exists
72buflisted({buf}) Number |TRUE| if buffer {buf} is listed
73bufload({buf}) Number load buffer {buf} if not loaded yet
74bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
75bufname([{buf}]) String Name of the buffer {buf}
76bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
77bufwinid({buf}) Number window ID of buffer {buf}
78bufwinnr({buf}) Number window number of buffer {buf}
79byte2line({byte}) Number line number at byte count {byte}
80byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
81byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
82call({func}, {arglist} [, {dict}])
83 any call {func} with arguments {arglist}
84ceil({expr}) Float round {expr} up
85ch_canread({handle}) Number check if there is something to read
86ch_close({handle}) none close {handle}
87ch_close_in({handle}) none close in part of {handle}
88ch_evalexpr({handle}, {expr} [, {options}])
89 any evaluate {expr} on JSON {handle}
90ch_evalraw({handle}, {string} [, {options}])
91 any evaluate {string} on raw {handle}
92ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
93ch_getjob({channel}) Job get the Job of {channel}
94ch_info({handle}) String info about channel {handle}
95ch_log({msg} [, {handle}]) none write {msg} in the channel log file
96ch_logfile({fname} [, {mode}]) none start logging channel activity
97ch_open({address} [, {options}])
98 Channel open a channel to {address}
99ch_read({handle} [, {options}]) String read from {handle}
100ch_readblob({handle} [, {options}])
101 Blob read Blob from {handle}
102ch_readraw({handle} [, {options}])
103 String read raw from {handle}
104ch_sendexpr({handle}, {expr} [, {options}])
105 any send {expr} over JSON {handle}
106ch_sendraw({handle}, {expr} [, {options}])
107 any send {expr} over raw {handle}
108ch_setoptions({handle}, {options})
109 none set options for {handle}
110ch_status({handle} [, {options}])
111 String status of channel {handle}
112changenr() Number current change number
113char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
114charclass({string}) Number character class of {string}
115charcol({expr}) Number column number of cursor or mark
116charidx({string}, {idx} [, {countcc}])
117 Number char index of byte {idx} in {string}
118chdir({dir}) String change current working directory
119cindent({lnum}) Number C indent for line {lnum}
120clearmatches([{win}]) none clear all matches
121col({expr}) Number column byte index of cursor or mark
122complete({startcol}, {matches}) none set Insert mode completion
123complete_add({expr}) Number add completion match
124complete_check() Number check for key typed during completion
125complete_info([{what}]) Dict get current completion information
126confirm({msg} [, {choices} [, {default} [, {type}]]])
127 Number number of choice picked by user
128copy({expr}) any make a shallow copy of {expr}
129cos({expr}) Float cosine of {expr}
130cosh({expr}) Float hyperbolic cosine of {expr}
131count({comp}, {expr} [, {ic} [, {start}]])
132 Number count how many {expr} are in {comp}
133cscope_connection([{num}, {dbpath} [, {prepend}]])
134 Number checks existence of cscope connection
135cursor({lnum}, {col} [, {off}])
136 Number move cursor to {lnum}, {col}, {off}
137cursor({list}) Number move cursor to position in {list}
138debugbreak({pid}) Number interrupt process being debugged
139deepcopy({expr} [, {noref}]) any make a full copy of {expr}
140delete({fname} [, {flags}]) Number delete the file or directory {fname}
141deletebufline({buf}, {first} [, {last}])
142 Number delete lines from buffer {buf}
143did_filetype() Number |TRUE| if FileType autocmd event used
144diff_filler({lnum}) Number diff filler lines about {lnum}
145diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
146digraph_get({chars}) String get the |digraph| of {chars}
147digraph_getlist([{listall}]) List get all |digraph|s
148digraph_set({chars}, {digraph}) Boolean register |digraph|
149digraph_setlist({digraphlist}) Boolean register multiple |digraph|s
150echoraw({expr}) none output {expr} as-is
151empty({expr}) Number |TRUE| if {expr} is empty
152environ() Dict return environment variables
153escape({string}, {chars}) String escape {chars} in {string} with '\'
154eval({string}) any evaluate {string} into its value
155eventhandler() Number |TRUE| if inside an event handler
156executable({expr}) Number 1 if executable {expr} exists
157execute({command}) String execute {command} and get the output
158exepath({expr}) String full path of the command {expr}
159exists({expr}) Number |TRUE| if {expr} exists
160exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
161exp({expr}) Float exponential of {expr}
162expand({expr} [, {nosuf} [, {list}]])
163 any expand special keywords in {expr}
164expandcmd({expr}) String expand {expr} like with `:edit`
165extend({expr1}, {expr2} [, {expr3}])
166 List/Dict insert items of {expr2} into {expr1}
167extendnew({expr1}, {expr2} [, {expr3}])
168 List/Dict like |extend()| but creates a new
169 List or Dictionary
170feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
171filereadable({file}) Number |TRUE| if {file} is a readable file
172filewritable({file}) Number |TRUE| if {file} is a writable file
173filter({expr1}, {expr2}) List/Dict/Blob/String
174 remove items from {expr1} where
175 {expr2} is 0
176finddir({name} [, {path} [, {count}]])
177 String find directory {name} in {path}
178findfile({name} [, {path} [, {count}]])
179 String find file {name} in {path}
180flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
181flattennew({list} [, {maxdepth}])
182 List flatten a copy of {list}
183float2nr({expr}) Number convert Float {expr} to a Number
184floor({expr}) Float round {expr} down
185fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
186fnameescape({fname}) String escape special characters in {fname}
187fnamemodify({fname}, {mods}) String modify file name
188foldclosed({lnum}) Number first line of fold at {lnum} if closed
189foldclosedend({lnum}) Number last line of fold at {lnum} if closed
190foldlevel({lnum}) Number fold level at {lnum}
191foldtext() String line displayed for closed fold
192foldtextresult({lnum}) String text for closed fold at {lnum}
193foreground() Number bring the Vim window to the foreground
194fullcommand({name}) String get full command from {name}
195funcref({name} [, {arglist}] [, {dict}])
196 Funcref reference to function {name}
197function({name} [, {arglist}] [, {dict}])
198 Funcref named reference to function {name}
199garbagecollect([{atexit}]) none free memory, breaking cyclic references
200get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
201get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
202get({func}, {what}) any get property of funcref/partial {func}
203getbufinfo([{buf}]) List information about buffers
204getbufline({buf}, {lnum} [, {end}])
205 List lines {lnum} to {end} of buffer {buf}
206getbufvar({buf}, {varname} [, {def}])
207 any variable {varname} in buffer {buf}
208getchangelist([{buf}]) List list of change list items
209getchar([expr]) Number or String
210 get one character from the user
211getcharmod() Number modifiers for the last typed character
212getcharpos({expr}) List position of cursor, mark, etc.
213getcharsearch() Dict last character search
214getcharstr([expr]) String get one character from the user
215getcmdline() String return the current command-line
216getcmdpos() Number return cursor position in command-line
217getcmdtype() String return current command-line type
218getcmdwintype() String return current command-line window type
219getcompletion({pat}, {type} [, {filtered}])
220 List list of cmdline completion matches
221getcurpos([{winnr}]) List position of the cursor
222getcursorcharpos([{winnr}]) List character position of the cursor
223getcwd([{winnr} [, {tabnr}]]) String get the current working directory
224getenv({name}) String return environment variable
225getfontname([{name}]) String name of font being used
226getfperm({fname}) String file permissions of file {fname}
227getfsize({fname}) Number size in bytes of file {fname}
228getftime({fname}) Number last modification time of file
229getftype({fname}) String description of type of file {fname}
230getimstatus() Number |TRUE| if the IME status is active
231getjumplist([{winnr} [, {tabnr}]])
232 List list of jump list items
233getline({lnum}) String line {lnum} of current buffer
234getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
235getloclist({nr}) List list of location list items
236getloclist({nr}, {what}) Dict get specific location list properties
237getmarklist([{buf}]) List list of global/local marks
238getmatches([{win}]) List list of current matches
239getmousepos() Dict last known mouse position
240getpid() Number process ID of Vim
241getpos({expr}) List position of cursor, mark, etc.
242getqflist() List list of quickfix items
243getqflist({what}) Dict get specific quickfix list properties
244getreg([{regname} [, 1 [, {list}]]])
245 String or List contents of a register
246getreginfo([{regname}]) Dict information about a register
247getregtype([{regname}]) String type of a register
248gettabinfo([{expr}]) List list of tab pages
249gettabvar({nr}, {varname} [, {def}])
250 any variable {varname} in tab {nr} or {def}
251gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
252 any {name} in {winnr} in tab page {tabnr}
253gettagstack([{nr}]) Dict get the tag stack of window {nr}
254gettext({text}) String lookup translation of {text}
255getwininfo([{winid}]) List list of info about each window
256getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
257getwinposx() Number X coord in pixels of the Vim window
258getwinposy() Number Y coord in pixels of the Vim window
259getwinvar({nr}, {varname} [, {def}])
260 any variable {varname} in window {nr}
261glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
262 any expand file wildcards in {expr}
263glob2regpat({expr}) String convert a glob pat into a search pat
264globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
265 String do glob({expr}) for all dirs in {path}
266has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
267has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
268haslocaldir([{winnr} [, {tabnr}]])
269 Number |TRUE| if the window executed |:lcd|
270 or |:tcd|
271hasmapto({what} [, {mode} [, {abbr}]])
272 Number |TRUE| if mapping to {what} exists
273histadd({history}, {item}) Number add an item to a history
274histdel({history} [, {item}]) Number remove an item from a history
275histget({history} [, {index}]) String get the item {index} from a history
276histnr({history}) Number highest index of a history
277hlID({name}) Number syntax ID of highlight group {name}
278hlexists({name}) Number |TRUE| if highlight group {name} exists
279hlget([{name} [, {resolve}]]) List get highlight group attributes
280hlset({list}) Number set highlight group attributes
281hostname() String name of the machine Vim is running on
282iconv({expr}, {from}, {to}) String convert encoding of {expr}
283indent({lnum}) Number indent of line {lnum}
284index({object}, {expr} [, {start} [, {ic}]])
285 Number index in {object} where {expr} appears
286input({prompt} [, {text} [, {completion}]])
287 String get input from the user
288inputdialog({prompt} [, {text} [, {completion}]])
289 String like input() but in a GUI dialog
290inputlist({textlist}) Number let the user pick from a choice list
291inputrestore() Number restore typeahead
292inputsave() Number save and clear typeahead
293inputsecret({prompt} [, {text}]) String like input() but hiding the text
294insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
295interrupt() none interrupt script execution
296invert({expr}) Number bitwise invert
297isdirectory({directory}) Number |TRUE| if {directory} is a directory
298isinf({expr}) Number determine if {expr} is infinity value
299 (positive or negative)
300islocked({expr}) Number |TRUE| if {expr} is locked
301isnan({expr}) Number |TRUE| if {expr} is NaN
302items({dict}) List key-value pairs in {dict}
303job_getchannel({job}) Channel get the channel handle for {job}
304job_info([{job}]) Dict get information about {job}
305job_setoptions({job}, {options}) none set options for {job}
306job_start({command} [, {options}])
307 Job start a job
308job_status({job}) String get the status of {job}
309job_stop({job} [, {how}]) Number stop {job}
310join({list} [, {sep}]) String join {list} items into one String
311js_decode({string}) any decode JS style JSON
312js_encode({expr}) String encode JS style JSON
313json_decode({string}) any decode JSON
314json_encode({expr}) String encode JSON
315keys({dict}) List keys in {dict}
316len({expr}) Number the length of {expr}
317libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
318libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
319line({expr} [, {winid}]) Number line nr of cursor, last line or mark
320line2byte({lnum}) Number byte count of line {lnum}
321lispindent({lnum}) Number Lisp indent for line {lnum}
322list2blob({list}) Blob turn {list} of numbers into a Blob
323list2str({list} [, {utf8}]) String turn {list} of numbers into a String
324listener_add({callback} [, {buf}])
325 Number add a callback to listen to changes
326listener_flush([{buf}]) none invoke listener callbacks
327listener_remove({id}) none remove a listener callback
328localtime() Number current time
329log({expr}) Float natural logarithm (base e) of {expr}
330log10({expr}) Float logarithm of Float {expr} to base 10
331luaeval({expr} [, {expr}]) any evaluate |Lua| expression
332map({expr1}, {expr2}) List/Dict/Blob/String
333 change each item in {expr1} to {expr2}
334maparg({name} [, {mode} [, {abbr} [, {dict}]]])
335 String or Dict
336 rhs of mapping {name} in mode {mode}
337mapcheck({name} [, {mode} [, {abbr}]])
338 String check for mappings matching {name}
339mapnew({expr1}, {expr2}) List/Dict/Blob/String
340 like |map()| but creates a new List or
341 Dictionary
342mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
343match({expr}, {pat} [, {start} [, {count}]])
344 Number position where {pat} matches in {expr}
345matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
346 Number highlight {pattern} with {group}
347matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
348 Number highlight positions with {group}
349matcharg({nr}) List arguments of |:match|
350matchdelete({id} [, {win}]) Number delete match identified by {id}
351matchend({expr}, {pat} [, {start} [, {count}]])
352 Number position where {pat} ends in {expr}
353matchfuzzy({list}, {str} [, {dict}])
354 List fuzzy match {str} in {list}
355matchfuzzypos({list}, {str} [, {dict}])
356 List fuzzy match {str} in {list}
357matchlist({expr}, {pat} [, {start} [, {count}]])
358 List match and submatches of {pat} in {expr}
359matchstr({expr}, {pat} [, {start} [, {count}]])
360 String {count}'th match of {pat} in {expr}
361matchstrpos({expr}, {pat} [, {start} [, {count}]])
362 List {count}'th match of {pat} in {expr}
363max({expr}) Number maximum value of items in {expr}
364menu_info({name} [, {mode}]) Dict get menu item information
365min({expr}) Number minimum value of items in {expr}
366mkdir({name} [, {path} [, {prot}]])
367 Number create directory {name}
368mode([expr]) String current editing mode
369mzeval({expr}) any evaluate |MzScheme| expression
370nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
371nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
372or({expr}, {expr}) Number bitwise OR
373pathshorten({expr} [, {len}]) String shorten directory names in a path
374perleval({expr}) any evaluate |Perl| expression
375popup_atcursor({what}, {options}) Number create popup window near the cursor
376popup_beval({what}, {options}) Number create popup window for 'ballooneval'
377popup_clear() none close all popup windows
378popup_close({id} [, {result}]) none close popup window {id}
379popup_create({what}, {options}) Number create a popup window
380popup_dialog({what}, {options}) Number create a popup window used as a dialog
381popup_filter_menu({id}, {key}) Number filter for a menu popup window
382popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
383popup_findinfo() Number get window ID of info popup window
384popup_findpreview() Number get window ID of preview popup window
385popup_getoptions({id}) Dict get options of popup window {id}
386popup_getpos({id}) Dict get position of popup window {id}
387popup_hide({id}) none hide popup menu {id}
388popup_list() List get a list of window IDs of all popups
389popup_locate({row}, {col}) Number get window ID of popup at position
390popup_menu({what}, {options}) Number create a popup window used as a menu
391popup_move({id}, {options}) none set position of popup window {id}
392popup_notification({what}, {options})
393 Number create a notification popup window
394popup_setoptions({id}, {options})
395 none set options for popup window {id}
396popup_settext({id}, {text}) none set the text of popup window {id}
397popup_show({id}) none unhide popup window {id}
398pow({x}, {y}) Float {x} to the power of {y}
399prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
400printf({fmt}, {expr1}...) String format text
401prompt_getprompt({buf}) String get prompt text
402prompt_setcallback({buf}, {expr}) none set prompt callback function
403prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
404prompt_setprompt({buf}, {text}) none set prompt text
405prop_add({lnum}, {col}, {props}) none add one text property
406prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
407 none add multiple text properties
408prop_clear({lnum} [, {lnum-end} [, {props}]])
409 none remove all text properties
410prop_find({props} [, {direction}])
411 Dict search for a text property
412prop_list({lnum} [, {props}]) List text properties in {lnum}
413prop_remove({props} [, {lnum} [, {lnum-end}]])
414 Number remove a text property
415prop_type_add({name}, {props}) none define a new property type
416prop_type_change({name}, {props})
417 none change an existing property type
418prop_type_delete({name} [, {props}])
419 none delete a property type
420prop_type_get({name} [, {props}])
421 Dict get property type values
422prop_type_list([{props}]) List get list of property types
423pum_getpos() Dict position and size of pum if visible
424pumvisible() Number whether popup menu is visible
425py3eval({expr}) any evaluate |python3| expression
426pyeval({expr}) any evaluate |Python| expression
427pyxeval({expr}) any evaluate |python_x| expression
428rand([{expr}]) Number get pseudo-random number
429range({expr} [, {max} [, {stride}]])
430 List items from {expr} to {max}
431readblob({fname}) Blob read a |Blob| from {fname}
432readdir({dir} [, {expr} [, {dict}]])
433 List file names in {dir} selected by {expr}
434readdirex({dir} [, {expr} [, {dict}]])
435 List file info in {dir} selected by {expr}
436readfile({fname} [, {type} [, {max}]])
437 List get list of lines from file {fname}
438reduce({object}, {func} [, {initial}])
439 any reduce {object} using {func}
440reg_executing() String get the executing register name
441reg_recording() String get the recording register name
442reltime([{start} [, {end}]]) List get time value
443reltimefloat({time}) Float turn the time value into a Float
444reltimestr({time}) String turn time value into a String
445remote_expr({server}, {string} [, {idvar} [, {timeout}]])
446 String send expression
447remote_foreground({server}) Number bring Vim server to the foreground
448remote_peek({serverid} [, {retvar}])
449 Number check for reply string
450remote_read({serverid} [, {timeout}])
451 String read reply string
452remote_send({server}, {string} [, {idvar}])
453 String send key sequence
454remote_startserver({name}) none become server {name}
455remove({list}, {idx} [, {end}]) any/List
456 remove items {idx}-{end} from {list}
457remove({blob}, {idx} [, {end}]) Number/Blob
458 remove bytes {idx}-{end} from {blob}
459remove({dict}, {key}) any remove entry {key} from {dict}
460rename({from}, {to}) Number rename (move) file from {from} to {to}
461repeat({expr}, {count}) String repeat {expr} {count} times
462resolve({filename}) String get filename a shortcut points to
463reverse({list}) List reverse {list} in-place
464round({expr}) Float round off {expr}
465rubyeval({expr}) any evaluate |Ruby| expression
466screenattr({row}, {col}) Number attribute at screen position
467screenchar({row}, {col}) Number character at screen position
468screenchars({row}, {col}) List List of characters at screen position
469screencol() Number current cursor column
470screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
471screenrow() Number current cursor row
472screenstring({row}, {col}) String characters at screen position
473search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
474 Number search for {pattern}
475searchcount([{options}]) Dict get or update search stats
476searchdecl({name} [, {global} [, {thisblock}]])
477 Number search for variable declaration
478searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
479 Number search for other end of start/end pair
480searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
481 List search for other end of start/end pair
482searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
483 List search for {pattern}
484server2client({clientid}, {string})
485 Number send reply string
486serverlist() String get a list of available servers
487setbufline({expr}, {lnum}, {text})
488 Number set line {lnum} to {text} in buffer
489 {expr}
490setbufvar({buf}, {varname}, {val})
491 none set {varname} in buffer {buf} to {val}
492setcellwidths({list}) none set character cell width overrides
493setcharpos({expr}, {list}) Number set the {expr} position to {list}
494setcharsearch({dict}) Dict set character search from {dict}
495setcmdpos({pos}) Number set cursor position in command-line
496setcursorcharpos({list}) Number move cursor to position in {list}
497setenv({name}, {val}) none set environment variable
498setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
499setline({lnum}, {line}) Number set line {lnum} to {line}
500setloclist({nr}, {list} [, {action}])
501 Number modify location list using {list}
502setloclist({nr}, {list}, {action}, {what})
503 Number modify specific location list props
504setmatches({list} [, {win}]) Number restore a list of matches
505setpos({expr}, {list}) Number set the {expr} position to {list}
506setqflist({list} [, {action}]) Number modify quickfix list using {list}
507setqflist({list}, {action}, {what})
508 Number modify specific quickfix list props
509setreg({n}, {v} [, {opt}]) Number set register to value and type
510settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
511settabwinvar({tabnr}, {winnr}, {varname}, {val})
512 none set {varname} in window {winnr} in tab
513 page {tabnr} to {val}
514settagstack({nr}, {dict} [, {action}])
515 Number modify tag stack using {dict}
516setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
517sha256({string}) String SHA256 checksum of {string}
518shellescape({string} [, {special}])
519 String escape {string} for use as shell
520 command argument
521shiftwidth([{col}]) Number effective value of 'shiftwidth'
522sign_define({name} [, {dict}]) Number define or update a sign
523sign_define({list}) List define or update a list of signs
524sign_getdefined([{name}]) List get a list of defined signs
525sign_getplaced([{buf} [, {dict}]])
526 List get a list of placed signs
527sign_jump({id}, {group}, {buf})
528 Number jump to a sign
529sign_place({id}, {group}, {name}, {buf} [, {dict}])
530 Number place a sign
531sign_placelist({list}) List place a list of signs
532sign_undefine([{name}]) Number undefine a sign
533sign_undefine({list}) List undefine a list of signs
534sign_unplace({group} [, {dict}])
535 Number unplace a sign
536sign_unplacelist({list}) List unplace a list of signs
537simplify({filename}) String simplify filename as much as possible
538sin({expr}) Float sine of {expr}
539sinh({expr}) Float hyperbolic sine of {expr}
540slice({expr}, {start} [, {end}]) String, List or Blob
541 slice of a String, List or Blob
542sort({list} [, {func} [, {dict}]])
543 List sort {list}, using {func} to compare
544sound_clear() none stop playing all sounds
545sound_playevent({name} [, {callback}])
546 Number play an event sound
547sound_playfile({path} [, {callback}])
548 Number play sound file {path}
549sound_stop({id}) none stop playing sound {id}
550soundfold({word}) String sound-fold {word}
551spellbadword() String badly spelled word at cursor
552spellsuggest({word} [, {max} [, {capital}]])
553 List spelling suggestions
554split({expr} [, {pat} [, {keepempty}]])
555 List make |List| from {pat} separated {expr}
556sqrt({expr}) Float square root of {expr}
557srand([{expr}]) List get seed for |rand()|
558state([{what}]) String current state of Vim
559str2float({expr} [, {quoted}]) Float convert String to Float
560str2list({expr} [, {utf8}]) List convert each character of {expr} to
561 ASCII/UTF-8 value
562str2nr({expr} [, {base} [, {quoted}]])
563 Number convert String to Number
564strcharlen({expr}) Number character length of the String {expr}
565strcharpart({str}, {start} [, {len} [, {skipcc}]])
566 String {len} characters of {str} at
567 character {start}
568strchars({expr} [, {skipcc}]) Number character count of the String {expr}
569strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
570strftime({format} [, {time}]) String format time with a specified format
571strgetchar({str}, {index}) Number get char {index} from {str}
572stridx({haystack}, {needle} [, {start}])
573 Number index of {needle} in {haystack}
574string({expr}) String String representation of {expr} value
575strlen({expr}) Number length of the String {expr}
576strpart({str}, {start} [, {len} [, {chars}]])
577 String {len} bytes/chars of {str} at
578 byte {start}
579strptime({format}, {timestring})
580 Number Convert {timestring} to unix timestamp
581strridx({haystack}, {needle} [, {start}])
582 Number last index of {needle} in {haystack}
583strtrans({expr}) String translate string to make it printable
584strwidth({expr}) Number display cell length of the String {expr}
585submatch({nr} [, {list}]) String or List
586 specific match in ":s" or substitute()
587substitute({expr}, {pat}, {sub}, {flags})
588 String all {pat} in {expr} replaced with {sub}
589swapinfo({fname}) Dict information about swap file {fname}
590swapname({buf}) String swap file of buffer {buf}
591synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
592synIDattr({synID}, {what} [, {mode}])
593 String attribute {what} of syntax ID {synID}
594synIDtrans({synID}) Number translated syntax ID of {synID}
595synconcealed({lnum}, {col}) List info about concealing
596synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
597system({expr} [, {input}]) String output of shell command/filter {expr}
598systemlist({expr} [, {input}]) List output of shell command/filter {expr}
599tabpagebuflist([{arg}]) List list of buffer numbers in tab page
600tabpagenr([{arg}]) Number number of current or last tab page
601tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
602tagfiles() List tags files used
603taglist({expr} [, {filename}]) List list of tags matching {expr}
604tan({expr}) Float tangent of {expr}
605tanh({expr}) Float hyperbolic tangent of {expr}
606tempname() String name for a temporary file
607term_dumpdiff({filename}, {filename} [, {options}])
608 Number display difference between two dumps
609term_dumpload({filename} [, {options}])
610 Number displaying a screen dump
611term_dumpwrite({buf}, {filename} [, {options}])
612 none dump terminal window contents
613term_getaltscreen({buf}) Number get the alternate screen flag
614term_getansicolors({buf}) List get ANSI palette in GUI color mode
615term_getattr({attr}, {what}) Number get the value of attribute {what}
616term_getcursor({buf}) List get the cursor position of a terminal
617term_getjob({buf}) Job get the job associated with a terminal
618term_getline({buf}, {row}) String get a line of text from a terminal
619term_getscrolled({buf}) Number get the scroll count of a terminal
620term_getsize({buf}) List get the size of a terminal
621term_getstatus({buf}) String get the status of a terminal
622term_gettitle({buf}) String get the title of a terminal
623term_gettty({buf}, [{input}]) String get the tty name of a terminal
624term_list() List get the list of terminal buffers
625term_scrape({buf}, {row}) List get row of a terminal screen
626term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
627term_setansicolors({buf}, {colors})
628 none set ANSI palette in GUI color mode
629term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
630term_setkill({buf}, {how}) none set signal to stop job in terminal
631term_setrestore({buf}, {command}) none set command to restore terminal
632term_setsize({buf}, {rows}, {cols})
633 none set the size of a terminal
634term_start({cmd} [, {options}]) Number open a terminal window and run a job
635term_wait({buf} [, {time}]) Number wait for screen to be updated
636terminalprops() Dict properties of the terminal
637test_alloc_fail({id}, {countdown}, {repeat})
638 none make memory allocation fail
639test_autochdir() none enable 'autochdir' during startup
640test_feedinput({string}) none add key sequence to input buffer
641test_garbagecollect_now() none free memory right now for testing
642test_garbagecollect_soon() none free memory soon for testing
643test_getvalue({string}) any get value of an internal variable
644test_gui_drop_files({list}, {row}, {col}, {mods})
645 none drop a list of files in a window
646test_gui_mouse_event({button}, {row}, {col}, {repeated}, {mods})
647 none add a mouse event to the input buffer
648test_ignore_error({expr}) none ignore a specific error
649test_null_blob() Blob null value for testing
650test_null_channel() Channel null value for testing
651test_null_dict() Dict null value for testing
652test_null_function() Funcref null value for testing
653test_null_job() Job null value for testing
654test_null_list() List null value for testing
655test_null_partial() Funcref null value for testing
656test_null_string() String null value for testing
657test_option_not_set({name}) none reset flag indicating option was set
658test_override({expr}, {val}) none test with Vim internal overrides
659test_refcount({expr}) Number get the reference count of {expr}
660test_scrollbar({which}, {value}, {dragging})
661 none scroll in the GUI for testing
662test_setmouse({row}, {col}) none set the mouse position for testing
663test_settime({expr}) none set current time for testing
664test_srand_seed([seed]) none set seed for testing srand()
665test_unknown() any unknown value for testing
666test_void() any void value for testing
667timer_info([{id}]) List information about timers
668timer_pause({id}, {pause}) none pause or unpause a timer
669timer_start({time}, {callback} [, {options}])
670 Number create a timer
671timer_stop({timer}) none stop a timer
672timer_stopall() none stop all timers
673tolower({expr}) String the String {expr} switched to lowercase
674toupper({expr}) String the String {expr} switched to uppercase
675tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
676 to chars in {tostr}
677trim({text} [, {mask} [, {dir}]])
678 String trim characters in {mask} from {text}
679trunc({expr}) Float truncate Float {expr}
680type({expr}) Number type of value {expr}
681typename({expr}) String representation of the type of {expr}
682undofile({name}) String undo file name for {name}
683undotree() List undo file tree
684uniq({list} [, {func} [, {dict}]])
685 List remove adjacent duplicates from a list
686values({dict}) List values in {dict}
687virtcol({expr}) Number screen column of cursor or mark
688visualmode([expr]) String last visual mode used
689wildmenumode() Number whether 'wildmenu' mode is active
690win_execute({id}, {command} [, {silent}])
691 String execute {command} in window {id}
692win_findbuf({bufnr}) List find windows containing {bufnr}
693win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
694win_gettype([{nr}]) String type of window {nr}
695win_gotoid({expr}) Number go to window with ID {expr}
696win_id2tabwin({expr}) List get tab and window nr from window ID
697win_id2win({expr}) Number get window nr from window ID
698win_screenpos({nr}) List get screen position of window {nr}
699win_splitmove({nr}, {target} [, {options}])
700 Number move window {nr} to split of {target}
701winbufnr({nr}) Number buffer number of window {nr}
702wincol() Number window column of the cursor
703windowsversion() String MS-Windows OS version
704winheight({nr}) Number height of window {nr}
705winlayout([{tabnr}]) List layout of windows in tab {tabnr}
706winline() Number window line of the cursor
707winnr([{expr}]) Number number of current window
708winrestcmd() String returns command to restore window sizes
709winrestview({dict}) none restore view of current window
710winsaveview() Dict save view of current window
711winwidth({nr}) Number width of window {nr}
712wordcount() Dict get byte/char/word statistics
713writefile({object}, {fname} [, {flags}])
714 Number write |Blob| or |List| of lines to file
715xor({expr}, {expr}) Number bitwise XOR
716
717==============================================================================
7182. Details *builtin-function-details*
719
720Not all functions are here, some have been moved to a help file covering the
721specific functionality.
722
723abs({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
742acos({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
759add({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
773and({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
782append({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
801appendbufline({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
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000809 {lnum} is the line number to append below. Note that using
810 |line()| would use the current buffer, not the one appending
811 to. Use "$" to append at the end of the buffer. Other string
812 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000813
814 On success 0 is returned, on failure 1 is returned.
815 In |Vim9| script an error is given for an invalid {lnum}.
816
817 If {buf} is not a valid buffer or {lnum} is not valid, an
818 error message is given. Example: >
819 :let failed = appendbufline(13, 0, "# THE START")
820<
821 Can also be used as a |method| after a List, the base is
822 passed as the second argument: >
823 mylist->appendbufline(buf, lnum)
824
825
826argc([{winid}]) *argc()*
827 The result is the number of files in the argument list. See
828 |arglist|.
829 If {winid} is not supplied, the argument list of the current
830 window is used.
831 If {winid} is -1, the global argument list is used.
832 Otherwise {winid} specifies the window of which the argument
833 list is used: either the window number or the window ID.
834 Returns -1 if the {winid} argument is invalid.
835
836 *argidx()*
837argidx() The result is the current index in the argument list. 0 is
838 the first file. argc() - 1 is the last one. See |arglist|.
839
840 *arglistid()*
841arglistid([{winnr} [, {tabnr}]])
842 Return the argument list ID. This is a number which
843 identifies the argument list being used. Zero is used for the
844 global argument list. See |arglist|.
845 Returns -1 if the arguments are invalid.
846
847 Without arguments use the current window.
848 With {winnr} only use this window in the current tab page.
849 With {winnr} and {tabnr} use the window in the specified tab
850 page.
851 {winnr} can be the window number or the |window-ID|.
852
853 *argv()*
854argv([{nr} [, {winid}]])
855 The result is the {nr}th file in the argument list. See
856 |arglist|. "argv(0)" is the first one. Example: >
857 :let i = 0
858 :while i < argc()
859 : let f = escape(fnameescape(argv(i)), '.')
860 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
861 : let i = i + 1
862 :endwhile
863< Without the {nr} argument, or when {nr} is -1, a |List| with
864 the whole |arglist| is returned.
865
866 The {winid} argument specifies the window ID, see |argc()|.
867 For the Vim command line arguments see |v:argv|.
868
869asin({expr}) *asin()*
870 Return the arc sine of {expr} measured in radians, as a |Float|
871 in the range of [-pi/2, pi/2].
872 {expr} must evaluate to a |Float| or a |Number| in the range
873 [-1, 1].
874 Examples: >
875 :echo asin(0.8)
876< 0.927295 >
877 :echo asin(-0.5)
878< -0.523599
879
880 Can also be used as a |method|: >
881 Compute()->asin()
882<
883 {only available when compiled with the |+float| feature}
884
885
886assert_ functions are documented here: |assert-functions-details|
887
888
889
890atan({expr}) *atan()*
891 Return the principal value of the arc tangent of {expr}, in
892 the range [-pi/2, +pi/2] radians, as a |Float|.
893 {expr} must evaluate to a |Float| or a |Number|.
894 Examples: >
895 :echo atan(100)
896< 1.560797 >
897 :echo atan(-4.01)
898< -1.326405
899
900 Can also be used as a |method|: >
901 Compute()->atan()
902<
903 {only available when compiled with the |+float| feature}
904
905
906atan2({expr1}, {expr2}) *atan2()*
907 Return the arc tangent of {expr1} / {expr2}, measured in
908 radians, as a |Float| in the range [-pi, pi].
909 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
910 Examples: >
911 :echo atan2(-1, 1)
912< -0.785398 >
913 :echo atan2(1, -1)
914< 2.356194
915
916 Can also be used as a |method|: >
917 Compute()->atan2(1)
918<
919 {only available when compiled with the |+float| feature}
920
921balloon_gettext() *balloon_gettext()*
922 Return the current text in the balloon. Only for the string,
923 not used for the List.
924
925balloon_show({expr}) *balloon_show()*
926 Show {expr} inside the balloon. For the GUI {expr} is used as
927 a string. For a terminal {expr} can be a list, which contains
928 the lines of the balloon. If {expr} is not a list it will be
929 split with |balloon_split()|.
930 If {expr} is an empty string any existing balloon is removed.
931
932 Example: >
933 func GetBalloonContent()
934 " ... initiate getting the content
935 return ''
936 endfunc
937 set balloonexpr=GetBalloonContent()
938
939 func BalloonCallback(result)
940 call balloon_show(a:result)
941 endfunc
942< Can also be used as a |method|: >
943 GetText()->balloon_show()
944<
945 The intended use is that fetching the content of the balloon
946 is initiated from 'balloonexpr'. It will invoke an
947 asynchronous method, in which a callback invokes
948 balloon_show(). The 'balloonexpr' itself can return an
949 empty string or a placeholder.
950
951 When showing a balloon is not possible nothing happens, no
952 error message.
953 {only available when compiled with the |+balloon_eval| or
954 |+balloon_eval_term| feature}
955
956balloon_split({msg}) *balloon_split()*
957 Split String {msg} into lines to be displayed in a balloon.
958 The splits are made for the current window size and optimize
959 to show debugger output.
960 Returns a |List| with the split lines.
961 Can also be used as a |method|: >
962 GetText()->balloon_split()->balloon_show()
963
964< {only available when compiled with the |+balloon_eval_term|
965 feature}
966
967blob2list({blob}) *blob2list()*
968 Return a List containing the number value of each byte in Blob
969 {blob}. Examples: >
970 blob2list(0z0102.0304) returns [1, 2, 3, 4]
971 blob2list(0z) returns []
972< Returns an empty List on error. |list2blob()| does the
973 opposite.
974
975 Can also be used as a |method|: >
976 GetBlob()->blob2list()
977
978 *browse()*
979browse({save}, {title}, {initdir}, {default})
980 Put up a file requester. This only works when "has("browse")"
981 returns |TRUE| (only in some GUI versions).
982 The input fields are:
983 {save} when |TRUE|, select file to write
984 {title} title for the requester
985 {initdir} directory to start browsing in
986 {default} default file name
987 An empty string is returned when the "Cancel" button is hit,
988 something went wrong, or browsing is not possible.
989
990 *browsedir()*
991browsedir({title}, {initdir})
992 Put up a directory requester. This only works when
993 "has("browse")" returns |TRUE| (only in some GUI versions).
994 On systems where a directory browser is not supported a file
995 browser is used. In that case: select a file in the directory
996 to be used.
997 The input fields are:
998 {title} title for the requester
999 {initdir} directory to start browsing in
1000 When the "Cancel" button is hit, something went wrong, or
1001 browsing is not possible, an empty string is returned.
1002
1003bufadd({name}) *bufadd()*
1004 Add a buffer to the buffer list with String {name}.
1005 If a buffer for file {name} already exists, return that buffer
1006 number. Otherwise return the buffer number of the newly
1007 created buffer. When {name} is an empty string then a new
1008 buffer is always created.
1009 The buffer will not have 'buflisted' set and not be loaded
1010 yet. To add some text to the buffer use this: >
1011 let bufnr = bufadd('someName')
1012 call bufload(bufnr)
1013 call setbufline(bufnr, 1, ['some', 'text'])
1014< Can also be used as a |method|: >
1015 let bufnr = 'somename'->bufadd()
1016
1017bufexists({buf}) *bufexists()*
1018 The result is a Number, which is |TRUE| if a buffer called
1019 {buf} exists.
1020 If the {buf} argument is a number, buffer numbers are used.
1021 Number zero is the alternate buffer for the current window.
1022
1023 If the {buf} argument is a string it must match a buffer name
1024 exactly. The name can be:
1025 - Relative to the current directory.
1026 - A full path.
1027 - The name of a buffer with 'buftype' set to "nofile".
1028 - A URL name.
1029 Unlisted buffers will be found.
1030 Note that help files are listed by their short name in the
1031 output of |:buffers|, but bufexists() requires using their
1032 long name to be able to find them.
1033 bufexists() may report a buffer exists, but to use the name
1034 with a |:buffer| command you may need to use |expand()|. Esp
1035 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1036 Use "bufexists(0)" to test for the existence of an alternate
1037 file name.
1038
1039 Can also be used as a |method|: >
1040 let exists = 'somename'->bufexists()
1041<
1042 Obsolete name: buffer_exists(). *buffer_exists()*
1043
1044buflisted({buf}) *buflisted()*
1045 The result is a Number, which is |TRUE| if a buffer called
1046 {buf} exists and is listed (has the 'buflisted' option set).
1047 The {buf} argument is used like with |bufexists()|.
1048
1049 Can also be used as a |method|: >
1050 let listed = 'somename'->buflisted()
1051
1052bufload({buf}) *bufload()*
1053 Ensure the buffer {buf} is loaded. When the buffer name
1054 refers to an existing file then the file is read. Otherwise
1055 the buffer will be empty. If the buffer was already loaded
1056 then there is no change.
1057 If there is an existing swap file for the file of the buffer,
1058 there will be no dialog, the buffer will be loaded anyway.
1059 The {buf} argument is used like with |bufexists()|.
1060
1061 Can also be used as a |method|: >
1062 eval 'somename'->bufload()
1063
1064bufloaded({buf}) *bufloaded()*
1065 The result is a Number, which is |TRUE| if a buffer called
1066 {buf} exists and is loaded (shown in a window or hidden).
1067 The {buf} argument is used like with |bufexists()|.
1068
1069 Can also be used as a |method|: >
1070 let loaded = 'somename'->bufloaded()
1071
1072bufname([{buf}]) *bufname()*
1073 The result is the name of a buffer. Mostly as it is displayed
1074 by the `:ls` command, but not using special names such as
1075 "[No Name]".
1076 If {buf} is omitted the current buffer is used.
1077 If {buf} is a Number, that buffer number's name is given.
1078 Number zero is the alternate buffer for the current window.
1079 If {buf} is a String, it is used as a |file-pattern| to match
1080 with the buffer names. This is always done like 'magic' is
1081 set and 'cpoptions' is empty. When there is more than one
1082 match an empty string is returned.
1083 "" or "%" can be used for the current buffer, "#" for the
1084 alternate buffer.
1085 A full match is preferred, otherwise a match at the start, end
1086 or middle of the buffer name is accepted. If you only want a
1087 full match then put "^" at the start and "$" at the end of the
1088 pattern.
1089 Listed buffers are found first. If there is a single match
1090 with a listed buffer, that one is returned. Next unlisted
1091 buffers are searched for.
1092 If the {buf} is a String, but you want to use it as a buffer
1093 number, force it to be a Number by adding zero to it: >
1094 :echo bufname("3" + 0)
1095< Can also be used as a |method|: >
1096 echo bufnr->bufname()
1097
1098< If the buffer doesn't exist, or doesn't have a name, an empty
1099 string is returned. >
1100 bufname("#") alternate buffer name
1101 bufname(3) name of buffer 3
1102 bufname("%") name of current buffer
1103 bufname("file2") name of buffer where "file2" matches.
1104< *buffer_name()*
1105 Obsolete name: buffer_name().
1106
1107 *bufnr()*
1108bufnr([{buf} [, {create}]])
1109 The result is the number of a buffer, as it is displayed by
1110 the `:ls` command. For the use of {buf}, see |bufname()|
1111 above.
1112
1113 If the buffer doesn't exist, -1 is returned. Or, if the
1114 {create} argument is present and TRUE, a new, unlisted,
1115 buffer is created and its number is returned. Example: >
1116 let newbuf = bufnr('Scratch001', 1)
1117< Using an empty name uses the current buffer. To create a new
1118 buffer with an empty name use |bufadd()|.
1119
1120 bufnr("$") is the last buffer: >
1121 :let last_buffer = bufnr("$")
1122< The result is a Number, which is the highest buffer number
1123 of existing buffers. Note that not all buffers with a smaller
1124 number necessarily exist, because ":bwipeout" may have removed
1125 them. Use bufexists() to test for the existence of a buffer.
1126
1127 Can also be used as a |method|: >
1128 echo bufref->bufnr()
1129<
1130 Obsolete name: buffer_number(). *buffer_number()*
1131 *last_buffer_nr()*
1132 Obsolete name for bufnr("$"): last_buffer_nr().
1133
1134bufwinid({buf}) *bufwinid()*
1135 The result is a Number, which is the |window-ID| of the first
1136 window associated with buffer {buf}. For the use of {buf},
1137 see |bufname()| above. If buffer {buf} doesn't exist or
1138 there is no such window, -1 is returned. Example: >
1139
1140 echo "A window containing buffer 1 is " . (bufwinid(1))
1141<
1142 Only deals with the current tab page.
1143
1144 Can also be used as a |method|: >
1145 FindBuffer()->bufwinid()
1146
1147bufwinnr({buf}) *bufwinnr()*
1148 Like |bufwinid()| but return the window number instead of the
1149 |window-ID|.
1150 If buffer {buf} doesn't exist or there is no such window, -1
1151 is returned. Example: >
1152
1153 echo "A window containing buffer 1 is " . (bufwinnr(1))
1154
1155< The number can be used with |CTRL-W_w| and ":wincmd w"
1156 |:wincmd|.
1157
1158 Can also be used as a |method|: >
1159 FindBuffer()->bufwinnr()
1160
1161byte2line({byte}) *byte2line()*
1162 Return the line number that contains the character at byte
1163 count {byte} in the current buffer. This includes the
1164 end-of-line character, depending on the 'fileformat' option
1165 for the current buffer. The first character has byte count
1166 one.
1167 Also see |line2byte()|, |go| and |:goto|.
1168
1169 Can also be used as a |method|: >
1170 GetOffset()->byte2line()
1171
1172< {not available when compiled without the |+byte_offset|
1173 feature}
1174
1175byteidx({expr}, {nr}) *byteidx()*
1176 Return byte index of the {nr}'th character in the String
1177 {expr}. Use zero for the first character, it then returns
1178 zero.
1179 If there are no multibyte characters the returned value is
1180 equal to {nr}.
1181 Composing characters are not counted separately, their byte
1182 length is added to the preceding base character. See
1183 |byteidxcomp()| below for counting composing characters
1184 separately.
1185 Example : >
1186 echo matchstr(str, ".", byteidx(str, 3))
1187< will display the fourth character. Another way to do the
1188 same: >
1189 let s = strpart(str, byteidx(str, 3))
1190 echo strpart(s, 0, byteidx(s, 1))
1191< Also see |strgetchar()| and |strcharpart()|.
1192
1193 If there are less than {nr} characters -1 is returned.
1194 If there are exactly {nr} characters the length of the string
1195 in bytes is returned.
1196
1197 Can also be used as a |method|: >
1198 GetName()->byteidx(idx)
1199
1200byteidxcomp({expr}, {nr}) *byteidxcomp()*
1201 Like byteidx(), except that a composing character is counted
1202 as a separate character. Example: >
1203 let s = 'e' . nr2char(0x301)
1204 echo byteidx(s, 1)
1205 echo byteidxcomp(s, 1)
1206 echo byteidxcomp(s, 2)
1207< The first and third echo result in 3 ('e' plus composing
1208 character is 3 bytes), the second echo results in 1 ('e' is
1209 one byte).
1210 Only works differently from byteidx() when 'encoding' is set
1211 to a Unicode encoding.
1212
1213 Can also be used as a |method|: >
1214 GetName()->byteidxcomp(idx)
1215
1216call({func}, {arglist} [, {dict}]) *call()* *E699*
1217 Call function {func} with the items in |List| {arglist} as
1218 arguments.
1219 {func} can either be a |Funcref| or the name of a function.
1220 a:firstline and a:lastline are set to the cursor line.
1221 Returns the return value of the called function.
1222 {dict} is for functions with the "dict" attribute. It will be
1223 used to set the local variable "self". |Dictionary-function|
1224
1225 Can also be used as a |method|: >
1226 GetFunc()->call([arg, arg], dict)
1227
1228ceil({expr}) *ceil()*
1229 Return the smallest integral value greater than or equal to
1230 {expr} as a |Float| (round up).
1231 {expr} must evaluate to a |Float| or a |Number|.
1232 Examples: >
1233 echo ceil(1.456)
1234< 2.0 >
1235 echo ceil(-5.456)
1236< -5.0 >
1237 echo ceil(4.0)
1238< 4.0
1239
1240 Can also be used as a |method|: >
1241 Compute()->ceil()
1242<
1243 {only available when compiled with the |+float| feature}
1244
1245
1246ch_ functions are documented here: |channel-functions-details|
1247
1248
1249changenr() *changenr()*
1250 Return the number of the most recent change. This is the same
1251 number as what is displayed with |:undolist| and can be used
1252 with the |:undo| command.
1253 When a change was made it is the number of that change. After
1254 redo it is the number of the redone change. After undo it is
1255 one less than the number of the undone change.
1256
1257char2nr({string} [, {utf8}]) *char2nr()*
1258 Return number value of the first char in {string}.
1259 Examples: >
1260 char2nr(" ") returns 32
1261 char2nr("ABC") returns 65
1262< When {utf8} is omitted or zero, the current 'encoding' is used.
1263 Example for "utf-8": >
1264 char2nr("á") returns 225
1265 char2nr("á"[0]) returns 195
1266< When {utf8} is TRUE, always treat as UTF-8 characters.
1267 A combining character is a separate character.
1268 |nr2char()| does the opposite.
1269 To turn a string into a list of character numbers: >
1270 let str = "ABC"
1271 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1272< Result: [65, 66, 67]
1273
1274 Can also be used as a |method|: >
1275 GetChar()->char2nr()
1276
1277
1278charclass({string}) *charclass()*
1279 Return the character class of the first character in {string}.
1280 The character class is one of:
1281 0 blank
1282 1 punctuation
1283 2 word character
1284 3 emoji
1285 other specific Unicode class
1286 The class is used in patterns and word motions.
1287
1288
1289charcol({expr}) *charcol()*
1290 Same as |col()| but returns the character index of the column
1291 position given with {expr} instead of the byte position.
1292
1293 Example:
1294 With the cursor on '세' in line 5 with text "여보세요": >
1295 charcol('.') returns 3
1296 col('.') returns 7
1297
1298< Can also be used as a |method|: >
1299 GetPos()->col()
1300<
1301 *charidx()*
1302charidx({string}, {idx} [, {countcc}])
1303 Return the character index of the byte at {idx} in {string}.
1304 The index of the first character is zero.
1305 If there are no multibyte characters the returned value is
1306 equal to {idx}.
1307 When {countcc} is omitted or |FALSE|, then composing characters
1308 are not counted separately, their byte length is
1309 added to the preceding base character.
1310 When {countcc} is |TRUE|, then composing characters are
1311 counted as separate characters.
1312 Returns -1 if the arguments are invalid or if {idx} is greater
1313 than the index of the last byte in {string}. An error is
1314 given if the first argument is not a string, the second
1315 argument is not a number or when the third argument is present
1316 and is not zero or one.
1317 See |byteidx()| and |byteidxcomp()| for getting the byte index
1318 from the character index.
1319 Examples: >
1320 echo charidx('áb́ć', 3) returns 1
1321 echo charidx('áb́ć', 6, 1) returns 4
1322 echo charidx('áb́ć', 16) returns -1
1323<
1324 Can also be used as a |method|: >
1325 GetName()->charidx(idx)
1326
1327chdir({dir}) *chdir()*
1328 Change the current working directory to {dir}. The scope of
1329 the directory change depends on the directory of the current
1330 window:
1331 - If the current window has a window-local directory
1332 (|:lcd|), then changes the window local directory.
1333 - Otherwise, if the current tabpage has a local
1334 directory (|:tcd|) then changes the tabpage local
1335 directory.
1336 - Otherwise, changes the global directory.
1337 {dir} must be a String.
1338 If successful, returns the previous working directory. Pass
1339 this to another chdir() to restore the directory.
1340 On failure, returns an empty string.
1341
1342 Example: >
1343 let save_dir = chdir(newdir)
1344 if save_dir != ""
1345 " ... do some work
1346 call chdir(save_dir)
1347 endif
1348
1349< Can also be used as a |method|: >
1350 GetDir()->chdir()
1351<
1352cindent({lnum}) *cindent()*
1353 Get the amount of indent for line {lnum} according the C
1354 indenting rules, as with 'cindent'.
1355 The indent is counted in spaces, the value of 'tabstop' is
1356 relevant. {lnum} is used just like in |getline()|.
1357 When {lnum} is invalid or Vim was not compiled the |+cindent|
1358 feature, -1 is returned.
1359 See |C-indenting|.
1360
1361 Can also be used as a |method|: >
1362 GetLnum()->cindent()
1363
1364clearmatches([{win}]) *clearmatches()*
1365 Clears all matches previously defined for the current window
1366 by |matchadd()| and the |:match| commands.
1367 If {win} is specified, use the window with this number or
1368 window ID instead of the current window.
1369
1370 Can also be used as a |method|: >
1371 GetWin()->clearmatches()
1372<
1373 *col()*
1374col({expr}) The result is a Number, which is the byte index of the column
1375 position given with {expr}. The accepted positions are:
1376 . the cursor position
1377 $ the end of the cursor line (the result is the
1378 number of bytes in the cursor line plus one)
1379 'x position of mark x (if the mark is not set, 0 is
1380 returned)
1381 v In Visual mode: the start of the Visual area (the
1382 cursor is the end). When not in Visual mode
1383 returns the cursor position. Differs from |'<| in
1384 that it's updated right away.
1385 Additionally {expr} can be [lnum, col]: a |List| with the line
1386 and column number. Most useful when the column is "$", to get
1387 the last column of a specific line. When "lnum" or "col" is
1388 out of range then col() returns zero.
1389 To get the line number use |line()|. To get both use
1390 |getpos()|.
1391 For the screen column position use |virtcol()|. For the
1392 character position use |charcol()|.
1393 Note that only marks in the current file can be used.
1394 Examples: >
1395 col(".") column of cursor
1396 col("$") length of cursor line plus one
1397 col("'t") column of mark t
1398 col("'" . markname) column of mark markname
1399< The first column is 1. 0 is returned for an error.
1400 For an uppercase mark the column may actually be in another
1401 buffer.
1402 For the cursor position, when 'virtualedit' is active, the
1403 column is one higher if the cursor is after the end of the
1404 line. This can be used to obtain the column in Insert mode: >
1405 :imap <F2> <C-O>:let save_ve = &ve<CR>
1406 \<C-O>:set ve=all<CR>
1407 \<C-O>:echo col(".") . "\n" <Bar>
1408 \let &ve = save_ve<CR>
1409
1410< Can also be used as a |method|: >
1411 GetPos()->col()
1412<
1413
1414complete({startcol}, {matches}) *complete()* *E785*
1415 Set the matches for Insert mode completion.
1416 Can only be used in Insert mode. You need to use a mapping
1417 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1418 or with an expression mapping.
1419 {startcol} is the byte offset in the line where the completed
1420 text start. The text up to the cursor is the original text
1421 that will be replaced by the matches. Use col('.') for an
1422 empty string. "col('.') - 1" will replace one character by a
1423 match.
1424 {matches} must be a |List|. Each |List| item is one match.
1425 See |complete-items| for the kind of items that are possible.
1426 "longest" in 'completeopt' is ignored.
1427 Note that the after calling this function you need to avoid
1428 inserting anything that would cause completion to stop.
1429 The match can be selected with CTRL-N and CTRL-P as usual with
1430 Insert mode completion. The popup menu will appear if
1431 specified, see |ins-completion-menu|.
1432 Example: >
1433 inoremap <F5> <C-R>=ListMonths()<CR>
1434
1435 func! ListMonths()
1436 call complete(col('.'), ['January', 'February', 'March',
1437 \ 'April', 'May', 'June', 'July', 'August', 'September',
1438 \ 'October', 'November', 'December'])
1439 return ''
1440 endfunc
1441< This isn't very useful, but it shows how it works. Note that
1442 an empty string is returned to avoid a zero being inserted.
1443
1444 Can also be used as a |method|, the base is passed as the
1445 second argument: >
1446 GetMatches()->complete(col('.'))
1447
1448complete_add({expr}) *complete_add()*
1449 Add {expr} to the list of matches. Only to be used by the
1450 function specified with the 'completefunc' option.
1451 Returns 0 for failure (empty string or out of memory),
1452 1 when the match was added, 2 when the match was already in
1453 the list.
1454 See |complete-functions| for an explanation of {expr}. It is
1455 the same as one item in the list that 'omnifunc' would return.
1456
1457 Can also be used as a |method|: >
1458 GetMoreMatches()->complete_add()
1459
1460complete_check() *complete_check()*
1461 Check for a key typed while looking for completion matches.
1462 This is to be used when looking for matches takes some time.
1463 Returns |TRUE| when searching for matches is to be aborted,
1464 zero otherwise.
1465 Only to be used by the function specified with the
1466 'completefunc' option.
1467
1468
1469complete_info([{what}]) *complete_info()*
1470 Returns a |Dictionary| with information about Insert mode
1471 completion. See |ins-completion|.
1472 The items are:
1473 mode Current completion mode name string.
1474 See |complete_info_mode| for the values.
1475 pum_visible |TRUE| if popup menu is visible.
1476 See |pumvisible()|.
1477 items List of completion matches. Each item is a
1478 dictionary containing the entries "word",
1479 "abbr", "menu", "kind", "info" and "user_data".
1480 See |complete-items|.
1481 selected Selected item index. First index is zero.
1482 Index is -1 if no item is selected (showing
1483 typed text only, or the last completion after
1484 no item is selected when using the <Up> or
1485 <Down> keys)
1486 inserted Inserted string. [NOT IMPLEMENT YET]
1487
1488 *complete_info_mode*
1489 mode values are:
1490 "" Not in completion mode
1491 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1492 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1493 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1494 |i_CTRL-X_CTRL-Y|
1495 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1496 "files" File names |i_CTRL-X_CTRL-F|
1497 "tags" Tags |i_CTRL-X_CTRL-]|
1498 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1499 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1500 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1501 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1502 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1503 "function" User defined completion |i_CTRL-X_CTRL-U|
1504 "omni" Omni completion |i_CTRL-X_CTRL-O|
1505 "spell" Spelling suggestions |i_CTRL-X_s|
1506 "eval" |complete()| completion
1507 "unknown" Other internal modes
1508
1509 If the optional {what} list argument is supplied, then only
1510 the items listed in {what} are returned. Unsupported items in
1511 {what} are silently ignored.
1512
1513 To get the position and size of the popup menu, see
1514 |pum_getpos()|. It's also available in |v:event| during the
1515 |CompleteChanged| event.
1516
1517 Examples: >
1518 " Get all items
1519 call complete_info()
1520 " Get only 'mode'
1521 call complete_info(['mode'])
1522 " Get only 'mode' and 'pum_visible'
1523 call complete_info(['mode', 'pum_visible'])
1524
1525< Can also be used as a |method|: >
1526 GetItems()->complete_info()
1527<
1528 *confirm()*
1529confirm({msg} [, {choices} [, {default} [, {type}]]])
1530 confirm() offers the user a dialog, from which a choice can be
1531 made. It returns the number of the choice. For the first
1532 choice this is 1.
1533 Note: confirm() is only supported when compiled with dialog
1534 support, see |+dialog_con| and |+dialog_gui|.
1535
1536 {msg} is displayed in a |dialog| with {choices} as the
1537 alternatives. When {choices} is missing or empty, "&OK" is
1538 used (and translated).
1539 {msg} is a String, use '\n' to include a newline. Only on
1540 some systems the string is wrapped when it doesn't fit.
1541
1542 {choices} is a String, with the individual choices separated
1543 by '\n', e.g. >
1544 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1545< The letter after the '&' is the shortcut key for that choice.
1546 Thus you can type 'c' to select "Cancel". The shortcut does
1547 not need to be the first letter: >
1548 confirm("file has been modified", "&Save\nSave &All")
1549< For the console, the first letter of each choice is used as
1550 the default shortcut key. Case is ignored.
1551
1552 The optional {default} argument is the number of the choice
1553 that is made if the user hits <CR>. Use 1 to make the first
1554 choice the default one. Use 0 to not set a default. If
1555 {default} is omitted, 1 is used.
1556
1557 The optional {type} String argument gives the type of dialog.
1558 This is only used for the icon of the GTK, Mac, Motif and
1559 Win32 GUI. It can be one of these values: "Error",
1560 "Question", "Info", "Warning" or "Generic". Only the first
1561 character is relevant. When {type} is omitted, "Generic" is
1562 used.
1563
1564 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1565 or another valid interrupt key, confirm() returns 0.
1566
1567 An example: >
1568 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
1569 :if choice == 0
1570 : echo "make up your mind!"
1571 :elseif choice == 3
1572 : echo "tasteful"
1573 :else
1574 : echo "I prefer bananas myself."
1575 :endif
1576< In a GUI dialog, buttons are used. The layout of the buttons
1577 depends on the 'v' flag in 'guioptions'. If it is included,
1578 the buttons are always put vertically. Otherwise, confirm()
1579 tries to put the buttons in one horizontal line. If they
1580 don't fit, a vertical layout is used anyway. For some systems
1581 the horizontal layout is always used.
1582
1583 Can also be used as a |method|in: >
1584 BuildMessage()->confirm("&Yes\n&No")
1585<
1586 *copy()*
1587copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1588 different from using {expr} directly.
1589 When {expr} is a |List| a shallow copy is created. This means
1590 that the original |List| can be changed without changing the
1591 copy, and vice versa. But the items are identical, thus
1592 changing an item changes the contents of both |Lists|.
1593 A |Dictionary| is copied in a similar way as a |List|.
1594 Also see |deepcopy()|.
1595 Can also be used as a |method|: >
1596 mylist->copy()
1597
1598cos({expr}) *cos()*
1599 Return the cosine of {expr}, measured in radians, as a |Float|.
1600 {expr} must evaluate to a |Float| or a |Number|.
1601 Examples: >
1602 :echo cos(100)
1603< 0.862319 >
1604 :echo cos(-4.01)
1605< -0.646043
1606
1607 Can also be used as a |method|: >
1608 Compute()->cos()
1609<
1610 {only available when compiled with the |+float| feature}
1611
1612
1613cosh({expr}) *cosh()*
1614 Return the hyperbolic cosine of {expr} as a |Float| in the range
1615 [1, inf].
1616 {expr} must evaluate to a |Float| or a |Number|.
1617 Examples: >
1618 :echo cosh(0.5)
1619< 1.127626 >
1620 :echo cosh(-0.5)
1621< -1.127626
1622
1623 Can also be used as a |method|: >
1624 Compute()->cosh()
1625<
1626 {only available when compiled with the |+float| feature}
1627
1628
1629count({comp}, {expr} [, {ic} [, {start}]]) *count()*
1630 Return the number of times an item with value {expr} appears
1631 in |String|, |List| or |Dictionary| {comp}.
1632
1633 If {start} is given then start with the item with this index.
1634 {start} can only be used with a |List|.
1635
1636 When {ic} is given and it's |TRUE| then case is ignored.
1637
1638 When {comp} is a string then the number of not overlapping
1639 occurrences of {expr} is returned. Zero is returned when
1640 {expr} is an empty string.
1641
1642 Can also be used as a |method|: >
1643 mylist->count(val)
1644<
1645 *cscope_connection()*
1646cscope_connection([{num} , {dbpath} [, {prepend}]])
1647 Checks for the existence of a |cscope| connection. If no
1648 parameters are specified, then the function returns:
1649 0, if cscope was not available (not compiled in), or
1650 if there are no cscope connections;
1651 1, if there is at least one cscope connection.
1652
1653 If parameters are specified, then the value of {num}
1654 determines how existence of a cscope connection is checked:
1655
1656 {num} Description of existence check
1657 ----- ------------------------------
1658 0 Same as no parameters (e.g., "cscope_connection()").
1659 1 Ignore {prepend}, and use partial string matches for
1660 {dbpath}.
1661 2 Ignore {prepend}, and use exact string matches for
1662 {dbpath}.
1663 3 Use {prepend}, use partial string matches for both
1664 {dbpath} and {prepend}.
1665 4 Use {prepend}, use exact string matches for both
1666 {dbpath} and {prepend}.
1667
1668 Note: All string comparisons are case sensitive!
1669
1670 Examples. Suppose we had the following (from ":cs show"): >
1671
1672 # pid database name prepend path
1673 0 27664 cscope.out /usr/local
1674<
1675 Invocation Return Val ~
1676 ---------- ---------- >
1677 cscope_connection() 1
1678 cscope_connection(1, "out") 1
1679 cscope_connection(2, "out") 0
1680 cscope_connection(3, "out") 0
1681 cscope_connection(3, "out", "local") 1
1682 cscope_connection(4, "out") 0
1683 cscope_connection(4, "out", "local") 0
1684 cscope_connection(4, "cscope.out", "/usr/local") 1
1685<
1686cursor({lnum}, {col} [, {off}]) *cursor()*
1687cursor({list})
1688 Positions the cursor at the column (byte count) {col} in the
1689 line {lnum}. The first column is one.
1690
1691 When there is one argument {list} this is used as a |List|
1692 with two, three or four item:
1693 [{lnum}, {col}]
1694 [{lnum}, {col}, {off}]
1695 [{lnum}, {col}, {off}, {curswant}]
1696 This is like the return value of |getpos()| or |getcurpos()|,
1697 but without the first item.
1698
1699 To position the cursor using the character count, use
1700 |setcursorcharpos()|.
1701
1702 Does not change the jumplist.
1703 {lnum} is used like with |getline()|.
1704 If {lnum} is greater than the number of lines in the buffer,
1705 the cursor will be positioned at the last line in the buffer.
1706 If {lnum} is zero, the cursor will stay in the current line.
1707 If {col} is greater than the number of bytes in the line,
1708 the cursor will be positioned at the last character in the
1709 line.
1710 If {col} is zero, the cursor will stay in the current column.
1711 If {curswant} is given it is used to set the preferred column
1712 for vertical movement. Otherwise {col} is used.
1713
1714 When 'virtualedit' is used {off} specifies the offset in
1715 screen columns from the start of the character. E.g., a
1716 position within a <Tab> or after the last character.
1717 Returns 0 when the position could be set, -1 otherwise.
1718
1719 Can also be used as a |method|: >
1720 GetCursorPos()->cursor()
1721
1722debugbreak({pid}) *debugbreak()*
1723 Specifically used to interrupt a program being debugged. It
1724 will cause process {pid} to get a SIGTRAP. Behavior for other
1725 processes is undefined. See |terminal-debugger|.
1726 {only available on MS-Windows}
1727
1728 Can also be used as a |method|: >
1729 GetPid()->debugbreak()
1730
1731deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
1732 Make a copy of {expr}. For Numbers and Strings this isn't
1733 different from using {expr} directly.
1734 When {expr} is a |List| a full copy is created. This means
1735 that the original |List| can be changed without changing the
1736 copy, and vice versa. When an item is a |List| or
1737 |Dictionary|, a copy for it is made, recursively. Thus
1738 changing an item in the copy does not change the contents of
1739 the original |List|.
1740 A |Dictionary| is copied in a similar way as a |List|.
1741
1742 When {noref} is omitted or zero a contained |List| or
1743 |Dictionary| is only copied once. All references point to
1744 this single copy. With {noref} set to 1 every occurrence of a
1745 |List| or |Dictionary| results in a new copy. This also means
1746 that a cyclic reference causes deepcopy() to fail.
1747 *E724*
1748 Nesting is possible up to 100 levels. When there is an item
1749 that refers back to a higher level making a deep copy with
1750 {noref} set to 1 will fail.
1751 Also see |copy()|.
1752
1753 Can also be used as a |method|: >
1754 GetObject()->deepcopy()
1755
1756delete({fname} [, {flags}]) *delete()*
1757 Without {flags} or with {flags} empty: Deletes the file by the
1758 name {fname}. This also works when {fname} is a symbolic link.
1759
1760 When {flags} is "d": Deletes the directory by the name
1761 {fname}. This fails when directory {fname} is not empty.
1762
1763 When {flags} is "rf": Deletes the directory by the name
1764 {fname} and everything in it, recursively. BE CAREFUL!
1765 Note: on MS-Windows it is not possible to delete a directory
1766 that is being used.
1767
1768 A symbolic link itself is deleted, not what it points to.
1769
1770 The result is a Number, which is 0/false if the delete
1771 operation was successful and -1/true when the deletion failed
1772 or partly failed.
1773
1774 Use |remove()| to delete an item from a |List|.
1775 To delete a line from the buffer use |:delete| or
1776 |deletebufline()|.
1777
1778 Can also be used as a |method|: >
1779 GetName()->delete()
1780
1781deletebufline({buf}, {first} [, {last}]) *deletebufline()*
1782 Delete lines {first} to {last} (inclusive) from buffer {buf}.
1783 If {last} is omitted then delete line {first} only.
1784 On success 0 is returned, on failure 1 is returned.
1785
1786 This function works only for loaded buffers. First call
1787 |bufload()| if needed.
1788
1789 For the use of {buf}, see |bufname()| above.
1790
1791 {first} and {last} are used like with |getline()|. Note that
1792 when using |line()| this refers to the current buffer. Use "$"
1793 to refer to the last line in buffer {buf}.
1794
1795 Can also be used as a |method|: >
1796 GetBuffer()->deletebufline(1)
1797<
1798 *did_filetype()*
1799did_filetype() Returns |TRUE| when autocommands are being executed and the
1800 FileType event has been triggered at least once. Can be used
1801 to avoid triggering the FileType event again in the scripts
1802 that detect the file type. |FileType|
1803 Returns |FALSE| when `:setf FALLBACK` was used.
1804 When editing another file, the counter is reset, thus this
1805 really checks if the FileType event has been triggered for the
1806 current buffer. This allows an autocommand that starts
1807 editing another buffer to set 'filetype' and load a syntax
1808 file.
1809
1810diff_filler({lnum}) *diff_filler()*
1811 Returns the number of filler lines above line {lnum}.
1812 These are the lines that were inserted at this point in
1813 another diff'ed window. These filler lines are shown in the
1814 display but don't exist in the buffer.
1815 {lnum} is used like with |getline()|. Thus "." is the current
1816 line, "'m" mark m, etc.
1817 Returns 0 if the current window is not in diff mode.
1818
1819 Can also be used as a |method|: >
1820 GetLnum()->diff_filler()
1821
1822diff_hlID({lnum}, {col}) *diff_hlID()*
1823 Returns the highlight ID for diff mode at line {lnum} column
1824 {col} (byte index). When the current line does not have a
1825 diff change zero is returned.
1826 {lnum} is used like with |getline()|. Thus "." is the current
1827 line, "'m" mark m, etc.
1828 {col} is 1 for the leftmost column, {lnum} is 1 for the first
1829 line.
1830 The highlight ID can be used with |synIDattr()| to obtain
1831 syntax information about the highlighting.
1832
1833 Can also be used as a |method|: >
1834 GetLnum()->diff_hlID(col)
1835<
1836
1837digraph_get({chars}) *digraph_get()* *E1214*
1838 Return the digraph of {chars}. This should be a string with
1839 exactly two characters. If {chars} are not just two
1840 characters, or the digraph of {chars} does not exist, an error
1841 is given and an empty string is returned.
1842
1843 The character will be converted from Unicode to 'encoding'
1844 when needed. This does require the conversion to be
1845 available, it might fail.
1846
1847 Also see |digraph_getlist()|.
1848
1849 Examples: >
1850 " Get a built-in digraph
1851 :echo digraph_get('00') " Returns '∞'
1852
1853 " Get a user-defined digraph
1854 :call digraph_set('aa', 'あ')
1855 :echo digraph_get('aa') " Returns 'あ'
1856<
1857 Can also be used as a |method|: >
1858 GetChars()->digraph_get()
1859<
1860 This function works only when compiled with the |+digraphs|
1861 feature. If this feature is disabled, this function will
1862 display an error message.
1863
1864
1865digraph_getlist([{listall}]) *digraph_getlist()*
1866 Return a list of digraphs. If the {listall} argument is given
1867 and it is TRUE, return all digraphs, including the default
1868 digraphs. Otherwise, return only user-defined digraphs.
1869
1870 The characters will be converted from Unicode to 'encoding'
1871 when needed. This does require the conservation to be
1872 available, it might fail.
1873
1874 Also see |digraph_get()|.
1875
1876 Examples: >
1877 " Get user-defined digraphs
1878 :echo digraph_getlist()
1879
1880 " Get all the digraphs, including default digraphs
1881 :echo digraph_getlist(1)
1882<
1883 Can also be used as a |method|: >
1884 GetNumber()->digraph_getlist()
1885<
1886 This function works only when compiled with the |+digraphs|
1887 feature. If this feature is disabled, this function will
1888 display an error message.
1889
1890
1891digraph_set({chars}, {digraph}) *digraph_set()* *E1205*
1892 Add digraph {chars} to the list. {chars} must be a string
1893 with two characters. {digraph} is a string with one UTF-8
1894 encoded character. Be careful, composing characters are NOT
1895 ignored. This function is similar to |:digraphs| command, but
1896 useful to add digraphs start with a white space.
1897
1898 The function result is v:true if |digraph| is registered. If
1899 this fails an error message is given and v:false is returned.
1900
1901 If you want to define multiple digraphs at once, you can use
1902 |digraph_setlist()|.
1903
1904 Example: >
1905 call digraph_set(' ', 'あ')
1906<
1907 Can be used as a |method|: >
1908 GetString()->digraph_set('あ')
1909<
1910 This function works only when compiled with the |+digraphs|
1911 feature. If this feature is disabled, this function will
1912 display an error message.
1913
1914
1915digraph_setlist({digraphlist}) *digraph_setlist()*
1916 Similar to |digraph_set()| but this function can add multiple
1917 digraphs at once. {digraphlist} is a list composed of lists,
1918 where each list contains two strings with {chars} and
1919 {digraph} as in |digraph_set()|.
1920 Example: >
1921 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
1922<
1923 It is similar to the following: >
1924 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
1925 call digraph_set(chars, digraph)
1926 endfor
1927< Except that the function returns after the first error,
1928 following digraphs will not be added.
1929
1930 Can be used as a |method|: >
1931 GetList()->digraph_setlist()
1932<
1933 This function works only when compiled with the |+digraphs|
1934 feature. If this feature is disabled, this function will
1935 display an error message.
1936
1937
1938echoraw({string}) *echoraw()*
1939 Output {string} as-is, including unprintable characters.
1940 This can be used to output a terminal code. For example, to
1941 disable modifyOtherKeys: >
1942 call echoraw(&t_TE)
1943< and to enable it again: >
1944 call echoraw(&t_TI)
1945< Use with care, you can mess up the terminal this way.
1946
1947
1948empty({expr}) *empty()*
1949 Return the Number 1 if {expr} is empty, zero otherwise.
1950 - A |List| or |Dictionary| is empty when it does not have any
1951 items.
1952 - A |String| is empty when its length is zero.
1953 - A |Number| and |Float| are empty when their value is zero.
1954 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
1955 - A |Job| is empty when it failed to start.
1956 - A |Channel| is empty when it is closed.
1957 - A |Blob| is empty when its length is zero.
1958
1959 For a long |List| this is much faster than comparing the
1960 length with zero.
1961
1962 Can also be used as a |method|: >
1963 mylist->empty()
1964
1965environ() *environ()*
1966 Return all of environment variables as dictionary. You can
1967 check if an environment variable exists like this: >
1968 :echo has_key(environ(), 'HOME')
1969< Note that the variable name may be CamelCase; to ignore case
1970 use this: >
1971 :echo index(keys(environ()), 'HOME', 0, 1) != -1
1972
1973escape({string}, {chars}) *escape()*
1974 Escape the characters in {chars} that occur in {string} with a
1975 backslash. Example: >
1976 :echo escape('c:\program files\vim', ' \')
1977< results in: >
1978 c:\\program\ files\\vim
1979< Also see |shellescape()| and |fnameescape()|.
1980
1981 Can also be used as a |method|: >
1982 GetText()->escape(' \')
1983<
1984 *eval()*
1985eval({string}) Evaluate {string} and return the result. Especially useful to
1986 turn the result of |string()| back into the original value.
1987 This works for Numbers, Floats, Strings, Blobs and composites
1988 of them. Also works for |Funcref|s that refer to existing
1989 functions.
1990
1991 Can also be used as a |method|: >
1992 argv->join()->eval()
1993
1994eventhandler() *eventhandler()*
1995 Returns 1 when inside an event handler. That is that Vim got
1996 interrupted while waiting for the user to type a character,
1997 e.g., when dropping a file on Vim. This means interactive
1998 commands cannot be used. Otherwise zero is returned.
1999
2000executable({expr}) *executable()*
2001 This function checks if an executable with the name {expr}
2002 exists. {expr} must be the name of the program without any
2003 arguments.
2004 executable() uses the value of $PATH and/or the normal
2005 searchpath for programs. *PATHEXT*
2006 On MS-Windows the ".exe", ".bat", etc. can optionally be
2007 included. Then the extensions in $PATHEXT are tried. Thus if
2008 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2009 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2010 by itself can be used in $PATHEXT to try using the name
2011 without an extension. When 'shell' looks like a Unix shell,
2012 then the name is also tried without adding an extension.
2013 On MS-Windows it only checks if the file exists and is not a
2014 directory, not if it's really executable.
2015 On MS-Windows an executable in the same directory as Vim is
2016 always found. Since this directory is added to $PATH it
2017 should also work to execute it |win32-PATH|.
2018 The result is a Number:
2019 1 exists
2020 0 does not exist
2021 -1 not implemented on this system
2022 |exepath()| can be used to get the full path of an executable.
2023
2024 Can also be used as a |method|: >
2025 GetCommand()->executable()
2026
2027execute({command} [, {silent}]) *execute()*
2028 Execute an Ex command or commands and return the output as a
2029 string.
2030 {command} can be a string or a List. In case of a List the
2031 lines are executed one by one.
2032 This is equivalent to: >
2033 redir => var
2034 {command}
2035 redir END
2036<
2037 The optional {silent} argument can have these values:
2038 "" no `:silent` used
2039 "silent" `:silent` used
2040 "silent!" `:silent!` used
2041 The default is "silent". Note that with "silent!", unlike
2042 `:redir`, error messages are dropped. When using an external
2043 command the screen may be messed up, use `system()` instead.
2044 *E930*
2045 It is not possible to use `:redir` anywhere in {command}.
2046
2047 To get a list of lines use |split()| on the result: >
2048 split(execute('args'), "\n")
2049
2050< To execute a command in another window than the current one
2051 use `win_execute()`.
2052
2053 When used recursively the output of the recursive call is not
2054 included in the output of the higher level call.
2055
2056 Can also be used as a |method|: >
2057 GetCommand()->execute()
2058
2059exepath({expr}) *exepath()*
2060 If {expr} is an executable and is either an absolute path, a
2061 relative path or found in $PATH, return the full path.
2062 Note that the current directory is used when {expr} starts
2063 with "./", which may be a problem for Vim: >
2064 echo exepath(v:progpath)
2065< If {expr} cannot be found in $PATH or is not executable then
2066 an empty string is returned.
2067
2068 Can also be used as a |method|: >
2069 GetCommand()->exepath()
2070<
2071 *exists()*
2072exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
2073 zero otherwise.
2074
2075 Note: In a compiled |:def| function the evaluation is done at
2076 runtime. Use `exists_compiled()` to evaluate the expression
2077 at compile time.
2078
2079 For checking for a supported feature use |has()|.
2080 For checking if a file exists use |filereadable()|.
2081
2082 The {expr} argument is a string, which contains one of these:
2083 &option-name Vim option (only checks if it exists,
2084 not if it really works)
2085 +option-name Vim option that works.
2086 $ENVNAME environment variable (could also be
2087 done by comparing with an empty
2088 string)
2089 *funcname built-in function (see |functions|)
2090 or user defined function (see
2091 |user-functions|) that is implemented.
2092 Also works for a variable that is a
2093 Funcref.
2094 ?funcname built-in function that could be
2095 implemented; to be used to check if
2096 "funcname" is valid
2097 varname internal variable (see
2098 |internal-variables|). Also works
2099 for |curly-braces-names|, |Dictionary|
2100 entries, |List| items, etc.
2101 Does not work for local variables in a
2102 compiled `:def` function.
2103 Beware that evaluating an index may
2104 cause an error message for an invalid
2105 expression. E.g.: >
2106 :let l = [1, 2, 3]
2107 :echo exists("l[5]")
2108< 0 >
2109 :echo exists("l[xx]")
2110< E121: Undefined variable: xx
2111 0
2112 :cmdname Ex command: built-in command, user
2113 command or command modifier |:command|.
2114 Returns:
2115 1 for match with start of a command
2116 2 full match with a command
2117 3 matches several user commands
2118 To check for a supported command
2119 always check the return value to be 2.
2120 :2match The |:2match| command.
2121 :3match The |:3match| command.
2122 #event autocommand defined for this event
2123 #event#pattern autocommand defined for this event and
2124 pattern (the pattern is taken
2125 literally and compared to the
2126 autocommand patterns character by
2127 character)
2128 #group autocommand group exists
2129 #group#event autocommand defined for this group and
2130 event.
2131 #group#event#pattern
2132 autocommand defined for this group,
2133 event and pattern.
2134 ##event autocommand for this event is
2135 supported.
2136
2137 Examples: >
2138 exists("&shortname")
2139 exists("$HOSTNAME")
2140 exists("*strftime")
2141 exists("*s:MyFunc")
2142 exists("bufcount")
2143 exists(":Make")
2144 exists("#CursorHold")
2145 exists("#BufReadPre#*.gz")
2146 exists("#filetypeindent")
2147 exists("#filetypeindent#FileType")
2148 exists("#filetypeindent#FileType#*")
2149 exists("##ColorScheme")
2150< There must be no space between the symbol (&/$/*/#) and the
2151 name.
2152 There must be no extra characters after the name, although in
2153 a few cases this is ignored. That may become more strict in
2154 the future, thus don't count on it!
2155 Working example: >
2156 exists(":make")
2157< NOT working example: >
2158 exists(":make install")
2159
2160< Note that the argument must be a string, not the name of the
2161 variable itself. For example: >
2162 exists(bufcount)
2163< This doesn't check for existence of the "bufcount" variable,
2164 but gets the value of "bufcount", and checks if that exists.
2165
2166 Can also be used as a |method|: >
2167 Varname()->exists()
2168<
2169
2170exists_compiled({expr}) *exists_compiled()*
2171 Like `exists()` but evaluated at compile time. This is useful
2172 to skip a block where a function is used that would otherwise
2173 give an error: >
2174 if exists_compiled('*ThatFunction')
2175 ThatFunction('works')
2176 endif
2177< If `exists()` were used then a compilation error would be
2178 given if ThatFunction() is not defined.
2179
2180 {expr} must be a literal string. *E1232*
2181 Can only be used in a |:def| function. *E1233*
2182 This does not work to check for arguments or local variables.
2183
2184
2185exp({expr}) *exp()*
2186 Return the exponential of {expr} as a |Float| in the range
2187 [0, inf].
2188 {expr} must evaluate to a |Float| or a |Number|.
2189 Examples: >
2190 :echo exp(2)
2191< 7.389056 >
2192 :echo exp(-1)
2193< 0.367879
2194
2195 Can also be used as a |method|: >
2196 Compute()->exp()
2197<
2198 {only available when compiled with the |+float| feature}
2199
2200
2201expand({string} [, {nosuf} [, {list}]]) *expand()*
2202 Expand wildcards and the following special keywords in
2203 {string}. 'wildignorecase' applies.
2204
2205 If {list} is given and it is |TRUE|, a List will be returned.
2206 Otherwise the result is a String and when there are several
2207 matches, they are separated by <NL> characters. [Note: in
2208 version 5.0 a space was used, which caused problems when a
2209 file name contains a space]
2210
2211 If the expansion fails, the result is an empty string. A name
2212 for a non-existing file is not included, unless {string} does
2213 not start with '%', '#' or '<', see below.
2214
2215 When {string} starts with '%', '#' or '<', the expansion is
2216 done like for the |cmdline-special| variables with their
2217 associated modifiers. Here is a short overview:
2218
2219 % current file name
2220 # alternate file name
2221 #n alternate file name n
2222 <cfile> file name under the cursor
2223 <afile> autocmd file name
2224 <abuf> autocmd buffer number (as a String!)
2225 <amatch> autocmd matched name
2226 <cexpr> C expression under the cursor
2227 <sfile> sourced script file or function name
2228 <slnum> sourced script line number or function
2229 line number
2230 <sflnum> script file line number, also when in
2231 a function
2232 <SID> "<SNR>123_" where "123" is the
2233 current script ID |<SID>|
2234 <stack> call stack
2235 <cword> word under the cursor
2236 <cWORD> WORD under the cursor
2237 <client> the {clientid} of the last received
2238 message |server2client()|
2239 Modifiers:
2240 :p expand to full path
2241 :h head (last path component removed)
2242 :t tail (last path component only)
2243 :r root (one extension removed)
2244 :e extension only
2245
2246 Example: >
2247 :let &tags = expand("%:p:h") . "/tags"
2248< Note that when expanding a string that starts with '%', '#' or
2249 '<', any following text is ignored. This does NOT work: >
2250 :let doesntwork = expand("%:h.bak")
2251< Use this: >
2252 :let doeswork = expand("%:h") . ".bak"
2253< Also note that expanding "<cfile>" and others only returns the
2254 referenced file name without further expansion. If "<cfile>"
2255 is "~/.cshrc", you need to do another expand() to have the
2256 "~/" expanded into the path of the home directory: >
2257 :echo expand(expand("<cfile>"))
2258<
2259 There cannot be white space between the variables and the
2260 following modifier. The |fnamemodify()| function can be used
2261 to modify normal file names.
2262
2263 When using '%' or '#', and the current or alternate file name
2264 is not defined, an empty string is used. Using "%:p" in a
2265 buffer with no name, results in the current directory, with a
2266 '/' added.
2267
2268 When {string} does not start with '%', '#' or '<', it is
2269 expanded like a file name is expanded on the command line.
2270 'suffixes' and 'wildignore' are used, unless the optional
2271 {nosuf} argument is given and it is |TRUE|.
2272 Names for non-existing files are included. The "**" item can
2273 be used to search in a directory tree. For example, to find
2274 all "README" files in the current directory and below: >
2275 :echo expand("**/README")
2276<
2277 expand() can also be used to expand variables and environment
2278 variables that are only known in a shell. But this can be
2279 slow, because a shell may be used to do the expansion. See
2280 |expr-env-expand|.
2281 The expanded variable is still handled like a list of file
2282 names. When an environment variable cannot be expanded, it is
2283 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2284 "$FOOBAR".
2285
2286 See |glob()| for finding existing files. See |system()| for
2287 getting the raw output of an external command.
2288
2289 Can also be used as a |method|: >
2290 Getpattern()->expand()
2291
2292expandcmd({string}) *expandcmd()*
2293 Expand special items in String {string} like what is done for
2294 an Ex command such as `:edit`. This expands special keywords,
2295 like with |expand()|, and environment variables, anywhere in
2296 {string}. "~user" and "~/path" are only expanded at the
2297 start.
2298 Returns the expanded string. Example: >
2299 :echo expandcmd('make %<.o')
2300
2301< Can also be used as a |method|: >
2302 GetCommand()->expandcmd()
2303<
2304extend({expr1}, {expr2} [, {expr3}]) *extend()*
2305 {expr1} and {expr2} must be both |Lists| or both
2306 |Dictionaries|.
2307
2308 If they are |Lists|: Append {expr2} to {expr1}.
2309 If {expr3} is given insert the items of {expr2} before the
2310 item with index {expr3} in {expr1}. When {expr3} is zero
2311 insert before the first item. When {expr3} is equal to
2312 len({expr1}) then {expr2} is appended.
2313 Examples: >
2314 :echo sort(extend(mylist, [7, 5]))
2315 :call extend(mylist, [2, 3], 1)
2316< When {expr1} is the same List as {expr2} then the number of
2317 items copied is equal to the original length of the List.
2318 E.g., when {expr3} is 1 you get N new copies of the first item
2319 (where N is the original length of the List).
2320 Use |add()| to concatenate one item to a list. To concatenate
2321 two lists into a new list use the + operator: >
2322 :let newlist = [1, 2, 3] + [4, 5]
2323<
2324 If they are |Dictionaries|:
2325 Add all entries from {expr2} to {expr1}.
2326 If a key exists in both {expr1} and {expr2} then {expr3} is
2327 used to decide what to do:
2328 {expr3} = "keep": keep the value of {expr1}
2329 {expr3} = "force": use the value of {expr2}
2330 {expr3} = "error": give an error message *E737*
2331 When {expr3} is omitted then "force" is assumed.
2332
2333 {expr1} is changed when {expr2} is not empty. If necessary
2334 make a copy of {expr1} first.
2335 {expr2} remains unchanged.
2336 When {expr1} is locked and {expr2} is not empty the operation
2337 fails.
2338 Returns {expr1}.
2339
2340 Can also be used as a |method|: >
2341 mylist->extend(otherlist)
2342
2343
2344extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2345 Like |extend()| but instead of adding items to {expr1} a new
2346 List or Dictionary is created and returned. {expr1} remains
2347 unchanged. Items can still be changed by {expr2}, if you
2348 don't want that use |deepcopy()| first.
2349
2350
2351feedkeys({string} [, {mode}]) *feedkeys()*
2352 Characters in {string} are queued for processing as if they
2353 come from a mapping or were typed by the user.
2354
2355 By default the string is added to the end of the typeahead
2356 buffer, thus if a mapping is still being executed the
2357 characters come after them. Use the 'i' flag to insert before
2358 other characters, they will be executed next, before any
2359 characters from a mapping.
2360
2361 The function does not wait for processing of keys contained in
2362 {string}.
2363
2364 To include special keys into {string}, use double-quotes
2365 and "\..." notation |expr-quote|. For example,
2366 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2367 feedkeys('\<CR>') pushes 5 characters.
2368 A special code that might be useful is <Ignore>, it exits the
2369 wait for a character without doing anything. *<Ignore>*
2370
2371 {mode} is a String, which can contain these character flags:
2372 'm' Remap keys. This is default. If {mode} is absent,
2373 keys are remapped.
2374 'n' Do not remap keys.
2375 't' Handle keys as if typed; otherwise they are handled as
2376 if coming from a mapping. This matters for undo,
2377 opening folds, etc.
2378 'L' Lowlevel input. Only works for Unix or when using the
2379 GUI. Keys are used as if they were coming from the
2380 terminal. Other flags are not used. *E980*
2381 When a CTRL-C interrupts and 't' is included it sets
2382 the internal "got_int" flag.
2383 'i' Insert the string instead of appending (see above).
2384 'x' Execute commands until typeahead is empty. This is
2385 similar to using ":normal!". You can call feedkeys()
2386 several times without 'x' and then one time with 'x'
2387 (possibly with an empty {string}) to execute all the
2388 typeahead. Note that when Vim ends in Insert mode it
2389 will behave as if <Esc> is typed, to avoid getting
2390 stuck, waiting for a character to be typed before the
2391 script continues.
2392 Note that if you manage to call feedkeys() while
2393 executing commands, thus calling it recursively, then
2394 all typeahead will be consumed by the last call.
2395 '!' When used with 'x' will not end Insert mode. Can be
2396 used in a test when a timer is set to exit Insert mode
2397 a little later. Useful for testing CursorHoldI.
2398
2399 Return value is always 0.
2400
2401 Can also be used as a |method|: >
2402 GetInput()->feedkeys()
2403
2404filereadable({file}) *filereadable()*
2405 The result is a Number, which is |TRUE| when a file with the
2406 name {file} exists, and can be read. If {file} doesn't exist,
2407 or is a directory, the result is |FALSE|. {file} is any
2408 expression, which is used as a String.
2409 If you don't care about the file being readable you can use
2410 |glob()|.
2411 {file} is used as-is, you may want to expand wildcards first: >
2412 echo filereadable('~/.vimrc')
2413 0
2414 echo filereadable(expand('~/.vimrc'))
2415 1
2416
2417< Can also be used as a |method|: >
2418 GetName()->filereadable()
2419< *file_readable()*
2420 Obsolete name: file_readable().
2421
2422
2423filewritable({file}) *filewritable()*
2424 The result is a Number, which is 1 when a file with the
2425 name {file} exists, and can be written. If {file} doesn't
2426 exist, or is not writable, the result is 0. If {file} is a
2427 directory, and we can write to it, the result is 2.
2428
2429 Can also be used as a |method|: >
2430 GetName()->filewritable()
2431
2432
2433filter({expr1}, {expr2}) *filter()*
2434 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
2435 For each item in {expr1} evaluate {expr2} and when the result
2436 is zero or false remove the item from the |List| or
2437 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002438 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002439
2440 {expr2} must be a |string| or |Funcref|.
2441
2442 If {expr2} is a |string|, inside {expr2} |v:val| has the value
2443 of the current item. For a |Dictionary| |v:key| has the key
2444 of the current item and for a |List| |v:key| has the index of
2445 the current item. For a |Blob| |v:key| has the index of the
2446 current byte. For a |String| |v:key| has the index of the
2447 current character.
2448 Examples: >
2449 call filter(mylist, 'v:val !~ "OLD"')
2450< Removes the items where "OLD" appears. >
2451 call filter(mydict, 'v:key >= 8')
2452< Removes the items with a key below 8. >
2453 call filter(var, 0)
2454< Removes all the items, thus clears the |List| or |Dictionary|.
2455
2456 Note that {expr2} is the result of expression and is then
2457 used as an expression again. Often it is good to use a
2458 |literal-string| to avoid having to double backslashes.
2459
2460 If {expr2} is a |Funcref| it must take two arguments:
2461 1. the key or the index of the current item.
2462 2. the value of the current item.
2463 The function must return |TRUE| if the item should be kept.
2464 Example that keeps the odd items of a list: >
2465 func Odd(idx, val)
2466 return a:idx % 2 == 1
2467 endfunc
2468 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002469< It is shorter when using a |lambda|. In |Vim9| syntax: >
2470 call filter(myList, (idx, val) => idx * val <= 42)
2471< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002472 call filter(myList, {idx, val -> idx * val <= 42})
2473< If you do not use "val" you can leave it out: >
2474 call filter(myList, {idx -> idx % 2 == 1})
2475<
2476 In |Vim9| script the result must be true, false, zero or one.
2477 Other values will result in a type error.
2478
2479 For a |List| and a |Dictionary| the operation is done
2480 in-place. If you want it to remain unmodified make a copy
2481 first: >
2482 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2483
2484< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00002485 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002486 When an error is encountered while evaluating {expr2} no
2487 further items in {expr1} are processed.
2488 When {expr2} is a Funcref errors inside a function are ignored,
2489 unless it was defined with the "abort" flag.
2490
2491 Can also be used as a |method|: >
2492 mylist->filter(expr2)
2493
2494finddir({name} [, {path} [, {count}]]) *finddir()*
2495 Find directory {name} in {path}. Supports both downwards and
2496 upwards recursive directory searches. See |file-searching|
2497 for the syntax of {path}.
2498
2499 Returns the path of the first found match. When the found
2500 directory is below the current directory a relative path is
2501 returned. Otherwise a full path is returned.
2502 If {path} is omitted or empty then 'path' is used.
2503
2504 If the optional {count} is given, find {count}'s occurrence of
2505 {name} in {path} instead of the first one.
2506 When {count} is negative return all the matches in a |List|.
2507
2508 This is quite similar to the ex-command `:find`.
2509 {only available when compiled with the |+file_in_path|
2510 feature}
2511
2512 Can also be used as a |method|: >
2513 GetName()->finddir()
2514
2515findfile({name} [, {path} [, {count}]]) *findfile()*
2516 Just like |finddir()|, but find a file instead of a directory.
2517 Uses 'suffixesadd'.
2518 Example: >
2519 :echo findfile("tags.vim", ".;")
2520< Searches from the directory of the current file upwards until
2521 it finds the file "tags.vim".
2522
2523 Can also be used as a |method|: >
2524 GetName()->findfile()
2525
2526flatten({list} [, {maxdepth}]) *flatten()*
2527 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
2528 the result is a |List| without nesting, as if {maxdepth} is
2529 a very large number.
2530 The {list} is changed in place, use |flattennew()| if you do
2531 not want that.
2532 In Vim9 script flatten() cannot be used, you must always use
2533 |flattennew()|.
2534 *E900*
2535 {maxdepth} means how deep in nested lists changes are made.
2536 {list} is not modified when {maxdepth} is 0.
2537 {maxdepth} must be positive number.
2538
2539 If there is an error the number zero is returned.
2540
2541 Example: >
2542 :echo flatten([1, [2, [3, 4]], 5])
2543< [1, 2, 3, 4, 5] >
2544 :echo flatten([1, [2, [3, 4]], 5], 1)
2545< [1, 2, [3, 4], 5]
2546
2547 Can also be used as a |method|: >
2548 mylist->flatten()
2549<
2550flattennew({list} [, {maxdepth}]) *flattennew()*
2551 Like |flatten()| but first make a copy of {list}.
2552
2553
2554float2nr({expr}) *float2nr()*
2555 Convert {expr} to a Number by omitting the part after the
2556 decimal point.
2557 {expr} must evaluate to a |Float| or a Number.
2558 When the value of {expr} is out of range for a |Number| the
2559 result is truncated to 0x7fffffff or -0x7fffffff (or when
2560 64-bit Number support is enabled, 0x7fffffffffffffff or
2561 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
2562 64-bit Number support is enabled, -0x8000000000000000).
2563 Examples: >
2564 echo float2nr(3.95)
2565< 3 >
2566 echo float2nr(-23.45)
2567< -23 >
2568 echo float2nr(1.0e100)
2569< 2147483647 (or 9223372036854775807) >
2570 echo float2nr(-1.0e150)
2571< -2147483647 (or -9223372036854775807) >
2572 echo float2nr(1.0e-100)
2573< 0
2574
2575 Can also be used as a |method|: >
2576 Compute()->float2nr()
2577<
2578 {only available when compiled with the |+float| feature}
2579
2580
2581floor({expr}) *floor()*
2582 Return the largest integral value less than or equal to
2583 {expr} as a |Float| (round down).
2584 {expr} must evaluate to a |Float| or a |Number|.
2585 Examples: >
2586 echo floor(1.856)
2587< 1.0 >
2588 echo floor(-5.456)
2589< -6.0 >
2590 echo floor(4.0)
2591< 4.0
2592
2593 Can also be used as a |method|: >
2594 Compute()->floor()
2595<
2596 {only available when compiled with the |+float| feature}
2597
2598
2599fmod({expr1}, {expr2}) *fmod()*
2600 Return the remainder of {expr1} / {expr2}, even if the
2601 division is not representable. Returns {expr1} - i * {expr2}
2602 for some integer i such that if {expr2} is non-zero, the
2603 result has the same sign as {expr1} and magnitude less than
2604 the magnitude of {expr2}. If {expr2} is zero, the value
2605 returned is zero. The value returned is a |Float|.
2606 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
2607 Examples: >
2608 :echo fmod(12.33, 1.22)
2609< 0.13 >
2610 :echo fmod(-12.33, 1.22)
2611< -0.13
2612
2613 Can also be used as a |method|: >
2614 Compute()->fmod(1.22)
2615<
2616 {only available when compiled with |+float| feature}
2617
2618
2619fnameescape({string}) *fnameescape()*
2620 Escape {string} for use as file name command argument. All
2621 characters that have a special meaning, such as '%' and '|'
2622 are escaped with a backslash.
2623 For most systems the characters escaped are
2624 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2625 appears in a filename, it depends on the value of 'isfname'.
2626 A leading '+' and '>' is also escaped (special after |:edit|
2627 and |:write|). And a "-" by itself (special after |:cd|).
2628 Example: >
2629 :let fname = '+some str%nge|name'
2630 :exe "edit " . fnameescape(fname)
2631< results in executing: >
2632 edit \+some\ str\%nge\|name
2633<
2634 Can also be used as a |method|: >
2635 GetName()->fnameescape()
2636
2637fnamemodify({fname}, {mods}) *fnamemodify()*
2638 Modify file name {fname} according to {mods}. {mods} is a
2639 string of characters like it is used for file names on the
2640 command line. See |filename-modifiers|.
2641 Example: >
2642 :echo fnamemodify("main.c", ":p:h")
2643< results in: >
2644 /home/mool/vim/vim/src
2645< If {mods} is empty then {fname} is returned.
2646 Note: Environment variables don't work in {fname}, use
2647 |expand()| first then.
2648
2649 Can also be used as a |method|: >
2650 GetName()->fnamemodify(':p:h')
2651
2652foldclosed({lnum}) *foldclosed()*
2653 The result is a Number. If the line {lnum} is in a closed
2654 fold, the result is the number of the first line in that fold.
2655 If the line {lnum} is not in a closed fold, -1 is returned.
2656 {lnum} is used like with |getline()|. Thus "." is the current
2657 line, "'m" mark m, etc.
2658
2659 Can also be used as a |method|: >
2660 GetLnum()->foldclosed()
2661
2662foldclosedend({lnum}) *foldclosedend()*
2663 The result is a Number. If the line {lnum} is in a closed
2664 fold, the result is the number of the last line in that fold.
2665 If the line {lnum} is not in a closed fold, -1 is returned.
2666 {lnum} is used like with |getline()|. Thus "." is the current
2667 line, "'m" mark m, etc.
2668
2669 Can also be used as a |method|: >
2670 GetLnum()->foldclosedend()
2671
2672foldlevel({lnum}) *foldlevel()*
2673 The result is a Number, which is the foldlevel of line {lnum}
2674 in the current buffer. For nested folds the deepest level is
2675 returned. If there is no fold at line {lnum}, zero is
2676 returned. It doesn't matter if the folds are open or closed.
2677 When used while updating folds (from 'foldexpr') -1 is
2678 returned for lines where folds are still to be updated and the
2679 foldlevel is unknown. As a special case the level of the
2680 previous line is usually available.
2681 {lnum} is used like with |getline()|. Thus "." is the current
2682 line, "'m" mark m, etc.
2683
2684 Can also be used as a |method|: >
2685 GetLnum()->foldlevel()
2686<
2687 *foldtext()*
2688foldtext() Returns a String, to be displayed for a closed fold. This is
2689 the default function used for the 'foldtext' option and should
2690 only be called from evaluating 'foldtext'. It uses the
2691 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2692 The returned string looks like this: >
2693 +-- 45 lines: abcdef
2694< The number of leading dashes depends on the foldlevel. The
2695 "45" is the number of lines in the fold. "abcdef" is the text
2696 in the first non-blank line of the fold. Leading white space,
2697 "//" or "/*" and the text from the 'foldmarker' and
2698 'commentstring' options is removed.
2699 When used to draw the actual foldtext, the rest of the line
2700 will be filled with the fold char from the 'fillchars'
2701 setting.
2702 {not available when compiled without the |+folding| feature}
2703
2704foldtextresult({lnum}) *foldtextresult()*
2705 Returns the text that is displayed for the closed fold at line
2706 {lnum}. Evaluates 'foldtext' in the appropriate context.
2707 When there is no closed fold at {lnum} an empty string is
2708 returned.
2709 {lnum} is used like with |getline()|. Thus "." is the current
2710 line, "'m" mark m, etc.
2711 Useful when exporting folded text, e.g., to HTML.
2712 {not available when compiled without the |+folding| feature}
2713
2714
2715 Can also be used as a |method|: >
2716 GetLnum()->foldtextresult()
2717<
2718 *foreground()*
2719foreground() Move the Vim window to the foreground. Useful when sent from
2720 a client to a Vim server. |remote_send()|
2721 On Win32 systems this might not work, the OS does not always
2722 allow a window to bring itself to the foreground. Use
2723 |remote_foreground()| instead.
2724 {only in the Win32, Athena, Motif and GTK GUI versions and the
2725 Win32 console version}
2726
2727fullcommand({name}) *fullcommand()*
2728 Get the full command name from a short abbreviated command
2729 name; see |20.2| for details on command abbreviations.
2730
2731 The string argument {name} may start with a `:` and can
2732 include a [range], these are skipped and not returned.
2733 Returns an empty string if a command doesn't exist or if it's
2734 ambiguous (for user-defined commands).
2735
2736 For example `fullcommand('s')`, `fullcommand('sub')`,
2737 `fullcommand(':%substitute')` all return "substitute".
2738
2739 Can also be used as a |method|: >
2740 GetName()->fullcommand()
2741<
2742 *funcref()*
2743funcref({name} [, {arglist}] [, {dict}])
2744 Just like |function()|, but the returned Funcref will lookup
2745 the function by reference, not by name. This matters when the
2746 function {name} is redefined later.
2747
2748 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002749 It only works for an autoloaded function if it has already
2750 been loaded (to avoid mistakenly loading the autoload script
2751 when only intending to use the function name, use |function()|
2752 instead). {name} cannot be a builtin function.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002753
2754 Can also be used as a |method|: >
2755 GetFuncname()->funcref([arg])
2756<
2757 *function()* *partial* *E700* *E922* *E923*
2758function({name} [, {arglist}] [, {dict}])
2759 Return a |Funcref| variable that refers to function {name}.
2760 {name} can be the name of a user defined function or an
2761 internal function.
2762
2763 {name} can also be a Funcref or a partial. When it is a
2764 partial the dict stored in it will be used and the {dict}
2765 argument is not allowed. E.g.: >
2766 let FuncWithArg = function(dict.Func, [arg])
2767 let Broken = function(dict.Func, [arg], dict)
2768<
2769 When using the Funcref the function will be found by {name},
2770 also when it was redefined later. Use |funcref()| to keep the
2771 same function.
2772
2773 When {arglist} or {dict} is present this creates a partial.
2774 That means the argument list and/or the dictionary is stored in
2775 the Funcref and will be used when the Funcref is called.
2776
2777 The arguments are passed to the function in front of other
2778 arguments, but after any argument from |method|. Example: >
2779 func Callback(arg1, arg2, name)
2780 ...
2781 let Partial = function('Callback', ['one', 'two'])
2782 ...
2783 call Partial('name')
2784< Invokes the function as with: >
2785 call Callback('one', 'two', 'name')
2786
2787< With a |method|: >
2788 func Callback(one, two, three)
2789 ...
2790 let Partial = function('Callback', ['two'])
2791 ...
2792 eval 'one'->Partial('three')
2793< Invokes the function as with: >
2794 call Callback('one', 'two', 'three')
2795
2796< The function() call can be nested to add more arguments to the
2797 Funcref. The extra arguments are appended to the list of
2798 arguments. Example: >
2799 func Callback(arg1, arg2, name)
2800 ...
2801 let Func = function('Callback', ['one'])
2802 let Func2 = function(Func, ['two'])
2803 ...
2804 call Func2('name')
2805< Invokes the function as with: >
2806 call Callback('one', 'two', 'name')
2807
2808< The Dictionary is only useful when calling a "dict" function.
2809 In that case the {dict} is passed in as "self". Example: >
2810 function Callback() dict
2811 echo "called for " . self.name
2812 endfunction
2813 ...
2814 let context = {"name": "example"}
2815 let Func = function('Callback', context)
2816 ...
2817 call Func() " will echo: called for example
2818< The use of function() is not needed when there are no extra
2819 arguments, these two are equivalent: >
2820 let Func = function('Callback', context)
2821 let Func = context.Callback
2822
2823< The argument list and the Dictionary can be combined: >
2824 function Callback(arg1, count) dict
2825 ...
2826 let context = {"name": "example"}
2827 let Func = function('Callback', ['one'], context)
2828 ...
2829 call Func(500)
2830< Invokes the function as with: >
2831 call context.Callback('one', 500)
2832<
2833 Can also be used as a |method|: >
2834 GetFuncname()->function([arg])
2835
2836
2837garbagecollect([{atexit}]) *garbagecollect()*
2838 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
2839 that have circular references.
2840
2841 There is hardly ever a need to invoke this function, as it is
2842 automatically done when Vim runs out of memory or is waiting
2843 for the user to press a key after 'updatetime'. Items without
2844 circular references are always freed when they become unused.
2845 This is useful if you have deleted a very big |List| and/or
2846 |Dictionary| with circular references in a script that runs
2847 for a long time.
2848
2849 When the optional {atexit} argument is one, garbage
2850 collection will also be done when exiting Vim, if it wasn't
2851 done before. This is useful when checking for memory leaks.
2852
2853 The garbage collection is not done immediately but only when
2854 it's safe to perform. This is when waiting for the user to
2855 type a character. To force garbage collection immediately use
2856 |test_garbagecollect_now()|.
2857
2858get({list}, {idx} [, {default}]) *get()*
2859 Get item {idx} from |List| {list}. When this item is not
2860 available return {default}. Return zero when {default} is
2861 omitted.
2862 Preferably used as a |method|: >
2863 mylist->get(idx)
2864get({blob}, {idx} [, {default}])
2865 Get byte {idx} from |Blob| {blob}. When this byte is not
2866 available return {default}. Return -1 when {default} is
2867 omitted.
2868 Preferably used as a |method|: >
2869 myblob->get(idx)
2870get({dict}, {key} [, {default}])
2871 Get item with key {key} from |Dictionary| {dict}. When this
2872 item is not available return {default}. Return zero when
2873 {default} is omitted. Useful example: >
2874 let val = get(g:, 'var_name', 'default')
2875< This gets the value of g:var_name if it exists, and uses
2876 'default' when it does not exist.
2877 Preferably used as a |method|: >
2878 mydict->get(key)
2879get({func}, {what})
2880 Get an item with from Funcref {func}. Possible values for
2881 {what} are:
2882 "name" The function name
2883 "func" The function
2884 "dict" The dictionary
2885 "args" The list with arguments
2886 Preferably used as a |method|: >
2887 myfunc->get(what)
2888<
2889 *getbufinfo()*
2890getbufinfo([{buf}])
2891getbufinfo([{dict}])
2892 Get information about buffers as a List of Dictionaries.
2893
2894 Without an argument information about all the buffers is
2895 returned.
2896
2897 When the argument is a |Dictionary| only the buffers matching
2898 the specified criteria are returned. The following keys can
2899 be specified in {dict}:
2900 buflisted include only listed buffers.
2901 bufloaded include only loaded buffers.
2902 bufmodified include only modified buffers.
2903
2904 Otherwise, {buf} specifies a particular buffer to return
2905 information for. For the use of {buf}, see |bufname()|
2906 above. If the buffer is found the returned List has one item.
2907 Otherwise the result is an empty list.
2908
2909 Each returned List item is a dictionary with the following
2910 entries:
2911 bufnr Buffer number.
2912 changed TRUE if the buffer is modified.
2913 changedtick Number of changes made to the buffer.
2914 hidden TRUE if the buffer is hidden.
2915 lastused Timestamp in seconds, like
2916 |localtime()|, when the buffer was
2917 last used.
2918 {only with the |+viminfo| feature}
2919 listed TRUE if the buffer is listed.
2920 lnum Line number used for the buffer when
2921 opened in the current window.
2922 Only valid if the buffer has been
2923 displayed in the window in the past.
2924 If you want the line number of the
2925 last known cursor position in a given
2926 window, use |line()|: >
2927 :echo line('.', {winid})
2928<
2929 linecount Number of lines in the buffer (only
2930 valid when loaded)
2931 loaded TRUE if the buffer is loaded.
2932 name Full path to the file in the buffer.
2933 signs List of signs placed in the buffer.
2934 Each list item is a dictionary with
2935 the following fields:
2936 id sign identifier
2937 lnum line number
2938 name sign name
2939 variables A reference to the dictionary with
2940 buffer-local variables.
2941 windows List of |window-ID|s that display this
2942 buffer
2943 popups List of popup |window-ID|s that
2944 display this buffer
2945
2946 Examples: >
2947 for buf in getbufinfo()
2948 echo buf.name
2949 endfor
2950 for buf in getbufinfo({'buflisted':1})
2951 if buf.changed
2952 ....
2953 endif
2954 endfor
2955<
2956 To get buffer-local options use: >
2957 getbufvar({bufnr}, '&option_name')
2958<
2959 Can also be used as a |method|: >
2960 GetBufnr()->getbufinfo()
2961<
2962
2963 *getbufline()*
2964getbufline({buf}, {lnum} [, {end}])
2965 Return a |List| with the lines starting from {lnum} to {end}
2966 (inclusive) in the buffer {buf}. If {end} is omitted, a
2967 |List| with only the line {lnum} is returned.
2968
2969 For the use of {buf}, see |bufname()| above.
2970
2971 For {lnum} and {end} "$" can be used for the last line of the
2972 buffer. Otherwise a number must be used.
2973
2974 When {lnum} is smaller than 1 or bigger than the number of
2975 lines in the buffer, an empty |List| is returned.
2976
2977 When {end} is greater than the number of lines in the buffer,
2978 it is treated as {end} is set to the number of lines in the
2979 buffer. When {end} is before {lnum} an empty |List| is
2980 returned.
2981
2982 This function works only for loaded buffers. For unloaded and
2983 non-existing buffers, an empty |List| is returned.
2984
2985 Example: >
2986 :let lines = getbufline(bufnr("myfile"), 1, "$")
2987
2988< Can also be used as a |method|: >
2989 GetBufnr()->getbufline(lnum)
2990
2991getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
2992 The result is the value of option or local buffer variable
2993 {varname} in buffer {buf}. Note that the name without "b:"
2994 must be used.
2995 The {varname} argument is a string.
2996 When {varname} is empty returns a |Dictionary| with all the
2997 buffer-local variables.
2998 When {varname} is equal to "&" returns a |Dictionary| with all
2999 the buffer-local options.
3000 Otherwise, when {varname} starts with "&" returns the value of
3001 a buffer-local option.
3002 This also works for a global or buffer-local option, but it
3003 doesn't work for a global variable, window-local variable or
3004 window-local option.
3005 For the use of {buf}, see |bufname()| above.
3006 When the buffer or variable doesn't exist {def} or an empty
3007 string is returned, there is no error message.
3008 Examples: >
3009 :let bufmodified = getbufvar(1, "&mod")
3010 :echo "todo myvar = " . getbufvar("todo", "myvar")
3011
3012< Can also be used as a |method|: >
3013 GetBufnr()->getbufvar(varname)
3014<
3015getchangelist([{buf}]) *getchangelist()*
3016 Returns the |changelist| for the buffer {buf}. For the use
3017 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3018 exist, an empty list is returned.
3019
3020 The returned list contains two entries: a list with the change
3021 locations and the current position in the list. Each
3022 entry in the change list is a dictionary with the following
3023 entries:
3024 col column number
3025 coladd column offset for 'virtualedit'
3026 lnum line number
3027 If buffer {buf} is the current buffer, then the current
3028 position refers to the position in the list. For other
3029 buffers, it is set to the length of the list.
3030
3031 Can also be used as a |method|: >
3032 GetBufnr()->getchangelist()
3033
3034getchar([expr]) *getchar()*
3035 Get a single character from the user or input stream.
3036 If [expr] is omitted, wait until a character is available.
3037 If [expr] is 0, only get a character when one is available.
3038 Return zero otherwise.
3039 If [expr] is 1, only check if a character is available, it is
3040 not consumed. Return zero if no character available.
3041 If you prefer always getting a string use |getcharstr()|.
3042
3043 Without [expr] and when [expr] is 0 a whole character or
3044 special key is returned. If it is a single character, the
3045 result is a number. Use nr2char() to convert it to a String.
3046 Otherwise a String is returned with the encoded character.
3047 For a special key it's a String with a sequence of bytes
3048 starting with 0x80 (decimal: 128). This is the same value as
3049 the String "\<Key>", e.g., "\<Left>". The returned value is
3050 also a String when a modifier (shift, control, alt) was used
3051 that is not included in the character.
3052
3053 When [expr] is 0 and Esc is typed, there will be a short delay
3054 while Vim waits to see if this is the start of an escape
3055 sequence.
3056
3057 When [expr] is 1 only the first byte is returned. For a
3058 one-byte character it is the character itself as a number.
3059 Use nr2char() to convert it to a String.
3060
3061 Use getcharmod() to obtain any additional modifiers.
3062
3063 When the user clicks a mouse button, the mouse event will be
3064 returned. The position can then be found in |v:mouse_col|,
3065 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3066 |getmousepos()| can also be used. Mouse move events will be
3067 ignored.
3068 This example positions the mouse as it would normally happen: >
3069 let c = getchar()
3070 if c == "\<LeftMouse>" && v:mouse_win > 0
3071 exe v:mouse_win . "wincmd w"
3072 exe v:mouse_lnum
3073 exe "normal " . v:mouse_col . "|"
3074 endif
3075<
3076 When using bracketed paste only the first character is
3077 returned, the rest of the pasted text is dropped.
3078 |xterm-bracketed-paste|.
3079
3080 There is no prompt, you will somehow have to make clear to the
3081 user that a character has to be typed. The screen is not
3082 redrawn, e.g. when resizing the window. When using a popup
3083 window it should work better with a |popup-filter|.
3084
3085 There is no mapping for the character.
3086 Key codes are replaced, thus when the user presses the <Del>
3087 key you get the code for the <Del> key, not the raw character
3088 sequence. Examples: >
3089 getchar() == "\<Del>"
3090 getchar() == "\<S-Left>"
3091< This example redefines "f" to ignore case: >
3092 :nmap f :call FindChar()<CR>
3093 :function FindChar()
3094 : let c = nr2char(getchar())
3095 : while col('.') < col('$') - 1
3096 : normal l
3097 : if getline('.')[col('.') - 1] ==? c
3098 : break
3099 : endif
3100 : endwhile
3101 :endfunction
3102<
3103 You may also receive synthetic characters, such as
3104 |<CursorHold>|. Often you will want to ignore this and get
3105 another character: >
3106 :function GetKey()
3107 : let c = getchar()
3108 : while c == "\<CursorHold>"
3109 : let c = getchar()
3110 : endwhile
3111 : return c
3112 :endfunction
3113
3114getcharmod() *getcharmod()*
3115 The result is a Number which is the state of the modifiers for
3116 the last obtained character with getchar() or in another way.
3117 These values are added together:
3118 2 shift
3119 4 control
3120 8 alt (meta)
3121 16 meta (when it's different from ALT)
3122 32 mouse double click
3123 64 mouse triple click
3124 96 mouse quadruple click (== 32 + 64)
3125 128 command (Macintosh only)
3126 Only the modifiers that have not been included in the
3127 character itself are obtained. Thus Shift-a results in "A"
3128 without a modifier.
3129
3130 *getcharpos()*
3131getcharpos({expr})
3132 Get the position for String {expr}. Same as |getpos()| but the
3133 column number in the returned List is a character index
3134 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00003135 If |getpos()| returns a very large column number, equal to
3136 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003137 of the last character.
3138
3139 Example:
3140 With the cursor on '세' in line 5 with text "여보세요": >
3141 getcharpos('.') returns [0, 5, 3, 0]
3142 getpos('.') returns [0, 5, 7, 0]
3143<
3144 Can also be used as a |method|: >
3145 GetMark()->getcharpos()
3146
3147getcharsearch() *getcharsearch()*
3148 Return the current character search information as a {dict}
3149 with the following entries:
3150
3151 char character previously used for a character
3152 search (|t|, |f|, |T|, or |F|); empty string
3153 if no character search has been performed
3154 forward direction of character search; 1 for forward,
3155 0 for backward
3156 until type of character search; 1 for a |t| or |T|
3157 character search, 0 for an |f| or |F|
3158 character search
3159
3160 This can be useful to always have |;| and |,| search
3161 forward/backward regardless of the direction of the previous
3162 character search: >
3163 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3164 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3165< Also see |setcharsearch()|.
3166
3167
3168getcharstr([expr]) *getcharstr()*
3169 Get a single character from the user or input stream as a
3170 string.
3171 If [expr] is omitted, wait until a character is available.
3172 If [expr] is 0 or false, only get a character when one is
3173 available. Return an empty string otherwise.
3174 If [expr] is 1 or true, only check if a character is
3175 available, it is not consumed. Return an empty string
3176 if no character is available.
3177 Otherwise this works like |getchar()|, except that a number
3178 result is converted to a string.
3179
3180
3181getcmdline() *getcmdline()*
3182 Return the current command-line. Only works when the command
3183 line is being edited, thus requires use of |c_CTRL-\_e| or
3184 |c_CTRL-R_=|.
3185 Example: >
3186 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
3187< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
3188 Returns an empty string when entering a password or using
3189 |inputsecret()|.
3190
3191getcmdpos() *getcmdpos()*
3192 Return the position of the cursor in the command line as a
3193 byte count. The first column is 1.
3194 Only works when editing the command line, thus requires use of
3195 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3196 Returns 0 otherwise.
3197 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3198
3199getcmdtype() *getcmdtype()*
3200 Return the current command-line type. Possible return values
3201 are:
3202 : normal Ex command
3203 > debug mode command |debug-mode|
3204 / forward search command
3205 ? backward search command
3206 @ |input()| command
3207 - |:insert| or |:append| command
3208 = |i_CTRL-R_=|
3209 Only works when editing the command line, thus requires use of
3210 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3211 Returns an empty string otherwise.
3212 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3213
3214getcmdwintype() *getcmdwintype()*
3215 Return the current |command-line-window| type. Possible return
3216 values are the same as |getcmdtype()|. Returns an empty string
3217 when not in the command-line window.
3218
3219getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
3220 Return a list of command-line completion matches. The String
3221 {type} argument specifies what for. The following completion
3222 types are supported:
3223
3224 arglist file names in argument list
3225 augroup autocmd groups
3226 buffer buffer names
3227 behave :behave suboptions
3228 color color schemes
3229 command Ex command
3230 cmdline |cmdline-completion| result
3231 compiler compilers
3232 cscope |:cscope| suboptions
3233 diff_buffer |:diffget| and |:diffput| completion
3234 dir directory names
3235 environment environment variable names
3236 event autocommand events
3237 expression Vim expression
3238 file file and directory names
3239 file_in_path file and directory names in |'path'|
3240 filetype filetype names |'filetype'|
3241 function function name
3242 help help subjects
3243 highlight highlight groups
3244 history :history suboptions
3245 locale locale names (as output of locale -a)
3246 mapclear buffer argument
3247 mapping mapping name
3248 menu menus
3249 messages |:messages| suboptions
3250 option options
3251 packadd optional package |pack-add| names
3252 shellcmd Shell command
3253 sign |:sign| suboptions
3254 syntax syntax file names |'syntax'|
3255 syntime |:syntime| suboptions
3256 tag tags
3257 tag_listfiles tags, file names
3258 user user names
3259 var user variables
3260
3261 If {pat} is an empty string, then all the matches are
3262 returned. Otherwise only items matching {pat} are returned.
3263 See |wildcards| for the use of special characters in {pat}.
3264
3265 If the optional {filtered} flag is set to 1, then 'wildignore'
3266 is applied to filter the results. Otherwise all the matches
3267 are returned. The 'wildignorecase' option always applies.
3268
3269 If {type} is "cmdline", then the |cmdline-completion| result is
3270 returned. For example, to complete the possible values after
3271 a ":call" command: >
3272 echo getcompletion('call ', 'cmdline')
3273<
3274 If there are no matches, an empty list is returned. An
3275 invalid value for {type} produces an error.
3276
3277 Can also be used as a |method|: >
3278 GetPattern()->getcompletion('color')
3279<
3280 *getcurpos()*
3281getcurpos([{winid}])
3282 Get the position of the cursor. This is like getpos('.'), but
3283 includes an extra "curswant" item in the list:
3284 [0, lnum, col, off, curswant] ~
3285 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00003286 cursor vertically. After |$| command it will be a very large
3287 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003288 |getpos()|.
3289 The first "bufnum" item is always zero. The byte position of
3290 the cursor is returned in 'col'. To get the character
3291 position, use |getcursorcharpos()|.
3292
3293 The optional {winid} argument can specify the window. It can
3294 be the window number or the |window-ID|. The last known
3295 cursor position is returned, this may be invalid for the
3296 current value of the buffer if it is not the current window.
3297 If {winid} is invalid a list with zeroes is returned.
3298
3299 This can be used to save and restore the cursor position: >
3300 let save_cursor = getcurpos()
3301 MoveTheCursorAround
3302 call setpos('.', save_cursor)
3303< Note that this only works within the window. See
3304 |winrestview()| for restoring more state.
3305
3306 Can also be used as a |method|: >
3307 GetWinid()->getcurpos()
3308<
3309 *getcursorcharpos()*
3310getcursorcharpos([{winid}])
3311 Same as |getcurpos()| but the column number in the returned
3312 List is a character index instead of a byte index.
3313
3314 Example:
3315 With the cursor on '보' in line 3 with text "여보세요": >
3316 getcursorcharpos() returns [0, 3, 2, 0, 3]
3317 getcurpos() returns [0, 3, 4, 0, 3]
3318<
3319 Can also be used as a |method|: >
3320 GetWinid()->getcursorcharpos()
3321
3322< *getcwd()*
3323getcwd([{winnr} [, {tabnr}]])
3324 The result is a String, which is the name of the current
3325 working directory. 'autochdir' is ignored.
3326
3327 With {winnr} return the local current directory of this window
3328 in the current tab page. {winnr} can be the window number or
3329 the |window-ID|.
3330 If {winnr} is -1 return the name of the global working
3331 directory. See also |haslocaldir()|.
3332
3333 With {winnr} and {tabnr} return the local current directory of
3334 the window in the specified tab page. If {winnr} is -1 return
3335 the working directory of the tabpage.
3336 If {winnr} is zero use the current window, if {tabnr} is zero
3337 use the current tabpage.
3338 Without any arguments, return the actual working directory of
3339 the current window.
3340 Return an empty string if the arguments are invalid.
3341
3342 Examples: >
3343 " Get the working directory of the current window
3344 :echo getcwd()
3345 :echo getcwd(0)
3346 :echo getcwd(0, 0)
3347 " Get the working directory of window 3 in tabpage 2
3348 :echo getcwd(3, 2)
3349 " Get the global working directory
3350 :echo getcwd(-1)
3351 " Get the working directory of tabpage 3
3352 :echo getcwd(-1, 3)
3353 " Get the working directory of current tabpage
3354 :echo getcwd(-1, 0)
3355
3356< Can also be used as a |method|: >
3357 GetWinnr()->getcwd()
3358
3359getenv({name}) *getenv()*
3360 Return the value of environment variable {name}. The {name}
3361 argument is a string, without a leading '$'. Example: >
3362 myHome = getenv('HOME')
3363
3364< When the variable does not exist |v:null| is returned. That
3365 is different from a variable set to an empty string, although
3366 some systems interpret the empty value as the variable being
3367 deleted. See also |expr-env|.
3368
3369 Can also be used as a |method|: >
3370 GetVarname()->getenv()
3371
3372getfontname([{name}]) *getfontname()*
3373 Without an argument returns the name of the normal font being
3374 used. Like what is used for the Normal highlight group
3375 |hl-Normal|.
3376 With an argument a check is done whether String {name} is a
3377 valid font name. If not then an empty string is returned.
3378 Otherwise the actual font name is returned, or {name} if the
3379 GUI does not support obtaining the real name.
3380 Only works when the GUI is running, thus not in your vimrc or
3381 gvimrc file. Use the |GUIEnter| autocommand to use this
3382 function just after the GUI has started.
3383 Note that the GTK GUI accepts any font name, thus checking for
3384 a valid name does not work.
3385
3386getfperm({fname}) *getfperm()*
3387 The result is a String, which is the read, write, and execute
3388 permissions of the given file {fname}.
3389 If {fname} does not exist or its directory cannot be read, an
3390 empty string is returned.
3391 The result is of the form "rwxrwxrwx", where each group of
3392 "rwx" flags represent, in turn, the permissions of the owner
3393 of the file, the group the file belongs to, and other users.
3394 If a user does not have a given permission the flag for this
3395 is replaced with the string "-". Examples: >
3396 :echo getfperm("/etc/passwd")
3397 :echo getfperm(expand("~/.vimrc"))
3398< This will hopefully (from a security point of view) display
3399 the string "rw-r--r--" or even "rw-------".
3400
3401 Can also be used as a |method|: >
3402 GetFilename()->getfperm()
3403<
3404 For setting permissions use |setfperm()|.
3405
3406getfsize({fname}) *getfsize()*
3407 The result is a Number, which is the size in bytes of the
3408 given file {fname}.
3409 If {fname} is a directory, 0 is returned.
3410 If the file {fname} can't be found, -1 is returned.
3411 If the size of {fname} is too big to fit in a Number then -2
3412 is returned.
3413
3414 Can also be used as a |method|: >
3415 GetFilename()->getfsize()
3416
3417getftime({fname}) *getftime()*
3418 The result is a Number, which is the last modification time of
3419 the given file {fname}. The value is measured as seconds
3420 since 1st Jan 1970, and may be passed to strftime(). See also
3421 |localtime()| and |strftime()|.
3422 If the file {fname} can't be found -1 is returned.
3423
3424 Can also be used as a |method|: >
3425 GetFilename()->getftime()
3426
3427getftype({fname}) *getftype()*
3428 The result is a String, which is a description of the kind of
3429 file of the given file {fname}.
3430 If {fname} does not exist an empty string is returned.
3431 Here is a table over different kinds of files and their
3432 results:
3433 Normal file "file"
3434 Directory "dir"
3435 Symbolic link "link"
3436 Block device "bdev"
3437 Character device "cdev"
3438 Socket "socket"
3439 FIFO "fifo"
3440 All other "other"
3441 Example: >
3442 getftype("/home")
3443< Note that a type such as "link" will only be returned on
3444 systems that support it. On some systems only "dir" and
3445 "file" are returned. On MS-Windows a symbolic link to a
3446 directory returns "dir" instead of "link".
3447
3448 Can also be used as a |method|: >
3449 GetFilename()->getftype()
3450
3451getimstatus() *getimstatus()*
3452 The result is a Number, which is |TRUE| when the IME status is
3453 active.
3454 See 'imstatusfunc'.
3455
3456getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
3457 Returns the |jumplist| for the specified window.
3458
3459 Without arguments use the current window.
3460 With {winnr} only use this window in the current tab page.
3461 {winnr} can also be a |window-ID|.
3462 With {winnr} and {tabnr} use the window in the specified tab
3463 page.
3464
3465 The returned list contains two entries: a list with the jump
3466 locations and the last used jump position number in the list.
3467 Each entry in the jump location list is a dictionary with
3468 the following entries:
3469 bufnr buffer number
3470 col column number
3471 coladd column offset for 'virtualedit'
3472 filename filename if available
3473 lnum line number
3474
3475 Can also be used as a |method|: >
3476 GetWinnr()->getjumplist()
3477
3478< *getline()*
3479getline({lnum} [, {end}])
3480 Without {end} the result is a String, which is line {lnum}
3481 from the current buffer. Example: >
3482 getline(1)
3483< When {lnum} is a String that doesn't start with a
3484 digit, |line()| is called to translate the String into a Number.
3485 To get the line under the cursor: >
3486 getline(".")
3487< When {lnum} is a number smaller than 1 or bigger than the
3488 number of lines in the buffer, an empty string is returned.
3489
3490 When {end} is given the result is a |List| where each item is
3491 a line from the current buffer in the range {lnum} to {end},
3492 including line {end}.
3493 {end} is used in the same way as {lnum}.
3494 Non-existing lines are silently omitted.
3495 When {end} is before {lnum} an empty |List| is returned.
3496 Example: >
3497 :let start = line('.')
3498 :let end = search("^$") - 1
3499 :let lines = getline(start, end)
3500
3501< Can also be used as a |method|: >
3502 ComputeLnum()->getline()
3503
3504< To get lines from another buffer see |getbufline()|
3505
3506getloclist({nr} [, {what}]) *getloclist()*
3507 Returns a |List| with all the entries in the location list for
3508 window {nr}. {nr} can be the window number or the |window-ID|.
3509 When {nr} is zero the current window is used.
3510
3511 For a location list window, the displayed location list is
3512 returned. For an invalid window number {nr}, an empty list is
3513 returned. Otherwise, same as |getqflist()|.
3514
3515 If the optional {what} dictionary argument is supplied, then
3516 returns the items listed in {what} as a dictionary. Refer to
3517 |getqflist()| for the supported items in {what}.
3518
3519 In addition to the items supported by |getqflist()| in {what},
3520 the following item is supported by |getloclist()|:
3521
3522 filewinid id of the window used to display files
3523 from the location list. This field is
3524 applicable only when called from a
3525 location list window. See
3526 |location-list-file-window| for more
3527 details.
3528
3529 Returns a |Dictionary| with default values if there is no
3530 location list for the window {nr}.
3531 Returns an empty Dictionary if window {nr} does not exist.
3532
3533 Examples (See also |getqflist-examples|): >
3534 :echo getloclist(3, {'all': 0})
3535 :echo getloclist(5, {'filewinid': 0})
3536
3537
3538getmarklist([{buf}]) *getmarklist()*
3539 Without the {buf} argument returns a |List| with information
3540 about all the global marks. |mark|
3541
3542 If the optional {buf} argument is specified, returns the
3543 local marks defined in buffer {buf}. For the use of {buf},
3544 see |bufname()|.
3545
3546 Each item in the returned List is a |Dict| with the following:
3547 mark name of the mark prefixed by "'"
3548 pos a |List| with the position of the mark:
3549 [bufnum, lnum, col, off]
3550 Refer to |getpos()| for more information.
3551 file file name
3552
3553 Refer to |getpos()| for getting information about a specific
3554 mark.
3555
3556 Can also be used as a |method|: >
3557 GetBufnr()->getmarklist()
3558
3559getmatches([{win}]) *getmatches()*
3560 Returns a |List| with all matches previously defined for the
3561 current window by |matchadd()| and the |:match| commands.
3562 |getmatches()| is useful in combination with |setmatches()|,
3563 as |setmatches()| can restore a list of matches saved by
3564 |getmatches()|.
3565 If {win} is specified, use the window with this number or
3566 window ID instead of the current window.
3567 Example: >
3568 :echo getmatches()
3569< [{'group': 'MyGroup1', 'pattern': 'TODO',
3570 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3571 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3572 :let m = getmatches()
3573 :call clearmatches()
3574 :echo getmatches()
3575< [] >
3576 :call setmatches(m)
3577 :echo getmatches()
3578< [{'group': 'MyGroup1', 'pattern': 'TODO',
3579 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3580 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3581 :unlet m
3582<
3583getmousepos() *getmousepos()*
3584 Returns a |Dictionary| with the last known position of the
3585 mouse. This can be used in a mapping for a mouse click or in
3586 a filter of a popup window. The items are:
3587 screenrow screen row
3588 screencol screen column
3589 winid Window ID of the click
3590 winrow row inside "winid"
3591 wincol column inside "winid"
3592 line text line inside "winid"
3593 column text column inside "winid"
3594 All numbers are 1-based.
3595
3596 If not over a window, e.g. when in the command line, then only
3597 "screenrow" and "screencol" are valid, the others are zero.
3598
3599 When on the status line below a window or the vertical
3600 separator right of a window, the "line" and "column" values
3601 are zero.
3602
3603 When the position is after the text then "column" is the
3604 length of the text in bytes plus one.
3605
3606 If the mouse is over a popup window then that window is used.
3607
3608 When using |getchar()| the Vim variables |v:mouse_lnum|,
3609 |v:mouse_col| and |v:mouse_winid| also provide these values.
3610
3611 *getpid()*
3612getpid() Return a Number which is the process ID of the Vim process.
3613 On Unix and MS-Windows this is a unique number, until Vim
3614 exits.
3615
3616 *getpos()*
3617getpos({expr}) Get the position for String {expr}. For possible values of
3618 {expr} see |line()|. For getting the cursor position see
3619 |getcurpos()|.
3620 The result is a |List| with four numbers:
3621 [bufnum, lnum, col, off]
3622 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3623 is the buffer number of the mark.
3624 "lnum" and "col" are the position in the buffer. The first
3625 column is 1.
3626 The "off" number is zero, unless 'virtualedit' is used. Then
3627 it is the offset in screen columns from the start of the
3628 character. E.g., a position within a <Tab> or after the last
3629 character.
3630 Note that for '< and '> Visual mode matters: when it is "V"
3631 (visual line mode) the column of '< is zero and the column of
naohiro ono56200ee2022-01-01 14:59:44 +00003632 '> is a large number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003633 The column number in the returned List is the byte position
3634 within the line. To get the character position in the line,
3635 use |getcharpos()|.
naohiro ono56200ee2022-01-01 14:59:44 +00003636 A very large column number equal to |v:maxcol| can be returned,
3637 in which case it means "after the end of the line".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003638 This can be used to save and restore the position of a mark: >
3639 let save_a_mark = getpos("'a")
3640 ...
3641 call setpos("'a", save_a_mark)
3642< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
3643
3644 Can also be used as a |method|: >
3645 GetMark()->getpos()
3646
3647getqflist([{what}]) *getqflist()*
3648 Returns a |List| with all the current quickfix errors. Each
3649 list item is a dictionary with these entries:
3650 bufnr number of buffer that has the file name, use
3651 bufname() to get the name
3652 module module name
3653 lnum line number in the buffer (first line is 1)
3654 end_lnum
3655 end of line number if the item is multiline
3656 col column number (first column is 1)
3657 end_col end of column number if the item has range
3658 vcol |TRUE|: "col" is visual column
3659 |FALSE|: "col" is byte index
3660 nr error number
3661 pattern search pattern used to locate the error
3662 text description of the error
3663 type type of the error, 'E', '1', etc.
3664 valid |TRUE|: recognized error message
3665
3666 When there is no error list or it's empty, an empty list is
3667 returned. Quickfix list entries with a non-existing buffer
3668 number are returned with "bufnr" set to zero (Note: some
3669 functions accept buffer number zero for the alternate buffer,
3670 you may need to explicitly check for zero).
3671
3672 Useful application: Find pattern matches in multiple files and
3673 do something with them: >
3674 :vimgrep /theword/jg *.c
3675 :for d in getqflist()
3676 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3677 :endfor
3678<
3679 If the optional {what} dictionary argument is supplied, then
3680 returns only the items listed in {what} as a dictionary. The
3681 following string items are supported in {what}:
3682 changedtick get the total number of changes made
3683 to the list |quickfix-changedtick|
3684 context get the |quickfix-context|
3685 efm errorformat to use when parsing "lines". If
3686 not present, then the 'errorformat' option
3687 value is used.
3688 id get information for the quickfix list with
3689 |quickfix-ID|; zero means the id for the
3690 current list or the list specified by "nr"
3691 idx get information for the quickfix entry at this
3692 index in the list specified by 'id' or 'nr'.
3693 If set to zero, then uses the current entry.
3694 See |quickfix-index|
3695 items quickfix list entries
3696 lines parse a list of lines using 'efm' and return
3697 the resulting entries. Only a |List| type is
3698 accepted. The current quickfix list is not
3699 modified. See |quickfix-parse|.
3700 nr get information for this quickfix list; zero
3701 means the current quickfix list and "$" means
3702 the last quickfix list
3703 qfbufnr number of the buffer displayed in the quickfix
3704 window. Returns 0 if the quickfix buffer is
3705 not present. See |quickfix-buffer|.
3706 size number of entries in the quickfix list
3707 title get the list title |quickfix-title|
3708 winid get the quickfix |window-ID|
3709 all all of the above quickfix properties
3710 Non-string items in {what} are ignored. To get the value of a
3711 particular item, set it to zero.
3712 If "nr" is not present then the current quickfix list is used.
3713 If both "nr" and a non-zero "id" are specified, then the list
3714 specified by "id" is used.
3715 To get the number of lists in the quickfix stack, set "nr" to
3716 "$" in {what}. The "nr" value in the returned dictionary
3717 contains the quickfix stack size.
3718 When "lines" is specified, all the other items except "efm"
3719 are ignored. The returned dictionary contains the entry
3720 "items" with the list of entries.
3721
3722 The returned dictionary contains the following entries:
3723 changedtick total number of changes made to the
3724 list |quickfix-changedtick|
3725 context quickfix list context. See |quickfix-context|
3726 If not present, set to "".
3727 id quickfix list ID |quickfix-ID|. If not
3728 present, set to 0.
3729 idx index of the quickfix entry in the list. If not
3730 present, set to 0.
3731 items quickfix list entries. If not present, set to
3732 an empty list.
3733 nr quickfix list number. If not present, set to 0
3734 qfbufnr number of the buffer displayed in the quickfix
3735 window. If not present, set to 0.
3736 size number of entries in the quickfix list. If not
3737 present, set to 0.
3738 title quickfix list title text. If not present, set
3739 to "".
3740 winid quickfix |window-ID|. If not present, set to 0
3741
3742 Examples (See also |getqflist-examples|): >
3743 :echo getqflist({'all': 1})
3744 :echo getqflist({'nr': 2, 'title': 1})
3745 :echo getqflist({'lines' : ["F1:10:L10"]})
3746<
3747getreg([{regname} [, 1 [, {list}]]]) *getreg()*
3748 The result is a String, which is the contents of register
3749 {regname}. Example: >
3750 :let cliptext = getreg('*')
3751< When register {regname} was not set the result is an empty
3752 string.
3753 The {regname} argument must be a string.
3754
3755 getreg('=') returns the last evaluated value of the expression
3756 register. (For use in maps.)
3757 getreg('=', 1) returns the expression itself, so that it can
3758 be restored with |setreg()|. For other registers the extra
3759 argument is ignored, thus you can always give it.
3760
3761 If {list} is present and |TRUE|, the result type is changed
3762 to |List|. Each list item is one text line. Use it if you care
3763 about zero bytes possibly present inside register: without
3764 third argument both NLs and zero bytes are represented as NLs
3765 (see |NL-used-for-Nul|).
3766 When the register was not set an empty list is returned.
3767
3768 If {regname} is "", the unnamed register '"' is used.
3769 If {regname} is not specified, |v:register| is used.
3770 In |Vim9-script| {regname} must be one character.
3771
3772 Can also be used as a |method|: >
3773 GetRegname()->getreg()
3774
3775getreginfo([{regname}]) *getreginfo()*
3776 Returns detailed information about register {regname} as a
3777 Dictionary with the following entries:
3778 regcontents List of lines contained in register
3779 {regname}, like
3780 |getreg|({regname}, 1, 1).
3781 regtype the type of register {regname}, as in
3782 |getregtype()|.
3783 isunnamed Boolean flag, v:true if this register
3784 is currently pointed to by the unnamed
3785 register.
3786 points_to for the unnamed register, gives the
3787 single letter name of the register
3788 currently pointed to (see |quotequote|).
3789 For example, after deleting a line
3790 with `dd`, this field will be "1",
3791 which is the register that got the
3792 deleted text.
3793
3794 The {regname} argument is a string. If {regname} is invalid
3795 or not set, an empty Dictionary will be returned.
3796 If {regname} is "" or "@", the unnamed register '"' is used.
3797 If {regname} is not specified, |v:register| is used.
3798 The returned Dictionary can be passed to |setreg()|.
3799 In |Vim9-script| {regname} must be one character.
3800
3801 Can also be used as a |method|: >
3802 GetRegname()->getreginfo()
3803
3804getregtype([{regname}]) *getregtype()*
3805 The result is a String, which is type of register {regname}.
3806 The value will be one of:
3807 "v" for |characterwise| text
3808 "V" for |linewise| text
3809 "<CTRL-V>{width}" for |blockwise-visual| text
3810 "" for an empty or unknown register
3811 <CTRL-V> is one character with value 0x16.
3812 The {regname} argument is a string. If {regname} is "", the
3813 unnamed register '"' is used. If {regname} is not specified,
3814 |v:register| is used.
3815 In |Vim9-script| {regname} must be one character.
3816
3817 Can also be used as a |method|: >
3818 GetRegname()->getregtype()
3819
3820gettabinfo([{tabnr}]) *gettabinfo()*
3821 If {tabnr} is not specified, then information about all the
3822 tab pages is returned as a |List|. Each List item is a
3823 |Dictionary|. Otherwise, {tabnr} specifies the tab page
3824 number and information about that one is returned. If the tab
3825 page does not exist an empty List is returned.
3826
3827 Each List item is a |Dictionary| with the following entries:
3828 tabnr tab page number.
3829 variables a reference to the dictionary with
3830 tabpage-local variables
3831 windows List of |window-ID|s in the tab page.
3832
3833 Can also be used as a |method|: >
3834 GetTabnr()->gettabinfo()
3835
3836gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
3837 Get the value of a tab-local variable {varname} in tab page
3838 {tabnr}. |t:var|
3839 Tabs are numbered starting with one.
3840 The {varname} argument is a string. When {varname} is empty a
3841 dictionary with all tab-local variables is returned.
3842 Note that the name without "t:" must be used.
3843 When the tab or variable doesn't exist {def} or an empty
3844 string is returned, there is no error message.
3845
3846 Can also be used as a |method|: >
3847 GetTabnr()->gettabvar(varname)
3848
3849gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
3850 Get the value of window-local variable {varname} in window
3851 {winnr} in tab page {tabnr}.
3852 The {varname} argument is a string. When {varname} is empty a
3853 dictionary with all window-local variables is returned.
3854 When {varname} is equal to "&" get the values of all
3855 window-local options in a |Dictionary|.
3856 Otherwise, when {varname} starts with "&" get the value of a
3857 window-local option.
3858 Note that {varname} must be the name without "w:".
3859 Tabs are numbered starting with one. For the current tabpage
3860 use |getwinvar()|.
3861 {winnr} can be the window number or the |window-ID|.
3862 When {winnr} is zero the current window is used.
3863 This also works for a global option, buffer-local option and
3864 window-local option, but it doesn't work for a global variable
3865 or buffer-local variable.
3866 When the tab, window or variable doesn't exist {def} or an
3867 empty string is returned, there is no error message.
3868 Examples: >
3869 :let list_is_on = gettabwinvar(1, 2, '&list')
3870 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
3871<
3872 To obtain all window-local variables use: >
3873 gettabwinvar({tabnr}, {winnr}, '&')
3874
3875< Can also be used as a |method|: >
3876 GetTabnr()->gettabwinvar(winnr, varname)
3877
3878gettagstack([{winnr}]) *gettagstack()*
3879 The result is a Dict, which is the tag stack of window {winnr}.
3880 {winnr} can be the window number or the |window-ID|.
3881 When {winnr} is not specified, the current window is used.
3882 When window {winnr} doesn't exist, an empty Dict is returned.
3883
3884 The returned dictionary contains the following entries:
3885 curidx Current index in the stack. When at
3886 top of the stack, set to (length + 1).
3887 Index of bottom of the stack is 1.
3888 items List of items in the stack. Each item
3889 is a dictionary containing the
3890 entries described below.
3891 length Number of entries in the stack.
3892
3893 Each item in the stack is a dictionary with the following
3894 entries:
3895 bufnr buffer number of the current jump
3896 from cursor position before the tag jump.
3897 See |getpos()| for the format of the
3898 returned list.
3899 matchnr current matching tag number. Used when
3900 multiple matching tags are found for a
3901 name.
3902 tagname name of the tag
3903
3904 See |tagstack| for more information about the tag stack.
3905
3906 Can also be used as a |method|: >
3907 GetWinnr()->gettagstack()
3908
3909
3910gettext({text}) *gettext()*
3911 Translate String {text} if possible.
3912 This is mainly for use in the distributed Vim scripts. When
3913 generating message translations the {text} is extracted by
3914 xgettext, the translator can add the translated message in the
3915 .po file and Vim will lookup the translation when gettext() is
3916 called.
3917 For {text} double quoted strings are preferred, because
3918 xgettext does not understand escaping in single quoted
3919 strings.
3920
3921
3922getwininfo([{winid}]) *getwininfo()*
3923 Returns information about windows as a |List| with Dictionaries.
3924
3925 If {winid} is given Information about the window with that ID
3926 is returned, as a |List| with one item. If the window does not
3927 exist the result is an empty list.
3928
3929 Without {winid} information about all the windows in all the
3930 tab pages is returned.
3931
3932 Each List item is a |Dictionary| with the following entries:
3933 botline last complete displayed buffer line
3934 bufnr number of buffer in the window
3935 height window height (excluding winbar)
3936 loclist 1 if showing a location list
3937 {only with the +quickfix feature}
3938 quickfix 1 if quickfix or location list window
3939 {only with the +quickfix feature}
3940 terminal 1 if a terminal window
3941 {only with the +terminal feature}
3942 tabnr tab page number
3943 topline first displayed buffer line
3944 variables a reference to the dictionary with
3945 window-local variables
3946 width window width
3947 winbar 1 if the window has a toolbar, 0
3948 otherwise
3949 wincol leftmost screen column of the window;
3950 "col" from |win_screenpos()|
3951 textoff number of columns occupied by any
3952 'foldcolumn', 'signcolumn' and line
3953 number in front of the text
3954 winid |window-ID|
3955 winnr window number
3956 winrow topmost screen line of the window;
3957 "row" from |win_screenpos()|
3958
3959 Can also be used as a |method|: >
3960 GetWinnr()->getwininfo()
3961
3962getwinpos([{timeout}]) *getwinpos()*
3963 The result is a |List| with two numbers, the result of
3964 |getwinposx()| and |getwinposy()| combined:
3965 [x-pos, y-pos]
3966 {timeout} can be used to specify how long to wait in msec for
3967 a response from the terminal. When omitted 100 msec is used.
3968 Use a longer time for a remote terminal.
3969 When using a value less than 10 and no response is received
3970 within that time, a previously reported position is returned,
3971 if available. This can be used to poll for the position and
3972 do some work in the meantime: >
3973 while 1
3974 let res = getwinpos(1)
3975 if res[0] >= 0
3976 break
3977 endif
3978 " Do some work here
3979 endwhile
3980<
3981
3982 Can also be used as a |method|: >
3983 GetTimeout()->getwinpos()
3984<
3985 *getwinposx()*
3986getwinposx() The result is a Number, which is the X coordinate in pixels of
3987 the left hand side of the GUI Vim window. Also works for an
3988 xterm (uses a timeout of 100 msec).
3989 The result will be -1 if the information is not available.
3990 The value can be used with `:winpos`.
3991
3992 *getwinposy()*
3993getwinposy() The result is a Number, which is the Y coordinate in pixels of
3994 the top of the GUI Vim window. Also works for an xterm (uses
3995 a timeout of 100 msec).
3996 The result will be -1 if the information is not available.
3997 The value can be used with `:winpos`.
3998
3999getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
4000 Like |gettabwinvar()| for the current tabpage.
4001 Examples: >
4002 :let list_is_on = getwinvar(2, '&list')
4003 :echo "myvar = " . getwinvar(1, 'myvar')
4004
4005< Can also be used as a |method|: >
4006 GetWinnr()->getwinvar(varname)
4007<
4008glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
4009 Expand the file wildcards in {expr}. See |wildcards| for the
4010 use of special characters.
4011
4012 Unless the optional {nosuf} argument is given and is |TRUE|,
4013 the 'suffixes' and 'wildignore' options apply: Names matching
4014 one of the patterns in 'wildignore' will be skipped and
4015 'suffixes' affect the ordering of matches.
4016 'wildignorecase' always applies.
4017
4018 When {list} is present and it is |TRUE| the result is a |List|
4019 with all matching files. The advantage of using a List is,
4020 you also get filenames containing newlines correctly.
4021 Otherwise the result is a String and when there are several
4022 matches, they are separated by <NL> characters.
4023
4024 If the expansion fails, the result is an empty String or List.
4025
4026 You can also use |readdir()| if you need to do complicated
4027 things, such as limiting the number of matches.
4028
4029 A name for a non-existing file is not included. A symbolic
4030 link is only included if it points to an existing file.
4031 However, when the {alllinks} argument is present and it is
4032 |TRUE| then all symbolic links are included.
4033
4034 For most systems backticks can be used to get files names from
4035 any external command. Example: >
4036 :let tagfiles = glob("`find . -name tags -print`")
4037 :let &tags = substitute(tagfiles, "\n", ",", "g")
4038< The result of the program inside the backticks should be one
4039 item per line. Spaces inside an item are allowed.
4040
4041 See |expand()| for expanding special Vim variables. See
4042 |system()| for getting the raw output of an external command.
4043
4044 Can also be used as a |method|: >
4045 GetExpr()->glob()
4046
4047glob2regpat({string}) *glob2regpat()*
4048 Convert a file pattern, as used by glob(), into a search
4049 pattern. The result can be used to match with a string that
4050 is a file name. E.g. >
4051 if filename =~ glob2regpat('Make*.mak')
4052< This is equivalent to: >
4053 if filename =~ '^Make.*\.mak$'
4054< When {string} is an empty string the result is "^$", match an
4055 empty string.
4056 Note that the result depends on the system. On MS-Windows
4057 a backslash usually means a path separator.
4058
4059 Can also be used as a |method|: >
4060 GetExpr()->glob2regpat()
4061< *globpath()*
4062globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
4063 Perform glob() for String {expr} on all directories in {path}
4064 and concatenate the results. Example: >
4065 :echo globpath(&rtp, "syntax/c.vim")
4066<
4067 {path} is a comma-separated list of directory names. Each
4068 directory name is prepended to {expr} and expanded like with
4069 |glob()|. A path separator is inserted when needed.
4070 To add a comma inside a directory name escape it with a
4071 backslash. Note that on MS-Windows a directory may have a
4072 trailing backslash, remove it if you put a comma after it.
4073 If the expansion fails for one of the directories, there is no
4074 error message.
4075
4076 Unless the optional {nosuf} argument is given and is |TRUE|,
4077 the 'suffixes' and 'wildignore' options apply: Names matching
4078 one of the patterns in 'wildignore' will be skipped and
4079 'suffixes' affect the ordering of matches.
4080
4081 When {list} is present and it is |TRUE| the result is a |List|
4082 with all matching files. The advantage of using a List is, you
4083 also get filenames containing newlines correctly. Otherwise
4084 the result is a String and when there are several matches,
4085 they are separated by <NL> characters. Example: >
4086 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4087<
4088 {alllinks} is used as with |glob()|.
4089
4090 The "**" item can be used to search in a directory tree.
4091 For example, to find all "README.txt" files in the directories
4092 in 'runtimepath' and below: >
4093 :echo globpath(&rtp, "**/README.txt")
4094< Upwards search and limiting the depth of "**" is not
4095 supported, thus using 'path' will not always work properly.
4096
4097 Can also be used as a |method|, the base is passed as the
4098 second argument: >
4099 GetExpr()->globpath(&rtp)
4100<
4101 *has()*
4102has({feature} [, {check}])
4103 When {check} is omitted or is zero: The result is a Number,
4104 which is 1 if the feature {feature} is supported, zero
4105 otherwise. The {feature} argument is a string, case is
4106 ignored. See |feature-list| below.
4107
4108 When {check} is present and not zero: The result is a Number,
4109 which is 1 if the feature {feature} could ever be supported,
4110 zero otherwise. This is useful to check for a typo in
4111 {feature} and to detect dead code. Keep in mind that an older
4112 Vim version will not know about a feature added later and
4113 features that have been abandoned will not be known by the
4114 current Vim version.
4115
4116 Also see |exists()| and |exists_compiled()|.
4117
4118 Note that to skip code that has a syntax error when the
4119 feature is not available, Vim may skip the rest of the line
4120 and miss a following `endif`. Therefore put the `endif` on a
4121 separate line: >
4122 if has('feature')
4123 let x = this->breaks->without->the->feature
4124 endif
4125< If the `endif` would be moved to the second line as "| endif" it
4126 would not be found.
4127
4128
4129has_key({dict}, {key}) *has_key()*
4130 The result is a Number, which is TRUE if |Dictionary| {dict}
4131 has an entry with key {key}. FALSE otherwise. The {key}
4132 argument is a string.
4133
4134 Can also be used as a |method|: >
4135 mydict->has_key(key)
4136
4137haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4138 The result is a Number:
4139 1 when the window has set a local directory via |:lcd|
4140 2 when the tab-page has set a local directory via |:tcd|
4141 0 otherwise.
4142
4143 Without arguments use the current window.
4144 With {winnr} use this window in the current tab page.
4145 With {winnr} and {tabnr} use the window in the specified tab
4146 page.
4147 {winnr} can be the window number or the |window-ID|.
4148 If {winnr} is -1 it is ignored and only the tabpage is used.
4149 Return 0 if the arguments are invalid.
4150 Examples: >
4151 if haslocaldir() == 1
4152 " window local directory case
4153 elseif haslocaldir() == 2
4154 " tab-local directory case
4155 else
4156 " global directory case
4157 endif
4158
4159 " current window
4160 :echo haslocaldir()
4161 :echo haslocaldir(0)
4162 :echo haslocaldir(0, 0)
4163 " window n in current tab page
4164 :echo haslocaldir(n)
4165 :echo haslocaldir(n, 0)
4166 " window n in tab page m
4167 :echo haslocaldir(n, m)
4168 " tab page m
4169 :echo haslocaldir(-1, m)
4170<
4171 Can also be used as a |method|: >
4172 GetWinnr()->haslocaldir()
4173
4174hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
4175 The result is a Number, which is TRUE if there is a mapping
4176 that contains {what} in somewhere in the rhs (what it is
4177 mapped to) and this mapping exists in one of the modes
4178 indicated by {mode}.
4179 The arguments {what} and {mode} are strings.
4180 When {abbr} is there and it is |TRUE| use abbreviations
4181 instead of mappings. Don't forget to specify Insert and/or
4182 Command-line mode.
4183 Both the global mappings and the mappings local to the current
4184 buffer are checked for a match.
4185 If no matching mapping is found FALSE is returned.
4186 The following characters are recognized in {mode}:
4187 n Normal mode
4188 v Visual and Select mode
4189 x Visual mode
4190 s Select mode
4191 o Operator-pending mode
4192 i Insert mode
4193 l Language-Argument ("r", "f", "t", etc.)
4194 c Command-line mode
4195 When {mode} is omitted, "nvo" is used.
4196
4197 This function is useful to check if a mapping already exists
4198 to a function in a Vim script. Example: >
4199 :if !hasmapto('\ABCdoit')
4200 : map <Leader>d \ABCdoit
4201 :endif
4202< This installs the mapping to "\ABCdoit" only if there isn't
4203 already a mapping to "\ABCdoit".
4204
4205 Can also be used as a |method|: >
4206 GetRHS()->hasmapto()
4207
4208histadd({history}, {item}) *histadd()*
4209 Add the String {item} to the history {history} which can be
4210 one of: *hist-names*
4211 "cmd" or ":" command line history
4212 "search" or "/" search pattern history
4213 "expr" or "=" typed expression history
4214 "input" or "@" input line history
4215 "debug" or ">" debug command history
4216 empty the current or last used history
4217 The {history} string does not need to be the whole name, one
4218 character is sufficient.
4219 If {item} does already exist in the history, it will be
4220 shifted to become the newest entry.
4221 The result is a Number: TRUE if the operation was successful,
4222 otherwise FALSE is returned.
4223
4224 Example: >
4225 :call histadd("input", strftime("%Y %b %d"))
4226 :let date=input("Enter date: ")
4227< This function is not available in the |sandbox|.
4228
4229 Can also be used as a |method|, the base is passed as the
4230 second argument: >
4231 GetHistory()->histadd('search')
4232
4233histdel({history} [, {item}]) *histdel()*
4234 Clear {history}, i.e. delete all its entries. See |hist-names|
4235 for the possible values of {history}.
4236
4237 If the parameter {item} evaluates to a String, it is used as a
4238 regular expression. All entries matching that expression will
4239 be removed from the history (if there are any).
4240 Upper/lowercase must match, unless "\c" is used |/\c|.
4241 If {item} evaluates to a Number, it will be interpreted as
4242 an index, see |:history-indexing|. The respective entry will
4243 be removed if it exists.
4244
4245 The result is TRUE for a successful operation, otherwise FALSE
4246 is returned.
4247
4248 Examples:
4249 Clear expression register history: >
4250 :call histdel("expr")
4251<
4252 Remove all entries starting with "*" from the search history: >
4253 :call histdel("/", '^\*')
4254<
4255 The following three are equivalent: >
4256 :call histdel("search", histnr("search"))
4257 :call histdel("search", -1)
4258 :call histdel("search", '^'.histget("search", -1).'$')
4259<
4260 To delete the last search pattern and use the last-but-one for
4261 the "n" command and 'hlsearch': >
4262 :call histdel("search", -1)
4263 :let @/ = histget("search", -1)
4264<
4265 Can also be used as a |method|: >
4266 GetHistory()->histdel()
4267
4268histget({history} [, {index}]) *histget()*
4269 The result is a String, the entry with Number {index} from
4270 {history}. See |hist-names| for the possible values of
4271 {history}, and |:history-indexing| for {index}. If there is
4272 no such entry, an empty String is returned. When {index} is
4273 omitted, the most recent item from the history is used.
4274
4275 Examples:
4276 Redo the second last search from history. >
4277 :execute '/' . histget("search", -2)
4278
4279< Define an Ex command ":H {num}" that supports re-execution of
4280 the {num}th entry from the output of |:history|. >
4281 :command -nargs=1 H execute histget("cmd", 0+<args>)
4282<
4283 Can also be used as a |method|: >
4284 GetHistory()->histget()
4285
4286histnr({history}) *histnr()*
4287 The result is the Number of the current entry in {history}.
4288 See |hist-names| for the possible values of {history}.
4289 If an error occurred, -1 is returned.
4290
4291 Example: >
4292 :let inp_index = histnr("expr")
4293
4294< Can also be used as a |method|: >
4295 GetHistory()->histnr()
4296<
4297hlexists({name}) *hlexists()*
4298 The result is a Number, which is TRUE if a highlight group
4299 called {name} exists. This is when the group has been
4300 defined in some way. Not necessarily when highlighting has
4301 been defined for it, it may also have been used for a syntax
4302 item.
4303 *highlight_exists()*
4304 Obsolete name: highlight_exists().
4305
4306 Can also be used as a |method|: >
4307 GetName()->hlexists()
4308<
4309hlget([{name} [, {resolve}]]) *hlget()*
4310 Returns a List of all the highlight group attributes. If the
4311 optional {name} is specified, then returns a List with only
4312 the attributes of the specified highlight group. Returns an
4313 empty List if the highlight group {name} is not present.
4314
4315 If the optional {resolve} argument is set to v:true and the
4316 highlight group {name} is linked to another group, then the
4317 link is resolved recursively and the attributes of the
4318 resolved highlight group are returned.
4319
4320 Each entry in the returned List is a Dictionary with the
4321 following items:
4322 cleared boolean flag, set to v:true if the highlight
4323 group attributes are cleared or not yet
4324 specified. See |highlight-clear|.
4325 cterm cterm attributes. See |highlight-cterm|.
4326 ctermbg cterm background color.
4327 See |highlight-ctermbg|.
4328 ctermfg cterm foreground color.
4329 See |highlight-ctermfg|.
4330 ctermul cterm underline color. See |highlight-ctermul|.
4331 default boolean flag, set to v:true if the highlight
4332 group link is a default link. See
4333 |highlight-default|.
4334 font highlight group font. See |highlight-font|.
4335 gui gui attributes. See |highlight-gui|.
4336 guibg gui background color. See |highlight-guibg|.
4337 guifg gui foreground color. See |highlight-guifg|.
4338 guisp gui special color. See |highlight-guisp|.
4339 id highlight group ID.
4340 linksto linked highlight group name.
4341 See |:highlight-link|.
4342 name highlight group name. See |group-name|.
4343 start start terminal keycode. See |highlight-start|.
4344 stop stop terminal keycode. See |highlight-stop|.
4345 term term attributes. See |highlight-term|.
4346
4347 The 'term', 'cterm' and 'gui' items in the above Dictionary
4348 have a dictionary value with the following optional boolean
4349 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
4350 'reverse', 'inverse' and 'strikethrough'.
4351
4352 Example(s): >
4353 :echo hlget()
4354 :echo hlget('ModeMsg')
4355 :echo hlget('Number', v:true)
4356<
4357 Can also be used as a |method|: >
4358 GetName()->hlget()
4359<
4360hlset({list}) *hlset()*
4361 Creates or modifies the attributes of a List of highlight
4362 groups. Each item in {list} is a dictionary containing the
4363 attributes of a highlight group. See |hlget()| for the list of
4364 supported items in this dictionary.
4365
4366 In addition to the items described in |hlget()|, the following
4367 additional items are supported in the dictionary:
4368
4369 force boolean flag to force the creation of
4370 a link for an existing highlight group
4371 with attributes.
4372
4373 The highlight group is identified using the 'name' item and
4374 the 'id' item (if supplied) is ignored. If a highlight group
4375 with a specified name doesn't exist, then it is created.
4376 Otherwise the attributes of an existing highlight group are
4377 modified.
4378
4379 If an empty dictionary value is used for the 'term' or 'cterm'
4380 or 'gui' entries, then the corresponding attributes are
4381 cleared. If the 'cleared' item is set to v:true, then all the
4382 attributes of the highlight group are cleared.
4383
4384 The 'linksto' item can be used to link a highlight group to
4385 another highlight group. See |:highlight-link|.
4386
4387 Returns zero for success, -1 for failure.
4388
4389 Example(s): >
4390 " add bold attribute to the Visual highlight group
4391 :call hlset([#{name: 'Visual',
4392 \ term: #{reverse: 1 , bold: 1}}])
4393 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
4394 :let l = hlget()
4395 :call hlset(l)
4396 " clear the Search highlight group
4397 :call hlset([#{name: 'Search', cleared: v:true}])
4398 " clear the 'term' attributes for a highlight group
4399 :call hlset([#{name: 'Title', term: {}}])
4400 " create the MyHlg group linking it to DiffAdd
4401 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
4402 " remove the MyHlg group link
4403 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
4404 " clear the attributes and a link
4405 :call hlset([#{name: 'MyHlg', cleared: v:true,
4406 \ linksto: 'NONE'}])
4407<
4408 Can also be used as a |method|: >
4409 GetAttrList()->hlset()
4410<
4411 *hlID()*
4412hlID({name}) The result is a Number, which is the ID of the highlight group
4413 with name {name}. When the highlight group doesn't exist,
4414 zero is returned.
4415 This can be used to retrieve information about the highlight
4416 group. For example, to get the background color of the
4417 "Comment" group: >
4418 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4419< *highlightID()*
4420 Obsolete name: highlightID().
4421
4422 Can also be used as a |method|: >
4423 GetName()->hlID()
4424
4425hostname() *hostname()*
4426 The result is a String, which is the name of the machine on
4427 which Vim is currently running. Machine names greater than
4428 256 characters long are truncated.
4429
4430iconv({string}, {from}, {to}) *iconv()*
4431 The result is a String, which is the text {string} converted
4432 from encoding {from} to encoding {to}.
4433 When the conversion completely fails an empty string is
4434 returned. When some characters could not be converted they
4435 are replaced with "?".
4436 The encoding names are whatever the iconv() library function
4437 can accept, see ":!man 3 iconv".
4438 Most conversions require Vim to be compiled with the |+iconv|
4439 feature. Otherwise only UTF-8 to latin1 conversion and back
4440 can be done.
4441 This can be used to display messages with special characters,
4442 no matter what 'encoding' is set to. Write the message in
4443 UTF-8 and use: >
4444 echo iconv(utf8_str, "utf-8", &enc)
4445< Note that Vim uses UTF-8 for all Unicode encodings, conversion
4446 from/to UCS-2 is automatically changed to use UTF-8. You
4447 cannot use UCS-2 in a string anyway, because of the NUL bytes.
4448
4449 Can also be used as a |method|: >
4450 GetText()->iconv('latin1', 'utf-8')
4451<
4452 *indent()*
4453indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4454 current buffer. The indent is counted in spaces, the value
4455 of 'tabstop' is relevant. {lnum} is used just like in
4456 |getline()|.
4457 When {lnum} is invalid -1 is returned. In |Vim9| script an
4458 error is given.
4459
4460 Can also be used as a |method|: >
4461 GetLnum()->indent()
4462
4463index({object}, {expr} [, {start} [, {ic}]]) *index()*
4464 If {object} is a |List| return the lowest index where the item
4465 has a value equal to {expr}. There is no automatic
4466 conversion, so the String "4" is different from the Number 4.
4467 And the number 4 is different from the Float 4.0. The value
4468 of 'ignorecase' is not used here, case always matters.
4469
4470 If {object} is |Blob| return the lowest index where the byte
4471 value is equal to {expr}.
4472
4473 If {start} is given then start looking at the item with index
4474 {start} (may be negative for an item relative to the end).
4475 When {ic} is given and it is |TRUE|, ignore case. Otherwise
4476 case must match.
4477 -1 is returned when {expr} is not found in {object}.
4478 Example: >
4479 :let idx = index(words, "the")
4480 :if index(numbers, 123) >= 0
4481
4482< Can also be used as a |method|: >
4483 GetObject()->index(what)
4484
4485input({prompt} [, {text} [, {completion}]]) *input()*
4486 The result is a String, which is whatever the user typed on
4487 the command-line. The {prompt} argument is either a prompt
4488 string, or a blank string (for no prompt). A '\n' can be used
4489 in the prompt to start a new line.
4490 The highlighting set with |:echohl| is used for the prompt.
4491 The input is entered just like a command-line, with the same
4492 editing commands and mappings. There is a separate history
4493 for lines typed for input().
4494 Example: >
4495 :if input("Coffee or beer? ") == "beer"
4496 : echo "Cheers!"
4497 :endif
4498<
4499 If the optional {text} argument is present and not empty, this
4500 is used for the default reply, as if the user typed this.
4501 Example: >
4502 :let color = input("Color? ", "white")
4503
4504< The optional {completion} argument specifies the type of
4505 completion supported for the input. Without it completion is
4506 not performed. The supported completion types are the same as
4507 that can be supplied to a user-defined command using the
4508 "-complete=" argument. Refer to |:command-completion| for
4509 more information. Example: >
4510 let fname = input("File: ", "", "file")
4511<
4512 NOTE: This function must not be used in a startup file, for
4513 the versions that only run in GUI mode (e.g., the Win32 GUI).
4514 Note: When input() is called from within a mapping it will
4515 consume remaining characters from that mapping, because a
4516 mapping is handled like the characters were typed.
4517 Use |inputsave()| before input() and |inputrestore()|
4518 after input() to avoid that. Another solution is to avoid
4519 that further characters follow in the mapping, e.g., by using
4520 |:execute| or |:normal|.
4521
4522 Example with a mapping: >
4523 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
4524 :function GetFoo()
4525 : call inputsave()
4526 : let g:Foo = input("enter search pattern: ")
4527 : call inputrestore()
4528 :endfunction
4529
4530< Can also be used as a |method|: >
4531 GetPrompt()->input()
4532
4533inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
4534 Like |input()|, but when the GUI is running and text dialogs
4535 are supported, a dialog window pops up to input the text.
4536 Example: >
4537 :let n = inputdialog("value for shiftwidth", shiftwidth())
4538 :if n != ""
4539 : let &sw = n
4540 :endif
4541< When the dialog is cancelled {cancelreturn} is returned. When
4542 omitted an empty string is returned.
4543 Hitting <Enter> works like pressing the OK button. Hitting
4544 <Esc> works like pressing the Cancel button.
4545 NOTE: Command-line completion is not supported.
4546
4547 Can also be used as a |method|: >
4548 GetPrompt()->inputdialog()
4549
4550inputlist({textlist}) *inputlist()*
4551 {textlist} must be a |List| of strings. This |List| is
4552 displayed, one string per line. The user will be prompted to
4553 enter a number, which is returned.
4554 The user can also select an item by clicking on it with the
4555 mouse, if the mouse is enabled in the command line ('mouse' is
4556 "a" or includes "c"). For the first string 0 is returned.
4557 When clicking above the first item a negative number is
4558 returned. When clicking on the prompt one more than the
4559 length of {textlist} is returned.
4560 Make sure {textlist} has less than 'lines' entries, otherwise
4561 it won't work. It's a good idea to put the entry number at
4562 the start of the string. And put a prompt in the first item.
4563 Example: >
4564 let color = inputlist(['Select color:', '1. red',
4565 \ '2. green', '3. blue'])
4566
4567< Can also be used as a |method|: >
4568 GetChoices()->inputlist()
4569
4570inputrestore() *inputrestore()*
4571 Restore typeahead that was saved with a previous |inputsave()|.
4572 Should be called the same number of times inputsave() is
4573 called. Calling it more often is harmless though.
4574 Returns TRUE when there is nothing to restore, FALSE otherwise.
4575
4576inputsave() *inputsave()*
4577 Preserve typeahead (also from mappings) and clear it, so that
4578 a following prompt gets input from the user. Should be
4579 followed by a matching inputrestore() after the prompt. Can
4580 be used several times, in which case there must be just as
4581 many inputrestore() calls.
4582 Returns TRUE when out of memory, FALSE otherwise.
4583
4584inputsecret({prompt} [, {text}]) *inputsecret()*
4585 This function acts much like the |input()| function with but
4586 two exceptions:
4587 a) the user's response will be displayed as a sequence of
4588 asterisks ("*") thereby keeping the entry secret, and
4589 b) the user's response will not be recorded on the input
4590 |history| stack.
4591 The result is a String, which is whatever the user actually
4592 typed on the command-line in response to the issued prompt.
4593 NOTE: Command-line completion is not supported.
4594
4595 Can also be used as a |method|: >
4596 GetPrompt()->inputsecret()
4597
4598insert({object}, {item} [, {idx}]) *insert()*
4599 When {object} is a |List| or a |Blob| insert {item} at the start
4600 of it.
4601
4602 If {idx} is specified insert {item} before the item with index
4603 {idx}. If {idx} is zero it goes before the first item, just
4604 like omitting {idx}. A negative {idx} is also possible, see
4605 |list-index|. -1 inserts just before the last item.
4606
4607 Returns the resulting |List| or |Blob|. Examples: >
4608 :let mylist = insert([2, 3, 5], 1)
4609 :call insert(mylist, 4, -1)
4610 :call insert(mylist, 6, len(mylist))
4611< The last example can be done simpler with |add()|.
4612 Note that when {item} is a |List| it is inserted as a single
4613 item. Use |extend()| to concatenate |Lists|.
4614
4615 Can also be used as a |method|: >
4616 mylist->insert(item)
4617
4618interrupt() *interrupt()*
4619 Interrupt script execution. It works more or less like the
4620 user typing CTRL-C, most commands won't execute and control
4621 returns to the user. This is useful to abort execution
4622 from lower down, e.g. in an autocommand. Example: >
4623 :function s:check_typoname(file)
4624 : if fnamemodify(a:file, ':t') == '['
4625 : echomsg 'Maybe typo'
4626 : call interrupt()
4627 : endif
4628 :endfunction
4629 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
4630
4631invert({expr}) *invert()*
4632 Bitwise invert. The argument is converted to a number. A
4633 List, Dict or Float argument causes an error. Example: >
4634 :let bits = invert(bits)
4635< Can also be used as a |method|: >
4636 :let bits = bits->invert()
4637
4638isdirectory({directory}) *isdirectory()*
4639 The result is a Number, which is |TRUE| when a directory
4640 with the name {directory} exists. If {directory} doesn't
4641 exist, or isn't a directory, the result is |FALSE|. {directory}
4642 is any expression, which is used as a String.
4643
4644 Can also be used as a |method|: >
4645 GetName()->isdirectory()
4646
4647isinf({expr}) *isinf()*
4648 Return 1 if {expr} is a positive infinity, or -1 a negative
4649 infinity, otherwise 0. >
4650 :echo isinf(1.0 / 0.0)
4651< 1 >
4652 :echo isinf(-1.0 / 0.0)
4653< -1
4654
4655 Can also be used as a |method|: >
4656 Compute()->isinf()
4657<
4658 {only available when compiled with the |+float| feature}
4659
4660islocked({expr}) *islocked()* *E786*
4661 The result is a Number, which is |TRUE| when {expr} is the
4662 name of a locked variable.
4663 The string argument {expr} must be the name of a variable,
4664 |List| item or |Dictionary| entry, not the variable itself!
4665 Example: >
4666 :let alist = [0, ['a', 'b'], 2, 3]
4667 :lockvar 1 alist
4668 :echo islocked('alist') " 1
4669 :echo islocked('alist[1]') " 0
4670
4671< When {expr} is a variable that does not exist you get an error
4672 message. Use |exists()| to check for existence.
4673 In Vim9 script it does not work for local variables.
4674
4675 Can also be used as a |method|: >
4676 GetName()->islocked()
4677
4678isnan({expr}) *isnan()*
4679 Return |TRUE| if {expr} is a float with value NaN. >
4680 echo isnan(0.0 / 0.0)
4681< 1
4682
4683 Can also be used as a |method|: >
4684 Compute()->isnan()
4685<
4686 {only available when compiled with the |+float| feature}
4687
4688items({dict}) *items()*
4689 Return a |List| with all the key-value pairs of {dict}. Each
4690 |List| item is a list with two items: the key of a {dict}
4691 entry and the value of this entry. The |List| is in arbitrary
4692 order. Also see |keys()| and |values()|.
4693 Example: >
4694 for [key, value] in items(mydict)
4695 echo key . ': ' . value
4696 endfor
4697
4698< Can also be used as a |method|: >
4699 mydict->items()
4700
4701job_ functions are documented here: |job-functions-details|
4702
4703
4704join({list} [, {sep}]) *join()*
4705 Join the items in {list} together into one String.
4706 When {sep} is specified it is put in between the items. If
4707 {sep} is omitted a single space is used.
4708 Note that {sep} is not added at the end. You might want to
4709 add it there too: >
4710 let lines = join(mylist, "\n") . "\n"
4711< String items are used as-is. |Lists| and |Dictionaries| are
4712 converted into a string like with |string()|.
4713 The opposite function is |split()|.
4714
4715 Can also be used as a |method|: >
4716 mylist->join()
4717
4718js_decode({string}) *js_decode()*
4719 This is similar to |json_decode()| with these differences:
4720 - Object key names do not have to be in quotes.
4721 - Strings can be in single quotes.
4722 - Empty items in an array (between two commas) are allowed and
4723 result in v:none items.
4724
4725 Can also be used as a |method|: >
4726 ReadObject()->js_decode()
4727
4728js_encode({expr}) *js_encode()*
4729 This is similar to |json_encode()| with these differences:
4730 - Object key names are not in quotes.
4731 - v:none items in an array result in an empty item between
4732 commas.
4733 For example, the Vim object:
4734 [1,v:none,{"one":1},v:none] ~
4735 Will be encoded as:
4736 [1,,{one:1},,] ~
4737 While json_encode() would produce:
4738 [1,null,{"one":1},null] ~
4739 This encoding is valid for JavaScript. It is more efficient
4740 than JSON, especially when using an array with optional items.
4741
4742 Can also be used as a |method|: >
4743 GetObject()->js_encode()
4744
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00004745json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004746 This parses a JSON formatted string and returns the equivalent
4747 in Vim values. See |json_encode()| for the relation between
4748 JSON and Vim values.
4749 The decoding is permissive:
4750 - A trailing comma in an array and object is ignored, e.g.
4751 "[1, 2, ]" is the same as "[1, 2]".
4752 - Integer keys are accepted in objects, e.g. {1:2} is the
4753 same as {"1":2}.
4754 - More floating point numbers are recognized, e.g. "1." for
4755 "1.0", or "001.2" for "1.2". Special floating point values
4756 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
4757 are accepted.
4758 - Leading zeroes in integer numbers are ignored, e.g. "012"
4759 for "12" or "-012" for "-12".
4760 - Capitalization is ignored in literal names null, true or
4761 false, e.g. "NULL" for "null", "True" for "true".
4762 - Control characters U+0000 through U+001F which are not
4763 escaped in strings are accepted, e.g. " " (tab
4764 character in string) for "\t".
4765 - An empty JSON expression or made of only spaces is accepted
4766 and results in v:none.
4767 - Backslash in an invalid 2-character sequence escape is
4768 ignored, e.g. "\a" is decoded as "a".
4769 - A correct surrogate pair in JSON strings should normally be
4770 a 12 character sequence such as "\uD834\uDD1E", but
4771 json_decode() silently accepts truncated surrogate pairs
4772 such as "\uD834" or "\uD834\u"
4773 *E938*
4774 A duplicate key in an object, valid in rfc7159, is not
4775 accepted by json_decode() as the result must be a valid Vim
4776 type, e.g. this fails: {"a":"b", "a":"c"}
4777
4778 Can also be used as a |method|: >
4779 ReadObject()->json_decode()
4780
4781json_encode({expr}) *json_encode()*
4782 Encode {expr} as JSON and return this as a string.
4783 The encoding is specified in:
4784 https://tools.ietf.org/html/rfc7159.html
4785 Vim values are converted as follows:
4786 |Number| decimal number
4787 |Float| floating point number
4788 Float nan "NaN"
4789 Float inf "Infinity"
4790 Float -inf "-Infinity"
4791 |String| in double quotes (possibly null)
4792 |Funcref| not possible, error
4793 |List| as an array (possibly null); when
4794 used recursively: []
4795 |Dict| as an object (possibly null); when
4796 used recursively: {}
4797 |Blob| as an array of the individual bytes
4798 v:false "false"
4799 v:true "true"
4800 v:none "null"
4801 v:null "null"
4802 Note that NaN and Infinity are passed on as values. This is
4803 missing in the JSON standard, but several implementations do
4804 allow it. If not then you will get an error.
4805
4806 Can also be used as a |method|: >
4807 GetObject()->json_encode()
4808
4809keys({dict}) *keys()*
4810 Return a |List| with all the keys of {dict}. The |List| is in
4811 arbitrary order. Also see |items()| and |values()|.
4812
4813 Can also be used as a |method|: >
4814 mydict->keys()
4815
4816< *len()* *E701*
4817len({expr}) The result is a Number, which is the length of the argument.
4818 When {expr} is a String or a Number the length in bytes is
4819 used, as with |strlen()|.
4820 When {expr} is a |List| the number of items in the |List| is
4821 returned.
4822 When {expr} is a |Blob| the number of bytes is returned.
4823 When {expr} is a |Dictionary| the number of entries in the
4824 |Dictionary| is returned.
4825 Otherwise an error is given.
4826
4827 Can also be used as a |method|: >
4828 mylist->len()
4829
4830< *libcall()* *E364* *E368*
4831libcall({libname}, {funcname}, {argument})
4832 Call function {funcname} in the run-time library {libname}
4833 with single argument {argument}.
4834 This is useful to call functions in a library that you
4835 especially made to be used with Vim. Since only one argument
4836 is possible, calling standard library functions is rather
4837 limited.
4838 The result is the String returned by the function. If the
4839 function returns NULL, this will appear as an empty string ""
4840 to Vim.
4841 If the function returns a number, use libcallnr()!
4842 If {argument} is a number, it is passed to the function as an
4843 int; if {argument} is a string, it is passed as a
4844 null-terminated string.
4845 This function will fail in |restricted-mode|.
4846
4847 libcall() allows you to write your own 'plug-in' extensions to
4848 Vim without having to recompile the program. It is NOT a
4849 means to call system functions! If you try to do so Vim will
4850 very probably crash.
4851
4852 For Win32, the functions you write must be placed in a DLL
4853 and use the normal C calling convention (NOT Pascal which is
4854 used in Windows System DLLs). The function must take exactly
4855 one parameter, either a character pointer or a long integer,
4856 and must return a character pointer or NULL. The character
4857 pointer returned must point to memory that will remain valid
4858 after the function has returned (e.g. in static data in the
4859 DLL). If it points to allocated memory, that memory will
4860 leak away. Using a static buffer in the function should work,
4861 it's then freed when the DLL is unloaded.
4862
4863 WARNING: If the function returns a non-valid pointer, Vim may
4864 crash! This also happens if the function returns a number,
4865 because Vim thinks it's a pointer.
4866 For Win32 systems, {libname} should be the filename of the DLL
4867 without the ".DLL" suffix. A full path is only required if
4868 the DLL is not in the usual places.
4869 For Unix: When compiling your own plugins, remember that the
4870 object code must be compiled as position-independent ('PIC').
4871 {only in Win32 and some Unix versions, when the |+libcall|
4872 feature is present}
4873 Examples: >
4874 :echo libcall("libc.so", "getenv", "HOME")
4875
4876< Can also be used as a |method|, the base is passed as the
4877 third argument: >
4878 GetValue()->libcall("libc.so", "getenv")
4879<
4880 *libcallnr()*
4881libcallnr({libname}, {funcname}, {argument})
4882 Just like |libcall()|, but used for a function that returns an
4883 int instead of a string.
4884 {only in Win32 on some Unix versions, when the |+libcall|
4885 feature is present}
4886 Examples: >
4887 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
4888 :call libcallnr("libc.so", "printf", "Hello World!\n")
4889 :call libcallnr("libc.so", "sleep", 10)
4890<
4891 Can also be used as a |method|, the base is passed as the
4892 third argument: >
4893 GetValue()->libcallnr("libc.so", "printf")
4894<
4895
4896line({expr} [, {winid}]) *line()*
4897 The result is a Number, which is the line number of the file
4898 position given with {expr}. The {expr} argument is a string.
4899 The accepted positions are:
4900 . the cursor position
4901 $ the last line in the current buffer
4902 'x position of mark x (if the mark is not set, 0 is
4903 returned)
4904 w0 first line visible in current window (one if the
4905 display isn't updated, e.g. in silent Ex mode)
4906 w$ last line visible in current window (this is one
4907 less than "w0" if no lines are visible)
4908 v In Visual mode: the start of the Visual area (the
4909 cursor is the end). When not in Visual mode
4910 returns the cursor position. Differs from |'<| in
4911 that it's updated right away.
4912 Note that a mark in another file can be used. The line number
4913 then applies to another buffer.
4914 To get the column number use |col()|. To get both use
4915 |getpos()|.
4916 With the optional {winid} argument the values are obtained for
4917 that window instead of the current window.
4918 Examples: >
4919 line(".") line number of the cursor
4920 line(".", winid) idem, in window "winid"
4921 line("'t") line number of mark t
4922 line("'" . marker) line number of mark marker
4923<
4924 To jump to the last known position when opening a file see
4925 |last-position-jump|.
4926
4927 Can also be used as a |method|: >
4928 GetValue()->line()
4929
4930line2byte({lnum}) *line2byte()*
4931 Return the byte count from the start of the buffer for line
4932 {lnum}. This includes the end-of-line character, depending on
4933 the 'fileformat' option for the current buffer. The first
4934 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
4935 This can also be used to get the byte count for the line just
4936 below the last line: >
4937 line2byte(line("$") + 1)
4938< This is the buffer size plus one. If 'fileencoding' is empty
4939 it is the file size plus one. {lnum} is used like with
4940 |getline()|. When {lnum} is invalid, or the |+byte_offset|
4941 feature has been disabled at compile time, -1 is returned.
4942 Also see |byte2line()|, |go| and |:goto|.
4943
4944 Can also be used as a |method|: >
4945 GetLnum()->line2byte()
4946
4947lispindent({lnum}) *lispindent()*
4948 Get the amount of indent for line {lnum} according the lisp
4949 indenting rules, as with 'lisp'.
4950 The indent is counted in spaces, the value of 'tabstop' is
4951 relevant. {lnum} is used just like in |getline()|.
4952 When {lnum} is invalid or Vim was not compiled the
4953 |+lispindent| feature, -1 is returned. In |Vim9| script an
4954 error is given.
4955
4956 Can also be used as a |method|: >
4957 GetLnum()->lispindent()
4958
4959list2blob({list}) *list2blob()*
4960 Return a Blob concatenating all the number values in {list}.
4961 Examples: >
4962 list2blob([1, 2, 3, 4]) returns 0z01020304
4963 list2blob([]) returns 0z
4964< Returns an empty Blob on error. If one of the numbers is
4965 negative or more than 255 error *E1239* is given.
4966
4967 |blob2list()| does the opposite.
4968
4969 Can also be used as a |method|: >
4970 GetList()->list2blob()
4971
4972list2str({list} [, {utf8}]) *list2str()*
4973 Convert each number in {list} to a character string can
4974 concatenate them all. Examples: >
4975 list2str([32]) returns " "
4976 list2str([65, 66, 67]) returns "ABC"
4977< The same can be done (slowly) with: >
4978 join(map(list, {nr, val -> nr2char(val)}), '')
4979< |str2list()| does the opposite.
4980
4981 When {utf8} is omitted or zero, the current 'encoding' is used.
4982 When {utf8} is TRUE, always return UTF-8 characters.
4983 With UTF-8 composing characters work as expected: >
4984 list2str([97, 769]) returns "á"
4985<
4986 Can also be used as a |method|: >
4987 GetList()->list2str()
4988
4989listener_add({callback} [, {buf}]) *listener_add()*
4990 Add a callback function that will be invoked when changes have
4991 been made to buffer {buf}.
4992 {buf} refers to a buffer name or number. For the accepted
4993 values, see |bufname()|. When {buf} is omitted the current
4994 buffer is used.
4995 Returns a unique ID that can be passed to |listener_remove()|.
4996
4997 The {callback} is invoked with five arguments:
4998 a:bufnr the buffer that was changed
4999 a:start first changed line number
5000 a:end first line number below the change
5001 a:added number of lines added, negative if lines were
5002 deleted
5003 a:changes a List of items with details about the changes
5004
5005 Example: >
5006 func Listener(bufnr, start, end, added, changes)
5007 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
5008 endfunc
5009 call listener_add('Listener', bufnr)
5010
5011< The List cannot be changed. Each item in a:changes is a
5012 dictionary with these entries:
5013 lnum the first line number of the change
5014 end the first line below the change
5015 added number of lines added; negative if lines were
5016 deleted
5017 col first column in "lnum" that was affected by
5018 the change; one if unknown or the whole line
5019 was affected; this is a byte index, first
5020 character has a value of one.
5021 When lines are inserted the values are:
5022 lnum line above which the new line is added
5023 end equal to "lnum"
5024 added number of lines inserted
5025 col 1
5026 When lines are deleted the values are:
5027 lnum the first deleted line
5028 end the line below the first deleted line, before
5029 the deletion was done
5030 added negative, number of lines deleted
5031 col 1
5032 When lines are changed:
5033 lnum the first changed line
5034 end the line below the last changed line
5035 added 0
5036 col first column with a change or 1
5037
5038 The entries are in the order the changes were made, thus the
5039 most recent change is at the end. The line numbers are valid
5040 when the callback is invoked, but later changes may make them
5041 invalid, thus keeping a copy for later might not work.
5042
5043 The {callback} is invoked just before the screen is updated,
5044 when |listener_flush()| is called or when a change is being
5045 made that changes the line count in a way it causes a line
5046 number in the list of changes to become invalid.
5047
5048 The {callback} is invoked with the text locked, see
5049 |textlock|. If you do need to make changes to the buffer, use
5050 a timer to do this later |timer_start()|.
5051
5052 The {callback} is not invoked when the buffer is first loaded.
5053 Use the |BufReadPost| autocmd event to handle the initial text
5054 of a buffer.
5055 The {callback} is also not invoked when the buffer is
5056 unloaded, use the |BufUnload| autocmd event for that.
5057
5058 Can also be used as a |method|, the base is passed as the
5059 second argument: >
5060 GetBuffer()->listener_add(callback)
5061
5062listener_flush([{buf}]) *listener_flush()*
5063 Invoke listener callbacks for buffer {buf}. If there are no
5064 pending changes then no callbacks are invoked.
5065
5066 {buf} refers to a buffer name or number. For the accepted
5067 values, see |bufname()|. When {buf} is omitted the current
5068 buffer is used.
5069
5070 Can also be used as a |method|: >
5071 GetBuffer()->listener_flush()
5072
5073listener_remove({id}) *listener_remove()*
5074 Remove a listener previously added with listener_add().
5075 Returns FALSE when {id} could not be found, TRUE when {id} was
5076 removed.
5077
5078 Can also be used as a |method|: >
5079 GetListenerId()->listener_remove()
5080
5081localtime() *localtime()*
5082 Return the current time, measured as seconds since 1st Jan
5083 1970. See also |strftime()|, |strptime()| and |getftime()|.
5084
5085
5086log({expr}) *log()*
5087 Return the natural logarithm (base e) of {expr} as a |Float|.
5088 {expr} must evaluate to a |Float| or a |Number| in the range
5089 (0, inf].
5090 Examples: >
5091 :echo log(10)
5092< 2.302585 >
5093 :echo log(exp(5))
5094< 5.0
5095
5096 Can also be used as a |method|: >
5097 Compute()->log()
5098<
5099 {only available when compiled with the |+float| feature}
5100
5101
5102log10({expr}) *log10()*
5103 Return the logarithm of Float {expr} to base 10 as a |Float|.
5104 {expr} must evaluate to a |Float| or a |Number|.
5105 Examples: >
5106 :echo log10(1000)
5107< 3.0 >
5108 :echo log10(0.01)
5109< -2.0
5110
5111 Can also be used as a |method|: >
5112 Compute()->log10()
5113<
5114 {only available when compiled with the |+float| feature}
5115
5116luaeval({expr} [, {expr}]) *luaeval()*
5117 Evaluate Lua expression {expr} and return its result converted
5118 to Vim data structures. Second {expr} may hold additional
5119 argument accessible as _A inside first {expr}.
5120 Strings are returned as they are.
5121 Boolean objects are converted to numbers.
5122 Numbers are converted to |Float| values if vim was compiled
5123 with |+float| and to numbers otherwise.
5124 Dictionaries and lists obtained by vim.eval() are returned
5125 as-is.
5126 Other objects are returned as zero without any errors.
5127 See |lua-luaeval| for more details.
5128 Note that in a `:def` function local variables are not visible
5129 to {expr}.
5130
5131 Can also be used as a |method|: >
5132 GetExpr()->luaeval()
5133
5134< {only available when compiled with the |+lua| feature}
5135
5136map({expr1}, {expr2}) *map()*
5137 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
5138 When {expr1} is a |List|| or |Dictionary|, replace each
5139 item in {expr1} with the result of evaluating {expr2}.
5140 For a |Blob| each byte is replaced.
5141 For a |String|, each character, including composing
5142 characters, is replaced.
5143 If the item type changes you may want to use |mapnew()| to
5144 create a new List or Dictionary. This is required when using
5145 Vim9 script.
5146
5147 {expr2} must be a |String| or |Funcref|.
5148
5149 If {expr2} is a |String|, inside {expr2} |v:val| has the value
5150 of the current item. For a |Dictionary| |v:key| has the key
5151 of the current item and for a |List| |v:key| has the index of
5152 the current item. For a |Blob| |v:key| has the index of the
5153 current byte. For a |String| |v:key| has the index of the
5154 current character.
5155 Example: >
5156 :call map(mylist, '"> " . v:val . " <"')
5157< This puts "> " before and " <" after each item in "mylist".
5158
5159 Note that {expr2} is the result of an expression and is then
5160 used as an expression again. Often it is good to use a
5161 |literal-string| to avoid having to double backslashes. You
5162 still have to double ' quotes
5163
5164 If {expr2} is a |Funcref| it is called with two arguments:
5165 1. The key or the index of the current item.
5166 2. the value of the current item.
5167 The function must return the new value of the item. Example
5168 that changes each value by "key-value": >
5169 func KeyValue(key, val)
5170 return a:key . '-' . a:val
5171 endfunc
5172 call map(myDict, function('KeyValue'))
5173< It is shorter when using a |lambda|: >
5174 call map(myDict, {key, val -> key . '-' . val})
5175< If you do not use "val" you can leave it out: >
5176 call map(myDict, {key -> 'item: ' . key})
5177< If you do not use "key" you can use a short name: >
5178 call map(myDict, {_, val -> 'item: ' . val})
5179<
5180 The operation is done in-place for a |List| and |Dictionary|.
5181 If you want it to remain unmodified make a copy first: >
5182 :let tlist = map(copy(mylist), ' v:val . "\t"')
5183
5184< Returns {expr1}, the |List| or |Dictionary| that was filtered,
5185 or a new |Blob| or |String|.
5186 When an error is encountered while evaluating {expr2} no
5187 further items in {expr1} are processed.
5188 When {expr2} is a Funcref errors inside a function are ignored,
5189 unless it was defined with the "abort" flag.
5190
5191 Can also be used as a |method|: >
5192 mylist->map(expr2)
5193
5194
5195maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
5196 When {dict} is omitted or zero: Return the rhs of mapping
5197 {name} in mode {mode}. The returned String has special
5198 characters translated like in the output of the ":map" command
5199 listing.
5200
5201 When there is no mapping for {name}, an empty String is
5202 returned. When the mapping for {name} is empty, then "<Nop>"
5203 is returned.
5204
5205 The {name} can have special key names, like in the ":map"
5206 command.
5207
5208 {mode} can be one of these strings:
5209 "n" Normal
5210 "v" Visual (including Select)
5211 "o" Operator-pending
5212 "i" Insert
5213 "c" Cmd-line
5214 "s" Select
5215 "x" Visual
5216 "l" langmap |language-mapping|
5217 "t" Terminal-Job
5218 "" Normal, Visual and Operator-pending
5219 When {mode} is omitted, the modes for "" are used.
5220
5221 When {abbr} is there and it is |TRUE| use abbreviations
5222 instead of mappings.
5223
5224 When {dict} is there and it is |TRUE| return a dictionary
5225 containing all the information of the mapping with the
5226 following items:
5227 "lhs" The {lhs} of the mapping as it would be typed
5228 "lhsraw" The {lhs} of the mapping as raw bytes
5229 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
5230 form, only present when it differs from "lhsraw"
5231 "rhs" The {rhs} of the mapping as typed.
5232 "silent" 1 for a |:map-silent| mapping, else 0.
5233 "noremap" 1 if the {rhs} of the mapping is not remappable.
5234 "script" 1 if mapping was defined with <script>.
5235 "expr" 1 for an expression mapping (|:map-<expr>|).
5236 "buffer" 1 for a buffer local mapping (|:map-local|).
5237 "mode" Modes for which the mapping is defined. In
5238 addition to the modes mentioned above, these
5239 characters will be used:
5240 " " Normal, Visual and Operator-pending
5241 "!" Insert and Commandline mode
5242 (|mapmode-ic|)
5243 "sid" The script local ID, used for <sid> mappings
5244 (|<SID>|).
5245 "lnum" The line number in "sid", zero if unknown.
5246 "nowait" Do not wait for other, longer mappings.
5247 (|:map-<nowait>|).
5248
5249 The dictionary can be used to restore a mapping with
5250 |mapset()|.
5251
5252 The mappings local to the current buffer are checked first,
5253 then the global mappings.
5254 This function can be used to map a key even when it's already
5255 mapped, and have it do the original mapping too. Sketch: >
5256 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
5257
5258< Can also be used as a |method|: >
5259 GetKey()->maparg('n')
5260
5261mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
5262 Check if there is a mapping that matches with {name} in mode
5263 {mode}. See |maparg()| for {mode} and special names in
5264 {name}.
5265 When {abbr} is there and it is |TRUE| use abbreviations
5266 instead of mappings.
5267 A match happens with a mapping that starts with {name} and
5268 with a mapping which is equal to the start of {name}.
5269
5270 matches mapping "a" "ab" "abc" ~
5271 mapcheck("a") yes yes yes
5272 mapcheck("abc") yes yes yes
5273 mapcheck("ax") yes no no
5274 mapcheck("b") no no no
5275
5276 The difference with maparg() is that mapcheck() finds a
5277 mapping that matches with {name}, while maparg() only finds a
5278 mapping for {name} exactly.
5279 When there is no mapping that starts with {name}, an empty
5280 String is returned. If there is one, the RHS of that mapping
5281 is returned. If there are several mappings that start with
5282 {name}, the RHS of one of them is returned. This will be
5283 "<Nop>" if the RHS is empty.
5284 The mappings local to the current buffer are checked first,
5285 then the global mappings.
5286 This function can be used to check if a mapping can be added
5287 without being ambiguous. Example: >
5288 :if mapcheck("_vv") == ""
5289 : map _vv :set guifont=7x13<CR>
5290 :endif
5291< This avoids adding the "_vv" mapping when there already is a
5292 mapping for "_v" or for "_vvv".
5293
5294 Can also be used as a |method|: >
5295 GetKey()->mapcheck('n')
5296
5297
5298mapnew({expr1}, {expr2}) *mapnew()*
5299 Like |map()| but instead of replacing items in {expr1} a new
5300 List or Dictionary is created and returned. {expr1} remains
5301 unchanged. Items can still be changed by {expr2}, if you
5302 don't want that use |deepcopy()| first.
5303
5304
5305mapset({mode}, {abbr}, {dict}) *mapset()*
5306 Restore a mapping from a dictionary returned by |maparg()|.
5307 {mode} and {abbr} should be the same as for the call to
5308 |maparg()|. *E460*
5309 {mode} is used to define the mode in which the mapping is set,
5310 not the "mode" entry in {dict}.
5311 Example for saving and restoring a mapping: >
5312 let save_map = maparg('K', 'n', 0, 1)
5313 nnoremap K somethingelse
5314 ...
5315 call mapset('n', 0, save_map)
5316< Note that if you are going to replace a map in several modes,
5317 e.g. with `:map!`, you need to save the mapping for all of
5318 them, since they can differ.
5319
5320
5321match({expr}, {pat} [, {start} [, {count}]]) *match()*
5322 When {expr} is a |List| then this returns the index of the
5323 first item where {pat} matches. Each item is used as a
5324 String, |Lists| and |Dictionaries| are used as echoed.
5325
5326 Otherwise, {expr} is used as a String. The result is a
5327 Number, which gives the index (byte offset) in {expr} where
5328 {pat} matches.
5329
5330 A match at the first character or |List| item returns zero.
5331 If there is no match -1 is returned.
5332
5333 For getting submatches see |matchlist()|.
5334 Example: >
5335 :echo match("testing", "ing") " results in 4
5336 :echo match([1, 'x'], '\a') " results in 1
5337< See |string-match| for how {pat} is used.
5338 *strpbrk()*
5339 Vim doesn't have a strpbrk() function. But you can do: >
5340 :let sepidx = match(line, '[.,;: \t]')
5341< *strcasestr()*
5342 Vim doesn't have a strcasestr() function. But you can add
5343 "\c" to the pattern to ignore case: >
5344 :let idx = match(haystack, '\cneedle')
5345<
5346 If {start} is given, the search starts from byte index
5347 {start} in a String or item {start} in a |List|.
5348 The result, however, is still the index counted from the
5349 first character/item. Example: >
5350 :echo match("testing", "ing", 2)
5351< result is again "4". >
5352 :echo match("testing", "ing", 4)
5353< result is again "4". >
5354 :echo match("testing", "t", 2)
5355< result is "3".
5356 For a String, if {start} > 0 then it is like the string starts
5357 {start} bytes later, thus "^" will match at {start}. Except
5358 when {count} is given, then it's like matches before the
5359 {start} byte are ignored (this is a bit complicated to keep it
5360 backwards compatible).
5361 For a String, if {start} < 0, it will be set to 0. For a list
5362 the index is counted from the end.
5363 If {start} is out of range ({start} > strlen({expr}) for a
5364 String or {start} > len({expr}) for a |List|) -1 is returned.
5365
5366 When {count} is given use the {count}'th match. When a match
5367 is found in a String the search for the next one starts one
5368 character further. Thus this example results in 1: >
5369 echo match("testing", "..", 0, 2)
5370< In a |List| the search continues in the next item.
5371 Note that when {count} is added the way {start} works changes,
5372 see above.
5373
5374 See |pattern| for the patterns that are accepted.
5375 The 'ignorecase' option is used to set the ignore-caseness of
5376 the pattern. 'smartcase' is NOT used. The matching is always
5377 done like 'magic' is set and 'cpoptions' is empty.
5378 Note that a match at the start is preferred, thus when the
5379 pattern is using "*" (any number of matches) it tends to find
5380 zero matches at the start instead of a number of matches
5381 further down in the text.
5382
5383 Can also be used as a |method|: >
5384 GetText()->match('word')
5385 GetList()->match('word')
5386<
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005387 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005388matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
5389 Defines a pattern to be highlighted in the current window (a
5390 "match"). It will be highlighted with {group}. Returns an
5391 identification number (ID), which can be used to delete the
5392 match using |matchdelete()|. The ID is bound to the window.
5393 Matching is case sensitive and magic, unless case sensitivity
5394 or magicness are explicitly overridden in {pattern}. The
5395 'magic', 'smartcase' and 'ignorecase' options are not used.
5396 The "Conceal" value is special, it causes the match to be
5397 concealed.
5398
5399 The optional {priority} argument assigns a priority to the
5400 match. A match with a high priority will have its
5401 highlighting overrule that of a match with a lower priority.
5402 A priority is specified as an integer (negative numbers are no
5403 exception). If the {priority} argument is not specified, the
5404 default priority is 10. The priority of 'hlsearch' is zero,
5405 hence all matches with a priority greater than zero will
5406 overrule it. Syntax highlighting (see 'syntax') is a separate
5407 mechanism, and regardless of the chosen priority a match will
5408 always overrule syntax highlighting.
5409
5410 The optional {id} argument allows the request for a specific
5411 match ID. If a specified ID is already taken, an error
5412 message will appear and the match will not be added. An ID
5413 is specified as a positive integer (zero excluded). IDs 1, 2
5414 and 3 are reserved for |:match|, |:2match| and |:3match|,
5415 respectively. If the {id} argument is not specified or -1,
5416 |matchadd()| automatically chooses a free ID.
5417
5418 The optional {dict} argument allows for further custom
5419 values. Currently this is used to specify a match specific
5420 conceal character that will be shown for |hl-Conceal|
5421 highlighted matches. The dict can have the following members:
5422
5423 conceal Special character to show instead of the
5424 match (only for |hl-Conceal| highlighted
5425 matches, see |:syn-cchar|)
5426 window Instead of the current window use the
5427 window with this number or window ID.
5428
5429 The number of matches is not limited, as it is the case with
5430 the |:match| commands.
5431
5432 Example: >
5433 :highlight MyGroup ctermbg=green guibg=green
5434 :let m = matchadd("MyGroup", "TODO")
5435< Deletion of the pattern: >
5436 :call matchdelete(m)
5437
5438< A list of matches defined by |matchadd()| and |:match| are
5439 available from |getmatches()|. All matches can be deleted in
5440 one operation by |clearmatches()|.
5441
5442 Can also be used as a |method|: >
5443 GetGroup()->matchadd('TODO')
5444<
5445 *matchaddpos()*
5446matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
5447 Same as |matchadd()|, but requires a list of positions {pos}
5448 instead of a pattern. This command is faster than |matchadd()|
5449 because it does not require to handle regular expressions and
5450 sets buffer line boundaries to redraw screen. It is supposed
5451 to be used when fast match additions and deletions are
5452 required, for example to highlight matching parentheses.
5453
5454 {pos} is a list of positions. Each position can be one of
5455 these:
5456 - A number. This whole line will be highlighted. The first
5457 line has number 1.
5458 - A list with one number, e.g., [23]. The whole line with this
5459 number will be highlighted.
5460 - A list with two numbers, e.g., [23, 11]. The first number is
5461 the line number, the second one is the column number (first
5462 column is 1, the value must correspond to the byte index as
5463 |col()| would return). The character at this position will
5464 be highlighted.
5465 - A list with three numbers, e.g., [23, 11, 3]. As above, but
5466 the third number gives the length of the highlight in bytes.
5467
5468 The maximum number of positions in {pos} is 8.
5469
5470 Example: >
5471 :highlight MyGroup ctermbg=green guibg=green
5472 :let m = matchaddpos("MyGroup", [[23, 24], 34])
5473< Deletion of the pattern: >
5474 :call matchdelete(m)
5475
5476< Matches added by |matchaddpos()| are returned by
5477 |getmatches()|.
5478
5479 Can also be used as a |method|: >
5480 GetGroup()->matchaddpos([23, 11])
5481
5482matcharg({nr}) *matcharg()*
5483 Selects the {nr} match item, as set with a |:match|,
5484 |:2match| or |:3match| command.
5485 Return a |List| with two elements:
5486 The name of the highlight group used
5487 The pattern used.
5488 When {nr} is not 1, 2 or 3 returns an empty |List|.
5489 When there is no match item set returns ['', ''].
5490 This is useful to save and restore a |:match|.
5491 Highlighting matches using the |:match| commands are limited
5492 to three matches. |matchadd()| does not have this limitation.
5493
5494 Can also be used as a |method|: >
5495 GetMatch()->matcharg()
5496
5497matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
5498 Deletes a match with ID {id} previously defined by |matchadd()|
5499 or one of the |:match| commands. Returns 0 if successful,
5500 otherwise -1. See example for |matchadd()|. All matches can
5501 be deleted in one operation by |clearmatches()|.
5502 If {win} is specified, use the window with this number or
5503 window ID instead of the current window.
5504
5505 Can also be used as a |method|: >
5506 GetMatch()->matchdelete()
5507
5508matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
5509 Same as |match()|, but return the index of first character
5510 after the match. Example: >
5511 :echo matchend("testing", "ing")
5512< results in "7".
5513 *strspn()* *strcspn()*
5514 Vim doesn't have a strspn() or strcspn() function, but you can
5515 do it with matchend(): >
5516 :let span = matchend(line, '[a-zA-Z]')
5517 :let span = matchend(line, '[^a-zA-Z]')
5518< Except that -1 is returned when there are no matches.
5519
5520 The {start}, if given, has the same meaning as for |match()|. >
5521 :echo matchend("testing", "ing", 2)
5522< results in "7". >
5523 :echo matchend("testing", "ing", 5)
5524< result is "-1".
5525 When {expr} is a |List| the result is equal to |match()|.
5526
5527 Can also be used as a |method|: >
5528 GetText()->matchend('word')
5529
5530
5531matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
5532 If {list} is a list of strings, then returns a |List| with all
5533 the strings in {list} that fuzzy match {str}. The strings in
5534 the returned list are sorted based on the matching score.
5535
5536 The optional {dict} argument always supports the following
5537 items:
5538 matchseq When this item is present and {str} contains
5539 multiple words separated by white space, then
5540 returns only matches that contain the words in
5541 the given sequence.
5542
5543 If {list} is a list of dictionaries, then the optional {dict}
5544 argument supports the following additional items:
5545 key key of the item which is fuzzy matched against
5546 {str}. The value of this item should be a
5547 string.
5548 text_cb |Funcref| that will be called for every item
5549 in {list} to get the text for fuzzy matching.
5550 This should accept a dictionary item as the
5551 argument and return the text for that item to
5552 use for fuzzy matching.
5553
5554 {str} is treated as a literal string and regular expression
5555 matching is NOT supported. The maximum supported {str} length
5556 is 256.
5557
5558 When {str} has multiple words each separated by white space,
5559 then the list of strings that have all the words is returned.
5560
5561 If there are no matching strings or there is an error, then an
5562 empty list is returned. If length of {str} is greater than
5563 256, then returns an empty list.
5564
5565 Refer to |fuzzy-match| for more information about fuzzy
5566 matching strings.
5567
5568 Example: >
5569 :echo matchfuzzy(["clay", "crow"], "cay")
5570< results in ["clay"]. >
5571 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
5572< results in a list of buffer names fuzzy matching "ndl". >
5573 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
5574< results in a list of buffer information dicts with buffer
5575 names fuzzy matching "ndl". >
5576 :echo getbufinfo()->matchfuzzy("spl",
5577 \ {'text_cb' : {v -> v.name}})
5578< results in a list of buffer information dicts with buffer
5579 names fuzzy matching "spl". >
5580 :echo v:oldfiles->matchfuzzy("test")
5581< results in a list of file names fuzzy matching "test". >
5582 :let l = readfile("buffer.c")->matchfuzzy("str")
5583< results in a list of lines in "buffer.c" fuzzy matching "str". >
5584 :echo ['one two', 'two one']->matchfuzzy('two one')
5585< results in ['two one', 'one two']. >
5586 :echo ['one two', 'two one']->matchfuzzy('two one',
5587 \ {'matchseq': 1})
5588< results in ['two one'].
5589
5590matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
5591 Same as |matchfuzzy()|, but returns the list of matched
5592 strings, the list of character positions where characters
5593 in {str} matches and a list of matching scores. You can
5594 use |byteidx()| to convert a character position to a byte
5595 position.
5596
5597 If {str} matches multiple times in a string, then only the
5598 positions for the best match is returned.
5599
5600 If there are no matching strings or there is an error, then a
5601 list with three empty list items is returned.
5602
5603 Example: >
5604 :echo matchfuzzypos(['testing'], 'tsg')
5605< results in [['testing'], [[0, 2, 6]], [99]] >
5606 :echo matchfuzzypos(['clay', 'lacy'], 'la')
5607< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
5608 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
5609< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
5610
5611matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
5612 Same as |match()|, but return a |List|. The first item in the
5613 list is the matched string, same as what matchstr() would
5614 return. Following items are submatches, like "\1", "\2", etc.
5615 in |:substitute|. When an optional submatch didn't match an
5616 empty string is used. Example: >
5617 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
5618< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
5619 When there is no match an empty list is returned.
5620
5621 You can pass in a List, but that is not very useful.
5622
5623 Can also be used as a |method|: >
5624 GetText()->matchlist('word')
5625
5626matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
5627 Same as |match()|, but return the matched string. Example: >
5628 :echo matchstr("testing", "ing")
5629< results in "ing".
5630 When there is no match "" is returned.
5631 The {start}, if given, has the same meaning as for |match()|. >
5632 :echo matchstr("testing", "ing", 2)
5633< results in "ing". >
5634 :echo matchstr("testing", "ing", 5)
5635< result is "".
5636 When {expr} is a |List| then the matching item is returned.
5637 The type isn't changed, it's not necessarily a String.
5638
5639 Can also be used as a |method|: >
5640 GetText()->matchstr('word')
5641
5642matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
5643 Same as |matchstr()|, but return the matched string, the start
5644 position and the end position of the match. Example: >
5645 :echo matchstrpos("testing", "ing")
5646< results in ["ing", 4, 7].
5647 When there is no match ["", -1, -1] is returned.
5648 The {start}, if given, has the same meaning as for |match()|. >
5649 :echo matchstrpos("testing", "ing", 2)
5650< results in ["ing", 4, 7]. >
5651 :echo matchstrpos("testing", "ing", 5)
5652< result is ["", -1, -1].
5653 When {expr} is a |List| then the matching item, the index
5654 of first item where {pat} matches, the start position and the
5655 end position of the match are returned. >
5656 :echo matchstrpos([1, '__x'], '\a')
5657< result is ["x", 1, 2, 3].
5658 The type isn't changed, it's not necessarily a String.
5659
5660 Can also be used as a |method|: >
5661 GetText()->matchstrpos('word')
5662<
5663
5664 *max()*
5665max({expr}) Return the maximum value of all items in {expr}. Example: >
5666 echo max([apples, pears, oranges])
5667
5668< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
5669 it returns the maximum of all values in the Dictionary.
5670 If {expr} is neither a List nor a Dictionary, or one of the
5671 items in {expr} cannot be used as a Number this results in
5672 an error. An empty |List| or |Dictionary| results in zero.
5673
5674 Can also be used as a |method|: >
5675 mylist->max()
5676
5677
5678menu_info({name} [, {mode}]) *menu_info()*
5679 Return information about the specified menu {name} in
5680 mode {mode}. The menu name should be specified without the
5681 shortcut character ('&'). If {name} is "", then the top-level
5682 menu names are returned.
5683
5684 {mode} can be one of these strings:
5685 "n" Normal
5686 "v" Visual (including Select)
5687 "o" Operator-pending
5688 "i" Insert
5689 "c" Cmd-line
5690 "s" Select
5691 "x" Visual
5692 "t" Terminal-Job
5693 "" Normal, Visual and Operator-pending
5694 "!" Insert and Cmd-line
5695 When {mode} is omitted, the modes for "" are used.
5696
5697 Returns a |Dictionary| containing the following items:
5698 accel menu item accelerator text |menu-text|
5699 display display name (name without '&')
5700 enabled v:true if this menu item is enabled
5701 Refer to |:menu-enable|
5702 icon name of the icon file (for toolbar)
5703 |toolbar-icon|
5704 iconidx index of a built-in icon
5705 modes modes for which the menu is defined. In
5706 addition to the modes mentioned above, these
5707 characters will be used:
5708 " " Normal, Visual and Operator-pending
5709 name menu item name.
5710 noremenu v:true if the {rhs} of the menu item is not
5711 remappable else v:false.
5712 priority menu order priority |menu-priority|
5713 rhs right-hand-side of the menu item. The returned
5714 string has special characters translated like
5715 in the output of the ":menu" command listing.
5716 When the {rhs} of a menu item is empty, then
5717 "<Nop>" is returned.
5718 script v:true if script-local remapping of {rhs} is
5719 allowed else v:false. See |:menu-script|.
5720 shortcut shortcut key (character after '&' in
5721 the menu name) |menu-shortcut|
5722 silent v:true if the menu item is created
5723 with <silent> argument |:menu-silent|
5724 submenus |List| containing the names of
5725 all the submenus. Present only if the menu
5726 item has submenus.
5727
5728 Returns an empty dictionary if the menu item is not found.
5729
5730 Examples: >
5731 :echo menu_info('Edit.Cut')
5732 :echo menu_info('File.Save', 'n')
5733
5734 " Display the entire menu hierarchy in a buffer
5735 func ShowMenu(name, pfx)
5736 let m = menu_info(a:name)
5737 call append(line('$'), a:pfx .. m.display)
5738 for child in m->get('submenus', [])
5739 call ShowMenu(a:name .. '.' .. escape(child, '.'),
5740 \ a:pfx .. ' ')
5741 endfor
5742 endfunc
5743 new
5744 for topmenu in menu_info('').submenus
5745 call ShowMenu(topmenu, '')
5746 endfor
5747<
5748 Can also be used as a |method|: >
5749 GetMenuName()->menu_info('v')
5750
5751
5752< *min()*
5753min({expr}) Return the minimum value of all items in {expr}. Example: >
5754 echo min([apples, pears, oranges])
5755
5756< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
5757 it returns the minimum of all values in the Dictionary.
5758 If {expr} is neither a List nor a Dictionary, or one of the
5759 items in {expr} cannot be used as a Number this results in
5760 an error. An empty |List| or |Dictionary| results in zero.
5761
5762 Can also be used as a |method|: >
5763 mylist->min()
5764
5765< *mkdir()* *E739*
5766mkdir({name} [, {path} [, {prot}]])
5767 Create directory {name}.
5768
5769 If {path} is "p" then intermediate directories are created as
5770 necessary. Otherwise it must be "".
5771
5772 If {prot} is given it is used to set the protection bits of
5773 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
5774 the user, readable for others). Use 0o700 to make it
5775 unreadable for others. This is only used for the last part of
5776 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
5777 created with 0o755.
5778 Example: >
5779 :call mkdir($HOME . "/tmp/foo/bar", "p", 0o700)
5780
5781< This function is not available in the |sandbox|.
5782
5783 There is no error if the directory already exists and the "p"
5784 flag is passed (since patch 8.0.1708). However, without the
5785 "p" option the call will fail.
5786
5787 The function result is a Number, which is TRUE if the call was
5788 successful or FALSE if the directory creation failed or partly
5789 failed.
5790
5791 Not available on all systems. To check use: >
5792 :if exists("*mkdir")
5793
5794< Can also be used as a |method|: >
5795 GetName()->mkdir()
5796<
5797 *mode()*
5798mode([expr]) Return a string that indicates the current mode.
5799 If [expr] is supplied and it evaluates to a non-zero Number or
5800 a non-empty String (|non-zero-arg|), then the full mode is
5801 returned, otherwise only the first letter is returned.
5802 Also see |state()|.
5803
5804 n Normal
5805 no Operator-pending
5806 nov Operator-pending (forced characterwise |o_v|)
5807 noV Operator-pending (forced linewise |o_V|)
5808 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
5809 CTRL-V is one character
5810 niI Normal using |i_CTRL-O| in |Insert-mode|
5811 niR Normal using |i_CTRL-O| in |Replace-mode|
5812 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
5813 nt Terminal-Normal (insert goes to Terminal-Job mode)
5814 v Visual by character
5815 vs Visual by character using |v_CTRL-O| in Select mode
5816 V Visual by line
5817 Vs Visual by line using |v_CTRL-O| in Select mode
5818 CTRL-V Visual blockwise
5819 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
5820 s Select by character
5821 S Select by line
5822 CTRL-S Select blockwise
5823 i Insert
5824 ic Insert mode completion |compl-generic|
5825 ix Insert mode |i_CTRL-X| completion
5826 R Replace |R|
5827 Rc Replace mode completion |compl-generic|
5828 Rx Replace mode |i_CTRL-X| completion
5829 Rv Virtual Replace |gR|
5830 Rvc Virtual Replace mode completion |compl-generic|
5831 Rvx Virtual Replace mode |i_CTRL-X| completion
5832 c Command-line editing
5833 cv Vim Ex mode |gQ|
5834 ce Normal Ex mode |Q|
5835 r Hit-enter prompt
5836 rm The -- more -- prompt
5837 r? A |:confirm| query of some sort
5838 ! Shell or external command is executing
5839 t Terminal-Job mode: keys go to the job
5840
5841 This is useful in the 'statusline' option or when used
5842 with |remote_expr()| In most other places it always returns
5843 "c" or "n".
5844 Note that in the future more modes and more specific modes may
5845 be added. It's better not to compare the whole string but only
5846 the leading character(s).
5847 Also see |visualmode()|.
5848
5849 Can also be used as a |method|: >
5850 DoFull()->mode()
5851
5852mzeval({expr}) *mzeval()*
5853 Evaluate MzScheme expression {expr} and return its result
5854 converted to Vim data structures.
5855 Numbers and strings are returned as they are.
5856 Pairs (including lists and improper lists) and vectors are
5857 returned as Vim |Lists|.
5858 Hash tables are represented as Vim |Dictionary| type with keys
5859 converted to strings.
5860 All other types are converted to string with display function.
5861 Examples: >
5862 :mz (define l (list 1 2 3))
5863 :mz (define h (make-hash)) (hash-set! h "list" l)
5864 :echo mzeval("l")
5865 :echo mzeval("h")
5866<
5867 Note that in a `:def` function local variables are not visible
5868 to {expr}.
5869
5870 Can also be used as a |method|: >
5871 GetExpr()->mzeval()
5872<
5873 {only available when compiled with the |+mzscheme| feature}
5874
5875nextnonblank({lnum}) *nextnonblank()*
5876 Return the line number of the first line at or below {lnum}
5877 that is not blank. Example: >
5878 if getline(nextnonblank(1)) =~ "Java"
5879< When {lnum} is invalid or there is no non-blank line at or
5880 below it, zero is returned.
5881 {lnum} is used like with |getline()|.
5882 See also |prevnonblank()|.
5883
5884 Can also be used as a |method|: >
5885 GetLnum()->nextnonblank()
5886
5887nr2char({expr} [, {utf8}]) *nr2char()*
5888 Return a string with a single character, which has the number
5889 value {expr}. Examples: >
5890 nr2char(64) returns "@"
5891 nr2char(32) returns " "
5892< When {utf8} is omitted or zero, the current 'encoding' is used.
5893 Example for "utf-8": >
5894 nr2char(300) returns I with bow character
5895< When {utf8} is TRUE, always return UTF-8 characters.
5896 Note that a NUL character in the file is specified with
5897 nr2char(10), because NULs are represented with newline
5898 characters. nr2char(0) is a real NUL and terminates the
5899 string, thus results in an empty string.
5900 To turn a list of character numbers into a string: >
5901 let list = [65, 66, 67]
5902 let str = join(map(list, {_, val -> nr2char(val)}), '')
5903< Result: "ABC"
5904
5905 Can also be used as a |method|: >
5906 GetNumber()->nr2char()
5907
5908or({expr}, {expr}) *or()*
5909 Bitwise OR on the two arguments. The arguments are converted
5910 to a number. A List, Dict or Float argument causes an error.
5911 Example: >
5912 :let bits = or(bits, 0x80)
5913< Can also be used as a |method|: >
5914 :let bits = bits->or(0x80)
5915
5916
5917pathshorten({path} [, {len}]) *pathshorten()*
5918 Shorten directory names in the path {path} and return the
5919 result. The tail, the file name, is kept as-is. The other
5920 components in the path are reduced to {len} letters in length.
5921 If {len} is omitted or smaller than 1 then 1 is used (single
5922 letters). Leading '~' and '.' characters are kept. Examples: >
5923 :echo pathshorten('~/.vim/autoload/myfile.vim')
5924< ~/.v/a/myfile.vim ~
5925>
5926 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
5927< ~/.vi/au/myfile.vim ~
5928 It doesn't matter if the path exists or not.
5929
5930 Can also be used as a |method|: >
5931 GetDirectories()->pathshorten()
5932
5933perleval({expr}) *perleval()*
5934 Evaluate Perl expression {expr} in scalar context and return
5935 its result converted to Vim data structures. If value can't be
5936 converted, it is returned as a string Perl representation.
5937 Note: If you want an array or hash, {expr} must return a
5938 reference to it.
5939 Example: >
5940 :echo perleval('[1 .. 4]')
5941< [1, 2, 3, 4]
5942
5943 Note that in a `:def` function local variables are not visible
5944 to {expr}.
5945
5946 Can also be used as a |method|: >
5947 GetExpr()->perleval()
5948
5949< {only available when compiled with the |+perl| feature}
5950
5951
5952popup_ functions are documented here: |popup-functions|
5953
5954
5955pow({x}, {y}) *pow()*
5956 Return the power of {x} to the exponent {y} as a |Float|.
5957 {x} and {y} must evaluate to a |Float| or a |Number|.
5958 Examples: >
5959 :echo pow(3, 3)
5960< 27.0 >
5961 :echo pow(2, 16)
5962< 65536.0 >
5963 :echo pow(32, 0.20)
5964< 2.0
5965
5966 Can also be used as a |method|: >
5967 Compute()->pow(3)
5968<
5969 {only available when compiled with the |+float| feature}
5970
5971prevnonblank({lnum}) *prevnonblank()*
5972 Return the line number of the first line at or above {lnum}
5973 that is not blank. Example: >
5974 let ind = indent(prevnonblank(v:lnum - 1))
5975< When {lnum} is invalid or there is no non-blank line at or
5976 above it, zero is returned.
5977 {lnum} is used like with |getline()|.
5978 Also see |nextnonblank()|.
5979
5980 Can also be used as a |method|: >
5981 GetLnum()->prevnonblank()
5982
5983printf({fmt}, {expr1} ...) *printf()*
5984 Return a String with {fmt}, where "%" items are replaced by
5985 the formatted form of their respective arguments. Example: >
5986 printf("%4d: E%d %.30s", lnum, errno, msg)
5987< May result in:
5988 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
5989
5990 When used as a |method| the base is passed as the second
5991 argument: >
5992 Compute()->printf("result: %d")
5993
5994< Often used items are:
5995 %s string
5996 %6S string right-aligned in 6 display cells
5997 %6s string right-aligned in 6 bytes
5998 %.9s string truncated to 9 bytes
5999 %c single byte
6000 %d decimal number
6001 %5d decimal number padded with spaces to 5 characters
6002 %x hex number
6003 %04x hex number padded with zeros to at least 4 characters
6004 %X hex number using upper case letters
6005 %o octal number
6006 %08b binary number padded with zeros to at least 8 chars
6007 %f floating point number as 12.23, inf, -inf or nan
6008 %F floating point number as 12.23, INF, -INF or NAN
6009 %e floating point number as 1.23e3, inf, -inf or nan
6010 %E floating point number as 1.23E3, INF, -INF or NAN
6011 %g floating point number, as %f or %e depending on value
6012 %G floating point number, as %F or %E depending on value
6013 %% the % character itself
6014
6015 Conversion specifications start with '%' and end with the
6016 conversion type. All other characters are copied unchanged to
6017 the result.
6018
6019 The "%" starts a conversion specification. The following
6020 arguments appear in sequence:
6021
6022 % [flags] [field-width] [.precision] type
6023
6024 flags
6025 Zero or more of the following flags:
6026
6027 # The value should be converted to an "alternate
6028 form". For c, d, and s conversions, this option
6029 has no effect. For o conversions, the precision
6030 of the number is increased to force the first
6031 character of the output string to a zero (except
6032 if a zero value is printed with an explicit
6033 precision of zero).
6034 For b and B conversions, a non-zero result has
6035 the string "0b" (or "0B" for B conversions)
6036 prepended to it.
6037 For x and X conversions, a non-zero result has
6038 the string "0x" (or "0X" for X conversions)
6039 prepended to it.
6040
6041 0 (zero) Zero padding. For all conversions the converted
6042 value is padded on the left with zeros rather
6043 than blanks. If a precision is given with a
6044 numeric conversion (d, b, B, o, x, and X), the 0
6045 flag is ignored.
6046
6047 - A negative field width flag; the converted value
6048 is to be left adjusted on the field boundary.
6049 The converted value is padded on the right with
6050 blanks, rather than on the left with blanks or
6051 zeros. A - overrides a 0 if both are given.
6052
6053 ' ' (space) A blank should be left before a positive
6054 number produced by a signed conversion (d).
6055
6056 + A sign must always be placed before a number
6057 produced by a signed conversion. A + overrides
6058 a space if both are used.
6059
6060 field-width
6061 An optional decimal digit string specifying a minimum
6062 field width. If the converted value has fewer bytes
6063 than the field width, it will be padded with spaces on
6064 the left (or right, if the left-adjustment flag has
6065 been given) to fill out the field width. For the S
6066 conversion the count is in cells.
6067
6068 .precision
6069 An optional precision, in the form of a period '.'
6070 followed by an optional digit string. If the digit
6071 string is omitted, the precision is taken as zero.
6072 This gives the minimum number of digits to appear for
6073 d, o, x, and X conversions, the maximum number of
6074 bytes to be printed from a string for s conversions,
6075 or the maximum number of cells to be printed from a
6076 string for S conversions.
6077 For floating point it is the number of digits after
6078 the decimal point.
6079
6080 type
6081 A character that specifies the type of conversion to
6082 be applied, see below.
6083
6084 A field width or precision, or both, may be indicated by an
6085 asterisk '*' instead of a digit string. In this case, a
6086 Number argument supplies the field width or precision. A
6087 negative field width is treated as a left adjustment flag
6088 followed by a positive field width; a negative precision is
6089 treated as though it were missing. Example: >
6090 :echo printf("%d: %.*s", nr, width, line)
6091< This limits the length of the text used from "line" to
6092 "width" bytes.
6093
6094 The conversion specifiers and their meanings are:
6095
6096 *printf-d* *printf-b* *printf-B* *printf-o*
6097 *printf-x* *printf-X*
6098 dbBoxX The Number argument is converted to signed decimal
6099 (d), unsigned binary (b and B), unsigned octal (o), or
6100 unsigned hexadecimal (x and X) notation. The letters
6101 "abcdef" are used for x conversions; the letters
6102 "ABCDEF" are used for X conversions.
6103 The precision, if any, gives the minimum number of
6104 digits that must appear; if the converted value
6105 requires fewer digits, it is padded on the left with
6106 zeros.
6107 In no case does a non-existent or small field width
6108 cause truncation of a numeric field; if the result of
6109 a conversion is wider than the field width, the field
6110 is expanded to contain the conversion result.
6111 The 'h' modifier indicates the argument is 16 bits.
6112 The 'l' modifier indicates the argument is 32 bits.
6113 The 'L' modifier indicates the argument is 64 bits.
6114 Generally, these modifiers are not useful. They are
6115 ignored when type is known from the argument.
6116
6117 i alias for d
6118 D alias for ld
6119 U alias for lu
6120 O alias for lo
6121
6122 *printf-c*
6123 c The Number argument is converted to a byte, and the
6124 resulting character is written.
6125
6126 *printf-s*
6127 s The text of the String argument is used. If a
6128 precision is specified, no more bytes than the number
6129 specified are used.
6130 If the argument is not a String type, it is
6131 automatically converted to text with the same format
6132 as ":echo".
6133 *printf-S*
6134 S The text of the String argument is used. If a
6135 precision is specified, no more display cells than the
6136 number specified are used.
6137
6138 *printf-f* *E807*
6139 f F The Float argument is converted into a string of the
6140 form 123.456. The precision specifies the number of
6141 digits after the decimal point. When the precision is
6142 zero the decimal point is omitted. When the precision
6143 is not specified 6 is used. A really big number
6144 (out of range or dividing by zero) results in "inf"
6145 or "-inf" with %f (INF or -INF with %F).
6146 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
6147 Example: >
6148 echo printf("%.2f", 12.115)
6149< 12.12
6150 Note that roundoff depends on the system libraries.
6151 Use |round()| when in doubt.
6152
6153 *printf-e* *printf-E*
6154 e E The Float argument is converted into a string of the
6155 form 1.234e+03 or 1.234E+03 when using 'E'. The
6156 precision specifies the number of digits after the
6157 decimal point, like with 'f'.
6158
6159 *printf-g* *printf-G*
6160 g G The Float argument is converted like with 'f' if the
6161 value is between 0.001 (inclusive) and 10000000.0
6162 (exclusive). Otherwise 'e' is used for 'g' and 'E'
6163 for 'G'. When no precision is specified superfluous
6164 zeroes and '+' signs are removed, except for the zero
6165 immediately after the decimal point. Thus 10000000.0
6166 results in 1.0e7.
6167
6168 *printf-%*
6169 % A '%' is written. No argument is converted. The
6170 complete conversion specification is "%%".
6171
6172 When a Number argument is expected a String argument is also
6173 accepted and automatically converted.
6174 When a Float or String argument is expected a Number argument
6175 is also accepted and automatically converted.
6176 Any other argument type results in an error message.
6177
6178 *E766* *E767*
6179 The number of {exprN} arguments must exactly match the number
6180 of "%" items. If there are not sufficient or too many
6181 arguments an error is given. Up to 18 arguments can be used.
6182
6183
6184prompt_getprompt({buf}) *prompt_getprompt()*
6185 Returns the effective prompt text for buffer {buf}. {buf} can
6186 be a buffer name or number. See |prompt-buffer|.
6187
6188 If the buffer doesn't exist or isn't a prompt buffer, an empty
6189 string is returned.
6190
6191 Can also be used as a |method|: >
6192 GetBuffer()->prompt_getprompt()
6193
6194< {only available when compiled with the |+channel| feature}
6195
6196
6197prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
6198 Set prompt callback for buffer {buf} to {expr}. When {expr}
6199 is an empty string the callback is removed. This has only
6200 effect if {buf} has 'buftype' set to "prompt".
6201
6202 The callback is invoked when pressing Enter. The current
6203 buffer will always be the prompt buffer. A new line for a
6204 prompt is added before invoking the callback, thus the prompt
6205 for which the callback was invoked will be in the last but one
6206 line.
6207 If the callback wants to add text to the buffer, it must
6208 insert it above the last line, since that is where the current
6209 prompt is. This can also be done asynchronously.
6210 The callback is invoked with one argument, which is the text
6211 that was entered at the prompt. This can be an empty string
6212 if the user only typed Enter.
6213 Example: >
6214 call prompt_setcallback(bufnr(), function('s:TextEntered'))
6215 func s:TextEntered(text)
6216 if a:text == 'exit' || a:text == 'quit'
6217 stopinsert
6218 close
6219 else
6220 call append(line('$') - 1, 'Entered: "' . a:text . '"')
6221 " Reset 'modified' to allow the buffer to be closed.
6222 set nomodified
6223 endif
6224 endfunc
6225
6226< Can also be used as a |method|: >
6227 GetBuffer()->prompt_setcallback(callback)
6228
6229< {only available when compiled with the |+channel| feature}
6230
6231prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
6232 Set a callback for buffer {buf} to {expr}. When {expr} is an
6233 empty string the callback is removed. This has only effect if
6234 {buf} has 'buftype' set to "prompt".
6235
6236 This callback will be invoked when pressing CTRL-C in Insert
6237 mode. Without setting a callback Vim will exit Insert mode,
6238 as in any buffer.
6239
6240 Can also be used as a |method|: >
6241 GetBuffer()->prompt_setinterrupt(callback)
6242
6243< {only available when compiled with the |+channel| feature}
6244
6245prompt_setprompt({buf}, {text}) *prompt_setprompt()*
6246 Set prompt for buffer {buf} to {text}. You most likely want
6247 {text} to end in a space.
6248 The result is only visible if {buf} has 'buftype' set to
6249 "prompt". Example: >
6250 call prompt_setprompt(bufnr(), 'command: ')
6251<
6252 Can also be used as a |method|: >
6253 GetBuffer()->prompt_setprompt('command: ')
6254
6255< {only available when compiled with the |+channel| feature}
6256
6257prop_ functions are documented here: |text-prop-functions|
6258
6259pum_getpos() *pum_getpos()*
6260 If the popup menu (see |ins-completion-menu|) is not visible,
6261 returns an empty |Dictionary|, otherwise, returns a
6262 |Dictionary| with the following keys:
6263 height nr of items visible
6264 width screen cells
6265 row top screen row (0 first row)
6266 col leftmost screen column (0 first col)
6267 size total nr of items
6268 scrollbar |TRUE| if scrollbar is visible
6269
6270 The values are the same as in |v:event| during
6271 |CompleteChanged|.
6272
6273pumvisible() *pumvisible()*
6274 Returns non-zero when the popup menu is visible, zero
6275 otherwise. See |ins-completion-menu|.
6276 This can be used to avoid some things that would remove the
6277 popup menu.
6278
6279py3eval({expr}) *py3eval()*
6280 Evaluate Python expression {expr} and return its result
6281 converted to Vim data structures.
6282 Numbers and strings are returned as they are (strings are
6283 copied though, Unicode strings are additionally converted to
6284 'encoding').
6285 Lists are represented as Vim |List| type.
6286 Dictionaries are represented as Vim |Dictionary| type with
6287 keys converted to strings.
6288 Note that in a `:def` function local variables are not visible
6289 to {expr}.
6290
6291 Can also be used as a |method|: >
6292 GetExpr()->py3eval()
6293
6294< {only available when compiled with the |+python3| feature}
6295
6296 *E858* *E859*
6297pyeval({expr}) *pyeval()*
6298 Evaluate Python expression {expr} and return its result
6299 converted to Vim data structures.
6300 Numbers and strings are returned as they are (strings are
6301 copied though).
6302 Lists are represented as Vim |List| type.
6303 Dictionaries are represented as Vim |Dictionary| type,
6304 non-string keys result in error.
6305 Note that in a `:def` function local variables are not visible
6306 to {expr}.
6307
6308 Can also be used as a |method|: >
6309 GetExpr()->pyeval()
6310
6311< {only available when compiled with the |+python| feature}
6312
6313pyxeval({expr}) *pyxeval()*
6314 Evaluate Python expression {expr} and return its result
6315 converted to Vim data structures.
6316 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
6317 See also: |pyeval()|, |py3eval()|
6318
6319 Can also be used as a |method|: >
6320 GetExpr()->pyxeval()
6321
6322< {only available when compiled with the |+python| or the
6323 |+python3| feature}
6324
6325rand([{expr}]) *rand()* *random*
6326 Return a pseudo-random Number generated with an xoshiro128**
6327 algorithm using seed {expr}. The returned number is 32 bits,
6328 also on 64 bits systems, for consistency.
6329 {expr} can be initialized by |srand()| and will be updated by
6330 rand(). If {expr} is omitted, an internal seed value is used
6331 and updated.
6332
6333 Examples: >
6334 :echo rand()
6335 :let seed = srand()
6336 :echo rand(seed)
6337 :echo rand(seed) % 16 " random number 0 - 15
6338<
6339
6340 *E726* *E727*
6341range({expr} [, {max} [, {stride}]]) *range()*
6342 Returns a |List| with Numbers:
6343 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
6344 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
6345 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
6346 {max}] (increasing {expr} with {stride} each time, not
6347 producing a value past {max}).
6348 When the maximum is one before the start the result is an
6349 empty list. When the maximum is more than one before the
6350 start this is an error.
6351 Examples: >
6352 range(4) " [0, 1, 2, 3]
6353 range(2, 4) " [2, 3, 4]
6354 range(2, 9, 3) " [2, 5, 8]
6355 range(2, -2, -1) " [2, 1, 0, -1, -2]
6356 range(0) " []
6357 range(2, 0) " error!
6358<
6359 Can also be used as a |method|: >
6360 GetExpr()->range()
6361<
6362
6363readblob({fname}) *readblob()*
6364 Read file {fname} in binary mode and return a |Blob|.
6365 When the file can't be opened an error message is given and
6366 the result is an empty |Blob|.
6367 Also see |readfile()| and |writefile()|.
6368
6369
6370readdir({directory} [, {expr} [, {dict}]]) *readdir()*
6371 Return a list with file and directory names in {directory}.
6372 You can also use |glob()| if you don't need to do complicated
6373 things, such as limiting the number of matches.
6374 The list will be sorted (case sensitive), see the {dict}
6375 argument below for changing the sort order.
6376
6377 When {expr} is omitted all entries are included.
6378 When {expr} is given, it is evaluated to check what to do:
6379 If {expr} results in -1 then no further entries will
6380 be handled.
6381 If {expr} results in 0 then this entry will not be
6382 added to the list.
6383 If {expr} results in 1 then this entry will be added
6384 to the list.
6385 The entries "." and ".." are always excluded.
6386 Each time {expr} is evaluated |v:val| is set to the entry name.
6387 When {expr} is a function the name is passed as the argument.
6388 For example, to get a list of files ending in ".txt": >
6389 readdir(dirname, {n -> n =~ '.txt$'})
6390< To skip hidden and backup files: >
6391 readdir(dirname, {n -> n !~ '^\.\|\~$'})
6392
6393< The optional {dict} argument allows for further custom
6394 values. Currently this is used to specify if and how sorting
6395 should be performed. The dict can have the following members:
6396
6397 sort How to sort the result returned from the system.
6398 Valid values are:
6399 "none" do not sort (fastest method)
6400 "case" sort case sensitive (byte value of
6401 each character, technically, using
6402 strcmp()) (default)
6403 "icase" sort case insensitive (technically
6404 using strcasecmp())
6405 "collate" sort using the collation order
6406 of the "POSIX" or "C" |locale|
6407 (technically using strcoll())
6408 Other values are silently ignored.
6409
6410 For example, to get a list of all files in the current
6411 directory without sorting the individual entries: >
6412 readdir('.', '1', #{sort: 'none'})
6413< If you want to get a directory tree: >
6414 function! s:tree(dir)
6415 return {a:dir : map(readdir(a:dir),
6416 \ {_, x -> isdirectory(x) ?
6417 \ {x : s:tree(a:dir . '/' . x)} : x})}
6418 endfunction
6419 echo s:tree(".")
6420<
6421 Can also be used as a |method|: >
6422 GetDirName()->readdir()
6423<
6424readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
6425 Extended version of |readdir()|.
6426 Return a list of Dictionaries with file and directory
6427 information in {directory}.
6428 This is useful if you want to get the attributes of file and
6429 directory at the same time as getting a list of a directory.
6430 This is much faster than calling |readdir()| then calling
6431 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
6432 each file and directory especially on MS-Windows.
6433 The list will by default be sorted by name (case sensitive),
6434 the sorting can be changed by using the optional {dict}
6435 argument, see |readdir()|.
6436
6437 The Dictionary for file and directory information has the
6438 following items:
6439 group Group name of the entry. (Only on Unix)
6440 name Name of the entry.
6441 perm Permissions of the entry. See |getfperm()|.
6442 size Size of the entry. See |getfsize()|.
6443 time Timestamp of the entry. See |getftime()|.
6444 type Type of the entry.
6445 On Unix, almost same as |getftype()| except:
6446 Symlink to a dir "linkd"
6447 Other symlink "link"
6448 On MS-Windows:
6449 Normal file "file"
6450 Directory "dir"
6451 Junction "junction"
6452 Symlink to a dir "linkd"
6453 Other symlink "link"
6454 Other reparse point "reparse"
6455 user User name of the entry's owner. (Only on Unix)
6456 On Unix, if the entry is a symlink, the Dictionary includes
6457 the information of the target (except the "type" item).
6458 On MS-Windows, it includes the information of the symlink
6459 itself because of performance reasons.
6460
6461 When {expr} is omitted all entries are included.
6462 When {expr} is given, it is evaluated to check what to do:
6463 If {expr} results in -1 then no further entries will
6464 be handled.
6465 If {expr} results in 0 then this entry will not be
6466 added to the list.
6467 If {expr} results in 1 then this entry will be added
6468 to the list.
6469 The entries "." and ".." are always excluded.
6470 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
6471 of the entry.
6472 When {expr} is a function the entry is passed as the argument.
6473 For example, to get a list of files ending in ".txt": >
6474 readdirex(dirname, {e -> e.name =~ '.txt$'})
6475<
6476 For example, to get a list of all files in the current
6477 directory without sorting the individual entries: >
6478 readdirex(dirname, '1', #{sort: 'none'})
6479
6480<
6481 Can also be used as a |method|: >
6482 GetDirName()->readdirex()
6483<
6484
6485 *readfile()*
6486readfile({fname} [, {type} [, {max}]])
6487 Read file {fname} and return a |List|, each line of the file
6488 as an item. Lines are broken at NL characters. Macintosh
6489 files separated with CR will result in a single long line
6490 (unless a NL appears somewhere).
6491 All NUL characters are replaced with a NL character.
6492 When {type} contains "b" binary mode is used:
6493 - When the last line ends in a NL an extra empty list item is
6494 added.
6495 - No CR characters are removed.
6496 Otherwise:
6497 - CR characters that appear before a NL are removed.
6498 - Whether the last line ends in a NL or not does not matter.
6499 - When 'encoding' is Unicode any UTF-8 byte order mark is
6500 removed from the text.
6501 When {max} is given this specifies the maximum number of lines
6502 to be read. Useful if you only want to check the first ten
6503 lines of a file: >
6504 :for line in readfile(fname, '', 10)
6505 : if line =~ 'Date' | echo line | endif
6506 :endfor
6507< When {max} is negative -{max} lines from the end of the file
6508 are returned, or as many as there are.
6509 When {max} is zero the result is an empty list.
6510 Note that without {max} the whole file is read into memory.
6511 Also note that there is no recognition of encoding. Read a
6512 file into a buffer if you need to.
6513 Deprecated (use |readblob()| instead): When {type} contains
6514 "B" a |Blob| is returned with the binary data of the file
6515 unmodified.
6516 When the file can't be opened an error message is given and
6517 the result is an empty list.
6518 Also see |writefile()|.
6519
6520 Can also be used as a |method|: >
6521 GetFileName()->readfile()
6522
6523reduce({object}, {func} [, {initial}]) *reduce()* *E998*
6524 {func} is called for every item in {object}, which can be a
6525 |String|, |List| or a |Blob|. {func} is called with two
6526 arguments: the result so far and current item. After
6527 processing all items the result is returned.
6528
6529 {initial} is the initial result. When omitted, the first item
6530 in {object} is used and {func} is first called for the second
6531 item. If {initial} is not given and {object} is empty no
6532 result can be computed, an E998 error is given.
6533
6534 Examples: >
6535 echo reduce([1, 3, 5], { acc, val -> acc + val })
6536 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
6537 echo reduce(0z1122, { acc, val -> 2 * acc + val })
6538 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
6539<
6540 Can also be used as a |method|: >
6541 echo mylist->reduce({ acc, val -> acc + val }, 0)
6542
6543
6544reg_executing() *reg_executing()*
6545 Returns the single letter name of the register being executed.
6546 Returns an empty string when no register is being executed.
6547 See |@|.
6548
6549reg_recording() *reg_recording()*
6550 Returns the single letter name of the register being recorded.
6551 Returns an empty string when not recording. See |q|.
6552
6553reltime([{start} [, {end}]]) *reltime()*
6554 Return an item that represents a time value. The item is a
6555 list with items that depend on the system. In Vim 9 script
6556 list<any> can be used.
6557 The item can be passed to |reltimestr()| to convert it to a
6558 string or |reltimefloat()| to convert to a Float.
6559
6560 Without an argument reltime() returns the current time.
6561 With one argument is returns the time passed since the time
6562 specified in the argument.
6563 With two arguments it returns the time passed between {start}
6564 and {end}.
6565
6566 The {start} and {end} arguments must be values returned by
6567 reltime(). If there is an error zero is returned in legacy
6568 script, in Vim9 script an error is given.
6569
6570 Can also be used as a |method|: >
6571 GetStart()->reltime()
6572<
6573 {only available when compiled with the |+reltime| feature}
6574
6575reltimefloat({time}) *reltimefloat()*
6576 Return a Float that represents the time value of {time}.
6577 Example: >
6578 let start = reltime()
6579 call MyFunction()
6580 let seconds = reltimefloat(reltime(start))
6581< See the note of reltimestr() about overhead.
6582 Also see |profiling|.
6583 If there is an error 0.0 is returned in legacy script, in Vim9
6584 script an error is given.
6585
6586 Can also be used as a |method|: >
6587 reltime(start)->reltimefloat()
6588
6589< {only available when compiled with the |+reltime| feature}
6590
6591reltimestr({time}) *reltimestr()*
6592 Return a String that represents the time value of {time}.
6593 This is the number of seconds, a dot and the number of
6594 microseconds. Example: >
6595 let start = reltime()
6596 call MyFunction()
6597 echo reltimestr(reltime(start))
6598< Note that overhead for the commands will be added to the time.
6599 The accuracy depends on the system.
6600 Leading spaces are used to make the string align nicely. You
6601 can use split() to remove it. >
6602 echo split(reltimestr(reltime(start)))[0]
6603< Also see |profiling|.
6604 If there is an error an empty string is returned in legacy
6605 script, in Vim9 script an error is given.
6606
6607 Can also be used as a |method|: >
6608 reltime(start)->reltimestr()
6609
6610< {only available when compiled with the |+reltime| feature}
6611
6612 *remote_expr()* *E449*
6613remote_expr({server}, {string} [, {idvar} [, {timeout}]])
6614 Send the {string} to {server}. The string is sent as an
6615 expression and the result is returned after evaluation.
6616 The result must be a String or a |List|. A |List| is turned
6617 into a String by joining the items with a line break in
6618 between (not at the end), like with join(expr, "\n").
6619 If {idvar} is present and not empty, it is taken as the name
6620 of a variable and a {serverid} for later use with
6621 |remote_read()| is stored there.
6622 If {timeout} is given the read times out after this many
6623 seconds. Otherwise a timeout of 600 seconds is used.
6624 See also |clientserver| |RemoteReply|.
6625 This function is not available in the |sandbox|.
6626 {only available when compiled with the |+clientserver| feature}
6627 Note: Any errors will cause a local error message to be issued
6628 and the result will be the empty string.
6629
6630 Variables will be evaluated in the global namespace,
6631 independent of a function currently being active. Except
6632 when in debug mode, then local function variables and
6633 arguments can be evaluated.
6634
6635 Examples: >
6636 :echo remote_expr("gvim", "2+2")
6637 :echo remote_expr("gvim1", "b:current_syntax")
6638<
6639 Can also be used as a |method|: >
6640 ServerName()->remote_expr(expr)
6641
6642remote_foreground({server}) *remote_foreground()*
6643 Move the Vim server with the name {server} to the foreground.
6644 The {server} argument is a string.
6645 This works like: >
6646 remote_expr({server}, "foreground()")
6647< Except that on Win32 systems the client does the work, to work
6648 around the problem that the OS doesn't always allow the server
6649 to bring itself to the foreground.
6650 Note: This does not restore the window if it was minimized,
6651 like foreground() does.
6652 This function is not available in the |sandbox|.
6653
6654 Can also be used as a |method|: >
6655 ServerName()->remote_foreground()
6656
6657< {only in the Win32, Athena, Motif and GTK GUI versions and the
6658 Win32 console version}
6659
6660
6661remote_peek({serverid} [, {retvar}]) *remote_peek()*
6662 Returns a positive number if there are available strings
6663 from {serverid}. Copies any reply string into the variable
6664 {retvar} if specified. {retvar} must be a string with the
6665 name of a variable.
6666 Returns zero if none are available.
6667 Returns -1 if something is wrong.
6668 See also |clientserver|.
6669 This function is not available in the |sandbox|.
6670 {only available when compiled with the |+clientserver| feature}
6671 Examples: >
6672 :let repl = ""
6673 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
6674
6675< Can also be used as a |method|: >
6676 ServerId()->remote_peek()
6677
6678remote_read({serverid}, [{timeout}]) *remote_read()*
6679 Return the oldest available reply from {serverid} and consume
6680 it. Unless a {timeout} in seconds is given, it blocks until a
6681 reply is available.
6682 See also |clientserver|.
6683 This function is not available in the |sandbox|.
6684 {only available when compiled with the |+clientserver| feature}
6685 Example: >
6686 :echo remote_read(id)
6687
6688< Can also be used as a |method|: >
6689 ServerId()->remote_read()
6690<
6691 *remote_send()* *E241*
6692remote_send({server}, {string} [, {idvar}])
6693 Send the {string} to {server}. The string is sent as input
6694 keys and the function returns immediately. At the Vim server
6695 the keys are not mapped |:map|.
6696 If {idvar} is present, it is taken as the name of a variable
6697 and a {serverid} for later use with remote_read() is stored
6698 there.
6699 See also |clientserver| |RemoteReply|.
6700 This function is not available in the |sandbox|.
6701 {only available when compiled with the |+clientserver| feature}
6702
6703 Note: Any errors will be reported in the server and may mess
6704 up the display.
6705 Examples: >
6706 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
6707 \ remote_read(serverid)
6708
6709 :autocmd NONE RemoteReply *
6710 \ echo remote_read(expand("<amatch>"))
6711 :echo remote_send("gvim", ":sleep 10 | echo ".
6712 \ 'server2client(expand("<client>"), "HELLO")<CR>')
6713<
6714 Can also be used as a |method|: >
6715 ServerName()->remote_send(keys)
6716<
6717 *remote_startserver()* *E941* *E942*
6718remote_startserver({name})
6719 Become the server {name}. This fails if already running as a
6720 server, when |v:servername| is not empty.
6721
6722 Can also be used as a |method|: >
6723 ServerName()->remote_startserver()
6724
6725< {only available when compiled with the |+clientserver| feature}
6726
6727remove({list}, {idx} [, {end}]) *remove()*
6728 Without {end}: Remove the item at {idx} from |List| {list} and
6729 return the item.
6730 With {end}: Remove items from {idx} to {end} (inclusive) and
6731 return a |List| with these items. When {idx} points to the same
6732 item as {end} a list with one item is returned. When {end}
6733 points to an item before {idx} this is an error.
6734 See |list-index| for possible values of {idx} and {end}.
6735 Example: >
6736 :echo "last item: " . remove(mylist, -1)
6737 :call remove(mylist, 0, 9)
6738<
6739 Use |delete()| to remove a file.
6740
6741 Can also be used as a |method|: >
6742 mylist->remove(idx)
6743
6744remove({blob}, {idx} [, {end}])
6745 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
6746 return the byte.
6747 With {end}: Remove bytes from {idx} to {end} (inclusive) and
6748 return a |Blob| with these bytes. When {idx} points to the same
6749 byte as {end} a |Blob| with one byte is returned. When {end}
6750 points to a byte before {idx} this is an error.
6751 Example: >
6752 :echo "last byte: " . remove(myblob, -1)
6753 :call remove(mylist, 0, 9)
6754
6755remove({dict}, {key})
6756 Remove the entry from {dict} with key {key} and return it.
6757 Example: >
6758 :echo "removed " . remove(dict, "one")
6759< If there is no {key} in {dict} this is an error.
6760
6761rename({from}, {to}) *rename()*
6762 Rename the file by the name {from} to the name {to}. This
6763 should also work to move files across file systems. The
6764 result is a Number, which is 0 if the file was renamed
6765 successfully, and non-zero when the renaming failed.
6766 NOTE: If {to} exists it is overwritten without warning.
6767 This function is not available in the |sandbox|.
6768
6769 Can also be used as a |method|: >
6770 GetOldName()->rename(newname)
6771
6772repeat({expr}, {count}) *repeat()*
6773 Repeat {expr} {count} times and return the concatenated
6774 result. Example: >
6775 :let separator = repeat('-', 80)
6776< When {count} is zero or negative the result is empty.
6777 When {expr} is a |List| the result is {expr} concatenated
6778 {count} times. Example: >
6779 :let longlist = repeat(['a', 'b'], 3)
6780< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
6781
6782 Can also be used as a |method|: >
6783 mylist->repeat(count)
6784
6785resolve({filename}) *resolve()* *E655*
6786 On MS-Windows, when {filename} is a shortcut (a .lnk file),
6787 returns the path the shortcut points to in a simplified form.
6788 When {filename} is a symbolic link or junction point, return
6789 the full path to the target. If the target of junction is
6790 removed, return {filename}.
6791 On Unix, repeat resolving symbolic links in all path
6792 components of {filename} and return the simplified result.
6793 To cope with link cycles, resolving of symbolic links is
6794 stopped after 100 iterations.
6795 On other systems, return the simplified {filename}.
6796 The simplification step is done as by |simplify()|.
6797 resolve() keeps a leading path component specifying the
6798 current directory (provided the result is still a relative
6799 path name) and also keeps a trailing path separator.
6800
6801 Can also be used as a |method|: >
6802 GetName()->resolve()
6803
6804reverse({object}) *reverse()*
6805 Reverse the order of items in {object} in-place.
6806 {object} can be a |List| or a |Blob|.
6807 Returns {object}.
6808 If you want an object to remain unmodified make a copy first: >
6809 :let revlist = reverse(copy(mylist))
6810< Can also be used as a |method|: >
6811 mylist->reverse()
6812
6813round({expr}) *round()*
6814 Round off {expr} to the nearest integral value and return it
6815 as a |Float|. If {expr} lies halfway between two integral
6816 values, then use the larger one (away from zero).
6817 {expr} must evaluate to a |Float| or a |Number|.
6818 Examples: >
6819 echo round(0.456)
6820< 0.0 >
6821 echo round(4.5)
6822< 5.0 >
6823 echo round(-4.5)
6824< -5.0
6825
6826 Can also be used as a |method|: >
6827 Compute()->round()
6828<
6829 {only available when compiled with the |+float| feature}
6830
6831rubyeval({expr}) *rubyeval()*
6832 Evaluate Ruby expression {expr} and return its result
6833 converted to Vim data structures.
6834 Numbers, floats and strings are returned as they are (strings
6835 are copied though).
6836 Arrays are represented as Vim |List| type.
6837 Hashes are represented as Vim |Dictionary| type.
6838 Other objects are represented as strings resulted from their
6839 "Object#to_s" method.
6840 Note that in a `:def` function local variables are not visible
6841 to {expr}.
6842
6843 Can also be used as a |method|: >
6844 GetRubyExpr()->rubyeval()
6845
6846< {only available when compiled with the |+ruby| feature}
6847
6848screenattr({row}, {col}) *screenattr()*
6849 Like |screenchar()|, but return the attribute. This is a rather
6850 arbitrary number that can only be used to compare to the
6851 attribute at other positions.
6852
6853 Can also be used as a |method|: >
6854 GetRow()->screenattr(col)
6855
6856screenchar({row}, {col}) *screenchar()*
6857 The result is a Number, which is the character at position
6858 [row, col] on the screen. This works for every possible
6859 screen position, also status lines, window separators and the
6860 command line. The top left position is row one, column one
6861 The character excludes composing characters. For double-byte
6862 encodings it may only be the first byte.
6863 This is mainly to be used for testing.
6864 Returns -1 when row or col is out of range.
6865
6866 Can also be used as a |method|: >
6867 GetRow()->screenchar(col)
6868
6869screenchars({row}, {col}) *screenchars()*
6870 The result is a |List| of Numbers. The first number is the same
6871 as what |screenchar()| returns. Further numbers are
6872 composing characters on top of the base character.
6873 This is mainly to be used for testing.
6874 Returns an empty List when row or col is out of range.
6875
6876 Can also be used as a |method|: >
6877 GetRow()->screenchars(col)
6878
6879screencol() *screencol()*
6880 The result is a Number, which is the current screen column of
6881 the cursor. The leftmost column has number 1.
6882 This function is mainly used for testing.
6883
6884 Note: Always returns the current screen column, thus if used
6885 in a command (e.g. ":echo screencol()") it will return the
6886 column inside the command line, which is 1 when the command is
6887 executed. To get the cursor position in the file use one of
6888 the following mappings: >
6889 nnoremap <expr> GG ":echom ".screencol()."\n"
6890 nnoremap <silent> GG :echom screencol()<CR>
6891 nnoremap GG <Cmd>echom screencol()<CR>
6892<
6893screenpos({winid}, {lnum}, {col}) *screenpos()*
6894 The result is a Dict with the screen position of the text
6895 character in window {winid} at buffer line {lnum} and column
6896 {col}. {col} is a one-based byte index.
6897 The Dict has these members:
6898 row screen row
6899 col first screen column
6900 endcol last screen column
6901 curscol cursor screen column
6902 If the specified position is not visible, all values are zero.
6903 The "endcol" value differs from "col" when the character
6904 occupies more than one screen cell. E.g. for a Tab "col" can
6905 be 1 and "endcol" can be 8.
6906 The "curscol" value is where the cursor would be placed. For
6907 a Tab it would be the same as "endcol", while for a double
6908 width character it would be the same as "col".
6909 The |conceal| feature is ignored here, the column numbers are
6910 as if 'conceallevel' is zero. You can set the cursor to the
6911 right position and use |screencol()| to get the value with
6912 |conceal| taken into account.
6913
6914 Can also be used as a |method|: >
6915 GetWinid()->screenpos(lnum, col)
6916
6917screenrow() *screenrow()*
6918 The result is a Number, which is the current screen row of the
6919 cursor. The top line has number one.
6920 This function is mainly used for testing.
6921 Alternatively you can use |winline()|.
6922
6923 Note: Same restrictions as with |screencol()|.
6924
6925screenstring({row}, {col}) *screenstring()*
6926 The result is a String that contains the base character and
6927 any composing characters at position [row, col] on the screen.
6928 This is like |screenchars()| but returning a String with the
6929 characters.
6930 This is mainly to be used for testing.
6931 Returns an empty String when row or col is out of range.
6932
6933 Can also be used as a |method|: >
6934 GetRow()->screenstring(col)
6935<
6936 *search()*
6937search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
6938 Search for regexp pattern {pattern}. The search starts at the
6939 cursor position (you can use |cursor()| to set it).
6940
6941 When a match has been found its line number is returned.
6942 If there is no match a 0 is returned and the cursor doesn't
6943 move. No error message is given.
6944
6945 {flags} is a String, which can contain these character flags:
6946 'b' search Backward instead of forward
6947 'c' accept a match at the Cursor position
6948 'e' move to the End of the match
6949 'n' do Not move the cursor
6950 'p' return number of matching sub-Pattern (see below)
6951 's' Set the ' mark at the previous location of the cursor
6952 'w' Wrap around the end of the file
6953 'W' don't Wrap around the end of the file
6954 'z' start searching at the cursor column instead of zero
6955 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
6956
6957 If the 's' flag is supplied, the ' mark is set, only if the
6958 cursor is moved. The 's' flag cannot be combined with the 'n'
6959 flag.
6960
6961 'ignorecase', 'smartcase' and 'magic' are used.
6962
6963 When the 'z' flag is not given, forward searching always
6964 starts in column zero and then matches before the cursor are
6965 skipped. When the 'c' flag is present in 'cpo' the next
6966 search starts after the match. Without the 'c' flag the next
6967 search starts one column further. This matters for
6968 overlapping matches.
6969 When searching backwards and the 'z' flag is given then the
6970 search starts in column zero, thus no match in the current
6971 line will be found (unless wrapping around the end of the
6972 file).
6973
6974 When the {stopline} argument is given then the search stops
6975 after searching this line. This is useful to restrict the
6976 search to a range of lines. Examples: >
6977 let match = search('(', 'b', line("w0"))
6978 let end = search('END', '', line("w$"))
6979< When {stopline} is used and it is not zero this also implies
6980 that the search does not wrap around the end of the file.
6981 A zero value is equal to not giving the argument.
6982
6983 When the {timeout} argument is given the search stops when
6984 more than this many milliseconds have passed. Thus when
6985 {timeout} is 500 the search stops after half a second.
6986 The value must not be negative. A zero value is like not
6987 giving the argument.
6988 {only available when compiled with the |+reltime| feature}
6989
6990 If the {skip} expression is given it is evaluated with the
6991 cursor positioned on the start of a match. If it evaluates to
6992 non-zero this match is skipped. This can be used, for
6993 example, to skip a match in a comment or a string.
6994 {skip} can be a string, which is evaluated as an expression, a
6995 function reference or a lambda.
6996 When {skip} is omitted or empty, every match is accepted.
6997 When evaluating {skip} causes an error the search is aborted
6998 and -1 returned.
6999 *search()-sub-match*
7000 With the 'p' flag the returned value is one more than the
7001 first sub-match in \(\). One if none of them matched but the
7002 whole pattern did match.
7003 To get the column number too use |searchpos()|.
7004
7005 The cursor will be positioned at the match, unless the 'n'
7006 flag is used.
7007
7008 Example (goes over all files in the argument list): >
7009 :let n = 1
7010 :while n <= argc() " loop over all files in arglist
7011 : exe "argument " . n
7012 : " start at the last char in the file and wrap for the
7013 : " first search to find match at start of file
7014 : normal G$
7015 : let flags = "w"
7016 : while search("foo", flags) > 0
7017 : s/foo/bar/g
7018 : let flags = "W"
7019 : endwhile
7020 : update " write the file if modified
7021 : let n = n + 1
7022 :endwhile
7023<
7024 Example for using some flags: >
7025 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7026< This will search for the keywords "if", "else", and "endif"
7027 under or after the cursor. Because of the 'p' flag, it
7028 returns 1, 2, or 3 depending on which keyword is found, or 0
7029 if the search fails. With the cursor on the first word of the
7030 line:
7031 if (foo == 0) | let foo = foo + 1 | endif ~
7032 the function returns 1. Without the 'c' flag, the function
7033 finds the "endif" and returns 3. The same thing happens
7034 without the 'e' flag if the cursor is on the "f" of "if".
7035 The 'n' flag tells the function not to move the cursor.
7036
7037 Can also be used as a |method|: >
7038 GetPattern()->search()
7039
7040searchcount([{options}]) *searchcount()*
7041 Get or update the last search count, like what is displayed
7042 without the "S" flag in 'shortmess'. This works even if
7043 'shortmess' does contain the "S" flag.
7044
7045 This returns a |Dictionary|. The dictionary is empty if the
7046 previous pattern was not set and "pattern" was not specified.
7047
7048 key type meaning ~
7049 current |Number| current position of match;
7050 0 if the cursor position is
7051 before the first match
7052 exact_match |Boolean| 1 if "current" is matched on
7053 "pos", otherwise 0
7054 total |Number| total count of matches found
7055 incomplete |Number| 0: search was fully completed
7056 1: recomputing was timed out
7057 2: max count exceeded
7058
7059 For {options} see further down.
7060
7061 To get the last search count when |n| or |N| was pressed, call
7062 this function with `recompute: 0` . This sometimes returns
7063 wrong information because |n| and |N|'s maximum count is 99.
7064 If it exceeded 99 the result must be max count + 1 (100). If
7065 you want to get correct information, specify `recompute: 1`: >
7066
7067 " result == maxcount + 1 (100) when many matches
7068 let result = searchcount(#{recompute: 0})
7069
7070 " Below returns correct result (recompute defaults
7071 " to 1)
7072 let result = searchcount()
7073<
7074 The function is useful to add the count to |statusline|: >
7075 function! LastSearchCount() abort
7076 let result = searchcount(#{recompute: 0})
7077 if empty(result)
7078 return ''
7079 endif
7080 if result.incomplete ==# 1 " timed out
7081 return printf(' /%s [?/??]', @/)
7082 elseif result.incomplete ==# 2 " max count exceeded
7083 if result.total > result.maxcount &&
7084 \ result.current > result.maxcount
7085 return printf(' /%s [>%d/>%d]', @/,
7086 \ result.current, result.total)
7087 elseif result.total > result.maxcount
7088 return printf(' /%s [%d/>%d]', @/,
7089 \ result.current, result.total)
7090 endif
7091 endif
7092 return printf(' /%s [%d/%d]', @/,
7093 \ result.current, result.total)
7094 endfunction
7095 let &statusline .= '%{LastSearchCount()}'
7096
7097 " Or if you want to show the count only when
7098 " 'hlsearch' was on
7099 " let &statusline .=
7100 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
7101<
7102 You can also update the search count, which can be useful in a
7103 |CursorMoved| or |CursorMovedI| autocommand: >
7104
7105 autocmd CursorMoved,CursorMovedI *
7106 \ let s:searchcount_timer = timer_start(
7107 \ 200, function('s:update_searchcount'))
7108 function! s:update_searchcount(timer) abort
7109 if a:timer ==# s:searchcount_timer
7110 call searchcount(#{
7111 \ recompute: 1, maxcount: 0, timeout: 100})
7112 redrawstatus
7113 endif
7114 endfunction
7115<
7116 This can also be used to count matched texts with specified
7117 pattern in the current buffer using "pattern": >
7118
7119 " Count '\<foo\>' in this buffer
7120 " (Note that it also updates search count)
7121 let result = searchcount(#{pattern: '\<foo\>'})
7122
7123 " To restore old search count by old pattern,
7124 " search again
7125 call searchcount()
7126<
7127 {options} must be a |Dictionary|. It can contain:
7128 key type meaning ~
7129 recompute |Boolean| if |TRUE|, recompute the count
7130 like |n| or |N| was executed.
7131 otherwise returns the last
7132 computed result (when |n| or
7133 |N| was used when "S" is not
7134 in 'shortmess', or this
7135 function was called).
7136 (default: |TRUE|)
7137 pattern |String| recompute if this was given
7138 and different with |@/|.
7139 this works as same as the
7140 below command is executed
7141 before calling this function >
7142 let @/ = pattern
7143< (default: |@/|)
7144 timeout |Number| 0 or negative number is no
7145 timeout. timeout milliseconds
7146 for recomputing the result
7147 (default: 0)
7148 maxcount |Number| 0 or negative number is no
7149 limit. max count of matched
7150 text while recomputing the
7151 result. if search exceeded
7152 total count, "total" value
7153 becomes `maxcount + 1`
7154 (default: 99)
7155 pos |List| `[lnum, col, off]` value
7156 when recomputing the result.
7157 this changes "current" result
7158 value. see |cursor()|,
7159 |getpos()|
7160 (default: cursor's position)
7161
7162 Can also be used as a |method|: >
7163 GetSearchOpts()->searchcount()
7164<
7165searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
7166 Search for the declaration of {name}.
7167
7168 With a non-zero {global} argument it works like |gD|, find
7169 first match in the file. Otherwise it works like |gd|, find
7170 first match in the function.
7171
7172 With a non-zero {thisblock} argument matches in a {} block
7173 that ends before the cursor position are ignored. Avoids
7174 finding variable declarations only valid in another scope.
7175
7176 Moves the cursor to the found match.
7177 Returns zero for success, non-zero for failure.
7178 Example: >
7179 if searchdecl('myvar') == 0
7180 echo getline('.')
7181 endif
7182<
7183 Can also be used as a |method|: >
7184 GetName()->searchdecl()
7185<
7186 *searchpair()*
7187searchpair({start}, {middle}, {end} [, {flags} [, {skip}
7188 [, {stopline} [, {timeout}]]]])
7189 Search for the match of a nested start-end pair. This can be
7190 used to find the "endif" that matches an "if", while other
7191 if/endif pairs in between are ignored.
7192 The search starts at the cursor. The default is to search
7193 forward, include 'b' in {flags} to search backward.
7194 If a match is found, the cursor is positioned at it and the
7195 line number is returned. If no match is found 0 or -1 is
7196 returned and the cursor doesn't move. No error message is
7197 given.
7198
7199 {start}, {middle} and {end} are patterns, see |pattern|. They
7200 must not contain \( \) pairs. Use of \%( \) is allowed. When
7201 {middle} is not empty, it is found when searching from either
7202 direction, but only when not in a nested start-end pair. A
7203 typical use is: >
7204 searchpair('\<if\>', '\<else\>', '\<endif\>')
7205< By leaving {middle} empty the "else" is skipped.
7206
7207 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
7208 |search()|. Additionally:
7209 'r' Repeat until no more matches found; will find the
7210 outer pair. Implies the 'W' flag.
7211 'm' Return number of matches instead of line number with
7212 the match; will be > 1 when 'r' is used.
7213 Note: it's nearly always a good idea to use the 'W' flag, to
7214 avoid wrapping around the end of the file.
7215
7216 When a match for {start}, {middle} or {end} is found, the
7217 {skip} expression is evaluated with the cursor positioned on
7218 the start of the match. It should return non-zero if this
7219 match is to be skipped. E.g., because it is inside a comment
7220 or a string.
7221 When {skip} is omitted or empty, every match is accepted.
7222 When evaluating {skip} causes an error the search is aborted
7223 and -1 returned.
7224 {skip} can be a string, a lambda, a funcref or a partial.
7225 Anything else makes the function fail.
7226 In a `:def` function when the {skip} argument is a string
7227 constant it is compiled into instructions.
7228
7229 For {stopline} and {timeout} see |search()|.
7230
7231 The value of 'ignorecase' is used. 'magic' is ignored, the
7232 patterns are used like it's on.
7233
7234 The search starts exactly at the cursor. A match with
7235 {start}, {middle} or {end} at the next character, in the
7236 direction of searching, is the first one found. Example: >
7237 if 1
7238 if 2
7239 endif 2
7240 endif 1
7241< When starting at the "if 2", with the cursor on the "i", and
7242 searching forwards, the "endif 2" is found. When starting on
7243 the character just before the "if 2", the "endif 1" will be
7244 found. That's because the "if 2" will be found first, and
7245 then this is considered to be a nested if/endif from "if 2" to
7246 "endif 2".
7247 When searching backwards and {end} is more than one character,
7248 it may be useful to put "\zs" at the end of the pattern, so
7249 that when the cursor is inside a match with the end it finds
7250 the matching start.
7251
7252 Example, to find the "endif" command in a Vim script: >
7253
7254 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
7255 \ 'getline(".") =~ "^\\s*\""')
7256
7257< The cursor must be at or after the "if" for which a match is
7258 to be found. Note that single-quote strings are used to avoid
7259 having to double the backslashes. The skip expression only
7260 catches comments at the start of a line, not after a command.
7261 Also, a word "en" or "if" halfway a line is considered a
7262 match.
7263 Another example, to search for the matching "{" of a "}": >
7264
7265 :echo searchpair('{', '', '}', 'bW')
7266
7267< This works when the cursor is at or before the "}" for which a
7268 match is to be found. To reject matches that syntax
7269 highlighting recognized as strings: >
7270
7271 :echo searchpair('{', '', '}', 'bW',
7272 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
7273<
7274 *searchpairpos()*
7275searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
7276 [, {stopline} [, {timeout}]]]])
7277 Same as |searchpair()|, but returns a |List| with the line and
7278 column position of the match. The first element of the |List|
7279 is the line number and the second element is the byte index of
7280 the column position of the match. If no match is found,
7281 returns [0, 0]. >
7282
7283 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
7284<
7285 See |match-parens| for a bigger and more useful example.
7286
7287 *searchpos()*
7288searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7289 Same as |search()|, but returns a |List| with the line and
7290 column position of the match. The first element of the |List|
7291 is the line number and the second element is the byte index of
7292 the column position of the match. If no match is found,
7293 returns [0, 0].
7294 Example: >
7295 :let [lnum, col] = searchpos('mypattern', 'n')
7296
7297< When the 'p' flag is given then there is an extra item with
7298 the sub-pattern match number |search()-sub-match|. Example: >
7299 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
7300< In this example "submatch" is 2 when a lowercase letter is
7301 found |/\l|, 3 when an uppercase letter is found |/\u|.
7302
7303 Can also be used as a |method|: >
7304 GetPattern()->searchpos()
7305
7306server2client({clientid}, {string}) *server2client()*
7307 Send a reply string to {clientid}. The most recent {clientid}
7308 that sent a string can be retrieved with expand("<client>").
7309 {only available when compiled with the |+clientserver| feature}
7310 Returns zero for success, -1 for failure.
7311 Note:
7312 This id has to be stored before the next command can be
7313 received. I.e. before returning from the received command and
7314 before calling any commands that waits for input.
7315 See also |clientserver|.
7316 Example: >
7317 :echo server2client(expand("<client>"), "HELLO")
7318
7319< Can also be used as a |method|: >
7320 GetClientId()->server2client(string)
7321<
7322serverlist() *serverlist()*
7323 Return a list of available server names, one per line.
7324 When there are no servers or the information is not available
7325 an empty string is returned. See also |clientserver|.
7326 {only available when compiled with the |+clientserver| feature}
7327 Example: >
7328 :echo serverlist()
7329<
7330setbufline({buf}, {lnum}, {text}) *setbufline()*
7331 Set line {lnum} to {text} in buffer {buf}. This works like
7332 |setline()| for the specified buffer.
7333
7334 This function works only for loaded buffers. First call
7335 |bufload()| if needed.
7336
7337 To insert lines use |appendbufline()|.
7338 Any text properties in {lnum} are cleared.
7339
7340 {text} can be a string to set one line, or a list of strings
7341 to set multiple lines. If the list extends below the last
7342 line then those lines are added.
7343
7344 For the use of {buf}, see |bufname()| above.
7345
7346 {lnum} is used like with |setline()|.
7347 Use "$" to refer to the last line in buffer {buf}.
7348 When {lnum} is just below the last line the {text} will be
7349 added below the last line.
7350
7351 When {buf} is not a valid buffer, the buffer is not loaded or
7352 {lnum} is not valid then 1 is returned. In |Vim9| script an
7353 error is given.
7354 On success 0 is returned.
7355
7356 Can also be used as a |method|, the base is passed as the
7357 third argument: >
7358 GetText()->setbufline(buf, lnum)
7359
7360setbufvar({buf}, {varname}, {val}) *setbufvar()*
7361 Set option or local variable {varname} in buffer {buf} to
7362 {val}.
7363 This also works for a global or local window option, but it
7364 doesn't work for a global or local window variable.
7365 For a local window option the global value is unchanged.
7366 For the use of {buf}, see |bufname()| above.
7367 The {varname} argument is a string.
7368 Note that the variable name without "b:" must be used.
7369 Examples: >
7370 :call setbufvar(1, "&mod", 1)
7371 :call setbufvar("todo", "myvar", "foobar")
7372< This function is not available in the |sandbox|.
7373
7374 Can also be used as a |method|, the base is passed as the
7375 third argument: >
7376 GetValue()->setbufvar(buf, varname)
7377
7378
7379setcellwidths({list}) *setcellwidths()*
7380 Specify overrides for cell widths of character ranges. This
7381 tells Vim how wide characters are, counted in screen cells.
7382 This overrides 'ambiwidth'. Example: >
7383 setcellwidths([[0xad, 0xad, 1],
7384 \ [0x2194, 0x2199, 2]])
7385
7386< *E1109* *E1110* *E1111* *E1112* *E1113*
7387 The {list} argument is a list of lists with each three
7388 numbers. These three numbers are [low, high, width]. "low"
7389 and "high" can be the same, in which case this refers to one
7390 character. Otherwise it is the range of characters from "low"
7391 to "high" (inclusive). "width" is either 1 or 2, indicating
7392 the character width in screen cells.
7393 An error is given if the argument is invalid, also when a
7394 range overlaps with another.
7395 Only characters with value 0x100 and higher can be used.
7396
7397 If the new value causes 'fillchars' or 'listchars' to become
7398 invalid it is rejected and an error is given.
7399
7400 To clear the overrides pass an empty list: >
7401 setcellwidths([]);
7402< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
7403 the effect for known emoji characters.
7404
7405setcharpos({expr}, {list}) *setcharpos()*
7406 Same as |setpos()| but uses the specified column number as the
7407 character index instead of the byte index in the line.
7408
7409 Example:
7410 With the text "여보세요" in line 8: >
7411 call setcharpos('.', [0, 8, 4, 0])
7412< positions the cursor on the fourth character '요'. >
7413 call setpos('.', [0, 8, 4, 0])
7414< positions the cursor on the second character '보'.
7415
7416 Can also be used as a |method|: >
7417 GetPosition()->setcharpos('.')
7418
7419setcharsearch({dict}) *setcharsearch()*
7420 Set the current character search information to {dict},
7421 which contains one or more of the following entries:
7422
7423 char character which will be used for a subsequent
7424 |,| or |;| command; an empty string clears the
7425 character search
7426 forward direction of character search; 1 for forward,
7427 0 for backward
7428 until type of character search; 1 for a |t| or |T|
7429 character search, 0 for an |f| or |F|
7430 character search
7431
7432 This can be useful to save/restore a user's character search
7433 from a script: >
7434 :let prevsearch = getcharsearch()
7435 :" Perform a command which clobbers user's search
7436 :call setcharsearch(prevsearch)
7437< Also see |getcharsearch()|.
7438
7439 Can also be used as a |method|: >
7440 SavedSearch()->setcharsearch()
7441
7442setcmdpos({pos}) *setcmdpos()*
7443 Set the cursor position in the command line to byte position
7444 {pos}. The first position is 1.
7445 Use |getcmdpos()| to obtain the current position.
7446 Only works while editing the command line, thus you must use
7447 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
7448 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
7449 set after the command line is set to the expression. For
7450 |c_CTRL-R_=| it is set after evaluating the expression but
7451 before inserting the resulting text.
7452 When the number is too big the cursor is put at the end of the
7453 line. A number smaller than one has undefined results.
7454 Returns FALSE when successful, TRUE when not editing the
7455 command line.
7456
7457 Can also be used as a |method|: >
7458 GetPos()->setcmdpos()
7459
7460setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
7461setcursorcharpos({list})
7462 Same as |cursor()| but uses the specified column number as the
7463 character index instead of the byte index in the line.
7464
7465 Example:
7466 With the text "여보세요" in line 4: >
7467 call setcursorcharpos(4, 3)
7468< positions the cursor on the third character '세'. >
7469 call cursor(4, 3)
7470< positions the cursor on the first character '여'.
7471
7472 Can also be used as a |method|: >
7473 GetCursorPos()->setcursorcharpos()
7474
7475
7476setenv({name}, {val}) *setenv()*
7477 Set environment variable {name} to {val}. Example: >
7478 call setenv('HOME', '/home/myhome')
7479
7480< When {val} is |v:null| the environment variable is deleted.
7481 See also |expr-env|.
7482
7483 Can also be used as a |method|, the base is passed as the
7484 second argument: >
7485 GetPath()->setenv('PATH')
7486
7487setfperm({fname}, {mode}) *setfperm()* *chmod*
7488 Set the file permissions for {fname} to {mode}.
7489 {mode} must be a string with 9 characters. It is of the form
7490 "rwxrwxrwx", where each group of "rwx" flags represent, in
7491 turn, the permissions of the owner of the file, the group the
7492 file belongs to, and other users. A '-' character means the
7493 permission is off, any other character means on. Multi-byte
7494 characters are not supported.
7495
7496 For example "rw-r-----" means read-write for the user,
7497 readable by the group, not accessible by others. "xx-x-----"
7498 would do the same thing.
7499
7500 Returns non-zero for success, zero for failure.
7501
7502 Can also be used as a |method|: >
7503 GetFilename()->setfperm(mode)
7504<
7505 To read permissions see |getfperm()|.
7506
7507
7508setline({lnum}, {text}) *setline()*
7509 Set line {lnum} of the current buffer to {text}. To insert
7510 lines use |append()|. To set lines in another buffer use
7511 |setbufline()|. Any text properties in {lnum} are cleared.
7512
7513 {lnum} is used like with |getline()|.
7514 When {lnum} is just below the last line the {text} will be
7515 added below the last line.
7516 {text} can be any type or a List of any type, each item is
7517 converted to a String.
7518
7519 If this succeeds, FALSE is returned. If this fails (most likely
7520 because {lnum} is invalid) TRUE is returned.
7521 In |Vim9| script an error is given if {lnum} is invalid.
7522
7523 Example: >
7524 :call setline(5, strftime("%c"))
7525
7526< When {text} is a |List| then line {lnum} and following lines
7527 will be set to the items in the list. Example: >
7528 :call setline(5, ['aaa', 'bbb', 'ccc'])
7529< This is equivalent to: >
7530 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
7531 : call setline(n, l)
7532 :endfor
7533
7534< Note: The '[ and '] marks are not set.
7535
7536 Can also be used as a |method|, the base is passed as the
7537 second argument: >
7538 GetText()->setline(lnum)
7539
7540setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
7541 Create or replace or add to the location list for window {nr}.
7542 {nr} can be the window number or the |window-ID|.
7543 When {nr} is zero the current window is used.
7544
7545 For a location list window, the displayed location list is
7546 modified. For an invalid window number {nr}, -1 is returned.
7547 Otherwise, same as |setqflist()|.
7548 Also see |location-list|.
7549
7550 For {action} see |setqflist-action|.
7551
7552 If the optional {what} dictionary argument is supplied, then
7553 only the items listed in {what} are set. Refer to |setqflist()|
7554 for the list of supported keys in {what}.
7555
7556 Can also be used as a |method|, the base is passed as the
7557 second argument: >
7558 GetLoclist()->setloclist(winnr)
7559
7560setmatches({list} [, {win}]) *setmatches()*
7561 Restores a list of matches saved by |getmatches()| for the
7562 current window. Returns 0 if successful, otherwise -1. All
7563 current matches are cleared before the list is restored. See
7564 example for |getmatches()|.
7565 If {win} is specified, use the window with this number or
7566 window ID instead of the current window.
7567
7568 Can also be used as a |method|: >
7569 GetMatches()->setmatches()
7570<
7571 *setpos()*
7572setpos({expr}, {list})
7573 Set the position for String {expr}. Possible values:
7574 . the cursor
7575 'x mark x
7576
7577 {list} must be a |List| with four or five numbers:
7578 [bufnum, lnum, col, off]
7579 [bufnum, lnum, col, off, curswant]
7580
7581 "bufnum" is the buffer number. Zero can be used for the
7582 current buffer. When setting an uppercase mark "bufnum" is
7583 used for the mark position. For other marks it specifies the
7584 buffer to set the mark in. You can use the |bufnr()| function
7585 to turn a file name into a buffer number.
7586 For setting the cursor and the ' mark "bufnum" is ignored,
7587 since these are associated with a window, not a buffer.
7588 Does not change the jumplist.
7589
7590 "lnum" and "col" are the position in the buffer. The first
7591 column is 1. Use a zero "lnum" to delete a mark. If "col" is
7592 smaller than 1 then 1 is used. To use the character count
7593 instead of the byte count, use |setcharpos()|.
7594
7595 The "off" number is only used when 'virtualedit' is set. Then
7596 it is the offset in screen columns from the start of the
7597 character. E.g., a position within a <Tab> or after the last
7598 character.
7599
7600 The "curswant" number is only used when setting the cursor
7601 position. It sets the preferred column for when moving the
7602 cursor vertically. When the "curswant" number is missing the
7603 preferred column is not set. When it is present and setting a
7604 mark position it is not used.
7605
7606 Note that for '< and '> changing the line number may result in
7607 the marks to be effectively be swapped, so that '< is always
7608 before '>.
7609
7610 Returns 0 when the position could be set, -1 otherwise.
7611 An error message is given if {expr} is invalid.
7612
7613 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
7614
7615 This does not restore the preferred column for moving
7616 vertically; if you set the cursor position with this, |j| and
7617 |k| motions will jump to previous columns! Use |cursor()| to
7618 also set the preferred column. Also see the "curswant" key in
7619 |winrestview()|.
7620
7621 Can also be used as a |method|: >
7622 GetPosition()->setpos('.')
7623
7624setqflist({list} [, {action} [, {what}]]) *setqflist()*
7625 Create or replace or add to the quickfix list.
7626
7627 If the optional {what} dictionary argument is supplied, then
7628 only the items listed in {what} are set. The first {list}
7629 argument is ignored. See below for the supported items in
7630 {what}.
7631 *setqflist-what*
7632 When {what} is not present, the items in {list} are used. Each
7633 item must be a dictionary. Non-dictionary items in {list} are
7634 ignored. Each dictionary item can contain the following
7635 entries:
7636
7637 bufnr buffer number; must be the number of a valid
7638 buffer
7639 filename name of a file; only used when "bufnr" is not
7640 present or it is invalid.
7641 module name of a module; if given it will be used in
7642 quickfix error window instead of the filename.
7643 lnum line number in the file
7644 pattern search pattern used to locate the error
7645 col column number
7646 vcol when non-zero: "col" is visual column
7647 when zero: "col" is byte index
7648 nr error number
7649 text description of the error
7650 type single-character error type, 'E', 'W', etc.
7651 valid recognized error message
7652
7653 The "col", "vcol", "nr", "type" and "text" entries are
7654 optional. Either "lnum" or "pattern" entry can be used to
7655 locate a matching error line.
7656 If the "filename" and "bufnr" entries are not present or
7657 neither the "lnum" or "pattern" entries are present, then the
7658 item will not be handled as an error line.
7659 If both "pattern" and "lnum" are present then "pattern" will
7660 be used.
7661 If the "valid" entry is not supplied, then the valid flag is
7662 set when "bufnr" is a valid buffer or "filename" exists.
7663 If you supply an empty {list}, the quickfix list will be
7664 cleared.
7665 Note that the list is not exactly the same as what
7666 |getqflist()| returns.
7667
7668 {action} values: *setqflist-action* *E927*
7669 'a' The items from {list} are added to the existing
7670 quickfix list. If there is no existing list, then a
7671 new list is created.
7672
7673 'r' The items from the current quickfix list are replaced
7674 with the items from {list}. This can also be used to
7675 clear the list: >
7676 :call setqflist([], 'r')
7677<
7678 'f' All the quickfix lists in the quickfix stack are
7679 freed.
7680
7681 If {action} is not present or is set to ' ', then a new list
7682 is created. The new quickfix list is added after the current
7683 quickfix list in the stack and all the following lists are
7684 freed. To add a new quickfix list at the end of the stack,
7685 set "nr" in {what} to "$".
7686
7687 The following items can be specified in dictionary {what}:
7688 context quickfix list context. See |quickfix-context|
7689 efm errorformat to use when parsing text from
7690 "lines". If this is not present, then the
7691 'errorformat' option value is used.
7692 See |quickfix-parse|
7693 id quickfix list identifier |quickfix-ID|
7694 idx index of the current entry in the quickfix
7695 list specified by 'id' or 'nr'. If set to '$',
7696 then the last entry in the list is set as the
7697 current entry. See |quickfix-index|
7698 items list of quickfix entries. Same as the {list}
7699 argument.
7700 lines use 'errorformat' to parse a list of lines and
7701 add the resulting entries to the quickfix list
7702 {nr} or {id}. Only a |List| value is supported.
7703 See |quickfix-parse|
7704 nr list number in the quickfix stack; zero
7705 means the current quickfix list and "$" means
7706 the last quickfix list.
7707 quickfixtextfunc
7708 function to get the text to display in the
7709 quickfix window. The value can be the name of
7710 a function or a funcref or a lambda. Refer to
7711 |quickfix-window-function| for an explanation
7712 of how to write the function and an example.
7713 title quickfix list title text. See |quickfix-title|
7714 Unsupported keys in {what} are ignored.
7715 If the "nr" item is not present, then the current quickfix list
7716 is modified. When creating a new quickfix list, "nr" can be
7717 set to a value one greater than the quickfix stack size.
7718 When modifying a quickfix list, to guarantee that the correct
7719 list is modified, "id" should be used instead of "nr" to
7720 specify the list.
7721
7722 Examples (See also |setqflist-examples|): >
7723 :call setqflist([], 'r', {'title': 'My search'})
7724 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
7725 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
7726<
7727 Returns zero for success, -1 for failure.
7728
7729 This function can be used to create a quickfix list
7730 independent of the 'errorformat' setting. Use a command like
7731 `:cc 1` to jump to the first position.
7732
7733 Can also be used as a |method|, the base is passed as the
7734 second argument: >
7735 GetErrorlist()->setqflist()
7736<
7737 *setreg()*
7738setreg({regname}, {value} [, {options}])
7739 Set the register {regname} to {value}.
7740 If {regname} is "" or "@", the unnamed register '"' is used.
7741 The {regname} argument is a string. In |Vim9-script|
7742 {regname} must be one character.
7743
7744 {value} may be any value returned by |getreg()| or
7745 |getreginfo()|, including a |List| or |Dict|.
7746 If {options} contains "a" or {regname} is upper case,
7747 then the value is appended.
7748
7749 {options} can also contain a register type specification:
7750 "c" or "v" |characterwise| mode
7751 "l" or "V" |linewise| mode
7752 "b" or "<CTRL-V>" |blockwise-visual| mode
7753 If a number immediately follows "b" or "<CTRL-V>" then this is
7754 used as the width of the selection - if it is not specified
7755 then the width of the block is set to the number of characters
7756 in the longest line (counting a <Tab> as 1 character).
7757
7758 If {options} contains no register settings, then the default
7759 is to use character mode unless {value} ends in a <NL> for
7760 string {value} and linewise mode for list {value}. Blockwise
7761 mode is never selected automatically.
7762 Returns zero for success, non-zero for failure.
7763
7764 *E883*
7765 Note: you may not use |List| containing more than one item to
7766 set search and expression registers. Lists containing no
7767 items act like empty strings.
7768
7769 Examples: >
7770 :call setreg(v:register, @*)
7771 :call setreg('*', @%, 'ac')
7772 :call setreg('a', "1\n2\n3", 'b5')
7773 :call setreg('"', { 'points_to': 'a'})
7774
7775< This example shows using the functions to save and restore a
7776 register: >
7777 :let var_a = getreginfo()
7778 :call setreg('a', var_a)
7779< or: >
7780 :let var_a = getreg('a', 1, 1)
7781 :let var_amode = getregtype('a')
7782 ....
7783 :call setreg('a', var_a, var_amode)
7784< Note: you may not reliably restore register value
7785 without using the third argument to |getreg()| as without it
7786 newlines are represented as newlines AND Nul bytes are
7787 represented as newlines as well, see |NL-used-for-Nul|.
7788
7789 You can also change the type of a register by appending
7790 nothing: >
7791 :call setreg('a', '', 'al')
7792
7793< Can also be used as a |method|, the base is passed as the
7794 second argument: >
7795 GetText()->setreg('a')
7796
7797settabvar({tabnr}, {varname}, {val}) *settabvar()*
7798 Set tab-local variable {varname} to {val} in tab page {tabnr}.
7799 |t:var|
7800 The {varname} argument is a string.
7801 Note that autocommands are blocked, side effects may not be
7802 triggered, e.g. when setting 'filetype'.
7803 Note that the variable name without "t:" must be used.
7804 Tabs are numbered starting with one.
7805 This function is not available in the |sandbox|.
7806
7807 Can also be used as a |method|, the base is passed as the
7808 third argument: >
7809 GetValue()->settabvar(tab, name)
7810
7811settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
7812 Set option or local variable {varname} in window {winnr} to
7813 {val}.
7814 Tabs are numbered starting with one. For the current tabpage
7815 use |setwinvar()|.
7816 {winnr} can be the window number or the |window-ID|.
7817 When {winnr} is zero the current window is used.
7818 Note that autocommands are blocked, side effects may not be
7819 triggered, e.g. when setting 'filetype' or 'syntax'.
7820 This also works for a global or local buffer option, but it
7821 doesn't work for a global or local buffer variable.
7822 For a local buffer option the global value is unchanged.
7823 Note that the variable name without "w:" must be used.
7824 Examples: >
7825 :call settabwinvar(1, 1, "&list", 0)
7826 :call settabwinvar(3, 2, "myvar", "foobar")
7827< This function is not available in the |sandbox|.
7828
7829 Can also be used as a |method|, the base is passed as the
7830 fourth argument: >
7831 GetValue()->settabwinvar(tab, winnr, name)
7832
7833settagstack({nr}, {dict} [, {action}]) *settagstack()*
7834 Modify the tag stack of the window {nr} using {dict}.
7835 {nr} can be the window number or the |window-ID|.
7836
7837 For a list of supported items in {dict}, refer to
7838 |gettagstack()|. "curidx" takes effect before changing the tag
7839 stack.
7840 *E962*
7841 How the tag stack is modified depends on the {action}
7842 argument:
7843 - If {action} is not present or is set to 'r', then the tag
7844 stack is replaced.
7845 - If {action} is set to 'a', then new entries from {dict} are
7846 pushed (added) onto the tag stack.
7847 - If {action} is set to 't', then all the entries from the
7848 current entry in the tag stack or "curidx" in {dict} are
7849 removed and then new entries are pushed to the stack.
7850
7851 The current index is set to one after the length of the tag
7852 stack after the modification.
7853
7854 Returns zero for success, -1 for failure.
7855
7856 Examples (for more examples see |tagstack-examples|):
7857 Empty the tag stack of window 3: >
7858 call settagstack(3, {'items' : []})
7859
7860< Save and restore the tag stack: >
7861 let stack = gettagstack(1003)
7862 " do something else
7863 call settagstack(1003, stack)
7864 unlet stack
7865<
7866 Can also be used as a |method|, the base is passed as the
7867 second argument: >
7868 GetStack()->settagstack(winnr)
7869
7870setwinvar({winnr}, {varname}, {val}) *setwinvar()*
7871 Like |settabwinvar()| for the current tab page.
7872 Examples: >
7873 :call setwinvar(1, "&list", 0)
7874 :call setwinvar(2, "myvar", "foobar")
7875
7876< Can also be used as a |method|, the base is passed as the
7877 third argument: >
7878 GetValue()->setwinvar(winnr, name)
7879
7880sha256({string}) *sha256()*
7881 Returns a String with 64 hex characters, which is the SHA256
7882 checksum of {string}.
7883
7884 Can also be used as a |method|: >
7885 GetText()->sha256()
7886
7887< {only available when compiled with the |+cryptv| feature}
7888
7889shellescape({string} [, {special}]) *shellescape()*
7890 Escape {string} for use as a shell command argument.
7891 When the 'shell' contains powershell (MS-Windows) or pwsh
7892 (MS-Windows, Linux, and MacOS) then it will enclose {string}
7893 in single quotes and will double up all internal single
7894 quotes.
7895 On MS-Windows, when 'shellslash' is not set, it will enclose
7896 {string} in double quotes and double all double quotes within
7897 {string}.
7898 Otherwise it will enclose {string} in single quotes and
7899 replace all "'" with "'\''".
7900
7901 When the {special} argument is present and it's a non-zero
7902 Number or a non-empty String (|non-zero-arg|), then special
7903 items such as "!", "%", "#" and "<cword>" will be preceded by
7904 a backslash. This backslash will be removed again by the |:!|
7905 command.
7906
7907 The "!" character will be escaped (again with a |non-zero-arg|
7908 {special}) when 'shell' contains "csh" in the tail. That is
7909 because for csh and tcsh "!" is used for history replacement
7910 even when inside single quotes.
7911
7912 With a |non-zero-arg| {special} the <NL> character is also
7913 escaped. When 'shell' containing "csh" in the tail it's
7914 escaped a second time.
7915
7916 The "\" character will be escaped when 'shell' contains "fish"
7917 in the tail. That is because for fish "\" is used as an escape
7918 character inside single quotes.
7919
7920 Example of use with a |:!| command: >
7921 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
7922< This results in a directory listing for the file under the
7923 cursor. Example of use with |system()|: >
7924 :call system("chmod +w -- " . shellescape(expand("%")))
7925< See also |::S|.
7926
7927 Can also be used as a |method|: >
7928 GetCommand()->shellescape()
7929
7930shiftwidth([{col}]) *shiftwidth()*
7931 Returns the effective value of 'shiftwidth'. This is the
7932 'shiftwidth' value unless it is zero, in which case it is the
7933 'tabstop' value. This function was introduced with patch
7934 7.3.694 in 2012, everybody should have it by now (however it
7935 did not allow for the optional {col} argument until 8.1.542).
7936
7937 When there is one argument {col} this is used as column number
7938 for which to return the 'shiftwidth' value. This matters for the
7939 'vartabstop' feature. If the 'vartabstop' setting is enabled and
7940 no {col} argument is given, column 1 will be assumed.
7941
7942 Can also be used as a |method|: >
7943 GetColumn()->shiftwidth()
7944
7945sign_ functions are documented here: |sign-functions-details|
7946
7947
7948simplify({filename}) *simplify()*
7949 Simplify the file name as much as possible without changing
7950 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
7951 Unix) are not resolved. If the first path component in
7952 {filename} designates the current directory, this will be
7953 valid for the result as well. A trailing path separator is
7954 not removed either. On Unix "//path" is unchanged, but
7955 "///path" is simplified to "/path" (this follows the Posix
7956 standard).
7957 Example: >
7958 simplify("./dir/.././/file/") == "./file/"
7959< Note: The combination "dir/.." is only removed if "dir" is
7960 a searchable directory or does not exist. On Unix, it is also
7961 removed when "dir" is a symbolic link within the same
7962 directory. In order to resolve all the involved symbolic
7963 links before simplifying the path name, use |resolve()|.
7964
7965 Can also be used as a |method|: >
7966 GetName()->simplify()
7967
7968sin({expr}) *sin()*
7969 Return the sine of {expr}, measured in radians, as a |Float|.
7970 {expr} must evaluate to a |Float| or a |Number|.
7971 Examples: >
7972 :echo sin(100)
7973< -0.506366 >
7974 :echo sin(-4.01)
7975< 0.763301
7976
7977 Can also be used as a |method|: >
7978 Compute()->sin()
7979<
7980 {only available when compiled with the |+float| feature}
7981
7982
7983sinh({expr}) *sinh()*
7984 Return the hyperbolic sine of {expr} as a |Float| in the range
7985 [-inf, inf].
7986 {expr} must evaluate to a |Float| or a |Number|.
7987 Examples: >
7988 :echo sinh(0.5)
7989< 0.521095 >
7990 :echo sinh(-0.9)
7991< -1.026517
7992
7993 Can also be used as a |method|: >
7994 Compute()->sinh()
7995<
7996 {only available when compiled with the |+float| feature}
7997
7998
7999slice({expr}, {start} [, {end}]) *slice()*
8000 Similar to using a |slice| "expr[start : end]", but "end" is
8001 used exclusive. And for a string the indexes are used as
8002 character indexes instead of byte indexes, like in
8003 |vim9script|. Also, composing characters are not counted.
8004 When {end} is omitted the slice continues to the last item.
8005 When {end} is -1 the last item is omitted.
8006
8007 Can also be used as a |method|: >
8008 GetList()->slice(offset)
8009
8010
8011sort({list} [, {func} [, {dict}]]) *sort()* *E702*
8012 Sort the items in {list} in-place. Returns {list}.
8013
8014 If you want a list to remain unmodified make a copy first: >
8015 :let sortedlist = sort(copy(mylist))
8016
8017< When {func} is omitted, is empty or zero, then sort() uses the
8018 string representation of each item to sort on. Numbers sort
8019 after Strings, |Lists| after Numbers. For sorting text in the
8020 current buffer use |:sort|.
8021
8022 When {func} is given and it is '1' or 'i' then case is
8023 ignored.
8024
8025 When {func} is given and it is 'l' then the current collation
8026 locale is used for ordering. Implementation details: strcoll()
8027 is used to compare strings. See |:language| check or set the
8028 collation locale. |v:collate| can also be used to check the
8029 current locale. Sorting using the locale typically ignores
8030 case. Example: >
8031 " ö is sorted similarly to o with English locale.
8032 :language collate en_US.UTF8
8033 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8034< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
8035>
8036 " ö is sorted after z with Swedish locale.
8037 :language collate sv_SE.UTF8
8038 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8039< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
8040 This does not work properly on Mac.
8041
8042 When {func} is given and it is 'n' then all items will be
8043 sorted numerical (Implementation detail: this uses the
8044 strtod() function to parse numbers, Strings, Lists, Dicts and
8045 Funcrefs will be considered as being 0).
8046
8047 When {func} is given and it is 'N' then all items will be
8048 sorted numerical. This is like 'n' but a string containing
8049 digits will be used as the number they represent.
8050
8051 When {func} is given and it is 'f' then all items will be
8052 sorted numerical. All values must be a Number or a Float.
8053
8054 When {func} is a |Funcref| or a function name, this function
8055 is called to compare items. The function is invoked with two
8056 items as argument and must return zero if they are equal, 1 or
8057 bigger if the first one sorts after the second one, -1 or
8058 smaller if the first one sorts before the second one.
8059
8060 {dict} is for functions with the "dict" attribute. It will be
8061 used to set the local variable "self". |Dictionary-function|
8062
8063 The sort is stable, items which compare equal (as number or as
8064 string) will keep their relative position. E.g., when sorting
8065 on numbers, text strings will sort next to each other, in the
8066 same order as they were originally.
8067
8068 Can also be used as a |method|: >
8069 mylist->sort()
8070
8071< Also see |uniq()|.
8072
8073 Example: >
8074 func MyCompare(i1, i2)
8075 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8076 endfunc
8077 eval mylist->sort("MyCompare")
8078< A shorter compare version for this specific simple case, which
8079 ignores overflow: >
8080 func MyCompare(i1, i2)
8081 return a:i1 - a:i2
8082 endfunc
8083< For a simple expression you can use a lambda: >
8084 eval mylist->sort({i1, i2 -> i1 - i2})
8085<
8086sound_clear() *sound_clear()*
8087 Stop playing all sounds.
8088
8089 On some Linux systems you may need the libcanberra-pulse
8090 package, otherwise sound may not stop.
8091
8092 {only available when compiled with the |+sound| feature}
8093
8094 *sound_playevent()*
8095sound_playevent({name} [, {callback}])
8096 Play a sound identified by {name}. Which event names are
8097 supported depends on the system. Often the XDG sound names
8098 are used. On Ubuntu they may be found in
8099 /usr/share/sounds/freedesktop/stereo. Example: >
8100 call sound_playevent('bell')
8101< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
8102 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
8103 SystemStart, SystemWelcome, etc.
8104
8105 When {callback} is specified it is invoked when the sound is
8106 finished. The first argument is the sound ID, the second
8107 argument is the status:
8108 0 sound was played to the end
8109 1 sound was interrupted
8110 2 error occurred after sound started
8111 Example: >
8112 func Callback(id, status)
8113 echomsg "sound " .. a:id .. " finished with " .. a:status
8114 endfunc
8115 call sound_playevent('bell', 'Callback')
8116
8117< MS-Windows: {callback} doesn't work for this function.
8118
8119 Returns the sound ID, which can be passed to `sound_stop()`.
8120 Returns zero if the sound could not be played.
8121
8122 Can also be used as a |method|: >
8123 GetSoundName()->sound_playevent()
8124
8125< {only available when compiled with the |+sound| feature}
8126
8127 *sound_playfile()*
8128sound_playfile({path} [, {callback}])
8129 Like `sound_playevent()` but play sound file {path}. {path}
8130 must be a full path. On Ubuntu you may find files to play
8131 with this command: >
8132 :!find /usr/share/sounds -type f | grep -v index.theme
8133
8134< Can also be used as a |method|: >
8135 GetSoundPath()->sound_playfile()
8136
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00008137< There is no error *E538* , but can listen to 538.nl.
8138 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008139
8140
8141sound_stop({id}) *sound_stop()*
8142 Stop playing sound {id}. {id} must be previously returned by
8143 `sound_playevent()` or `sound_playfile()`.
8144
8145 On some Linux systems you may need the libcanberra-pulse
8146 package, otherwise sound may not stop.
8147
8148 On MS-Windows, this does not work for event sound started by
8149 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
8150
8151 Can also be used as a |method|: >
8152 soundid->sound_stop()
8153
8154< {only available when compiled with the |+sound| feature}
8155
8156 *soundfold()*
8157soundfold({word})
8158 Return the sound-folded equivalent of {word}. Uses the first
8159 language in 'spelllang' for the current window that supports
8160 soundfolding. 'spell' must be set. When no sound folding is
8161 possible the {word} is returned unmodified.
8162 This can be used for making spelling suggestions. Note that
8163 the method can be quite slow.
8164
8165 Can also be used as a |method|: >
8166 GetWord()->soundfold()
8167<
8168 *spellbadword()*
8169spellbadword([{sentence}])
8170 Without argument: The result is the badly spelled word under
8171 or after the cursor. The cursor is moved to the start of the
8172 bad word. When no bad word is found in the cursor line the
8173 result is an empty string and the cursor doesn't move.
8174
8175 With argument: The result is the first word in {sentence} that
8176 is badly spelled. If there are no spelling mistakes the
8177 result is an empty string.
8178
8179 The return value is a list with two items:
8180 - The badly spelled word or an empty string.
8181 - The type of the spelling error:
8182 "bad" spelling mistake
8183 "rare" rare word
8184 "local" word only valid in another region
8185 "caps" word should start with Capital
8186 Example: >
8187 echo spellbadword("the quik brown fox")
8188< ['quik', 'bad'] ~
8189
8190 The spelling information for the current window and the value
8191 of 'spelllang' are used.
8192
8193 Can also be used as a |method|: >
8194 GetText()->spellbadword()
8195<
8196 *spellsuggest()*
8197spellsuggest({word} [, {max} [, {capital}]])
8198 Return a |List| with spelling suggestions to replace {word}.
8199 When {max} is given up to this number of suggestions are
8200 returned. Otherwise up to 25 suggestions are returned.
8201
8202 When the {capital} argument is given and it's non-zero only
8203 suggestions with a leading capital will be given. Use this
8204 after a match with 'spellcapcheck'.
8205
8206 {word} can be a badly spelled word followed by other text.
8207 This allows for joining two words that were split. The
8208 suggestions also include the following text, thus you can
8209 replace a line.
8210
8211 {word} may also be a good word. Similar words will then be
8212 returned. {word} itself is not included in the suggestions,
8213 although it may appear capitalized.
8214
8215 The spelling information for the current window is used. The
8216 values of 'spelllang' and 'spellsuggest' are used.
8217
8218 Can also be used as a |method|: >
8219 GetWord()->spellsuggest()
8220
8221split({string} [, {pattern} [, {keepempty}]]) *split()*
8222 Make a |List| out of {string}. When {pattern} is omitted or
8223 empty each white-separated sequence of characters becomes an
8224 item.
8225 Otherwise the string is split where {pattern} matches,
8226 removing the matched characters. 'ignorecase' is not used
8227 here, add \c to ignore case. |/\c|
8228 When the first or last item is empty it is omitted, unless the
8229 {keepempty} argument is given and it's non-zero.
8230 Other empty items are kept when {pattern} matches at least one
8231 character or when {keepempty} is non-zero.
8232 Example: >
8233 :let words = split(getline('.'), '\W\+')
8234< To split a string in individual characters: >
8235 :for c in split(mystring, '\zs')
8236< If you want to keep the separator you can also use '\zs' at
8237 the end of the pattern: >
8238 :echo split('abc:def:ghi', ':\zs')
8239< ['abc:', 'def:', 'ghi'] ~
8240 Splitting a table where the first element can be empty: >
8241 :let items = split(line, ':', 1)
8242< The opposite function is |join()|.
8243
8244 Can also be used as a |method|: >
8245 GetString()->split()
8246
8247sqrt({expr}) *sqrt()*
8248 Return the non-negative square root of Float {expr} as a
8249 |Float|.
8250 {expr} must evaluate to a |Float| or a |Number|. When {expr}
8251 is negative the result is NaN (Not a Number).
8252 Examples: >
8253 :echo sqrt(100)
8254< 10.0 >
8255 :echo sqrt(-4.01)
8256< nan
8257 "nan" may be different, it depends on system libraries.
8258
8259 Can also be used as a |method|: >
8260 Compute()->sqrt()
8261<
8262 {only available when compiled with the |+float| feature}
8263
8264
8265srand([{expr}]) *srand()*
8266 Initialize seed used by |rand()|:
8267 - If {expr} is not given, seed values are initialized by
8268 reading from /dev/urandom, if possible, or using time(NULL)
8269 a.k.a. epoch time otherwise; this only has second accuracy.
8270 - If {expr} is given it must be a Number. It is used to
8271 initialize the seed values. This is useful for testing or
8272 when a predictable sequence is intended.
8273
8274 Examples: >
8275 :let seed = srand()
8276 :let seed = srand(userinput)
8277 :echo rand(seed)
8278
8279state([{what}]) *state()*
8280 Return a string which contains characters indicating the
8281 current state. Mostly useful in callbacks that want to do
8282 work that may not always be safe. Roughly this works like:
8283 - callback uses state() to check if work is safe to do.
8284 Yes: then do it right away.
8285 No: add to work queue and add a |SafeState| and/or
8286 |SafeStateAgain| autocommand (|SafeState| triggers at
8287 toplevel, |SafeStateAgain| triggers after handling
8288 messages and callbacks).
8289 - When SafeState or SafeStateAgain is triggered and executes
8290 your autocommand, check with `state()` if the work can be
8291 done now, and if yes remove it from the queue and execute.
8292 Remove the autocommand if the queue is now empty.
8293 Also see |mode()|.
8294
8295 When {what} is given only characters in this string will be
8296 added. E.g, this checks if the screen has scrolled: >
8297 if state('s') == ''
8298 " screen has not scrolled
8299<
8300 These characters indicate the state, generally indicating that
8301 something is busy:
8302 m halfway a mapping, :normal command, feedkeys() or
8303 stuffed command
8304 o operator pending, e.g. after |d|
8305 a Insert mode autocomplete active
8306 x executing an autocommand
8307 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
8308 ch_readraw() when reading json
8309 S not triggering SafeState or SafeStateAgain, e.g. after
8310 |f| or a count
8311 c callback invoked, including timer (repeats for
8312 recursiveness up to "ccc")
8313 s screen has scrolled for messages
8314
8315str2float({string} [, {quoted}]) *str2float()*
8316 Convert String {string} to a Float. This mostly works the
8317 same as when using a floating point number in an expression,
8318 see |floating-point-format|. But it's a bit more permissive.
8319 E.g., "1e40" is accepted, while in an expression you need to
8320 write "1.0e40". The hexadecimal form "0x123" is also
8321 accepted, but not others, like binary or octal.
8322 When {quoted} is present and non-zero then embedded single
8323 quotes before the dot are ignored, thus "1'000.0" is a
8324 thousand.
8325 Text after the number is silently ignored.
8326 The decimal point is always '.', no matter what the locale is
8327 set to. A comma ends the number: "12,345.67" is converted to
8328 12.0. You can strip out thousands separators with
8329 |substitute()|: >
8330 let f = str2float(substitute(text, ',', '', 'g'))
8331<
8332 Can also be used as a |method|: >
8333 let f = text->substitute(',', '', 'g')->str2float()
8334<
8335 {only available when compiled with the |+float| feature}
8336
8337str2list({string} [, {utf8}]) *str2list()*
8338 Return a list containing the number values which represent
8339 each character in String {string}. Examples: >
8340 str2list(" ") returns [32]
8341 str2list("ABC") returns [65, 66, 67]
8342< |list2str()| does the opposite.
8343
8344 When {utf8} is omitted or zero, the current 'encoding' is used.
8345 When {utf8} is TRUE, always treat the String as UTF-8
8346 characters. With UTF-8 composing characters are handled
8347 properly: >
8348 str2list("á") returns [97, 769]
8349
8350< Can also be used as a |method|: >
8351 GetString()->str2list()
8352
8353
8354str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
8355 Convert string {string} to a number.
8356 {base} is the conversion base, it can be 2, 8, 10 or 16.
8357 When {quoted} is present and non-zero then embedded single
8358 quotes are ignored, thus "1'000'000" is a million.
8359
8360 When {base} is omitted base 10 is used. This also means that
8361 a leading zero doesn't cause octal conversion to be used, as
8362 with the default String to Number conversion. Example: >
8363 let nr = str2nr('0123')
8364<
8365 When {base} is 16 a leading "0x" or "0X" is ignored. With a
8366 different base the result will be zero. Similarly, when
8367 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
8368 {base} is 2 a leading "0b" or "0B" is ignored.
8369 Text after the number is silently ignored.
8370
8371 Can also be used as a |method|: >
8372 GetText()->str2nr()
8373
8374
8375strcharlen({string}) *strcharlen()*
8376 The result is a Number, which is the number of characters
8377 in String {string}. Composing characters are ignored.
8378 |strchars()| can count the number of characters, counting
8379 composing characters separately.
8380
8381 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8382
8383 Can also be used as a |method|: >
8384 GetText()->strcharlen()
8385
8386
8387strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
8388 Like |strpart()| but using character index and length instead
8389 of byte index and length.
8390 When {skipcc} is omitted or zero, composing characters are
8391 counted separately.
8392 When {skipcc} set to 1, Composing characters are ignored,
8393 similar to |slice()|.
8394 When a character index is used where a character does not
8395 exist it is omitted and counted as one character. For
8396 example: >
8397 strcharpart('abc', -1, 2)
8398< results in 'a'.
8399
8400 Can also be used as a |method|: >
8401 GetText()->strcharpart(5)
8402
8403
8404strchars({string} [, {skipcc}]) *strchars()*
8405 The result is a Number, which is the number of characters
8406 in String {string}.
8407 When {skipcc} is omitted or zero, composing characters are
8408 counted separately.
8409 When {skipcc} set to 1, Composing characters are ignored.
8410 |strcharlen()| always does this.
8411
8412 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8413
8414 {skipcc} is only available after 7.4.755. For backward
8415 compatibility, you can define a wrapper function: >
8416 if has("patch-7.4.755")
8417 function s:strchars(str, skipcc)
8418 return strchars(a:str, a:skipcc)
8419 endfunction
8420 else
8421 function s:strchars(str, skipcc)
8422 if a:skipcc
8423 return strlen(substitute(a:str, ".", "x", "g"))
8424 else
8425 return strchars(a:str)
8426 endif
8427 endfunction
8428 endif
8429<
8430 Can also be used as a |method|: >
8431 GetText()->strchars()
8432
8433strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
8434 The result is a Number, which is the number of display cells
8435 String {string} occupies on the screen when it starts at {col}
8436 (first column is zero). When {col} is omitted zero is used.
8437 Otherwise it is the screen column where to start. This
8438 matters for Tab characters.
8439 The option settings of the current window are used. This
8440 matters for anything that's displayed differently, such as
8441 'tabstop' and 'display'.
8442 When {string} contains characters with East Asian Width Class
8443 Ambiguous, this function's return value depends on 'ambiwidth'.
8444 Also see |strlen()|, |strwidth()| and |strchars()|.
8445
8446 Can also be used as a |method|: >
8447 GetText()->strdisplaywidth()
8448
8449strftime({format} [, {time}]) *strftime()*
8450 The result is a String, which is a formatted date and time, as
8451 specified by the {format} string. The given {time} is used,
8452 or the current time if no time is given. The accepted
8453 {format} depends on your system, thus this is not portable!
8454 See the manual page of the C function strftime() for the
8455 format. The maximum length of the result is 80 characters.
8456 See also |localtime()|, |getftime()| and |strptime()|.
8457 The language can be changed with the |:language| command.
8458 Examples: >
8459 :echo strftime("%c") Sun Apr 27 11:49:23 1997
8460 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
8461 :echo strftime("%y%m%d %T") 970427 11:53:55
8462 :echo strftime("%H:%M") 11:55
8463 :echo strftime("%c", getftime("file.c"))
8464 Show mod time of file.c.
8465< Not available on all systems. To check use: >
8466 :if exists("*strftime")
8467
8468< Can also be used as a |method|: >
8469 GetFormat()->strftime()
8470
8471strgetchar({str}, {index}) *strgetchar()*
8472 Get character {index} from {str}. This uses a character
8473 index, not a byte index. Composing characters are considered
8474 separate characters here.
8475 Also see |strcharpart()| and |strchars()|.
8476
8477 Can also be used as a |method|: >
8478 GetText()->strgetchar(5)
8479
8480stridx({haystack}, {needle} [, {start}]) *stridx()*
8481 The result is a Number, which gives the byte index in
8482 {haystack} of the first occurrence of the String {needle}.
8483 If {start} is specified, the search starts at index {start}.
8484 This can be used to find a second match: >
8485 :let colon1 = stridx(line, ":")
8486 :let colon2 = stridx(line, ":", colon1 + 1)
8487< The search is done case-sensitive.
8488 For pattern searches use |match()|.
8489 -1 is returned if the {needle} does not occur in {haystack}.
8490 See also |strridx()|.
8491 Examples: >
8492 :echo stridx("An Example", "Example") 3
8493 :echo stridx("Starting point", "Start") 0
8494 :echo stridx("Starting point", "start") -1
8495< *strstr()* *strchr()*
8496 stridx() works similar to the C function strstr(). When used
8497 with a single character it works similar to strchr().
8498
8499 Can also be used as a |method|: >
8500 GetHaystack()->stridx(needle)
8501<
8502 *string()*
8503string({expr}) Return {expr} converted to a String. If {expr} is a Number,
8504 Float, String, Blob or a composition of them, then the result
8505 can be parsed back with |eval()|.
8506 {expr} type result ~
8507 String 'string' (single quotes are doubled)
8508 Number 123
8509 Float 123.123456 or 1.123456e8
8510 Funcref function('name')
8511 Blob 0z00112233.44556677.8899
8512 List [item, item]
8513 Dictionary {key: value, key: value}
8514
8515 When a |List| or |Dictionary| has a recursive reference it is
8516 replaced by "[...]" or "{...}". Using eval() on the result
8517 will then fail.
8518
8519 Can also be used as a |method|: >
8520 mylist->string()
8521
8522< Also see |strtrans()|.
8523
8524
8525strlen({string}) *strlen()*
8526 The result is a Number, which is the length of the String
8527 {string} in bytes.
8528 If the argument is a Number it is first converted to a String.
8529 For other types an error is given.
8530 If you want to count the number of multibyte characters use
8531 |strchars()|.
8532 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
8533
8534 Can also be used as a |method|: >
8535 GetString()->strlen()
8536
8537strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
8538 The result is a String, which is part of {src}, starting from
8539 byte {start}, with the byte length {len}.
8540 When {chars} is present and TRUE then {len} is the number of
8541 characters positions (composing characters are not counted
8542 separately, thus "1" means one base character and any
8543 following composing characters).
8544 To count {start} as characters instead of bytes use
8545 |strcharpart()|.
8546
8547 When bytes are selected which do not exist, this doesn't
8548 result in an error, the bytes are simply omitted.
8549 If {len} is missing, the copy continues from {start} till the
8550 end of the {src}. >
8551 strpart("abcdefg", 3, 2) == "de"
8552 strpart("abcdefg", -2, 4) == "ab"
8553 strpart("abcdefg", 5, 4) == "fg"
8554 strpart("abcdefg", 3) == "defg"
8555
8556< Note: To get the first character, {start} must be 0. For
8557 example, to get the character under the cursor: >
8558 strpart(getline("."), col(".") - 1, 1, v:true)
8559<
8560 Can also be used as a |method|: >
8561 GetText()->strpart(5)
8562
8563strptime({format}, {timestring}) *strptime()*
8564 The result is a Number, which is a unix timestamp representing
8565 the date and time in {timestring}, which is expected to match
8566 the format specified in {format}.
8567
8568 The accepted {format} depends on your system, thus this is not
8569 portable! See the manual page of the C function strptime()
8570 for the format. Especially avoid "%c". The value of $TZ also
8571 matters.
8572
8573 If the {timestring} cannot be parsed with {format} zero is
8574 returned. If you do not know the format of {timestring} you
8575 can try different {format} values until you get a non-zero
8576 result.
8577
8578 See also |strftime()|.
8579 Examples: >
8580 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
8581< 862156163 >
8582 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
8583< Sun Apr 27 11:53:55 1997 >
8584 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
8585< Sun Apr 27 12:53:55 1997
8586
8587 Can also be used as a |method|: >
8588 GetFormat()->strptime(timestring)
8589<
8590 Not available on all systems. To check use: >
8591 :if exists("*strptime")
8592
8593strridx({haystack}, {needle} [, {start}]) *strridx()*
8594 The result is a Number, which gives the byte index in
8595 {haystack} of the last occurrence of the String {needle}.
8596 When {start} is specified, matches beyond this index are
8597 ignored. This can be used to find a match before a previous
8598 match: >
8599 :let lastcomma = strridx(line, ",")
8600 :let comma2 = strridx(line, ",", lastcomma - 1)
8601< The search is done case-sensitive.
8602 For pattern searches use |match()|.
8603 -1 is returned if the {needle} does not occur in {haystack}.
8604 If the {needle} is empty the length of {haystack} is returned.
8605 See also |stridx()|. Examples: >
8606 :echo strridx("an angry armadillo", "an") 3
8607< *strrchr()*
8608 When used with a single character it works similar to the C
8609 function strrchr().
8610
8611 Can also be used as a |method|: >
8612 GetHaystack()->strridx(needle)
8613
8614strtrans({string}) *strtrans()*
8615 The result is a String, which is {string} with all unprintable
8616 characters translated into printable characters |'isprint'|.
8617 Like they are shown in a window. Example: >
8618 echo strtrans(@a)
8619< This displays a newline in register a as "^@" instead of
8620 starting a new line.
8621
8622 Can also be used as a |method|: >
8623 GetString()->strtrans()
8624
8625strwidth({string}) *strwidth()*
8626 The result is a Number, which is the number of display cells
8627 String {string} occupies. A Tab character is counted as one
8628 cell, alternatively use |strdisplaywidth()|.
8629 When {string} contains characters with East Asian Width Class
8630 Ambiguous, this function's return value depends on 'ambiwidth'.
8631 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
8632
8633 Can also be used as a |method|: >
8634 GetString()->strwidth()
8635
8636submatch({nr} [, {list}]) *submatch()* *E935*
8637 Only for an expression in a |:substitute| command or
8638 substitute() function.
8639 Returns the {nr}'th submatch of the matched text. When {nr}
8640 is 0 the whole matched text is returned.
8641 Note that a NL in the string can stand for a line break of a
8642 multi-line match or a NUL character in the text.
8643 Also see |sub-replace-expression|.
8644
8645 If {list} is present and non-zero then submatch() returns
8646 a list of strings, similar to |getline()| with two arguments.
8647 NL characters in the text represent NUL characters in the
8648 text.
8649 Only returns more than one item for |:substitute|, inside
8650 |substitute()| this list will always contain one or zero
8651 items, since there are no real line breaks.
8652
8653 When substitute() is used recursively only the submatches in
8654 the current (deepest) call can be obtained.
8655
8656 Examples: >
8657 :s/\d\+/\=submatch(0) + 1/
8658 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
8659< This finds the first number in the line and adds one to it.
8660 A line break is included as a newline character.
8661
8662 Can also be used as a |method|: >
8663 GetNr()->submatch()
8664
8665substitute({string}, {pat}, {sub}, {flags}) *substitute()*
8666 The result is a String, which is a copy of {string}, in which
8667 the first match of {pat} is replaced with {sub}.
8668 When {flags} is "g", all matches of {pat} in {string} are
8669 replaced. Otherwise {flags} should be "".
8670
8671 This works like the ":substitute" command (without any flags).
8672 But the matching with {pat} is always done like the 'magic'
8673 option is set and 'cpoptions' is empty (to make scripts
8674 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
8675 if you want to ignore or match case and ignore 'ignorecase'.
8676 'smartcase' is not used. See |string-match| for how {pat} is
8677 used.
8678
8679 A "~" in {sub} is not replaced with the previous {sub}.
8680 Note that some codes in {sub} have a special meaning
8681 |sub-replace-special|. For example, to replace something with
8682 "\n" (two characters), use "\\\\n" or '\\n'.
8683
8684 When {pat} does not match in {string}, {string} is returned
8685 unmodified.
8686
8687 Example: >
8688 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
8689< This removes the last component of the 'path' option. >
8690 :echo substitute("testing", ".*", "\\U\\0", "")
8691< results in "TESTING".
8692
8693 When {sub} starts with "\=", the remainder is interpreted as
8694 an expression. See |sub-replace-expression|. Example: >
8695 :echo substitute(s, '%\(\x\x\)',
8696 \ '\=nr2char("0x" . submatch(1))', 'g')
8697
8698< When {sub} is a Funcref that function is called, with one
8699 optional argument. Example: >
8700 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
8701< The optional argument is a list which contains the whole
8702 matched string and up to nine submatches, like what
8703 |submatch()| returns. Example: >
8704 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g')
8705
8706< Can also be used as a |method|: >
8707 GetString()->substitute(pat, sub, flags)
8708
8709swapinfo({fname}) *swapinfo()*
8710 The result is a dictionary, which holds information about the
8711 swapfile {fname}. The available fields are:
8712 version Vim version
8713 user user name
8714 host host name
8715 fname original file name
8716 pid PID of the Vim process that created the swap
8717 file
8718 mtime last modification time in seconds
8719 inode Optional: INODE number of the file
8720 dirty 1 if file was modified, 0 if not
8721 Note that "user" and "host" are truncated to at most 39 bytes.
8722 In case of failure an "error" item is added with the reason:
8723 Cannot open file: file not found or in accessible
8724 Cannot read file: cannot read first block
8725 Not a swap file: does not contain correct block ID
8726 Magic number mismatch: Info in first block is invalid
8727
8728 Can also be used as a |method|: >
8729 GetFilename()->swapinfo()
8730
8731swapname({buf}) *swapname()*
8732 The result is the swap file path of the buffer {expr}.
8733 For the use of {buf}, see |bufname()| above.
8734 If buffer {buf} is the current buffer, the result is equal to
8735 |:swapname| (unless there is no swap file).
8736 If buffer {buf} has no swap file, returns an empty string.
8737
8738 Can also be used as a |method|: >
8739 GetBufname()->swapname()
8740
8741synID({lnum}, {col}, {trans}) *synID()*
8742 The result is a Number, which is the syntax ID at the position
8743 {lnum} and {col} in the current window.
8744 The syntax ID can be used with |synIDattr()| and
8745 |synIDtrans()| to obtain syntax information about text.
8746
8747 {col} is 1 for the leftmost column, {lnum} is 1 for the first
8748 line. 'synmaxcol' applies, in a longer line zero is returned.
8749 Note that when the position is after the last character,
8750 that's where the cursor can be in Insert mode, synID() returns
8751 zero. {lnum} is used like with |getline()|.
8752
8753 When {trans} is |TRUE|, transparent items are reduced to the
8754 item that they reveal. This is useful when wanting to know
8755 the effective color. When {trans} is |FALSE|, the transparent
8756 item is returned. This is useful when wanting to know which
8757 syntax item is effective (e.g. inside parens).
8758 Warning: This function can be very slow. Best speed is
8759 obtained by going through the file in forward direction.
8760
8761 Example (echoes the name of the syntax item under the cursor): >
8762 :echo synIDattr(synID(line("."), col("."), 1), "name")
8763<
8764
8765synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
8766 The result is a String, which is the {what} attribute of
8767 syntax ID {synID}. This can be used to obtain information
8768 about a syntax item.
8769 {mode} can be "gui", "cterm" or "term", to get the attributes
8770 for that mode. When {mode} is omitted, or an invalid value is
8771 used, the attributes for the currently active highlighting are
8772 used (GUI, cterm or term).
8773 Use synIDtrans() to follow linked highlight groups.
8774 {what} result
8775 "name" the name of the syntax item
8776 "fg" foreground color (GUI: color name used to set
8777 the color, cterm: color number as a string,
8778 term: empty string)
8779 "bg" background color (as with "fg")
8780 "font" font name (only available in the GUI)
8781 |highlight-font|
8782 "sp" special color for the GUI (as with "fg")
8783 |highlight-guisp|
8784 "ul" underline color for cterm: number as a string
8785 "fg#" like "fg", but for the GUI and the GUI is
8786 running the name in "#RRGGBB" form
8787 "bg#" like "fg#" for "bg"
8788 "sp#" like "fg#" for "sp"
8789 "bold" "1" if bold
8790 "italic" "1" if italic
8791 "reverse" "1" if reverse
8792 "inverse" "1" if inverse (= reverse)
8793 "standout" "1" if standout
8794 "underline" "1" if underlined
8795 "undercurl" "1" if undercurled
8796 "strike" "1" if strikethrough
8797
8798 Example (echoes the color of the syntax item under the
8799 cursor): >
8800 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
8801<
8802 Can also be used as a |method|: >
8803 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
8804
8805
8806synIDtrans({synID}) *synIDtrans()*
8807 The result is a Number, which is the translated syntax ID of
8808 {synID}. This is the syntax group ID of what is being used to
8809 highlight the character. Highlight links given with
8810 ":highlight link" are followed.
8811
8812 Can also be used as a |method|: >
8813 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
8814
8815synconcealed({lnum}, {col}) *synconcealed()*
8816 The result is a |List| with currently three items:
8817 1. The first item in the list is 0 if the character at the
8818 position {lnum} and {col} is not part of a concealable
8819 region, 1 if it is. {lnum} is used like with |getline()|.
8820 2. The second item in the list is a string. If the first item
8821 is 1, the second item contains the text which will be
8822 displayed in place of the concealed text, depending on the
8823 current setting of 'conceallevel' and 'listchars'.
8824 3. The third and final item in the list is a number
8825 representing the specific syntax region matched in the
8826 line. When the character is not concealed the value is
8827 zero. This allows detection of the beginning of a new
8828 concealable region if there are two consecutive regions
8829 with the same replacement character. For an example, if
8830 the text is "123456" and both "23" and "45" are concealed
8831 and replaced by the character "X", then:
8832 call returns ~
8833 synconcealed(lnum, 1) [0, '', 0]
8834 synconcealed(lnum, 2) [1, 'X', 1]
8835 synconcealed(lnum, 3) [1, 'X', 1]
8836 synconcealed(lnum, 4) [1, 'X', 2]
8837 synconcealed(lnum, 5) [1, 'X', 2]
8838 synconcealed(lnum, 6) [0, '', 0]
8839
8840
8841synstack({lnum}, {col}) *synstack()*
8842 Return a |List|, which is the stack of syntax items at the
8843 position {lnum} and {col} in the current window. {lnum} is
8844 used like with |getline()|. Each item in the List is an ID
8845 like what |synID()| returns.
8846 The first item in the List is the outer region, following are
8847 items contained in that one. The last one is what |synID()|
8848 returns, unless not the whole item is highlighted or it is a
8849 transparent item.
8850 This function is useful for debugging a syntax file.
8851 Example that shows the syntax stack under the cursor: >
8852 for id in synstack(line("."), col("."))
8853 echo synIDattr(id, "name")
8854 endfor
8855< When the position specified with {lnum} and {col} is invalid
8856 nothing is returned. The position just after the last
8857 character in a line and the first column in an empty line are
8858 valid positions.
8859
8860system({expr} [, {input}]) *system()* *E677*
8861 Get the output of the shell command {expr} as a |String|. See
8862 |systemlist()| to get the output as a |List|.
8863
8864 When {input} is given and is a |String| this string is written
8865 to a file and passed as stdin to the command. The string is
8866 written as-is, you need to take care of using the correct line
8867 separators yourself.
8868 If {input} is given and is a |List| it is written to the file
8869 in a way |writefile()| does with {binary} set to "b" (i.e.
8870 with a newline between each list item with newlines inside
8871 list items converted to NULs).
8872 When {input} is given and is a number that is a valid id for
8873 an existing buffer then the content of the buffer is written
8874 to the file line by line, each line terminated by a NL and
8875 NULs characters where the text has a NL.
8876
8877 Pipes are not used, the 'shelltemp' option is not used.
8878
8879 When prepended by |:silent| the terminal will not be set to
8880 cooked mode. This is meant to be used for commands that do
8881 not need the user to type. It avoids stray characters showing
8882 up on the screen which require |CTRL-L| to remove. >
8883 :silent let f = system('ls *.vim')
8884<
8885 Note: Use |shellescape()| or |::S| with |expand()| or
8886 |fnamemodify()| to escape special characters in a command
8887 argument. Newlines in {expr} may cause the command to fail.
8888 The characters in 'shellquote' and 'shellxquote' may also
8889 cause trouble.
8890 This is not to be used for interactive commands.
8891
8892 The result is a String. Example: >
8893 :let files = system("ls " . shellescape(expand('%:h')))
8894 :let files = system('ls ' . expand('%:h:S'))
8895
8896< To make the result more system-independent, the shell output
8897 is filtered to replace <CR> with <NL> for Macintosh, and
8898 <CR><NL> with <NL> for DOS-like systems.
8899 To avoid the string being truncated at a NUL, all NUL
8900 characters are replaced with SOH (0x01).
8901
8902 The command executed is constructed using several options:
8903 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
8904 ({tmp} is an automatically generated file name).
8905 For Unix, braces are put around {expr} to allow for
8906 concatenated commands.
8907
8908 The command will be executed in "cooked" mode, so that a
8909 CTRL-C will interrupt the command (on Unix at least).
8910
8911 The resulting error code can be found in |v:shell_error|.
8912 This function will fail in |restricted-mode|.
8913
8914 Note that any wrong value in the options mentioned above may
8915 make the function fail. It has also been reported to fail
8916 when using a security agent application.
8917 Unlike ":!cmd" there is no automatic check for changed files.
8918 Use |:checktime| to force a check.
8919
8920 Can also be used as a |method|: >
8921 :echo GetCmd()->system()
8922
8923
8924systemlist({expr} [, {input}]) *systemlist()*
8925 Same as |system()|, but returns a |List| with lines (parts of
8926 output separated by NL) with NULs transformed into NLs. Output
8927 is the same as |readfile()| will output with {binary} argument
8928 set to "b", except that there is no extra empty item when the
8929 result ends in a NL.
8930 Note that on MS-Windows you may get trailing CR characters.
8931
8932 To see the difference between "echo hello" and "echo -n hello"
8933 use |system()| and |split()|: >
8934 echo system('echo hello')->split('\n', 1)
8935<
8936 Returns an empty string on error.
8937
8938 Can also be used as a |method|: >
8939 :echo GetCmd()->systemlist()
8940
8941
8942tabpagebuflist([{arg}]) *tabpagebuflist()*
8943 The result is a |List|, where each item is the number of the
8944 buffer associated with each window in the current tab page.
8945 {arg} specifies the number of the tab page to be used. When
8946 omitted the current tab page is used.
8947 When {arg} is invalid the number zero is returned.
8948 To get a list of all buffers in all tabs use this: >
8949 let buflist = []
8950 for i in range(tabpagenr('$'))
8951 call extend(buflist, tabpagebuflist(i + 1))
8952 endfor
8953< Note that a buffer may appear in more than one window.
8954
8955 Can also be used as a |method|: >
8956 GetTabpage()->tabpagebuflist()
8957
8958tabpagenr([{arg}]) *tabpagenr()*
8959 The result is a Number, which is the number of the current
8960 tab page. The first tab page has number 1.
8961
8962 The optional argument {arg} supports the following values:
8963 $ the number of the last tab page (the tab page
8964 count).
8965 # the number of the last accessed tab page
8966 (where |g<Tab>| goes to). if there is no
8967 previous tab page 0 is returned.
8968 The number can be used with the |:tab| command.
8969
8970
8971tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
8972 Like |winnr()| but for tab page {tabarg}.
8973 {tabarg} specifies the number of tab page to be used.
8974 {arg} is used like with |winnr()|:
8975 - When omitted the current window number is returned. This is
8976 the window which will be used when going to this tab page.
8977 - When "$" the number of windows is returned.
8978 - When "#" the previous window nr is returned.
8979 Useful examples: >
8980 tabpagewinnr(1) " current window of tab page 1
8981 tabpagewinnr(4, '$') " number of windows in tab page 4
8982< When {tabarg} is invalid zero is returned.
8983
8984 Can also be used as a |method|: >
8985 GetTabpage()->tabpagewinnr()
8986<
8987 *tagfiles()*
8988tagfiles() Returns a |List| with the file names used to search for tags
8989 for the current buffer. This is the 'tags' option expanded.
8990
8991
8992taglist({expr} [, {filename}]) *taglist()*
8993 Returns a |List| of tags matching the regular expression {expr}.
8994
8995 If {filename} is passed it is used to prioritize the results
8996 in the same way that |:tselect| does. See |tag-priority|.
8997 {filename} should be the full path of the file.
8998
8999 Each list item is a dictionary with at least the following
9000 entries:
9001 name Name of the tag.
9002 filename Name of the file where the tag is
9003 defined. It is either relative to the
9004 current directory or a full path.
9005 cmd Ex command used to locate the tag in
9006 the file.
9007 kind Type of the tag. The value for this
9008 entry depends on the language specific
9009 kind values. Only available when
9010 using a tags file generated by
9011 Exuberant ctags or hdrtag.
9012 static A file specific tag. Refer to
9013 |static-tag| for more information.
9014 More entries may be present, depending on the content of the
9015 tags file: access, implementation, inherits and signature.
9016 Refer to the ctags documentation for information about these
9017 fields. For C code the fields "struct", "class" and "enum"
9018 may appear, they give the name of the entity the tag is
9019 contained in.
9020
9021 The ex-command "cmd" can be either an ex search pattern, a
9022 line number or a line number followed by a byte number.
9023
9024 If there are no matching tags, then an empty list is returned.
9025
9026 To get an exact tag match, the anchors '^' and '$' should be
9027 used in {expr}. This also make the function work faster.
9028 Refer to |tag-regexp| for more information about the tag
9029 search regular expression pattern.
9030
9031 Refer to |'tags'| for information about how the tags file is
9032 located by Vim. Refer to |tags-file-format| for the format of
9033 the tags file generated by the different ctags tools.
9034
9035 Can also be used as a |method|: >
9036 GetTagpattern()->taglist()
9037
9038tan({expr}) *tan()*
9039 Return the tangent of {expr}, measured in radians, as a |Float|
9040 in the range [-inf, inf].
9041 {expr} must evaluate to a |Float| or a |Number|.
9042 Examples: >
9043 :echo tan(10)
9044< 0.648361 >
9045 :echo tan(-4.01)
9046< -1.181502
9047
9048 Can also be used as a |method|: >
9049 Compute()->tan()
9050<
9051 {only available when compiled with the |+float| feature}
9052
9053
9054tanh({expr}) *tanh()*
9055 Return the hyperbolic tangent of {expr} as a |Float| in the
9056 range [-1, 1].
9057 {expr} must evaluate to a |Float| or a |Number|.
9058 Examples: >
9059 :echo tanh(0.5)
9060< 0.462117 >
9061 :echo tanh(-1)
9062< -0.761594
9063
9064 Can also be used as a |method|: >
9065 Compute()->tanh()
9066<
9067 {only available when compiled with the |+float| feature}
9068
9069
9070tempname() *tempname()* *temp-file-name*
9071 The result is a String, which is the name of a file that
9072 doesn't exist. It can be used for a temporary file. The name
9073 is different for at least 26 consecutive calls. Example: >
9074 :let tmpfile = tempname()
9075 :exe "redir > " . tmpfile
9076< For Unix, the file will be in a private directory |tempfile|.
9077 For MS-Windows forward slashes are used when the 'shellslash'
9078 option is set, or when 'shellcmdflag' starts with '-' and
9079 'shell' does not contain powershell or pwsh.
9080
9081
9082term_ functions are documented here: |terminal-function-details|
9083
9084
9085terminalprops() *terminalprops()*
9086 Returns a |Dictionary| with properties of the terminal that Vim
9087 detected from the response to |t_RV| request. See
9088 |v:termresponse| for the response itself. If |v:termresponse|
9089 is empty most values here will be 'u' for unknown.
9090 cursor_style whether sending |t_RS| works **
9091 cursor_blink_mode whether sending |t_RC| works **
9092 underline_rgb whether |t_8u| works **
9093 mouse mouse type supported
9094
9095 ** value 'u' for unknown, 'y' for yes, 'n' for no
9096
9097 If the |+termresponse| feature is missing then the result is
9098 an empty dictionary.
9099
9100 If "cursor_style" is 'y' then |t_RS| will be sent to request the
9101 current cursor style.
9102 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
9103 request the cursor blink status.
9104 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
9105 is not empty, Vim will detect the working of sending |t_RS|
9106 and |t_RC| on startup.
9107
9108 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
9109 This avoids sending it to xterm, which would clear the colors.
9110
9111 For "mouse" the value 'u' is unknown
9112
9113 Also see:
9114 - 'ambiwidth' - detected by using |t_u7|.
9115 - |v:termstyleresp| and |v:termblinkresp| for the response to
9116 |t_RS| and |t_RC|.
9117
9118
9119test_ functions are documented here: |test-functions-details|
9120
9121
9122 *timer_info()*
9123timer_info([{id}])
9124 Return a list with information about timers.
9125 When {id} is given only information about this timer is
9126 returned. When timer {id} does not exist an empty list is
9127 returned.
9128 When {id} is omitted information about all timers is returned.
9129
9130 For each timer the information is stored in a |Dictionary| with
9131 these items:
9132 "id" the timer ID
9133 "time" time the timer was started with
9134 "remaining" time until the timer fires
9135 "repeat" number of times the timer will still fire;
9136 -1 means forever
9137 "callback" the callback
9138 "paused" 1 if the timer is paused, 0 otherwise
9139
9140 Can also be used as a |method|: >
9141 GetTimer()->timer_info()
9142
9143< {only available when compiled with the |+timers| feature}
9144
9145timer_pause({timer}, {paused}) *timer_pause()*
9146 Pause or unpause a timer. A paused timer does not invoke its
9147 callback when its time expires. Unpausing a timer may cause
9148 the callback to be invoked almost immediately if enough time
9149 has passed.
9150
9151 Pausing a timer is useful to avoid the callback to be called
9152 for a short time.
9153
9154 If {paused} evaluates to a non-zero Number or a non-empty
9155 String, then the timer is paused, otherwise it is unpaused.
9156 See |non-zero-arg|.
9157
9158 Can also be used as a |method|: >
9159 GetTimer()->timer_pause(1)
9160
9161< {only available when compiled with the |+timers| feature}
9162
9163 *timer_start()* *timer* *timers*
9164timer_start({time}, {callback} [, {options}])
9165 Create a timer and return the timer ID.
9166
9167 {time} is the waiting time in milliseconds. This is the
9168 minimum time before invoking the callback. When the system is
9169 busy or Vim is not waiting for input the time will be longer.
9170
9171 {callback} is the function to call. It can be the name of a
9172 function or a |Funcref|. It is called with one argument, which
9173 is the timer ID. The callback is only invoked when Vim is
9174 waiting for input.
9175 If you want to show a message look at |popup_notification()|
9176 to avoid interfering with what the user is doing.
9177
9178 {options} is a dictionary. Supported entries:
9179 "repeat" Number of times to repeat calling the
9180 callback. -1 means forever. When not present
9181 the callback will be called once.
9182 If the timer causes an error three times in a
9183 row the repeat is cancelled. This avoids that
9184 Vim becomes unusable because of all the error
9185 messages.
9186
9187 Example: >
9188 func MyHandler(timer)
9189 echo 'Handler called'
9190 endfunc
9191 let timer = timer_start(500, 'MyHandler',
9192 \ {'repeat': 3})
9193< This will invoke MyHandler() three times at 500 msec
9194 intervals.
9195
9196 Can also be used as a |method|: >
9197 GetMsec()->timer_start(callback)
9198
9199< Not available in the |sandbox|.
9200 {only available when compiled with the |+timers| feature}
9201
9202timer_stop({timer}) *timer_stop()*
9203 Stop a timer. The timer callback will no longer be invoked.
9204 {timer} is an ID returned by timer_start(), thus it must be a
9205 Number. If {timer} does not exist there is no error.
9206
9207 Can also be used as a |method|: >
9208 GetTimer()->timer_stop()
9209
9210< {only available when compiled with the |+timers| feature}
9211
9212timer_stopall() *timer_stopall()*
9213 Stop all timers. The timer callbacks will no longer be
9214 invoked. Useful if a timer is misbehaving. If there are no
9215 timers there is no error.
9216
9217 {only available when compiled with the |+timers| feature}
9218
9219tolower({expr}) *tolower()*
9220 The result is a copy of the String given, with all uppercase
9221 characters turned into lowercase (just like applying |gu| to
9222 the string).
9223
9224 Can also be used as a |method|: >
9225 GetText()->tolower()
9226
9227toupper({expr}) *toupper()*
9228 The result is a copy of the String given, with all lowercase
9229 characters turned into uppercase (just like applying |gU| to
9230 the string).
9231
9232 Can also be used as a |method|: >
9233 GetText()->toupper()
9234
9235tr({src}, {fromstr}, {tostr}) *tr()*
9236 The result is a copy of the {src} string with all characters
9237 which appear in {fromstr} replaced by the character in that
9238 position in the {tostr} string. Thus the first character in
9239 {fromstr} is translated into the first character in {tostr}
9240 and so on. Exactly like the unix "tr" command.
9241 This code also deals with multibyte characters properly.
9242
9243 Examples: >
9244 echo tr("hello there", "ht", "HT")
9245< returns "Hello THere" >
9246 echo tr("<blob>", "<>", "{}")
9247< returns "{blob}"
9248
9249 Can also be used as a |method|: >
9250 GetText()->tr(from, to)
9251
9252trim({text} [, {mask} [, {dir}]]) *trim()*
9253 Return {text} as a String where any character in {mask} is
9254 removed from the beginning and/or end of {text}.
9255
9256 If {mask} is not given, {mask} is all characters up to 0x20,
9257 which includes Tab, space, NL and CR, plus the non-breaking
9258 space character 0xa0.
9259
9260 The optional {dir} argument specifies where to remove the
9261 characters:
9262 0 remove from the beginning and end of {text}
9263 1 remove only at the beginning of {text}
9264 2 remove only at the end of {text}
9265 When omitted both ends are trimmed.
9266
9267 This function deals with multibyte characters properly.
9268
9269 Examples: >
9270 echo trim(" some text ")
9271< returns "some text" >
9272 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL"
9273< returns "RESERVE_TAIL" >
9274 echo trim("rm<Xrm<>X>rrm", "rm<>")
9275< returns "Xrm<>X" (characters in the middle are not removed) >
9276 echo trim(" vim ", " ", 2)
9277< returns " vim"
9278
9279 Can also be used as a |method|: >
9280 GetText()->trim()
9281
9282trunc({expr}) *trunc()*
9283 Return the largest integral value with magnitude less than or
9284 equal to {expr} as a |Float| (truncate towards zero).
9285 {expr} must evaluate to a |Float| or a |Number|.
9286 Examples: >
9287 echo trunc(1.456)
9288< 1.0 >
9289 echo trunc(-5.456)
9290< -5.0 >
9291 echo trunc(4.0)
9292< 4.0
9293
9294 Can also be used as a |method|: >
9295 Compute()->trunc()
9296<
9297 {only available when compiled with the |+float| feature}
9298
9299 *type()*
9300type({expr}) The result is a Number representing the type of {expr}.
9301 Instead of using the number directly, it is better to use the
9302 v:t_ variable that has the value:
9303 Number: 0 |v:t_number|
9304 String: 1 |v:t_string|
9305 Funcref: 2 |v:t_func|
9306 List: 3 |v:t_list|
9307 Dictionary: 4 |v:t_dict|
9308 Float: 5 |v:t_float|
9309 Boolean: 6 |v:t_bool| (v:false and v:true)
9310 None: 7 |v:t_none| (v:null and v:none)
9311 Job: 8 |v:t_job|
9312 Channel: 9 |v:t_channel|
9313 Blob: 10 |v:t_blob|
9314 For backward compatibility, this method can be used: >
9315 :if type(myvar) == type(0)
9316 :if type(myvar) == type("")
9317 :if type(myvar) == type(function("tr"))
9318 :if type(myvar) == type([])
9319 :if type(myvar) == type({})
9320 :if type(myvar) == type(0.0)
9321 :if type(myvar) == type(v:false)
9322 :if type(myvar) == type(v:none)
9323< To check if the v:t_ variables exist use this: >
9324 :if exists('v:t_number')
9325
9326< Can also be used as a |method|: >
9327 mylist->type()
9328
9329
9330typename({expr}) *typename()*
9331 Return a string representation of the type of {expr}.
9332 Example: >
9333 echo typename([1, 2, 3])
9334 list<number>
9335
9336
9337undofile({name}) *undofile()*
9338 Return the name of the undo file that would be used for a file
9339 with name {name} when writing. This uses the 'undodir'
9340 option, finding directories that exist. It does not check if
9341 the undo file exists.
9342 {name} is always expanded to the full path, since that is what
9343 is used internally.
9344 If {name} is empty undofile() returns an empty string, since a
9345 buffer without a file name will not write an undo file.
9346 Useful in combination with |:wundo| and |:rundo|.
9347 When compiled without the |+persistent_undo| option this always
9348 returns an empty string.
9349
9350 Can also be used as a |method|: >
9351 GetFilename()->undofile()
9352
9353undotree() *undotree()*
9354 Return the current state of the undo tree in a dictionary with
9355 the following items:
9356 "seq_last" The highest undo sequence number used.
9357 "seq_cur" The sequence number of the current position in
9358 the undo tree. This differs from "seq_last"
9359 when some changes were undone.
9360 "time_cur" Time last used for |:earlier| and related
9361 commands. Use |strftime()| to convert to
9362 something readable.
9363 "save_last" Number of the last file write. Zero when no
9364 write yet.
9365 "save_cur" Number of the current position in the undo
9366 tree.
9367 "synced" Non-zero when the last undo block was synced.
9368 This happens when waiting from input from the
9369 user. See |undo-blocks|.
9370 "entries" A list of dictionaries with information about
9371 undo blocks.
9372
9373 The first item in the "entries" list is the oldest undo item.
9374 Each List item is a |Dictionary| with these items:
9375 "seq" Undo sequence number. Same as what appears in
9376 |:undolist|.
9377 "time" Timestamp when the change happened. Use
9378 |strftime()| to convert to something readable.
9379 "newhead" Only appears in the item that is the last one
9380 that was added. This marks the last change
9381 and where further changes will be added.
9382 "curhead" Only appears in the item that is the last one
9383 that was undone. This marks the current
9384 position in the undo tree, the block that will
9385 be used by a redo command. When nothing was
9386 undone after the last change this item will
9387 not appear anywhere.
9388 "save" Only appears on the last block before a file
9389 write. The number is the write count. The
9390 first write has number 1, the last one the
9391 "save_last" mentioned above.
9392 "alt" Alternate entry. This is again a List of undo
9393 blocks. Each item may again have an "alt"
9394 item.
9395
9396uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
9397 Remove second and succeeding copies of repeated adjacent
9398 {list} items in-place. Returns {list}. If you want a list
9399 to remain unmodified make a copy first: >
9400 :let newlist = uniq(copy(mylist))
9401< The default compare function uses the string representation of
9402 each item. For the use of {func} and {dict} see |sort()|.
9403
9404 Can also be used as a |method|: >
9405 mylist->uniq()
9406
9407values({dict}) *values()*
9408 Return a |List| with all the values of {dict}. The |List| is
9409 in arbitrary order. Also see |items()| and |keys()|.
9410
9411 Can also be used as a |method|: >
9412 mydict->values()
9413
9414virtcol({expr}) *virtcol()*
9415 The result is a Number, which is the screen column of the file
9416 position given with {expr}. That is, the last screen position
9417 occupied by the character at that position, when the screen
9418 would be of unlimited width. When there is a <Tab> at the
9419 position, the returned Number will be the column at the end of
9420 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
9421 set to 8, it returns 8. |conceal| is ignored.
9422 For the byte position use |col()|.
9423 For the use of {expr} see |col()|.
9424 When 'virtualedit' is used {expr} can be [lnum, col, off], where
9425 "off" is the offset in screen columns from the start of the
9426 character. E.g., a position within a <Tab> or after the last
9427 character. When "off" is omitted zero is used.
9428 When Virtual editing is active in the current mode, a position
9429 beyond the end of the line can be returned. |'virtualedit'|
9430 The accepted positions are:
9431 . the cursor position
9432 $ the end of the cursor line (the result is the
9433 number of displayed characters in the cursor line
9434 plus one)
9435 'x position of mark x (if the mark is not set, 0 is
9436 returned)
9437 v In Visual mode: the start of the Visual area (the
9438 cursor is the end). When not in Visual mode
9439 returns the cursor position. Differs from |'<| in
9440 that it's updated right away.
9441 Note that only marks in the current file can be used.
9442 Examples: >
9443 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
9444 virtcol("$") with text "foo^Lbar", returns 9
9445 virtcol("'t") with text " there", with 't at 'h', returns 6
9446< The first column is 1. 0 is returned for an error.
9447 A more advanced example that echoes the maximum length of
9448 all lines: >
9449 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
9450
9451< Can also be used as a |method|: >
9452 GetPos()->virtcol()
9453
9454
9455visualmode([{expr}]) *visualmode()*
9456 The result is a String, which describes the last Visual mode
9457 used in the current buffer. Initially it returns an empty
9458 string, but once Visual mode has been used, it returns "v",
9459 "V", or "<CTRL-V>" (a single CTRL-V character) for
9460 character-wise, line-wise, or block-wise Visual mode
9461 respectively.
9462 Example: >
9463 :exe "normal " . visualmode()
9464< This enters the same Visual mode as before. It is also useful
9465 in scripts if you wish to act differently depending on the
9466 Visual mode that was used.
9467 If Visual mode is active, use |mode()| to get the Visual mode
9468 (e.g., in a |:vmap|).
9469 If {expr} is supplied and it evaluates to a non-zero Number or
9470 a non-empty String, then the Visual mode will be cleared and
9471 the old value is returned. See |non-zero-arg|.
9472
9473wildmenumode() *wildmenumode()*
9474 Returns |TRUE| when the wildmenu is active and |FALSE|
9475 otherwise. See 'wildmenu' and 'wildmode'.
9476 This can be used in mappings to handle the 'wildcharm' option
9477 gracefully. (Makes only sense with |mapmode-c| mappings).
9478
9479 For example to make <c-j> work like <down> in wildmode, use: >
9480 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
9481<
9482 (Note, this needs the 'wildcharm' option set appropriately).
9483
9484win_execute({id}, {command} [, {silent}]) *win_execute()*
9485 Like `execute()` but in the context of window {id}.
9486 The window will temporarily be made the current window,
9487 without triggering autocommands or changing directory. When
9488 executing {command} autocommands will be triggered, this may
9489 have unexpected side effects. Use |:noautocmd| if needed.
9490 Example: >
9491 call win_execute(winid, 'set syntax=python')
9492< Doing the same with `setwinvar()` would not trigger
9493 autocommands and not actually show syntax highlighting.
9494
9495 *E994*
9496 Not all commands are allowed in popup windows.
9497 When window {id} does not exist then no error is given and
9498 an empty string is returned.
9499
9500 Can also be used as a |method|, the base is passed as the
9501 second argument: >
9502 GetCommand()->win_execute(winid)
9503
9504win_findbuf({bufnr}) *win_findbuf()*
9505 Returns a |List| with |window-ID|s for windows that contain
9506 buffer {bufnr}. When there is none the list is empty.
9507
9508 Can also be used as a |method|: >
9509 GetBufnr()->win_findbuf()
9510
9511win_getid([{win} [, {tab}]]) *win_getid()*
9512 Get the |window-ID| for the specified window.
9513 When {win} is missing use the current window.
9514 With {win} this is the window number. The top window has
9515 number 1.
9516 Without {tab} use the current tab, otherwise the tab with
9517 number {tab}. The first tab has number one.
9518 Return zero if the window cannot be found.
9519
9520 Can also be used as a |method|: >
9521 GetWinnr()->win_getid()
9522
9523
9524win_gettype([{nr}]) *win_gettype()*
9525 Return the type of the window:
9526 "autocmd" autocommand window. Temporary window
9527 used to execute autocommands.
9528 "command" command-line window |cmdwin|
9529 (empty) normal window
9530 "loclist" |location-list-window|
9531 "popup" popup window |popup|
9532 "preview" preview window |preview-window|
9533 "quickfix" |quickfix-window|
9534 "unknown" window {nr} not found
9535
9536 When {nr} is omitted return the type of the current window.
9537 When {nr} is given return the type of this window by number or
9538 |window-ID|.
9539
9540 Also see the 'buftype' option. When running a terminal in a
9541 popup window then 'buftype' is "terminal" and win_gettype()
9542 returns "popup".
9543
9544 Can also be used as a |method|: >
9545 GetWinid()->win_gettype()
9546<
9547win_gotoid({expr}) *win_gotoid()*
9548 Go to window with ID {expr}. This may also change the current
9549 tabpage.
9550 Return TRUE if successful, FALSE if the window cannot be found.
9551
9552 Can also be used as a |method|: >
9553 GetWinid()->win_gotoid()
9554
9555win_id2tabwin({expr}) *win_id2tabwin()*
9556 Return a list with the tab number and window number of window
9557 with ID {expr}: [tabnr, winnr].
9558 Return [0, 0] if the window cannot be found.
9559
9560 Can also be used as a |method|: >
9561 GetWinid()->win_id2tabwin()
9562
9563win_id2win({expr}) *win_id2win()*
9564 Return the window number of window with ID {expr}.
9565 Return 0 if the window cannot be found in the current tabpage.
9566
9567 Can also be used as a |method|: >
9568 GetWinid()->win_id2win()
9569
9570win_screenpos({nr}) *win_screenpos()*
9571 Return the screen position of window {nr} as a list with two
9572 numbers: [row, col]. The first window always has position
9573 [1, 1], unless there is a tabline, then it is [2, 1].
9574 {nr} can be the window number or the |window-ID|. Use zero
9575 for the current window.
9576 Returns [0, 0] if the window cannot be found in the current
9577 tabpage.
9578
9579 Can also be used as a |method|: >
9580 GetWinid()->win_screenpos()
9581<
9582win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
9583 Move the window {nr} to a new split of the window {target}.
9584 This is similar to moving to {target}, creating a new window
9585 using |:split| but having the same contents as window {nr}, and
9586 then closing {nr}.
9587
9588 Both {nr} and {target} can be window numbers or |window-ID|s.
9589 Both must be in the current tab page.
9590
9591 Returns zero for success, non-zero for failure.
9592
9593 {options} is a |Dictionary| with the following optional entries:
9594 "vertical" When TRUE, the split is created vertically,
9595 like with |:vsplit|.
9596 "rightbelow" When TRUE, the split is made below or to the
9597 right (if vertical). When FALSE, it is done
9598 above or to the left (if vertical). When not
9599 present, the values of 'splitbelow' and
9600 'splitright' are used.
9601
9602 Can also be used as a |method|: >
9603 GetWinid()->win_splitmove(target)
9604<
9605
9606 *winbufnr()*
9607winbufnr({nr}) The result is a Number, which is the number of the buffer
9608 associated with window {nr}. {nr} can be the window number or
9609 the |window-ID|.
9610 When {nr} is zero, the number of the buffer in the current
9611 window is returned.
9612 When window {nr} doesn't exist, -1 is returned.
9613 Example: >
9614 :echo "The file in the current window is " . bufname(winbufnr(0))
9615<
9616 Can also be used as a |method|: >
9617 FindWindow()->winbufnr()->bufname()
9618<
9619 *wincol()*
9620wincol() The result is a Number, which is the virtual column of the
9621 cursor in the window. This is counting screen cells from the
9622 left side of the window. The leftmost column is one.
9623
9624 *windowsversion()*
9625windowsversion()
9626 The result is a String. For MS-Windows it indicates the OS
9627 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
9628 Windows XP is "5.1". For non-MS-Windows systems the result is
9629 an empty string.
9630
9631winheight({nr}) *winheight()*
9632 The result is a Number, which is the height of window {nr}.
9633 {nr} can be the window number or the |window-ID|.
9634 When {nr} is zero, the height of the current window is
9635 returned. When window {nr} doesn't exist, -1 is returned.
9636 An existing window always has a height of zero or more.
9637 This excludes any window toolbar line.
9638 Examples: >
9639 :echo "The current window has " . winheight(0) . " lines."
9640
9641< Can also be used as a |method|: >
9642 GetWinid()->winheight()
9643<
9644winlayout([{tabnr}]) *winlayout()*
9645 The result is a nested List containing the layout of windows
9646 in a tabpage.
9647
9648 Without {tabnr} use the current tabpage, otherwise the tabpage
9649 with number {tabnr}. If the tabpage {tabnr} is not found,
9650 returns an empty list.
9651
9652 For a leaf window, it returns:
9653 ['leaf', {winid}]
9654 For horizontally split windows, which form a column, it
9655 returns:
9656 ['col', [{nested list of windows}]]
9657 For vertically split windows, which form a row, it returns:
9658 ['row', [{nested list of windows}]]
9659
9660 Example: >
9661 " Only one window in the tab page
9662 :echo winlayout()
9663 ['leaf', 1000]
9664 " Two horizontally split windows
9665 :echo winlayout()
9666 ['col', [['leaf', 1000], ['leaf', 1001]]]
9667 " The second tab page, with three horizontally split
9668 " windows, with two vertically split windows in the
9669 " middle window
9670 :echo winlayout(2)
9671 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
9672 ['leaf', 1001]]], ['leaf', 1000]]]
9673<
9674 Can also be used as a |method|: >
9675 GetTabnr()->winlayout()
9676<
9677 *winline()*
9678winline() The result is a Number, which is the screen line of the cursor
9679 in the window. This is counting screen lines from the top of
9680 the window. The first line is one.
9681 If the cursor was moved the view on the file will be updated
9682 first, this may cause a scroll.
9683
9684 *winnr()*
9685winnr([{arg}]) The result is a Number, which is the number of the current
9686 window. The top window has number 1.
9687 Returns zero for a popup window.
9688
9689 The optional argument {arg} supports the following values:
9690 $ the number of the last window (the window
9691 count).
9692 # the number of the last accessed window (where
9693 |CTRL-W_p| goes to). If there is no previous
9694 window or it is in another tab page 0 is
9695 returned.
9696 {N}j the number of the Nth window below the
9697 current window (where |CTRL-W_j| goes to).
9698 {N}k the number of the Nth window above the current
9699 window (where |CTRL-W_k| goes to).
9700 {N}h the number of the Nth window left of the
9701 current window (where |CTRL-W_h| goes to).
9702 {N}l the number of the Nth window right of the
9703 current window (where |CTRL-W_l| goes to).
9704 The number can be used with |CTRL-W_w| and ":wincmd w"
9705 |:wincmd|.
9706 Also see |tabpagewinnr()| and |win_getid()|.
9707 Examples: >
9708 let window_count = winnr('$')
9709 let prev_window = winnr('#')
9710 let wnum = winnr('3k')
9711
9712< Can also be used as a |method|: >
9713 GetWinval()->winnr()
9714<
9715 *winrestcmd()*
9716winrestcmd() Returns a sequence of |:resize| commands that should restore
9717 the current window sizes. Only works properly when no windows
9718 are opened or closed and the current window and tab page is
9719 unchanged.
9720 Example: >
9721 :let cmd = winrestcmd()
9722 :call MessWithWindowSizes()
9723 :exe cmd
9724<
9725 *winrestview()*
9726winrestview({dict})
9727 Uses the |Dictionary| returned by |winsaveview()| to restore
9728 the view of the current window.
9729 Note: The {dict} does not have to contain all values, that are
9730 returned by |winsaveview()|. If values are missing, those
9731 settings won't be restored. So you can use: >
9732 :call winrestview({'curswant': 4})
9733<
9734 This will only set the curswant value (the column the cursor
9735 wants to move on vertical movements) of the cursor to column 5
9736 (yes, that is 5), while all other settings will remain the
9737 same. This is useful, if you set the cursor position manually.
9738
9739 If you have changed the values the result is unpredictable.
9740 If the window size changed the result won't be the same.
9741
9742 Can also be used as a |method|: >
9743 GetView()->winrestview()
9744<
9745 *winsaveview()*
9746winsaveview() Returns a |Dictionary| that contains information to restore
9747 the view of the current window. Use |winrestview()| to
9748 restore the view.
9749 This is useful if you have a mapping that jumps around in the
9750 buffer and you want to go back to the original view.
9751 This does not save fold information. Use the 'foldenable'
9752 option to temporarily switch off folding, so that folds are
9753 not opened when moving around. This may have side effects.
9754 The return value includes:
9755 lnum cursor line number
9756 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +00009757 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009758 returns)
9759 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +00009760 curswant column for vertical movement (Note:
9761 the first column is zero, as opposed
9762 to what |getcurpos()| returns). After
9763 |$| command it will be a very large
9764 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009765 topline first line in the window
9766 topfill filler lines, only in diff mode
9767 leftcol first column displayed; only used when
9768 'wrap' is off
9769 skipcol columns skipped
9770 Note that no option values are saved.
9771
9772
9773winwidth({nr}) *winwidth()*
9774 The result is a Number, which is the width of window {nr}.
9775 {nr} can be the window number or the |window-ID|.
9776 When {nr} is zero, the width of the current window is
9777 returned. When window {nr} doesn't exist, -1 is returned.
9778 An existing window always has a width of zero or more.
9779 Examples: >
9780 :echo "The current window has " . winwidth(0) . " columns."
9781 :if winwidth(0) <= 50
9782 : 50 wincmd |
9783 :endif
9784< For getting the terminal or screen size, see the 'columns'
9785 option.
9786
9787 Can also be used as a |method|: >
9788 GetWinid()->winwidth()
9789
9790
9791wordcount() *wordcount()*
9792 The result is a dictionary of byte/chars/word statistics for
9793 the current buffer. This is the same info as provided by
9794 |g_CTRL-G|
9795 The return value includes:
9796 bytes Number of bytes in the buffer
9797 chars Number of chars in the buffer
9798 words Number of words in the buffer
9799 cursor_bytes Number of bytes before cursor position
9800 (not in Visual mode)
9801 cursor_chars Number of chars before cursor position
9802 (not in Visual mode)
9803 cursor_words Number of words before cursor position
9804 (not in Visual mode)
9805 visual_bytes Number of bytes visually selected
9806 (only in Visual mode)
9807 visual_chars Number of chars visually selected
9808 (only in Visual mode)
9809 visual_words Number of words visually selected
9810 (only in Visual mode)
9811
9812
9813 *writefile()*
9814writefile({object}, {fname} [, {flags}])
9815 When {object} is a |List| write it to file {fname}. Each list
9816 item is separated with a NL. Each list item must be a String
9817 or Number.
9818 When {flags} contains "b" then binary mode is used: There will
9819 not be a NL after the last list item. An empty item at the
9820 end does cause the last line in the file to end in a NL.
9821
9822 When {object} is a |Blob| write the bytes to file {fname}
9823 unmodified.
9824
9825 When {flags} contains "a" then append mode is used, lines are
9826 appended to the file: >
9827 :call writefile(["foo"], "event.log", "a")
9828 :call writefile(["bar"], "event.log", "a")
9829<
9830 When {flags} contains "s" then fsync() is called after writing
9831 the file. This flushes the file to disk, if possible. This
9832 takes more time but avoids losing the file if the system
9833 crashes.
9834 When {flags} does not contain "S" or "s" then fsync() is
9835 called if the 'fsync' option is set.
9836 When {flags} contains "S" then fsync() is not called, even
9837 when 'fsync' is set.
9838
9839 All NL characters are replaced with a NUL character.
9840 Inserting CR characters needs to be done before passing {list}
9841 to writefile().
9842 An existing file is overwritten, if possible.
9843 When the write fails -1 is returned, otherwise 0. There is an
9844 error message if the file can't be created or when writing
9845 fails.
9846 Also see |readfile()|.
9847 To copy a file byte for byte: >
9848 :let fl = readfile("foo", "b")
9849 :call writefile(fl, "foocopy", "b")
9850
9851< Can also be used as a |method|: >
9852 GetText()->writefile("thefile")
9853
9854
9855xor({expr}, {expr}) *xor()*
9856 Bitwise XOR on the two arguments. The arguments are converted
9857 to a number. A List, Dict or Float argument causes an error.
9858 Example: >
9859 :let bits = xor(bits, 0x80)
9860<
9861 Can also be used as a |method|: >
9862 :let bits = bits->xor(0x80)
9863<
9864
9865==============================================================================
98663. Feature list *feature-list*
9867
9868There are three types of features:
98691. Features that are only supported when they have been enabled when Vim
9870 was compiled |+feature-list|. Example: >
9871 :if has("cindent")
9872< *gui_running*
98732. Features that are only supported when certain conditions have been met.
9874 Example: >
9875 :if has("gui_running")
9876< *has-patch*
98773. Beyond a certain version or at a certain version and including a specific
9878 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
9879 later, or it is version 7.4 and patch 248 was included. Example: >
9880 :if has("patch-7.4.248")
9881< Note that it's possible for patch 248 to be omitted even though 249 is
9882 included. Only happens when cherry-picking patches.
9883 Note that this form only works for patch 7.4.237 and later, before that
9884 you need to check for the patch and the v:version. Example (checking
9885 version 6.2.148 or later): >
9886 :if v:version > 602 || (v:version == 602 && has("patch148"))
9887
9888Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
9889use: `if exists('+shellslash')`
9890
9891
9892acl Compiled with |ACL| support.
9893all_builtin_terms Compiled with all builtin terminals enabled.
9894amiga Amiga version of Vim.
9895arabic Compiled with Arabic support |Arabic|.
9896arp Compiled with ARP support (Amiga).
9897autocmd Compiled with autocommand support. (always true)
9898autochdir Compiled with support for 'autochdir'
9899autoservername Automatically enable |clientserver|
9900balloon_eval Compiled with |balloon-eval| support.
9901balloon_multiline GUI supports multiline balloons.
9902beos BeOS version of Vim.
9903browse Compiled with |:browse| support, and browse() will
9904 work.
9905browsefilter Compiled with support for |browsefilter|.
9906bsd Compiled on an OS in the BSD family (excluding macOS).
9907builtin_terms Compiled with some builtin terminals.
9908byte_offset Compiled with support for 'o' in 'statusline'
9909channel Compiled with support for |channel| and |job|
9910cindent Compiled with 'cindent' support.
9911clientserver Compiled with remote invocation support |clientserver|.
9912clipboard Compiled with 'clipboard' support.
9913clipboard_working Compiled with 'clipboard' support and it can be used.
9914cmdline_compl Compiled with |cmdline-completion| support.
9915cmdline_hist Compiled with |cmdline-history| support.
9916cmdline_info Compiled with 'showcmd' and 'ruler' support.
9917comments Compiled with |'comments'| support.
9918compatible Compiled to be very Vi compatible.
9919conpty Platform where |ConPTY| can be used.
9920cryptv Compiled with encryption support |encryption|.
9921cscope Compiled with |cscope| support.
9922cursorbind Compiled with |'cursorbind'| (always true)
9923debug Compiled with "DEBUG" defined.
9924dialog_con Compiled with console dialog support.
9925dialog_gui Compiled with GUI dialog support.
9926diff Compiled with |vimdiff| and 'diff' support.
9927digraphs Compiled with support for digraphs.
9928directx Compiled with support for DirectX and 'renderoptions'.
9929dnd Compiled with support for the "~ register |quote_~|.
9930drop_file Compiled with |drop_file| support.
9931ebcdic Compiled on a machine with ebcdic character set.
9932emacs_tags Compiled with support for Emacs tags.
9933eval Compiled with expression evaluation support. Always
9934 true, of course!
9935ex_extra |+ex_extra| (always true)
9936extra_search Compiled with support for |'incsearch'| and
9937 |'hlsearch'|
9938farsi Support for Farsi was removed |farsi|.
9939file_in_path Compiled with support for |gf| and |<cfile>|
9940filterpipe When 'shelltemp' is off pipes are used for shell
9941 read/write/filter commands
9942find_in_path Compiled with support for include file searches
9943 |+find_in_path|.
9944float Compiled with support for |Float|.
9945fname_case Case in file names matters (for Amiga and MS-Windows
9946 this is not present).
9947folding Compiled with |folding| support.
9948footer Compiled with GUI footer support. |gui-footer|
9949fork Compiled to use fork()/exec() instead of system().
9950gettext Compiled with message translation |multi-lang|
9951gui Compiled with GUI enabled.
9952gui_athena Compiled with Athena GUI.
9953gui_gnome Compiled with Gnome support (gui_gtk is also defined).
9954gui_gtk Compiled with GTK+ GUI (any version).
9955gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
9956gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
9957gui_haiku Compiled with Haiku GUI.
9958gui_mac Compiled with Macintosh GUI.
9959gui_motif Compiled with Motif GUI.
9960gui_photon Compiled with Photon GUI.
9961gui_running Vim is running in the GUI, or it will start soon.
9962gui_win32 Compiled with MS-Windows Win32 GUI.
9963gui_win32s idem, and Win32s system being used (Windows 3.1)
9964haiku Haiku version of Vim.
9965hangul_input Compiled with Hangul input support. |hangul|
9966hpux HP-UX version of Vim.
9967iconv Can use iconv() for conversion.
9968insert_expand Compiled with support for CTRL-X expansion commands in
9969 Insert mode. (always true)
9970job Compiled with support for |channel| and |job|
9971ipv6 Compiled with support for IPv6 networking in |channel|.
9972jumplist Compiled with |jumplist| support.
9973keymap Compiled with 'keymap' support.
9974lambda Compiled with |lambda| support.
9975langmap Compiled with 'langmap' support.
9976libcall Compiled with |libcall()| support.
9977linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
9978 'breakindent' support.
9979linux Linux version of Vim.
9980lispindent Compiled with support for lisp indenting.
9981listcmds Compiled with commands for the buffer list |:files|
9982 and the argument list |arglist|.
9983localmap Compiled with local mappings and abbr. |:map-local|
9984lua Compiled with Lua interface |Lua|.
9985mac Any Macintosh version of Vim cf. osx
9986macunix Synonym for osxdarwin
9987menu Compiled with support for |:menu|.
9988mksession Compiled with support for |:mksession|.
9989modify_fname Compiled with file name modifiers. |filename-modifiers|
9990 (always true)
9991mouse Compiled with support for mouse.
9992mouse_dec Compiled with support for Dec terminal mouse.
9993mouse_gpm Compiled with support for gpm (Linux console mouse)
9994mouse_gpm_enabled GPM mouse is working
9995mouse_netterm Compiled with support for netterm mouse.
9996mouse_pterm Compiled with support for qnx pterm mouse.
9997mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
9998mouse_sgr Compiled with support for sgr mouse.
9999mouse_urxvt Compiled with support for urxvt mouse.
10000mouse_xterm Compiled with support for xterm mouse.
10001mouseshape Compiled with support for 'mouseshape'.
10002multi_byte Compiled with support for 'encoding' (always true)
10003multi_byte_encoding 'encoding' is set to a multibyte encoding.
10004multi_byte_ime Compiled with support for IME input method.
10005multi_lang Compiled with support for multiple languages.
10006mzscheme Compiled with MzScheme interface |mzscheme|.
10007nanotime Compiled with sub-second time stamp checks.
10008netbeans_enabled Compiled with support for |netbeans| and connected.
10009netbeans_intg Compiled with support for |netbeans|.
10010num64 Compiled with 64-bit |Number| support.
10011ole Compiled with OLE automation support for Win32.
10012osx Compiled for macOS cf. mac
10013osxdarwin Compiled for macOS, with |mac-darwin-feature|
10014packages Compiled with |packages| support.
10015path_extra Compiled with up/downwards search in 'path' and 'tags'
10016perl Compiled with Perl interface.
10017persistent_undo Compiled with support for persistent undo history.
10018postscript Compiled with PostScript file printing.
10019printer Compiled with |:hardcopy| support.
10020profile Compiled with |:profile| support.
10021python Python 2.x interface available. |has-python|
10022python_compiled Compiled with Python 2.x interface. |has-python|
10023python_dynamic Python 2.x interface is dynamically loaded. |has-python|
10024python3 Python 3.x interface available. |has-python|
10025python3_compiled Compiled with Python 3.x interface. |has-python|
10026python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
10027pythonx Python 2.x and/or 3.x interface available. |python_x|
10028qnx QNX version of Vim.
10029quickfix Compiled with |quickfix| support.
10030reltime Compiled with |reltime()| support.
10031rightleft Compiled with 'rightleft' support.
10032ruby Compiled with Ruby interface |ruby|.
10033scrollbind Compiled with 'scrollbind' support. (always true)
10034showcmd Compiled with 'showcmd' support.
10035signs Compiled with |:sign| support.
10036smartindent Compiled with 'smartindent' support.
10037sodium Compiled with libsodium for better crypt support
10038sound Compiled with sound support, e.g. `sound_playevent()`
10039spell Compiled with spell checking support |spell|.
10040startuptime Compiled with |--startuptime| support.
10041statusline Compiled with support for 'statusline', 'rulerformat'
10042 and special formats of 'titlestring' and 'iconstring'.
10043sun SunOS version of Vim.
10044sun_workshop Support for Sun |workshop| has been removed.
10045syntax Compiled with syntax highlighting support |syntax|.
10046syntax_items There are active syntax highlighting items for the
10047 current buffer.
10048system Compiled to use system() instead of fork()/exec().
10049tag_binary Compiled with binary searching in tags files
10050 |tag-binary-search|.
10051tag_old_static Support for old static tags was removed, see
10052 |tag-old-static|.
10053tcl Compiled with Tcl interface.
10054termguicolors Compiled with true color in terminal support.
10055terminal Compiled with |terminal| support.
10056terminfo Compiled with terminfo instead of termcap.
10057termresponse Compiled with support for |t_RV| and |v:termresponse|.
10058textobjects Compiled with support for |text-objects|.
10059textprop Compiled with support for |text-properties|.
10060tgetent Compiled with tgetent support, able to use a termcap
10061 or terminfo file.
10062timers Compiled with |timer_start()| support.
10063title Compiled with window title support |'title'|.
10064toolbar Compiled with support for |gui-toolbar|.
10065ttyin input is a terminal (tty)
10066ttyout output is a terminal (tty)
10067unix Unix version of Vim. *+unix*
10068unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
10069user_commands User-defined commands. (always true)
10070vartabs Compiled with variable tabstop support |'vartabstop'|.
10071vcon Win32: Virtual console support is working, can use
10072 'termguicolors'. Also see |+vtp|.
10073vertsplit Compiled with vertically split windows |:vsplit|.
10074 (always true)
10075vim_starting True while initial source'ing takes place. |startup|
10076 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000010077vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010078viminfo Compiled with viminfo support.
10079vimscript-1 Compiled Vim script version 1 support
10080vimscript-2 Compiled Vim script version 2 support
10081vimscript-3 Compiled Vim script version 3 support
10082virtualedit Compiled with 'virtualedit' option. (always true)
10083visual Compiled with Visual mode. (always true)
10084visualextra Compiled with extra Visual mode commands. (always
10085 true) |blockwise-operators|.
10086vms VMS version of Vim.
10087vreplace Compiled with |gR| and |gr| commands. (always true)
10088vtp Compiled for vcon support |+vtp| (check vcon to find
10089 out if it works in the current console).
10090wildignore Compiled with 'wildignore' option.
10091wildmenu Compiled with 'wildmenu' option.
10092win16 old version for MS-Windows 3.1 (always false)
10093win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
10094 64 bits)
10095win32unix Win32 version of Vim, using Unix files (Cygwin)
10096win64 Win64 version of Vim (MS-Windows 64 bit).
10097win95 Win32 version for MS-Windows 95/98/ME (always false)
10098winaltkeys Compiled with 'winaltkeys' option.
10099windows Compiled with support for more than one window.
10100 (always true)
10101writebackup Compiled with 'writebackup' default on.
10102xfontset Compiled with X fontset support |xfontset|.
10103xim Compiled with X input method support |xim|.
10104xpm Compiled with pixmap support.
10105xpm_w32 Compiled with pixmap support for Win32. (Only for
10106 backward compatibility. Use "xpm" instead.)
10107xsmp Compiled with X session management support.
10108xsmp_interact Compiled with interactive X session management support.
10109xterm_clipboard Compiled with support for xterm clipboard.
10110xterm_save Compiled with support for saving and restoring the
10111 xterm screen.
10112x11 Compiled with X11 support.
10113
10114
10115==============================================================================
101164. Matching a pattern in a String *string-match*
10117
10118This is common between several functions. A regexp pattern as explained at
10119|pattern| is normally used to find a match in the buffer lines. When a
10120pattern is used to find a match in a String, almost everything works in the
10121same way. The difference is that a String is handled like it is one line.
10122When it contains a "\n" character, this is not seen as a line break for the
10123pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
10124>
10125 :let a = "aaaa\nxxxx"
10126 :echo matchstr(a, "..\n..")
10127 aa
10128 xx
10129 :echo matchstr(a, "a.x")
10130 a
10131 x
10132
10133Don't forget that "^" will only match at the first character of the String and
10134"$" at the last character of the string. They don't match after or before a
10135"\n".
10136
10137 vim:tw=78:ts=8:noet:ft=help:norl: