blob: 3c0f143c5179fd71151956d598df6c46100fb26f [file] [log] [blame]
Bram Moolenaareb490412022-06-28 13:44:46 +01001*builtin.txt* For Vim version 9.0. Last change: 2022 Jun 27
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}
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +010063autocmd_add({acmds}) Bool add a list of autocmds and groups
64autocmd_delete({acmds}) Bool delete a list of autocmds and groups
65autocmd_get([{opts}]) List return a list of autocmds
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000066balloon_gettext() String current text in the balloon
67balloon_show({expr}) none show {expr} inside the balloon
68balloon_split({msg}) List split {msg} as used for a balloon
69blob2list({blob}) List convert {blob} into a list of numbers
70browse({save}, {title}, {initdir}, {default})
71 String put up a file requester
72browsedir({title}, {initdir}) String put up a directory requester
73bufadd({name}) Number add a buffer to the buffer list
74bufexists({buf}) Number |TRUE| if buffer {buf} exists
75buflisted({buf}) Number |TRUE| if buffer {buf} is listed
76bufload({buf}) Number load buffer {buf} if not loaded yet
77bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
78bufname([{buf}]) String Name of the buffer {buf}
79bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
80bufwinid({buf}) Number window ID of buffer {buf}
81bufwinnr({buf}) Number window number of buffer {buf}
82byte2line({byte}) Number line number at byte count {byte}
83byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
84byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
85call({func}, {arglist} [, {dict}])
86 any call {func} with arguments {arglist}
87ceil({expr}) Float round {expr} up
88ch_canread({handle}) Number check if there is something to read
89ch_close({handle}) none close {handle}
90ch_close_in({handle}) none close in part of {handle}
91ch_evalexpr({handle}, {expr} [, {options}])
92 any evaluate {expr} on JSON {handle}
93ch_evalraw({handle}, {string} [, {options}])
94 any evaluate {string} on raw {handle}
95ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
96ch_getjob({channel}) Job get the Job of {channel}
97ch_info({handle}) String info about channel {handle}
98ch_log({msg} [, {handle}]) none write {msg} in the channel log file
99ch_logfile({fname} [, {mode}]) none start logging channel activity
100ch_open({address} [, {options}])
101 Channel open a channel to {address}
102ch_read({handle} [, {options}]) String read from {handle}
103ch_readblob({handle} [, {options}])
104 Blob read Blob from {handle}
105ch_readraw({handle} [, {options}])
106 String read raw from {handle}
107ch_sendexpr({handle}, {expr} [, {options}])
108 any send {expr} over JSON {handle}
109ch_sendraw({handle}, {expr} [, {options}])
110 any send {expr} over raw {handle}
111ch_setoptions({handle}, {options})
112 none set options for {handle}
113ch_status({handle} [, {options}])
114 String status of channel {handle}
115changenr() Number current change number
116char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
117charclass({string}) Number character class of {string}
118charcol({expr}) Number column number of cursor or mark
119charidx({string}, {idx} [, {countcc}])
120 Number char index of byte {idx} in {string}
121chdir({dir}) String change current working directory
122cindent({lnum}) Number C indent for line {lnum}
123clearmatches([{win}]) none clear all matches
124col({expr}) Number column byte index of cursor or mark
125complete({startcol}, {matches}) none set Insert mode completion
126complete_add({expr}) Number add completion match
127complete_check() Number check for key typed during completion
128complete_info([{what}]) Dict get current completion information
129confirm({msg} [, {choices} [, {default} [, {type}]]])
130 Number number of choice picked by user
131copy({expr}) any make a shallow copy of {expr}
132cos({expr}) Float cosine of {expr}
133cosh({expr}) Float hyperbolic cosine of {expr}
134count({comp}, {expr} [, {ic} [, {start}]])
135 Number count how many {expr} are in {comp}
136cscope_connection([{num}, {dbpath} [, {prepend}]])
137 Number checks existence of cscope connection
138cursor({lnum}, {col} [, {off}])
139 Number move cursor to {lnum}, {col}, {off}
140cursor({list}) Number move cursor to position in {list}
141debugbreak({pid}) Number interrupt process being debugged
142deepcopy({expr} [, {noref}]) any make a full copy of {expr}
143delete({fname} [, {flags}]) Number delete the file or directory {fname}
144deletebufline({buf}, {first} [, {last}])
145 Number delete lines from buffer {buf}
146did_filetype() Number |TRUE| if FileType autocmd event used
147diff_filler({lnum}) Number diff filler lines about {lnum}
148diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
149digraph_get({chars}) String get the |digraph| of {chars}
150digraph_getlist([{listall}]) List get all |digraph|s
151digraph_set({chars}, {digraph}) Boolean register |digraph|
152digraph_setlist({digraphlist}) Boolean register multiple |digraph|s
153echoraw({expr}) none output {expr} as-is
154empty({expr}) Number |TRUE| if {expr} is empty
155environ() Dict return environment variables
156escape({string}, {chars}) String escape {chars} in {string} with '\'
157eval({string}) any evaluate {string} into its value
158eventhandler() Number |TRUE| if inside an event handler
159executable({expr}) Number 1 if executable {expr} exists
160execute({command}) String execute {command} and get the output
161exepath({expr}) String full path of the command {expr}
162exists({expr}) Number |TRUE| if {expr} exists
163exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
164exp({expr}) Float exponential of {expr}
165expand({expr} [, {nosuf} [, {list}]])
166 any expand special keywords in {expr}
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +0100167expandcmd({string} [, {options}])
168 String expand {string} like with `:edit`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000169extend({expr1}, {expr2} [, {expr3}])
170 List/Dict insert items of {expr2} into {expr1}
171extendnew({expr1}, {expr2} [, {expr3}])
172 List/Dict like |extend()| but creates a new
173 List or Dictionary
174feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
175filereadable({file}) Number |TRUE| if {file} is a readable file
176filewritable({file}) Number |TRUE| if {file} is a writable file
177filter({expr1}, {expr2}) List/Dict/Blob/String
178 remove items from {expr1} where
179 {expr2} is 0
180finddir({name} [, {path} [, {count}]])
181 String find directory {name} in {path}
182findfile({name} [, {path} [, {count}]])
183 String find file {name} in {path}
184flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
185flattennew({list} [, {maxdepth}])
186 List flatten a copy of {list}
187float2nr({expr}) Number convert Float {expr} to a Number
188floor({expr}) Float round {expr} down
189fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
190fnameescape({fname}) String escape special characters in {fname}
191fnamemodify({fname}, {mods}) String modify file name
192foldclosed({lnum}) Number first line of fold at {lnum} if closed
193foldclosedend({lnum}) Number last line of fold at {lnum} if closed
194foldlevel({lnum}) Number fold level at {lnum}
195foldtext() String line displayed for closed fold
196foldtextresult({lnum}) String text for closed fold at {lnum}
197foreground() Number bring the Vim window to the foreground
198fullcommand({name}) String get full command from {name}
199funcref({name} [, {arglist}] [, {dict}])
200 Funcref reference to function {name}
201function({name} [, {arglist}] [, {dict}])
202 Funcref named reference to function {name}
203garbagecollect([{atexit}]) none free memory, breaking cyclic references
204get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
205get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
206get({func}, {what}) any get property of funcref/partial {func}
207getbufinfo([{buf}]) List information about buffers
208getbufline({buf}, {lnum} [, {end}])
209 List lines {lnum} to {end} of buffer {buf}
210getbufvar({buf}, {varname} [, {def}])
211 any variable {varname} in buffer {buf}
212getchangelist([{buf}]) List list of change list items
213getchar([expr]) Number or String
214 get one character from the user
215getcharmod() Number modifiers for the last typed character
216getcharpos({expr}) List position of cursor, mark, etc.
217getcharsearch() Dict last character search
218getcharstr([expr]) String get one character from the user
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100219getcmdcompltype() String return the type of the current
220 command-line completion
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000221getcmdline() String return the current command-line
222getcmdpos() Number return cursor position in command-line
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100223getcmdscreenpos() Number return cursor screen position in
224 command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000225getcmdtype() String return current command-line type
226getcmdwintype() String return current command-line window type
227getcompletion({pat}, {type} [, {filtered}])
228 List list of cmdline completion matches
229getcurpos([{winnr}]) List position of the cursor
230getcursorcharpos([{winnr}]) List character position of the cursor
231getcwd([{winnr} [, {tabnr}]]) String get the current working directory
232getenv({name}) String return environment variable
233getfontname([{name}]) String name of font being used
234getfperm({fname}) String file permissions of file {fname}
235getfsize({fname}) Number size in bytes of file {fname}
236getftime({fname}) Number last modification time of file
237getftype({fname}) String description of type of file {fname}
238getimstatus() Number |TRUE| if the IME status is active
239getjumplist([{winnr} [, {tabnr}]])
240 List list of jump list items
241getline({lnum}) String line {lnum} of current buffer
242getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
243getloclist({nr}) List list of location list items
244getloclist({nr}, {what}) Dict get specific location list properties
245getmarklist([{buf}]) List list of global/local marks
246getmatches([{win}]) List list of current matches
247getmousepos() Dict last known mouse position
248getpid() Number process ID of Vim
249getpos({expr}) List position of cursor, mark, etc.
250getqflist() List list of quickfix items
251getqflist({what}) Dict get specific quickfix list properties
252getreg([{regname} [, 1 [, {list}]]])
253 String or List contents of a register
254getreginfo([{regname}]) Dict information about a register
255getregtype([{regname}]) String type of a register
256gettabinfo([{expr}]) List list of tab pages
257gettabvar({nr}, {varname} [, {def}])
258 any variable {varname} in tab {nr} or {def}
259gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
260 any {name} in {winnr} in tab page {tabnr}
261gettagstack([{nr}]) Dict get the tag stack of window {nr}
262gettext({text}) String lookup translation of {text}
263getwininfo([{winid}]) List list of info about each window
264getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
265getwinposx() Number X coord in pixels of the Vim window
266getwinposy() Number Y coord in pixels of the Vim window
267getwinvar({nr}, {varname} [, {def}])
268 any variable {varname} in window {nr}
269glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
270 any expand file wildcards in {expr}
271glob2regpat({expr}) String convert a glob pat into a search pat
272globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
273 String do glob({expr}) for all dirs in {path}
274has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
275has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
276haslocaldir([{winnr} [, {tabnr}]])
277 Number |TRUE| if the window executed |:lcd|
278 or |:tcd|
279hasmapto({what} [, {mode} [, {abbr}]])
280 Number |TRUE| if mapping to {what} exists
281histadd({history}, {item}) Number add an item to a history
282histdel({history} [, {item}]) Number remove an item from a history
283histget({history} [, {index}]) String get the item {index} from a history
284histnr({history}) Number highest index of a history
285hlID({name}) Number syntax ID of highlight group {name}
286hlexists({name}) Number |TRUE| if highlight group {name} exists
287hlget([{name} [, {resolve}]]) List get highlight group attributes
288hlset({list}) Number set highlight group attributes
289hostname() String name of the machine Vim is running on
290iconv({expr}, {from}, {to}) String convert encoding of {expr}
291indent({lnum}) Number indent of line {lnum}
292index({object}, {expr} [, {start} [, {ic}]])
293 Number index in {object} where {expr} appears
Yegappan Lakshmananb2186552022-08-13 13:09:20 +0100294indexof({object}, {expr} [, {opts}]])
295 Number index in {object} where {expr} is true
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000296input({prompt} [, {text} [, {completion}]])
297 String get input from the user
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100298inputdialog({prompt} [, {text} [, {cancelreturn}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000299 String like input() but in a GUI dialog
300inputlist({textlist}) Number let the user pick from a choice list
301inputrestore() Number restore typeahead
302inputsave() Number save and clear typeahead
303inputsecret({prompt} [, {text}]) String like input() but hiding the text
304insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
305interrupt() none interrupt script execution
306invert({expr}) Number bitwise invert
LemonBoydca1d402022-04-28 15:26:33 +0100307isabsolutepath({path}) Number |TRUE| if {path} is an absolute path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000308isdirectory({directory}) Number |TRUE| if {directory} is a directory
309isinf({expr}) Number determine if {expr} is infinity value
310 (positive or negative)
311islocked({expr}) Number |TRUE| if {expr} is locked
312isnan({expr}) Number |TRUE| if {expr} is NaN
313items({dict}) List key-value pairs in {dict}
314job_getchannel({job}) Channel get the channel handle for {job}
315job_info([{job}]) Dict get information about {job}
316job_setoptions({job}, {options}) none set options for {job}
317job_start({command} [, {options}])
318 Job start a job
319job_status({job}) String get the status of {job}
320job_stop({job} [, {how}]) Number stop {job}
321join({list} [, {sep}]) String join {list} items into one String
322js_decode({string}) any decode JS style JSON
323js_encode({expr}) String encode JS style JSON
324json_decode({string}) any decode JSON
325json_encode({expr}) String encode JSON
326keys({dict}) List keys in {dict}
327len({expr}) Number the length of {expr}
328libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
329libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
330line({expr} [, {winid}]) Number line nr of cursor, last line or mark
331line2byte({lnum}) Number byte count of line {lnum}
332lispindent({lnum}) Number Lisp indent for line {lnum}
333list2blob({list}) Blob turn {list} of numbers into a Blob
334list2str({list} [, {utf8}]) String turn {list} of numbers into a String
335listener_add({callback} [, {buf}])
336 Number add a callback to listen to changes
337listener_flush([{buf}]) none invoke listener callbacks
338listener_remove({id}) none remove a listener callback
339localtime() Number current time
340log({expr}) Float natural logarithm (base e) of {expr}
341log10({expr}) Float logarithm of Float {expr} to base 10
342luaeval({expr} [, {expr}]) any evaluate |Lua| expression
343map({expr1}, {expr2}) List/Dict/Blob/String
344 change each item in {expr1} to {expr2}
345maparg({name} [, {mode} [, {abbr} [, {dict}]]])
346 String or Dict
347 rhs of mapping {name} in mode {mode}
348mapcheck({name} [, {mode} [, {abbr}]])
349 String check for mappings matching {name}
Ernie Rael09661202022-04-25 14:40:44 +0100350maplist([{abbr}]) List list of all mappings, a dict for each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000351mapnew({expr1}, {expr2}) List/Dict/Blob/String
352 like |map()| but creates a new List or
353 Dictionary
354mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
355match({expr}, {pat} [, {start} [, {count}]])
356 Number position where {pat} matches in {expr}
357matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
358 Number highlight {pattern} with {group}
359matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
360 Number highlight positions with {group}
361matcharg({nr}) List arguments of |:match|
362matchdelete({id} [, {win}]) Number delete match identified by {id}
363matchend({expr}, {pat} [, {start} [, {count}]])
364 Number position where {pat} ends in {expr}
365matchfuzzy({list}, {str} [, {dict}])
366 List fuzzy match {str} in {list}
367matchfuzzypos({list}, {str} [, {dict}])
368 List fuzzy match {str} in {list}
369matchlist({expr}, {pat} [, {start} [, {count}]])
370 List match and submatches of {pat} in {expr}
371matchstr({expr}, {pat} [, {start} [, {count}]])
372 String {count}'th match of {pat} in {expr}
373matchstrpos({expr}, {pat} [, {start} [, {count}]])
374 List {count}'th match of {pat} in {expr}
375max({expr}) Number maximum value of items in {expr}
376menu_info({name} [, {mode}]) Dict get menu item information
377min({expr}) Number minimum value of items in {expr}
378mkdir({name} [, {path} [, {prot}]])
379 Number create directory {name}
380mode([expr]) String current editing mode
381mzeval({expr}) any evaluate |MzScheme| expression
382nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
383nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
384or({expr}, {expr}) Number bitwise OR
385pathshorten({expr} [, {len}]) String shorten directory names in a path
386perleval({expr}) any evaluate |Perl| expression
387popup_atcursor({what}, {options}) Number create popup window near the cursor
388popup_beval({what}, {options}) Number create popup window for 'ballooneval'
389popup_clear() none close all popup windows
390popup_close({id} [, {result}]) none close popup window {id}
391popup_create({what}, {options}) Number create a popup window
392popup_dialog({what}, {options}) Number create a popup window used as a dialog
393popup_filter_menu({id}, {key}) Number filter for a menu popup window
394popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
395popup_findinfo() Number get window ID of info popup window
396popup_findpreview() Number get window ID of preview popup window
397popup_getoptions({id}) Dict get options of popup window {id}
398popup_getpos({id}) Dict get position of popup window {id}
399popup_hide({id}) none hide popup menu {id}
400popup_list() List get a list of window IDs of all popups
401popup_locate({row}, {col}) Number get window ID of popup at position
402popup_menu({what}, {options}) Number create a popup window used as a menu
403popup_move({id}, {options}) none set position of popup window {id}
404popup_notification({what}, {options})
405 Number create a notification popup window
406popup_setoptions({id}, {options})
407 none set options for popup window {id}
408popup_settext({id}, {text}) none set the text of popup window {id}
409popup_show({id}) none unhide popup window {id}
410pow({x}, {y}) Float {x} to the power of {y}
411prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
412printf({fmt}, {expr1}...) String format text
413prompt_getprompt({buf}) String get prompt text
414prompt_setcallback({buf}, {expr}) none set prompt callback function
415prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
416prompt_setprompt({buf}, {text}) none set prompt text
417prop_add({lnum}, {col}, {props}) none add one text property
418prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
419 none add multiple text properties
420prop_clear({lnum} [, {lnum-end} [, {props}]])
421 none remove all text properties
422prop_find({props} [, {direction}])
423 Dict search for a text property
424prop_list({lnum} [, {props}]) List text properties in {lnum}
425prop_remove({props} [, {lnum} [, {lnum-end}]])
426 Number remove a text property
427prop_type_add({name}, {props}) none define a new property type
428prop_type_change({name}, {props})
429 none change an existing property type
430prop_type_delete({name} [, {props}])
431 none delete a property type
432prop_type_get({name} [, {props}])
433 Dict get property type values
434prop_type_list([{props}]) List get list of property types
435pum_getpos() Dict position and size of pum if visible
436pumvisible() Number whether popup menu is visible
437py3eval({expr}) any evaluate |python3| expression
438pyeval({expr}) any evaluate |Python| expression
439pyxeval({expr}) any evaluate |python_x| expression
440rand([{expr}]) Number get pseudo-random number
441range({expr} [, {max} [, {stride}]])
442 List items from {expr} to {max}
443readblob({fname}) Blob read a |Blob| from {fname}
444readdir({dir} [, {expr} [, {dict}]])
445 List file names in {dir} selected by {expr}
446readdirex({dir} [, {expr} [, {dict}]])
447 List file info in {dir} selected by {expr}
448readfile({fname} [, {type} [, {max}]])
449 List get list of lines from file {fname}
450reduce({object}, {func} [, {initial}])
451 any reduce {object} using {func}
452reg_executing() String get the executing register name
453reg_recording() String get the recording register name
454reltime([{start} [, {end}]]) List get time value
455reltimefloat({time}) Float turn the time value into a Float
456reltimestr({time}) String turn time value into a String
457remote_expr({server}, {string} [, {idvar} [, {timeout}]])
458 String send expression
459remote_foreground({server}) Number bring Vim server to the foreground
460remote_peek({serverid} [, {retvar}])
461 Number check for reply string
462remote_read({serverid} [, {timeout}])
463 String read reply string
464remote_send({server}, {string} [, {idvar}])
465 String send key sequence
466remote_startserver({name}) none become server {name}
467remove({list}, {idx} [, {end}]) any/List
468 remove items {idx}-{end} from {list}
469remove({blob}, {idx} [, {end}]) Number/Blob
470 remove bytes {idx}-{end} from {blob}
471remove({dict}, {key}) any remove entry {key} from {dict}
472rename({from}, {to}) Number rename (move) file from {from} to {to}
473repeat({expr}, {count}) String repeat {expr} {count} times
474resolve({filename}) String get filename a shortcut points to
475reverse({list}) List reverse {list} in-place
476round({expr}) Float round off {expr}
477rubyeval({expr}) any evaluate |Ruby| expression
478screenattr({row}, {col}) Number attribute at screen position
479screenchar({row}, {col}) Number character at screen position
480screenchars({row}, {col}) List List of characters at screen position
481screencol() Number current cursor column
482screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
483screenrow() Number current cursor row
484screenstring({row}, {col}) String characters at screen position
485search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
486 Number search for {pattern}
487searchcount([{options}]) Dict get or update search stats
488searchdecl({name} [, {global} [, {thisblock}]])
489 Number search for variable declaration
490searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
491 Number search for other end of start/end pair
492searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
493 List search for other end of start/end pair
494searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
495 List search for {pattern}
496server2client({clientid}, {string})
497 Number send reply string
498serverlist() String get a list of available servers
499setbufline({expr}, {lnum}, {text})
500 Number set line {lnum} to {text} in buffer
501 {expr}
502setbufvar({buf}, {varname}, {val})
503 none set {varname} in buffer {buf} to {val}
504setcellwidths({list}) none set character cell width overrides
505setcharpos({expr}, {list}) Number set the {expr} position to {list}
506setcharsearch({dict}) Dict set character search from {dict}
507setcmdpos({pos}) Number set cursor position in command-line
508setcursorcharpos({list}) Number move cursor to position in {list}
509setenv({name}, {val}) none set environment variable
510setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
511setline({lnum}, {line}) Number set line {lnum} to {line}
512setloclist({nr}, {list} [, {action}])
513 Number modify location list using {list}
514setloclist({nr}, {list}, {action}, {what})
515 Number modify specific location list props
516setmatches({list} [, {win}]) Number restore a list of matches
517setpos({expr}, {list}) Number set the {expr} position to {list}
518setqflist({list} [, {action}]) Number modify quickfix list using {list}
519setqflist({list}, {action}, {what})
520 Number modify specific quickfix list props
521setreg({n}, {v} [, {opt}]) Number set register to value and type
522settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
523settabwinvar({tabnr}, {winnr}, {varname}, {val})
524 none set {varname} in window {winnr} in tab
525 page {tabnr} to {val}
526settagstack({nr}, {dict} [, {action}])
527 Number modify tag stack using {dict}
528setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
529sha256({string}) String SHA256 checksum of {string}
530shellescape({string} [, {special}])
531 String escape {string} for use as shell
532 command argument
533shiftwidth([{col}]) Number effective value of 'shiftwidth'
534sign_define({name} [, {dict}]) Number define or update a sign
535sign_define({list}) List define or update a list of signs
536sign_getdefined([{name}]) List get a list of defined signs
537sign_getplaced([{buf} [, {dict}]])
538 List get a list of placed signs
539sign_jump({id}, {group}, {buf})
540 Number jump to a sign
541sign_place({id}, {group}, {name}, {buf} [, {dict}])
542 Number place a sign
543sign_placelist({list}) List place a list of signs
544sign_undefine([{name}]) Number undefine a sign
545sign_undefine({list}) List undefine a list of signs
546sign_unplace({group} [, {dict}])
547 Number unplace a sign
548sign_unplacelist({list}) List unplace a list of signs
549simplify({filename}) String simplify filename as much as possible
550sin({expr}) Float sine of {expr}
551sinh({expr}) Float hyperbolic sine of {expr}
552slice({expr}, {start} [, {end}]) String, List or Blob
553 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000554sort({list} [, {how} [, {dict}]])
555 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000556sound_clear() none stop playing all sounds
557sound_playevent({name} [, {callback}])
558 Number play an event sound
559sound_playfile({path} [, {callback}])
560 Number play sound file {path}
561sound_stop({id}) none stop playing sound {id}
562soundfold({word}) String sound-fold {word}
563spellbadword() String badly spelled word at cursor
564spellsuggest({word} [, {max} [, {capital}]])
565 List spelling suggestions
566split({expr} [, {pat} [, {keepempty}]])
567 List make |List| from {pat} separated {expr}
568sqrt({expr}) Float square root of {expr}
569srand([{expr}]) List get seed for |rand()|
570state([{what}]) String current state of Vim
571str2float({expr} [, {quoted}]) Float convert String to Float
572str2list({expr} [, {utf8}]) List convert each character of {expr} to
573 ASCII/UTF-8 value
574str2nr({expr} [, {base} [, {quoted}]])
575 Number convert String to Number
576strcharlen({expr}) Number character length of the String {expr}
577strcharpart({str}, {start} [, {len} [, {skipcc}]])
578 String {len} characters of {str} at
579 character {start}
580strchars({expr} [, {skipcc}]) Number character count of the String {expr}
581strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
582strftime({format} [, {time}]) String format time with a specified format
583strgetchar({str}, {index}) Number get char {index} from {str}
584stridx({haystack}, {needle} [, {start}])
585 Number index of {needle} in {haystack}
586string({expr}) String String representation of {expr} value
587strlen({expr}) Number length of the String {expr}
588strpart({str}, {start} [, {len} [, {chars}]])
589 String {len} bytes/chars of {str} at
590 byte {start}
591strptime({format}, {timestring})
592 Number Convert {timestring} to unix timestamp
593strridx({haystack}, {needle} [, {start}])
594 Number last index of {needle} in {haystack}
595strtrans({expr}) String translate string to make it printable
596strwidth({expr}) Number display cell length of the String {expr}
597submatch({nr} [, {list}]) String or List
598 specific match in ":s" or substitute()
599substitute({expr}, {pat}, {sub}, {flags})
600 String all {pat} in {expr} replaced with {sub}
601swapinfo({fname}) Dict information about swap file {fname}
602swapname({buf}) String swap file of buffer {buf}
603synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
604synIDattr({synID}, {what} [, {mode}])
605 String attribute {what} of syntax ID {synID}
606synIDtrans({synID}) Number translated syntax ID of {synID}
607synconcealed({lnum}, {col}) List info about concealing
608synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
609system({expr} [, {input}]) String output of shell command/filter {expr}
610systemlist({expr} [, {input}]) List output of shell command/filter {expr}
611tabpagebuflist([{arg}]) List list of buffer numbers in tab page
612tabpagenr([{arg}]) Number number of current or last tab page
613tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
614tagfiles() List tags files used
615taglist({expr} [, {filename}]) List list of tags matching {expr}
616tan({expr}) Float tangent of {expr}
617tanh({expr}) Float hyperbolic tangent of {expr}
618tempname() String name for a temporary file
619term_dumpdiff({filename}, {filename} [, {options}])
620 Number display difference between two dumps
621term_dumpload({filename} [, {options}])
622 Number displaying a screen dump
623term_dumpwrite({buf}, {filename} [, {options}])
624 none dump terminal window contents
625term_getaltscreen({buf}) Number get the alternate screen flag
626term_getansicolors({buf}) List get ANSI palette in GUI color mode
627term_getattr({attr}, {what}) Number get the value of attribute {what}
628term_getcursor({buf}) List get the cursor position of a terminal
629term_getjob({buf}) Job get the job associated with a terminal
630term_getline({buf}, {row}) String get a line of text from a terminal
631term_getscrolled({buf}) Number get the scroll count of a terminal
632term_getsize({buf}) List get the size of a terminal
633term_getstatus({buf}) String get the status of a terminal
634term_gettitle({buf}) String get the title of a terminal
635term_gettty({buf}, [{input}]) String get the tty name of a terminal
636term_list() List get the list of terminal buffers
637term_scrape({buf}, {row}) List get row of a terminal screen
638term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
639term_setansicolors({buf}, {colors})
640 none set ANSI palette in GUI color mode
641term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
642term_setkill({buf}, {how}) none set signal to stop job in terminal
643term_setrestore({buf}, {command}) none set command to restore terminal
644term_setsize({buf}, {rows}, {cols})
645 none set the size of a terminal
646term_start({cmd} [, {options}]) Number open a terminal window and run a job
647term_wait({buf} [, {time}]) Number wait for screen to be updated
648terminalprops() Dict properties of the terminal
649test_alloc_fail({id}, {countdown}, {repeat})
650 none make memory allocation fail
651test_autochdir() none enable 'autochdir' during startup
652test_feedinput({string}) none add key sequence to input buffer
653test_garbagecollect_now() none free memory right now for testing
654test_garbagecollect_soon() none free memory soon for testing
655test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000656test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000657test_ignore_error({expr}) none ignore a specific error
658test_null_blob() Blob null value for testing
659test_null_channel() Channel null value for testing
660test_null_dict() Dict null value for testing
661test_null_function() Funcref null value for testing
662test_null_job() Job null value for testing
663test_null_list() List null value for testing
664test_null_partial() Funcref null value for testing
665test_null_string() String null value for testing
666test_option_not_set({name}) none reset flag indicating option was set
667test_override({expr}, {val}) none test with Vim internal overrides
668test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000669test_setmouse({row}, {col}) none set the mouse position for testing
670test_settime({expr}) none set current time for testing
671test_srand_seed([seed]) none set seed for testing srand()
672test_unknown() any unknown value for testing
673test_void() any void value for testing
674timer_info([{id}]) List information about timers
675timer_pause({id}, {pause}) none pause or unpause a timer
676timer_start({time}, {callback} [, {options}])
677 Number create a timer
678timer_stop({timer}) none stop a timer
679timer_stopall() none stop all timers
680tolower({expr}) String the String {expr} switched to lowercase
681toupper({expr}) String the String {expr} switched to uppercase
682tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
683 to chars in {tostr}
684trim({text} [, {mask} [, {dir}]])
685 String trim characters in {mask} from {text}
686trunc({expr}) Float truncate Float {expr}
687type({expr}) Number type of value {expr}
688typename({expr}) String representation of the type of {expr}
689undofile({name}) String undo file name for {name}
690undotree() List undo file tree
691uniq({list} [, {func} [, {dict}]])
692 List remove adjacent duplicates from a list
693values({dict}) List values in {dict}
LemonBoy0f7a3e12022-05-26 12:10:37 +0100694virtcol({expr} [, {list}]) Number or List
695 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100696virtcol2col({winid}, {lnum}, {col})
697 Number byte index of a character on screen
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000698visualmode([expr]) String last visual mode used
699wildmenumode() Number whether 'wildmenu' mode is active
700win_execute({id}, {command} [, {silent}])
701 String execute {command} in window {id}
702win_findbuf({bufnr}) List find windows containing {bufnr}
703win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
704win_gettype([{nr}]) String type of window {nr}
705win_gotoid({expr}) Number go to window with ID {expr}
706win_id2tabwin({expr}) List get tab and window nr from window ID
707win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000708win_move_separator({nr}) Number move window vertical separator
709win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000710win_screenpos({nr}) List get screen position of window {nr}
711win_splitmove({nr}, {target} [, {options}])
712 Number move window {nr} to split of {target}
713winbufnr({nr}) Number buffer number of window {nr}
714wincol() Number window column of the cursor
715windowsversion() String MS-Windows OS version
716winheight({nr}) Number height of window {nr}
717winlayout([{tabnr}]) List layout of windows in tab {tabnr}
718winline() Number window line of the cursor
719winnr([{expr}]) Number number of current window
720winrestcmd() String returns command to restore window sizes
721winrestview({dict}) none restore view of current window
722winsaveview() Dict save view of current window
723winwidth({nr}) Number width of window {nr}
724wordcount() Dict get byte/char/word statistics
725writefile({object}, {fname} [, {flags}])
726 Number write |Blob| or |List| of lines to file
727xor({expr}, {expr}) Number bitwise XOR
728
729==============================================================================
7302. Details *builtin-function-details*
731
732Not all functions are here, some have been moved to a help file covering the
733specific functionality.
734
735abs({expr}) *abs()*
736 Return the absolute value of {expr}. When {expr} evaluates to
737 a |Float| abs() returns a |Float|. When {expr} can be
738 converted to a |Number| abs() returns a |Number|. Otherwise
739 abs() gives an error message and returns -1.
740 Examples: >
741 echo abs(1.456)
742< 1.456 >
743 echo abs(-5.456)
744< 5.456 >
745 echo abs(-4)
746< 4
747
748 Can also be used as a |method|: >
749 Compute()->abs()
750
751< {only available when compiled with the |+float| feature}
752
753
754acos({expr}) *acos()*
755 Return the arc cosine of {expr} measured in radians, as a
756 |Float| in the range of [0, pi].
757 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100758 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000759 Examples: >
760 :echo acos(0)
761< 1.570796 >
762 :echo acos(-0.5)
763< 2.094395
764
765 Can also be used as a |method|: >
766 Compute()->acos()
767
768< {only available when compiled with the |+float| feature}
769
770
771add({object}, {expr}) *add()*
772 Append the item {expr} to |List| or |Blob| {object}. Returns
773 the resulting |List| or |Blob|. Examples: >
774 :let alist = add([1, 2, 3], item)
775 :call add(mylist, "woodstock")
776< Note that when {expr} is a |List| it is appended as a single
777 item. Use |extend()| to concatenate |Lists|.
778 When {object} is a |Blob| then {expr} must be a number.
779 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100780 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000781
782 Can also be used as a |method|: >
783 mylist->add(val1)->add(val2)
784
785
786and({expr}, {expr}) *and()*
787 Bitwise AND on the two arguments. The arguments are converted
788 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100789 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000790 Example: >
791 :let flag = and(bits, 0x80)
792< Can also be used as a |method|: >
793 :let flag = bits->and(0x80)
794
795
796append({lnum}, {text}) *append()*
797 When {text} is a |List|: Append each item of the |List| as a
798 text line below line {lnum} in the current buffer.
799 Otherwise append {text} as one text line below line {lnum} in
800 the current buffer.
801 Any type of item is accepted and converted to a String.
802 {lnum} can be zero to insert a line before the first one.
803 {lnum} is used like with |getline()|.
804 Returns 1 for failure ({lnum} out of range or out of memory),
805 0 for success. In |Vim9| script an invalid argument or
806 negative number results in an error. Example: >
807 :let failed = append(line('$'), "# THE END")
808 :let failed = append(0, ["Chapter 1", "the beginning"])
809
810< Can also be used as a |method| after a List, the base is
811 passed as the second argument: >
812 mylist->append(lnum)
813
814
815appendbufline({buf}, {lnum}, {text}) *appendbufline()*
816 Like |append()| but append the text in buffer {buf}.
817
818 This function works only for loaded buffers. First call
819 |bufload()| if needed.
820
821 For the use of {buf}, see |bufname()|.
822
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000823 {lnum} is the line number to append below. Note that using
824 |line()| would use the current buffer, not the one appending
825 to. Use "$" to append at the end of the buffer. Other string
826 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000827
828 On success 0 is returned, on failure 1 is returned.
829 In |Vim9| script an error is given for an invalid {lnum}.
830
831 If {buf} is not a valid buffer or {lnum} is not valid, an
832 error message is given. Example: >
833 :let failed = appendbufline(13, 0, "# THE START")
834<
835 Can also be used as a |method| after a List, the base is
836 passed as the second argument: >
837 mylist->appendbufline(buf, lnum)
838
839
840argc([{winid}]) *argc()*
841 The result is the number of files in the argument list. See
842 |arglist|.
843 If {winid} is not supplied, the argument list of the current
844 window is used.
845 If {winid} is -1, the global argument list is used.
846 Otherwise {winid} specifies the window of which the argument
847 list is used: either the window number or the window ID.
848 Returns -1 if the {winid} argument is invalid.
849
850 *argidx()*
851argidx() The result is the current index in the argument list. 0 is
852 the first file. argc() - 1 is the last one. See |arglist|.
853
854 *arglistid()*
855arglistid([{winnr} [, {tabnr}]])
856 Return the argument list ID. This is a number which
857 identifies the argument list being used. Zero is used for the
858 global argument list. See |arglist|.
859 Returns -1 if the arguments are invalid.
860
861 Without arguments use the current window.
862 With {winnr} only use this window in the current tab page.
863 With {winnr} and {tabnr} use the window in the specified tab
864 page.
865 {winnr} can be the window number or the |window-ID|.
866
867 *argv()*
868argv([{nr} [, {winid}]])
869 The result is the {nr}th file in the argument list. See
870 |arglist|. "argv(0)" is the first one. Example: >
871 :let i = 0
872 :while i < argc()
873 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000874 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000875 : let i = i + 1
876 :endwhile
877< Without the {nr} argument, or when {nr} is -1, a |List| with
878 the whole |arglist| is returned.
879
880 The {winid} argument specifies the window ID, see |argc()|.
881 For the Vim command line arguments see |v:argv|.
882
Bram Moolenaar016188f2022-06-06 20:52:59 +0100883 Returns an empty string if {nr}th argument is not present in
884 the argument list. Returns an empty List if the {winid}
885 argument is invalid.
886
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000887asin({expr}) *asin()*
888 Return the arc sine of {expr} measured in radians, as a |Float|
889 in the range of [-pi/2, pi/2].
890 {expr} must evaluate to a |Float| or a |Number| in the range
891 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100892 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
893 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000894 Examples: >
895 :echo asin(0.8)
896< 0.927295 >
897 :echo asin(-0.5)
898< -0.523599
899
900 Can also be used as a |method|: >
901 Compute()->asin()
902<
903 {only available when compiled with the |+float| feature}
904
905
906assert_ functions are documented here: |assert-functions-details|
907
908
909
910atan({expr}) *atan()*
911 Return the principal value of the arc tangent of {expr}, in
912 the range [-pi/2, +pi/2] radians, as a |Float|.
913 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100914 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000915 Examples: >
916 :echo atan(100)
917< 1.560797 >
918 :echo atan(-4.01)
919< -1.326405
920
921 Can also be used as a |method|: >
922 Compute()->atan()
923<
924 {only available when compiled with the |+float| feature}
925
926
927atan2({expr1}, {expr2}) *atan2()*
928 Return the arc tangent of {expr1} / {expr2}, measured in
929 radians, as a |Float| in the range [-pi, pi].
930 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100931 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
932 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000933 Examples: >
934 :echo atan2(-1, 1)
935< -0.785398 >
936 :echo atan2(1, -1)
937< 2.356194
938
939 Can also be used as a |method|: >
940 Compute()->atan2(1)
941<
942 {only available when compiled with the |+float| feature}
943
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100944
945autocmd_add({acmds}) *autocmd_add()*
946 Adds a List of autocmds and autocmd groups.
947
948 The {acmds} argument is a List where each item is a Dict with
949 the following optional items:
950 bufnr buffer number to add a buffer-local autocmd.
951 If this item is specified, then the "pattern"
952 item is ignored.
953 cmd Ex command to execute for this autocmd event
954 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100955 This can be either a String with a single
956 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100957 group autocmd group name. Refer to |autocmd-groups|.
958 If this group doesn't exist then it is
959 created. If not specified or empty, then the
960 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100961 nested boolean flag, set to v:true to add a nested
962 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100963 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100964 which executes only once. Refer to
965 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100966 pattern autocmd pattern string. Refer to
967 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100968 present, then this item is ignored. This can
969 be a String with a single pattern or a List of
970 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100971 replace boolean flag, set to v:true to remove all the
972 commands associated with the specified autocmd
973 event and group and add the {cmd}. This is
974 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +0100975 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100976
977 Returns v:true on success and v:false on failure.
978 Examples: >
979 " Create a buffer-local autocmd for buffer 5
980 let acmd = {}
981 let acmd.group = 'MyGroup'
982 let acmd.event = 'BufEnter'
983 let acmd.bufnr = 5
984 let acmd.cmd = 'call BufEnterFunc()'
985 call autocmd_add([acmd])
986
987 Can also be used as a |method|: >
988 GetAutocmdList()->autocmd_add()
989<
990autocmd_delete({acmds}) *autocmd_delete()*
991 Deletes a List of autocmds and autocmd groups.
992
993 The {acmds} argument is a List where each item is a Dict with
994 the following optional items:
995 bufnr buffer number to delete a buffer-local autocmd.
996 If this item is specified, then the "pattern"
997 item is ignored.
998 cmd Ex command for this autocmd event
999 event autocmd event name. Refer to |autocmd-events|.
1000 If '*' then all the autocmd events in this
1001 group are deleted.
1002 group autocmd group name. Refer to |autocmd-groups|.
1003 If not specified or empty, then the default
1004 group is used.
1005 nested set to v:true for a nested autocmd.
1006 Refer to |autocmd-nested|.
1007 once set to v:true for an autocmd which executes
1008 only once. Refer to |autocmd-once|.
1009 pattern autocmd pattern string. Refer to
1010 |autocmd-patterns|. If "bufnr" item is
1011 present, then this item is ignored.
1012
1013 If only {group} is specified in a {acmds} entry and {event},
1014 {pattern} and {cmd} are not specified, then that autocmd group
1015 is deleted.
1016
Bram Moolenaar016188f2022-06-06 20:52:59 +01001017 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001018 Examples: >
1019 " :autocmd! BufLeave *.vim
1020 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1021 call autocmd_delete([acmd]})
1022 " :autocmd! MyGroup1 BufLeave
1023 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1024 call autocmd_delete([acmd])
1025 " :autocmd! MyGroup2 BufEnter *.c
1026 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1027 \ pattern: '*.c'}
1028 " :autocmd! MyGroup2 * *.c
1029 let acmd = #{group: 'MyGroup2', event: '*',
1030 \ pattern: '*.c'}
1031 call autocmd_delete([acmd])
1032 " :autocmd! MyGroup3
1033 let acmd = #{group: 'MyGroup3'}
1034 call autocmd_delete([acmd])
1035<
1036 Can also be used as a |method|: >
1037 GetAutocmdList()->autocmd_delete()
1038
1039autocmd_get([{opts}]) *autocmd_get()*
1040 Returns a |List| of autocmds. If {opts} is not supplied, then
1041 returns the autocmds for all the events in all the groups.
1042
1043 The optional {opts} Dict argument supports the following
1044 items:
1045 group Autocmd group name. If specified, returns only
1046 the autocmds defined in this group. If the
1047 specified group doesn't exist, results in an
1048 error message. If set to an empty string,
1049 then the default autocmd group is used.
1050 event Autocmd event name. If specified, returns only
1051 the autocmds defined for this event. If set
1052 to "*", then returns autocmds for all the
1053 events. If the specified event doesn't exist,
1054 results in an error message.
1055 pattern Autocmd pattern. If specified, returns only
1056 the autocmds defined for this pattern.
1057 A combination of the above three times can be supplied in
1058 {opts}.
1059
1060 Each Dict in the returned List contains the following items:
1061 bufnr For buffer-local autocmds, buffer number where
1062 the autocmd is defined.
1063 cmd Command executed for this autocmd.
1064 event Autocmd event name.
1065 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001066 nested Boolean flag, set to v:true for a nested
1067 autocmd. See |autocmd-nested|.
1068 once Boolean flag, set to v:true, if the autocmd
1069 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001070 pattern Autocmd pattern. For a buffer-local
1071 autocmd, this will be of the form "<buffer=n>".
1072 If there are multiple commands for an autocmd event in a
1073 group, then separate items are returned for each command.
1074
Bram Moolenaar016188f2022-06-06 20:52:59 +01001075 Returns an empty List if an autocmd with the specified group
1076 or event or pattern is not found.
1077
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001078 Examples: >
1079 " :autocmd MyGroup
1080 echo autocmd_get(#{group: 'Mygroup'})
1081 " :autocmd G BufUnload
1082 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1083 " :autocmd G * *.ts
1084 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1085 echo autocmd_get(acmd)
1086 " :autocmd Syntax
1087 echo autocmd_get(#{event: 'Syntax'})
1088 " :autocmd G BufEnter *.ts
1089 let acmd = #{group: 'G', event: 'BufEnter',
1090 \ pattern: '*.ts'}
1091 echo autocmd_get(acmd)
1092<
1093 Can also be used as a |method|: >
1094 Getopts()->autocmd_get()
1095<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001096balloon_gettext() *balloon_gettext()*
1097 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001098 not used for the List. Returns an empty string if balloon
1099 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001100
1101balloon_show({expr}) *balloon_show()*
1102 Show {expr} inside the balloon. For the GUI {expr} is used as
1103 a string. For a terminal {expr} can be a list, which contains
1104 the lines of the balloon. If {expr} is not a list it will be
1105 split with |balloon_split()|.
1106 If {expr} is an empty string any existing balloon is removed.
1107
1108 Example: >
1109 func GetBalloonContent()
1110 " ... initiate getting the content
1111 return ''
1112 endfunc
1113 set balloonexpr=GetBalloonContent()
1114
1115 func BalloonCallback(result)
1116 call balloon_show(a:result)
1117 endfunc
1118< Can also be used as a |method|: >
1119 GetText()->balloon_show()
1120<
1121 The intended use is that fetching the content of the balloon
1122 is initiated from 'balloonexpr'. It will invoke an
1123 asynchronous method, in which a callback invokes
1124 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001125 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001126
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001127 When showing a balloon is not possible then nothing happens,
1128 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001129 {only available when compiled with the |+balloon_eval| or
1130 |+balloon_eval_term| feature}
1131
1132balloon_split({msg}) *balloon_split()*
1133 Split String {msg} into lines to be displayed in a balloon.
1134 The splits are made for the current window size and optimize
1135 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001136 Returns a |List| with the split lines. Returns an empty List
1137 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001138 Can also be used as a |method|: >
1139 GetText()->balloon_split()->balloon_show()
1140
1141< {only available when compiled with the |+balloon_eval_term|
1142 feature}
1143
1144blob2list({blob}) *blob2list()*
1145 Return a List containing the number value of each byte in Blob
1146 {blob}. Examples: >
1147 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1148 blob2list(0z) returns []
1149< Returns an empty List on error. |list2blob()| does the
1150 opposite.
1151
1152 Can also be used as a |method|: >
1153 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001154<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001155 *browse()*
1156browse({save}, {title}, {initdir}, {default})
1157 Put up a file requester. This only works when "has("browse")"
1158 returns |TRUE| (only in some GUI versions).
1159 The input fields are:
1160 {save} when |TRUE|, select file to write
1161 {title} title for the requester
1162 {initdir} directory to start browsing in
1163 {default} default file name
1164 An empty string is returned when the "Cancel" button is hit,
1165 something went wrong, or browsing is not possible.
1166
1167 *browsedir()*
1168browsedir({title}, {initdir})
1169 Put up a directory requester. This only works when
1170 "has("browse")" returns |TRUE| (only in some GUI versions).
1171 On systems where a directory browser is not supported a file
1172 browser is used. In that case: select a file in the directory
1173 to be used.
1174 The input fields are:
1175 {title} title for the requester
1176 {initdir} directory to start browsing in
1177 When the "Cancel" button is hit, something went wrong, or
1178 browsing is not possible, an empty string is returned.
1179
1180bufadd({name}) *bufadd()*
1181 Add a buffer to the buffer list with String {name}.
1182 If a buffer for file {name} already exists, return that buffer
1183 number. Otherwise return the buffer number of the newly
1184 created buffer. When {name} is an empty string then a new
1185 buffer is always created.
1186 The buffer will not have 'buflisted' set and not be loaded
1187 yet. To add some text to the buffer use this: >
1188 let bufnr = bufadd('someName')
1189 call bufload(bufnr)
1190 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001191< Returns 0 on error.
1192 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001193 let bufnr = 'somename'->bufadd()
1194
1195bufexists({buf}) *bufexists()*
1196 The result is a Number, which is |TRUE| if a buffer called
1197 {buf} exists.
1198 If the {buf} argument is a number, buffer numbers are used.
1199 Number zero is the alternate buffer for the current window.
1200
1201 If the {buf} argument is a string it must match a buffer name
1202 exactly. The name can be:
1203 - Relative to the current directory.
1204 - A full path.
1205 - The name of a buffer with 'buftype' set to "nofile".
1206 - A URL name.
1207 Unlisted buffers will be found.
1208 Note that help files are listed by their short name in the
1209 output of |:buffers|, but bufexists() requires using their
1210 long name to be able to find them.
1211 bufexists() may report a buffer exists, but to use the name
1212 with a |:buffer| command you may need to use |expand()|. Esp
1213 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1214 Use "bufexists(0)" to test for the existence of an alternate
1215 file name.
1216
1217 Can also be used as a |method|: >
1218 let exists = 'somename'->bufexists()
1219<
1220 Obsolete name: buffer_exists(). *buffer_exists()*
1221
1222buflisted({buf}) *buflisted()*
1223 The result is a Number, which is |TRUE| if a buffer called
1224 {buf} exists and is listed (has the 'buflisted' option set).
1225 The {buf} argument is used like with |bufexists()|.
1226
1227 Can also be used as a |method|: >
1228 let listed = 'somename'->buflisted()
1229
1230bufload({buf}) *bufload()*
1231 Ensure the buffer {buf} is loaded. When the buffer name
1232 refers to an existing file then the file is read. Otherwise
1233 the buffer will be empty. If the buffer was already loaded
1234 then there is no change.
1235 If there is an existing swap file for the file of the buffer,
1236 there will be no dialog, the buffer will be loaded anyway.
1237 The {buf} argument is used like with |bufexists()|.
1238
1239 Can also be used as a |method|: >
1240 eval 'somename'->bufload()
1241
1242bufloaded({buf}) *bufloaded()*
1243 The result is a Number, which is |TRUE| if a buffer called
1244 {buf} exists and is loaded (shown in a window or hidden).
1245 The {buf} argument is used like with |bufexists()|.
1246
1247 Can also be used as a |method|: >
1248 let loaded = 'somename'->bufloaded()
1249
1250bufname([{buf}]) *bufname()*
1251 The result is the name of a buffer. Mostly as it is displayed
1252 by the `:ls` command, but not using special names such as
1253 "[No Name]".
1254 If {buf} is omitted the current buffer is used.
1255 If {buf} is a Number, that buffer number's name is given.
1256 Number zero is the alternate buffer for the current window.
1257 If {buf} is a String, it is used as a |file-pattern| to match
1258 with the buffer names. This is always done like 'magic' is
1259 set and 'cpoptions' is empty. When there is more than one
1260 match an empty string is returned.
1261 "" or "%" can be used for the current buffer, "#" for the
1262 alternate buffer.
1263 A full match is preferred, otherwise a match at the start, end
1264 or middle of the buffer name is accepted. If you only want a
1265 full match then put "^" at the start and "$" at the end of the
1266 pattern.
1267 Listed buffers are found first. If there is a single match
1268 with a listed buffer, that one is returned. Next unlisted
1269 buffers are searched for.
1270 If the {buf} is a String, but you want to use it as a buffer
1271 number, force it to be a Number by adding zero to it: >
1272 :echo bufname("3" + 0)
1273< Can also be used as a |method|: >
1274 echo bufnr->bufname()
1275
1276< If the buffer doesn't exist, or doesn't have a name, an empty
1277 string is returned. >
1278 bufname("#") alternate buffer name
1279 bufname(3) name of buffer 3
1280 bufname("%") name of current buffer
1281 bufname("file2") name of buffer where "file2" matches.
1282< *buffer_name()*
1283 Obsolete name: buffer_name().
1284
1285 *bufnr()*
1286bufnr([{buf} [, {create}]])
1287 The result is the number of a buffer, as it is displayed by
1288 the `:ls` command. For the use of {buf}, see |bufname()|
1289 above.
1290
1291 If the buffer doesn't exist, -1 is returned. Or, if the
1292 {create} argument is present and TRUE, a new, unlisted,
1293 buffer is created and its number is returned. Example: >
1294 let newbuf = bufnr('Scratch001', 1)
1295< Using an empty name uses the current buffer. To create a new
1296 buffer with an empty name use |bufadd()|.
1297
1298 bufnr("$") is the last buffer: >
1299 :let last_buffer = bufnr("$")
1300< The result is a Number, which is the highest buffer number
1301 of existing buffers. Note that not all buffers with a smaller
1302 number necessarily exist, because ":bwipeout" may have removed
1303 them. Use bufexists() to test for the existence of a buffer.
1304
1305 Can also be used as a |method|: >
1306 echo bufref->bufnr()
1307<
1308 Obsolete name: buffer_number(). *buffer_number()*
1309 *last_buffer_nr()*
1310 Obsolete name for bufnr("$"): last_buffer_nr().
1311
1312bufwinid({buf}) *bufwinid()*
1313 The result is a Number, which is the |window-ID| of the first
1314 window associated with buffer {buf}. For the use of {buf},
1315 see |bufname()| above. If buffer {buf} doesn't exist or
1316 there is no such window, -1 is returned. Example: >
1317
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001318 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001319<
1320 Only deals with the current tab page.
1321
1322 Can also be used as a |method|: >
1323 FindBuffer()->bufwinid()
1324
1325bufwinnr({buf}) *bufwinnr()*
1326 Like |bufwinid()| but return the window number instead of the
1327 |window-ID|.
1328 If buffer {buf} doesn't exist or there is no such window, -1
1329 is returned. Example: >
1330
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001331 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001332
1333< The number can be used with |CTRL-W_w| and ":wincmd w"
1334 |:wincmd|.
1335
1336 Can also be used as a |method|: >
1337 FindBuffer()->bufwinnr()
1338
1339byte2line({byte}) *byte2line()*
1340 Return the line number that contains the character at byte
1341 count {byte} in the current buffer. This includes the
1342 end-of-line character, depending on the 'fileformat' option
1343 for the current buffer. The first character has byte count
1344 one.
1345 Also see |line2byte()|, |go| and |:goto|.
1346
Bram Moolenaar016188f2022-06-06 20:52:59 +01001347 Returns -1 if the {byte} value is invalid.
1348
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001349 Can also be used as a |method|: >
1350 GetOffset()->byte2line()
1351
1352< {not available when compiled without the |+byte_offset|
1353 feature}
1354
1355byteidx({expr}, {nr}) *byteidx()*
1356 Return byte index of the {nr}'th character in the String
1357 {expr}. Use zero for the first character, it then returns
1358 zero.
1359 If there are no multibyte characters the returned value is
1360 equal to {nr}.
1361 Composing characters are not counted separately, their byte
1362 length is added to the preceding base character. See
1363 |byteidxcomp()| below for counting composing characters
1364 separately.
1365 Example : >
1366 echo matchstr(str, ".", byteidx(str, 3))
1367< will display the fourth character. Another way to do the
1368 same: >
1369 let s = strpart(str, byteidx(str, 3))
1370 echo strpart(s, 0, byteidx(s, 1))
1371< Also see |strgetchar()| and |strcharpart()|.
1372
1373 If there are less than {nr} characters -1 is returned.
1374 If there are exactly {nr} characters the length of the string
1375 in bytes is returned.
1376
1377 Can also be used as a |method|: >
1378 GetName()->byteidx(idx)
1379
1380byteidxcomp({expr}, {nr}) *byteidxcomp()*
1381 Like byteidx(), except that a composing character is counted
1382 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001383 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001384 echo byteidx(s, 1)
1385 echo byteidxcomp(s, 1)
1386 echo byteidxcomp(s, 2)
1387< The first and third echo result in 3 ('e' plus composing
1388 character is 3 bytes), the second echo results in 1 ('e' is
1389 one byte).
1390 Only works differently from byteidx() when 'encoding' is set
1391 to a Unicode encoding.
1392
1393 Can also be used as a |method|: >
1394 GetName()->byteidxcomp(idx)
1395
1396call({func}, {arglist} [, {dict}]) *call()* *E699*
1397 Call function {func} with the items in |List| {arglist} as
1398 arguments.
1399 {func} can either be a |Funcref| or the name of a function.
1400 a:firstline and a:lastline are set to the cursor line.
1401 Returns the return value of the called function.
1402 {dict} is for functions with the "dict" attribute. It will be
1403 used to set the local variable "self". |Dictionary-function|
1404
1405 Can also be used as a |method|: >
1406 GetFunc()->call([arg, arg], dict)
1407
1408ceil({expr}) *ceil()*
1409 Return the smallest integral value greater than or equal to
1410 {expr} as a |Float| (round up).
1411 {expr} must evaluate to a |Float| or a |Number|.
1412 Examples: >
1413 echo ceil(1.456)
1414< 2.0 >
1415 echo ceil(-5.456)
1416< -5.0 >
1417 echo ceil(4.0)
1418< 4.0
1419
Bram Moolenaar016188f2022-06-06 20:52:59 +01001420 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1421
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001422 Can also be used as a |method|: >
1423 Compute()->ceil()
1424<
1425 {only available when compiled with the |+float| feature}
1426
1427
1428ch_ functions are documented here: |channel-functions-details|
1429
1430
1431changenr() *changenr()*
1432 Return the number of the most recent change. This is the same
1433 number as what is displayed with |:undolist| and can be used
1434 with the |:undo| command.
1435 When a change was made it is the number of that change. After
1436 redo it is the number of the redone change. After undo it is
1437 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001438 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001439
1440char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001441 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001442 Examples: >
1443 char2nr(" ") returns 32
1444 char2nr("ABC") returns 65
1445< When {utf8} is omitted or zero, the current 'encoding' is used.
1446 Example for "utf-8": >
1447 char2nr("á") returns 225
1448 char2nr("á"[0]) returns 195
1449< When {utf8} is TRUE, always treat as UTF-8 characters.
1450 A combining character is a separate character.
1451 |nr2char()| does the opposite.
1452 To turn a string into a list of character numbers: >
1453 let str = "ABC"
1454 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1455< Result: [65, 66, 67]
1456
Bram Moolenaar016188f2022-06-06 20:52:59 +01001457 Returns 0 if {string} is not a |String|.
1458
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001459 Can also be used as a |method|: >
1460 GetChar()->char2nr()
1461
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001462charclass({string}) *charclass()*
1463 Return the character class of the first character in {string}.
1464 The character class is one of:
1465 0 blank
1466 1 punctuation
1467 2 word character
1468 3 emoji
1469 other specific Unicode class
1470 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001471 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001472
1473
1474charcol({expr}) *charcol()*
1475 Same as |col()| but returns the character index of the column
1476 position given with {expr} instead of the byte position.
1477
1478 Example:
1479 With the cursor on '세' in line 5 with text "여보세요": >
1480 charcol('.') returns 3
1481 col('.') returns 7
1482
1483< Can also be used as a |method|: >
1484 GetPos()->col()
1485<
1486 *charidx()*
1487charidx({string}, {idx} [, {countcc}])
1488 Return the character index of the byte at {idx} in {string}.
1489 The index of the first character is zero.
1490 If there are no multibyte characters the returned value is
1491 equal to {idx}.
1492 When {countcc} is omitted or |FALSE|, then composing characters
1493 are not counted separately, their byte length is
1494 added to the preceding base character.
1495 When {countcc} is |TRUE|, then composing characters are
1496 counted as separate characters.
1497 Returns -1 if the arguments are invalid or if {idx} is greater
1498 than the index of the last byte in {string}. An error is
1499 given if the first argument is not a string, the second
1500 argument is not a number or when the third argument is present
1501 and is not zero or one.
1502 See |byteidx()| and |byteidxcomp()| for getting the byte index
1503 from the character index.
1504 Examples: >
1505 echo charidx('áb́ć', 3) returns 1
1506 echo charidx('áb́ć', 6, 1) returns 4
1507 echo charidx('áb́ć', 16) returns -1
1508<
1509 Can also be used as a |method|: >
1510 GetName()->charidx(idx)
1511
1512chdir({dir}) *chdir()*
1513 Change the current working directory to {dir}. The scope of
1514 the directory change depends on the directory of the current
1515 window:
1516 - If the current window has a window-local directory
1517 (|:lcd|), then changes the window local directory.
1518 - Otherwise, if the current tabpage has a local
1519 directory (|:tcd|) then changes the tabpage local
1520 directory.
1521 - Otherwise, changes the global directory.
1522 {dir} must be a String.
1523 If successful, returns the previous working directory. Pass
1524 this to another chdir() to restore the directory.
1525 On failure, returns an empty string.
1526
1527 Example: >
1528 let save_dir = chdir(newdir)
1529 if save_dir != ""
1530 " ... do some work
1531 call chdir(save_dir)
1532 endif
1533
1534< Can also be used as a |method|: >
1535 GetDir()->chdir()
1536<
1537cindent({lnum}) *cindent()*
1538 Get the amount of indent for line {lnum} according the C
1539 indenting rules, as with 'cindent'.
1540 The indent is counted in spaces, the value of 'tabstop' is
1541 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001542 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001543 See |C-indenting|.
1544
1545 Can also be used as a |method|: >
1546 GetLnum()->cindent()
1547
1548clearmatches([{win}]) *clearmatches()*
1549 Clears all matches previously defined for the current window
1550 by |matchadd()| and the |:match| commands.
1551 If {win} is specified, use the window with this number or
1552 window ID instead of the current window.
1553
1554 Can also be used as a |method|: >
1555 GetWin()->clearmatches()
1556<
1557 *col()*
1558col({expr}) The result is a Number, which is the byte index of the column
1559 position given with {expr}. The accepted positions are:
1560 . the cursor position
1561 $ the end of the cursor line (the result is the
1562 number of bytes in the cursor line plus one)
1563 'x position of mark x (if the mark is not set, 0 is
1564 returned)
1565 v In Visual mode: the start of the Visual area (the
1566 cursor is the end). When not in Visual mode
1567 returns the cursor position. Differs from |'<| in
1568 that it's updated right away.
1569 Additionally {expr} can be [lnum, col]: a |List| with the line
1570 and column number. Most useful when the column is "$", to get
1571 the last column of a specific line. When "lnum" or "col" is
1572 out of range then col() returns zero.
1573 To get the line number use |line()|. To get both use
1574 |getpos()|.
1575 For the screen column position use |virtcol()|. For the
1576 character position use |charcol()|.
1577 Note that only marks in the current file can be used.
1578 Examples: >
1579 col(".") column of cursor
1580 col("$") length of cursor line plus one
1581 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001582 col("'" .. markname) column of mark markname
Bram Moolenaar016188f2022-06-06 20:52:59 +01001583< The first column is 1. Returns 0 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001584 For an uppercase mark the column may actually be in another
1585 buffer.
1586 For the cursor position, when 'virtualedit' is active, the
1587 column is one higher if the cursor is after the end of the
1588 line. This can be used to obtain the column in Insert mode: >
1589 :imap <F2> <C-O>:let save_ve = &ve<CR>
1590 \<C-O>:set ve=all<CR>
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001591 \<C-O>:echo col(".") .. "\n" <Bar>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001592 \let &ve = save_ve<CR>
1593
1594< Can also be used as a |method|: >
1595 GetPos()->col()
1596<
1597
1598complete({startcol}, {matches}) *complete()* *E785*
1599 Set the matches for Insert mode completion.
1600 Can only be used in Insert mode. You need to use a mapping
1601 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1602 or with an expression mapping.
1603 {startcol} is the byte offset in the line where the completed
1604 text start. The text up to the cursor is the original text
1605 that will be replaced by the matches. Use col('.') for an
1606 empty string. "col('.') - 1" will replace one character by a
1607 match.
1608 {matches} must be a |List|. Each |List| item is one match.
1609 See |complete-items| for the kind of items that are possible.
1610 "longest" in 'completeopt' is ignored.
1611 Note that the after calling this function you need to avoid
1612 inserting anything that would cause completion to stop.
1613 The match can be selected with CTRL-N and CTRL-P as usual with
1614 Insert mode completion. The popup menu will appear if
1615 specified, see |ins-completion-menu|.
1616 Example: >
1617 inoremap <F5> <C-R>=ListMonths()<CR>
1618
1619 func! ListMonths()
1620 call complete(col('.'), ['January', 'February', 'March',
1621 \ 'April', 'May', 'June', 'July', 'August', 'September',
1622 \ 'October', 'November', 'December'])
1623 return ''
1624 endfunc
1625< This isn't very useful, but it shows how it works. Note that
1626 an empty string is returned to avoid a zero being inserted.
1627
1628 Can also be used as a |method|, the base is passed as the
1629 second argument: >
1630 GetMatches()->complete(col('.'))
1631
1632complete_add({expr}) *complete_add()*
1633 Add {expr} to the list of matches. Only to be used by the
1634 function specified with the 'completefunc' option.
1635 Returns 0 for failure (empty string or out of memory),
1636 1 when the match was added, 2 when the match was already in
1637 the list.
1638 See |complete-functions| for an explanation of {expr}. It is
1639 the same as one item in the list that 'omnifunc' would return.
1640
1641 Can also be used as a |method|: >
1642 GetMoreMatches()->complete_add()
1643
1644complete_check() *complete_check()*
1645 Check for a key typed while looking for completion matches.
1646 This is to be used when looking for matches takes some time.
1647 Returns |TRUE| when searching for matches is to be aborted,
1648 zero otherwise.
1649 Only to be used by the function specified with the
1650 'completefunc' option.
1651
1652
1653complete_info([{what}]) *complete_info()*
1654 Returns a |Dictionary| with information about Insert mode
1655 completion. See |ins-completion|.
1656 The items are:
1657 mode Current completion mode name string.
1658 See |complete_info_mode| for the values.
1659 pum_visible |TRUE| if popup menu is visible.
1660 See |pumvisible()|.
1661 items List of completion matches. Each item is a
1662 dictionary containing the entries "word",
1663 "abbr", "menu", "kind", "info" and "user_data".
1664 See |complete-items|.
1665 selected Selected item index. First index is zero.
1666 Index is -1 if no item is selected (showing
1667 typed text only, or the last completion after
1668 no item is selected when using the <Up> or
1669 <Down> keys)
1670 inserted Inserted string. [NOT IMPLEMENT YET]
1671
1672 *complete_info_mode*
1673 mode values are:
1674 "" Not in completion mode
1675 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1676 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1677 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1678 |i_CTRL-X_CTRL-Y|
1679 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1680 "files" File names |i_CTRL-X_CTRL-F|
1681 "tags" Tags |i_CTRL-X_CTRL-]|
1682 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1683 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1684 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1685 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1686 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1687 "function" User defined completion |i_CTRL-X_CTRL-U|
1688 "omni" Omni completion |i_CTRL-X_CTRL-O|
1689 "spell" Spelling suggestions |i_CTRL-X_s|
1690 "eval" |complete()| completion
1691 "unknown" Other internal modes
1692
1693 If the optional {what} list argument is supplied, then only
1694 the items listed in {what} are returned. Unsupported items in
1695 {what} are silently ignored.
1696
1697 To get the position and size of the popup menu, see
1698 |pum_getpos()|. It's also available in |v:event| during the
1699 |CompleteChanged| event.
1700
Bram Moolenaar016188f2022-06-06 20:52:59 +01001701 Returns an empty |Dictionary| on error.
1702
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001703 Examples: >
1704 " Get all items
1705 call complete_info()
1706 " Get only 'mode'
1707 call complete_info(['mode'])
1708 " Get only 'mode' and 'pum_visible'
1709 call complete_info(['mode', 'pum_visible'])
1710
1711< Can also be used as a |method|: >
1712 GetItems()->complete_info()
1713<
1714 *confirm()*
1715confirm({msg} [, {choices} [, {default} [, {type}]]])
1716 confirm() offers the user a dialog, from which a choice can be
1717 made. It returns the number of the choice. For the first
1718 choice this is 1.
1719 Note: confirm() is only supported when compiled with dialog
1720 support, see |+dialog_con| and |+dialog_gui|.
1721
1722 {msg} is displayed in a |dialog| with {choices} as the
1723 alternatives. When {choices} is missing or empty, "&OK" is
1724 used (and translated).
1725 {msg} is a String, use '\n' to include a newline. Only on
1726 some systems the string is wrapped when it doesn't fit.
1727
1728 {choices} is a String, with the individual choices separated
1729 by '\n', e.g. >
1730 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1731< The letter after the '&' is the shortcut key for that choice.
1732 Thus you can type 'c' to select "Cancel". The shortcut does
1733 not need to be the first letter: >
1734 confirm("file has been modified", "&Save\nSave &All")
1735< For the console, the first letter of each choice is used as
1736 the default shortcut key. Case is ignored.
1737
1738 The optional {default} argument is the number of the choice
1739 that is made if the user hits <CR>. Use 1 to make the first
1740 choice the default one. Use 0 to not set a default. If
1741 {default} is omitted, 1 is used.
1742
1743 The optional {type} String argument gives the type of dialog.
1744 This is only used for the icon of the GTK, Mac, Motif and
1745 Win32 GUI. It can be one of these values: "Error",
1746 "Question", "Info", "Warning" or "Generic". Only the first
1747 character is relevant. When {type} is omitted, "Generic" is
1748 used.
1749
1750 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1751 or another valid interrupt key, confirm() returns 0.
1752
1753 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01001754 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001755 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01001756 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001757 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001758 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001759 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001760 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001761 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01001762 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001763< In a GUI dialog, buttons are used. The layout of the buttons
1764 depends on the 'v' flag in 'guioptions'. If it is included,
1765 the buttons are always put vertically. Otherwise, confirm()
1766 tries to put the buttons in one horizontal line. If they
1767 don't fit, a vertical layout is used anyway. For some systems
1768 the horizontal layout is always used.
1769
1770 Can also be used as a |method|in: >
1771 BuildMessage()->confirm("&Yes\n&No")
1772<
1773 *copy()*
1774copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1775 different from using {expr} directly.
1776 When {expr} is a |List| a shallow copy is created. This means
1777 that the original |List| can be changed without changing the
1778 copy, and vice versa. But the items are identical, thus
1779 changing an item changes the contents of both |Lists|.
1780 A |Dictionary| is copied in a similar way as a |List|.
1781 Also see |deepcopy()|.
1782 Can also be used as a |method|: >
1783 mylist->copy()
1784
1785cos({expr}) *cos()*
1786 Return the cosine of {expr}, measured in radians, as a |Float|.
1787 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001788 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001789 Examples: >
1790 :echo cos(100)
1791< 0.862319 >
1792 :echo cos(-4.01)
1793< -0.646043
1794
1795 Can also be used as a |method|: >
1796 Compute()->cos()
1797<
1798 {only available when compiled with the |+float| feature}
1799
1800
1801cosh({expr}) *cosh()*
1802 Return the hyperbolic cosine of {expr} as a |Float| in the range
1803 [1, inf].
1804 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001805 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001806 Examples: >
1807 :echo cosh(0.5)
1808< 1.127626 >
1809 :echo cosh(-0.5)
1810< -1.127626
1811
1812 Can also be used as a |method|: >
1813 Compute()->cosh()
1814<
1815 {only available when compiled with the |+float| feature}
1816
1817
1818count({comp}, {expr} [, {ic} [, {start}]]) *count()*
1819 Return the number of times an item with value {expr} appears
1820 in |String|, |List| or |Dictionary| {comp}.
1821
1822 If {start} is given then start with the item with this index.
1823 {start} can only be used with a |List|.
1824
1825 When {ic} is given and it's |TRUE| then case is ignored.
1826
1827 When {comp} is a string then the number of not overlapping
1828 occurrences of {expr} is returned. Zero is returned when
1829 {expr} is an empty string.
1830
1831 Can also be used as a |method|: >
1832 mylist->count(val)
1833<
1834 *cscope_connection()*
1835cscope_connection([{num} , {dbpath} [, {prepend}]])
1836 Checks for the existence of a |cscope| connection. If no
1837 parameters are specified, then the function returns:
1838 0, if cscope was not available (not compiled in), or
1839 if there are no cscope connections;
1840 1, if there is at least one cscope connection.
1841
1842 If parameters are specified, then the value of {num}
1843 determines how existence of a cscope connection is checked:
1844
1845 {num} Description of existence check
1846 ----- ------------------------------
1847 0 Same as no parameters (e.g., "cscope_connection()").
1848 1 Ignore {prepend}, and use partial string matches for
1849 {dbpath}.
1850 2 Ignore {prepend}, and use exact string matches for
1851 {dbpath}.
1852 3 Use {prepend}, use partial string matches for both
1853 {dbpath} and {prepend}.
1854 4 Use {prepend}, use exact string matches for both
1855 {dbpath} and {prepend}.
1856
1857 Note: All string comparisons are case sensitive!
1858
1859 Examples. Suppose we had the following (from ":cs show"): >
1860
1861 # pid database name prepend path
1862 0 27664 cscope.out /usr/local
1863<
1864 Invocation Return Val ~
1865 ---------- ---------- >
1866 cscope_connection() 1
1867 cscope_connection(1, "out") 1
1868 cscope_connection(2, "out") 0
1869 cscope_connection(3, "out") 0
1870 cscope_connection(3, "out", "local") 1
1871 cscope_connection(4, "out") 0
1872 cscope_connection(4, "out", "local") 0
1873 cscope_connection(4, "cscope.out", "/usr/local") 1
1874<
1875cursor({lnum}, {col} [, {off}]) *cursor()*
1876cursor({list})
1877 Positions the cursor at the column (byte count) {col} in the
1878 line {lnum}. The first column is one.
1879
1880 When there is one argument {list} this is used as a |List|
1881 with two, three or four item:
1882 [{lnum}, {col}]
1883 [{lnum}, {col}, {off}]
1884 [{lnum}, {col}, {off}, {curswant}]
1885 This is like the return value of |getpos()| or |getcurpos()|,
1886 but without the first item.
1887
1888 To position the cursor using the character count, use
1889 |setcursorcharpos()|.
1890
1891 Does not change the jumplist.
1892 {lnum} is used like with |getline()|.
1893 If {lnum} is greater than the number of lines in the buffer,
1894 the cursor will be positioned at the last line in the buffer.
1895 If {lnum} is zero, the cursor will stay in the current line.
1896 If {col} is greater than the number of bytes in the line,
1897 the cursor will be positioned at the last character in the
1898 line.
1899 If {col} is zero, the cursor will stay in the current column.
1900 If {curswant} is given it is used to set the preferred column
1901 for vertical movement. Otherwise {col} is used.
1902
1903 When 'virtualedit' is used {off} specifies the offset in
1904 screen columns from the start of the character. E.g., a
1905 position within a <Tab> or after the last character.
1906 Returns 0 when the position could be set, -1 otherwise.
1907
1908 Can also be used as a |method|: >
1909 GetCursorPos()->cursor()
1910
1911debugbreak({pid}) *debugbreak()*
1912 Specifically used to interrupt a program being debugged. It
1913 will cause process {pid} to get a SIGTRAP. Behavior for other
1914 processes is undefined. See |terminal-debugger|.
1915 {only available on MS-Windows}
1916
Bram Moolenaar016188f2022-06-06 20:52:59 +01001917 Returns |TRUE| if successfully interrupted the program.
1918 Otherwise returns |FALSE|.
1919
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001920 Can also be used as a |method|: >
1921 GetPid()->debugbreak()
1922
1923deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
1924 Make a copy of {expr}. For Numbers and Strings this isn't
1925 different from using {expr} directly.
1926 When {expr} is a |List| a full copy is created. This means
1927 that the original |List| can be changed without changing the
1928 copy, and vice versa. When an item is a |List| or
1929 |Dictionary|, a copy for it is made, recursively. Thus
1930 changing an item in the copy does not change the contents of
1931 the original |List|.
1932 A |Dictionary| is copied in a similar way as a |List|.
1933
1934 When {noref} is omitted or zero a contained |List| or
1935 |Dictionary| is only copied once. All references point to
1936 this single copy. With {noref} set to 1 every occurrence of a
1937 |List| or |Dictionary| results in a new copy. This also means
1938 that a cyclic reference causes deepcopy() to fail.
1939 *E724*
1940 Nesting is possible up to 100 levels. When there is an item
1941 that refers back to a higher level making a deep copy with
1942 {noref} set to 1 will fail.
1943 Also see |copy()|.
1944
1945 Can also be used as a |method|: >
1946 GetObject()->deepcopy()
1947
1948delete({fname} [, {flags}]) *delete()*
1949 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001950 name {fname}.
1951
1952 This also works when {fname} is a symbolic link. The symbolic
1953 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001954
1955 When {flags} is "d": Deletes the directory by the name
1956 {fname}. This fails when directory {fname} is not empty.
1957
1958 When {flags} is "rf": Deletes the directory by the name
1959 {fname} and everything in it, recursively. BE CAREFUL!
1960 Note: on MS-Windows it is not possible to delete a directory
1961 that is being used.
1962
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001963 The result is a Number, which is 0/false if the delete
1964 operation was successful and -1/true when the deletion failed
1965 or partly failed.
1966
1967 Use |remove()| to delete an item from a |List|.
1968 To delete a line from the buffer use |:delete| or
1969 |deletebufline()|.
1970
1971 Can also be used as a |method|: >
1972 GetName()->delete()
1973
1974deletebufline({buf}, {first} [, {last}]) *deletebufline()*
1975 Delete lines {first} to {last} (inclusive) from buffer {buf}.
1976 If {last} is omitted then delete line {first} only.
1977 On success 0 is returned, on failure 1 is returned.
1978
1979 This function works only for loaded buffers. First call
1980 |bufload()| if needed.
1981
1982 For the use of {buf}, see |bufname()| above.
1983
1984 {first} and {last} are used like with |getline()|. Note that
1985 when using |line()| this refers to the current buffer. Use "$"
1986 to refer to the last line in buffer {buf}.
1987
1988 Can also be used as a |method|: >
1989 GetBuffer()->deletebufline(1)
1990<
1991 *did_filetype()*
1992did_filetype() Returns |TRUE| when autocommands are being executed and the
1993 FileType event has been triggered at least once. Can be used
1994 to avoid triggering the FileType event again in the scripts
1995 that detect the file type. |FileType|
1996 Returns |FALSE| when `:setf FALLBACK` was used.
1997 When editing another file, the counter is reset, thus this
1998 really checks if the FileType event has been triggered for the
1999 current buffer. This allows an autocommand that starts
2000 editing another buffer to set 'filetype' and load a syntax
2001 file.
2002
2003diff_filler({lnum}) *diff_filler()*
2004 Returns the number of filler lines above line {lnum}.
2005 These are the lines that were inserted at this point in
2006 another diff'ed window. These filler lines are shown in the
2007 display but don't exist in the buffer.
2008 {lnum} is used like with |getline()|. Thus "." is the current
2009 line, "'m" mark m, etc.
2010 Returns 0 if the current window is not in diff mode.
2011
2012 Can also be used as a |method|: >
2013 GetLnum()->diff_filler()
2014
2015diff_hlID({lnum}, {col}) *diff_hlID()*
2016 Returns the highlight ID for diff mode at line {lnum} column
2017 {col} (byte index). When the current line does not have a
2018 diff change zero is returned.
2019 {lnum} is used like with |getline()|. Thus "." is the current
2020 line, "'m" mark m, etc.
2021 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2022 line.
2023 The highlight ID can be used with |synIDattr()| to obtain
2024 syntax information about the highlighting.
2025
2026 Can also be used as a |method|: >
2027 GetLnum()->diff_hlID(col)
2028<
2029
2030digraph_get({chars}) *digraph_get()* *E1214*
2031 Return the digraph of {chars}. This should be a string with
2032 exactly two characters. If {chars} are not just two
2033 characters, or the digraph of {chars} does not exist, an error
2034 is given and an empty string is returned.
2035
2036 The character will be converted from Unicode to 'encoding'
2037 when needed. This does require the conversion to be
2038 available, it might fail.
2039
2040 Also see |digraph_getlist()|.
2041
2042 Examples: >
2043 " Get a built-in digraph
2044 :echo digraph_get('00') " Returns '∞'
2045
2046 " Get a user-defined digraph
2047 :call digraph_set('aa', 'あ')
2048 :echo digraph_get('aa') " Returns 'あ'
2049<
2050 Can also be used as a |method|: >
2051 GetChars()->digraph_get()
2052<
2053 This function works only when compiled with the |+digraphs|
2054 feature. If this feature is disabled, this function will
2055 display an error message.
2056
2057
2058digraph_getlist([{listall}]) *digraph_getlist()*
2059 Return a list of digraphs. If the {listall} argument is given
2060 and it is TRUE, return all digraphs, including the default
2061 digraphs. Otherwise, return only user-defined digraphs.
2062
2063 The characters will be converted from Unicode to 'encoding'
2064 when needed. This does require the conservation to be
2065 available, it might fail.
2066
2067 Also see |digraph_get()|.
2068
2069 Examples: >
2070 " Get user-defined digraphs
2071 :echo digraph_getlist()
2072
2073 " Get all the digraphs, including default digraphs
2074 :echo digraph_getlist(1)
2075<
2076 Can also be used as a |method|: >
2077 GetNumber()->digraph_getlist()
2078<
2079 This function works only when compiled with the |+digraphs|
2080 feature. If this feature is disabled, this function will
2081 display an error message.
2082
2083
Bram Moolenaara2baa732022-02-04 16:09:54 +00002084digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002085 Add digraph {chars} to the list. {chars} must be a string
2086 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002087 encoded character. *E1215*
2088 Be careful, composing characters are NOT ignored. This
2089 function is similar to |:digraphs| command, but useful to add
2090 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002091
2092 The function result is v:true if |digraph| is registered. If
2093 this fails an error message is given and v:false is returned.
2094
2095 If you want to define multiple digraphs at once, you can use
2096 |digraph_setlist()|.
2097
2098 Example: >
2099 call digraph_set(' ', 'あ')
2100<
2101 Can be used as a |method|: >
2102 GetString()->digraph_set('あ')
2103<
2104 This function works only when compiled with the |+digraphs|
2105 feature. If this feature is disabled, this function will
2106 display an error message.
2107
2108
2109digraph_setlist({digraphlist}) *digraph_setlist()*
2110 Similar to |digraph_set()| but this function can add multiple
2111 digraphs at once. {digraphlist} is a list composed of lists,
2112 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002113 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002114 Example: >
2115 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2116<
2117 It is similar to the following: >
2118 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2119 call digraph_set(chars, digraph)
2120 endfor
2121< Except that the function returns after the first error,
2122 following digraphs will not be added.
2123
2124 Can be used as a |method|: >
2125 GetList()->digraph_setlist()
2126<
2127 This function works only when compiled with the |+digraphs|
2128 feature. If this feature is disabled, this function will
2129 display an error message.
2130
2131
2132echoraw({string}) *echoraw()*
2133 Output {string} as-is, including unprintable characters.
2134 This can be used to output a terminal code. For example, to
2135 disable modifyOtherKeys: >
2136 call echoraw(&t_TE)
2137< and to enable it again: >
2138 call echoraw(&t_TI)
2139< Use with care, you can mess up the terminal this way.
2140
2141
2142empty({expr}) *empty()*
2143 Return the Number 1 if {expr} is empty, zero otherwise.
2144 - A |List| or |Dictionary| is empty when it does not have any
2145 items.
2146 - A |String| is empty when its length is zero.
2147 - A |Number| and |Float| are empty when their value is zero.
2148 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2149 - A |Job| is empty when it failed to start.
2150 - A |Channel| is empty when it is closed.
2151 - A |Blob| is empty when its length is zero.
2152
2153 For a long |List| this is much faster than comparing the
2154 length with zero.
2155
2156 Can also be used as a |method|: >
2157 mylist->empty()
2158
2159environ() *environ()*
2160 Return all of environment variables as dictionary. You can
2161 check if an environment variable exists like this: >
2162 :echo has_key(environ(), 'HOME')
2163< Note that the variable name may be CamelCase; to ignore case
2164 use this: >
2165 :echo index(keys(environ()), 'HOME', 0, 1) != -1
2166
2167escape({string}, {chars}) *escape()*
2168 Escape the characters in {chars} that occur in {string} with a
2169 backslash. Example: >
2170 :echo escape('c:\program files\vim', ' \')
2171< results in: >
2172 c:\\program\ files\\vim
2173< Also see |shellescape()| and |fnameescape()|.
2174
2175 Can also be used as a |method|: >
2176 GetText()->escape(' \')
2177<
2178 *eval()*
2179eval({string}) Evaluate {string} and return the result. Especially useful to
2180 turn the result of |string()| back into the original value.
2181 This works for Numbers, Floats, Strings, Blobs and composites
2182 of them. Also works for |Funcref|s that refer to existing
2183 functions.
2184
2185 Can also be used as a |method|: >
2186 argv->join()->eval()
2187
2188eventhandler() *eventhandler()*
2189 Returns 1 when inside an event handler. That is that Vim got
2190 interrupted while waiting for the user to type a character,
2191 e.g., when dropping a file on Vim. This means interactive
2192 commands cannot be used. Otherwise zero is returned.
2193
2194executable({expr}) *executable()*
2195 This function checks if an executable with the name {expr}
2196 exists. {expr} must be the name of the program without any
2197 arguments.
2198 executable() uses the value of $PATH and/or the normal
2199 searchpath for programs. *PATHEXT*
2200 On MS-Windows the ".exe", ".bat", etc. can optionally be
2201 included. Then the extensions in $PATHEXT are tried. Thus if
2202 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2203 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2204 by itself can be used in $PATHEXT to try using the name
2205 without an extension. When 'shell' looks like a Unix shell,
2206 then the name is also tried without adding an extension.
2207 On MS-Windows it only checks if the file exists and is not a
2208 directory, not if it's really executable.
2209 On MS-Windows an executable in the same directory as Vim is
Yasuhiro Matsumoto05cf63e2022-05-03 11:02:28 +01002210 normally found. Since this directory is added to $PATH it
2211 should also work to execute it |win32-PATH|. This can be
2212 disabled by setting the $NoDefaultCurrentDirectoryInExePath
2213 environment variable. *NoDefaultCurrentDirectoryInExePath*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002214 The result is a Number:
2215 1 exists
2216 0 does not exist
2217 -1 not implemented on this system
2218 |exepath()| can be used to get the full path of an executable.
2219
2220 Can also be used as a |method|: >
2221 GetCommand()->executable()
2222
2223execute({command} [, {silent}]) *execute()*
2224 Execute an Ex command or commands and return the output as a
2225 string.
2226 {command} can be a string or a List. In case of a List the
2227 lines are executed one by one.
2228 This is equivalent to: >
2229 redir => var
2230 {command}
2231 redir END
2232<
2233 The optional {silent} argument can have these values:
2234 "" no `:silent` used
2235 "silent" `:silent` used
2236 "silent!" `:silent!` used
2237 The default is "silent". Note that with "silent!", unlike
2238 `:redir`, error messages are dropped. When using an external
2239 command the screen may be messed up, use `system()` instead.
2240 *E930*
2241 It is not possible to use `:redir` anywhere in {command}.
2242
2243 To get a list of lines use |split()| on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002244 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002245
2246< To execute a command in another window than the current one
2247 use `win_execute()`.
2248
2249 When used recursively the output of the recursive call is not
2250 included in the output of the higher level call.
2251
2252 Can also be used as a |method|: >
2253 GetCommand()->execute()
2254
2255exepath({expr}) *exepath()*
2256 If {expr} is an executable and is either an absolute path, a
2257 relative path or found in $PATH, return the full path.
2258 Note that the current directory is used when {expr} starts
2259 with "./", which may be a problem for Vim: >
2260 echo exepath(v:progpath)
2261< If {expr} cannot be found in $PATH or is not executable then
2262 an empty string is returned.
2263
2264 Can also be used as a |method|: >
2265 GetCommand()->exepath()
2266<
2267 *exists()*
2268exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
2269 zero otherwise.
2270
2271 Note: In a compiled |:def| function the evaluation is done at
2272 runtime. Use `exists_compiled()` to evaluate the expression
2273 at compile time.
2274
2275 For checking for a supported feature use |has()|.
2276 For checking if a file exists use |filereadable()|.
2277
2278 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002279 varname internal variable (see
2280 dict.key |internal-variables|). Also works
2281 list[i] for |curly-braces-names|, |Dictionary|
2282 import.Func entries, |List| items, imported
Bram Moolenaar944697a2022-02-20 19:48:20 +00002283 items, etc.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002284 Does not work for local variables in a
2285 compiled `:def` function.
Bram Moolenaar944697a2022-02-20 19:48:20 +00002286 Also works for a function in |Vim9|
2287 script, since it can be used as a
2288 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002289 Beware that evaluating an index may
2290 cause an error message for an invalid
2291 expression. E.g.: >
2292 :let l = [1, 2, 3]
2293 :echo exists("l[5]")
2294< 0 >
2295 :echo exists("l[xx]")
2296< E121: Undefined variable: xx
2297 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002298 &option-name Vim option (only checks if it exists,
2299 not if it really works)
2300 +option-name Vim option that works.
2301 $ENVNAME environment variable (could also be
2302 done by comparing with an empty
2303 string)
2304 *funcname built-in function (see |functions|)
2305 or user defined function (see
2306 |user-functions|) that is implemented.
2307 Also works for a variable that is a
2308 Funcref.
2309 ?funcname built-in function that could be
2310 implemented; to be used to check if
2311 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002312 :cmdname Ex command: built-in command, user
2313 command or command modifier |:command|.
2314 Returns:
2315 1 for match with start of a command
2316 2 full match with a command
2317 3 matches several user commands
2318 To check for a supported command
2319 always check the return value to be 2.
2320 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002321 :3match The |:3match| command (but you
2322 probably should not use it, it is
2323 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002324 #event autocommand defined for this event
2325 #event#pattern autocommand defined for this event and
2326 pattern (the pattern is taken
2327 literally and compared to the
2328 autocommand patterns character by
2329 character)
2330 #group autocommand group exists
2331 #group#event autocommand defined for this group and
2332 event.
2333 #group#event#pattern
2334 autocommand defined for this group,
2335 event and pattern.
2336 ##event autocommand for this event is
2337 supported.
2338
2339 Examples: >
2340 exists("&shortname")
2341 exists("$HOSTNAME")
2342 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002343 exists("*s:MyFunc") " only for legacy script
2344 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002345 exists("bufcount")
2346 exists(":Make")
2347 exists("#CursorHold")
2348 exists("#BufReadPre#*.gz")
2349 exists("#filetypeindent")
2350 exists("#filetypeindent#FileType")
2351 exists("#filetypeindent#FileType#*")
2352 exists("##ColorScheme")
2353< There must be no space between the symbol (&/$/*/#) and the
2354 name.
2355 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002356 a few cases this is ignored. That may become stricter in the
2357 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002358 Working example: >
2359 exists(":make")
2360< NOT working example: >
2361 exists(":make install")
2362
2363< Note that the argument must be a string, not the name of the
2364 variable itself. For example: >
2365 exists(bufcount)
2366< This doesn't check for existence of the "bufcount" variable,
2367 but gets the value of "bufcount", and checks if that exists.
2368
2369 Can also be used as a |method|: >
2370 Varname()->exists()
2371<
2372
2373exists_compiled({expr}) *exists_compiled()*
2374 Like `exists()` but evaluated at compile time. This is useful
2375 to skip a block where a function is used that would otherwise
2376 give an error: >
2377 if exists_compiled('*ThatFunction')
2378 ThatFunction('works')
2379 endif
2380< If `exists()` were used then a compilation error would be
2381 given if ThatFunction() is not defined.
2382
2383 {expr} must be a literal string. *E1232*
2384 Can only be used in a |:def| function. *E1233*
2385 This does not work to check for arguments or local variables.
2386
2387
2388exp({expr}) *exp()*
2389 Return the exponential of {expr} as a |Float| in the range
2390 [0, inf].
2391 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002392 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002393 Examples: >
2394 :echo exp(2)
2395< 7.389056 >
2396 :echo exp(-1)
2397< 0.367879
2398
2399 Can also be used as a |method|: >
2400 Compute()->exp()
2401<
2402 {only available when compiled with the |+float| feature}
2403
2404
2405expand({string} [, {nosuf} [, {list}]]) *expand()*
2406 Expand wildcards and the following special keywords in
2407 {string}. 'wildignorecase' applies.
2408
2409 If {list} is given and it is |TRUE|, a List will be returned.
2410 Otherwise the result is a String and when there are several
2411 matches, they are separated by <NL> characters. [Note: in
2412 version 5.0 a space was used, which caused problems when a
2413 file name contains a space]
2414
2415 If the expansion fails, the result is an empty string. A name
2416 for a non-existing file is not included, unless {string} does
2417 not start with '%', '#' or '<', see below.
2418
2419 When {string} starts with '%', '#' or '<', the expansion is
2420 done like for the |cmdline-special| variables with their
2421 associated modifiers. Here is a short overview:
2422
2423 % current file name
2424 # alternate file name
2425 #n alternate file name n
2426 <cfile> file name under the cursor
2427 <afile> autocmd file name
2428 <abuf> autocmd buffer number (as a String!)
2429 <amatch> autocmd matched name
2430 <cexpr> C expression under the cursor
2431 <sfile> sourced script file or function name
2432 <slnum> sourced script line number or function
2433 line number
2434 <sflnum> script file line number, also when in
2435 a function
2436 <SID> "<SNR>123_" where "123" is the
2437 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002438 <script> sourced script file, or script file
2439 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002440 <stack> call stack
2441 <cword> word under the cursor
2442 <cWORD> WORD under the cursor
2443 <client> the {clientid} of the last received
2444 message |server2client()|
2445 Modifiers:
2446 :p expand to full path
2447 :h head (last path component removed)
2448 :t tail (last path component only)
2449 :r root (one extension removed)
2450 :e extension only
2451
2452 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002453 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002454< Note that when expanding a string that starts with '%', '#' or
2455 '<', any following text is ignored. This does NOT work: >
2456 :let doesntwork = expand("%:h.bak")
2457< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002458 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002459< Also note that expanding "<cfile>" and others only returns the
2460 referenced file name without further expansion. If "<cfile>"
2461 is "~/.cshrc", you need to do another expand() to have the
2462 "~/" expanded into the path of the home directory: >
2463 :echo expand(expand("<cfile>"))
2464<
2465 There cannot be white space between the variables and the
2466 following modifier. The |fnamemodify()| function can be used
2467 to modify normal file names.
2468
2469 When using '%' or '#', and the current or alternate file name
2470 is not defined, an empty string is used. Using "%:p" in a
2471 buffer with no name, results in the current directory, with a
2472 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01002473 When 'verbose' is set then expanding '%', '#' and <> items
2474 will result in an error message if the argument cannot be
2475 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002476
2477 When {string} does not start with '%', '#' or '<', it is
2478 expanded like a file name is expanded on the command line.
2479 'suffixes' and 'wildignore' are used, unless the optional
2480 {nosuf} argument is given and it is |TRUE|.
2481 Names for non-existing files are included. The "**" item can
2482 be used to search in a directory tree. For example, to find
2483 all "README" files in the current directory and below: >
2484 :echo expand("**/README")
2485<
2486 expand() can also be used to expand variables and environment
2487 variables that are only known in a shell. But this can be
2488 slow, because a shell may be used to do the expansion. See
2489 |expr-env-expand|.
2490 The expanded variable is still handled like a list of file
2491 names. When an environment variable cannot be expanded, it is
2492 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2493 "$FOOBAR".
2494
2495 See |glob()| for finding existing files. See |system()| for
2496 getting the raw output of an external command.
2497
2498 Can also be used as a |method|: >
2499 Getpattern()->expand()
2500
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002501expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002502 Expand special items in String {string} like what is done for
2503 an Ex command such as `:edit`. This expands special keywords,
2504 like with |expand()|, and environment variables, anywhere in
2505 {string}. "~user" and "~/path" are only expanded at the
2506 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002507
2508 The following items are supported in the {options} Dict
2509 argument:
2510 errmsg If set to TRUE, error messages are displayed
2511 if an error is encountered during expansion.
2512 By default, error messages are not displayed.
2513
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002514 Returns the expanded string. If an error is encountered
2515 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002516
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002517 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002518 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002519 make /path/runtime/doc/builtin.o
2520 :echo expandcmd('make %<.o', {'errmsg': v:true})
2521<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002522 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002523 GetCommand()->expandcmd()
2524<
2525extend({expr1}, {expr2} [, {expr3}]) *extend()*
2526 {expr1} and {expr2} must be both |Lists| or both
2527 |Dictionaries|.
2528
2529 If they are |Lists|: Append {expr2} to {expr1}.
2530 If {expr3} is given insert the items of {expr2} before the
2531 item with index {expr3} in {expr1}. When {expr3} is zero
2532 insert before the first item. When {expr3} is equal to
2533 len({expr1}) then {expr2} is appended.
2534 Examples: >
2535 :echo sort(extend(mylist, [7, 5]))
2536 :call extend(mylist, [2, 3], 1)
2537< When {expr1} is the same List as {expr2} then the number of
2538 items copied is equal to the original length of the List.
2539 E.g., when {expr3} is 1 you get N new copies of the first item
2540 (where N is the original length of the List).
2541 Use |add()| to concatenate one item to a list. To concatenate
2542 two lists into a new list use the + operator: >
2543 :let newlist = [1, 2, 3] + [4, 5]
2544<
2545 If they are |Dictionaries|:
2546 Add all entries from {expr2} to {expr1}.
2547 If a key exists in both {expr1} and {expr2} then {expr3} is
2548 used to decide what to do:
2549 {expr3} = "keep": keep the value of {expr1}
2550 {expr3} = "force": use the value of {expr2}
2551 {expr3} = "error": give an error message *E737*
2552 When {expr3} is omitted then "force" is assumed.
2553
2554 {expr1} is changed when {expr2} is not empty. If necessary
2555 make a copy of {expr1} first.
2556 {expr2} remains unchanged.
2557 When {expr1} is locked and {expr2} is not empty the operation
2558 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002559 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002560
2561 Can also be used as a |method|: >
2562 mylist->extend(otherlist)
2563
2564
2565extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2566 Like |extend()| but instead of adding items to {expr1} a new
2567 List or Dictionary is created and returned. {expr1} remains
2568 unchanged. Items can still be changed by {expr2}, if you
2569 don't want that use |deepcopy()| first.
2570
2571
2572feedkeys({string} [, {mode}]) *feedkeys()*
2573 Characters in {string} are queued for processing as if they
2574 come from a mapping or were typed by the user.
2575
2576 By default the string is added to the end of the typeahead
2577 buffer, thus if a mapping is still being executed the
2578 characters come after them. Use the 'i' flag to insert before
2579 other characters, they will be executed next, before any
2580 characters from a mapping.
2581
2582 The function does not wait for processing of keys contained in
2583 {string}.
2584
2585 To include special keys into {string}, use double-quotes
2586 and "\..." notation |expr-quote|. For example,
2587 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2588 feedkeys('\<CR>') pushes 5 characters.
2589 A special code that might be useful is <Ignore>, it exits the
2590 wait for a character without doing anything. *<Ignore>*
2591
2592 {mode} is a String, which can contain these character flags:
2593 'm' Remap keys. This is default. If {mode} is absent,
2594 keys are remapped.
2595 'n' Do not remap keys.
2596 't' Handle keys as if typed; otherwise they are handled as
2597 if coming from a mapping. This matters for undo,
2598 opening folds, etc.
2599 'L' Lowlevel input. Only works for Unix or when using the
2600 GUI. Keys are used as if they were coming from the
2601 terminal. Other flags are not used. *E980*
2602 When a CTRL-C interrupts and 't' is included it sets
2603 the internal "got_int" flag.
2604 'i' Insert the string instead of appending (see above).
2605 'x' Execute commands until typeahead is empty. This is
2606 similar to using ":normal!". You can call feedkeys()
2607 several times without 'x' and then one time with 'x'
2608 (possibly with an empty {string}) to execute all the
2609 typeahead. Note that when Vim ends in Insert mode it
2610 will behave as if <Esc> is typed, to avoid getting
2611 stuck, waiting for a character to be typed before the
2612 script continues.
2613 Note that if you manage to call feedkeys() while
2614 executing commands, thus calling it recursively, then
2615 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00002616 'c' Remove any script context when executing, so that
2617 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01002618 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01002619 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002620 '!' When used with 'x' will not end Insert mode. Can be
2621 used in a test when a timer is set to exit Insert mode
2622 a little later. Useful for testing CursorHoldI.
2623
2624 Return value is always 0.
2625
2626 Can also be used as a |method|: >
2627 GetInput()->feedkeys()
2628
2629filereadable({file}) *filereadable()*
2630 The result is a Number, which is |TRUE| when a file with the
2631 name {file} exists, and can be read. If {file} doesn't exist,
2632 or is a directory, the result is |FALSE|. {file} is any
2633 expression, which is used as a String.
2634 If you don't care about the file being readable you can use
2635 |glob()|.
2636 {file} is used as-is, you may want to expand wildcards first: >
2637 echo filereadable('~/.vimrc')
2638 0
2639 echo filereadable(expand('~/.vimrc'))
2640 1
2641
2642< Can also be used as a |method|: >
2643 GetName()->filereadable()
2644< *file_readable()*
2645 Obsolete name: file_readable().
2646
2647
2648filewritable({file}) *filewritable()*
2649 The result is a Number, which is 1 when a file with the
2650 name {file} exists, and can be written. If {file} doesn't
2651 exist, or is not writable, the result is 0. If {file} is a
2652 directory, and we can write to it, the result is 2.
2653
2654 Can also be used as a |method|: >
2655 GetName()->filewritable()
2656
2657
2658filter({expr1}, {expr2}) *filter()*
2659 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
2660 For each item in {expr1} evaluate {expr2} and when the result
2661 is zero or false remove the item from the |List| or
2662 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002663 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002664
2665 {expr2} must be a |string| or |Funcref|.
2666
2667 If {expr2} is a |string|, inside {expr2} |v:val| has the value
2668 of the current item. For a |Dictionary| |v:key| has the key
2669 of the current item and for a |List| |v:key| has the index of
2670 the current item. For a |Blob| |v:key| has the index of the
2671 current byte. For a |String| |v:key| has the index of the
2672 current character.
2673 Examples: >
2674 call filter(mylist, 'v:val !~ "OLD"')
2675< Removes the items where "OLD" appears. >
2676 call filter(mydict, 'v:key >= 8')
2677< Removes the items with a key below 8. >
2678 call filter(var, 0)
2679< Removes all the items, thus clears the |List| or |Dictionary|.
2680
2681 Note that {expr2} is the result of expression and is then
2682 used as an expression again. Often it is good to use a
2683 |literal-string| to avoid having to double backslashes.
2684
2685 If {expr2} is a |Funcref| it must take two arguments:
2686 1. the key or the index of the current item.
2687 2. the value of the current item.
2688 The function must return |TRUE| if the item should be kept.
2689 Example that keeps the odd items of a list: >
2690 func Odd(idx, val)
2691 return a:idx % 2 == 1
2692 endfunc
2693 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002694< It is shorter when using a |lambda|. In |Vim9| syntax: >
2695 call filter(myList, (idx, val) => idx * val <= 42)
2696< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002697 call filter(myList, {idx, val -> idx * val <= 42})
2698< If you do not use "val" you can leave it out: >
2699 call filter(myList, {idx -> idx % 2 == 1})
2700<
2701 In |Vim9| script the result must be true, false, zero or one.
2702 Other values will result in a type error.
2703
2704 For a |List| and a |Dictionary| the operation is done
2705 in-place. If you want it to remain unmodified make a copy
2706 first: >
2707 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2708
2709< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00002710 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002711 When an error is encountered while evaluating {expr2} no
2712 further items in {expr1} are processed.
2713 When {expr2} is a Funcref errors inside a function are ignored,
2714 unless it was defined with the "abort" flag.
2715
2716 Can also be used as a |method|: >
2717 mylist->filter(expr2)
2718
2719finddir({name} [, {path} [, {count}]]) *finddir()*
2720 Find directory {name} in {path}. Supports both downwards and
2721 upwards recursive directory searches. See |file-searching|
2722 for the syntax of {path}.
2723
2724 Returns the path of the first found match. When the found
2725 directory is below the current directory a relative path is
2726 returned. Otherwise a full path is returned.
2727 If {path} is omitted or empty then 'path' is used.
2728
2729 If the optional {count} is given, find {count}'s occurrence of
2730 {name} in {path} instead of the first one.
2731 When {count} is negative return all the matches in a |List|.
2732
Bram Moolenaar016188f2022-06-06 20:52:59 +01002733 Returns an empty string if the directory is not found.
2734
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002735 This is quite similar to the ex-command `:find`.
2736 {only available when compiled with the |+file_in_path|
2737 feature}
2738
2739 Can also be used as a |method|: >
2740 GetName()->finddir()
2741
2742findfile({name} [, {path} [, {count}]]) *findfile()*
2743 Just like |finddir()|, but find a file instead of a directory.
2744 Uses 'suffixesadd'.
2745 Example: >
2746 :echo findfile("tags.vim", ".;")
2747< Searches from the directory of the current file upwards until
2748 it finds the file "tags.vim".
2749
2750 Can also be used as a |method|: >
2751 GetName()->findfile()
2752
2753flatten({list} [, {maxdepth}]) *flatten()*
2754 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
2755 the result is a |List| without nesting, as if {maxdepth} is
2756 a very large number.
2757 The {list} is changed in place, use |flattennew()| if you do
2758 not want that.
2759 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00002760 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002761 *E900*
2762 {maxdepth} means how deep in nested lists changes are made.
2763 {list} is not modified when {maxdepth} is 0.
2764 {maxdepth} must be positive number.
2765
2766 If there is an error the number zero is returned.
2767
2768 Example: >
2769 :echo flatten([1, [2, [3, 4]], 5])
2770< [1, 2, 3, 4, 5] >
2771 :echo flatten([1, [2, [3, 4]], 5], 1)
2772< [1, 2, [3, 4], 5]
2773
2774 Can also be used as a |method|: >
2775 mylist->flatten()
2776<
2777flattennew({list} [, {maxdepth}]) *flattennew()*
2778 Like |flatten()| but first make a copy of {list}.
2779
2780
2781float2nr({expr}) *float2nr()*
2782 Convert {expr} to a Number by omitting the part after the
2783 decimal point.
2784 {expr} must evaluate to a |Float| or a Number.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002785 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002786 When the value of {expr} is out of range for a |Number| the
2787 result is truncated to 0x7fffffff or -0x7fffffff (or when
2788 64-bit Number support is enabled, 0x7fffffffffffffff or
2789 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
2790 64-bit Number support is enabled, -0x8000000000000000).
2791 Examples: >
2792 echo float2nr(3.95)
2793< 3 >
2794 echo float2nr(-23.45)
2795< -23 >
2796 echo float2nr(1.0e100)
2797< 2147483647 (or 9223372036854775807) >
2798 echo float2nr(-1.0e150)
2799< -2147483647 (or -9223372036854775807) >
2800 echo float2nr(1.0e-100)
2801< 0
2802
2803 Can also be used as a |method|: >
2804 Compute()->float2nr()
2805<
2806 {only available when compiled with the |+float| feature}
2807
2808
2809floor({expr}) *floor()*
2810 Return the largest integral value less than or equal to
2811 {expr} as a |Float| (round down).
2812 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002813 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002814 Examples: >
2815 echo floor(1.856)
2816< 1.0 >
2817 echo floor(-5.456)
2818< -6.0 >
2819 echo floor(4.0)
2820< 4.0
2821
2822 Can also be used as a |method|: >
2823 Compute()->floor()
2824<
2825 {only available when compiled with the |+float| feature}
2826
2827
2828fmod({expr1}, {expr2}) *fmod()*
2829 Return the remainder of {expr1} / {expr2}, even if the
2830 division is not representable. Returns {expr1} - i * {expr2}
2831 for some integer i such that if {expr2} is non-zero, the
2832 result has the same sign as {expr1} and magnitude less than
2833 the magnitude of {expr2}. If {expr2} is zero, the value
2834 returned is zero. The value returned is a |Float|.
2835 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002836 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
2837 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002838 Examples: >
2839 :echo fmod(12.33, 1.22)
2840< 0.13 >
2841 :echo fmod(-12.33, 1.22)
2842< -0.13
2843
2844 Can also be used as a |method|: >
2845 Compute()->fmod(1.22)
2846<
2847 {only available when compiled with |+float| feature}
2848
2849
2850fnameescape({string}) *fnameescape()*
2851 Escape {string} for use as file name command argument. All
2852 characters that have a special meaning, such as '%' and '|'
2853 are escaped with a backslash.
2854 For most systems the characters escaped are
2855 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2856 appears in a filename, it depends on the value of 'isfname'.
2857 A leading '+' and '>' is also escaped (special after |:edit|
2858 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01002859 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002860 Example: >
2861 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002862 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002863< results in executing: >
2864 edit \+some\ str\%nge\|name
2865<
2866 Can also be used as a |method|: >
2867 GetName()->fnameescape()
2868
2869fnamemodify({fname}, {mods}) *fnamemodify()*
2870 Modify file name {fname} according to {mods}. {mods} is a
2871 string of characters like it is used for file names on the
2872 command line. See |filename-modifiers|.
2873 Example: >
2874 :echo fnamemodify("main.c", ":p:h")
2875< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01002876 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01002877< If {mods} is empty or an unsupported modifier is used then
2878 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01002879 When {fname} is empty then with {mods} ":h" returns ".", so
2880 that `:cd` can be used with it. This is different from
2881 expand('%:h') without a buffer name, which returns an empty
2882 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002883 Note: Environment variables don't work in {fname}, use
2884 |expand()| first then.
2885
2886 Can also be used as a |method|: >
2887 GetName()->fnamemodify(':p:h')
2888
2889foldclosed({lnum}) *foldclosed()*
2890 The result is a Number. If the line {lnum} is in a closed
2891 fold, the result is the number of the first line in that fold.
2892 If the line {lnum} is not in a closed fold, -1 is returned.
2893 {lnum} is used like with |getline()|. Thus "." is the current
2894 line, "'m" mark m, etc.
2895
2896 Can also be used as a |method|: >
2897 GetLnum()->foldclosed()
2898
2899foldclosedend({lnum}) *foldclosedend()*
2900 The result is a Number. If the line {lnum} is in a closed
2901 fold, the result is the number of the last line in that fold.
2902 If the line {lnum} is not in a closed fold, -1 is returned.
2903 {lnum} is used like with |getline()|. Thus "." is the current
2904 line, "'m" mark m, etc.
2905
2906 Can also be used as a |method|: >
2907 GetLnum()->foldclosedend()
2908
2909foldlevel({lnum}) *foldlevel()*
2910 The result is a Number, which is the foldlevel of line {lnum}
2911 in the current buffer. For nested folds the deepest level is
2912 returned. If there is no fold at line {lnum}, zero is
2913 returned. It doesn't matter if the folds are open or closed.
2914 When used while updating folds (from 'foldexpr') -1 is
2915 returned for lines where folds are still to be updated and the
2916 foldlevel is unknown. As a special case the level of the
2917 previous line is usually available.
2918 {lnum} is used like with |getline()|. Thus "." is the current
2919 line, "'m" mark m, etc.
2920
2921 Can also be used as a |method|: >
2922 GetLnum()->foldlevel()
2923<
2924 *foldtext()*
2925foldtext() Returns a String, to be displayed for a closed fold. This is
2926 the default function used for the 'foldtext' option and should
2927 only be called from evaluating 'foldtext'. It uses the
2928 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2929 The returned string looks like this: >
2930 +-- 45 lines: abcdef
2931< The number of leading dashes depends on the foldlevel. The
2932 "45" is the number of lines in the fold. "abcdef" is the text
2933 in the first non-blank line of the fold. Leading white space,
2934 "//" or "/*" and the text from the 'foldmarker' and
2935 'commentstring' options is removed.
2936 When used to draw the actual foldtext, the rest of the line
2937 will be filled with the fold char from the 'fillchars'
2938 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002939 Returns an empty string when there is no fold.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002940 {not available when compiled without the |+folding| feature}
2941
2942foldtextresult({lnum}) *foldtextresult()*
2943 Returns the text that is displayed for the closed fold at line
2944 {lnum}. Evaluates 'foldtext' in the appropriate context.
2945 When there is no closed fold at {lnum} an empty string is
2946 returned.
2947 {lnum} is used like with |getline()|. Thus "." is the current
2948 line, "'m" mark m, etc.
2949 Useful when exporting folded text, e.g., to HTML.
2950 {not available when compiled without the |+folding| feature}
2951
2952
2953 Can also be used as a |method|: >
2954 GetLnum()->foldtextresult()
2955<
2956 *foreground()*
2957foreground() Move the Vim window to the foreground. Useful when sent from
2958 a client to a Vim server. |remote_send()|
2959 On Win32 systems this might not work, the OS does not always
2960 allow a window to bring itself to the foreground. Use
2961 |remote_foreground()| instead.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002962 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002963 Win32 console version}
2964
2965fullcommand({name}) *fullcommand()*
2966 Get the full command name from a short abbreviated command
2967 name; see |20.2| for details on command abbreviations.
2968
2969 The string argument {name} may start with a `:` and can
2970 include a [range], these are skipped and not returned.
2971 Returns an empty string if a command doesn't exist or if it's
2972 ambiguous (for user-defined commands).
2973
2974 For example `fullcommand('s')`, `fullcommand('sub')`,
2975 `fullcommand(':%substitute')` all return "substitute".
2976
2977 Can also be used as a |method|: >
2978 GetName()->fullcommand()
2979<
2980 *funcref()*
2981funcref({name} [, {arglist}] [, {dict}])
2982 Just like |function()|, but the returned Funcref will lookup
2983 the function by reference, not by name. This matters when the
2984 function {name} is redefined later.
2985
2986 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002987 It only works for an autoloaded function if it has already
2988 been loaded (to avoid mistakenly loading the autoload script
2989 when only intending to use the function name, use |function()|
2990 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002991 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002992
2993 Can also be used as a |method|: >
2994 GetFuncname()->funcref([arg])
2995<
2996 *function()* *partial* *E700* *E922* *E923*
2997function({name} [, {arglist}] [, {dict}])
2998 Return a |Funcref| variable that refers to function {name}.
2999 {name} can be the name of a user defined function or an
3000 internal function.
3001
3002 {name} can also be a Funcref or a partial. When it is a
3003 partial the dict stored in it will be used and the {dict}
3004 argument is not allowed. E.g.: >
3005 let FuncWithArg = function(dict.Func, [arg])
3006 let Broken = function(dict.Func, [arg], dict)
3007<
3008 When using the Funcref the function will be found by {name},
3009 also when it was redefined later. Use |funcref()| to keep the
3010 same function.
3011
3012 When {arglist} or {dict} is present this creates a partial.
3013 That means the argument list and/or the dictionary is stored in
3014 the Funcref and will be used when the Funcref is called.
3015
3016 The arguments are passed to the function in front of other
3017 arguments, but after any argument from |method|. Example: >
3018 func Callback(arg1, arg2, name)
3019 ...
3020 let Partial = function('Callback', ['one', 'two'])
3021 ...
3022 call Partial('name')
3023< Invokes the function as with: >
3024 call Callback('one', 'two', 'name')
3025
3026< With a |method|: >
3027 func Callback(one, two, three)
3028 ...
3029 let Partial = function('Callback', ['two'])
3030 ...
3031 eval 'one'->Partial('three')
3032< Invokes the function as with: >
3033 call Callback('one', 'two', 'three')
3034
3035< The function() call can be nested to add more arguments to the
3036 Funcref. The extra arguments are appended to the list of
3037 arguments. Example: >
3038 func Callback(arg1, arg2, name)
3039 ...
3040 let Func = function('Callback', ['one'])
3041 let Func2 = function(Func, ['two'])
3042 ...
3043 call Func2('name')
3044< Invokes the function as with: >
3045 call Callback('one', 'two', 'name')
3046
3047< The Dictionary is only useful when calling a "dict" function.
3048 In that case the {dict} is passed in as "self". Example: >
3049 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003050 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003051 endfunction
3052 ...
3053 let context = {"name": "example"}
3054 let Func = function('Callback', context)
3055 ...
3056 call Func() " will echo: called for example
3057< The use of function() is not needed when there are no extra
3058 arguments, these two are equivalent: >
3059 let Func = function('Callback', context)
3060 let Func = context.Callback
3061
3062< The argument list and the Dictionary can be combined: >
3063 function Callback(arg1, count) dict
3064 ...
3065 let context = {"name": "example"}
3066 let Func = function('Callback', ['one'], context)
3067 ...
3068 call Func(500)
3069< Invokes the function as with: >
3070 call context.Callback('one', 500)
3071<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003072 Returns 0 on error.
3073
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003074 Can also be used as a |method|: >
3075 GetFuncname()->function([arg])
3076
3077
3078garbagecollect([{atexit}]) *garbagecollect()*
3079 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3080 that have circular references.
3081
3082 There is hardly ever a need to invoke this function, as it is
3083 automatically done when Vim runs out of memory or is waiting
3084 for the user to press a key after 'updatetime'. Items without
3085 circular references are always freed when they become unused.
3086 This is useful if you have deleted a very big |List| and/or
3087 |Dictionary| with circular references in a script that runs
3088 for a long time.
3089
3090 When the optional {atexit} argument is one, garbage
3091 collection will also be done when exiting Vim, if it wasn't
3092 done before. This is useful when checking for memory leaks.
3093
3094 The garbage collection is not done immediately but only when
3095 it's safe to perform. This is when waiting for the user to
3096 type a character. To force garbage collection immediately use
3097 |test_garbagecollect_now()|.
3098
3099get({list}, {idx} [, {default}]) *get()*
3100 Get item {idx} from |List| {list}. When this item is not
3101 available return {default}. Return zero when {default} is
3102 omitted.
3103 Preferably used as a |method|: >
3104 mylist->get(idx)
3105get({blob}, {idx} [, {default}])
3106 Get byte {idx} from |Blob| {blob}. When this byte is not
3107 available return {default}. Return -1 when {default} is
3108 omitted.
3109 Preferably used as a |method|: >
3110 myblob->get(idx)
3111get({dict}, {key} [, {default}])
3112 Get item with key {key} from |Dictionary| {dict}. When this
3113 item is not available return {default}. Return zero when
3114 {default} is omitted. Useful example: >
3115 let val = get(g:, 'var_name', 'default')
3116< This gets the value of g:var_name if it exists, and uses
3117 'default' when it does not exist.
3118 Preferably used as a |method|: >
3119 mydict->get(key)
3120get({func}, {what})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003121 Get item {what} from Funcref {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003122 {what} are:
3123 "name" The function name
3124 "func" The function
3125 "dict" The dictionary
3126 "args" The list with arguments
Bram Moolenaar016188f2022-06-06 20:52:59 +01003127 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003128 Preferably used as a |method|: >
3129 myfunc->get(what)
3130<
3131 *getbufinfo()*
3132getbufinfo([{buf}])
3133getbufinfo([{dict}])
3134 Get information about buffers as a List of Dictionaries.
3135
3136 Without an argument information about all the buffers is
3137 returned.
3138
3139 When the argument is a |Dictionary| only the buffers matching
3140 the specified criteria are returned. The following keys can
3141 be specified in {dict}:
3142 buflisted include only listed buffers.
3143 bufloaded include only loaded buffers.
3144 bufmodified include only modified buffers.
3145
3146 Otherwise, {buf} specifies a particular buffer to return
3147 information for. For the use of {buf}, see |bufname()|
3148 above. If the buffer is found the returned List has one item.
3149 Otherwise the result is an empty list.
3150
3151 Each returned List item is a dictionary with the following
3152 entries:
3153 bufnr Buffer number.
3154 changed TRUE if the buffer is modified.
3155 changedtick Number of changes made to the buffer.
3156 hidden TRUE if the buffer is hidden.
3157 lastused Timestamp in seconds, like
3158 |localtime()|, when the buffer was
3159 last used.
3160 {only with the |+viminfo| feature}
3161 listed TRUE if the buffer is listed.
3162 lnum Line number used for the buffer when
3163 opened in the current window.
3164 Only valid if the buffer has been
3165 displayed in the window in the past.
3166 If you want the line number of the
3167 last known cursor position in a given
3168 window, use |line()|: >
3169 :echo line('.', {winid})
3170<
3171 linecount Number of lines in the buffer (only
3172 valid when loaded)
3173 loaded TRUE if the buffer is loaded.
3174 name Full path to the file in the buffer.
3175 signs List of signs placed in the buffer.
3176 Each list item is a dictionary with
3177 the following fields:
3178 id sign identifier
3179 lnum line number
3180 name sign name
3181 variables A reference to the dictionary with
3182 buffer-local variables.
3183 windows List of |window-ID|s that display this
3184 buffer
3185 popups List of popup |window-ID|s that
3186 display this buffer
3187
3188 Examples: >
3189 for buf in getbufinfo()
3190 echo buf.name
3191 endfor
3192 for buf in getbufinfo({'buflisted':1})
3193 if buf.changed
3194 ....
3195 endif
3196 endfor
3197<
3198 To get buffer-local options use: >
3199 getbufvar({bufnr}, '&option_name')
3200<
3201 Can also be used as a |method|: >
3202 GetBufnr()->getbufinfo()
3203<
3204
3205 *getbufline()*
3206getbufline({buf}, {lnum} [, {end}])
3207 Return a |List| with the lines starting from {lnum} to {end}
3208 (inclusive) in the buffer {buf}. If {end} is omitted, a
3209 |List| with only the line {lnum} is returned.
3210
3211 For the use of {buf}, see |bufname()| above.
3212
3213 For {lnum} and {end} "$" can be used for the last line of the
3214 buffer. Otherwise a number must be used.
3215
3216 When {lnum} is smaller than 1 or bigger than the number of
3217 lines in the buffer, an empty |List| is returned.
3218
3219 When {end} is greater than the number of lines in the buffer,
3220 it is treated as {end} is set to the number of lines in the
3221 buffer. When {end} is before {lnum} an empty |List| is
3222 returned.
3223
3224 This function works only for loaded buffers. For unloaded and
3225 non-existing buffers, an empty |List| is returned.
3226
3227 Example: >
3228 :let lines = getbufline(bufnr("myfile"), 1, "$")
3229
3230< Can also be used as a |method|: >
3231 GetBufnr()->getbufline(lnum)
3232
3233getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3234 The result is the value of option or local buffer variable
3235 {varname} in buffer {buf}. Note that the name without "b:"
3236 must be used.
3237 The {varname} argument is a string.
3238 When {varname} is empty returns a |Dictionary| with all the
3239 buffer-local variables.
3240 When {varname} is equal to "&" returns a |Dictionary| with all
3241 the buffer-local options.
3242 Otherwise, when {varname} starts with "&" returns the value of
3243 a buffer-local option.
3244 This also works for a global or buffer-local option, but it
3245 doesn't work for a global variable, window-local variable or
3246 window-local option.
3247 For the use of {buf}, see |bufname()| above.
3248 When the buffer or variable doesn't exist {def} or an empty
3249 string is returned, there is no error message.
3250 Examples: >
3251 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003252 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003253
3254< Can also be used as a |method|: >
3255 GetBufnr()->getbufvar(varname)
3256<
3257getchangelist([{buf}]) *getchangelist()*
3258 Returns the |changelist| for the buffer {buf}. For the use
3259 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3260 exist, an empty list is returned.
3261
3262 The returned list contains two entries: a list with the change
3263 locations and the current position in the list. Each
3264 entry in the change list is a dictionary with the following
3265 entries:
3266 col column number
3267 coladd column offset for 'virtualedit'
3268 lnum line number
3269 If buffer {buf} is the current buffer, then the current
3270 position refers to the position in the list. For other
3271 buffers, it is set to the length of the list.
3272
3273 Can also be used as a |method|: >
3274 GetBufnr()->getchangelist()
3275
3276getchar([expr]) *getchar()*
3277 Get a single character from the user or input stream.
3278 If [expr] is omitted, wait until a character is available.
3279 If [expr] is 0, only get a character when one is available.
3280 Return zero otherwise.
3281 If [expr] is 1, only check if a character is available, it is
3282 not consumed. Return zero if no character available.
3283 If you prefer always getting a string use |getcharstr()|.
3284
3285 Without [expr] and when [expr] is 0 a whole character or
3286 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01003287 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003288 Otherwise a String is returned with the encoded character.
3289 For a special key it's a String with a sequence of bytes
3290 starting with 0x80 (decimal: 128). This is the same value as
3291 the String "\<Key>", e.g., "\<Left>". The returned value is
3292 also a String when a modifier (shift, control, alt) was used
3293 that is not included in the character.
3294
3295 When [expr] is 0 and Esc is typed, there will be a short delay
3296 while Vim waits to see if this is the start of an escape
3297 sequence.
3298
3299 When [expr] is 1 only the first byte is returned. For a
3300 one-byte character it is the character itself as a number.
3301 Use nr2char() to convert it to a String.
3302
3303 Use getcharmod() to obtain any additional modifiers.
3304
3305 When the user clicks a mouse button, the mouse event will be
3306 returned. The position can then be found in |v:mouse_col|,
3307 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3308 |getmousepos()| can also be used. Mouse move events will be
3309 ignored.
3310 This example positions the mouse as it would normally happen: >
3311 let c = getchar()
3312 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003313 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003314 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003315 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003316 endif
3317<
3318 When using bracketed paste only the first character is
3319 returned, the rest of the pasted text is dropped.
3320 |xterm-bracketed-paste|.
3321
3322 There is no prompt, you will somehow have to make clear to the
3323 user that a character has to be typed. The screen is not
3324 redrawn, e.g. when resizing the window. When using a popup
3325 window it should work better with a |popup-filter|.
3326
3327 There is no mapping for the character.
3328 Key codes are replaced, thus when the user presses the <Del>
3329 key you get the code for the <Del> key, not the raw character
3330 sequence. Examples: >
3331 getchar() == "\<Del>"
3332 getchar() == "\<S-Left>"
3333< This example redefines "f" to ignore case: >
3334 :nmap f :call FindChar()<CR>
3335 :function FindChar()
3336 : let c = nr2char(getchar())
3337 : while col('.') < col('$') - 1
3338 : normal l
3339 : if getline('.')[col('.') - 1] ==? c
3340 : break
3341 : endif
3342 : endwhile
3343 :endfunction
3344<
3345 You may also receive synthetic characters, such as
3346 |<CursorHold>|. Often you will want to ignore this and get
3347 another character: >
3348 :function GetKey()
3349 : let c = getchar()
3350 : while c == "\<CursorHold>"
3351 : let c = getchar()
3352 : endwhile
3353 : return c
3354 :endfunction
3355
3356getcharmod() *getcharmod()*
3357 The result is a Number which is the state of the modifiers for
3358 the last obtained character with getchar() or in another way.
3359 These values are added together:
3360 2 shift
3361 4 control
3362 8 alt (meta)
3363 16 meta (when it's different from ALT)
3364 32 mouse double click
3365 64 mouse triple click
3366 96 mouse quadruple click (== 32 + 64)
3367 128 command (Macintosh only)
3368 Only the modifiers that have not been included in the
3369 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01003370 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003371
3372 *getcharpos()*
3373getcharpos({expr})
3374 Get the position for String {expr}. Same as |getpos()| but the
3375 column number in the returned List is a character index
3376 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00003377 If |getpos()| returns a very large column number, equal to
3378 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003379 of the last character.
3380
3381 Example:
3382 With the cursor on '세' in line 5 with text "여보세요": >
3383 getcharpos('.') returns [0, 5, 3, 0]
3384 getpos('.') returns [0, 5, 7, 0]
3385<
3386 Can also be used as a |method|: >
3387 GetMark()->getcharpos()
3388
3389getcharsearch() *getcharsearch()*
3390 Return the current character search information as a {dict}
3391 with the following entries:
3392
3393 char character previously used for a character
3394 search (|t|, |f|, |T|, or |F|); empty string
3395 if no character search has been performed
3396 forward direction of character search; 1 for forward,
3397 0 for backward
3398 until type of character search; 1 for a |t| or |T|
3399 character search, 0 for an |f| or |F|
3400 character search
3401
3402 This can be useful to always have |;| and |,| search
3403 forward/backward regardless of the direction of the previous
3404 character search: >
3405 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3406 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3407< Also see |setcharsearch()|.
3408
3409
3410getcharstr([expr]) *getcharstr()*
3411 Get a single character from the user or input stream as a
3412 string.
3413 If [expr] is omitted, wait until a character is available.
3414 If [expr] is 0 or false, only get a character when one is
3415 available. Return an empty string otherwise.
3416 If [expr] is 1 or true, only check if a character is
3417 available, it is not consumed. Return an empty string
3418 if no character is available.
3419 Otherwise this works like |getchar()|, except that a number
3420 result is converted to a string.
3421
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003422getcmdcompltype() *getcmdcompltype()*
3423 Return the type of the current command-line completion.
3424 Only works when the command line is being edited, thus
3425 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01003426 See |:command-completion| for the return string.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003427 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3428 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003429
3430getcmdline() *getcmdline()*
3431 Return the current command-line. Only works when the command
3432 line is being edited, thus requires use of |c_CTRL-\_e| or
3433 |c_CTRL-R_=|.
3434 Example: >
3435 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
3436< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
3437 Returns an empty string when entering a password or using
3438 |inputsecret()|.
3439
3440getcmdpos() *getcmdpos()*
3441 Return the position of the cursor in the command line as a
3442 byte count. The first column is 1.
3443 Only works when editing the command line, thus requires use of
3444 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3445 Returns 0 otherwise.
3446 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3447
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003448getcmdscreenpos() *getcmdscreenpos()*
3449 Return the screen position of the cursor in the command line
3450 as a byte count. The first column is 1.
3451 Instead of |getcmdpos()|, it adds the prompt position.
3452 Only works when editing the command line, thus requires use of
3453 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3454 Returns 0 otherwise.
3455 Also see |getcmdpos()|, |setcmdpos()|.
3456
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003457getcmdtype() *getcmdtype()*
3458 Return the current command-line type. Possible return values
3459 are:
3460 : normal Ex command
3461 > debug mode command |debug-mode|
3462 / forward search command
3463 ? backward search command
3464 @ |input()| command
3465 - |:insert| or |:append| command
3466 = |i_CTRL-R_=|
3467 Only works when editing the command line, thus requires use of
3468 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3469 Returns an empty string otherwise.
3470 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3471
3472getcmdwintype() *getcmdwintype()*
3473 Return the current |command-line-window| type. Possible return
3474 values are the same as |getcmdtype()|. Returns an empty string
3475 when not in the command-line window.
3476
3477getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
3478 Return a list of command-line completion matches. The String
3479 {type} argument specifies what for. The following completion
3480 types are supported:
3481
3482 arglist file names in argument list
3483 augroup autocmd groups
3484 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003485 behave |:behave| suboptions
3486 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003487 color color schemes
3488 command Ex command
3489 cmdline |cmdline-completion| result
3490 compiler compilers
3491 cscope |:cscope| suboptions
3492 diff_buffer |:diffget| and |:diffput| completion
3493 dir directory names
3494 environment environment variable names
3495 event autocommand events
3496 expression Vim expression
3497 file file and directory names
3498 file_in_path file and directory names in |'path'|
3499 filetype filetype names |'filetype'|
3500 function function name
3501 help help subjects
3502 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003503 history |:history| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003504 locale locale names (as output of locale -a)
3505 mapclear buffer argument
3506 mapping mapping name
3507 menu menus
3508 messages |:messages| suboptions
3509 option options
3510 packadd optional package |pack-add| names
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003511 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003512 shellcmd Shell command
3513 sign |:sign| suboptions
3514 syntax syntax file names |'syntax'|
3515 syntime |:syntime| suboptions
3516 tag tags
3517 tag_listfiles tags, file names
3518 user user names
3519 var user variables
3520
3521 If {pat} is an empty string, then all the matches are
3522 returned. Otherwise only items matching {pat} are returned.
3523 See |wildcards| for the use of special characters in {pat}.
3524
3525 If the optional {filtered} flag is set to 1, then 'wildignore'
3526 is applied to filter the results. Otherwise all the matches
3527 are returned. The 'wildignorecase' option always applies.
3528
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003529 If the 'wildoptions' option contains 'fuzzy', then fuzzy
3530 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003531 regular expression matching is used. Thus this function
3532 follows the user preference, what happens on the command line.
3533 If you do not want this you can make 'wildoptions' empty
3534 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003535
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003536 If {type} is "cmdline", then the |cmdline-completion| result is
3537 returned. For example, to complete the possible values after
3538 a ":call" command: >
3539 echo getcompletion('call ', 'cmdline')
3540<
3541 If there are no matches, an empty list is returned. An
3542 invalid value for {type} produces an error.
3543
3544 Can also be used as a |method|: >
3545 GetPattern()->getcompletion('color')
3546<
3547 *getcurpos()*
3548getcurpos([{winid}])
3549 Get the position of the cursor. This is like getpos('.'), but
3550 includes an extra "curswant" item in the list:
3551 [0, lnum, col, off, curswant] ~
3552 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00003553 cursor vertically. After |$| command it will be a very large
3554 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003555 |getpos()|.
3556 The first "bufnum" item is always zero. The byte position of
3557 the cursor is returned in 'col'. To get the character
3558 position, use |getcursorcharpos()|.
3559
3560 The optional {winid} argument can specify the window. It can
3561 be the window number or the |window-ID|. The last known
3562 cursor position is returned, this may be invalid for the
3563 current value of the buffer if it is not the current window.
3564 If {winid} is invalid a list with zeroes is returned.
3565
3566 This can be used to save and restore the cursor position: >
3567 let save_cursor = getcurpos()
3568 MoveTheCursorAround
3569 call setpos('.', save_cursor)
3570< Note that this only works within the window. See
3571 |winrestview()| for restoring more state.
3572
3573 Can also be used as a |method|: >
3574 GetWinid()->getcurpos()
3575<
3576 *getcursorcharpos()*
3577getcursorcharpos([{winid}])
3578 Same as |getcurpos()| but the column number in the returned
3579 List is a character index instead of a byte index.
3580
3581 Example:
3582 With the cursor on '보' in line 3 with text "여보세요": >
3583 getcursorcharpos() returns [0, 3, 2, 0, 3]
3584 getcurpos() returns [0, 3, 4, 0, 3]
3585<
3586 Can also be used as a |method|: >
3587 GetWinid()->getcursorcharpos()
3588
3589< *getcwd()*
3590getcwd([{winnr} [, {tabnr}]])
3591 The result is a String, which is the name of the current
3592 working directory. 'autochdir' is ignored.
3593
3594 With {winnr} return the local current directory of this window
3595 in the current tab page. {winnr} can be the window number or
3596 the |window-ID|.
3597 If {winnr} is -1 return the name of the global working
3598 directory. See also |haslocaldir()|.
3599
3600 With {winnr} and {tabnr} return the local current directory of
3601 the window in the specified tab page. If {winnr} is -1 return
3602 the working directory of the tabpage.
3603 If {winnr} is zero use the current window, if {tabnr} is zero
3604 use the current tabpage.
3605 Without any arguments, return the actual working directory of
3606 the current window.
3607 Return an empty string if the arguments are invalid.
3608
3609 Examples: >
3610 " Get the working directory of the current window
3611 :echo getcwd()
3612 :echo getcwd(0)
3613 :echo getcwd(0, 0)
3614 " Get the working directory of window 3 in tabpage 2
3615 :echo getcwd(3, 2)
3616 " Get the global working directory
3617 :echo getcwd(-1)
3618 " Get the working directory of tabpage 3
3619 :echo getcwd(-1, 3)
3620 " Get the working directory of current tabpage
3621 :echo getcwd(-1, 0)
3622
3623< Can also be used as a |method|: >
3624 GetWinnr()->getcwd()
3625
3626getenv({name}) *getenv()*
3627 Return the value of environment variable {name}. The {name}
3628 argument is a string, without a leading '$'. Example: >
3629 myHome = getenv('HOME')
3630
3631< When the variable does not exist |v:null| is returned. That
3632 is different from a variable set to an empty string, although
3633 some systems interpret the empty value as the variable being
3634 deleted. See also |expr-env|.
3635
3636 Can also be used as a |method|: >
3637 GetVarname()->getenv()
3638
3639getfontname([{name}]) *getfontname()*
3640 Without an argument returns the name of the normal font being
3641 used. Like what is used for the Normal highlight group
3642 |hl-Normal|.
3643 With an argument a check is done whether String {name} is a
3644 valid font name. If not then an empty string is returned.
3645 Otherwise the actual font name is returned, or {name} if the
3646 GUI does not support obtaining the real name.
3647 Only works when the GUI is running, thus not in your vimrc or
3648 gvimrc file. Use the |GUIEnter| autocommand to use this
3649 function just after the GUI has started.
3650 Note that the GTK GUI accepts any font name, thus checking for
3651 a valid name does not work.
3652
3653getfperm({fname}) *getfperm()*
3654 The result is a String, which is the read, write, and execute
3655 permissions of the given file {fname}.
3656 If {fname} does not exist or its directory cannot be read, an
3657 empty string is returned.
3658 The result is of the form "rwxrwxrwx", where each group of
3659 "rwx" flags represent, in turn, the permissions of the owner
3660 of the file, the group the file belongs to, and other users.
3661 If a user does not have a given permission the flag for this
3662 is replaced with the string "-". Examples: >
3663 :echo getfperm("/etc/passwd")
3664 :echo getfperm(expand("~/.vimrc"))
3665< This will hopefully (from a security point of view) display
3666 the string "rw-r--r--" or even "rw-------".
3667
3668 Can also be used as a |method|: >
3669 GetFilename()->getfperm()
3670<
3671 For setting permissions use |setfperm()|.
3672
3673getfsize({fname}) *getfsize()*
3674 The result is a Number, which is the size in bytes of the
3675 given file {fname}.
3676 If {fname} is a directory, 0 is returned.
3677 If the file {fname} can't be found, -1 is returned.
3678 If the size of {fname} is too big to fit in a Number then -2
3679 is returned.
3680
3681 Can also be used as a |method|: >
3682 GetFilename()->getfsize()
3683
3684getftime({fname}) *getftime()*
3685 The result is a Number, which is the last modification time of
3686 the given file {fname}. The value is measured as seconds
3687 since 1st Jan 1970, and may be passed to strftime(). See also
3688 |localtime()| and |strftime()|.
3689 If the file {fname} can't be found -1 is returned.
3690
3691 Can also be used as a |method|: >
3692 GetFilename()->getftime()
3693
3694getftype({fname}) *getftype()*
3695 The result is a String, which is a description of the kind of
3696 file of the given file {fname}.
3697 If {fname} does not exist an empty string is returned.
3698 Here is a table over different kinds of files and their
3699 results:
3700 Normal file "file"
3701 Directory "dir"
3702 Symbolic link "link"
3703 Block device "bdev"
3704 Character device "cdev"
3705 Socket "socket"
3706 FIFO "fifo"
3707 All other "other"
3708 Example: >
3709 getftype("/home")
3710< Note that a type such as "link" will only be returned on
3711 systems that support it. On some systems only "dir" and
3712 "file" are returned. On MS-Windows a symbolic link to a
3713 directory returns "dir" instead of "link".
3714
3715 Can also be used as a |method|: >
3716 GetFilename()->getftype()
3717
3718getimstatus() *getimstatus()*
3719 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01003720 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003721 See 'imstatusfunc'.
3722
3723getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
3724 Returns the |jumplist| for the specified window.
3725
3726 Without arguments use the current window.
3727 With {winnr} only use this window in the current tab page.
3728 {winnr} can also be a |window-ID|.
3729 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01003730 page. If {winnr} or {tabnr} is invalid, an empty list is
3731 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003732
3733 The returned list contains two entries: a list with the jump
3734 locations and the last used jump position number in the list.
3735 Each entry in the jump location list is a dictionary with
3736 the following entries:
3737 bufnr buffer number
3738 col column number
3739 coladd column offset for 'virtualedit'
3740 filename filename if available
3741 lnum line number
3742
3743 Can also be used as a |method|: >
3744 GetWinnr()->getjumplist()
3745
3746< *getline()*
3747getline({lnum} [, {end}])
3748 Without {end} the result is a String, which is line {lnum}
3749 from the current buffer. Example: >
3750 getline(1)
3751< When {lnum} is a String that doesn't start with a
3752 digit, |line()| is called to translate the String into a Number.
3753 To get the line under the cursor: >
3754 getline(".")
3755< When {lnum} is a number smaller than 1 or bigger than the
3756 number of lines in the buffer, an empty string is returned.
3757
3758 When {end} is given the result is a |List| where each item is
3759 a line from the current buffer in the range {lnum} to {end},
3760 including line {end}.
3761 {end} is used in the same way as {lnum}.
3762 Non-existing lines are silently omitted.
3763 When {end} is before {lnum} an empty |List| is returned.
3764 Example: >
3765 :let start = line('.')
3766 :let end = search("^$") - 1
3767 :let lines = getline(start, end)
3768
3769< Can also be used as a |method|: >
3770 ComputeLnum()->getline()
3771
3772< To get lines from another buffer see |getbufline()|
3773
3774getloclist({nr} [, {what}]) *getloclist()*
3775 Returns a |List| with all the entries in the location list for
3776 window {nr}. {nr} can be the window number or the |window-ID|.
3777 When {nr} is zero the current window is used.
3778
3779 For a location list window, the displayed location list is
3780 returned. For an invalid window number {nr}, an empty list is
3781 returned. Otherwise, same as |getqflist()|.
3782
3783 If the optional {what} dictionary argument is supplied, then
3784 returns the items listed in {what} as a dictionary. Refer to
3785 |getqflist()| for the supported items in {what}.
3786
3787 In addition to the items supported by |getqflist()| in {what},
3788 the following item is supported by |getloclist()|:
3789
3790 filewinid id of the window used to display files
3791 from the location list. This field is
3792 applicable only when called from a
3793 location list window. See
3794 |location-list-file-window| for more
3795 details.
3796
3797 Returns a |Dictionary| with default values if there is no
3798 location list for the window {nr}.
3799 Returns an empty Dictionary if window {nr} does not exist.
3800
3801 Examples (See also |getqflist-examples|): >
3802 :echo getloclist(3, {'all': 0})
3803 :echo getloclist(5, {'filewinid': 0})
3804
3805
3806getmarklist([{buf}]) *getmarklist()*
3807 Without the {buf} argument returns a |List| with information
3808 about all the global marks. |mark|
3809
3810 If the optional {buf} argument is specified, returns the
3811 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01003812 see |bufname()|. If {buf} is invalid, an empty list is
3813 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003814
3815 Each item in the returned List is a |Dict| with the following:
3816 mark name of the mark prefixed by "'"
3817 pos a |List| with the position of the mark:
3818 [bufnum, lnum, col, off]
3819 Refer to |getpos()| for more information.
3820 file file name
3821
3822 Refer to |getpos()| for getting information about a specific
3823 mark.
3824
3825 Can also be used as a |method|: >
3826 GetBufnr()->getmarklist()
3827
3828getmatches([{win}]) *getmatches()*
3829 Returns a |List| with all matches previously defined for the
3830 current window by |matchadd()| and the |:match| commands.
3831 |getmatches()| is useful in combination with |setmatches()|,
3832 as |setmatches()| can restore a list of matches saved by
3833 |getmatches()|.
3834 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01003835 window ID instead of the current window. If {win} is invalid,
3836 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003837 Example: >
3838 :echo getmatches()
3839< [{'group': 'MyGroup1', 'pattern': 'TODO',
3840 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3841 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3842 :let m = getmatches()
3843 :call clearmatches()
3844 :echo getmatches()
3845< [] >
3846 :call setmatches(m)
3847 :echo getmatches()
3848< [{'group': 'MyGroup1', 'pattern': 'TODO',
3849 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3850 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3851 :unlet m
3852<
3853getmousepos() *getmousepos()*
3854 Returns a |Dictionary| with the last known position of the
3855 mouse. This can be used in a mapping for a mouse click or in
3856 a filter of a popup window. The items are:
3857 screenrow screen row
3858 screencol screen column
3859 winid Window ID of the click
3860 winrow row inside "winid"
3861 wincol column inside "winid"
3862 line text line inside "winid"
3863 column text column inside "winid"
3864 All numbers are 1-based.
3865
3866 If not over a window, e.g. when in the command line, then only
3867 "screenrow" and "screencol" are valid, the others are zero.
3868
3869 When on the status line below a window or the vertical
3870 separator right of a window, the "line" and "column" values
3871 are zero.
3872
3873 When the position is after the text then "column" is the
3874 length of the text in bytes plus one.
3875
3876 If the mouse is over a popup window then that window is used.
3877
3878 When using |getchar()| the Vim variables |v:mouse_lnum|,
3879 |v:mouse_col| and |v:mouse_winid| also provide these values.
3880
3881 *getpid()*
3882getpid() Return a Number which is the process ID of the Vim process.
3883 On Unix and MS-Windows this is a unique number, until Vim
3884 exits.
3885
3886 *getpos()*
3887getpos({expr}) Get the position for String {expr}. For possible values of
3888 {expr} see |line()|. For getting the cursor position see
3889 |getcurpos()|.
3890 The result is a |List| with four numbers:
3891 [bufnum, lnum, col, off]
3892 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3893 is the buffer number of the mark.
3894 "lnum" and "col" are the position in the buffer. The first
3895 column is 1.
3896 The "off" number is zero, unless 'virtualedit' is used. Then
3897 it is the offset in screen columns from the start of the
3898 character. E.g., a position within a <Tab> or after the last
3899 character.
3900 Note that for '< and '> Visual mode matters: when it is "V"
3901 (visual line mode) the column of '< is zero and the column of
naohiro ono56200ee2022-01-01 14:59:44 +00003902 '> is a large number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003903 The column number in the returned List is the byte position
3904 within the line. To get the character position in the line,
3905 use |getcharpos()|.
naohiro ono56200ee2022-01-01 14:59:44 +00003906 A very large column number equal to |v:maxcol| can be returned,
3907 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01003908 If {expr} is invalid, returns a list with all zeros.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003909 This can be used to save and restore the position of a mark: >
3910 let save_a_mark = getpos("'a")
3911 ...
3912 call setpos("'a", save_a_mark)
3913< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
3914
3915 Can also be used as a |method|: >
3916 GetMark()->getpos()
3917
3918getqflist([{what}]) *getqflist()*
3919 Returns a |List| with all the current quickfix errors. Each
3920 list item is a dictionary with these entries:
3921 bufnr number of buffer that has the file name, use
3922 bufname() to get the name
3923 module module name
3924 lnum line number in the buffer (first line is 1)
3925 end_lnum
3926 end of line number if the item is multiline
3927 col column number (first column is 1)
3928 end_col end of column number if the item has range
3929 vcol |TRUE|: "col" is visual column
3930 |FALSE|: "col" is byte index
3931 nr error number
3932 pattern search pattern used to locate the error
3933 text description of the error
3934 type type of the error, 'E', '1', etc.
3935 valid |TRUE|: recognized error message
3936
3937 When there is no error list or it's empty, an empty list is
3938 returned. Quickfix list entries with a non-existing buffer
3939 number are returned with "bufnr" set to zero (Note: some
3940 functions accept buffer number zero for the alternate buffer,
3941 you may need to explicitly check for zero).
3942
3943 Useful application: Find pattern matches in multiple files and
3944 do something with them: >
3945 :vimgrep /theword/jg *.c
3946 :for d in getqflist()
3947 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3948 :endfor
3949<
3950 If the optional {what} dictionary argument is supplied, then
3951 returns only the items listed in {what} as a dictionary. The
3952 following string items are supported in {what}:
3953 changedtick get the total number of changes made
3954 to the list |quickfix-changedtick|
3955 context get the |quickfix-context|
3956 efm errorformat to use when parsing "lines". If
3957 not present, then the 'errorformat' option
3958 value is used.
3959 id get information for the quickfix list with
3960 |quickfix-ID|; zero means the id for the
3961 current list or the list specified by "nr"
3962 idx get information for the quickfix entry at this
3963 index in the list specified by 'id' or 'nr'.
3964 If set to zero, then uses the current entry.
3965 See |quickfix-index|
3966 items quickfix list entries
3967 lines parse a list of lines using 'efm' and return
3968 the resulting entries. Only a |List| type is
3969 accepted. The current quickfix list is not
3970 modified. See |quickfix-parse|.
3971 nr get information for this quickfix list; zero
3972 means the current quickfix list and "$" means
3973 the last quickfix list
3974 qfbufnr number of the buffer displayed in the quickfix
3975 window. Returns 0 if the quickfix buffer is
3976 not present. See |quickfix-buffer|.
3977 size number of entries in the quickfix list
3978 title get the list title |quickfix-title|
3979 winid get the quickfix |window-ID|
3980 all all of the above quickfix properties
3981 Non-string items in {what} are ignored. To get the value of a
3982 particular item, set it to zero.
3983 If "nr" is not present then the current quickfix list is used.
3984 If both "nr" and a non-zero "id" are specified, then the list
3985 specified by "id" is used.
3986 To get the number of lists in the quickfix stack, set "nr" to
3987 "$" in {what}. The "nr" value in the returned dictionary
3988 contains the quickfix stack size.
3989 When "lines" is specified, all the other items except "efm"
3990 are ignored. The returned dictionary contains the entry
3991 "items" with the list of entries.
3992
3993 The returned dictionary contains the following entries:
3994 changedtick total number of changes made to the
3995 list |quickfix-changedtick|
3996 context quickfix list context. See |quickfix-context|
3997 If not present, set to "".
3998 id quickfix list ID |quickfix-ID|. If not
3999 present, set to 0.
4000 idx index of the quickfix entry in the list. If not
4001 present, set to 0.
4002 items quickfix list entries. If not present, set to
4003 an empty list.
4004 nr quickfix list number. If not present, set to 0
4005 qfbufnr number of the buffer displayed in the quickfix
4006 window. If not present, set to 0.
4007 size number of entries in the quickfix list. If not
4008 present, set to 0.
4009 title quickfix list title text. If not present, set
4010 to "".
4011 winid quickfix |window-ID|. If not present, set to 0
4012
4013 Examples (See also |getqflist-examples|): >
4014 :echo getqflist({'all': 1})
4015 :echo getqflist({'nr': 2, 'title': 1})
4016 :echo getqflist({'lines' : ["F1:10:L10"]})
4017<
4018getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4019 The result is a String, which is the contents of register
4020 {regname}. Example: >
4021 :let cliptext = getreg('*')
4022< When register {regname} was not set the result is an empty
4023 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004024 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004025
4026 getreg('=') returns the last evaluated value of the expression
4027 register. (For use in maps.)
4028 getreg('=', 1) returns the expression itself, so that it can
4029 be restored with |setreg()|. For other registers the extra
4030 argument is ignored, thus you can always give it.
4031
4032 If {list} is present and |TRUE|, the result type is changed
4033 to |List|. Each list item is one text line. Use it if you care
4034 about zero bytes possibly present inside register: without
4035 third argument both NLs and zero bytes are represented as NLs
4036 (see |NL-used-for-Nul|).
4037 When the register was not set an empty list is returned.
4038
4039 If {regname} is "", the unnamed register '"' is used.
4040 If {regname} is not specified, |v:register| is used.
4041 In |Vim9-script| {regname} must be one character.
4042
4043 Can also be used as a |method|: >
4044 GetRegname()->getreg()
4045
4046getreginfo([{regname}]) *getreginfo()*
4047 Returns detailed information about register {regname} as a
4048 Dictionary with the following entries:
4049 regcontents List of lines contained in register
4050 {regname}, like
4051 |getreg|({regname}, 1, 1).
4052 regtype the type of register {regname}, as in
4053 |getregtype()|.
4054 isunnamed Boolean flag, v:true if this register
4055 is currently pointed to by the unnamed
4056 register.
4057 points_to for the unnamed register, gives the
4058 single letter name of the register
4059 currently pointed to (see |quotequote|).
4060 For example, after deleting a line
4061 with `dd`, this field will be "1",
4062 which is the register that got the
4063 deleted text.
4064
4065 The {regname} argument is a string. If {regname} is invalid
4066 or not set, an empty Dictionary will be returned.
4067 If {regname} is "" or "@", the unnamed register '"' is used.
4068 If {regname} is not specified, |v:register| is used.
4069 The returned Dictionary can be passed to |setreg()|.
4070 In |Vim9-script| {regname} must be one character.
4071
4072 Can also be used as a |method|: >
4073 GetRegname()->getreginfo()
4074
4075getregtype([{regname}]) *getregtype()*
4076 The result is a String, which is type of register {regname}.
4077 The value will be one of:
4078 "v" for |characterwise| text
4079 "V" for |linewise| text
4080 "<CTRL-V>{width}" for |blockwise-visual| text
4081 "" for an empty or unknown register
4082 <CTRL-V> is one character with value 0x16.
4083 The {regname} argument is a string. If {regname} is "", the
4084 unnamed register '"' is used. If {regname} is not specified,
4085 |v:register| is used.
4086 In |Vim9-script| {regname} must be one character.
4087
4088 Can also be used as a |method|: >
4089 GetRegname()->getregtype()
4090
4091gettabinfo([{tabnr}]) *gettabinfo()*
4092 If {tabnr} is not specified, then information about all the
4093 tab pages is returned as a |List|. Each List item is a
4094 |Dictionary|. Otherwise, {tabnr} specifies the tab page
4095 number and information about that one is returned. If the tab
4096 page does not exist an empty List is returned.
4097
4098 Each List item is a |Dictionary| with the following entries:
4099 tabnr tab page number.
4100 variables a reference to the dictionary with
4101 tabpage-local variables
4102 windows List of |window-ID|s in the tab page.
4103
4104 Can also be used as a |method|: >
4105 GetTabnr()->gettabinfo()
4106
4107gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
4108 Get the value of a tab-local variable {varname} in tab page
4109 {tabnr}. |t:var|
4110 Tabs are numbered starting with one.
4111 The {varname} argument is a string. When {varname} is empty a
4112 dictionary with all tab-local variables is returned.
4113 Note that the name without "t:" must be used.
4114 When the tab or variable doesn't exist {def} or an empty
4115 string is returned, there is no error message.
4116
4117 Can also be used as a |method|: >
4118 GetTabnr()->gettabvar(varname)
4119
4120gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
4121 Get the value of window-local variable {varname} in window
4122 {winnr} in tab page {tabnr}.
4123 The {varname} argument is a string. When {varname} is empty a
4124 dictionary with all window-local variables is returned.
4125 When {varname} is equal to "&" get the values of all
4126 window-local options in a |Dictionary|.
4127 Otherwise, when {varname} starts with "&" get the value of a
4128 window-local option.
4129 Note that {varname} must be the name without "w:".
4130 Tabs are numbered starting with one. For the current tabpage
4131 use |getwinvar()|.
4132 {winnr} can be the window number or the |window-ID|.
4133 When {winnr} is zero the current window is used.
4134 This also works for a global option, buffer-local option and
4135 window-local option, but it doesn't work for a global variable
4136 or buffer-local variable.
4137 When the tab, window or variable doesn't exist {def} or an
4138 empty string is returned, there is no error message.
4139 Examples: >
4140 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004141 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004142<
4143 To obtain all window-local variables use: >
4144 gettabwinvar({tabnr}, {winnr}, '&')
4145
4146< Can also be used as a |method|: >
4147 GetTabnr()->gettabwinvar(winnr, varname)
4148
4149gettagstack([{winnr}]) *gettagstack()*
4150 The result is a Dict, which is the tag stack of window {winnr}.
4151 {winnr} can be the window number or the |window-ID|.
4152 When {winnr} is not specified, the current window is used.
4153 When window {winnr} doesn't exist, an empty Dict is returned.
4154
4155 The returned dictionary contains the following entries:
4156 curidx Current index in the stack. When at
4157 top of the stack, set to (length + 1).
4158 Index of bottom of the stack is 1.
4159 items List of items in the stack. Each item
4160 is a dictionary containing the
4161 entries described below.
4162 length Number of entries in the stack.
4163
4164 Each item in the stack is a dictionary with the following
4165 entries:
4166 bufnr buffer number of the current jump
4167 from cursor position before the tag jump.
4168 See |getpos()| for the format of the
4169 returned list.
4170 matchnr current matching tag number. Used when
4171 multiple matching tags are found for a
4172 name.
4173 tagname name of the tag
4174
4175 See |tagstack| for more information about the tag stack.
4176
4177 Can also be used as a |method|: >
4178 GetWinnr()->gettagstack()
4179
4180
4181gettext({text}) *gettext()*
4182 Translate String {text} if possible.
4183 This is mainly for use in the distributed Vim scripts. When
4184 generating message translations the {text} is extracted by
4185 xgettext, the translator can add the translated message in the
4186 .po file and Vim will lookup the translation when gettext() is
4187 called.
4188 For {text} double quoted strings are preferred, because
4189 xgettext does not understand escaping in single quoted
4190 strings.
4191
4192
4193getwininfo([{winid}]) *getwininfo()*
4194 Returns information about windows as a |List| with Dictionaries.
4195
4196 If {winid} is given Information about the window with that ID
4197 is returned, as a |List| with one item. If the window does not
4198 exist the result is an empty list.
4199
4200 Without {winid} information about all the windows in all the
4201 tab pages is returned.
4202
4203 Each List item is a |Dictionary| with the following entries:
4204 botline last complete displayed buffer line
4205 bufnr number of buffer in the window
4206 height window height (excluding winbar)
4207 loclist 1 if showing a location list
4208 {only with the +quickfix feature}
4209 quickfix 1 if quickfix or location list window
4210 {only with the +quickfix feature}
4211 terminal 1 if a terminal window
4212 {only with the +terminal feature}
4213 tabnr tab page number
4214 topline first displayed buffer line
4215 variables a reference to the dictionary with
4216 window-local variables
4217 width window width
4218 winbar 1 if the window has a toolbar, 0
4219 otherwise
4220 wincol leftmost screen column of the window;
4221 "col" from |win_screenpos()|
4222 textoff number of columns occupied by any
4223 'foldcolumn', 'signcolumn' and line
4224 number in front of the text
4225 winid |window-ID|
4226 winnr window number
4227 winrow topmost screen line of the window;
4228 "row" from |win_screenpos()|
4229
4230 Can also be used as a |method|: >
4231 GetWinnr()->getwininfo()
4232
4233getwinpos([{timeout}]) *getwinpos()*
4234 The result is a |List| with two numbers, the result of
4235 |getwinposx()| and |getwinposy()| combined:
4236 [x-pos, y-pos]
4237 {timeout} can be used to specify how long to wait in msec for
4238 a response from the terminal. When omitted 100 msec is used.
4239 Use a longer time for a remote terminal.
4240 When using a value less than 10 and no response is received
4241 within that time, a previously reported position is returned,
4242 if available. This can be used to poll for the position and
4243 do some work in the meantime: >
4244 while 1
4245 let res = getwinpos(1)
4246 if res[0] >= 0
4247 break
4248 endif
4249 " Do some work here
4250 endwhile
4251<
4252
4253 Can also be used as a |method|: >
4254 GetTimeout()->getwinpos()
4255<
4256 *getwinposx()*
4257getwinposx() The result is a Number, which is the X coordinate in pixels of
4258 the left hand side of the GUI Vim window. Also works for an
4259 xterm (uses a timeout of 100 msec).
4260 The result will be -1 if the information is not available.
4261 The value can be used with `:winpos`.
4262
4263 *getwinposy()*
4264getwinposy() The result is a Number, which is the Y coordinate in pixels of
4265 the top of the GUI Vim window. Also works for an xterm (uses
4266 a timeout of 100 msec).
4267 The result will be -1 if the information is not available.
4268 The value can be used with `:winpos`.
4269
4270getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
4271 Like |gettabwinvar()| for the current tabpage.
4272 Examples: >
4273 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004274 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004275
4276< Can also be used as a |method|: >
4277 GetWinnr()->getwinvar(varname)
4278<
4279glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
4280 Expand the file wildcards in {expr}. See |wildcards| for the
4281 use of special characters.
4282
4283 Unless the optional {nosuf} argument is given and is |TRUE|,
4284 the 'suffixes' and 'wildignore' options apply: Names matching
4285 one of the patterns in 'wildignore' will be skipped and
4286 'suffixes' affect the ordering of matches.
4287 'wildignorecase' always applies.
4288
4289 When {list} is present and it is |TRUE| the result is a |List|
4290 with all matching files. The advantage of using a List is,
4291 you also get filenames containing newlines correctly.
4292 Otherwise the result is a String and when there are several
4293 matches, they are separated by <NL> characters.
4294
4295 If the expansion fails, the result is an empty String or List.
4296
4297 You can also use |readdir()| if you need to do complicated
4298 things, such as limiting the number of matches.
4299
4300 A name for a non-existing file is not included. A symbolic
4301 link is only included if it points to an existing file.
4302 However, when the {alllinks} argument is present and it is
4303 |TRUE| then all symbolic links are included.
4304
4305 For most systems backticks can be used to get files names from
4306 any external command. Example: >
4307 :let tagfiles = glob("`find . -name tags -print`")
4308 :let &tags = substitute(tagfiles, "\n", ",", "g")
4309< The result of the program inside the backticks should be one
4310 item per line. Spaces inside an item are allowed.
4311
4312 See |expand()| for expanding special Vim variables. See
4313 |system()| for getting the raw output of an external command.
4314
4315 Can also be used as a |method|: >
4316 GetExpr()->glob()
4317
4318glob2regpat({string}) *glob2regpat()*
4319 Convert a file pattern, as used by glob(), into a search
4320 pattern. The result can be used to match with a string that
4321 is a file name. E.g. >
4322 if filename =~ glob2regpat('Make*.mak')
4323< This is equivalent to: >
4324 if filename =~ '^Make.*\.mak$'
4325< When {string} is an empty string the result is "^$", match an
4326 empty string.
4327 Note that the result depends on the system. On MS-Windows
4328 a backslash usually means a path separator.
4329
4330 Can also be used as a |method|: >
4331 GetExpr()->glob2regpat()
4332< *globpath()*
4333globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
4334 Perform glob() for String {expr} on all directories in {path}
4335 and concatenate the results. Example: >
4336 :echo globpath(&rtp, "syntax/c.vim")
4337<
4338 {path} is a comma-separated list of directory names. Each
4339 directory name is prepended to {expr} and expanded like with
4340 |glob()|. A path separator is inserted when needed.
4341 To add a comma inside a directory name escape it with a
4342 backslash. Note that on MS-Windows a directory may have a
4343 trailing backslash, remove it if you put a comma after it.
4344 If the expansion fails for one of the directories, there is no
4345 error message.
4346
4347 Unless the optional {nosuf} argument is given and is |TRUE|,
4348 the 'suffixes' and 'wildignore' options apply: Names matching
4349 one of the patterns in 'wildignore' will be skipped and
4350 'suffixes' affect the ordering of matches.
4351
4352 When {list} is present and it is |TRUE| the result is a |List|
4353 with all matching files. The advantage of using a List is, you
4354 also get filenames containing newlines correctly. Otherwise
4355 the result is a String and when there are several matches,
4356 they are separated by <NL> characters. Example: >
4357 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4358<
4359 {alllinks} is used as with |glob()|.
4360
4361 The "**" item can be used to search in a directory tree.
4362 For example, to find all "README.txt" files in the directories
4363 in 'runtimepath' and below: >
4364 :echo globpath(&rtp, "**/README.txt")
4365< Upwards search and limiting the depth of "**" is not
4366 supported, thus using 'path' will not always work properly.
4367
4368 Can also be used as a |method|, the base is passed as the
4369 second argument: >
4370 GetExpr()->globpath(&rtp)
4371<
4372 *has()*
4373has({feature} [, {check}])
4374 When {check} is omitted or is zero: The result is a Number,
4375 which is 1 if the feature {feature} is supported, zero
4376 otherwise. The {feature} argument is a string, case is
4377 ignored. See |feature-list| below.
4378
4379 When {check} is present and not zero: The result is a Number,
4380 which is 1 if the feature {feature} could ever be supported,
4381 zero otherwise. This is useful to check for a typo in
4382 {feature} and to detect dead code. Keep in mind that an older
4383 Vim version will not know about a feature added later and
4384 features that have been abandoned will not be known by the
4385 current Vim version.
4386
4387 Also see |exists()| and |exists_compiled()|.
4388
4389 Note that to skip code that has a syntax error when the
4390 feature is not available, Vim may skip the rest of the line
4391 and miss a following `endif`. Therefore put the `endif` on a
4392 separate line: >
4393 if has('feature')
4394 let x = this->breaks->without->the->feature
4395 endif
4396< If the `endif` would be moved to the second line as "| endif" it
4397 would not be found.
4398
4399
4400has_key({dict}, {key}) *has_key()*
4401 The result is a Number, which is TRUE if |Dictionary| {dict}
4402 has an entry with key {key}. FALSE otherwise. The {key}
4403 argument is a string.
4404
4405 Can also be used as a |method|: >
4406 mydict->has_key(key)
4407
4408haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4409 The result is a Number:
4410 1 when the window has set a local directory via |:lcd|
4411 2 when the tab-page has set a local directory via |:tcd|
4412 0 otherwise.
4413
4414 Without arguments use the current window.
4415 With {winnr} use this window in the current tab page.
4416 With {winnr} and {tabnr} use the window in the specified tab
4417 page.
4418 {winnr} can be the window number or the |window-ID|.
4419 If {winnr} is -1 it is ignored and only the tabpage is used.
4420 Return 0 if the arguments are invalid.
4421 Examples: >
4422 if haslocaldir() == 1
4423 " window local directory case
4424 elseif haslocaldir() == 2
4425 " tab-local directory case
4426 else
4427 " global directory case
4428 endif
4429
4430 " current window
4431 :echo haslocaldir()
4432 :echo haslocaldir(0)
4433 :echo haslocaldir(0, 0)
4434 " window n in current tab page
4435 :echo haslocaldir(n)
4436 :echo haslocaldir(n, 0)
4437 " window n in tab page m
4438 :echo haslocaldir(n, m)
4439 " tab page m
4440 :echo haslocaldir(-1, m)
4441<
4442 Can also be used as a |method|: >
4443 GetWinnr()->haslocaldir()
4444
4445hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
4446 The result is a Number, which is TRUE if there is a mapping
4447 that contains {what} in somewhere in the rhs (what it is
4448 mapped to) and this mapping exists in one of the modes
4449 indicated by {mode}.
4450 The arguments {what} and {mode} are strings.
4451 When {abbr} is there and it is |TRUE| use abbreviations
4452 instead of mappings. Don't forget to specify Insert and/or
4453 Command-line mode.
4454 Both the global mappings and the mappings local to the current
4455 buffer are checked for a match.
4456 If no matching mapping is found FALSE is returned.
4457 The following characters are recognized in {mode}:
4458 n Normal mode
4459 v Visual and Select mode
4460 x Visual mode
4461 s Select mode
4462 o Operator-pending mode
4463 i Insert mode
4464 l Language-Argument ("r", "f", "t", etc.)
4465 c Command-line mode
4466 When {mode} is omitted, "nvo" is used.
4467
4468 This function is useful to check if a mapping already exists
4469 to a function in a Vim script. Example: >
4470 :if !hasmapto('\ABCdoit')
4471 : map <Leader>d \ABCdoit
4472 :endif
4473< This installs the mapping to "\ABCdoit" only if there isn't
4474 already a mapping to "\ABCdoit".
4475
4476 Can also be used as a |method|: >
4477 GetRHS()->hasmapto()
4478
4479histadd({history}, {item}) *histadd()*
4480 Add the String {item} to the history {history} which can be
4481 one of: *hist-names*
4482 "cmd" or ":" command line history
4483 "search" or "/" search pattern history
4484 "expr" or "=" typed expression history
4485 "input" or "@" input line history
4486 "debug" or ">" debug command history
4487 empty the current or last used history
4488 The {history} string does not need to be the whole name, one
4489 character is sufficient.
4490 If {item} does already exist in the history, it will be
4491 shifted to become the newest entry.
4492 The result is a Number: TRUE if the operation was successful,
4493 otherwise FALSE is returned.
4494
4495 Example: >
4496 :call histadd("input", strftime("%Y %b %d"))
4497 :let date=input("Enter date: ")
4498< This function is not available in the |sandbox|.
4499
4500 Can also be used as a |method|, the base is passed as the
4501 second argument: >
4502 GetHistory()->histadd('search')
4503
4504histdel({history} [, {item}]) *histdel()*
4505 Clear {history}, i.e. delete all its entries. See |hist-names|
4506 for the possible values of {history}.
4507
4508 If the parameter {item} evaluates to a String, it is used as a
4509 regular expression. All entries matching that expression will
4510 be removed from the history (if there are any).
4511 Upper/lowercase must match, unless "\c" is used |/\c|.
4512 If {item} evaluates to a Number, it will be interpreted as
4513 an index, see |:history-indexing|. The respective entry will
4514 be removed if it exists.
4515
4516 The result is TRUE for a successful operation, otherwise FALSE
4517 is returned.
4518
4519 Examples:
4520 Clear expression register history: >
4521 :call histdel("expr")
4522<
4523 Remove all entries starting with "*" from the search history: >
4524 :call histdel("/", '^\*')
4525<
4526 The following three are equivalent: >
4527 :call histdel("search", histnr("search"))
4528 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004529 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004530<
4531 To delete the last search pattern and use the last-but-one for
4532 the "n" command and 'hlsearch': >
4533 :call histdel("search", -1)
4534 :let @/ = histget("search", -1)
4535<
4536 Can also be used as a |method|: >
4537 GetHistory()->histdel()
4538
4539histget({history} [, {index}]) *histget()*
4540 The result is a String, the entry with Number {index} from
4541 {history}. See |hist-names| for the possible values of
4542 {history}, and |:history-indexing| for {index}. If there is
4543 no such entry, an empty String is returned. When {index} is
4544 omitted, the most recent item from the history is used.
4545
4546 Examples:
4547 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004548 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004549
4550< Define an Ex command ":H {num}" that supports re-execution of
4551 the {num}th entry from the output of |:history|. >
4552 :command -nargs=1 H execute histget("cmd", 0+<args>)
4553<
4554 Can also be used as a |method|: >
4555 GetHistory()->histget()
4556
4557histnr({history}) *histnr()*
4558 The result is the Number of the current entry in {history}.
4559 See |hist-names| for the possible values of {history}.
4560 If an error occurred, -1 is returned.
4561
4562 Example: >
4563 :let inp_index = histnr("expr")
4564
4565< Can also be used as a |method|: >
4566 GetHistory()->histnr()
4567<
4568hlexists({name}) *hlexists()*
4569 The result is a Number, which is TRUE if a highlight group
4570 called {name} exists. This is when the group has been
4571 defined in some way. Not necessarily when highlighting has
4572 been defined for it, it may also have been used for a syntax
4573 item.
4574 *highlight_exists()*
4575 Obsolete name: highlight_exists().
4576
4577 Can also be used as a |method|: >
4578 GetName()->hlexists()
4579<
4580hlget([{name} [, {resolve}]]) *hlget()*
4581 Returns a List of all the highlight group attributes. If the
4582 optional {name} is specified, then returns a List with only
4583 the attributes of the specified highlight group. Returns an
4584 empty List if the highlight group {name} is not present.
4585
4586 If the optional {resolve} argument is set to v:true and the
4587 highlight group {name} is linked to another group, then the
4588 link is resolved recursively and the attributes of the
4589 resolved highlight group are returned.
4590
4591 Each entry in the returned List is a Dictionary with the
4592 following items:
4593 cleared boolean flag, set to v:true if the highlight
4594 group attributes are cleared or not yet
4595 specified. See |highlight-clear|.
4596 cterm cterm attributes. See |highlight-cterm|.
4597 ctermbg cterm background color.
4598 See |highlight-ctermbg|.
4599 ctermfg cterm foreground color.
4600 See |highlight-ctermfg|.
4601 ctermul cterm underline color. See |highlight-ctermul|.
4602 default boolean flag, set to v:true if the highlight
4603 group link is a default link. See
4604 |highlight-default|.
4605 font highlight group font. See |highlight-font|.
4606 gui gui attributes. See |highlight-gui|.
4607 guibg gui background color. See |highlight-guibg|.
4608 guifg gui foreground color. See |highlight-guifg|.
4609 guisp gui special color. See |highlight-guisp|.
4610 id highlight group ID.
4611 linksto linked highlight group name.
4612 See |:highlight-link|.
4613 name highlight group name. See |group-name|.
4614 start start terminal keycode. See |highlight-start|.
4615 stop stop terminal keycode. See |highlight-stop|.
4616 term term attributes. See |highlight-term|.
4617
4618 The 'term', 'cterm' and 'gui' items in the above Dictionary
4619 have a dictionary value with the following optional boolean
4620 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
4621 'reverse', 'inverse' and 'strikethrough'.
4622
4623 Example(s): >
4624 :echo hlget()
4625 :echo hlget('ModeMsg')
4626 :echo hlget('Number', v:true)
4627<
4628 Can also be used as a |method|: >
4629 GetName()->hlget()
4630<
4631hlset({list}) *hlset()*
4632 Creates or modifies the attributes of a List of highlight
4633 groups. Each item in {list} is a dictionary containing the
4634 attributes of a highlight group. See |hlget()| for the list of
4635 supported items in this dictionary.
4636
4637 In addition to the items described in |hlget()|, the following
4638 additional items are supported in the dictionary:
4639
4640 force boolean flag to force the creation of
4641 a link for an existing highlight group
4642 with attributes.
4643
4644 The highlight group is identified using the 'name' item and
4645 the 'id' item (if supplied) is ignored. If a highlight group
4646 with a specified name doesn't exist, then it is created.
4647 Otherwise the attributes of an existing highlight group are
4648 modified.
4649
4650 If an empty dictionary value is used for the 'term' or 'cterm'
4651 or 'gui' entries, then the corresponding attributes are
4652 cleared. If the 'cleared' item is set to v:true, then all the
4653 attributes of the highlight group are cleared.
4654
4655 The 'linksto' item can be used to link a highlight group to
4656 another highlight group. See |:highlight-link|.
4657
4658 Returns zero for success, -1 for failure.
4659
4660 Example(s): >
4661 " add bold attribute to the Visual highlight group
4662 :call hlset([#{name: 'Visual',
4663 \ term: #{reverse: 1 , bold: 1}}])
4664 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
4665 :let l = hlget()
4666 :call hlset(l)
4667 " clear the Search highlight group
4668 :call hlset([#{name: 'Search', cleared: v:true}])
4669 " clear the 'term' attributes for a highlight group
4670 :call hlset([#{name: 'Title', term: {}}])
4671 " create the MyHlg group linking it to DiffAdd
4672 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
4673 " remove the MyHlg group link
4674 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
4675 " clear the attributes and a link
4676 :call hlset([#{name: 'MyHlg', cleared: v:true,
4677 \ linksto: 'NONE'}])
4678<
4679 Can also be used as a |method|: >
4680 GetAttrList()->hlset()
4681<
4682 *hlID()*
4683hlID({name}) The result is a Number, which is the ID of the highlight group
4684 with name {name}. When the highlight group doesn't exist,
4685 zero is returned.
4686 This can be used to retrieve information about the highlight
4687 group. For example, to get the background color of the
4688 "Comment" group: >
4689 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4690< *highlightID()*
4691 Obsolete name: highlightID().
4692
4693 Can also be used as a |method|: >
4694 GetName()->hlID()
4695
4696hostname() *hostname()*
4697 The result is a String, which is the name of the machine on
4698 which Vim is currently running. Machine names greater than
4699 256 characters long are truncated.
4700
4701iconv({string}, {from}, {to}) *iconv()*
4702 The result is a String, which is the text {string} converted
4703 from encoding {from} to encoding {to}.
4704 When the conversion completely fails an empty string is
4705 returned. When some characters could not be converted they
4706 are replaced with "?".
4707 The encoding names are whatever the iconv() library function
4708 can accept, see ":!man 3 iconv".
4709 Most conversions require Vim to be compiled with the |+iconv|
4710 feature. Otherwise only UTF-8 to latin1 conversion and back
4711 can be done.
4712 This can be used to display messages with special characters,
4713 no matter what 'encoding' is set to. Write the message in
4714 UTF-8 and use: >
4715 echo iconv(utf8_str, "utf-8", &enc)
4716< Note that Vim uses UTF-8 for all Unicode encodings, conversion
4717 from/to UCS-2 is automatically changed to use UTF-8. You
4718 cannot use UCS-2 in a string anyway, because of the NUL bytes.
4719
4720 Can also be used as a |method|: >
4721 GetText()->iconv('latin1', 'utf-8')
4722<
4723 *indent()*
4724indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4725 current buffer. The indent is counted in spaces, the value
4726 of 'tabstop' is relevant. {lnum} is used just like in
4727 |getline()|.
4728 When {lnum} is invalid -1 is returned. In |Vim9| script an
4729 error is given.
4730
4731 Can also be used as a |method|: >
4732 GetLnum()->indent()
4733
4734index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004735 Find {expr} in {object} and return its index. See
4736 |filterof()| for using a lambda to select the item.
4737
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004738 If {object} is a |List| return the lowest index where the item
4739 has a value equal to {expr}. There is no automatic
4740 conversion, so the String "4" is different from the Number 4.
4741 And the number 4 is different from the Float 4.0. The value
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004742 of 'ignorecase' is not used here, case matters as indicated by
4743 the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004744
4745 If {object} is |Blob| return the lowest index where the byte
4746 value is equal to {expr}.
4747
4748 If {start} is given then start looking at the item with index
4749 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004750
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004751 When {ic} is given and it is |TRUE|, ignore case. Otherwise
4752 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004753
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004754 -1 is returned when {expr} is not found in {object}.
4755 Example: >
4756 :let idx = index(words, "the")
4757 :if index(numbers, 123) >= 0
4758
4759< Can also be used as a |method|: >
4760 GetObject()->index(what)
4761
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004762indexof({object}, {expr} [, {opt}]) *indexof()*
4763 {object} must be a |List| or a |Blob|.
4764 If {object} is a |List|, evaluate {expr} for each item in the
4765 List until the expression returns v:true and return the index
4766 of this item.
4767
4768 If {object} is a |Blob| evaluate {expr} for each byte in the
4769 Blob until the expression returns v:true and return the index
4770 of this byte.
4771
4772 {expr} must be a |string| or |Funcref|.
4773
4774 If {expr} is a |string|: If {object} is a |List|, inside
4775 {expr} |v:key| has the index of the current List item and
4776 |v:val| has the value of the item. If {object} is a |Blob|,
4777 inside {expr} |v:key| has the index of the current byte and
4778 |v:val| has the byte value.
4779
4780 If {expr} is a |Funcref| it must take two arguments:
4781 1. the key or the index of the current item.
4782 2. the value of the current item.
4783 The function must return |TRUE| if the item is found and the
4784 search should stop.
4785
4786 The optional argument {opt} is a Dict and supports the
4787 following items:
4788 start start evaluating {expr} at the item with index
4789 {start} (may be negative for an item relative
4790 to the end).
4791 Returns -1 when {expr} evaluates to v:false for all the items.
4792 Example: >
4793 :let l = [#{n: 10}, #{n: 20}, #{n: 30]]
4794 :let idx = indexof(l, "v:val.n == 20")
4795 :let idx = indexof(l, {i, v -> v.n == 30})
4796
4797< Can also be used as a |method|: >
4798 mylist->indexof(expr)
4799
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004800input({prompt} [, {text} [, {completion}]]) *input()*
4801 The result is a String, which is whatever the user typed on
4802 the command-line. The {prompt} argument is either a prompt
4803 string, or a blank string (for no prompt). A '\n' can be used
4804 in the prompt to start a new line.
4805 The highlighting set with |:echohl| is used for the prompt.
4806 The input is entered just like a command-line, with the same
4807 editing commands and mappings. There is a separate history
4808 for lines typed for input().
4809 Example: >
4810 :if input("Coffee or beer? ") == "beer"
4811 : echo "Cheers!"
4812 :endif
4813<
4814 If the optional {text} argument is present and not empty, this
4815 is used for the default reply, as if the user typed this.
4816 Example: >
4817 :let color = input("Color? ", "white")
4818
4819< The optional {completion} argument specifies the type of
4820 completion supported for the input. Without it completion is
4821 not performed. The supported completion types are the same as
4822 that can be supplied to a user-defined command using the
4823 "-complete=" argument. Refer to |:command-completion| for
4824 more information. Example: >
4825 let fname = input("File: ", "", "file")
4826<
4827 NOTE: This function must not be used in a startup file, for
4828 the versions that only run in GUI mode (e.g., the Win32 GUI).
4829 Note: When input() is called from within a mapping it will
4830 consume remaining characters from that mapping, because a
4831 mapping is handled like the characters were typed.
4832 Use |inputsave()| before input() and |inputrestore()|
4833 after input() to avoid that. Another solution is to avoid
4834 that further characters follow in the mapping, e.g., by using
4835 |:execute| or |:normal|.
4836
4837 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004838 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004839 :function GetFoo()
4840 : call inputsave()
4841 : let g:Foo = input("enter search pattern: ")
4842 : call inputrestore()
4843 :endfunction
4844
4845< Can also be used as a |method|: >
4846 GetPrompt()->input()
4847
4848inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
4849 Like |input()|, but when the GUI is running and text dialogs
4850 are supported, a dialog window pops up to input the text.
4851 Example: >
4852 :let n = inputdialog("value for shiftwidth", shiftwidth())
4853 :if n != ""
4854 : let &sw = n
4855 :endif
4856< When the dialog is cancelled {cancelreturn} is returned. When
4857 omitted an empty string is returned.
4858 Hitting <Enter> works like pressing the OK button. Hitting
4859 <Esc> works like pressing the Cancel button.
4860 NOTE: Command-line completion is not supported.
4861
4862 Can also be used as a |method|: >
4863 GetPrompt()->inputdialog()
4864
4865inputlist({textlist}) *inputlist()*
4866 {textlist} must be a |List| of strings. This |List| is
4867 displayed, one string per line. The user will be prompted to
4868 enter a number, which is returned.
4869 The user can also select an item by clicking on it with the
4870 mouse, if the mouse is enabled in the command line ('mouse' is
4871 "a" or includes "c"). For the first string 0 is returned.
4872 When clicking above the first item a negative number is
4873 returned. When clicking on the prompt one more than the
4874 length of {textlist} is returned.
4875 Make sure {textlist} has less than 'lines' entries, otherwise
4876 it won't work. It's a good idea to put the entry number at
4877 the start of the string. And put a prompt in the first item.
4878 Example: >
4879 let color = inputlist(['Select color:', '1. red',
4880 \ '2. green', '3. blue'])
4881
4882< Can also be used as a |method|: >
4883 GetChoices()->inputlist()
4884
4885inputrestore() *inputrestore()*
4886 Restore typeahead that was saved with a previous |inputsave()|.
4887 Should be called the same number of times inputsave() is
4888 called. Calling it more often is harmless though.
4889 Returns TRUE when there is nothing to restore, FALSE otherwise.
4890
4891inputsave() *inputsave()*
4892 Preserve typeahead (also from mappings) and clear it, so that
4893 a following prompt gets input from the user. Should be
4894 followed by a matching inputrestore() after the prompt. Can
4895 be used several times, in which case there must be just as
4896 many inputrestore() calls.
4897 Returns TRUE when out of memory, FALSE otherwise.
4898
4899inputsecret({prompt} [, {text}]) *inputsecret()*
4900 This function acts much like the |input()| function with but
4901 two exceptions:
4902 a) the user's response will be displayed as a sequence of
4903 asterisks ("*") thereby keeping the entry secret, and
4904 b) the user's response will not be recorded on the input
4905 |history| stack.
4906 The result is a String, which is whatever the user actually
4907 typed on the command-line in response to the issued prompt.
4908 NOTE: Command-line completion is not supported.
4909
4910 Can also be used as a |method|: >
4911 GetPrompt()->inputsecret()
4912
4913insert({object}, {item} [, {idx}]) *insert()*
4914 When {object} is a |List| or a |Blob| insert {item} at the start
4915 of it.
4916
4917 If {idx} is specified insert {item} before the item with index
4918 {idx}. If {idx} is zero it goes before the first item, just
4919 like omitting {idx}. A negative {idx} is also possible, see
4920 |list-index|. -1 inserts just before the last item.
4921
4922 Returns the resulting |List| or |Blob|. Examples: >
4923 :let mylist = insert([2, 3, 5], 1)
4924 :call insert(mylist, 4, -1)
4925 :call insert(mylist, 6, len(mylist))
4926< The last example can be done simpler with |add()|.
4927 Note that when {item} is a |List| it is inserted as a single
4928 item. Use |extend()| to concatenate |Lists|.
4929
4930 Can also be used as a |method|: >
4931 mylist->insert(item)
4932
4933interrupt() *interrupt()*
4934 Interrupt script execution. It works more or less like the
4935 user typing CTRL-C, most commands won't execute and control
4936 returns to the user. This is useful to abort execution
4937 from lower down, e.g. in an autocommand. Example: >
4938 :function s:check_typoname(file)
4939 : if fnamemodify(a:file, ':t') == '['
4940 : echomsg 'Maybe typo'
4941 : call interrupt()
4942 : endif
4943 :endfunction
4944 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
4945
4946invert({expr}) *invert()*
4947 Bitwise invert. The argument is converted to a number. A
4948 List, Dict or Float argument causes an error. Example: >
4949 :let bits = invert(bits)
4950< Can also be used as a |method|: >
4951 :let bits = bits->invert()
4952
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01004953isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01004954 The result is a Number, which is |TRUE| when {path} is an
4955 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01004956 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01004957 On MS-Windows, it is considered absolute when it starts with an
4958 optional drive prefix and is followed by a '\' or '/'. UNC paths
4959 are always absolute.
4960 Example: >
4961 echo isabsolutepath('/usr/share/') " 1
4962 echo isabsolutepath('./foobar') " 0
4963 echo isabsolutepath('C:\Windows') " 1
4964 echo isabsolutepath('foobar') " 0
4965 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01004966<
LemonBoydca1d402022-04-28 15:26:33 +01004967 Can also be used as a |method|: >
4968 GetName()->isabsolutepath()
4969
4970
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004971isdirectory({directory}) *isdirectory()*
4972 The result is a Number, which is |TRUE| when a directory
4973 with the name {directory} exists. If {directory} doesn't
4974 exist, or isn't a directory, the result is |FALSE|. {directory}
4975 is any expression, which is used as a String.
4976
4977 Can also be used as a |method|: >
4978 GetName()->isdirectory()
4979
4980isinf({expr}) *isinf()*
4981 Return 1 if {expr} is a positive infinity, or -1 a negative
4982 infinity, otherwise 0. >
4983 :echo isinf(1.0 / 0.0)
4984< 1 >
4985 :echo isinf(-1.0 / 0.0)
4986< -1
4987
4988 Can also be used as a |method|: >
4989 Compute()->isinf()
4990<
4991 {only available when compiled with the |+float| feature}
4992
4993islocked({expr}) *islocked()* *E786*
4994 The result is a Number, which is |TRUE| when {expr} is the
4995 name of a locked variable.
4996 The string argument {expr} must be the name of a variable,
4997 |List| item or |Dictionary| entry, not the variable itself!
4998 Example: >
4999 :let alist = [0, ['a', 'b'], 2, 3]
5000 :lockvar 1 alist
5001 :echo islocked('alist') " 1
5002 :echo islocked('alist[1]') " 0
5003
Bram Moolenaar9da17d72022-02-09 21:50:44 +00005004< When {expr} is a variable that does not exist -1 is returned.
5005 If {expr} uses a range, list or dict index that is out of
5006 range or does not exist you get an error message. Use
5007 |exists()| to check for existence.
5008 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005009
5010 Can also be used as a |method|: >
5011 GetName()->islocked()
5012
5013isnan({expr}) *isnan()*
5014 Return |TRUE| if {expr} is a float with value NaN. >
5015 echo isnan(0.0 / 0.0)
5016< 1
5017
5018 Can also be used as a |method|: >
5019 Compute()->isnan()
5020<
5021 {only available when compiled with the |+float| feature}
5022
5023items({dict}) *items()*
5024 Return a |List| with all the key-value pairs of {dict}. Each
5025 |List| item is a list with two items: the key of a {dict}
5026 entry and the value of this entry. The |List| is in arbitrary
5027 order. Also see |keys()| and |values()|.
5028 Example: >
5029 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005030 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005031 endfor
5032
5033< Can also be used as a |method|: >
5034 mydict->items()
5035
5036job_ functions are documented here: |job-functions-details|
5037
5038
5039join({list} [, {sep}]) *join()*
5040 Join the items in {list} together into one String.
5041 When {sep} is specified it is put in between the items. If
5042 {sep} is omitted a single space is used.
5043 Note that {sep} is not added at the end. You might want to
5044 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005045 let lines = join(mylist, "\n") .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005046< String items are used as-is. |Lists| and |Dictionaries| are
5047 converted into a string like with |string()|.
5048 The opposite function is |split()|.
5049
5050 Can also be used as a |method|: >
5051 mylist->join()
5052
5053js_decode({string}) *js_decode()*
5054 This is similar to |json_decode()| with these differences:
5055 - Object key names do not have to be in quotes.
5056 - Strings can be in single quotes.
5057 - Empty items in an array (between two commas) are allowed and
5058 result in v:none items.
5059
5060 Can also be used as a |method|: >
5061 ReadObject()->js_decode()
5062
5063js_encode({expr}) *js_encode()*
5064 This is similar to |json_encode()| with these differences:
5065 - Object key names are not in quotes.
5066 - v:none items in an array result in an empty item between
5067 commas.
5068 For example, the Vim object:
5069 [1,v:none,{"one":1},v:none] ~
5070 Will be encoded as:
5071 [1,,{one:1},,] ~
5072 While json_encode() would produce:
5073 [1,null,{"one":1},null] ~
5074 This encoding is valid for JavaScript. It is more efficient
5075 than JSON, especially when using an array with optional items.
5076
5077 Can also be used as a |method|: >
5078 GetObject()->js_encode()
5079
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005080json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005081 This parses a JSON formatted string and returns the equivalent
5082 in Vim values. See |json_encode()| for the relation between
5083 JSON and Vim values.
5084 The decoding is permissive:
5085 - A trailing comma in an array and object is ignored, e.g.
5086 "[1, 2, ]" is the same as "[1, 2]".
5087 - Integer keys are accepted in objects, e.g. {1:2} is the
5088 same as {"1":2}.
5089 - More floating point numbers are recognized, e.g. "1." for
5090 "1.0", or "001.2" for "1.2". Special floating point values
5091 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
5092 are accepted.
5093 - Leading zeroes in integer numbers are ignored, e.g. "012"
5094 for "12" or "-012" for "-12".
5095 - Capitalization is ignored in literal names null, true or
5096 false, e.g. "NULL" for "null", "True" for "true".
5097 - Control characters U+0000 through U+001F which are not
5098 escaped in strings are accepted, e.g. " " (tab
5099 character in string) for "\t".
5100 - An empty JSON expression or made of only spaces is accepted
5101 and results in v:none.
5102 - Backslash in an invalid 2-character sequence escape is
5103 ignored, e.g. "\a" is decoded as "a".
5104 - A correct surrogate pair in JSON strings should normally be
5105 a 12 character sequence such as "\uD834\uDD1E", but
5106 json_decode() silently accepts truncated surrogate pairs
5107 such as "\uD834" or "\uD834\u"
5108 *E938*
5109 A duplicate key in an object, valid in rfc7159, is not
5110 accepted by json_decode() as the result must be a valid Vim
5111 type, e.g. this fails: {"a":"b", "a":"c"}
5112
5113 Can also be used as a |method|: >
5114 ReadObject()->json_decode()
5115
5116json_encode({expr}) *json_encode()*
5117 Encode {expr} as JSON and return this as a string.
5118 The encoding is specified in:
5119 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00005120 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005121 |Number| decimal number
5122 |Float| floating point number
5123 Float nan "NaN"
5124 Float inf "Infinity"
5125 Float -inf "-Infinity"
5126 |String| in double quotes (possibly null)
5127 |Funcref| not possible, error
5128 |List| as an array (possibly null); when
5129 used recursively: []
5130 |Dict| as an object (possibly null); when
5131 used recursively: {}
5132 |Blob| as an array of the individual bytes
5133 v:false "false"
5134 v:true "true"
5135 v:none "null"
5136 v:null "null"
5137 Note that NaN and Infinity are passed on as values. This is
5138 missing in the JSON standard, but several implementations do
5139 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01005140 If a string contains an illegal character then the replacement
5141 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005142
5143 Can also be used as a |method|: >
5144 GetObject()->json_encode()
5145
5146keys({dict}) *keys()*
5147 Return a |List| with all the keys of {dict}. The |List| is in
5148 arbitrary order. Also see |items()| and |values()|.
5149
5150 Can also be used as a |method|: >
5151 mydict->keys()
5152
5153< *len()* *E701*
5154len({expr}) The result is a Number, which is the length of the argument.
5155 When {expr} is a String or a Number the length in bytes is
5156 used, as with |strlen()|.
5157 When {expr} is a |List| the number of items in the |List| is
5158 returned.
5159 When {expr} is a |Blob| the number of bytes is returned.
5160 When {expr} is a |Dictionary| the number of entries in the
5161 |Dictionary| is returned.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005162 Otherwise an error is given and returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005163
5164 Can also be used as a |method|: >
5165 mylist->len()
5166
5167< *libcall()* *E364* *E368*
5168libcall({libname}, {funcname}, {argument})
5169 Call function {funcname} in the run-time library {libname}
5170 with single argument {argument}.
5171 This is useful to call functions in a library that you
5172 especially made to be used with Vim. Since only one argument
5173 is possible, calling standard library functions is rather
5174 limited.
5175 The result is the String returned by the function. If the
5176 function returns NULL, this will appear as an empty string ""
5177 to Vim.
5178 If the function returns a number, use libcallnr()!
5179 If {argument} is a number, it is passed to the function as an
5180 int; if {argument} is a string, it is passed as a
5181 null-terminated string.
5182 This function will fail in |restricted-mode|.
5183
5184 libcall() allows you to write your own 'plug-in' extensions to
5185 Vim without having to recompile the program. It is NOT a
5186 means to call system functions! If you try to do so Vim will
5187 very probably crash.
5188
5189 For Win32, the functions you write must be placed in a DLL
5190 and use the normal C calling convention (NOT Pascal which is
5191 used in Windows System DLLs). The function must take exactly
5192 one parameter, either a character pointer or a long integer,
5193 and must return a character pointer or NULL. The character
5194 pointer returned must point to memory that will remain valid
5195 after the function has returned (e.g. in static data in the
5196 DLL). If it points to allocated memory, that memory will
5197 leak away. Using a static buffer in the function should work,
5198 it's then freed when the DLL is unloaded.
5199
5200 WARNING: If the function returns a non-valid pointer, Vim may
5201 crash! This also happens if the function returns a number,
5202 because Vim thinks it's a pointer.
5203 For Win32 systems, {libname} should be the filename of the DLL
5204 without the ".DLL" suffix. A full path is only required if
5205 the DLL is not in the usual places.
5206 For Unix: When compiling your own plugins, remember that the
5207 object code must be compiled as position-independent ('PIC').
5208 {only in Win32 and some Unix versions, when the |+libcall|
5209 feature is present}
5210 Examples: >
5211 :echo libcall("libc.so", "getenv", "HOME")
5212
5213< Can also be used as a |method|, the base is passed as the
5214 third argument: >
5215 GetValue()->libcall("libc.so", "getenv")
5216<
5217 *libcallnr()*
5218libcallnr({libname}, {funcname}, {argument})
5219 Just like |libcall()|, but used for a function that returns an
5220 int instead of a string.
5221 {only in Win32 on some Unix versions, when the |+libcall|
5222 feature is present}
5223 Examples: >
5224 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
5225 :call libcallnr("libc.so", "printf", "Hello World!\n")
5226 :call libcallnr("libc.so", "sleep", 10)
5227<
5228 Can also be used as a |method|, the base is passed as the
5229 third argument: >
5230 GetValue()->libcallnr("libc.so", "printf")
5231<
5232
5233line({expr} [, {winid}]) *line()*
5234 The result is a Number, which is the line number of the file
5235 position given with {expr}. The {expr} argument is a string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00005236 The accepted positions are: *E1209*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005237 . the cursor position
5238 $ the last line in the current buffer
5239 'x position of mark x (if the mark is not set, 0 is
5240 returned)
5241 w0 first line visible in current window (one if the
5242 display isn't updated, e.g. in silent Ex mode)
5243 w$ last line visible in current window (this is one
5244 less than "w0" if no lines are visible)
5245 v In Visual mode: the start of the Visual area (the
5246 cursor is the end). When not in Visual mode
5247 returns the cursor position. Differs from |'<| in
5248 that it's updated right away.
5249 Note that a mark in another file can be used. The line number
5250 then applies to another buffer.
5251 To get the column number use |col()|. To get both use
5252 |getpos()|.
5253 With the optional {winid} argument the values are obtained for
5254 that window instead of the current window.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005255 Returns 0 for invalid values of {expr} and {winid}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005256 Examples: >
5257 line(".") line number of the cursor
5258 line(".", winid) idem, in window "winid"
5259 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005260 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005261<
5262 To jump to the last known position when opening a file see
5263 |last-position-jump|.
5264
5265 Can also be used as a |method|: >
5266 GetValue()->line()
5267
5268line2byte({lnum}) *line2byte()*
5269 Return the byte count from the start of the buffer for line
5270 {lnum}. This includes the end-of-line character, depending on
5271 the 'fileformat' option for the current buffer. The first
5272 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
5273 This can also be used to get the byte count for the line just
5274 below the last line: >
5275 line2byte(line("$") + 1)
5276< This is the buffer size plus one. If 'fileencoding' is empty
5277 it is the file size plus one. {lnum} is used like with
5278 |getline()|. When {lnum} is invalid, or the |+byte_offset|
5279 feature has been disabled at compile time, -1 is returned.
5280 Also see |byte2line()|, |go| and |:goto|.
5281
5282 Can also be used as a |method|: >
5283 GetLnum()->line2byte()
5284
5285lispindent({lnum}) *lispindent()*
5286 Get the amount of indent for line {lnum} according the lisp
5287 indenting rules, as with 'lisp'.
5288 The indent is counted in spaces, the value of 'tabstop' is
5289 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01005290 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005291 error is given.
5292
5293 Can also be used as a |method|: >
5294 GetLnum()->lispindent()
5295
5296list2blob({list}) *list2blob()*
5297 Return a Blob concatenating all the number values in {list}.
5298 Examples: >
5299 list2blob([1, 2, 3, 4]) returns 0z01020304
5300 list2blob([]) returns 0z
5301< Returns an empty Blob on error. If one of the numbers is
5302 negative or more than 255 error *E1239* is given.
5303
5304 |blob2list()| does the opposite.
5305
5306 Can also be used as a |method|: >
5307 GetList()->list2blob()
5308
5309list2str({list} [, {utf8}]) *list2str()*
5310 Convert each number in {list} to a character string can
5311 concatenate them all. Examples: >
5312 list2str([32]) returns " "
5313 list2str([65, 66, 67]) returns "ABC"
5314< The same can be done (slowly) with: >
5315 join(map(list, {nr, val -> nr2char(val)}), '')
5316< |str2list()| does the opposite.
5317
5318 When {utf8} is omitted or zero, the current 'encoding' is used.
5319 When {utf8} is TRUE, always return UTF-8 characters.
5320 With UTF-8 composing characters work as expected: >
5321 list2str([97, 769]) returns "á"
5322<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005323 Returns an empty string on error.
5324
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005325 Can also be used as a |method|: >
5326 GetList()->list2str()
5327
5328listener_add({callback} [, {buf}]) *listener_add()*
5329 Add a callback function that will be invoked when changes have
5330 been made to buffer {buf}.
5331 {buf} refers to a buffer name or number. For the accepted
5332 values, see |bufname()|. When {buf} is omitted the current
5333 buffer is used.
5334 Returns a unique ID that can be passed to |listener_remove()|.
5335
5336 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00005337 bufnr the buffer that was changed
5338 start first changed line number
5339 end first line number below the change
5340 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005341 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00005342 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005343
5344 Example: >
5345 func Listener(bufnr, start, end, added, changes)
5346 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
5347 endfunc
5348 call listener_add('Listener', bufnr)
5349
Bram Moolenaar944697a2022-02-20 19:48:20 +00005350< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005351 dictionary with these entries:
5352 lnum the first line number of the change
5353 end the first line below the change
5354 added number of lines added; negative if lines were
5355 deleted
5356 col first column in "lnum" that was affected by
5357 the change; one if unknown or the whole line
5358 was affected; this is a byte index, first
5359 character has a value of one.
5360 When lines are inserted the values are:
5361 lnum line above which the new line is added
5362 end equal to "lnum"
5363 added number of lines inserted
5364 col 1
5365 When lines are deleted the values are:
5366 lnum the first deleted line
5367 end the line below the first deleted line, before
5368 the deletion was done
5369 added negative, number of lines deleted
5370 col 1
5371 When lines are changed:
5372 lnum the first changed line
5373 end the line below the last changed line
5374 added 0
5375 col first column with a change or 1
5376
5377 The entries are in the order the changes were made, thus the
5378 most recent change is at the end. The line numbers are valid
5379 when the callback is invoked, but later changes may make them
5380 invalid, thus keeping a copy for later might not work.
5381
5382 The {callback} is invoked just before the screen is updated,
5383 when |listener_flush()| is called or when a change is being
5384 made that changes the line count in a way it causes a line
5385 number in the list of changes to become invalid.
5386
5387 The {callback} is invoked with the text locked, see
5388 |textlock|. If you do need to make changes to the buffer, use
5389 a timer to do this later |timer_start()|.
5390
5391 The {callback} is not invoked when the buffer is first loaded.
5392 Use the |BufReadPost| autocmd event to handle the initial text
5393 of a buffer.
5394 The {callback} is also not invoked when the buffer is
5395 unloaded, use the |BufUnload| autocmd event for that.
5396
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005397 Returns zero if {callback} or {buf} is invalid.
5398
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005399 Can also be used as a |method|, the base is passed as the
5400 second argument: >
5401 GetBuffer()->listener_add(callback)
5402
5403listener_flush([{buf}]) *listener_flush()*
5404 Invoke listener callbacks for buffer {buf}. If there are no
5405 pending changes then no callbacks are invoked.
5406
5407 {buf} refers to a buffer name or number. For the accepted
5408 values, see |bufname()|. When {buf} is omitted the current
5409 buffer is used.
5410
5411 Can also be used as a |method|: >
5412 GetBuffer()->listener_flush()
5413
5414listener_remove({id}) *listener_remove()*
5415 Remove a listener previously added with listener_add().
5416 Returns FALSE when {id} could not be found, TRUE when {id} was
5417 removed.
5418
5419 Can also be used as a |method|: >
5420 GetListenerId()->listener_remove()
5421
5422localtime() *localtime()*
5423 Return the current time, measured as seconds since 1st Jan
5424 1970. See also |strftime()|, |strptime()| and |getftime()|.
5425
5426
5427log({expr}) *log()*
5428 Return the natural logarithm (base e) of {expr} as a |Float|.
5429 {expr} must evaluate to a |Float| or a |Number| in the range
5430 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005431 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005432 Examples: >
5433 :echo log(10)
5434< 2.302585 >
5435 :echo log(exp(5))
5436< 5.0
5437
5438 Can also be used as a |method|: >
5439 Compute()->log()
5440<
5441 {only available when compiled with the |+float| feature}
5442
5443
5444log10({expr}) *log10()*
5445 Return the logarithm of Float {expr} to base 10 as a |Float|.
5446 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005447 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005448 Examples: >
5449 :echo log10(1000)
5450< 3.0 >
5451 :echo log10(0.01)
5452< -2.0
5453
5454 Can also be used as a |method|: >
5455 Compute()->log10()
5456<
5457 {only available when compiled with the |+float| feature}
5458
5459luaeval({expr} [, {expr}]) *luaeval()*
5460 Evaluate Lua expression {expr} and return its result converted
5461 to Vim data structures. Second {expr} may hold additional
5462 argument accessible as _A inside first {expr}.
5463 Strings are returned as they are.
5464 Boolean objects are converted to numbers.
5465 Numbers are converted to |Float| values if vim was compiled
5466 with |+float| and to numbers otherwise.
5467 Dictionaries and lists obtained by vim.eval() are returned
5468 as-is.
5469 Other objects are returned as zero without any errors.
5470 See |lua-luaeval| for more details.
5471 Note that in a `:def` function local variables are not visible
5472 to {expr}.
5473
5474 Can also be used as a |method|: >
5475 GetExpr()->luaeval()
5476
5477< {only available when compiled with the |+lua| feature}
5478
5479map({expr1}, {expr2}) *map()*
5480 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00005481 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005482 item in {expr1} with the result of evaluating {expr2}.
5483 For a |Blob| each byte is replaced.
5484 For a |String|, each character, including composing
5485 characters, is replaced.
5486 If the item type changes you may want to use |mapnew()| to
5487 create a new List or Dictionary. This is required when using
5488 Vim9 script.
5489
5490 {expr2} must be a |String| or |Funcref|.
5491
5492 If {expr2} is a |String|, inside {expr2} |v:val| has the value
5493 of the current item. For a |Dictionary| |v:key| has the key
5494 of the current item and for a |List| |v:key| has the index of
5495 the current item. For a |Blob| |v:key| has the index of the
5496 current byte. For a |String| |v:key| has the index of the
5497 current character.
5498 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005499 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005500< This puts "> " before and " <" after each item in "mylist".
5501
5502 Note that {expr2} is the result of an expression and is then
5503 used as an expression again. Often it is good to use a
5504 |literal-string| to avoid having to double backslashes. You
5505 still have to double ' quotes
5506
5507 If {expr2} is a |Funcref| it is called with two arguments:
5508 1. The key or the index of the current item.
5509 2. the value of the current item.
5510 The function must return the new value of the item. Example
5511 that changes each value by "key-value": >
5512 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005513 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005514 endfunc
5515 call map(myDict, function('KeyValue'))
5516< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005517 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005518< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005519 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005520< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005521 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005522<
5523 The operation is done in-place for a |List| and |Dictionary|.
5524 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005525 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005526
5527< Returns {expr1}, the |List| or |Dictionary| that was filtered,
5528 or a new |Blob| or |String|.
5529 When an error is encountered while evaluating {expr2} no
5530 further items in {expr1} are processed.
5531 When {expr2} is a Funcref errors inside a function are ignored,
5532 unless it was defined with the "abort" flag.
5533
5534 Can also be used as a |method|: >
5535 mylist->map(expr2)
5536
5537
5538maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
5539 When {dict} is omitted or zero: Return the rhs of mapping
5540 {name} in mode {mode}. The returned String has special
5541 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01005542 listing. When {dict} is TRUE a dictionary is returned, see
5543 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005544
5545 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005546 returned if {dict} is FALSE, otherwise returns an empty Dict.
5547 When the mapping for {name} is empty, then "<Nop>" is
5548 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005549
5550 The {name} can have special key names, like in the ":map"
5551 command.
5552
5553 {mode} can be one of these strings:
5554 "n" Normal
5555 "v" Visual (including Select)
5556 "o" Operator-pending
5557 "i" Insert
5558 "c" Cmd-line
5559 "s" Select
5560 "x" Visual
5561 "l" langmap |language-mapping|
5562 "t" Terminal-Job
5563 "" Normal, Visual and Operator-pending
5564 When {mode} is omitted, the modes for "" are used.
5565
5566 When {abbr} is there and it is |TRUE| use abbreviations
5567 instead of mappings.
5568
5569 When {dict} is there and it is |TRUE| return a dictionary
5570 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01005571 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005572 "lhs" The {lhs} of the mapping as it would be typed
5573 "lhsraw" The {lhs} of the mapping as raw bytes
5574 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
5575 form, only present when it differs from "lhsraw"
5576 "rhs" The {rhs} of the mapping as typed.
5577 "silent" 1 for a |:map-silent| mapping, else 0.
5578 "noremap" 1 if the {rhs} of the mapping is not remappable.
5579 "script" 1 if mapping was defined with <script>.
5580 "expr" 1 for an expression mapping (|:map-<expr>|).
5581 "buffer" 1 for a buffer local mapping (|:map-local|).
5582 "mode" Modes for which the mapping is defined. In
5583 addition to the modes mentioned above, these
5584 characters will be used:
5585 " " Normal, Visual and Operator-pending
5586 "!" Insert and Commandline mode
5587 (|mapmode-ic|)
5588 "sid" The script local ID, used for <sid> mappings
5589 (|<SID>|).
Bram Moolenaara9528b32022-01-18 20:51:35 +00005590 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005591 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005592 "lnum" The line number in "sid", zero if unknown.
5593 "nowait" Do not wait for other, longer mappings.
5594 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01005595 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01005596 "mode_bits" Vim's internal binary representation of "mode".
5597 |mapset()| ignores this; only "mode" is used.
5598 See |maplist()| for usage examples. The values
5599 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005600
5601 The dictionary can be used to restore a mapping with
5602 |mapset()|.
5603
5604 The mappings local to the current buffer are checked first,
5605 then the global mappings.
5606 This function can be used to map a key even when it's already
5607 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005608 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005609
5610< Can also be used as a |method|: >
5611 GetKey()->maparg('n')
5612
5613mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
5614 Check if there is a mapping that matches with {name} in mode
5615 {mode}. See |maparg()| for {mode} and special names in
5616 {name}.
5617 When {abbr} is there and it is |TRUE| use abbreviations
5618 instead of mappings.
5619 A match happens with a mapping that starts with {name} and
5620 with a mapping which is equal to the start of {name}.
5621
5622 matches mapping "a" "ab" "abc" ~
5623 mapcheck("a") yes yes yes
5624 mapcheck("abc") yes yes yes
5625 mapcheck("ax") yes no no
5626 mapcheck("b") no no no
5627
5628 The difference with maparg() is that mapcheck() finds a
5629 mapping that matches with {name}, while maparg() only finds a
5630 mapping for {name} exactly.
5631 When there is no mapping that starts with {name}, an empty
5632 String is returned. If there is one, the RHS of that mapping
5633 is returned. If there are several mappings that start with
5634 {name}, the RHS of one of them is returned. This will be
5635 "<Nop>" if the RHS is empty.
5636 The mappings local to the current buffer are checked first,
5637 then the global mappings.
5638 This function can be used to check if a mapping can be added
5639 without being ambiguous. Example: >
5640 :if mapcheck("_vv") == ""
5641 : map _vv :set guifont=7x13<CR>
5642 :endif
5643< This avoids adding the "_vv" mapping when there already is a
5644 mapping for "_v" or for "_vvv".
5645
5646 Can also be used as a |method|: >
5647 GetKey()->mapcheck('n')
5648
5649
Ernie Rael09661202022-04-25 14:40:44 +01005650maplist([{abbr}]) *maplist()*
5651 Returns a |List| of all mappings. Each List item is a |Dict|,
5652 the same as what is returned by |maparg()|, see
5653 |mapping-dict|. When {abbr} is there and it is |TRUE| use
5654 abbreviations instead of mappings.
5655
5656 Example to show all mappings with 'MultiMatch' in rhs: >
5657 vim9script
5658 echo maplist()->filter(
5659 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01005660< It can be tricky to find mappings for particular |:map-modes|.
5661 |mapping-dict|'s "mode_bits" can simplify this. For example,
5662 the mode_bits for Normal, Insert or Command-line modes are
5663 0x19. To find all the mappings available in those modes you
5664 can do: >
5665 vim9script
5666 var saved_maps = []
5667 for m in maplist()
5668 if and(m.mode_bits, 0x19) != 0
5669 saved_maps->add(m)
5670 endif
5671 endfor
5672 echo saved_maps->mapnew((_, m) => m.lhs)
5673< The values of the mode_bits are defined in Vim's src/vim.h
5674 file and they can be discovered at runtime using
5675 |:map-commands| and "maplist()". Example: >
5676 vim9script
5677 omap xyzzy <Nop>
5678 var op_bit = maplist()->filter(
5679 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
5680 ounmap xyzzy
5681 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Ernie Rael09661202022-04-25 14:40:44 +01005682
5683
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005684mapnew({expr1}, {expr2}) *mapnew()*
5685 Like |map()| but instead of replacing items in {expr1} a new
5686 List or Dictionary is created and returned. {expr1} remains
5687 unchanged. Items can still be changed by {expr2}, if you
5688 don't want that use |deepcopy()| first.
5689
5690
5691mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01005692mapset({dict})
5693 Restore a mapping from a dictionary, possibly returned by
5694 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
5695 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005696 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01005697 feature allows copying mappings from one buffer to another.
5698 The dict.mode value may restore a single mapping that covers
5699 more than one mode, like with mode values of '!', ' ', 'nox',
5700 or 'v'. *E1276*
5701
5702 In the first form, {mode} and {abbr} should be the same as
5703 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005704 {mode} is used to define the mode in which the mapping is set,
5705 not the "mode" entry in {dict}.
5706 Example for saving and restoring a mapping: >
5707 let save_map = maparg('K', 'n', 0, 1)
5708 nnoremap K somethingelse
5709 ...
5710 call mapset('n', 0, save_map)
5711< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01005712 e.g. with `:map!`, you need to save/restore the mapping for
5713 all of them, when they might differ.
5714
5715 In the second form, with {dict} as the only argument, mode
5716 and abbr are taken from the dict.
5717 Example: >
5718 vim9script
5719 var save_maps = maplist()->filter(
5720 (_, m) => m.lhs == 'K')
5721 nnoremap K somethingelse
5722 cnoremap K somethingelse2
5723 # ...
5724 unmap K
5725 for d in save_maps
5726 mapset(d)
5727 endfor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005728
5729
5730match({expr}, {pat} [, {start} [, {count}]]) *match()*
5731 When {expr} is a |List| then this returns the index of the
5732 first item where {pat} matches. Each item is used as a
5733 String, |Lists| and |Dictionaries| are used as echoed.
5734
5735 Otherwise, {expr} is used as a String. The result is a
5736 Number, which gives the index (byte offset) in {expr} where
5737 {pat} matches.
5738
5739 A match at the first character or |List| item returns zero.
5740 If there is no match -1 is returned.
5741
5742 For getting submatches see |matchlist()|.
5743 Example: >
5744 :echo match("testing", "ing") " results in 4
5745 :echo match([1, 'x'], '\a') " results in 1
5746< See |string-match| for how {pat} is used.
5747 *strpbrk()*
5748 Vim doesn't have a strpbrk() function. But you can do: >
5749 :let sepidx = match(line, '[.,;: \t]')
5750< *strcasestr()*
5751 Vim doesn't have a strcasestr() function. But you can add
5752 "\c" to the pattern to ignore case: >
5753 :let idx = match(haystack, '\cneedle')
5754<
5755 If {start} is given, the search starts from byte index
5756 {start} in a String or item {start} in a |List|.
5757 The result, however, is still the index counted from the
5758 first character/item. Example: >
5759 :echo match("testing", "ing", 2)
5760< result is again "4". >
5761 :echo match("testing", "ing", 4)
5762< result is again "4". >
5763 :echo match("testing", "t", 2)
5764< result is "3".
5765 For a String, if {start} > 0 then it is like the string starts
5766 {start} bytes later, thus "^" will match at {start}. Except
5767 when {count} is given, then it's like matches before the
5768 {start} byte are ignored (this is a bit complicated to keep it
5769 backwards compatible).
5770 For a String, if {start} < 0, it will be set to 0. For a list
5771 the index is counted from the end.
5772 If {start} is out of range ({start} > strlen({expr}) for a
5773 String or {start} > len({expr}) for a |List|) -1 is returned.
5774
5775 When {count} is given use the {count}'th match. When a match
5776 is found in a String the search for the next one starts one
5777 character further. Thus this example results in 1: >
5778 echo match("testing", "..", 0, 2)
5779< In a |List| the search continues in the next item.
5780 Note that when {count} is added the way {start} works changes,
5781 see above.
5782
5783 See |pattern| for the patterns that are accepted.
5784 The 'ignorecase' option is used to set the ignore-caseness of
5785 the pattern. 'smartcase' is NOT used. The matching is always
5786 done like 'magic' is set and 'cpoptions' is empty.
5787 Note that a match at the start is preferred, thus when the
5788 pattern is using "*" (any number of matches) it tends to find
5789 zero matches at the start instead of a number of matches
5790 further down in the text.
5791
5792 Can also be used as a |method|: >
5793 GetText()->match('word')
5794 GetList()->match('word')
5795<
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005796 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005797matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
5798 Defines a pattern to be highlighted in the current window (a
5799 "match"). It will be highlighted with {group}. Returns an
5800 identification number (ID), which can be used to delete the
5801 match using |matchdelete()|. The ID is bound to the window.
5802 Matching is case sensitive and magic, unless case sensitivity
5803 or magicness are explicitly overridden in {pattern}. The
5804 'magic', 'smartcase' and 'ignorecase' options are not used.
5805 The "Conceal" value is special, it causes the match to be
5806 concealed.
5807
5808 The optional {priority} argument assigns a priority to the
5809 match. A match with a high priority will have its
5810 highlighting overrule that of a match with a lower priority.
5811 A priority is specified as an integer (negative numbers are no
5812 exception). If the {priority} argument is not specified, the
5813 default priority is 10. The priority of 'hlsearch' is zero,
5814 hence all matches with a priority greater than zero will
5815 overrule it. Syntax highlighting (see 'syntax') is a separate
5816 mechanism, and regardless of the chosen priority a match will
5817 always overrule syntax highlighting.
5818
5819 The optional {id} argument allows the request for a specific
5820 match ID. If a specified ID is already taken, an error
5821 message will appear and the match will not be added. An ID
5822 is specified as a positive integer (zero excluded). IDs 1, 2
5823 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01005824 respectively. 3 is reserved for use by the |matchparen|
5825 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01005826 If the {id} argument is not specified or -1, |matchadd()|
5827 automatically chooses a free ID.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005828
5829 The optional {dict} argument allows for further custom
5830 values. Currently this is used to specify a match specific
5831 conceal character that will be shown for |hl-Conceal|
5832 highlighted matches. The dict can have the following members:
5833
5834 conceal Special character to show instead of the
5835 match (only for |hl-Conceal| highlighted
5836 matches, see |:syn-cchar|)
5837 window Instead of the current window use the
5838 window with this number or window ID.
5839
5840 The number of matches is not limited, as it is the case with
5841 the |:match| commands.
5842
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005843 Returns -1 on error.
5844
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005845 Example: >
5846 :highlight MyGroup ctermbg=green guibg=green
5847 :let m = matchadd("MyGroup", "TODO")
5848< Deletion of the pattern: >
5849 :call matchdelete(m)
5850
5851< A list of matches defined by |matchadd()| and |:match| are
5852 available from |getmatches()|. All matches can be deleted in
5853 one operation by |clearmatches()|.
5854
5855 Can also be used as a |method|: >
5856 GetGroup()->matchadd('TODO')
5857<
5858 *matchaddpos()*
5859matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
5860 Same as |matchadd()|, but requires a list of positions {pos}
5861 instead of a pattern. This command is faster than |matchadd()|
5862 because it does not require to handle regular expressions and
5863 sets buffer line boundaries to redraw screen. It is supposed
5864 to be used when fast match additions and deletions are
5865 required, for example to highlight matching parentheses.
5866
5867 {pos} is a list of positions. Each position can be one of
5868 these:
5869 - A number. This whole line will be highlighted. The first
5870 line has number 1.
5871 - A list with one number, e.g., [23]. The whole line with this
5872 number will be highlighted.
5873 - A list with two numbers, e.g., [23, 11]. The first number is
5874 the line number, the second one is the column number (first
5875 column is 1, the value must correspond to the byte index as
5876 |col()| would return). The character at this position will
5877 be highlighted.
5878 - A list with three numbers, e.g., [23, 11, 3]. As above, but
5879 the third number gives the length of the highlight in bytes.
5880
5881 The maximum number of positions in {pos} is 8.
5882
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005883 Returns -1 on error.
5884
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005885 Example: >
5886 :highlight MyGroup ctermbg=green guibg=green
5887 :let m = matchaddpos("MyGroup", [[23, 24], 34])
5888< Deletion of the pattern: >
5889 :call matchdelete(m)
5890
5891< Matches added by |matchaddpos()| are returned by
5892 |getmatches()|.
5893
5894 Can also be used as a |method|: >
5895 GetGroup()->matchaddpos([23, 11])
5896
5897matcharg({nr}) *matcharg()*
5898 Selects the {nr} match item, as set with a |:match|,
5899 |:2match| or |:3match| command.
5900 Return a |List| with two elements:
5901 The name of the highlight group used
5902 The pattern used.
5903 When {nr} is not 1, 2 or 3 returns an empty |List|.
5904 When there is no match item set returns ['', ''].
5905 This is useful to save and restore a |:match|.
5906 Highlighting matches using the |:match| commands are limited
5907 to three matches. |matchadd()| does not have this limitation.
5908
5909 Can also be used as a |method|: >
5910 GetMatch()->matcharg()
5911
5912matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
5913 Deletes a match with ID {id} previously defined by |matchadd()|
5914 or one of the |:match| commands. Returns 0 if successful,
5915 otherwise -1. See example for |matchadd()|. All matches can
5916 be deleted in one operation by |clearmatches()|.
5917 If {win} is specified, use the window with this number or
5918 window ID instead of the current window.
5919
5920 Can also be used as a |method|: >
5921 GetMatch()->matchdelete()
5922
5923matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
5924 Same as |match()|, but return the index of first character
5925 after the match. Example: >
5926 :echo matchend("testing", "ing")
5927< results in "7".
5928 *strspn()* *strcspn()*
5929 Vim doesn't have a strspn() or strcspn() function, but you can
5930 do it with matchend(): >
5931 :let span = matchend(line, '[a-zA-Z]')
5932 :let span = matchend(line, '[^a-zA-Z]')
5933< Except that -1 is returned when there are no matches.
5934
5935 The {start}, if given, has the same meaning as for |match()|. >
5936 :echo matchend("testing", "ing", 2)
5937< results in "7". >
5938 :echo matchend("testing", "ing", 5)
5939< result is "-1".
5940 When {expr} is a |List| the result is equal to |match()|.
5941
5942 Can also be used as a |method|: >
5943 GetText()->matchend('word')
5944
5945
5946matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
5947 If {list} is a list of strings, then returns a |List| with all
5948 the strings in {list} that fuzzy match {str}. The strings in
5949 the returned list are sorted based on the matching score.
5950
5951 The optional {dict} argument always supports the following
5952 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01005953 matchseq When this item is present return only matches
5954 that contain the characters in {str} in the
5955 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01005956 limit Maximum number of matches in {list} to be
5957 returned. Zero means no limit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005958
5959 If {list} is a list of dictionaries, then the optional {dict}
5960 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01005961 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005962 {str}. The value of this item should be a
5963 string.
5964 text_cb |Funcref| that will be called for every item
5965 in {list} to get the text for fuzzy matching.
5966 This should accept a dictionary item as the
5967 argument and return the text for that item to
5968 use for fuzzy matching.
5969
5970 {str} is treated as a literal string and regular expression
5971 matching is NOT supported. The maximum supported {str} length
5972 is 256.
5973
5974 When {str} has multiple words each separated by white space,
5975 then the list of strings that have all the words is returned.
5976
5977 If there are no matching strings or there is an error, then an
5978 empty list is returned. If length of {str} is greater than
5979 256, then returns an empty list.
5980
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01005981 When {limit} is given, matchfuzzy() will find up to this
5982 number of matches in {list} and return them in sorted order.
5983
Bram Moolenaar1588bc82022-03-08 21:35:07 +00005984 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005985 matching strings.
5986
5987 Example: >
5988 :echo matchfuzzy(["clay", "crow"], "cay")
5989< results in ["clay"]. >
5990 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
5991< results in a list of buffer names fuzzy matching "ndl". >
5992 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
5993< results in a list of buffer information dicts with buffer
5994 names fuzzy matching "ndl". >
5995 :echo getbufinfo()->matchfuzzy("spl",
5996 \ {'text_cb' : {v -> v.name}})
5997< results in a list of buffer information dicts with buffer
5998 names fuzzy matching "spl". >
5999 :echo v:oldfiles->matchfuzzy("test")
6000< results in a list of file names fuzzy matching "test". >
6001 :let l = readfile("buffer.c")->matchfuzzy("str")
6002< results in a list of lines in "buffer.c" fuzzy matching "str". >
6003 :echo ['one two', 'two one']->matchfuzzy('two one')
6004< results in ['two one', 'one two']. >
6005 :echo ['one two', 'two one']->matchfuzzy('two one',
6006 \ {'matchseq': 1})
6007< results in ['two one'].
6008
6009matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
6010 Same as |matchfuzzy()|, but returns the list of matched
6011 strings, the list of character positions where characters
6012 in {str} matches and a list of matching scores. You can
6013 use |byteidx()| to convert a character position to a byte
6014 position.
6015
6016 If {str} matches multiple times in a string, then only the
6017 positions for the best match is returned.
6018
6019 If there are no matching strings or there is an error, then a
6020 list with three empty list items is returned.
6021
6022 Example: >
6023 :echo matchfuzzypos(['testing'], 'tsg')
6024< results in [['testing'], [[0, 2, 6]], [99]] >
6025 :echo matchfuzzypos(['clay', 'lacy'], 'la')
6026< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
6027 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
6028< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
6029
6030matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
6031 Same as |match()|, but return a |List|. The first item in the
6032 list is the matched string, same as what matchstr() would
6033 return. Following items are submatches, like "\1", "\2", etc.
6034 in |:substitute|. When an optional submatch didn't match an
6035 empty string is used. Example: >
6036 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
6037< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
6038 When there is no match an empty list is returned.
6039
6040 You can pass in a List, but that is not very useful.
6041
6042 Can also be used as a |method|: >
6043 GetText()->matchlist('word')
6044
6045matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
6046 Same as |match()|, but return the matched string. Example: >
6047 :echo matchstr("testing", "ing")
6048< results in "ing".
6049 When there is no match "" is returned.
6050 The {start}, if given, has the same meaning as for |match()|. >
6051 :echo matchstr("testing", "ing", 2)
6052< results in "ing". >
6053 :echo matchstr("testing", "ing", 5)
6054< result is "".
6055 When {expr} is a |List| then the matching item is returned.
6056 The type isn't changed, it's not necessarily a String.
6057
6058 Can also be used as a |method|: >
6059 GetText()->matchstr('word')
6060
6061matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
6062 Same as |matchstr()|, but return the matched string, the start
6063 position and the end position of the match. Example: >
6064 :echo matchstrpos("testing", "ing")
6065< results in ["ing", 4, 7].
6066 When there is no match ["", -1, -1] is returned.
6067 The {start}, if given, has the same meaning as for |match()|. >
6068 :echo matchstrpos("testing", "ing", 2)
6069< results in ["ing", 4, 7]. >
6070 :echo matchstrpos("testing", "ing", 5)
6071< result is ["", -1, -1].
6072 When {expr} is a |List| then the matching item, the index
6073 of first item where {pat} matches, the start position and the
6074 end position of the match are returned. >
6075 :echo matchstrpos([1, '__x'], '\a')
6076< result is ["x", 1, 2, 3].
6077 The type isn't changed, it's not necessarily a String.
6078
6079 Can also be used as a |method|: >
6080 GetText()->matchstrpos('word')
6081<
6082
6083 *max()*
6084max({expr}) Return the maximum value of all items in {expr}. Example: >
6085 echo max([apples, pears, oranges])
6086
6087< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6088 it returns the maximum of all values in the Dictionary.
6089 If {expr} is neither a List nor a Dictionary, or one of the
6090 items in {expr} cannot be used as a Number this results in
6091 an error. An empty |List| or |Dictionary| results in zero.
6092
6093 Can also be used as a |method|: >
6094 mylist->max()
6095
6096
6097menu_info({name} [, {mode}]) *menu_info()*
6098 Return information about the specified menu {name} in
6099 mode {mode}. The menu name should be specified without the
6100 shortcut character ('&'). If {name} is "", then the top-level
6101 menu names are returned.
6102
6103 {mode} can be one of these strings:
6104 "n" Normal
6105 "v" Visual (including Select)
6106 "o" Operator-pending
6107 "i" Insert
6108 "c" Cmd-line
6109 "s" Select
6110 "x" Visual
6111 "t" Terminal-Job
6112 "" Normal, Visual and Operator-pending
6113 "!" Insert and Cmd-line
6114 When {mode} is omitted, the modes for "" are used.
6115
6116 Returns a |Dictionary| containing the following items:
6117 accel menu item accelerator text |menu-text|
6118 display display name (name without '&')
6119 enabled v:true if this menu item is enabled
6120 Refer to |:menu-enable|
6121 icon name of the icon file (for toolbar)
6122 |toolbar-icon|
6123 iconidx index of a built-in icon
6124 modes modes for which the menu is defined. In
6125 addition to the modes mentioned above, these
6126 characters will be used:
6127 " " Normal, Visual and Operator-pending
6128 name menu item name.
6129 noremenu v:true if the {rhs} of the menu item is not
6130 remappable else v:false.
6131 priority menu order priority |menu-priority|
6132 rhs right-hand-side of the menu item. The returned
6133 string has special characters translated like
6134 in the output of the ":menu" command listing.
6135 When the {rhs} of a menu item is empty, then
6136 "<Nop>" is returned.
6137 script v:true if script-local remapping of {rhs} is
6138 allowed else v:false. See |:menu-script|.
6139 shortcut shortcut key (character after '&' in
6140 the menu name) |menu-shortcut|
6141 silent v:true if the menu item is created
6142 with <silent> argument |:menu-silent|
6143 submenus |List| containing the names of
6144 all the submenus. Present only if the menu
6145 item has submenus.
6146
6147 Returns an empty dictionary if the menu item is not found.
6148
6149 Examples: >
6150 :echo menu_info('Edit.Cut')
6151 :echo menu_info('File.Save', 'n')
6152
6153 " Display the entire menu hierarchy in a buffer
6154 func ShowMenu(name, pfx)
6155 let m = menu_info(a:name)
6156 call append(line('$'), a:pfx .. m.display)
6157 for child in m->get('submenus', [])
6158 call ShowMenu(a:name .. '.' .. escape(child, '.'),
6159 \ a:pfx .. ' ')
6160 endfor
6161 endfunc
6162 new
6163 for topmenu in menu_info('').submenus
6164 call ShowMenu(topmenu, '')
6165 endfor
6166<
6167 Can also be used as a |method|: >
6168 GetMenuName()->menu_info('v')
6169
6170
6171< *min()*
6172min({expr}) Return the minimum value of all items in {expr}. Example: >
6173 echo min([apples, pears, oranges])
6174
6175< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6176 it returns the minimum of all values in the Dictionary.
6177 If {expr} is neither a List nor a Dictionary, or one of the
6178 items in {expr} cannot be used as a Number this results in
6179 an error. An empty |List| or |Dictionary| results in zero.
6180
6181 Can also be used as a |method|: >
6182 mylist->min()
6183
6184< *mkdir()* *E739*
6185mkdir({name} [, {path} [, {prot}]])
6186 Create directory {name}.
6187
6188 If {path} is "p" then intermediate directories are created as
6189 necessary. Otherwise it must be "".
6190
6191 If {prot} is given it is used to set the protection bits of
6192 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
6193 the user, readable for others). Use 0o700 to make it
6194 unreadable for others. This is only used for the last part of
6195 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
6196 created with 0o755.
6197 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006198 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006199
6200< This function is not available in the |sandbox|.
6201
6202 There is no error if the directory already exists and the "p"
6203 flag is passed (since patch 8.0.1708). However, without the
6204 "p" option the call will fail.
6205
6206 The function result is a Number, which is TRUE if the call was
6207 successful or FALSE if the directory creation failed or partly
6208 failed.
6209
6210 Not available on all systems. To check use: >
6211 :if exists("*mkdir")
6212
6213< Can also be used as a |method|: >
6214 GetName()->mkdir()
6215<
6216 *mode()*
6217mode([expr]) Return a string that indicates the current mode.
6218 If [expr] is supplied and it evaluates to a non-zero Number or
6219 a non-empty String (|non-zero-arg|), then the full mode is
6220 returned, otherwise only the first letter is returned.
6221 Also see |state()|.
6222
6223 n Normal
6224 no Operator-pending
6225 nov Operator-pending (forced characterwise |o_v|)
6226 noV Operator-pending (forced linewise |o_V|)
6227 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
6228 CTRL-V is one character
6229 niI Normal using |i_CTRL-O| in |Insert-mode|
6230 niR Normal using |i_CTRL-O| in |Replace-mode|
6231 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
6232 nt Terminal-Normal (insert goes to Terminal-Job mode)
6233 v Visual by character
6234 vs Visual by character using |v_CTRL-O| in Select mode
6235 V Visual by line
6236 Vs Visual by line using |v_CTRL-O| in Select mode
6237 CTRL-V Visual blockwise
6238 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
6239 s Select by character
6240 S Select by line
6241 CTRL-S Select blockwise
6242 i Insert
6243 ic Insert mode completion |compl-generic|
6244 ix Insert mode |i_CTRL-X| completion
6245 R Replace |R|
6246 Rc Replace mode completion |compl-generic|
6247 Rx Replace mode |i_CTRL-X| completion
6248 Rv Virtual Replace |gR|
6249 Rvc Virtual Replace mode completion |compl-generic|
6250 Rvx Virtual Replace mode |i_CTRL-X| completion
6251 c Command-line editing
6252 cv Vim Ex mode |gQ|
6253 ce Normal Ex mode |Q|
6254 r Hit-enter prompt
6255 rm The -- more -- prompt
6256 r? A |:confirm| query of some sort
6257 ! Shell or external command is executing
6258 t Terminal-Job mode: keys go to the job
6259
6260 This is useful in the 'statusline' option or when used
6261 with |remote_expr()| In most other places it always returns
6262 "c" or "n".
6263 Note that in the future more modes and more specific modes may
6264 be added. It's better not to compare the whole string but only
6265 the leading character(s).
6266 Also see |visualmode()|.
6267
6268 Can also be used as a |method|: >
6269 DoFull()->mode()
6270
6271mzeval({expr}) *mzeval()*
6272 Evaluate MzScheme expression {expr} and return its result
6273 converted to Vim data structures.
6274 Numbers and strings are returned as they are.
6275 Pairs (including lists and improper lists) and vectors are
6276 returned as Vim |Lists|.
6277 Hash tables are represented as Vim |Dictionary| type with keys
6278 converted to strings.
6279 All other types are converted to string with display function.
6280 Examples: >
6281 :mz (define l (list 1 2 3))
6282 :mz (define h (make-hash)) (hash-set! h "list" l)
6283 :echo mzeval("l")
6284 :echo mzeval("h")
6285<
6286 Note that in a `:def` function local variables are not visible
6287 to {expr}.
6288
6289 Can also be used as a |method|: >
6290 GetExpr()->mzeval()
6291<
6292 {only available when compiled with the |+mzscheme| feature}
6293
6294nextnonblank({lnum}) *nextnonblank()*
6295 Return the line number of the first line at or below {lnum}
6296 that is not blank. Example: >
6297 if getline(nextnonblank(1)) =~ "Java"
6298< When {lnum} is invalid or there is no non-blank line at or
6299 below it, zero is returned.
6300 {lnum} is used like with |getline()|.
6301 See also |prevnonblank()|.
6302
6303 Can also be used as a |method|: >
6304 GetLnum()->nextnonblank()
6305
6306nr2char({expr} [, {utf8}]) *nr2char()*
6307 Return a string with a single character, which has the number
6308 value {expr}. Examples: >
6309 nr2char(64) returns "@"
6310 nr2char(32) returns " "
6311< When {utf8} is omitted or zero, the current 'encoding' is used.
6312 Example for "utf-8": >
6313 nr2char(300) returns I with bow character
6314< When {utf8} is TRUE, always return UTF-8 characters.
6315 Note that a NUL character in the file is specified with
6316 nr2char(10), because NULs are represented with newline
6317 characters. nr2char(0) is a real NUL and terminates the
6318 string, thus results in an empty string.
6319 To turn a list of character numbers into a string: >
6320 let list = [65, 66, 67]
6321 let str = join(map(list, {_, val -> nr2char(val)}), '')
6322< Result: "ABC"
6323
6324 Can also be used as a |method|: >
6325 GetNumber()->nr2char()
6326
6327or({expr}, {expr}) *or()*
6328 Bitwise OR on the two arguments. The arguments are converted
6329 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006330 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006331 Example: >
6332 :let bits = or(bits, 0x80)
6333< Can also be used as a |method|: >
6334 :let bits = bits->or(0x80)
6335
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006336< Rationale: The reason this is a function and not using the "|"
6337 character like many languages, is that Vi has always used "|"
6338 to separate commands. In many places it would not be clear if
6339 "|" is an operator or a command separator.
6340
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006341
6342pathshorten({path} [, {len}]) *pathshorten()*
6343 Shorten directory names in the path {path} and return the
6344 result. The tail, the file name, is kept as-is. The other
6345 components in the path are reduced to {len} letters in length.
6346 If {len} is omitted or smaller than 1 then 1 is used (single
6347 letters). Leading '~' and '.' characters are kept. Examples: >
6348 :echo pathshorten('~/.vim/autoload/myfile.vim')
6349< ~/.v/a/myfile.vim ~
6350>
6351 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
6352< ~/.vi/au/myfile.vim ~
6353 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006354 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006355
6356 Can also be used as a |method|: >
6357 GetDirectories()->pathshorten()
6358
6359perleval({expr}) *perleval()*
6360 Evaluate Perl expression {expr} in scalar context and return
6361 its result converted to Vim data structures. If value can't be
6362 converted, it is returned as a string Perl representation.
6363 Note: If you want an array or hash, {expr} must return a
6364 reference to it.
6365 Example: >
6366 :echo perleval('[1 .. 4]')
6367< [1, 2, 3, 4]
6368
6369 Note that in a `:def` function local variables are not visible
6370 to {expr}.
6371
6372 Can also be used as a |method|: >
6373 GetExpr()->perleval()
6374
6375< {only available when compiled with the |+perl| feature}
6376
6377
6378popup_ functions are documented here: |popup-functions|
6379
6380
6381pow({x}, {y}) *pow()*
6382 Return the power of {x} to the exponent {y} as a |Float|.
6383 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006384 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006385 Examples: >
6386 :echo pow(3, 3)
6387< 27.0 >
6388 :echo pow(2, 16)
6389< 65536.0 >
6390 :echo pow(32, 0.20)
6391< 2.0
6392
6393 Can also be used as a |method|: >
6394 Compute()->pow(3)
6395<
6396 {only available when compiled with the |+float| feature}
6397
6398prevnonblank({lnum}) *prevnonblank()*
6399 Return the line number of the first line at or above {lnum}
6400 that is not blank. Example: >
6401 let ind = indent(prevnonblank(v:lnum - 1))
6402< When {lnum} is invalid or there is no non-blank line at or
6403 above it, zero is returned.
6404 {lnum} is used like with |getline()|.
6405 Also see |nextnonblank()|.
6406
6407 Can also be used as a |method|: >
6408 GetLnum()->prevnonblank()
6409
6410printf({fmt}, {expr1} ...) *printf()*
6411 Return a String with {fmt}, where "%" items are replaced by
6412 the formatted form of their respective arguments. Example: >
6413 printf("%4d: E%d %.30s", lnum, errno, msg)
6414< May result in:
6415 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
6416
6417 When used as a |method| the base is passed as the second
6418 argument: >
6419 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006420<
6421 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006422
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006423 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006424 %s string
6425 %6S string right-aligned in 6 display cells
6426 %6s string right-aligned in 6 bytes
6427 %.9s string truncated to 9 bytes
6428 %c single byte
6429 %d decimal number
6430 %5d decimal number padded with spaces to 5 characters
6431 %x hex number
6432 %04x hex number padded with zeros to at least 4 characters
6433 %X hex number using upper case letters
6434 %o octal number
6435 %08b binary number padded with zeros to at least 8 chars
6436 %f floating point number as 12.23, inf, -inf or nan
6437 %F floating point number as 12.23, INF, -INF or NAN
6438 %e floating point number as 1.23e3, inf, -inf or nan
6439 %E floating point number as 1.23E3, INF, -INF or NAN
6440 %g floating point number, as %f or %e depending on value
6441 %G floating point number, as %F or %E depending on value
6442 %% the % character itself
6443
6444 Conversion specifications start with '%' and end with the
6445 conversion type. All other characters are copied unchanged to
6446 the result.
6447
6448 The "%" starts a conversion specification. The following
6449 arguments appear in sequence:
6450
6451 % [flags] [field-width] [.precision] type
6452
6453 flags
6454 Zero or more of the following flags:
6455
6456 # The value should be converted to an "alternate
6457 form". For c, d, and s conversions, this option
6458 has no effect. For o conversions, the precision
6459 of the number is increased to force the first
6460 character of the output string to a zero (except
6461 if a zero value is printed with an explicit
6462 precision of zero).
6463 For b and B conversions, a non-zero result has
6464 the string "0b" (or "0B" for B conversions)
6465 prepended to it.
6466 For x and X conversions, a non-zero result has
6467 the string "0x" (or "0X" for X conversions)
6468 prepended to it.
6469
6470 0 (zero) Zero padding. For all conversions the converted
6471 value is padded on the left with zeros rather
6472 than blanks. If a precision is given with a
6473 numeric conversion (d, b, B, o, x, and X), the 0
6474 flag is ignored.
6475
6476 - A negative field width flag; the converted value
6477 is to be left adjusted on the field boundary.
6478 The converted value is padded on the right with
6479 blanks, rather than on the left with blanks or
6480 zeros. A - overrides a 0 if both are given.
6481
6482 ' ' (space) A blank should be left before a positive
6483 number produced by a signed conversion (d).
6484
6485 + A sign must always be placed before a number
6486 produced by a signed conversion. A + overrides
6487 a space if both are used.
6488
6489 field-width
6490 An optional decimal digit string specifying a minimum
6491 field width. If the converted value has fewer bytes
6492 than the field width, it will be padded with spaces on
6493 the left (or right, if the left-adjustment flag has
6494 been given) to fill out the field width. For the S
6495 conversion the count is in cells.
6496
6497 .precision
6498 An optional precision, in the form of a period '.'
6499 followed by an optional digit string. If the digit
6500 string is omitted, the precision is taken as zero.
6501 This gives the minimum number of digits to appear for
6502 d, o, x, and X conversions, the maximum number of
6503 bytes to be printed from a string for s conversions,
6504 or the maximum number of cells to be printed from a
6505 string for S conversions.
6506 For floating point it is the number of digits after
6507 the decimal point.
6508
6509 type
6510 A character that specifies the type of conversion to
6511 be applied, see below.
6512
6513 A field width or precision, or both, may be indicated by an
6514 asterisk '*' instead of a digit string. In this case, a
6515 Number argument supplies the field width or precision. A
6516 negative field width is treated as a left adjustment flag
6517 followed by a positive field width; a negative precision is
6518 treated as though it were missing. Example: >
6519 :echo printf("%d: %.*s", nr, width, line)
6520< This limits the length of the text used from "line" to
6521 "width" bytes.
6522
6523 The conversion specifiers and their meanings are:
6524
6525 *printf-d* *printf-b* *printf-B* *printf-o*
6526 *printf-x* *printf-X*
6527 dbBoxX The Number argument is converted to signed decimal
6528 (d), unsigned binary (b and B), unsigned octal (o), or
6529 unsigned hexadecimal (x and X) notation. The letters
6530 "abcdef" are used for x conversions; the letters
6531 "ABCDEF" are used for X conversions.
6532 The precision, if any, gives the minimum number of
6533 digits that must appear; if the converted value
6534 requires fewer digits, it is padded on the left with
6535 zeros.
6536 In no case does a non-existent or small field width
6537 cause truncation of a numeric field; if the result of
6538 a conversion is wider than the field width, the field
6539 is expanded to contain the conversion result.
6540 The 'h' modifier indicates the argument is 16 bits.
6541 The 'l' modifier indicates the argument is 32 bits.
6542 The 'L' modifier indicates the argument is 64 bits.
6543 Generally, these modifiers are not useful. They are
6544 ignored when type is known from the argument.
6545
6546 i alias for d
6547 D alias for ld
6548 U alias for lu
6549 O alias for lo
6550
6551 *printf-c*
6552 c The Number argument is converted to a byte, and the
6553 resulting character is written.
6554
6555 *printf-s*
6556 s The text of the String argument is used. If a
6557 precision is specified, no more bytes than the number
6558 specified are used.
6559 If the argument is not a String type, it is
6560 automatically converted to text with the same format
6561 as ":echo".
6562 *printf-S*
6563 S The text of the String argument is used. If a
6564 precision is specified, no more display cells than the
6565 number specified are used.
6566
6567 *printf-f* *E807*
6568 f F The Float argument is converted into a string of the
6569 form 123.456. The precision specifies the number of
6570 digits after the decimal point. When the precision is
6571 zero the decimal point is omitted. When the precision
6572 is not specified 6 is used. A really big number
6573 (out of range or dividing by zero) results in "inf"
6574 or "-inf" with %f (INF or -INF with %F).
6575 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
6576 Example: >
6577 echo printf("%.2f", 12.115)
6578< 12.12
6579 Note that roundoff depends on the system libraries.
6580 Use |round()| when in doubt.
6581
6582 *printf-e* *printf-E*
6583 e E The Float argument is converted into a string of the
6584 form 1.234e+03 or 1.234E+03 when using 'E'. The
6585 precision specifies the number of digits after the
6586 decimal point, like with 'f'.
6587
6588 *printf-g* *printf-G*
6589 g G The Float argument is converted like with 'f' if the
6590 value is between 0.001 (inclusive) and 10000000.0
6591 (exclusive). Otherwise 'e' is used for 'g' and 'E'
6592 for 'G'. When no precision is specified superfluous
6593 zeroes and '+' signs are removed, except for the zero
6594 immediately after the decimal point. Thus 10000000.0
6595 results in 1.0e7.
6596
6597 *printf-%*
6598 % A '%' is written. No argument is converted. The
6599 complete conversion specification is "%%".
6600
6601 When a Number argument is expected a String argument is also
6602 accepted and automatically converted.
6603 When a Float or String argument is expected a Number argument
6604 is also accepted and automatically converted.
6605 Any other argument type results in an error message.
6606
6607 *E766* *E767*
6608 The number of {exprN} arguments must exactly match the number
6609 of "%" items. If there are not sufficient or too many
6610 arguments an error is given. Up to 18 arguments can be used.
6611
6612
6613prompt_getprompt({buf}) *prompt_getprompt()*
6614 Returns the effective prompt text for buffer {buf}. {buf} can
6615 be a buffer name or number. See |prompt-buffer|.
6616
6617 If the buffer doesn't exist or isn't a prompt buffer, an empty
6618 string is returned.
6619
6620 Can also be used as a |method|: >
6621 GetBuffer()->prompt_getprompt()
6622
6623< {only available when compiled with the |+channel| feature}
6624
6625
6626prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
6627 Set prompt callback for buffer {buf} to {expr}. When {expr}
6628 is an empty string the callback is removed. This has only
6629 effect if {buf} has 'buftype' set to "prompt".
6630
6631 The callback is invoked when pressing Enter. The current
6632 buffer will always be the prompt buffer. A new line for a
6633 prompt is added before invoking the callback, thus the prompt
6634 for which the callback was invoked will be in the last but one
6635 line.
6636 If the callback wants to add text to the buffer, it must
6637 insert it above the last line, since that is where the current
6638 prompt is. This can also be done asynchronously.
6639 The callback is invoked with one argument, which is the text
6640 that was entered at the prompt. This can be an empty string
6641 if the user only typed Enter.
6642 Example: >
6643 call prompt_setcallback(bufnr(), function('s:TextEntered'))
6644 func s:TextEntered(text)
6645 if a:text == 'exit' || a:text == 'quit'
6646 stopinsert
6647 close
6648 else
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006649 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006650 " Reset 'modified' to allow the buffer to be closed.
6651 set nomodified
6652 endif
6653 endfunc
6654
6655< Can also be used as a |method|: >
6656 GetBuffer()->prompt_setcallback(callback)
6657
6658< {only available when compiled with the |+channel| feature}
6659
6660prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
6661 Set a callback for buffer {buf} to {expr}. When {expr} is an
6662 empty string the callback is removed. This has only effect if
6663 {buf} has 'buftype' set to "prompt".
6664
6665 This callback will be invoked when pressing CTRL-C in Insert
6666 mode. Without setting a callback Vim will exit Insert mode,
6667 as in any buffer.
6668
6669 Can also be used as a |method|: >
6670 GetBuffer()->prompt_setinterrupt(callback)
6671
6672< {only available when compiled with the |+channel| feature}
6673
6674prompt_setprompt({buf}, {text}) *prompt_setprompt()*
6675 Set prompt for buffer {buf} to {text}. You most likely want
6676 {text} to end in a space.
6677 The result is only visible if {buf} has 'buftype' set to
6678 "prompt". Example: >
6679 call prompt_setprompt(bufnr(), 'command: ')
6680<
6681 Can also be used as a |method|: >
6682 GetBuffer()->prompt_setprompt('command: ')
6683
6684< {only available when compiled with the |+channel| feature}
6685
6686prop_ functions are documented here: |text-prop-functions|
6687
6688pum_getpos() *pum_getpos()*
6689 If the popup menu (see |ins-completion-menu|) is not visible,
6690 returns an empty |Dictionary|, otherwise, returns a
6691 |Dictionary| with the following keys:
6692 height nr of items visible
6693 width screen cells
6694 row top screen row (0 first row)
6695 col leftmost screen column (0 first col)
6696 size total nr of items
6697 scrollbar |TRUE| if scrollbar is visible
6698
6699 The values are the same as in |v:event| during
6700 |CompleteChanged|.
6701
6702pumvisible() *pumvisible()*
6703 Returns non-zero when the popup menu is visible, zero
6704 otherwise. See |ins-completion-menu|.
6705 This can be used to avoid some things that would remove the
6706 popup menu.
6707
6708py3eval({expr}) *py3eval()*
6709 Evaluate Python expression {expr} and return its result
6710 converted to Vim data structures.
6711 Numbers and strings are returned as they are (strings are
6712 copied though, Unicode strings are additionally converted to
6713 'encoding').
6714 Lists are represented as Vim |List| type.
6715 Dictionaries are represented as Vim |Dictionary| type with
6716 keys converted to strings.
6717 Note that in a `:def` function local variables are not visible
6718 to {expr}.
6719
6720 Can also be used as a |method|: >
6721 GetExpr()->py3eval()
6722
6723< {only available when compiled with the |+python3| feature}
6724
6725 *E858* *E859*
6726pyeval({expr}) *pyeval()*
6727 Evaluate Python expression {expr} and return its result
6728 converted to Vim data structures.
6729 Numbers and strings are returned as they are (strings are
6730 copied though).
6731 Lists are represented as Vim |List| type.
6732 Dictionaries are represented as Vim |Dictionary| type,
6733 non-string keys result in error.
6734 Note that in a `:def` function local variables are not visible
6735 to {expr}.
6736
6737 Can also be used as a |method|: >
6738 GetExpr()->pyeval()
6739
6740< {only available when compiled with the |+python| feature}
6741
6742pyxeval({expr}) *pyxeval()*
6743 Evaluate Python expression {expr} and return its result
6744 converted to Vim data structures.
6745 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
6746 See also: |pyeval()|, |py3eval()|
6747
6748 Can also be used as a |method|: >
6749 GetExpr()->pyxeval()
6750
6751< {only available when compiled with the |+python| or the
6752 |+python3| feature}
6753
6754rand([{expr}]) *rand()* *random*
6755 Return a pseudo-random Number generated with an xoshiro128**
6756 algorithm using seed {expr}. The returned number is 32 bits,
6757 also on 64 bits systems, for consistency.
6758 {expr} can be initialized by |srand()| and will be updated by
6759 rand(). If {expr} is omitted, an internal seed value is used
6760 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006761 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006762
6763 Examples: >
6764 :echo rand()
6765 :let seed = srand()
6766 :echo rand(seed)
6767 :echo rand(seed) % 16 " random number 0 - 15
6768<
6769
6770 *E726* *E727*
6771range({expr} [, {max} [, {stride}]]) *range()*
6772 Returns a |List| with Numbers:
6773 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
6774 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
6775 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
6776 {max}] (increasing {expr} with {stride} each time, not
6777 producing a value past {max}).
6778 When the maximum is one before the start the result is an
6779 empty list. When the maximum is more than one before the
6780 start this is an error.
6781 Examples: >
6782 range(4) " [0, 1, 2, 3]
6783 range(2, 4) " [2, 3, 4]
6784 range(2, 9, 3) " [2, 5, 8]
6785 range(2, -2, -1) " [2, 1, 0, -1, -2]
6786 range(0) " []
6787 range(2, 0) " error!
6788<
6789 Can also be used as a |method|: >
6790 GetExpr()->range()
6791<
6792
6793readblob({fname}) *readblob()*
6794 Read file {fname} in binary mode and return a |Blob|.
6795 When the file can't be opened an error message is given and
6796 the result is an empty |Blob|.
6797 Also see |readfile()| and |writefile()|.
6798
6799
6800readdir({directory} [, {expr} [, {dict}]]) *readdir()*
6801 Return a list with file and directory names in {directory}.
6802 You can also use |glob()| if you don't need to do complicated
6803 things, such as limiting the number of matches.
6804 The list will be sorted (case sensitive), see the {dict}
6805 argument below for changing the sort order.
6806
6807 When {expr} is omitted all entries are included.
6808 When {expr} is given, it is evaluated to check what to do:
6809 If {expr} results in -1 then no further entries will
6810 be handled.
6811 If {expr} results in 0 then this entry will not be
6812 added to the list.
6813 If {expr} results in 1 then this entry will be added
6814 to the list.
6815 The entries "." and ".." are always excluded.
6816 Each time {expr} is evaluated |v:val| is set to the entry name.
6817 When {expr} is a function the name is passed as the argument.
6818 For example, to get a list of files ending in ".txt": >
6819 readdir(dirname, {n -> n =~ '.txt$'})
6820< To skip hidden and backup files: >
6821 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00006822< *E857*
6823 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006824 values. Currently this is used to specify if and how sorting
6825 should be performed. The dict can have the following members:
6826
6827 sort How to sort the result returned from the system.
6828 Valid values are:
6829 "none" do not sort (fastest method)
6830 "case" sort case sensitive (byte value of
6831 each character, technically, using
6832 strcmp()) (default)
6833 "icase" sort case insensitive (technically
6834 using strcasecmp())
6835 "collate" sort using the collation order
6836 of the "POSIX" or "C" |locale|
6837 (technically using strcoll())
6838 Other values are silently ignored.
6839
6840 For example, to get a list of all files in the current
6841 directory without sorting the individual entries: >
6842 readdir('.', '1', #{sort: 'none'})
6843< If you want to get a directory tree: >
6844 function! s:tree(dir)
6845 return {a:dir : map(readdir(a:dir),
6846 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006847 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006848 endfunction
6849 echo s:tree(".")
6850<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006851 Returns an empty List on error.
6852
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006853 Can also be used as a |method|: >
6854 GetDirName()->readdir()
6855<
6856readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
6857 Extended version of |readdir()|.
6858 Return a list of Dictionaries with file and directory
6859 information in {directory}.
6860 This is useful if you want to get the attributes of file and
6861 directory at the same time as getting a list of a directory.
6862 This is much faster than calling |readdir()| then calling
6863 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
6864 each file and directory especially on MS-Windows.
6865 The list will by default be sorted by name (case sensitive),
6866 the sorting can be changed by using the optional {dict}
6867 argument, see |readdir()|.
6868
6869 The Dictionary for file and directory information has the
6870 following items:
6871 group Group name of the entry. (Only on Unix)
6872 name Name of the entry.
6873 perm Permissions of the entry. See |getfperm()|.
6874 size Size of the entry. See |getfsize()|.
6875 time Timestamp of the entry. See |getftime()|.
6876 type Type of the entry.
6877 On Unix, almost same as |getftype()| except:
6878 Symlink to a dir "linkd"
6879 Other symlink "link"
6880 On MS-Windows:
6881 Normal file "file"
6882 Directory "dir"
6883 Junction "junction"
6884 Symlink to a dir "linkd"
6885 Other symlink "link"
6886 Other reparse point "reparse"
6887 user User name of the entry's owner. (Only on Unix)
6888 On Unix, if the entry is a symlink, the Dictionary includes
6889 the information of the target (except the "type" item).
6890 On MS-Windows, it includes the information of the symlink
6891 itself because of performance reasons.
6892
6893 When {expr} is omitted all entries are included.
6894 When {expr} is given, it is evaluated to check what to do:
6895 If {expr} results in -1 then no further entries will
6896 be handled.
6897 If {expr} results in 0 then this entry will not be
6898 added to the list.
6899 If {expr} results in 1 then this entry will be added
6900 to the list.
6901 The entries "." and ".." are always excluded.
6902 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
6903 of the entry.
6904 When {expr} is a function the entry is passed as the argument.
6905 For example, to get a list of files ending in ".txt": >
6906 readdirex(dirname, {e -> e.name =~ '.txt$'})
6907<
6908 For example, to get a list of all files in the current
6909 directory without sorting the individual entries: >
6910 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006911<
6912 Can also be used as a |method|: >
6913 GetDirName()->readdirex()
6914<
6915
6916 *readfile()*
6917readfile({fname} [, {type} [, {max}]])
6918 Read file {fname} and return a |List|, each line of the file
6919 as an item. Lines are broken at NL characters. Macintosh
6920 files separated with CR will result in a single long line
6921 (unless a NL appears somewhere).
6922 All NUL characters are replaced with a NL character.
6923 When {type} contains "b" binary mode is used:
6924 - When the last line ends in a NL an extra empty list item is
6925 added.
6926 - No CR characters are removed.
6927 Otherwise:
6928 - CR characters that appear before a NL are removed.
6929 - Whether the last line ends in a NL or not does not matter.
6930 - When 'encoding' is Unicode any UTF-8 byte order mark is
6931 removed from the text.
6932 When {max} is given this specifies the maximum number of lines
6933 to be read. Useful if you only want to check the first ten
6934 lines of a file: >
6935 :for line in readfile(fname, '', 10)
6936 : if line =~ 'Date' | echo line | endif
6937 :endfor
6938< When {max} is negative -{max} lines from the end of the file
6939 are returned, or as many as there are.
6940 When {max} is zero the result is an empty list.
6941 Note that without {max} the whole file is read into memory.
6942 Also note that there is no recognition of encoding. Read a
6943 file into a buffer if you need to.
6944 Deprecated (use |readblob()| instead): When {type} contains
6945 "B" a |Blob| is returned with the binary data of the file
6946 unmodified.
6947 When the file can't be opened an error message is given and
6948 the result is an empty list.
6949 Also see |writefile()|.
6950
6951 Can also be used as a |method|: >
6952 GetFileName()->readfile()
6953
6954reduce({object}, {func} [, {initial}]) *reduce()* *E998*
6955 {func} is called for every item in {object}, which can be a
6956 |String|, |List| or a |Blob|. {func} is called with two
6957 arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00006958 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006959
6960 {initial} is the initial result. When omitted, the first item
6961 in {object} is used and {func} is first called for the second
6962 item. If {initial} is not given and {object} is empty no
6963 result can be computed, an E998 error is given.
6964
6965 Examples: >
6966 echo reduce([1, 3, 5], { acc, val -> acc + val })
6967 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
6968 echo reduce(0z1122, { acc, val -> 2 * acc + val })
6969 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
6970<
6971 Can also be used as a |method|: >
6972 echo mylist->reduce({ acc, val -> acc + val }, 0)
6973
6974
6975reg_executing() *reg_executing()*
6976 Returns the single letter name of the register being executed.
6977 Returns an empty string when no register is being executed.
6978 See |@|.
6979
6980reg_recording() *reg_recording()*
6981 Returns the single letter name of the register being recorded.
6982 Returns an empty string when not recording. See |q|.
6983
6984reltime([{start} [, {end}]]) *reltime()*
6985 Return an item that represents a time value. The item is a
6986 list with items that depend on the system. In Vim 9 script
6987 list<any> can be used.
6988 The item can be passed to |reltimestr()| to convert it to a
6989 string or |reltimefloat()| to convert to a Float.
6990
Bram Moolenaar016188f2022-06-06 20:52:59 +01006991 Without an argument reltime() returns the current time (the
Bram Moolenaareb490412022-06-28 13:44:46 +01006992 representation is system-dependent, it can not be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01006993 wall-clock time, see |localtime()| for that).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006994 With one argument is returns the time passed since the time
6995 specified in the argument.
6996 With two arguments it returns the time passed between {start}
6997 and {end}.
6998
6999 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007000 reltime(). If there is an error an empty List is returned in
7001 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007002
7003 Can also be used as a |method|: >
7004 GetStart()->reltime()
7005<
7006 {only available when compiled with the |+reltime| feature}
7007
7008reltimefloat({time}) *reltimefloat()*
7009 Return a Float that represents the time value of {time}.
7010 Example: >
7011 let start = reltime()
7012 call MyFunction()
7013 let seconds = reltimefloat(reltime(start))
7014< See the note of reltimestr() about overhead.
7015 Also see |profiling|.
7016 If there is an error 0.0 is returned in legacy script, in Vim9
7017 script an error is given.
7018
7019 Can also be used as a |method|: >
7020 reltime(start)->reltimefloat()
7021
7022< {only available when compiled with the |+reltime| feature}
7023
7024reltimestr({time}) *reltimestr()*
7025 Return a String that represents the time value of {time}.
7026 This is the number of seconds, a dot and the number of
7027 microseconds. Example: >
7028 let start = reltime()
7029 call MyFunction()
7030 echo reltimestr(reltime(start))
7031< Note that overhead for the commands will be added to the time.
7032 The accuracy depends on the system.
7033 Leading spaces are used to make the string align nicely. You
7034 can use split() to remove it. >
7035 echo split(reltimestr(reltime(start)))[0]
7036< Also see |profiling|.
7037 If there is an error an empty string is returned in legacy
7038 script, in Vim9 script an error is given.
7039
7040 Can also be used as a |method|: >
7041 reltime(start)->reltimestr()
7042
7043< {only available when compiled with the |+reltime| feature}
7044
7045 *remote_expr()* *E449*
7046remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007047 Send the {string} to {server}. The {server} argument is a
7048 string, also see |{server}|.
7049
7050 The string is sent as an expression and the result is returned
7051 after evaluation. The result must be a String or a |List|. A
7052 |List| is turned into a String by joining the items with a
7053 line break in between (not at the end), like with join(expr,
7054 "\n").
7055
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007056 If {idvar} is present and not empty, it is taken as the name
7057 of a variable and a {serverid} for later use with
7058 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007059
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007060 If {timeout} is given the read times out after this many
7061 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007062
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007063 See also |clientserver| |RemoteReply|.
7064 This function is not available in the |sandbox|.
7065 {only available when compiled with the |+clientserver| feature}
7066 Note: Any errors will cause a local error message to be issued
7067 and the result will be the empty string.
7068
7069 Variables will be evaluated in the global namespace,
7070 independent of a function currently being active. Except
7071 when in debug mode, then local function variables and
7072 arguments can be evaluated.
7073
7074 Examples: >
7075 :echo remote_expr("gvim", "2+2")
7076 :echo remote_expr("gvim1", "b:current_syntax")
7077<
7078 Can also be used as a |method|: >
7079 ServerName()->remote_expr(expr)
7080
7081remote_foreground({server}) *remote_foreground()*
7082 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007083 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007084 This works like: >
7085 remote_expr({server}, "foreground()")
7086< Except that on Win32 systems the client does the work, to work
7087 around the problem that the OS doesn't always allow the server
7088 to bring itself to the foreground.
7089 Note: This does not restore the window if it was minimized,
7090 like foreground() does.
7091 This function is not available in the |sandbox|.
7092
7093 Can also be used as a |method|: >
7094 ServerName()->remote_foreground()
7095
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007096< {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007097 Win32 console version}
7098
7099
7100remote_peek({serverid} [, {retvar}]) *remote_peek()*
7101 Returns a positive number if there are available strings
7102 from {serverid}. Copies any reply string into the variable
7103 {retvar} if specified. {retvar} must be a string with the
7104 name of a variable.
7105 Returns zero if none are available.
7106 Returns -1 if something is wrong.
7107 See also |clientserver|.
7108 This function is not available in the |sandbox|.
7109 {only available when compiled with the |+clientserver| feature}
7110 Examples: >
7111 :let repl = ""
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007112 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007113
7114< Can also be used as a |method|: >
7115 ServerId()->remote_peek()
7116
7117remote_read({serverid}, [{timeout}]) *remote_read()*
7118 Return the oldest available reply from {serverid} and consume
7119 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007120 reply is available. Returns an empty string, if a reply is
7121 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007122 See also |clientserver|.
7123 This function is not available in the |sandbox|.
7124 {only available when compiled with the |+clientserver| feature}
7125 Example: >
7126 :echo remote_read(id)
7127
7128< Can also be used as a |method|: >
7129 ServerId()->remote_read()
7130<
7131 *remote_send()* *E241*
7132remote_send({server}, {string} [, {idvar}])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007133 Send the {string} to {server}. The {server} argument is a
7134 string, also see |{server}|.
7135
7136 The string is sent as input keys and the function returns
7137 immediately. At the Vim server the keys are not mapped
7138 |:map|.
7139
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007140 If {idvar} is present, it is taken as the name of a variable
7141 and a {serverid} for later use with remote_read() is stored
7142 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007143
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007144 See also |clientserver| |RemoteReply|.
7145 This function is not available in the |sandbox|.
7146 {only available when compiled with the |+clientserver| feature}
7147
7148 Note: Any errors will be reported in the server and may mess
7149 up the display.
7150 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007151 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007152 \ remote_read(serverid)
7153
7154 :autocmd NONE RemoteReply *
7155 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007156 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007157 \ 'server2client(expand("<client>"), "HELLO")<CR>')
7158<
7159 Can also be used as a |method|: >
7160 ServerName()->remote_send(keys)
7161<
7162 *remote_startserver()* *E941* *E942*
7163remote_startserver({name})
7164 Become the server {name}. This fails if already running as a
7165 server, when |v:servername| is not empty.
7166
7167 Can also be used as a |method|: >
7168 ServerName()->remote_startserver()
7169
7170< {only available when compiled with the |+clientserver| feature}
7171
7172remove({list}, {idx} [, {end}]) *remove()*
7173 Without {end}: Remove the item at {idx} from |List| {list} and
7174 return the item.
7175 With {end}: Remove items from {idx} to {end} (inclusive) and
7176 return a |List| with these items. When {idx} points to the same
7177 item as {end} a list with one item is returned. When {end}
7178 points to an item before {idx} this is an error.
7179 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007180 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007181 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007182 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007183 :call remove(mylist, 0, 9)
7184<
7185 Use |delete()| to remove a file.
7186
7187 Can also be used as a |method|: >
7188 mylist->remove(idx)
7189
7190remove({blob}, {idx} [, {end}])
7191 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
7192 return the byte.
7193 With {end}: Remove bytes from {idx} to {end} (inclusive) and
7194 return a |Blob| with these bytes. When {idx} points to the same
7195 byte as {end} a |Blob| with one byte is returned. When {end}
7196 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007197 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007198 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007199 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007200 :call remove(mylist, 0, 9)
7201
7202remove({dict}, {key})
7203 Remove the entry from {dict} with key {key} and return it.
7204 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007205 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007206< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007207 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007208
7209rename({from}, {to}) *rename()*
7210 Rename the file by the name {from} to the name {to}. This
7211 should also work to move files across file systems. The
7212 result is a Number, which is 0 if the file was renamed
7213 successfully, and non-zero when the renaming failed.
7214 NOTE: If {to} exists it is overwritten without warning.
7215 This function is not available in the |sandbox|.
7216
7217 Can also be used as a |method|: >
7218 GetOldName()->rename(newname)
7219
7220repeat({expr}, {count}) *repeat()*
7221 Repeat {expr} {count} times and return the concatenated
7222 result. Example: >
7223 :let separator = repeat('-', 80)
7224< When {count} is zero or negative the result is empty.
7225 When {expr} is a |List| the result is {expr} concatenated
7226 {count} times. Example: >
7227 :let longlist = repeat(['a', 'b'], 3)
7228< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
7229
7230 Can also be used as a |method|: >
7231 mylist->repeat(count)
7232
7233resolve({filename}) *resolve()* *E655*
7234 On MS-Windows, when {filename} is a shortcut (a .lnk file),
7235 returns the path the shortcut points to in a simplified form.
7236 When {filename} is a symbolic link or junction point, return
7237 the full path to the target. If the target of junction is
7238 removed, return {filename}.
7239 On Unix, repeat resolving symbolic links in all path
7240 components of {filename} and return the simplified result.
7241 To cope with link cycles, resolving of symbolic links is
7242 stopped after 100 iterations.
7243 On other systems, return the simplified {filename}.
7244 The simplification step is done as by |simplify()|.
7245 resolve() keeps a leading path component specifying the
7246 current directory (provided the result is still a relative
7247 path name) and also keeps a trailing path separator.
7248
7249 Can also be used as a |method|: >
7250 GetName()->resolve()
7251
7252reverse({object}) *reverse()*
7253 Reverse the order of items in {object} in-place.
7254 {object} can be a |List| or a |Blob|.
7255 Returns {object}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007256 Returns zero if {object} is not a List or a Blob.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007257 If you want an object to remain unmodified make a copy first: >
7258 :let revlist = reverse(copy(mylist))
7259< Can also be used as a |method|: >
7260 mylist->reverse()
7261
7262round({expr}) *round()*
7263 Round off {expr} to the nearest integral value and return it
7264 as a |Float|. If {expr} lies halfway between two integral
7265 values, then use the larger one (away from zero).
7266 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007267 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007268 Examples: >
7269 echo round(0.456)
7270< 0.0 >
7271 echo round(4.5)
7272< 5.0 >
7273 echo round(-4.5)
7274< -5.0
7275
7276 Can also be used as a |method|: >
7277 Compute()->round()
7278<
7279 {only available when compiled with the |+float| feature}
7280
7281rubyeval({expr}) *rubyeval()*
7282 Evaluate Ruby expression {expr} and return its result
7283 converted to Vim data structures.
7284 Numbers, floats and strings are returned as they are (strings
7285 are copied though).
7286 Arrays are represented as Vim |List| type.
7287 Hashes are represented as Vim |Dictionary| type.
7288 Other objects are represented as strings resulted from their
7289 "Object#to_s" method.
7290 Note that in a `:def` function local variables are not visible
7291 to {expr}.
7292
7293 Can also be used as a |method|: >
7294 GetRubyExpr()->rubyeval()
7295
7296< {only available when compiled with the |+ruby| feature}
7297
7298screenattr({row}, {col}) *screenattr()*
7299 Like |screenchar()|, but return the attribute. This is a rather
7300 arbitrary number that can only be used to compare to the
7301 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007302 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007303
7304 Can also be used as a |method|: >
7305 GetRow()->screenattr(col)
7306
7307screenchar({row}, {col}) *screenchar()*
7308 The result is a Number, which is the character at position
7309 [row, col] on the screen. This works for every possible
7310 screen position, also status lines, window separators and the
7311 command line. The top left position is row one, column one
7312 The character excludes composing characters. For double-byte
7313 encodings it may only be the first byte.
7314 This is mainly to be used for testing.
7315 Returns -1 when row or col is out of range.
7316
7317 Can also be used as a |method|: >
7318 GetRow()->screenchar(col)
7319
7320screenchars({row}, {col}) *screenchars()*
7321 The result is a |List| of Numbers. The first number is the same
7322 as what |screenchar()| returns. Further numbers are
7323 composing characters on top of the base character.
7324 This is mainly to be used for testing.
7325 Returns an empty List when row or col is out of range.
7326
7327 Can also be used as a |method|: >
7328 GetRow()->screenchars(col)
7329
7330screencol() *screencol()*
7331 The result is a Number, which is the current screen column of
7332 the cursor. The leftmost column has number 1.
7333 This function is mainly used for testing.
7334
7335 Note: Always returns the current screen column, thus if used
7336 in a command (e.g. ":echo screencol()") it will return the
7337 column inside the command line, which is 1 when the command is
7338 executed. To get the cursor position in the file use one of
7339 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007340 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007341 nnoremap <silent> GG :echom screencol()<CR>
7342 nnoremap GG <Cmd>echom screencol()<CR>
7343<
7344screenpos({winid}, {lnum}, {col}) *screenpos()*
7345 The result is a Dict with the screen position of the text
7346 character in window {winid} at buffer line {lnum} and column
7347 {col}. {col} is a one-based byte index.
7348 The Dict has these members:
7349 row screen row
7350 col first screen column
7351 endcol last screen column
7352 curscol cursor screen column
7353 If the specified position is not visible, all values are zero.
7354 The "endcol" value differs from "col" when the character
7355 occupies more than one screen cell. E.g. for a Tab "col" can
7356 be 1 and "endcol" can be 8.
7357 The "curscol" value is where the cursor would be placed. For
7358 a Tab it would be the same as "endcol", while for a double
7359 width character it would be the same as "col".
7360 The |conceal| feature is ignored here, the column numbers are
7361 as if 'conceallevel' is zero. You can set the cursor to the
7362 right position and use |screencol()| to get the value with
7363 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007364 If the position is in a closed fold the screen position of the
7365 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007366 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007367
7368 Can also be used as a |method|: >
7369 GetWinid()->screenpos(lnum, col)
7370
7371screenrow() *screenrow()*
7372 The result is a Number, which is the current screen row of the
7373 cursor. The top line has number one.
7374 This function is mainly used for testing.
7375 Alternatively you can use |winline()|.
7376
7377 Note: Same restrictions as with |screencol()|.
7378
7379screenstring({row}, {col}) *screenstring()*
7380 The result is a String that contains the base character and
7381 any composing characters at position [row, col] on the screen.
7382 This is like |screenchars()| but returning a String with the
7383 characters.
7384 This is mainly to be used for testing.
7385 Returns an empty String when row or col is out of range.
7386
7387 Can also be used as a |method|: >
7388 GetRow()->screenstring(col)
7389<
7390 *search()*
7391search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7392 Search for regexp pattern {pattern}. The search starts at the
7393 cursor position (you can use |cursor()| to set it).
7394
7395 When a match has been found its line number is returned.
7396 If there is no match a 0 is returned and the cursor doesn't
7397 move. No error message is given.
7398
7399 {flags} is a String, which can contain these character flags:
7400 'b' search Backward instead of forward
7401 'c' accept a match at the Cursor position
7402 'e' move to the End of the match
7403 'n' do Not move the cursor
7404 'p' return number of matching sub-Pattern (see below)
7405 's' Set the ' mark at the previous location of the cursor
7406 'w' Wrap around the end of the file
7407 'W' don't Wrap around the end of the file
7408 'z' start searching at the cursor column instead of zero
7409 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
7410
7411 If the 's' flag is supplied, the ' mark is set, only if the
7412 cursor is moved. The 's' flag cannot be combined with the 'n'
7413 flag.
7414
7415 'ignorecase', 'smartcase' and 'magic' are used.
7416
7417 When the 'z' flag is not given, forward searching always
7418 starts in column zero and then matches before the cursor are
7419 skipped. When the 'c' flag is present in 'cpo' the next
7420 search starts after the match. Without the 'c' flag the next
7421 search starts one column further. This matters for
7422 overlapping matches.
7423 When searching backwards and the 'z' flag is given then the
7424 search starts in column zero, thus no match in the current
7425 line will be found (unless wrapping around the end of the
7426 file).
7427
7428 When the {stopline} argument is given then the search stops
7429 after searching this line. This is useful to restrict the
7430 search to a range of lines. Examples: >
7431 let match = search('(', 'b', line("w0"))
7432 let end = search('END', '', line("w$"))
7433< When {stopline} is used and it is not zero this also implies
7434 that the search does not wrap around the end of the file.
7435 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01007436 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007437 When the {timeout} argument is given the search stops when
7438 more than this many milliseconds have passed. Thus when
7439 {timeout} is 500 the search stops after half a second.
7440 The value must not be negative. A zero value is like not
7441 giving the argument.
7442 {only available when compiled with the |+reltime| feature}
7443
7444 If the {skip} expression is given it is evaluated with the
7445 cursor positioned on the start of a match. If it evaluates to
7446 non-zero this match is skipped. This can be used, for
7447 example, to skip a match in a comment or a string.
7448 {skip} can be a string, which is evaluated as an expression, a
7449 function reference or a lambda.
7450 When {skip} is omitted or empty, every match is accepted.
7451 When evaluating {skip} causes an error the search is aborted
7452 and -1 returned.
7453 *search()-sub-match*
7454 With the 'p' flag the returned value is one more than the
7455 first sub-match in \(\). One if none of them matched but the
7456 whole pattern did match.
7457 To get the column number too use |searchpos()|.
7458
7459 The cursor will be positioned at the match, unless the 'n'
7460 flag is used.
7461
7462 Example (goes over all files in the argument list): >
7463 :let n = 1
7464 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007465 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007466 : " start at the last char in the file and wrap for the
7467 : " first search to find match at start of file
7468 : normal G$
7469 : let flags = "w"
7470 : while search("foo", flags) > 0
7471 : s/foo/bar/g
7472 : let flags = "W"
7473 : endwhile
7474 : update " write the file if modified
7475 : let n = n + 1
7476 :endwhile
7477<
7478 Example for using some flags: >
7479 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7480< This will search for the keywords "if", "else", and "endif"
7481 under or after the cursor. Because of the 'p' flag, it
7482 returns 1, 2, or 3 depending on which keyword is found, or 0
7483 if the search fails. With the cursor on the first word of the
7484 line:
7485 if (foo == 0) | let foo = foo + 1 | endif ~
7486 the function returns 1. Without the 'c' flag, the function
7487 finds the "endif" and returns 3. The same thing happens
7488 without the 'e' flag if the cursor is on the "f" of "if".
7489 The 'n' flag tells the function not to move the cursor.
7490
7491 Can also be used as a |method|: >
7492 GetPattern()->search()
7493
7494searchcount([{options}]) *searchcount()*
7495 Get or update the last search count, like what is displayed
7496 without the "S" flag in 'shortmess'. This works even if
7497 'shortmess' does contain the "S" flag.
7498
7499 This returns a |Dictionary|. The dictionary is empty if the
7500 previous pattern was not set and "pattern" was not specified.
7501
7502 key type meaning ~
7503 current |Number| current position of match;
7504 0 if the cursor position is
7505 before the first match
7506 exact_match |Boolean| 1 if "current" is matched on
7507 "pos", otherwise 0
7508 total |Number| total count of matches found
7509 incomplete |Number| 0: search was fully completed
7510 1: recomputing was timed out
7511 2: max count exceeded
7512
7513 For {options} see further down.
7514
7515 To get the last search count when |n| or |N| was pressed, call
7516 this function with `recompute: 0` . This sometimes returns
7517 wrong information because |n| and |N|'s maximum count is 99.
7518 If it exceeded 99 the result must be max count + 1 (100). If
7519 you want to get correct information, specify `recompute: 1`: >
7520
7521 " result == maxcount + 1 (100) when many matches
7522 let result = searchcount(#{recompute: 0})
7523
7524 " Below returns correct result (recompute defaults
7525 " to 1)
7526 let result = searchcount()
7527<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01007528 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007529 function! LastSearchCount() abort
7530 let result = searchcount(#{recompute: 0})
7531 if empty(result)
7532 return ''
7533 endif
7534 if result.incomplete ==# 1 " timed out
7535 return printf(' /%s [?/??]', @/)
7536 elseif result.incomplete ==# 2 " max count exceeded
7537 if result.total > result.maxcount &&
7538 \ result.current > result.maxcount
7539 return printf(' /%s [>%d/>%d]', @/,
7540 \ result.current, result.total)
7541 elseif result.total > result.maxcount
7542 return printf(' /%s [%d/>%d]', @/,
7543 \ result.current, result.total)
7544 endif
7545 endif
7546 return printf(' /%s [%d/%d]', @/,
7547 \ result.current, result.total)
7548 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007549 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007550
7551 " Or if you want to show the count only when
7552 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007553 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007554 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
7555<
7556 You can also update the search count, which can be useful in a
7557 |CursorMoved| or |CursorMovedI| autocommand: >
7558
7559 autocmd CursorMoved,CursorMovedI *
7560 \ let s:searchcount_timer = timer_start(
7561 \ 200, function('s:update_searchcount'))
7562 function! s:update_searchcount(timer) abort
7563 if a:timer ==# s:searchcount_timer
7564 call searchcount(#{
7565 \ recompute: 1, maxcount: 0, timeout: 100})
7566 redrawstatus
7567 endif
7568 endfunction
7569<
7570 This can also be used to count matched texts with specified
7571 pattern in the current buffer using "pattern": >
7572
7573 " Count '\<foo\>' in this buffer
7574 " (Note that it also updates search count)
7575 let result = searchcount(#{pattern: '\<foo\>'})
7576
7577 " To restore old search count by old pattern,
7578 " search again
7579 call searchcount()
7580<
7581 {options} must be a |Dictionary|. It can contain:
7582 key type meaning ~
7583 recompute |Boolean| if |TRUE|, recompute the count
7584 like |n| or |N| was executed.
7585 otherwise returns the last
7586 computed result (when |n| or
7587 |N| was used when "S" is not
7588 in 'shortmess', or this
7589 function was called).
7590 (default: |TRUE|)
7591 pattern |String| recompute if this was given
7592 and different with |@/|.
7593 this works as same as the
7594 below command is executed
7595 before calling this function >
7596 let @/ = pattern
7597< (default: |@/|)
7598 timeout |Number| 0 or negative number is no
7599 timeout. timeout milliseconds
7600 for recomputing the result
7601 (default: 0)
7602 maxcount |Number| 0 or negative number is no
7603 limit. max count of matched
7604 text while recomputing the
7605 result. if search exceeded
7606 total count, "total" value
7607 becomes `maxcount + 1`
7608 (default: 99)
7609 pos |List| `[lnum, col, off]` value
7610 when recomputing the result.
7611 this changes "current" result
7612 value. see |cursor()|,
7613 |getpos()|
7614 (default: cursor's position)
7615
7616 Can also be used as a |method|: >
7617 GetSearchOpts()->searchcount()
7618<
7619searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
7620 Search for the declaration of {name}.
7621
7622 With a non-zero {global} argument it works like |gD|, find
7623 first match in the file. Otherwise it works like |gd|, find
7624 first match in the function.
7625
7626 With a non-zero {thisblock} argument matches in a {} block
7627 that ends before the cursor position are ignored. Avoids
7628 finding variable declarations only valid in another scope.
7629
7630 Moves the cursor to the found match.
7631 Returns zero for success, non-zero for failure.
7632 Example: >
7633 if searchdecl('myvar') == 0
7634 echo getline('.')
7635 endif
7636<
7637 Can also be used as a |method|: >
7638 GetName()->searchdecl()
7639<
7640 *searchpair()*
7641searchpair({start}, {middle}, {end} [, {flags} [, {skip}
7642 [, {stopline} [, {timeout}]]]])
7643 Search for the match of a nested start-end pair. This can be
7644 used to find the "endif" that matches an "if", while other
7645 if/endif pairs in between are ignored.
7646 The search starts at the cursor. The default is to search
7647 forward, include 'b' in {flags} to search backward.
7648 If a match is found, the cursor is positioned at it and the
7649 line number is returned. If no match is found 0 or -1 is
7650 returned and the cursor doesn't move. No error message is
7651 given.
7652
7653 {start}, {middle} and {end} are patterns, see |pattern|. They
7654 must not contain \( \) pairs. Use of \%( \) is allowed. When
7655 {middle} is not empty, it is found when searching from either
7656 direction, but only when not in a nested start-end pair. A
7657 typical use is: >
7658 searchpair('\<if\>', '\<else\>', '\<endif\>')
7659< By leaving {middle} empty the "else" is skipped.
7660
7661 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
7662 |search()|. Additionally:
7663 'r' Repeat until no more matches found; will find the
7664 outer pair. Implies the 'W' flag.
7665 'm' Return number of matches instead of line number with
7666 the match; will be > 1 when 'r' is used.
7667 Note: it's nearly always a good idea to use the 'W' flag, to
7668 avoid wrapping around the end of the file.
7669
7670 When a match for {start}, {middle} or {end} is found, the
7671 {skip} expression is evaluated with the cursor positioned on
7672 the start of the match. It should return non-zero if this
7673 match is to be skipped. E.g., because it is inside a comment
7674 or a string.
7675 When {skip} is omitted or empty, every match is accepted.
7676 When evaluating {skip} causes an error the search is aborted
7677 and -1 returned.
7678 {skip} can be a string, a lambda, a funcref or a partial.
7679 Anything else makes the function fail.
7680 In a `:def` function when the {skip} argument is a string
7681 constant it is compiled into instructions.
7682
7683 For {stopline} and {timeout} see |search()|.
7684
7685 The value of 'ignorecase' is used. 'magic' is ignored, the
7686 patterns are used like it's on.
7687
7688 The search starts exactly at the cursor. A match with
7689 {start}, {middle} or {end} at the next character, in the
7690 direction of searching, is the first one found. Example: >
7691 if 1
7692 if 2
7693 endif 2
7694 endif 1
7695< When starting at the "if 2", with the cursor on the "i", and
7696 searching forwards, the "endif 2" is found. When starting on
7697 the character just before the "if 2", the "endif 1" will be
7698 found. That's because the "if 2" will be found first, and
7699 then this is considered to be a nested if/endif from "if 2" to
7700 "endif 2".
7701 When searching backwards and {end} is more than one character,
7702 it may be useful to put "\zs" at the end of the pattern, so
7703 that when the cursor is inside a match with the end it finds
7704 the matching start.
7705
7706 Example, to find the "endif" command in a Vim script: >
7707
7708 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
7709 \ 'getline(".") =~ "^\\s*\""')
7710
7711< The cursor must be at or after the "if" for which a match is
7712 to be found. Note that single-quote strings are used to avoid
7713 having to double the backslashes. The skip expression only
7714 catches comments at the start of a line, not after a command.
7715 Also, a word "en" or "if" halfway a line is considered a
7716 match.
7717 Another example, to search for the matching "{" of a "}": >
7718
7719 :echo searchpair('{', '', '}', 'bW')
7720
7721< This works when the cursor is at or before the "}" for which a
7722 match is to be found. To reject matches that syntax
7723 highlighting recognized as strings: >
7724
7725 :echo searchpair('{', '', '}', 'bW',
7726 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
7727<
7728 *searchpairpos()*
7729searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
7730 [, {stopline} [, {timeout}]]]])
7731 Same as |searchpair()|, but returns a |List| with the line and
7732 column position of the match. The first element of the |List|
7733 is the line number and the second element is the byte index of
7734 the column position of the match. If no match is found,
7735 returns [0, 0]. >
7736
7737 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
7738<
7739 See |match-parens| for a bigger and more useful example.
7740
7741 *searchpos()*
7742searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7743 Same as |search()|, but returns a |List| with the line and
7744 column position of the match. The first element of the |List|
7745 is the line number and the second element is the byte index of
7746 the column position of the match. If no match is found,
7747 returns [0, 0].
7748 Example: >
7749 :let [lnum, col] = searchpos('mypattern', 'n')
7750
7751< When the 'p' flag is given then there is an extra item with
7752 the sub-pattern match number |search()-sub-match|. Example: >
7753 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
7754< In this example "submatch" is 2 when a lowercase letter is
7755 found |/\l|, 3 when an uppercase letter is found |/\u|.
7756
7757 Can also be used as a |method|: >
7758 GetPattern()->searchpos()
7759
7760server2client({clientid}, {string}) *server2client()*
7761 Send a reply string to {clientid}. The most recent {clientid}
7762 that sent a string can be retrieved with expand("<client>").
7763 {only available when compiled with the |+clientserver| feature}
7764 Returns zero for success, -1 for failure.
7765 Note:
7766 This id has to be stored before the next command can be
7767 received. I.e. before returning from the received command and
7768 before calling any commands that waits for input.
7769 See also |clientserver|.
7770 Example: >
7771 :echo server2client(expand("<client>"), "HELLO")
7772
7773< Can also be used as a |method|: >
7774 GetClientId()->server2client(string)
7775<
7776serverlist() *serverlist()*
7777 Return a list of available server names, one per line.
7778 When there are no servers or the information is not available
7779 an empty string is returned. See also |clientserver|.
7780 {only available when compiled with the |+clientserver| feature}
7781 Example: >
7782 :echo serverlist()
7783<
7784setbufline({buf}, {lnum}, {text}) *setbufline()*
7785 Set line {lnum} to {text} in buffer {buf}. This works like
7786 |setline()| for the specified buffer.
7787
7788 This function works only for loaded buffers. First call
7789 |bufload()| if needed.
7790
7791 To insert lines use |appendbufline()|.
7792 Any text properties in {lnum} are cleared.
7793
7794 {text} can be a string to set one line, or a list of strings
7795 to set multiple lines. If the list extends below the last
7796 line then those lines are added.
7797
7798 For the use of {buf}, see |bufname()| above.
7799
7800 {lnum} is used like with |setline()|.
7801 Use "$" to refer to the last line in buffer {buf}.
7802 When {lnum} is just below the last line the {text} will be
7803 added below the last line.
7804
7805 When {buf} is not a valid buffer, the buffer is not loaded or
7806 {lnum} is not valid then 1 is returned. In |Vim9| script an
7807 error is given.
7808 On success 0 is returned.
7809
7810 Can also be used as a |method|, the base is passed as the
7811 third argument: >
7812 GetText()->setbufline(buf, lnum)
7813
7814setbufvar({buf}, {varname}, {val}) *setbufvar()*
7815 Set option or local variable {varname} in buffer {buf} to
7816 {val}.
7817 This also works for a global or local window option, but it
7818 doesn't work for a global or local window variable.
7819 For a local window option the global value is unchanged.
7820 For the use of {buf}, see |bufname()| above.
7821 The {varname} argument is a string.
7822 Note that the variable name without "b:" must be used.
7823 Examples: >
7824 :call setbufvar(1, "&mod", 1)
7825 :call setbufvar("todo", "myvar", "foobar")
7826< This function is not available in the |sandbox|.
7827
7828 Can also be used as a |method|, the base is passed as the
7829 third argument: >
7830 GetValue()->setbufvar(buf, varname)
7831
7832
7833setcellwidths({list}) *setcellwidths()*
7834 Specify overrides for cell widths of character ranges. This
7835 tells Vim how wide characters are, counted in screen cells.
7836 This overrides 'ambiwidth'. Example: >
7837 setcellwidths([[0xad, 0xad, 1],
7838 \ [0x2194, 0x2199, 2]])
7839
Bram Moolenaarf10911e2022-01-29 22:20:48 +00007840< *E1109* *E1110* *E1111* *E1112* *E1113* *E1114*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007841 The {list} argument is a list of lists with each three
7842 numbers. These three numbers are [low, high, width]. "low"
7843 and "high" can be the same, in which case this refers to one
7844 character. Otherwise it is the range of characters from "low"
7845 to "high" (inclusive). "width" is either 1 or 2, indicating
7846 the character width in screen cells.
7847 An error is given if the argument is invalid, also when a
7848 range overlaps with another.
7849 Only characters with value 0x100 and higher can be used.
7850
7851 If the new value causes 'fillchars' or 'listchars' to become
7852 invalid it is rejected and an error is given.
7853
7854 To clear the overrides pass an empty list: >
7855 setcellwidths([]);
7856< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
7857 the effect for known emoji characters.
7858
7859setcharpos({expr}, {list}) *setcharpos()*
7860 Same as |setpos()| but uses the specified column number as the
7861 character index instead of the byte index in the line.
7862
7863 Example:
7864 With the text "여보세요" in line 8: >
7865 call setcharpos('.', [0, 8, 4, 0])
7866< positions the cursor on the fourth character '요'. >
7867 call setpos('.', [0, 8, 4, 0])
7868< positions the cursor on the second character '보'.
7869
7870 Can also be used as a |method|: >
7871 GetPosition()->setcharpos('.')
7872
7873setcharsearch({dict}) *setcharsearch()*
7874 Set the current character search information to {dict},
7875 which contains one or more of the following entries:
7876
7877 char character which will be used for a subsequent
7878 |,| or |;| command; an empty string clears the
7879 character search
7880 forward direction of character search; 1 for forward,
7881 0 for backward
7882 until type of character search; 1 for a |t| or |T|
7883 character search, 0 for an |f| or |F|
7884 character search
7885
7886 This can be useful to save/restore a user's character search
7887 from a script: >
7888 :let prevsearch = getcharsearch()
7889 :" Perform a command which clobbers user's search
7890 :call setcharsearch(prevsearch)
7891< Also see |getcharsearch()|.
7892
7893 Can also be used as a |method|: >
7894 SavedSearch()->setcharsearch()
7895
7896setcmdpos({pos}) *setcmdpos()*
7897 Set the cursor position in the command line to byte position
7898 {pos}. The first position is 1.
7899 Use |getcmdpos()| to obtain the current position.
7900 Only works while editing the command line, thus you must use
7901 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
7902 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
7903 set after the command line is set to the expression. For
7904 |c_CTRL-R_=| it is set after evaluating the expression but
7905 before inserting the resulting text.
7906 When the number is too big the cursor is put at the end of the
7907 line. A number smaller than one has undefined results.
7908 Returns FALSE when successful, TRUE when not editing the
7909 command line.
7910
7911 Can also be used as a |method|: >
7912 GetPos()->setcmdpos()
7913
7914setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
7915setcursorcharpos({list})
7916 Same as |cursor()| but uses the specified column number as the
7917 character index instead of the byte index in the line.
7918
7919 Example:
7920 With the text "여보세요" in line 4: >
7921 call setcursorcharpos(4, 3)
7922< positions the cursor on the third character '세'. >
7923 call cursor(4, 3)
7924< positions the cursor on the first character '여'.
7925
7926 Can also be used as a |method|: >
7927 GetCursorPos()->setcursorcharpos()
7928
7929
7930setenv({name}, {val}) *setenv()*
7931 Set environment variable {name} to {val}. Example: >
7932 call setenv('HOME', '/home/myhome')
7933
7934< When {val} is |v:null| the environment variable is deleted.
7935 See also |expr-env|.
7936
7937 Can also be used as a |method|, the base is passed as the
7938 second argument: >
7939 GetPath()->setenv('PATH')
7940
7941setfperm({fname}, {mode}) *setfperm()* *chmod*
7942 Set the file permissions for {fname} to {mode}.
7943 {mode} must be a string with 9 characters. It is of the form
7944 "rwxrwxrwx", where each group of "rwx" flags represent, in
7945 turn, the permissions of the owner of the file, the group the
7946 file belongs to, and other users. A '-' character means the
7947 permission is off, any other character means on. Multi-byte
7948 characters are not supported.
7949
7950 For example "rw-r-----" means read-write for the user,
7951 readable by the group, not accessible by others. "xx-x-----"
7952 would do the same thing.
7953
7954 Returns non-zero for success, zero for failure.
7955
7956 Can also be used as a |method|: >
7957 GetFilename()->setfperm(mode)
7958<
7959 To read permissions see |getfperm()|.
7960
7961
7962setline({lnum}, {text}) *setline()*
7963 Set line {lnum} of the current buffer to {text}. To insert
7964 lines use |append()|. To set lines in another buffer use
7965 |setbufline()|. Any text properties in {lnum} are cleared.
7966
7967 {lnum} is used like with |getline()|.
7968 When {lnum} is just below the last line the {text} will be
7969 added below the last line.
7970 {text} can be any type or a List of any type, each item is
7971 converted to a String.
7972
7973 If this succeeds, FALSE is returned. If this fails (most likely
7974 because {lnum} is invalid) TRUE is returned.
7975 In |Vim9| script an error is given if {lnum} is invalid.
7976
7977 Example: >
7978 :call setline(5, strftime("%c"))
7979
7980< When {text} is a |List| then line {lnum} and following lines
7981 will be set to the items in the list. Example: >
7982 :call setline(5, ['aaa', 'bbb', 'ccc'])
7983< This is equivalent to: >
7984 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
7985 : call setline(n, l)
7986 :endfor
7987
7988< Note: The '[ and '] marks are not set.
7989
7990 Can also be used as a |method|, the base is passed as the
7991 second argument: >
7992 GetText()->setline(lnum)
7993
7994setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
7995 Create or replace or add to the location list for window {nr}.
7996 {nr} can be the window number or the |window-ID|.
7997 When {nr} is zero the current window is used.
7998
7999 For a location list window, the displayed location list is
8000 modified. For an invalid window number {nr}, -1 is returned.
8001 Otherwise, same as |setqflist()|.
8002 Also see |location-list|.
8003
8004 For {action} see |setqflist-action|.
8005
8006 If the optional {what} dictionary argument is supplied, then
8007 only the items listed in {what} are set. Refer to |setqflist()|
8008 for the list of supported keys in {what}.
8009
8010 Can also be used as a |method|, the base is passed as the
8011 second argument: >
8012 GetLoclist()->setloclist(winnr)
8013
8014setmatches({list} [, {win}]) *setmatches()*
8015 Restores a list of matches saved by |getmatches()| for the
8016 current window. Returns 0 if successful, otherwise -1. All
8017 current matches are cleared before the list is restored. See
8018 example for |getmatches()|.
8019 If {win} is specified, use the window with this number or
8020 window ID instead of the current window.
8021
8022 Can also be used as a |method|: >
8023 GetMatches()->setmatches()
8024<
8025 *setpos()*
8026setpos({expr}, {list})
8027 Set the position for String {expr}. Possible values:
8028 . the cursor
8029 'x mark x
8030
8031 {list} must be a |List| with four or five numbers:
8032 [bufnum, lnum, col, off]
8033 [bufnum, lnum, col, off, curswant]
8034
8035 "bufnum" is the buffer number. Zero can be used for the
8036 current buffer. When setting an uppercase mark "bufnum" is
8037 used for the mark position. For other marks it specifies the
8038 buffer to set the mark in. You can use the |bufnr()| function
8039 to turn a file name into a buffer number.
8040 For setting the cursor and the ' mark "bufnum" is ignored,
8041 since these are associated with a window, not a buffer.
8042 Does not change the jumplist.
8043
8044 "lnum" and "col" are the position in the buffer. The first
8045 column is 1. Use a zero "lnum" to delete a mark. If "col" is
8046 smaller than 1 then 1 is used. To use the character count
8047 instead of the byte count, use |setcharpos()|.
8048
8049 The "off" number is only used when 'virtualedit' is set. Then
8050 it is the offset in screen columns from the start of the
8051 character. E.g., a position within a <Tab> or after the last
8052 character.
8053
8054 The "curswant" number is only used when setting the cursor
8055 position. It sets the preferred column for when moving the
8056 cursor vertically. When the "curswant" number is missing the
8057 preferred column is not set. When it is present and setting a
8058 mark position it is not used.
8059
8060 Note that for '< and '> changing the line number may result in
8061 the marks to be effectively be swapped, so that '< is always
8062 before '>.
8063
8064 Returns 0 when the position could be set, -1 otherwise.
8065 An error message is given if {expr} is invalid.
8066
8067 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
8068
8069 This does not restore the preferred column for moving
8070 vertically; if you set the cursor position with this, |j| and
8071 |k| motions will jump to previous columns! Use |cursor()| to
8072 also set the preferred column. Also see the "curswant" key in
8073 |winrestview()|.
8074
8075 Can also be used as a |method|: >
8076 GetPosition()->setpos('.')
8077
8078setqflist({list} [, {action} [, {what}]]) *setqflist()*
8079 Create or replace or add to the quickfix list.
8080
8081 If the optional {what} dictionary argument is supplied, then
8082 only the items listed in {what} are set. The first {list}
8083 argument is ignored. See below for the supported items in
8084 {what}.
8085 *setqflist-what*
8086 When {what} is not present, the items in {list} are used. Each
8087 item must be a dictionary. Non-dictionary items in {list} are
8088 ignored. Each dictionary item can contain the following
8089 entries:
8090
8091 bufnr buffer number; must be the number of a valid
8092 buffer
8093 filename name of a file; only used when "bufnr" is not
8094 present or it is invalid.
8095 module name of a module; if given it will be used in
8096 quickfix error window instead of the filename.
8097 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +00008098 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008099 pattern search pattern used to locate the error
8100 col column number
8101 vcol when non-zero: "col" is visual column
8102 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +00008103 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008104 nr error number
8105 text description of the error
8106 type single-character error type, 'E', 'W', etc.
8107 valid recognized error message
8108
8109 The "col", "vcol", "nr", "type" and "text" entries are
8110 optional. Either "lnum" or "pattern" entry can be used to
8111 locate a matching error line.
8112 If the "filename" and "bufnr" entries are not present or
8113 neither the "lnum" or "pattern" entries are present, then the
8114 item will not be handled as an error line.
8115 If both "pattern" and "lnum" are present then "pattern" will
8116 be used.
8117 If the "valid" entry is not supplied, then the valid flag is
8118 set when "bufnr" is a valid buffer or "filename" exists.
8119 If you supply an empty {list}, the quickfix list will be
8120 cleared.
8121 Note that the list is not exactly the same as what
8122 |getqflist()| returns.
8123
8124 {action} values: *setqflist-action* *E927*
8125 'a' The items from {list} are added to the existing
8126 quickfix list. If there is no existing list, then a
8127 new list is created.
8128
8129 'r' The items from the current quickfix list are replaced
8130 with the items from {list}. This can also be used to
8131 clear the list: >
8132 :call setqflist([], 'r')
8133<
8134 'f' All the quickfix lists in the quickfix stack are
8135 freed.
8136
8137 If {action} is not present or is set to ' ', then a new list
8138 is created. The new quickfix list is added after the current
8139 quickfix list in the stack and all the following lists are
8140 freed. To add a new quickfix list at the end of the stack,
8141 set "nr" in {what} to "$".
8142
8143 The following items can be specified in dictionary {what}:
8144 context quickfix list context. See |quickfix-context|
8145 efm errorformat to use when parsing text from
8146 "lines". If this is not present, then the
8147 'errorformat' option value is used.
8148 See |quickfix-parse|
8149 id quickfix list identifier |quickfix-ID|
8150 idx index of the current entry in the quickfix
8151 list specified by 'id' or 'nr'. If set to '$',
8152 then the last entry in the list is set as the
8153 current entry. See |quickfix-index|
8154 items list of quickfix entries. Same as the {list}
8155 argument.
8156 lines use 'errorformat' to parse a list of lines and
8157 add the resulting entries to the quickfix list
8158 {nr} or {id}. Only a |List| value is supported.
8159 See |quickfix-parse|
8160 nr list number in the quickfix stack; zero
8161 means the current quickfix list and "$" means
8162 the last quickfix list.
8163 quickfixtextfunc
8164 function to get the text to display in the
8165 quickfix window. The value can be the name of
8166 a function or a funcref or a lambda. Refer to
8167 |quickfix-window-function| for an explanation
8168 of how to write the function and an example.
8169 title quickfix list title text. See |quickfix-title|
8170 Unsupported keys in {what} are ignored.
8171 If the "nr" item is not present, then the current quickfix list
8172 is modified. When creating a new quickfix list, "nr" can be
8173 set to a value one greater than the quickfix stack size.
8174 When modifying a quickfix list, to guarantee that the correct
8175 list is modified, "id" should be used instead of "nr" to
8176 specify the list.
8177
8178 Examples (See also |setqflist-examples|): >
8179 :call setqflist([], 'r', {'title': 'My search'})
8180 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
8181 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
8182<
8183 Returns zero for success, -1 for failure.
8184
8185 This function can be used to create a quickfix list
8186 independent of the 'errorformat' setting. Use a command like
8187 `:cc 1` to jump to the first position.
8188
8189 Can also be used as a |method|, the base is passed as the
8190 second argument: >
8191 GetErrorlist()->setqflist()
8192<
8193 *setreg()*
8194setreg({regname}, {value} [, {options}])
8195 Set the register {regname} to {value}.
8196 If {regname} is "" or "@", the unnamed register '"' is used.
8197 The {regname} argument is a string. In |Vim9-script|
8198 {regname} must be one character.
8199
8200 {value} may be any value returned by |getreg()| or
8201 |getreginfo()|, including a |List| or |Dict|.
8202 If {options} contains "a" or {regname} is upper case,
8203 then the value is appended.
8204
8205 {options} can also contain a register type specification:
8206 "c" or "v" |characterwise| mode
8207 "l" or "V" |linewise| mode
8208 "b" or "<CTRL-V>" |blockwise-visual| mode
8209 If a number immediately follows "b" or "<CTRL-V>" then this is
8210 used as the width of the selection - if it is not specified
8211 then the width of the block is set to the number of characters
8212 in the longest line (counting a <Tab> as 1 character).
8213
8214 If {options} contains no register settings, then the default
8215 is to use character mode unless {value} ends in a <NL> for
8216 string {value} and linewise mode for list {value}. Blockwise
8217 mode is never selected automatically.
8218 Returns zero for success, non-zero for failure.
8219
8220 *E883*
8221 Note: you may not use |List| containing more than one item to
8222 set search and expression registers. Lists containing no
8223 items act like empty strings.
8224
8225 Examples: >
8226 :call setreg(v:register, @*)
8227 :call setreg('*', @%, 'ac')
8228 :call setreg('a', "1\n2\n3", 'b5')
8229 :call setreg('"', { 'points_to': 'a'})
8230
8231< This example shows using the functions to save and restore a
8232 register: >
8233 :let var_a = getreginfo()
8234 :call setreg('a', var_a)
8235< or: >
8236 :let var_a = getreg('a', 1, 1)
8237 :let var_amode = getregtype('a')
8238 ....
8239 :call setreg('a', var_a, var_amode)
8240< Note: you may not reliably restore register value
8241 without using the third argument to |getreg()| as without it
8242 newlines are represented as newlines AND Nul bytes are
8243 represented as newlines as well, see |NL-used-for-Nul|.
8244
8245 You can also change the type of a register by appending
8246 nothing: >
8247 :call setreg('a', '', 'al')
8248
8249< Can also be used as a |method|, the base is passed as the
8250 second argument: >
8251 GetText()->setreg('a')
8252
8253settabvar({tabnr}, {varname}, {val}) *settabvar()*
8254 Set tab-local variable {varname} to {val} in tab page {tabnr}.
8255 |t:var|
8256 The {varname} argument is a string.
8257 Note that autocommands are blocked, side effects may not be
8258 triggered, e.g. when setting 'filetype'.
8259 Note that the variable name without "t:" must be used.
8260 Tabs are numbered starting with one.
8261 This function is not available in the |sandbox|.
8262
8263 Can also be used as a |method|, the base is passed as the
8264 third argument: >
8265 GetValue()->settabvar(tab, name)
8266
8267settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
8268 Set option or local variable {varname} in window {winnr} to
8269 {val}.
8270 Tabs are numbered starting with one. For the current tabpage
8271 use |setwinvar()|.
8272 {winnr} can be the window number or the |window-ID|.
8273 When {winnr} is zero the current window is used.
8274 Note that autocommands are blocked, side effects may not be
8275 triggered, e.g. when setting 'filetype' or 'syntax'.
8276 This also works for a global or local buffer option, but it
8277 doesn't work for a global or local buffer variable.
8278 For a local buffer option the global value is unchanged.
8279 Note that the variable name without "w:" must be used.
8280 Examples: >
8281 :call settabwinvar(1, 1, "&list", 0)
8282 :call settabwinvar(3, 2, "myvar", "foobar")
8283< This function is not available in the |sandbox|.
8284
8285 Can also be used as a |method|, the base is passed as the
8286 fourth argument: >
8287 GetValue()->settabwinvar(tab, winnr, name)
8288
8289settagstack({nr}, {dict} [, {action}]) *settagstack()*
8290 Modify the tag stack of the window {nr} using {dict}.
8291 {nr} can be the window number or the |window-ID|.
8292
8293 For a list of supported items in {dict}, refer to
8294 |gettagstack()|. "curidx" takes effect before changing the tag
8295 stack.
8296 *E962*
8297 How the tag stack is modified depends on the {action}
8298 argument:
8299 - If {action} is not present or is set to 'r', then the tag
8300 stack is replaced.
8301 - If {action} is set to 'a', then new entries from {dict} are
8302 pushed (added) onto the tag stack.
8303 - If {action} is set to 't', then all the entries from the
8304 current entry in the tag stack or "curidx" in {dict} are
8305 removed and then new entries are pushed to the stack.
8306
8307 The current index is set to one after the length of the tag
8308 stack after the modification.
8309
8310 Returns zero for success, -1 for failure.
8311
8312 Examples (for more examples see |tagstack-examples|):
8313 Empty the tag stack of window 3: >
8314 call settagstack(3, {'items' : []})
8315
8316< Save and restore the tag stack: >
8317 let stack = gettagstack(1003)
8318 " do something else
8319 call settagstack(1003, stack)
8320 unlet stack
8321<
8322 Can also be used as a |method|, the base is passed as the
8323 second argument: >
8324 GetStack()->settagstack(winnr)
8325
8326setwinvar({winnr}, {varname}, {val}) *setwinvar()*
8327 Like |settabwinvar()| for the current tab page.
8328 Examples: >
8329 :call setwinvar(1, "&list", 0)
8330 :call setwinvar(2, "myvar", "foobar")
8331
8332< Can also be used as a |method|, the base is passed as the
8333 third argument: >
8334 GetValue()->setwinvar(winnr, name)
8335
8336sha256({string}) *sha256()*
8337 Returns a String with 64 hex characters, which is the SHA256
8338 checksum of {string}.
8339
8340 Can also be used as a |method|: >
8341 GetText()->sha256()
8342
8343< {only available when compiled with the |+cryptv| feature}
8344
8345shellescape({string} [, {special}]) *shellescape()*
8346 Escape {string} for use as a shell command argument.
8347 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +00008348 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008349 in single quotes and will double up all internal single
8350 quotes.
8351 On MS-Windows, when 'shellslash' is not set, it will enclose
8352 {string} in double quotes and double all double quotes within
8353 {string}.
8354 Otherwise it will enclose {string} in single quotes and
8355 replace all "'" with "'\''".
8356
8357 When the {special} argument is present and it's a non-zero
8358 Number or a non-empty String (|non-zero-arg|), then special
8359 items such as "!", "%", "#" and "<cword>" will be preceded by
8360 a backslash. This backslash will be removed again by the |:!|
8361 command.
8362
8363 The "!" character will be escaped (again with a |non-zero-arg|
8364 {special}) when 'shell' contains "csh" in the tail. That is
8365 because for csh and tcsh "!" is used for history replacement
8366 even when inside single quotes.
8367
8368 With a |non-zero-arg| {special} the <NL> character is also
8369 escaped. When 'shell' containing "csh" in the tail it's
8370 escaped a second time.
8371
8372 The "\" character will be escaped when 'shell' contains "fish"
8373 in the tail. That is because for fish "\" is used as an escape
8374 character inside single quotes.
8375
8376 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008377 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008378< This results in a directory listing for the file under the
8379 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008380 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008381< See also |::S|.
8382
8383 Can also be used as a |method|: >
8384 GetCommand()->shellescape()
8385
8386shiftwidth([{col}]) *shiftwidth()*
8387 Returns the effective value of 'shiftwidth'. This is the
8388 'shiftwidth' value unless it is zero, in which case it is the
8389 'tabstop' value. This function was introduced with patch
8390 7.3.694 in 2012, everybody should have it by now (however it
8391 did not allow for the optional {col} argument until 8.1.542).
8392
8393 When there is one argument {col} this is used as column number
8394 for which to return the 'shiftwidth' value. This matters for the
8395 'vartabstop' feature. If the 'vartabstop' setting is enabled and
8396 no {col} argument is given, column 1 will be assumed.
8397
8398 Can also be used as a |method|: >
8399 GetColumn()->shiftwidth()
8400
8401sign_ functions are documented here: |sign-functions-details|
8402
8403
8404simplify({filename}) *simplify()*
8405 Simplify the file name as much as possible without changing
8406 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
8407 Unix) are not resolved. If the first path component in
8408 {filename} designates the current directory, this will be
8409 valid for the result as well. A trailing path separator is
8410 not removed either. On Unix "//path" is unchanged, but
8411 "///path" is simplified to "/path" (this follows the Posix
8412 standard).
8413 Example: >
8414 simplify("./dir/.././/file/") == "./file/"
8415< Note: The combination "dir/.." is only removed if "dir" is
8416 a searchable directory or does not exist. On Unix, it is also
8417 removed when "dir" is a symbolic link within the same
8418 directory. In order to resolve all the involved symbolic
8419 links before simplifying the path name, use |resolve()|.
8420
8421 Can also be used as a |method|: >
8422 GetName()->simplify()
8423
8424sin({expr}) *sin()*
8425 Return the sine of {expr}, measured in radians, as a |Float|.
8426 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008427 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008428 Examples: >
8429 :echo sin(100)
8430< -0.506366 >
8431 :echo sin(-4.01)
8432< 0.763301
8433
8434 Can also be used as a |method|: >
8435 Compute()->sin()
8436<
8437 {only available when compiled with the |+float| feature}
8438
8439
8440sinh({expr}) *sinh()*
8441 Return the hyperbolic sine of {expr} as a |Float| in the range
8442 [-inf, inf].
8443 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008444 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008445 Examples: >
8446 :echo sinh(0.5)
8447< 0.521095 >
8448 :echo sinh(-0.9)
8449< -1.026517
8450
8451 Can also be used as a |method|: >
8452 Compute()->sinh()
8453<
8454 {only available when compiled with the |+float| feature}
8455
8456
8457slice({expr}, {start} [, {end}]) *slice()*
8458 Similar to using a |slice| "expr[start : end]", but "end" is
8459 used exclusive. And for a string the indexes are used as
8460 character indexes instead of byte indexes, like in
8461 |vim9script|. Also, composing characters are not counted.
8462 When {end} is omitted the slice continues to the last item.
8463 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008464 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008465
8466 Can also be used as a |method|: >
8467 GetList()->slice(offset)
8468
8469
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008470sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008471 Sort the items in {list} in-place. Returns {list}.
8472
8473 If you want a list to remain unmodified make a copy first: >
8474 :let sortedlist = sort(copy(mylist))
8475
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01008476< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008477 string representation of each item to sort on. Numbers sort
8478 after Strings, |Lists| after Numbers. For sorting text in the
8479 current buffer use |:sort|.
8480
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008481 When {how} is given and it is 'i' then case is ignored.
8482 In legacy script, for backwards compatibility, the value one
8483 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008484
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008485 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008486 locale is used for ordering. Implementation details: strcoll()
8487 is used to compare strings. See |:language| check or set the
8488 collation locale. |v:collate| can also be used to check the
8489 current locale. Sorting using the locale typically ignores
8490 case. Example: >
8491 " ö is sorted similarly to o with English locale.
8492 :language collate en_US.UTF8
8493 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8494< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
8495>
8496 " ö is sorted after z with Swedish locale.
8497 :language collate sv_SE.UTF8
8498 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8499< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
8500 This does not work properly on Mac.
8501
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008502 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008503 sorted numerical (Implementation detail: this uses the
8504 strtod() function to parse numbers, Strings, Lists, Dicts and
8505 Funcrefs will be considered as being 0).
8506
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008507 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008508 sorted numerical. This is like 'n' but a string containing
8509 digits will be used as the number they represent.
8510
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008511 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008512 sorted numerical. All values must be a Number or a Float.
8513
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008514 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008515 is called to compare items. The function is invoked with two
8516 items as argument and must return zero if they are equal, 1 or
8517 bigger if the first one sorts after the second one, -1 or
8518 smaller if the first one sorts before the second one.
8519
8520 {dict} is for functions with the "dict" attribute. It will be
8521 used to set the local variable "self". |Dictionary-function|
8522
8523 The sort is stable, items which compare equal (as number or as
8524 string) will keep their relative position. E.g., when sorting
8525 on numbers, text strings will sort next to each other, in the
8526 same order as they were originally.
8527
8528 Can also be used as a |method|: >
8529 mylist->sort()
8530
8531< Also see |uniq()|.
8532
8533 Example: >
8534 func MyCompare(i1, i2)
8535 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8536 endfunc
8537 eval mylist->sort("MyCompare")
8538< A shorter compare version for this specific simple case, which
8539 ignores overflow: >
8540 func MyCompare(i1, i2)
8541 return a:i1 - a:i2
8542 endfunc
8543< For a simple expression you can use a lambda: >
8544 eval mylist->sort({i1, i2 -> i1 - i2})
8545<
8546sound_clear() *sound_clear()*
8547 Stop playing all sounds.
8548
8549 On some Linux systems you may need the libcanberra-pulse
8550 package, otherwise sound may not stop.
8551
8552 {only available when compiled with the |+sound| feature}
8553
8554 *sound_playevent()*
8555sound_playevent({name} [, {callback}])
8556 Play a sound identified by {name}. Which event names are
8557 supported depends on the system. Often the XDG sound names
8558 are used. On Ubuntu they may be found in
8559 /usr/share/sounds/freedesktop/stereo. Example: >
8560 call sound_playevent('bell')
8561< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
8562 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
8563 SystemStart, SystemWelcome, etc.
8564
8565 When {callback} is specified it is invoked when the sound is
8566 finished. The first argument is the sound ID, the second
8567 argument is the status:
8568 0 sound was played to the end
8569 1 sound was interrupted
8570 2 error occurred after sound started
8571 Example: >
8572 func Callback(id, status)
8573 echomsg "sound " .. a:id .. " finished with " .. a:status
8574 endfunc
8575 call sound_playevent('bell', 'Callback')
8576
8577< MS-Windows: {callback} doesn't work for this function.
8578
8579 Returns the sound ID, which can be passed to `sound_stop()`.
8580 Returns zero if the sound could not be played.
8581
8582 Can also be used as a |method|: >
8583 GetSoundName()->sound_playevent()
8584
8585< {only available when compiled with the |+sound| feature}
8586
8587 *sound_playfile()*
8588sound_playfile({path} [, {callback}])
8589 Like `sound_playevent()` but play sound file {path}. {path}
8590 must be a full path. On Ubuntu you may find files to play
8591 with this command: >
8592 :!find /usr/share/sounds -type f | grep -v index.theme
8593
8594< Can also be used as a |method|: >
8595 GetSoundPath()->sound_playfile()
8596
Bram Moolenaar1588bc82022-03-08 21:35:07 +00008597< {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008598
8599
8600sound_stop({id}) *sound_stop()*
8601 Stop playing sound {id}. {id} must be previously returned by
8602 `sound_playevent()` or `sound_playfile()`.
8603
8604 On some Linux systems you may need the libcanberra-pulse
8605 package, otherwise sound may not stop.
8606
8607 On MS-Windows, this does not work for event sound started by
8608 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
8609
8610 Can also be used as a |method|: >
8611 soundid->sound_stop()
8612
8613< {only available when compiled with the |+sound| feature}
8614
8615 *soundfold()*
8616soundfold({word})
8617 Return the sound-folded equivalent of {word}. Uses the first
8618 language in 'spelllang' for the current window that supports
8619 soundfolding. 'spell' must be set. When no sound folding is
8620 possible the {word} is returned unmodified.
8621 This can be used for making spelling suggestions. Note that
8622 the method can be quite slow.
8623
8624 Can also be used as a |method|: >
8625 GetWord()->soundfold()
8626<
8627 *spellbadword()*
8628spellbadword([{sentence}])
8629 Without argument: The result is the badly spelled word under
8630 or after the cursor. The cursor is moved to the start of the
8631 bad word. When no bad word is found in the cursor line the
8632 result is an empty string and the cursor doesn't move.
8633
8634 With argument: The result is the first word in {sentence} that
8635 is badly spelled. If there are no spelling mistakes the
8636 result is an empty string.
8637
8638 The return value is a list with two items:
8639 - The badly spelled word or an empty string.
8640 - The type of the spelling error:
8641 "bad" spelling mistake
8642 "rare" rare word
8643 "local" word only valid in another region
8644 "caps" word should start with Capital
8645 Example: >
8646 echo spellbadword("the quik brown fox")
8647< ['quik', 'bad'] ~
8648
8649 The spelling information for the current window and the value
8650 of 'spelllang' are used.
8651
8652 Can also be used as a |method|: >
8653 GetText()->spellbadword()
8654<
8655 *spellsuggest()*
8656spellsuggest({word} [, {max} [, {capital}]])
8657 Return a |List| with spelling suggestions to replace {word}.
8658 When {max} is given up to this number of suggestions are
8659 returned. Otherwise up to 25 suggestions are returned.
8660
8661 When the {capital} argument is given and it's non-zero only
8662 suggestions with a leading capital will be given. Use this
8663 after a match with 'spellcapcheck'.
8664
8665 {word} can be a badly spelled word followed by other text.
8666 This allows for joining two words that were split. The
8667 suggestions also include the following text, thus you can
8668 replace a line.
8669
8670 {word} may also be a good word. Similar words will then be
8671 returned. {word} itself is not included in the suggestions,
8672 although it may appear capitalized.
8673
8674 The spelling information for the current window is used. The
8675 values of 'spelllang' and 'spellsuggest' are used.
8676
8677 Can also be used as a |method|: >
8678 GetWord()->spellsuggest()
8679
8680split({string} [, {pattern} [, {keepempty}]]) *split()*
8681 Make a |List| out of {string}. When {pattern} is omitted or
8682 empty each white-separated sequence of characters becomes an
8683 item.
8684 Otherwise the string is split where {pattern} matches,
8685 removing the matched characters. 'ignorecase' is not used
8686 here, add \c to ignore case. |/\c|
8687 When the first or last item is empty it is omitted, unless the
8688 {keepempty} argument is given and it's non-zero.
8689 Other empty items are kept when {pattern} matches at least one
8690 character or when {keepempty} is non-zero.
8691 Example: >
8692 :let words = split(getline('.'), '\W\+')
8693< To split a string in individual characters: >
8694 :for c in split(mystring, '\zs')
8695< If you want to keep the separator you can also use '\zs' at
8696 the end of the pattern: >
8697 :echo split('abc:def:ghi', ':\zs')
8698< ['abc:', 'def:', 'ghi'] ~
8699 Splitting a table where the first element can be empty: >
8700 :let items = split(line, ':', 1)
8701< The opposite function is |join()|.
8702
8703 Can also be used as a |method|: >
8704 GetString()->split()
8705
8706sqrt({expr}) *sqrt()*
8707 Return the non-negative square root of Float {expr} as a
8708 |Float|.
8709 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008710 is negative the result is NaN (Not a Number). Returns 0.0 if
8711 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008712 Examples: >
8713 :echo sqrt(100)
8714< 10.0 >
8715 :echo sqrt(-4.01)
8716< nan
8717 "nan" may be different, it depends on system libraries.
8718
8719 Can also be used as a |method|: >
8720 Compute()->sqrt()
8721<
8722 {only available when compiled with the |+float| feature}
8723
8724
8725srand([{expr}]) *srand()*
8726 Initialize seed used by |rand()|:
8727 - If {expr} is not given, seed values are initialized by
8728 reading from /dev/urandom, if possible, or using time(NULL)
8729 a.k.a. epoch time otherwise; this only has second accuracy.
8730 - If {expr} is given it must be a Number. It is used to
8731 initialize the seed values. This is useful for testing or
8732 when a predictable sequence is intended.
8733
8734 Examples: >
8735 :let seed = srand()
8736 :let seed = srand(userinput)
8737 :echo rand(seed)
8738
8739state([{what}]) *state()*
8740 Return a string which contains characters indicating the
8741 current state. Mostly useful in callbacks that want to do
8742 work that may not always be safe. Roughly this works like:
8743 - callback uses state() to check if work is safe to do.
8744 Yes: then do it right away.
8745 No: add to work queue and add a |SafeState| and/or
8746 |SafeStateAgain| autocommand (|SafeState| triggers at
8747 toplevel, |SafeStateAgain| triggers after handling
8748 messages and callbacks).
8749 - When SafeState or SafeStateAgain is triggered and executes
8750 your autocommand, check with `state()` if the work can be
8751 done now, and if yes remove it from the queue and execute.
8752 Remove the autocommand if the queue is now empty.
8753 Also see |mode()|.
8754
8755 When {what} is given only characters in this string will be
8756 added. E.g, this checks if the screen has scrolled: >
8757 if state('s') == ''
8758 " screen has not scrolled
8759<
8760 These characters indicate the state, generally indicating that
8761 something is busy:
8762 m halfway a mapping, :normal command, feedkeys() or
8763 stuffed command
8764 o operator pending, e.g. after |d|
8765 a Insert mode autocomplete active
8766 x executing an autocommand
8767 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
8768 ch_readraw() when reading json
8769 S not triggering SafeState or SafeStateAgain, e.g. after
8770 |f| or a count
8771 c callback invoked, including timer (repeats for
8772 recursiveness up to "ccc")
8773 s screen has scrolled for messages
8774
8775str2float({string} [, {quoted}]) *str2float()*
8776 Convert String {string} to a Float. This mostly works the
8777 same as when using a floating point number in an expression,
8778 see |floating-point-format|. But it's a bit more permissive.
8779 E.g., "1e40" is accepted, while in an expression you need to
8780 write "1.0e40". The hexadecimal form "0x123" is also
8781 accepted, but not others, like binary or octal.
8782 When {quoted} is present and non-zero then embedded single
8783 quotes before the dot are ignored, thus "1'000.0" is a
8784 thousand.
8785 Text after the number is silently ignored.
8786 The decimal point is always '.', no matter what the locale is
8787 set to. A comma ends the number: "12,345.67" is converted to
8788 12.0. You can strip out thousands separators with
8789 |substitute()|: >
8790 let f = str2float(substitute(text, ',', '', 'g'))
8791<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008792 Returns 0.0 if the conversion fails.
8793
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008794 Can also be used as a |method|: >
8795 let f = text->substitute(',', '', 'g')->str2float()
8796<
8797 {only available when compiled with the |+float| feature}
8798
8799str2list({string} [, {utf8}]) *str2list()*
8800 Return a list containing the number values which represent
8801 each character in String {string}. Examples: >
8802 str2list(" ") returns [32]
8803 str2list("ABC") returns [65, 66, 67]
8804< |list2str()| does the opposite.
8805
8806 When {utf8} is omitted or zero, the current 'encoding' is used.
8807 When {utf8} is TRUE, always treat the String as UTF-8
8808 characters. With UTF-8 composing characters are handled
8809 properly: >
8810 str2list("á") returns [97, 769]
8811
8812< Can also be used as a |method|: >
8813 GetString()->str2list()
8814
8815
8816str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
8817 Convert string {string} to a number.
8818 {base} is the conversion base, it can be 2, 8, 10 or 16.
8819 When {quoted} is present and non-zero then embedded single
8820 quotes are ignored, thus "1'000'000" is a million.
8821
8822 When {base} is omitted base 10 is used. This also means that
8823 a leading zero doesn't cause octal conversion to be used, as
8824 with the default String to Number conversion. Example: >
8825 let nr = str2nr('0123')
8826<
8827 When {base} is 16 a leading "0x" or "0X" is ignored. With a
8828 different base the result will be zero. Similarly, when
8829 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
8830 {base} is 2 a leading "0b" or "0B" is ignored.
8831 Text after the number is silently ignored.
8832
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008833 Returns 0 if {string} is empty or on error.
8834
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008835 Can also be used as a |method|: >
8836 GetText()->str2nr()
8837
8838
8839strcharlen({string}) *strcharlen()*
8840 The result is a Number, which is the number of characters
8841 in String {string}. Composing characters are ignored.
8842 |strchars()| can count the number of characters, counting
8843 composing characters separately.
8844
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008845 Returns 0 if {string} is empty or on error.
8846
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008847 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8848
8849 Can also be used as a |method|: >
8850 GetText()->strcharlen()
8851
8852
8853strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
8854 Like |strpart()| but using character index and length instead
8855 of byte index and length.
8856 When {skipcc} is omitted or zero, composing characters are
8857 counted separately.
8858 When {skipcc} set to 1, Composing characters are ignored,
8859 similar to |slice()|.
8860 When a character index is used where a character does not
8861 exist it is omitted and counted as one character. For
8862 example: >
8863 strcharpart('abc', -1, 2)
8864< results in 'a'.
8865
Bram Moolenaard592deb2022-06-17 15:42:40 +01008866 Returns an empty string on error.
8867
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008868 Can also be used as a |method|: >
8869 GetText()->strcharpart(5)
8870
8871
8872strchars({string} [, {skipcc}]) *strchars()*
8873 The result is a Number, which is the number of characters
8874 in String {string}.
8875 When {skipcc} is omitted or zero, composing characters are
8876 counted separately.
8877 When {skipcc} set to 1, Composing characters are ignored.
8878 |strcharlen()| always does this.
8879
Bram Moolenaard592deb2022-06-17 15:42:40 +01008880 Returns zero on error.
8881
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008882 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8883
8884 {skipcc} is only available after 7.4.755. For backward
8885 compatibility, you can define a wrapper function: >
8886 if has("patch-7.4.755")
8887 function s:strchars(str, skipcc)
8888 return strchars(a:str, a:skipcc)
8889 endfunction
8890 else
8891 function s:strchars(str, skipcc)
8892 if a:skipcc
8893 return strlen(substitute(a:str, ".", "x", "g"))
8894 else
8895 return strchars(a:str)
8896 endif
8897 endfunction
8898 endif
8899<
8900 Can also be used as a |method|: >
8901 GetText()->strchars()
8902
8903strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
8904 The result is a Number, which is the number of display cells
8905 String {string} occupies on the screen when it starts at {col}
8906 (first column is zero). When {col} is omitted zero is used.
8907 Otherwise it is the screen column where to start. This
8908 matters for Tab characters.
8909 The option settings of the current window are used. This
8910 matters for anything that's displayed differently, such as
8911 'tabstop' and 'display'.
8912 When {string} contains characters with East Asian Width Class
8913 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01008914 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008915 Also see |strlen()|, |strwidth()| and |strchars()|.
8916
8917 Can also be used as a |method|: >
8918 GetText()->strdisplaywidth()
8919
8920strftime({format} [, {time}]) *strftime()*
8921 The result is a String, which is a formatted date and time, as
8922 specified by the {format} string. The given {time} is used,
8923 or the current time if no time is given. The accepted
8924 {format} depends on your system, thus this is not portable!
8925 See the manual page of the C function strftime() for the
8926 format. The maximum length of the result is 80 characters.
8927 See also |localtime()|, |getftime()| and |strptime()|.
8928 The language can be changed with the |:language| command.
8929 Examples: >
8930 :echo strftime("%c") Sun Apr 27 11:49:23 1997
8931 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
8932 :echo strftime("%y%m%d %T") 970427 11:53:55
8933 :echo strftime("%H:%M") 11:55
8934 :echo strftime("%c", getftime("file.c"))
8935 Show mod time of file.c.
8936< Not available on all systems. To check use: >
8937 :if exists("*strftime")
8938
8939< Can also be used as a |method|: >
8940 GetFormat()->strftime()
8941
8942strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01008943 Get a Number corresponding to the character at {index} in
8944 {str}. This uses a zero-based character index, not a byte
8945 index. Composing characters are considered separate
8946 characters here. Use |nr2char()| to convert the Number to a
8947 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01008948 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008949 Also see |strcharpart()| and |strchars()|.
8950
8951 Can also be used as a |method|: >
8952 GetText()->strgetchar(5)
8953
8954stridx({haystack}, {needle} [, {start}]) *stridx()*
8955 The result is a Number, which gives the byte index in
8956 {haystack} of the first occurrence of the String {needle}.
8957 If {start} is specified, the search starts at index {start}.
8958 This can be used to find a second match: >
8959 :let colon1 = stridx(line, ":")
8960 :let colon2 = stridx(line, ":", colon1 + 1)
8961< The search is done case-sensitive.
8962 For pattern searches use |match()|.
8963 -1 is returned if the {needle} does not occur in {haystack}.
8964 See also |strridx()|.
8965 Examples: >
8966 :echo stridx("An Example", "Example") 3
8967 :echo stridx("Starting point", "Start") 0
8968 :echo stridx("Starting point", "start") -1
8969< *strstr()* *strchr()*
8970 stridx() works similar to the C function strstr(). When used
8971 with a single character it works similar to strchr().
8972
8973 Can also be used as a |method|: >
8974 GetHaystack()->stridx(needle)
8975<
8976 *string()*
8977string({expr}) Return {expr} converted to a String. If {expr} is a Number,
8978 Float, String, Blob or a composition of them, then the result
8979 can be parsed back with |eval()|.
8980 {expr} type result ~
8981 String 'string' (single quotes are doubled)
8982 Number 123
8983 Float 123.123456 or 1.123456e8
8984 Funcref function('name')
8985 Blob 0z00112233.44556677.8899
8986 List [item, item]
8987 Dictionary {key: value, key: value}
8988
8989 When a |List| or |Dictionary| has a recursive reference it is
8990 replaced by "[...]" or "{...}". Using eval() on the result
8991 will then fail.
8992
8993 Can also be used as a |method|: >
8994 mylist->string()
8995
8996< Also see |strtrans()|.
8997
8998
8999strlen({string}) *strlen()*
9000 The result is a Number, which is the length of the String
9001 {string} in bytes.
9002 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009003 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009004 If you want to count the number of multibyte characters use
9005 |strchars()|.
9006 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
9007
9008 Can also be used as a |method|: >
9009 GetString()->strlen()
9010
9011strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
9012 The result is a String, which is part of {src}, starting from
9013 byte {start}, with the byte length {len}.
9014 When {chars} is present and TRUE then {len} is the number of
9015 characters positions (composing characters are not counted
9016 separately, thus "1" means one base character and any
9017 following composing characters).
9018 To count {start} as characters instead of bytes use
9019 |strcharpart()|.
9020
9021 When bytes are selected which do not exist, this doesn't
9022 result in an error, the bytes are simply omitted.
9023 If {len} is missing, the copy continues from {start} till the
9024 end of the {src}. >
9025 strpart("abcdefg", 3, 2) == "de"
9026 strpart("abcdefg", -2, 4) == "ab"
9027 strpart("abcdefg", 5, 4) == "fg"
9028 strpart("abcdefg", 3) == "defg"
9029
9030< Note: To get the first character, {start} must be 0. For
9031 example, to get the character under the cursor: >
9032 strpart(getline("."), col(".") - 1, 1, v:true)
9033<
Bram Moolenaard592deb2022-06-17 15:42:40 +01009034 Returns an empty string on error.
9035
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009036 Can also be used as a |method|: >
9037 GetText()->strpart(5)
9038
9039strptime({format}, {timestring}) *strptime()*
9040 The result is a Number, which is a unix timestamp representing
9041 the date and time in {timestring}, which is expected to match
9042 the format specified in {format}.
9043
9044 The accepted {format} depends on your system, thus this is not
9045 portable! See the manual page of the C function strptime()
9046 for the format. Especially avoid "%c". The value of $TZ also
9047 matters.
9048
9049 If the {timestring} cannot be parsed with {format} zero is
9050 returned. If you do not know the format of {timestring} you
9051 can try different {format} values until you get a non-zero
9052 result.
9053
9054 See also |strftime()|.
9055 Examples: >
9056 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
9057< 862156163 >
9058 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
9059< Sun Apr 27 11:53:55 1997 >
9060 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
9061< Sun Apr 27 12:53:55 1997
9062
9063 Can also be used as a |method|: >
9064 GetFormat()->strptime(timestring)
9065<
9066 Not available on all systems. To check use: >
9067 :if exists("*strptime")
9068
9069strridx({haystack}, {needle} [, {start}]) *strridx()*
9070 The result is a Number, which gives the byte index in
9071 {haystack} of the last occurrence of the String {needle}.
9072 When {start} is specified, matches beyond this index are
9073 ignored. This can be used to find a match before a previous
9074 match: >
9075 :let lastcomma = strridx(line, ",")
9076 :let comma2 = strridx(line, ",", lastcomma - 1)
9077< The search is done case-sensitive.
9078 For pattern searches use |match()|.
9079 -1 is returned if the {needle} does not occur in {haystack}.
9080 If the {needle} is empty the length of {haystack} is returned.
9081 See also |stridx()|. Examples: >
9082 :echo strridx("an angry armadillo", "an") 3
9083< *strrchr()*
9084 When used with a single character it works similar to the C
9085 function strrchr().
9086
9087 Can also be used as a |method|: >
9088 GetHaystack()->strridx(needle)
9089
9090strtrans({string}) *strtrans()*
9091 The result is a String, which is {string} with all unprintable
9092 characters translated into printable characters |'isprint'|.
9093 Like they are shown in a window. Example: >
9094 echo strtrans(@a)
9095< This displays a newline in register a as "^@" instead of
9096 starting a new line.
9097
Bram Moolenaard592deb2022-06-17 15:42:40 +01009098 Returns an empty string on error.
9099
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009100 Can also be used as a |method|: >
9101 GetString()->strtrans()
9102
9103strwidth({string}) *strwidth()*
9104 The result is a Number, which is the number of display cells
9105 String {string} occupies. A Tab character is counted as one
9106 cell, alternatively use |strdisplaywidth()|.
9107 When {string} contains characters with East Asian Width Class
9108 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009109 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009110 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
9111
9112 Can also be used as a |method|: >
9113 GetString()->strwidth()
9114
9115submatch({nr} [, {list}]) *submatch()* *E935*
9116 Only for an expression in a |:substitute| command or
9117 substitute() function.
9118 Returns the {nr}'th submatch of the matched text. When {nr}
9119 is 0 the whole matched text is returned.
9120 Note that a NL in the string can stand for a line break of a
9121 multi-line match or a NUL character in the text.
9122 Also see |sub-replace-expression|.
9123
9124 If {list} is present and non-zero then submatch() returns
9125 a list of strings, similar to |getline()| with two arguments.
9126 NL characters in the text represent NUL characters in the
9127 text.
9128 Only returns more than one item for |:substitute|, inside
9129 |substitute()| this list will always contain one or zero
9130 items, since there are no real line breaks.
9131
9132 When substitute() is used recursively only the submatches in
9133 the current (deepest) call can be obtained.
9134
Bram Moolenaard592deb2022-06-17 15:42:40 +01009135 Returns an empty string or list on error.
9136
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009137 Examples: >
9138 :s/\d\+/\=submatch(0) + 1/
9139 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
9140< This finds the first number in the line and adds one to it.
9141 A line break is included as a newline character.
9142
9143 Can also be used as a |method|: >
9144 GetNr()->submatch()
9145
9146substitute({string}, {pat}, {sub}, {flags}) *substitute()*
9147 The result is a String, which is a copy of {string}, in which
9148 the first match of {pat} is replaced with {sub}.
9149 When {flags} is "g", all matches of {pat} in {string} are
9150 replaced. Otherwise {flags} should be "".
9151
9152 This works like the ":substitute" command (without any flags).
9153 But the matching with {pat} is always done like the 'magic'
9154 option is set and 'cpoptions' is empty (to make scripts
9155 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
9156 if you want to ignore or match case and ignore 'ignorecase'.
9157 'smartcase' is not used. See |string-match| for how {pat} is
9158 used.
9159
9160 A "~" in {sub} is not replaced with the previous {sub}.
9161 Note that some codes in {sub} have a special meaning
9162 |sub-replace-special|. For example, to replace something with
9163 "\n" (two characters), use "\\\\n" or '\\n'.
9164
9165 When {pat} does not match in {string}, {string} is returned
9166 unmodified.
9167
9168 Example: >
9169 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
9170< This removes the last component of the 'path' option. >
9171 :echo substitute("testing", ".*", "\\U\\0", "")
9172< results in "TESTING".
9173
9174 When {sub} starts with "\=", the remainder is interpreted as
9175 an expression. See |sub-replace-expression|. Example: >
9176 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009177 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009178
9179< When {sub} is a Funcref that function is called, with one
9180 optional argument. Example: >
9181 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
9182< The optional argument is a list which contains the whole
9183 matched string and up to nine submatches, like what
9184 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009185 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009186
Bram Moolenaard592deb2022-06-17 15:42:40 +01009187< Returns an empty string on error.
9188
9189 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009190 GetString()->substitute(pat, sub, flags)
9191
9192swapinfo({fname}) *swapinfo()*
9193 The result is a dictionary, which holds information about the
9194 swapfile {fname}. The available fields are:
9195 version Vim version
9196 user user name
9197 host host name
9198 fname original file name
9199 pid PID of the Vim process that created the swap
9200 file
9201 mtime last modification time in seconds
9202 inode Optional: INODE number of the file
9203 dirty 1 if file was modified, 0 if not
9204 Note that "user" and "host" are truncated to at most 39 bytes.
9205 In case of failure an "error" item is added with the reason:
9206 Cannot open file: file not found or in accessible
9207 Cannot read file: cannot read first block
9208 Not a swap file: does not contain correct block ID
9209 Magic number mismatch: Info in first block is invalid
9210
9211 Can also be used as a |method|: >
9212 GetFilename()->swapinfo()
9213
9214swapname({buf}) *swapname()*
9215 The result is the swap file path of the buffer {expr}.
9216 For the use of {buf}, see |bufname()| above.
9217 If buffer {buf} is the current buffer, the result is equal to
9218 |:swapname| (unless there is no swap file).
9219 If buffer {buf} has no swap file, returns an empty string.
9220
9221 Can also be used as a |method|: >
9222 GetBufname()->swapname()
9223
9224synID({lnum}, {col}, {trans}) *synID()*
9225 The result is a Number, which is the syntax ID at the position
9226 {lnum} and {col} in the current window.
9227 The syntax ID can be used with |synIDattr()| and
9228 |synIDtrans()| to obtain syntax information about text.
9229
9230 {col} is 1 for the leftmost column, {lnum} is 1 for the first
9231 line. 'synmaxcol' applies, in a longer line zero is returned.
9232 Note that when the position is after the last character,
9233 that's where the cursor can be in Insert mode, synID() returns
9234 zero. {lnum} is used like with |getline()|.
9235
9236 When {trans} is |TRUE|, transparent items are reduced to the
9237 item that they reveal. This is useful when wanting to know
9238 the effective color. When {trans} is |FALSE|, the transparent
9239 item is returned. This is useful when wanting to know which
9240 syntax item is effective (e.g. inside parens).
9241 Warning: This function can be very slow. Best speed is
9242 obtained by going through the file in forward direction.
9243
Bram Moolenaard592deb2022-06-17 15:42:40 +01009244 Returns zero on error.
9245
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009246 Example (echoes the name of the syntax item under the cursor): >
9247 :echo synIDattr(synID(line("."), col("."), 1), "name")
9248<
9249
9250synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
9251 The result is a String, which is the {what} attribute of
9252 syntax ID {synID}. This can be used to obtain information
9253 about a syntax item.
9254 {mode} can be "gui", "cterm" or "term", to get the attributes
9255 for that mode. When {mode} is omitted, or an invalid value is
9256 used, the attributes for the currently active highlighting are
9257 used (GUI, cterm or term).
9258 Use synIDtrans() to follow linked highlight groups.
9259 {what} result
9260 "name" the name of the syntax item
9261 "fg" foreground color (GUI: color name used to set
9262 the color, cterm: color number as a string,
9263 term: empty string)
9264 "bg" background color (as with "fg")
9265 "font" font name (only available in the GUI)
9266 |highlight-font|
9267 "sp" special color for the GUI (as with "fg")
9268 |highlight-guisp|
9269 "ul" underline color for cterm: number as a string
9270 "fg#" like "fg", but for the GUI and the GUI is
9271 running the name in "#RRGGBB" form
9272 "bg#" like "fg#" for "bg"
9273 "sp#" like "fg#" for "sp"
9274 "bold" "1" if bold
9275 "italic" "1" if italic
9276 "reverse" "1" if reverse
9277 "inverse" "1" if inverse (= reverse)
9278 "standout" "1" if standout
9279 "underline" "1" if underlined
9280 "undercurl" "1" if undercurled
9281 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +01009282 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009283
Bram Moolenaard592deb2022-06-17 15:42:40 +01009284 Returns an empty string on error.
9285
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009286 Example (echoes the color of the syntax item under the
9287 cursor): >
9288 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
9289<
9290 Can also be used as a |method|: >
9291 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9292
9293
9294synIDtrans({synID}) *synIDtrans()*
9295 The result is a Number, which is the translated syntax ID of
9296 {synID}. This is the syntax group ID of what is being used to
9297 highlight the character. Highlight links given with
9298 ":highlight link" are followed.
9299
Bram Moolenaard592deb2022-06-17 15:42:40 +01009300 Returns zero on error.
9301
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009302 Can also be used as a |method|: >
9303 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9304
9305synconcealed({lnum}, {col}) *synconcealed()*
9306 The result is a |List| with currently three items:
9307 1. The first item in the list is 0 if the character at the
9308 position {lnum} and {col} is not part of a concealable
9309 region, 1 if it is. {lnum} is used like with |getline()|.
9310 2. The second item in the list is a string. If the first item
9311 is 1, the second item contains the text which will be
9312 displayed in place of the concealed text, depending on the
9313 current setting of 'conceallevel' and 'listchars'.
9314 3. The third and final item in the list is a number
9315 representing the specific syntax region matched in the
9316 line. When the character is not concealed the value is
9317 zero. This allows detection of the beginning of a new
9318 concealable region if there are two consecutive regions
9319 with the same replacement character. For an example, if
9320 the text is "123456" and both "23" and "45" are concealed
9321 and replaced by the character "X", then:
9322 call returns ~
9323 synconcealed(lnum, 1) [0, '', 0]
9324 synconcealed(lnum, 2) [1, 'X', 1]
9325 synconcealed(lnum, 3) [1, 'X', 1]
9326 synconcealed(lnum, 4) [1, 'X', 2]
9327 synconcealed(lnum, 5) [1, 'X', 2]
9328 synconcealed(lnum, 6) [0, '', 0]
9329
9330
9331synstack({lnum}, {col}) *synstack()*
9332 Return a |List|, which is the stack of syntax items at the
9333 position {lnum} and {col} in the current window. {lnum} is
9334 used like with |getline()|. Each item in the List is an ID
9335 like what |synID()| returns.
9336 The first item in the List is the outer region, following are
9337 items contained in that one. The last one is what |synID()|
9338 returns, unless not the whole item is highlighted or it is a
9339 transparent item.
9340 This function is useful for debugging a syntax file.
9341 Example that shows the syntax stack under the cursor: >
9342 for id in synstack(line("."), col("."))
9343 echo synIDattr(id, "name")
9344 endfor
9345< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +01009346 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009347 character in a line and the first column in an empty line are
9348 valid positions.
9349
9350system({expr} [, {input}]) *system()* *E677*
9351 Get the output of the shell command {expr} as a |String|. See
9352 |systemlist()| to get the output as a |List|.
9353
9354 When {input} is given and is a |String| this string is written
9355 to a file and passed as stdin to the command. The string is
9356 written as-is, you need to take care of using the correct line
9357 separators yourself.
9358 If {input} is given and is a |List| it is written to the file
9359 in a way |writefile()| does with {binary} set to "b" (i.e.
9360 with a newline between each list item with newlines inside
9361 list items converted to NULs).
9362 When {input} is given and is a number that is a valid id for
9363 an existing buffer then the content of the buffer is written
9364 to the file line by line, each line terminated by a NL and
9365 NULs characters where the text has a NL.
9366
9367 Pipes are not used, the 'shelltemp' option is not used.
9368
9369 When prepended by |:silent| the terminal will not be set to
9370 cooked mode. This is meant to be used for commands that do
9371 not need the user to type. It avoids stray characters showing
9372 up on the screen which require |CTRL-L| to remove. >
9373 :silent let f = system('ls *.vim')
9374<
9375 Note: Use |shellescape()| or |::S| with |expand()| or
9376 |fnamemodify()| to escape special characters in a command
9377 argument. Newlines in {expr} may cause the command to fail.
9378 The characters in 'shellquote' and 'shellxquote' may also
9379 cause trouble.
9380 This is not to be used for interactive commands.
9381
9382 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009383 :let files = system('ls ' .. shellescape(expand('%:h')))
9384 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009385
9386< To make the result more system-independent, the shell output
9387 is filtered to replace <CR> with <NL> for Macintosh, and
9388 <CR><NL> with <NL> for DOS-like systems.
9389 To avoid the string being truncated at a NUL, all NUL
9390 characters are replaced with SOH (0x01).
9391
9392 The command executed is constructed using several options:
9393 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
9394 ({tmp} is an automatically generated file name).
9395 For Unix, braces are put around {expr} to allow for
9396 concatenated commands.
9397
9398 The command will be executed in "cooked" mode, so that a
9399 CTRL-C will interrupt the command (on Unix at least).
9400
9401 The resulting error code can be found in |v:shell_error|.
9402 This function will fail in |restricted-mode|.
9403
9404 Note that any wrong value in the options mentioned above may
9405 make the function fail. It has also been reported to fail
9406 when using a security agent application.
9407 Unlike ":!cmd" there is no automatic check for changed files.
9408 Use |:checktime| to force a check.
9409
9410 Can also be used as a |method|: >
9411 :echo GetCmd()->system()
9412
9413
9414systemlist({expr} [, {input}]) *systemlist()*
9415 Same as |system()|, but returns a |List| with lines (parts of
9416 output separated by NL) with NULs transformed into NLs. Output
9417 is the same as |readfile()| will output with {binary} argument
9418 set to "b", except that there is no extra empty item when the
9419 result ends in a NL.
9420 Note that on MS-Windows you may get trailing CR characters.
9421
9422 To see the difference between "echo hello" and "echo -n hello"
9423 use |system()| and |split()|: >
9424 echo system('echo hello')->split('\n', 1)
9425<
9426 Returns an empty string on error.
9427
9428 Can also be used as a |method|: >
9429 :echo GetCmd()->systemlist()
9430
9431
9432tabpagebuflist([{arg}]) *tabpagebuflist()*
9433 The result is a |List|, where each item is the number of the
9434 buffer associated with each window in the current tab page.
9435 {arg} specifies the number of the tab page to be used. When
9436 omitted the current tab page is used.
9437 When {arg} is invalid the number zero is returned.
9438 To get a list of all buffers in all tabs use this: >
9439 let buflist = []
9440 for i in range(tabpagenr('$'))
9441 call extend(buflist, tabpagebuflist(i + 1))
9442 endfor
9443< Note that a buffer may appear in more than one window.
9444
9445 Can also be used as a |method|: >
9446 GetTabpage()->tabpagebuflist()
9447
9448tabpagenr([{arg}]) *tabpagenr()*
9449 The result is a Number, which is the number of the current
9450 tab page. The first tab page has number 1.
9451
9452 The optional argument {arg} supports the following values:
9453 $ the number of the last tab page (the tab page
9454 count).
9455 # the number of the last accessed tab page
9456 (where |g<Tab>| goes to). if there is no
9457 previous tab page 0 is returned.
9458 The number can be used with the |:tab| command.
9459
Bram Moolenaard592deb2022-06-17 15:42:40 +01009460 Returns zero on error.
9461
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009462
9463tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
9464 Like |winnr()| but for tab page {tabarg}.
9465 {tabarg} specifies the number of tab page to be used.
9466 {arg} is used like with |winnr()|:
9467 - When omitted the current window number is returned. This is
9468 the window which will be used when going to this tab page.
9469 - When "$" the number of windows is returned.
9470 - When "#" the previous window nr is returned.
9471 Useful examples: >
9472 tabpagewinnr(1) " current window of tab page 1
9473 tabpagewinnr(4, '$') " number of windows in tab page 4
9474< When {tabarg} is invalid zero is returned.
9475
9476 Can also be used as a |method|: >
9477 GetTabpage()->tabpagewinnr()
9478<
9479 *tagfiles()*
9480tagfiles() Returns a |List| with the file names used to search for tags
9481 for the current buffer. This is the 'tags' option expanded.
9482
9483
9484taglist({expr} [, {filename}]) *taglist()*
9485 Returns a |List| of tags matching the regular expression {expr}.
9486
9487 If {filename} is passed it is used to prioritize the results
9488 in the same way that |:tselect| does. See |tag-priority|.
9489 {filename} should be the full path of the file.
9490
9491 Each list item is a dictionary with at least the following
9492 entries:
9493 name Name of the tag.
9494 filename Name of the file where the tag is
9495 defined. It is either relative to the
9496 current directory or a full path.
9497 cmd Ex command used to locate the tag in
9498 the file.
9499 kind Type of the tag. The value for this
9500 entry depends on the language specific
9501 kind values. Only available when
9502 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +00009503 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009504 static A file specific tag. Refer to
9505 |static-tag| for more information.
9506 More entries may be present, depending on the content of the
9507 tags file: access, implementation, inherits and signature.
9508 Refer to the ctags documentation for information about these
9509 fields. For C code the fields "struct", "class" and "enum"
9510 may appear, they give the name of the entity the tag is
9511 contained in.
9512
9513 The ex-command "cmd" can be either an ex search pattern, a
9514 line number or a line number followed by a byte number.
9515
9516 If there are no matching tags, then an empty list is returned.
9517
9518 To get an exact tag match, the anchors '^' and '$' should be
9519 used in {expr}. This also make the function work faster.
9520 Refer to |tag-regexp| for more information about the tag
9521 search regular expression pattern.
9522
9523 Refer to |'tags'| for information about how the tags file is
9524 located by Vim. Refer to |tags-file-format| for the format of
9525 the tags file generated by the different ctags tools.
9526
9527 Can also be used as a |method|: >
9528 GetTagpattern()->taglist()
9529
9530tan({expr}) *tan()*
9531 Return the tangent of {expr}, measured in radians, as a |Float|
9532 in the range [-inf, inf].
9533 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009534 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009535 Examples: >
9536 :echo tan(10)
9537< 0.648361 >
9538 :echo tan(-4.01)
9539< -1.181502
9540
9541 Can also be used as a |method|: >
9542 Compute()->tan()
9543<
9544 {only available when compiled with the |+float| feature}
9545
9546
9547tanh({expr}) *tanh()*
9548 Return the hyperbolic tangent of {expr} as a |Float| in the
9549 range [-1, 1].
9550 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009551 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009552 Examples: >
9553 :echo tanh(0.5)
9554< 0.462117 >
9555 :echo tanh(-1)
9556< -0.761594
9557
9558 Can also be used as a |method|: >
9559 Compute()->tanh()
9560<
9561 {only available when compiled with the |+float| feature}
9562
9563
9564tempname() *tempname()* *temp-file-name*
9565 The result is a String, which is the name of a file that
9566 doesn't exist. It can be used for a temporary file. The name
9567 is different for at least 26 consecutive calls. Example: >
9568 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009569 :exe "redir > " .. tmpfile
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009570< For Unix, the file will be in a private directory |tempfile|.
9571 For MS-Windows forward slashes are used when the 'shellslash'
9572 option is set, or when 'shellcmdflag' starts with '-' and
9573 'shell' does not contain powershell or pwsh.
9574
9575
9576term_ functions are documented here: |terminal-function-details|
9577
9578
9579terminalprops() *terminalprops()*
9580 Returns a |Dictionary| with properties of the terminal that Vim
9581 detected from the response to |t_RV| request. See
9582 |v:termresponse| for the response itself. If |v:termresponse|
9583 is empty most values here will be 'u' for unknown.
9584 cursor_style whether sending |t_RS| works **
9585 cursor_blink_mode whether sending |t_RC| works **
9586 underline_rgb whether |t_8u| works **
9587 mouse mouse type supported
9588
9589 ** value 'u' for unknown, 'y' for yes, 'n' for no
9590
9591 If the |+termresponse| feature is missing then the result is
9592 an empty dictionary.
9593
9594 If "cursor_style" is 'y' then |t_RS| will be sent to request the
9595 current cursor style.
9596 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
9597 request the cursor blink status.
9598 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
9599 is not empty, Vim will detect the working of sending |t_RS|
9600 and |t_RC| on startup.
9601
9602 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
9603 This avoids sending it to xterm, which would clear the colors.
9604
9605 For "mouse" the value 'u' is unknown
9606
9607 Also see:
9608 - 'ambiwidth' - detected by using |t_u7|.
9609 - |v:termstyleresp| and |v:termblinkresp| for the response to
9610 |t_RS| and |t_RC|.
9611
9612
9613test_ functions are documented here: |test-functions-details|
9614
9615
9616 *timer_info()*
9617timer_info([{id}])
9618 Return a list with information about timers.
9619 When {id} is given only information about this timer is
9620 returned. When timer {id} does not exist an empty list is
9621 returned.
9622 When {id} is omitted information about all timers is returned.
9623
9624 For each timer the information is stored in a |Dictionary| with
9625 these items:
9626 "id" the timer ID
9627 "time" time the timer was started with
9628 "remaining" time until the timer fires
9629 "repeat" number of times the timer will still fire;
9630 -1 means forever
9631 "callback" the callback
9632 "paused" 1 if the timer is paused, 0 otherwise
9633
9634 Can also be used as a |method|: >
9635 GetTimer()->timer_info()
9636
9637< {only available when compiled with the |+timers| feature}
9638
9639timer_pause({timer}, {paused}) *timer_pause()*
9640 Pause or unpause a timer. A paused timer does not invoke its
9641 callback when its time expires. Unpausing a timer may cause
9642 the callback to be invoked almost immediately if enough time
9643 has passed.
9644
9645 Pausing a timer is useful to avoid the callback to be called
9646 for a short time.
9647
9648 If {paused} evaluates to a non-zero Number or a non-empty
9649 String, then the timer is paused, otherwise it is unpaused.
9650 See |non-zero-arg|.
9651
9652 Can also be used as a |method|: >
9653 GetTimer()->timer_pause(1)
9654
9655< {only available when compiled with the |+timers| feature}
9656
9657 *timer_start()* *timer* *timers*
9658timer_start({time}, {callback} [, {options}])
9659 Create a timer and return the timer ID.
9660
9661 {time} is the waiting time in milliseconds. This is the
9662 minimum time before invoking the callback. When the system is
9663 busy or Vim is not waiting for input the time will be longer.
9664
9665 {callback} is the function to call. It can be the name of a
9666 function or a |Funcref|. It is called with one argument, which
9667 is the timer ID. The callback is only invoked when Vim is
9668 waiting for input.
9669 If you want to show a message look at |popup_notification()|
9670 to avoid interfering with what the user is doing.
9671
9672 {options} is a dictionary. Supported entries:
9673 "repeat" Number of times to repeat calling the
9674 callback. -1 means forever. When not present
9675 the callback will be called once.
9676 If the timer causes an error three times in a
9677 row the repeat is cancelled. This avoids that
9678 Vim becomes unusable because of all the error
9679 messages.
9680
Bram Moolenaard592deb2022-06-17 15:42:40 +01009681 Returns -1 on error.
9682
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009683 Example: >
9684 func MyHandler(timer)
9685 echo 'Handler called'
9686 endfunc
9687 let timer = timer_start(500, 'MyHandler',
9688 \ {'repeat': 3})
9689< This will invoke MyHandler() three times at 500 msec
9690 intervals.
9691
9692 Can also be used as a |method|: >
9693 GetMsec()->timer_start(callback)
9694
9695< Not available in the |sandbox|.
9696 {only available when compiled with the |+timers| feature}
9697
9698timer_stop({timer}) *timer_stop()*
9699 Stop a timer. The timer callback will no longer be invoked.
9700 {timer} is an ID returned by timer_start(), thus it must be a
9701 Number. If {timer} does not exist there is no error.
9702
9703 Can also be used as a |method|: >
9704 GetTimer()->timer_stop()
9705
9706< {only available when compiled with the |+timers| feature}
9707
9708timer_stopall() *timer_stopall()*
9709 Stop all timers. The timer callbacks will no longer be
9710 invoked. Useful if a timer is misbehaving. If there are no
9711 timers there is no error.
9712
9713 {only available when compiled with the |+timers| feature}
9714
9715tolower({expr}) *tolower()*
9716 The result is a copy of the String given, with all uppercase
9717 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +01009718 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009719
9720 Can also be used as a |method|: >
9721 GetText()->tolower()
9722
9723toupper({expr}) *toupper()*
9724 The result is a copy of the String given, with all lowercase
9725 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +01009726 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009727
9728 Can also be used as a |method|: >
9729 GetText()->toupper()
9730
9731tr({src}, {fromstr}, {tostr}) *tr()*
9732 The result is a copy of the {src} string with all characters
9733 which appear in {fromstr} replaced by the character in that
9734 position in the {tostr} string. Thus the first character in
9735 {fromstr} is translated into the first character in {tostr}
9736 and so on. Exactly like the unix "tr" command.
9737 This code also deals with multibyte characters properly.
9738
Bram Moolenaard592deb2022-06-17 15:42:40 +01009739 Returns an empty string on error.
9740
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009741 Examples: >
9742 echo tr("hello there", "ht", "HT")
9743< returns "Hello THere" >
9744 echo tr("<blob>", "<>", "{}")
9745< returns "{blob}"
9746
9747 Can also be used as a |method|: >
9748 GetText()->tr(from, to)
9749
9750trim({text} [, {mask} [, {dir}]]) *trim()*
9751 Return {text} as a String where any character in {mask} is
9752 removed from the beginning and/or end of {text}.
9753
9754 If {mask} is not given, {mask} is all characters up to 0x20,
9755 which includes Tab, space, NL and CR, plus the non-breaking
9756 space character 0xa0.
9757
9758 The optional {dir} argument specifies where to remove the
9759 characters:
9760 0 remove from the beginning and end of {text}
9761 1 remove only at the beginning of {text}
9762 2 remove only at the end of {text}
9763 When omitted both ends are trimmed.
9764
9765 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009766 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009767
9768 Examples: >
9769 echo trim(" some text ")
9770< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009771 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009772< returns "RESERVE_TAIL" >
9773 echo trim("rm<Xrm<>X>rrm", "rm<>")
9774< returns "Xrm<>X" (characters in the middle are not removed) >
9775 echo trim(" vim ", " ", 2)
9776< returns " vim"
9777
9778 Can also be used as a |method|: >
9779 GetText()->trim()
9780
9781trunc({expr}) *trunc()*
9782 Return the largest integral value with magnitude less than or
9783 equal to {expr} as a |Float| (truncate towards zero).
9784 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009785 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009786 Examples: >
9787 echo trunc(1.456)
9788< 1.0 >
9789 echo trunc(-5.456)
9790< -5.0 >
9791 echo trunc(4.0)
9792< 4.0
9793
9794 Can also be used as a |method|: >
9795 Compute()->trunc()
9796<
9797 {only available when compiled with the |+float| feature}
9798
9799 *type()*
9800type({expr}) The result is a Number representing the type of {expr}.
9801 Instead of using the number directly, it is better to use the
9802 v:t_ variable that has the value:
9803 Number: 0 |v:t_number|
9804 String: 1 |v:t_string|
9805 Funcref: 2 |v:t_func|
9806 List: 3 |v:t_list|
9807 Dictionary: 4 |v:t_dict|
9808 Float: 5 |v:t_float|
9809 Boolean: 6 |v:t_bool| (v:false and v:true)
9810 None: 7 |v:t_none| (v:null and v:none)
9811 Job: 8 |v:t_job|
9812 Channel: 9 |v:t_channel|
9813 Blob: 10 |v:t_blob|
9814 For backward compatibility, this method can be used: >
9815 :if type(myvar) == type(0)
9816 :if type(myvar) == type("")
9817 :if type(myvar) == type(function("tr"))
9818 :if type(myvar) == type([])
9819 :if type(myvar) == type({})
9820 :if type(myvar) == type(0.0)
9821 :if type(myvar) == type(v:false)
9822 :if type(myvar) == type(v:none)
9823< To check if the v:t_ variables exist use this: >
9824 :if exists('v:t_number')
9825
9826< Can also be used as a |method|: >
9827 mylist->type()
9828
9829
9830typename({expr}) *typename()*
9831 Return a string representation of the type of {expr}.
9832 Example: >
9833 echo typename([1, 2, 3])
9834 list<number>
9835
9836
9837undofile({name}) *undofile()*
9838 Return the name of the undo file that would be used for a file
9839 with name {name} when writing. This uses the 'undodir'
9840 option, finding directories that exist. It does not check if
9841 the undo file exists.
9842 {name} is always expanded to the full path, since that is what
9843 is used internally.
9844 If {name} is empty undofile() returns an empty string, since a
9845 buffer without a file name will not write an undo file.
9846 Useful in combination with |:wundo| and |:rundo|.
9847 When compiled without the |+persistent_undo| option this always
9848 returns an empty string.
9849
9850 Can also be used as a |method|: >
9851 GetFilename()->undofile()
9852
9853undotree() *undotree()*
9854 Return the current state of the undo tree in a dictionary with
9855 the following items:
9856 "seq_last" The highest undo sequence number used.
9857 "seq_cur" The sequence number of the current position in
9858 the undo tree. This differs from "seq_last"
9859 when some changes were undone.
9860 "time_cur" Time last used for |:earlier| and related
9861 commands. Use |strftime()| to convert to
9862 something readable.
9863 "save_last" Number of the last file write. Zero when no
9864 write yet.
9865 "save_cur" Number of the current position in the undo
9866 tree.
9867 "synced" Non-zero when the last undo block was synced.
9868 This happens when waiting from input from the
9869 user. See |undo-blocks|.
9870 "entries" A list of dictionaries with information about
9871 undo blocks.
9872
9873 The first item in the "entries" list is the oldest undo item.
9874 Each List item is a |Dictionary| with these items:
9875 "seq" Undo sequence number. Same as what appears in
9876 |:undolist|.
9877 "time" Timestamp when the change happened. Use
9878 |strftime()| to convert to something readable.
9879 "newhead" Only appears in the item that is the last one
9880 that was added. This marks the last change
9881 and where further changes will be added.
9882 "curhead" Only appears in the item that is the last one
9883 that was undone. This marks the current
9884 position in the undo tree, the block that will
9885 be used by a redo command. When nothing was
9886 undone after the last change this item will
9887 not appear anywhere.
9888 "save" Only appears on the last block before a file
9889 write. The number is the write count. The
9890 first write has number 1, the last one the
9891 "save_last" mentioned above.
9892 "alt" Alternate entry. This is again a List of undo
9893 blocks. Each item may again have an "alt"
9894 item.
9895
9896uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
9897 Remove second and succeeding copies of repeated adjacent
9898 {list} items in-place. Returns {list}. If you want a list
9899 to remain unmodified make a copy first: >
9900 :let newlist = uniq(copy(mylist))
9901< The default compare function uses the string representation of
9902 each item. For the use of {func} and {dict} see |sort()|.
9903
Bram Moolenaard592deb2022-06-17 15:42:40 +01009904 Returns zero if {list} is not a |List|.
9905
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009906 Can also be used as a |method|: >
9907 mylist->uniq()
9908
9909values({dict}) *values()*
9910 Return a |List| with all the values of {dict}. The |List| is
9911 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009912 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009913
9914 Can also be used as a |method|: >
9915 mydict->values()
9916
LemonBoy0f7a3e12022-05-26 12:10:37 +01009917virtcol({expr} [, {list}]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009918 The result is a Number, which is the screen column of the file
9919 position given with {expr}. That is, the last screen position
9920 occupied by the character at that position, when the screen
9921 would be of unlimited width. When there is a <Tab> at the
9922 position, the returned Number will be the column at the end of
9923 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
9924 set to 8, it returns 8. |conceal| is ignored.
9925 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +01009926
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009927 For the use of {expr} see |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +01009928
9929 When 'virtualedit' is used {expr} can be [lnum, col, off],
9930 where "off" is the offset in screen columns from the start of
9931 the character. E.g., a position within a <Tab> or after the
9932 last character. When "off" is omitted zero is used. When
9933 Virtual editing is active in the current mode, a position
9934 beyond the end of the line can be returned. Also see
9935 |'virtualedit'|
9936
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009937 The accepted positions are:
9938 . the cursor position
9939 $ the end of the cursor line (the result is the
9940 number of displayed characters in the cursor line
9941 plus one)
9942 'x position of mark x (if the mark is not set, 0 is
9943 returned)
9944 v In Visual mode: the start of the Visual area (the
9945 cursor is the end). When not in Visual mode
9946 returns the cursor position. Differs from |'<| in
9947 that it's updated right away.
LemonBoy0f7a3e12022-05-26 12:10:37 +01009948
9949 If {list} is present and non-zero then virtcol() returns a List
9950 with the first and last screen position occupied by the
9951 character.
9952
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009953 Note that only marks in the current file can be used.
9954 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +01009955 " With text "foo^Lbar" and cursor on the "^L":
9956
9957 virtcol(".") " returns 5
9958 virtcol(".", 1) " returns [4, 5]
9959 virtcol("$") " returns 9
9960
9961 " With text " there", with 't at 'h':
9962
9963 virtcol("'t") " returns 6
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009964< The first column is 1. 0 is returned for an error.
9965 A more advanced example that echoes the maximum length of
9966 all lines: >
9967 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
9968
9969< Can also be used as a |method|: >
9970 GetPos()->virtcol()
9971
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01009972virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
9973 The result is a Number, which is the byte index of the
9974 character in window {winid} at buffer line {lnum} and virtual
9975 column {col}.
9976
9977 If {col} is greater than the last virtual column in line
9978 {lnum}, then the byte index of the character at the last
9979 virtual column is returned.
9980
9981 The {winid} argument can be the window number or the
9982 |window-ID|. If this is zero, then the current window is used.
9983
9984 Returns -1 if the window {winid} doesn't exist or the buffer
9985 line {lnum} or virtual column {col} is invalid.
9986
9987 See also |screenpos()|, |virtcol()| and |col()|.
9988
9989 Can also be used as a |method|: >
9990 GetWinid()->virtcol2col(lnum, col)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009991
9992visualmode([{expr}]) *visualmode()*
9993 The result is a String, which describes the last Visual mode
9994 used in the current buffer. Initially it returns an empty
9995 string, but once Visual mode has been used, it returns "v",
9996 "V", or "<CTRL-V>" (a single CTRL-V character) for
9997 character-wise, line-wise, or block-wise Visual mode
9998 respectively.
9999 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010000 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010001< This enters the same Visual mode as before. It is also useful
10002 in scripts if you wish to act differently depending on the
10003 Visual mode that was used.
10004 If Visual mode is active, use |mode()| to get the Visual mode
10005 (e.g., in a |:vmap|).
10006 If {expr} is supplied and it evaluates to a non-zero Number or
10007 a non-empty String, then the Visual mode will be cleared and
10008 the old value is returned. See |non-zero-arg|.
10009
10010wildmenumode() *wildmenumode()*
10011 Returns |TRUE| when the wildmenu is active and |FALSE|
10012 otherwise. See 'wildmenu' and 'wildmode'.
10013 This can be used in mappings to handle the 'wildcharm' option
10014 gracefully. (Makes only sense with |mapmode-c| mappings).
10015
10016 For example to make <c-j> work like <down> in wildmode, use: >
10017 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
10018<
10019 (Note, this needs the 'wildcharm' option set appropriately).
10020
10021win_execute({id}, {command} [, {silent}]) *win_execute()*
10022 Like `execute()` but in the context of window {id}.
10023 The window will temporarily be made the current window,
10024 without triggering autocommands or changing directory. When
10025 executing {command} autocommands will be triggered, this may
10026 have unexpected side effects. Use |:noautocmd| if needed.
10027 Example: >
10028 call win_execute(winid, 'set syntax=python')
10029< Doing the same with `setwinvar()` would not trigger
10030 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010031 *E994*
10032 Not all commands are allowed in popup windows.
10033 When window {id} does not exist then no error is given and
10034 an empty string is returned.
10035
10036 Can also be used as a |method|, the base is passed as the
10037 second argument: >
10038 GetCommand()->win_execute(winid)
10039
10040win_findbuf({bufnr}) *win_findbuf()*
10041 Returns a |List| with |window-ID|s for windows that contain
10042 buffer {bufnr}. When there is none the list is empty.
10043
10044 Can also be used as a |method|: >
10045 GetBufnr()->win_findbuf()
10046
10047win_getid([{win} [, {tab}]]) *win_getid()*
10048 Get the |window-ID| for the specified window.
10049 When {win} is missing use the current window.
10050 With {win} this is the window number. The top window has
10051 number 1.
10052 Without {tab} use the current tab, otherwise the tab with
10053 number {tab}. The first tab has number one.
10054 Return zero if the window cannot be found.
10055
10056 Can also be used as a |method|: >
10057 GetWinnr()->win_getid()
10058
10059
10060win_gettype([{nr}]) *win_gettype()*
10061 Return the type of the window:
10062 "autocmd" autocommand window. Temporary window
10063 used to execute autocommands.
10064 "command" command-line window |cmdwin|
10065 (empty) normal window
10066 "loclist" |location-list-window|
10067 "popup" popup window |popup|
10068 "preview" preview window |preview-window|
10069 "quickfix" |quickfix-window|
10070 "unknown" window {nr} not found
10071
10072 When {nr} is omitted return the type of the current window.
10073 When {nr} is given return the type of this window by number or
10074 |window-ID|.
10075
10076 Also see the 'buftype' option. When running a terminal in a
10077 popup window then 'buftype' is "terminal" and win_gettype()
10078 returns "popup".
10079
10080 Can also be used as a |method|: >
10081 GetWinid()->win_gettype()
10082<
10083win_gotoid({expr}) *win_gotoid()*
10084 Go to window with ID {expr}. This may also change the current
10085 tabpage.
10086 Return TRUE if successful, FALSE if the window cannot be found.
10087
10088 Can also be used as a |method|: >
10089 GetWinid()->win_gotoid()
10090
10091win_id2tabwin({expr}) *win_id2tabwin()*
10092 Return a list with the tab number and window number of window
10093 with ID {expr}: [tabnr, winnr].
10094 Return [0, 0] if the window cannot be found.
10095
10096 Can also be used as a |method|: >
10097 GetWinid()->win_id2tabwin()
10098
10099win_id2win({expr}) *win_id2win()*
10100 Return the window number of window with ID {expr}.
10101 Return 0 if the window cannot be found in the current tabpage.
10102
10103 Can also be used as a |method|: >
10104 GetWinid()->win_id2win()
10105
Daniel Steinbergee630312022-01-10 13:36:34 +000010106win_move_separator({nr}, {offset}) *win_move_separator()*
10107 Move window {nr}'s vertical separator (i.e., the right border)
10108 by {offset} columns, as if being dragged by the mouse. {nr}
10109 can be a window number or |window-ID|. A positive {offset}
10110 moves right and a negative {offset} moves left. Moving a
10111 window's vertical separator will change the width of the
10112 window and the width of other windows adjacent to the vertical
10113 separator. The magnitude of movement may be smaller than
10114 specified (e.g., as a consequence of maintaining
10115 'winminwidth'). Returns TRUE if the window can be found and
10116 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010117 This will fail for the rightmost window and a full-width
10118 window, since it has no separator on the right.
Daniel Steinbergee630312022-01-10 13:36:34 +000010119
10120 Can also be used as a |method|: >
10121 GetWinnr()->win_move_separator(offset)
10122
10123win_move_statusline({nr}, {offset}) *win_move_statusline()*
10124 Move window {nr}'s status line (i.e., the bottom border) by
10125 {offset} rows, as if being dragged by the mouse. {nr} can be a
10126 window number or |window-ID|. A positive {offset} moves down
10127 and a negative {offset} moves up. Moving a window's status
10128 line will change the height of the window and the height of
10129 other windows adjacent to the status line. The magnitude of
10130 movement may be smaller than specified (e.g., as a consequence
10131 of maintaining 'winminheight'). Returns TRUE if the window can
10132 be found and FALSE otherwise.
10133
10134 Can also be used as a |method|: >
10135 GetWinnr()->win_move_statusline(offset)
10136
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010137win_screenpos({nr}) *win_screenpos()*
10138 Return the screen position of window {nr} as a list with two
10139 numbers: [row, col]. The first window always has position
10140 [1, 1], unless there is a tabline, then it is [2, 1].
10141 {nr} can be the window number or the |window-ID|. Use zero
10142 for the current window.
10143 Returns [0, 0] if the window cannot be found in the current
10144 tabpage.
10145
10146 Can also be used as a |method|: >
10147 GetWinid()->win_screenpos()
10148<
10149win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
10150 Move the window {nr} to a new split of the window {target}.
10151 This is similar to moving to {target}, creating a new window
10152 using |:split| but having the same contents as window {nr}, and
10153 then closing {nr}.
10154
10155 Both {nr} and {target} can be window numbers or |window-ID|s.
10156 Both must be in the current tab page.
10157
10158 Returns zero for success, non-zero for failure.
10159
10160 {options} is a |Dictionary| with the following optional entries:
10161 "vertical" When TRUE, the split is created vertically,
10162 like with |:vsplit|.
10163 "rightbelow" When TRUE, the split is made below or to the
10164 right (if vertical). When FALSE, it is done
10165 above or to the left (if vertical). When not
10166 present, the values of 'splitbelow' and
10167 'splitright' are used.
10168
10169 Can also be used as a |method|: >
10170 GetWinid()->win_splitmove(target)
10171<
10172
10173 *winbufnr()*
10174winbufnr({nr}) The result is a Number, which is the number of the buffer
10175 associated with window {nr}. {nr} can be the window number or
10176 the |window-ID|.
10177 When {nr} is zero, the number of the buffer in the current
10178 window is returned.
10179 When window {nr} doesn't exist, -1 is returned.
10180 Example: >
10181 :echo "The file in the current window is " . bufname(winbufnr(0))
10182<
10183 Can also be used as a |method|: >
10184 FindWindow()->winbufnr()->bufname()
10185<
10186 *wincol()*
10187wincol() The result is a Number, which is the virtual column of the
10188 cursor in the window. This is counting screen cells from the
10189 left side of the window. The leftmost column is one.
10190
10191 *windowsversion()*
10192windowsversion()
10193 The result is a String. For MS-Windows it indicates the OS
10194 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
10195 Windows XP is "5.1". For non-MS-Windows systems the result is
10196 an empty string.
10197
10198winheight({nr}) *winheight()*
10199 The result is a Number, which is the height of window {nr}.
10200 {nr} can be the window number or the |window-ID|.
10201 When {nr} is zero, the height of the current window is
10202 returned. When window {nr} doesn't exist, -1 is returned.
10203 An existing window always has a height of zero or more.
10204 This excludes any window toolbar line.
10205 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010206 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010207
10208< Can also be used as a |method|: >
10209 GetWinid()->winheight()
10210<
10211winlayout([{tabnr}]) *winlayout()*
10212 The result is a nested List containing the layout of windows
10213 in a tabpage.
10214
10215 Without {tabnr} use the current tabpage, otherwise the tabpage
10216 with number {tabnr}. If the tabpage {tabnr} is not found,
10217 returns an empty list.
10218
10219 For a leaf window, it returns:
10220 ['leaf', {winid}]
10221 For horizontally split windows, which form a column, it
10222 returns:
10223 ['col', [{nested list of windows}]]
10224 For vertically split windows, which form a row, it returns:
10225 ['row', [{nested list of windows}]]
10226
10227 Example: >
10228 " Only one window in the tab page
10229 :echo winlayout()
10230 ['leaf', 1000]
10231 " Two horizontally split windows
10232 :echo winlayout()
10233 ['col', [['leaf', 1000], ['leaf', 1001]]]
10234 " The second tab page, with three horizontally split
10235 " windows, with two vertically split windows in the
10236 " middle window
10237 :echo winlayout(2)
10238 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
10239 ['leaf', 1001]]], ['leaf', 1000]]]
10240<
10241 Can also be used as a |method|: >
10242 GetTabnr()->winlayout()
10243<
10244 *winline()*
10245winline() The result is a Number, which is the screen line of the cursor
10246 in the window. This is counting screen lines from the top of
10247 the window. The first line is one.
10248 If the cursor was moved the view on the file will be updated
10249 first, this may cause a scroll.
10250
10251 *winnr()*
10252winnr([{arg}]) The result is a Number, which is the number of the current
10253 window. The top window has number 1.
10254 Returns zero for a popup window.
10255
10256 The optional argument {arg} supports the following values:
10257 $ the number of the last window (the window
10258 count).
10259 # the number of the last accessed window (where
10260 |CTRL-W_p| goes to). If there is no previous
10261 window or it is in another tab page 0 is
10262 returned.
10263 {N}j the number of the Nth window below the
10264 current window (where |CTRL-W_j| goes to).
10265 {N}k the number of the Nth window above the current
10266 window (where |CTRL-W_k| goes to).
10267 {N}h the number of the Nth window left of the
10268 current window (where |CTRL-W_h| goes to).
10269 {N}l the number of the Nth window right of the
10270 current window (where |CTRL-W_l| goes to).
10271 The number can be used with |CTRL-W_w| and ":wincmd w"
10272 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010010273 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010274 Also see |tabpagewinnr()| and |win_getid()|.
10275 Examples: >
10276 let window_count = winnr('$')
10277 let prev_window = winnr('#')
10278 let wnum = winnr('3k')
10279
10280< Can also be used as a |method|: >
10281 GetWinval()->winnr()
10282<
10283 *winrestcmd()*
10284winrestcmd() Returns a sequence of |:resize| commands that should restore
10285 the current window sizes. Only works properly when no windows
10286 are opened or closed and the current window and tab page is
10287 unchanged.
10288 Example: >
10289 :let cmd = winrestcmd()
10290 :call MessWithWindowSizes()
10291 :exe cmd
10292<
10293 *winrestview()*
10294winrestview({dict})
10295 Uses the |Dictionary| returned by |winsaveview()| to restore
10296 the view of the current window.
10297 Note: The {dict} does not have to contain all values, that are
10298 returned by |winsaveview()|. If values are missing, those
10299 settings won't be restored. So you can use: >
10300 :call winrestview({'curswant': 4})
10301<
10302 This will only set the curswant value (the column the cursor
10303 wants to move on vertical movements) of the cursor to column 5
10304 (yes, that is 5), while all other settings will remain the
10305 same. This is useful, if you set the cursor position manually.
10306
10307 If you have changed the values the result is unpredictable.
10308 If the window size changed the result won't be the same.
10309
10310 Can also be used as a |method|: >
10311 GetView()->winrestview()
10312<
10313 *winsaveview()*
10314winsaveview() Returns a |Dictionary| that contains information to restore
10315 the view of the current window. Use |winrestview()| to
10316 restore the view.
10317 This is useful if you have a mapping that jumps around in the
10318 buffer and you want to go back to the original view.
10319 This does not save fold information. Use the 'foldenable'
10320 option to temporarily switch off folding, so that folds are
10321 not opened when moving around. This may have side effects.
10322 The return value includes:
10323 lnum cursor line number
10324 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000010325 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010326 returns)
10327 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000010328 curswant column for vertical movement (Note:
10329 the first column is zero, as opposed
10330 to what |getcurpos()| returns). After
10331 |$| command it will be a very large
10332 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010333 topline first line in the window
10334 topfill filler lines, only in diff mode
10335 leftcol first column displayed; only used when
10336 'wrap' is off
10337 skipcol columns skipped
10338 Note that no option values are saved.
10339
10340
10341winwidth({nr}) *winwidth()*
10342 The result is a Number, which is the width of window {nr}.
10343 {nr} can be the window number or the |window-ID|.
10344 When {nr} is zero, the width of the current window is
10345 returned. When window {nr} doesn't exist, -1 is returned.
10346 An existing window always has a width of zero or more.
10347 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010348 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010349 :if winwidth(0) <= 50
10350 : 50 wincmd |
10351 :endif
10352< For getting the terminal or screen size, see the 'columns'
10353 option.
10354
10355 Can also be used as a |method|: >
10356 GetWinid()->winwidth()
10357
10358
10359wordcount() *wordcount()*
10360 The result is a dictionary of byte/chars/word statistics for
10361 the current buffer. This is the same info as provided by
10362 |g_CTRL-G|
10363 The return value includes:
10364 bytes Number of bytes in the buffer
10365 chars Number of chars in the buffer
10366 words Number of words in the buffer
10367 cursor_bytes Number of bytes before cursor position
10368 (not in Visual mode)
10369 cursor_chars Number of chars before cursor position
10370 (not in Visual mode)
10371 cursor_words Number of words before cursor position
10372 (not in Visual mode)
10373 visual_bytes Number of bytes visually selected
10374 (only in Visual mode)
10375 visual_chars Number of chars visually selected
10376 (only in Visual mode)
10377 visual_words Number of words visually selected
10378 (only in Visual mode)
10379
10380
10381 *writefile()*
10382writefile({object}, {fname} [, {flags}])
10383 When {object} is a |List| write it to file {fname}. Each list
10384 item is separated with a NL. Each list item must be a String
10385 or Number.
10386 When {flags} contains "b" then binary mode is used: There will
10387 not be a NL after the last list item. An empty item at the
10388 end does cause the last line in the file to end in a NL.
10389
10390 When {object} is a |Blob| write the bytes to file {fname}
10391 unmodified.
10392
10393 When {flags} contains "a" then append mode is used, lines are
10394 appended to the file: >
10395 :call writefile(["foo"], "event.log", "a")
10396 :call writefile(["bar"], "event.log", "a")
10397<
10398 When {flags} contains "s" then fsync() is called after writing
10399 the file. This flushes the file to disk, if possible. This
10400 takes more time but avoids losing the file if the system
10401 crashes.
10402 When {flags} does not contain "S" or "s" then fsync() is
10403 called if the 'fsync' option is set.
10404 When {flags} contains "S" then fsync() is not called, even
10405 when 'fsync' is set.
10406
10407 All NL characters are replaced with a NUL character.
10408 Inserting CR characters needs to be done before passing {list}
10409 to writefile().
10410 An existing file is overwritten, if possible.
10411 When the write fails -1 is returned, otherwise 0. There is an
10412 error message if the file can't be created or when writing
10413 fails.
10414 Also see |readfile()|.
10415 To copy a file byte for byte: >
10416 :let fl = readfile("foo", "b")
10417 :call writefile(fl, "foocopy", "b")
10418
10419< Can also be used as a |method|: >
10420 GetText()->writefile("thefile")
10421
10422
10423xor({expr}, {expr}) *xor()*
10424 Bitwise XOR on the two arguments. The arguments are converted
10425 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010426 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010427 Example: >
10428 :let bits = xor(bits, 0x80)
10429<
10430 Can also be used as a |method|: >
10431 :let bits = bits->xor(0x80)
10432<
10433
10434==============================================================================
104353. Feature list *feature-list*
10436
10437There are three types of features:
104381. Features that are only supported when they have been enabled when Vim
10439 was compiled |+feature-list|. Example: >
10440 :if has("cindent")
10441< *gui_running*
104422. Features that are only supported when certain conditions have been met.
10443 Example: >
10444 :if has("gui_running")
10445< *has-patch*
104463. Beyond a certain version or at a certain version and including a specific
10447 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
10448 later, or it is version 7.4 and patch 248 was included. Example: >
10449 :if has("patch-7.4.248")
10450< Note that it's possible for patch 248 to be omitted even though 249 is
10451 included. Only happens when cherry-picking patches.
10452 Note that this form only works for patch 7.4.237 and later, before that
10453 you need to check for the patch and the v:version. Example (checking
10454 version 6.2.148 or later): >
10455 :if v:version > 602 || (v:version == 602 && has("patch148"))
10456
10457Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
10458use: `if exists('+shellslash')`
10459
10460
10461acl Compiled with |ACL| support.
10462all_builtin_terms Compiled with all builtin terminals enabled.
10463amiga Amiga version of Vim.
10464arabic Compiled with Arabic support |Arabic|.
10465arp Compiled with ARP support (Amiga).
10466autocmd Compiled with autocommand support. (always true)
10467autochdir Compiled with support for 'autochdir'
10468autoservername Automatically enable |clientserver|
10469balloon_eval Compiled with |balloon-eval| support.
10470balloon_multiline GUI supports multiline balloons.
10471beos BeOS version of Vim.
10472browse Compiled with |:browse| support, and browse() will
10473 work.
10474browsefilter Compiled with support for |browsefilter|.
10475bsd Compiled on an OS in the BSD family (excluding macOS).
10476builtin_terms Compiled with some builtin terminals.
10477byte_offset Compiled with support for 'o' in 'statusline'
10478channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010479cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010480clientserver Compiled with remote invocation support |clientserver|.
10481clipboard Compiled with 'clipboard' support.
10482clipboard_working Compiled with 'clipboard' support and it can be used.
10483cmdline_compl Compiled with |cmdline-completion| support.
10484cmdline_hist Compiled with |cmdline-history| support.
10485cmdline_info Compiled with 'showcmd' and 'ruler' support.
10486comments Compiled with |'comments'| support.
10487compatible Compiled to be very Vi compatible.
10488conpty Platform where |ConPTY| can be used.
10489cryptv Compiled with encryption support |encryption|.
10490cscope Compiled with |cscope| support.
10491cursorbind Compiled with |'cursorbind'| (always true)
10492debug Compiled with "DEBUG" defined.
10493dialog_con Compiled with console dialog support.
10494dialog_gui Compiled with GUI dialog support.
10495diff Compiled with |vimdiff| and 'diff' support.
10496digraphs Compiled with support for digraphs.
10497directx Compiled with support for DirectX and 'renderoptions'.
10498dnd Compiled with support for the "~ register |quote_~|.
10499drop_file Compiled with |drop_file| support.
10500ebcdic Compiled on a machine with ebcdic character set.
10501emacs_tags Compiled with support for Emacs tags.
10502eval Compiled with expression evaluation support. Always
10503 true, of course!
10504ex_extra |+ex_extra| (always true)
10505extra_search Compiled with support for |'incsearch'| and
10506 |'hlsearch'|
10507farsi Support for Farsi was removed |farsi|.
10508file_in_path Compiled with support for |gf| and |<cfile>|
10509filterpipe When 'shelltemp' is off pipes are used for shell
10510 read/write/filter commands
10511find_in_path Compiled with support for include file searches
10512 |+find_in_path|.
10513float Compiled with support for |Float|.
10514fname_case Case in file names matters (for Amiga and MS-Windows
10515 this is not present).
10516folding Compiled with |folding| support.
10517footer Compiled with GUI footer support. |gui-footer|
10518fork Compiled to use fork()/exec() instead of system().
10519gettext Compiled with message translation |multi-lang|
10520gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010010521gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010522gui_gnome Compiled with Gnome support (gui_gtk is also defined).
10523gui_gtk Compiled with GTK+ GUI (any version).
10524gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
10525gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
10526gui_haiku Compiled with Haiku GUI.
10527gui_mac Compiled with Macintosh GUI.
10528gui_motif Compiled with Motif GUI.
10529gui_photon Compiled with Photon GUI.
10530gui_running Vim is running in the GUI, or it will start soon.
10531gui_win32 Compiled with MS-Windows Win32 GUI.
10532gui_win32s idem, and Win32s system being used (Windows 3.1)
10533haiku Haiku version of Vim.
10534hangul_input Compiled with Hangul input support. |hangul|
10535hpux HP-UX version of Vim.
10536iconv Can use iconv() for conversion.
10537insert_expand Compiled with support for CTRL-X expansion commands in
10538 Insert mode. (always true)
10539job Compiled with support for |channel| and |job|
10540ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010541jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010542keymap Compiled with 'keymap' support.
10543lambda Compiled with |lambda| support.
10544langmap Compiled with 'langmap' support.
10545libcall Compiled with |libcall()| support.
10546linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
10547 'breakindent' support.
10548linux Linux version of Vim.
10549lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010550 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010551listcmds Compiled with commands for the buffer list |:files|
10552 and the argument list |arglist|.
10553localmap Compiled with local mappings and abbr. |:map-local|
10554lua Compiled with Lua interface |Lua|.
10555mac Any Macintosh version of Vim cf. osx
10556macunix Synonym for osxdarwin
10557menu Compiled with support for |:menu|.
10558mksession Compiled with support for |:mksession|.
10559modify_fname Compiled with file name modifiers. |filename-modifiers|
10560 (always true)
10561mouse Compiled with support for mouse.
10562mouse_dec Compiled with support for Dec terminal mouse.
10563mouse_gpm Compiled with support for gpm (Linux console mouse)
10564mouse_gpm_enabled GPM mouse is working
10565mouse_netterm Compiled with support for netterm mouse.
10566mouse_pterm Compiled with support for qnx pterm mouse.
10567mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
10568mouse_sgr Compiled with support for sgr mouse.
10569mouse_urxvt Compiled with support for urxvt mouse.
10570mouse_xterm Compiled with support for xterm mouse.
10571mouseshape Compiled with support for 'mouseshape'.
10572multi_byte Compiled with support for 'encoding' (always true)
10573multi_byte_encoding 'encoding' is set to a multibyte encoding.
10574multi_byte_ime Compiled with support for IME input method.
10575multi_lang Compiled with support for multiple languages.
10576mzscheme Compiled with MzScheme interface |mzscheme|.
10577nanotime Compiled with sub-second time stamp checks.
10578netbeans_enabled Compiled with support for |netbeans| and connected.
10579netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010580num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010581ole Compiled with OLE automation support for Win32.
10582osx Compiled for macOS cf. mac
10583osxdarwin Compiled for macOS, with |mac-darwin-feature|
10584packages Compiled with |packages| support.
10585path_extra Compiled with up/downwards search in 'path' and 'tags'
10586perl Compiled with Perl interface.
10587persistent_undo Compiled with support for persistent undo history.
10588postscript Compiled with PostScript file printing.
10589printer Compiled with |:hardcopy| support.
10590profile Compiled with |:profile| support.
10591python Python 2.x interface available. |has-python|
10592python_compiled Compiled with Python 2.x interface. |has-python|
10593python_dynamic Python 2.x interface is dynamically loaded. |has-python|
10594python3 Python 3.x interface available. |has-python|
10595python3_compiled Compiled with Python 3.x interface. |has-python|
10596python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
10597pythonx Python 2.x and/or 3.x interface available. |python_x|
10598qnx QNX version of Vim.
10599quickfix Compiled with |quickfix| support.
10600reltime Compiled with |reltime()| support.
10601rightleft Compiled with 'rightleft' support.
10602ruby Compiled with Ruby interface |ruby|.
10603scrollbind Compiled with 'scrollbind' support. (always true)
10604showcmd Compiled with 'showcmd' support.
10605signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010606smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010607sodium Compiled with libsodium for better crypt support
10608sound Compiled with sound support, e.g. `sound_playevent()`
10609spell Compiled with spell checking support |spell|.
10610startuptime Compiled with |--startuptime| support.
10611statusline Compiled with support for 'statusline', 'rulerformat'
10612 and special formats of 'titlestring' and 'iconstring'.
10613sun SunOS version of Vim.
10614sun_workshop Support for Sun |workshop| has been removed.
10615syntax Compiled with syntax highlighting support |syntax|.
10616syntax_items There are active syntax highlighting items for the
10617 current buffer.
10618system Compiled to use system() instead of fork()/exec().
10619tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010620 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010621tag_old_static Support for old static tags was removed, see
10622 |tag-old-static|.
10623tcl Compiled with Tcl interface.
10624termguicolors Compiled with true color in terminal support.
10625terminal Compiled with |terminal| support.
10626terminfo Compiled with terminfo instead of termcap.
10627termresponse Compiled with support for |t_RV| and |v:termresponse|.
10628textobjects Compiled with support for |text-objects|.
10629textprop Compiled with support for |text-properties|.
10630tgetent Compiled with tgetent support, able to use a termcap
10631 or terminfo file.
10632timers Compiled with |timer_start()| support.
10633title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010634 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010635toolbar Compiled with support for |gui-toolbar|.
10636ttyin input is a terminal (tty)
10637ttyout output is a terminal (tty)
10638unix Unix version of Vim. *+unix*
10639unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
10640user_commands User-defined commands. (always true)
10641vartabs Compiled with variable tabstop support |'vartabstop'|.
10642vcon Win32: Virtual console support is working, can use
10643 'termguicolors'. Also see |+vtp|.
10644vertsplit Compiled with vertically split windows |:vsplit|.
10645 (always true)
10646vim_starting True while initial source'ing takes place. |startup|
10647 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000010648vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010649viminfo Compiled with viminfo support.
10650vimscript-1 Compiled Vim script version 1 support
10651vimscript-2 Compiled Vim script version 2 support
10652vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010010653vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010654virtualedit Compiled with 'virtualedit' option. (always true)
10655visual Compiled with Visual mode. (always true)
10656visualextra Compiled with extra Visual mode commands. (always
10657 true) |blockwise-operators|.
10658vms VMS version of Vim.
10659vreplace Compiled with |gR| and |gr| commands. (always true)
10660vtp Compiled for vcon support |+vtp| (check vcon to find
10661 out if it works in the current console).
10662wildignore Compiled with 'wildignore' option.
10663wildmenu Compiled with 'wildmenu' option.
10664win16 old version for MS-Windows 3.1 (always false)
10665win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
10666 64 bits)
10667win32unix Win32 version of Vim, using Unix files (Cygwin)
10668win64 Win64 version of Vim (MS-Windows 64 bit).
10669win95 Win32 version for MS-Windows 95/98/ME (always false)
10670winaltkeys Compiled with 'winaltkeys' option.
10671windows Compiled with support for more than one window.
10672 (always true)
10673writebackup Compiled with 'writebackup' default on.
10674xfontset Compiled with X fontset support |xfontset|.
10675xim Compiled with X input method support |xim|.
10676xpm Compiled with pixmap support.
10677xpm_w32 Compiled with pixmap support for Win32. (Only for
10678 backward compatibility. Use "xpm" instead.)
10679xsmp Compiled with X session management support.
10680xsmp_interact Compiled with interactive X session management support.
10681xterm_clipboard Compiled with support for xterm clipboard.
10682xterm_save Compiled with support for saving and restoring the
10683 xterm screen.
10684x11 Compiled with X11 support.
10685
10686
10687==============================================================================
106884. Matching a pattern in a String *string-match*
10689
10690This is common between several functions. A regexp pattern as explained at
10691|pattern| is normally used to find a match in the buffer lines. When a
10692pattern is used to find a match in a String, almost everything works in the
10693same way. The difference is that a String is handled like it is one line.
10694When it contains a "\n" character, this is not seen as a line break for the
10695pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
10696>
10697 :let a = "aaaa\nxxxx"
10698 :echo matchstr(a, "..\n..")
10699 aa
10700 xx
10701 :echo matchstr(a, "a.x")
10702 a
10703 x
10704
10705Don't forget that "^" will only match at the first character of the String and
10706"$" at the last character of the string. They don't match after or before a
10707"\n".
10708
10709 vim:tw=78:ts=8:noet:ft=help:norl: