blob: b9dd4d20bf4e1d93901f1cf126c6f965a2e5af29 [file] [log] [blame]
zeertzjqc95e64f2024-05-20 14:00:31 +02001*builtin.txt* For Vim version 9.1. Last change: 2024 May 20
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Builtin functions *builtin-functions*
8
Bram Moolenaarf269eab2022-10-03 18:04:35 +01009Note: Expression evaluation can be disabled at compile time, the builtin
10functions are not available then. See |+eval| and |no-eval-feature|.
11
12For functions grouped by what they are used for see |function-list|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013
141. Overview |builtin-function-list|
152. Details |builtin-function-details|
163. Feature list |feature-list|
174. Matching a pattern in a String |string-match|
18
19==============================================================================
201. Overview *builtin-function-list*
21
22Use CTRL-] on the function name to jump to the full explanation.
23
24USAGE RESULT DESCRIPTION ~
25
26abs({expr}) Float or Number absolute value of {expr}
27acos({expr}) Float arc cosine of {expr}
28add({object}, {item}) List/Blob append {item} to {object}
29and({expr}, {expr}) Number bitwise AND
30append({lnum}, {text}) Number append {text} below line {lnum}
31appendbufline({expr}, {lnum}, {text})
32 Number append {text} below line {lnum}
33 in buffer {expr}
34argc([{winid}]) Number number of files in the argument list
35argidx() Number current index in the argument list
36arglistid([{winnr} [, {tabnr}]]) Number argument list id
37argv({nr} [, {winid}]) String {nr} entry of the argument list
38argv([-1, {winid}]) List the argument list
39asin({expr}) Float arc sine of {expr}
40assert_beeps({cmd}) Number assert {cmd} causes a beep
41assert_equal({exp}, {act} [, {msg}])
42 Number assert {exp} is equal to {act}
43assert_equalfile({fname-one}, {fname-two} [, {msg}])
44 Number assert file contents are equal
45assert_exception({error} [, {msg}])
46 Number assert {error} is in v:exception
47assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])
48 Number assert {cmd} fails
49assert_false({actual} [, {msg}])
50 Number assert {actual} is false
51assert_inrange({lower}, {upper}, {actual} [, {msg}])
52 Number assert {actual} is inside the range
53assert_match({pat}, {text} [, {msg}])
54 Number assert {pat} matches {text}
55assert_nobeep({cmd}) Number assert {cmd} does not cause a beep
56assert_notequal({exp}, {act} [, {msg}])
57 Number assert {exp} is not equal {act}
58assert_notmatch({pat}, {text} [, {msg}])
59 Number assert {pat} not matches {text}
60assert_report({msg}) Number report a test failure
61assert_true({actual} [, {msg}]) Number assert {actual} is true
62atan({expr}) Float arc tangent of {expr}
63atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +010064autocmd_add({acmds}) Bool add a list of autocmds and groups
65autocmd_delete({acmds}) Bool delete a list of autocmds and groups
66autocmd_get([{opts}]) List return a list of autocmds
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000067balloon_gettext() String current text in the balloon
68balloon_show({expr}) none show {expr} inside the balloon
69balloon_split({msg}) List split {msg} as used for a balloon
70blob2list({blob}) List convert {blob} into a list of numbers
71browse({save}, {title}, {initdir}, {default})
72 String put up a file requester
73browsedir({title}, {initdir}) String put up a directory requester
74bufadd({name}) Number add a buffer to the buffer list
75bufexists({buf}) Number |TRUE| if buffer {buf} exists
76buflisted({buf}) Number |TRUE| if buffer {buf} is listed
77bufload({buf}) Number load buffer {buf} if not loaded yet
78bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
79bufname([{buf}]) String Name of the buffer {buf}
80bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
81bufwinid({buf}) Number window ID of buffer {buf}
82bufwinnr({buf}) Number window number of buffer {buf}
83byte2line({byte}) Number line number at byte count {byte}
Christian Brabandt67672ef2023-04-24 21:09:54 +010084byteidx({expr}, {nr} [, {utf16}])
85 Number byte index of {nr}'th char in {expr}
86byteidxcomp({expr}, {nr} [, {utf16}])
87 Number byte index of {nr}'th char in {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000088call({func}, {arglist} [, {dict}])
89 any call {func} with arguments {arglist}
90ceil({expr}) Float round {expr} up
91ch_canread({handle}) Number check if there is something to read
92ch_close({handle}) none close {handle}
93ch_close_in({handle}) none close in part of {handle}
94ch_evalexpr({handle}, {expr} [, {options}])
95 any evaluate {expr} on JSON {handle}
96ch_evalraw({handle}, {string} [, {options}])
97 any evaluate {string} on raw {handle}
98ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
99ch_getjob({channel}) Job get the Job of {channel}
100ch_info({handle}) String info about channel {handle}
101ch_log({msg} [, {handle}]) none write {msg} in the channel log file
102ch_logfile({fname} [, {mode}]) none start logging channel activity
103ch_open({address} [, {options}])
104 Channel open a channel to {address}
105ch_read({handle} [, {options}]) String read from {handle}
106ch_readblob({handle} [, {options}])
107 Blob read Blob from {handle}
108ch_readraw({handle} [, {options}])
109 String read raw from {handle}
110ch_sendexpr({handle}, {expr} [, {options}])
111 any send {expr} over JSON {handle}
112ch_sendraw({handle}, {expr} [, {options}])
113 any send {expr} over raw {handle}
114ch_setoptions({handle}, {options})
115 none set options for {handle}
116ch_status({handle} [, {options}])
117 String status of channel {handle}
118changenr() Number current change number
119char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
120charclass({string}) Number character class of {string}
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000121charcol({expr} [, {winid}]) Number column number of cursor or mark
Christian Brabandt67672ef2023-04-24 21:09:54 +0100122charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000123 Number char index of byte {idx} in {string}
124chdir({dir}) String change current working directory
125cindent({lnum}) Number C indent for line {lnum}
126clearmatches([{win}]) none clear all matches
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000127col({expr} [, {winid}]) Number column byte index of cursor or mark
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000128complete({startcol}, {matches}) none set Insert mode completion
129complete_add({expr}) Number add completion match
130complete_check() Number check for key typed during completion
131complete_info([{what}]) Dict get current completion information
132confirm({msg} [, {choices} [, {default} [, {type}]]])
133 Number number of choice picked by user
134copy({expr}) any make a shallow copy of {expr}
135cos({expr}) Float cosine of {expr}
136cosh({expr}) Float hyperbolic cosine of {expr}
137count({comp}, {expr} [, {ic} [, {start}]])
138 Number count how many {expr} are in {comp}
139cscope_connection([{num}, {dbpath} [, {prepend}]])
140 Number checks existence of cscope connection
141cursor({lnum}, {col} [, {off}])
142 Number move cursor to {lnum}, {col}, {off}
143cursor({list}) Number move cursor to position in {list}
144debugbreak({pid}) Number interrupt process being debugged
145deepcopy({expr} [, {noref}]) any make a full copy of {expr}
146delete({fname} [, {flags}]) Number delete the file or directory {fname}
147deletebufline({buf}, {first} [, {last}])
148 Number delete lines from buffer {buf}
149did_filetype() Number |TRUE| if FileType autocmd event used
Yegappan Lakshmananfa378352024-02-01 22:05:27 +0100150diff({fromlist}, {tolist} [, {options}])
151 List diff two Lists of strings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000152diff_filler({lnum}) Number diff filler lines about {lnum}
153diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
154digraph_get({chars}) String get the |digraph| of {chars}
155digraph_getlist([{listall}]) List get all |digraph|s
156digraph_set({chars}, {digraph}) Boolean register |digraph|
157digraph_setlist({digraphlist}) Boolean register multiple |digraph|s
158echoraw({expr}) none output {expr} as-is
159empty({expr}) Number |TRUE| if {expr} is empty
160environ() Dict return environment variables
Sean Dewarb0efa492023-07-08 10:35:19 +0100161err_teapot([{expr}]) none give E418, or E503 if {expr} is |TRUE|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000162escape({string}, {chars}) String escape {chars} in {string} with '\'
163eval({string}) any evaluate {string} into its value
164eventhandler() Number |TRUE| if inside an event handler
165executable({expr}) Number 1 if executable {expr} exists
166execute({command}) String execute {command} and get the output
167exepath({expr}) String full path of the command {expr}
168exists({expr}) Number |TRUE| if {expr} exists
169exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
170exp({expr}) Float exponential of {expr}
171expand({expr} [, {nosuf} [, {list}]])
172 any expand special keywords in {expr}
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +0100173expandcmd({string} [, {options}])
174 String expand {string} like with `:edit`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000175extend({expr1}, {expr2} [, {expr3}])
176 List/Dict insert items of {expr2} into {expr1}
177extendnew({expr1}, {expr2} [, {expr3}])
178 List/Dict like |extend()| but creates a new
179 List or Dictionary
180feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
181filereadable({file}) Number |TRUE| if {file} is a readable file
182filewritable({file}) Number |TRUE| if {file} is a writable file
183filter({expr1}, {expr2}) List/Dict/Blob/String
184 remove items from {expr1} where
185 {expr2} is 0
186finddir({name} [, {path} [, {count}]])
187 String find directory {name} in {path}
188findfile({name} [, {path} [, {count}]])
189 String find file {name} in {path}
190flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
191flattennew({list} [, {maxdepth}])
192 List flatten a copy of {list}
193float2nr({expr}) Number convert Float {expr} to a Number
194floor({expr}) Float round {expr} down
195fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
196fnameescape({fname}) String escape special characters in {fname}
197fnamemodify({fname}, {mods}) String modify file name
198foldclosed({lnum}) Number first line of fold at {lnum} if closed
199foldclosedend({lnum}) Number last line of fold at {lnum} if closed
200foldlevel({lnum}) Number fold level at {lnum}
201foldtext() String line displayed for closed fold
202foldtextresult({lnum}) String text for closed fold at {lnum}
Ernie Raele79e2072024-01-13 11:47:33 +0100203foreach({expr1}, {expr2}) List/Dict/Blob/String
204 for each item in {expr1} call {expr2}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000205foreground() Number bring the Vim window to the foreground
Bram Moolenaaraa534142022-09-15 21:46:02 +0100206fullcommand({name} [, {vim9}]) String get full command from {name}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000207funcref({name} [, {arglist}] [, {dict}])
208 Funcref reference to function {name}
209function({name} [, {arglist}] [, {dict}])
210 Funcref named reference to function {name}
211garbagecollect([{atexit}]) none free memory, breaking cyclic references
212get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
213get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
214get({func}, {what}) any get property of funcref/partial {func}
215getbufinfo([{buf}]) List information about buffers
216getbufline({buf}, {lnum} [, {end}])
217 List lines {lnum} to {end} of buffer {buf}
Bram Moolenaarce30ccc2022-11-21 19:57:04 +0000218getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000219getbufvar({buf}, {varname} [, {def}])
220 any variable {varname} in buffer {buf}
Kota Kato66bb9ae2023-01-17 18:31:56 +0000221getcellwidths() List get character cell width overrides
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000222getchangelist([{buf}]) List list of change list items
Doug Kearns9cd9e752024-04-07 17:42:17 +0200223getchar([{expr}]) Number or String
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000224 get one character from the user
225getcharmod() Number modifiers for the last typed character
226getcharpos({expr}) List position of cursor, mark, etc.
227getcharsearch() Dict last character search
Doug Kearns9cd9e752024-04-07 17:42:17 +0200228getcharstr([{expr}]) String get one character from the user
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100229getcmdcompltype() String return the type of the current
230 command-line completion
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000231getcmdline() String return the current command-line
232getcmdpos() Number return cursor position in command-line
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100233getcmdscreenpos() Number return cursor screen position in
234 command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000235getcmdtype() String return current command-line type
236getcmdwintype() String return current command-line window type
237getcompletion({pat}, {type} [, {filtered}])
238 List list of cmdline completion matches
239getcurpos([{winnr}]) List position of the cursor
240getcursorcharpos([{winnr}]) List character position of the cursor
241getcwd([{winnr} [, {tabnr}]]) String get the current working directory
242getenv({name}) String return environment variable
243getfontname([{name}]) String name of font being used
244getfperm({fname}) String file permissions of file {fname}
245getfsize({fname}) Number size in bytes of file {fname}
246getftime({fname}) Number last modification time of file
247getftype({fname}) String description of type of file {fname}
248getimstatus() Number |TRUE| if the IME status is active
249getjumplist([{winnr} [, {tabnr}]])
250 List list of jump list items
251getline({lnum}) String line {lnum} of current buffer
252getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
253getloclist({nr}) List list of location list items
254getloclist({nr}, {what}) Dict get specific location list properties
255getmarklist([{buf}]) List list of global/local marks
256getmatches([{win}]) List list of current matches
257getmousepos() Dict last known mouse position
Bram Moolenaar24dc19c2022-11-14 19:49:15 +0000258getmouseshape() String current mouse shape name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000259getpid() Number process ID of Vim
260getpos({expr}) List position of cursor, mark, etc.
261getqflist() List list of quickfix items
262getqflist({what}) Dict get specific quickfix list properties
263getreg([{regname} [, 1 [, {list}]]])
264 String or List contents of a register
265getreginfo([{regname}]) Dict information about a register
Shougo Matsushita19b71882024-02-28 22:48:12 +0100266getregion({pos1}, {pos2} [, {opts}])
Shougo Matsushita3f905ab2024-02-21 00:02:45 +0100267 List get the text from {pos1} to {pos2}
Shougo Matsushitab4757e62024-05-07 20:49:24 +0200268getregionpos({pos1}, {pos2} [, {opts}])
269 List get a list of positions for a region
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000270getregtype([{regname}]) String type of a register
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +0100271getscriptinfo([{opts}]) List list of sourced scripts
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000272gettabinfo([{expr}]) List list of tab pages
273gettabvar({nr}, {varname} [, {def}])
274 any variable {varname} in tab {nr} or {def}
275gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
276 any {name} in {winnr} in tab page {tabnr}
277gettagstack([{nr}]) Dict get the tag stack of window {nr}
278gettext({text}) String lookup translation of {text}
279getwininfo([{winid}]) List list of info about each window
Bram Moolenaar938ae282023-02-20 20:44:55 +0000280getwinpos([{timeout}]) List X and Y coord in pixels of Vim window
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000281getwinposx() Number X coord in pixels of the Vim window
282getwinposy() Number Y coord in pixels of the Vim window
283getwinvar({nr}, {varname} [, {def}])
284 any variable {varname} in window {nr}
285glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
286 any expand file wildcards in {expr}
287glob2regpat({expr}) String convert a glob pat into a search pat
288globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
289 String do glob({expr}) for all dirs in {path}
290has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
291has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
292haslocaldir([{winnr} [, {tabnr}]])
293 Number |TRUE| if the window executed |:lcd|
294 or |:tcd|
295hasmapto({what} [, {mode} [, {abbr}]])
296 Number |TRUE| if mapping to {what} exists
297histadd({history}, {item}) Number add an item to a history
298histdel({history} [, {item}]) Number remove an item from a history
299histget({history} [, {index}]) String get the item {index} from a history
300histnr({history}) Number highest index of a history
301hlID({name}) Number syntax ID of highlight group {name}
302hlexists({name}) Number |TRUE| if highlight group {name} exists
303hlget([{name} [, {resolve}]]) List get highlight group attributes
304hlset({list}) Number set highlight group attributes
305hostname() String name of the machine Vim is running on
306iconv({expr}, {from}, {to}) String convert encoding of {expr}
307indent({lnum}) Number indent of line {lnum}
308index({object}, {expr} [, {start} [, {ic}]])
309 Number index in {object} where {expr} appears
Yegappan Lakshmananb2186552022-08-13 13:09:20 +0100310indexof({object}, {expr} [, {opts}]])
311 Number index in {object} where {expr} is true
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000312input({prompt} [, {text} [, {completion}]])
313 String get input from the user
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100314inputdialog({prompt} [, {text} [, {cancelreturn}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000315 String like input() but in a GUI dialog
316inputlist({textlist}) Number let the user pick from a choice list
317inputrestore() Number restore typeahead
318inputsave() Number save and clear typeahead
319inputsecret({prompt} [, {text}]) String like input() but hiding the text
320insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
LemonBoyafe04662023-08-23 21:08:11 +0200321instanceof({object}, {class}) Number |TRUE| if {object} is an instance of {class}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000322interrupt() none interrupt script execution
323invert({expr}) Number bitwise invert
LemonBoydca1d402022-04-28 15:26:33 +0100324isabsolutepath({path}) Number |TRUE| if {path} is an absolute path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000325isdirectory({directory}) Number |TRUE| if {directory} is a directory
326isinf({expr}) Number determine if {expr} is infinity value
327 (positive or negative)
328islocked({expr}) Number |TRUE| if {expr} is locked
329isnan({expr}) Number |TRUE| if {expr} is NaN
330items({dict}) List key-value pairs in {dict}
331job_getchannel({job}) Channel get the channel handle for {job}
332job_info([{job}]) Dict get information about {job}
333job_setoptions({job}, {options}) none set options for {job}
334job_start({command} [, {options}])
335 Job start a job
336job_status({job}) String get the status of {job}
337job_stop({job} [, {how}]) Number stop {job}
338join({list} [, {sep}]) String join {list} items into one String
339js_decode({string}) any decode JS style JSON
340js_encode({expr}) String encode JS style JSON
341json_decode({string}) any decode JSON
342json_encode({expr}) String encode JSON
343keys({dict}) List keys in {dict}
zeertzjqcdc83932022-09-12 13:38:41 +0100344keytrans({string}) String translate internal keycodes to a form
345 that can be used by |:map|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000346len({expr}) Number the length of {expr}
347libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
348libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
349line({expr} [, {winid}]) Number line nr of cursor, last line or mark
350line2byte({lnum}) Number byte count of line {lnum}
351lispindent({lnum}) Number Lisp indent for line {lnum}
352list2blob({list}) Blob turn {list} of numbers into a Blob
353list2str({list} [, {utf8}]) String turn {list} of numbers into a String
354listener_add({callback} [, {buf}])
355 Number add a callback to listen to changes
356listener_flush([{buf}]) none invoke listener callbacks
357listener_remove({id}) none remove a listener callback
358localtime() Number current time
359log({expr}) Float natural logarithm (base e) of {expr}
360log10({expr}) Float logarithm of Float {expr} to base 10
361luaeval({expr} [, {expr}]) any evaluate |Lua| expression
362map({expr1}, {expr2}) List/Dict/Blob/String
363 change each item in {expr1} to {expr2}
364maparg({name} [, {mode} [, {abbr} [, {dict}]]])
365 String or Dict
366 rhs of mapping {name} in mode {mode}
367mapcheck({name} [, {mode} [, {abbr}]])
368 String check for mappings matching {name}
Ernie Rael09661202022-04-25 14:40:44 +0100369maplist([{abbr}]) List list of all mappings, a dict for each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000370mapnew({expr1}, {expr2}) List/Dict/Blob/String
371 like |map()| but creates a new List or
372 Dictionary
373mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
374match({expr}, {pat} [, {start} [, {count}]])
375 Number position where {pat} matches in {expr}
376matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
377 Number highlight {pattern} with {group}
378matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
379 Number highlight positions with {group}
380matcharg({nr}) List arguments of |:match|
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100381matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict})
382 List all the {pat} matches in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000383matchdelete({id} [, {win}]) Number delete match identified by {id}
384matchend({expr}, {pat} [, {start} [, {count}]])
385 Number position where {pat} ends in {expr}
386matchfuzzy({list}, {str} [, {dict}])
387 List fuzzy match {str} in {list}
388matchfuzzypos({list}, {str} [, {dict}])
389 List fuzzy match {str} in {list}
390matchlist({expr}, {pat} [, {start} [, {count}]])
391 List match and submatches of {pat} in {expr}
392matchstr({expr}, {pat} [, {start} [, {count}]])
393 String {count}'th match of {pat} in {expr}
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100394matchstrlist({list}, {pat} [, {dict})
395 List all the {pat} matches in {list}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000396matchstrpos({expr}, {pat} [, {start} [, {count}]])
397 List {count}'th match of {pat} in {expr}
398max({expr}) Number maximum value of items in {expr}
399menu_info({name} [, {mode}]) Dict get menu item information
400min({expr}) Number minimum value of items in {expr}
Bram Moolenaar938ae282023-02-20 20:44:55 +0000401mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000402 Number create directory {name}
Doug Kearns9cd9e752024-04-07 17:42:17 +0200403mode([{expr}]) String current editing mode
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000404mzeval({expr}) any evaluate |MzScheme| expression
405nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
406nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
407or({expr}, {expr}) Number bitwise OR
408pathshorten({expr} [, {len}]) String shorten directory names in a path
409perleval({expr}) any evaluate |Perl| expression
410popup_atcursor({what}, {options}) Number create popup window near the cursor
411popup_beval({what}, {options}) Number create popup window for 'ballooneval'
412popup_clear() none close all popup windows
413popup_close({id} [, {result}]) none close popup window {id}
414popup_create({what}, {options}) Number create a popup window
415popup_dialog({what}, {options}) Number create a popup window used as a dialog
416popup_filter_menu({id}, {key}) Number filter for a menu popup window
417popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
Bram Moolenaarbdc09a12022-10-07 14:31:45 +0100418popup_findecho() Number get window ID of popup for `:echowin`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000419popup_findinfo() Number get window ID of info popup window
420popup_findpreview() Number get window ID of preview popup window
421popup_getoptions({id}) Dict get options of popup window {id}
422popup_getpos({id}) Dict get position of popup window {id}
423popup_hide({id}) none hide popup menu {id}
424popup_list() List get a list of window IDs of all popups
425popup_locate({row}, {col}) Number get window ID of popup at position
426popup_menu({what}, {options}) Number create a popup window used as a menu
427popup_move({id}, {options}) none set position of popup window {id}
428popup_notification({what}, {options})
429 Number create a notification popup window
430popup_setoptions({id}, {options})
431 none set options for popup window {id}
432popup_settext({id}, {text}) none set the text of popup window {id}
433popup_show({id}) none unhide popup window {id}
434pow({x}, {y}) Float {x} to the power of {y}
435prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
436printf({fmt}, {expr1}...) String format text
437prompt_getprompt({buf}) String get prompt text
438prompt_setcallback({buf}, {expr}) none set prompt callback function
439prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
440prompt_setprompt({buf}, {text}) none set prompt text
441prop_add({lnum}, {col}, {props}) none add one text property
442prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
443 none add multiple text properties
444prop_clear({lnum} [, {lnum-end} [, {props}]])
445 none remove all text properties
446prop_find({props} [, {direction}])
447 Dict search for a text property
448prop_list({lnum} [, {props}]) List text properties in {lnum}
449prop_remove({props} [, {lnum} [, {lnum-end}]])
450 Number remove a text property
451prop_type_add({name}, {props}) none define a new property type
452prop_type_change({name}, {props})
453 none change an existing property type
454prop_type_delete({name} [, {props}])
455 none delete a property type
456prop_type_get({name} [, {props}])
457 Dict get property type values
458prop_type_list([{props}]) List get list of property types
459pum_getpos() Dict position and size of pum if visible
460pumvisible() Number whether popup menu is visible
461py3eval({expr}) any evaluate |python3| expression
462pyeval({expr}) any evaluate |Python| expression
463pyxeval({expr}) any evaluate |python_x| expression
464rand([{expr}]) Number get pseudo-random number
465range({expr} [, {max} [, {stride}]])
466 List items from {expr} to {max}
K.Takata11df3ae2022-10-19 14:02:40 +0100467readblob({fname} [, {offset} [, {size}]])
468 Blob read a |Blob| from {fname}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000469readdir({dir} [, {expr} [, {dict}]])
470 List file names in {dir} selected by {expr}
471readdirex({dir} [, {expr} [, {dict}]])
472 List file info in {dir} selected by {expr}
473readfile({fname} [, {type} [, {max}]])
474 List get list of lines from file {fname}
475reduce({object}, {func} [, {initial}])
476 any reduce {object} using {func}
477reg_executing() String get the executing register name
478reg_recording() String get the recording register name
479reltime([{start} [, {end}]]) List get time value
480reltimefloat({time}) Float turn the time value into a Float
481reltimestr({time}) String turn time value into a String
482remote_expr({server}, {string} [, {idvar} [, {timeout}]])
483 String send expression
484remote_foreground({server}) Number bring Vim server to the foreground
485remote_peek({serverid} [, {retvar}])
486 Number check for reply string
487remote_read({serverid} [, {timeout}])
488 String read reply string
489remote_send({server}, {string} [, {idvar}])
490 String send key sequence
491remote_startserver({name}) none become server {name}
492remove({list}, {idx} [, {end}]) any/List
493 remove items {idx}-{end} from {list}
494remove({blob}, {idx} [, {end}]) Number/Blob
495 remove bytes {idx}-{end} from {blob}
496remove({dict}, {key}) any remove entry {key} from {dict}
497rename({from}, {to}) Number rename (move) file from {from} to {to}
Bakudankun375141e2022-09-09 18:46:47 +0100498repeat({expr}, {count}) List/Blob/String
499 repeat {expr} {count} times
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000500resolve({filename}) String get filename a shortcut points to
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +0100501reverse({obj}) List/Blob/String
502 reverse {obj}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000503round({expr}) Float round off {expr}
504rubyeval({expr}) any evaluate |Ruby| expression
505screenattr({row}, {col}) Number attribute at screen position
506screenchar({row}, {col}) Number character at screen position
507screenchars({row}, {col}) List List of characters at screen position
508screencol() Number current cursor column
509screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
510screenrow() Number current cursor row
511screenstring({row}, {col}) String characters at screen position
512search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
513 Number search for {pattern}
514searchcount([{options}]) Dict get or update search stats
515searchdecl({name} [, {global} [, {thisblock}]])
516 Number search for variable declaration
517searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
518 Number search for other end of start/end pair
519searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
520 List search for other end of start/end pair
521searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
522 List search for {pattern}
523server2client({clientid}, {string})
524 Number send reply string
525serverlist() String get a list of available servers
526setbufline({expr}, {lnum}, {text})
527 Number set line {lnum} to {text} in buffer
528 {expr}
529setbufvar({buf}, {varname}, {val})
530 none set {varname} in buffer {buf} to {val}
531setcellwidths({list}) none set character cell width overrides
532setcharpos({expr}, {list}) Number set the {expr} position to {list}
533setcharsearch({dict}) Dict set character search from {dict}
Shougo Matsushita07ea5f12022-08-27 12:22:25 +0100534setcmdline({str} [, {pos}]) Number set command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000535setcmdpos({pos}) Number set cursor position in command-line
536setcursorcharpos({list}) Number move cursor to position in {list}
537setenv({name}, {val}) none set environment variable
538setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
539setline({lnum}, {line}) Number set line {lnum} to {line}
540setloclist({nr}, {list} [, {action}])
541 Number modify location list using {list}
542setloclist({nr}, {list}, {action}, {what})
543 Number modify specific location list props
544setmatches({list} [, {win}]) Number restore a list of matches
545setpos({expr}, {list}) Number set the {expr} position to {list}
546setqflist({list} [, {action}]) Number modify quickfix list using {list}
547setqflist({list}, {action}, {what})
548 Number modify specific quickfix list props
549setreg({n}, {v} [, {opt}]) Number set register to value and type
550settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
551settabwinvar({tabnr}, {winnr}, {varname}, {val})
552 none set {varname} in window {winnr} in tab
553 page {tabnr} to {val}
554settagstack({nr}, {dict} [, {action}])
555 Number modify tag stack using {dict}
556setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
557sha256({string}) String SHA256 checksum of {string}
558shellescape({string} [, {special}])
559 String escape {string} for use as shell
560 command argument
561shiftwidth([{col}]) Number effective value of 'shiftwidth'
562sign_define({name} [, {dict}]) Number define or update a sign
563sign_define({list}) List define or update a list of signs
564sign_getdefined([{name}]) List get a list of defined signs
565sign_getplaced([{buf} [, {dict}]])
566 List get a list of placed signs
567sign_jump({id}, {group}, {buf})
568 Number jump to a sign
569sign_place({id}, {group}, {name}, {buf} [, {dict}])
570 Number place a sign
571sign_placelist({list}) List place a list of signs
572sign_undefine([{name}]) Number undefine a sign
573sign_undefine({list}) List undefine a list of signs
574sign_unplace({group} [, {dict}])
575 Number unplace a sign
576sign_unplacelist({list}) List unplace a list of signs
577simplify({filename}) String simplify filename as much as possible
578sin({expr}) Float sine of {expr}
579sinh({expr}) Float hyperbolic sine of {expr}
580slice({expr}, {start} [, {end}]) String, List or Blob
581 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000582sort({list} [, {how} [, {dict}]])
583 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000584sound_clear() none stop playing all sounds
585sound_playevent({name} [, {callback}])
586 Number play an event sound
587sound_playfile({path} [, {callback}])
588 Number play sound file {path}
589sound_stop({id}) none stop playing sound {id}
590soundfold({word}) String sound-fold {word}
591spellbadword() String badly spelled word at cursor
592spellsuggest({word} [, {max} [, {capital}]])
593 List spelling suggestions
594split({expr} [, {pat} [, {keepempty}]])
595 List make |List| from {pat} separated {expr}
596sqrt({expr}) Float square root of {expr}
597srand([{expr}]) List get seed for |rand()|
598state([{what}]) String current state of Vim
599str2float({expr} [, {quoted}]) Float convert String to Float
600str2list({expr} [, {utf8}]) List convert each character of {expr} to
601 ASCII/UTF-8 value
602str2nr({expr} [, {base} [, {quoted}]])
603 Number convert String to Number
604strcharlen({expr}) Number character length of the String {expr}
605strcharpart({str}, {start} [, {len} [, {skipcc}]])
606 String {len} characters of {str} at
607 character {start}
608strchars({expr} [, {skipcc}]) Number character count of the String {expr}
609strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
610strftime({format} [, {time}]) String format time with a specified format
611strgetchar({str}, {index}) Number get char {index} from {str}
612stridx({haystack}, {needle} [, {start}])
613 Number index of {needle} in {haystack}
614string({expr}) String String representation of {expr} value
615strlen({expr}) Number length of the String {expr}
616strpart({str}, {start} [, {len} [, {chars}]])
617 String {len} bytes/chars of {str} at
618 byte {start}
619strptime({format}, {timestring})
620 Number Convert {timestring} to unix timestamp
621strridx({haystack}, {needle} [, {start}])
622 Number last index of {needle} in {haystack}
623strtrans({expr}) String translate string to make it printable
Christian Brabandt67672ef2023-04-24 21:09:54 +0100624strutf16len({string} [, {countcc}])
625 Number number of UTF-16 code units in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000626strwidth({expr}) Number display cell length of the String {expr}
627submatch({nr} [, {list}]) String or List
628 specific match in ":s" or substitute()
629substitute({expr}, {pat}, {sub}, {flags})
630 String all {pat} in {expr} replaced with {sub}
Bram Moolenaarc216a7a2022-12-05 13:50:55 +0000631swapfilelist() List swap files found in 'directory'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000632swapinfo({fname}) Dict information about swap file {fname}
633swapname({buf}) String swap file of buffer {buf}
634synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
635synIDattr({synID}, {what} [, {mode}])
636 String attribute {what} of syntax ID {synID}
637synIDtrans({synID}) Number translated syntax ID of {synID}
638synconcealed({lnum}, {col}) List info about concealing
639synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
640system({expr} [, {input}]) String output of shell command/filter {expr}
641systemlist({expr} [, {input}]) List output of shell command/filter {expr}
642tabpagebuflist([{arg}]) List list of buffer numbers in tab page
643tabpagenr([{arg}]) Number number of current or last tab page
644tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
645tagfiles() List tags files used
646taglist({expr} [, {filename}]) List list of tags matching {expr}
647tan({expr}) Float tangent of {expr}
648tanh({expr}) Float hyperbolic tangent of {expr}
649tempname() String name for a temporary file
650term_dumpdiff({filename}, {filename} [, {options}])
651 Number display difference between two dumps
652term_dumpload({filename} [, {options}])
653 Number displaying a screen dump
654term_dumpwrite({buf}, {filename} [, {options}])
655 none dump terminal window contents
656term_getaltscreen({buf}) Number get the alternate screen flag
657term_getansicolors({buf}) List get ANSI palette in GUI color mode
658term_getattr({attr}, {what}) Number get the value of attribute {what}
659term_getcursor({buf}) List get the cursor position of a terminal
660term_getjob({buf}) Job get the job associated with a terminal
661term_getline({buf}, {row}) String get a line of text from a terminal
662term_getscrolled({buf}) Number get the scroll count of a terminal
663term_getsize({buf}) List get the size of a terminal
664term_getstatus({buf}) String get the status of a terminal
665term_gettitle({buf}) String get the title of a terminal
666term_gettty({buf}, [{input}]) String get the tty name of a terminal
667term_list() List get the list of terminal buffers
668term_scrape({buf}, {row}) List get row of a terminal screen
669term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
670term_setansicolors({buf}, {colors})
671 none set ANSI palette in GUI color mode
672term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
673term_setkill({buf}, {how}) none set signal to stop job in terminal
674term_setrestore({buf}, {command}) none set command to restore terminal
675term_setsize({buf}, {rows}, {cols})
676 none set the size of a terminal
677term_start({cmd} [, {options}]) Number open a terminal window and run a job
678term_wait({buf} [, {time}]) Number wait for screen to be updated
679terminalprops() Dict properties of the terminal
680test_alloc_fail({id}, {countdown}, {repeat})
681 none make memory allocation fail
682test_autochdir() none enable 'autochdir' during startup
683test_feedinput({string}) none add key sequence to input buffer
684test_garbagecollect_now() none free memory right now for testing
685test_garbagecollect_soon() none free memory soon for testing
686test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000687test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000688test_ignore_error({expr}) none ignore a specific error
Christopher Plewright20b795e2022-12-20 20:01:58 +0000689test_mswin_event({event}, {args})
690 bool generate MS-Windows event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000691test_null_blob() Blob null value for testing
692test_null_channel() Channel null value for testing
693test_null_dict() Dict null value for testing
694test_null_function() Funcref null value for testing
695test_null_job() Job null value for testing
696test_null_list() List null value for testing
697test_null_partial() Funcref null value for testing
698test_null_string() String null value for testing
699test_option_not_set({name}) none reset flag indicating option was set
700test_override({expr}, {val}) none test with Vim internal overrides
701test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000702test_setmouse({row}, {col}) none set the mouse position for testing
703test_settime({expr}) none set current time for testing
Doug Kearns9cd9e752024-04-07 17:42:17 +0200704test_srand_seed([{seed}]) none set seed for testing srand()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000705test_unknown() any unknown value for testing
706test_void() any void value for testing
707timer_info([{id}]) List information about timers
708timer_pause({id}, {pause}) none pause or unpause a timer
709timer_start({time}, {callback} [, {options}])
710 Number create a timer
711timer_stop({timer}) none stop a timer
712timer_stopall() none stop all timers
713tolower({expr}) String the String {expr} switched to lowercase
714toupper({expr}) String the String {expr} switched to uppercase
715tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
716 to chars in {tostr}
717trim({text} [, {mask} [, {dir}]])
718 String trim characters in {mask} from {text}
719trunc({expr}) Float truncate Float {expr}
720type({expr}) Number type of value {expr}
721typename({expr}) String representation of the type of {expr}
722undofile({name}) String undo file name for {name}
Devin J. Pohly5fee1112023-04-23 20:26:59 -0500723undotree([{buf}]) List undo file tree for buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000724uniq({list} [, {func} [, {dict}]])
725 List remove adjacent duplicates from a list
Christian Brabandt67672ef2023-04-24 21:09:54 +0100726utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
727 Number UTF-16 index of byte {idx} in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000728values({dict}) List values in {dict}
zeertzjq825cf812023-08-17 22:55:25 +0200729virtcol({expr} [, {list} [, {winid}])
730 Number or List
LemonBoy0f7a3e12022-05-26 12:10:37 +0100731 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100732virtcol2col({winid}, {lnum}, {col})
733 Number byte index of a character on screen
Doug Kearns9cd9e752024-04-07 17:42:17 +0200734visualmode([{expr}]) String last visual mode used
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000735wildmenumode() Number whether 'wildmenu' mode is active
736win_execute({id}, {command} [, {silent}])
737 String execute {command} in window {id}
738win_findbuf({bufnr}) List find windows containing {bufnr}
739win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
740win_gettype([{nr}]) String type of window {nr}
741win_gotoid({expr}) Number go to window with ID {expr}
742win_id2tabwin({expr}) List get tab and window nr from window ID
743win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000744win_move_separator({nr}) Number move window vertical separator
745win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000746win_screenpos({nr}) List get screen position of window {nr}
747win_splitmove({nr}, {target} [, {options}])
748 Number move window {nr} to split of {target}
749winbufnr({nr}) Number buffer number of window {nr}
750wincol() Number window column of the cursor
751windowsversion() String MS-Windows OS version
752winheight({nr}) Number height of window {nr}
753winlayout([{tabnr}]) List layout of windows in tab {tabnr}
754winline() Number window line of the cursor
755winnr([{expr}]) Number number of current window
756winrestcmd() String returns command to restore window sizes
757winrestview({dict}) none restore view of current window
758winsaveview() Dict save view of current window
759winwidth({nr}) Number width of window {nr}
760wordcount() Dict get byte/char/word statistics
761writefile({object}, {fname} [, {flags}])
762 Number write |Blob| or |List| of lines to file
763xor({expr}, {expr}) Number bitwise XOR
764
765==============================================================================
7662. Details *builtin-function-details*
767
768Not all functions are here, some have been moved to a help file covering the
769specific functionality.
770
771abs({expr}) *abs()*
772 Return the absolute value of {expr}. When {expr} evaluates to
773 a |Float| abs() returns a |Float|. When {expr} can be
774 converted to a |Number| abs() returns a |Number|. Otherwise
775 abs() gives an error message and returns -1.
776 Examples: >
777 echo abs(1.456)
778< 1.456 >
779 echo abs(-5.456)
780< 5.456 >
781 echo abs(-4)
782< 4
783
784 Can also be used as a |method|: >
785 Compute()->abs()
786
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000787
788acos({expr}) *acos()*
789 Return the arc cosine of {expr} measured in radians, as a
790 |Float| in the range of [0, pi].
791 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100792 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000793 Examples: >
794 :echo acos(0)
795< 1.570796 >
796 :echo acos(-0.5)
797< 2.094395
798
799 Can also be used as a |method|: >
800 Compute()->acos()
801
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000802
803add({object}, {expr}) *add()*
804 Append the item {expr} to |List| or |Blob| {object}. Returns
805 the resulting |List| or |Blob|. Examples: >
806 :let alist = add([1, 2, 3], item)
807 :call add(mylist, "woodstock")
808< Note that when {expr} is a |List| it is appended as a single
809 item. Use |extend()| to concatenate |Lists|.
810 When {object} is a |Blob| then {expr} must be a number.
811 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100812 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000813
814 Can also be used as a |method|: >
815 mylist->add(val1)->add(val2)
816
817
818and({expr}, {expr}) *and()*
819 Bitwise AND on the two arguments. The arguments are converted
820 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100821 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000822 Example: >
823 :let flag = and(bits, 0x80)
824< Can also be used as a |method|: >
825 :let flag = bits->and(0x80)
826
827
828append({lnum}, {text}) *append()*
829 When {text} is a |List|: Append each item of the |List| as a
830 text line below line {lnum} in the current buffer.
831 Otherwise append {text} as one text line below line {lnum} in
832 the current buffer.
833 Any type of item is accepted and converted to a String.
834 {lnum} can be zero to insert a line before the first one.
835 {lnum} is used like with |getline()|.
836 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000837 0 for success. When {text} is an empty list zero is returned,
838 no matter the value of {lnum}.
839 In |Vim9| script an invalid argument or negative number
840 results in an error. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000841 :let failed = append(line('$'), "# THE END")
842 :let failed = append(0, ["Chapter 1", "the beginning"])
843
844< Can also be used as a |method| after a List, the base is
845 passed as the second argument: >
846 mylist->append(lnum)
847
848
849appendbufline({buf}, {lnum}, {text}) *appendbufline()*
850 Like |append()| but append the text in buffer {buf}.
851
852 This function works only for loaded buffers. First call
853 |bufload()| if needed.
854
855 For the use of {buf}, see |bufname()|.
856
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000857 {lnum} is the line number to append below. Note that using
858 |line()| would use the current buffer, not the one appending
859 to. Use "$" to append at the end of the buffer. Other string
860 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000861
862 On success 0 is returned, on failure 1 is returned.
863 In |Vim9| script an error is given for an invalid {lnum}.
864
865 If {buf} is not a valid buffer or {lnum} is not valid, an
866 error message is given. Example: >
867 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000868< However, when {text} is an empty list then no error is given
869 for an invalid {lnum}, since {lnum} isn't actually used.
870
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000871 Can also be used as a |method| after a List, the base is
872 passed as the second argument: >
873 mylist->appendbufline(buf, lnum)
874
875
876argc([{winid}]) *argc()*
877 The result is the number of files in the argument list. See
878 |arglist|.
879 If {winid} is not supplied, the argument list of the current
880 window is used.
881 If {winid} is -1, the global argument list is used.
882 Otherwise {winid} specifies the window of which the argument
883 list is used: either the window number or the window ID.
884 Returns -1 if the {winid} argument is invalid.
885
886 *argidx()*
887argidx() The result is the current index in the argument list. 0 is
888 the first file. argc() - 1 is the last one. See |arglist|.
889
890 *arglistid()*
891arglistid([{winnr} [, {tabnr}]])
892 Return the argument list ID. This is a number which
893 identifies the argument list being used. Zero is used for the
894 global argument list. See |arglist|.
895 Returns -1 if the arguments are invalid.
896
897 Without arguments use the current window.
898 With {winnr} only use this window in the current tab page.
899 With {winnr} and {tabnr} use the window in the specified tab
900 page.
901 {winnr} can be the window number or the |window-ID|.
902
903 *argv()*
904argv([{nr} [, {winid}]])
905 The result is the {nr}th file in the argument list. See
906 |arglist|. "argv(0)" is the first one. Example: >
907 :let i = 0
908 :while i < argc()
909 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000910 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000911 : let i = i + 1
912 :endwhile
913< Without the {nr} argument, or when {nr} is -1, a |List| with
914 the whole |arglist| is returned.
915
916 The {winid} argument specifies the window ID, see |argc()|.
917 For the Vim command line arguments see |v:argv|.
918
Bram Moolenaar016188f2022-06-06 20:52:59 +0100919 Returns an empty string if {nr}th argument is not present in
920 the argument list. Returns an empty List if the {winid}
921 argument is invalid.
922
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000923asin({expr}) *asin()*
924 Return the arc sine of {expr} measured in radians, as a |Float|
925 in the range of [-pi/2, pi/2].
926 {expr} must evaluate to a |Float| or a |Number| in the range
927 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100928 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
929 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000930 Examples: >
931 :echo asin(0.8)
932< 0.927295 >
933 :echo asin(-0.5)
934< -0.523599
935
936 Can also be used as a |method|: >
937 Compute()->asin()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000938
939
940assert_ functions are documented here: |assert-functions-details|
941
942
943
944atan({expr}) *atan()*
945 Return the principal value of the arc tangent of {expr}, in
946 the range [-pi/2, +pi/2] radians, as a |Float|.
947 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100948 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000949 Examples: >
950 :echo atan(100)
951< 1.560797 >
952 :echo atan(-4.01)
953< -1.326405
954
955 Can also be used as a |method|: >
956 Compute()->atan()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000957
958
959atan2({expr1}, {expr2}) *atan2()*
960 Return the arc tangent of {expr1} / {expr2}, measured in
961 radians, as a |Float| in the range [-pi, pi].
962 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100963 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
964 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000965 Examples: >
966 :echo atan2(-1, 1)
967< -0.785398 >
968 :echo atan2(1, -1)
969< 2.356194
970
971 Can also be used as a |method|: >
972 Compute()->atan2(1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000973
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100974
975autocmd_add({acmds}) *autocmd_add()*
976 Adds a List of autocmds and autocmd groups.
977
978 The {acmds} argument is a List where each item is a Dict with
979 the following optional items:
980 bufnr buffer number to add a buffer-local autocmd.
981 If this item is specified, then the "pattern"
982 item is ignored.
983 cmd Ex command to execute for this autocmd event
984 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100985 This can be either a String with a single
986 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100987 group autocmd group name. Refer to |autocmd-groups|.
988 If this group doesn't exist then it is
989 created. If not specified or empty, then the
990 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100991 nested boolean flag, set to v:true to add a nested
992 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100993 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100994 which executes only once. Refer to
995 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100996 pattern autocmd pattern string. Refer to
997 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100998 present, then this item is ignored. This can
999 be a String with a single pattern or a List of
1000 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001001 replace boolean flag, set to v:true to remove all the
1002 commands associated with the specified autocmd
1003 event and group and add the {cmd}. This is
1004 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +01001005 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001006
1007 Returns v:true on success and v:false on failure.
1008 Examples: >
1009 " Create a buffer-local autocmd for buffer 5
1010 let acmd = {}
1011 let acmd.group = 'MyGroup'
1012 let acmd.event = 'BufEnter'
1013 let acmd.bufnr = 5
1014 let acmd.cmd = 'call BufEnterFunc()'
1015 call autocmd_add([acmd])
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00001016<
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001017 Can also be used as a |method|: >
1018 GetAutocmdList()->autocmd_add()
1019<
1020autocmd_delete({acmds}) *autocmd_delete()*
1021 Deletes a List of autocmds and autocmd groups.
1022
1023 The {acmds} argument is a List where each item is a Dict with
1024 the following optional items:
1025 bufnr buffer number to delete a buffer-local autocmd.
1026 If this item is specified, then the "pattern"
1027 item is ignored.
1028 cmd Ex command for this autocmd event
1029 event autocmd event name. Refer to |autocmd-events|.
1030 If '*' then all the autocmd events in this
1031 group are deleted.
1032 group autocmd group name. Refer to |autocmd-groups|.
1033 If not specified or empty, then the default
1034 group is used.
1035 nested set to v:true for a nested autocmd.
1036 Refer to |autocmd-nested|.
1037 once set to v:true for an autocmd which executes
1038 only once. Refer to |autocmd-once|.
1039 pattern autocmd pattern string. Refer to
1040 |autocmd-patterns|. If "bufnr" item is
1041 present, then this item is ignored.
1042
1043 If only {group} is specified in a {acmds} entry and {event},
1044 {pattern} and {cmd} are not specified, then that autocmd group
1045 is deleted.
1046
Bram Moolenaar016188f2022-06-06 20:52:59 +01001047 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001048 Examples: >
1049 " :autocmd! BufLeave *.vim
1050 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1051 call autocmd_delete([acmd]})
1052 " :autocmd! MyGroup1 BufLeave
1053 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1054 call autocmd_delete([acmd])
1055 " :autocmd! MyGroup2 BufEnter *.c
1056 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1057 \ pattern: '*.c'}
1058 " :autocmd! MyGroup2 * *.c
1059 let acmd = #{group: 'MyGroup2', event: '*',
1060 \ pattern: '*.c'}
1061 call autocmd_delete([acmd])
1062 " :autocmd! MyGroup3
1063 let acmd = #{group: 'MyGroup3'}
1064 call autocmd_delete([acmd])
1065<
1066 Can also be used as a |method|: >
1067 GetAutocmdList()->autocmd_delete()
1068
1069autocmd_get([{opts}]) *autocmd_get()*
1070 Returns a |List| of autocmds. If {opts} is not supplied, then
1071 returns the autocmds for all the events in all the groups.
1072
1073 The optional {opts} Dict argument supports the following
1074 items:
1075 group Autocmd group name. If specified, returns only
1076 the autocmds defined in this group. If the
1077 specified group doesn't exist, results in an
1078 error message. If set to an empty string,
1079 then the default autocmd group is used.
1080 event Autocmd event name. If specified, returns only
1081 the autocmds defined for this event. If set
1082 to "*", then returns autocmds for all the
1083 events. If the specified event doesn't exist,
1084 results in an error message.
1085 pattern Autocmd pattern. If specified, returns only
1086 the autocmds defined for this pattern.
1087 A combination of the above three times can be supplied in
1088 {opts}.
1089
1090 Each Dict in the returned List contains the following items:
1091 bufnr For buffer-local autocmds, buffer number where
1092 the autocmd is defined.
1093 cmd Command executed for this autocmd.
1094 event Autocmd event name.
1095 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001096 nested Boolean flag, set to v:true for a nested
1097 autocmd. See |autocmd-nested|.
1098 once Boolean flag, set to v:true, if the autocmd
1099 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001100 pattern Autocmd pattern. For a buffer-local
1101 autocmd, this will be of the form "<buffer=n>".
1102 If there are multiple commands for an autocmd event in a
1103 group, then separate items are returned for each command.
1104
Bram Moolenaar016188f2022-06-06 20:52:59 +01001105 Returns an empty List if an autocmd with the specified group
1106 or event or pattern is not found.
1107
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001108 Examples: >
1109 " :autocmd MyGroup
1110 echo autocmd_get(#{group: 'Mygroup'})
1111 " :autocmd G BufUnload
1112 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1113 " :autocmd G * *.ts
1114 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1115 echo autocmd_get(acmd)
1116 " :autocmd Syntax
1117 echo autocmd_get(#{event: 'Syntax'})
1118 " :autocmd G BufEnter *.ts
1119 let acmd = #{group: 'G', event: 'BufEnter',
1120 \ pattern: '*.ts'}
1121 echo autocmd_get(acmd)
1122<
1123 Can also be used as a |method|: >
1124 Getopts()->autocmd_get()
1125<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001126balloon_gettext() *balloon_gettext()*
1127 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001128 not used for the List. Returns an empty string if balloon
1129 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001130
1131balloon_show({expr}) *balloon_show()*
1132 Show {expr} inside the balloon. For the GUI {expr} is used as
1133 a string. For a terminal {expr} can be a list, which contains
1134 the lines of the balloon. If {expr} is not a list it will be
1135 split with |balloon_split()|.
1136 If {expr} is an empty string any existing balloon is removed.
1137
1138 Example: >
1139 func GetBalloonContent()
1140 " ... initiate getting the content
1141 return ''
1142 endfunc
1143 set balloonexpr=GetBalloonContent()
1144
1145 func BalloonCallback(result)
1146 call balloon_show(a:result)
1147 endfunc
1148< Can also be used as a |method|: >
1149 GetText()->balloon_show()
1150<
1151 The intended use is that fetching the content of the balloon
1152 is initiated from 'balloonexpr'. It will invoke an
1153 asynchronous method, in which a callback invokes
1154 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001155 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001156
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001157 When showing a balloon is not possible then nothing happens,
1158 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001159 {only available when compiled with the |+balloon_eval| or
1160 |+balloon_eval_term| feature}
1161
1162balloon_split({msg}) *balloon_split()*
1163 Split String {msg} into lines to be displayed in a balloon.
1164 The splits are made for the current window size and optimize
1165 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001166 Returns a |List| with the split lines. Returns an empty List
1167 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001168 Can also be used as a |method|: >
1169 GetText()->balloon_split()->balloon_show()
1170
1171< {only available when compiled with the |+balloon_eval_term|
1172 feature}
1173
1174blob2list({blob}) *blob2list()*
1175 Return a List containing the number value of each byte in Blob
1176 {blob}. Examples: >
1177 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1178 blob2list(0z) returns []
1179< Returns an empty List on error. |list2blob()| does the
1180 opposite.
1181
1182 Can also be used as a |method|: >
1183 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001184<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001185 *browse()*
1186browse({save}, {title}, {initdir}, {default})
1187 Put up a file requester. This only works when "has("browse")"
1188 returns |TRUE| (only in some GUI versions).
1189 The input fields are:
1190 {save} when |TRUE|, select file to write
1191 {title} title for the requester
1192 {initdir} directory to start browsing in
1193 {default} default file name
1194 An empty string is returned when the "Cancel" button is hit,
1195 something went wrong, or browsing is not possible.
1196
1197 *browsedir()*
1198browsedir({title}, {initdir})
1199 Put up a directory requester. This only works when
1200 "has("browse")" returns |TRUE| (only in some GUI versions).
1201 On systems where a directory browser is not supported a file
1202 browser is used. In that case: select a file in the directory
1203 to be used.
1204 The input fields are:
1205 {title} title for the requester
1206 {initdir} directory to start browsing in
1207 When the "Cancel" button is hit, something went wrong, or
1208 browsing is not possible, an empty string is returned.
1209
1210bufadd({name}) *bufadd()*
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001211 Add a buffer to the buffer list with name {name} (must be a
1212 String).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001213 If a buffer for file {name} already exists, return that buffer
1214 number. Otherwise return the buffer number of the newly
1215 created buffer. When {name} is an empty string then a new
1216 buffer is always created.
1217 The buffer will not have 'buflisted' set and not be loaded
1218 yet. To add some text to the buffer use this: >
1219 let bufnr = bufadd('someName')
1220 call bufload(bufnr)
1221 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001222< Returns 0 on error.
1223 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001224 let bufnr = 'somename'->bufadd()
1225
1226bufexists({buf}) *bufexists()*
1227 The result is a Number, which is |TRUE| if a buffer called
1228 {buf} exists.
1229 If the {buf} argument is a number, buffer numbers are used.
1230 Number zero is the alternate buffer for the current window.
1231
1232 If the {buf} argument is a string it must match a buffer name
1233 exactly. The name can be:
1234 - Relative to the current directory.
1235 - A full path.
1236 - The name of a buffer with 'buftype' set to "nofile".
1237 - A URL name.
1238 Unlisted buffers will be found.
1239 Note that help files are listed by their short name in the
1240 output of |:buffers|, but bufexists() requires using their
1241 long name to be able to find them.
1242 bufexists() may report a buffer exists, but to use the name
1243 with a |:buffer| command you may need to use |expand()|. Esp
1244 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1245 Use "bufexists(0)" to test for the existence of an alternate
1246 file name.
1247
1248 Can also be used as a |method|: >
1249 let exists = 'somename'->bufexists()
1250<
1251 Obsolete name: buffer_exists(). *buffer_exists()*
1252
1253buflisted({buf}) *buflisted()*
1254 The result is a Number, which is |TRUE| if a buffer called
1255 {buf} exists and is listed (has the 'buflisted' option set).
1256 The {buf} argument is used like with |bufexists()|.
1257
1258 Can also be used as a |method|: >
1259 let listed = 'somename'->buflisted()
1260
1261bufload({buf}) *bufload()*
1262 Ensure the buffer {buf} is loaded. When the buffer name
1263 refers to an existing file then the file is read. Otherwise
1264 the buffer will be empty. If the buffer was already loaded
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001265 then there is no change. If the buffer is not related to a
Daniel Steinbergc2bd2052023-08-09 12:10:59 -04001266 file then no file is read (e.g., when 'buftype' is "nofile").
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001267 If there is an existing swap file for the file of the buffer,
1268 there will be no dialog, the buffer will be loaded anyway.
1269 The {buf} argument is used like with |bufexists()|.
1270
1271 Can also be used as a |method|: >
1272 eval 'somename'->bufload()
1273
1274bufloaded({buf}) *bufloaded()*
1275 The result is a Number, which is |TRUE| if a buffer called
1276 {buf} exists and is loaded (shown in a window or hidden).
1277 The {buf} argument is used like with |bufexists()|.
1278
1279 Can also be used as a |method|: >
1280 let loaded = 'somename'->bufloaded()
1281
1282bufname([{buf}]) *bufname()*
1283 The result is the name of a buffer. Mostly as it is displayed
1284 by the `:ls` command, but not using special names such as
1285 "[No Name]".
1286 If {buf} is omitted the current buffer is used.
1287 If {buf} is a Number, that buffer number's name is given.
1288 Number zero is the alternate buffer for the current window.
1289 If {buf} is a String, it is used as a |file-pattern| to match
1290 with the buffer names. This is always done like 'magic' is
1291 set and 'cpoptions' is empty. When there is more than one
1292 match an empty string is returned.
1293 "" or "%" can be used for the current buffer, "#" for the
1294 alternate buffer.
1295 A full match is preferred, otherwise a match at the start, end
1296 or middle of the buffer name is accepted. If you only want a
1297 full match then put "^" at the start and "$" at the end of the
1298 pattern.
1299 Listed buffers are found first. If there is a single match
1300 with a listed buffer, that one is returned. Next unlisted
1301 buffers are searched for.
1302 If the {buf} is a String, but you want to use it as a buffer
1303 number, force it to be a Number by adding zero to it: >
1304 :echo bufname("3" + 0)
1305< Can also be used as a |method|: >
1306 echo bufnr->bufname()
1307
1308< If the buffer doesn't exist, or doesn't have a name, an empty
1309 string is returned. >
1310 bufname("#") alternate buffer name
1311 bufname(3) name of buffer 3
1312 bufname("%") name of current buffer
1313 bufname("file2") name of buffer where "file2" matches.
1314< *buffer_name()*
1315 Obsolete name: buffer_name().
1316
1317 *bufnr()*
1318bufnr([{buf} [, {create}]])
1319 The result is the number of a buffer, as it is displayed by
1320 the `:ls` command. For the use of {buf}, see |bufname()|
1321 above.
1322
1323 If the buffer doesn't exist, -1 is returned. Or, if the
1324 {create} argument is present and TRUE, a new, unlisted,
1325 buffer is created and its number is returned. Example: >
1326 let newbuf = bufnr('Scratch001', 1)
1327< Using an empty name uses the current buffer. To create a new
1328 buffer with an empty name use |bufadd()|.
1329
1330 bufnr("$") is the last buffer: >
1331 :let last_buffer = bufnr("$")
1332< The result is a Number, which is the highest buffer number
1333 of existing buffers. Note that not all buffers with a smaller
1334 number necessarily exist, because ":bwipeout" may have removed
1335 them. Use bufexists() to test for the existence of a buffer.
1336
1337 Can also be used as a |method|: >
1338 echo bufref->bufnr()
1339<
1340 Obsolete name: buffer_number(). *buffer_number()*
1341 *last_buffer_nr()*
1342 Obsolete name for bufnr("$"): last_buffer_nr().
1343
1344bufwinid({buf}) *bufwinid()*
1345 The result is a Number, which is the |window-ID| of the first
1346 window associated with buffer {buf}. For the use of {buf},
1347 see |bufname()| above. If buffer {buf} doesn't exist or
1348 there is no such window, -1 is returned. Example: >
1349
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001350 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001351<
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001352 Only deals with the current tab page. See |win_findbuf()| for
1353 finding more.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001354
1355 Can also be used as a |method|: >
1356 FindBuffer()->bufwinid()
1357
1358bufwinnr({buf}) *bufwinnr()*
1359 Like |bufwinid()| but return the window number instead of the
1360 |window-ID|.
1361 If buffer {buf} doesn't exist or there is no such window, -1
1362 is returned. Example: >
1363
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001364 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001365
1366< The number can be used with |CTRL-W_w| and ":wincmd w"
1367 |:wincmd|.
1368
1369 Can also be used as a |method|: >
1370 FindBuffer()->bufwinnr()
1371
1372byte2line({byte}) *byte2line()*
1373 Return the line number that contains the character at byte
1374 count {byte} in the current buffer. This includes the
1375 end-of-line character, depending on the 'fileformat' option
1376 for the current buffer. The first character has byte count
1377 one.
1378 Also see |line2byte()|, |go| and |:goto|.
1379
Bram Moolenaar016188f2022-06-06 20:52:59 +01001380 Returns -1 if the {byte} value is invalid.
1381
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001382 Can also be used as a |method|: >
1383 GetOffset()->byte2line()
1384
1385< {not available when compiled without the |+byte_offset|
1386 feature}
1387
Christian Brabandt67672ef2023-04-24 21:09:54 +01001388byteidx({expr}, {nr} [, {utf16}]) *byteidx()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001389 Return byte index of the {nr}'th character in the String
1390 {expr}. Use zero for the first character, it then returns
1391 zero.
1392 If there are no multibyte characters the returned value is
1393 equal to {nr}.
1394 Composing characters are not counted separately, their byte
1395 length is added to the preceding base character. See
1396 |byteidxcomp()| below for counting composing characters
1397 separately.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001398 When {utf16} is present and TRUE, {nr} is used as the UTF-16
1399 index in the String {expr} instead of as the character index.
1400 The UTF-16 index is the index in the string when it is encoded
1401 with 16-bit words. If the specified UTF-16 index is in the
1402 middle of a character (e.g. in a 4-byte character), then the
1403 byte index of the first byte in the character is returned.
1404 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001405 Example : >
1406 echo matchstr(str, ".", byteidx(str, 3))
1407< will display the fourth character. Another way to do the
1408 same: >
1409 let s = strpart(str, byteidx(str, 3))
1410 echo strpart(s, 0, byteidx(s, 1))
1411< Also see |strgetchar()| and |strcharpart()|.
1412
1413 If there are less than {nr} characters -1 is returned.
1414 If there are exactly {nr} characters the length of the string
1415 in bytes is returned.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001416 See |charidx()| and |utf16idx()| for getting the character and
1417 UTF-16 index respectively from the byte index.
1418 Examples: >
1419 echo byteidx('a😊😊', 2) returns 5
1420 echo byteidx('a😊😊', 2, 1) returns 1
1421 echo byteidx('a😊😊', 3, 1) returns 5
1422<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001423 Can also be used as a |method|: >
1424 GetName()->byteidx(idx)
1425
Christian Brabandt67672ef2023-04-24 21:09:54 +01001426byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001427 Like byteidx(), except that a composing character is counted
1428 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001429 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001430 echo byteidx(s, 1)
1431 echo byteidxcomp(s, 1)
1432 echo byteidxcomp(s, 2)
1433< The first and third echo result in 3 ('e' plus composing
1434 character is 3 bytes), the second echo results in 1 ('e' is
1435 one byte).
1436 Only works differently from byteidx() when 'encoding' is set
1437 to a Unicode encoding.
1438
1439 Can also be used as a |method|: >
1440 GetName()->byteidxcomp(idx)
1441
1442call({func}, {arglist} [, {dict}]) *call()* *E699*
1443 Call function {func} with the items in |List| {arglist} as
1444 arguments.
1445 {func} can either be a |Funcref| or the name of a function.
1446 a:firstline and a:lastline are set to the cursor line.
1447 Returns the return value of the called function.
1448 {dict} is for functions with the "dict" attribute. It will be
1449 used to set the local variable "self". |Dictionary-function|
1450
1451 Can also be used as a |method|: >
1452 GetFunc()->call([arg, arg], dict)
1453
1454ceil({expr}) *ceil()*
1455 Return the smallest integral value greater than or equal to
1456 {expr} as a |Float| (round up).
1457 {expr} must evaluate to a |Float| or a |Number|.
1458 Examples: >
1459 echo ceil(1.456)
1460< 2.0 >
1461 echo ceil(-5.456)
1462< -5.0 >
1463 echo ceil(4.0)
1464< 4.0
1465
Bram Moolenaar016188f2022-06-06 20:52:59 +01001466 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1467
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001468 Can also be used as a |method|: >
1469 Compute()->ceil()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001470
1471
1472ch_ functions are documented here: |channel-functions-details|
1473
1474
1475changenr() *changenr()*
1476 Return the number of the most recent change. This is the same
1477 number as what is displayed with |:undolist| and can be used
1478 with the |:undo| command.
1479 When a change was made it is the number of that change. After
1480 redo it is the number of the redone change. After undo it is
1481 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001482 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001483
1484char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001485 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001486 Examples: >
1487 char2nr(" ") returns 32
1488 char2nr("ABC") returns 65
1489< When {utf8} is omitted or zero, the current 'encoding' is used.
1490 Example for "utf-8": >
1491 char2nr("á") returns 225
1492 char2nr("á"[0]) returns 195
1493< When {utf8} is TRUE, always treat as UTF-8 characters.
1494 A combining character is a separate character.
1495 |nr2char()| does the opposite.
1496 To turn a string into a list of character numbers: >
1497 let str = "ABC"
1498 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1499< Result: [65, 66, 67]
1500
Bram Moolenaar016188f2022-06-06 20:52:59 +01001501 Returns 0 if {string} is not a |String|.
1502
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001503 Can also be used as a |method|: >
1504 GetChar()->char2nr()
1505
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001506charclass({string}) *charclass()*
1507 Return the character class of the first character in {string}.
1508 The character class is one of:
1509 0 blank
1510 1 punctuation
1511 2 word character
1512 3 emoji
1513 other specific Unicode class
1514 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001515 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001516
1517
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001518charcol({expr} [, {winid}]) *charcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001519 Same as |col()| but returns the character index of the column
1520 position given with {expr} instead of the byte position.
1521
1522 Example:
1523 With the cursor on '세' in line 5 with text "여보세요": >
1524 charcol('.') returns 3
1525 col('.') returns 7
1526
1527< Can also be used as a |method|: >
1528 GetPos()->col()
1529<
1530 *charidx()*
Christian Brabandt67672ef2023-04-24 21:09:54 +01001531charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001532 Return the character index of the byte at {idx} in {string}.
1533 The index of the first character is zero.
1534 If there are no multibyte characters the returned value is
1535 equal to {idx}.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001536
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001537 When {countcc} is omitted or |FALSE|, then composing characters
Christian Brabandt67672ef2023-04-24 21:09:54 +01001538 are not counted separately, their byte length is added to the
1539 preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001540 When {countcc} is |TRUE|, then composing characters are
1541 counted as separate characters.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001542
1543 When {utf16} is present and TRUE, {idx} is used as the UTF-16
1544 index in the String {expr} instead of as the byte index.
1545
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +01001546 Returns -1 if the arguments are invalid or if there are less
1547 than {idx} bytes. If there are exactly {idx} bytes the length
1548 of the string in characters is returned.
1549
1550 An error is given and -1 is returned if the first argument is
1551 not a string, the second argument is not a number or when the
1552 third argument is present and is not zero or one.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001553
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001554 See |byteidx()| and |byteidxcomp()| for getting the byte index
Christian Brabandt67672ef2023-04-24 21:09:54 +01001555 from the character index and |utf16idx()| for getting the
1556 UTF-16 index from the character index.
1557 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001558 Examples: >
1559 echo charidx('áb́ć', 3) returns 1
1560 echo charidx('áb́ć', 6, 1) returns 4
1561 echo charidx('áb́ć', 16) returns -1
Christian Brabandt67672ef2023-04-24 21:09:54 +01001562 echo charidx('a😊😊', 4, 0, 1) returns 2
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001563<
1564 Can also be used as a |method|: >
1565 GetName()->charidx(idx)
1566
1567chdir({dir}) *chdir()*
1568 Change the current working directory to {dir}. The scope of
1569 the directory change depends on the directory of the current
1570 window:
1571 - If the current window has a window-local directory
1572 (|:lcd|), then changes the window local directory.
1573 - Otherwise, if the current tabpage has a local
1574 directory (|:tcd|) then changes the tabpage local
1575 directory.
1576 - Otherwise, changes the global directory.
1577 {dir} must be a String.
1578 If successful, returns the previous working directory. Pass
1579 this to another chdir() to restore the directory.
1580 On failure, returns an empty string.
1581
1582 Example: >
1583 let save_dir = chdir(newdir)
1584 if save_dir != ""
1585 " ... do some work
1586 call chdir(save_dir)
1587 endif
1588
1589< Can also be used as a |method|: >
1590 GetDir()->chdir()
1591<
1592cindent({lnum}) *cindent()*
1593 Get the amount of indent for line {lnum} according the C
1594 indenting rules, as with 'cindent'.
1595 The indent is counted in spaces, the value of 'tabstop' is
1596 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001597 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001598 See |C-indenting|.
1599
1600 Can also be used as a |method|: >
1601 GetLnum()->cindent()
1602
1603clearmatches([{win}]) *clearmatches()*
1604 Clears all matches previously defined for the current window
1605 by |matchadd()| and the |:match| commands.
1606 If {win} is specified, use the window with this number or
1607 window ID instead of the current window.
1608
1609 Can also be used as a |method|: >
1610 GetWin()->clearmatches()
1611<
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001612col({expr} [, {winid}]) *col()*
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001613 The result is a Number, which is the byte index of the column
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001614 position given with {expr}. The accepted positions are:
1615 . the cursor position
1616 $ the end of the cursor line (the result is the
1617 number of bytes in the cursor line plus one)
1618 'x position of mark x (if the mark is not set, 0 is
1619 returned)
1620 v In Visual mode: the start of the Visual area (the
1621 cursor is the end). When not in Visual mode
1622 returns the cursor position. Differs from |'<| in
1623 that it's updated right away.
1624 Additionally {expr} can be [lnum, col]: a |List| with the line
1625 and column number. Most useful when the column is "$", to get
1626 the last column of a specific line. When "lnum" or "col" is
1627 out of range then col() returns zero.
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001628 With the optional {winid} argument the values are obtained for
1629 that window instead of the current window.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001630 To get the line number use |line()|. To get both use
1631 |getpos()|.
1632 For the screen column position use |virtcol()|. For the
1633 character position use |charcol()|.
1634 Note that only marks in the current file can be used.
1635 Examples: >
1636 col(".") column of cursor
1637 col("$") length of cursor line plus one
1638 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001639 col("'" .. markname) column of mark markname
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001640< The first column is 1. Returns 0 if {expr} is invalid or when
1641 the window with ID {winid} is not found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001642 For an uppercase mark the column may actually be in another
1643 buffer.
1644 For the cursor position, when 'virtualedit' is active, the
1645 column is one higher if the cursor is after the end of the
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01001646 line. Also, when using a <Cmd> mapping the cursor isn't
1647 moved, this can be used to obtain the column in Insert mode: >
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001648 :imap <F2> <Cmd>echowin col(".")<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001649
1650< Can also be used as a |method|: >
1651 GetPos()->col()
1652<
1653
1654complete({startcol}, {matches}) *complete()* *E785*
1655 Set the matches for Insert mode completion.
1656 Can only be used in Insert mode. You need to use a mapping
1657 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1658 or with an expression mapping.
1659 {startcol} is the byte offset in the line where the completed
1660 text start. The text up to the cursor is the original text
1661 that will be replaced by the matches. Use col('.') for an
1662 empty string. "col('.') - 1" will replace one character by a
1663 match.
1664 {matches} must be a |List|. Each |List| item is one match.
1665 See |complete-items| for the kind of items that are possible.
1666 "longest" in 'completeopt' is ignored.
1667 Note that the after calling this function you need to avoid
1668 inserting anything that would cause completion to stop.
1669 The match can be selected with CTRL-N and CTRL-P as usual with
1670 Insert mode completion. The popup menu will appear if
1671 specified, see |ins-completion-menu|.
1672 Example: >
1673 inoremap <F5> <C-R>=ListMonths()<CR>
1674
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001675 func ListMonths()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001676 call complete(col('.'), ['January', 'February', 'March',
1677 \ 'April', 'May', 'June', 'July', 'August', 'September',
1678 \ 'October', 'November', 'December'])
1679 return ''
1680 endfunc
1681< This isn't very useful, but it shows how it works. Note that
1682 an empty string is returned to avoid a zero being inserted.
1683
1684 Can also be used as a |method|, the base is passed as the
1685 second argument: >
1686 GetMatches()->complete(col('.'))
1687
1688complete_add({expr}) *complete_add()*
1689 Add {expr} to the list of matches. Only to be used by the
1690 function specified with the 'completefunc' option.
1691 Returns 0 for failure (empty string or out of memory),
1692 1 when the match was added, 2 when the match was already in
1693 the list.
1694 See |complete-functions| for an explanation of {expr}. It is
1695 the same as one item in the list that 'omnifunc' would return.
1696
1697 Can also be used as a |method|: >
1698 GetMoreMatches()->complete_add()
1699
1700complete_check() *complete_check()*
1701 Check for a key typed while looking for completion matches.
1702 This is to be used when looking for matches takes some time.
1703 Returns |TRUE| when searching for matches is to be aborted,
1704 zero otherwise.
1705 Only to be used by the function specified with the
1706 'completefunc' option.
1707
1708
1709complete_info([{what}]) *complete_info()*
1710 Returns a |Dictionary| with information about Insert mode
1711 completion. See |ins-completion|.
1712 The items are:
1713 mode Current completion mode name string.
1714 See |complete_info_mode| for the values.
1715 pum_visible |TRUE| if popup menu is visible.
1716 See |pumvisible()|.
1717 items List of completion matches. Each item is a
1718 dictionary containing the entries "word",
1719 "abbr", "menu", "kind", "info" and "user_data".
1720 See |complete-items|.
1721 selected Selected item index. First index is zero.
1722 Index is -1 if no item is selected (showing
1723 typed text only, or the last completion after
1724 no item is selected when using the <Up> or
1725 <Down> keys)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01001726 inserted Inserted string. [NOT IMPLEMENTED YET]
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001727
1728 *complete_info_mode*
1729 mode values are:
1730 "" Not in completion mode
1731 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1732 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1733 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1734 |i_CTRL-X_CTRL-Y|
1735 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1736 "files" File names |i_CTRL-X_CTRL-F|
1737 "tags" Tags |i_CTRL-X_CTRL-]|
1738 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1739 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1740 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1741 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1742 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1743 "function" User defined completion |i_CTRL-X_CTRL-U|
1744 "omni" Omni completion |i_CTRL-X_CTRL-O|
1745 "spell" Spelling suggestions |i_CTRL-X_s|
1746 "eval" |complete()| completion
1747 "unknown" Other internal modes
1748
1749 If the optional {what} list argument is supplied, then only
1750 the items listed in {what} are returned. Unsupported items in
1751 {what} are silently ignored.
1752
1753 To get the position and size of the popup menu, see
1754 |pum_getpos()|. It's also available in |v:event| during the
1755 |CompleteChanged| event.
1756
Bram Moolenaar016188f2022-06-06 20:52:59 +01001757 Returns an empty |Dictionary| on error.
1758
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001759 Examples: >
1760 " Get all items
1761 call complete_info()
1762 " Get only 'mode'
1763 call complete_info(['mode'])
1764 " Get only 'mode' and 'pum_visible'
1765 call complete_info(['mode', 'pum_visible'])
1766
1767< Can also be used as a |method|: >
1768 GetItems()->complete_info()
1769<
1770 *confirm()*
1771confirm({msg} [, {choices} [, {default} [, {type}]]])
1772 confirm() offers the user a dialog, from which a choice can be
1773 made. It returns the number of the choice. For the first
1774 choice this is 1.
1775 Note: confirm() is only supported when compiled with dialog
glepnirdf461152024-04-04 22:23:29 +02001776 support, see |+dialog_con| |+dialog_con_gui| and |+dialog_gui|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001777
1778 {msg} is displayed in a |dialog| with {choices} as the
1779 alternatives. When {choices} is missing or empty, "&OK" is
1780 used (and translated).
1781 {msg} is a String, use '\n' to include a newline. Only on
1782 some systems the string is wrapped when it doesn't fit.
1783
1784 {choices} is a String, with the individual choices separated
1785 by '\n', e.g. >
1786 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1787< The letter after the '&' is the shortcut key for that choice.
1788 Thus you can type 'c' to select "Cancel". The shortcut does
1789 not need to be the first letter: >
1790 confirm("file has been modified", "&Save\nSave &All")
1791< For the console, the first letter of each choice is used as
1792 the default shortcut key. Case is ignored.
1793
1794 The optional {default} argument is the number of the choice
1795 that is made if the user hits <CR>. Use 1 to make the first
1796 choice the default one. Use 0 to not set a default. If
1797 {default} is omitted, 1 is used.
1798
1799 The optional {type} String argument gives the type of dialog.
1800 This is only used for the icon of the GTK, Mac, Motif and
1801 Win32 GUI. It can be one of these values: "Error",
1802 "Question", "Info", "Warning" or "Generic". Only the first
1803 character is relevant. When {type} is omitted, "Generic" is
1804 used.
1805
1806 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1807 or another valid interrupt key, confirm() returns 0.
1808
1809 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01001810 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001811 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01001812 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001813 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001814 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001815 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001816 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001817 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01001818 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001819< In a GUI dialog, buttons are used. The layout of the buttons
1820 depends on the 'v' flag in 'guioptions'. If it is included,
1821 the buttons are always put vertically. Otherwise, confirm()
1822 tries to put the buttons in one horizontal line. If they
1823 don't fit, a vertical layout is used anyway. For some systems
1824 the horizontal layout is always used.
1825
1826 Can also be used as a |method|in: >
1827 BuildMessage()->confirm("&Yes\n&No")
1828<
1829 *copy()*
1830copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1831 different from using {expr} directly.
1832 When {expr} is a |List| a shallow copy is created. This means
1833 that the original |List| can be changed without changing the
1834 copy, and vice versa. But the items are identical, thus
1835 changing an item changes the contents of both |Lists|.
1836 A |Dictionary| is copied in a similar way as a |List|.
1837 Also see |deepcopy()|.
1838 Can also be used as a |method|: >
1839 mylist->copy()
1840
1841cos({expr}) *cos()*
1842 Return the cosine of {expr}, measured in radians, as a |Float|.
1843 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001844 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001845 Examples: >
1846 :echo cos(100)
1847< 0.862319 >
1848 :echo cos(-4.01)
1849< -0.646043
1850
1851 Can also be used as a |method|: >
1852 Compute()->cos()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001853
1854
1855cosh({expr}) *cosh()*
1856 Return the hyperbolic cosine of {expr} as a |Float| in the range
1857 [1, inf].
1858 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001859 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001860 Examples: >
1861 :echo cosh(0.5)
1862< 1.127626 >
1863 :echo cosh(-0.5)
1864< -1.127626
1865
1866 Can also be used as a |method|: >
1867 Compute()->cosh()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001868
1869
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07001870count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001871 Return the number of times an item with value {expr} appears
1872 in |String|, |List| or |Dictionary| {comp}.
1873
1874 If {start} is given then start with the item with this index.
1875 {start} can only be used with a |List|.
1876
1877 When {ic} is given and it's |TRUE| then case is ignored.
1878
1879 When {comp} is a string then the number of not overlapping
1880 occurrences of {expr} is returned. Zero is returned when
1881 {expr} is an empty string.
1882
1883 Can also be used as a |method|: >
1884 mylist->count(val)
1885<
1886 *cscope_connection()*
1887cscope_connection([{num} , {dbpath} [, {prepend}]])
1888 Checks for the existence of a |cscope| connection. If no
1889 parameters are specified, then the function returns:
1890 0, if cscope was not available (not compiled in), or
1891 if there are no cscope connections;
1892 1, if there is at least one cscope connection.
1893
1894 If parameters are specified, then the value of {num}
1895 determines how existence of a cscope connection is checked:
1896
1897 {num} Description of existence check
1898 ----- ------------------------------
1899 0 Same as no parameters (e.g., "cscope_connection()").
1900 1 Ignore {prepend}, and use partial string matches for
1901 {dbpath}.
1902 2 Ignore {prepend}, and use exact string matches for
1903 {dbpath}.
1904 3 Use {prepend}, use partial string matches for both
1905 {dbpath} and {prepend}.
1906 4 Use {prepend}, use exact string matches for both
1907 {dbpath} and {prepend}.
1908
1909 Note: All string comparisons are case sensitive!
1910
1911 Examples. Suppose we had the following (from ":cs show"): >
1912
1913 # pid database name prepend path
1914 0 27664 cscope.out /usr/local
1915<
1916 Invocation Return Val ~
1917 ---------- ---------- >
1918 cscope_connection() 1
1919 cscope_connection(1, "out") 1
1920 cscope_connection(2, "out") 0
1921 cscope_connection(3, "out") 0
1922 cscope_connection(3, "out", "local") 1
1923 cscope_connection(4, "out") 0
1924 cscope_connection(4, "out", "local") 0
1925 cscope_connection(4, "cscope.out", "/usr/local") 1
1926<
1927cursor({lnum}, {col} [, {off}]) *cursor()*
1928cursor({list})
1929 Positions the cursor at the column (byte count) {col} in the
1930 line {lnum}. The first column is one.
1931
1932 When there is one argument {list} this is used as a |List|
1933 with two, three or four item:
1934 [{lnum}, {col}]
1935 [{lnum}, {col}, {off}]
1936 [{lnum}, {col}, {off}, {curswant}]
1937 This is like the return value of |getpos()| or |getcurpos()|,
1938 but without the first item.
1939
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001940 To position the cursor using {col} as the character count, use
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001941 |setcursorcharpos()|.
1942
1943 Does not change the jumplist.
Bram Moolenaar7c6cd442022-10-11 21:54:04 +01001944 {lnum} is used like with |getline()|, except that if {lnum} is
1945 zero, the cursor will stay in the current line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001946 If {lnum} is greater than the number of lines in the buffer,
1947 the cursor will be positioned at the last line in the buffer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001948 If {col} is greater than the number of bytes in the line,
1949 the cursor will be positioned at the last character in the
1950 line.
1951 If {col} is zero, the cursor will stay in the current column.
1952 If {curswant} is given it is used to set the preferred column
1953 for vertical movement. Otherwise {col} is used.
1954
1955 When 'virtualedit' is used {off} specifies the offset in
1956 screen columns from the start of the character. E.g., a
1957 position within a <Tab> or after the last character.
1958 Returns 0 when the position could be set, -1 otherwise.
1959
1960 Can also be used as a |method|: >
1961 GetCursorPos()->cursor()
1962
1963debugbreak({pid}) *debugbreak()*
1964 Specifically used to interrupt a program being debugged. It
1965 will cause process {pid} to get a SIGTRAP. Behavior for other
1966 processes is undefined. See |terminal-debugger|.
1967 {only available on MS-Windows}
1968
Bram Moolenaar016188f2022-06-06 20:52:59 +01001969 Returns |TRUE| if successfully interrupted the program.
1970 Otherwise returns |FALSE|.
1971
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001972 Can also be used as a |method|: >
1973 GetPid()->debugbreak()
1974
1975deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
1976 Make a copy of {expr}. For Numbers and Strings this isn't
1977 different from using {expr} directly.
1978 When {expr} is a |List| a full copy is created. This means
1979 that the original |List| can be changed without changing the
1980 copy, and vice versa. When an item is a |List| or
1981 |Dictionary|, a copy for it is made, recursively. Thus
1982 changing an item in the copy does not change the contents of
1983 the original |List|.
1984 A |Dictionary| is copied in a similar way as a |List|.
1985
1986 When {noref} is omitted or zero a contained |List| or
1987 |Dictionary| is only copied once. All references point to
1988 this single copy. With {noref} set to 1 every occurrence of a
1989 |List| or |Dictionary| results in a new copy. This also means
1990 that a cyclic reference causes deepcopy() to fail.
1991 *E724*
1992 Nesting is possible up to 100 levels. When there is an item
1993 that refers back to a higher level making a deep copy with
1994 {noref} set to 1 will fail.
1995 Also see |copy()|.
1996
1997 Can also be used as a |method|: >
1998 GetObject()->deepcopy()
1999
2000delete({fname} [, {flags}]) *delete()*
2001 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002002 name {fname}.
2003
2004 This also works when {fname} is a symbolic link. The symbolic
2005 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002006
2007 When {flags} is "d": Deletes the directory by the name
2008 {fname}. This fails when directory {fname} is not empty.
2009
2010 When {flags} is "rf": Deletes the directory by the name
2011 {fname} and everything in it, recursively. BE CAREFUL!
2012 Note: on MS-Windows it is not possible to delete a directory
2013 that is being used.
2014
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002015 The result is a Number, which is 0/false if the delete
2016 operation was successful and -1/true when the deletion failed
2017 or partly failed.
2018
2019 Use |remove()| to delete an item from a |List|.
2020 To delete a line from the buffer use |:delete| or
2021 |deletebufline()|.
2022
2023 Can also be used as a |method|: >
2024 GetName()->delete()
2025
2026deletebufline({buf}, {first} [, {last}]) *deletebufline()*
2027 Delete lines {first} to {last} (inclusive) from buffer {buf}.
2028 If {last} is omitted then delete line {first} only.
2029 On success 0 is returned, on failure 1 is returned.
2030
2031 This function works only for loaded buffers. First call
2032 |bufload()| if needed.
2033
2034 For the use of {buf}, see |bufname()| above.
2035
2036 {first} and {last} are used like with |getline()|. Note that
2037 when using |line()| this refers to the current buffer. Use "$"
2038 to refer to the last line in buffer {buf}.
2039
2040 Can also be used as a |method|: >
2041 GetBuffer()->deletebufline(1)
2042<
2043 *did_filetype()*
2044did_filetype() Returns |TRUE| when autocommands are being executed and the
2045 FileType event has been triggered at least once. Can be used
2046 to avoid triggering the FileType event again in the scripts
2047 that detect the file type. |FileType|
2048 Returns |FALSE| when `:setf FALLBACK` was used.
2049 When editing another file, the counter is reset, thus this
2050 really checks if the FileType event has been triggered for the
2051 current buffer. This allows an autocommand that starts
2052 editing another buffer to set 'filetype' and load a syntax
2053 file.
2054
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002055diff({fromlist}, {tolist} [, {options}]) *diff()*
2056 Returns a String or a List containing the diff between the
2057 strings in {fromlist} and {tolist}. Uses the Vim internal
2058 diff library to compute the diff.
2059
2060 *E106*
2061 The optional "output" item in {options} specifies the returned
2062 diff format. The following values are supported:
2063 indices Return a List of the starting and ending
2064 indices and a count of the strings in each
2065 diff hunk.
2066 unified Return the unified diff output as a String.
2067 This is the default.
2068
2069 If the "output" item in {options} is "indices", then a List is
2070 returned. Each List item contains a Dict with the following
2071 items for each diff hunk:
2072 from_idx start index in {fromlist} for this diff hunk.
2073 from_count number of strings in {fromlist} that are
2074 added/removed/modified in this diff hunk.
2075 to_idx start index in {tolist} for this diff hunk.
2076 to_count number of strings in {tolist} that are
2077 added/removed/modified in this diff hunk.
2078
2079 The {options} Dict argument also specifies diff options
2080 (similar to 'diffopt') and supports the following items:
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002081 algorithm Dict specifying the diff algorithm to
2082 use. Supported boolean items are
2083 "myers", "minimal", "patience" and
2084 "histogram".
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002085 context diff context length. Default is 0.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002086 iblank ignore changes where lines are all
2087 blank.
2088 icase ignore changes in case of text.
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002089 indent-heuristic use the indent heuristic for the
2090 internal diff library.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002091 iwhite ignore changes in amount of white
2092 space.
2093 iwhiteall ignore all white space changes.
2094 iwhiteeol ignore white space changes at end of
2095 line.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002096 For more information about these options, refer to 'diffopt'.
2097
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002098 To compute the unified diff, all the items in {fromlist} are
2099 concatenated into a string using a newline separator and the
2100 same for {tolist}. The unified diff output uses line numbers.
2101
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002102 Returns an empty List or String if {fromlist} and {tolist} are
2103 identical.
2104
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002105 Examples: >
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002106 :echo diff(['abc'], ['xxx'])
2107 @@ -1 +1 @@
2108 -abc
2109 +xxx
2110
2111 :echo diff(['abc'], ['xxx'], {'output': 'indices'})
2112 [{'from_idx': 0, 'from_count': 1, 'to_idx': 0, 'to_count': 1}]
2113 :echo diff(readfile('oldfile'), readfile('newfile'))
2114 :echo diff(getbufline(5, 1, '$'), getbufline(6, 1, '$'))
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002115<
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002116 For more examples, refer to |diff-func-examples|
2117
2118 Can also be used as a |method|: >
2119 GetFromList->diff(to_list)
2120<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002121diff_filler({lnum}) *diff_filler()*
2122 Returns the number of filler lines above line {lnum}.
2123 These are the lines that were inserted at this point in
2124 another diff'ed window. These filler lines are shown in the
2125 display but don't exist in the buffer.
2126 {lnum} is used like with |getline()|. Thus "." is the current
2127 line, "'m" mark m, etc.
2128 Returns 0 if the current window is not in diff mode.
2129
2130 Can also be used as a |method|: >
2131 GetLnum()->diff_filler()
2132
2133diff_hlID({lnum}, {col}) *diff_hlID()*
2134 Returns the highlight ID for diff mode at line {lnum} column
2135 {col} (byte index). When the current line does not have a
2136 diff change zero is returned.
2137 {lnum} is used like with |getline()|. Thus "." is the current
2138 line, "'m" mark m, etc.
2139 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2140 line.
2141 The highlight ID can be used with |synIDattr()| to obtain
2142 syntax information about the highlighting.
2143
2144 Can also be used as a |method|: >
2145 GetLnum()->diff_hlID(col)
2146<
2147
2148digraph_get({chars}) *digraph_get()* *E1214*
2149 Return the digraph of {chars}. This should be a string with
2150 exactly two characters. If {chars} are not just two
2151 characters, or the digraph of {chars} does not exist, an error
2152 is given and an empty string is returned.
2153
2154 The character will be converted from Unicode to 'encoding'
2155 when needed. This does require the conversion to be
2156 available, it might fail.
2157
2158 Also see |digraph_getlist()|.
2159
2160 Examples: >
2161 " Get a built-in digraph
2162 :echo digraph_get('00') " Returns '∞'
2163
2164 " Get a user-defined digraph
2165 :call digraph_set('aa', 'あ')
2166 :echo digraph_get('aa') " Returns 'あ'
2167<
2168 Can also be used as a |method|: >
2169 GetChars()->digraph_get()
2170<
2171 This function works only when compiled with the |+digraphs|
2172 feature. If this feature is disabled, this function will
2173 display an error message.
2174
2175
2176digraph_getlist([{listall}]) *digraph_getlist()*
2177 Return a list of digraphs. If the {listall} argument is given
2178 and it is TRUE, return all digraphs, including the default
2179 digraphs. Otherwise, return only user-defined digraphs.
2180
2181 The characters will be converted from Unicode to 'encoding'
2182 when needed. This does require the conservation to be
2183 available, it might fail.
2184
2185 Also see |digraph_get()|.
2186
2187 Examples: >
2188 " Get user-defined digraphs
2189 :echo digraph_getlist()
2190
2191 " Get all the digraphs, including default digraphs
2192 :echo digraph_getlist(1)
2193<
2194 Can also be used as a |method|: >
2195 GetNumber()->digraph_getlist()
2196<
2197 This function works only when compiled with the |+digraphs|
2198 feature. If this feature is disabled, this function will
2199 display an error message.
2200
2201
Bram Moolenaara2baa732022-02-04 16:09:54 +00002202digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002203 Add digraph {chars} to the list. {chars} must be a string
2204 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002205 encoded character. *E1215*
2206 Be careful, composing characters are NOT ignored. This
2207 function is similar to |:digraphs| command, but useful to add
2208 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002209
2210 The function result is v:true if |digraph| is registered. If
2211 this fails an error message is given and v:false is returned.
2212
2213 If you want to define multiple digraphs at once, you can use
2214 |digraph_setlist()|.
2215
2216 Example: >
2217 call digraph_set(' ', 'あ')
2218<
2219 Can be used as a |method|: >
2220 GetString()->digraph_set('あ')
2221<
2222 This function works only when compiled with the |+digraphs|
2223 feature. If this feature is disabled, this function will
2224 display an error message.
2225
2226
2227digraph_setlist({digraphlist}) *digraph_setlist()*
2228 Similar to |digraph_set()| but this function can add multiple
2229 digraphs at once. {digraphlist} is a list composed of lists,
2230 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002231 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002232 Example: >
2233 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2234<
2235 It is similar to the following: >
2236 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2237 call digraph_set(chars, digraph)
2238 endfor
2239< Except that the function returns after the first error,
2240 following digraphs will not be added.
2241
2242 Can be used as a |method|: >
2243 GetList()->digraph_setlist()
2244<
2245 This function works only when compiled with the |+digraphs|
2246 feature. If this feature is disabled, this function will
2247 display an error message.
2248
2249
2250echoraw({string}) *echoraw()*
2251 Output {string} as-is, including unprintable characters.
2252 This can be used to output a terminal code. For example, to
2253 disable modifyOtherKeys: >
2254 call echoraw(&t_TE)
2255< and to enable it again: >
2256 call echoraw(&t_TI)
2257< Use with care, you can mess up the terminal this way.
2258
2259
2260empty({expr}) *empty()*
2261 Return the Number 1 if {expr} is empty, zero otherwise.
2262 - A |List| or |Dictionary| is empty when it does not have any
2263 items.
2264 - A |String| is empty when its length is zero.
2265 - A |Number| and |Float| are empty when their value is zero.
2266 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2267 - A |Job| is empty when it failed to start.
2268 - A |Channel| is empty when it is closed.
2269 - A |Blob| is empty when its length is zero.
mityu7f0bba22024-03-29 10:14:41 +01002270 - An |Object| is empty, when the empty() method in the object
2271 (if present) returns true. |object-empty()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002272
2273 For a long |List| this is much faster than comparing the
2274 length with zero.
2275
2276 Can also be used as a |method|: >
2277 mylist->empty()
2278
2279environ() *environ()*
2280 Return all of environment variables as dictionary. You can
2281 check if an environment variable exists like this: >
2282 :echo has_key(environ(), 'HOME')
2283< Note that the variable name may be CamelCase; to ignore case
2284 use this: >
2285 :echo index(keys(environ()), 'HOME', 0, 1) != -1
2286
Bram Moolenaar416bd912023-07-07 23:19:18 +01002287
2288err_teapot([{expr}]) *err_teapot()*
2289 Produce an error with number 418, needed for implementation of
Christian Brabandtee17b6f2023-09-09 11:23:50 +02002290 RFC 2324.
Bram Moolenaar416bd912023-07-07 23:19:18 +01002291 If {expr} is present and it is TRUE error 503 is given,
2292 indicating that coffee is temporarily not available.
2293 If {expr} is present it must be a String.
2294
2295
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002296escape({string}, {chars}) *escape()*
2297 Escape the characters in {chars} that occur in {string} with a
2298 backslash. Example: >
2299 :echo escape('c:\program files\vim', ' \')
2300< results in: >
2301 c:\\program\ files\\vim
2302< Also see |shellescape()| and |fnameescape()|.
2303
2304 Can also be used as a |method|: >
2305 GetText()->escape(' \')
2306<
2307 *eval()*
2308eval({string}) Evaluate {string} and return the result. Especially useful to
2309 turn the result of |string()| back into the original value.
2310 This works for Numbers, Floats, Strings, Blobs and composites
2311 of them. Also works for |Funcref|s that refer to existing
Aliaksei Budavei95740222024-04-04 23:05:33 +03002312 functions. In |Vim9| script, it can be used to obtain |enum|
2313 values from their fully qualified names.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002314
2315 Can also be used as a |method|: >
2316 argv->join()->eval()
2317
2318eventhandler() *eventhandler()*
2319 Returns 1 when inside an event handler. That is that Vim got
2320 interrupted while waiting for the user to type a character,
2321 e.g., when dropping a file on Vim. This means interactive
2322 commands cannot be used. Otherwise zero is returned.
2323
2324executable({expr}) *executable()*
2325 This function checks if an executable with the name {expr}
2326 exists. {expr} must be the name of the program without any
2327 arguments.
2328 executable() uses the value of $PATH and/or the normal
2329 searchpath for programs. *PATHEXT*
2330 On MS-Windows the ".exe", ".bat", etc. can optionally be
2331 included. Then the extensions in $PATHEXT are tried. Thus if
2332 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2333 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2334 by itself can be used in $PATHEXT to try using the name
2335 without an extension. When 'shell' looks like a Unix shell,
2336 then the name is also tried without adding an extension.
2337 On MS-Windows it only checks if the file exists and is not a
2338 directory, not if it's really executable.
2339 On MS-Windows an executable in the same directory as Vim is
Yasuhiro Matsumoto05cf63e2022-05-03 11:02:28 +01002340 normally found. Since this directory is added to $PATH it
2341 should also work to execute it |win32-PATH|. This can be
2342 disabled by setting the $NoDefaultCurrentDirectoryInExePath
2343 environment variable. *NoDefaultCurrentDirectoryInExePath*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002344 The result is a Number:
2345 1 exists
2346 0 does not exist
2347 -1 not implemented on this system
2348 |exepath()| can be used to get the full path of an executable.
2349
2350 Can also be used as a |method|: >
2351 GetCommand()->executable()
2352
2353execute({command} [, {silent}]) *execute()*
2354 Execute an Ex command or commands and return the output as a
2355 string.
2356 {command} can be a string or a List. In case of a List the
2357 lines are executed one by one.
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002358 This is more or less equivalent to: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002359 redir => var
2360 {command}
2361 redir END
Bram Moolenaar71badf92023-04-22 22:40:14 +01002362< Except that line continuation in {command} is not recognized.
2363
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002364 The optional {silent} argument can have these values:
2365 "" no `:silent` used
2366 "silent" `:silent` used
2367 "silent!" `:silent!` used
2368 The default is "silent". Note that with "silent!", unlike
2369 `:redir`, error messages are dropped. When using an external
2370 command the screen may be messed up, use `system()` instead.
2371 *E930*
2372 It is not possible to use `:redir` anywhere in {command}.
2373
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002374 To get a list of lines use `split()` on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002375 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002376
2377< To execute a command in another window than the current one
2378 use `win_execute()`.
2379
2380 When used recursively the output of the recursive call is not
2381 included in the output of the higher level call.
2382
2383 Can also be used as a |method|: >
2384 GetCommand()->execute()
2385
2386exepath({expr}) *exepath()*
2387 If {expr} is an executable and is either an absolute path, a
2388 relative path or found in $PATH, return the full path.
2389 Note that the current directory is used when {expr} starts
2390 with "./", which may be a problem for Vim: >
2391 echo exepath(v:progpath)
2392< If {expr} cannot be found in $PATH or is not executable then
2393 an empty string is returned.
2394
2395 Can also be used as a |method|: >
2396 GetCommand()->exepath()
2397<
2398 *exists()*
2399exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
2400 zero otherwise.
2401
2402 Note: In a compiled |:def| function the evaluation is done at
2403 runtime. Use `exists_compiled()` to evaluate the expression
2404 at compile time.
2405
2406 For checking for a supported feature use |has()|.
2407 For checking if a file exists use |filereadable()|.
2408
2409 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002410 varname internal variable (see
2411 dict.key |internal-variables|). Also works
2412 list[i] for |curly-braces-names|, |Dictionary|
Yegappan Lakshmanana2ebb6e2024-02-25 08:40:10 +01002413 import.Func entries, |List| items, class and
2414 class.Func object methods, imported items, etc.
2415 object.Func Does not work for local variables in a
2416 class.varname compiled `:def` function.
2417 object.varname Also works for a function in |Vim9|
Bram Moolenaar944697a2022-02-20 19:48:20 +00002418 script, since it can be used as a
2419 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002420 Beware that evaluating an index may
2421 cause an error message for an invalid
2422 expression. E.g.: >
2423 :let l = [1, 2, 3]
2424 :echo exists("l[5]")
2425< 0 >
2426 :echo exists("l[xx]")
2427< E121: Undefined variable: xx
2428 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002429 &option-name Vim option (only checks if it exists,
2430 not if it really works)
2431 +option-name Vim option that works.
2432 $ENVNAME environment variable (could also be
2433 done by comparing with an empty
2434 string)
2435 *funcname built-in function (see |functions|)
2436 or user defined function (see
2437 |user-functions|) that is implemented.
2438 Also works for a variable that is a
2439 Funcref.
2440 ?funcname built-in function that could be
2441 implemented; to be used to check if
2442 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002443 :cmdname Ex command: built-in command, user
2444 command or command modifier |:command|.
2445 Returns:
2446 1 for match with start of a command
2447 2 full match with a command
2448 3 matches several user commands
2449 To check for a supported command
2450 always check the return value to be 2.
2451 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002452 :3match The |:3match| command (but you
2453 probably should not use it, it is
2454 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002455 #event autocommand defined for this event
2456 #event#pattern autocommand defined for this event and
2457 pattern (the pattern is taken
2458 literally and compared to the
2459 autocommand patterns character by
2460 character)
2461 #group autocommand group exists
2462 #group#event autocommand defined for this group and
2463 event.
2464 #group#event#pattern
2465 autocommand defined for this group,
2466 event and pattern.
2467 ##event autocommand for this event is
2468 supported.
2469
2470 Examples: >
2471 exists("&shortname")
2472 exists("$HOSTNAME")
2473 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002474 exists("*s:MyFunc") " only for legacy script
2475 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002476 exists("bufcount")
2477 exists(":Make")
2478 exists("#CursorHold")
2479 exists("#BufReadPre#*.gz")
2480 exists("#filetypeindent")
2481 exists("#filetypeindent#FileType")
2482 exists("#filetypeindent#FileType#*")
2483 exists("##ColorScheme")
2484< There must be no space between the symbol (&/$/*/#) and the
2485 name.
2486 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002487 a few cases this is ignored. That may become stricter in the
2488 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002489 Working example: >
2490 exists(":make")
2491< NOT working example: >
2492 exists(":make install")
2493
2494< Note that the argument must be a string, not the name of the
2495 variable itself. For example: >
2496 exists(bufcount)
2497< This doesn't check for existence of the "bufcount" variable,
2498 but gets the value of "bufcount", and checks if that exists.
2499
2500 Can also be used as a |method|: >
2501 Varname()->exists()
2502<
2503
2504exists_compiled({expr}) *exists_compiled()*
2505 Like `exists()` but evaluated at compile time. This is useful
2506 to skip a block where a function is used that would otherwise
2507 give an error: >
2508 if exists_compiled('*ThatFunction')
2509 ThatFunction('works')
2510 endif
2511< If `exists()` were used then a compilation error would be
2512 given if ThatFunction() is not defined.
2513
2514 {expr} must be a literal string. *E1232*
2515 Can only be used in a |:def| function. *E1233*
2516 This does not work to check for arguments or local variables.
2517
2518
2519exp({expr}) *exp()*
2520 Return the exponential of {expr} as a |Float| in the range
2521 [0, inf].
2522 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002523 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002524 Examples: >
2525 :echo exp(2)
2526< 7.389056 >
2527 :echo exp(-1)
2528< 0.367879
2529
2530 Can also be used as a |method|: >
2531 Compute()->exp()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002532
2533
2534expand({string} [, {nosuf} [, {list}]]) *expand()*
2535 Expand wildcards and the following special keywords in
2536 {string}. 'wildignorecase' applies.
2537
2538 If {list} is given and it is |TRUE|, a List will be returned.
2539 Otherwise the result is a String and when there are several
2540 matches, they are separated by <NL> characters. [Note: in
2541 version 5.0 a space was used, which caused problems when a
2542 file name contains a space]
2543
2544 If the expansion fails, the result is an empty string. A name
2545 for a non-existing file is not included, unless {string} does
2546 not start with '%', '#' or '<', see below.
2547
Christian Brabandtec9c3262024-02-21 20:40:05 +01002548 For a |:terminal| window '%' expands to a '!' followed by
h-east53753f62024-05-05 18:42:31 +02002549 the command or shell that is run. |terminal-bufname|
Christian Brabandtec9c3262024-02-21 20:40:05 +01002550
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002551 When {string} starts with '%', '#' or '<', the expansion is
2552 done like for the |cmdline-special| variables with their
2553 associated modifiers. Here is a short overview:
2554
2555 % current file name
2556 # alternate file name
2557 #n alternate file name n
2558 <cfile> file name under the cursor
2559 <afile> autocmd file name
2560 <abuf> autocmd buffer number (as a String!)
2561 <amatch> autocmd matched name
2562 <cexpr> C expression under the cursor
2563 <sfile> sourced script file or function name
2564 <slnum> sourced script line number or function
2565 line number
2566 <sflnum> script file line number, also when in
2567 a function
2568 <SID> "<SNR>123_" where "123" is the
2569 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002570 <script> sourced script file, or script file
2571 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002572 <stack> call stack
2573 <cword> word under the cursor
2574 <cWORD> WORD under the cursor
2575 <client> the {clientid} of the last received
2576 message |server2client()|
2577 Modifiers:
2578 :p expand to full path
2579 :h head (last path component removed)
2580 :t tail (last path component only)
2581 :r root (one extension removed)
2582 :e extension only
2583
2584 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002585 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002586< Note that when expanding a string that starts with '%', '#' or
2587 '<', any following text is ignored. This does NOT work: >
2588 :let doesntwork = expand("%:h.bak")
2589< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002590 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002591< Also note that expanding "<cfile>" and others only returns the
2592 referenced file name without further expansion. If "<cfile>"
2593 is "~/.cshrc", you need to do another expand() to have the
2594 "~/" expanded into the path of the home directory: >
2595 :echo expand(expand("<cfile>"))
2596<
2597 There cannot be white space between the variables and the
2598 following modifier. The |fnamemodify()| function can be used
2599 to modify normal file names.
2600
2601 When using '%' or '#', and the current or alternate file name
2602 is not defined, an empty string is used. Using "%:p" in a
2603 buffer with no name, results in the current directory, with a
2604 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01002605 When 'verbose' is set then expanding '%', '#' and <> items
2606 will result in an error message if the argument cannot be
2607 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002608
2609 When {string} does not start with '%', '#' or '<', it is
2610 expanded like a file name is expanded on the command line.
2611 'suffixes' and 'wildignore' are used, unless the optional
2612 {nosuf} argument is given and it is |TRUE|.
2613 Names for non-existing files are included. The "**" item can
2614 be used to search in a directory tree. For example, to find
2615 all "README" files in the current directory and below: >
2616 :echo expand("**/README")
2617<
2618 expand() can also be used to expand variables and environment
2619 variables that are only known in a shell. But this can be
2620 slow, because a shell may be used to do the expansion. See
2621 |expr-env-expand|.
2622 The expanded variable is still handled like a list of file
2623 names. When an environment variable cannot be expanded, it is
2624 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2625 "$FOOBAR".
2626
2627 See |glob()| for finding existing files. See |system()| for
2628 getting the raw output of an external command.
2629
2630 Can also be used as a |method|: >
2631 Getpattern()->expand()
2632
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002633expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002634 Expand special items in String {string} like what is done for
2635 an Ex command such as `:edit`. This expands special keywords,
2636 like with |expand()|, and environment variables, anywhere in
2637 {string}. "~user" and "~/path" are only expanded at the
2638 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002639
2640 The following items are supported in the {options} Dict
2641 argument:
2642 errmsg If set to TRUE, error messages are displayed
2643 if an error is encountered during expansion.
2644 By default, error messages are not displayed.
2645
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002646 Returns the expanded string. If an error is encountered
2647 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002648
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002649 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002650 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002651 make /path/runtime/doc/builtin.o
2652 :echo expandcmd('make %<.o', {'errmsg': v:true})
2653<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002654 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002655 GetCommand()->expandcmd()
2656<
2657extend({expr1}, {expr2} [, {expr3}]) *extend()*
2658 {expr1} and {expr2} must be both |Lists| or both
2659 |Dictionaries|.
2660
2661 If they are |Lists|: Append {expr2} to {expr1}.
2662 If {expr3} is given insert the items of {expr2} before the
2663 item with index {expr3} in {expr1}. When {expr3} is zero
2664 insert before the first item. When {expr3} is equal to
2665 len({expr1}) then {expr2} is appended.
2666 Examples: >
2667 :echo sort(extend(mylist, [7, 5]))
2668 :call extend(mylist, [2, 3], 1)
2669< When {expr1} is the same List as {expr2} then the number of
2670 items copied is equal to the original length of the List.
2671 E.g., when {expr3} is 1 you get N new copies of the first item
2672 (where N is the original length of the List).
2673 Use |add()| to concatenate one item to a list. To concatenate
2674 two lists into a new list use the + operator: >
2675 :let newlist = [1, 2, 3] + [4, 5]
2676<
2677 If they are |Dictionaries|:
2678 Add all entries from {expr2} to {expr1}.
2679 If a key exists in both {expr1} and {expr2} then {expr3} is
2680 used to decide what to do:
2681 {expr3} = "keep": keep the value of {expr1}
2682 {expr3} = "force": use the value of {expr2}
2683 {expr3} = "error": give an error message *E737*
2684 When {expr3} is omitted then "force" is assumed.
2685
2686 {expr1} is changed when {expr2} is not empty. If necessary
2687 make a copy of {expr1} first.
2688 {expr2} remains unchanged.
2689 When {expr1} is locked and {expr2} is not empty the operation
2690 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002691 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002692
2693 Can also be used as a |method|: >
2694 mylist->extend(otherlist)
2695
2696
2697extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2698 Like |extend()| but instead of adding items to {expr1} a new
2699 List or Dictionary is created and returned. {expr1} remains
Bram Moolenaardd60c362023-02-27 15:49:53 +00002700 unchanged.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002701
2702
2703feedkeys({string} [, {mode}]) *feedkeys()*
2704 Characters in {string} are queued for processing as if they
2705 come from a mapping or were typed by the user.
2706
2707 By default the string is added to the end of the typeahead
2708 buffer, thus if a mapping is still being executed the
2709 characters come after them. Use the 'i' flag to insert before
2710 other characters, they will be executed next, before any
2711 characters from a mapping.
2712
2713 The function does not wait for processing of keys contained in
2714 {string}.
2715
2716 To include special keys into {string}, use double-quotes
2717 and "\..." notation |expr-quote|. For example,
2718 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2719 feedkeys('\<CR>') pushes 5 characters.
2720 A special code that might be useful is <Ignore>, it exits the
2721 wait for a character without doing anything. *<Ignore>*
2722
2723 {mode} is a String, which can contain these character flags:
2724 'm' Remap keys. This is default. If {mode} is absent,
2725 keys are remapped.
2726 'n' Do not remap keys.
2727 't' Handle keys as if typed; otherwise they are handled as
2728 if coming from a mapping. This matters for undo,
2729 opening folds, etc.
2730 'L' Lowlevel input. Only works for Unix or when using the
2731 GUI. Keys are used as if they were coming from the
2732 terminal. Other flags are not used. *E980*
2733 When a CTRL-C interrupts and 't' is included it sets
2734 the internal "got_int" flag.
2735 'i' Insert the string instead of appending (see above).
2736 'x' Execute commands until typeahead is empty. This is
2737 similar to using ":normal!". You can call feedkeys()
2738 several times without 'x' and then one time with 'x'
2739 (possibly with an empty {string}) to execute all the
2740 typeahead. Note that when Vim ends in Insert mode it
2741 will behave as if <Esc> is typed, to avoid getting
2742 stuck, waiting for a character to be typed before the
2743 script continues.
2744 Note that if you manage to call feedkeys() while
2745 executing commands, thus calling it recursively, then
2746 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00002747 'c' Remove any script context when executing, so that
2748 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01002749 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01002750 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002751 '!' When used with 'x' will not end Insert mode. Can be
2752 used in a test when a timer is set to exit Insert mode
2753 a little later. Useful for testing CursorHoldI.
2754
2755 Return value is always 0.
2756
2757 Can also be used as a |method|: >
2758 GetInput()->feedkeys()
2759
2760filereadable({file}) *filereadable()*
2761 The result is a Number, which is |TRUE| when a file with the
2762 name {file} exists, and can be read. If {file} doesn't exist,
2763 or is a directory, the result is |FALSE|. {file} is any
2764 expression, which is used as a String.
2765 If you don't care about the file being readable you can use
2766 |glob()|.
2767 {file} is used as-is, you may want to expand wildcards first: >
2768 echo filereadable('~/.vimrc')
2769 0
2770 echo filereadable(expand('~/.vimrc'))
2771 1
2772
2773< Can also be used as a |method|: >
2774 GetName()->filereadable()
2775< *file_readable()*
2776 Obsolete name: file_readable().
2777
2778
2779filewritable({file}) *filewritable()*
2780 The result is a Number, which is 1 when a file with the
2781 name {file} exists, and can be written. If {file} doesn't
2782 exist, or is not writable, the result is 0. If {file} is a
2783 directory, and we can write to it, the result is 2.
2784
2785 Can also be used as a |method|: >
2786 GetName()->filewritable()
2787
2788
2789filter({expr1}, {expr2}) *filter()*
2790 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
2791 For each item in {expr1} evaluate {expr2} and when the result
2792 is zero or false remove the item from the |List| or
2793 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002794 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002795
2796 {expr2} must be a |string| or |Funcref|.
2797
2798 If {expr2} is a |string|, inside {expr2} |v:val| has the value
2799 of the current item. For a |Dictionary| |v:key| has the key
2800 of the current item and for a |List| |v:key| has the index of
2801 the current item. For a |Blob| |v:key| has the index of the
2802 current byte. For a |String| |v:key| has the index of the
2803 current character.
2804 Examples: >
2805 call filter(mylist, 'v:val !~ "OLD"')
2806< Removes the items where "OLD" appears. >
2807 call filter(mydict, 'v:key >= 8')
2808< Removes the items with a key below 8. >
2809 call filter(var, 0)
2810< Removes all the items, thus clears the |List| or |Dictionary|.
2811
2812 Note that {expr2} is the result of expression and is then
2813 used as an expression again. Often it is good to use a
2814 |literal-string| to avoid having to double backslashes.
2815
2816 If {expr2} is a |Funcref| it must take two arguments:
2817 1. the key or the index of the current item.
2818 2. the value of the current item.
2819 The function must return |TRUE| if the item should be kept.
2820 Example that keeps the odd items of a list: >
2821 func Odd(idx, val)
2822 return a:idx % 2 == 1
2823 endfunc
2824 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002825< It is shorter when using a |lambda|. In |Vim9| syntax: >
2826 call filter(myList, (idx, val) => idx * val <= 42)
2827< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002828 call filter(myList, {idx, val -> idx * val <= 42})
2829< If you do not use "val" you can leave it out: >
2830 call filter(myList, {idx -> idx % 2 == 1})
2831<
2832 In |Vim9| script the result must be true, false, zero or one.
2833 Other values will result in a type error.
2834
2835 For a |List| and a |Dictionary| the operation is done
2836 in-place. If you want it to remain unmodified make a copy
2837 first: >
2838 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2839
2840< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00002841 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002842 When an error is encountered while evaluating {expr2} no
2843 further items in {expr1} are processed.
2844 When {expr2} is a Funcref errors inside a function are ignored,
2845 unless it was defined with the "abort" flag.
2846
2847 Can also be used as a |method|: >
2848 mylist->filter(expr2)
2849
2850finddir({name} [, {path} [, {count}]]) *finddir()*
2851 Find directory {name} in {path}. Supports both downwards and
2852 upwards recursive directory searches. See |file-searching|
2853 for the syntax of {path}.
2854
2855 Returns the path of the first found match. When the found
2856 directory is below the current directory a relative path is
2857 returned. Otherwise a full path is returned.
2858 If {path} is omitted or empty then 'path' is used.
2859
2860 If the optional {count} is given, find {count}'s occurrence of
2861 {name} in {path} instead of the first one.
2862 When {count} is negative return all the matches in a |List|.
2863
Bram Moolenaar016188f2022-06-06 20:52:59 +01002864 Returns an empty string if the directory is not found.
2865
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002866 This is quite similar to the ex-command `:find`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002867
2868 Can also be used as a |method|: >
2869 GetName()->finddir()
2870
2871findfile({name} [, {path} [, {count}]]) *findfile()*
2872 Just like |finddir()|, but find a file instead of a directory.
2873 Uses 'suffixesadd'.
2874 Example: >
2875 :echo findfile("tags.vim", ".;")
2876< Searches from the directory of the current file upwards until
2877 it finds the file "tags.vim".
2878
2879 Can also be used as a |method|: >
2880 GetName()->findfile()
2881
2882flatten({list} [, {maxdepth}]) *flatten()*
2883 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
2884 the result is a |List| without nesting, as if {maxdepth} is
2885 a very large number.
2886 The {list} is changed in place, use |flattennew()| if you do
2887 not want that.
2888 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00002889 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002890 *E900*
2891 {maxdepth} means how deep in nested lists changes are made.
2892 {list} is not modified when {maxdepth} is 0.
2893 {maxdepth} must be positive number.
2894
2895 If there is an error the number zero is returned.
2896
2897 Example: >
2898 :echo flatten([1, [2, [3, 4]], 5])
2899< [1, 2, 3, 4, 5] >
2900 :echo flatten([1, [2, [3, 4]], 5], 1)
2901< [1, 2, [3, 4], 5]
2902
2903 Can also be used as a |method|: >
2904 mylist->flatten()
2905<
2906flattennew({list} [, {maxdepth}]) *flattennew()*
2907 Like |flatten()| but first make a copy of {list}.
2908
2909
2910float2nr({expr}) *float2nr()*
2911 Convert {expr} to a Number by omitting the part after the
2912 decimal point.
Bram Moolenaar76db9e02022-11-09 21:21:04 +00002913 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002914 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002915 When the value of {expr} is out of range for a |Number| the
2916 result is truncated to 0x7fffffff or -0x7fffffff (or when
2917 64-bit Number support is enabled, 0x7fffffffffffffff or
2918 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
2919 64-bit Number support is enabled, -0x8000000000000000).
2920 Examples: >
2921 echo float2nr(3.95)
2922< 3 >
2923 echo float2nr(-23.45)
2924< -23 >
2925 echo float2nr(1.0e100)
2926< 2147483647 (or 9223372036854775807) >
2927 echo float2nr(-1.0e150)
2928< -2147483647 (or -9223372036854775807) >
2929 echo float2nr(1.0e-100)
2930< 0
2931
2932 Can also be used as a |method|: >
2933 Compute()->float2nr()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002934
2935
2936floor({expr}) *floor()*
2937 Return the largest integral value less than or equal to
2938 {expr} as a |Float| (round down).
2939 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002940 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002941 Examples: >
2942 echo floor(1.856)
2943< 1.0 >
2944 echo floor(-5.456)
2945< -6.0 >
2946 echo floor(4.0)
2947< 4.0
2948
2949 Can also be used as a |method|: >
2950 Compute()->floor()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002951
2952
2953fmod({expr1}, {expr2}) *fmod()*
2954 Return the remainder of {expr1} / {expr2}, even if the
2955 division is not representable. Returns {expr1} - i * {expr2}
2956 for some integer i such that if {expr2} is non-zero, the
2957 result has the same sign as {expr1} and magnitude less than
2958 the magnitude of {expr2}. If {expr2} is zero, the value
2959 returned is zero. The value returned is a |Float|.
2960 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002961 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
2962 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002963 Examples: >
2964 :echo fmod(12.33, 1.22)
2965< 0.13 >
2966 :echo fmod(-12.33, 1.22)
2967< -0.13
2968
2969 Can also be used as a |method|: >
2970 Compute()->fmod(1.22)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002971
2972
2973fnameescape({string}) *fnameescape()*
2974 Escape {string} for use as file name command argument. All
2975 characters that have a special meaning, such as '%' and '|'
2976 are escaped with a backslash.
2977 For most systems the characters escaped are
2978 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2979 appears in a filename, it depends on the value of 'isfname'.
2980 A leading '+' and '>' is also escaped (special after |:edit|
2981 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01002982 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002983 Example: >
2984 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002985 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002986< results in executing: >
2987 edit \+some\ str\%nge\|name
2988<
2989 Can also be used as a |method|: >
2990 GetName()->fnameescape()
2991
2992fnamemodify({fname}, {mods}) *fnamemodify()*
2993 Modify file name {fname} according to {mods}. {mods} is a
2994 string of characters like it is used for file names on the
2995 command line. See |filename-modifiers|.
2996 Example: >
2997 :echo fnamemodify("main.c", ":p:h")
2998< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01002999 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01003000< If {mods} is empty or an unsupported modifier is used then
3001 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01003002 When {fname} is empty then with {mods} ":h" returns ".", so
3003 that `:cd` can be used with it. This is different from
3004 expand('%:h') without a buffer name, which returns an empty
3005 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003006 Note: Environment variables don't work in {fname}, use
3007 |expand()| first then.
3008
3009 Can also be used as a |method|: >
3010 GetName()->fnamemodify(':p:h')
3011
3012foldclosed({lnum}) *foldclosed()*
3013 The result is a Number. If the line {lnum} is in a closed
3014 fold, the result is the number of the first line in that fold.
3015 If the line {lnum} is not in a closed fold, -1 is returned.
3016 {lnum} is used like with |getline()|. Thus "." is the current
3017 line, "'m" mark m, etc.
3018
3019 Can also be used as a |method|: >
3020 GetLnum()->foldclosed()
3021
3022foldclosedend({lnum}) *foldclosedend()*
3023 The result is a Number. If the line {lnum} is in a closed
3024 fold, the result is the number of the last line in that fold.
3025 If the line {lnum} is not in a closed fold, -1 is returned.
3026 {lnum} is used like with |getline()|. Thus "." is the current
3027 line, "'m" mark m, etc.
3028
3029 Can also be used as a |method|: >
3030 GetLnum()->foldclosedend()
3031
3032foldlevel({lnum}) *foldlevel()*
3033 The result is a Number, which is the foldlevel of line {lnum}
3034 in the current buffer. For nested folds the deepest level is
3035 returned. If there is no fold at line {lnum}, zero is
3036 returned. It doesn't matter if the folds are open or closed.
3037 When used while updating folds (from 'foldexpr') -1 is
3038 returned for lines where folds are still to be updated and the
3039 foldlevel is unknown. As a special case the level of the
3040 previous line is usually available.
3041 {lnum} is used like with |getline()|. Thus "." is the current
3042 line, "'m" mark m, etc.
3043
3044 Can also be used as a |method|: >
3045 GetLnum()->foldlevel()
3046<
3047 *foldtext()*
3048foldtext() Returns a String, to be displayed for a closed fold. This is
3049 the default function used for the 'foldtext' option and should
3050 only be called from evaluating 'foldtext'. It uses the
3051 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3052 The returned string looks like this: >
3053 +-- 45 lines: abcdef
3054< The number of leading dashes depends on the foldlevel. The
3055 "45" is the number of lines in the fold. "abcdef" is the text
3056 in the first non-blank line of the fold. Leading white space,
3057 "//" or "/*" and the text from the 'foldmarker' and
3058 'commentstring' options is removed.
3059 When used to draw the actual foldtext, the rest of the line
3060 will be filled with the fold char from the 'fillchars'
3061 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003062 Returns an empty string when there is no fold.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003063 {not available when compiled without the |+folding| feature}
3064
3065foldtextresult({lnum}) *foldtextresult()*
3066 Returns the text that is displayed for the closed fold at line
3067 {lnum}. Evaluates 'foldtext' in the appropriate context.
3068 When there is no closed fold at {lnum} an empty string is
3069 returned.
3070 {lnum} is used like with |getline()|. Thus "." is the current
3071 line, "'m" mark m, etc.
3072 Useful when exporting folded text, e.g., to HTML.
3073 {not available when compiled without the |+folding| feature}
3074
3075
3076 Can also be used as a |method|: >
3077 GetLnum()->foldtextresult()
Ernie Raele79e2072024-01-13 11:47:33 +01003078
3079foreach({expr1}, {expr2}) *foreach()*
3080 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
3081 For each item in {expr1} execute {expr2}. {expr1} is not
erraelc92b8be2024-01-14 10:11:07 -08003082 modified; its values may be, as with |:lockvar| 1. |E741|
Ernie Raele79e2072024-01-13 11:47:33 +01003083 See |map()| and |filter()| to modify {expr1}.
3084
3085 {expr2} must be a |string| or |Funcref|.
3086
3087 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3088 of the current item. For a |Dictionary| |v:key| has the key
3089 of the current item and for a |List| |v:key| has the index of
3090 the current item. For a |Blob| |v:key| has the index of the
3091 current byte. For a |String| |v:key| has the index of the
3092 current character.
3093 Examples: >
3094 call foreach(mylist, 'used[v:val] = true')
3095< This records the items that are in the {expr1} list.
3096
3097 Note that {expr2} is the result of expression and is then used
3098 as a command. Often it is good to use a |literal-string| to
3099 avoid having to double backslashes.
3100
3101 If {expr2} is a |Funcref| it must take two arguments:
3102 1. the key or the index of the current item.
3103 2. the value of the current item.
3104 With a legacy script lambda you don't get an error if it only
3105 accepts one argument, but with a Vim9 lambda you get "E1106:
3106 One argument too many", the number of arguments must match.
3107 If the function returns a value, it is ignored.
3108
3109 Returns {expr1} in all cases.
3110 When an error is encountered while executing {expr2} no
3111 further items in {expr1} are processed.
3112 When {expr2} is a Funcref errors inside a function are ignored,
3113 unless it was defined with the "abort" flag.
3114
3115 Can also be used as a |method|: >
3116 mylist->foreach(expr2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003117<
3118 *foreground()*
3119foreground() Move the Vim window to the foreground. Useful when sent from
3120 a client to a Vim server. |remote_send()|
3121 On Win32 systems this might not work, the OS does not always
3122 allow a window to bring itself to the foreground. Use
3123 |remote_foreground()| instead.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003124 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003125 Win32 console version}
3126
Bram Moolenaaraa534142022-09-15 21:46:02 +01003127fullcommand({name} [, {vim9}]) *fullcommand()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003128 Get the full command name from a short abbreviated command
3129 name; see |20.2| for details on command abbreviations.
3130
3131 The string argument {name} may start with a `:` and can
3132 include a [range], these are skipped and not returned.
Bram Moolenaaraa534142022-09-15 21:46:02 +01003133 Returns an empty string if a command doesn't exist, if it's
3134 ambiguous (for user-defined commands) or cannot be shortened
3135 this way. |vim9-no-shorten|
3136
3137 Without the {vim9} argument uses the current script version.
3138 If {vim9} is present and FALSE then legacy script rules are
3139 used. When {vim9} is present and TRUE then Vim9 rules are
3140 used, e.g. "en" is not a short form of "endif".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003141
3142 For example `fullcommand('s')`, `fullcommand('sub')`,
3143 `fullcommand(':%substitute')` all return "substitute".
3144
3145 Can also be used as a |method|: >
3146 GetName()->fullcommand()
3147<
3148 *funcref()*
3149funcref({name} [, {arglist}] [, {dict}])
3150 Just like |function()|, but the returned Funcref will lookup
3151 the function by reference, not by name. This matters when the
3152 function {name} is redefined later.
3153
3154 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003155 It only works for an autoloaded function if it has already
3156 been loaded (to avoid mistakenly loading the autoload script
3157 when only intending to use the function name, use |function()|
3158 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003159 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003160
3161 Can also be used as a |method|: >
3162 GetFuncname()->funcref([arg])
3163<
Dominique Pellee764d1b2023-03-12 21:20:59 +00003164 *function()* *partial* *E700* *E923*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003165function({name} [, {arglist}] [, {dict}])
3166 Return a |Funcref| variable that refers to function {name}.
3167 {name} can be the name of a user defined function or an
3168 internal function.
3169
3170 {name} can also be a Funcref or a partial. When it is a
3171 partial the dict stored in it will be used and the {dict}
3172 argument is not allowed. E.g.: >
3173 let FuncWithArg = function(dict.Func, [arg])
3174 let Broken = function(dict.Func, [arg], dict)
3175<
3176 When using the Funcref the function will be found by {name},
3177 also when it was redefined later. Use |funcref()| to keep the
3178 same function.
3179
3180 When {arglist} or {dict} is present this creates a partial.
3181 That means the argument list and/or the dictionary is stored in
3182 the Funcref and will be used when the Funcref is called.
3183
3184 The arguments are passed to the function in front of other
3185 arguments, but after any argument from |method|. Example: >
3186 func Callback(arg1, arg2, name)
3187 ...
3188 let Partial = function('Callback', ['one', 'two'])
3189 ...
3190 call Partial('name')
3191< Invokes the function as with: >
3192 call Callback('one', 'two', 'name')
3193
3194< With a |method|: >
3195 func Callback(one, two, three)
3196 ...
3197 let Partial = function('Callback', ['two'])
3198 ...
3199 eval 'one'->Partial('three')
3200< Invokes the function as with: >
3201 call Callback('one', 'two', 'three')
3202
3203< The function() call can be nested to add more arguments to the
3204 Funcref. The extra arguments are appended to the list of
3205 arguments. Example: >
3206 func Callback(arg1, arg2, name)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003207 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003208 let Func = function('Callback', ['one'])
3209 let Func2 = function(Func, ['two'])
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003210 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003211 call Func2('name')
3212< Invokes the function as with: >
3213 call Callback('one', 'two', 'name')
3214
3215< The Dictionary is only useful when calling a "dict" function.
3216 In that case the {dict} is passed in as "self". Example: >
3217 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003218 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003219 endfunction
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003220 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003221 let context = {"name": "example"}
3222 let Func = function('Callback', context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003223 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003224 call Func() " will echo: called for example
3225< The use of function() is not needed when there are no extra
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003226 arguments, these two are equivalent, if Callback() is defined
3227 as context.Callback(): >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003228 let Func = function('Callback', context)
3229 let Func = context.Callback
3230
3231< The argument list and the Dictionary can be combined: >
3232 function Callback(arg1, count) dict
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003233 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003234 let context = {"name": "example"}
3235 let Func = function('Callback', ['one'], context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003236 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003237 call Func(500)
3238< Invokes the function as with: >
3239 call context.Callback('one', 500)
3240<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003241 Returns 0 on error.
3242
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003243 Can also be used as a |method|: >
3244 GetFuncname()->function([arg])
3245
3246
3247garbagecollect([{atexit}]) *garbagecollect()*
3248 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3249 that have circular references.
3250
3251 There is hardly ever a need to invoke this function, as it is
3252 automatically done when Vim runs out of memory or is waiting
3253 for the user to press a key after 'updatetime'. Items without
3254 circular references are always freed when they become unused.
3255 This is useful if you have deleted a very big |List| and/or
3256 |Dictionary| with circular references in a script that runs
3257 for a long time.
3258
3259 When the optional {atexit} argument is one, garbage
3260 collection will also be done when exiting Vim, if it wasn't
3261 done before. This is useful when checking for memory leaks.
3262
3263 The garbage collection is not done immediately but only when
3264 it's safe to perform. This is when waiting for the user to
3265 type a character. To force garbage collection immediately use
3266 |test_garbagecollect_now()|.
3267
3268get({list}, {idx} [, {default}]) *get()*
3269 Get item {idx} from |List| {list}. When this item is not
3270 available return {default}. Return zero when {default} is
3271 omitted.
3272 Preferably used as a |method|: >
3273 mylist->get(idx)
3274get({blob}, {idx} [, {default}])
3275 Get byte {idx} from |Blob| {blob}. When this byte is not
3276 available return {default}. Return -1 when {default} is
3277 omitted.
3278 Preferably used as a |method|: >
3279 myblob->get(idx)
3280get({dict}, {key} [, {default}])
3281 Get item with key {key} from |Dictionary| {dict}. When this
3282 item is not available return {default}. Return zero when
3283 {default} is omitted. Useful example: >
3284 let val = get(g:, 'var_name', 'default')
3285< This gets the value of g:var_name if it exists, and uses
3286 'default' when it does not exist.
3287 Preferably used as a |method|: >
3288 mydict->get(key)
3289get({func}, {what})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003290 Get item {what} from Funcref {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003291 {what} are:
3292 "name" The function name
3293 "func" The function
3294 "dict" The dictionary
3295 "args" The list with arguments
Bram Moolenaar016188f2022-06-06 20:52:59 +01003296 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003297 Preferably used as a |method|: >
3298 myfunc->get(what)
3299<
3300 *getbufinfo()*
3301getbufinfo([{buf}])
3302getbufinfo([{dict}])
3303 Get information about buffers as a List of Dictionaries.
3304
3305 Without an argument information about all the buffers is
3306 returned.
3307
3308 When the argument is a |Dictionary| only the buffers matching
3309 the specified criteria are returned. The following keys can
3310 be specified in {dict}:
3311 buflisted include only listed buffers.
3312 bufloaded include only loaded buffers.
3313 bufmodified include only modified buffers.
3314
3315 Otherwise, {buf} specifies a particular buffer to return
3316 information for. For the use of {buf}, see |bufname()|
3317 above. If the buffer is found the returned List has one item.
3318 Otherwise the result is an empty list.
3319
3320 Each returned List item is a dictionary with the following
3321 entries:
3322 bufnr Buffer number.
3323 changed TRUE if the buffer is modified.
3324 changedtick Number of changes made to the buffer.
Sean Dewar1fb41032023-08-16 17:15:05 +01003325 command TRUE if the buffer belongs to the
3326 command-line window |cmdwin|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003327 hidden TRUE if the buffer is hidden.
3328 lastused Timestamp in seconds, like
3329 |localtime()|, when the buffer was
3330 last used.
3331 {only with the |+viminfo| feature}
3332 listed TRUE if the buffer is listed.
3333 lnum Line number used for the buffer when
3334 opened in the current window.
3335 Only valid if the buffer has been
3336 displayed in the window in the past.
3337 If you want the line number of the
3338 last known cursor position in a given
3339 window, use |line()|: >
3340 :echo line('.', {winid})
3341<
3342 linecount Number of lines in the buffer (only
3343 valid when loaded)
3344 loaded TRUE if the buffer is loaded.
3345 name Full path to the file in the buffer.
3346 signs List of signs placed in the buffer.
3347 Each list item is a dictionary with
3348 the following fields:
3349 id sign identifier
3350 lnum line number
3351 name sign name
3352 variables A reference to the dictionary with
3353 buffer-local variables.
3354 windows List of |window-ID|s that display this
3355 buffer
3356 popups List of popup |window-ID|s that
3357 display this buffer
3358
3359 Examples: >
3360 for buf in getbufinfo()
3361 echo buf.name
3362 endfor
3363 for buf in getbufinfo({'buflisted':1})
3364 if buf.changed
3365 ....
3366 endif
3367 endfor
3368<
3369 To get buffer-local options use: >
3370 getbufvar({bufnr}, '&option_name')
3371<
3372 Can also be used as a |method|: >
3373 GetBufnr()->getbufinfo()
3374<
3375
3376 *getbufline()*
3377getbufline({buf}, {lnum} [, {end}])
3378 Return a |List| with the lines starting from {lnum} to {end}
3379 (inclusive) in the buffer {buf}. If {end} is omitted, a
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003380 |List| with only the line {lnum} is returned. See
3381 `getbufoneline()` for only getting the line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003382
3383 For the use of {buf}, see |bufname()| above.
3384
3385 For {lnum} and {end} "$" can be used for the last line of the
3386 buffer. Otherwise a number must be used.
3387
3388 When {lnum} is smaller than 1 or bigger than the number of
3389 lines in the buffer, an empty |List| is returned.
3390
3391 When {end} is greater than the number of lines in the buffer,
3392 it is treated as {end} is set to the number of lines in the
3393 buffer. When {end} is before {lnum} an empty |List| is
3394 returned.
3395
3396 This function works only for loaded buffers. For unloaded and
3397 non-existing buffers, an empty |List| is returned.
3398
3399 Example: >
3400 :let lines = getbufline(bufnr("myfile"), 1, "$")
3401
3402< Can also be used as a |method|: >
3403 GetBufnr()->getbufline(lnum)
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003404<
3405 *getbufoneline()*
3406getbufoneline({buf}, {lnum})
3407 Just like `getbufline()` but only get one line and return it
3408 as a string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003409
3410getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3411 The result is the value of option or local buffer variable
3412 {varname} in buffer {buf}. Note that the name without "b:"
3413 must be used.
3414 The {varname} argument is a string.
3415 When {varname} is empty returns a |Dictionary| with all the
3416 buffer-local variables.
3417 When {varname} is equal to "&" returns a |Dictionary| with all
3418 the buffer-local options.
3419 Otherwise, when {varname} starts with "&" returns the value of
3420 a buffer-local option.
3421 This also works for a global or buffer-local option, but it
3422 doesn't work for a global variable, window-local variable or
3423 window-local option.
3424 For the use of {buf}, see |bufname()| above.
3425 When the buffer or variable doesn't exist {def} or an empty
3426 string is returned, there is no error message.
3427 Examples: >
3428 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003429 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003430
3431< Can also be used as a |method|: >
3432 GetBufnr()->getbufvar(varname)
3433<
Kota Kato66bb9ae2023-01-17 18:31:56 +00003434getcellwidths() *getcellwidths()*
3435 Returns a |List| of cell widths of character ranges overridden
3436 by |setcellwidths()|. The format is equal to the argument of
3437 |setcellwidths()|. If no character ranges have their cell
3438 widths overridden, an empty List is returned.
3439
3440
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003441getchangelist([{buf}]) *getchangelist()*
3442 Returns the |changelist| for the buffer {buf}. For the use
3443 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3444 exist, an empty list is returned.
3445
3446 The returned list contains two entries: a list with the change
3447 locations and the current position in the list. Each
3448 entry in the change list is a dictionary with the following
3449 entries:
3450 col column number
3451 coladd column offset for 'virtualedit'
3452 lnum line number
3453 If buffer {buf} is the current buffer, then the current
3454 position refers to the position in the list. For other
3455 buffers, it is set to the length of the list.
3456
3457 Can also be used as a |method|: >
3458 GetBufnr()->getchangelist()
3459
Doug Kearns9cd9e752024-04-07 17:42:17 +02003460getchar([{expr}]) *getchar()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003461 Get a single character from the user or input stream.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003462 If {expr} is omitted, wait until a character is available.
3463 If {expr} is 0, only get a character when one is available.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003464 Return zero otherwise.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003465 If {expr} is 1, only check if a character is available, it is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003466 not consumed. Return zero if no character available.
3467 If you prefer always getting a string use |getcharstr()|.
3468
Doug Kearns9cd9e752024-04-07 17:42:17 +02003469 Without {expr} and when {expr} is 0 a whole character or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003470 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01003471 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003472 Otherwise a String is returned with the encoded character.
3473 For a special key it's a String with a sequence of bytes
3474 starting with 0x80 (decimal: 128). This is the same value as
3475 the String "\<Key>", e.g., "\<Left>". The returned value is
3476 also a String when a modifier (shift, control, alt) was used
3477 that is not included in the character.
3478
Doug Kearns9cd9e752024-04-07 17:42:17 +02003479 When {expr} is 0 and Esc is typed, there will be a short delay
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003480 while Vim waits to see if this is the start of an escape
3481 sequence.
3482
Doug Kearns9cd9e752024-04-07 17:42:17 +02003483 When {expr} is 1 only the first byte is returned. For a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003484 one-byte character it is the character itself as a number.
3485 Use nr2char() to convert it to a String.
3486
3487 Use getcharmod() to obtain any additional modifiers.
3488
3489 When the user clicks a mouse button, the mouse event will be
3490 returned. The position can then be found in |v:mouse_col|,
3491 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3492 |getmousepos()| can also be used. Mouse move events will be
3493 ignored.
3494 This example positions the mouse as it would normally happen: >
3495 let c = getchar()
3496 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003497 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003498 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003499 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003500 endif
3501<
3502 When using bracketed paste only the first character is
3503 returned, the rest of the pasted text is dropped.
3504 |xterm-bracketed-paste|.
3505
3506 There is no prompt, you will somehow have to make clear to the
3507 user that a character has to be typed. The screen is not
3508 redrawn, e.g. when resizing the window. When using a popup
3509 window it should work better with a |popup-filter|.
3510
3511 There is no mapping for the character.
3512 Key codes are replaced, thus when the user presses the <Del>
3513 key you get the code for the <Del> key, not the raw character
3514 sequence. Examples: >
3515 getchar() == "\<Del>"
3516 getchar() == "\<S-Left>"
3517< This example redefines "f" to ignore case: >
3518 :nmap f :call FindChar()<CR>
3519 :function FindChar()
3520 : let c = nr2char(getchar())
3521 : while col('.') < col('$') - 1
3522 : normal l
3523 : if getline('.')[col('.') - 1] ==? c
3524 : break
3525 : endif
3526 : endwhile
3527 :endfunction
3528<
3529 You may also receive synthetic characters, such as
3530 |<CursorHold>|. Often you will want to ignore this and get
3531 another character: >
3532 :function GetKey()
3533 : let c = getchar()
3534 : while c == "\<CursorHold>"
3535 : let c = getchar()
3536 : endwhile
3537 : return c
3538 :endfunction
3539
3540getcharmod() *getcharmod()*
3541 The result is a Number which is the state of the modifiers for
3542 the last obtained character with getchar() or in another way.
3543 These values are added together:
3544 2 shift
3545 4 control
3546 8 alt (meta)
3547 16 meta (when it's different from ALT)
3548 32 mouse double click
3549 64 mouse triple click
3550 96 mouse quadruple click (== 32 + 64)
Casey Tucker92e90a12024-01-25 22:44:00 +01003551 128 command (Mac) or super (GTK)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003552 Only the modifiers that have not been included in the
3553 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01003554 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003555
3556 *getcharpos()*
3557getcharpos({expr})
3558 Get the position for String {expr}. Same as |getpos()| but the
3559 column number in the returned List is a character index
3560 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00003561 If |getpos()| returns a very large column number, equal to
3562 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003563 of the last character.
3564
3565 Example:
3566 With the cursor on '세' in line 5 with text "여보세요": >
3567 getcharpos('.') returns [0, 5, 3, 0]
3568 getpos('.') returns [0, 5, 7, 0]
3569<
3570 Can also be used as a |method|: >
3571 GetMark()->getcharpos()
3572
3573getcharsearch() *getcharsearch()*
3574 Return the current character search information as a {dict}
3575 with the following entries:
3576
3577 char character previously used for a character
3578 search (|t|, |f|, |T|, or |F|); empty string
3579 if no character search has been performed
3580 forward direction of character search; 1 for forward,
3581 0 for backward
3582 until type of character search; 1 for a |t| or |T|
3583 character search, 0 for an |f| or |F|
3584 character search
3585
3586 This can be useful to always have |;| and |,| search
3587 forward/backward regardless of the direction of the previous
3588 character search: >
3589 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3590 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3591< Also see |setcharsearch()|.
3592
3593
Doug Kearns9cd9e752024-04-07 17:42:17 +02003594getcharstr([{expr}]) *getcharstr()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003595 Get a single character from the user or input stream as a
3596 string.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003597 If {expr} is omitted, wait until a character is available.
3598 If {expr} is 0 or false, only get a character when one is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003599 available. Return an empty string otherwise.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003600 If {expr} is 1 or true, only check if a character is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003601 available, it is not consumed. Return an empty string
3602 if no character is available.
3603 Otherwise this works like |getchar()|, except that a number
3604 result is converted to a string.
3605
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003606getcmdcompltype() *getcmdcompltype()*
3607 Return the type of the current command-line completion.
3608 Only works when the command line is being edited, thus
3609 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01003610 See |:command-completion| for the return string.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003611 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3612 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003613 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003614
3615getcmdline() *getcmdline()*
3616 Return the current command-line. Only works when the command
3617 line is being edited, thus requires use of |c_CTRL-\_e| or
3618 |c_CTRL-R_=|.
3619 Example: >
3620 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003621< Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and
3622 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003623 Returns an empty string when entering a password or using
3624 |inputsecret()|.
3625
3626getcmdpos() *getcmdpos()*
3627 Return the position of the cursor in the command line as a
3628 byte count. The first column is 1.
3629 Only works when editing the command line, thus requires use of
3630 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3631 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003632 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3633 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003634
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003635getcmdscreenpos() *getcmdscreenpos()*
3636 Return the screen position of the cursor in the command line
3637 as a byte count. The first column is 1.
3638 Instead of |getcmdpos()|, it adds the prompt position.
3639 Only works when editing the command line, thus requires use of
3640 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3641 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003642 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
3643 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003644
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003645getcmdtype() *getcmdtype()*
3646 Return the current command-line type. Possible return values
3647 are:
3648 : normal Ex command
3649 > debug mode command |debug-mode|
3650 / forward search command
3651 ? backward search command
3652 @ |input()| command
3653 - |:insert| or |:append| command
3654 = |i_CTRL-R_=|
3655 Only works when editing the command line, thus requires use of
3656 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3657 Returns an empty string otherwise.
3658 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3659
3660getcmdwintype() *getcmdwintype()*
3661 Return the current |command-line-window| type. Possible return
3662 values are the same as |getcmdtype()|. Returns an empty string
3663 when not in the command-line window.
3664
3665getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
3666 Return a list of command-line completion matches. The String
3667 {type} argument specifies what for. The following completion
3668 types are supported:
3669
3670 arglist file names in argument list
3671 augroup autocmd groups
3672 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003673 behave |:behave| suboptions
3674 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003675 color color schemes
3676 command Ex command
3677 cmdline |cmdline-completion| result
3678 compiler compilers
3679 cscope |:cscope| suboptions
Shougo Matsushita92997dd2023-08-20 20:55:55 +02003680 custom,{func} custom completion, defined via {func}
3681 customlist,{func} custom completion, defined via {func}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003682 diff_buffer |:diffget| and |:diffput| completion
3683 dir directory names
3684 environment environment variable names
3685 event autocommand events
3686 expression Vim expression
3687 file file and directory names
3688 file_in_path file and directory names in |'path'|
3689 filetype filetype names |'filetype'|
3690 function function name
3691 help help subjects
3692 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003693 history |:history| suboptions
Doug Kearns81642d92024-01-04 22:37:44 +01003694 keymap keyboard mappings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003695 locale locale names (as output of locale -a)
3696 mapclear buffer argument
3697 mapping mapping name
3698 menu menus
3699 messages |:messages| suboptions
3700 option options
3701 packadd optional package |pack-add| names
zeertzjq5c8771b2023-01-24 12:34:03 +00003702 runtime |:runtime| completion
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003703 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003704 shellcmd Shell command
3705 sign |:sign| suboptions
3706 syntax syntax file names |'syntax'|
3707 syntime |:syntime| suboptions
3708 tag tags
3709 tag_listfiles tags, file names
3710 user user names
3711 var user variables
3712
3713 If {pat} is an empty string, then all the matches are
3714 returned. Otherwise only items matching {pat} are returned.
3715 See |wildcards| for the use of special characters in {pat}.
3716
3717 If the optional {filtered} flag is set to 1, then 'wildignore'
3718 is applied to filter the results. Otherwise all the matches
3719 are returned. The 'wildignorecase' option always applies.
3720
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003721 If the 'wildoptions' option contains 'fuzzy', then fuzzy
3722 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003723 regular expression matching is used. Thus this function
3724 follows the user preference, what happens on the command line.
3725 If you do not want this you can make 'wildoptions' empty
3726 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003727
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003728 If {type} is "cmdline", then the |cmdline-completion| result is
3729 returned. For example, to complete the possible values after
3730 a ":call" command: >
3731 echo getcompletion('call ', 'cmdline')
3732<
3733 If there are no matches, an empty list is returned. An
3734 invalid value for {type} produces an error.
3735
3736 Can also be used as a |method|: >
3737 GetPattern()->getcompletion('color')
3738<
3739 *getcurpos()*
3740getcurpos([{winid}])
3741 Get the position of the cursor. This is like getpos('.'), but
3742 includes an extra "curswant" item in the list:
3743 [0, lnum, col, off, curswant] ~
3744 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00003745 cursor vertically. After |$| command it will be a very large
3746 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003747 |getpos()|.
3748 The first "bufnum" item is always zero. The byte position of
3749 the cursor is returned in 'col'. To get the character
3750 position, use |getcursorcharpos()|.
3751
3752 The optional {winid} argument can specify the window. It can
3753 be the window number or the |window-ID|. The last known
3754 cursor position is returned, this may be invalid for the
3755 current value of the buffer if it is not the current window.
3756 If {winid} is invalid a list with zeroes is returned.
3757
3758 This can be used to save and restore the cursor position: >
3759 let save_cursor = getcurpos()
3760 MoveTheCursorAround
3761 call setpos('.', save_cursor)
3762< Note that this only works within the window. See
3763 |winrestview()| for restoring more state.
3764
3765 Can also be used as a |method|: >
3766 GetWinid()->getcurpos()
3767<
3768 *getcursorcharpos()*
3769getcursorcharpos([{winid}])
3770 Same as |getcurpos()| but the column number in the returned
3771 List is a character index instead of a byte index.
3772
3773 Example:
3774 With the cursor on '보' in line 3 with text "여보세요": >
3775 getcursorcharpos() returns [0, 3, 2, 0, 3]
3776 getcurpos() returns [0, 3, 4, 0, 3]
3777<
3778 Can also be used as a |method|: >
3779 GetWinid()->getcursorcharpos()
3780
3781< *getcwd()*
3782getcwd([{winnr} [, {tabnr}]])
3783 The result is a String, which is the name of the current
3784 working directory. 'autochdir' is ignored.
3785
3786 With {winnr} return the local current directory of this window
3787 in the current tab page. {winnr} can be the window number or
3788 the |window-ID|.
3789 If {winnr} is -1 return the name of the global working
3790 directory. See also |haslocaldir()|.
3791
3792 With {winnr} and {tabnr} return the local current directory of
3793 the window in the specified tab page. If {winnr} is -1 return
3794 the working directory of the tabpage.
3795 If {winnr} is zero use the current window, if {tabnr} is zero
3796 use the current tabpage.
3797 Without any arguments, return the actual working directory of
3798 the current window.
3799 Return an empty string if the arguments are invalid.
3800
3801 Examples: >
3802 " Get the working directory of the current window
3803 :echo getcwd()
3804 :echo getcwd(0)
3805 :echo getcwd(0, 0)
3806 " Get the working directory of window 3 in tabpage 2
3807 :echo getcwd(3, 2)
3808 " Get the global working directory
3809 :echo getcwd(-1)
3810 " Get the working directory of tabpage 3
3811 :echo getcwd(-1, 3)
3812 " Get the working directory of current tabpage
3813 :echo getcwd(-1, 0)
3814
3815< Can also be used as a |method|: >
3816 GetWinnr()->getcwd()
3817
3818getenv({name}) *getenv()*
3819 Return the value of environment variable {name}. The {name}
3820 argument is a string, without a leading '$'. Example: >
3821 myHome = getenv('HOME')
3822
3823< When the variable does not exist |v:null| is returned. That
3824 is different from a variable set to an empty string, although
3825 some systems interpret the empty value as the variable being
3826 deleted. See also |expr-env|.
3827
3828 Can also be used as a |method|: >
3829 GetVarname()->getenv()
3830
3831getfontname([{name}]) *getfontname()*
3832 Without an argument returns the name of the normal font being
3833 used. Like what is used for the Normal highlight group
3834 |hl-Normal|.
3835 With an argument a check is done whether String {name} is a
3836 valid font name. If not then an empty string is returned.
3837 Otherwise the actual font name is returned, or {name} if the
3838 GUI does not support obtaining the real name.
3839 Only works when the GUI is running, thus not in your vimrc or
3840 gvimrc file. Use the |GUIEnter| autocommand to use this
3841 function just after the GUI has started.
3842 Note that the GTK GUI accepts any font name, thus checking for
3843 a valid name does not work.
3844
3845getfperm({fname}) *getfperm()*
3846 The result is a String, which is the read, write, and execute
3847 permissions of the given file {fname}.
3848 If {fname} does not exist or its directory cannot be read, an
3849 empty string is returned.
3850 The result is of the form "rwxrwxrwx", where each group of
3851 "rwx" flags represent, in turn, the permissions of the owner
3852 of the file, the group the file belongs to, and other users.
3853 If a user does not have a given permission the flag for this
3854 is replaced with the string "-". Examples: >
3855 :echo getfperm("/etc/passwd")
3856 :echo getfperm(expand("~/.vimrc"))
3857< This will hopefully (from a security point of view) display
3858 the string "rw-r--r--" or even "rw-------".
3859
3860 Can also be used as a |method|: >
3861 GetFilename()->getfperm()
3862<
3863 For setting permissions use |setfperm()|.
3864
3865getfsize({fname}) *getfsize()*
3866 The result is a Number, which is the size in bytes of the
3867 given file {fname}.
3868 If {fname} is a directory, 0 is returned.
3869 If the file {fname} can't be found, -1 is returned.
3870 If the size of {fname} is too big to fit in a Number then -2
3871 is returned.
3872
3873 Can also be used as a |method|: >
3874 GetFilename()->getfsize()
3875
3876getftime({fname}) *getftime()*
3877 The result is a Number, which is the last modification time of
3878 the given file {fname}. The value is measured as seconds
3879 since 1st Jan 1970, and may be passed to strftime(). See also
3880 |localtime()| and |strftime()|.
3881 If the file {fname} can't be found -1 is returned.
3882
3883 Can also be used as a |method|: >
3884 GetFilename()->getftime()
3885
3886getftype({fname}) *getftype()*
3887 The result is a String, which is a description of the kind of
3888 file of the given file {fname}.
3889 If {fname} does not exist an empty string is returned.
3890 Here is a table over different kinds of files and their
3891 results:
3892 Normal file "file"
3893 Directory "dir"
3894 Symbolic link "link"
3895 Block device "bdev"
3896 Character device "cdev"
3897 Socket "socket"
3898 FIFO "fifo"
3899 All other "other"
3900 Example: >
3901 getftype("/home")
3902< Note that a type such as "link" will only be returned on
3903 systems that support it. On some systems only "dir" and
3904 "file" are returned. On MS-Windows a symbolic link to a
3905 directory returns "dir" instead of "link".
3906
3907 Can also be used as a |method|: >
3908 GetFilename()->getftype()
3909
3910getimstatus() *getimstatus()*
3911 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01003912 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003913 See 'imstatusfunc'.
3914
3915getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
3916 Returns the |jumplist| for the specified window.
3917
3918 Without arguments use the current window.
3919 With {winnr} only use this window in the current tab page.
3920 {winnr} can also be a |window-ID|.
3921 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01003922 page. If {winnr} or {tabnr} is invalid, an empty list is
3923 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003924
3925 The returned list contains two entries: a list with the jump
3926 locations and the last used jump position number in the list.
3927 Each entry in the jump location list is a dictionary with
3928 the following entries:
3929 bufnr buffer number
3930 col column number
3931 coladd column offset for 'virtualedit'
3932 filename filename if available
3933 lnum line number
3934
3935 Can also be used as a |method|: >
3936 GetWinnr()->getjumplist()
3937
3938< *getline()*
3939getline({lnum} [, {end}])
3940 Without {end} the result is a String, which is line {lnum}
3941 from the current buffer. Example: >
3942 getline(1)
3943< When {lnum} is a String that doesn't start with a
3944 digit, |line()| is called to translate the String into a Number.
3945 To get the line under the cursor: >
3946 getline(".")
3947< When {lnum} is a number smaller than 1 or bigger than the
3948 number of lines in the buffer, an empty string is returned.
3949
3950 When {end} is given the result is a |List| where each item is
3951 a line from the current buffer in the range {lnum} to {end},
3952 including line {end}.
3953 {end} is used in the same way as {lnum}.
3954 Non-existing lines are silently omitted.
3955 When {end} is before {lnum} an empty |List| is returned.
3956 Example: >
3957 :let start = line('.')
3958 :let end = search("^$") - 1
3959 :let lines = getline(start, end)
3960
3961< Can also be used as a |method|: >
3962 ComputeLnum()->getline()
3963
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003964< To get lines from another buffer see |getbufline()| and
3965 |getbufoneline()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003966
3967getloclist({nr} [, {what}]) *getloclist()*
3968 Returns a |List| with all the entries in the location list for
3969 window {nr}. {nr} can be the window number or the |window-ID|.
3970 When {nr} is zero the current window is used.
3971
3972 For a location list window, the displayed location list is
3973 returned. For an invalid window number {nr}, an empty list is
3974 returned. Otherwise, same as |getqflist()|.
3975
3976 If the optional {what} dictionary argument is supplied, then
3977 returns the items listed in {what} as a dictionary. Refer to
3978 |getqflist()| for the supported items in {what}.
3979
3980 In addition to the items supported by |getqflist()| in {what},
3981 the following item is supported by |getloclist()|:
3982
3983 filewinid id of the window used to display files
3984 from the location list. This field is
3985 applicable only when called from a
3986 location list window. See
3987 |location-list-file-window| for more
3988 details.
3989
3990 Returns a |Dictionary| with default values if there is no
3991 location list for the window {nr}.
3992 Returns an empty Dictionary if window {nr} does not exist.
3993
3994 Examples (See also |getqflist-examples|): >
3995 :echo getloclist(3, {'all': 0})
3996 :echo getloclist(5, {'filewinid': 0})
3997
3998
3999getmarklist([{buf}]) *getmarklist()*
4000 Without the {buf} argument returns a |List| with information
4001 about all the global marks. |mark|
4002
4003 If the optional {buf} argument is specified, returns the
4004 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01004005 see |bufname()|. If {buf} is invalid, an empty list is
4006 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004007
4008 Each item in the returned List is a |Dict| with the following:
4009 mark name of the mark prefixed by "'"
4010 pos a |List| with the position of the mark:
4011 [bufnum, lnum, col, off]
4012 Refer to |getpos()| for more information.
4013 file file name
4014
4015 Refer to |getpos()| for getting information about a specific
4016 mark.
4017
4018 Can also be used as a |method|: >
4019 GetBufnr()->getmarklist()
4020
4021getmatches([{win}]) *getmatches()*
4022 Returns a |List| with all matches previously defined for the
4023 current window by |matchadd()| and the |:match| commands.
4024 |getmatches()| is useful in combination with |setmatches()|,
4025 as |setmatches()| can restore a list of matches saved by
4026 |getmatches()|.
4027 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01004028 window ID instead of the current window. If {win} is invalid,
4029 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004030 Example: >
4031 :echo getmatches()
4032< [{'group': 'MyGroup1', 'pattern': 'TODO',
4033 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4034 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4035 :let m = getmatches()
4036 :call clearmatches()
4037 :echo getmatches()
4038< [] >
4039 :call setmatches(m)
4040 :echo getmatches()
4041< [{'group': 'MyGroup1', 'pattern': 'TODO',
4042 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4043 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4044 :unlet m
4045<
4046getmousepos() *getmousepos()*
4047 Returns a |Dictionary| with the last known position of the
4048 mouse. This can be used in a mapping for a mouse click or in
4049 a filter of a popup window. The items are:
4050 screenrow screen row
4051 screencol screen column
4052 winid Window ID of the click
4053 winrow row inside "winid"
4054 wincol column inside "winid"
4055 line text line inside "winid"
4056 column text column inside "winid"
zeertzjqf5a94d52023-10-15 10:03:30 +02004057 coladd offset (in screen columns) from the
4058 start of the clicked char
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004059 All numbers are 1-based.
4060
4061 If not over a window, e.g. when in the command line, then only
4062 "screenrow" and "screencol" are valid, the others are zero.
4063
4064 When on the status line below a window or the vertical
4065 separator right of a window, the "line" and "column" values
4066 are zero.
4067
4068 When the position is after the text then "column" is the
4069 length of the text in bytes plus one.
4070
4071 If the mouse is over a popup window then that window is used.
4072
4073 When using |getchar()| the Vim variables |v:mouse_lnum|,
4074 |v:mouse_col| and |v:mouse_winid| also provide these values.
4075
Bram Moolenaar24dc19c2022-11-14 19:49:15 +00004076getmouseshape() *getmouseshape()*
4077 Returns the name of the currently showing mouse pointer.
4078 When the |+mouseshape| feature is not supported or the shape
4079 is unknown an empty string is returned.
4080 This function is mainly intended for testing.
4081
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004082 *getpid()*
4083getpid() Return a Number which is the process ID of the Vim process.
4084 On Unix and MS-Windows this is a unique number, until Vim
4085 exits.
4086
4087 *getpos()*
4088getpos({expr}) Get the position for String {expr}. For possible values of
4089 {expr} see |line()|. For getting the cursor position see
4090 |getcurpos()|.
4091 The result is a |List| with four numbers:
4092 [bufnum, lnum, col, off]
4093 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4094 is the buffer number of the mark.
4095 "lnum" and "col" are the position in the buffer. The first
4096 column is 1.
4097 The "off" number is zero, unless 'virtualedit' is used. Then
4098 it is the offset in screen columns from the start of the
4099 character. E.g., a position within a <Tab> or after the last
4100 character.
4101 Note that for '< and '> Visual mode matters: when it is "V"
4102 (visual line mode) the column of '< is zero and the column of
naohiro ono56200ee2022-01-01 14:59:44 +00004103 '> is a large number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004104 The column number in the returned List is the byte position
4105 within the line. To get the character position in the line,
4106 use |getcharpos()|.
naohiro ono56200ee2022-01-01 14:59:44 +00004107 A very large column number equal to |v:maxcol| can be returned,
4108 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01004109 If {expr} is invalid, returns a list with all zeros.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004110 This can be used to save and restore the position of a mark: >
4111 let save_a_mark = getpos("'a")
4112 ...
4113 call setpos("'a", save_a_mark)
4114< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
4115
4116 Can also be used as a |method|: >
4117 GetMark()->getpos()
4118
4119getqflist([{what}]) *getqflist()*
4120 Returns a |List| with all the current quickfix errors. Each
4121 list item is a dictionary with these entries:
4122 bufnr number of buffer that has the file name, use
4123 bufname() to get the name
4124 module module name
4125 lnum line number in the buffer (first line is 1)
4126 end_lnum
4127 end of line number if the item is multiline
4128 col column number (first column is 1)
4129 end_col end of column number if the item has range
4130 vcol |TRUE|: "col" is visual column
4131 |FALSE|: "col" is byte index
4132 nr error number
4133 pattern search pattern used to locate the error
4134 text description of the error
4135 type type of the error, 'E', '1', etc.
4136 valid |TRUE|: recognized error message
h_east596a9f22023-11-21 21:24:23 +09004137 user_data
4138 custom data associated with the item, can be
Tom Praschanca6ac992023-08-11 23:26:12 +02004139 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004140
4141 When there is no error list or it's empty, an empty list is
4142 returned. Quickfix list entries with a non-existing buffer
4143 number are returned with "bufnr" set to zero (Note: some
4144 functions accept buffer number zero for the alternate buffer,
4145 you may need to explicitly check for zero).
4146
4147 Useful application: Find pattern matches in multiple files and
4148 do something with them: >
4149 :vimgrep /theword/jg *.c
4150 :for d in getqflist()
4151 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4152 :endfor
4153<
4154 If the optional {what} dictionary argument is supplied, then
4155 returns only the items listed in {what} as a dictionary. The
4156 following string items are supported in {what}:
4157 changedtick get the total number of changes made
4158 to the list |quickfix-changedtick|
4159 context get the |quickfix-context|
4160 efm errorformat to use when parsing "lines". If
4161 not present, then the 'errorformat' option
4162 value is used.
4163 id get information for the quickfix list with
4164 |quickfix-ID|; zero means the id for the
4165 current list or the list specified by "nr"
4166 idx get information for the quickfix entry at this
4167 index in the list specified by 'id' or 'nr'.
4168 If set to zero, then uses the current entry.
4169 See |quickfix-index|
4170 items quickfix list entries
4171 lines parse a list of lines using 'efm' and return
4172 the resulting entries. Only a |List| type is
4173 accepted. The current quickfix list is not
4174 modified. See |quickfix-parse|.
4175 nr get information for this quickfix list; zero
4176 means the current quickfix list and "$" means
4177 the last quickfix list
4178 qfbufnr number of the buffer displayed in the quickfix
4179 window. Returns 0 if the quickfix buffer is
4180 not present. See |quickfix-buffer|.
4181 size number of entries in the quickfix list
4182 title get the list title |quickfix-title|
4183 winid get the quickfix |window-ID|
4184 all all of the above quickfix properties
4185 Non-string items in {what} are ignored. To get the value of a
4186 particular item, set it to zero.
4187 If "nr" is not present then the current quickfix list is used.
4188 If both "nr" and a non-zero "id" are specified, then the list
4189 specified by "id" is used.
4190 To get the number of lists in the quickfix stack, set "nr" to
4191 "$" in {what}. The "nr" value in the returned dictionary
4192 contains the quickfix stack size.
4193 When "lines" is specified, all the other items except "efm"
4194 are ignored. The returned dictionary contains the entry
4195 "items" with the list of entries.
4196
4197 The returned dictionary contains the following entries:
4198 changedtick total number of changes made to the
4199 list |quickfix-changedtick|
4200 context quickfix list context. See |quickfix-context|
4201 If not present, set to "".
4202 id quickfix list ID |quickfix-ID|. If not
4203 present, set to 0.
4204 idx index of the quickfix entry in the list. If not
4205 present, set to 0.
4206 items quickfix list entries. If not present, set to
4207 an empty list.
4208 nr quickfix list number. If not present, set to 0
4209 qfbufnr number of the buffer displayed in the quickfix
4210 window. If not present, set to 0.
4211 size number of entries in the quickfix list. If not
4212 present, set to 0.
4213 title quickfix list title text. If not present, set
4214 to "".
4215 winid quickfix |window-ID|. If not present, set to 0
4216
4217 Examples (See also |getqflist-examples|): >
4218 :echo getqflist({'all': 1})
4219 :echo getqflist({'nr': 2, 'title': 1})
4220 :echo getqflist({'lines' : ["F1:10:L10"]})
4221<
4222getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4223 The result is a String, which is the contents of register
4224 {regname}. Example: >
4225 :let cliptext = getreg('*')
4226< When register {regname} was not set the result is an empty
4227 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004228 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004229
4230 getreg('=') returns the last evaluated value of the expression
4231 register. (For use in maps.)
4232 getreg('=', 1) returns the expression itself, so that it can
4233 be restored with |setreg()|. For other registers the extra
4234 argument is ignored, thus you can always give it.
4235
4236 If {list} is present and |TRUE|, the result type is changed
4237 to |List|. Each list item is one text line. Use it if you care
4238 about zero bytes possibly present inside register: without
4239 third argument both NLs and zero bytes are represented as NLs
4240 (see |NL-used-for-Nul|).
4241 When the register was not set an empty list is returned.
4242
4243 If {regname} is "", the unnamed register '"' is used.
4244 If {regname} is not specified, |v:register| is used.
4245 In |Vim9-script| {regname} must be one character.
4246
4247 Can also be used as a |method|: >
4248 GetRegname()->getreg()
4249
4250getreginfo([{regname}]) *getreginfo()*
4251 Returns detailed information about register {regname} as a
4252 Dictionary with the following entries:
4253 regcontents List of lines contained in register
4254 {regname}, like
4255 |getreg|({regname}, 1, 1).
4256 regtype the type of register {regname}, as in
4257 |getregtype()|.
4258 isunnamed Boolean flag, v:true if this register
4259 is currently pointed to by the unnamed
4260 register.
4261 points_to for the unnamed register, gives the
4262 single letter name of the register
4263 currently pointed to (see |quotequote|).
4264 For example, after deleting a line
4265 with `dd`, this field will be "1",
4266 which is the register that got the
4267 deleted text.
4268
4269 The {regname} argument is a string. If {regname} is invalid
4270 or not set, an empty Dictionary will be returned.
4271 If {regname} is "" or "@", the unnamed register '"' is used.
4272 If {regname} is not specified, |v:register| is used.
4273 The returned Dictionary can be passed to |setreg()|.
4274 In |Vim9-script| {regname} must be one character.
4275
4276 Can also be used as a |method|: >
4277 GetRegname()->getreginfo()
4278
Shougo Matsushita19b71882024-02-28 22:48:12 +01004279getregion({pos1}, {pos2} [, {opts}]) *getregion()*
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004280 Returns the list of strings from {pos1} to {pos2} from a
Shougo Matsushita19b71882024-02-28 22:48:12 +01004281 buffer.
4282
4283 {pos1} and {pos2} must both be |List|s with four numbers.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004284 See |getpos()| for the format of the list. It's possible
4285 to specify positions from a different buffer, but please
zeertzjq0df8f932024-03-07 21:40:53 +01004286 note the limitations at |getregion-notes|.
Shougo Matsushita19b71882024-02-28 22:48:12 +01004287
4288 The optional argument {opts} is a Dict and supports the
4289 following items:
4290
zeertzjq87410ab2024-03-02 06:00:23 +08004291 type Specify the region's selection type
Shougo Matsushita19b71882024-02-28 22:48:12 +01004292 (default: "v"):
4293 "v" for |characterwise| mode
4294 "V" for |linewise| mode
4295 "<CTRL-V>" for |blockwise-visual| mode
4296
zeertzjq87410ab2024-03-02 06:00:23 +08004297 exclusive If |TRUE|, use exclusive selection
4298 for the end position
4299 (default: follow 'selection')
Shougo Matsushita19b71882024-02-28 22:48:12 +01004300
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004301 You can get the last selection type by |visualmode()|.
4302 If Visual mode is active, use |mode()| to get the Visual mode
4303 (e.g., in a |:vmap|).
zeertzjq87410ab2024-03-02 06:00:23 +08004304 This function is useful to get text starting and ending in
4305 different columns, such as a |characterwise-visual| selection.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004306
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004307 *getregion-notes*
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004308 Note that:
4309 - Order of {pos1} and {pos2} doesn't matter, it will always
4310 return content from the upper left position to the lower
4311 right position.
zeertzjq87410ab2024-03-02 06:00:23 +08004312 - If 'virtualedit' is enabled and the region is past the end
4313 of the lines, resulting lines are padded with spaces.
4314 - If the region is blockwise and it starts or ends in the
4315 middle of a multi-cell character, it is not included but
4316 its selected part is substituted with spaces.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004317 - If {pos1} and {pos2} are not in the same buffer, an empty
zeertzjq421b5972024-02-22 19:48:06 +01004318 list is returned.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004319 - {pos1} and {pos2} must belong to a |bufloaded()| buffer.
zeertzjq0df8f932024-03-07 21:40:53 +01004320 - It is evaluated in current window context, which makes a
4321 difference if the buffer is displayed in a window with
4322 different 'virtualedit' or 'list' values.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004323
4324 Examples: >
4325 :xnoremap <CR>
Shougo Matsushita19b71882024-02-28 22:48:12 +01004326 \ <Cmd>echow getregion(
4327 \ getpos('v'), getpos('.'), #{ type: mode() })<CR>
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004328<
4329 Can also be used as a |method|: >
Shougo Matsushita19b71882024-02-28 22:48:12 +01004330 getpos('.')->getregion(getpos("'a"))
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004331<
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004332getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()*
4333 Same as |getregion()|, but returns a list of positions
4334 describing the buffer text segments bound by {pos1} and
4335 {pos2}.
4336 The segments are a pair of positions for every line: >
4337 [[{start_pos}, {end_pos}], ...]
4338<
4339 The position is a |List| with four numbers:
4340 [bufnum, lnum, col, off]
4341 "bufnum" is the buffer number.
4342 "lnum" and "col" are the position in the buffer. The first
4343 column is 1.
zeertzjqc95e64f2024-05-20 14:00:31 +02004344 If the "off" number of a starting position is non-zero, it is
4345 the offset in screen columns from the start of the character.
4346 E.g., a position within a <Tab> or after the last character.
4347 If the "off" number of an ending position is non-zero, it is
4348 the character's number of cells included in the selection,
4349 otherwise the whole character is included.
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004350
4351 Can also be used as a |method|: >
4352 getpos('.')->getregionpos(getpos("'a"))
4353<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004354getregtype([{regname}]) *getregtype()*
4355 The result is a String, which is type of register {regname}.
4356 The value will be one of:
4357 "v" for |characterwise| text
4358 "V" for |linewise| text
4359 "<CTRL-V>{width}" for |blockwise-visual| text
4360 "" for an empty or unknown register
4361 <CTRL-V> is one character with value 0x16.
4362 The {regname} argument is a string. If {regname} is "", the
4363 unnamed register '"' is used. If {regname} is not specified,
4364 |v:register| is used.
4365 In |Vim9-script| {regname} must be one character.
4366
4367 Can also be used as a |method|: >
4368 GetRegname()->getregtype()
4369
Bram Moolenaar71badf92023-04-22 22:40:14 +01004370getscriptinfo([{opts}]) *getscriptinfo()*
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004371 Returns a |List| with information about all the sourced Vim
Bram Moolenaar753885b2022-08-24 16:30:36 +01004372 scripts in the order they were sourced, like what
4373 `:scriptnames` shows.
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004374
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004375 The optional Dict argument {opts} supports the following
4376 optional items:
4377 name Script name match pattern. If specified,
4378 and "sid" is not specified, information about
Bram Moolenaar71badf92023-04-22 22:40:14 +01004379 scripts with a name that match the pattern
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004380 "name" are returned.
4381 sid Script ID |<SID>|. If specified, only
4382 information about the script with ID "sid" is
4383 returned and "name" is ignored.
4384
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004385 Each item in the returned List is a |Dict| with the following
4386 items:
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004387 autoload Set to TRUE for a script that was used with
Bram Moolenaar753885b2022-08-24 16:30:36 +01004388 `import autoload` but was not actually sourced
4389 yet (see |import-autoload|).
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004390 functions List of script-local function names defined in
4391 the script. Present only when a particular
4392 script is specified using the "sid" item in
4393 {opts}.
4394 name Vim script file name.
4395 sid Script ID |<SID>|.
4396 sourced Script ID of the actually sourced script that
Bram Moolenaarfd999452022-08-24 18:30:14 +01004397 this script name links to, if any, otherwise
4398 zero
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004399 variables A dictionary with the script-local variables.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00004400 Present only when a particular script is
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004401 specified using the "sid" item in {opts}.
4402 Note that this is a copy, the value of
4403 script-local variables cannot be changed using
4404 this dictionary.
h_east59858792023-10-25 22:47:05 +09004405 version Vim script version (|scriptversion|)
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01004406
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004407 Examples: >
4408 :echo getscriptinfo({'name': 'myscript'})
zeertzjqad4881c2024-05-04 15:35:30 +08004409 :echo getscriptinfo({'sid': 15})[0].variables
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004410<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004411gettabinfo([{tabnr}]) *gettabinfo()*
4412 If {tabnr} is not specified, then information about all the
4413 tab pages is returned as a |List|. Each List item is a
4414 |Dictionary|. Otherwise, {tabnr} specifies the tab page
4415 number and information about that one is returned. If the tab
4416 page does not exist an empty List is returned.
4417
4418 Each List item is a |Dictionary| with the following entries:
4419 tabnr tab page number.
4420 variables a reference to the dictionary with
4421 tabpage-local variables
4422 windows List of |window-ID|s in the tab page.
4423
4424 Can also be used as a |method|: >
4425 GetTabnr()->gettabinfo()
4426
4427gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
4428 Get the value of a tab-local variable {varname} in tab page
4429 {tabnr}. |t:var|
4430 Tabs are numbered starting with one.
4431 The {varname} argument is a string. When {varname} is empty a
4432 dictionary with all tab-local variables is returned.
4433 Note that the name without "t:" must be used.
4434 When the tab or variable doesn't exist {def} or an empty
4435 string is returned, there is no error message.
4436
4437 Can also be used as a |method|: >
4438 GetTabnr()->gettabvar(varname)
4439
4440gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
4441 Get the value of window-local variable {varname} in window
4442 {winnr} in tab page {tabnr}.
4443 The {varname} argument is a string. When {varname} is empty a
4444 dictionary with all window-local variables is returned.
4445 When {varname} is equal to "&" get the values of all
4446 window-local options in a |Dictionary|.
4447 Otherwise, when {varname} starts with "&" get the value of a
4448 window-local option.
4449 Note that {varname} must be the name without "w:".
4450 Tabs are numbered starting with one. For the current tabpage
4451 use |getwinvar()|.
4452 {winnr} can be the window number or the |window-ID|.
4453 When {winnr} is zero the current window is used.
4454 This also works for a global option, buffer-local option and
4455 window-local option, but it doesn't work for a global variable
4456 or buffer-local variable.
4457 When the tab, window or variable doesn't exist {def} or an
4458 empty string is returned, there is no error message.
4459 Examples: >
4460 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004461 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004462<
4463 To obtain all window-local variables use: >
4464 gettabwinvar({tabnr}, {winnr}, '&')
4465
4466< Can also be used as a |method|: >
4467 GetTabnr()->gettabwinvar(winnr, varname)
4468
4469gettagstack([{winnr}]) *gettagstack()*
4470 The result is a Dict, which is the tag stack of window {winnr}.
4471 {winnr} can be the window number or the |window-ID|.
4472 When {winnr} is not specified, the current window is used.
4473 When window {winnr} doesn't exist, an empty Dict is returned.
4474
4475 The returned dictionary contains the following entries:
4476 curidx Current index in the stack. When at
4477 top of the stack, set to (length + 1).
4478 Index of bottom of the stack is 1.
4479 items List of items in the stack. Each item
4480 is a dictionary containing the
4481 entries described below.
4482 length Number of entries in the stack.
4483
4484 Each item in the stack is a dictionary with the following
4485 entries:
4486 bufnr buffer number of the current jump
4487 from cursor position before the tag jump.
4488 See |getpos()| for the format of the
4489 returned list.
4490 matchnr current matching tag number. Used when
4491 multiple matching tags are found for a
4492 name.
4493 tagname name of the tag
4494
4495 See |tagstack| for more information about the tag stack.
4496
4497 Can also be used as a |method|: >
4498 GetWinnr()->gettagstack()
4499
4500
4501gettext({text}) *gettext()*
4502 Translate String {text} if possible.
4503 This is mainly for use in the distributed Vim scripts. When
4504 generating message translations the {text} is extracted by
4505 xgettext, the translator can add the translated message in the
4506 .po file and Vim will lookup the translation when gettext() is
4507 called.
4508 For {text} double quoted strings are preferred, because
4509 xgettext does not understand escaping in single quoted
4510 strings.
4511
4512
4513getwininfo([{winid}]) *getwininfo()*
4514 Returns information about windows as a |List| with Dictionaries.
4515
4516 If {winid} is given Information about the window with that ID
4517 is returned, as a |List| with one item. If the window does not
4518 exist the result is an empty list.
4519
4520 Without {winid} information about all the windows in all the
4521 tab pages is returned.
4522
4523 Each List item is a |Dictionary| with the following entries:
4524 botline last complete displayed buffer line
4525 bufnr number of buffer in the window
4526 height window height (excluding winbar)
4527 loclist 1 if showing a location list
4528 {only with the +quickfix feature}
4529 quickfix 1 if quickfix or location list window
4530 {only with the +quickfix feature}
4531 terminal 1 if a terminal window
4532 {only with the +terminal feature}
4533 tabnr tab page number
4534 topline first displayed buffer line
4535 variables a reference to the dictionary with
4536 window-local variables
4537 width window width
4538 winbar 1 if the window has a toolbar, 0
4539 otherwise
4540 wincol leftmost screen column of the window;
4541 "col" from |win_screenpos()|
4542 textoff number of columns occupied by any
4543 'foldcolumn', 'signcolumn' and line
4544 number in front of the text
4545 winid |window-ID|
4546 winnr window number
4547 winrow topmost screen line of the window;
4548 "row" from |win_screenpos()|
4549
4550 Can also be used as a |method|: >
4551 GetWinnr()->getwininfo()
4552
4553getwinpos([{timeout}]) *getwinpos()*
4554 The result is a |List| with two numbers, the result of
4555 |getwinposx()| and |getwinposy()| combined:
4556 [x-pos, y-pos]
4557 {timeout} can be used to specify how long to wait in msec for
4558 a response from the terminal. When omitted 100 msec is used.
4559 Use a longer time for a remote terminal.
4560 When using a value less than 10 and no response is received
4561 within that time, a previously reported position is returned,
4562 if available. This can be used to poll for the position and
4563 do some work in the meantime: >
4564 while 1
4565 let res = getwinpos(1)
4566 if res[0] >= 0
4567 break
4568 endif
4569 " Do some work here
4570 endwhile
4571<
4572
4573 Can also be used as a |method|: >
4574 GetTimeout()->getwinpos()
4575<
4576 *getwinposx()*
4577getwinposx() The result is a Number, which is the X coordinate in pixels of
4578 the left hand side of the GUI Vim window. Also works for an
4579 xterm (uses a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01004580 The result will be -1 if the information is not available
4581 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004582 The value can be used with `:winpos`.
4583
4584 *getwinposy()*
4585getwinposy() The result is a Number, which is the Y coordinate in pixels of
4586 the top of the GUI Vim window. Also works for an xterm (uses
4587 a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01004588 The result will be -1 if the information is not available
4589 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004590 The value can be used with `:winpos`.
4591
4592getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
4593 Like |gettabwinvar()| for the current tabpage.
4594 Examples: >
4595 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004596 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004597
4598< Can also be used as a |method|: >
4599 GetWinnr()->getwinvar(varname)
4600<
4601glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
4602 Expand the file wildcards in {expr}. See |wildcards| for the
4603 use of special characters.
4604
4605 Unless the optional {nosuf} argument is given and is |TRUE|,
4606 the 'suffixes' and 'wildignore' options apply: Names matching
4607 one of the patterns in 'wildignore' will be skipped and
4608 'suffixes' affect the ordering of matches.
4609 'wildignorecase' always applies.
4610
4611 When {list} is present and it is |TRUE| the result is a |List|
4612 with all matching files. The advantage of using a List is,
4613 you also get filenames containing newlines correctly.
4614 Otherwise the result is a String and when there are several
4615 matches, they are separated by <NL> characters.
4616
4617 If the expansion fails, the result is an empty String or List.
4618
4619 You can also use |readdir()| if you need to do complicated
4620 things, such as limiting the number of matches.
4621
4622 A name for a non-existing file is not included. A symbolic
4623 link is only included if it points to an existing file.
4624 However, when the {alllinks} argument is present and it is
4625 |TRUE| then all symbolic links are included.
4626
4627 For most systems backticks can be used to get files names from
4628 any external command. Example: >
4629 :let tagfiles = glob("`find . -name tags -print`")
4630 :let &tags = substitute(tagfiles, "\n", ",", "g")
4631< The result of the program inside the backticks should be one
4632 item per line. Spaces inside an item are allowed.
4633
4634 See |expand()| for expanding special Vim variables. See
4635 |system()| for getting the raw output of an external command.
4636
4637 Can also be used as a |method|: >
4638 GetExpr()->glob()
4639
4640glob2regpat({string}) *glob2regpat()*
4641 Convert a file pattern, as used by glob(), into a search
4642 pattern. The result can be used to match with a string that
4643 is a file name. E.g. >
4644 if filename =~ glob2regpat('Make*.mak')
4645< This is equivalent to: >
4646 if filename =~ '^Make.*\.mak$'
4647< When {string} is an empty string the result is "^$", match an
4648 empty string.
4649 Note that the result depends on the system. On MS-Windows
4650 a backslash usually means a path separator.
4651
4652 Can also be used as a |method|: >
4653 GetExpr()->glob2regpat()
4654< *globpath()*
4655globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
4656 Perform glob() for String {expr} on all directories in {path}
4657 and concatenate the results. Example: >
4658 :echo globpath(&rtp, "syntax/c.vim")
4659<
4660 {path} is a comma-separated list of directory names. Each
4661 directory name is prepended to {expr} and expanded like with
4662 |glob()|. A path separator is inserted when needed.
4663 To add a comma inside a directory name escape it with a
4664 backslash. Note that on MS-Windows a directory may have a
4665 trailing backslash, remove it if you put a comma after it.
4666 If the expansion fails for one of the directories, there is no
4667 error message.
4668
4669 Unless the optional {nosuf} argument is given and is |TRUE|,
4670 the 'suffixes' and 'wildignore' options apply: Names matching
4671 one of the patterns in 'wildignore' will be skipped and
4672 'suffixes' affect the ordering of matches.
4673
4674 When {list} is present and it is |TRUE| the result is a |List|
4675 with all matching files. The advantage of using a List is, you
4676 also get filenames containing newlines correctly. Otherwise
4677 the result is a String and when there are several matches,
4678 they are separated by <NL> characters. Example: >
4679 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4680<
4681 {alllinks} is used as with |glob()|.
4682
4683 The "**" item can be used to search in a directory tree.
4684 For example, to find all "README.txt" files in the directories
4685 in 'runtimepath' and below: >
4686 :echo globpath(&rtp, "**/README.txt")
4687< Upwards search and limiting the depth of "**" is not
4688 supported, thus using 'path' will not always work properly.
4689
4690 Can also be used as a |method|, the base is passed as the
4691 second argument: >
4692 GetExpr()->globpath(&rtp)
4693<
4694 *has()*
4695has({feature} [, {check}])
4696 When {check} is omitted or is zero: The result is a Number,
4697 which is 1 if the feature {feature} is supported, zero
4698 otherwise. The {feature} argument is a string, case is
4699 ignored. See |feature-list| below.
4700
4701 When {check} is present and not zero: The result is a Number,
4702 which is 1 if the feature {feature} could ever be supported,
4703 zero otherwise. This is useful to check for a typo in
4704 {feature} and to detect dead code. Keep in mind that an older
4705 Vim version will not know about a feature added later and
4706 features that have been abandoned will not be known by the
4707 current Vim version.
4708
4709 Also see |exists()| and |exists_compiled()|.
4710
4711 Note that to skip code that has a syntax error when the
4712 feature is not available, Vim may skip the rest of the line
4713 and miss a following `endif`. Therefore put the `endif` on a
4714 separate line: >
4715 if has('feature')
4716 let x = this->breaks->without->the->feature
4717 endif
4718< If the `endif` would be moved to the second line as "| endif" it
4719 would not be found.
4720
4721
4722has_key({dict}, {key}) *has_key()*
4723 The result is a Number, which is TRUE if |Dictionary| {dict}
Bram Moolenaare8008642022-08-19 17:15:35 +01004724 has an entry with key {key}. FALSE otherwise.
4725 The {key} argument is a string. In |Vim9| script a number is
4726 also accepted (and converted to a string) but no other types.
4727 In legacy script the usual automatic conversion to string is
4728 done.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004729
4730 Can also be used as a |method|: >
4731 mydict->has_key(key)
4732
4733haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4734 The result is a Number:
4735 1 when the window has set a local directory via |:lcd|
4736 2 when the tab-page has set a local directory via |:tcd|
4737 0 otherwise.
4738
4739 Without arguments use the current window.
4740 With {winnr} use this window in the current tab page.
4741 With {winnr} and {tabnr} use the window in the specified tab
4742 page.
4743 {winnr} can be the window number or the |window-ID|.
4744 If {winnr} is -1 it is ignored and only the tabpage is used.
4745 Return 0 if the arguments are invalid.
4746 Examples: >
4747 if haslocaldir() == 1
4748 " window local directory case
4749 elseif haslocaldir() == 2
4750 " tab-local directory case
4751 else
4752 " global directory case
4753 endif
4754
4755 " current window
4756 :echo haslocaldir()
4757 :echo haslocaldir(0)
4758 :echo haslocaldir(0, 0)
4759 " window n in current tab page
4760 :echo haslocaldir(n)
4761 :echo haslocaldir(n, 0)
4762 " window n in tab page m
4763 :echo haslocaldir(n, m)
4764 " tab page m
4765 :echo haslocaldir(-1, m)
4766<
4767 Can also be used as a |method|: >
4768 GetWinnr()->haslocaldir()
4769
4770hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
4771 The result is a Number, which is TRUE if there is a mapping
4772 that contains {what} in somewhere in the rhs (what it is
4773 mapped to) and this mapping exists in one of the modes
4774 indicated by {mode}.
4775 The arguments {what} and {mode} are strings.
4776 When {abbr} is there and it is |TRUE| use abbreviations
4777 instead of mappings. Don't forget to specify Insert and/or
4778 Command-line mode.
4779 Both the global mappings and the mappings local to the current
4780 buffer are checked for a match.
4781 If no matching mapping is found FALSE is returned.
4782 The following characters are recognized in {mode}:
4783 n Normal mode
4784 v Visual and Select mode
4785 x Visual mode
4786 s Select mode
4787 o Operator-pending mode
4788 i Insert mode
4789 l Language-Argument ("r", "f", "t", etc.)
4790 c Command-line mode
4791 When {mode} is omitted, "nvo" is used.
4792
4793 This function is useful to check if a mapping already exists
4794 to a function in a Vim script. Example: >
4795 :if !hasmapto('\ABCdoit')
4796 : map <Leader>d \ABCdoit
4797 :endif
4798< This installs the mapping to "\ABCdoit" only if there isn't
4799 already a mapping to "\ABCdoit".
4800
4801 Can also be used as a |method|: >
4802 GetRHS()->hasmapto()
4803
4804histadd({history}, {item}) *histadd()*
4805 Add the String {item} to the history {history} which can be
4806 one of: *hist-names*
4807 "cmd" or ":" command line history
4808 "search" or "/" search pattern history
4809 "expr" or "=" typed expression history
4810 "input" or "@" input line history
4811 "debug" or ">" debug command history
4812 empty the current or last used history
4813 The {history} string does not need to be the whole name, one
4814 character is sufficient.
4815 If {item} does already exist in the history, it will be
4816 shifted to become the newest entry.
4817 The result is a Number: TRUE if the operation was successful,
4818 otherwise FALSE is returned.
4819
4820 Example: >
4821 :call histadd("input", strftime("%Y %b %d"))
4822 :let date=input("Enter date: ")
4823< This function is not available in the |sandbox|.
4824
4825 Can also be used as a |method|, the base is passed as the
4826 second argument: >
4827 GetHistory()->histadd('search')
4828
4829histdel({history} [, {item}]) *histdel()*
4830 Clear {history}, i.e. delete all its entries. See |hist-names|
4831 for the possible values of {history}.
4832
4833 If the parameter {item} evaluates to a String, it is used as a
4834 regular expression. All entries matching that expression will
4835 be removed from the history (if there are any).
4836 Upper/lowercase must match, unless "\c" is used |/\c|.
4837 If {item} evaluates to a Number, it will be interpreted as
4838 an index, see |:history-indexing|. The respective entry will
4839 be removed if it exists.
4840
4841 The result is TRUE for a successful operation, otherwise FALSE
4842 is returned.
4843
4844 Examples:
4845 Clear expression register history: >
4846 :call histdel("expr")
4847<
4848 Remove all entries starting with "*" from the search history: >
4849 :call histdel("/", '^\*')
4850<
4851 The following three are equivalent: >
4852 :call histdel("search", histnr("search"))
4853 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004854 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004855<
4856 To delete the last search pattern and use the last-but-one for
4857 the "n" command and 'hlsearch': >
4858 :call histdel("search", -1)
4859 :let @/ = histget("search", -1)
4860<
4861 Can also be used as a |method|: >
4862 GetHistory()->histdel()
4863
4864histget({history} [, {index}]) *histget()*
4865 The result is a String, the entry with Number {index} from
4866 {history}. See |hist-names| for the possible values of
4867 {history}, and |:history-indexing| for {index}. If there is
4868 no such entry, an empty String is returned. When {index} is
4869 omitted, the most recent item from the history is used.
4870
4871 Examples:
4872 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004873 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004874
4875< Define an Ex command ":H {num}" that supports re-execution of
4876 the {num}th entry from the output of |:history|. >
4877 :command -nargs=1 H execute histget("cmd", 0+<args>)
4878<
4879 Can also be used as a |method|: >
4880 GetHistory()->histget()
4881
4882histnr({history}) *histnr()*
4883 The result is the Number of the current entry in {history}.
4884 See |hist-names| for the possible values of {history}.
4885 If an error occurred, -1 is returned.
4886
4887 Example: >
4888 :let inp_index = histnr("expr")
4889
4890< Can also be used as a |method|: >
4891 GetHistory()->histnr()
4892<
4893hlexists({name}) *hlexists()*
4894 The result is a Number, which is TRUE if a highlight group
4895 called {name} exists. This is when the group has been
4896 defined in some way. Not necessarily when highlighting has
4897 been defined for it, it may also have been used for a syntax
4898 item.
4899 *highlight_exists()*
4900 Obsolete name: highlight_exists().
4901
4902 Can also be used as a |method|: >
4903 GetName()->hlexists()
4904<
4905hlget([{name} [, {resolve}]]) *hlget()*
4906 Returns a List of all the highlight group attributes. If the
4907 optional {name} is specified, then returns a List with only
4908 the attributes of the specified highlight group. Returns an
4909 empty List if the highlight group {name} is not present.
4910
4911 If the optional {resolve} argument is set to v:true and the
4912 highlight group {name} is linked to another group, then the
4913 link is resolved recursively and the attributes of the
4914 resolved highlight group are returned.
4915
4916 Each entry in the returned List is a Dictionary with the
4917 following items:
4918 cleared boolean flag, set to v:true if the highlight
4919 group attributes are cleared or not yet
4920 specified. See |highlight-clear|.
4921 cterm cterm attributes. See |highlight-cterm|.
4922 ctermbg cterm background color.
4923 See |highlight-ctermbg|.
4924 ctermfg cterm foreground color.
4925 See |highlight-ctermfg|.
4926 ctermul cterm underline color. See |highlight-ctermul|.
4927 default boolean flag, set to v:true if the highlight
4928 group link is a default link. See
4929 |highlight-default|.
4930 font highlight group font. See |highlight-font|.
4931 gui gui attributes. See |highlight-gui|.
4932 guibg gui background color. See |highlight-guibg|.
4933 guifg gui foreground color. See |highlight-guifg|.
4934 guisp gui special color. See |highlight-guisp|.
4935 id highlight group ID.
4936 linksto linked highlight group name.
4937 See |:highlight-link|.
4938 name highlight group name. See |group-name|.
4939 start start terminal keycode. See |highlight-start|.
4940 stop stop terminal keycode. See |highlight-stop|.
4941 term term attributes. See |highlight-term|.
4942
4943 The 'term', 'cterm' and 'gui' items in the above Dictionary
4944 have a dictionary value with the following optional boolean
4945 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
4946 'reverse', 'inverse' and 'strikethrough'.
4947
4948 Example(s): >
4949 :echo hlget()
4950 :echo hlget('ModeMsg')
4951 :echo hlget('Number', v:true)
4952<
4953 Can also be used as a |method|: >
4954 GetName()->hlget()
4955<
4956hlset({list}) *hlset()*
4957 Creates or modifies the attributes of a List of highlight
4958 groups. Each item in {list} is a dictionary containing the
4959 attributes of a highlight group. See |hlget()| for the list of
4960 supported items in this dictionary.
4961
4962 In addition to the items described in |hlget()|, the following
4963 additional items are supported in the dictionary:
4964
4965 force boolean flag to force the creation of
4966 a link for an existing highlight group
4967 with attributes.
4968
4969 The highlight group is identified using the 'name' item and
4970 the 'id' item (if supplied) is ignored. If a highlight group
4971 with a specified name doesn't exist, then it is created.
4972 Otherwise the attributes of an existing highlight group are
4973 modified.
4974
4975 If an empty dictionary value is used for the 'term' or 'cterm'
4976 or 'gui' entries, then the corresponding attributes are
4977 cleared. If the 'cleared' item is set to v:true, then all the
4978 attributes of the highlight group are cleared.
4979
4980 The 'linksto' item can be used to link a highlight group to
4981 another highlight group. See |:highlight-link|.
4982
4983 Returns zero for success, -1 for failure.
4984
4985 Example(s): >
4986 " add bold attribute to the Visual highlight group
4987 :call hlset([#{name: 'Visual',
4988 \ term: #{reverse: 1 , bold: 1}}])
4989 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
4990 :let l = hlget()
4991 :call hlset(l)
4992 " clear the Search highlight group
4993 :call hlset([#{name: 'Search', cleared: v:true}])
4994 " clear the 'term' attributes for a highlight group
4995 :call hlset([#{name: 'Title', term: {}}])
4996 " create the MyHlg group linking it to DiffAdd
4997 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
4998 " remove the MyHlg group link
4999 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
5000 " clear the attributes and a link
5001 :call hlset([#{name: 'MyHlg', cleared: v:true,
5002 \ linksto: 'NONE'}])
5003<
5004 Can also be used as a |method|: >
5005 GetAttrList()->hlset()
5006<
5007 *hlID()*
5008hlID({name}) The result is a Number, which is the ID of the highlight group
5009 with name {name}. When the highlight group doesn't exist,
5010 zero is returned.
5011 This can be used to retrieve information about the highlight
5012 group. For example, to get the background color of the
5013 "Comment" group: >
5014 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5015< *highlightID()*
5016 Obsolete name: highlightID().
5017
5018 Can also be used as a |method|: >
5019 GetName()->hlID()
5020
5021hostname() *hostname()*
5022 The result is a String, which is the name of the machine on
5023 which Vim is currently running. Machine names greater than
5024 256 characters long are truncated.
5025
5026iconv({string}, {from}, {to}) *iconv()*
5027 The result is a String, which is the text {string} converted
5028 from encoding {from} to encoding {to}.
5029 When the conversion completely fails an empty string is
5030 returned. When some characters could not be converted they
5031 are replaced with "?".
5032 The encoding names are whatever the iconv() library function
5033 can accept, see ":!man 3 iconv".
5034 Most conversions require Vim to be compiled with the |+iconv|
5035 feature. Otherwise only UTF-8 to latin1 conversion and back
5036 can be done.
5037 This can be used to display messages with special characters,
5038 no matter what 'encoding' is set to. Write the message in
5039 UTF-8 and use: >
5040 echo iconv(utf8_str, "utf-8", &enc)
5041< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5042 from/to UCS-2 is automatically changed to use UTF-8. You
5043 cannot use UCS-2 in a string anyway, because of the NUL bytes.
5044
5045 Can also be used as a |method|: >
5046 GetText()->iconv('latin1', 'utf-8')
5047<
5048 *indent()*
5049indent({lnum}) The result is a Number, which is indent of line {lnum} in the
5050 current buffer. The indent is counted in spaces, the value
5051 of 'tabstop' is relevant. {lnum} is used just like in
5052 |getline()|.
5053 When {lnum} is invalid -1 is returned. In |Vim9| script an
5054 error is given.
5055
5056 Can also be used as a |method|: >
5057 GetLnum()->indent()
5058
5059index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005060 Find {expr} in {object} and return its index. See
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005061 |indexof()| for using a lambda to select the item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005062
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005063 If {object} is a |List| return the lowest index where the item
5064 has a value equal to {expr}. There is no automatic
5065 conversion, so the String "4" is different from the Number 4.
5066 And the number 4 is different from the Float 4.0. The value
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005067 of 'ignorecase' is not used here, case matters as indicated by
5068 the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005069
5070 If {object} is |Blob| return the lowest index where the byte
5071 value is equal to {expr}.
5072
5073 If {start} is given then start looking at the item with index
5074 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005075
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005076 When {ic} is given and it is |TRUE|, ignore case. Otherwise
5077 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005078
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005079 -1 is returned when {expr} is not found in {object}.
5080 Example: >
5081 :let idx = index(words, "the")
5082 :if index(numbers, 123) >= 0
5083
5084< Can also be used as a |method|: >
5085 GetObject()->index(what)
5086
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005087indexof({object}, {expr} [, {opts}]) *indexof()*
5088 Returns the index of an item in {object} where {expr} is
5089 v:true. {object} must be a |List| or a |Blob|.
5090
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005091 If {object} is a |List|, evaluate {expr} for each item in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005092 List until the expression is v:true and return the index of
5093 this item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005094
5095 If {object} is a |Blob| evaluate {expr} for each byte in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005096 Blob until the expression is v:true and return the index of
5097 this byte.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005098
5099 {expr} must be a |string| or |Funcref|.
5100
5101 If {expr} is a |string|: If {object} is a |List|, inside
5102 {expr} |v:key| has the index of the current List item and
5103 |v:val| has the value of the item. If {object} is a |Blob|,
5104 inside {expr} |v:key| has the index of the current byte and
5105 |v:val| has the byte value.
5106
5107 If {expr} is a |Funcref| it must take two arguments:
5108 1. the key or the index of the current item.
5109 2. the value of the current item.
5110 The function must return |TRUE| if the item is found and the
5111 search should stop.
5112
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005113 The optional argument {opts} is a Dict and supports the
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005114 following items:
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005115 startidx start evaluating {expr} at the item with this
5116 index; may be negative for an item relative to
5117 the end
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005118 Returns -1 when {expr} evaluates to v:false for all the items.
5119 Example: >
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005120 :let l = [#{n: 10}, #{n: 20}, #{n: 30}]
5121 :echo indexof(l, "v:val.n == 20")
5122 :echo indexof(l, {i, v -> v.n == 30})
5123 :echo indexof(l, "v:val.n == 20", #{startidx: 1})
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005124
5125< Can also be used as a |method|: >
5126 mylist->indexof(expr)
5127
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005128input({prompt} [, {text} [, {completion}]]) *input()*
5129 The result is a String, which is whatever the user typed on
5130 the command-line. The {prompt} argument is either a prompt
5131 string, or a blank string (for no prompt). A '\n' can be used
5132 in the prompt to start a new line.
5133 The highlighting set with |:echohl| is used for the prompt.
5134 The input is entered just like a command-line, with the same
5135 editing commands and mappings. There is a separate history
5136 for lines typed for input().
5137 Example: >
5138 :if input("Coffee or beer? ") == "beer"
5139 : echo "Cheers!"
5140 :endif
5141<
5142 If the optional {text} argument is present and not empty, this
5143 is used for the default reply, as if the user typed this.
5144 Example: >
5145 :let color = input("Color? ", "white")
5146
5147< The optional {completion} argument specifies the type of
5148 completion supported for the input. Without it completion is
5149 not performed. The supported completion types are the same as
5150 that can be supplied to a user-defined command using the
5151 "-complete=" argument. Refer to |:command-completion| for
5152 more information. Example: >
5153 let fname = input("File: ", "", "file")
5154<
5155 NOTE: This function must not be used in a startup file, for
5156 the versions that only run in GUI mode (e.g., the Win32 GUI).
5157 Note: When input() is called from within a mapping it will
5158 consume remaining characters from that mapping, because a
5159 mapping is handled like the characters were typed.
5160 Use |inputsave()| before input() and |inputrestore()|
5161 after input() to avoid that. Another solution is to avoid
5162 that further characters follow in the mapping, e.g., by using
5163 |:execute| or |:normal|.
5164
5165 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005166 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005167 :function GetFoo()
5168 : call inputsave()
5169 : let g:Foo = input("enter search pattern: ")
5170 : call inputrestore()
5171 :endfunction
5172
5173< Can also be used as a |method|: >
5174 GetPrompt()->input()
5175
5176inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
5177 Like |input()|, but when the GUI is running and text dialogs
5178 are supported, a dialog window pops up to input the text.
5179 Example: >
5180 :let n = inputdialog("value for shiftwidth", shiftwidth())
5181 :if n != ""
5182 : let &sw = n
5183 :endif
5184< When the dialog is cancelled {cancelreturn} is returned. When
5185 omitted an empty string is returned.
5186 Hitting <Enter> works like pressing the OK button. Hitting
5187 <Esc> works like pressing the Cancel button.
5188 NOTE: Command-line completion is not supported.
5189
5190 Can also be used as a |method|: >
5191 GetPrompt()->inputdialog()
5192
5193inputlist({textlist}) *inputlist()*
5194 {textlist} must be a |List| of strings. This |List| is
5195 displayed, one string per line. The user will be prompted to
5196 enter a number, which is returned.
5197 The user can also select an item by clicking on it with the
5198 mouse, if the mouse is enabled in the command line ('mouse' is
5199 "a" or includes "c"). For the first string 0 is returned.
5200 When clicking above the first item a negative number is
5201 returned. When clicking on the prompt one more than the
5202 length of {textlist} is returned.
5203 Make sure {textlist} has less than 'lines' entries, otherwise
5204 it won't work. It's a good idea to put the entry number at
5205 the start of the string. And put a prompt in the first item.
5206 Example: >
5207 let color = inputlist(['Select color:', '1. red',
5208 \ '2. green', '3. blue'])
5209
5210< Can also be used as a |method|: >
5211 GetChoices()->inputlist()
5212
5213inputrestore() *inputrestore()*
5214 Restore typeahead that was saved with a previous |inputsave()|.
5215 Should be called the same number of times inputsave() is
5216 called. Calling it more often is harmless though.
5217 Returns TRUE when there is nothing to restore, FALSE otherwise.
5218
5219inputsave() *inputsave()*
5220 Preserve typeahead (also from mappings) and clear it, so that
5221 a following prompt gets input from the user. Should be
5222 followed by a matching inputrestore() after the prompt. Can
5223 be used several times, in which case there must be just as
5224 many inputrestore() calls.
5225 Returns TRUE when out of memory, FALSE otherwise.
5226
5227inputsecret({prompt} [, {text}]) *inputsecret()*
5228 This function acts much like the |input()| function with but
5229 two exceptions:
5230 a) the user's response will be displayed as a sequence of
5231 asterisks ("*") thereby keeping the entry secret, and
5232 b) the user's response will not be recorded on the input
5233 |history| stack.
5234 The result is a String, which is whatever the user actually
5235 typed on the command-line in response to the issued prompt.
5236 NOTE: Command-line completion is not supported.
5237
5238 Can also be used as a |method|: >
5239 GetPrompt()->inputsecret()
5240
5241insert({object}, {item} [, {idx}]) *insert()*
5242 When {object} is a |List| or a |Blob| insert {item} at the start
5243 of it.
5244
5245 If {idx} is specified insert {item} before the item with index
5246 {idx}. If {idx} is zero it goes before the first item, just
5247 like omitting {idx}. A negative {idx} is also possible, see
5248 |list-index|. -1 inserts just before the last item.
5249
5250 Returns the resulting |List| or |Blob|. Examples: >
5251 :let mylist = insert([2, 3, 5], 1)
5252 :call insert(mylist, 4, -1)
5253 :call insert(mylist, 6, len(mylist))
5254< The last example can be done simpler with |add()|.
5255 Note that when {item} is a |List| it is inserted as a single
5256 item. Use |extend()| to concatenate |Lists|.
5257
5258 Can also be used as a |method|: >
5259 mylist->insert(item)
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005260<
5261 *instanceof()* *E614* *E616* *E693*
5262instanceof({object}, {class})
5263 The result is a Number, which is |TRUE| when the {object}
Ernie Rael2025af12023-12-12 16:58:00 +01005264 argument is a direct or indirect instance of a |Class|,
5265 |Interface|, or class |:type| alias specified by {class}.
5266 If {class} is varargs, the function returns |TRUE| when
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005267 {object} is an instance of any of the specified classes.
LemonBoyafe04662023-08-23 21:08:11 +02005268 Example: >
Ernie Rael2025af12023-12-12 16:58:00 +01005269 instanceof(animal, Dog, Cat)
LemonBoyafe04662023-08-23 21:08:11 +02005270
5271< Can also be used as a |method|: >
5272 myobj->instanceof(mytype)
5273
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005274interrupt() *interrupt()*
5275 Interrupt script execution. It works more or less like the
5276 user typing CTRL-C, most commands won't execute and control
5277 returns to the user. This is useful to abort execution
5278 from lower down, e.g. in an autocommand. Example: >
5279 :function s:check_typoname(file)
5280 : if fnamemodify(a:file, ':t') == '['
5281 : echomsg 'Maybe typo'
5282 : call interrupt()
5283 : endif
5284 :endfunction
5285 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
5286
5287invert({expr}) *invert()*
5288 Bitwise invert. The argument is converted to a number. A
5289 List, Dict or Float argument causes an error. Example: >
5290 :let bits = invert(bits)
5291< Can also be used as a |method|: >
5292 :let bits = bits->invert()
5293
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005294isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01005295 The result is a Number, which is |TRUE| when {path} is an
5296 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005297 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01005298 On MS-Windows, it is considered absolute when it starts with an
5299 optional drive prefix and is followed by a '\' or '/'. UNC paths
5300 are always absolute.
5301 Example: >
5302 echo isabsolutepath('/usr/share/') " 1
5303 echo isabsolutepath('./foobar') " 0
5304 echo isabsolutepath('C:\Windows') " 1
5305 echo isabsolutepath('foobar') " 0
5306 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005307<
LemonBoydca1d402022-04-28 15:26:33 +01005308 Can also be used as a |method|: >
5309 GetName()->isabsolutepath()
5310
5311
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005312isdirectory({directory}) *isdirectory()*
5313 The result is a Number, which is |TRUE| when a directory
5314 with the name {directory} exists. If {directory} doesn't
5315 exist, or isn't a directory, the result is |FALSE|. {directory}
5316 is any expression, which is used as a String.
5317
5318 Can also be used as a |method|: >
5319 GetName()->isdirectory()
5320
5321isinf({expr}) *isinf()*
5322 Return 1 if {expr} is a positive infinity, or -1 a negative
5323 infinity, otherwise 0. >
5324 :echo isinf(1.0 / 0.0)
5325< 1 >
5326 :echo isinf(-1.0 / 0.0)
5327< -1
5328
5329 Can also be used as a |method|: >
5330 Compute()->isinf()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005331
5332islocked({expr}) *islocked()* *E786*
5333 The result is a Number, which is |TRUE| when {expr} is the
5334 name of a locked variable.
5335 The string argument {expr} must be the name of a variable,
5336 |List| item or |Dictionary| entry, not the variable itself!
5337 Example: >
5338 :let alist = [0, ['a', 'b'], 2, 3]
5339 :lockvar 1 alist
5340 :echo islocked('alist') " 1
5341 :echo islocked('alist[1]') " 0
5342
Bram Moolenaar9da17d72022-02-09 21:50:44 +00005343< When {expr} is a variable that does not exist -1 is returned.
5344 If {expr} uses a range, list or dict index that is out of
5345 range or does not exist you get an error message. Use
5346 |exists()| to check for existence.
5347 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005348
5349 Can also be used as a |method|: >
5350 GetName()->islocked()
5351
5352isnan({expr}) *isnan()*
5353 Return |TRUE| if {expr} is a float with value NaN. >
5354 echo isnan(0.0 / 0.0)
5355< 1
5356
5357 Can also be used as a |method|: >
5358 Compute()->isnan()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005359
5360items({dict}) *items()*
5361 Return a |List| with all the key-value pairs of {dict}. Each
5362 |List| item is a list with two items: the key of a {dict}
5363 entry and the value of this entry. The |List| is in arbitrary
5364 order. Also see |keys()| and |values()|.
5365 Example: >
5366 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005367 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005368 endfor
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01005369<
5370 A List or a String argument is also supported. In these
5371 cases, items() returns a List with the index and the value at
5372 the index.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005373
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01005374 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005375 mydict->items()
5376
5377job_ functions are documented here: |job-functions-details|
5378
5379
5380join({list} [, {sep}]) *join()*
5381 Join the items in {list} together into one String.
5382 When {sep} is specified it is put in between the items. If
5383 {sep} is omitted a single space is used.
5384 Note that {sep} is not added at the end. You might want to
5385 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005386 let lines = join(mylist, "\n") .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005387< String items are used as-is. |Lists| and |Dictionaries| are
5388 converted into a string like with |string()|.
5389 The opposite function is |split()|.
5390
5391 Can also be used as a |method|: >
5392 mylist->join()
5393
5394js_decode({string}) *js_decode()*
5395 This is similar to |json_decode()| with these differences:
5396 - Object key names do not have to be in quotes.
5397 - Strings can be in single quotes.
5398 - Empty items in an array (between two commas) are allowed and
5399 result in v:none items.
5400
5401 Can also be used as a |method|: >
5402 ReadObject()->js_decode()
5403
5404js_encode({expr}) *js_encode()*
5405 This is similar to |json_encode()| with these differences:
5406 - Object key names are not in quotes.
5407 - v:none items in an array result in an empty item between
5408 commas.
5409 For example, the Vim object:
5410 [1,v:none,{"one":1},v:none] ~
5411 Will be encoded as:
5412 [1,,{one:1},,] ~
5413 While json_encode() would produce:
5414 [1,null,{"one":1},null] ~
5415 This encoding is valid for JavaScript. It is more efficient
5416 than JSON, especially when using an array with optional items.
5417
5418 Can also be used as a |method|: >
5419 GetObject()->js_encode()
5420
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005421json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005422 This parses a JSON formatted string and returns the equivalent
5423 in Vim values. See |json_encode()| for the relation between
5424 JSON and Vim values.
5425 The decoding is permissive:
5426 - A trailing comma in an array and object is ignored, e.g.
5427 "[1, 2, ]" is the same as "[1, 2]".
5428 - Integer keys are accepted in objects, e.g. {1:2} is the
5429 same as {"1":2}.
5430 - More floating point numbers are recognized, e.g. "1." for
5431 "1.0", or "001.2" for "1.2". Special floating point values
5432 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
5433 are accepted.
5434 - Leading zeroes in integer numbers are ignored, e.g. "012"
5435 for "12" or "-012" for "-12".
5436 - Capitalization is ignored in literal names null, true or
5437 false, e.g. "NULL" for "null", "True" for "true".
5438 - Control characters U+0000 through U+001F which are not
5439 escaped in strings are accepted, e.g. " " (tab
5440 character in string) for "\t".
5441 - An empty JSON expression or made of only spaces is accepted
5442 and results in v:none.
5443 - Backslash in an invalid 2-character sequence escape is
5444 ignored, e.g. "\a" is decoded as "a".
5445 - A correct surrogate pair in JSON strings should normally be
5446 a 12 character sequence such as "\uD834\uDD1E", but
5447 json_decode() silently accepts truncated surrogate pairs
5448 such as "\uD834" or "\uD834\u"
5449 *E938*
5450 A duplicate key in an object, valid in rfc7159, is not
5451 accepted by json_decode() as the result must be a valid Vim
5452 type, e.g. this fails: {"a":"b", "a":"c"}
5453
5454 Can also be used as a |method|: >
5455 ReadObject()->json_decode()
5456
5457json_encode({expr}) *json_encode()*
5458 Encode {expr} as JSON and return this as a string.
5459 The encoding is specified in:
5460 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00005461 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005462 |Number| decimal number
5463 |Float| floating point number
5464 Float nan "NaN"
5465 Float inf "Infinity"
5466 Float -inf "-Infinity"
5467 |String| in double quotes (possibly null)
5468 |Funcref| not possible, error
5469 |List| as an array (possibly null); when
5470 used recursively: []
5471 |Dict| as an object (possibly null); when
5472 used recursively: {}
5473 |Blob| as an array of the individual bytes
5474 v:false "false"
5475 v:true "true"
5476 v:none "null"
5477 v:null "null"
5478 Note that NaN and Infinity are passed on as values. This is
5479 missing in the JSON standard, but several implementations do
5480 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01005481 If a string contains an illegal character then the replacement
5482 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005483
5484 Can also be used as a |method|: >
5485 GetObject()->json_encode()
5486
5487keys({dict}) *keys()*
5488 Return a |List| with all the keys of {dict}. The |List| is in
5489 arbitrary order. Also see |items()| and |values()|.
5490
5491 Can also be used as a |method|: >
5492 mydict->keys()
5493
zeertzjqcdc83932022-09-12 13:38:41 +01005494keytrans({string}) *keytrans()*
5495 Turn the internal byte representation of keys into a form that
5496 can be used for |:map|. E.g. >
5497 :let xx = "\<C-Home>"
5498 :echo keytrans(xx)
5499< <C-Home>
5500
5501 Can also be used as a |method|: >
5502 "\<C-Home>"->keytrans()
5503
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005504< *len()* *E701*
5505len({expr}) The result is a Number, which is the length of the argument.
5506 When {expr} is a String or a Number the length in bytes is
5507 used, as with |strlen()|.
5508 When {expr} is a |List| the number of items in the |List| is
5509 returned.
5510 When {expr} is a |Blob| the number of bytes is returned.
5511 When {expr} is a |Dictionary| the number of entries in the
5512 |Dictionary| is returned.
mityu7f0bba22024-03-29 10:14:41 +01005513 When {expr} is an |Object|, invokes the len() method in the
5514 object (if present) to get the length (|object-len()|).
5515 Otherwise returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005516
5517 Can also be used as a |method|: >
5518 mylist->len()
5519
5520< *libcall()* *E364* *E368*
5521libcall({libname}, {funcname}, {argument})
5522 Call function {funcname} in the run-time library {libname}
5523 with single argument {argument}.
5524 This is useful to call functions in a library that you
5525 especially made to be used with Vim. Since only one argument
5526 is possible, calling standard library functions is rather
5527 limited.
5528 The result is the String returned by the function. If the
5529 function returns NULL, this will appear as an empty string ""
5530 to Vim.
5531 If the function returns a number, use libcallnr()!
5532 If {argument} is a number, it is passed to the function as an
5533 int; if {argument} is a string, it is passed as a
5534 null-terminated string.
5535 This function will fail in |restricted-mode|.
5536
5537 libcall() allows you to write your own 'plug-in' extensions to
5538 Vim without having to recompile the program. It is NOT a
5539 means to call system functions! If you try to do so Vim will
5540 very probably crash.
5541
5542 For Win32, the functions you write must be placed in a DLL
5543 and use the normal C calling convention (NOT Pascal which is
5544 used in Windows System DLLs). The function must take exactly
5545 one parameter, either a character pointer or a long integer,
5546 and must return a character pointer or NULL. The character
5547 pointer returned must point to memory that will remain valid
5548 after the function has returned (e.g. in static data in the
5549 DLL). If it points to allocated memory, that memory will
5550 leak away. Using a static buffer in the function should work,
5551 it's then freed when the DLL is unloaded.
5552
5553 WARNING: If the function returns a non-valid pointer, Vim may
5554 crash! This also happens if the function returns a number,
5555 because Vim thinks it's a pointer.
5556 For Win32 systems, {libname} should be the filename of the DLL
5557 without the ".DLL" suffix. A full path is only required if
5558 the DLL is not in the usual places.
5559 For Unix: When compiling your own plugins, remember that the
5560 object code must be compiled as position-independent ('PIC').
5561 {only in Win32 and some Unix versions, when the |+libcall|
5562 feature is present}
5563 Examples: >
5564 :echo libcall("libc.so", "getenv", "HOME")
5565
5566< Can also be used as a |method|, the base is passed as the
5567 third argument: >
5568 GetValue()->libcall("libc.so", "getenv")
5569<
5570 *libcallnr()*
5571libcallnr({libname}, {funcname}, {argument})
5572 Just like |libcall()|, but used for a function that returns an
5573 int instead of a string.
5574 {only in Win32 on some Unix versions, when the |+libcall|
5575 feature is present}
5576 Examples: >
5577 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
5578 :call libcallnr("libc.so", "printf", "Hello World!\n")
5579 :call libcallnr("libc.so", "sleep", 10)
5580<
5581 Can also be used as a |method|, the base is passed as the
5582 third argument: >
5583 GetValue()->libcallnr("libc.so", "printf")
5584<
5585
5586line({expr} [, {winid}]) *line()*
5587 The result is a Number, which is the line number of the file
5588 position given with {expr}. The {expr} argument is a string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00005589 The accepted positions are: *E1209*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005590 . the cursor position
5591 $ the last line in the current buffer
5592 'x position of mark x (if the mark is not set, 0 is
5593 returned)
5594 w0 first line visible in current window (one if the
5595 display isn't updated, e.g. in silent Ex mode)
5596 w$ last line visible in current window (this is one
5597 less than "w0" if no lines are visible)
5598 v In Visual mode: the start of the Visual area (the
5599 cursor is the end). When not in Visual mode
5600 returns the cursor position. Differs from |'<| in
5601 that it's updated right away.
5602 Note that a mark in another file can be used. The line number
5603 then applies to another buffer.
5604 To get the column number use |col()|. To get both use
5605 |getpos()|.
5606 With the optional {winid} argument the values are obtained for
5607 that window instead of the current window.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005608 Returns 0 for invalid values of {expr} and {winid}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005609 Examples: >
5610 line(".") line number of the cursor
5611 line(".", winid) idem, in window "winid"
5612 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005613 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005614<
5615 To jump to the last known position when opening a file see
5616 |last-position-jump|.
5617
5618 Can also be used as a |method|: >
5619 GetValue()->line()
5620
5621line2byte({lnum}) *line2byte()*
5622 Return the byte count from the start of the buffer for line
5623 {lnum}. This includes the end-of-line character, depending on
5624 the 'fileformat' option for the current buffer. The first
5625 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
5626 This can also be used to get the byte count for the line just
5627 below the last line: >
5628 line2byte(line("$") + 1)
5629< This is the buffer size plus one. If 'fileencoding' is empty
5630 it is the file size plus one. {lnum} is used like with
5631 |getline()|. When {lnum} is invalid, or the |+byte_offset|
5632 feature has been disabled at compile time, -1 is returned.
5633 Also see |byte2line()|, |go| and |:goto|.
5634
5635 Can also be used as a |method|: >
5636 GetLnum()->line2byte()
5637
5638lispindent({lnum}) *lispindent()*
5639 Get the amount of indent for line {lnum} according the lisp
5640 indenting rules, as with 'lisp'.
5641 The indent is counted in spaces, the value of 'tabstop' is
5642 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01005643 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005644 error is given.
5645
5646 Can also be used as a |method|: >
5647 GetLnum()->lispindent()
5648
5649list2blob({list}) *list2blob()*
5650 Return a Blob concatenating all the number values in {list}.
5651 Examples: >
5652 list2blob([1, 2, 3, 4]) returns 0z01020304
5653 list2blob([]) returns 0z
5654< Returns an empty Blob on error. If one of the numbers is
5655 negative or more than 255 error *E1239* is given.
5656
5657 |blob2list()| does the opposite.
5658
5659 Can also be used as a |method|: >
5660 GetList()->list2blob()
5661
5662list2str({list} [, {utf8}]) *list2str()*
5663 Convert each number in {list} to a character string can
5664 concatenate them all. Examples: >
5665 list2str([32]) returns " "
5666 list2str([65, 66, 67]) returns "ABC"
5667< The same can be done (slowly) with: >
5668 join(map(list, {nr, val -> nr2char(val)}), '')
5669< |str2list()| does the opposite.
5670
5671 When {utf8} is omitted or zero, the current 'encoding' is used.
5672 When {utf8} is TRUE, always return UTF-8 characters.
5673 With UTF-8 composing characters work as expected: >
5674 list2str([97, 769]) returns "á"
5675<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005676 Returns an empty string on error.
5677
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005678 Can also be used as a |method|: >
5679 GetList()->list2str()
5680
5681listener_add({callback} [, {buf}]) *listener_add()*
5682 Add a callback function that will be invoked when changes have
5683 been made to buffer {buf}.
5684 {buf} refers to a buffer name or number. For the accepted
5685 values, see |bufname()|. When {buf} is omitted the current
5686 buffer is used.
5687 Returns a unique ID that can be passed to |listener_remove()|.
5688
5689 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00005690 bufnr the buffer that was changed
5691 start first changed line number
5692 end first line number below the change
5693 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005694 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00005695 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005696
5697 Example: >
5698 func Listener(bufnr, start, end, added, changes)
5699 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
5700 endfunc
5701 call listener_add('Listener', bufnr)
5702
Bram Moolenaar944697a2022-02-20 19:48:20 +00005703< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005704 dictionary with these entries:
5705 lnum the first line number of the change
5706 end the first line below the change
5707 added number of lines added; negative if lines were
5708 deleted
5709 col first column in "lnum" that was affected by
5710 the change; one if unknown or the whole line
5711 was affected; this is a byte index, first
5712 character has a value of one.
Bram Moolenaar3c053a12022-10-16 13:11:12 +01005713 When lines are inserted (not when a line is split, e.g. by
5714 typing CR in Insert mode) the values are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005715 lnum line above which the new line is added
5716 end equal to "lnum"
5717 added number of lines inserted
5718 col 1
5719 When lines are deleted the values are:
5720 lnum the first deleted line
5721 end the line below the first deleted line, before
5722 the deletion was done
5723 added negative, number of lines deleted
5724 col 1
5725 When lines are changed:
5726 lnum the first changed line
5727 end the line below the last changed line
5728 added 0
5729 col first column with a change or 1
5730
5731 The entries are in the order the changes were made, thus the
5732 most recent change is at the end. The line numbers are valid
5733 when the callback is invoked, but later changes may make them
5734 invalid, thus keeping a copy for later might not work.
5735
5736 The {callback} is invoked just before the screen is updated,
5737 when |listener_flush()| is called or when a change is being
5738 made that changes the line count in a way it causes a line
5739 number in the list of changes to become invalid.
5740
5741 The {callback} is invoked with the text locked, see
5742 |textlock|. If you do need to make changes to the buffer, use
5743 a timer to do this later |timer_start()|.
5744
5745 The {callback} is not invoked when the buffer is first loaded.
5746 Use the |BufReadPost| autocmd event to handle the initial text
5747 of a buffer.
5748 The {callback} is also not invoked when the buffer is
5749 unloaded, use the |BufUnload| autocmd event for that.
5750
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005751 Returns zero if {callback} or {buf} is invalid.
5752
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005753 Can also be used as a |method|, the base is passed as the
5754 second argument: >
5755 GetBuffer()->listener_add(callback)
5756
5757listener_flush([{buf}]) *listener_flush()*
5758 Invoke listener callbacks for buffer {buf}. If there are no
5759 pending changes then no callbacks are invoked.
5760
5761 {buf} refers to a buffer name or number. For the accepted
5762 values, see |bufname()|. When {buf} is omitted the current
5763 buffer is used.
5764
5765 Can also be used as a |method|: >
5766 GetBuffer()->listener_flush()
5767
5768listener_remove({id}) *listener_remove()*
5769 Remove a listener previously added with listener_add().
5770 Returns FALSE when {id} could not be found, TRUE when {id} was
5771 removed.
5772
5773 Can also be used as a |method|: >
5774 GetListenerId()->listener_remove()
5775
5776localtime() *localtime()*
5777 Return the current time, measured as seconds since 1st Jan
5778 1970. See also |strftime()|, |strptime()| and |getftime()|.
5779
5780
5781log({expr}) *log()*
5782 Return the natural logarithm (base e) of {expr} as a |Float|.
5783 {expr} must evaluate to a |Float| or a |Number| in the range
5784 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005785 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005786 Examples: >
5787 :echo log(10)
5788< 2.302585 >
5789 :echo log(exp(5))
5790< 5.0
5791
5792 Can also be used as a |method|: >
5793 Compute()->log()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005794
5795
5796log10({expr}) *log10()*
5797 Return the logarithm of Float {expr} to base 10 as a |Float|.
5798 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005799 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005800 Examples: >
5801 :echo log10(1000)
5802< 3.0 >
5803 :echo log10(0.01)
5804< -2.0
5805
5806 Can also be used as a |method|: >
5807 Compute()->log10()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005808
5809luaeval({expr} [, {expr}]) *luaeval()*
5810 Evaluate Lua expression {expr} and return its result converted
5811 to Vim data structures. Second {expr} may hold additional
5812 argument accessible as _A inside first {expr}.
5813 Strings are returned as they are.
5814 Boolean objects are converted to numbers.
Bram Moolenaar73e28dc2022-09-17 21:08:33 +01005815 Numbers are converted to |Float| values.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005816 Dictionaries and lists obtained by vim.eval() are returned
5817 as-is.
5818 Other objects are returned as zero without any errors.
5819 See |lua-luaeval| for more details.
5820 Note that in a `:def` function local variables are not visible
5821 to {expr}.
5822
5823 Can also be used as a |method|: >
5824 GetExpr()->luaeval()
5825
5826< {only available when compiled with the |+lua| feature}
5827
5828map({expr1}, {expr2}) *map()*
5829 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00005830 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005831 item in {expr1} with the result of evaluating {expr2}.
5832 For a |Blob| each byte is replaced.
5833 For a |String|, each character, including composing
5834 characters, is replaced.
5835 If the item type changes you may want to use |mapnew()| to
5836 create a new List or Dictionary. This is required when using
5837 Vim9 script.
5838
5839 {expr2} must be a |String| or |Funcref|.
5840
5841 If {expr2} is a |String|, inside {expr2} |v:val| has the value
5842 of the current item. For a |Dictionary| |v:key| has the key
5843 of the current item and for a |List| |v:key| has the index of
5844 the current item. For a |Blob| |v:key| has the index of the
5845 current byte. For a |String| |v:key| has the index of the
5846 current character.
5847 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005848 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005849< This puts "> " before and " <" after each item in "mylist".
5850
5851 Note that {expr2} is the result of an expression and is then
5852 used as an expression again. Often it is good to use a
5853 |literal-string| to avoid having to double backslashes. You
5854 still have to double ' quotes
5855
5856 If {expr2} is a |Funcref| it is called with two arguments:
5857 1. The key or the index of the current item.
5858 2. the value of the current item.
Bram Moolenaarb59ae592022-11-23 23:46:31 +00005859 With a legacy script lambda you don't get an error if it only
5860 accepts one argument, but with a Vim9 lambda you get "E1106:
5861 One argument too many", the number of arguments must match.
5862
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005863 The function must return the new value of the item. Example
5864 that changes each value by "key-value": >
5865 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005866 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005867 endfunc
5868 call map(myDict, function('KeyValue'))
5869< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005870 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005871< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005872 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005873< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005874 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005875<
5876 The operation is done in-place for a |List| and |Dictionary|.
5877 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005878 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005879
5880< Returns {expr1}, the |List| or |Dictionary| that was filtered,
5881 or a new |Blob| or |String|.
5882 When an error is encountered while evaluating {expr2} no
5883 further items in {expr1} are processed.
5884 When {expr2} is a Funcref errors inside a function are ignored,
5885 unless it was defined with the "abort" flag.
5886
5887 Can also be used as a |method|: >
5888 mylist->map(expr2)
5889
5890
5891maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
5892 When {dict} is omitted or zero: Return the rhs of mapping
5893 {name} in mode {mode}. The returned String has special
5894 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01005895 listing. When {dict} is TRUE a dictionary is returned, see
5896 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005897
5898 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005899 returned if {dict} is FALSE, otherwise returns an empty Dict.
5900 When the mapping for {name} is empty, then "<Nop>" is
5901 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005902
5903 The {name} can have special key names, like in the ":map"
5904 command.
5905
5906 {mode} can be one of these strings:
5907 "n" Normal
5908 "v" Visual (including Select)
5909 "o" Operator-pending
5910 "i" Insert
5911 "c" Cmd-line
5912 "s" Select
5913 "x" Visual
5914 "l" langmap |language-mapping|
5915 "t" Terminal-Job
5916 "" Normal, Visual and Operator-pending
5917 When {mode} is omitted, the modes for "" are used.
5918
5919 When {abbr} is there and it is |TRUE| use abbreviations
5920 instead of mappings.
5921
5922 When {dict} is there and it is |TRUE| return a dictionary
5923 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01005924 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005925 "lhs" The {lhs} of the mapping as it would be typed
5926 "lhsraw" The {lhs} of the mapping as raw bytes
5927 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
5928 form, only present when it differs from "lhsraw"
5929 "rhs" The {rhs} of the mapping as typed.
5930 "silent" 1 for a |:map-silent| mapping, else 0.
5931 "noremap" 1 if the {rhs} of the mapping is not remappable.
5932 "script" 1 if mapping was defined with <script>.
5933 "expr" 1 for an expression mapping (|:map-<expr>|).
5934 "buffer" 1 for a buffer local mapping (|:map-local|).
5935 "mode" Modes for which the mapping is defined. In
5936 addition to the modes mentioned above, these
5937 characters will be used:
5938 " " Normal, Visual and Operator-pending
5939 "!" Insert and Commandline mode
5940 (|mapmode-ic|)
5941 "sid" The script local ID, used for <sid> mappings
Bram Moolenaar71badf92023-04-22 22:40:14 +01005942 (|<SID>|). Negative for special contexts.
Bram Moolenaara9528b32022-01-18 20:51:35 +00005943 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005944 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005945 "lnum" The line number in "sid", zero if unknown.
5946 "nowait" Do not wait for other, longer mappings.
5947 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01005948 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01005949 "mode_bits" Vim's internal binary representation of "mode".
5950 |mapset()| ignores this; only "mode" is used.
5951 See |maplist()| for usage examples. The values
5952 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005953
5954 The dictionary can be used to restore a mapping with
5955 |mapset()|.
5956
5957 The mappings local to the current buffer are checked first,
5958 then the global mappings.
5959 This function can be used to map a key even when it's already
5960 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005961 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005962
5963< Can also be used as a |method|: >
5964 GetKey()->maparg('n')
5965
5966mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
5967 Check if there is a mapping that matches with {name} in mode
5968 {mode}. See |maparg()| for {mode} and special names in
5969 {name}.
5970 When {abbr} is there and it is |TRUE| use abbreviations
5971 instead of mappings.
5972 A match happens with a mapping that starts with {name} and
5973 with a mapping which is equal to the start of {name}.
5974
5975 matches mapping "a" "ab" "abc" ~
5976 mapcheck("a") yes yes yes
5977 mapcheck("abc") yes yes yes
5978 mapcheck("ax") yes no no
5979 mapcheck("b") no no no
5980
5981 The difference with maparg() is that mapcheck() finds a
5982 mapping that matches with {name}, while maparg() only finds a
5983 mapping for {name} exactly.
5984 When there is no mapping that starts with {name}, an empty
5985 String is returned. If there is one, the RHS of that mapping
5986 is returned. If there are several mappings that start with
5987 {name}, the RHS of one of them is returned. This will be
5988 "<Nop>" if the RHS is empty.
5989 The mappings local to the current buffer are checked first,
5990 then the global mappings.
5991 This function can be used to check if a mapping can be added
5992 without being ambiguous. Example: >
5993 :if mapcheck("_vv") == ""
5994 : map _vv :set guifont=7x13<CR>
5995 :endif
5996< This avoids adding the "_vv" mapping when there already is a
5997 mapping for "_v" or for "_vvv".
5998
5999 Can also be used as a |method|: >
6000 GetKey()->mapcheck('n')
6001
6002
Ernie Rael09661202022-04-25 14:40:44 +01006003maplist([{abbr}]) *maplist()*
6004 Returns a |List| of all mappings. Each List item is a |Dict|,
6005 the same as what is returned by |maparg()|, see
6006 |mapping-dict|. When {abbr} is there and it is |TRUE| use
6007 abbreviations instead of mappings.
6008
6009 Example to show all mappings with 'MultiMatch' in rhs: >
6010 vim9script
6011 echo maplist()->filter(
6012 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01006013< It can be tricky to find mappings for particular |:map-modes|.
6014 |mapping-dict|'s "mode_bits" can simplify this. For example,
6015 the mode_bits for Normal, Insert or Command-line modes are
6016 0x19. To find all the mappings available in those modes you
6017 can do: >
6018 vim9script
6019 var saved_maps = []
6020 for m in maplist()
6021 if and(m.mode_bits, 0x19) != 0
6022 saved_maps->add(m)
6023 endif
6024 endfor
6025 echo saved_maps->mapnew((_, m) => m.lhs)
6026< The values of the mode_bits are defined in Vim's src/vim.h
6027 file and they can be discovered at runtime using
6028 |:map-commands| and "maplist()". Example: >
6029 vim9script
6030 omap xyzzy <Nop>
6031 var op_bit = maplist()->filter(
6032 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
6033 ounmap xyzzy
6034 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Ernie Rael09661202022-04-25 14:40:44 +01006035
6036
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006037mapnew({expr1}, {expr2}) *mapnew()*
6038 Like |map()| but instead of replacing items in {expr1} a new
6039 List or Dictionary is created and returned. {expr1} remains
6040 unchanged. Items can still be changed by {expr2}, if you
6041 don't want that use |deepcopy()| first.
6042
6043
6044mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01006045mapset({dict})
6046 Restore a mapping from a dictionary, possibly returned by
6047 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
6048 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01006049 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01006050 feature allows copying mappings from one buffer to another.
6051 The dict.mode value may restore a single mapping that covers
6052 more than one mode, like with mode values of '!', ' ', 'nox',
6053 or 'v'. *E1276*
6054
6055 In the first form, {mode} and {abbr} should be the same as
6056 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006057 {mode} is used to define the mode in which the mapping is set,
6058 not the "mode" entry in {dict}.
6059 Example for saving and restoring a mapping: >
6060 let save_map = maparg('K', 'n', 0, 1)
6061 nnoremap K somethingelse
6062 ...
6063 call mapset('n', 0, save_map)
6064< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01006065 e.g. with `:map!`, you need to save/restore the mapping for
6066 all of them, when they might differ.
6067
6068 In the second form, with {dict} as the only argument, mode
6069 and abbr are taken from the dict.
6070 Example: >
6071 vim9script
6072 var save_maps = maplist()->filter(
6073 (_, m) => m.lhs == 'K')
6074 nnoremap K somethingelse
6075 cnoremap K somethingelse2
6076 # ...
6077 unmap K
6078 for d in save_maps
6079 mapset(d)
6080 endfor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006081
6082
6083match({expr}, {pat} [, {start} [, {count}]]) *match()*
6084 When {expr} is a |List| then this returns the index of the
6085 first item where {pat} matches. Each item is used as a
6086 String, |Lists| and |Dictionaries| are used as echoed.
6087
6088 Otherwise, {expr} is used as a String. The result is a
6089 Number, which gives the index (byte offset) in {expr} where
6090 {pat} matches.
6091
6092 A match at the first character or |List| item returns zero.
6093 If there is no match -1 is returned.
6094
6095 For getting submatches see |matchlist()|.
6096 Example: >
6097 :echo match("testing", "ing") " results in 4
6098 :echo match([1, 'x'], '\a') " results in 1
6099< See |string-match| for how {pat} is used.
6100 *strpbrk()*
6101 Vim doesn't have a strpbrk() function. But you can do: >
6102 :let sepidx = match(line, '[.,;: \t]')
6103< *strcasestr()*
6104 Vim doesn't have a strcasestr() function. But you can add
6105 "\c" to the pattern to ignore case: >
6106 :let idx = match(haystack, '\cneedle')
6107<
6108 If {start} is given, the search starts from byte index
6109 {start} in a String or item {start} in a |List|.
6110 The result, however, is still the index counted from the
6111 first character/item. Example: >
6112 :echo match("testing", "ing", 2)
6113< result is again "4". >
6114 :echo match("testing", "ing", 4)
6115< result is again "4". >
6116 :echo match("testing", "t", 2)
6117< result is "3".
6118 For a String, if {start} > 0 then it is like the string starts
6119 {start} bytes later, thus "^" will match at {start}. Except
6120 when {count} is given, then it's like matches before the
6121 {start} byte are ignored (this is a bit complicated to keep it
6122 backwards compatible).
6123 For a String, if {start} < 0, it will be set to 0. For a list
6124 the index is counted from the end.
6125 If {start} is out of range ({start} > strlen({expr}) for a
6126 String or {start} > len({expr}) for a |List|) -1 is returned.
6127
6128 When {count} is given use the {count}'th match. When a match
6129 is found in a String the search for the next one starts one
6130 character further. Thus this example results in 1: >
6131 echo match("testing", "..", 0, 2)
6132< In a |List| the search continues in the next item.
6133 Note that when {count} is added the way {start} works changes,
6134 see above.
6135
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01006136 *match-pattern*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006137 See |pattern| for the patterns that are accepted.
6138 The 'ignorecase' option is used to set the ignore-caseness of
6139 the pattern. 'smartcase' is NOT used. The matching is always
6140 done like 'magic' is set and 'cpoptions' is empty.
6141 Note that a match at the start is preferred, thus when the
6142 pattern is using "*" (any number of matches) it tends to find
6143 zero matches at the start instead of a number of matches
6144 further down in the text.
6145
6146 Can also be used as a |method|: >
6147 GetText()->match('word')
6148 GetList()->match('word')
6149<
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00006150 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006151matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
6152 Defines a pattern to be highlighted in the current window (a
6153 "match"). It will be highlighted with {group}. Returns an
6154 identification number (ID), which can be used to delete the
6155 match using |matchdelete()|. The ID is bound to the window.
6156 Matching is case sensitive and magic, unless case sensitivity
6157 or magicness are explicitly overridden in {pattern}. The
6158 'magic', 'smartcase' and 'ignorecase' options are not used.
6159 The "Conceal" value is special, it causes the match to be
6160 concealed.
6161
6162 The optional {priority} argument assigns a priority to the
6163 match. A match with a high priority will have its
6164 highlighting overrule that of a match with a lower priority.
6165 A priority is specified as an integer (negative numbers are no
6166 exception). If the {priority} argument is not specified, the
6167 default priority is 10. The priority of 'hlsearch' is zero,
6168 hence all matches with a priority greater than zero will
6169 overrule it. Syntax highlighting (see 'syntax') is a separate
6170 mechanism, and regardless of the chosen priority a match will
6171 always overrule syntax highlighting.
6172
6173 The optional {id} argument allows the request for a specific
6174 match ID. If a specified ID is already taken, an error
6175 message will appear and the match will not be added. An ID
6176 is specified as a positive integer (zero excluded). IDs 1, 2
6177 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01006178 respectively. 3 is reserved for use by the |matchparen|
6179 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01006180 If the {id} argument is not specified or -1, |matchadd()|
Bram Moolenaar9f573a82022-09-29 13:50:08 +01006181 automatically chooses a free ID, which is at least 1000.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006182
6183 The optional {dict} argument allows for further custom
6184 values. Currently this is used to specify a match specific
6185 conceal character that will be shown for |hl-Conceal|
6186 highlighted matches. The dict can have the following members:
6187
6188 conceal Special character to show instead of the
6189 match (only for |hl-Conceal| highlighted
6190 matches, see |:syn-cchar|)
6191 window Instead of the current window use the
6192 window with this number or window ID.
6193
6194 The number of matches is not limited, as it is the case with
6195 the |:match| commands.
6196
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006197 Returns -1 on error.
6198
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006199 Example: >
6200 :highlight MyGroup ctermbg=green guibg=green
6201 :let m = matchadd("MyGroup", "TODO")
6202< Deletion of the pattern: >
6203 :call matchdelete(m)
6204
6205< A list of matches defined by |matchadd()| and |:match| are
6206 available from |getmatches()|. All matches can be deleted in
6207 one operation by |clearmatches()|.
6208
6209 Can also be used as a |method|: >
6210 GetGroup()->matchadd('TODO')
6211<
6212 *matchaddpos()*
6213matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
6214 Same as |matchadd()|, but requires a list of positions {pos}
6215 instead of a pattern. This command is faster than |matchadd()|
6216 because it does not require to handle regular expressions and
6217 sets buffer line boundaries to redraw screen. It is supposed
6218 to be used when fast match additions and deletions are
6219 required, for example to highlight matching parentheses.
6220
6221 {pos} is a list of positions. Each position can be one of
6222 these:
6223 - A number. This whole line will be highlighted. The first
6224 line has number 1.
6225 - A list with one number, e.g., [23]. The whole line with this
6226 number will be highlighted.
6227 - A list with two numbers, e.g., [23, 11]. The first number is
6228 the line number, the second one is the column number (first
6229 column is 1, the value must correspond to the byte index as
6230 |col()| would return). The character at this position will
6231 be highlighted.
6232 - A list with three numbers, e.g., [23, 11, 3]. As above, but
6233 the third number gives the length of the highlight in bytes.
6234
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006235 Returns -1 on error.
6236
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006237 Example: >
6238 :highlight MyGroup ctermbg=green guibg=green
6239 :let m = matchaddpos("MyGroup", [[23, 24], 34])
6240< Deletion of the pattern: >
6241 :call matchdelete(m)
6242
6243< Matches added by |matchaddpos()| are returned by
6244 |getmatches()|.
6245
6246 Can also be used as a |method|: >
6247 GetGroup()->matchaddpos([23, 11])
6248
6249matcharg({nr}) *matcharg()*
6250 Selects the {nr} match item, as set with a |:match|,
6251 |:2match| or |:3match| command.
6252 Return a |List| with two elements:
6253 The name of the highlight group used
6254 The pattern used.
6255 When {nr} is not 1, 2 or 3 returns an empty |List|.
6256 When there is no match item set returns ['', ''].
6257 This is useful to save and restore a |:match|.
6258 Highlighting matches using the |:match| commands are limited
6259 to three matches. |matchadd()| does not have this limitation.
6260
6261 Can also be used as a |method|: >
6262 GetMatch()->matcharg()
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006263<
6264 *matchbufline()*
6265matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])
6266 Returns the |List| of matches in lines from {lnum} to {end} in
6267 buffer {buf} where {pat} matches.
6268
6269 {lnum} and {end} can either be a line number or the string "$"
6270 to refer to the last line in {buf}.
6271
6272 The {dict} argument supports following items:
6273 submatches include submatch information (|/\(|)
6274
6275 For each match, a |Dict| with the following items is returned:
6276 byteidx starting byte index of the match
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08006277 lnum line number where there is a match
6278 text matched string
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006279 Note that there can be multiple matches in a single line.
6280
6281 This function works only for loaded buffers. First call
6282 |bufload()| if needed.
6283
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01006284 See |match-pattern| for information about the effect of some
6285 option settings on the pattern.
6286
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006287 When {buf} is not a valid buffer, the buffer is not loaded or
6288 {lnum} or {end} is not valid then an error is given and an
6289 empty |List| is returned.
6290
6291 Examples: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08006292 " Assuming line 3 in buffer 5 contains "a"
6293 :echo matchbufline(5, '\<\k\+\>', 3, 3)
6294 [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
6295 " Assuming line 4 in buffer 10 contains "tik tok"
6296 :echo matchbufline(10, '\<\k\+\>', 1, 4)
6297 [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006298<
6299 If {submatch} is present and is v:true, then submatches like
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08006300 "\1", "\2", etc. are also returned. Example: >
6301 " Assuming line 2 in buffer 2 contains "acd"
6302 :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006303 \ {'submatches': v:true})
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08006304 [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006305< The "submatches" List always contains 9 items. If a submatch
6306 is not found, then an empty string is returned for that
6307 submatch.
6308
6309 Can also be used as a |method|: >
6310 GetBuffer()->matchbufline('mypat', 1, '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006311
6312matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
6313 Deletes a match with ID {id} previously defined by |matchadd()|
6314 or one of the |:match| commands. Returns 0 if successful,
6315 otherwise -1. See example for |matchadd()|. All matches can
6316 be deleted in one operation by |clearmatches()|.
6317 If {win} is specified, use the window with this number or
6318 window ID instead of the current window.
6319
6320 Can also be used as a |method|: >
6321 GetMatch()->matchdelete()
6322
6323matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
6324 Same as |match()|, but return the index of first character
6325 after the match. Example: >
6326 :echo matchend("testing", "ing")
6327< results in "7".
6328 *strspn()* *strcspn()*
6329 Vim doesn't have a strspn() or strcspn() function, but you can
6330 do it with matchend(): >
6331 :let span = matchend(line, '[a-zA-Z]')
6332 :let span = matchend(line, '[^a-zA-Z]')
6333< Except that -1 is returned when there are no matches.
6334
6335 The {start}, if given, has the same meaning as for |match()|. >
6336 :echo matchend("testing", "ing", 2)
6337< results in "7". >
6338 :echo matchend("testing", "ing", 5)
6339< result is "-1".
6340 When {expr} is a |List| the result is equal to |match()|.
6341
6342 Can also be used as a |method|: >
6343 GetText()->matchend('word')
6344
6345
6346matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
6347 If {list} is a list of strings, then returns a |List| with all
6348 the strings in {list} that fuzzy match {str}. The strings in
6349 the returned list are sorted based on the matching score.
6350
6351 The optional {dict} argument always supports the following
6352 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01006353 matchseq When this item is present return only matches
6354 that contain the characters in {str} in the
6355 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01006356 limit Maximum number of matches in {list} to be
6357 returned. Zero means no limit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006358
6359 If {list} is a list of dictionaries, then the optional {dict}
6360 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01006361 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006362 {str}. The value of this item should be a
6363 string.
6364 text_cb |Funcref| that will be called for every item
6365 in {list} to get the text for fuzzy matching.
6366 This should accept a dictionary item as the
6367 argument and return the text for that item to
6368 use for fuzzy matching.
6369
6370 {str} is treated as a literal string and regular expression
6371 matching is NOT supported. The maximum supported {str} length
6372 is 256.
6373
6374 When {str} has multiple words each separated by white space,
6375 then the list of strings that have all the words is returned.
6376
6377 If there are no matching strings or there is an error, then an
6378 empty list is returned. If length of {str} is greater than
6379 256, then returns an empty list.
6380
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01006381 When {limit} is given, matchfuzzy() will find up to this
6382 number of matches in {list} and return them in sorted order.
6383
Bram Moolenaar1588bc82022-03-08 21:35:07 +00006384 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006385 matching strings.
6386
6387 Example: >
6388 :echo matchfuzzy(["clay", "crow"], "cay")
6389< results in ["clay"]. >
6390 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
6391< results in a list of buffer names fuzzy matching "ndl". >
6392 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
6393< results in a list of buffer information dicts with buffer
6394 names fuzzy matching "ndl". >
6395 :echo getbufinfo()->matchfuzzy("spl",
6396 \ {'text_cb' : {v -> v.name}})
6397< results in a list of buffer information dicts with buffer
6398 names fuzzy matching "spl". >
6399 :echo v:oldfiles->matchfuzzy("test")
6400< results in a list of file names fuzzy matching "test". >
6401 :let l = readfile("buffer.c")->matchfuzzy("str")
6402< results in a list of lines in "buffer.c" fuzzy matching "str". >
6403 :echo ['one two', 'two one']->matchfuzzy('two one')
6404< results in ['two one', 'one two']. >
6405 :echo ['one two', 'two one']->matchfuzzy('two one',
6406 \ {'matchseq': 1})
6407< results in ['two one'].
6408
6409matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
6410 Same as |matchfuzzy()|, but returns the list of matched
6411 strings, the list of character positions where characters
6412 in {str} matches and a list of matching scores. You can
6413 use |byteidx()| to convert a character position to a byte
6414 position.
6415
6416 If {str} matches multiple times in a string, then only the
6417 positions for the best match is returned.
6418
6419 If there are no matching strings or there is an error, then a
6420 list with three empty list items is returned.
6421
6422 Example: >
6423 :echo matchfuzzypos(['testing'], 'tsg')
6424< results in [['testing'], [[0, 2, 6]], [99]] >
6425 :echo matchfuzzypos(['clay', 'lacy'], 'la')
6426< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
6427 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
6428< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
6429
6430matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
6431 Same as |match()|, but return a |List|. The first item in the
6432 list is the matched string, same as what matchstr() would
6433 return. Following items are submatches, like "\1", "\2", etc.
6434 in |:substitute|. When an optional submatch didn't match an
6435 empty string is used. Example: >
6436 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
6437< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
6438 When there is no match an empty list is returned.
6439
6440 You can pass in a List, but that is not very useful.
6441
6442 Can also be used as a |method|: >
6443 GetText()->matchlist('word')
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006444<
6445 *matchstrlist()*
6446matchstrlist({list}, {pat} [, {dict}])
6447 Returns the |List| of matches in {list} where {pat} matches.
6448 {list} is a |List| of strings. {pat} is matched against each
6449 string in {list}.
6450
6451 The {dict} argument supports following items:
6452 submatches include submatch information (|/\(|)
6453
6454 For each match, a |Dict| with the following items is returned:
6455 byteidx starting byte index of the match.
6456 idx index in {list} of the match.
6457 text matched string
6458 submatches a List of submatches. Present only if
6459 "submatches" is set to v:true in {dict}.
6460
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01006461 See |match-pattern| for information about the effect of some
6462 option settings on the pattern.
6463
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006464 Example: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08006465 :echo matchstrlist(['tik tok'], '\<\k\+\>')
6466 [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
6467 :echo matchstrlist(['a', 'b'], '\<\k\+\>')
6468 [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006469<
6470 If "submatches" is present and is v:true, then submatches like
6471 "\1", "\2", etc. are also returned. Example: >
6472 :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
6473 \ #{submatches: v:true})
6474 [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
6475< The "submatches" List always contains 9 items. If a submatch
6476 is not found, then an empty string is returned for that
6477 submatch.
6478
6479 Can also be used as a |method|: >
6480 GetListOfStrings()->matchstrlist('mypat')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006481
6482matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
6483 Same as |match()|, but return the matched string. Example: >
6484 :echo matchstr("testing", "ing")
6485< results in "ing".
6486 When there is no match "" is returned.
6487 The {start}, if given, has the same meaning as for |match()|. >
6488 :echo matchstr("testing", "ing", 2)
6489< results in "ing". >
6490 :echo matchstr("testing", "ing", 5)
6491< result is "".
6492 When {expr} is a |List| then the matching item is returned.
6493 The type isn't changed, it's not necessarily a String.
6494
6495 Can also be used as a |method|: >
6496 GetText()->matchstr('word')
6497
6498matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
6499 Same as |matchstr()|, but return the matched string, the start
6500 position and the end position of the match. Example: >
6501 :echo matchstrpos("testing", "ing")
6502< results in ["ing", 4, 7].
6503 When there is no match ["", -1, -1] is returned.
6504 The {start}, if given, has the same meaning as for |match()|. >
6505 :echo matchstrpos("testing", "ing", 2)
6506< results in ["ing", 4, 7]. >
6507 :echo matchstrpos("testing", "ing", 5)
6508< result is ["", -1, -1].
6509 When {expr} is a |List| then the matching item, the index
6510 of first item where {pat} matches, the start position and the
6511 end position of the match are returned. >
6512 :echo matchstrpos([1, '__x'], '\a')
6513< result is ["x", 1, 2, 3].
6514 The type isn't changed, it's not necessarily a String.
6515
6516 Can also be used as a |method|: >
6517 GetText()->matchstrpos('word')
6518<
6519
6520 *max()*
6521max({expr}) Return the maximum value of all items in {expr}. Example: >
6522 echo max([apples, pears, oranges])
6523
6524< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6525 it returns the maximum of all values in the Dictionary.
6526 If {expr} is neither a List nor a Dictionary, or one of the
6527 items in {expr} cannot be used as a Number this results in
6528 an error. An empty |List| or |Dictionary| results in zero.
6529
6530 Can also be used as a |method|: >
6531 mylist->max()
6532
6533
6534menu_info({name} [, {mode}]) *menu_info()*
6535 Return information about the specified menu {name} in
6536 mode {mode}. The menu name should be specified without the
6537 shortcut character ('&'). If {name} is "", then the top-level
6538 menu names are returned.
6539
6540 {mode} can be one of these strings:
6541 "n" Normal
6542 "v" Visual (including Select)
6543 "o" Operator-pending
6544 "i" Insert
6545 "c" Cmd-line
6546 "s" Select
6547 "x" Visual
6548 "t" Terminal-Job
6549 "" Normal, Visual and Operator-pending
6550 "!" Insert and Cmd-line
6551 When {mode} is omitted, the modes for "" are used.
6552
6553 Returns a |Dictionary| containing the following items:
6554 accel menu item accelerator text |menu-text|
6555 display display name (name without '&')
6556 enabled v:true if this menu item is enabled
6557 Refer to |:menu-enable|
6558 icon name of the icon file (for toolbar)
6559 |toolbar-icon|
6560 iconidx index of a built-in icon
6561 modes modes for which the menu is defined. In
6562 addition to the modes mentioned above, these
6563 characters will be used:
6564 " " Normal, Visual and Operator-pending
6565 name menu item name.
6566 noremenu v:true if the {rhs} of the menu item is not
6567 remappable else v:false.
6568 priority menu order priority |menu-priority|
6569 rhs right-hand-side of the menu item. The returned
6570 string has special characters translated like
6571 in the output of the ":menu" command listing.
6572 When the {rhs} of a menu item is empty, then
6573 "<Nop>" is returned.
6574 script v:true if script-local remapping of {rhs} is
6575 allowed else v:false. See |:menu-script|.
6576 shortcut shortcut key (character after '&' in
6577 the menu name) |menu-shortcut|
6578 silent v:true if the menu item is created
6579 with <silent> argument |:menu-silent|
6580 submenus |List| containing the names of
6581 all the submenus. Present only if the menu
6582 item has submenus.
6583
6584 Returns an empty dictionary if the menu item is not found.
6585
6586 Examples: >
6587 :echo menu_info('Edit.Cut')
6588 :echo menu_info('File.Save', 'n')
6589
6590 " Display the entire menu hierarchy in a buffer
6591 func ShowMenu(name, pfx)
6592 let m = menu_info(a:name)
6593 call append(line('$'), a:pfx .. m.display)
6594 for child in m->get('submenus', [])
6595 call ShowMenu(a:name .. '.' .. escape(child, '.'),
6596 \ a:pfx .. ' ')
6597 endfor
6598 endfunc
6599 new
6600 for topmenu in menu_info('').submenus
6601 call ShowMenu(topmenu, '')
6602 endfor
6603<
6604 Can also be used as a |method|: >
6605 GetMenuName()->menu_info('v')
6606
6607
6608< *min()*
6609min({expr}) Return the minimum value of all items in {expr}. Example: >
6610 echo min([apples, pears, oranges])
6611
6612< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6613 it returns the minimum of all values in the Dictionary.
6614 If {expr} is neither a List nor a Dictionary, or one of the
6615 items in {expr} cannot be used as a Number this results in
6616 an error. An empty |List| or |Dictionary| results in zero.
6617
6618 Can also be used as a |method|: >
6619 mylist->min()
6620
6621< *mkdir()* *E739*
Bram Moolenaar938ae282023-02-20 20:44:55 +00006622mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006623 Create directory {name}.
6624
Bram Moolenaar938ae282023-02-20 20:44:55 +00006625 When {flags} is present it must be a string. An empty string
6626 has no effect.
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006627
Bram Moolenaar938ae282023-02-20 20:44:55 +00006628 If {flags} contains "p" then intermediate directories are
6629 created as necessary.
6630
6631 If {flags} contains "D" then {name} is deleted at the end of
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006632 the current function, as with: >
6633 defer delete({name}, 'd')
6634<
Bram Moolenaar938ae282023-02-20 20:44:55 +00006635 If {flags} contains "R" then {name} is deleted recursively at
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006636 the end of the current function, as with: >
6637 defer delete({name}, 'rf')
6638< Note that when {name} has more than one part and "p" is used
6639 some directories may already exist. Only the first one that
6640 is created and what it contains is scheduled to be deleted.
6641 E.g. when using: >
6642 call mkdir('subdir/tmp/autoload', 'pR')
6643< and "subdir" already exists then "subdir/tmp" will be
6644 scheduled for deletion, like with: >
6645 defer delete('subdir/tmp', 'rf')
6646< Note that if scheduling the defer fails the directory is not
6647 deleted. This should only happen when out of memory.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006648
6649 If {prot} is given it is used to set the protection bits of
6650 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
6651 the user, readable for others). Use 0o700 to make it
6652 unreadable for others. This is only used for the last part of
6653 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
6654 created with 0o755.
6655 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006656 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006657
6658< This function is not available in the |sandbox|.
6659
6660 There is no error if the directory already exists and the "p"
6661 flag is passed (since patch 8.0.1708). However, without the
6662 "p" option the call will fail.
6663
6664 The function result is a Number, which is TRUE if the call was
6665 successful or FALSE if the directory creation failed or partly
6666 failed.
6667
6668 Not available on all systems. To check use: >
6669 :if exists("*mkdir")
6670
6671< Can also be used as a |method|: >
6672 GetName()->mkdir()
6673<
6674 *mode()*
Doug Kearns9cd9e752024-04-07 17:42:17 +02006675mode([{expr}]) Return a string that indicates the current mode.
6676 If {expr} is supplied and it evaluates to a non-zero Number or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006677 a non-empty String (|non-zero-arg|), then the full mode is
6678 returned, otherwise only the first letter is returned.
6679 Also see |state()|.
6680
6681 n Normal
6682 no Operator-pending
6683 nov Operator-pending (forced characterwise |o_v|)
6684 noV Operator-pending (forced linewise |o_V|)
6685 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
6686 CTRL-V is one character
6687 niI Normal using |i_CTRL-O| in |Insert-mode|
6688 niR Normal using |i_CTRL-O| in |Replace-mode|
6689 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
6690 nt Terminal-Normal (insert goes to Terminal-Job mode)
6691 v Visual by character
6692 vs Visual by character using |v_CTRL-O| in Select mode
6693 V Visual by line
6694 Vs Visual by line using |v_CTRL-O| in Select mode
6695 CTRL-V Visual blockwise
6696 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
6697 s Select by character
6698 S Select by line
6699 CTRL-S Select blockwise
6700 i Insert
6701 ic Insert mode completion |compl-generic|
6702 ix Insert mode |i_CTRL-X| completion
6703 R Replace |R|
6704 Rc Replace mode completion |compl-generic|
6705 Rx Replace mode |i_CTRL-X| completion
6706 Rv Virtual Replace |gR|
6707 Rvc Virtual Replace mode completion |compl-generic|
6708 Rvx Virtual Replace mode |i_CTRL-X| completion
6709 c Command-line editing
h-east71ebf3b2023-09-03 17:12:55 +02006710 ct Command-line editing via Terminal-Job mode
zeertzjqfcaeb3d2023-11-28 20:46:29 +01006711 cr Command-line editing overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006712 cv Vim Ex mode |gQ|
zeertzjqfcaeb3d2023-11-28 20:46:29 +01006713 cvr Vim Ex mode while in overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006714 ce Normal Ex mode |Q|
6715 r Hit-enter prompt
6716 rm The -- more -- prompt
6717 r? A |:confirm| query of some sort
6718 ! Shell or external command is executing
6719 t Terminal-Job mode: keys go to the job
6720
6721 This is useful in the 'statusline' option or when used
6722 with |remote_expr()| In most other places it always returns
6723 "c" or "n".
6724 Note that in the future more modes and more specific modes may
6725 be added. It's better not to compare the whole string but only
6726 the leading character(s).
6727 Also see |visualmode()|.
6728
6729 Can also be used as a |method|: >
6730 DoFull()->mode()
6731
6732mzeval({expr}) *mzeval()*
6733 Evaluate MzScheme expression {expr} and return its result
6734 converted to Vim data structures.
6735 Numbers and strings are returned as they are.
6736 Pairs (including lists and improper lists) and vectors are
6737 returned as Vim |Lists|.
6738 Hash tables are represented as Vim |Dictionary| type with keys
6739 converted to strings.
6740 All other types are converted to string with display function.
6741 Examples: >
6742 :mz (define l (list 1 2 3))
6743 :mz (define h (make-hash)) (hash-set! h "list" l)
6744 :echo mzeval("l")
6745 :echo mzeval("h")
6746<
6747 Note that in a `:def` function local variables are not visible
6748 to {expr}.
6749
6750 Can also be used as a |method|: >
6751 GetExpr()->mzeval()
6752<
6753 {only available when compiled with the |+mzscheme| feature}
6754
6755nextnonblank({lnum}) *nextnonblank()*
6756 Return the line number of the first line at or below {lnum}
6757 that is not blank. Example: >
6758 if getline(nextnonblank(1)) =~ "Java"
6759< When {lnum} is invalid or there is no non-blank line at or
6760 below it, zero is returned.
6761 {lnum} is used like with |getline()|.
6762 See also |prevnonblank()|.
6763
6764 Can also be used as a |method|: >
6765 GetLnum()->nextnonblank()
6766
6767nr2char({expr} [, {utf8}]) *nr2char()*
6768 Return a string with a single character, which has the number
6769 value {expr}. Examples: >
6770 nr2char(64) returns "@"
6771 nr2char(32) returns " "
6772< When {utf8} is omitted or zero, the current 'encoding' is used.
6773 Example for "utf-8": >
6774 nr2char(300) returns I with bow character
6775< When {utf8} is TRUE, always return UTF-8 characters.
6776 Note that a NUL character in the file is specified with
6777 nr2char(10), because NULs are represented with newline
6778 characters. nr2char(0) is a real NUL and terminates the
6779 string, thus results in an empty string.
6780 To turn a list of character numbers into a string: >
6781 let list = [65, 66, 67]
6782 let str = join(map(list, {_, val -> nr2char(val)}), '')
6783< Result: "ABC"
6784
6785 Can also be used as a |method|: >
6786 GetNumber()->nr2char()
6787
6788or({expr}, {expr}) *or()*
6789 Bitwise OR on the two arguments. The arguments are converted
6790 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006791 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006792 Example: >
6793 :let bits = or(bits, 0x80)
6794< Can also be used as a |method|: >
6795 :let bits = bits->or(0x80)
6796
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006797< Rationale: The reason this is a function and not using the "|"
6798 character like many languages, is that Vi has always used "|"
6799 to separate commands. In many places it would not be clear if
6800 "|" is an operator or a command separator.
6801
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006802
6803pathshorten({path} [, {len}]) *pathshorten()*
6804 Shorten directory names in the path {path} and return the
6805 result. The tail, the file name, is kept as-is. The other
6806 components in the path are reduced to {len} letters in length.
6807 If {len} is omitted or smaller than 1 then 1 is used (single
6808 letters). Leading '~' and '.' characters are kept. Examples: >
6809 :echo pathshorten('~/.vim/autoload/myfile.vim')
6810< ~/.v/a/myfile.vim ~
6811>
6812 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
6813< ~/.vi/au/myfile.vim ~
6814 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006815 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006816
6817 Can also be used as a |method|: >
6818 GetDirectories()->pathshorten()
6819
6820perleval({expr}) *perleval()*
6821 Evaluate Perl expression {expr} in scalar context and return
6822 its result converted to Vim data structures. If value can't be
6823 converted, it is returned as a string Perl representation.
6824 Note: If you want an array or hash, {expr} must return a
6825 reference to it.
6826 Example: >
6827 :echo perleval('[1 .. 4]')
6828< [1, 2, 3, 4]
6829
6830 Note that in a `:def` function local variables are not visible
6831 to {expr}.
6832
6833 Can also be used as a |method|: >
6834 GetExpr()->perleval()
6835
6836< {only available when compiled with the |+perl| feature}
6837
6838
6839popup_ functions are documented here: |popup-functions|
6840
6841
6842pow({x}, {y}) *pow()*
6843 Return the power of {x} to the exponent {y} as a |Float|.
6844 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006845 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006846 Examples: >
6847 :echo pow(3, 3)
6848< 27.0 >
6849 :echo pow(2, 16)
6850< 65536.0 >
6851 :echo pow(32, 0.20)
6852< 2.0
6853
6854 Can also be used as a |method|: >
6855 Compute()->pow(3)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006856
6857prevnonblank({lnum}) *prevnonblank()*
6858 Return the line number of the first line at or above {lnum}
6859 that is not blank. Example: >
6860 let ind = indent(prevnonblank(v:lnum - 1))
6861< When {lnum} is invalid or there is no non-blank line at or
6862 above it, zero is returned.
6863 {lnum} is used like with |getline()|.
6864 Also see |nextnonblank()|.
6865
6866 Can also be used as a |method|: >
6867 GetLnum()->prevnonblank()
6868
6869printf({fmt}, {expr1} ...) *printf()*
6870 Return a String with {fmt}, where "%" items are replaced by
6871 the formatted form of their respective arguments. Example: >
6872 printf("%4d: E%d %.30s", lnum, errno, msg)
6873< May result in:
6874 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
6875
6876 When used as a |method| the base is passed as the second
6877 argument: >
6878 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006879<
6880 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006881
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006882 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006883 %s string
6884 %6S string right-aligned in 6 display cells
6885 %6s string right-aligned in 6 bytes
6886 %.9s string truncated to 9 bytes
6887 %c single byte
6888 %d decimal number
6889 %5d decimal number padded with spaces to 5 characters
6890 %x hex number
6891 %04x hex number padded with zeros to at least 4 characters
6892 %X hex number using upper case letters
6893 %o octal number
6894 %08b binary number padded with zeros to at least 8 chars
6895 %f floating point number as 12.23, inf, -inf or nan
6896 %F floating point number as 12.23, INF, -INF or NAN
6897 %e floating point number as 1.23e3, inf, -inf or nan
6898 %E floating point number as 1.23E3, INF, -INF or NAN
6899 %g floating point number, as %f or %e depending on value
6900 %G floating point number, as %F or %E depending on value
6901 %% the % character itself
6902
6903 Conversion specifications start with '%' and end with the
6904 conversion type. All other characters are copied unchanged to
6905 the result.
6906
6907 The "%" starts a conversion specification. The following
6908 arguments appear in sequence:
6909
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006910 % [pos-argument] [flags] [field-width] [.precision] type
6911
6912 pos-argument
6913 At most one positional argument specifier. These
6914 take the form {n$}, where n is >= 1.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006915
6916 flags
6917 Zero or more of the following flags:
6918
6919 # The value should be converted to an "alternate
6920 form". For c, d, and s conversions, this option
6921 has no effect. For o conversions, the precision
6922 of the number is increased to force the first
6923 character of the output string to a zero (except
6924 if a zero value is printed with an explicit
6925 precision of zero).
6926 For b and B conversions, a non-zero result has
6927 the string "0b" (or "0B" for B conversions)
6928 prepended to it.
6929 For x and X conversions, a non-zero result has
6930 the string "0x" (or "0X" for X conversions)
6931 prepended to it.
6932
6933 0 (zero) Zero padding. For all conversions the converted
6934 value is padded on the left with zeros rather
6935 than blanks. If a precision is given with a
6936 numeric conversion (d, b, B, o, x, and X), the 0
6937 flag is ignored.
6938
6939 - A negative field width flag; the converted value
6940 is to be left adjusted on the field boundary.
6941 The converted value is padded on the right with
6942 blanks, rather than on the left with blanks or
6943 zeros. A - overrides a 0 if both are given.
6944
6945 ' ' (space) A blank should be left before a positive
6946 number produced by a signed conversion (d).
6947
6948 + A sign must always be placed before a number
6949 produced by a signed conversion. A + overrides
6950 a space if both are used.
6951
6952 field-width
6953 An optional decimal digit string specifying a minimum
6954 field width. If the converted value has fewer bytes
6955 than the field width, it will be padded with spaces on
6956 the left (or right, if the left-adjustment flag has
6957 been given) to fill out the field width. For the S
6958 conversion the count is in cells.
6959
6960 .precision
6961 An optional precision, in the form of a period '.'
6962 followed by an optional digit string. If the digit
6963 string is omitted, the precision is taken as zero.
6964 This gives the minimum number of digits to appear for
6965 d, o, x, and X conversions, the maximum number of
6966 bytes to be printed from a string for s conversions,
6967 or the maximum number of cells to be printed from a
6968 string for S conversions.
6969 For floating point it is the number of digits after
6970 the decimal point.
6971
6972 type
6973 A character that specifies the type of conversion to
6974 be applied, see below.
6975
6976 A field width or precision, or both, may be indicated by an
6977 asterisk '*' instead of a digit string. In this case, a
6978 Number argument supplies the field width or precision. A
6979 negative field width is treated as a left adjustment flag
6980 followed by a positive field width; a negative precision is
6981 treated as though it were missing. Example: >
6982 :echo printf("%d: %.*s", nr, width, line)
6983< This limits the length of the text used from "line" to
6984 "width" bytes.
6985
Dominique Pellé17dca3c2023-12-14 20:36:32 +01006986 If the argument to be formatted is specified using a
6987 positional argument specifier, and a '*' is used to indicate
6988 that a number argument is to be used to specify the width or
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006989 precision, the argument(s) to be used must also be specified
6990 using a {n$} positional argument specifier. See |printf-$|.
6991
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006992 The conversion specifiers and their meanings are:
6993
6994 *printf-d* *printf-b* *printf-B* *printf-o*
6995 *printf-x* *printf-X*
6996 dbBoxX The Number argument is converted to signed decimal
6997 (d), unsigned binary (b and B), unsigned octal (o), or
6998 unsigned hexadecimal (x and X) notation. The letters
6999 "abcdef" are used for x conversions; the letters
7000 "ABCDEF" are used for X conversions.
7001 The precision, if any, gives the minimum number of
7002 digits that must appear; if the converted value
7003 requires fewer digits, it is padded on the left with
7004 zeros.
7005 In no case does a non-existent or small field width
7006 cause truncation of a numeric field; if the result of
7007 a conversion is wider than the field width, the field
7008 is expanded to contain the conversion result.
7009 The 'h' modifier indicates the argument is 16 bits.
Christ van Willegenaa90d4f2023-09-03 17:22:37 +02007010 The 'l' modifier indicates the argument is a long
7011 integer. The size will be 32 bits or 64 bits
7012 depending on your platform.
7013 The "ll" modifier indicates the argument is 64 bits.
7014 The b and B conversion specifiers never take a width
7015 modifier and always assume their argument is a 64 bit
7016 integer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007017 Generally, these modifiers are not useful. They are
7018 ignored when type is known from the argument.
7019
7020 i alias for d
7021 D alias for ld
7022 U alias for lu
7023 O alias for lo
7024
7025 *printf-c*
7026 c The Number argument is converted to a byte, and the
7027 resulting character is written.
7028
7029 *printf-s*
7030 s The text of the String argument is used. If a
7031 precision is specified, no more bytes than the number
7032 specified are used.
7033 If the argument is not a String type, it is
7034 automatically converted to text with the same format
7035 as ":echo".
7036 *printf-S*
7037 S The text of the String argument is used. If a
7038 precision is specified, no more display cells than the
7039 number specified are used.
7040
7041 *printf-f* *E807*
7042 f F The Float argument is converted into a string of the
7043 form 123.456. The precision specifies the number of
7044 digits after the decimal point. When the precision is
7045 zero the decimal point is omitted. When the precision
7046 is not specified 6 is used. A really big number
7047 (out of range or dividing by zero) results in "inf"
7048 or "-inf" with %f (INF or -INF with %F).
7049 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
7050 Example: >
7051 echo printf("%.2f", 12.115)
7052< 12.12
7053 Note that roundoff depends on the system libraries.
7054 Use |round()| when in doubt.
7055
7056 *printf-e* *printf-E*
7057 e E The Float argument is converted into a string of the
7058 form 1.234e+03 or 1.234E+03 when using 'E'. The
7059 precision specifies the number of digits after the
7060 decimal point, like with 'f'.
7061
7062 *printf-g* *printf-G*
7063 g G The Float argument is converted like with 'f' if the
7064 value is between 0.001 (inclusive) and 10000000.0
7065 (exclusive). Otherwise 'e' is used for 'g' and 'E'
7066 for 'G'. When no precision is specified superfluous
7067 zeroes and '+' signs are removed, except for the zero
7068 immediately after the decimal point. Thus 10000000.0
7069 results in 1.0e7.
7070
7071 *printf-%*
7072 % A '%' is written. No argument is converted. The
7073 complete conversion specification is "%%".
7074
7075 When a Number argument is expected a String argument is also
7076 accepted and automatically converted.
7077 When a Float or String argument is expected a Number argument
7078 is also accepted and automatically converted.
7079 Any other argument type results in an error message.
7080
7081 *E766* *E767*
7082 The number of {exprN} arguments must exactly match the number
7083 of "%" items. If there are not sufficient or too many
7084 arguments an error is given. Up to 18 arguments can be used.
7085
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007086 *printf-$*
7087 In certain languages, error and informative messages are
7088 more readable when the order of words is different from the
Christian Brabandtee17b6f2023-09-09 11:23:50 +02007089 corresponding message in English. To accommodate translations
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007090 having a different word order, positional arguments may be
7091 used to indicate this. For instance: >
7092
h_east596a9f22023-11-21 21:24:23 +09007093 #, c-format
7094 msgid "%s returning %s"
7095 msgstr "waarde %2$s komt terug van %1$s"
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007096<
h_east596a9f22023-11-21 21:24:23 +09007097 In this example, the sentence has its 2 string arguments
7098 reversed in the output. >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007099
h_east596a9f22023-11-21 21:24:23 +09007100 echo printf(
7101 "In The Netherlands, vim's creator's name is: %1$s %2$s",
7102 "Bram", "Moolenaar")
7103< In The Netherlands, vim's creator's name is: Bram Moolenaar >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007104
h_east596a9f22023-11-21 21:24:23 +09007105 echo printf(
7106 "In Belgium, vim's creator's name is: %2$s %1$s",
7107 "Bram", "Moolenaar")
7108< In Belgium, vim's creator's name is: Moolenaar Bram
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007109
7110 Width (and precision) can be specified using the '*' specifier.
7111 In this case, you must specify the field width position in the
7112 argument list. >
7113
h_east596a9f22023-11-21 21:24:23 +09007114 echo printf("%1$*2$.*3$d", 1, 2, 3)
7115< 001 >
7116 echo printf("%2$*3$.*1$d", 1, 2, 3)
7117< 2 >
7118 echo printf("%3$*1$.*2$d", 1, 2, 3)
7119< 03 >
7120 echo printf("%1$*2$.*3$g", 1.4142, 2, 3)
7121< 1.414
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007122
7123 You can mix specifying the width and/or precision directly
7124 and via positional arguments: >
7125
h_east596a9f22023-11-21 21:24:23 +09007126 echo printf("%1$4.*2$f", 1.4142135, 6)
7127< 1.414214 >
7128 echo printf("%1$*2$.4f", 1.4142135, 6)
7129< 1.4142 >
7130 echo printf("%1$*2$.*3$f", 1.4142135, 6, 2)
7131< 1.41
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007132
Christ van Willegenc35fc032024-03-14 18:30:41 +01007133 You will get an overflow error |E1510|, when the field-width
7134 or precision will result in a string longer than 6400 chars.
7135
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007136 *E1500*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007137 You cannot mix positional and non-positional arguments: >
h_east596a9f22023-11-21 21:24:23 +09007138 echo printf("%s%1$s", "One", "Two")
7139< E1500: Cannot mix positional and non-positional arguments:
7140 %s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007141
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007142 *E1501*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007143 You cannot skip a positional argument in a format string: >
h_east596a9f22023-11-21 21:24:23 +09007144 echo printf("%3$s%1$s", "One", "Two", "Three")
7145< E1501: format argument 2 unused in $-style format:
7146 %3$s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007147
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007148 *E1502*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007149 You can re-use a [field-width] (or [precision]) argument: >
h_east596a9f22023-11-21 21:24:23 +09007150 echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2)
7151< 1 at width 2 is: 01
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007152
7153 However, you can't use it as a different type: >
h_east596a9f22023-11-21 21:24:23 +09007154 echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2)
7155< E1502: Positional argument 2 used as field width reused as
7156 different type: long int/int
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007157
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007158 *E1503*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007159 When a positional argument is used, but not the correct number
7160 or arguments is given, an error is raised: >
h_east596a9f22023-11-21 21:24:23 +09007161 echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2)
7162< E1503: Positional argument 3 out of bounds: %1$d at width
7163 %2$d is: %01$*2$.*3$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007164
7165 Only the first error is reported: >
h_east596a9f22023-11-21 21:24:23 +09007166 echo printf("%01$*2$.*3$d %4$d", 1, 2)
7167< E1503: Positional argument 3 out of bounds: %01$*2$.*3$d
7168 %4$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007169
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007170 *E1504*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007171 A positional argument can be used more than once: >
h_east596a9f22023-11-21 21:24:23 +09007172 echo printf("%1$s %2$s %1$s", "One", "Two")
7173< One Two One
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007174
7175 However, you can't use a different type the second time: >
h_east596a9f22023-11-21 21:24:23 +09007176 echo printf("%1$s %2$s %1$d", "One", "Two")
7177< E1504: Positional argument 1 type used inconsistently:
7178 int/string
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007179
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007180 *E1505*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007181 Various other errors that lead to a format string being
7182 wrongly formatted lead to: >
h_east596a9f22023-11-21 21:24:23 +09007183 echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2)
7184< E1505: Invalid format specifier: %1$d at width %2$d is:
7185 %01$*2$.3$d
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007186
Christ van Willegenea746f92023-10-05 20:48:36 +02007187 *E1507*
zeertzjq27e12c72023-10-07 01:34:04 +08007188 This internal error indicates that the logic to parse a
7189 positional format argument ran into a problem that couldn't be
7190 otherwise reported. Please file a bug against Vim if you run
7191 into this, copying the exact format string and parameters that
7192 were used.
Christ van Willegenea746f92023-10-05 20:48:36 +02007193
7194
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007195prompt_getprompt({buf}) *prompt_getprompt()*
7196 Returns the effective prompt text for buffer {buf}. {buf} can
7197 be a buffer name or number. See |prompt-buffer|.
7198
7199 If the buffer doesn't exist or isn't a prompt buffer, an empty
7200 string is returned.
7201
7202 Can also be used as a |method|: >
7203 GetBuffer()->prompt_getprompt()
7204
7205< {only available when compiled with the |+channel| feature}
7206
7207
7208prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
7209 Set prompt callback for buffer {buf} to {expr}. When {expr}
7210 is an empty string the callback is removed. This has only
7211 effect if {buf} has 'buftype' set to "prompt".
7212
7213 The callback is invoked when pressing Enter. The current
7214 buffer will always be the prompt buffer. A new line for a
7215 prompt is added before invoking the callback, thus the prompt
7216 for which the callback was invoked will be in the last but one
7217 line.
7218 If the callback wants to add text to the buffer, it must
7219 insert it above the last line, since that is where the current
7220 prompt is. This can also be done asynchronously.
7221 The callback is invoked with one argument, which is the text
7222 that was entered at the prompt. This can be an empty string
7223 if the user only typed Enter.
7224 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007225 func s:TextEntered(text)
7226 if a:text == 'exit' || a:text == 'quit'
7227 stopinsert
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01007228 " Reset 'modified' to allow the buffer to be closed.
7229 " We assume there is nothing useful to be saved.
7230 set nomodified
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007231 close
7232 else
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01007233 " Do something useful with "a:text". In this example
7234 " we just repeat it.
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007235 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007236 endif
7237 endfunc
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01007238 call prompt_setcallback(bufnr(), function('s:TextEntered'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007239
7240< Can also be used as a |method|: >
7241 GetBuffer()->prompt_setcallback(callback)
7242
7243< {only available when compiled with the |+channel| feature}
7244
7245prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
7246 Set a callback for buffer {buf} to {expr}. When {expr} is an
7247 empty string the callback is removed. This has only effect if
7248 {buf} has 'buftype' set to "prompt".
7249
7250 This callback will be invoked when pressing CTRL-C in Insert
7251 mode. Without setting a callback Vim will exit Insert mode,
7252 as in any buffer.
7253
7254 Can also be used as a |method|: >
7255 GetBuffer()->prompt_setinterrupt(callback)
7256
7257< {only available when compiled with the |+channel| feature}
7258
7259prompt_setprompt({buf}, {text}) *prompt_setprompt()*
7260 Set prompt for buffer {buf} to {text}. You most likely want
7261 {text} to end in a space.
7262 The result is only visible if {buf} has 'buftype' set to
7263 "prompt". Example: >
7264 call prompt_setprompt(bufnr(), 'command: ')
7265<
7266 Can also be used as a |method|: >
7267 GetBuffer()->prompt_setprompt('command: ')
7268
7269< {only available when compiled with the |+channel| feature}
7270
7271prop_ functions are documented here: |text-prop-functions|
7272
7273pum_getpos() *pum_getpos()*
7274 If the popup menu (see |ins-completion-menu|) is not visible,
7275 returns an empty |Dictionary|, otherwise, returns a
7276 |Dictionary| with the following keys:
7277 height nr of items visible
7278 width screen cells
7279 row top screen row (0 first row)
7280 col leftmost screen column (0 first col)
7281 size total nr of items
7282 scrollbar |TRUE| if scrollbar is visible
7283
7284 The values are the same as in |v:event| during
7285 |CompleteChanged|.
7286
7287pumvisible() *pumvisible()*
7288 Returns non-zero when the popup menu is visible, zero
7289 otherwise. See |ins-completion-menu|.
7290 This can be used to avoid some things that would remove the
7291 popup menu.
7292
7293py3eval({expr}) *py3eval()*
7294 Evaluate Python expression {expr} and return its result
7295 converted to Vim data structures.
7296 Numbers and strings are returned as they are (strings are
7297 copied though, Unicode strings are additionally converted to
7298 'encoding').
7299 Lists are represented as Vim |List| type.
7300 Dictionaries are represented as Vim |Dictionary| type with
7301 keys converted to strings.
7302 Note that in a `:def` function local variables are not visible
7303 to {expr}.
7304
7305 Can also be used as a |method|: >
7306 GetExpr()->py3eval()
7307
7308< {only available when compiled with the |+python3| feature}
7309
7310 *E858* *E859*
7311pyeval({expr}) *pyeval()*
7312 Evaluate Python expression {expr} and return its result
7313 converted to Vim data structures.
7314 Numbers and strings are returned as they are (strings are
7315 copied though).
7316 Lists are represented as Vim |List| type.
7317 Dictionaries are represented as Vim |Dictionary| type,
7318 non-string keys result in error.
7319 Note that in a `:def` function local variables are not visible
7320 to {expr}.
7321
7322 Can also be used as a |method|: >
7323 GetExpr()->pyeval()
7324
7325< {only available when compiled with the |+python| feature}
7326
7327pyxeval({expr}) *pyxeval()*
7328 Evaluate Python expression {expr} and return its result
7329 converted to Vim data structures.
7330 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
7331 See also: |pyeval()|, |py3eval()|
7332
7333 Can also be used as a |method|: >
7334 GetExpr()->pyxeval()
7335
7336< {only available when compiled with the |+python| or the
7337 |+python3| feature}
7338
7339rand([{expr}]) *rand()* *random*
7340 Return a pseudo-random Number generated with an xoshiro128**
7341 algorithm using seed {expr}. The returned number is 32 bits,
7342 also on 64 bits systems, for consistency.
7343 {expr} can be initialized by |srand()| and will be updated by
7344 rand(). If {expr} is omitted, an internal seed value is used
7345 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007346 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007347
7348 Examples: >
7349 :echo rand()
7350 :let seed = srand()
7351 :echo rand(seed)
7352 :echo rand(seed) % 16 " random number 0 - 15
7353<
7354
7355 *E726* *E727*
7356range({expr} [, {max} [, {stride}]]) *range()*
7357 Returns a |List| with Numbers:
7358 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
7359 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
7360 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
7361 {max}] (increasing {expr} with {stride} each time, not
7362 producing a value past {max}).
7363 When the maximum is one before the start the result is an
7364 empty list. When the maximum is more than one before the
7365 start this is an error.
7366 Examples: >
7367 range(4) " [0, 1, 2, 3]
7368 range(2, 4) " [2, 3, 4]
7369 range(2, 9, 3) " [2, 5, 8]
7370 range(2, -2, -1) " [2, 1, 0, -1, -2]
7371 range(0) " []
7372 range(2, 0) " error!
7373<
7374 Can also be used as a |method|: >
7375 GetExpr()->range()
7376<
7377
K.Takata11df3ae2022-10-19 14:02:40 +01007378readblob({fname} [, {offset} [, {size}]]) *readblob()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007379 Read file {fname} in binary mode and return a |Blob|.
K.Takata11df3ae2022-10-19 14:02:40 +01007380 If {offset} is specified, read the file from the specified
7381 offset. If it is a negative value, it is used as an offset
7382 from the end of the file. E.g., to read the last 12 bytes: >
7383 readblob('file.bin', -12)
7384< If {size} is specified, only the specified size will be read.
7385 E.g. to read the first 100 bytes of a file: >
7386 readblob('file.bin', 0, 100)
7387< If {size} is -1 or omitted, the whole data starting from
7388 {offset} will be read.
K.Takata43625762022-10-20 13:28:51 +01007389 This can be also used to read the data from a character device
7390 on Unix when {size} is explicitly set. Only if the device
7391 supports seeking {offset} can be used. Otherwise it should be
7392 zero. E.g. to read 10 bytes from a serial console: >
7393 readblob('/dev/ttyS0', 0, 10)
7394< When the file can't be opened an error message is given and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007395 the result is an empty |Blob|.
Bram Moolenaar5b2a3d72022-10-21 11:25:30 +01007396 When the offset is beyond the end of the file the result is an
7397 empty blob.
7398 When trying to read more bytes than are available the result
7399 is truncated.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007400 Also see |readfile()| and |writefile()|.
7401
7402
7403readdir({directory} [, {expr} [, {dict}]]) *readdir()*
7404 Return a list with file and directory names in {directory}.
7405 You can also use |glob()| if you don't need to do complicated
7406 things, such as limiting the number of matches.
7407 The list will be sorted (case sensitive), see the {dict}
7408 argument below for changing the sort order.
7409
7410 When {expr} is omitted all entries are included.
7411 When {expr} is given, it is evaluated to check what to do:
7412 If {expr} results in -1 then no further entries will
7413 be handled.
7414 If {expr} results in 0 then this entry will not be
7415 added to the list.
7416 If {expr} results in 1 then this entry will be added
7417 to the list.
7418 The entries "." and ".." are always excluded.
7419 Each time {expr} is evaluated |v:val| is set to the entry name.
7420 When {expr} is a function the name is passed as the argument.
7421 For example, to get a list of files ending in ".txt": >
7422 readdir(dirname, {n -> n =~ '.txt$'})
7423< To skip hidden and backup files: >
7424 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00007425< *E857*
7426 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007427 values. Currently this is used to specify if and how sorting
7428 should be performed. The dict can have the following members:
7429
7430 sort How to sort the result returned from the system.
7431 Valid values are:
7432 "none" do not sort (fastest method)
7433 "case" sort case sensitive (byte value of
7434 each character, technically, using
7435 strcmp()) (default)
7436 "icase" sort case insensitive (technically
7437 using strcasecmp())
7438 "collate" sort using the collation order
7439 of the "POSIX" or "C" |locale|
7440 (technically using strcoll())
7441 Other values are silently ignored.
7442
7443 For example, to get a list of all files in the current
7444 directory without sorting the individual entries: >
7445 readdir('.', '1', #{sort: 'none'})
7446< If you want to get a directory tree: >
7447 function! s:tree(dir)
7448 return {a:dir : map(readdir(a:dir),
7449 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007450 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007451 endfunction
7452 echo s:tree(".")
7453<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007454 Returns an empty List on error.
7455
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007456 Can also be used as a |method|: >
7457 GetDirName()->readdir()
7458<
7459readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
7460 Extended version of |readdir()|.
7461 Return a list of Dictionaries with file and directory
7462 information in {directory}.
7463 This is useful if you want to get the attributes of file and
7464 directory at the same time as getting a list of a directory.
7465 This is much faster than calling |readdir()| then calling
7466 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
7467 each file and directory especially on MS-Windows.
7468 The list will by default be sorted by name (case sensitive),
7469 the sorting can be changed by using the optional {dict}
7470 argument, see |readdir()|.
7471
7472 The Dictionary for file and directory information has the
7473 following items:
7474 group Group name of the entry. (Only on Unix)
7475 name Name of the entry.
7476 perm Permissions of the entry. See |getfperm()|.
7477 size Size of the entry. See |getfsize()|.
7478 time Timestamp of the entry. See |getftime()|.
7479 type Type of the entry.
7480 On Unix, almost same as |getftype()| except:
7481 Symlink to a dir "linkd"
7482 Other symlink "link"
7483 On MS-Windows:
7484 Normal file "file"
7485 Directory "dir"
7486 Junction "junction"
7487 Symlink to a dir "linkd"
7488 Other symlink "link"
7489 Other reparse point "reparse"
7490 user User name of the entry's owner. (Only on Unix)
7491 On Unix, if the entry is a symlink, the Dictionary includes
7492 the information of the target (except the "type" item).
7493 On MS-Windows, it includes the information of the symlink
7494 itself because of performance reasons.
7495
7496 When {expr} is omitted all entries are included.
7497 When {expr} is given, it is evaluated to check what to do:
7498 If {expr} results in -1 then no further entries will
7499 be handled.
7500 If {expr} results in 0 then this entry will not be
7501 added to the list.
7502 If {expr} results in 1 then this entry will be added
7503 to the list.
7504 The entries "." and ".." are always excluded.
7505 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
7506 of the entry.
7507 When {expr} is a function the entry is passed as the argument.
7508 For example, to get a list of files ending in ".txt": >
7509 readdirex(dirname, {e -> e.name =~ '.txt$'})
7510<
7511 For example, to get a list of all files in the current
7512 directory without sorting the individual entries: >
7513 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007514<
7515 Can also be used as a |method|: >
7516 GetDirName()->readdirex()
7517<
7518
7519 *readfile()*
7520readfile({fname} [, {type} [, {max}]])
7521 Read file {fname} and return a |List|, each line of the file
7522 as an item. Lines are broken at NL characters. Macintosh
7523 files separated with CR will result in a single long line
7524 (unless a NL appears somewhere).
7525 All NUL characters are replaced with a NL character.
7526 When {type} contains "b" binary mode is used:
7527 - When the last line ends in a NL an extra empty list item is
7528 added.
7529 - No CR characters are removed.
7530 Otherwise:
7531 - CR characters that appear before a NL are removed.
7532 - Whether the last line ends in a NL or not does not matter.
7533 - When 'encoding' is Unicode any UTF-8 byte order mark is
7534 removed from the text.
7535 When {max} is given this specifies the maximum number of lines
7536 to be read. Useful if you only want to check the first ten
7537 lines of a file: >
7538 :for line in readfile(fname, '', 10)
7539 : if line =~ 'Date' | echo line | endif
7540 :endfor
7541< When {max} is negative -{max} lines from the end of the file
7542 are returned, or as many as there are.
7543 When {max} is zero the result is an empty list.
7544 Note that without {max} the whole file is read into memory.
7545 Also note that there is no recognition of encoding. Read a
7546 file into a buffer if you need to.
7547 Deprecated (use |readblob()| instead): When {type} contains
7548 "B" a |Blob| is returned with the binary data of the file
7549 unmodified.
7550 When the file can't be opened an error message is given and
7551 the result is an empty list.
7552 Also see |writefile()|.
7553
7554 Can also be used as a |method|: >
7555 GetFileName()->readfile()
7556
7557reduce({object}, {func} [, {initial}]) *reduce()* *E998*
7558 {func} is called for every item in {object}, which can be a
7559 |String|, |List| or a |Blob|. {func} is called with two
7560 arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00007561 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007562
7563 {initial} is the initial result. When omitted, the first item
7564 in {object} is used and {func} is first called for the second
7565 item. If {initial} is not given and {object} is empty no
7566 result can be computed, an E998 error is given.
7567
7568 Examples: >
7569 echo reduce([1, 3, 5], { acc, val -> acc + val })
7570 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
7571 echo reduce(0z1122, { acc, val -> 2 * acc + val })
7572 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
7573<
7574 Can also be used as a |method|: >
7575 echo mylist->reduce({ acc, val -> acc + val }, 0)
7576
7577
7578reg_executing() *reg_executing()*
7579 Returns the single letter name of the register being executed.
7580 Returns an empty string when no register is being executed.
7581 See |@|.
7582
7583reg_recording() *reg_recording()*
7584 Returns the single letter name of the register being recorded.
7585 Returns an empty string when not recording. See |q|.
7586
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007587reltime()
7588reltime({start})
7589reltime({start}, {end}) *reltime()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007590 Return an item that represents a time value. The item is a
7591 list with items that depend on the system. In Vim 9 script
Bram Moolenaar71badf92023-04-22 22:40:14 +01007592 the type list<any> can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007593 The item can be passed to |reltimestr()| to convert it to a
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007594 string or |reltimefloat()| to convert to a Float. For
7595 example, to see the time spent in function Work(): >
7596 var startTime = reltime()
7597 Work()
7598 echo startTime->reltime()->reltimestr()
7599<
Bram Moolenaar016188f2022-06-06 20:52:59 +01007600 Without an argument reltime() returns the current time (the
Lifepillar963fd7d2024-01-05 17:44:57 +01007601 representation is system-dependent, it cannot be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01007602 wall-clock time, see |localtime()| for that).
Lifepillar963fd7d2024-01-05 17:44:57 +01007603 With one argument it returns the time passed since the time
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007604 specified in the argument.
7605 With two arguments it returns the time passed between {start}
7606 and {end}.
7607
7608 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007609 reltime(). If there is an error an empty List is returned in
7610 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007611
7612 Can also be used as a |method|: >
7613 GetStart()->reltime()
7614<
7615 {only available when compiled with the |+reltime| feature}
7616
7617reltimefloat({time}) *reltimefloat()*
7618 Return a Float that represents the time value of {time}.
7619 Example: >
7620 let start = reltime()
7621 call MyFunction()
7622 let seconds = reltimefloat(reltime(start))
7623< See the note of reltimestr() about overhead.
7624 Also see |profiling|.
7625 If there is an error 0.0 is returned in legacy script, in Vim9
7626 script an error is given.
7627
7628 Can also be used as a |method|: >
7629 reltime(start)->reltimefloat()
7630
7631< {only available when compiled with the |+reltime| feature}
7632
7633reltimestr({time}) *reltimestr()*
7634 Return a String that represents the time value of {time}.
7635 This is the number of seconds, a dot and the number of
7636 microseconds. Example: >
7637 let start = reltime()
7638 call MyFunction()
7639 echo reltimestr(reltime(start))
7640< Note that overhead for the commands will be added to the time.
Ernie Rael076de792023-03-16 21:43:15 +00007641 The accuracy depends on the system. Use reltimefloat() for the
7642 greatest accuracy which is nanoseconds on some systems.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007643 Leading spaces are used to make the string align nicely. You
7644 can use split() to remove it. >
7645 echo split(reltimestr(reltime(start)))[0]
7646< Also see |profiling|.
7647 If there is an error an empty string is returned in legacy
7648 script, in Vim9 script an error is given.
7649
7650 Can also be used as a |method|: >
7651 reltime(start)->reltimestr()
7652
7653< {only available when compiled with the |+reltime| feature}
7654
7655 *remote_expr()* *E449*
7656remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007657 Send the {string} to {server}. The {server} argument is a
7658 string, also see |{server}|.
7659
7660 The string is sent as an expression and the result is returned
7661 after evaluation. The result must be a String or a |List|. A
7662 |List| is turned into a String by joining the items with a
7663 line break in between (not at the end), like with join(expr,
7664 "\n").
7665
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007666 If {idvar} is present and not empty, it is taken as the name
7667 of a variable and a {serverid} for later use with
7668 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007669
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007670 If {timeout} is given the read times out after this many
7671 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007672
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007673 See also |clientserver| |RemoteReply|.
7674 This function is not available in the |sandbox|.
7675 {only available when compiled with the |+clientserver| feature}
7676 Note: Any errors will cause a local error message to be issued
7677 and the result will be the empty string.
7678
7679 Variables will be evaluated in the global namespace,
7680 independent of a function currently being active. Except
7681 when in debug mode, then local function variables and
7682 arguments can be evaluated.
7683
7684 Examples: >
7685 :echo remote_expr("gvim", "2+2")
7686 :echo remote_expr("gvim1", "b:current_syntax")
7687<
7688 Can also be used as a |method|: >
7689 ServerName()->remote_expr(expr)
7690
7691remote_foreground({server}) *remote_foreground()*
7692 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007693 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007694 This works like: >
7695 remote_expr({server}, "foreground()")
7696< Except that on Win32 systems the client does the work, to work
7697 around the problem that the OS doesn't always allow the server
7698 to bring itself to the foreground.
7699 Note: This does not restore the window if it was minimized,
7700 like foreground() does.
7701 This function is not available in the |sandbox|.
7702
7703 Can also be used as a |method|: >
7704 ServerName()->remote_foreground()
7705
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007706< {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007707 Win32 console version}
7708
7709
7710remote_peek({serverid} [, {retvar}]) *remote_peek()*
7711 Returns a positive number if there are available strings
7712 from {serverid}. Copies any reply string into the variable
7713 {retvar} if specified. {retvar} must be a string with the
7714 name of a variable.
7715 Returns zero if none are available.
7716 Returns -1 if something is wrong.
7717 See also |clientserver|.
7718 This function is not available in the |sandbox|.
7719 {only available when compiled with the |+clientserver| feature}
7720 Examples: >
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007721 :let repl = ""
7722 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007723
7724< Can also be used as a |method|: >
7725 ServerId()->remote_peek()
7726
7727remote_read({serverid}, [{timeout}]) *remote_read()*
7728 Return the oldest available reply from {serverid} and consume
7729 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007730 reply is available. Returns an empty string, if a reply is
7731 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007732 See also |clientserver|.
7733 This function is not available in the |sandbox|.
7734 {only available when compiled with the |+clientserver| feature}
7735 Example: >
7736 :echo remote_read(id)
7737
7738< Can also be used as a |method|: >
7739 ServerId()->remote_read()
7740<
7741 *remote_send()* *E241*
7742remote_send({server}, {string} [, {idvar}])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007743 Send the {string} to {server}. The {server} argument is a
7744 string, also see |{server}|.
7745
7746 The string is sent as input keys and the function returns
7747 immediately. At the Vim server the keys are not mapped
7748 |:map|.
7749
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007750 If {idvar} is present, it is taken as the name of a variable
7751 and a {serverid} for later use with remote_read() is stored
7752 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007753
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007754 See also |clientserver| |RemoteReply|.
7755 This function is not available in the |sandbox|.
7756 {only available when compiled with the |+clientserver| feature}
7757
7758 Note: Any errors will be reported in the server and may mess
7759 up the display.
7760 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007761 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007762 \ remote_read(serverid)
7763
7764 :autocmd NONE RemoteReply *
7765 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007766 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007767 \ 'server2client(expand("<client>"), "HELLO")<CR>')
7768<
7769 Can also be used as a |method|: >
7770 ServerName()->remote_send(keys)
7771<
7772 *remote_startserver()* *E941* *E942*
7773remote_startserver({name})
h-east17b69512023-05-01 22:36:56 +01007774 Become the server {name}. {name} must be a non-empty string.
7775 This fails if already running as a server, when |v:servername|
7776 is not empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007777
7778 Can also be used as a |method|: >
7779 ServerName()->remote_startserver()
7780
7781< {only available when compiled with the |+clientserver| feature}
7782
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007783remove({list}, {idx})
7784remove({list}, {idx}, {end}) *remove()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007785 Without {end}: Remove the item at {idx} from |List| {list} and
7786 return the item.
7787 With {end}: Remove items from {idx} to {end} (inclusive) and
7788 return a |List| with these items. When {idx} points to the same
7789 item as {end} a list with one item is returned. When {end}
7790 points to an item before {idx} this is an error.
7791 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007792 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007793 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007794 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007795 :call remove(mylist, 0, 9)
7796<
7797 Use |delete()| to remove a file.
7798
7799 Can also be used as a |method|: >
7800 mylist->remove(idx)
7801
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007802remove({blob}, {idx})
7803remove({blob}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007804 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
7805 return the byte.
7806 With {end}: Remove bytes from {idx} to {end} (inclusive) and
7807 return a |Blob| with these bytes. When {idx} points to the same
7808 byte as {end} a |Blob| with one byte is returned. When {end}
7809 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007810 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007811 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007812 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007813 :call remove(mylist, 0, 9)
7814
7815remove({dict}, {key})
7816 Remove the entry from {dict} with key {key} and return it.
7817 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007818 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007819< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007820 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007821
7822rename({from}, {to}) *rename()*
7823 Rename the file by the name {from} to the name {to}. This
7824 should also work to move files across file systems. The
7825 result is a Number, which is 0 if the file was renamed
7826 successfully, and non-zero when the renaming failed.
7827 NOTE: If {to} exists it is overwritten without warning.
7828 This function is not available in the |sandbox|.
7829
7830 Can also be used as a |method|: >
7831 GetOldName()->rename(newname)
7832
7833repeat({expr}, {count}) *repeat()*
7834 Repeat {expr} {count} times and return the concatenated
7835 result. Example: >
7836 :let separator = repeat('-', 80)
7837< When {count} is zero or negative the result is empty.
Bakudankun375141e2022-09-09 18:46:47 +01007838 When {expr} is a |List| or a |Blob| the result is {expr}
7839 concatenated {count} times. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007840 :let longlist = repeat(['a', 'b'], 3)
7841< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
7842
7843 Can also be used as a |method|: >
7844 mylist->repeat(count)
7845
7846resolve({filename}) *resolve()* *E655*
7847 On MS-Windows, when {filename} is a shortcut (a .lnk file),
7848 returns the path the shortcut points to in a simplified form.
7849 When {filename} is a symbolic link or junction point, return
7850 the full path to the target. If the target of junction is
7851 removed, return {filename}.
7852 On Unix, repeat resolving symbolic links in all path
7853 components of {filename} and return the simplified result.
7854 To cope with link cycles, resolving of symbolic links is
7855 stopped after 100 iterations.
7856 On other systems, return the simplified {filename}.
7857 The simplification step is done as by |simplify()|.
7858 resolve() keeps a leading path component specifying the
7859 current directory (provided the result is still a relative
7860 path name) and also keeps a trailing path separator.
7861
7862 Can also be used as a |method|: >
7863 GetName()->resolve()
7864
7865reverse({object}) *reverse()*
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +01007866 Reverse the order of items in {object}. {object} can be a
7867 |List|, a |Blob| or a |String|. For a List and a Blob the
7868 items are reversed in-place and {object} is returned.
7869 For a String a new String is returned.
7870 Returns zero if {object} is not a List, Blob or a String.
7871 If you want a List or Blob to remain unmodified make a copy
7872 first: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007873 :let revlist = reverse(copy(mylist))
7874< Can also be used as a |method|: >
7875 mylist->reverse()
7876
7877round({expr}) *round()*
7878 Round off {expr} to the nearest integral value and return it
7879 as a |Float|. If {expr} lies halfway between two integral
7880 values, then use the larger one (away from zero).
7881 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007882 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007883 Examples: >
7884 echo round(0.456)
7885< 0.0 >
7886 echo round(4.5)
7887< 5.0 >
7888 echo round(-4.5)
7889< -5.0
7890
7891 Can also be used as a |method|: >
7892 Compute()->round()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007893
7894rubyeval({expr}) *rubyeval()*
7895 Evaluate Ruby expression {expr} and return its result
7896 converted to Vim data structures.
7897 Numbers, floats and strings are returned as they are (strings
7898 are copied though).
7899 Arrays are represented as Vim |List| type.
7900 Hashes are represented as Vim |Dictionary| type.
7901 Other objects are represented as strings resulted from their
7902 "Object#to_s" method.
7903 Note that in a `:def` function local variables are not visible
7904 to {expr}.
7905
7906 Can also be used as a |method|: >
7907 GetRubyExpr()->rubyeval()
7908
7909< {only available when compiled with the |+ruby| feature}
7910
7911screenattr({row}, {col}) *screenattr()*
7912 Like |screenchar()|, but return the attribute. This is a rather
7913 arbitrary number that can only be used to compare to the
7914 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007915 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007916
7917 Can also be used as a |method|: >
7918 GetRow()->screenattr(col)
7919
7920screenchar({row}, {col}) *screenchar()*
7921 The result is a Number, which is the character at position
7922 [row, col] on the screen. This works for every possible
7923 screen position, also status lines, window separators and the
7924 command line. The top left position is row one, column one
7925 The character excludes composing characters. For double-byte
7926 encodings it may only be the first byte.
7927 This is mainly to be used for testing.
7928 Returns -1 when row or col is out of range.
7929
7930 Can also be used as a |method|: >
7931 GetRow()->screenchar(col)
7932
7933screenchars({row}, {col}) *screenchars()*
7934 The result is a |List| of Numbers. The first number is the same
7935 as what |screenchar()| returns. Further numbers are
7936 composing characters on top of the base character.
7937 This is mainly to be used for testing.
7938 Returns an empty List when row or col is out of range.
7939
7940 Can also be used as a |method|: >
7941 GetRow()->screenchars(col)
7942
7943screencol() *screencol()*
7944 The result is a Number, which is the current screen column of
7945 the cursor. The leftmost column has number 1.
7946 This function is mainly used for testing.
7947
7948 Note: Always returns the current screen column, thus if used
7949 in a command (e.g. ":echo screencol()") it will return the
7950 column inside the command line, which is 1 when the command is
7951 executed. To get the cursor position in the file use one of
7952 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007953 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007954 nnoremap <silent> GG :echom screencol()<CR>
7955 nnoremap GG <Cmd>echom screencol()<CR>
7956<
7957screenpos({winid}, {lnum}, {col}) *screenpos()*
7958 The result is a Dict with the screen position of the text
7959 character in window {winid} at buffer line {lnum} and column
7960 {col}. {col} is a one-based byte index.
7961 The Dict has these members:
7962 row screen row
7963 col first screen column
7964 endcol last screen column
7965 curscol cursor screen column
7966 If the specified position is not visible, all values are zero.
7967 The "endcol" value differs from "col" when the character
7968 occupies more than one screen cell. E.g. for a Tab "col" can
7969 be 1 and "endcol" can be 8.
7970 The "curscol" value is where the cursor would be placed. For
7971 a Tab it would be the same as "endcol", while for a double
7972 width character it would be the same as "col".
7973 The |conceal| feature is ignored here, the column numbers are
7974 as if 'conceallevel' is zero. You can set the cursor to the
7975 right position and use |screencol()| to get the value with
7976 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007977 If the position is in a closed fold the screen position of the
7978 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007979 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007980
7981 Can also be used as a |method|: >
7982 GetWinid()->screenpos(lnum, col)
7983
7984screenrow() *screenrow()*
7985 The result is a Number, which is the current screen row of the
7986 cursor. The top line has number one.
7987 This function is mainly used for testing.
7988 Alternatively you can use |winline()|.
7989
7990 Note: Same restrictions as with |screencol()|.
7991
7992screenstring({row}, {col}) *screenstring()*
7993 The result is a String that contains the base character and
7994 any composing characters at position [row, col] on the screen.
7995 This is like |screenchars()| but returning a String with the
7996 characters.
7997 This is mainly to be used for testing.
7998 Returns an empty String when row or col is out of range.
7999
8000 Can also be used as a |method|: >
8001 GetRow()->screenstring(col)
8002<
8003 *search()*
8004search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
8005 Search for regexp pattern {pattern}. The search starts at the
8006 cursor position (you can use |cursor()| to set it).
8007
8008 When a match has been found its line number is returned.
8009 If there is no match a 0 is returned and the cursor doesn't
8010 move. No error message is given.
Christian Brabandt9a660d22024-03-12 22:03:09 +01008011 To get the matched string, use |matchbufline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008012
8013 {flags} is a String, which can contain these character flags:
8014 'b' search Backward instead of forward
8015 'c' accept a match at the Cursor position
8016 'e' move to the End of the match
8017 'n' do Not move the cursor
8018 'p' return number of matching sub-Pattern (see below)
8019 's' Set the ' mark at the previous location of the cursor
8020 'w' Wrap around the end of the file
8021 'W' don't Wrap around the end of the file
8022 'z' start searching at the cursor column instead of zero
8023 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
8024
8025 If the 's' flag is supplied, the ' mark is set, only if the
8026 cursor is moved. The 's' flag cannot be combined with the 'n'
8027 flag.
8028
8029 'ignorecase', 'smartcase' and 'magic' are used.
8030
8031 When the 'z' flag is not given, forward searching always
8032 starts in column zero and then matches before the cursor are
8033 skipped. When the 'c' flag is present in 'cpo' the next
8034 search starts after the match. Without the 'c' flag the next
Bram Moolenaarfd999452022-08-24 18:30:14 +01008035 search starts one column after the start of the match. This
8036 matters for overlapping matches. See |cpo-c|. You can also
8037 insert "\ze" to change where the match ends, see |/\ze|.
8038
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008039 When searching backwards and the 'z' flag is given then the
8040 search starts in column zero, thus no match in the current
8041 line will be found (unless wrapping around the end of the
8042 file).
8043
8044 When the {stopline} argument is given then the search stops
8045 after searching this line. This is useful to restrict the
8046 search to a range of lines. Examples: >
8047 let match = search('(', 'b', line("w0"))
8048 let end = search('END', '', line("w$"))
8049< When {stopline} is used and it is not zero this also implies
8050 that the search does not wrap around the end of the file.
8051 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01008052 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008053 When the {timeout} argument is given the search stops when
8054 more than this many milliseconds have passed. Thus when
8055 {timeout} is 500 the search stops after half a second.
8056 The value must not be negative. A zero value is like not
8057 giving the argument.
8058 {only available when compiled with the |+reltime| feature}
8059
8060 If the {skip} expression is given it is evaluated with the
8061 cursor positioned on the start of a match. If it evaluates to
8062 non-zero this match is skipped. This can be used, for
8063 example, to skip a match in a comment or a string.
8064 {skip} can be a string, which is evaluated as an expression, a
8065 function reference or a lambda.
8066 When {skip} is omitted or empty, every match is accepted.
8067 When evaluating {skip} causes an error the search is aborted
8068 and -1 returned.
8069 *search()-sub-match*
8070 With the 'p' flag the returned value is one more than the
8071 first sub-match in \(\). One if none of them matched but the
8072 whole pattern did match.
8073 To get the column number too use |searchpos()|.
8074
8075 The cursor will be positioned at the match, unless the 'n'
8076 flag is used.
8077
8078 Example (goes over all files in the argument list): >
8079 :let n = 1
8080 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008081 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008082 : " start at the last char in the file and wrap for the
8083 : " first search to find match at start of file
8084 : normal G$
8085 : let flags = "w"
8086 : while search("foo", flags) > 0
8087 : s/foo/bar/g
8088 : let flags = "W"
8089 : endwhile
8090 : update " write the file if modified
8091 : let n = n + 1
8092 :endwhile
8093<
8094 Example for using some flags: >
8095 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
8096< This will search for the keywords "if", "else", and "endif"
8097 under or after the cursor. Because of the 'p' flag, it
8098 returns 1, 2, or 3 depending on which keyword is found, or 0
8099 if the search fails. With the cursor on the first word of the
8100 line:
8101 if (foo == 0) | let foo = foo + 1 | endif ~
8102 the function returns 1. Without the 'c' flag, the function
8103 finds the "endif" and returns 3. The same thing happens
8104 without the 'e' flag if the cursor is on the "f" of "if".
8105 The 'n' flag tells the function not to move the cursor.
8106
8107 Can also be used as a |method|: >
8108 GetPattern()->search()
8109
8110searchcount([{options}]) *searchcount()*
8111 Get or update the last search count, like what is displayed
8112 without the "S" flag in 'shortmess'. This works even if
8113 'shortmess' does contain the "S" flag.
8114
8115 This returns a |Dictionary|. The dictionary is empty if the
8116 previous pattern was not set and "pattern" was not specified.
8117
8118 key type meaning ~
8119 current |Number| current position of match;
8120 0 if the cursor position is
8121 before the first match
8122 exact_match |Boolean| 1 if "current" is matched on
8123 "pos", otherwise 0
8124 total |Number| total count of matches found
8125 incomplete |Number| 0: search was fully completed
8126 1: recomputing was timed out
8127 2: max count exceeded
8128
8129 For {options} see further down.
8130
8131 To get the last search count when |n| or |N| was pressed, call
8132 this function with `recompute: 0` . This sometimes returns
8133 wrong information because |n| and |N|'s maximum count is 99.
8134 If it exceeded 99 the result must be max count + 1 (100). If
8135 you want to get correct information, specify `recompute: 1`: >
8136
8137 " result == maxcount + 1 (100) when many matches
8138 let result = searchcount(#{recompute: 0})
8139
8140 " Below returns correct result (recompute defaults
8141 " to 1)
8142 let result = searchcount()
8143<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01008144 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008145 function! LastSearchCount() abort
8146 let result = searchcount(#{recompute: 0})
8147 if empty(result)
8148 return ''
8149 endif
8150 if result.incomplete ==# 1 " timed out
8151 return printf(' /%s [?/??]', @/)
8152 elseif result.incomplete ==# 2 " max count exceeded
8153 if result.total > result.maxcount &&
8154 \ result.current > result.maxcount
8155 return printf(' /%s [>%d/>%d]', @/,
8156 \ result.current, result.total)
8157 elseif result.total > result.maxcount
8158 return printf(' /%s [%d/>%d]', @/,
8159 \ result.current, result.total)
8160 endif
8161 endif
8162 return printf(' /%s [%d/%d]', @/,
8163 \ result.current, result.total)
8164 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008165 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008166
8167 " Or if you want to show the count only when
8168 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008169 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008170 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
8171<
8172 You can also update the search count, which can be useful in a
8173 |CursorMoved| or |CursorMovedI| autocommand: >
8174
8175 autocmd CursorMoved,CursorMovedI *
8176 \ let s:searchcount_timer = timer_start(
8177 \ 200, function('s:update_searchcount'))
8178 function! s:update_searchcount(timer) abort
8179 if a:timer ==# s:searchcount_timer
8180 call searchcount(#{
8181 \ recompute: 1, maxcount: 0, timeout: 100})
8182 redrawstatus
8183 endif
8184 endfunction
8185<
8186 This can also be used to count matched texts with specified
8187 pattern in the current buffer using "pattern": >
8188
8189 " Count '\<foo\>' in this buffer
8190 " (Note that it also updates search count)
8191 let result = searchcount(#{pattern: '\<foo\>'})
8192
8193 " To restore old search count by old pattern,
8194 " search again
8195 call searchcount()
8196<
8197 {options} must be a |Dictionary|. It can contain:
8198 key type meaning ~
8199 recompute |Boolean| if |TRUE|, recompute the count
8200 like |n| or |N| was executed.
8201 otherwise returns the last
8202 computed result (when |n| or
8203 |N| was used when "S" is not
8204 in 'shortmess', or this
8205 function was called).
8206 (default: |TRUE|)
8207 pattern |String| recompute if this was given
8208 and different with |@/|.
8209 this works as same as the
8210 below command is executed
8211 before calling this function >
8212 let @/ = pattern
8213< (default: |@/|)
8214 timeout |Number| 0 or negative number is no
8215 timeout. timeout milliseconds
8216 for recomputing the result
8217 (default: 0)
8218 maxcount |Number| 0 or negative number is no
8219 limit. max count of matched
8220 text while recomputing the
8221 result. if search exceeded
8222 total count, "total" value
8223 becomes `maxcount + 1`
8224 (default: 99)
8225 pos |List| `[lnum, col, off]` value
8226 when recomputing the result.
8227 this changes "current" result
8228 value. see |cursor()|,
8229 |getpos()|
8230 (default: cursor's position)
8231
8232 Can also be used as a |method|: >
8233 GetSearchOpts()->searchcount()
8234<
8235searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
8236 Search for the declaration of {name}.
8237
8238 With a non-zero {global} argument it works like |gD|, find
8239 first match in the file. Otherwise it works like |gd|, find
8240 first match in the function.
8241
8242 With a non-zero {thisblock} argument matches in a {} block
8243 that ends before the cursor position are ignored. Avoids
8244 finding variable declarations only valid in another scope.
8245
8246 Moves the cursor to the found match.
8247 Returns zero for success, non-zero for failure.
8248 Example: >
8249 if searchdecl('myvar') == 0
8250 echo getline('.')
8251 endif
8252<
8253 Can also be used as a |method|: >
8254 GetName()->searchdecl()
8255<
8256 *searchpair()*
8257searchpair({start}, {middle}, {end} [, {flags} [, {skip}
8258 [, {stopline} [, {timeout}]]]])
8259 Search for the match of a nested start-end pair. This can be
8260 used to find the "endif" that matches an "if", while other
8261 if/endif pairs in between are ignored.
8262 The search starts at the cursor. The default is to search
8263 forward, include 'b' in {flags} to search backward.
8264 If a match is found, the cursor is positioned at it and the
8265 line number is returned. If no match is found 0 or -1 is
8266 returned and the cursor doesn't move. No error message is
8267 given.
8268
8269 {start}, {middle} and {end} are patterns, see |pattern|. They
8270 must not contain \( \) pairs. Use of \%( \) is allowed. When
8271 {middle} is not empty, it is found when searching from either
8272 direction, but only when not in a nested start-end pair. A
8273 typical use is: >
8274 searchpair('\<if\>', '\<else\>', '\<endif\>')
8275< By leaving {middle} empty the "else" is skipped.
8276
8277 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
8278 |search()|. Additionally:
8279 'r' Repeat until no more matches found; will find the
8280 outer pair. Implies the 'W' flag.
8281 'm' Return number of matches instead of line number with
8282 the match; will be > 1 when 'r' is used.
8283 Note: it's nearly always a good idea to use the 'W' flag, to
8284 avoid wrapping around the end of the file.
8285
8286 When a match for {start}, {middle} or {end} is found, the
8287 {skip} expression is evaluated with the cursor positioned on
8288 the start of the match. It should return non-zero if this
8289 match is to be skipped. E.g., because it is inside a comment
8290 or a string.
8291 When {skip} is omitted or empty, every match is accepted.
8292 When evaluating {skip} causes an error the search is aborted
8293 and -1 returned.
8294 {skip} can be a string, a lambda, a funcref or a partial.
8295 Anything else makes the function fail.
8296 In a `:def` function when the {skip} argument is a string
8297 constant it is compiled into instructions.
8298
8299 For {stopline} and {timeout} see |search()|.
8300
8301 The value of 'ignorecase' is used. 'magic' is ignored, the
8302 patterns are used like it's on.
8303
8304 The search starts exactly at the cursor. A match with
8305 {start}, {middle} or {end} at the next character, in the
8306 direction of searching, is the first one found. Example: >
8307 if 1
8308 if 2
8309 endif 2
8310 endif 1
8311< When starting at the "if 2", with the cursor on the "i", and
8312 searching forwards, the "endif 2" is found. When starting on
8313 the character just before the "if 2", the "endif 1" will be
8314 found. That's because the "if 2" will be found first, and
8315 then this is considered to be a nested if/endif from "if 2" to
8316 "endif 2".
8317 When searching backwards and {end} is more than one character,
8318 it may be useful to put "\zs" at the end of the pattern, so
8319 that when the cursor is inside a match with the end it finds
8320 the matching start.
8321
8322 Example, to find the "endif" command in a Vim script: >
8323
8324 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
8325 \ 'getline(".") =~ "^\\s*\""')
8326
8327< The cursor must be at or after the "if" for which a match is
8328 to be found. Note that single-quote strings are used to avoid
8329 having to double the backslashes. The skip expression only
8330 catches comments at the start of a line, not after a command.
8331 Also, a word "en" or "if" halfway a line is considered a
8332 match.
8333 Another example, to search for the matching "{" of a "}": >
8334
8335 :echo searchpair('{', '', '}', 'bW')
8336
8337< This works when the cursor is at or before the "}" for which a
8338 match is to be found. To reject matches that syntax
8339 highlighting recognized as strings: >
8340
8341 :echo searchpair('{', '', '}', 'bW',
8342 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
8343<
8344 *searchpairpos()*
8345searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
8346 [, {stopline} [, {timeout}]]]])
8347 Same as |searchpair()|, but returns a |List| with the line and
8348 column position of the match. The first element of the |List|
8349 is the line number and the second element is the byte index of
8350 the column position of the match. If no match is found,
8351 returns [0, 0]. >
8352
8353 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
8354<
8355 See |match-parens| for a bigger and more useful example.
8356
8357 *searchpos()*
8358searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
8359 Same as |search()|, but returns a |List| with the line and
8360 column position of the match. The first element of the |List|
8361 is the line number and the second element is the byte index of
8362 the column position of the match. If no match is found,
8363 returns [0, 0].
8364 Example: >
8365 :let [lnum, col] = searchpos('mypattern', 'n')
8366
8367< When the 'p' flag is given then there is an extra item with
8368 the sub-pattern match number |search()-sub-match|. Example: >
8369 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
8370< In this example "submatch" is 2 when a lowercase letter is
8371 found |/\l|, 3 when an uppercase letter is found |/\u|.
8372
8373 Can also be used as a |method|: >
8374 GetPattern()->searchpos()
8375
8376server2client({clientid}, {string}) *server2client()*
8377 Send a reply string to {clientid}. The most recent {clientid}
8378 that sent a string can be retrieved with expand("<client>").
8379 {only available when compiled with the |+clientserver| feature}
8380 Returns zero for success, -1 for failure.
8381 Note:
8382 This id has to be stored before the next command can be
8383 received. I.e. before returning from the received command and
8384 before calling any commands that waits for input.
8385 See also |clientserver|.
8386 Example: >
8387 :echo server2client(expand("<client>"), "HELLO")
8388
8389< Can also be used as a |method|: >
8390 GetClientId()->server2client(string)
8391<
8392serverlist() *serverlist()*
8393 Return a list of available server names, one per line.
8394 When there are no servers or the information is not available
8395 an empty string is returned. See also |clientserver|.
8396 {only available when compiled with the |+clientserver| feature}
8397 Example: >
8398 :echo serverlist()
8399<
8400setbufline({buf}, {lnum}, {text}) *setbufline()*
8401 Set line {lnum} to {text} in buffer {buf}. This works like
8402 |setline()| for the specified buffer.
8403
8404 This function works only for loaded buffers. First call
8405 |bufload()| if needed.
8406
8407 To insert lines use |appendbufline()|.
8408 Any text properties in {lnum} are cleared.
8409
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00008410 {text} can be a string to set one line, or a List of strings
8411 to set multiple lines. If the List extends below the last
8412 line then those lines are added. If the List is empty then
8413 nothing is changed and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008414
8415 For the use of {buf}, see |bufname()| above.
8416
8417 {lnum} is used like with |setline()|.
8418 Use "$" to refer to the last line in buffer {buf}.
8419 When {lnum} is just below the last line the {text} will be
8420 added below the last line.
8421
8422 When {buf} is not a valid buffer, the buffer is not loaded or
8423 {lnum} is not valid then 1 is returned. In |Vim9| script an
8424 error is given.
8425 On success 0 is returned.
8426
8427 Can also be used as a |method|, the base is passed as the
8428 third argument: >
8429 GetText()->setbufline(buf, lnum)
8430
8431setbufvar({buf}, {varname}, {val}) *setbufvar()*
8432 Set option or local variable {varname} in buffer {buf} to
8433 {val}.
8434 This also works for a global or local window option, but it
8435 doesn't work for a global or local window variable.
8436 For a local window option the global value is unchanged.
8437 For the use of {buf}, see |bufname()| above.
8438 The {varname} argument is a string.
8439 Note that the variable name without "b:" must be used.
8440 Examples: >
8441 :call setbufvar(1, "&mod", 1)
8442 :call setbufvar("todo", "myvar", "foobar")
8443< This function is not available in the |sandbox|.
8444
8445 Can also be used as a |method|, the base is passed as the
8446 third argument: >
8447 GetValue()->setbufvar(buf, varname)
8448
8449
8450setcellwidths({list}) *setcellwidths()*
8451 Specify overrides for cell widths of character ranges. This
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008452 tells Vim how wide characters are when displayed in the
8453 terminal, counted in screen cells. The values override
8454 'ambiwidth'. Example: >
8455 call setcellwidths([
Bram Moolenaar938ae282023-02-20 20:44:55 +00008456 \ [0x111, 0x111, 1],
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008457 \ [0x2194, 0x2199, 2],
8458 \ ])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008459
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008460< The {list} argument is a List of Lists with each three
8461 numbers: [{low}, {high}, {width}]. *E1109* *E1110*
8462 {low} and {high} can be the same, in which case this refers to
8463 one character. Otherwise it is the range of characters from
8464 {low} to {high} (inclusive). *E1111* *E1114*
K.Takata71933232023-01-20 16:00:55 +00008465 Only characters with value 0x80 and higher can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008466
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008467 {width} must be either 1 or 2, indicating the character width
8468 in screen cells. *E1112*
8469 An error is given if the argument is invalid, also when a
Bram Moolenaar938ae282023-02-20 20:44:55 +00008470 range overlaps with another. *E1113*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008471
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008472 If the new value causes 'fillchars' or 'listchars' to become
8473 invalid it is rejected and an error is given.
8474
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008475 To clear the overrides pass an empty {list}: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008476 setcellwidths([]);
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008477
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008478< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008479 the effect for known emoji characters. Move the cursor
8480 through the text to check if the cell widths of your terminal
8481 match with what Vim knows about each emoji. If it doesn't
8482 look right you need to adjust the {list} argument.
8483
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008484
8485setcharpos({expr}, {list}) *setcharpos()*
8486 Same as |setpos()| but uses the specified column number as the
8487 character index instead of the byte index in the line.
8488
8489 Example:
8490 With the text "여보세요" in line 8: >
8491 call setcharpos('.', [0, 8, 4, 0])
8492< positions the cursor on the fourth character '요'. >
8493 call setpos('.', [0, 8, 4, 0])
8494< positions the cursor on the second character '보'.
8495
8496 Can also be used as a |method|: >
8497 GetPosition()->setcharpos('.')
8498
8499setcharsearch({dict}) *setcharsearch()*
8500 Set the current character search information to {dict},
8501 which contains one or more of the following entries:
8502
8503 char character which will be used for a subsequent
8504 |,| or |;| command; an empty string clears the
8505 character search
8506 forward direction of character search; 1 for forward,
8507 0 for backward
8508 until type of character search; 1 for a |t| or |T|
8509 character search, 0 for an |f| or |F|
8510 character search
8511
8512 This can be useful to save/restore a user's character search
8513 from a script: >
8514 :let prevsearch = getcharsearch()
8515 :" Perform a command which clobbers user's search
8516 :call setcharsearch(prevsearch)
8517< Also see |getcharsearch()|.
8518
8519 Can also be used as a |method|: >
8520 SavedSearch()->setcharsearch()
8521
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01008522setcmdline({str} [, {pos}]) *setcmdline()*
8523 Set the command line to {str} and set the cursor position to
8524 {pos}.
8525 If {pos} is omitted, the cursor is positioned after the text.
8526 Returns 0 when successful, 1 when not editing the command
8527 line.
8528
8529 Can also be used as a |method|: >
8530 GetText()->setcmdline()
8531
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008532setcmdpos({pos}) *setcmdpos()*
8533 Set the cursor position in the command line to byte position
8534 {pos}. The first position is 1.
8535 Use |getcmdpos()| to obtain the current position.
8536 Only works while editing the command line, thus you must use
8537 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
8538 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
8539 set after the command line is set to the expression. For
8540 |c_CTRL-R_=| it is set after evaluating the expression but
8541 before inserting the resulting text.
8542 When the number is too big the cursor is put at the end of the
8543 line. A number smaller than one has undefined results.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01008544 Returns 0 when successful, 1 when not editing the command
8545 line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008546
8547 Can also be used as a |method|: >
8548 GetPos()->setcmdpos()
8549
8550setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
8551setcursorcharpos({list})
8552 Same as |cursor()| but uses the specified column number as the
8553 character index instead of the byte index in the line.
8554
8555 Example:
8556 With the text "여보세요" in line 4: >
8557 call setcursorcharpos(4, 3)
8558< positions the cursor on the third character '세'. >
8559 call cursor(4, 3)
8560< positions the cursor on the first character '여'.
8561
8562 Can also be used as a |method|: >
8563 GetCursorPos()->setcursorcharpos()
8564
8565
8566setenv({name}, {val}) *setenv()*
8567 Set environment variable {name} to {val}. Example: >
8568 call setenv('HOME', '/home/myhome')
8569
8570< When {val} is |v:null| the environment variable is deleted.
8571 See also |expr-env|.
8572
8573 Can also be used as a |method|, the base is passed as the
8574 second argument: >
8575 GetPath()->setenv('PATH')
8576
8577setfperm({fname}, {mode}) *setfperm()* *chmod*
8578 Set the file permissions for {fname} to {mode}.
8579 {mode} must be a string with 9 characters. It is of the form
8580 "rwxrwxrwx", where each group of "rwx" flags represent, in
8581 turn, the permissions of the owner of the file, the group the
8582 file belongs to, and other users. A '-' character means the
8583 permission is off, any other character means on. Multi-byte
8584 characters are not supported.
8585
8586 For example "rw-r-----" means read-write for the user,
8587 readable by the group, not accessible by others. "xx-x-----"
8588 would do the same thing.
8589
8590 Returns non-zero for success, zero for failure.
8591
8592 Can also be used as a |method|: >
8593 GetFilename()->setfperm(mode)
8594<
8595 To read permissions see |getfperm()|.
8596
8597
8598setline({lnum}, {text}) *setline()*
8599 Set line {lnum} of the current buffer to {text}. To insert
8600 lines use |append()|. To set lines in another buffer use
8601 |setbufline()|. Any text properties in {lnum} are cleared.
8602
8603 {lnum} is used like with |getline()|.
8604 When {lnum} is just below the last line the {text} will be
8605 added below the last line.
8606 {text} can be any type or a List of any type, each item is
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00008607 converted to a String. When {text} is an empty List then
8608 nothing is changed and FALSE is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008609
8610 If this succeeds, FALSE is returned. If this fails (most likely
8611 because {lnum} is invalid) TRUE is returned.
8612 In |Vim9| script an error is given if {lnum} is invalid.
8613
8614 Example: >
8615 :call setline(5, strftime("%c"))
8616
8617< When {text} is a |List| then line {lnum} and following lines
8618 will be set to the items in the list. Example: >
8619 :call setline(5, ['aaa', 'bbb', 'ccc'])
8620< This is equivalent to: >
8621 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
8622 : call setline(n, l)
8623 :endfor
8624
8625< Note: The '[ and '] marks are not set.
8626
8627 Can also be used as a |method|, the base is passed as the
8628 second argument: >
8629 GetText()->setline(lnum)
8630
8631setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
8632 Create or replace or add to the location list for window {nr}.
8633 {nr} can be the window number or the |window-ID|.
8634 When {nr} is zero the current window is used.
8635
8636 For a location list window, the displayed location list is
8637 modified. For an invalid window number {nr}, -1 is returned.
8638 Otherwise, same as |setqflist()|.
8639 Also see |location-list|.
8640
8641 For {action} see |setqflist-action|.
8642
8643 If the optional {what} dictionary argument is supplied, then
8644 only the items listed in {what} are set. Refer to |setqflist()|
8645 for the list of supported keys in {what}.
8646
8647 Can also be used as a |method|, the base is passed as the
8648 second argument: >
8649 GetLoclist()->setloclist(winnr)
8650
8651setmatches({list} [, {win}]) *setmatches()*
8652 Restores a list of matches saved by |getmatches()| for the
8653 current window. Returns 0 if successful, otherwise -1. All
8654 current matches are cleared before the list is restored. See
8655 example for |getmatches()|.
8656 If {win} is specified, use the window with this number or
8657 window ID instead of the current window.
8658
8659 Can also be used as a |method|: >
8660 GetMatches()->setmatches()
8661<
8662 *setpos()*
8663setpos({expr}, {list})
8664 Set the position for String {expr}. Possible values:
8665 . the cursor
8666 'x mark x
8667
8668 {list} must be a |List| with four or five numbers:
8669 [bufnum, lnum, col, off]
8670 [bufnum, lnum, col, off, curswant]
8671
8672 "bufnum" is the buffer number. Zero can be used for the
8673 current buffer. When setting an uppercase mark "bufnum" is
8674 used for the mark position. For other marks it specifies the
8675 buffer to set the mark in. You can use the |bufnr()| function
8676 to turn a file name into a buffer number.
8677 For setting the cursor and the ' mark "bufnum" is ignored,
8678 since these are associated with a window, not a buffer.
8679 Does not change the jumplist.
8680
8681 "lnum" and "col" are the position in the buffer. The first
8682 column is 1. Use a zero "lnum" to delete a mark. If "col" is
8683 smaller than 1 then 1 is used. To use the character count
8684 instead of the byte count, use |setcharpos()|.
8685
8686 The "off" number is only used when 'virtualedit' is set. Then
8687 it is the offset in screen columns from the start of the
8688 character. E.g., a position within a <Tab> or after the last
8689 character.
8690
8691 The "curswant" number is only used when setting the cursor
8692 position. It sets the preferred column for when moving the
8693 cursor vertically. When the "curswant" number is missing the
8694 preferred column is not set. When it is present and setting a
8695 mark position it is not used.
8696
8697 Note that for '< and '> changing the line number may result in
8698 the marks to be effectively be swapped, so that '< is always
8699 before '>.
8700
8701 Returns 0 when the position could be set, -1 otherwise.
8702 An error message is given if {expr} is invalid.
8703
8704 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
8705
8706 This does not restore the preferred column for moving
8707 vertically; if you set the cursor position with this, |j| and
8708 |k| motions will jump to previous columns! Use |cursor()| to
8709 also set the preferred column. Also see the "curswant" key in
8710 |winrestview()|.
8711
8712 Can also be used as a |method|: >
8713 GetPosition()->setpos('.')
8714
8715setqflist({list} [, {action} [, {what}]]) *setqflist()*
8716 Create or replace or add to the quickfix list.
8717
8718 If the optional {what} dictionary argument is supplied, then
8719 only the items listed in {what} are set. The first {list}
8720 argument is ignored. See below for the supported items in
8721 {what}.
8722 *setqflist-what*
8723 When {what} is not present, the items in {list} are used. Each
8724 item must be a dictionary. Non-dictionary items in {list} are
8725 ignored. Each dictionary item can contain the following
8726 entries:
8727
8728 bufnr buffer number; must be the number of a valid
8729 buffer
8730 filename name of a file; only used when "bufnr" is not
8731 present or it is invalid.
8732 module name of a module; if given it will be used in
8733 quickfix error window instead of the filename.
8734 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +00008735 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008736 pattern search pattern used to locate the error
8737 col column number
8738 vcol when non-zero: "col" is visual column
8739 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +00008740 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008741 nr error number
8742 text description of the error
8743 type single-character error type, 'E', 'W', etc.
8744 valid recognized error message
Tom Praschanca6ac992023-08-11 23:26:12 +02008745 user_data custom data associated with the item, can be
8746 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008747
8748 The "col", "vcol", "nr", "type" and "text" entries are
8749 optional. Either "lnum" or "pattern" entry can be used to
8750 locate a matching error line.
8751 If the "filename" and "bufnr" entries are not present or
8752 neither the "lnum" or "pattern" entries are present, then the
8753 item will not be handled as an error line.
8754 If both "pattern" and "lnum" are present then "pattern" will
8755 be used.
8756 If the "valid" entry is not supplied, then the valid flag is
8757 set when "bufnr" is a valid buffer or "filename" exists.
8758 If you supply an empty {list}, the quickfix list will be
8759 cleared.
8760 Note that the list is not exactly the same as what
8761 |getqflist()| returns.
8762
8763 {action} values: *setqflist-action* *E927*
8764 'a' The items from {list} are added to the existing
8765 quickfix list. If there is no existing list, then a
8766 new list is created.
8767
8768 'r' The items from the current quickfix list are replaced
8769 with the items from {list}. This can also be used to
8770 clear the list: >
8771 :call setqflist([], 'r')
8772<
8773 'f' All the quickfix lists in the quickfix stack are
8774 freed.
8775
8776 If {action} is not present or is set to ' ', then a new list
8777 is created. The new quickfix list is added after the current
8778 quickfix list in the stack and all the following lists are
8779 freed. To add a new quickfix list at the end of the stack,
8780 set "nr" in {what} to "$".
8781
8782 The following items can be specified in dictionary {what}:
8783 context quickfix list context. See |quickfix-context|
8784 efm errorformat to use when parsing text from
8785 "lines". If this is not present, then the
8786 'errorformat' option value is used.
8787 See |quickfix-parse|
8788 id quickfix list identifier |quickfix-ID|
8789 idx index of the current entry in the quickfix
8790 list specified by 'id' or 'nr'. If set to '$',
8791 then the last entry in the list is set as the
8792 current entry. See |quickfix-index|
8793 items list of quickfix entries. Same as the {list}
8794 argument.
8795 lines use 'errorformat' to parse a list of lines and
8796 add the resulting entries to the quickfix list
8797 {nr} or {id}. Only a |List| value is supported.
8798 See |quickfix-parse|
8799 nr list number in the quickfix stack; zero
8800 means the current quickfix list and "$" means
8801 the last quickfix list.
8802 quickfixtextfunc
8803 function to get the text to display in the
8804 quickfix window. The value can be the name of
8805 a function or a funcref or a lambda. Refer to
8806 |quickfix-window-function| for an explanation
8807 of how to write the function and an example.
8808 title quickfix list title text. See |quickfix-title|
8809 Unsupported keys in {what} are ignored.
8810 If the "nr" item is not present, then the current quickfix list
8811 is modified. When creating a new quickfix list, "nr" can be
8812 set to a value one greater than the quickfix stack size.
8813 When modifying a quickfix list, to guarantee that the correct
8814 list is modified, "id" should be used instead of "nr" to
8815 specify the list.
8816
8817 Examples (See also |setqflist-examples|): >
8818 :call setqflist([], 'r', {'title': 'My search'})
8819 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
8820 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
8821<
8822 Returns zero for success, -1 for failure.
8823
8824 This function can be used to create a quickfix list
8825 independent of the 'errorformat' setting. Use a command like
8826 `:cc 1` to jump to the first position.
8827
8828 Can also be used as a |method|, the base is passed as the
8829 second argument: >
8830 GetErrorlist()->setqflist()
8831<
8832 *setreg()*
8833setreg({regname}, {value} [, {options}])
8834 Set the register {regname} to {value}.
8835 If {regname} is "" or "@", the unnamed register '"' is used.
8836 The {regname} argument is a string. In |Vim9-script|
8837 {regname} must be one character.
8838
8839 {value} may be any value returned by |getreg()| or
8840 |getreginfo()|, including a |List| or |Dict|.
8841 If {options} contains "a" or {regname} is upper case,
8842 then the value is appended.
8843
8844 {options} can also contain a register type specification:
8845 "c" or "v" |characterwise| mode
8846 "l" or "V" |linewise| mode
8847 "b" or "<CTRL-V>" |blockwise-visual| mode
8848 If a number immediately follows "b" or "<CTRL-V>" then this is
8849 used as the width of the selection - if it is not specified
8850 then the width of the block is set to the number of characters
8851 in the longest line (counting a <Tab> as 1 character).
8852
8853 If {options} contains no register settings, then the default
8854 is to use character mode unless {value} ends in a <NL> for
8855 string {value} and linewise mode for list {value}. Blockwise
8856 mode is never selected automatically.
8857 Returns zero for success, non-zero for failure.
8858
8859 *E883*
8860 Note: you may not use |List| containing more than one item to
8861 set search and expression registers. Lists containing no
8862 items act like empty strings.
8863
8864 Examples: >
8865 :call setreg(v:register, @*)
8866 :call setreg('*', @%, 'ac')
8867 :call setreg('a', "1\n2\n3", 'b5')
8868 :call setreg('"', { 'points_to': 'a'})
8869
8870< This example shows using the functions to save and restore a
8871 register: >
8872 :let var_a = getreginfo()
8873 :call setreg('a', var_a)
8874< or: >
8875 :let var_a = getreg('a', 1, 1)
8876 :let var_amode = getregtype('a')
8877 ....
8878 :call setreg('a', var_a, var_amode)
8879< Note: you may not reliably restore register value
8880 without using the third argument to |getreg()| as without it
8881 newlines are represented as newlines AND Nul bytes are
8882 represented as newlines as well, see |NL-used-for-Nul|.
8883
8884 You can also change the type of a register by appending
8885 nothing: >
8886 :call setreg('a', '', 'al')
8887
8888< Can also be used as a |method|, the base is passed as the
8889 second argument: >
8890 GetText()->setreg('a')
8891
8892settabvar({tabnr}, {varname}, {val}) *settabvar()*
8893 Set tab-local variable {varname} to {val} in tab page {tabnr}.
8894 |t:var|
8895 The {varname} argument is a string.
8896 Note that autocommands are blocked, side effects may not be
8897 triggered, e.g. when setting 'filetype'.
8898 Note that the variable name without "t:" must be used.
8899 Tabs are numbered starting with one.
8900 This function is not available in the |sandbox|.
8901
8902 Can also be used as a |method|, the base is passed as the
8903 third argument: >
8904 GetValue()->settabvar(tab, name)
8905
8906settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
8907 Set option or local variable {varname} in window {winnr} to
8908 {val}.
8909 Tabs are numbered starting with one. For the current tabpage
8910 use |setwinvar()|.
8911 {winnr} can be the window number or the |window-ID|.
8912 When {winnr} is zero the current window is used.
8913 Note that autocommands are blocked, side effects may not be
8914 triggered, e.g. when setting 'filetype' or 'syntax'.
8915 This also works for a global or local buffer option, but it
8916 doesn't work for a global or local buffer variable.
8917 For a local buffer option the global value is unchanged.
8918 Note that the variable name without "w:" must be used.
8919 Examples: >
8920 :call settabwinvar(1, 1, "&list", 0)
8921 :call settabwinvar(3, 2, "myvar", "foobar")
8922< This function is not available in the |sandbox|.
8923
8924 Can also be used as a |method|, the base is passed as the
8925 fourth argument: >
8926 GetValue()->settabwinvar(tab, winnr, name)
8927
8928settagstack({nr}, {dict} [, {action}]) *settagstack()*
8929 Modify the tag stack of the window {nr} using {dict}.
8930 {nr} can be the window number or the |window-ID|.
8931
8932 For a list of supported items in {dict}, refer to
8933 |gettagstack()|. "curidx" takes effect before changing the tag
8934 stack.
8935 *E962*
8936 How the tag stack is modified depends on the {action}
8937 argument:
8938 - If {action} is not present or is set to 'r', then the tag
8939 stack is replaced.
8940 - If {action} is set to 'a', then new entries from {dict} are
8941 pushed (added) onto the tag stack.
8942 - If {action} is set to 't', then all the entries from the
8943 current entry in the tag stack or "curidx" in {dict} are
8944 removed and then new entries are pushed to the stack.
8945
8946 The current index is set to one after the length of the tag
8947 stack after the modification.
8948
8949 Returns zero for success, -1 for failure.
8950
8951 Examples (for more examples see |tagstack-examples|):
8952 Empty the tag stack of window 3: >
8953 call settagstack(3, {'items' : []})
8954
8955< Save and restore the tag stack: >
8956 let stack = gettagstack(1003)
8957 " do something else
8958 call settagstack(1003, stack)
8959 unlet stack
8960<
8961 Can also be used as a |method|, the base is passed as the
8962 second argument: >
8963 GetStack()->settagstack(winnr)
8964
8965setwinvar({winnr}, {varname}, {val}) *setwinvar()*
8966 Like |settabwinvar()| for the current tab page.
8967 Examples: >
8968 :call setwinvar(1, "&list", 0)
8969 :call setwinvar(2, "myvar", "foobar")
8970
8971< Can also be used as a |method|, the base is passed as the
8972 third argument: >
8973 GetValue()->setwinvar(winnr, name)
8974
8975sha256({string}) *sha256()*
8976 Returns a String with 64 hex characters, which is the SHA256
8977 checksum of {string}.
8978
8979 Can also be used as a |method|: >
8980 GetText()->sha256()
8981
8982< {only available when compiled with the |+cryptv| feature}
8983
8984shellescape({string} [, {special}]) *shellescape()*
8985 Escape {string} for use as a shell command argument.
8986 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +00008987 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008988 in single quotes and will double up all internal single
8989 quotes.
8990 On MS-Windows, when 'shellslash' is not set, it will enclose
8991 {string} in double quotes and double all double quotes within
8992 {string}.
8993 Otherwise it will enclose {string} in single quotes and
8994 replace all "'" with "'\''".
8995
Enno5faeb602024-05-15 21:54:19 +02008996 The {special} argument adds additional escaping of keywords
8997 used in Vim commands. When it is not omitted and a non-zero
K.Takatac0e038b2024-05-16 12:39:01 +09008998 number or a non-empty String (|non-zero-arg|), then special
8999 items such as "!", "%", "#" and "<cword>" (as listed in
9000 |expand()|) will be preceded by a backslash.
Enno5faeb602024-05-15 21:54:19 +02009001 This backslash will be removed again by the |:!| command.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009002
9003 The "!" character will be escaped (again with a |non-zero-arg|
9004 {special}) when 'shell' contains "csh" in the tail. That is
9005 because for csh and tcsh "!" is used for history replacement
9006 even when inside single quotes.
9007
9008 With a |non-zero-arg| {special} the <NL> character is also
9009 escaped. When 'shell' containing "csh" in the tail it's
9010 escaped a second time.
9011
9012 The "\" character will be escaped when 'shell' contains "fish"
9013 in the tail. That is because for fish "\" is used as an escape
9014 character inside single quotes.
9015
9016 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009017 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009018< This results in a directory listing for the file under the
9019 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009020 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009021< See also |::S|.
9022
9023 Can also be used as a |method|: >
9024 GetCommand()->shellescape()
9025
9026shiftwidth([{col}]) *shiftwidth()*
9027 Returns the effective value of 'shiftwidth'. This is the
9028 'shiftwidth' value unless it is zero, in which case it is the
9029 'tabstop' value. This function was introduced with patch
9030 7.3.694 in 2012, everybody should have it by now (however it
9031 did not allow for the optional {col} argument until 8.1.542).
9032
9033 When there is one argument {col} this is used as column number
9034 for which to return the 'shiftwidth' value. This matters for the
9035 'vartabstop' feature. If the 'vartabstop' setting is enabled and
9036 no {col} argument is given, column 1 will be assumed.
9037
9038 Can also be used as a |method|: >
9039 GetColumn()->shiftwidth()
9040
9041sign_ functions are documented here: |sign-functions-details|
9042
9043
9044simplify({filename}) *simplify()*
9045 Simplify the file name as much as possible without changing
9046 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
9047 Unix) are not resolved. If the first path component in
9048 {filename} designates the current directory, this will be
9049 valid for the result as well. A trailing path separator is
9050 not removed either. On Unix "//path" is unchanged, but
9051 "///path" is simplified to "/path" (this follows the Posix
9052 standard).
9053 Example: >
9054 simplify("./dir/.././/file/") == "./file/"
9055< Note: The combination "dir/.." is only removed if "dir" is
9056 a searchable directory or does not exist. On Unix, it is also
9057 removed when "dir" is a symbolic link within the same
9058 directory. In order to resolve all the involved symbolic
9059 links before simplifying the path name, use |resolve()|.
9060
9061 Can also be used as a |method|: >
9062 GetName()->simplify()
9063
9064sin({expr}) *sin()*
9065 Return the sine of {expr}, measured in radians, as a |Float|.
9066 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009067 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009068 Examples: >
9069 :echo sin(100)
9070< -0.506366 >
9071 :echo sin(-4.01)
9072< 0.763301
9073
9074 Can also be used as a |method|: >
9075 Compute()->sin()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009076
9077
9078sinh({expr}) *sinh()*
9079 Return the hyperbolic sine of {expr} as a |Float| in the range
9080 [-inf, inf].
9081 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009082 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009083 Examples: >
9084 :echo sinh(0.5)
9085< 0.521095 >
9086 :echo sinh(-0.9)
9087< -1.026517
9088
9089 Can also be used as a |method|: >
9090 Compute()->sinh()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009091
9092
9093slice({expr}, {start} [, {end}]) *slice()*
9094 Similar to using a |slice| "expr[start : end]", but "end" is
9095 used exclusive. And for a string the indexes are used as
9096 character indexes instead of byte indexes, like in
zeertzjqad387692024-03-23 08:23:48 +01009097 |vim9script|. Also, composing characters are treated as a
9098 part of the preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009099 When {end} is omitted the slice continues to the last item.
9100 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009101 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009102
9103 Can also be used as a |method|: >
9104 GetList()->slice(offset)
9105
9106
Bram Moolenaar2007dd42022-02-23 13:17:47 +00009107sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009108 Sort the items in {list} in-place. Returns {list}.
9109
9110 If you want a list to remain unmodified make a copy first: >
9111 :let sortedlist = sort(copy(mylist))
9112
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01009113< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009114 string representation of each item to sort on. Numbers sort
9115 after Strings, |Lists| after Numbers. For sorting text in the
9116 current buffer use |:sort|.
9117
Bram Moolenaar2007dd42022-02-23 13:17:47 +00009118 When {how} is given and it is 'i' then case is ignored.
9119 In legacy script, for backwards compatibility, the value one
9120 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009121
Bram Moolenaar2007dd42022-02-23 13:17:47 +00009122 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009123 locale is used for ordering. Implementation details: strcoll()
9124 is used to compare strings. See |:language| check or set the
9125 collation locale. |v:collate| can also be used to check the
9126 current locale. Sorting using the locale typically ignores
9127 case. Example: >
9128 " ö is sorted similarly to o with English locale.
9129 :language collate en_US.UTF8
9130 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
9131< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
9132>
9133 " ö is sorted after z with Swedish locale.
9134 :language collate sv_SE.UTF8
9135 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
9136< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
9137 This does not work properly on Mac.
9138
Bram Moolenaar2007dd42022-02-23 13:17:47 +00009139 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009140 sorted numerical (Implementation detail: this uses the
Bram Moolenaarbe19d782023-03-09 22:06:49 +00009141 strtod() function to parse numbers. Strings, Lists, Dicts and
9142 Funcrefs will be considered as being 0). Note that this won't
9143 sort a list of strings with numbers!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009144
Bram Moolenaar2007dd42022-02-23 13:17:47 +00009145 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009146 sorted numerical. This is like 'n' but a string containing
9147 digits will be used as the number they represent.
9148
Bram Moolenaar2007dd42022-02-23 13:17:47 +00009149 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009150 sorted numerical. All values must be a Number or a Float.
9151
Bram Moolenaar2007dd42022-02-23 13:17:47 +00009152 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009153 is called to compare items. The function is invoked with two
9154 items as argument and must return zero if they are equal, 1 or
9155 bigger if the first one sorts after the second one, -1 or
9156 smaller if the first one sorts before the second one.
9157
9158 {dict} is for functions with the "dict" attribute. It will be
9159 used to set the local variable "self". |Dictionary-function|
9160
9161 The sort is stable, items which compare equal (as number or as
9162 string) will keep their relative position. E.g., when sorting
9163 on numbers, text strings will sort next to each other, in the
9164 same order as they were originally.
9165
9166 Can also be used as a |method|: >
9167 mylist->sort()
9168
9169< Also see |uniq()|.
9170
9171 Example: >
9172 func MyCompare(i1, i2)
9173 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
9174 endfunc
9175 eval mylist->sort("MyCompare")
9176< A shorter compare version for this specific simple case, which
9177 ignores overflow: >
9178 func MyCompare(i1, i2)
9179 return a:i1 - a:i2
9180 endfunc
9181< For a simple expression you can use a lambda: >
9182 eval mylist->sort({i1, i2 -> i1 - i2})
9183<
9184sound_clear() *sound_clear()*
9185 Stop playing all sounds.
9186
9187 On some Linux systems you may need the libcanberra-pulse
9188 package, otherwise sound may not stop.
9189
9190 {only available when compiled with the |+sound| feature}
9191
9192 *sound_playevent()*
9193sound_playevent({name} [, {callback}])
9194 Play a sound identified by {name}. Which event names are
9195 supported depends on the system. Often the XDG sound names
9196 are used. On Ubuntu they may be found in
9197 /usr/share/sounds/freedesktop/stereo. Example: >
9198 call sound_playevent('bell')
9199< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
9200 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
9201 SystemStart, SystemWelcome, etc.
Yee Cheng Chin4314e4f2022-10-08 13:50:05 +01009202 On macOS, {name} refers to files located in
9203 /System/Library/Sounds (e.g. "Tink"). It will also work for
9204 custom installed sounds in folders like ~/Library/Sounds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009205
9206 When {callback} is specified it is invoked when the sound is
9207 finished. The first argument is the sound ID, the second
9208 argument is the status:
9209 0 sound was played to the end
9210 1 sound was interrupted
9211 2 error occurred after sound started
9212 Example: >
9213 func Callback(id, status)
9214 echomsg "sound " .. a:id .. " finished with " .. a:status
9215 endfunc
9216 call sound_playevent('bell', 'Callback')
9217
9218< MS-Windows: {callback} doesn't work for this function.
9219
9220 Returns the sound ID, which can be passed to `sound_stop()`.
9221 Returns zero if the sound could not be played.
9222
9223 Can also be used as a |method|: >
9224 GetSoundName()->sound_playevent()
9225
9226< {only available when compiled with the |+sound| feature}
9227
9228 *sound_playfile()*
9229sound_playfile({path} [, {callback}])
9230 Like `sound_playevent()` but play sound file {path}. {path}
9231 must be a full path. On Ubuntu you may find files to play
9232 with this command: >
9233 :!find /usr/share/sounds -type f | grep -v index.theme
9234
9235< Can also be used as a |method|: >
9236 GetSoundPath()->sound_playfile()
9237
Bram Moolenaar1588bc82022-03-08 21:35:07 +00009238< {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009239
9240
9241sound_stop({id}) *sound_stop()*
9242 Stop playing sound {id}. {id} must be previously returned by
9243 `sound_playevent()` or `sound_playfile()`.
9244
9245 On some Linux systems you may need the libcanberra-pulse
9246 package, otherwise sound may not stop.
9247
9248 On MS-Windows, this does not work for event sound started by
9249 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
9250
9251 Can also be used as a |method|: >
9252 soundid->sound_stop()
9253
9254< {only available when compiled with the |+sound| feature}
9255
9256 *soundfold()*
9257soundfold({word})
9258 Return the sound-folded equivalent of {word}. Uses the first
9259 language in 'spelllang' for the current window that supports
9260 soundfolding. 'spell' must be set. When no sound folding is
9261 possible the {word} is returned unmodified.
9262 This can be used for making spelling suggestions. Note that
9263 the method can be quite slow.
9264
9265 Can also be used as a |method|: >
9266 GetWord()->soundfold()
9267<
9268 *spellbadword()*
9269spellbadword([{sentence}])
9270 Without argument: The result is the badly spelled word under
9271 or after the cursor. The cursor is moved to the start of the
9272 bad word. When no bad word is found in the cursor line the
9273 result is an empty string and the cursor doesn't move.
9274
9275 With argument: The result is the first word in {sentence} that
9276 is badly spelled. If there are no spelling mistakes the
9277 result is an empty string.
9278
9279 The return value is a list with two items:
9280 - The badly spelled word or an empty string.
9281 - The type of the spelling error:
9282 "bad" spelling mistake
9283 "rare" rare word
9284 "local" word only valid in another region
9285 "caps" word should start with Capital
9286 Example: >
9287 echo spellbadword("the quik brown fox")
9288< ['quik', 'bad'] ~
9289
9290 The spelling information for the current window and the value
9291 of 'spelllang' are used.
9292
9293 Can also be used as a |method|: >
9294 GetText()->spellbadword()
9295<
9296 *spellsuggest()*
9297spellsuggest({word} [, {max} [, {capital}]])
9298 Return a |List| with spelling suggestions to replace {word}.
9299 When {max} is given up to this number of suggestions are
9300 returned. Otherwise up to 25 suggestions are returned.
9301
9302 When the {capital} argument is given and it's non-zero only
9303 suggestions with a leading capital will be given. Use this
9304 after a match with 'spellcapcheck'.
9305
9306 {word} can be a badly spelled word followed by other text.
9307 This allows for joining two words that were split. The
9308 suggestions also include the following text, thus you can
9309 replace a line.
9310
9311 {word} may also be a good word. Similar words will then be
9312 returned. {word} itself is not included in the suggestions,
9313 although it may appear capitalized.
9314
9315 The spelling information for the current window is used. The
9316 values of 'spelllang' and 'spellsuggest' are used.
9317
9318 Can also be used as a |method|: >
9319 GetWord()->spellsuggest()
9320
9321split({string} [, {pattern} [, {keepempty}]]) *split()*
9322 Make a |List| out of {string}. When {pattern} is omitted or
9323 empty each white-separated sequence of characters becomes an
9324 item.
9325 Otherwise the string is split where {pattern} matches,
9326 removing the matched characters. 'ignorecase' is not used
9327 here, add \c to ignore case. |/\c|
9328 When the first or last item is empty it is omitted, unless the
9329 {keepempty} argument is given and it's non-zero.
9330 Other empty items are kept when {pattern} matches at least one
9331 character or when {keepempty} is non-zero.
9332 Example: >
9333 :let words = split(getline('.'), '\W\+')
9334< To split a string in individual characters: >
9335 :for c in split(mystring, '\zs')
9336< If you want to keep the separator you can also use '\zs' at
9337 the end of the pattern: >
9338 :echo split('abc:def:ghi', ':\zs')
9339< ['abc:', 'def:', 'ghi'] ~
9340 Splitting a table where the first element can be empty: >
9341 :let items = split(line, ':', 1)
9342< The opposite function is |join()|.
9343
9344 Can also be used as a |method|: >
9345 GetString()->split()
9346
9347sqrt({expr}) *sqrt()*
9348 Return the non-negative square root of Float {expr} as a
9349 |Float|.
9350 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009351 is negative the result is NaN (Not a Number). Returns 0.0 if
9352 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009353 Examples: >
9354 :echo sqrt(100)
9355< 10.0 >
9356 :echo sqrt(-4.01)
9357< nan
9358 "nan" may be different, it depends on system libraries.
9359
9360 Can also be used as a |method|: >
9361 Compute()->sqrt()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009362
9363
9364srand([{expr}]) *srand()*
9365 Initialize seed used by |rand()|:
9366 - If {expr} is not given, seed values are initialized by
9367 reading from /dev/urandom, if possible, or using time(NULL)
9368 a.k.a. epoch time otherwise; this only has second accuracy.
9369 - If {expr} is given it must be a Number. It is used to
9370 initialize the seed values. This is useful for testing or
9371 when a predictable sequence is intended.
9372
9373 Examples: >
9374 :let seed = srand()
9375 :let seed = srand(userinput)
9376 :echo rand(seed)
9377
9378state([{what}]) *state()*
9379 Return a string which contains characters indicating the
9380 current state. Mostly useful in callbacks that want to do
9381 work that may not always be safe. Roughly this works like:
9382 - callback uses state() to check if work is safe to do.
9383 Yes: then do it right away.
9384 No: add to work queue and add a |SafeState| and/or
9385 |SafeStateAgain| autocommand (|SafeState| triggers at
9386 toplevel, |SafeStateAgain| triggers after handling
9387 messages and callbacks).
9388 - When SafeState or SafeStateAgain is triggered and executes
9389 your autocommand, check with `state()` if the work can be
9390 done now, and if yes remove it from the queue and execute.
9391 Remove the autocommand if the queue is now empty.
9392 Also see |mode()|.
9393
9394 When {what} is given only characters in this string will be
9395 added. E.g, this checks if the screen has scrolled: >
9396 if state('s') == ''
9397 " screen has not scrolled
9398<
9399 These characters indicate the state, generally indicating that
9400 something is busy:
9401 m halfway a mapping, :normal command, feedkeys() or
9402 stuffed command
9403 o operator pending, e.g. after |d|
9404 a Insert mode autocomplete active
9405 x executing an autocommand
9406 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
9407 ch_readraw() when reading json
9408 S not triggering SafeState or SafeStateAgain, e.g. after
9409 |f| or a count
9410 c callback invoked, including timer (repeats for
9411 recursiveness up to "ccc")
9412 s screen has scrolled for messages
9413
9414str2float({string} [, {quoted}]) *str2float()*
9415 Convert String {string} to a Float. This mostly works the
9416 same as when using a floating point number in an expression,
9417 see |floating-point-format|. But it's a bit more permissive.
9418 E.g., "1e40" is accepted, while in an expression you need to
9419 write "1.0e40". The hexadecimal form "0x123" is also
9420 accepted, but not others, like binary or octal.
9421 When {quoted} is present and non-zero then embedded single
9422 quotes before the dot are ignored, thus "1'000.0" is a
9423 thousand.
9424 Text after the number is silently ignored.
9425 The decimal point is always '.', no matter what the locale is
9426 set to. A comma ends the number: "12,345.67" is converted to
9427 12.0. You can strip out thousands separators with
9428 |substitute()|: >
9429 let f = str2float(substitute(text, ',', '', 'g'))
9430<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009431 Returns 0.0 if the conversion fails.
9432
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009433 Can also be used as a |method|: >
9434 let f = text->substitute(',', '', 'g')->str2float()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009435
9436str2list({string} [, {utf8}]) *str2list()*
9437 Return a list containing the number values which represent
9438 each character in String {string}. Examples: >
9439 str2list(" ") returns [32]
9440 str2list("ABC") returns [65, 66, 67]
9441< |list2str()| does the opposite.
9442
9443 When {utf8} is omitted or zero, the current 'encoding' is used.
9444 When {utf8} is TRUE, always treat the String as UTF-8
9445 characters. With UTF-8 composing characters are handled
9446 properly: >
9447 str2list("á") returns [97, 769]
9448
9449< Can also be used as a |method|: >
9450 GetString()->str2list()
9451
9452
9453str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
9454 Convert string {string} to a number.
9455 {base} is the conversion base, it can be 2, 8, 10 or 16.
9456 When {quoted} is present and non-zero then embedded single
9457 quotes are ignored, thus "1'000'000" is a million.
9458
9459 When {base} is omitted base 10 is used. This also means that
9460 a leading zero doesn't cause octal conversion to be used, as
9461 with the default String to Number conversion. Example: >
9462 let nr = str2nr('0123')
9463<
9464 When {base} is 16 a leading "0x" or "0X" is ignored. With a
9465 different base the result will be zero. Similarly, when
9466 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
9467 {base} is 2 a leading "0b" or "0B" is ignored.
9468 Text after the number is silently ignored.
9469
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009470 Returns 0 if {string} is empty or on error.
9471
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009472 Can also be used as a |method|: >
9473 GetText()->str2nr()
9474
9475
9476strcharlen({string}) *strcharlen()*
9477 The result is a Number, which is the number of characters
9478 in String {string}. Composing characters are ignored.
9479 |strchars()| can count the number of characters, counting
9480 composing characters separately.
9481
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009482 Returns 0 if {string} is empty or on error.
9483
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009484 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
9485
9486 Can also be used as a |method|: >
9487 GetText()->strcharlen()
9488
9489
9490strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
9491 Like |strpart()| but using character index and length instead
9492 of byte index and length.
9493 When {skipcc} is omitted or zero, composing characters are
9494 counted separately.
zeertzjqad387692024-03-23 08:23:48 +01009495 When {skipcc} set to 1, composing characters are treated as a
9496 part of the preceding base character, similar to |slice()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009497 When a character index is used where a character does not
9498 exist it is omitted and counted as one character. For
9499 example: >
9500 strcharpart('abc', -1, 2)
9501< results in 'a'.
9502
Bram Moolenaard592deb2022-06-17 15:42:40 +01009503 Returns an empty string on error.
9504
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009505 Can also be used as a |method|: >
9506 GetText()->strcharpart(5)
9507
9508
9509strchars({string} [, {skipcc}]) *strchars()*
9510 The result is a Number, which is the number of characters
9511 in String {string}.
9512 When {skipcc} is omitted or zero, composing characters are
9513 counted separately.
zeertzjqad387692024-03-23 08:23:48 +01009514 When {skipcc} set to 1, composing characters are ignored.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009515 |strcharlen()| always does this.
9516
Bram Moolenaard592deb2022-06-17 15:42:40 +01009517 Returns zero on error.
9518
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009519 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
9520
9521 {skipcc} is only available after 7.4.755. For backward
9522 compatibility, you can define a wrapper function: >
9523 if has("patch-7.4.755")
9524 function s:strchars(str, skipcc)
9525 return strchars(a:str, a:skipcc)
9526 endfunction
9527 else
9528 function s:strchars(str, skipcc)
9529 if a:skipcc
9530 return strlen(substitute(a:str, ".", "x", "g"))
9531 else
9532 return strchars(a:str)
9533 endif
9534 endfunction
9535 endif
9536<
9537 Can also be used as a |method|: >
9538 GetText()->strchars()
9539
9540strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
9541 The result is a Number, which is the number of display cells
9542 String {string} occupies on the screen when it starts at {col}
9543 (first column is zero). When {col} is omitted zero is used.
9544 Otherwise it is the screen column where to start. This
9545 matters for Tab characters.
9546 The option settings of the current window are used. This
9547 matters for anything that's displayed differently, such as
9548 'tabstop' and 'display'.
9549 When {string} contains characters with East Asian Width Class
9550 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009551 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009552 Also see |strlen()|, |strwidth()| and |strchars()|.
9553
9554 Can also be used as a |method|: >
9555 GetText()->strdisplaywidth()
9556
9557strftime({format} [, {time}]) *strftime()*
9558 The result is a String, which is a formatted date and time, as
9559 specified by the {format} string. The given {time} is used,
9560 or the current time if no time is given. The accepted
9561 {format} depends on your system, thus this is not portable!
9562 See the manual page of the C function strftime() for the
9563 format. The maximum length of the result is 80 characters.
9564 See also |localtime()|, |getftime()| and |strptime()|.
9565 The language can be changed with the |:language| command.
9566 Examples: >
9567 :echo strftime("%c") Sun Apr 27 11:49:23 1997
9568 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
9569 :echo strftime("%y%m%d %T") 970427 11:53:55
9570 :echo strftime("%H:%M") 11:55
9571 :echo strftime("%c", getftime("file.c"))
9572 Show mod time of file.c.
9573< Not available on all systems. To check use: >
9574 :if exists("*strftime")
9575
9576< Can also be used as a |method|: >
9577 GetFormat()->strftime()
9578
9579strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01009580 Get a Number corresponding to the character at {index} in
9581 {str}. This uses a zero-based character index, not a byte
9582 index. Composing characters are considered separate
9583 characters here. Use |nr2char()| to convert the Number to a
9584 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009585 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009586 Also see |strcharpart()| and |strchars()|.
9587
9588 Can also be used as a |method|: >
9589 GetText()->strgetchar(5)
9590
9591stridx({haystack}, {needle} [, {start}]) *stridx()*
9592 The result is a Number, which gives the byte index in
9593 {haystack} of the first occurrence of the String {needle}.
9594 If {start} is specified, the search starts at index {start}.
9595 This can be used to find a second match: >
9596 :let colon1 = stridx(line, ":")
9597 :let colon2 = stridx(line, ":", colon1 + 1)
9598< The search is done case-sensitive.
9599 For pattern searches use |match()|.
9600 -1 is returned if the {needle} does not occur in {haystack}.
9601 See also |strridx()|.
9602 Examples: >
9603 :echo stridx("An Example", "Example") 3
9604 :echo stridx("Starting point", "Start") 0
9605 :echo stridx("Starting point", "start") -1
9606< *strstr()* *strchr()*
9607 stridx() works similar to the C function strstr(). When used
9608 with a single character it works similar to strchr().
9609
9610 Can also be used as a |method|: >
9611 GetHaystack()->stridx(needle)
9612<
9613 *string()*
9614string({expr}) Return {expr} converted to a String. If {expr} is a Number,
9615 Float, String, Blob or a composition of them, then the result
9616 can be parsed back with |eval()|.
9617 {expr} type result ~
9618 String 'string' (single quotes are doubled)
9619 Number 123
9620 Float 123.123456 or 1.123456e8
9621 Funcref function('name')
9622 Blob 0z00112233.44556677.8899
9623 List [item, item]
9624 Dictionary {key: value, key: value}
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00009625 Class class SomeName
9626 Object object of SomeName {lnum: 1, col: 3}
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +01009627 Enum enum EnumName
Yegappan Lakshmanan3cf121e2024-03-31 18:45:35 +02009628 EnumValue enum name.value {name: str, ordinal: nr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009629
9630 When a |List| or |Dictionary| has a recursive reference it is
9631 replaced by "[...]" or "{...}". Using eval() on the result
9632 will then fail.
9633
mityu7f0bba22024-03-29 10:14:41 +01009634 For an object, invokes the string() method to get a textual
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +01009635 representation of the object. If the method is not present,
mityu7f0bba22024-03-29 10:14:41 +01009636 then the default representation is used. |object-string()|
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +01009637
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009638 Can also be used as a |method|: >
9639 mylist->string()
9640
9641< Also see |strtrans()|.
9642
9643
9644strlen({string}) *strlen()*
9645 The result is a Number, which is the length of the String
9646 {string} in bytes.
9647 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009648 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009649 If you want to count the number of multibyte characters use
9650 |strchars()|.
9651 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
9652
9653 Can also be used as a |method|: >
9654 GetString()->strlen()
9655
9656strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
9657 The result is a String, which is part of {src}, starting from
9658 byte {start}, with the byte length {len}.
9659 When {chars} is present and TRUE then {len} is the number of
9660 characters positions (composing characters are not counted
9661 separately, thus "1" means one base character and any
9662 following composing characters).
9663 To count {start} as characters instead of bytes use
9664 |strcharpart()|.
9665
9666 When bytes are selected which do not exist, this doesn't
9667 result in an error, the bytes are simply omitted.
9668 If {len} is missing, the copy continues from {start} till the
9669 end of the {src}. >
9670 strpart("abcdefg", 3, 2) == "de"
9671 strpart("abcdefg", -2, 4) == "ab"
9672 strpart("abcdefg", 5, 4) == "fg"
9673 strpart("abcdefg", 3) == "defg"
9674
9675< Note: To get the first character, {start} must be 0. For
9676 example, to get the character under the cursor: >
9677 strpart(getline("."), col(".") - 1, 1, v:true)
9678<
Bram Moolenaard592deb2022-06-17 15:42:40 +01009679 Returns an empty string on error.
9680
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009681 Can also be used as a |method|: >
9682 GetText()->strpart(5)
9683
9684strptime({format}, {timestring}) *strptime()*
9685 The result is a Number, which is a unix timestamp representing
9686 the date and time in {timestring}, which is expected to match
9687 the format specified in {format}.
9688
9689 The accepted {format} depends on your system, thus this is not
9690 portable! See the manual page of the C function strptime()
9691 for the format. Especially avoid "%c". The value of $TZ also
9692 matters.
9693
9694 If the {timestring} cannot be parsed with {format} zero is
9695 returned. If you do not know the format of {timestring} you
9696 can try different {format} values until you get a non-zero
9697 result.
9698
9699 See also |strftime()|.
9700 Examples: >
9701 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
9702< 862156163 >
9703 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
9704< Sun Apr 27 11:53:55 1997 >
9705 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
9706< Sun Apr 27 12:53:55 1997
9707
9708 Can also be used as a |method|: >
9709 GetFormat()->strptime(timestring)
9710<
9711 Not available on all systems. To check use: >
9712 :if exists("*strptime")
9713
9714strridx({haystack}, {needle} [, {start}]) *strridx()*
9715 The result is a Number, which gives the byte index in
9716 {haystack} of the last occurrence of the String {needle}.
9717 When {start} is specified, matches beyond this index are
9718 ignored. This can be used to find a match before a previous
9719 match: >
9720 :let lastcomma = strridx(line, ",")
9721 :let comma2 = strridx(line, ",", lastcomma - 1)
9722< The search is done case-sensitive.
9723 For pattern searches use |match()|.
9724 -1 is returned if the {needle} does not occur in {haystack}.
9725 If the {needle} is empty the length of {haystack} is returned.
9726 See also |stridx()|. Examples: >
9727 :echo strridx("an angry armadillo", "an") 3
9728< *strrchr()*
9729 When used with a single character it works similar to the C
9730 function strrchr().
9731
9732 Can also be used as a |method|: >
9733 GetHaystack()->strridx(needle)
9734
9735strtrans({string}) *strtrans()*
9736 The result is a String, which is {string} with all unprintable
9737 characters translated into printable characters |'isprint'|.
9738 Like they are shown in a window. Example: >
9739 echo strtrans(@a)
9740< This displays a newline in register a as "^@" instead of
9741 starting a new line.
9742
Bram Moolenaard592deb2022-06-17 15:42:40 +01009743 Returns an empty string on error.
9744
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009745 Can also be used as a |method|: >
9746 GetString()->strtrans()
9747
Christian Brabandt67672ef2023-04-24 21:09:54 +01009748strutf16len({string} [, {countcc}]) *strutf16len()*
9749 The result is a Number, which is the number of UTF-16 code
9750 units in String {string} (after converting it to UTF-16).
9751
9752 When {countcc} is TRUE, composing characters are counted
9753 separately.
9754 When {countcc} is omitted or FALSE, composing characters are
9755 ignored.
9756
9757 Returns zero on error.
9758
9759 Also see |strlen()| and |strcharlen()|.
9760 Examples: >
9761 echo strutf16len('a') returns 1
9762 echo strutf16len('©') returns 1
9763 echo strutf16len('😊') returns 2
9764 echo strutf16len('ą́') returns 1
9765 echo strutf16len('ą́', v:true) returns 3
a5ob7r790f9a82023-09-25 06:05:47 +09009766<
Christian Brabandt67672ef2023-04-24 21:09:54 +01009767 Can also be used as a |method|: >
9768 GetText()->strutf16len()
9769<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009770strwidth({string}) *strwidth()*
9771 The result is a Number, which is the number of display cells
9772 String {string} occupies. A Tab character is counted as one
9773 cell, alternatively use |strdisplaywidth()|.
9774 When {string} contains characters with East Asian Width Class
9775 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009776 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009777 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
9778
9779 Can also be used as a |method|: >
9780 GetString()->strwidth()
9781
9782submatch({nr} [, {list}]) *submatch()* *E935*
9783 Only for an expression in a |:substitute| command or
9784 substitute() function.
9785 Returns the {nr}'th submatch of the matched text. When {nr}
9786 is 0 the whole matched text is returned.
9787 Note that a NL in the string can stand for a line break of a
9788 multi-line match or a NUL character in the text.
9789 Also see |sub-replace-expression|.
9790
9791 If {list} is present and non-zero then submatch() returns
9792 a list of strings, similar to |getline()| with two arguments.
9793 NL characters in the text represent NUL characters in the
9794 text.
9795 Only returns more than one item for |:substitute|, inside
9796 |substitute()| this list will always contain one or zero
9797 items, since there are no real line breaks.
9798
9799 When substitute() is used recursively only the submatches in
9800 the current (deepest) call can be obtained.
9801
Bram Moolenaard592deb2022-06-17 15:42:40 +01009802 Returns an empty string or list on error.
9803
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009804 Examples: >
9805 :s/\d\+/\=submatch(0) + 1/
9806 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
9807< This finds the first number in the line and adds one to it.
9808 A line break is included as a newline character.
9809
9810 Can also be used as a |method|: >
9811 GetNr()->submatch()
9812
9813substitute({string}, {pat}, {sub}, {flags}) *substitute()*
9814 The result is a String, which is a copy of {string}, in which
9815 the first match of {pat} is replaced with {sub}.
9816 When {flags} is "g", all matches of {pat} in {string} are
9817 replaced. Otherwise {flags} should be "".
9818
9819 This works like the ":substitute" command (without any flags).
9820 But the matching with {pat} is always done like the 'magic'
9821 option is set and 'cpoptions' is empty (to make scripts
9822 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
9823 if you want to ignore or match case and ignore 'ignorecase'.
9824 'smartcase' is not used. See |string-match| for how {pat} is
9825 used.
9826
9827 A "~" in {sub} is not replaced with the previous {sub}.
9828 Note that some codes in {sub} have a special meaning
9829 |sub-replace-special|. For example, to replace something with
9830 "\n" (two characters), use "\\\\n" or '\\n'.
9831
9832 When {pat} does not match in {string}, {string} is returned
9833 unmodified.
9834
9835 Example: >
9836 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
9837< This removes the last component of the 'path' option. >
9838 :echo substitute("testing", ".*", "\\U\\0", "")
9839< results in "TESTING".
9840
9841 When {sub} starts with "\=", the remainder is interpreted as
9842 an expression. See |sub-replace-expression|. Example: >
9843 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009844 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009845
9846< When {sub} is a Funcref that function is called, with one
9847 optional argument. Example: >
9848 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
9849< The optional argument is a list which contains the whole
9850 matched string and up to nine submatches, like what
9851 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009852 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009853
Bram Moolenaard592deb2022-06-17 15:42:40 +01009854< Returns an empty string on error.
9855
9856 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009857 GetString()->substitute(pat, sub, flags)
9858
Bram Moolenaarc216a7a2022-12-05 13:50:55 +00009859swapfilelist() *swapfilelist()*
9860 Returns a list of swap file names, like what "vim -r" shows.
9861 See the |-r| command argument. The 'directory' option is used
9862 for the directories to inspect. If you only want to get a
9863 list of swap files in the current directory then temporarily
9864 set 'directory' to a dot: >
9865 let save_dir = &directory
9866 let &directory = '.'
9867 let swapfiles = swapfilelist()
9868 let &directory = save_dir
9869
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009870swapinfo({fname}) *swapinfo()*
9871 The result is a dictionary, which holds information about the
9872 swapfile {fname}. The available fields are:
9873 version Vim version
9874 user user name
9875 host host name
9876 fname original file name
9877 pid PID of the Vim process that created the swap
9878 file
9879 mtime last modification time in seconds
9880 inode Optional: INODE number of the file
9881 dirty 1 if file was modified, 0 if not
9882 Note that "user" and "host" are truncated to at most 39 bytes.
9883 In case of failure an "error" item is added with the reason:
9884 Cannot open file: file not found or in accessible
9885 Cannot read file: cannot read first block
9886 Not a swap file: does not contain correct block ID
9887 Magic number mismatch: Info in first block is invalid
9888
9889 Can also be used as a |method|: >
9890 GetFilename()->swapinfo()
9891
9892swapname({buf}) *swapname()*
9893 The result is the swap file path of the buffer {expr}.
9894 For the use of {buf}, see |bufname()| above.
9895 If buffer {buf} is the current buffer, the result is equal to
9896 |:swapname| (unless there is no swap file).
9897 If buffer {buf} has no swap file, returns an empty string.
9898
9899 Can also be used as a |method|: >
9900 GetBufname()->swapname()
9901
9902synID({lnum}, {col}, {trans}) *synID()*
9903 The result is a Number, which is the syntax ID at the position
9904 {lnum} and {col} in the current window.
9905 The syntax ID can be used with |synIDattr()| and
9906 |synIDtrans()| to obtain syntax information about text.
9907
9908 {col} is 1 for the leftmost column, {lnum} is 1 for the first
9909 line. 'synmaxcol' applies, in a longer line zero is returned.
9910 Note that when the position is after the last character,
9911 that's where the cursor can be in Insert mode, synID() returns
9912 zero. {lnum} is used like with |getline()|.
9913
9914 When {trans} is |TRUE|, transparent items are reduced to the
9915 item that they reveal. This is useful when wanting to know
9916 the effective color. When {trans} is |FALSE|, the transparent
9917 item is returned. This is useful when wanting to know which
9918 syntax item is effective (e.g. inside parens).
9919 Warning: This function can be very slow. Best speed is
9920 obtained by going through the file in forward direction.
9921
Bram Moolenaard592deb2022-06-17 15:42:40 +01009922 Returns zero on error.
9923
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009924 Example (echoes the name of the syntax item under the cursor): >
9925 :echo synIDattr(synID(line("."), col("."), 1), "name")
9926<
9927
9928synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
9929 The result is a String, which is the {what} attribute of
9930 syntax ID {synID}. This can be used to obtain information
9931 about a syntax item.
9932 {mode} can be "gui", "cterm" or "term", to get the attributes
9933 for that mode. When {mode} is omitted, or an invalid value is
9934 used, the attributes for the currently active highlighting are
9935 used (GUI, cterm or term).
9936 Use synIDtrans() to follow linked highlight groups.
9937 {what} result
9938 "name" the name of the syntax item
9939 "fg" foreground color (GUI: color name used to set
9940 the color, cterm: color number as a string,
9941 term: empty string)
9942 "bg" background color (as with "fg")
9943 "font" font name (only available in the GUI)
9944 |highlight-font|
9945 "sp" special color for the GUI (as with "fg")
9946 |highlight-guisp|
9947 "ul" underline color for cterm: number as a string
9948 "fg#" like "fg", but for the GUI and the GUI is
9949 running the name in "#RRGGBB" form
9950 "bg#" like "fg#" for "bg"
9951 "sp#" like "fg#" for "sp"
9952 "bold" "1" if bold
9953 "italic" "1" if italic
9954 "reverse" "1" if reverse
9955 "inverse" "1" if inverse (= reverse)
9956 "standout" "1" if standout
9957 "underline" "1" if underlined
9958 "undercurl" "1" if undercurled
9959 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +01009960 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009961
Bram Moolenaard592deb2022-06-17 15:42:40 +01009962 Returns an empty string on error.
9963
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009964 Example (echoes the color of the syntax item under the
9965 cursor): >
9966 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
9967<
9968 Can also be used as a |method|: >
9969 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9970
9971
9972synIDtrans({synID}) *synIDtrans()*
9973 The result is a Number, which is the translated syntax ID of
9974 {synID}. This is the syntax group ID of what is being used to
9975 highlight the character. Highlight links given with
9976 ":highlight link" are followed.
9977
Bram Moolenaard592deb2022-06-17 15:42:40 +01009978 Returns zero on error.
9979
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009980 Can also be used as a |method|: >
9981 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9982
9983synconcealed({lnum}, {col}) *synconcealed()*
9984 The result is a |List| with currently three items:
9985 1. The first item in the list is 0 if the character at the
9986 position {lnum} and {col} is not part of a concealable
9987 region, 1 if it is. {lnum} is used like with |getline()|.
9988 2. The second item in the list is a string. If the first item
9989 is 1, the second item contains the text which will be
9990 displayed in place of the concealed text, depending on the
9991 current setting of 'conceallevel' and 'listchars'.
9992 3. The third and final item in the list is a number
9993 representing the specific syntax region matched in the
9994 line. When the character is not concealed the value is
9995 zero. This allows detection of the beginning of a new
9996 concealable region if there are two consecutive regions
9997 with the same replacement character. For an example, if
9998 the text is "123456" and both "23" and "45" are concealed
9999 and replaced by the character "X", then:
10000 call returns ~
10001 synconcealed(lnum, 1) [0, '', 0]
10002 synconcealed(lnum, 2) [1, 'X', 1]
10003 synconcealed(lnum, 3) [1, 'X', 1]
10004 synconcealed(lnum, 4) [1, 'X', 2]
10005 synconcealed(lnum, 5) [1, 'X', 2]
10006 synconcealed(lnum, 6) [0, '', 0]
10007
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020010008 Note: Doesn't consider |matchadd()| highlighting items,
10009 since syntax and matching highlighting are two different
10010 mechanisms |syntax-vs-match|.
10011
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010012
10013synstack({lnum}, {col}) *synstack()*
10014 Return a |List|, which is the stack of syntax items at the
10015 position {lnum} and {col} in the current window. {lnum} is
10016 used like with |getline()|. Each item in the List is an ID
10017 like what |synID()| returns.
10018 The first item in the List is the outer region, following are
10019 items contained in that one. The last one is what |synID()|
10020 returns, unless not the whole item is highlighted or it is a
10021 transparent item.
10022 This function is useful for debugging a syntax file.
10023 Example that shows the syntax stack under the cursor: >
10024 for id in synstack(line("."), col("."))
10025 echo synIDattr(id, "name")
10026 endfor
10027< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +010010028 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010029 character in a line and the first column in an empty line are
10030 valid positions.
10031
10032system({expr} [, {input}]) *system()* *E677*
10033 Get the output of the shell command {expr} as a |String|. See
10034 |systemlist()| to get the output as a |List|.
10035
10036 When {input} is given and is a |String| this string is written
10037 to a file and passed as stdin to the command. The string is
10038 written as-is, you need to take care of using the correct line
10039 separators yourself.
10040 If {input} is given and is a |List| it is written to the file
10041 in a way |writefile()| does with {binary} set to "b" (i.e.
10042 with a newline between each list item with newlines inside
10043 list items converted to NULs).
10044 When {input} is given and is a number that is a valid id for
10045 an existing buffer then the content of the buffer is written
10046 to the file line by line, each line terminated by a NL and
10047 NULs characters where the text has a NL.
10048
10049 Pipes are not used, the 'shelltemp' option is not used.
10050
10051 When prepended by |:silent| the terminal will not be set to
10052 cooked mode. This is meant to be used for commands that do
10053 not need the user to type. It avoids stray characters showing
10054 up on the screen which require |CTRL-L| to remove. >
10055 :silent let f = system('ls *.vim')
10056<
10057 Note: Use |shellescape()| or |::S| with |expand()| or
10058 |fnamemodify()| to escape special characters in a command
10059 argument. Newlines in {expr} may cause the command to fail.
10060 The characters in 'shellquote' and 'shellxquote' may also
10061 cause trouble.
10062 This is not to be used for interactive commands.
10063
10064 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010065 :let files = system('ls ' .. shellescape(expand('%:h')))
10066 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010067
10068< To make the result more system-independent, the shell output
10069 is filtered to replace <CR> with <NL> for Macintosh, and
10070 <CR><NL> with <NL> for DOS-like systems.
10071 To avoid the string being truncated at a NUL, all NUL
10072 characters are replaced with SOH (0x01).
10073
10074 The command executed is constructed using several options:
10075 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
10076 ({tmp} is an automatically generated file name).
10077 For Unix, braces are put around {expr} to allow for
10078 concatenated commands.
10079
10080 The command will be executed in "cooked" mode, so that a
10081 CTRL-C will interrupt the command (on Unix at least).
10082
10083 The resulting error code can be found in |v:shell_error|.
10084 This function will fail in |restricted-mode|.
10085
10086 Note that any wrong value in the options mentioned above may
10087 make the function fail. It has also been reported to fail
10088 when using a security agent application.
10089 Unlike ":!cmd" there is no automatic check for changed files.
10090 Use |:checktime| to force a check.
10091
10092 Can also be used as a |method|: >
10093 :echo GetCmd()->system()
10094
10095
10096systemlist({expr} [, {input}]) *systemlist()*
10097 Same as |system()|, but returns a |List| with lines (parts of
10098 output separated by NL) with NULs transformed into NLs. Output
10099 is the same as |readfile()| will output with {binary} argument
10100 set to "b", except that there is no extra empty item when the
10101 result ends in a NL.
10102 Note that on MS-Windows you may get trailing CR characters.
10103
10104 To see the difference between "echo hello" and "echo -n hello"
10105 use |system()| and |split()|: >
10106 echo system('echo hello')->split('\n', 1)
10107<
10108 Returns an empty string on error.
10109
10110 Can also be used as a |method|: >
10111 :echo GetCmd()->systemlist()
10112
10113
10114tabpagebuflist([{arg}]) *tabpagebuflist()*
10115 The result is a |List|, where each item is the number of the
10116 buffer associated with each window in the current tab page.
10117 {arg} specifies the number of the tab page to be used. When
10118 omitted the current tab page is used.
10119 When {arg} is invalid the number zero is returned.
10120 To get a list of all buffers in all tabs use this: >
10121 let buflist = []
10122 for i in range(tabpagenr('$'))
10123 call extend(buflist, tabpagebuflist(i + 1))
10124 endfor
10125< Note that a buffer may appear in more than one window.
10126
10127 Can also be used as a |method|: >
10128 GetTabpage()->tabpagebuflist()
10129
10130tabpagenr([{arg}]) *tabpagenr()*
10131 The result is a Number, which is the number of the current
10132 tab page. The first tab page has number 1.
10133
10134 The optional argument {arg} supports the following values:
10135 $ the number of the last tab page (the tab page
10136 count).
10137 # the number of the last accessed tab page
10138 (where |g<Tab>| goes to). if there is no
10139 previous tab page 0 is returned.
10140 The number can be used with the |:tab| command.
10141
Bram Moolenaard592deb2022-06-17 15:42:40 +010010142 Returns zero on error.
10143
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010144
10145tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
10146 Like |winnr()| but for tab page {tabarg}.
10147 {tabarg} specifies the number of tab page to be used.
10148 {arg} is used like with |winnr()|:
10149 - When omitted the current window number is returned. This is
10150 the window which will be used when going to this tab page.
10151 - When "$" the number of windows is returned.
10152 - When "#" the previous window nr is returned.
10153 Useful examples: >
10154 tabpagewinnr(1) " current window of tab page 1
10155 tabpagewinnr(4, '$') " number of windows in tab page 4
10156< When {tabarg} is invalid zero is returned.
10157
10158 Can also be used as a |method|: >
10159 GetTabpage()->tabpagewinnr()
10160<
10161 *tagfiles()*
10162tagfiles() Returns a |List| with the file names used to search for tags
10163 for the current buffer. This is the 'tags' option expanded.
10164
10165
10166taglist({expr} [, {filename}]) *taglist()*
10167 Returns a |List| of tags matching the regular expression {expr}.
10168
10169 If {filename} is passed it is used to prioritize the results
10170 in the same way that |:tselect| does. See |tag-priority|.
10171 {filename} should be the full path of the file.
10172
10173 Each list item is a dictionary with at least the following
10174 entries:
10175 name Name of the tag.
10176 filename Name of the file where the tag is
10177 defined. It is either relative to the
10178 current directory or a full path.
10179 cmd Ex command used to locate the tag in
10180 the file.
10181 kind Type of the tag. The value for this
10182 entry depends on the language specific
10183 kind values. Only available when
10184 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +000010185 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010186 static A file specific tag. Refer to
10187 |static-tag| for more information.
10188 More entries may be present, depending on the content of the
10189 tags file: access, implementation, inherits and signature.
10190 Refer to the ctags documentation for information about these
10191 fields. For C code the fields "struct", "class" and "enum"
10192 may appear, they give the name of the entity the tag is
10193 contained in.
10194
10195 The ex-command "cmd" can be either an ex search pattern, a
10196 line number or a line number followed by a byte number.
10197
10198 If there are no matching tags, then an empty list is returned.
10199
10200 To get an exact tag match, the anchors '^' and '$' should be
10201 used in {expr}. This also make the function work faster.
10202 Refer to |tag-regexp| for more information about the tag
10203 search regular expression pattern.
10204
10205 Refer to |'tags'| for information about how the tags file is
10206 located by Vim. Refer to |tags-file-format| for the format of
10207 the tags file generated by the different ctags tools.
10208
10209 Can also be used as a |method|: >
10210 GetTagpattern()->taglist()
10211
10212tan({expr}) *tan()*
10213 Return the tangent of {expr}, measured in radians, as a |Float|
10214 in the range [-inf, inf].
10215 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010216 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010217 Examples: >
10218 :echo tan(10)
10219< 0.648361 >
10220 :echo tan(-4.01)
10221< -1.181502
10222
10223 Can also be used as a |method|: >
10224 Compute()->tan()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010225
10226
10227tanh({expr}) *tanh()*
10228 Return the hyperbolic tangent of {expr} as a |Float| in the
10229 range [-1, 1].
10230 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010231 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010232 Examples: >
10233 :echo tanh(0.5)
10234< 0.462117 >
10235 :echo tanh(-1)
10236< -0.761594
10237
10238 Can also be used as a |method|: >
10239 Compute()->tanh()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010240
10241
10242tempname() *tempname()* *temp-file-name*
10243 The result is a String, which is the name of a file that
10244 doesn't exist. It can be used for a temporary file. The name
10245 is different for at least 26 consecutive calls. Example: >
10246 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010247 :exe "redir > " .. tmpfile
Christian Brabandt5cf53012024-05-18 10:13:11 +020010248< For Unix, the file will be in a private directory |tempfile|
10249 that is recursively deleted when Vim exits, on other systems
10250 temporary files are not cleaned up automatically on exit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010251 For MS-Windows forward slashes are used when the 'shellslash'
10252 option is set, or when 'shellcmdflag' starts with '-' and
10253 'shell' does not contain powershell or pwsh.
10254
10255
10256term_ functions are documented here: |terminal-function-details|
10257
10258
10259terminalprops() *terminalprops()*
10260 Returns a |Dictionary| with properties of the terminal that Vim
10261 detected from the response to |t_RV| request. See
10262 |v:termresponse| for the response itself. If |v:termresponse|
10263 is empty most values here will be 'u' for unknown.
10264 cursor_style whether sending |t_RS| works **
10265 cursor_blink_mode whether sending |t_RC| works **
10266 underline_rgb whether |t_8u| works **
10267 mouse mouse type supported
Bram Moolenaar4bc85f22022-10-21 14:17:24 +010010268 kitty whether Kitty terminal was detected
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010269
10270 ** value 'u' for unknown, 'y' for yes, 'n' for no
10271
10272 If the |+termresponse| feature is missing then the result is
10273 an empty dictionary.
10274
10275 If "cursor_style" is 'y' then |t_RS| will be sent to request the
10276 current cursor style.
10277 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
10278 request the cursor blink status.
10279 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
10280 is not empty, Vim will detect the working of sending |t_RS|
10281 and |t_RC| on startup.
10282
10283 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
10284 This avoids sending it to xterm, which would clear the colors.
10285
10286 For "mouse" the value 'u' is unknown
10287
10288 Also see:
10289 - 'ambiwidth' - detected by using |t_u7|.
10290 - |v:termstyleresp| and |v:termblinkresp| for the response to
10291 |t_RS| and |t_RC|.
10292
10293
10294test_ functions are documented here: |test-functions-details|
10295
10296
10297 *timer_info()*
10298timer_info([{id}])
10299 Return a list with information about timers.
10300 When {id} is given only information about this timer is
10301 returned. When timer {id} does not exist an empty list is
10302 returned.
10303 When {id} is omitted information about all timers is returned.
10304
10305 For each timer the information is stored in a |Dictionary| with
10306 these items:
10307 "id" the timer ID
10308 "time" time the timer was started with
10309 "remaining" time until the timer fires
10310 "repeat" number of times the timer will still fire;
10311 -1 means forever
10312 "callback" the callback
10313 "paused" 1 if the timer is paused, 0 otherwise
10314
10315 Can also be used as a |method|: >
10316 GetTimer()->timer_info()
10317
10318< {only available when compiled with the |+timers| feature}
10319
10320timer_pause({timer}, {paused}) *timer_pause()*
10321 Pause or unpause a timer. A paused timer does not invoke its
10322 callback when its time expires. Unpausing a timer may cause
10323 the callback to be invoked almost immediately if enough time
10324 has passed.
10325
10326 Pausing a timer is useful to avoid the callback to be called
10327 for a short time.
10328
10329 If {paused} evaluates to a non-zero Number or a non-empty
10330 String, then the timer is paused, otherwise it is unpaused.
10331 See |non-zero-arg|.
10332
10333 Can also be used as a |method|: >
10334 GetTimer()->timer_pause(1)
10335
10336< {only available when compiled with the |+timers| feature}
10337
10338 *timer_start()* *timer* *timers*
10339timer_start({time}, {callback} [, {options}])
10340 Create a timer and return the timer ID.
10341
10342 {time} is the waiting time in milliseconds. This is the
10343 minimum time before invoking the callback. When the system is
10344 busy or Vim is not waiting for input the time will be longer.
Bram Moolenaardd60c362023-02-27 15:49:53 +000010345 Zero can be used to execute the callback when Vim is back in
10346 the main loop.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010347
10348 {callback} is the function to call. It can be the name of a
10349 function or a |Funcref|. It is called with one argument, which
10350 is the timer ID. The callback is only invoked when Vim is
10351 waiting for input.
10352 If you want to show a message look at |popup_notification()|
10353 to avoid interfering with what the user is doing.
10354
10355 {options} is a dictionary. Supported entries:
10356 "repeat" Number of times to repeat calling the
10357 callback. -1 means forever. When not present
10358 the callback will be called once.
10359 If the timer causes an error three times in a
10360 row the repeat is cancelled. This avoids that
10361 Vim becomes unusable because of all the error
10362 messages.
10363
Bram Moolenaard592deb2022-06-17 15:42:40 +010010364 Returns -1 on error.
10365
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010366 Example: >
10367 func MyHandler(timer)
10368 echo 'Handler called'
10369 endfunc
10370 let timer = timer_start(500, 'MyHandler',
10371 \ {'repeat': 3})
10372< This will invoke MyHandler() three times at 500 msec
10373 intervals.
10374
10375 Can also be used as a |method|: >
10376 GetMsec()->timer_start(callback)
10377
10378< Not available in the |sandbox|.
10379 {only available when compiled with the |+timers| feature}
10380
10381timer_stop({timer}) *timer_stop()*
10382 Stop a timer. The timer callback will no longer be invoked.
10383 {timer} is an ID returned by timer_start(), thus it must be a
10384 Number. If {timer} does not exist there is no error.
10385
10386 Can also be used as a |method|: >
10387 GetTimer()->timer_stop()
10388
10389< {only available when compiled with the |+timers| feature}
10390
10391timer_stopall() *timer_stopall()*
10392 Stop all timers. The timer callbacks will no longer be
10393 invoked. Useful if a timer is misbehaving. If there are no
10394 timers there is no error.
10395
10396 {only available when compiled with the |+timers| feature}
10397
10398tolower({expr}) *tolower()*
10399 The result is a copy of the String given, with all uppercase
10400 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010010401 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010402
10403 Can also be used as a |method|: >
10404 GetText()->tolower()
10405
10406toupper({expr}) *toupper()*
10407 The result is a copy of the String given, with all lowercase
10408 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010010409 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010410
10411 Can also be used as a |method|: >
10412 GetText()->toupper()
10413
10414tr({src}, {fromstr}, {tostr}) *tr()*
10415 The result is a copy of the {src} string with all characters
10416 which appear in {fromstr} replaced by the character in that
10417 position in the {tostr} string. Thus the first character in
10418 {fromstr} is translated into the first character in {tostr}
10419 and so on. Exactly like the unix "tr" command.
10420 This code also deals with multibyte characters properly.
10421
Bram Moolenaard592deb2022-06-17 15:42:40 +010010422 Returns an empty string on error.
10423
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010424 Examples: >
10425 echo tr("hello there", "ht", "HT")
10426< returns "Hello THere" >
10427 echo tr("<blob>", "<>", "{}")
10428< returns "{blob}"
10429
10430 Can also be used as a |method|: >
10431 GetText()->tr(from, to)
10432
10433trim({text} [, {mask} [, {dir}]]) *trim()*
10434 Return {text} as a String where any character in {mask} is
10435 removed from the beginning and/or end of {text}.
10436
Illia Bobyr80799172023-10-17 18:00:50 +020010437 If {mask} is not given, or is an empty string, {mask} is all
10438 characters up to 0x20, which includes Tab, space, NL and CR,
10439 plus the non-breaking space character 0xa0.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010440
10441 The optional {dir} argument specifies where to remove the
10442 characters:
10443 0 remove from the beginning and end of {text}
10444 1 remove only at the beginning of {text}
10445 2 remove only at the end of {text}
10446 When omitted both ends are trimmed.
10447
10448 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010449 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010450
10451 Examples: >
10452 echo trim(" some text ")
10453< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010454 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010455< returns "RESERVE_TAIL" >
10456 echo trim("rm<Xrm<>X>rrm", "rm<>")
10457< returns "Xrm<>X" (characters in the middle are not removed) >
10458 echo trim(" vim ", " ", 2)
10459< returns " vim"
10460
10461 Can also be used as a |method|: >
10462 GetText()->trim()
10463
10464trunc({expr}) *trunc()*
10465 Return the largest integral value with magnitude less than or
10466 equal to {expr} as a |Float| (truncate towards zero).
10467 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010468 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010469 Examples: >
10470 echo trunc(1.456)
10471< 1.0 >
10472 echo trunc(-5.456)
10473< -5.0 >
10474 echo trunc(4.0)
10475< 4.0
10476
10477 Can also be used as a |method|: >
10478 Compute()->trunc()
10479<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010480 *type()*
10481type({expr}) The result is a Number representing the type of {expr}.
10482 Instead of using the number directly, it is better to use the
10483 v:t_ variable that has the value:
10484 Number: 0 |v:t_number|
10485 String: 1 |v:t_string|
10486 Funcref: 2 |v:t_func|
10487 List: 3 |v:t_list|
10488 Dictionary: 4 |v:t_dict|
10489 Float: 5 |v:t_float|
10490 Boolean: 6 |v:t_bool| (v:false and v:true)
10491 None: 7 |v:t_none| (v:null and v:none)
10492 Job: 8 |v:t_job|
10493 Channel: 9 |v:t_channel|
10494 Blob: 10 |v:t_blob|
h_east596a9f22023-11-21 21:24:23 +090010495 Class: 12 |v:t_class|
10496 Object: 13 |v:t_object|
Yegappan Lakshmanan2a71b542023-12-14 20:03:03 +010010497 Typealias: 14 |v:t_typealias|
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010010498 Enum: 15 |v:t_enum|
10499 EnumValue: 16 |v:t_enumvalue|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010500 For backward compatibility, this method can be used: >
10501 :if type(myvar) == type(0)
10502 :if type(myvar) == type("")
10503 :if type(myvar) == type(function("tr"))
10504 :if type(myvar) == type([])
10505 :if type(myvar) == type({})
10506 :if type(myvar) == type(0.0)
10507 :if type(myvar) == type(v:false)
10508 :if type(myvar) == type(v:none)
10509< To check if the v:t_ variables exist use this: >
10510 :if exists('v:t_number')
10511
10512< Can also be used as a |method|: >
10513 mylist->type()
10514
10515
10516typename({expr}) *typename()*
10517 Return a string representation of the type of {expr}.
10518 Example: >
10519 echo typename([1, 2, 3])
Kota Kato66bb9ae2023-01-17 18:31:56 +000010520< list<number> ~
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010521
10522
10523undofile({name}) *undofile()*
10524 Return the name of the undo file that would be used for a file
10525 with name {name} when writing. This uses the 'undodir'
10526 option, finding directories that exist. It does not check if
10527 the undo file exists.
10528 {name} is always expanded to the full path, since that is what
10529 is used internally.
10530 If {name} is empty undofile() returns an empty string, since a
10531 buffer without a file name will not write an undo file.
10532 Useful in combination with |:wundo| and |:rundo|.
10533 When compiled without the |+persistent_undo| option this always
10534 returns an empty string.
10535
10536 Can also be used as a |method|: >
10537 GetFilename()->undofile()
10538
Devin J. Pohly5fee1112023-04-23 20:26:59 -050010539undotree([{buf}]) *undotree()*
10540 Return the current state of the undo tree for the current
10541 buffer, or for a specific buffer if {buf} is given. The
10542 result is a dictionary with the following items:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010543 "seq_last" The highest undo sequence number used.
10544 "seq_cur" The sequence number of the current position in
10545 the undo tree. This differs from "seq_last"
10546 when some changes were undone.
10547 "time_cur" Time last used for |:earlier| and related
10548 commands. Use |strftime()| to convert to
10549 something readable.
10550 "save_last" Number of the last file write. Zero when no
10551 write yet.
10552 "save_cur" Number of the current position in the undo
10553 tree.
10554 "synced" Non-zero when the last undo block was synced.
10555 This happens when waiting from input from the
10556 user. See |undo-blocks|.
10557 "entries" A list of dictionaries with information about
10558 undo blocks.
10559
10560 The first item in the "entries" list is the oldest undo item.
10561 Each List item is a |Dictionary| with these items:
10562 "seq" Undo sequence number. Same as what appears in
10563 |:undolist|.
10564 "time" Timestamp when the change happened. Use
10565 |strftime()| to convert to something readable.
10566 "newhead" Only appears in the item that is the last one
10567 that was added. This marks the last change
10568 and where further changes will be added.
10569 "curhead" Only appears in the item that is the last one
10570 that was undone. This marks the current
10571 position in the undo tree, the block that will
10572 be used by a redo command. When nothing was
10573 undone after the last change this item will
10574 not appear anywhere.
10575 "save" Only appears on the last block before a file
10576 write. The number is the write count. The
10577 first write has number 1, the last one the
10578 "save_last" mentioned above.
10579 "alt" Alternate entry. This is again a List of undo
10580 blocks. Each item may again have an "alt"
10581 item.
10582
10583uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
10584 Remove second and succeeding copies of repeated adjacent
10585 {list} items in-place. Returns {list}. If you want a list
10586 to remain unmodified make a copy first: >
10587 :let newlist = uniq(copy(mylist))
10588< The default compare function uses the string representation of
10589 each item. For the use of {func} and {dict} see |sort()|.
10590
Bram Moolenaard592deb2022-06-17 15:42:40 +010010591 Returns zero if {list} is not a |List|.
10592
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010593 Can also be used as a |method|: >
10594 mylist->uniq()
Christian Brabandt67672ef2023-04-24 21:09:54 +010010595<
10596 *utf16idx()*
10597utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010010598 Same as |charidx()| but returns the UTF-16 code unit index of
10599 the byte at {idx} in {string} (after converting it to UTF-16).
Christian Brabandt67672ef2023-04-24 21:09:54 +010010600
10601 When {charidx} is present and TRUE, {idx} is used as the
10602 character index in the String {string} instead of as the byte
10603 index.
Yegappan Lakshmanan95707032023-06-14 13:10:15 +010010604 An {idx} in the middle of a UTF-8 sequence is rounded
10605 downwards to the beginning of that sequence.
Christian Brabandt67672ef2023-04-24 21:09:54 +010010606
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010010607 Returns -1 if the arguments are invalid or if there are less
10608 than {idx} bytes in {string}. If there are exactly {idx} bytes
10609 the length of the string in UTF-16 code units is returned.
10610
Christian Brabandt67672ef2023-04-24 21:09:54 +010010611 See |byteidx()| and |byteidxcomp()| for getting the byte index
10612 from the UTF-16 index and |charidx()| for getting the
10613 character index from the UTF-16 index.
10614 Refer to |string-offset-encoding| for more information.
10615 Examples: >
10616 echo utf16idx('a😊😊', 3) returns 2
10617 echo utf16idx('a😊😊', 7) returns 4
10618 echo utf16idx('a😊😊', 1, 0, 1) returns 2
10619 echo utf16idx('a😊😊', 2, 0, 1) returns 4
10620 echo utf16idx('aą́c', 6) returns 2
10621 echo utf16idx('aą́c', 6, 1) returns 4
10622 echo utf16idx('a😊😊', 9) returns -1
10623<
10624 Can also be used as a |method|: >
10625 GetName()->utf16idx(idx)
10626
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010627
10628values({dict}) *values()*
10629 Return a |List| with all the values of {dict}. The |List| is
10630 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010631 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010632
10633 Can also be used as a |method|: >
10634 mydict->values()
10635
zeertzjq825cf812023-08-17 22:55:25 +020010636virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010637 The result is a Number, which is the screen column of the file
10638 position given with {expr}. That is, the last screen position
10639 occupied by the character at that position, when the screen
10640 would be of unlimited width. When there is a <Tab> at the
10641 position, the returned Number will be the column at the end of
10642 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
10643 set to 8, it returns 8. |conceal| is ignored.
10644 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010645
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010646 For the use of {expr} see |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010647
10648 When 'virtualedit' is used {expr} can be [lnum, col, off],
10649 where "off" is the offset in screen columns from the start of
10650 the character. E.g., a position within a <Tab> or after the
10651 last character. When "off" is omitted zero is used. When
10652 Virtual editing is active in the current mode, a position
10653 beyond the end of the line can be returned. Also see
10654 |'virtualedit'|
10655
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010656 The accepted positions are:
10657 . the cursor position
10658 $ the end of the cursor line (the result is the
10659 number of displayed characters in the cursor line
10660 plus one)
10661 'x position of mark x (if the mark is not set, 0 is
10662 returned)
10663 v In Visual mode: the start of the Visual area (the
10664 cursor is the end). When not in Visual mode
10665 returns the cursor position. Differs from |'<| in
10666 that it's updated right away.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010667
zeertzjq825cf812023-08-17 22:55:25 +020010668 If {list} is present and non-zero then virtcol() returns a
10669 List with the first and last screen position occupied by the
LemonBoy0f7a3e12022-05-26 12:10:37 +010010670 character.
10671
zeertzjq825cf812023-08-17 22:55:25 +020010672 With the optional {winid} argument the values are obtained for
10673 that window instead of the current window.
10674
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010675 Note that only marks in the current file can be used.
10676 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +010010677 " With text "foo^Lbar" and cursor on the "^L":
10678
10679 virtcol(".") " returns 5
10680 virtcol(".", 1) " returns [4, 5]
10681 virtcol("$") " returns 9
10682
10683 " With text " there", with 't at 'h':
10684
10685 virtcol("'t") " returns 6
zeertzjq825cf812023-08-17 22:55:25 +020010686< The first column is 1. 0 or [0, 0] is returned for an error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010687 A more advanced example that echoes the maximum length of
10688 all lines: >
10689 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
10690
10691< Can also be used as a |method|: >
10692 GetPos()->virtcol()
10693
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010694virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
10695 The result is a Number, which is the byte index of the
10696 character in window {winid} at buffer line {lnum} and virtual
10697 column {col}.
10698
zeertzjqb583eda2023-10-14 11:32:28 +020010699 If buffer line {lnum} is an empty line, 0 is returned.
10700
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010701 If {col} is greater than the last virtual column in line
10702 {lnum}, then the byte index of the character at the last
10703 virtual column is returned.
10704
Yegappan Lakshmananb209b862023-08-15 23:01:44 +020010705 For a multi-byte character, the column number of the first
10706 byte in the character is returned.
10707
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010708 The {winid} argument can be the window number or the
10709 |window-ID|. If this is zero, then the current window is used.
10710
10711 Returns -1 if the window {winid} doesn't exist or the buffer
10712 line {lnum} or virtual column {col} is invalid.
10713
10714 See also |screenpos()|, |virtcol()| and |col()|.
10715
10716 Can also be used as a |method|: >
10717 GetWinid()->virtcol2col(lnum, col)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010718
10719visualmode([{expr}]) *visualmode()*
10720 The result is a String, which describes the last Visual mode
10721 used in the current buffer. Initially it returns an empty
10722 string, but once Visual mode has been used, it returns "v",
10723 "V", or "<CTRL-V>" (a single CTRL-V character) for
10724 character-wise, line-wise, or block-wise Visual mode
10725 respectively.
10726 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010727 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010728< This enters the same Visual mode as before. It is also useful
10729 in scripts if you wish to act differently depending on the
10730 Visual mode that was used.
10731 If Visual mode is active, use |mode()| to get the Visual mode
10732 (e.g., in a |:vmap|).
10733 If {expr} is supplied and it evaluates to a non-zero Number or
10734 a non-empty String, then the Visual mode will be cleared and
10735 the old value is returned. See |non-zero-arg|.
10736
10737wildmenumode() *wildmenumode()*
10738 Returns |TRUE| when the wildmenu is active and |FALSE|
10739 otherwise. See 'wildmenu' and 'wildmode'.
10740 This can be used in mappings to handle the 'wildcharm' option
10741 gracefully. (Makes only sense with |mapmode-c| mappings).
10742
10743 For example to make <c-j> work like <down> in wildmode, use: >
10744 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
10745<
10746 (Note, this needs the 'wildcharm' option set appropriately).
10747
10748win_execute({id}, {command} [, {silent}]) *win_execute()*
10749 Like `execute()` but in the context of window {id}.
10750 The window will temporarily be made the current window,
10751 without triggering autocommands or changing directory. When
10752 executing {command} autocommands will be triggered, this may
Bram Moolenaarb7398fe2023-05-14 18:50:25 +010010753 have unexpected side effects. Use `:noautocmd` if needed.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010754 Example: >
10755 call win_execute(winid, 'set syntax=python')
10756< Doing the same with `setwinvar()` would not trigger
10757 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010758 *E994*
10759 Not all commands are allowed in popup windows.
10760 When window {id} does not exist then no error is given and
10761 an empty string is returned.
10762
10763 Can also be used as a |method|, the base is passed as the
10764 second argument: >
10765 GetCommand()->win_execute(winid)
10766
10767win_findbuf({bufnr}) *win_findbuf()*
10768 Returns a |List| with |window-ID|s for windows that contain
10769 buffer {bufnr}. When there is none the list is empty.
10770
10771 Can also be used as a |method|: >
10772 GetBufnr()->win_findbuf()
10773
10774win_getid([{win} [, {tab}]]) *win_getid()*
10775 Get the |window-ID| for the specified window.
10776 When {win} is missing use the current window.
10777 With {win} this is the window number. The top window has
10778 number 1.
10779 Without {tab} use the current tab, otherwise the tab with
10780 number {tab}. The first tab has number one.
10781 Return zero if the window cannot be found.
10782
10783 Can also be used as a |method|: >
10784 GetWinnr()->win_getid()
10785
10786
10787win_gettype([{nr}]) *win_gettype()*
10788 Return the type of the window:
10789 "autocmd" autocommand window. Temporary window
10790 used to execute autocommands.
10791 "command" command-line window |cmdwin|
10792 (empty) normal window
10793 "loclist" |location-list-window|
10794 "popup" popup window |popup|
10795 "preview" preview window |preview-window|
10796 "quickfix" |quickfix-window|
10797 "unknown" window {nr} not found
10798
10799 When {nr} is omitted return the type of the current window.
10800 When {nr} is given return the type of this window by number or
10801 |window-ID|.
10802
10803 Also see the 'buftype' option. When running a terminal in a
10804 popup window then 'buftype' is "terminal" and win_gettype()
10805 returns "popup".
10806
10807 Can also be used as a |method|: >
10808 GetWinid()->win_gettype()
10809<
10810win_gotoid({expr}) *win_gotoid()*
10811 Go to window with ID {expr}. This may also change the current
10812 tabpage.
10813 Return TRUE if successful, FALSE if the window cannot be found.
10814
10815 Can also be used as a |method|: >
10816 GetWinid()->win_gotoid()
10817
10818win_id2tabwin({expr}) *win_id2tabwin()*
10819 Return a list with the tab number and window number of window
10820 with ID {expr}: [tabnr, winnr].
10821 Return [0, 0] if the window cannot be found.
10822
10823 Can also be used as a |method|: >
10824 GetWinid()->win_id2tabwin()
10825
10826win_id2win({expr}) *win_id2win()*
10827 Return the window number of window with ID {expr}.
10828 Return 0 if the window cannot be found in the current tabpage.
10829
10830 Can also be used as a |method|: >
10831 GetWinid()->win_id2win()
10832
Daniel Steinbergee630312022-01-10 13:36:34 +000010833win_move_separator({nr}, {offset}) *win_move_separator()*
10834 Move window {nr}'s vertical separator (i.e., the right border)
10835 by {offset} columns, as if being dragged by the mouse. {nr}
10836 can be a window number or |window-ID|. A positive {offset}
10837 moves right and a negative {offset} moves left. Moving a
10838 window's vertical separator will change the width of the
10839 window and the width of other windows adjacent to the vertical
10840 separator. The magnitude of movement may be smaller than
10841 specified (e.g., as a consequence of maintaining
10842 'winminwidth'). Returns TRUE if the window can be found and
10843 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010844 This will fail for the rightmost window and a full-width
10845 window, since it has no separator on the right.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000010846 Only works for the current tab page. *E1308*
Daniel Steinbergee630312022-01-10 13:36:34 +000010847
10848 Can also be used as a |method|: >
10849 GetWinnr()->win_move_separator(offset)
10850
10851win_move_statusline({nr}, {offset}) *win_move_statusline()*
10852 Move window {nr}'s status line (i.e., the bottom border) by
10853 {offset} rows, as if being dragged by the mouse. {nr} can be a
10854 window number or |window-ID|. A positive {offset} moves down
10855 and a negative {offset} moves up. Moving a window's status
10856 line will change the height of the window and the height of
10857 other windows adjacent to the status line. The magnitude of
10858 movement may be smaller than specified (e.g., as a consequence
10859 of maintaining 'winminheight'). Returns TRUE if the window can
10860 be found and FALSE otherwise.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000010861 Only works for the current tab page.
Daniel Steinbergee630312022-01-10 13:36:34 +000010862
10863 Can also be used as a |method|: >
10864 GetWinnr()->win_move_statusline(offset)
10865
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010866win_screenpos({nr}) *win_screenpos()*
10867 Return the screen position of window {nr} as a list with two
10868 numbers: [row, col]. The first window always has position
10869 [1, 1], unless there is a tabline, then it is [2, 1].
10870 {nr} can be the window number or the |window-ID|. Use zero
10871 for the current window.
Sean Dewar5866bc32024-03-13 20:17:24 +010010872 Returns [0, 0] if the window cannot be found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010873
10874 Can also be used as a |method|: >
10875 GetWinid()->win_screenpos()
10876<
10877win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
Sean Dewar96cc4ae2024-02-20 21:52:31 +010010878 Temporarily switch to window {target}, then move window {nr}
10879 to a new split adjacent to {target}.
10880 Unlike commands such as |:split|, no new windows are created
10881 (the |window-ID| of window {nr} is unchanged after the move).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010882
10883 Both {nr} and {target} can be window numbers or |window-ID|s.
10884 Both must be in the current tab page.
10885
10886 Returns zero for success, non-zero for failure.
10887
10888 {options} is a |Dictionary| with the following optional entries:
10889 "vertical" When TRUE, the split is created vertically,
10890 like with |:vsplit|.
10891 "rightbelow" When TRUE, the split is made below or to the
10892 right (if vertical). When FALSE, it is done
10893 above or to the left (if vertical). When not
10894 present, the values of 'splitbelow' and
10895 'splitright' are used.
10896
10897 Can also be used as a |method|: >
10898 GetWinid()->win_splitmove(target)
10899<
10900
10901 *winbufnr()*
10902winbufnr({nr}) The result is a Number, which is the number of the buffer
10903 associated with window {nr}. {nr} can be the window number or
10904 the |window-ID|.
10905 When {nr} is zero, the number of the buffer in the current
10906 window is returned.
10907 When window {nr} doesn't exist, -1 is returned.
10908 Example: >
10909 :echo "The file in the current window is " . bufname(winbufnr(0))
10910<
10911 Can also be used as a |method|: >
10912 FindWindow()->winbufnr()->bufname()
10913<
10914 *wincol()*
10915wincol() The result is a Number, which is the virtual column of the
10916 cursor in the window. This is counting screen cells from the
10917 left side of the window. The leftmost column is one.
10918
10919 *windowsversion()*
10920windowsversion()
10921 The result is a String. For MS-Windows it indicates the OS
10922 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
10923 Windows XP is "5.1". For non-MS-Windows systems the result is
10924 an empty string.
10925
10926winheight({nr}) *winheight()*
10927 The result is a Number, which is the height of window {nr}.
10928 {nr} can be the window number or the |window-ID|.
10929 When {nr} is zero, the height of the current window is
10930 returned. When window {nr} doesn't exist, -1 is returned.
10931 An existing window always has a height of zero or more.
10932 This excludes any window toolbar line.
10933 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010934 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010935
10936< Can also be used as a |method|: >
10937 GetWinid()->winheight()
10938<
10939winlayout([{tabnr}]) *winlayout()*
10940 The result is a nested List containing the layout of windows
10941 in a tabpage.
10942
10943 Without {tabnr} use the current tabpage, otherwise the tabpage
10944 with number {tabnr}. If the tabpage {tabnr} is not found,
10945 returns an empty list.
10946
10947 For a leaf window, it returns:
10948 ['leaf', {winid}]
10949 For horizontally split windows, which form a column, it
10950 returns:
10951 ['col', [{nested list of windows}]]
10952 For vertically split windows, which form a row, it returns:
10953 ['row', [{nested list of windows}]]
10954
10955 Example: >
10956 " Only one window in the tab page
10957 :echo winlayout()
10958 ['leaf', 1000]
10959 " Two horizontally split windows
10960 :echo winlayout()
10961 ['col', [['leaf', 1000], ['leaf', 1001]]]
10962 " The second tab page, with three horizontally split
10963 " windows, with two vertically split windows in the
10964 " middle window
10965 :echo winlayout(2)
10966 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
10967 ['leaf', 1001]]], ['leaf', 1000]]]
10968<
10969 Can also be used as a |method|: >
10970 GetTabnr()->winlayout()
10971<
10972 *winline()*
10973winline() The result is a Number, which is the screen line of the cursor
10974 in the window. This is counting screen lines from the top of
10975 the window. The first line is one.
10976 If the cursor was moved the view on the file will be updated
10977 first, this may cause a scroll.
10978
10979 *winnr()*
10980winnr([{arg}]) The result is a Number, which is the number of the current
10981 window. The top window has number 1.
10982 Returns zero for a popup window.
10983
10984 The optional argument {arg} supports the following values:
10985 $ the number of the last window (the window
10986 count).
10987 # the number of the last accessed window (where
10988 |CTRL-W_p| goes to). If there is no previous
10989 window or it is in another tab page 0 is
Sean Deward64801e2024-03-12 20:46:12 +010010990 returned. May refer to the current window in
10991 some cases (e.g. when evaluating 'statusline'
10992 expressions).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010993 {N}j the number of the Nth window below the
10994 current window (where |CTRL-W_j| goes to).
10995 {N}k the number of the Nth window above the current
10996 window (where |CTRL-W_k| goes to).
10997 {N}h the number of the Nth window left of the
10998 current window (where |CTRL-W_h| goes to).
10999 {N}l the number of the Nth window right of the
11000 current window (where |CTRL-W_l| goes to).
11001 The number can be used with |CTRL-W_w| and ":wincmd w"
11002 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010011003 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011004 Also see |tabpagewinnr()| and |win_getid()|.
11005 Examples: >
11006 let window_count = winnr('$')
11007 let prev_window = winnr('#')
11008 let wnum = winnr('3k')
11009
11010< Can also be used as a |method|: >
11011 GetWinval()->winnr()
11012<
11013 *winrestcmd()*
11014winrestcmd() Returns a sequence of |:resize| commands that should restore
11015 the current window sizes. Only works properly when no windows
11016 are opened or closed and the current window and tab page is
11017 unchanged.
11018 Example: >
11019 :let cmd = winrestcmd()
11020 :call MessWithWindowSizes()
11021 :exe cmd
11022<
11023 *winrestview()*
11024winrestview({dict})
11025 Uses the |Dictionary| returned by |winsaveview()| to restore
11026 the view of the current window.
11027 Note: The {dict} does not have to contain all values, that are
11028 returned by |winsaveview()|. If values are missing, those
11029 settings won't be restored. So you can use: >
11030 :call winrestview({'curswant': 4})
11031<
11032 This will only set the curswant value (the column the cursor
11033 wants to move on vertical movements) of the cursor to column 5
11034 (yes, that is 5), while all other settings will remain the
11035 same. This is useful, if you set the cursor position manually.
11036
11037 If you have changed the values the result is unpredictable.
11038 If the window size changed the result won't be the same.
11039
11040 Can also be used as a |method|: >
11041 GetView()->winrestview()
11042<
11043 *winsaveview()*
11044winsaveview() Returns a |Dictionary| that contains information to restore
11045 the view of the current window. Use |winrestview()| to
11046 restore the view.
11047 This is useful if you have a mapping that jumps around in the
11048 buffer and you want to go back to the original view.
11049 This does not save fold information. Use the 'foldenable'
11050 option to temporarily switch off folding, so that folds are
11051 not opened when moving around. This may have side effects.
11052 The return value includes:
11053 lnum cursor line number
11054 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000011055 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011056 returns)
11057 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000011058 curswant column for vertical movement (Note:
11059 the first column is zero, as opposed
11060 to what |getcurpos()| returns). After
11061 |$| command it will be a very large
11062 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011063 topline first line in the window
11064 topfill filler lines, only in diff mode
11065 leftcol first column displayed; only used when
11066 'wrap' is off
11067 skipcol columns skipped
11068 Note that no option values are saved.
11069
11070
11071winwidth({nr}) *winwidth()*
11072 The result is a Number, which is the width of window {nr}.
11073 {nr} can be the window number or the |window-ID|.
11074 When {nr} is zero, the width of the current window is
11075 returned. When window {nr} doesn't exist, -1 is returned.
11076 An existing window always has a width of zero or more.
11077 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011078 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011079 :if winwidth(0) <= 50
11080 : 50 wincmd |
11081 :endif
11082< For getting the terminal or screen size, see the 'columns'
11083 option.
11084
11085 Can also be used as a |method|: >
11086 GetWinid()->winwidth()
11087
11088
11089wordcount() *wordcount()*
11090 The result is a dictionary of byte/chars/word statistics for
11091 the current buffer. This is the same info as provided by
11092 |g_CTRL-G|
11093 The return value includes:
11094 bytes Number of bytes in the buffer
11095 chars Number of chars in the buffer
11096 words Number of words in the buffer
11097 cursor_bytes Number of bytes before cursor position
11098 (not in Visual mode)
11099 cursor_chars Number of chars before cursor position
11100 (not in Visual mode)
11101 cursor_words Number of words before cursor position
11102 (not in Visual mode)
11103 visual_bytes Number of bytes visually selected
11104 (only in Visual mode)
11105 visual_chars Number of chars visually selected
11106 (only in Visual mode)
11107 visual_words Number of words visually selected
11108 (only in Visual mode)
11109
11110
11111 *writefile()*
11112writefile({object}, {fname} [, {flags}])
11113 When {object} is a |List| write it to file {fname}. Each list
11114 item is separated with a NL. Each list item must be a String
11115 or Number.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011116 All NL characters are replaced with a NUL character.
11117 Inserting CR characters needs to be done before passing {list}
11118 to writefile().
Bram Moolenaar806a2732022-09-04 15:40:36 +010011119
11120 When {object} is a |Blob| write the bytes to file {fname}
11121 unmodified, also when binary mode is not specified.
11122
11123 {flags} must be a String. These characters are recognized:
11124
11125 'b' Binary mode is used: There will not be a NL after the
11126 last list item. An empty item at the end does cause the
11127 last line in the file to end in a NL.
11128
11129 'a' Append mode is used, lines are appended to the file: >
11130 :call writefile(["foo"], "event.log", "a")
11131 :call writefile(["bar"], "event.log", "a")
11132<
11133 'D' Delete the file when the current function ends. This
11134 works like: >
Bram Moolenaar938ae282023-02-20 20:44:55 +000011135 :defer delete({fname})
Bram Moolenaar806a2732022-09-04 15:40:36 +010011136< Fails when not in a function. Also see |:defer|.
11137
11138 's' fsync() is called after writing the file. This flushes
11139 the file to disk, if possible. This takes more time but
11140 avoids losing the file if the system crashes.
11141
11142 'S' fsync() is not called, even when 'fsync' is set.
11143
11144 When {flags} does not contain "S" or "s" then fsync() is
11145 called if the 'fsync' option is set.
11146
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011147 An existing file is overwritten, if possible.
Bram Moolenaar806a2732022-09-04 15:40:36 +010011148
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011149 When the write fails -1 is returned, otherwise 0. There is an
11150 error message if the file can't be created or when writing
11151 fails.
Bram Moolenaar806a2732022-09-04 15:40:36 +010011152
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011153 Also see |readfile()|.
11154 To copy a file byte for byte: >
11155 :let fl = readfile("foo", "b")
11156 :call writefile(fl, "foocopy", "b")
11157
11158< Can also be used as a |method|: >
11159 GetText()->writefile("thefile")
11160
11161
11162xor({expr}, {expr}) *xor()*
11163 Bitwise XOR on the two arguments. The arguments are converted
11164 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010011165 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011166 Example: >
11167 :let bits = xor(bits, 0x80)
11168<
11169 Can also be used as a |method|: >
11170 :let bits = bits->xor(0x80)
11171<
11172
11173==============================================================================
111743. Feature list *feature-list*
11175
11176There are three types of features:
111771. Features that are only supported when they have been enabled when Vim
11178 was compiled |+feature-list|. Example: >
11179 :if has("cindent")
11180< *gui_running*
111812. Features that are only supported when certain conditions have been met.
11182 Example: >
11183 :if has("gui_running")
11184< *has-patch*
111853. Beyond a certain version or at a certain version and including a specific
11186 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
11187 later, or it is version 7.4 and patch 248 was included. Example: >
11188 :if has("patch-7.4.248")
11189< Note that it's possible for patch 248 to be omitted even though 249 is
11190 included. Only happens when cherry-picking patches.
11191 Note that this form only works for patch 7.4.237 and later, before that
11192 you need to check for the patch and the v:version. Example (checking
11193 version 6.2.148 or later): >
11194 :if v:version > 602 || (v:version == 602 && has("patch148"))
11195
11196Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
11197use: `if exists('+shellslash')`
11198
11199
11200acl Compiled with |ACL| support.
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010011201all_builtin_terms Compiled with all builtin terminals enabled. (always
11202 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011203amiga Amiga version of Vim.
11204arabic Compiled with Arabic support |Arabic|.
11205arp Compiled with ARP support (Amiga).
11206autocmd Compiled with autocommand support. (always true)
11207autochdir Compiled with support for 'autochdir'
11208autoservername Automatically enable |clientserver|
11209balloon_eval Compiled with |balloon-eval| support.
11210balloon_multiline GUI supports multiline balloons.
11211beos BeOS version of Vim.
11212browse Compiled with |:browse| support, and browse() will
11213 work.
11214browsefilter Compiled with support for |browsefilter|.
11215bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010011216builtin_terms Compiled with some builtin terminals. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011217byte_offset Compiled with support for 'o' in 'statusline'
11218channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011219cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011220clientserver Compiled with remote invocation support |clientserver|.
11221clipboard Compiled with 'clipboard' support.
11222clipboard_working Compiled with 'clipboard' support and it can be used.
11223cmdline_compl Compiled with |cmdline-completion| support.
11224cmdline_hist Compiled with |cmdline-history| support.
11225cmdline_info Compiled with 'showcmd' and 'ruler' support.
11226comments Compiled with |'comments'| support.
11227compatible Compiled to be very Vi compatible.
11228conpty Platform where |ConPTY| can be used.
11229cryptv Compiled with encryption support |encryption|.
11230cscope Compiled with |cscope| support.
11231cursorbind Compiled with |'cursorbind'| (always true)
11232debug Compiled with "DEBUG" defined.
11233dialog_con Compiled with console dialog support.
glepnirdf461152024-04-04 22:23:29 +020011234dialog_con_gui Compiled with console and GUI dialog support.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011235dialog_gui Compiled with GUI dialog support.
11236diff Compiled with |vimdiff| and 'diff' support.
11237digraphs Compiled with support for digraphs.
11238directx Compiled with support for DirectX and 'renderoptions'.
11239dnd Compiled with support for the "~ register |quote_~|.
11240drop_file Compiled with |drop_file| support.
11241ebcdic Compiled on a machine with ebcdic character set.
11242emacs_tags Compiled with support for Emacs tags.
11243eval Compiled with expression evaluation support. Always
11244 true, of course!
11245ex_extra |+ex_extra| (always true)
11246extra_search Compiled with support for |'incsearch'| and
11247 |'hlsearch'|
11248farsi Support for Farsi was removed |farsi|.
Bram Moolenaarf80f40a2022-08-25 16:02:23 +010011249file_in_path Compiled with support for |gf| and |<cfile>| (always
11250 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011251filterpipe When 'shelltemp' is off pipes are used for shell
11252 read/write/filter commands
11253find_in_path Compiled with support for include file searches
11254 |+find_in_path|.
11255float Compiled with support for |Float|.
11256fname_case Case in file names matters (for Amiga and MS-Windows
11257 this is not present).
11258folding Compiled with |folding| support.
11259footer Compiled with GUI footer support. |gui-footer|
11260fork Compiled to use fork()/exec() instead of system().
11261gettext Compiled with message translation |multi-lang|
11262gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010011263gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011264gui_gnome Compiled with Gnome support (gui_gtk is also defined).
11265gui_gtk Compiled with GTK+ GUI (any version).
11266gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
11267gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
11268gui_haiku Compiled with Haiku GUI.
11269gui_mac Compiled with Macintosh GUI.
11270gui_motif Compiled with Motif GUI.
11271gui_photon Compiled with Photon GUI.
11272gui_running Vim is running in the GUI, or it will start soon.
11273gui_win32 Compiled with MS-Windows Win32 GUI.
11274gui_win32s idem, and Win32s system being used (Windows 3.1)
11275haiku Haiku version of Vim.
11276hangul_input Compiled with Hangul input support. |hangul|
11277hpux HP-UX version of Vim.
11278iconv Can use iconv() for conversion.
11279insert_expand Compiled with support for CTRL-X expansion commands in
11280 Insert mode. (always true)
11281job Compiled with support for |channel| and |job|
11282ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011283jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011284keymap Compiled with 'keymap' support.
11285lambda Compiled with |lambda| support.
11286langmap Compiled with 'langmap' support.
11287libcall Compiled with |libcall()| support.
11288linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
11289 'breakindent' support.
11290linux Linux version of Vim.
11291lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011292 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011293listcmds Compiled with commands for the buffer list |:files|
11294 and the argument list |arglist|.
11295localmap Compiled with local mappings and abbr. |:map-local|
11296lua Compiled with Lua interface |Lua|.
11297mac Any Macintosh version of Vim cf. osx
11298macunix Synonym for osxdarwin
11299menu Compiled with support for |:menu|.
11300mksession Compiled with support for |:mksession|.
11301modify_fname Compiled with file name modifiers. |filename-modifiers|
11302 (always true)
11303mouse Compiled with support for mouse.
11304mouse_dec Compiled with support for Dec terminal mouse.
11305mouse_gpm Compiled with support for gpm (Linux console mouse)
11306mouse_gpm_enabled GPM mouse is working
11307mouse_netterm Compiled with support for netterm mouse.
11308mouse_pterm Compiled with support for qnx pterm mouse.
11309mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
11310mouse_sgr Compiled with support for sgr mouse.
11311mouse_urxvt Compiled with support for urxvt mouse.
11312mouse_xterm Compiled with support for xterm mouse.
11313mouseshape Compiled with support for 'mouseshape'.
11314multi_byte Compiled with support for 'encoding' (always true)
11315multi_byte_encoding 'encoding' is set to a multibyte encoding.
11316multi_byte_ime Compiled with support for IME input method.
11317multi_lang Compiled with support for multiple languages.
11318mzscheme Compiled with MzScheme interface |mzscheme|.
11319nanotime Compiled with sub-second time stamp checks.
11320netbeans_enabled Compiled with support for |netbeans| and connected.
11321netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011322num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011323ole Compiled with OLE automation support for Win32.
11324osx Compiled for macOS cf. mac
11325osxdarwin Compiled for macOS, with |mac-darwin-feature|
11326packages Compiled with |packages| support.
11327path_extra Compiled with up/downwards search in 'path' and 'tags'
11328perl Compiled with Perl interface.
11329persistent_undo Compiled with support for persistent undo history.
11330postscript Compiled with PostScript file printing.
11331printer Compiled with |:hardcopy| support.
11332profile Compiled with |:profile| support.
Bram Moolenaar71badf92023-04-22 22:40:14 +010011333prof_nsec Profile results are in nanoseconds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011334python Python 2.x interface available. |has-python|
11335python_compiled Compiled with Python 2.x interface. |has-python|
11336python_dynamic Python 2.x interface is dynamically loaded. |has-python|
11337python3 Python 3.x interface available. |has-python|
11338python3_compiled Compiled with Python 3.x interface. |has-python|
11339python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Yee Cheng Chinc13b3d12023-08-20 21:18:38 +020011340python3_stable Python 3.x interface is using Python Stable ABI. |has-python|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011341pythonx Python 2.x and/or 3.x interface available. |python_x|
11342qnx QNX version of Vim.
11343quickfix Compiled with |quickfix| support.
11344reltime Compiled with |reltime()| support.
11345rightleft Compiled with 'rightleft' support.
11346ruby Compiled with Ruby interface |ruby|.
11347scrollbind Compiled with 'scrollbind' support. (always true)
11348showcmd Compiled with 'showcmd' support.
11349signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011350smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011351sodium Compiled with libsodium for better crypt support
11352sound Compiled with sound support, e.g. `sound_playevent()`
11353spell Compiled with spell checking support |spell|.
11354startuptime Compiled with |--startuptime| support.
11355statusline Compiled with support for 'statusline', 'rulerformat'
11356 and special formats of 'titlestring' and 'iconstring'.
11357sun SunOS version of Vim.
11358sun_workshop Support for Sun |workshop| has been removed.
11359syntax Compiled with syntax highlighting support |syntax|.
11360syntax_items There are active syntax highlighting items for the
11361 current buffer.
11362system Compiled to use system() instead of fork()/exec().
11363tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011364 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011365tag_old_static Support for old static tags was removed, see
11366 |tag-old-static|.
11367tcl Compiled with Tcl interface.
11368termguicolors Compiled with true color in terminal support.
11369terminal Compiled with |terminal| support.
11370terminfo Compiled with terminfo instead of termcap.
11371termresponse Compiled with support for |t_RV| and |v:termresponse|.
11372textobjects Compiled with support for |text-objects|.
11373textprop Compiled with support for |text-properties|.
11374tgetent Compiled with tgetent support, able to use a termcap
11375 or terminfo file.
11376timers Compiled with |timer_start()| support.
11377title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011378 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011379toolbar Compiled with support for |gui-toolbar|.
11380ttyin input is a terminal (tty)
11381ttyout output is a terminal (tty)
11382unix Unix version of Vim. *+unix*
11383unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
11384user_commands User-defined commands. (always true)
11385vartabs Compiled with variable tabstop support |'vartabstop'|.
11386vcon Win32: Virtual console support is working, can use
11387 'termguicolors'. Also see |+vtp|.
11388vertsplit Compiled with vertically split windows |:vsplit|.
11389 (always true)
11390vim_starting True while initial source'ing takes place. |startup|
11391 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000011392vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011393viminfo Compiled with viminfo support.
11394vimscript-1 Compiled Vim script version 1 support
11395vimscript-2 Compiled Vim script version 2 support
11396vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010011397vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011398virtualedit Compiled with 'virtualedit' option. (always true)
11399visual Compiled with Visual mode. (always true)
11400visualextra Compiled with extra Visual mode commands. (always
11401 true) |blockwise-operators|.
11402vms VMS version of Vim.
11403vreplace Compiled with |gR| and |gr| commands. (always true)
11404vtp Compiled for vcon support |+vtp| (check vcon to find
11405 out if it works in the current console).
11406wildignore Compiled with 'wildignore' option.
11407wildmenu Compiled with 'wildmenu' option.
11408win16 old version for MS-Windows 3.1 (always false)
11409win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
11410 64 bits)
11411win32unix Win32 version of Vim, using Unix files (Cygwin)
11412win64 Win64 version of Vim (MS-Windows 64 bit).
11413win95 Win32 version for MS-Windows 95/98/ME (always false)
11414winaltkeys Compiled with 'winaltkeys' option.
11415windows Compiled with support for more than one window.
11416 (always true)
11417writebackup Compiled with 'writebackup' default on.
Christian Brabandte085dfd2023-09-30 12:49:18 +020011418xattr Compiled with extended attributes support |xattr|
11419 (currently only supported on Linux).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011420xfontset Compiled with X fontset support |xfontset|.
11421xim Compiled with X input method support |xim|.
11422xpm Compiled with pixmap support.
11423xpm_w32 Compiled with pixmap support for Win32. (Only for
11424 backward compatibility. Use "xpm" instead.)
11425xsmp Compiled with X session management support.
11426xsmp_interact Compiled with interactive X session management support.
11427xterm_clipboard Compiled with support for xterm clipboard.
11428xterm_save Compiled with support for saving and restoring the
11429 xterm screen.
11430x11 Compiled with X11 support.
11431
11432
11433==============================================================================
114344. Matching a pattern in a String *string-match*
11435
11436This is common between several functions. A regexp pattern as explained at
11437|pattern| is normally used to find a match in the buffer lines. When a
11438pattern is used to find a match in a String, almost everything works in the
11439same way. The difference is that a String is handled like it is one line.
11440When it contains a "\n" character, this is not seen as a line break for the
11441pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
11442>
11443 :let a = "aaaa\nxxxx"
11444 :echo matchstr(a, "..\n..")
11445 aa
11446 xx
11447 :echo matchstr(a, "a.x")
11448 a
11449 x
11450
11451Don't forget that "^" will only match at the first character of the String and
11452"$" at the last character of the string. They don't match after or before a
11453"\n".
11454
11455 vim:tw=78:ts=8:noet:ft=help:norl: