blob: fe0b9aa335a215aac154cfdb9a3012157394a3e0 [file] [log] [blame]
Shougo Matsushita69084282024-09-23 20:34:47 +02001*builtin.txt* For Vim version 9.1. Last change: 2024 Sep 23
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}
erraelf0837ba2024-06-24 12:27:01 -070031appendbufline({buf}, {lnum}, {text})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000032 Number append {text} below line {lnum}
erraelf0837ba2024-06-24 12:27:01 -070033 in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000034argc([{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
Christ van Willegence0ef912024-06-20 23:41:59 +020070bindtextdomain({package}, {path})
Christ van Willegen8252ef12024-07-11 21:36:21 +020071 Bool bind text domain to specified path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000072blob2list({blob}) List convert {blob} into a list of numbers
73browse({save}, {title}, {initdir}, {default})
74 String put up a file requester
75browsedir({title}, {initdir}) String put up a directory requester
76bufadd({name}) Number add a buffer to the buffer list
77bufexists({buf}) Number |TRUE| if buffer {buf} exists
78buflisted({buf}) Number |TRUE| if buffer {buf} is listed
79bufload({buf}) Number load buffer {buf} if not loaded yet
80bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
81bufname([{buf}]) String Name of the buffer {buf}
82bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
83bufwinid({buf}) Number window ID of buffer {buf}
84bufwinnr({buf}) Number window number of buffer {buf}
85byte2line({byte}) Number line number at byte count {byte}
Christian Brabandt67672ef2023-04-24 21:09:54 +010086byteidx({expr}, {nr} [, {utf16}])
87 Number byte index of {nr}'th char in {expr}
88byteidxcomp({expr}, {nr} [, {utf16}])
89 Number byte index of {nr}'th char in {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000090call({func}, {arglist} [, {dict}])
91 any call {func} with arguments {arglist}
92ceil({expr}) Float round {expr} up
93ch_canread({handle}) Number check if there is something to read
94ch_close({handle}) none close {handle}
95ch_close_in({handle}) none close in part of {handle}
96ch_evalexpr({handle}, {expr} [, {options}])
97 any evaluate {expr} on JSON {handle}
98ch_evalraw({handle}, {string} [, {options}])
99 any evaluate {string} on raw {handle}
100ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
101ch_getjob({channel}) Job get the Job of {channel}
102ch_info({handle}) String info about channel {handle}
103ch_log({msg} [, {handle}]) none write {msg} in the channel log file
104ch_logfile({fname} [, {mode}]) none start logging channel activity
105ch_open({address} [, {options}])
106 Channel open a channel to {address}
107ch_read({handle} [, {options}]) String read from {handle}
108ch_readblob({handle} [, {options}])
109 Blob read Blob from {handle}
110ch_readraw({handle} [, {options}])
111 String read raw from {handle}
112ch_sendexpr({handle}, {expr} [, {options}])
113 any send {expr} over JSON {handle}
114ch_sendraw({handle}, {expr} [, {options}])
115 any send {expr} over raw {handle}
116ch_setoptions({handle}, {options})
117 none set options for {handle}
118ch_status({handle} [, {options}])
119 String status of channel {handle}
120changenr() Number current change number
121char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
122charclass({string}) Number character class of {string}
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000123charcol({expr} [, {winid}]) Number column number of cursor or mark
Christian Brabandt67672ef2023-04-24 21:09:54 +0100124charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000125 Number char index of byte {idx} in {string}
126chdir({dir}) String change current working directory
127cindent({lnum}) Number C indent for line {lnum}
128clearmatches([{win}]) none clear all matches
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000129col({expr} [, {winid}]) Number column byte index of cursor or mark
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000130complete({startcol}, {matches}) none set Insert mode completion
131complete_add({expr}) Number add completion match
132complete_check() Number check for key typed during completion
133complete_info([{what}]) Dict get current completion information
134confirm({msg} [, {choices} [, {default} [, {type}]]])
135 Number number of choice picked by user
136copy({expr}) any make a shallow copy of {expr}
137cos({expr}) Float cosine of {expr}
138cosh({expr}) Float hyperbolic cosine of {expr}
139count({comp}, {expr} [, {ic} [, {start}]])
140 Number count how many {expr} are in {comp}
141cscope_connection([{num}, {dbpath} [, {prepend}]])
142 Number checks existence of cscope connection
143cursor({lnum}, {col} [, {off}])
144 Number move cursor to {lnum}, {col}, {off}
145cursor({list}) Number move cursor to position in {list}
146debugbreak({pid}) Number interrupt process being debugged
147deepcopy({expr} [, {noref}]) any make a full copy of {expr}
148delete({fname} [, {flags}]) Number delete the file or directory {fname}
149deletebufline({buf}, {first} [, {last}])
150 Number delete lines from buffer {buf}
151did_filetype() Number |TRUE| if FileType autocmd event used
Yegappan Lakshmananfa378352024-02-01 22:05:27 +0100152diff({fromlist}, {tolist} [, {options}])
153 List diff two Lists of strings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000154diff_filler({lnum}) Number diff filler lines about {lnum}
155diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
156digraph_get({chars}) String get the |digraph| of {chars}
157digraph_getlist([{listall}]) List get all |digraph|s
Christian Brabandtfbc37f12024-06-18 20:50:58 +0200158digraph_set({chars}, {digraph}) Bool register |digraph|
159digraph_setlist({digraphlist}) Bool register multiple |digraph|s
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000160echoraw({expr}) none output {expr} as-is
161empty({expr}) Number |TRUE| if {expr} is empty
162environ() Dict return environment variables
Sean Dewarb0efa492023-07-08 10:35:19 +0100163err_teapot([{expr}]) none give E418, or E503 if {expr} is |TRUE|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000164escape({string}, {chars}) String escape {chars} in {string} with '\'
165eval({string}) any evaluate {string} into its value
166eventhandler() Number |TRUE| if inside an event handler
167executable({expr}) Number 1 if executable {expr} exists
168execute({command}) String execute {command} and get the output
169exepath({expr}) String full path of the command {expr}
170exists({expr}) Number |TRUE| if {expr} exists
171exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
172exp({expr}) Float exponential of {expr}
173expand({expr} [, {nosuf} [, {list}]])
174 any expand special keywords in {expr}
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +0100175expandcmd({string} [, {options}])
176 String expand {string} like with `:edit`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000177extend({expr1}, {expr2} [, {expr3}])
178 List/Dict insert items of {expr2} into {expr1}
179extendnew({expr1}, {expr2} [, {expr3}])
180 List/Dict like |extend()| but creates a new
181 List or Dictionary
182feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Shougo Matsushita60c87432024-06-03 22:59:27 +0200183filecopy({from}, {to}) Number |TRUE| if copying file {from} to {to}
184 worked
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000185filereadable({file}) Number |TRUE| if {file} is a readable file
186filewritable({file}) Number |TRUE| if {file} is a writable file
187filter({expr1}, {expr2}) List/Dict/Blob/String
188 remove items from {expr1} where
189 {expr2} is 0
190finddir({name} [, {path} [, {count}]])
191 String find directory {name} in {path}
192findfile({name} [, {path} [, {count}]])
193 String find file {name} in {path}
194flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
195flattennew({list} [, {maxdepth}])
196 List flatten a copy of {list}
197float2nr({expr}) Number convert Float {expr} to a Number
198floor({expr}) Float round {expr} down
199fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
200fnameescape({fname}) String escape special characters in {fname}
201fnamemodify({fname}, {mods}) String modify file name
202foldclosed({lnum}) Number first line of fold at {lnum} if closed
203foldclosedend({lnum}) Number last line of fold at {lnum} if closed
204foldlevel({lnum}) Number fold level at {lnum}
205foldtext() String line displayed for closed fold
206foldtextresult({lnum}) String text for closed fold at {lnum}
Ernie Raele79e2072024-01-13 11:47:33 +0100207foreach({expr1}, {expr2}) List/Dict/Blob/String
208 for each item in {expr1} call {expr2}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000209foreground() Number bring the Vim window to the foreground
Bram Moolenaaraa534142022-09-15 21:46:02 +0100210fullcommand({name} [, {vim9}]) String get full command from {name}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000211funcref({name} [, {arglist}] [, {dict}])
212 Funcref reference to function {name}
213function({name} [, {arglist}] [, {dict}])
214 Funcref named reference to function {name}
215garbagecollect([{atexit}]) none free memory, breaking cyclic references
216get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
217get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
218get({func}, {what}) any get property of funcref/partial {func}
219getbufinfo([{buf}]) List information about buffers
220getbufline({buf}, {lnum} [, {end}])
221 List lines {lnum} to {end} of buffer {buf}
Bram Moolenaarce30ccc2022-11-21 19:57:04 +0000222getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000223getbufvar({buf}, {varname} [, {def}])
224 any variable {varname} in buffer {buf}
Kota Kato66bb9ae2023-01-17 18:31:56 +0000225getcellwidths() List get character cell width overrides
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000226getchangelist([{buf}]) List list of change list items
Doug Kearns9cd9e752024-04-07 17:42:17 +0200227getchar([{expr}]) Number or String
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000228 get one character from the user
229getcharmod() Number modifiers for the last typed character
230getcharpos({expr}) List position of cursor, mark, etc.
231getcharsearch() Dict last character search
Doug Kearns9cd9e752024-04-07 17:42:17 +0200232getcharstr([{expr}]) String get one character from the user
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100233getcmdcompltype() String return the type of the current
234 command-line completion
Shougo Matsushita69084282024-09-23 20:34:47 +0200235getcmdline() String return the current command-line input
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000236getcmdpos() Number return cursor position in command-line
Shougo Matsushita69084282024-09-23 20:34:47 +0200237getcmdprompt() String return the current command-line prompt
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100238getcmdscreenpos() Number return cursor screen position in
239 command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000240getcmdtype() String return current command-line type
241getcmdwintype() String return current command-line window type
242getcompletion({pat}, {type} [, {filtered}])
243 List list of cmdline completion matches
244getcurpos([{winnr}]) List position of the cursor
245getcursorcharpos([{winnr}]) List character position of the cursor
246getcwd([{winnr} [, {tabnr}]]) String get the current working directory
247getenv({name}) String return environment variable
248getfontname([{name}]) String name of font being used
249getfperm({fname}) String file permissions of file {fname}
250getfsize({fname}) Number size in bytes of file {fname}
251getftime({fname}) Number last modification time of file
252getftype({fname}) String description of type of file {fname}
253getimstatus() Number |TRUE| if the IME status is active
254getjumplist([{winnr} [, {tabnr}]])
255 List list of jump list items
256getline({lnum}) String line {lnum} of current buffer
257getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
258getloclist({nr}) List list of location list items
259getloclist({nr}, {what}) Dict get specific location list properties
260getmarklist([{buf}]) List list of global/local marks
261getmatches([{win}]) List list of current matches
262getmousepos() Dict last known mouse position
Bram Moolenaar24dc19c2022-11-14 19:49:15 +0000263getmouseshape() String current mouse shape name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000264getpid() Number process ID of Vim
265getpos({expr}) List position of cursor, mark, etc.
266getqflist() List list of quickfix items
267getqflist({what}) Dict get specific quickfix list properties
268getreg([{regname} [, 1 [, {list}]]])
269 String or List contents of a register
270getreginfo([{regname}]) Dict information about a register
Shougo Matsushita19b71882024-02-28 22:48:12 +0100271getregion({pos1}, {pos2} [, {opts}])
Shougo Matsushita3f905ab2024-02-21 00:02:45 +0100272 List get the text from {pos1} to {pos2}
Shougo Matsushitab4757e62024-05-07 20:49:24 +0200273getregionpos({pos1}, {pos2} [, {opts}])
274 List get a list of positions for a region
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000275getregtype([{regname}]) String type of a register
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +0100276getscriptinfo([{opts}]) List list of sourced scripts
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000277gettabinfo([{expr}]) List list of tab pages
278gettabvar({nr}, {varname} [, {def}])
279 any variable {varname} in tab {nr} or {def}
280gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
281 any {name} in {winnr} in tab page {tabnr}
282gettagstack([{nr}]) Dict get the tag stack of window {nr}
h-east52e7cc22024-07-28 17:03:29 +0200283gettext({text} [, {package}]) String lookup translation of {text}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000284getwininfo([{winid}]) List list of info about each window
Bram Moolenaar938ae282023-02-20 20:44:55 +0000285getwinpos([{timeout}]) List X and Y coord in pixels of Vim window
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000286getwinposx() Number X coord in pixels of the Vim window
287getwinposy() Number Y coord in pixels of the Vim window
288getwinvar({nr}, {varname} [, {def}])
289 any variable {varname} in window {nr}
290glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
291 any expand file wildcards in {expr}
292glob2regpat({expr}) String convert a glob pat into a search pat
293globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
294 String do glob({expr}) for all dirs in {path}
295has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
296has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
297haslocaldir([{winnr} [, {tabnr}]])
298 Number |TRUE| if the window executed |:lcd|
299 or |:tcd|
300hasmapto({what} [, {mode} [, {abbr}]])
301 Number |TRUE| if mapping to {what} exists
302histadd({history}, {item}) Number add an item to a history
303histdel({history} [, {item}]) Number remove an item from a history
304histget({history} [, {index}]) String get the item {index} from a history
305histnr({history}) Number highest index of a history
306hlID({name}) Number syntax ID of highlight group {name}
307hlexists({name}) Number |TRUE| if highlight group {name} exists
308hlget([{name} [, {resolve}]]) List get highlight group attributes
309hlset({list}) Number set highlight group attributes
310hostname() String name of the machine Vim is running on
311iconv({expr}, {from}, {to}) String convert encoding of {expr}
Ernie Rael05124252024-07-11 22:10:45 +0200312id({item}) String get unique identity string of item
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000313indent({lnum}) Number indent of line {lnum}
314index({object}, {expr} [, {start} [, {ic}]])
315 Number index in {object} where {expr} appears
Yegappan Lakshmananb2186552022-08-13 13:09:20 +0100316indexof({object}, {expr} [, {opts}]])
317 Number index in {object} where {expr} is true
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000318input({prompt} [, {text} [, {completion}]])
319 String get input from the user
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100320inputdialog({prompt} [, {text} [, {cancelreturn}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000321 String like input() but in a GUI dialog
322inputlist({textlist}) Number let the user pick from a choice list
323inputrestore() Number restore typeahead
324inputsave() Number save and clear typeahead
325inputsecret({prompt} [, {text}]) String like input() but hiding the text
326insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
LemonBoyafe04662023-08-23 21:08:11 +0200327instanceof({object}, {class}) Number |TRUE| if {object} is an instance of {class}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000328interrupt() none interrupt script execution
329invert({expr}) Number bitwise invert
LemonBoydca1d402022-04-28 15:26:33 +0100330isabsolutepath({path}) Number |TRUE| if {path} is an absolute path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000331isdirectory({directory}) Number |TRUE| if {directory} is a directory
332isinf({expr}) Number determine if {expr} is infinity value
333 (positive or negative)
334islocked({expr}) Number |TRUE| if {expr} is locked
335isnan({expr}) Number |TRUE| if {expr} is NaN
336items({dict}) List key-value pairs in {dict}
337job_getchannel({job}) Channel get the channel handle for {job}
338job_info([{job}]) Dict get information about {job}
339job_setoptions({job}, {options}) none set options for {job}
340job_start({command} [, {options}])
341 Job start a job
342job_status({job}) String get the status of {job}
343job_stop({job} [, {how}]) Number stop {job}
344join({list} [, {sep}]) String join {list} items into one String
345js_decode({string}) any decode JS style JSON
346js_encode({expr}) String encode JS style JSON
347json_decode({string}) any decode JSON
348json_encode({expr}) String encode JSON
349keys({dict}) List keys in {dict}
zeertzjqcdc83932022-09-12 13:38:41 +0100350keytrans({string}) String translate internal keycodes to a form
351 that can be used by |:map|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000352len({expr}) Number the length of {expr}
353libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
354libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
355line({expr} [, {winid}]) Number line nr of cursor, last line or mark
356line2byte({lnum}) Number byte count of line {lnum}
357lispindent({lnum}) Number Lisp indent for line {lnum}
358list2blob({list}) Blob turn {list} of numbers into a Blob
359list2str({list} [, {utf8}]) String turn {list} of numbers into a String
360listener_add({callback} [, {buf}])
361 Number add a callback to listen to changes
362listener_flush([{buf}]) none invoke listener callbacks
363listener_remove({id}) none remove a listener callback
364localtime() Number current time
365log({expr}) Float natural logarithm (base e) of {expr}
366log10({expr}) Float logarithm of Float {expr} to base 10
367luaeval({expr} [, {expr}]) any evaluate |Lua| expression
368map({expr1}, {expr2}) List/Dict/Blob/String
369 change each item in {expr1} to {expr2}
370maparg({name} [, {mode} [, {abbr} [, {dict}]]])
371 String or Dict
372 rhs of mapping {name} in mode {mode}
373mapcheck({name} [, {mode} [, {abbr}]])
374 String check for mappings matching {name}
Ernie Rael09661202022-04-25 14:40:44 +0100375maplist([{abbr}]) List list of all mappings, a dict for each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000376mapnew({expr1}, {expr2}) List/Dict/Blob/String
377 like |map()| but creates a new List or
378 Dictionary
379mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
380match({expr}, {pat} [, {start} [, {count}]])
381 Number position where {pat} matches in {expr}
382matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
383 Number highlight {pattern} with {group}
384matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
385 Number highlight positions with {group}
386matcharg({nr}) List arguments of |:match|
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100387matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict})
388 List all the {pat} matches in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000389matchdelete({id} [, {win}]) Number delete match identified by {id}
390matchend({expr}, {pat} [, {start} [, {count}]])
391 Number position where {pat} ends in {expr}
392matchfuzzy({list}, {str} [, {dict}])
393 List fuzzy match {str} in {list}
394matchfuzzypos({list}, {str} [, {dict}])
395 List fuzzy match {str} in {list}
396matchlist({expr}, {pat} [, {start} [, {count}]])
397 List match and submatches of {pat} in {expr}
398matchstr({expr}, {pat} [, {start} [, {count}]])
399 String {count}'th match of {pat} in {expr}
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100400matchstrlist({list}, {pat} [, {dict})
401 List all the {pat} matches in {list}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000402matchstrpos({expr}, {pat} [, {start} [, {count}]])
403 List {count}'th match of {pat} in {expr}
404max({expr}) Number maximum value of items in {expr}
405menu_info({name} [, {mode}]) Dict get menu item information
406min({expr}) Number minimum value of items in {expr}
Bram Moolenaar938ae282023-02-20 20:44:55 +0000407mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000408 Number create directory {name}
Doug Kearns9cd9e752024-04-07 17:42:17 +0200409mode([{expr}]) String current editing mode
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000410mzeval({expr}) any evaluate |MzScheme| expression
411nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
412nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
413or({expr}, {expr}) Number bitwise OR
414pathshorten({expr} [, {len}]) String shorten directory names in a path
415perleval({expr}) any evaluate |Perl| expression
416popup_atcursor({what}, {options}) Number create popup window near the cursor
417popup_beval({what}, {options}) Number create popup window for 'ballooneval'
418popup_clear() none close all popup windows
419popup_close({id} [, {result}]) none close popup window {id}
420popup_create({what}, {options}) Number create a popup window
421popup_dialog({what}, {options}) Number create a popup window used as a dialog
422popup_filter_menu({id}, {key}) Number filter for a menu popup window
423popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
Bram Moolenaarbdc09a12022-10-07 14:31:45 +0100424popup_findecho() Number get window ID of popup for `:echowin`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000425popup_findinfo() Number get window ID of info popup window
426popup_findpreview() Number get window ID of preview popup window
427popup_getoptions({id}) Dict get options of popup window {id}
428popup_getpos({id}) Dict get position of popup window {id}
429popup_hide({id}) none hide popup menu {id}
430popup_list() List get a list of window IDs of all popups
431popup_locate({row}, {col}) Number get window ID of popup at position
432popup_menu({what}, {options}) Number create a popup window used as a menu
433popup_move({id}, {options}) none set position of popup window {id}
434popup_notification({what}, {options})
435 Number create a notification popup window
Christian Brabandtfbc37f12024-06-18 20:50:58 +0200436popup_setbuf({id}, {buf}) Bool set the buffer for the popup window {id}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000437popup_setoptions({id}, {options})
438 none set options for popup window {id}
439popup_settext({id}, {text}) none set the text of popup window {id}
440popup_show({id}) none unhide popup window {id}
441pow({x}, {y}) Float {x} to the power of {y}
442prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
443printf({fmt}, {expr1}...) String format text
444prompt_getprompt({buf}) String get prompt text
445prompt_setcallback({buf}, {expr}) none set prompt callback function
446prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
447prompt_setprompt({buf}, {text}) none set prompt text
448prop_add({lnum}, {col}, {props}) none add one text property
449prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
450 none add multiple text properties
451prop_clear({lnum} [, {lnum-end} [, {props}]])
452 none remove all text properties
453prop_find({props} [, {direction}])
454 Dict search for a text property
455prop_list({lnum} [, {props}]) List text properties in {lnum}
456prop_remove({props} [, {lnum} [, {lnum-end}]])
457 Number remove a text property
458prop_type_add({name}, {props}) none define a new property type
459prop_type_change({name}, {props})
460 none change an existing property type
461prop_type_delete({name} [, {props}])
462 none delete a property type
463prop_type_get({name} [, {props}])
464 Dict get property type values
465prop_type_list([{props}]) List get list of property types
466pum_getpos() Dict position and size of pum if visible
467pumvisible() Number whether popup menu is visible
468py3eval({expr}) any evaluate |python3| expression
469pyeval({expr}) any evaluate |Python| expression
470pyxeval({expr}) any evaluate |python_x| expression
471rand([{expr}]) Number get pseudo-random number
472range({expr} [, {max} [, {stride}]])
473 List items from {expr} to {max}
K.Takata11df3ae2022-10-19 14:02:40 +0100474readblob({fname} [, {offset} [, {size}]])
475 Blob read a |Blob| from {fname}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000476readdir({dir} [, {expr} [, {dict}]])
477 List file names in {dir} selected by {expr}
478readdirex({dir} [, {expr} [, {dict}]])
479 List file info in {dir} selected by {expr}
480readfile({fname} [, {type} [, {max}]])
481 List get list of lines from file {fname}
482reduce({object}, {func} [, {initial}])
483 any reduce {object} using {func}
484reg_executing() String get the executing register name
485reg_recording() String get the recording register name
486reltime([{start} [, {end}]]) List get time value
487reltimefloat({time}) Float turn the time value into a Float
488reltimestr({time}) String turn time value into a String
489remote_expr({server}, {string} [, {idvar} [, {timeout}]])
490 String send expression
491remote_foreground({server}) Number bring Vim server to the foreground
492remote_peek({serverid} [, {retvar}])
493 Number check for reply string
494remote_read({serverid} [, {timeout}])
495 String read reply string
496remote_send({server}, {string} [, {idvar}])
497 String send key sequence
498remote_startserver({name}) none become server {name}
499remove({list}, {idx} [, {end}]) any/List
500 remove items {idx}-{end} from {list}
501remove({blob}, {idx} [, {end}]) Number/Blob
502 remove bytes {idx}-{end} from {blob}
503remove({dict}, {key}) any remove entry {key} from {dict}
504rename({from}, {to}) Number rename (move) file from {from} to {to}
Bakudankun375141e2022-09-09 18:46:47 +0100505repeat({expr}, {count}) List/Blob/String
506 repeat {expr} {count} times
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000507resolve({filename}) String get filename a shortcut points to
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +0100508reverse({obj}) List/Blob/String
509 reverse {obj}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000510round({expr}) Float round off {expr}
511rubyeval({expr}) any evaluate |Ruby| expression
512screenattr({row}, {col}) Number attribute at screen position
513screenchar({row}, {col}) Number character at screen position
514screenchars({row}, {col}) List List of characters at screen position
515screencol() Number current cursor column
516screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
517screenrow() Number current cursor row
518screenstring({row}, {col}) String characters at screen position
519search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
520 Number search for {pattern}
521searchcount([{options}]) Dict get or update search stats
522searchdecl({name} [, {global} [, {thisblock}]])
523 Number search for variable declaration
524searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
525 Number search for other end of start/end pair
526searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
527 List search for other end of start/end pair
528searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
529 List search for {pattern}
530server2client({clientid}, {string})
531 Number send reply string
532serverlist() String get a list of available servers
erraelf0837ba2024-06-24 12:27:01 -0700533setbufline({buf}, {lnum}, {text})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000534 Number set line {lnum} to {text} in buffer
erraelf0837ba2024-06-24 12:27:01 -0700535 {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000536setbufvar({buf}, {varname}, {val})
537 none set {varname} in buffer {buf} to {val}
538setcellwidths({list}) none set character cell width overrides
539setcharpos({expr}, {list}) Number set the {expr} position to {list}
540setcharsearch({dict}) Dict set character search from {dict}
Shougo Matsushita07ea5f12022-08-27 12:22:25 +0100541setcmdline({str} [, {pos}]) Number set command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000542setcmdpos({pos}) Number set cursor position in command-line
543setcursorcharpos({list}) Number move cursor to position in {list}
544setenv({name}, {val}) none set environment variable
545setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
546setline({lnum}, {line}) Number set line {lnum} to {line}
547setloclist({nr}, {list} [, {action}])
548 Number modify location list using {list}
549setloclist({nr}, {list}, {action}, {what})
550 Number modify specific location list props
551setmatches({list} [, {win}]) Number restore a list of matches
552setpos({expr}, {list}) Number set the {expr} position to {list}
553setqflist({list} [, {action}]) Number modify quickfix list using {list}
554setqflist({list}, {action}, {what})
555 Number modify specific quickfix list props
556setreg({n}, {v} [, {opt}]) Number set register to value and type
557settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
558settabwinvar({tabnr}, {winnr}, {varname}, {val})
559 none set {varname} in window {winnr} in tab
560 page {tabnr} to {val}
561settagstack({nr}, {dict} [, {action}])
562 Number modify tag stack using {dict}
563setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
564sha256({string}) String SHA256 checksum of {string}
565shellescape({string} [, {special}])
566 String escape {string} for use as shell
567 command argument
568shiftwidth([{col}]) Number effective value of 'shiftwidth'
569sign_define({name} [, {dict}]) Number define or update a sign
570sign_define({list}) List define or update a list of signs
571sign_getdefined([{name}]) List get a list of defined signs
572sign_getplaced([{buf} [, {dict}]])
573 List get a list of placed signs
574sign_jump({id}, {group}, {buf})
575 Number jump to a sign
576sign_place({id}, {group}, {name}, {buf} [, {dict}])
577 Number place a sign
578sign_placelist({list}) List place a list of signs
579sign_undefine([{name}]) Number undefine a sign
580sign_undefine({list}) List undefine a list of signs
581sign_unplace({group} [, {dict}])
582 Number unplace a sign
583sign_unplacelist({list}) List unplace a list of signs
584simplify({filename}) String simplify filename as much as possible
585sin({expr}) Float sine of {expr}
586sinh({expr}) Float hyperbolic sine of {expr}
587slice({expr}, {start} [, {end}]) String, List or Blob
588 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000589sort({list} [, {how} [, {dict}]])
590 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000591sound_clear() none stop playing all sounds
592sound_playevent({name} [, {callback}])
593 Number play an event sound
594sound_playfile({path} [, {callback}])
595 Number play sound file {path}
596sound_stop({id}) none stop playing sound {id}
597soundfold({word}) String sound-fold {word}
598spellbadword() String badly spelled word at cursor
599spellsuggest({word} [, {max} [, {capital}]])
600 List spelling suggestions
601split({expr} [, {pat} [, {keepempty}]])
602 List make |List| from {pat} separated {expr}
603sqrt({expr}) Float square root of {expr}
604srand([{expr}]) List get seed for |rand()|
605state([{what}]) String current state of Vim
606str2float({expr} [, {quoted}]) Float convert String to Float
607str2list({expr} [, {utf8}]) List convert each character of {expr} to
608 ASCII/UTF-8 value
609str2nr({expr} [, {base} [, {quoted}]])
610 Number convert String to Number
611strcharlen({expr}) Number character length of the String {expr}
612strcharpart({str}, {start} [, {len} [, {skipcc}]])
613 String {len} characters of {str} at
614 character {start}
615strchars({expr} [, {skipcc}]) Number character count of the String {expr}
616strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
617strftime({format} [, {time}]) String format time with a specified format
618strgetchar({str}, {index}) Number get char {index} from {str}
619stridx({haystack}, {needle} [, {start}])
620 Number index of {needle} in {haystack}
621string({expr}) String String representation of {expr} value
622strlen({expr}) Number length of the String {expr}
623strpart({str}, {start} [, {len} [, {chars}]])
624 String {len} bytes/chars of {str} at
625 byte {start}
626strptime({format}, {timestring})
627 Number Convert {timestring} to unix timestamp
628strridx({haystack}, {needle} [, {start}])
629 Number last index of {needle} in {haystack}
630strtrans({expr}) String translate string to make it printable
Christian Brabandt67672ef2023-04-24 21:09:54 +0100631strutf16len({string} [, {countcc}])
632 Number number of UTF-16 code units in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000633strwidth({expr}) Number display cell length of the String {expr}
634submatch({nr} [, {list}]) String or List
635 specific match in ":s" or substitute()
636substitute({expr}, {pat}, {sub}, {flags})
637 String all {pat} in {expr} replaced with {sub}
Bram Moolenaarc216a7a2022-12-05 13:50:55 +0000638swapfilelist() List swap files found in 'directory'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000639swapinfo({fname}) Dict information about swap file {fname}
640swapname({buf}) String swap file of buffer {buf}
641synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
642synIDattr({synID}, {what} [, {mode}])
643 String attribute {what} of syntax ID {synID}
644synIDtrans({synID}) Number translated syntax ID of {synID}
645synconcealed({lnum}, {col}) List info about concealing
646synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
647system({expr} [, {input}]) String output of shell command/filter {expr}
648systemlist({expr} [, {input}]) List output of shell command/filter {expr}
649tabpagebuflist([{arg}]) List list of buffer numbers in tab page
650tabpagenr([{arg}]) Number number of current or last tab page
651tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
652tagfiles() List tags files used
653taglist({expr} [, {filename}]) List list of tags matching {expr}
654tan({expr}) Float tangent of {expr}
655tanh({expr}) Float hyperbolic tangent of {expr}
656tempname() String name for a temporary file
657term_dumpdiff({filename}, {filename} [, {options}])
658 Number display difference between two dumps
659term_dumpload({filename} [, {options}])
660 Number displaying a screen dump
661term_dumpwrite({buf}, {filename} [, {options}])
662 none dump terminal window contents
663term_getaltscreen({buf}) Number get the alternate screen flag
664term_getansicolors({buf}) List get ANSI palette in GUI color mode
665term_getattr({attr}, {what}) Number get the value of attribute {what}
666term_getcursor({buf}) List get the cursor position of a terminal
667term_getjob({buf}) Job get the job associated with a terminal
668term_getline({buf}, {row}) String get a line of text from a terminal
669term_getscrolled({buf}) Number get the scroll count of a terminal
670term_getsize({buf}) List get the size of a terminal
671term_getstatus({buf}) String get the status of a terminal
672term_gettitle({buf}) String get the title of a terminal
673term_gettty({buf}, [{input}]) String get the tty name of a terminal
674term_list() List get the list of terminal buffers
675term_scrape({buf}, {row}) List get row of a terminal screen
676term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
677term_setansicolors({buf}, {colors})
678 none set ANSI palette in GUI color mode
679term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
680term_setkill({buf}, {how}) none set signal to stop job in terminal
681term_setrestore({buf}, {command}) none set command to restore terminal
682term_setsize({buf}, {rows}, {cols})
683 none set the size of a terminal
684term_start({cmd} [, {options}]) Number open a terminal window and run a job
685term_wait({buf} [, {time}]) Number wait for screen to be updated
686terminalprops() Dict properties of the terminal
687test_alloc_fail({id}, {countdown}, {repeat})
688 none make memory allocation fail
689test_autochdir() none enable 'autochdir' during startup
690test_feedinput({string}) none add key sequence to input buffer
691test_garbagecollect_now() none free memory right now for testing
692test_garbagecollect_soon() none free memory soon for testing
693test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000694test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000695test_ignore_error({expr}) none ignore a specific error
Christopher Plewright20b795e2022-12-20 20:01:58 +0000696test_mswin_event({event}, {args})
697 bool generate MS-Windows event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000698test_null_blob() Blob null value for testing
699test_null_channel() Channel null value for testing
700test_null_dict() Dict null value for testing
701test_null_function() Funcref null value for testing
702test_null_job() Job null value for testing
703test_null_list() List null value for testing
704test_null_partial() Funcref null value for testing
705test_null_string() String null value for testing
706test_option_not_set({name}) none reset flag indicating option was set
707test_override({expr}, {val}) none test with Vim internal overrides
708test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000709test_setmouse({row}, {col}) none set the mouse position for testing
710test_settime({expr}) none set current time for testing
Doug Kearns9cd9e752024-04-07 17:42:17 +0200711test_srand_seed([{seed}]) none set seed for testing srand()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000712test_unknown() any unknown value for testing
713test_void() any void value for testing
714timer_info([{id}]) List information about timers
715timer_pause({id}, {pause}) none pause or unpause a timer
716timer_start({time}, {callback} [, {options}])
717 Number create a timer
718timer_stop({timer}) none stop a timer
719timer_stopall() none stop all timers
720tolower({expr}) String the String {expr} switched to lowercase
721toupper({expr}) String the String {expr} switched to uppercase
722tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
723 to chars in {tostr}
724trim({text} [, {mask} [, {dir}]])
725 String trim characters in {mask} from {text}
726trunc({expr}) Float truncate Float {expr}
727type({expr}) Number type of value {expr}
728typename({expr}) String representation of the type of {expr}
729undofile({name}) String undo file name for {name}
Devin J. Pohly5fee1112023-04-23 20:26:59 -0500730undotree([{buf}]) List undo file tree for buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000731uniq({list} [, {func} [, {dict}]])
732 List remove adjacent duplicates from a list
Christian Brabandt67672ef2023-04-24 21:09:54 +0100733utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
734 Number UTF-16 index of byte {idx} in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000735values({dict}) List values in {dict}
zeertzjq825cf812023-08-17 22:55:25 +0200736virtcol({expr} [, {list} [, {winid}])
737 Number or List
LemonBoy0f7a3e12022-05-26 12:10:37 +0100738 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100739virtcol2col({winid}, {lnum}, {col})
740 Number byte index of a character on screen
Doug Kearns9cd9e752024-04-07 17:42:17 +0200741visualmode([{expr}]) String last visual mode used
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000742wildmenumode() Number whether 'wildmenu' mode is active
743win_execute({id}, {command} [, {silent}])
744 String execute {command} in window {id}
745win_findbuf({bufnr}) List find windows containing {bufnr}
746win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
747win_gettype([{nr}]) String type of window {nr}
748win_gotoid({expr}) Number go to window with ID {expr}
749win_id2tabwin({expr}) List get tab and window nr from window ID
750win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000751win_move_separator({nr}) Number move window vertical separator
752win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000753win_screenpos({nr}) List get screen position of window {nr}
754win_splitmove({nr}, {target} [, {options}])
755 Number move window {nr} to split of {target}
756winbufnr({nr}) Number buffer number of window {nr}
757wincol() Number window column of the cursor
758windowsversion() String MS-Windows OS version
759winheight({nr}) Number height of window {nr}
760winlayout([{tabnr}]) List layout of windows in tab {tabnr}
761winline() Number window line of the cursor
762winnr([{expr}]) Number number of current window
763winrestcmd() String returns command to restore window sizes
764winrestview({dict}) none restore view of current window
765winsaveview() Dict save view of current window
766winwidth({nr}) Number width of window {nr}
767wordcount() Dict get byte/char/word statistics
768writefile({object}, {fname} [, {flags}])
769 Number write |Blob| or |List| of lines to file
770xor({expr}, {expr}) Number bitwise XOR
771
772==============================================================================
7732. Details *builtin-function-details*
774
775Not all functions are here, some have been moved to a help file covering the
776specific functionality.
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200777Return type specifies the type for |Vim9-script|, see |vim9-types|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000778
779abs({expr}) *abs()*
780 Return the absolute value of {expr}. When {expr} evaluates to
781 a |Float| abs() returns a |Float|. When {expr} can be
782 converted to a |Number| abs() returns a |Number|. Otherwise
783 abs() gives an error message and returns -1.
784 Examples: >
785 echo abs(1.456)
786< 1.456 >
787 echo abs(-5.456)
788< 5.456 >
789 echo abs(-4)
790< 4
791
792 Can also be used as a |method|: >
793 Compute()->abs()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200794<
795 Return type: |Number| or |Float| depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000796
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000797
798acos({expr}) *acos()*
799 Return the arc cosine of {expr} measured in radians, as a
800 |Float| in the range of [0, pi].
801 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100802 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000803 Examples: >
804 :echo acos(0)
805< 1.570796 >
806 :echo acos(-0.5)
807< 2.094395
808
809 Can also be used as a |method|: >
810 Compute()->acos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200811<
812 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000813
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000814
815add({object}, {expr}) *add()*
816 Append the item {expr} to |List| or |Blob| {object}. Returns
817 the resulting |List| or |Blob|. Examples: >
818 :let alist = add([1, 2, 3], item)
819 :call add(mylist, "woodstock")
820< Note that when {expr} is a |List| it is appended as a single
821 item. Use |extend()| to concatenate |Lists|.
822 When {object} is a |Blob| then {expr} must be a number.
823 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100824 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000825
826 Can also be used as a |method|: >
827 mylist->add(val1)->add(val2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200828<
829 Return type: list<{type}> (depending on the given |List|) or
830 |Blob|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000831
832
833and({expr}, {expr}) *and()*
834 Bitwise AND on the two arguments. The arguments are converted
835 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100836 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000837 Example: >
838 :let flag = and(bits, 0x80)
839< Can also be used as a |method|: >
840 :let flag = bits->and(0x80)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200841<
842 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000843
844
845append({lnum}, {text}) *append()*
846 When {text} is a |List|: Append each item of the |List| as a
847 text line below line {lnum} in the current buffer.
848 Otherwise append {text} as one text line below line {lnum} in
849 the current buffer.
850 Any type of item is accepted and converted to a String.
851 {lnum} can be zero to insert a line before the first one.
852 {lnum} is used like with |getline()|.
853 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000854 0 for success. When {text} is an empty list zero is returned,
855 no matter the value of {lnum}.
856 In |Vim9| script an invalid argument or negative number
857 results in an error. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000858 :let failed = append(line('$'), "# THE END")
859 :let failed = append(0, ["Chapter 1", "the beginning"])
860
861< Can also be used as a |method| after a List, the base is
862 passed as the second argument: >
863 mylist->append(lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200864<
865 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000866
867
868appendbufline({buf}, {lnum}, {text}) *appendbufline()*
869 Like |append()| but append the text in buffer {buf}.
870
871 This function works only for loaded buffers. First call
872 |bufload()| if needed.
873
874 For the use of {buf}, see |bufname()|.
875
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000876 {lnum} is the line number to append below. Note that using
877 |line()| would use the current buffer, not the one appending
878 to. Use "$" to append at the end of the buffer. Other string
879 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000880
881 On success 0 is returned, on failure 1 is returned.
882 In |Vim9| script an error is given for an invalid {lnum}.
883
884 If {buf} is not a valid buffer or {lnum} is not valid, an
885 error message is given. Example: >
886 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000887< However, when {text} is an empty list then no error is given
888 for an invalid {lnum}, since {lnum} isn't actually used.
889
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000890 Can also be used as a |method| after a List, the base is
891 passed as the second argument: >
892 mylist->appendbufline(buf, lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200893<
894 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000895
896
897argc([{winid}]) *argc()*
898 The result is the number of files in the argument list. See
899 |arglist|.
900 If {winid} is not supplied, the argument list of the current
901 window is used.
902 If {winid} is -1, the global argument list is used.
903 Otherwise {winid} specifies the window of which the argument
904 list is used: either the window number or the window ID.
905 Returns -1 if the {winid} argument is invalid.
906
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200907 Return type: |Number|
908
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000909 *argidx()*
910argidx() The result is the current index in the argument list. 0 is
911 the first file. argc() - 1 is the last one. See |arglist|.
912
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200913 Return type: |Number|
914
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000915 *arglistid()*
916arglistid([{winnr} [, {tabnr}]])
917 Return the argument list ID. This is a number which
918 identifies the argument list being used. Zero is used for the
919 global argument list. See |arglist|.
920 Returns -1 if the arguments are invalid.
921
922 Without arguments use the current window.
923 With {winnr} only use this window in the current tab page.
924 With {winnr} and {tabnr} use the window in the specified tab
925 page.
926 {winnr} can be the window number or the |window-ID|.
927
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200928 Return type: |Number|
929
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000930 *argv()*
931argv([{nr} [, {winid}]])
932 The result is the {nr}th file in the argument list. See
933 |arglist|. "argv(0)" is the first one. Example: >
934 :let i = 0
935 :while i < argc()
936 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000937 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000938 : let i = i + 1
939 :endwhile
940< Without the {nr} argument, or when {nr} is -1, a |List| with
941 the whole |arglist| is returned.
942
943 The {winid} argument specifies the window ID, see |argc()|.
944 For the Vim command line arguments see |v:argv|.
945
Bram Moolenaar016188f2022-06-06 20:52:59 +0100946 Returns an empty string if {nr}th argument is not present in
947 the argument list. Returns an empty List if the {winid}
948 argument is invalid.
949
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200950 Return type: |String|
951
952
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000953asin({expr}) *asin()*
954 Return the arc sine of {expr} measured in radians, as a |Float|
955 in the range of [-pi/2, pi/2].
956 {expr} must evaluate to a |Float| or a |Number| in the range
957 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100958 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
959 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000960 Examples: >
961 :echo asin(0.8)
962< 0.927295 >
963 :echo asin(-0.5)
964< -0.523599
965
966 Can also be used as a |method|: >
967 Compute()->asin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200968<
969 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000970
971assert_ functions are documented here: |assert-functions-details|
972
973
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000974atan({expr}) *atan()*
975 Return the principal value of the arc tangent of {expr}, in
976 the range [-pi/2, +pi/2] radians, as a |Float|.
977 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100978 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000979 Examples: >
980 :echo atan(100)
981< 1.560797 >
982 :echo atan(-4.01)
983< -1.326405
984
985 Can also be used as a |method|: >
986 Compute()->atan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200987<
988 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000989
990
991atan2({expr1}, {expr2}) *atan2()*
992 Return the arc tangent of {expr1} / {expr2}, measured in
993 radians, as a |Float| in the range [-pi, pi].
994 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100995 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
996 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000997 Examples: >
998 :echo atan2(-1, 1)
999< -0.785398 >
1000 :echo atan2(1, -1)
1001< 2.356194
1002
1003 Can also be used as a |method|: >
1004 Compute()->atan2(1)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001005<
1006 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001007
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001008
1009autocmd_add({acmds}) *autocmd_add()*
1010 Adds a List of autocmds and autocmd groups.
1011
1012 The {acmds} argument is a List where each item is a Dict with
1013 the following optional items:
1014 bufnr buffer number to add a buffer-local autocmd.
1015 If this item is specified, then the "pattern"
1016 item is ignored.
1017 cmd Ex command to execute for this autocmd event
1018 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +01001019 This can be either a String with a single
1020 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001021 group autocmd group name. Refer to |autocmd-groups|.
1022 If this group doesn't exist then it is
1023 created. If not specified or empty, then the
1024 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001025 nested boolean flag, set to v:true to add a nested
1026 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +01001027 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001028 which executes only once. Refer to
1029 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001030 pattern autocmd pattern string. Refer to
1031 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +01001032 present, then this item is ignored. This can
1033 be a String with a single pattern or a List of
1034 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001035 replace boolean flag, set to v:true to remove all the
1036 commands associated with the specified autocmd
1037 event and group and add the {cmd}. This is
1038 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +01001039 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001040
1041 Returns v:true on success and v:false on failure.
1042 Examples: >
1043 " Create a buffer-local autocmd for buffer 5
1044 let acmd = {}
1045 let acmd.group = 'MyGroup'
1046 let acmd.event = 'BufEnter'
1047 let acmd.bufnr = 5
1048 let acmd.cmd = 'call BufEnterFunc()'
1049 call autocmd_add([acmd])
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00001050<
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001051 Can also be used as a |method|: >
1052 GetAutocmdList()->autocmd_add()
1053<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001054 Return type: |vim9-boolean|
1055
1056
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001057autocmd_delete({acmds}) *autocmd_delete()*
1058 Deletes a List of autocmds and autocmd groups.
1059
1060 The {acmds} argument is a List where each item is a Dict with
1061 the following optional items:
1062 bufnr buffer number to delete a buffer-local autocmd.
1063 If this item is specified, then the "pattern"
1064 item is ignored.
1065 cmd Ex command for this autocmd event
1066 event autocmd event name. Refer to |autocmd-events|.
1067 If '*' then all the autocmd events in this
1068 group are deleted.
1069 group autocmd group name. Refer to |autocmd-groups|.
1070 If not specified or empty, then the default
1071 group is used.
1072 nested set to v:true for a nested autocmd.
1073 Refer to |autocmd-nested|.
1074 once set to v:true for an autocmd which executes
1075 only once. Refer to |autocmd-once|.
1076 pattern autocmd pattern string. Refer to
1077 |autocmd-patterns|. If "bufnr" item is
1078 present, then this item is ignored.
1079
1080 If only {group} is specified in a {acmds} entry and {event},
1081 {pattern} and {cmd} are not specified, then that autocmd group
1082 is deleted.
1083
Bram Moolenaar016188f2022-06-06 20:52:59 +01001084 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001085 Examples: >
1086 " :autocmd! BufLeave *.vim
1087 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1088 call autocmd_delete([acmd]})
1089 " :autocmd! MyGroup1 BufLeave
1090 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1091 call autocmd_delete([acmd])
1092 " :autocmd! MyGroup2 BufEnter *.c
1093 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1094 \ pattern: '*.c'}
1095 " :autocmd! MyGroup2 * *.c
1096 let acmd = #{group: 'MyGroup2', event: '*',
1097 \ pattern: '*.c'}
1098 call autocmd_delete([acmd])
1099 " :autocmd! MyGroup3
1100 let acmd = #{group: 'MyGroup3'}
1101 call autocmd_delete([acmd])
1102<
1103 Can also be used as a |method|: >
1104 GetAutocmdList()->autocmd_delete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001105<
1106 Return type: |vim9-boolean|
1107
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001108
1109autocmd_get([{opts}]) *autocmd_get()*
1110 Returns a |List| of autocmds. If {opts} is not supplied, then
1111 returns the autocmds for all the events in all the groups.
1112
1113 The optional {opts} Dict argument supports the following
1114 items:
1115 group Autocmd group name. If specified, returns only
1116 the autocmds defined in this group. If the
1117 specified group doesn't exist, results in an
1118 error message. If set to an empty string,
1119 then the default autocmd group is used.
1120 event Autocmd event name. If specified, returns only
1121 the autocmds defined for this event. If set
1122 to "*", then returns autocmds for all the
1123 events. If the specified event doesn't exist,
1124 results in an error message.
1125 pattern Autocmd pattern. If specified, returns only
1126 the autocmds defined for this pattern.
1127 A combination of the above three times can be supplied in
1128 {opts}.
1129
1130 Each Dict in the returned List contains the following items:
1131 bufnr For buffer-local autocmds, buffer number where
1132 the autocmd is defined.
1133 cmd Command executed for this autocmd.
1134 event Autocmd event name.
1135 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001136 nested Boolean flag, set to v:true for a nested
1137 autocmd. See |autocmd-nested|.
1138 once Boolean flag, set to v:true, if the autocmd
1139 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001140 pattern Autocmd pattern. For a buffer-local
1141 autocmd, this will be of the form "<buffer=n>".
1142 If there are multiple commands for an autocmd event in a
1143 group, then separate items are returned for each command.
1144
Bram Moolenaar016188f2022-06-06 20:52:59 +01001145 Returns an empty List if an autocmd with the specified group
1146 or event or pattern is not found.
1147
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001148 Examples: >
1149 " :autocmd MyGroup
1150 echo autocmd_get(#{group: 'Mygroup'})
1151 " :autocmd G BufUnload
1152 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1153 " :autocmd G * *.ts
1154 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1155 echo autocmd_get(acmd)
1156 " :autocmd Syntax
1157 echo autocmd_get(#{event: 'Syntax'})
1158 " :autocmd G BufEnter *.ts
1159 let acmd = #{group: 'G', event: 'BufEnter',
1160 \ pattern: '*.ts'}
1161 echo autocmd_get(acmd)
1162<
1163 Can also be used as a |method|: >
1164 Getopts()->autocmd_get()
1165<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001166 Return type: list<dict<any>>
1167
1168
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001169balloon_gettext() *balloon_gettext()*
1170 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001171 not used for the List. Returns an empty string if balloon
1172 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001173
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001174 Return type: |String|
1175
1176
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001177balloon_show({expr}) *balloon_show()*
1178 Show {expr} inside the balloon. For the GUI {expr} is used as
1179 a string. For a terminal {expr} can be a list, which contains
1180 the lines of the balloon. If {expr} is not a list it will be
1181 split with |balloon_split()|.
1182 If {expr} is an empty string any existing balloon is removed.
1183
1184 Example: >
1185 func GetBalloonContent()
1186 " ... initiate getting the content
1187 return ''
1188 endfunc
1189 set balloonexpr=GetBalloonContent()
1190
1191 func BalloonCallback(result)
1192 call balloon_show(a:result)
1193 endfunc
1194< Can also be used as a |method|: >
1195 GetText()->balloon_show()
1196<
1197 The intended use is that fetching the content of the balloon
1198 is initiated from 'balloonexpr'. It will invoke an
1199 asynchronous method, in which a callback invokes
1200 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001201 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001202
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001203 When showing a balloon is not possible then nothing happens,
1204 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001205 {only available when compiled with the |+balloon_eval| or
1206 |+balloon_eval_term| feature}
1207
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001208 Return type: |Number|
1209
1210
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001211balloon_split({msg}) *balloon_split()*
1212 Split String {msg} into lines to be displayed in a balloon.
1213 The splits are made for the current window size and optimize
1214 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001215 Returns a |List| with the split lines. Returns an empty List
1216 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001217 Can also be used as a |method|: >
1218 GetText()->balloon_split()->balloon_show()
1219
1220< {only available when compiled with the |+balloon_eval_term|
1221 feature}
1222
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001223 Return type: list<any> or list<string>
1224
Christ van Willegence0ef912024-06-20 23:41:59 +02001225bindtextdomain({package}, {path}) *bindtextdomain()*
1226 Bind a specific {package} to a {path} so that the
1227 |gettext()| function can be used to get language-specific
1228 translations for a package. {path} is the directory name
h-east52e7cc22024-07-28 17:03:29 +02001229 for the translations. See |package-translation|.
Christ van Willegence0ef912024-06-20 23:41:59 +02001230
Christ van Willegen8252ef12024-07-11 21:36:21 +02001231 Returns v:true on success and v:false on failure (out of
1232 memory).
1233
1234 Return type: |vim9-boolean|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001235
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001236blob2list({blob}) *blob2list()*
1237 Return a List containing the number value of each byte in Blob
1238 {blob}. Examples: >
1239 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1240 blob2list(0z) returns []
1241< Returns an empty List on error. |list2blob()| does the
1242 opposite.
1243
1244 Can also be used as a |method|: >
1245 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001246<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001247 Return type: list<any> or list<number>
1248
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001249 *browse()*
1250browse({save}, {title}, {initdir}, {default})
1251 Put up a file requester. This only works when "has("browse")"
1252 returns |TRUE| (only in some GUI versions).
1253 The input fields are:
1254 {save} when |TRUE|, select file to write
1255 {title} title for the requester
1256 {initdir} directory to start browsing in
1257 {default} default file name
1258 An empty string is returned when the "Cancel" button is hit,
1259 something went wrong, or browsing is not possible.
1260
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001261 Return type: |String|
1262
1263
1264browsedir({title}, {initdir}) *browsedir()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001265 Put up a directory requester. This only works when
1266 "has("browse")" returns |TRUE| (only in some GUI versions).
1267 On systems where a directory browser is not supported a file
1268 browser is used. In that case: select a file in the directory
1269 to be used.
1270 The input fields are:
1271 {title} title for the requester
1272 {initdir} directory to start browsing in
1273 When the "Cancel" button is hit, something went wrong, or
1274 browsing is not possible, an empty string is returned.
1275
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001276 Return type: |String|
1277
1278
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001279bufadd({name}) *bufadd()*
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001280 Add a buffer to the buffer list with name {name} (must be a
1281 String).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001282 If a buffer for file {name} already exists, return that buffer
1283 number. Otherwise return the buffer number of the newly
1284 created buffer. When {name} is an empty string then a new
1285 buffer is always created.
1286 The buffer will not have 'buflisted' set and not be loaded
1287 yet. To add some text to the buffer use this: >
1288 let bufnr = bufadd('someName')
1289 call bufload(bufnr)
1290 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001291< Returns 0 on error.
1292 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001293 let bufnr = 'somename'->bufadd()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001294<
1295 Return type: |Number|
1296
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001297
1298bufexists({buf}) *bufexists()*
1299 The result is a Number, which is |TRUE| if a buffer called
1300 {buf} exists.
1301 If the {buf} argument is a number, buffer numbers are used.
1302 Number zero is the alternate buffer for the current window.
1303
1304 If the {buf} argument is a string it must match a buffer name
1305 exactly. The name can be:
1306 - Relative to the current directory.
1307 - A full path.
1308 - The name of a buffer with 'buftype' set to "nofile".
1309 - A URL name.
1310 Unlisted buffers will be found.
1311 Note that help files are listed by their short name in the
1312 output of |:buffers|, but bufexists() requires using their
1313 long name to be able to find them.
1314 bufexists() may report a buffer exists, but to use the name
1315 with a |:buffer| command you may need to use |expand()|. Esp
1316 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1317 Use "bufexists(0)" to test for the existence of an alternate
1318 file name.
1319
1320 Can also be used as a |method|: >
1321 let exists = 'somename'->bufexists()
1322<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001323 Return type: |Number|
1324
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001325 Obsolete name: buffer_exists(). *buffer_exists()*
1326
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001327
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001328buflisted({buf}) *buflisted()*
1329 The result is a Number, which is |TRUE| if a buffer called
1330 {buf} exists and is listed (has the 'buflisted' option set).
1331 The {buf} argument is used like with |bufexists()|.
1332
1333 Can also be used as a |method|: >
1334 let listed = 'somename'->buflisted()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001335<
1336 Return type: |Number|
1337
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001338
1339bufload({buf}) *bufload()*
1340 Ensure the buffer {buf} is loaded. When the buffer name
1341 refers to an existing file then the file is read. Otherwise
1342 the buffer will be empty. If the buffer was already loaded
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001343 then there is no change. If the buffer is not related to a
Daniel Steinbergc2bd2052023-08-09 12:10:59 -04001344 file then no file is read (e.g., when 'buftype' is "nofile").
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001345 If there is an existing swap file for the file of the buffer,
1346 there will be no dialog, the buffer will be loaded anyway.
1347 The {buf} argument is used like with |bufexists()|.
1348
1349 Can also be used as a |method|: >
1350 eval 'somename'->bufload()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001351<
1352 Return type: |Number|
1353
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001354
1355bufloaded({buf}) *bufloaded()*
1356 The result is a Number, which is |TRUE| if a buffer called
1357 {buf} exists and is loaded (shown in a window or hidden).
1358 The {buf} argument is used like with |bufexists()|.
1359
1360 Can also be used as a |method|: >
1361 let loaded = 'somename'->bufloaded()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001362<
1363 Return type: |Number|
1364
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001365
1366bufname([{buf}]) *bufname()*
1367 The result is the name of a buffer. Mostly as it is displayed
1368 by the `:ls` command, but not using special names such as
1369 "[No Name]".
1370 If {buf} is omitted the current buffer is used.
1371 If {buf} is a Number, that buffer number's name is given.
1372 Number zero is the alternate buffer for the current window.
1373 If {buf} is a String, it is used as a |file-pattern| to match
1374 with the buffer names. This is always done like 'magic' is
1375 set and 'cpoptions' is empty. When there is more than one
1376 match an empty string is returned.
1377 "" or "%" can be used for the current buffer, "#" for the
1378 alternate buffer.
1379 A full match is preferred, otherwise a match at the start, end
1380 or middle of the buffer name is accepted. If you only want a
1381 full match then put "^" at the start and "$" at the end of the
1382 pattern.
1383 Listed buffers are found first. If there is a single match
1384 with a listed buffer, that one is returned. Next unlisted
1385 buffers are searched for.
1386 If the {buf} is a String, but you want to use it as a buffer
1387 number, force it to be a Number by adding zero to it: >
1388 :echo bufname("3" + 0)
1389< Can also be used as a |method|: >
1390 echo bufnr->bufname()
1391
1392< If the buffer doesn't exist, or doesn't have a name, an empty
1393 string is returned. >
1394 bufname("#") alternate buffer name
1395 bufname(3) name of buffer 3
1396 bufname("%") name of current buffer
1397 bufname("file2") name of buffer where "file2" matches.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001398<
1399 Return type: |String|
1400 *buffer_name()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001401 Obsolete name: buffer_name().
1402
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001403
1404bufnr([{buf} [, {create}]]) *bufnr()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001405 The result is the number of a buffer, as it is displayed by
1406 the `:ls` command. For the use of {buf}, see |bufname()|
1407 above.
1408
1409 If the buffer doesn't exist, -1 is returned. Or, if the
1410 {create} argument is present and TRUE, a new, unlisted,
1411 buffer is created and its number is returned. Example: >
1412 let newbuf = bufnr('Scratch001', 1)
1413< Using an empty name uses the current buffer. To create a new
1414 buffer with an empty name use |bufadd()|.
1415
1416 bufnr("$") is the last buffer: >
1417 :let last_buffer = bufnr("$")
1418< The result is a Number, which is the highest buffer number
1419 of existing buffers. Note that not all buffers with a smaller
1420 number necessarily exist, because ":bwipeout" may have removed
1421 them. Use bufexists() to test for the existence of a buffer.
1422
1423 Can also be used as a |method|: >
1424 echo bufref->bufnr()
1425<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001426 Return type: |Number|
1427
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001428 Obsolete name: buffer_number(). *buffer_number()*
1429 *last_buffer_nr()*
1430 Obsolete name for bufnr("$"): last_buffer_nr().
1431
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001432
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001433bufwinid({buf}) *bufwinid()*
1434 The result is a Number, which is the |window-ID| of the first
1435 window associated with buffer {buf}. For the use of {buf},
1436 see |bufname()| above. If buffer {buf} doesn't exist or
1437 there is no such window, -1 is returned. Example: >
1438
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001439 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001440<
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001441 Only deals with the current tab page. See |win_findbuf()| for
1442 finding more.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001443
1444 Can also be used as a |method|: >
1445 FindBuffer()->bufwinid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001446<
1447 Return type: |Number|
1448
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001449
1450bufwinnr({buf}) *bufwinnr()*
1451 Like |bufwinid()| but return the window number instead of the
1452 |window-ID|.
1453 If buffer {buf} doesn't exist or there is no such window, -1
1454 is returned. Example: >
1455
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001456 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001457
1458< The number can be used with |CTRL-W_w| and ":wincmd w"
1459 |:wincmd|.
1460
1461 Can also be used as a |method|: >
1462 FindBuffer()->bufwinnr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001463<
1464 Return type: |Number|
1465
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001466
1467byte2line({byte}) *byte2line()*
1468 Return the line number that contains the character at byte
1469 count {byte} in the current buffer. This includes the
1470 end-of-line character, depending on the 'fileformat' option
1471 for the current buffer. The first character has byte count
1472 one.
1473 Also see |line2byte()|, |go| and |:goto|.
1474
Bram Moolenaar016188f2022-06-06 20:52:59 +01001475 Returns -1 if the {byte} value is invalid.
1476
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001477 Can also be used as a |method|: >
1478 GetOffset()->byte2line()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001479<
1480 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001481
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001482 {not available when compiled without the |+byte_offset|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001483 feature}
1484
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001485
Christian Brabandt67672ef2023-04-24 21:09:54 +01001486byteidx({expr}, {nr} [, {utf16}]) *byteidx()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001487 Return byte index of the {nr}'th character in the String
1488 {expr}. Use zero for the first character, it then returns
1489 zero.
1490 If there are no multibyte characters the returned value is
1491 equal to {nr}.
1492 Composing characters are not counted separately, their byte
1493 length is added to the preceding base character. See
1494 |byteidxcomp()| below for counting composing characters
1495 separately.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001496 When {utf16} is present and TRUE, {nr} is used as the UTF-16
1497 index in the String {expr} instead of as the character index.
1498 The UTF-16 index is the index in the string when it is encoded
1499 with 16-bit words. If the specified UTF-16 index is in the
1500 middle of a character (e.g. in a 4-byte character), then the
1501 byte index of the first byte in the character is returned.
1502 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001503 Example : >
1504 echo matchstr(str, ".", byteidx(str, 3))
1505< will display the fourth character. Another way to do the
1506 same: >
1507 let s = strpart(str, byteidx(str, 3))
1508 echo strpart(s, 0, byteidx(s, 1))
1509< Also see |strgetchar()| and |strcharpart()|.
1510
1511 If there are less than {nr} characters -1 is returned.
1512 If there are exactly {nr} characters the length of the string
1513 in bytes is returned.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001514 See |charidx()| and |utf16idx()| for getting the character and
1515 UTF-16 index respectively from the byte index.
1516 Examples: >
1517 echo byteidx('a😊😊', 2) returns 5
1518 echo byteidx('a😊😊', 2, 1) returns 1
1519 echo byteidx('a😊😊', 3, 1) returns 5
1520<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001521 Can also be used as a |method|: >
1522 GetName()->byteidx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001523<
1524 Return type: |Number|
1525
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001526
Christian Brabandt67672ef2023-04-24 21:09:54 +01001527byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001528 Like byteidx(), except that a composing character is counted
1529 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001530 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001531 echo byteidx(s, 1)
1532 echo byteidxcomp(s, 1)
1533 echo byteidxcomp(s, 2)
1534< The first and third echo result in 3 ('e' plus composing
1535 character is 3 bytes), the second echo results in 1 ('e' is
1536 one byte).
1537 Only works differently from byteidx() when 'encoding' is set
1538 to a Unicode encoding.
1539
1540 Can also be used as a |method|: >
1541 GetName()->byteidxcomp(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001542<
1543 Return type: |Number|
1544
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001545
1546call({func}, {arglist} [, {dict}]) *call()* *E699*
1547 Call function {func} with the items in |List| {arglist} as
1548 arguments.
1549 {func} can either be a |Funcref| or the name of a function.
1550 a:firstline and a:lastline are set to the cursor line.
1551 Returns the return value of the called function.
1552 {dict} is for functions with the "dict" attribute. It will be
1553 used to set the local variable "self". |Dictionary-function|
1554
1555 Can also be used as a |method|: >
1556 GetFunc()->call([arg, arg], dict)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001557<
1558 Return type: any, depending on {func}
1559
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001560
1561ceil({expr}) *ceil()*
1562 Return the smallest integral value greater than or equal to
1563 {expr} as a |Float| (round up).
1564 {expr} must evaluate to a |Float| or a |Number|.
1565 Examples: >
1566 echo ceil(1.456)
1567< 2.0 >
1568 echo ceil(-5.456)
1569< -5.0 >
1570 echo ceil(4.0)
1571< 4.0
1572
Bram Moolenaar016188f2022-06-06 20:52:59 +01001573 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1574
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001575 Can also be used as a |method|: >
1576 Compute()->ceil()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001577<
1578 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001579
1580
1581ch_ functions are documented here: |channel-functions-details|
1582
1583
1584changenr() *changenr()*
1585 Return the number of the most recent change. This is the same
1586 number as what is displayed with |:undolist| and can be used
1587 with the |:undo| command.
1588 When a change was made it is the number of that change. After
1589 redo it is the number of the redone change. After undo it is
1590 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001591 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001592
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001593 Return type: |Number|
1594
1595
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001596char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001597 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001598 Examples: >
1599 char2nr(" ") returns 32
1600 char2nr("ABC") returns 65
1601< When {utf8} is omitted or zero, the current 'encoding' is used.
1602 Example for "utf-8": >
1603 char2nr("á") returns 225
1604 char2nr("á"[0]) returns 195
1605< When {utf8} is TRUE, always treat as UTF-8 characters.
1606 A combining character is a separate character.
1607 |nr2char()| does the opposite.
1608 To turn a string into a list of character numbers: >
1609 let str = "ABC"
1610 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1611< Result: [65, 66, 67]
1612
Bram Moolenaar016188f2022-06-06 20:52:59 +01001613 Returns 0 if {string} is not a |String|.
1614
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001615 Can also be used as a |method|: >
1616 GetChar()->char2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001617<
1618 Return type: |Number|
1619
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001620
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001621charclass({string}) *charclass()*
1622 Return the character class of the first character in {string}.
1623 The character class is one of:
1624 0 blank
1625 1 punctuation
1626 2 word character
1627 3 emoji
1628 other specific Unicode class
1629 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001630 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001631
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001632 Return type: |Number|
1633
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001634
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001635charcol({expr} [, {winid}]) *charcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001636 Same as |col()| but returns the character index of the column
1637 position given with {expr} instead of the byte position.
1638
1639 Example:
1640 With the cursor on '세' in line 5 with text "여보세요": >
1641 charcol('.') returns 3
1642 col('.') returns 7
1643
1644< Can also be used as a |method|: >
1645 GetPos()->col()
1646<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001647 Return type: |Number|
1648
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001649 *charidx()*
Christian Brabandt67672ef2023-04-24 21:09:54 +01001650charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001651 Return the character index of the byte at {idx} in {string}.
1652 The index of the first character is zero.
1653 If there are no multibyte characters the returned value is
1654 equal to {idx}.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001655
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001656 When {countcc} is omitted or |FALSE|, then composing characters
Christian Brabandt67672ef2023-04-24 21:09:54 +01001657 are not counted separately, their byte length is added to the
1658 preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001659 When {countcc} is |TRUE|, then composing characters are
1660 counted as separate characters.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001661
1662 When {utf16} is present and TRUE, {idx} is used as the UTF-16
1663 index in the String {expr} instead of as the byte index.
1664
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +01001665 Returns -1 if the arguments are invalid or if there are less
1666 than {idx} bytes. If there are exactly {idx} bytes the length
1667 of the string in characters is returned.
1668
1669 An error is given and -1 is returned if the first argument is
1670 not a string, the second argument is not a number or when the
1671 third argument is present and is not zero or one.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001672
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001673 See |byteidx()| and |byteidxcomp()| for getting the byte index
Christian Brabandt67672ef2023-04-24 21:09:54 +01001674 from the character index and |utf16idx()| for getting the
1675 UTF-16 index from the character index.
1676 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001677 Examples: >
1678 echo charidx('áb́ć', 3) returns 1
1679 echo charidx('áb́ć', 6, 1) returns 4
1680 echo charidx('áb́ć', 16) returns -1
Christian Brabandt67672ef2023-04-24 21:09:54 +01001681 echo charidx('a😊😊', 4, 0, 1) returns 2
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001682<
1683 Can also be used as a |method|: >
1684 GetName()->charidx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001685<
1686 Return type: |Number|
1687
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001688
1689chdir({dir}) *chdir()*
1690 Change the current working directory to {dir}. The scope of
1691 the directory change depends on the directory of the current
1692 window:
1693 - If the current window has a window-local directory
1694 (|:lcd|), then changes the window local directory.
1695 - Otherwise, if the current tabpage has a local
1696 directory (|:tcd|) then changes the tabpage local
1697 directory.
1698 - Otherwise, changes the global directory.
1699 {dir} must be a String.
1700 If successful, returns the previous working directory. Pass
1701 this to another chdir() to restore the directory.
1702 On failure, returns an empty string.
1703
1704 Example: >
1705 let save_dir = chdir(newdir)
1706 if save_dir != ""
1707 " ... do some work
1708 call chdir(save_dir)
1709 endif
1710
1711< Can also be used as a |method|: >
1712 GetDir()->chdir()
1713<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001714 Return type: |String|
1715
1716
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001717cindent({lnum}) *cindent()*
1718 Get the amount of indent for line {lnum} according the C
1719 indenting rules, as with 'cindent'.
1720 The indent is counted in spaces, the value of 'tabstop' is
1721 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001722 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001723 See |C-indenting|.
1724
1725 Can also be used as a |method|: >
1726 GetLnum()->cindent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001727<
1728 Return type: |Number|
1729
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001730
1731clearmatches([{win}]) *clearmatches()*
1732 Clears all matches previously defined for the current window
1733 by |matchadd()| and the |:match| commands.
1734 If {win} is specified, use the window with this number or
1735 window ID instead of the current window.
1736
1737 Can also be used as a |method|: >
1738 GetWin()->clearmatches()
1739<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001740 Return type: |Number|
1741
1742
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001743col({expr} [, {winid}]) *col()*
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001744 The result is a Number, which is the byte index of the column
zeertzjq02f3eba2024-06-12 20:45:24 +02001745 position given with {expr}.
1746 For accepted positions see |getpos()|.
zeertzjqd353d272024-06-13 23:00:25 +08001747 When {expr} is "$", it means the end of the cursor line, so
1748 the result is the number of bytes in the cursor line plus one.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001749 Additionally {expr} can be [lnum, col]: a |List| with the line
1750 and column number. Most useful when the column is "$", to get
1751 the last column of a specific line. When "lnum" or "col" is
1752 out of range then col() returns zero.
zeertzjq02f3eba2024-06-12 20:45:24 +02001753
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001754 With the optional {winid} argument the values are obtained for
1755 that window instead of the current window.
zeertzjq02f3eba2024-06-12 20:45:24 +02001756
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001757 To get the line number use |line()|. To get both use
1758 |getpos()|.
1759 For the screen column position use |virtcol()|. For the
1760 character position use |charcol()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02001761
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001762 Note that only marks in the current file can be used.
zeertzjq02f3eba2024-06-12 20:45:24 +02001763
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001764 Examples: >
1765 col(".") column of cursor
1766 col("$") length of cursor line plus one
1767 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001768 col("'" .. markname) column of mark markname
zeertzjq02f3eba2024-06-12 20:45:24 +02001769<
1770 The first column is 1. Returns 0 if {expr} is invalid or when
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001771 the window with ID {winid} is not found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001772 For an uppercase mark the column may actually be in another
1773 buffer.
1774 For the cursor position, when 'virtualedit' is active, the
1775 column is one higher if the cursor is after the end of the
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01001776 line. Also, when using a <Cmd> mapping the cursor isn't
1777 moved, this can be used to obtain the column in Insert mode: >
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001778 :imap <F2> <Cmd>echowin col(".")<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001779
1780< Can also be used as a |method|: >
1781 GetPos()->col()
1782<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001783 Return type: |Number|
1784
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001785
1786complete({startcol}, {matches}) *complete()* *E785*
1787 Set the matches for Insert mode completion.
1788 Can only be used in Insert mode. You need to use a mapping
1789 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1790 or with an expression mapping.
1791 {startcol} is the byte offset in the line where the completed
1792 text start. The text up to the cursor is the original text
1793 that will be replaced by the matches. Use col('.') for an
1794 empty string. "col('.') - 1" will replace one character by a
1795 match.
1796 {matches} must be a |List|. Each |List| item is one match.
1797 See |complete-items| for the kind of items that are possible.
1798 "longest" in 'completeopt' is ignored.
1799 Note that the after calling this function you need to avoid
1800 inserting anything that would cause completion to stop.
1801 The match can be selected with CTRL-N and CTRL-P as usual with
1802 Insert mode completion. The popup menu will appear if
1803 specified, see |ins-completion-menu|.
1804 Example: >
1805 inoremap <F5> <C-R>=ListMonths()<CR>
1806
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001807 func ListMonths()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001808 call complete(col('.'), ['January', 'February', 'March',
1809 \ 'April', 'May', 'June', 'July', 'August', 'September',
1810 \ 'October', 'November', 'December'])
1811 return ''
1812 endfunc
1813< This isn't very useful, but it shows how it works. Note that
1814 an empty string is returned to avoid a zero being inserted.
1815
1816 Can also be used as a |method|, the base is passed as the
1817 second argument: >
1818 GetMatches()->complete(col('.'))
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001819<
1820 Return type: |Number|
1821
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001822
1823complete_add({expr}) *complete_add()*
1824 Add {expr} to the list of matches. Only to be used by the
1825 function specified with the 'completefunc' option.
1826 Returns 0 for failure (empty string or out of memory),
1827 1 when the match was added, 2 when the match was already in
1828 the list.
1829 See |complete-functions| for an explanation of {expr}. It is
1830 the same as one item in the list that 'omnifunc' would return.
1831
1832 Can also be used as a |method|: >
1833 GetMoreMatches()->complete_add()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001834<
1835 Return type: |Number|
1836
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001837
1838complete_check() *complete_check()*
1839 Check for a key typed while looking for completion matches.
1840 This is to be used when looking for matches takes some time.
1841 Returns |TRUE| when searching for matches is to be aborted,
1842 zero otherwise.
1843 Only to be used by the function specified with the
1844 'completefunc' option.
1845
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001846 Return type: |Number|
1847
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001848
1849complete_info([{what}]) *complete_info()*
1850 Returns a |Dictionary| with information about Insert mode
1851 completion. See |ins-completion|.
1852 The items are:
1853 mode Current completion mode name string.
1854 See |complete_info_mode| for the values.
1855 pum_visible |TRUE| if popup menu is visible.
1856 See |pumvisible()|.
1857 items List of completion matches. Each item is a
1858 dictionary containing the entries "word",
1859 "abbr", "menu", "kind", "info" and "user_data".
1860 See |complete-items|.
1861 selected Selected item index. First index is zero.
1862 Index is -1 if no item is selected (showing
1863 typed text only, or the last completion after
1864 no item is selected when using the <Up> or
1865 <Down> keys)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01001866 inserted Inserted string. [NOT IMPLEMENTED YET]
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001867
1868 *complete_info_mode*
1869 mode values are:
1870 "" Not in completion mode
1871 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1872 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1873 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1874 |i_CTRL-X_CTRL-Y|
1875 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1876 "files" File names |i_CTRL-X_CTRL-F|
1877 "tags" Tags |i_CTRL-X_CTRL-]|
1878 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1879 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1880 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1881 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1882 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1883 "function" User defined completion |i_CTRL-X_CTRL-U|
1884 "omni" Omni completion |i_CTRL-X_CTRL-O|
1885 "spell" Spelling suggestions |i_CTRL-X_s|
1886 "eval" |complete()| completion
1887 "unknown" Other internal modes
1888
1889 If the optional {what} list argument is supplied, then only
1890 the items listed in {what} are returned. Unsupported items in
1891 {what} are silently ignored.
1892
1893 To get the position and size of the popup menu, see
1894 |pum_getpos()|. It's also available in |v:event| during the
1895 |CompleteChanged| event.
1896
Bram Moolenaar016188f2022-06-06 20:52:59 +01001897 Returns an empty |Dictionary| on error.
1898
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001899 Examples: >
1900 " Get all items
1901 call complete_info()
1902 " Get only 'mode'
1903 call complete_info(['mode'])
1904 " Get only 'mode' and 'pum_visible'
1905 call complete_info(['mode', 'pum_visible'])
1906
1907< Can also be used as a |method|: >
1908 GetItems()->complete_info()
1909<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001910 Return type: dict<any>
1911
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001912 *confirm()*
1913confirm({msg} [, {choices} [, {default} [, {type}]]])
1914 confirm() offers the user a dialog, from which a choice can be
1915 made. It returns the number of the choice. For the first
1916 choice this is 1.
1917 Note: confirm() is only supported when compiled with dialog
glepnirdf461152024-04-04 22:23:29 +02001918 support, see |+dialog_con| |+dialog_con_gui| and |+dialog_gui|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001919
1920 {msg} is displayed in a |dialog| with {choices} as the
1921 alternatives. When {choices} is missing or empty, "&OK" is
1922 used (and translated).
1923 {msg} is a String, use '\n' to include a newline. Only on
1924 some systems the string is wrapped when it doesn't fit.
1925
1926 {choices} is a String, with the individual choices separated
1927 by '\n', e.g. >
1928 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1929< The letter after the '&' is the shortcut key for that choice.
1930 Thus you can type 'c' to select "Cancel". The shortcut does
1931 not need to be the first letter: >
1932 confirm("file has been modified", "&Save\nSave &All")
1933< For the console, the first letter of each choice is used as
1934 the default shortcut key. Case is ignored.
1935
1936 The optional {default} argument is the number of the choice
1937 that is made if the user hits <CR>. Use 1 to make the first
1938 choice the default one. Use 0 to not set a default. If
1939 {default} is omitted, 1 is used.
1940
1941 The optional {type} String argument gives the type of dialog.
1942 This is only used for the icon of the GTK, Mac, Motif and
1943 Win32 GUI. It can be one of these values: "Error",
1944 "Question", "Info", "Warning" or "Generic". Only the first
1945 character is relevant. When {type} is omitted, "Generic" is
1946 used.
1947
1948 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1949 or another valid interrupt key, confirm() returns 0.
1950
1951 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01001952 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001953 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01001954 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001955 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001956 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001957 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001958 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001959 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01001960 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001961< In a GUI dialog, buttons are used. The layout of the buttons
1962 depends on the 'v' flag in 'guioptions'. If it is included,
1963 the buttons are always put vertically. Otherwise, confirm()
1964 tries to put the buttons in one horizontal line. If they
1965 don't fit, a vertical layout is used anyway. For some systems
1966 the horizontal layout is always used.
1967
1968 Can also be used as a |method|in: >
1969 BuildMessage()->confirm("&Yes\n&No")
1970<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001971 Return type: |Number|
1972
1973
1974copy({expr}) *copy()*
1975 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001976 different from using {expr} directly.
1977 When {expr} is a |List| a shallow copy is created. This means
1978 that the original |List| can be changed without changing the
1979 copy, and vice versa. But the items are identical, thus
1980 changing an item changes the contents of both |Lists|.
1981 A |Dictionary| is copied in a similar way as a |List|.
1982 Also see |deepcopy()|.
1983 Can also be used as a |method|: >
1984 mylist->copy()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001985<
1986 Return type: any, depending on {expr}
1987
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001988
1989cos({expr}) *cos()*
1990 Return the cosine of {expr}, measured in radians, as a |Float|.
1991 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001992 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001993 Examples: >
1994 :echo cos(100)
1995< 0.862319 >
1996 :echo cos(-4.01)
1997< -0.646043
1998
1999 Can also be used as a |method|: >
2000 Compute()->cos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002001<
2002 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002003
2004
2005cosh({expr}) *cosh()*
2006 Return the hyperbolic cosine of {expr} as a |Float| in the range
2007 [1, inf].
2008 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002009 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002010 Examples: >
2011 :echo cosh(0.5)
2012< 1.127626 >
2013 :echo cosh(-0.5)
2014< -1.127626
2015
2016 Can also be used as a |method|: >
2017 Compute()->cosh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002018<
2019 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002020
2021
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07002022count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002023 Return the number of times an item with value {expr} appears
2024 in |String|, |List| or |Dictionary| {comp}.
2025
2026 If {start} is given then start with the item with this index.
2027 {start} can only be used with a |List|.
2028
2029 When {ic} is given and it's |TRUE| then case is ignored.
2030
2031 When {comp} is a string then the number of not overlapping
2032 occurrences of {expr} is returned. Zero is returned when
2033 {expr} is an empty string.
2034
2035 Can also be used as a |method|: >
2036 mylist->count(val)
2037<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002038 Return type: |Number|
2039
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002040 *cscope_connection()*
2041cscope_connection([{num} , {dbpath} [, {prepend}]])
2042 Checks for the existence of a |cscope| connection. If no
2043 parameters are specified, then the function returns:
2044 0, if cscope was not available (not compiled in), or
2045 if there are no cscope connections;
2046 1, if there is at least one cscope connection.
2047
2048 If parameters are specified, then the value of {num}
2049 determines how existence of a cscope connection is checked:
2050
2051 {num} Description of existence check
2052 ----- ------------------------------
2053 0 Same as no parameters (e.g., "cscope_connection()").
2054 1 Ignore {prepend}, and use partial string matches for
2055 {dbpath}.
2056 2 Ignore {prepend}, and use exact string matches for
2057 {dbpath}.
2058 3 Use {prepend}, use partial string matches for both
2059 {dbpath} and {prepend}.
2060 4 Use {prepend}, use exact string matches for both
2061 {dbpath} and {prepend}.
2062
2063 Note: All string comparisons are case sensitive!
2064
2065 Examples. Suppose we had the following (from ":cs show"): >
2066
2067 # pid database name prepend path
2068 0 27664 cscope.out /usr/local
2069<
2070 Invocation Return Val ~
2071 ---------- ---------- >
2072 cscope_connection() 1
2073 cscope_connection(1, "out") 1
2074 cscope_connection(2, "out") 0
2075 cscope_connection(3, "out") 0
2076 cscope_connection(3, "out", "local") 1
2077 cscope_connection(4, "out") 0
2078 cscope_connection(4, "out", "local") 0
2079 cscope_connection(4, "cscope.out", "/usr/local") 1
2080<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002081 Return type: |Number|
2082
2083
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002084cursor({lnum}, {col} [, {off}]) *cursor()*
2085cursor({list})
2086 Positions the cursor at the column (byte count) {col} in the
2087 line {lnum}. The first column is one.
2088
2089 When there is one argument {list} this is used as a |List|
2090 with two, three or four item:
2091 [{lnum}, {col}]
2092 [{lnum}, {col}, {off}]
2093 [{lnum}, {col}, {off}, {curswant}]
2094 This is like the return value of |getpos()| or |getcurpos()|,
2095 but without the first item.
2096
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01002097 To position the cursor using {col} as the character count, use
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002098 |setcursorcharpos()|.
2099
2100 Does not change the jumplist.
Bram Moolenaar7c6cd442022-10-11 21:54:04 +01002101 {lnum} is used like with |getline()|, except that if {lnum} is
2102 zero, the cursor will stay in the current line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002103 If {lnum} is greater than the number of lines in the buffer,
2104 the cursor will be positioned at the last line in the buffer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002105 If {col} is greater than the number of bytes in the line,
2106 the cursor will be positioned at the last character in the
2107 line.
2108 If {col} is zero, the cursor will stay in the current column.
2109 If {curswant} is given it is used to set the preferred column
2110 for vertical movement. Otherwise {col} is used.
2111
2112 When 'virtualedit' is used {off} specifies the offset in
2113 screen columns from the start of the character. E.g., a
2114 position within a <Tab> or after the last character.
2115 Returns 0 when the position could be set, -1 otherwise.
2116
2117 Can also be used as a |method|: >
2118 GetCursorPos()->cursor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002119<
2120 Return type: |Number|
2121
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002122
2123debugbreak({pid}) *debugbreak()*
2124 Specifically used to interrupt a program being debugged. It
2125 will cause process {pid} to get a SIGTRAP. Behavior for other
2126 processes is undefined. See |terminal-debugger|.
2127 {only available on MS-Windows}
2128
Bram Moolenaar016188f2022-06-06 20:52:59 +01002129 Returns |TRUE| if successfully interrupted the program.
2130 Otherwise returns |FALSE|.
2131
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002132 Can also be used as a |method|: >
2133 GetPid()->debugbreak()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002134<
2135 Return type: |Number|
2136
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002137
2138deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
2139 Make a copy of {expr}. For Numbers and Strings this isn't
2140 different from using {expr} directly.
2141 When {expr} is a |List| a full copy is created. This means
2142 that the original |List| can be changed without changing the
2143 copy, and vice versa. When an item is a |List| or
2144 |Dictionary|, a copy for it is made, recursively. Thus
2145 changing an item in the copy does not change the contents of
2146 the original |List|.
2147 A |Dictionary| is copied in a similar way as a |List|.
2148
2149 When {noref} is omitted or zero a contained |List| or
2150 |Dictionary| is only copied once. All references point to
2151 this single copy. With {noref} set to 1 every occurrence of a
2152 |List| or |Dictionary| results in a new copy. This also means
2153 that a cyclic reference causes deepcopy() to fail.
2154 *E724*
2155 Nesting is possible up to 100 levels. When there is an item
2156 that refers back to a higher level making a deep copy with
2157 {noref} set to 1 will fail.
2158 Also see |copy()|.
2159
2160 Can also be used as a |method|: >
2161 GetObject()->deepcopy()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002162<
2163 Return type: any, depending on {expr}
2164
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002165
2166delete({fname} [, {flags}]) *delete()*
2167 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002168 name {fname}.
2169
2170 This also works when {fname} is a symbolic link. The symbolic
2171 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002172
2173 When {flags} is "d": Deletes the directory by the name
2174 {fname}. This fails when directory {fname} is not empty.
2175
2176 When {flags} is "rf": Deletes the directory by the name
2177 {fname} and everything in it, recursively. BE CAREFUL!
2178 Note: on MS-Windows it is not possible to delete a directory
2179 that is being used.
2180
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002181 The result is a Number, which is 0/false if the delete
2182 operation was successful and -1/true when the deletion failed
2183 or partly failed.
2184
2185 Use |remove()| to delete an item from a |List|.
2186 To delete a line from the buffer use |:delete| or
2187 |deletebufline()|.
2188
2189 Can also be used as a |method|: >
2190 GetName()->delete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002191<
2192 Return type: |Number|
2193
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002194
2195deletebufline({buf}, {first} [, {last}]) *deletebufline()*
2196 Delete lines {first} to {last} (inclusive) from buffer {buf}.
2197 If {last} is omitted then delete line {first} only.
2198 On success 0 is returned, on failure 1 is returned.
2199
2200 This function works only for loaded buffers. First call
2201 |bufload()| if needed.
2202
2203 For the use of {buf}, see |bufname()| above.
2204
2205 {first} and {last} are used like with |getline()|. Note that
2206 when using |line()| this refers to the current buffer. Use "$"
2207 to refer to the last line in buffer {buf}.
2208
2209 Can also be used as a |method|: >
2210 GetBuffer()->deletebufline(1)
2211<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002212 Return type: |Number|
2213
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002214 *did_filetype()*
2215did_filetype() Returns |TRUE| when autocommands are being executed and the
2216 FileType event has been triggered at least once. Can be used
2217 to avoid triggering the FileType event again in the scripts
2218 that detect the file type. |FileType|
2219 Returns |FALSE| when `:setf FALLBACK` was used.
2220 When editing another file, the counter is reset, thus this
2221 really checks if the FileType event has been triggered for the
2222 current buffer. This allows an autocommand that starts
2223 editing another buffer to set 'filetype' and load a syntax
2224 file.
2225
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002226 Return type: |Number|
2227
2228
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002229diff({fromlist}, {tolist} [, {options}]) *diff()*
2230 Returns a String or a List containing the diff between the
2231 strings in {fromlist} and {tolist}. Uses the Vim internal
2232 diff library to compute the diff.
2233
2234 *E106*
2235 The optional "output" item in {options} specifies the returned
2236 diff format. The following values are supported:
2237 indices Return a List of the starting and ending
2238 indices and a count of the strings in each
2239 diff hunk.
2240 unified Return the unified diff output as a String.
2241 This is the default.
2242
2243 If the "output" item in {options} is "indices", then a List is
2244 returned. Each List item contains a Dict with the following
2245 items for each diff hunk:
2246 from_idx start index in {fromlist} for this diff hunk.
2247 from_count number of strings in {fromlist} that are
2248 added/removed/modified in this diff hunk.
2249 to_idx start index in {tolist} for this diff hunk.
2250 to_count number of strings in {tolist} that are
2251 added/removed/modified in this diff hunk.
2252
2253 The {options} Dict argument also specifies diff options
2254 (similar to 'diffopt') and supports the following items:
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002255 algorithm Dict specifying the diff algorithm to
2256 use. Supported boolean items are
2257 "myers", "minimal", "patience" and
2258 "histogram".
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002259 context diff context length. Default is 0.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002260 iblank ignore changes where lines are all
2261 blank.
2262 icase ignore changes in case of text.
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002263 indent-heuristic use the indent heuristic for the
2264 internal diff library.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002265 iwhite ignore changes in amount of white
2266 space.
2267 iwhiteall ignore all white space changes.
2268 iwhiteeol ignore white space changes at end of
2269 line.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002270 For more information about these options, refer to 'diffopt'.
2271
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002272 To compute the unified diff, all the items in {fromlist} are
2273 concatenated into a string using a newline separator and the
2274 same for {tolist}. The unified diff output uses line numbers.
2275
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002276 Returns an empty List or String if {fromlist} and {tolist} are
2277 identical.
2278
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002279 Examples: >
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002280 :echo diff(['abc'], ['xxx'])
2281 @@ -1 +1 @@
2282 -abc
2283 +xxx
2284
2285 :echo diff(['abc'], ['xxx'], {'output': 'indices'})
2286 [{'from_idx': 0, 'from_count': 1, 'to_idx': 0, 'to_count': 1}]
2287 :echo diff(readfile('oldfile'), readfile('newfile'))
2288 :echo diff(getbufline(5, 1, '$'), getbufline(6, 1, '$'))
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002289<
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002290 For more examples, refer to |diff-func-examples|
2291
2292 Can also be used as a |method|: >
2293 GetFromList->diff(to_list)
2294<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002295 Return type: |String| or list<dict<number>> or list<any>
2296 depending on {options}
2297
2298
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002299diff_filler({lnum}) *diff_filler()*
2300 Returns the number of filler lines above line {lnum}.
2301 These are the lines that were inserted at this point in
2302 another diff'ed window. These filler lines are shown in the
2303 display but don't exist in the buffer.
2304 {lnum} is used like with |getline()|. Thus "." is the current
2305 line, "'m" mark m, etc.
2306 Returns 0 if the current window is not in diff mode.
2307
2308 Can also be used as a |method|: >
2309 GetLnum()->diff_filler()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002310<
2311 Return type: |Number|
2312
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002313
2314diff_hlID({lnum}, {col}) *diff_hlID()*
2315 Returns the highlight ID for diff mode at line {lnum} column
2316 {col} (byte index). When the current line does not have a
2317 diff change zero is returned.
2318 {lnum} is used like with |getline()|. Thus "." is the current
2319 line, "'m" mark m, etc.
2320 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2321 line.
2322 The highlight ID can be used with |synIDattr()| to obtain
2323 syntax information about the highlighting.
2324
2325 Can also be used as a |method|: >
2326 GetLnum()->diff_hlID(col)
2327<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002328 Return type: |Number|
2329
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002330
2331digraph_get({chars}) *digraph_get()* *E1214*
2332 Return the digraph of {chars}. This should be a string with
2333 exactly two characters. If {chars} are not just two
2334 characters, or the digraph of {chars} does not exist, an error
2335 is given and an empty string is returned.
2336
2337 The character will be converted from Unicode to 'encoding'
2338 when needed. This does require the conversion to be
2339 available, it might fail.
2340
2341 Also see |digraph_getlist()|.
2342
2343 Examples: >
2344 " Get a built-in digraph
2345 :echo digraph_get('00') " Returns '∞'
2346
2347 " Get a user-defined digraph
2348 :call digraph_set('aa', 'あ')
2349 :echo digraph_get('aa') " Returns 'あ'
2350<
2351 Can also be used as a |method|: >
2352 GetChars()->digraph_get()
2353<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002354 Return type: |String|
2355
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002356 This function works only when compiled with the |+digraphs|
2357 feature. If this feature is disabled, this function will
2358 display an error message.
2359
2360
2361digraph_getlist([{listall}]) *digraph_getlist()*
2362 Return a list of digraphs. If the {listall} argument is given
2363 and it is TRUE, return all digraphs, including the default
2364 digraphs. Otherwise, return only user-defined digraphs.
2365
2366 The characters will be converted from Unicode to 'encoding'
2367 when needed. This does require the conservation to be
2368 available, it might fail.
2369
2370 Also see |digraph_get()|.
2371
2372 Examples: >
2373 " Get user-defined digraphs
2374 :echo digraph_getlist()
2375
2376 " Get all the digraphs, including default digraphs
2377 :echo digraph_getlist(1)
2378<
2379 Can also be used as a |method|: >
2380 GetNumber()->digraph_getlist()
2381<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002382 Return type: list<list<string>>
2383
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002384 This function works only when compiled with the |+digraphs|
2385 feature. If this feature is disabled, this function will
2386 display an error message.
2387
2388
Bram Moolenaara2baa732022-02-04 16:09:54 +00002389digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002390 Add digraph {chars} to the list. {chars} must be a string
2391 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002392 encoded character. *E1215*
2393 Be careful, composing characters are NOT ignored. This
2394 function is similar to |:digraphs| command, but useful to add
2395 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002396
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002397 The function returns v:true if |digraph| is registered. If
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002398 this fails an error message is given and v:false is returned.
2399
2400 If you want to define multiple digraphs at once, you can use
2401 |digraph_setlist()|.
2402
2403 Example: >
2404 call digraph_set(' ', 'あ')
2405<
2406 Can be used as a |method|: >
2407 GetString()->digraph_set('あ')
2408<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002409 Return type: |vim9-boolean|
2410
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002411 This function works only when compiled with the |+digraphs|
2412 feature. If this feature is disabled, this function will
2413 display an error message.
2414
2415
2416digraph_setlist({digraphlist}) *digraph_setlist()*
2417 Similar to |digraph_set()| but this function can add multiple
2418 digraphs at once. {digraphlist} is a list composed of lists,
2419 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002420 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002421 Example: >
2422 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2423<
2424 It is similar to the following: >
2425 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2426 call digraph_set(chars, digraph)
2427 endfor
2428< Except that the function returns after the first error,
2429 following digraphs will not be added.
2430
2431 Can be used as a |method|: >
2432 GetList()->digraph_setlist()
2433<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002434 Return type: |vim9-boolean|
2435
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002436 This function works only when compiled with the |+digraphs|
2437 feature. If this feature is disabled, this function will
2438 display an error message.
2439
2440
2441echoraw({string}) *echoraw()*
2442 Output {string} as-is, including unprintable characters.
2443 This can be used to output a terminal code. For example, to
2444 disable modifyOtherKeys: >
2445 call echoraw(&t_TE)
2446< and to enable it again: >
2447 call echoraw(&t_TI)
2448< Use with care, you can mess up the terminal this way.
2449
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002450 Return type: |Number|
2451
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002452
2453empty({expr}) *empty()*
2454 Return the Number 1 if {expr} is empty, zero otherwise.
2455 - A |List| or |Dictionary| is empty when it does not have any
2456 items.
2457 - A |String| is empty when its length is zero.
2458 - A |Number| and |Float| are empty when their value is zero.
2459 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2460 - A |Job| is empty when it failed to start.
2461 - A |Channel| is empty when it is closed.
2462 - A |Blob| is empty when its length is zero.
mityu7f0bba22024-03-29 10:14:41 +01002463 - An |Object| is empty, when the empty() method in the object
2464 (if present) returns true. |object-empty()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002465
2466 For a long |List| this is much faster than comparing the
2467 length with zero.
2468
2469 Can also be used as a |method|: >
2470 mylist->empty()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002471<
2472 Return type: |Number|
2473
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002474
2475environ() *environ()*
2476 Return all of environment variables as dictionary. You can
2477 check if an environment variable exists like this: >
2478 :echo has_key(environ(), 'HOME')
2479< Note that the variable name may be CamelCase; to ignore case
2480 use this: >
2481 :echo index(keys(environ()), 'HOME', 0, 1) != -1
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002482<
2483 Return type: dict<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002484
Bram Moolenaar416bd912023-07-07 23:19:18 +01002485
2486err_teapot([{expr}]) *err_teapot()*
2487 Produce an error with number 418, needed for implementation of
Christian Brabandtee17b6f2023-09-09 11:23:50 +02002488 RFC 2324.
Bram Moolenaar416bd912023-07-07 23:19:18 +01002489 If {expr} is present and it is TRUE error 503 is given,
2490 indicating that coffee is temporarily not available.
2491 If {expr} is present it must be a String.
2492
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002493 Return type: |Number|
2494
Bram Moolenaar416bd912023-07-07 23:19:18 +01002495
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002496escape({string}, {chars}) *escape()*
2497 Escape the characters in {chars} that occur in {string} with a
2498 backslash. Example: >
2499 :echo escape('c:\program files\vim', ' \')
2500< results in: >
2501 c:\\program\ files\\vim
2502< Also see |shellescape()| and |fnameescape()|.
2503
2504 Can also be used as a |method|: >
2505 GetText()->escape(' \')
2506<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002507 Return type: |String|
2508
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002509 *eval()*
2510eval({string}) Evaluate {string} and return the result. Especially useful to
2511 turn the result of |string()| back into the original value.
2512 This works for Numbers, Floats, Strings, Blobs and composites
2513 of them. Also works for |Funcref|s that refer to existing
Aliaksei Budavei95740222024-04-04 23:05:33 +03002514 functions. In |Vim9| script, it can be used to obtain |enum|
2515 values from their fully qualified names.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002516
2517 Can also be used as a |method|: >
2518 argv->join()->eval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002519<
2520 Return type: any, depending on {string}
2521
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002522
2523eventhandler() *eventhandler()*
2524 Returns 1 when inside an event handler. That is that Vim got
2525 interrupted while waiting for the user to type a character,
2526 e.g., when dropping a file on Vim. This means interactive
2527 commands cannot be used. Otherwise zero is returned.
2528
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002529 Return type: |Number|
2530
2531
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002532executable({expr}) *executable()*
2533 This function checks if an executable with the name {expr}
2534 exists. {expr} must be the name of the program without any
2535 arguments.
zeertzjq0cc5dce2024-08-08 21:12:15 +02002536
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002537 executable() uses the value of $PATH and/or the normal
zeertzjq0cc5dce2024-08-08 21:12:15 +02002538 searchpath for programs.
2539 *PATHEXT*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002540 On MS-Windows the ".exe", ".bat", etc. can optionally be
2541 included. Then the extensions in $PATHEXT are tried. Thus if
2542 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2543 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2544 by itself can be used in $PATHEXT to try using the name
2545 without an extension. When 'shell' looks like a Unix shell,
2546 then the name is also tried without adding an extension.
2547 On MS-Windows it only checks if the file exists and is not a
2548 directory, not if it's really executable.
zeertzjq0cc5dce2024-08-08 21:12:15 +02002549 On MS-Windows an executable in the same directory as the Vim
2550 executable is always found. Since this directory is added to
2551 $PATH it should also work to execute it |win32-PATH|.
2552 *NoDefaultCurrentDirectoryInExePath*
2553 On MS-Windows an executable in Vim's current working directory
2554 is also normally found, but this can be disabled by setting
2555 the $NoDefaultCurrentDirectoryInExePath environment variable.
2556
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002557 The result is a Number:
2558 1 exists
2559 0 does not exist
2560 -1 not implemented on this system
2561 |exepath()| can be used to get the full path of an executable.
2562
2563 Can also be used as a |method|: >
2564 GetCommand()->executable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002565<
2566 Return type: |Number|
2567
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002568
2569execute({command} [, {silent}]) *execute()*
2570 Execute an Ex command or commands and return the output as a
2571 string.
2572 {command} can be a string or a List. In case of a List the
2573 lines are executed one by one.
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002574 This is more or less equivalent to: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002575 redir => var
2576 {command}
2577 redir END
Bram Moolenaar71badf92023-04-22 22:40:14 +01002578< Except that line continuation in {command} is not recognized.
2579
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002580 The optional {silent} argument can have these values:
2581 "" no `:silent` used
2582 "silent" `:silent` used
2583 "silent!" `:silent!` used
2584 The default is "silent". Note that with "silent!", unlike
2585 `:redir`, error messages are dropped. When using an external
2586 command the screen may be messed up, use `system()` instead.
2587 *E930*
2588 It is not possible to use `:redir` anywhere in {command}.
2589
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002590 To get a list of lines use `split()` on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002591 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002592
2593< To execute a command in another window than the current one
2594 use `win_execute()`.
2595
2596 When used recursively the output of the recursive call is not
2597 included in the output of the higher level call.
2598
2599 Can also be used as a |method|: >
2600 GetCommand()->execute()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002601<
Marius Gedminasc98bfb92024-06-19 19:59:23 +02002602 Return type: |String|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002603
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002604
2605exepath({expr}) *exepath()*
2606 If {expr} is an executable and is either an absolute path, a
2607 relative path or found in $PATH, return the full path.
2608 Note that the current directory is used when {expr} starts
2609 with "./", which may be a problem for Vim: >
2610 echo exepath(v:progpath)
2611< If {expr} cannot be found in $PATH or is not executable then
2612 an empty string is returned.
2613
2614 Can also be used as a |method|: >
2615 GetCommand()->exepath()
2616<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002617 Return type: |String|
2618
2619
2620exists({expr}) *exists()*
2621 The result is a Number, which is |TRUE| if {expr} is defined,
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002622 zero otherwise.
2623
2624 Note: In a compiled |:def| function the evaluation is done at
2625 runtime. Use `exists_compiled()` to evaluate the expression
2626 at compile time.
2627
2628 For checking for a supported feature use |has()|.
2629 For checking if a file exists use |filereadable()|.
2630
2631 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002632 varname internal variable (see
2633 dict.key |internal-variables|). Also works
2634 list[i] for |curly-braces-names|, |Dictionary|
Yegappan Lakshmanana2ebb6e2024-02-25 08:40:10 +01002635 import.Func entries, |List| items, class and
2636 class.Func object methods, imported items, etc.
2637 object.Func Does not work for local variables in a
2638 class.varname compiled `:def` function.
2639 object.varname Also works for a function in |Vim9|
Bram Moolenaar944697a2022-02-20 19:48:20 +00002640 script, since it can be used as a
2641 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002642 Beware that evaluating an index may
2643 cause an error message for an invalid
2644 expression. E.g.: >
2645 :let l = [1, 2, 3]
2646 :echo exists("l[5]")
2647< 0 >
2648 :echo exists("l[xx]")
2649< E121: Undefined variable: xx
2650 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002651 &option-name Vim option (only checks if it exists,
2652 not if it really works)
2653 +option-name Vim option that works.
2654 $ENVNAME environment variable (could also be
2655 done by comparing with an empty
2656 string)
2657 *funcname built-in function (see |functions|)
2658 or user defined function (see
2659 |user-functions|) that is implemented.
2660 Also works for a variable that is a
2661 Funcref.
2662 ?funcname built-in function that could be
2663 implemented; to be used to check if
2664 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002665 :cmdname Ex command: built-in command, user
2666 command or command modifier |:command|.
2667 Returns:
2668 1 for match with start of a command
2669 2 full match with a command
2670 3 matches several user commands
2671 To check for a supported command
2672 always check the return value to be 2.
2673 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002674 :3match The |:3match| command (but you
2675 probably should not use it, it is
2676 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002677 #event autocommand defined for this event
2678 #event#pattern autocommand defined for this event and
2679 pattern (the pattern is taken
2680 literally and compared to the
2681 autocommand patterns character by
2682 character)
2683 #group autocommand group exists
2684 #group#event autocommand defined for this group and
2685 event.
2686 #group#event#pattern
2687 autocommand defined for this group,
2688 event and pattern.
2689 ##event autocommand for this event is
2690 supported.
2691
2692 Examples: >
2693 exists("&shortname")
2694 exists("$HOSTNAME")
2695 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002696 exists("*s:MyFunc") " only for legacy script
2697 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002698 exists("bufcount")
2699 exists(":Make")
2700 exists("#CursorHold")
2701 exists("#BufReadPre#*.gz")
2702 exists("#filetypeindent")
2703 exists("#filetypeindent#FileType")
2704 exists("#filetypeindent#FileType#*")
2705 exists("##ColorScheme")
2706< There must be no space between the symbol (&/$/*/#) and the
2707 name.
2708 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002709 a few cases this is ignored. That may become stricter in the
2710 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002711 Working example: >
2712 exists(":make")
2713< NOT working example: >
2714 exists(":make install")
2715
2716< Note that the argument must be a string, not the name of the
2717 variable itself. For example: >
2718 exists(bufcount)
2719< This doesn't check for existence of the "bufcount" variable,
2720 but gets the value of "bufcount", and checks if that exists.
2721
2722 Can also be used as a |method|: >
2723 Varname()->exists()
2724<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002725 Return type: |String|
2726
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002727
2728exists_compiled({expr}) *exists_compiled()*
2729 Like `exists()` but evaluated at compile time. This is useful
2730 to skip a block where a function is used that would otherwise
2731 give an error: >
2732 if exists_compiled('*ThatFunction')
2733 ThatFunction('works')
2734 endif
2735< If `exists()` were used then a compilation error would be
2736 given if ThatFunction() is not defined.
2737
2738 {expr} must be a literal string. *E1232*
2739 Can only be used in a |:def| function. *E1233*
2740 This does not work to check for arguments or local variables.
2741
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002742 Return type: |String|
2743
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002744
2745exp({expr}) *exp()*
2746 Return the exponential of {expr} as a |Float| in the range
2747 [0, inf].
2748 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002749 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002750 Examples: >
2751 :echo exp(2)
2752< 7.389056 >
2753 :echo exp(-1)
2754< 0.367879
2755
2756 Can also be used as a |method|: >
2757 Compute()->exp()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002758<
2759 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002760
2761
2762expand({string} [, {nosuf} [, {list}]]) *expand()*
2763 Expand wildcards and the following special keywords in
2764 {string}. 'wildignorecase' applies.
2765
2766 If {list} is given and it is |TRUE|, a List will be returned.
2767 Otherwise the result is a String and when there are several
2768 matches, they are separated by <NL> characters. [Note: in
2769 version 5.0 a space was used, which caused problems when a
2770 file name contains a space]
2771
2772 If the expansion fails, the result is an empty string. A name
2773 for a non-existing file is not included, unless {string} does
2774 not start with '%', '#' or '<', see below.
2775
Christian Brabandtec9c3262024-02-21 20:40:05 +01002776 For a |:terminal| window '%' expands to a '!' followed by
h-east53753f62024-05-05 18:42:31 +02002777 the command or shell that is run. |terminal-bufname|
Christian Brabandtec9c3262024-02-21 20:40:05 +01002778
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002779 When {string} starts with '%', '#' or '<', the expansion is
2780 done like for the |cmdline-special| variables with their
2781 associated modifiers. Here is a short overview:
2782
2783 % current file name
2784 # alternate file name
2785 #n alternate file name n
2786 <cfile> file name under the cursor
2787 <afile> autocmd file name
2788 <abuf> autocmd buffer number (as a String!)
2789 <amatch> autocmd matched name
2790 <cexpr> C expression under the cursor
2791 <sfile> sourced script file or function name
2792 <slnum> sourced script line number or function
2793 line number
2794 <sflnum> script file line number, also when in
2795 a function
2796 <SID> "<SNR>123_" where "123" is the
2797 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002798 <script> sourced script file, or script file
2799 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002800 <stack> call stack
2801 <cword> word under the cursor
2802 <cWORD> WORD under the cursor
2803 <client> the {clientid} of the last received
2804 message |server2client()|
2805 Modifiers:
2806 :p expand to full path
2807 :h head (last path component removed)
2808 :t tail (last path component only)
2809 :r root (one extension removed)
2810 :e extension only
2811
2812 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002813 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002814< Note that when expanding a string that starts with '%', '#' or
2815 '<', any following text is ignored. This does NOT work: >
2816 :let doesntwork = expand("%:h.bak")
2817< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002818 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002819< Also note that expanding "<cfile>" and others only returns the
2820 referenced file name without further expansion. If "<cfile>"
2821 is "~/.cshrc", you need to do another expand() to have the
2822 "~/" expanded into the path of the home directory: >
2823 :echo expand(expand("<cfile>"))
2824<
2825 There cannot be white space between the variables and the
2826 following modifier. The |fnamemodify()| function can be used
2827 to modify normal file names.
2828
2829 When using '%' or '#', and the current or alternate file name
2830 is not defined, an empty string is used. Using "%:p" in a
2831 buffer with no name, results in the current directory, with a
2832 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01002833 When 'verbose' is set then expanding '%', '#' and <> items
2834 will result in an error message if the argument cannot be
2835 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002836
2837 When {string} does not start with '%', '#' or '<', it is
2838 expanded like a file name is expanded on the command line.
2839 'suffixes' and 'wildignore' are used, unless the optional
2840 {nosuf} argument is given and it is |TRUE|.
2841 Names for non-existing files are included. The "**" item can
2842 be used to search in a directory tree. For example, to find
2843 all "README" files in the current directory and below: >
2844 :echo expand("**/README")
2845<
2846 expand() can also be used to expand variables and environment
2847 variables that are only known in a shell. But this can be
2848 slow, because a shell may be used to do the expansion. See
2849 |expr-env-expand|.
2850 The expanded variable is still handled like a list of file
2851 names. When an environment variable cannot be expanded, it is
2852 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2853 "$FOOBAR".
2854
2855 See |glob()| for finding existing files. See |system()| for
2856 getting the raw output of an external command.
2857
2858 Can also be used as a |method|: >
2859 Getpattern()->expand()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002860<
2861 Return type: |String| or list<string> depending on {list}
2862
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002863
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002864expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002865 Expand special items in String {string} like what is done for
2866 an Ex command such as `:edit`. This expands special keywords,
2867 like with |expand()|, and environment variables, anywhere in
2868 {string}. "~user" and "~/path" are only expanded at the
2869 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002870
2871 The following items are supported in the {options} Dict
2872 argument:
2873 errmsg If set to TRUE, error messages are displayed
2874 if an error is encountered during expansion.
2875 By default, error messages are not displayed.
2876
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002877 Returns the expanded string. If an error is encountered
2878 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002879
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002880 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002881 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002882 make /path/runtime/doc/builtin.o
2883 :echo expandcmd('make %<.o', {'errmsg': v:true})
2884<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002885 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002886 GetCommand()->expandcmd()
2887<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002888 Return type: |String| or list<string> depending on {list}
2889
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002890extend({expr1}, {expr2} [, {expr3}]) *extend()*
2891 {expr1} and {expr2} must be both |Lists| or both
2892 |Dictionaries|.
2893
2894 If they are |Lists|: Append {expr2} to {expr1}.
2895 If {expr3} is given insert the items of {expr2} before the
2896 item with index {expr3} in {expr1}. When {expr3} is zero
2897 insert before the first item. When {expr3} is equal to
2898 len({expr1}) then {expr2} is appended.
2899 Examples: >
2900 :echo sort(extend(mylist, [7, 5]))
2901 :call extend(mylist, [2, 3], 1)
2902< When {expr1} is the same List as {expr2} then the number of
2903 items copied is equal to the original length of the List.
2904 E.g., when {expr3} is 1 you get N new copies of the first item
2905 (where N is the original length of the List).
2906 Use |add()| to concatenate one item to a list. To concatenate
2907 two lists into a new list use the + operator: >
2908 :let newlist = [1, 2, 3] + [4, 5]
2909<
2910 If they are |Dictionaries|:
2911 Add all entries from {expr2} to {expr1}.
2912 If a key exists in both {expr1} and {expr2} then {expr3} is
2913 used to decide what to do:
2914 {expr3} = "keep": keep the value of {expr1}
2915 {expr3} = "force": use the value of {expr2}
2916 {expr3} = "error": give an error message *E737*
2917 When {expr3} is omitted then "force" is assumed.
2918
2919 {expr1} is changed when {expr2} is not empty. If necessary
2920 make a copy of {expr1} first.
2921 {expr2} remains unchanged.
2922 When {expr1} is locked and {expr2} is not empty the operation
2923 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002924 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002925
2926 Can also be used as a |method|: >
2927 mylist->extend(otherlist)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002928<
2929 Return type: list<{type}> or dict<{type}> depending on {expr1}
2930 and {expr2}, in case of error: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002931
2932
2933extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2934 Like |extend()| but instead of adding items to {expr1} a new
2935 List or Dictionary is created and returned. {expr1} remains
Bram Moolenaardd60c362023-02-27 15:49:53 +00002936 unchanged.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002937
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002938 Return type: list<{type}> or dict<{type}> depending on {expr1}
2939 and {expr2}, in case of error: |Number|
2940
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002941
2942feedkeys({string} [, {mode}]) *feedkeys()*
2943 Characters in {string} are queued for processing as if they
2944 come from a mapping or were typed by the user.
2945
2946 By default the string is added to the end of the typeahead
2947 buffer, thus if a mapping is still being executed the
2948 characters come after them. Use the 'i' flag to insert before
2949 other characters, they will be executed next, before any
2950 characters from a mapping.
2951
2952 The function does not wait for processing of keys contained in
2953 {string}.
2954
2955 To include special keys into {string}, use double-quotes
2956 and "\..." notation |expr-quote|. For example,
2957 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2958 feedkeys('\<CR>') pushes 5 characters.
2959 A special code that might be useful is <Ignore>, it exits the
2960 wait for a character without doing anything. *<Ignore>*
2961
2962 {mode} is a String, which can contain these character flags:
2963 'm' Remap keys. This is default. If {mode} is absent,
2964 keys are remapped.
2965 'n' Do not remap keys.
2966 't' Handle keys as if typed; otherwise they are handled as
2967 if coming from a mapping. This matters for undo,
2968 opening folds, etc.
2969 'L' Lowlevel input. Only works for Unix or when using the
2970 GUI. Keys are used as if they were coming from the
2971 terminal. Other flags are not used. *E980*
2972 When a CTRL-C interrupts and 't' is included it sets
2973 the internal "got_int" flag.
2974 'i' Insert the string instead of appending (see above).
2975 'x' Execute commands until typeahead is empty. This is
2976 similar to using ":normal!". You can call feedkeys()
2977 several times without 'x' and then one time with 'x'
2978 (possibly with an empty {string}) to execute all the
2979 typeahead. Note that when Vim ends in Insert mode it
2980 will behave as if <Esc> is typed, to avoid getting
2981 stuck, waiting for a character to be typed before the
2982 script continues.
2983 Note that if you manage to call feedkeys() while
2984 executing commands, thus calling it recursively, then
2985 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00002986 'c' Remove any script context when executing, so that
2987 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01002988 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01002989 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002990 '!' When used with 'x' will not end Insert mode. Can be
2991 used in a test when a timer is set to exit Insert mode
2992 a little later. Useful for testing CursorHoldI.
2993
2994 Return value is always 0.
2995
2996 Can also be used as a |method|: >
2997 GetInput()->feedkeys()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002998<
2999 Return type: |String| or list<string> depending on {list}
3000
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003001
Shougo Matsushita60c87432024-06-03 22:59:27 +02003002filecopy({from}, {to}) *filecopy()*
3003 Copy the file pointed to by the name {from} to {to}. The
3004 result is a Number, which is |TRUE| if the file was copied
3005 successfully, and |FALSE| when it failed.
3006 If a file with name {to} already exists, it will fail.
3007 Note that it does not handle directories (yet).
3008
3009 This function is not available in the |sandbox|.
3010
3011 Can also be used as a |method|: >
3012 GetOldName()->filecopy(newname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003013<
3014 Return type: |Number|
3015
Shougo Matsushita60c87432024-06-03 22:59:27 +02003016
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003017filereadable({file}) *filereadable()*
3018 The result is a Number, which is |TRUE| when a file with the
3019 name {file} exists, and can be read. If {file} doesn't exist,
3020 or is a directory, the result is |FALSE|. {file} is any
3021 expression, which is used as a String.
3022 If you don't care about the file being readable you can use
3023 |glob()|.
3024 {file} is used as-is, you may want to expand wildcards first: >
3025 echo filereadable('~/.vimrc')
3026 0
3027 echo filereadable(expand('~/.vimrc'))
3028 1
3029
3030< Can also be used as a |method|: >
3031 GetName()->filereadable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003032<
3033 Return type: |Number|
3034
3035 *file_readable()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003036 Obsolete name: file_readable().
3037
3038
3039filewritable({file}) *filewritable()*
3040 The result is a Number, which is 1 when a file with the
3041 name {file} exists, and can be written. If {file} doesn't
3042 exist, or is not writable, the result is 0. If {file} is a
3043 directory, and we can write to it, the result is 2.
3044
3045 Can also be used as a |method|: >
3046 GetName()->filewritable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003047<
3048 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003049
3050
3051filter({expr1}, {expr2}) *filter()*
3052 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
3053 For each item in {expr1} evaluate {expr2} and when the result
3054 is zero or false remove the item from the |List| or
3055 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003056 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003057
3058 {expr2} must be a |string| or |Funcref|.
3059
3060 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3061 of the current item. For a |Dictionary| |v:key| has the key
3062 of the current item and for a |List| |v:key| has the index of
3063 the current item. For a |Blob| |v:key| has the index of the
3064 current byte. For a |String| |v:key| has the index of the
3065 current character.
3066 Examples: >
3067 call filter(mylist, 'v:val !~ "OLD"')
3068< Removes the items where "OLD" appears. >
3069 call filter(mydict, 'v:key >= 8')
3070< Removes the items with a key below 8. >
3071 call filter(var, 0)
3072< Removes all the items, thus clears the |List| or |Dictionary|.
3073
3074 Note that {expr2} is the result of expression and is then
3075 used as an expression again. Often it is good to use a
3076 |literal-string| to avoid having to double backslashes.
3077
3078 If {expr2} is a |Funcref| it must take two arguments:
3079 1. the key or the index of the current item.
3080 2. the value of the current item.
3081 The function must return |TRUE| if the item should be kept.
3082 Example that keeps the odd items of a list: >
3083 func Odd(idx, val)
3084 return a:idx % 2 == 1
3085 endfunc
3086 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003087< It is shorter when using a |lambda|. In |Vim9| syntax: >
3088 call filter(myList, (idx, val) => idx * val <= 42)
3089< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003090 call filter(myList, {idx, val -> idx * val <= 42})
3091< If you do not use "val" you can leave it out: >
3092 call filter(myList, {idx -> idx % 2 == 1})
3093<
3094 In |Vim9| script the result must be true, false, zero or one.
3095 Other values will result in a type error.
3096
3097 For a |List| and a |Dictionary| the operation is done
3098 in-place. If you want it to remain unmodified make a copy
3099 first: >
3100 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
3101
3102< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00003103 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003104 When an error is encountered while evaluating {expr2} no
3105 further items in {expr1} are processed.
3106 When {expr2} is a Funcref errors inside a function are ignored,
3107 unless it was defined with the "abort" flag.
3108
3109 Can also be used as a |method|: >
3110 mylist->filter(expr2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003111<
3112 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
3113 depending on {expr1}
3114
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003115
3116finddir({name} [, {path} [, {count}]]) *finddir()*
3117 Find directory {name} in {path}. Supports both downwards and
3118 upwards recursive directory searches. See |file-searching|
3119 for the syntax of {path}.
3120
3121 Returns the path of the first found match. When the found
3122 directory is below the current directory a relative path is
3123 returned. Otherwise a full path is returned.
3124 If {path} is omitted or empty then 'path' is used.
3125
3126 If the optional {count} is given, find {count}'s occurrence of
3127 {name} in {path} instead of the first one.
3128 When {count} is negative return all the matches in a |List|.
3129
Bram Moolenaar016188f2022-06-06 20:52:59 +01003130 Returns an empty string if the directory is not found.
3131
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003132 This is quite similar to the ex-command `:find`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003133
3134 Can also be used as a |method|: >
3135 GetName()->finddir()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003136<
3137 Return type: |String|
3138
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003139
3140findfile({name} [, {path} [, {count}]]) *findfile()*
3141 Just like |finddir()|, but find a file instead of a directory.
3142 Uses 'suffixesadd'.
3143 Example: >
3144 :echo findfile("tags.vim", ".;")
3145< Searches from the directory of the current file upwards until
3146 it finds the file "tags.vim".
3147
3148 Can also be used as a |method|: >
3149 GetName()->findfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003150<
3151 Return type: |String|
3152
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003153
3154flatten({list} [, {maxdepth}]) *flatten()*
3155 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
3156 the result is a |List| without nesting, as if {maxdepth} is
3157 a very large number.
3158 The {list} is changed in place, use |flattennew()| if you do
3159 not want that.
3160 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00003161 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003162 *E900*
3163 {maxdepth} means how deep in nested lists changes are made.
3164 {list} is not modified when {maxdepth} is 0.
3165 {maxdepth} must be positive number.
3166
3167 If there is an error the number zero is returned.
3168
3169 Example: >
3170 :echo flatten([1, [2, [3, 4]], 5])
3171< [1, 2, 3, 4, 5] >
3172 :echo flatten([1, [2, [3, 4]], 5], 1)
3173< [1, 2, [3, 4], 5]
3174
3175 Can also be used as a |method|: >
3176 mylist->flatten()
3177<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003178 Return type: list<{type}>
3179
3180
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003181flattennew({list} [, {maxdepth}]) *flattennew()*
3182 Like |flatten()| but first make a copy of {list}.
3183
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003184 Return type: list<{type}>
3185
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003186
3187float2nr({expr}) *float2nr()*
3188 Convert {expr} to a Number by omitting the part after the
3189 decimal point.
Bram Moolenaar76db9e02022-11-09 21:21:04 +00003190 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003191 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003192 When the value of {expr} is out of range for a |Number| the
3193 result is truncated to 0x7fffffff or -0x7fffffff (or when
3194 64-bit Number support is enabled, 0x7fffffffffffffff or
3195 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
3196 64-bit Number support is enabled, -0x8000000000000000).
3197 Examples: >
3198 echo float2nr(3.95)
3199< 3 >
3200 echo float2nr(-23.45)
3201< -23 >
3202 echo float2nr(1.0e100)
3203< 2147483647 (or 9223372036854775807) >
3204 echo float2nr(-1.0e150)
3205< -2147483647 (or -9223372036854775807) >
3206 echo float2nr(1.0e-100)
3207< 0
3208
3209 Can also be used as a |method|: >
3210 Compute()->float2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003211<
3212 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003213
3214
3215floor({expr}) *floor()*
3216 Return the largest integral value less than or equal to
3217 {expr} as a |Float| (round down).
3218 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003219 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003220 Examples: >
3221 echo floor(1.856)
3222< 1.0 >
3223 echo floor(-5.456)
3224< -6.0 >
3225 echo floor(4.0)
3226< 4.0
3227
3228 Can also be used as a |method|: >
3229 Compute()->floor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003230<
3231 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003232
3233
3234fmod({expr1}, {expr2}) *fmod()*
3235 Return the remainder of {expr1} / {expr2}, even if the
3236 division is not representable. Returns {expr1} - i * {expr2}
3237 for some integer i such that if {expr2} is non-zero, the
3238 result has the same sign as {expr1} and magnitude less than
3239 the magnitude of {expr2}. If {expr2} is zero, the value
3240 returned is zero. The value returned is a |Float|.
3241 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003242 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
3243 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003244 Examples: >
3245 :echo fmod(12.33, 1.22)
3246< 0.13 >
3247 :echo fmod(-12.33, 1.22)
3248< -0.13
3249
3250 Can also be used as a |method|: >
3251 Compute()->fmod(1.22)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003252<
3253 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003254
3255
3256fnameescape({string}) *fnameescape()*
3257 Escape {string} for use as file name command argument. All
3258 characters that have a special meaning, such as '%' and '|'
3259 are escaped with a backslash.
3260 For most systems the characters escaped are
3261 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3262 appears in a filename, it depends on the value of 'isfname'.
3263 A leading '+' and '>' is also escaped (special after |:edit|
3264 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01003265 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003266 Example: >
3267 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003268 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003269< results in executing: >
3270 edit \+some\ str\%nge\|name
3271<
3272 Can also be used as a |method|: >
3273 GetName()->fnameescape()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003274<
3275 Return type: |String|
3276
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003277
3278fnamemodify({fname}, {mods}) *fnamemodify()*
3279 Modify file name {fname} according to {mods}. {mods} is a
3280 string of characters like it is used for file names on the
3281 command line. See |filename-modifiers|.
3282 Example: >
3283 :echo fnamemodify("main.c", ":p:h")
3284< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01003285 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01003286< If {mods} is empty or an unsupported modifier is used then
3287 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01003288 When {fname} is empty then with {mods} ":h" returns ".", so
3289 that `:cd` can be used with it. This is different from
3290 expand('%:h') without a buffer name, which returns an empty
3291 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003292 Note: Environment variables don't work in {fname}, use
3293 |expand()| first then.
3294
3295 Can also be used as a |method|: >
3296 GetName()->fnamemodify(':p:h')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003297<
3298 Return type: |String|
3299
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003300
3301foldclosed({lnum}) *foldclosed()*
3302 The result is a Number. If the line {lnum} is in a closed
3303 fold, the result is the number of the first line in that fold.
3304 If the line {lnum} is not in a closed fold, -1 is returned.
3305 {lnum} is used like with |getline()|. Thus "." is the current
3306 line, "'m" mark m, etc.
3307
3308 Can also be used as a |method|: >
3309 GetLnum()->foldclosed()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003310<
3311 Return type: |Number|
3312
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003313
3314foldclosedend({lnum}) *foldclosedend()*
3315 The result is a Number. If the line {lnum} is in a closed
3316 fold, the result is the number of the last line in that fold.
3317 If the line {lnum} is not in a closed fold, -1 is returned.
3318 {lnum} is used like with |getline()|. Thus "." is the current
3319 line, "'m" mark m, etc.
3320
3321 Can also be used as a |method|: >
3322 GetLnum()->foldclosedend()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003323<
3324 Return type: |Number|
3325
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003326
3327foldlevel({lnum}) *foldlevel()*
3328 The result is a Number, which is the foldlevel of line {lnum}
3329 in the current buffer. For nested folds the deepest level is
3330 returned. If there is no fold at line {lnum}, zero is
3331 returned. It doesn't matter if the folds are open or closed.
3332 When used while updating folds (from 'foldexpr') -1 is
3333 returned for lines where folds are still to be updated and the
3334 foldlevel is unknown. As a special case the level of the
3335 previous line is usually available.
3336 {lnum} is used like with |getline()|. Thus "." is the current
3337 line, "'m" mark m, etc.
3338
3339 Can also be used as a |method|: >
3340 GetLnum()->foldlevel()
3341<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003342 Return type: |Number|
3343
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003344 *foldtext()*
3345foldtext() Returns a String, to be displayed for a closed fold. This is
3346 the default function used for the 'foldtext' option and should
3347 only be called from evaluating 'foldtext'. It uses the
3348 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3349 The returned string looks like this: >
3350 +-- 45 lines: abcdef
3351< The number of leading dashes depends on the foldlevel. The
3352 "45" is the number of lines in the fold. "abcdef" is the text
3353 in the first non-blank line of the fold. Leading white space,
3354 "//" or "/*" and the text from the 'foldmarker' and
3355 'commentstring' options is removed.
3356 When used to draw the actual foldtext, the rest of the line
3357 will be filled with the fold char from the 'fillchars'
3358 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003359 Returns an empty string when there is no fold.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003360
3361 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003362 {not available when compiled without the |+folding| feature}
3363
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003364
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003365foldtextresult({lnum}) *foldtextresult()*
3366 Returns the text that is displayed for the closed fold at line
3367 {lnum}. Evaluates 'foldtext' in the appropriate context.
3368 When there is no closed fold at {lnum} an empty string is
3369 returned.
3370 {lnum} is used like with |getline()|. Thus "." is the current
3371 line, "'m" mark m, etc.
3372 Useful when exporting folded text, e.g., to HTML.
3373 {not available when compiled without the |+folding| feature}
3374
3375
3376 Can also be used as a |method|: >
3377 GetLnum()->foldtextresult()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003378<
3379 Return type: |String|
3380
Ernie Raele79e2072024-01-13 11:47:33 +01003381
3382foreach({expr1}, {expr2}) *foreach()*
3383 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
3384 For each item in {expr1} execute {expr2}. {expr1} is not
erraelc92b8be2024-01-14 10:11:07 -08003385 modified; its values may be, as with |:lockvar| 1. |E741|
Ernie Raele79e2072024-01-13 11:47:33 +01003386 See |map()| and |filter()| to modify {expr1}.
3387
3388 {expr2} must be a |string| or |Funcref|.
3389
3390 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3391 of the current item. For a |Dictionary| |v:key| has the key
3392 of the current item and for a |List| |v:key| has the index of
3393 the current item. For a |Blob| |v:key| has the index of the
3394 current byte. For a |String| |v:key| has the index of the
3395 current character.
3396 Examples: >
3397 call foreach(mylist, 'used[v:val] = true')
3398< This records the items that are in the {expr1} list.
3399
3400 Note that {expr2} is the result of expression and is then used
3401 as a command. Often it is good to use a |literal-string| to
3402 avoid having to double backslashes.
3403
3404 If {expr2} is a |Funcref| it must take two arguments:
3405 1. the key or the index of the current item.
3406 2. the value of the current item.
3407 With a legacy script lambda you don't get an error if it only
3408 accepts one argument, but with a Vim9 lambda you get "E1106:
3409 One argument too many", the number of arguments must match.
3410 If the function returns a value, it is ignored.
3411
3412 Returns {expr1} in all cases.
3413 When an error is encountered while executing {expr2} no
3414 further items in {expr1} are processed.
3415 When {expr2} is a Funcref errors inside a function are ignored,
3416 unless it was defined with the "abort" flag.
3417
3418 Can also be used as a |method|: >
3419 mylist->foreach(expr2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003420<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003421 Return type: |String|, |Blob| list<{type}> or dict<{type}>
3422 depending on {expr1}
3423
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003424 *foreground()*
3425foreground() Move the Vim window to the foreground. Useful when sent from
3426 a client to a Vim server. |remote_send()|
3427 On Win32 systems this might not work, the OS does not always
3428 allow a window to bring itself to the foreground. Use
3429 |remote_foreground()| instead.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003430
3431 Return type: |Number|
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003432 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003433 Win32 console version}
3434
Bram Moolenaaraa534142022-09-15 21:46:02 +01003435fullcommand({name} [, {vim9}]) *fullcommand()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003436 Get the full command name from a short abbreviated command
3437 name; see |20.2| for details on command abbreviations.
3438
3439 The string argument {name} may start with a `:` and can
3440 include a [range], these are skipped and not returned.
Bram Moolenaaraa534142022-09-15 21:46:02 +01003441 Returns an empty string if a command doesn't exist, if it's
3442 ambiguous (for user-defined commands) or cannot be shortened
3443 this way. |vim9-no-shorten|
3444
3445 Without the {vim9} argument uses the current script version.
3446 If {vim9} is present and FALSE then legacy script rules are
3447 used. When {vim9} is present and TRUE then Vim9 rules are
3448 used, e.g. "en" is not a short form of "endif".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003449
3450 For example `fullcommand('s')`, `fullcommand('sub')`,
3451 `fullcommand(':%substitute')` all return "substitute".
3452
3453 Can also be used as a |method|: >
3454 GetName()->fullcommand()
3455<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003456 Return type: |String|
3457
3458
3459funcref({name} [, {arglist}] [, {dict}]) *funcref()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003460 Just like |function()|, but the returned Funcref will lookup
3461 the function by reference, not by name. This matters when the
3462 function {name} is redefined later.
3463
3464 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003465 It only works for an autoloaded function if it has already
3466 been loaded (to avoid mistakenly loading the autoload script
3467 when only intending to use the function name, use |function()|
3468 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003469 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003470
3471 Can also be used as a |method|: >
3472 GetFuncname()->funcref([arg])
3473<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003474 Return type: func(...): any or |Number| on error
3475
Dominique Pellee764d1b2023-03-12 21:20:59 +00003476 *function()* *partial* *E700* *E923*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003477function({name} [, {arglist}] [, {dict}])
3478 Return a |Funcref| variable that refers to function {name}.
3479 {name} can be the name of a user defined function or an
3480 internal function.
3481
3482 {name} can also be a Funcref or a partial. When it is a
3483 partial the dict stored in it will be used and the {dict}
3484 argument is not allowed. E.g.: >
3485 let FuncWithArg = function(dict.Func, [arg])
3486 let Broken = function(dict.Func, [arg], dict)
3487<
3488 When using the Funcref the function will be found by {name},
3489 also when it was redefined later. Use |funcref()| to keep the
3490 same function.
3491
3492 When {arglist} or {dict} is present this creates a partial.
3493 That means the argument list and/or the dictionary is stored in
3494 the Funcref and will be used when the Funcref is called.
3495
3496 The arguments are passed to the function in front of other
3497 arguments, but after any argument from |method|. Example: >
3498 func Callback(arg1, arg2, name)
3499 ...
3500 let Partial = function('Callback', ['one', 'two'])
3501 ...
3502 call Partial('name')
3503< Invokes the function as with: >
3504 call Callback('one', 'two', 'name')
3505
3506< With a |method|: >
3507 func Callback(one, two, three)
3508 ...
3509 let Partial = function('Callback', ['two'])
3510 ...
3511 eval 'one'->Partial('three')
3512< Invokes the function as with: >
3513 call Callback('one', 'two', 'three')
3514
3515< The function() call can be nested to add more arguments to the
3516 Funcref. The extra arguments are appended to the list of
3517 arguments. Example: >
3518 func Callback(arg1, arg2, name)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003519 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003520 let Func = function('Callback', ['one'])
3521 let Func2 = function(Func, ['two'])
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003522 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003523 call Func2('name')
3524< Invokes the function as with: >
3525 call Callback('one', 'two', 'name')
3526
3527< The Dictionary is only useful when calling a "dict" function.
3528 In that case the {dict} is passed in as "self". Example: >
3529 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003530 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003531 endfunction
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003532 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003533 let context = {"name": "example"}
3534 let Func = function('Callback', context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003535 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003536 call Func() " will echo: called for example
3537< The use of function() is not needed when there are no extra
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003538 arguments, these two are equivalent, if Callback() is defined
3539 as context.Callback(): >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003540 let Func = function('Callback', context)
3541 let Func = context.Callback
3542
3543< The argument list and the Dictionary can be combined: >
3544 function Callback(arg1, count) dict
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003545 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003546 let context = {"name": "example"}
3547 let Func = function('Callback', ['one'], context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003548 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003549 call Func(500)
3550< Invokes the function as with: >
3551 call context.Callback('one', 500)
3552<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003553 Returns 0 on error.
3554
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003555 Can also be used as a |method|: >
3556 GetFuncname()->function([arg])
3557
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003558<
3559 Return type: func(...): any or |Number| on error
3560
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003561
3562garbagecollect([{atexit}]) *garbagecollect()*
3563 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3564 that have circular references.
3565
3566 There is hardly ever a need to invoke this function, as it is
3567 automatically done when Vim runs out of memory or is waiting
3568 for the user to press a key after 'updatetime'. Items without
3569 circular references are always freed when they become unused.
3570 This is useful if you have deleted a very big |List| and/or
3571 |Dictionary| with circular references in a script that runs
3572 for a long time.
3573
3574 When the optional {atexit} argument is one, garbage
3575 collection will also be done when exiting Vim, if it wasn't
3576 done before. This is useful when checking for memory leaks.
3577
3578 The garbage collection is not done immediately but only when
3579 it's safe to perform. This is when waiting for the user to
3580 type a character. To force garbage collection immediately use
3581 |test_garbagecollect_now()|.
3582
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003583 Return type: |String|
3584
3585
LemonBoy48b7d052024-07-09 18:24:59 +02003586get({list}, {idx} [, {default}]) *get()* *get()-list*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003587 Get item {idx} from |List| {list}. When this item is not
3588 available return {default}. Return zero when {default} is
3589 omitted.
3590 Preferably used as a |method|: >
3591 mylist->get(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003592<
3593 Return type: any, depending on {list}
3594
LemonBoy48b7d052024-07-09 18:24:59 +02003595get({blob}, {idx} [, {default}]) *get()-blob*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003596 Get byte {idx} from |Blob| {blob}. When this byte is not
3597 available return {default}. Return -1 when {default} is
3598 omitted.
3599 Preferably used as a |method|: >
3600 myblob->get(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003601<
3602 Return type: |Number|
3603
LemonBoy48b7d052024-07-09 18:24:59 +02003604get({dict}, {key} [, {default}]) *get()-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003605 Get item with key {key} from |Dictionary| {dict}. When this
3606 item is not available return {default}. Return zero when
3607 {default} is omitted. Useful example: >
3608 let val = get(g:, 'var_name', 'default')
3609< This gets the value of g:var_name if it exists, and uses
3610 'default' when it does not exist.
3611 Preferably used as a |method|: >
3612 mydict->get(key)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003613<
h-east84ac2122024-06-17 18:12:30 +02003614 Return type: any, depending on {dict}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003615
LemonBoy48b7d052024-07-09 18:24:59 +02003616get({func}, {what}) *get()-func*
3617 Get item {what} from |Funcref| {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003618 {what} are:
LemonBoy48b7d052024-07-09 18:24:59 +02003619 "name" The function name
3620 "func" The function
3621 "dict" The dictionary
3622 "args" The list with arguments
3623 "arity" A dictionary with information about the number of
3624 arguments accepted by the function (minus the
3625 {arglist}) with the following fields:
3626 required the number of positional arguments
3627 optional the number of optional arguments,
3628 in addition to the required ones
3629 varargs |TRUE| if the function accepts a
3630 variable number of arguments |...|
3631
3632 Note: There is no error, if the {arglist} of
3633 the Funcref contains more arguments than the
3634 Funcref expects, it's not validated.
3635
Bram Moolenaar016188f2022-06-06 20:52:59 +01003636 Returns zero on error.
LemonBoy48b7d052024-07-09 18:24:59 +02003637
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003638 Preferably used as a |method|: >
3639 myfunc->get(what)
3640<
LemonBoy48b7d052024-07-09 18:24:59 +02003641 Return type: any, depending on {func} and {what}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003642
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003643 *getbufinfo()*
3644getbufinfo([{buf}])
3645getbufinfo([{dict}])
3646 Get information about buffers as a List of Dictionaries.
3647
3648 Without an argument information about all the buffers is
3649 returned.
3650
3651 When the argument is a |Dictionary| only the buffers matching
3652 the specified criteria are returned. The following keys can
3653 be specified in {dict}:
3654 buflisted include only listed buffers.
3655 bufloaded include only loaded buffers.
3656 bufmodified include only modified buffers.
3657
3658 Otherwise, {buf} specifies a particular buffer to return
3659 information for. For the use of {buf}, see |bufname()|
3660 above. If the buffer is found the returned List has one item.
3661 Otherwise the result is an empty list.
3662
3663 Each returned List item is a dictionary with the following
3664 entries:
3665 bufnr Buffer number.
3666 changed TRUE if the buffer is modified.
3667 changedtick Number of changes made to the buffer.
Sean Dewar1fb41032023-08-16 17:15:05 +01003668 command TRUE if the buffer belongs to the
3669 command-line window |cmdwin|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003670 hidden TRUE if the buffer is hidden.
3671 lastused Timestamp in seconds, like
3672 |localtime()|, when the buffer was
3673 last used.
3674 {only with the |+viminfo| feature}
3675 listed TRUE if the buffer is listed.
3676 lnum Line number used for the buffer when
3677 opened in the current window.
3678 Only valid if the buffer has been
3679 displayed in the window in the past.
3680 If you want the line number of the
3681 last known cursor position in a given
3682 window, use |line()|: >
3683 :echo line('.', {winid})
3684<
3685 linecount Number of lines in the buffer (only
3686 valid when loaded)
3687 loaded TRUE if the buffer is loaded.
3688 name Full path to the file in the buffer.
3689 signs List of signs placed in the buffer.
3690 Each list item is a dictionary with
3691 the following fields:
3692 id sign identifier
3693 lnum line number
3694 name sign name
3695 variables A reference to the dictionary with
3696 buffer-local variables.
3697 windows List of |window-ID|s that display this
3698 buffer
3699 popups List of popup |window-ID|s that
3700 display this buffer
3701
3702 Examples: >
3703 for buf in getbufinfo()
3704 echo buf.name
3705 endfor
3706 for buf in getbufinfo({'buflisted':1})
3707 if buf.changed
3708 ....
3709 endif
3710 endfor
3711<
3712 To get buffer-local options use: >
3713 getbufvar({bufnr}, '&option_name')
3714<
3715 Can also be used as a |method|: >
3716 GetBufnr()->getbufinfo()
3717<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003718 Return type: list<dict<any>>
3719
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003720
3721 *getbufline()*
3722getbufline({buf}, {lnum} [, {end}])
3723 Return a |List| with the lines starting from {lnum} to {end}
3724 (inclusive) in the buffer {buf}. If {end} is omitted, a
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003725 |List| with only the line {lnum} is returned. See
3726 `getbufoneline()` for only getting the line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003727
3728 For the use of {buf}, see |bufname()| above.
3729
3730 For {lnum} and {end} "$" can be used for the last line of the
3731 buffer. Otherwise a number must be used.
3732
3733 When {lnum} is smaller than 1 or bigger than the number of
3734 lines in the buffer, an empty |List| is returned.
3735
3736 When {end} is greater than the number of lines in the buffer,
3737 it is treated as {end} is set to the number of lines in the
3738 buffer. When {end} is before {lnum} an empty |List| is
3739 returned.
3740
3741 This function works only for loaded buffers. For unloaded and
3742 non-existing buffers, an empty |List| is returned.
3743
3744 Example: >
3745 :let lines = getbufline(bufnr("myfile"), 1, "$")
3746
3747< Can also be used as a |method|: >
3748 GetBufnr()->getbufline(lnum)
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003749<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003750 Return type: list<string>
3751
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003752 *getbufoneline()*
3753getbufoneline({buf}, {lnum})
3754 Just like `getbufline()` but only get one line and return it
3755 as a string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003756
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003757 Return type: |String|
3758
3759
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003760getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3761 The result is the value of option or local buffer variable
3762 {varname} in buffer {buf}. Note that the name without "b:"
3763 must be used.
3764 The {varname} argument is a string.
3765 When {varname} is empty returns a |Dictionary| with all the
3766 buffer-local variables.
3767 When {varname} is equal to "&" returns a |Dictionary| with all
3768 the buffer-local options.
3769 Otherwise, when {varname} starts with "&" returns the value of
3770 a buffer-local option.
3771 This also works for a global or buffer-local option, but it
3772 doesn't work for a global variable, window-local variable or
3773 window-local option.
3774 For the use of {buf}, see |bufname()| above.
3775 When the buffer or variable doesn't exist {def} or an empty
3776 string is returned, there is no error message.
3777 Examples: >
3778 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003779 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003780
3781< Can also be used as a |method|: >
3782 GetBufnr()->getbufvar(varname)
3783<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003784 Return type: any, depending on {varname}
3785
3786
Kota Kato66bb9ae2023-01-17 18:31:56 +00003787getcellwidths() *getcellwidths()*
3788 Returns a |List| of cell widths of character ranges overridden
3789 by |setcellwidths()|. The format is equal to the argument of
3790 |setcellwidths()|. If no character ranges have their cell
3791 widths overridden, an empty List is returned.
h-east84ac2122024-06-17 18:12:30 +02003792
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003793 Return type: list<any>
Kota Kato66bb9ae2023-01-17 18:31:56 +00003794
3795
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003796getchangelist([{buf}]) *getchangelist()*
3797 Returns the |changelist| for the buffer {buf}. For the use
3798 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3799 exist, an empty list is returned.
3800
3801 The returned list contains two entries: a list with the change
3802 locations and the current position in the list. Each
3803 entry in the change list is a dictionary with the following
3804 entries:
3805 col column number
3806 coladd column offset for 'virtualedit'
3807 lnum line number
3808 If buffer {buf} is the current buffer, then the current
3809 position refers to the position in the list. For other
3810 buffers, it is set to the length of the list.
3811
3812 Can also be used as a |method|: >
3813 GetBufnr()->getchangelist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003814<
3815 Return type: list<any>
3816
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003817
Doug Kearns9cd9e752024-04-07 17:42:17 +02003818getchar([{expr}]) *getchar()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003819 Get a single character from the user or input stream.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003820 If {expr} is omitted, wait until a character is available.
3821 If {expr} is 0, only get a character when one is available.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003822 Return zero otherwise.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003823 If {expr} is 1, only check if a character is available, it is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003824 not consumed. Return zero if no character available.
3825 If you prefer always getting a string use |getcharstr()|.
3826
Doug Kearns9cd9e752024-04-07 17:42:17 +02003827 Without {expr} and when {expr} is 0 a whole character or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003828 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01003829 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003830 Otherwise a String is returned with the encoded character.
3831 For a special key it's a String with a sequence of bytes
3832 starting with 0x80 (decimal: 128). This is the same value as
3833 the String "\<Key>", e.g., "\<Left>". The returned value is
3834 also a String when a modifier (shift, control, alt) was used
3835 that is not included in the character.
3836
Doug Kearns9cd9e752024-04-07 17:42:17 +02003837 When {expr} is 0 and Esc is typed, there will be a short delay
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003838 while Vim waits to see if this is the start of an escape
3839 sequence.
3840
Doug Kearns9cd9e752024-04-07 17:42:17 +02003841 When {expr} is 1 only the first byte is returned. For a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003842 one-byte character it is the character itself as a number.
3843 Use nr2char() to convert it to a String.
3844
3845 Use getcharmod() to obtain any additional modifiers.
3846
3847 When the user clicks a mouse button, the mouse event will be
3848 returned. The position can then be found in |v:mouse_col|,
3849 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3850 |getmousepos()| can also be used. Mouse move events will be
3851 ignored.
3852 This example positions the mouse as it would normally happen: >
3853 let c = getchar()
3854 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003855 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003856 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003857 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003858 endif
3859<
3860 When using bracketed paste only the first character is
3861 returned, the rest of the pasted text is dropped.
3862 |xterm-bracketed-paste|.
3863
3864 There is no prompt, you will somehow have to make clear to the
3865 user that a character has to be typed. The screen is not
3866 redrawn, e.g. when resizing the window. When using a popup
3867 window it should work better with a |popup-filter|.
3868
3869 There is no mapping for the character.
3870 Key codes are replaced, thus when the user presses the <Del>
3871 key you get the code for the <Del> key, not the raw character
3872 sequence. Examples: >
3873 getchar() == "\<Del>"
3874 getchar() == "\<S-Left>"
3875< This example redefines "f" to ignore case: >
3876 :nmap f :call FindChar()<CR>
3877 :function FindChar()
3878 : let c = nr2char(getchar())
3879 : while col('.') < col('$') - 1
3880 : normal l
3881 : if getline('.')[col('.') - 1] ==? c
3882 : break
3883 : endif
3884 : endwhile
3885 :endfunction
3886<
3887 You may also receive synthetic characters, such as
3888 |<CursorHold>|. Often you will want to ignore this and get
3889 another character: >
3890 :function GetKey()
3891 : let c = getchar()
3892 : while c == "\<CursorHold>"
3893 : let c = getchar()
3894 : endwhile
3895 : return c
3896 :endfunction
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003897<
3898 Return type: |Number| or |String|
3899
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003900
3901getcharmod() *getcharmod()*
3902 The result is a Number which is the state of the modifiers for
3903 the last obtained character with getchar() or in another way.
3904 These values are added together:
3905 2 shift
3906 4 control
3907 8 alt (meta)
3908 16 meta (when it's different from ALT)
3909 32 mouse double click
3910 64 mouse triple click
3911 96 mouse quadruple click (== 32 + 64)
Casey Tucker92e90a12024-01-25 22:44:00 +01003912 128 command (Mac) or super (GTK)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003913 Only the modifiers that have not been included in the
3914 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01003915 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003916
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003917 Return type: |Number|
3918
3919
3920getcharpos({expr}) *getcharpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003921 Get the position for String {expr}. Same as |getpos()| but the
3922 column number in the returned List is a character index
3923 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00003924 If |getpos()| returns a very large column number, equal to
3925 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003926 of the last character.
3927
3928 Example:
3929 With the cursor on '세' in line 5 with text "여보세요": >
3930 getcharpos('.') returns [0, 5, 3, 0]
3931 getpos('.') returns [0, 5, 7, 0]
3932<
3933 Can also be used as a |method|: >
3934 GetMark()->getcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003935<
3936 Return type: list<number>
3937
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003938
3939getcharsearch() *getcharsearch()*
3940 Return the current character search information as a {dict}
3941 with the following entries:
3942
3943 char character previously used for a character
3944 search (|t|, |f|, |T|, or |F|); empty string
3945 if no character search has been performed
3946 forward direction of character search; 1 for forward,
3947 0 for backward
3948 until type of character search; 1 for a |t| or |T|
3949 character search, 0 for an |f| or |F|
3950 character search
3951
3952 This can be useful to always have |;| and |,| search
3953 forward/backward regardless of the direction of the previous
3954 character search: >
3955 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3956 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3957< Also see |setcharsearch()|.
3958
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003959 Return type: dict<any>
3960
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003961
Doug Kearns9cd9e752024-04-07 17:42:17 +02003962getcharstr([{expr}]) *getcharstr()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003963 Get a single character from the user or input stream as a
3964 string.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003965 If {expr} is omitted, wait until a character is available.
3966 If {expr} is 0 or false, only get a character when one is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003967 available. Return an empty string otherwise.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003968 If {expr} is 1 or true, only check if a character is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003969 available, it is not consumed. Return an empty string
3970 if no character is available.
3971 Otherwise this works like |getchar()|, except that a number
3972 result is converted to a string.
3973
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003974 Return type: |String|
3975
3976
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003977getcmdcompltype() *getcmdcompltype()*
3978 Return the type of the current command-line completion.
3979 Only works when the command line is being edited, thus
3980 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01003981 See |:command-completion| for the return string.
Shougo Matsushita69084282024-09-23 20:34:47 +02003982 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
3983 |getcmdprompt()| and |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003984 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003985
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003986 Return type: |String|
3987
3988
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003989getcmdline() *getcmdline()*
Shougo Matsushita69084282024-09-23 20:34:47 +02003990 Return the current command-line input. Only works when the
3991 command line is being edited, thus requires use of
3992 |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003993 Example: >
3994 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Shougo Matsushita69084282024-09-23 20:34:47 +02003995< Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()|,
3996 |getcmdprompt()| and |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003997 Returns an empty string when entering a password or using
3998 |inputsecret()|.
3999
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004000 Return type: |String|
4001
4002
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004003getcmdpos() *getcmdpos()*
4004 Return the position of the cursor in the command line as a
4005 byte count. The first column is 1.
4006 Only works when editing the command line, thus requires use of
4007 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4008 Returns 0 otherwise.
Shougo Matsushita69084282024-09-23 20:34:47 +02004009 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
4010 |getcmdprompt()| and |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004011
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004012 Return type: |Number|
4013
4014
Shougo Matsushita69084282024-09-23 20:34:47 +02004015getcmdprompt() *getcmdprompt()*
4016 Return the current command-line prompt when using functions
4017 like |input()| or |confirm()|.
4018 Only works when the command line is being edited, thus
4019 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
4020 Also see |getcmdtype()|, |getcmdline()|, |getcmdpos()|,
4021 |setcmdpos()| and |setcmdline()|.
4022
4023 Return type: |String|
4024
4025
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004026getcmdscreenpos() *getcmdscreenpos()*
4027 Return the screen position of the cursor in the command line
4028 as a byte count. The first column is 1.
4029 Instead of |getcmdpos()|, it adds the prompt position.
4030 Only works when editing the command line, thus requires use of
4031 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4032 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01004033 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
4034 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004035
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004036 Return type: |Number|
4037
4038
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004039getcmdtype() *getcmdtype()*
4040 Return the current command-line type. Possible return values
4041 are:
4042 : normal Ex command
4043 > debug mode command |debug-mode|
4044 / forward search command
4045 ? backward search command
4046 @ |input()| command
4047 - |:insert| or |:append| command
4048 = |i_CTRL-R_=|
4049 Only works when editing the command line, thus requires use of
4050 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4051 Returns an empty string otherwise.
4052 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
4053
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004054 Return type: |String|
4055
4056
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004057getcmdwintype() *getcmdwintype()*
4058 Return the current |command-line-window| type. Possible return
4059 values are the same as |getcmdtype()|. Returns an empty string
4060 when not in the command-line window.
4061
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004062 Return type: |String|
4063
4064
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004065getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
4066 Return a list of command-line completion matches. The String
4067 {type} argument specifies what for. The following completion
4068 types are supported:
4069
4070 arglist file names in argument list
4071 augroup autocmd groups
4072 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00004073 behave |:behave| suboptions
4074 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004075 color color schemes
4076 command Ex command
4077 cmdline |cmdline-completion| result
4078 compiler compilers
4079 cscope |:cscope| suboptions
Shougo Matsushita92997dd2023-08-20 20:55:55 +02004080 custom,{func} custom completion, defined via {func}
4081 customlist,{func} custom completion, defined via {func}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004082 diff_buffer |:diffget| and |:diffput| completion
4083 dir directory names
LemonBoya20bf692024-07-11 22:35:53 +02004084 dir_in_path directory names in |'cdpath'|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004085 environment environment variable names
4086 event autocommand events
4087 expression Vim expression
4088 file file and directory names
4089 file_in_path file and directory names in |'path'|
4090 filetype filetype names |'filetype'|
4091 function function name
4092 help help subjects
4093 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00004094 history |:history| suboptions
Doug Kearns81642d92024-01-04 22:37:44 +01004095 keymap keyboard mappings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004096 locale locale names (as output of locale -a)
4097 mapclear buffer argument
4098 mapping mapping name
4099 menu menus
4100 messages |:messages| suboptions
4101 option options
4102 packadd optional package |pack-add| names
zeertzjq5c8771b2023-01-24 12:34:03 +00004103 runtime |:runtime| completion
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00004104 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004105 shellcmd Shell command
4106 sign |:sign| suboptions
4107 syntax syntax file names |'syntax'|
4108 syntime |:syntime| suboptions
4109 tag tags
4110 tag_listfiles tags, file names
4111 user user names
4112 var user variables
4113
4114 If {pat} is an empty string, then all the matches are
4115 returned. Otherwise only items matching {pat} are returned.
4116 See |wildcards| for the use of special characters in {pat}.
4117
4118 If the optional {filtered} flag is set to 1, then 'wildignore'
4119 is applied to filter the results. Otherwise all the matches
4120 are returned. The 'wildignorecase' option always applies.
4121
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00004122 If the 'wildoptions' option contains 'fuzzy', then fuzzy
4123 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00004124 regular expression matching is used. Thus this function
4125 follows the user preference, what happens on the command line.
4126 If you do not want this you can make 'wildoptions' empty
4127 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00004128
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004129 If {type} is "cmdline", then the |cmdline-completion| result is
4130 returned. For example, to complete the possible values after
4131 a ":call" command: >
4132 echo getcompletion('call ', 'cmdline')
4133<
4134 If there are no matches, an empty list is returned. An
4135 invalid value for {type} produces an error.
4136
4137 Can also be used as a |method|: >
4138 GetPattern()->getcompletion('color')
4139<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004140 Return type: list<string>
4141
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004142 *getcurpos()*
4143getcurpos([{winid}])
4144 Get the position of the cursor. This is like getpos('.'), but
4145 includes an extra "curswant" item in the list:
4146 [0, lnum, col, off, curswant] ~
4147 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00004148 cursor vertically. After |$| command it will be a very large
4149 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004150 |getpos()|.
4151 The first "bufnum" item is always zero. The byte position of
4152 the cursor is returned in 'col'. To get the character
4153 position, use |getcursorcharpos()|.
4154
4155 The optional {winid} argument can specify the window. It can
4156 be the window number or the |window-ID|. The last known
4157 cursor position is returned, this may be invalid for the
4158 current value of the buffer if it is not the current window.
4159 If {winid} is invalid a list with zeroes is returned.
4160
4161 This can be used to save and restore the cursor position: >
4162 let save_cursor = getcurpos()
4163 MoveTheCursorAround
4164 call setpos('.', save_cursor)
4165< Note that this only works within the window. See
4166 |winrestview()| for restoring more state.
4167
4168 Can also be used as a |method|: >
4169 GetWinid()->getcurpos()
4170<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004171 Return type: list<number>
4172
4173
4174getcursorcharpos([{winid}]) *getcursorcharpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004175 Same as |getcurpos()| but the column number in the returned
4176 List is a character index instead of a byte index.
4177
4178 Example:
4179 With the cursor on '보' in line 3 with text "여보세요": >
4180 getcursorcharpos() returns [0, 3, 2, 0, 3]
4181 getcurpos() returns [0, 3, 4, 0, 3]
4182<
4183 Can also be used as a |method|: >
4184 GetWinid()->getcursorcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004185<
4186 Return type: list<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004187
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004188
4189getcwd([{winnr} [, {tabnr}]]) *getcwd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004190 The result is a String, which is the name of the current
4191 working directory. 'autochdir' is ignored.
4192
4193 With {winnr} return the local current directory of this window
4194 in the current tab page. {winnr} can be the window number or
4195 the |window-ID|.
4196 If {winnr} is -1 return the name of the global working
4197 directory. See also |haslocaldir()|.
4198
4199 With {winnr} and {tabnr} return the local current directory of
4200 the window in the specified tab page. If {winnr} is -1 return
4201 the working directory of the tabpage.
4202 If {winnr} is zero use the current window, if {tabnr} is zero
4203 use the current tabpage.
4204 Without any arguments, return the actual working directory of
4205 the current window.
4206 Return an empty string if the arguments are invalid.
4207
4208 Examples: >
4209 " Get the working directory of the current window
4210 :echo getcwd()
4211 :echo getcwd(0)
4212 :echo getcwd(0, 0)
4213 " Get the working directory of window 3 in tabpage 2
4214 :echo getcwd(3, 2)
4215 " Get the global working directory
4216 :echo getcwd(-1)
4217 " Get the working directory of tabpage 3
4218 :echo getcwd(-1, 3)
4219 " Get the working directory of current tabpage
4220 :echo getcwd(-1, 0)
4221
4222< Can also be used as a |method|: >
4223 GetWinnr()->getcwd()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004224<
4225 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004226
4227getenv({name}) *getenv()*
4228 Return the value of environment variable {name}. The {name}
4229 argument is a string, without a leading '$'. Example: >
4230 myHome = getenv('HOME')
4231
4232< When the variable does not exist |v:null| is returned. That
4233 is different from a variable set to an empty string, although
4234 some systems interpret the empty value as the variable being
4235 deleted. See also |expr-env|.
4236
4237 Can also be used as a |method|: >
4238 GetVarname()->getenv()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004239<
4240 Return type: |String| or |Number|
4241
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004242
4243getfontname([{name}]) *getfontname()*
4244 Without an argument returns the name of the normal font being
4245 used. Like what is used for the Normal highlight group
4246 |hl-Normal|.
4247 With an argument a check is done whether String {name} is a
4248 valid font name. If not then an empty string is returned.
4249 Otherwise the actual font name is returned, or {name} if the
4250 GUI does not support obtaining the real name.
4251 Only works when the GUI is running, thus not in your vimrc or
4252 gvimrc file. Use the |GUIEnter| autocommand to use this
4253 function just after the GUI has started.
4254 Note that the GTK GUI accepts any font name, thus checking for
4255 a valid name does not work.
4256
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004257 Return type: |String|
4258
4259
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004260getfperm({fname}) *getfperm()*
4261 The result is a String, which is the read, write, and execute
4262 permissions of the given file {fname}.
4263 If {fname} does not exist or its directory cannot be read, an
4264 empty string is returned.
4265 The result is of the form "rwxrwxrwx", where each group of
4266 "rwx" flags represent, in turn, the permissions of the owner
4267 of the file, the group the file belongs to, and other users.
4268 If a user does not have a given permission the flag for this
4269 is replaced with the string "-". Examples: >
4270 :echo getfperm("/etc/passwd")
4271 :echo getfperm(expand("~/.vimrc"))
4272< This will hopefully (from a security point of view) display
4273 the string "rw-r--r--" or even "rw-------".
4274
4275 Can also be used as a |method|: >
4276 GetFilename()->getfperm()
4277<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004278 Return type: |String|
4279
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004280 For setting permissions use |setfperm()|.
4281
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004282
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004283getfsize({fname}) *getfsize()*
4284 The result is a Number, which is the size in bytes of the
4285 given file {fname}.
4286 If {fname} is a directory, 0 is returned.
4287 If the file {fname} can't be found, -1 is returned.
4288 If the size of {fname} is too big to fit in a Number then -2
4289 is returned.
4290
4291 Can also be used as a |method|: >
4292 GetFilename()->getfsize()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004293<
4294 Return type: |Number|
4295
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004296
4297getftime({fname}) *getftime()*
4298 The result is a Number, which is the last modification time of
4299 the given file {fname}. The value is measured as seconds
4300 since 1st Jan 1970, and may be passed to strftime(). See also
4301 |localtime()| and |strftime()|.
4302 If the file {fname} can't be found -1 is returned.
4303
4304 Can also be used as a |method|: >
4305 GetFilename()->getftime()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004306<
4307 Return type: |Number|
4308
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004309
4310getftype({fname}) *getftype()*
4311 The result is a String, which is a description of the kind of
4312 file of the given file {fname}.
4313 If {fname} does not exist an empty string is returned.
4314 Here is a table over different kinds of files and their
4315 results:
4316 Normal file "file"
4317 Directory "dir"
4318 Symbolic link "link"
4319 Block device "bdev"
4320 Character device "cdev"
4321 Socket "socket"
4322 FIFO "fifo"
4323 All other "other"
4324 Example: >
4325 getftype("/home")
4326< Note that a type such as "link" will only be returned on
4327 systems that support it. On some systems only "dir" and
4328 "file" are returned. On MS-Windows a symbolic link to a
4329 directory returns "dir" instead of "link".
4330
4331 Can also be used as a |method|: >
4332 GetFilename()->getftype()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004333<
4334 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004335
4336getimstatus() *getimstatus()*
4337 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01004338 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004339 See 'imstatusfunc'.
4340
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004341 Return type: |Number|
4342
4343
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004344getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
4345 Returns the |jumplist| for the specified window.
4346
4347 Without arguments use the current window.
4348 With {winnr} only use this window in the current tab page.
4349 {winnr} can also be a |window-ID|.
4350 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01004351 page. If {winnr} or {tabnr} is invalid, an empty list is
4352 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004353
4354 The returned list contains two entries: a list with the jump
4355 locations and the last used jump position number in the list.
4356 Each entry in the jump location list is a dictionary with
4357 the following entries:
4358 bufnr buffer number
4359 col column number
4360 coladd column offset for 'virtualedit'
4361 filename filename if available
4362 lnum line number
4363
4364 Can also be used as a |method|: >
4365 GetWinnr()->getjumplist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004366<
4367 Return type: list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004368
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004369 *getline()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004370getline({lnum} [, {end}])
4371 Without {end} the result is a String, which is line {lnum}
4372 from the current buffer. Example: >
4373 getline(1)
4374< When {lnum} is a String that doesn't start with a
4375 digit, |line()| is called to translate the String into a Number.
4376 To get the line under the cursor: >
4377 getline(".")
4378< When {lnum} is a number smaller than 1 or bigger than the
4379 number of lines in the buffer, an empty string is returned.
4380
4381 When {end} is given the result is a |List| where each item is
4382 a line from the current buffer in the range {lnum} to {end},
4383 including line {end}.
4384 {end} is used in the same way as {lnum}.
4385 Non-existing lines are silently omitted.
4386 When {end} is before {lnum} an empty |List| is returned.
4387 Example: >
4388 :let start = line('.')
4389 :let end = search("^$") - 1
4390 :let lines = getline(start, end)
4391
4392< Can also be used as a |method|: >
4393 ComputeLnum()->getline()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004394<
4395 Return type: list<string> or |String| depending on {end}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004396
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004397 To get lines from another buffer see |getbufline()| and
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00004398 |getbufoneline()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004399
4400getloclist({nr} [, {what}]) *getloclist()*
4401 Returns a |List| with all the entries in the location list for
4402 window {nr}. {nr} can be the window number or the |window-ID|.
4403 When {nr} is zero the current window is used.
4404
4405 For a location list window, the displayed location list is
4406 returned. For an invalid window number {nr}, an empty list is
4407 returned. Otherwise, same as |getqflist()|.
4408
4409 If the optional {what} dictionary argument is supplied, then
4410 returns the items listed in {what} as a dictionary. Refer to
4411 |getqflist()| for the supported items in {what}.
4412
4413 In addition to the items supported by |getqflist()| in {what},
4414 the following item is supported by |getloclist()|:
4415
4416 filewinid id of the window used to display files
4417 from the location list. This field is
4418 applicable only when called from a
4419 location list window. See
4420 |location-list-file-window| for more
4421 details.
4422
4423 Returns a |Dictionary| with default values if there is no
4424 location list for the window {nr}.
4425 Returns an empty Dictionary if window {nr} does not exist.
4426
4427 Examples (See also |getqflist-examples|): >
4428 :echo getloclist(3, {'all': 0})
4429 :echo getloclist(5, {'filewinid': 0})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004430<
4431 Return type: list<dict<any>> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004432
4433
4434getmarklist([{buf}]) *getmarklist()*
4435 Without the {buf} argument returns a |List| with information
4436 about all the global marks. |mark|
4437
4438 If the optional {buf} argument is specified, returns the
4439 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01004440 see |bufname()|. If {buf} is invalid, an empty list is
4441 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004442
4443 Each item in the returned List is a |Dict| with the following:
4444 mark name of the mark prefixed by "'"
4445 pos a |List| with the position of the mark:
4446 [bufnum, lnum, col, off]
4447 Refer to |getpos()| for more information.
4448 file file name
4449
4450 Refer to |getpos()| for getting information about a specific
4451 mark.
4452
4453 Can also be used as a |method|: >
4454 GetBufnr()->getmarklist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004455<
4456 Return type: list<dict<any>> or list<any>
4457
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004458
4459getmatches([{win}]) *getmatches()*
4460 Returns a |List| with all matches previously defined for the
4461 current window by |matchadd()| and the |:match| commands.
4462 |getmatches()| is useful in combination with |setmatches()|,
4463 as |setmatches()| can restore a list of matches saved by
4464 |getmatches()|.
4465 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01004466 window ID instead of the current window. If {win} is invalid,
4467 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004468 Example: >
4469 :echo getmatches()
4470< [{'group': 'MyGroup1', 'pattern': 'TODO',
4471 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4472 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4473 :let m = getmatches()
4474 :call clearmatches()
4475 :echo getmatches()
4476< [] >
4477 :call setmatches(m)
4478 :echo getmatches()
4479< [{'group': 'MyGroup1', 'pattern': 'TODO',
4480 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4481 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4482 :unlet m
4483<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004484 Return type: list<dict<any>> or list<any>
4485
4486
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004487getmousepos() *getmousepos()*
4488 Returns a |Dictionary| with the last known position of the
4489 mouse. This can be used in a mapping for a mouse click or in
4490 a filter of a popup window. The items are:
4491 screenrow screen row
4492 screencol screen column
4493 winid Window ID of the click
4494 winrow row inside "winid"
4495 wincol column inside "winid"
4496 line text line inside "winid"
4497 column text column inside "winid"
zeertzjqf5a94d52023-10-15 10:03:30 +02004498 coladd offset (in screen columns) from the
4499 start of the clicked char
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004500 All numbers are 1-based.
4501
4502 If not over a window, e.g. when in the command line, then only
4503 "screenrow" and "screencol" are valid, the others are zero.
4504
4505 When on the status line below a window or the vertical
4506 separator right of a window, the "line" and "column" values
4507 are zero.
4508
4509 When the position is after the text then "column" is the
4510 length of the text in bytes plus one.
4511
4512 If the mouse is over a popup window then that window is used.
4513
4514 When using |getchar()| the Vim variables |v:mouse_lnum|,
4515 |v:mouse_col| and |v:mouse_winid| also provide these values.
4516
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004517 Return type: dict<number>
4518
4519
Bram Moolenaar24dc19c2022-11-14 19:49:15 +00004520getmouseshape() *getmouseshape()*
4521 Returns the name of the currently showing mouse pointer.
4522 When the |+mouseshape| feature is not supported or the shape
4523 is unknown an empty string is returned.
4524 This function is mainly intended for testing.
4525
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004526 Return type: |String|
4527
4528
4529getpid() *getpid()*
4530 Return a Number which is the process ID of the Vim process.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004531 On Unix and MS-Windows this is a unique number, until Vim
4532 exits.
4533
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004534 Return type: |Number|
4535
4536
4537getpos({expr}) *getpos()*
zeertzjq02f3eba2024-06-12 20:45:24 +02004538 Get the position for String {expr}.
4539 The accepted values for {expr} are: *E1209*
4540 . The cursor position.
4541 $ The last line in the current buffer.
4542 'x Position of mark x (if the mark is not set, 0 is
zeertzjqd353d272024-06-13 23:00:25 +08004543 returned for all values).
zeertzjq02f3eba2024-06-12 20:45:24 +02004544 w0 First line visible in current window (one if the
4545 display isn't updated, e.g. in silent Ex mode).
4546 w$ Last line visible in current window (this is one
4547 less than "w0" if no lines are visible).
4548 v When not in Visual mode, returns the cursor
4549 position. In Visual mode, returns the other end
4550 of the Visual area. A good way to think about
4551 this is that in Visual mode "v" and "." complement
4552 each other. While "." refers to the cursor
4553 position, "v" refers to where |v_o| would move the
4554 cursor. As a result, you can use "v" and "."
4555 together to work on all of a selection in
4556 characterwise Visual mode. If the cursor is at
4557 the end of a characterwise Visual area, "v" refers
4558 to the start of the same Visual area. And if the
4559 cursor is at the start of a characterwise Visual
4560 area, "v" refers to the end of the same Visual
4561 area. "v" differs from |'<| and |'>| in that it's
4562 updated right away.
4563 Note that a mark in another file can be used. The line number
4564 then applies to another buffer.
4565
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004566 The result is a |List| with four numbers:
4567 [bufnum, lnum, col, off]
4568 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4569 is the buffer number of the mark.
4570 "lnum" and "col" are the position in the buffer. The first
4571 column is 1.
4572 The "off" number is zero, unless 'virtualedit' is used. Then
4573 it is the offset in screen columns from the start of the
4574 character. E.g., a position within a <Tab> or after the last
4575 character.
zeertzjq02f3eba2024-06-12 20:45:24 +02004576
4577 For getting the cursor position see |getcurpos()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004578 The column number in the returned List is the byte position
4579 within the line. To get the character position in the line,
4580 use |getcharpos()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02004581
4582 Note that for '< and '> Visual mode matters: when it is "V"
4583 (visual line mode) the column of '< is zero and the column of
4584 '> is a large number equal to |v:maxcol|.
naohiro ono56200ee2022-01-01 14:59:44 +00004585 A very large column number equal to |v:maxcol| can be returned,
4586 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01004587 If {expr} is invalid, returns a list with all zeros.
zeertzjq02f3eba2024-06-12 20:45:24 +02004588
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004589 This can be used to save and restore the position of a mark: >
4590 let save_a_mark = getpos("'a")
4591 ...
4592 call setpos("'a", save_a_mark)
zeertzjqd353d272024-06-13 23:00:25 +08004593<
4594 Also see |getcharpos()|, |getcurpos()| and |setpos()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004595
4596 Can also be used as a |method|: >
4597 GetMark()->getpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004598<
4599 Return type: list<number>
4600
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004601
4602getqflist([{what}]) *getqflist()*
4603 Returns a |List| with all the current quickfix errors. Each
4604 list item is a dictionary with these entries:
4605 bufnr number of buffer that has the file name, use
4606 bufname() to get the name
4607 module module name
4608 lnum line number in the buffer (first line is 1)
4609 end_lnum
4610 end of line number if the item is multiline
4611 col column number (first column is 1)
4612 end_col end of column number if the item has range
4613 vcol |TRUE|: "col" is visual column
4614 |FALSE|: "col" is byte index
4615 nr error number
h-east84ac2122024-06-17 18:12:30 +02004616 pattern search pattern used to locate the error
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004617 text description of the error
4618 type type of the error, 'E', '1', etc.
4619 valid |TRUE|: recognized error message
h_east596a9f22023-11-21 21:24:23 +09004620 user_data
4621 custom data associated with the item, can be
Tom Praschanca6ac992023-08-11 23:26:12 +02004622 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004623
4624 When there is no error list or it's empty, an empty list is
4625 returned. Quickfix list entries with a non-existing buffer
4626 number are returned with "bufnr" set to zero (Note: some
4627 functions accept buffer number zero for the alternate buffer,
4628 you may need to explicitly check for zero).
4629
4630 Useful application: Find pattern matches in multiple files and
4631 do something with them: >
4632 :vimgrep /theword/jg *.c
4633 :for d in getqflist()
4634 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4635 :endfor
4636<
4637 If the optional {what} dictionary argument is supplied, then
4638 returns only the items listed in {what} as a dictionary. The
4639 following string items are supported in {what}:
4640 changedtick get the total number of changes made
4641 to the list |quickfix-changedtick|
4642 context get the |quickfix-context|
4643 efm errorformat to use when parsing "lines". If
4644 not present, then the 'errorformat' option
4645 value is used.
4646 id get information for the quickfix list with
4647 |quickfix-ID|; zero means the id for the
4648 current list or the list specified by "nr"
4649 idx get information for the quickfix entry at this
4650 index in the list specified by 'id' or 'nr'.
4651 If set to zero, then uses the current entry.
4652 See |quickfix-index|
4653 items quickfix list entries
4654 lines parse a list of lines using 'efm' and return
4655 the resulting entries. Only a |List| type is
4656 accepted. The current quickfix list is not
4657 modified. See |quickfix-parse|.
4658 nr get information for this quickfix list; zero
4659 means the current quickfix list and "$" means
4660 the last quickfix list
4661 qfbufnr number of the buffer displayed in the quickfix
4662 window. Returns 0 if the quickfix buffer is
4663 not present. See |quickfix-buffer|.
4664 size number of entries in the quickfix list
4665 title get the list title |quickfix-title|
4666 winid get the quickfix |window-ID|
4667 all all of the above quickfix properties
4668 Non-string items in {what} are ignored. To get the value of a
4669 particular item, set it to zero.
4670 If "nr" is not present then the current quickfix list is used.
4671 If both "nr" and a non-zero "id" are specified, then the list
4672 specified by "id" is used.
4673 To get the number of lists in the quickfix stack, set "nr" to
4674 "$" in {what}. The "nr" value in the returned dictionary
4675 contains the quickfix stack size.
4676 When "lines" is specified, all the other items except "efm"
4677 are ignored. The returned dictionary contains the entry
4678 "items" with the list of entries.
4679
4680 The returned dictionary contains the following entries:
4681 changedtick total number of changes made to the
4682 list |quickfix-changedtick|
4683 context quickfix list context. See |quickfix-context|
4684 If not present, set to "".
4685 id quickfix list ID |quickfix-ID|. If not
4686 present, set to 0.
4687 idx index of the quickfix entry in the list. If not
4688 present, set to 0.
4689 items quickfix list entries. If not present, set to
4690 an empty list.
4691 nr quickfix list number. If not present, set to 0
4692 qfbufnr number of the buffer displayed in the quickfix
4693 window. If not present, set to 0.
4694 size number of entries in the quickfix list. If not
4695 present, set to 0.
4696 title quickfix list title text. If not present, set
4697 to "".
4698 winid quickfix |window-ID|. If not present, set to 0
4699
4700 Examples (See also |getqflist-examples|): >
4701 :echo getqflist({'all': 1})
4702 :echo getqflist({'nr': 2, 'title': 1})
4703 :echo getqflist({'lines' : ["F1:10:L10"]})
4704<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004705 Return type: list<dict<any>> or list<any>
4706
4707
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004708getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4709 The result is a String, which is the contents of register
4710 {regname}. Example: >
4711 :let cliptext = getreg('*')
4712< When register {regname} was not set the result is an empty
4713 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004714 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004715
4716 getreg('=') returns the last evaluated value of the expression
4717 register. (For use in maps.)
4718 getreg('=', 1) returns the expression itself, so that it can
4719 be restored with |setreg()|. For other registers the extra
4720 argument is ignored, thus you can always give it.
4721
4722 If {list} is present and |TRUE|, the result type is changed
4723 to |List|. Each list item is one text line. Use it if you care
4724 about zero bytes possibly present inside register: without
4725 third argument both NLs and zero bytes are represented as NLs
4726 (see |NL-used-for-Nul|).
4727 When the register was not set an empty list is returned.
4728
4729 If {regname} is "", the unnamed register '"' is used.
4730 If {regname} is not specified, |v:register| is used.
4731 In |Vim9-script| {regname} must be one character.
4732
4733 Can also be used as a |method|: >
4734 GetRegname()->getreg()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004735<
4736 Return type: |String|
4737
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004738
4739getreginfo([{regname}]) *getreginfo()*
4740 Returns detailed information about register {regname} as a
4741 Dictionary with the following entries:
4742 regcontents List of lines contained in register
4743 {regname}, like
4744 |getreg|({regname}, 1, 1).
4745 regtype the type of register {regname}, as in
4746 |getregtype()|.
4747 isunnamed Boolean flag, v:true if this register
4748 is currently pointed to by the unnamed
4749 register.
4750 points_to for the unnamed register, gives the
4751 single letter name of the register
4752 currently pointed to (see |quotequote|).
4753 For example, after deleting a line
4754 with `dd`, this field will be "1",
4755 which is the register that got the
4756 deleted text.
4757
4758 The {regname} argument is a string. If {regname} is invalid
4759 or not set, an empty Dictionary will be returned.
4760 If {regname} is "" or "@", the unnamed register '"' is used.
4761 If {regname} is not specified, |v:register| is used.
4762 The returned Dictionary can be passed to |setreg()|.
4763 In |Vim9-script| {regname} must be one character.
4764
4765 Can also be used as a |method|: >
4766 GetRegname()->getreginfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004767<
4768 Return type: dict<any>
4769
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004770
Shougo Matsushita19b71882024-02-28 22:48:12 +01004771getregion({pos1}, {pos2} [, {opts}]) *getregion()*
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004772 Returns the list of strings from {pos1} to {pos2} from a
Shougo Matsushita19b71882024-02-28 22:48:12 +01004773 buffer.
4774
4775 {pos1} and {pos2} must both be |List|s with four numbers.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004776 See |getpos()| for the format of the list. It's possible
4777 to specify positions from a different buffer, but please
zeertzjq0df8f932024-03-07 21:40:53 +01004778 note the limitations at |getregion-notes|.
Shougo Matsushita19b71882024-02-28 22:48:12 +01004779
4780 The optional argument {opts} is a Dict and supports the
4781 following items:
4782
zeertzjqafc22952024-05-24 19:07:12 +02004783 type Specify the region's selection type.
4784 See |getregtype()| for possible values,
zeertzjqdff55a32024-05-25 10:25:36 +02004785 except that the width can be omitted
4786 and an empty string cannot be used.
zeertzjqafc22952024-05-24 19:07:12 +02004787 (default: "v")
Shougo Matsushita19b71882024-02-28 22:48:12 +01004788
zeertzjq87410ab2024-03-02 06:00:23 +08004789 exclusive If |TRUE|, use exclusive selection
zeertzjqafc22952024-05-24 19:07:12 +02004790 for the end position.
zeertzjq87410ab2024-03-02 06:00:23 +08004791 (default: follow 'selection')
Shougo Matsushita19b71882024-02-28 22:48:12 +01004792
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004793 You can get the last selection type by |visualmode()|.
4794 If Visual mode is active, use |mode()| to get the Visual mode
4795 (e.g., in a |:vmap|).
zeertzjq87410ab2024-03-02 06:00:23 +08004796 This function is useful to get text starting and ending in
4797 different columns, such as a |characterwise-visual| selection.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004798
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004799 *getregion-notes*
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004800 Note that:
4801 - Order of {pos1} and {pos2} doesn't matter, it will always
4802 return content from the upper left position to the lower
4803 right position.
zeertzjq87410ab2024-03-02 06:00:23 +08004804 - If 'virtualedit' is enabled and the region is past the end
4805 of the lines, resulting lines are padded with spaces.
4806 - If the region is blockwise and it starts or ends in the
4807 middle of a multi-cell character, it is not included but
4808 its selected part is substituted with spaces.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004809 - If {pos1} and {pos2} are not in the same buffer, an empty
zeertzjq421b5972024-02-22 19:48:06 +01004810 list is returned.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004811 - {pos1} and {pos2} must belong to a |bufloaded()| buffer.
zeertzjq0df8f932024-03-07 21:40:53 +01004812 - It is evaluated in current window context, which makes a
4813 difference if the buffer is displayed in a window with
4814 different 'virtualedit' or 'list' values.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004815
4816 Examples: >
4817 :xnoremap <CR>
Shougo Matsushita19b71882024-02-28 22:48:12 +01004818 \ <Cmd>echow getregion(
4819 \ getpos('v'), getpos('.'), #{ type: mode() })<CR>
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004820<
4821 Can also be used as a |method|: >
Shougo Matsushita19b71882024-02-28 22:48:12 +01004822 getpos('.')->getregion(getpos("'a"))
zeertzjqd4d12072024-07-16 20:34:16 +02004823<
4824 Return type: list<string>
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004825
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004826<
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004827getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()*
4828 Same as |getregion()|, but returns a list of positions
4829 describing the buffer text segments bound by {pos1} and
4830 {pos2}.
4831 The segments are a pair of positions for every line: >
4832 [[{start_pos}, {end_pos}], ...]
4833<
4834 The position is a |List| with four numbers:
4835 [bufnum, lnum, col, off]
4836 "bufnum" is the buffer number.
4837 "lnum" and "col" are the position in the buffer. The first
4838 column is 1.
zeertzjqc95e64f2024-05-20 14:00:31 +02004839 If the "off" number of a starting position is non-zero, it is
4840 the offset in screen columns from the start of the character.
4841 E.g., a position within a <Tab> or after the last character.
4842 If the "off" number of an ending position is non-zero, it is
zeertzjq52a6f342024-05-22 16:42:44 +02004843 the offset of the character's first cell not included in the
4844 selection, otherwise all its cells are included.
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004845
zeertzjq2b09de92024-05-24 07:48:51 +02004846 Apart from the options supported by |getregion()|, {opts} also
4847 supports the following:
4848
4849 eol If |TRUE|, indicate positions beyond
4850 the end of a line with "col" values
4851 one more than the length of the line.
4852 If |FALSE|, positions are limited
4853 within their lines, and if a line is
4854 empty or the selection is entirely
4855 beyond the end of a line, a "col"
4856 value of 0 is used for both positions.
4857 (default: |FALSE|)
4858
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004859 Can also be used as a |method|: >
4860 getpos('.')->getregionpos(getpos("'a"))
4861<
zeertzjqd4d12072024-07-16 20:34:16 +02004862 Return type: list<list<list<number>>>
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004863
4864
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004865getregtype([{regname}]) *getregtype()*
4866 The result is a String, which is type of register {regname}.
4867 The value will be one of:
4868 "v" for |characterwise| text
4869 "V" for |linewise| text
4870 "<CTRL-V>{width}" for |blockwise-visual| text
4871 "" for an empty or unknown register
4872 <CTRL-V> is one character with value 0x16.
4873 The {regname} argument is a string. If {regname} is "", the
4874 unnamed register '"' is used. If {regname} is not specified,
4875 |v:register| is used.
4876 In |Vim9-script| {regname} must be one character.
4877
4878 Can also be used as a |method|: >
4879 GetRegname()->getregtype()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004880<
4881 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004882
Bram Moolenaar71badf92023-04-22 22:40:14 +01004883getscriptinfo([{opts}]) *getscriptinfo()*
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004884 Returns a |List| with information about all the sourced Vim
Bram Moolenaar753885b2022-08-24 16:30:36 +01004885 scripts in the order they were sourced, like what
4886 `:scriptnames` shows.
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004887
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004888 The optional Dict argument {opts} supports the following
4889 optional items:
4890 name Script name match pattern. If specified,
4891 and "sid" is not specified, information about
Bram Moolenaar71badf92023-04-22 22:40:14 +01004892 scripts with a name that match the pattern
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004893 "name" are returned.
4894 sid Script ID |<SID>|. If specified, only
4895 information about the script with ID "sid" is
4896 returned and "name" is ignored.
4897
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004898 Each item in the returned List is a |Dict| with the following
4899 items:
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004900 autoload Set to TRUE for a script that was used with
Bram Moolenaar753885b2022-08-24 16:30:36 +01004901 `import autoload` but was not actually sourced
4902 yet (see |import-autoload|).
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004903 functions List of script-local function names defined in
4904 the script. Present only when a particular
4905 script is specified using the "sid" item in
4906 {opts}.
4907 name Vim script file name.
4908 sid Script ID |<SID>|.
4909 sourced Script ID of the actually sourced script that
Bram Moolenaarfd999452022-08-24 18:30:14 +01004910 this script name links to, if any, otherwise
4911 zero
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004912 variables A dictionary with the script-local variables.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00004913 Present only when a particular script is
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004914 specified using the "sid" item in {opts}.
4915 Note that this is a copy, the value of
4916 script-local variables cannot be changed using
4917 this dictionary.
h_east59858792023-10-25 22:47:05 +09004918 version Vim script version (|scriptversion|)
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01004919
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004920 Examples: >
4921 :echo getscriptinfo({'name': 'myscript'})
zeertzjqad4881c2024-05-04 15:35:30 +08004922 :echo getscriptinfo({'sid': 15})[0].variables
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004923<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004924 Return type: list<dict<any>>
4925
4926
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004927gettabinfo([{tabnr}]) *gettabinfo()*
4928 If {tabnr} is not specified, then information about all the
4929 tab pages is returned as a |List|. Each List item is a
4930 |Dictionary|. Otherwise, {tabnr} specifies the tab page
4931 number and information about that one is returned. If the tab
4932 page does not exist an empty List is returned.
4933
4934 Each List item is a |Dictionary| with the following entries:
4935 tabnr tab page number.
4936 variables a reference to the dictionary with
4937 tabpage-local variables
4938 windows List of |window-ID|s in the tab page.
4939
4940 Can also be used as a |method|: >
4941 GetTabnr()->gettabinfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004942<
4943 Return type: list<dict<any>>
4944
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004945
4946gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
4947 Get the value of a tab-local variable {varname} in tab page
4948 {tabnr}. |t:var|
4949 Tabs are numbered starting with one.
4950 The {varname} argument is a string. When {varname} is empty a
4951 dictionary with all tab-local variables is returned.
4952 Note that the name without "t:" must be used.
4953 When the tab or variable doesn't exist {def} or an empty
4954 string is returned, there is no error message.
4955
4956 Can also be used as a |method|: >
4957 GetTabnr()->gettabvar(varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004958<
4959 Return type: any, depending on {varname}
4960
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004961
4962gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
4963 Get the value of window-local variable {varname} in window
4964 {winnr} in tab page {tabnr}.
4965 The {varname} argument is a string. When {varname} is empty a
4966 dictionary with all window-local variables is returned.
4967 When {varname} is equal to "&" get the values of all
4968 window-local options in a |Dictionary|.
4969 Otherwise, when {varname} starts with "&" get the value of a
4970 window-local option.
4971 Note that {varname} must be the name without "w:".
4972 Tabs are numbered starting with one. For the current tabpage
4973 use |getwinvar()|.
4974 {winnr} can be the window number or the |window-ID|.
4975 When {winnr} is zero the current window is used.
4976 This also works for a global option, buffer-local option and
4977 window-local option, but it doesn't work for a global variable
4978 or buffer-local variable.
4979 When the tab, window or variable doesn't exist {def} or an
4980 empty string is returned, there is no error message.
4981 Examples: >
4982 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004983 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004984<
4985 To obtain all window-local variables use: >
4986 gettabwinvar({tabnr}, {winnr}, '&')
4987
4988< Can also be used as a |method|: >
4989 GetTabnr()->gettabwinvar(winnr, varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004990<
4991 Return type: any, depending on {varname}
4992
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004993
4994gettagstack([{winnr}]) *gettagstack()*
4995 The result is a Dict, which is the tag stack of window {winnr}.
4996 {winnr} can be the window number or the |window-ID|.
4997 When {winnr} is not specified, the current window is used.
4998 When window {winnr} doesn't exist, an empty Dict is returned.
4999
5000 The returned dictionary contains the following entries:
5001 curidx Current index in the stack. When at
5002 top of the stack, set to (length + 1).
5003 Index of bottom of the stack is 1.
5004 items List of items in the stack. Each item
5005 is a dictionary containing the
5006 entries described below.
5007 length Number of entries in the stack.
5008
5009 Each item in the stack is a dictionary with the following
5010 entries:
5011 bufnr buffer number of the current jump
5012 from cursor position before the tag jump.
5013 See |getpos()| for the format of the
5014 returned list.
5015 matchnr current matching tag number. Used when
5016 multiple matching tags are found for a
5017 name.
5018 tagname name of the tag
5019
5020 See |tagstack| for more information about the tag stack.
5021
5022 Can also be used as a |method|: >
5023 GetWinnr()->gettagstack()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005024<
5025 Return type: dict<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005026
5027
Christ van Willegence0ef912024-06-20 23:41:59 +02005028gettext({text} [, {package}]) *gettext()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005029 Translate String {text} if possible.
RestorerZ96509102024-07-11 21:14:15 +02005030 This is intended for use in Vim scripts. When generating
5031 message translations the {text} is extracted by `xgettext`,
5032 the translator can add translated messages into the .po file
5033 and Vim will lookup the translation when gettext() is called.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005034 For {text} double quoted strings are preferred, because
RestorerZ96509102024-07-11 21:14:15 +02005035 `xgettext` does not support single quoted escaped text.
5036
Christ van Willegence0ef912024-06-20 23:41:59 +02005037 When the {package} is specified, the translation is looked up
RestorerZ96509102024-07-11 21:14:15 +02005038 for that specific package. This is mainly required for
5039 third-party Vim scripts. You need to specify a path to the
5040 translations with the |bindtextdomain()| function before
5041 using the gettext() function.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005042
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005043 Return type: |String|
5044
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005045
5046getwininfo([{winid}]) *getwininfo()*
5047 Returns information about windows as a |List| with Dictionaries.
5048
5049 If {winid} is given Information about the window with that ID
5050 is returned, as a |List| with one item. If the window does not
5051 exist the result is an empty list.
5052
5053 Without {winid} information about all the windows in all the
5054 tab pages is returned.
5055
5056 Each List item is a |Dictionary| with the following entries:
5057 botline last complete displayed buffer line
5058 bufnr number of buffer in the window
5059 height window height (excluding winbar)
5060 loclist 1 if showing a location list
5061 {only with the +quickfix feature}
5062 quickfix 1 if quickfix or location list window
5063 {only with the +quickfix feature}
5064 terminal 1 if a terminal window
5065 {only with the +terminal feature}
5066 tabnr tab page number
5067 topline first displayed buffer line
5068 variables a reference to the dictionary with
5069 window-local variables
5070 width window width
5071 winbar 1 if the window has a toolbar, 0
5072 otherwise
5073 wincol leftmost screen column of the window;
5074 "col" from |win_screenpos()|
5075 textoff number of columns occupied by any
5076 'foldcolumn', 'signcolumn' and line
5077 number in front of the text
5078 winid |window-ID|
5079 winnr window number
5080 winrow topmost screen line of the window;
5081 "row" from |win_screenpos()|
5082
5083 Can also be used as a |method|: >
5084 GetWinnr()->getwininfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005085<
5086 Return type: list<dict<any>>
5087
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005088
5089getwinpos([{timeout}]) *getwinpos()*
5090 The result is a |List| with two numbers, the result of
5091 |getwinposx()| and |getwinposy()| combined:
5092 [x-pos, y-pos]
5093 {timeout} can be used to specify how long to wait in msec for
5094 a response from the terminal. When omitted 100 msec is used.
5095 Use a longer time for a remote terminal.
5096 When using a value less than 10 and no response is received
5097 within that time, a previously reported position is returned,
5098 if available. This can be used to poll for the position and
5099 do some work in the meantime: >
5100 while 1
5101 let res = getwinpos(1)
5102 if res[0] >= 0
5103 break
5104 endif
5105 " Do some work here
5106 endwhile
5107<
5108
5109 Can also be used as a |method|: >
5110 GetTimeout()->getwinpos()
5111<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005112 Return type: list<number>
5113
5114
5115getwinposx() *getwinposx()*
5116 The result is a Number, which is the X coordinate in pixels of
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005117 the left hand side of the GUI Vim window. Also works for an
5118 xterm (uses a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01005119 The result will be -1 if the information is not available
5120 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005121 The value can be used with `:winpos`.
5122
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005123 Return type: |Number|
5124
5125
5126getwinposy() *getwinposy()*
5127 The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005128 the top of the GUI Vim window. Also works for an xterm (uses
5129 a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01005130 The result will be -1 if the information is not available
5131 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005132 The value can be used with `:winpos`.
5133
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005134 Return type: |Number|
5135
5136
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005137getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
5138 Like |gettabwinvar()| for the current tabpage.
5139 Examples: >
5140 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005141 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005142
5143< Can also be used as a |method|: >
5144 GetWinnr()->getwinvar(varname)
5145<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005146 Return type: any, depending on {varname}
5147
5148
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005149glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
5150 Expand the file wildcards in {expr}. See |wildcards| for the
5151 use of special characters.
5152
5153 Unless the optional {nosuf} argument is given and is |TRUE|,
5154 the 'suffixes' and 'wildignore' options apply: Names matching
5155 one of the patterns in 'wildignore' will be skipped and
5156 'suffixes' affect the ordering of matches.
5157 'wildignorecase' always applies.
5158
5159 When {list} is present and it is |TRUE| the result is a |List|
5160 with all matching files. The advantage of using a List is,
5161 you also get filenames containing newlines correctly.
5162 Otherwise the result is a String and when there are several
5163 matches, they are separated by <NL> characters.
5164
5165 If the expansion fails, the result is an empty String or List.
5166
5167 You can also use |readdir()| if you need to do complicated
5168 things, such as limiting the number of matches.
5169
5170 A name for a non-existing file is not included. A symbolic
5171 link is only included if it points to an existing file.
5172 However, when the {alllinks} argument is present and it is
5173 |TRUE| then all symbolic links are included.
5174
5175 For most systems backticks can be used to get files names from
5176 any external command. Example: >
5177 :let tagfiles = glob("`find . -name tags -print`")
5178 :let &tags = substitute(tagfiles, "\n", ",", "g")
5179< The result of the program inside the backticks should be one
5180 item per line. Spaces inside an item are allowed.
5181
5182 See |expand()| for expanding special Vim variables. See
5183 |system()| for getting the raw output of an external command.
5184
5185 Can also be used as a |method|: >
5186 GetExpr()->glob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005187<
5188 Return type: |String| or list<string> or list<any> depending
5189 on {list}
5190
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005191
5192glob2regpat({string}) *glob2regpat()*
5193 Convert a file pattern, as used by glob(), into a search
5194 pattern. The result can be used to match with a string that
5195 is a file name. E.g. >
5196 if filename =~ glob2regpat('Make*.mak')
5197< This is equivalent to: >
5198 if filename =~ '^Make.*\.mak$'
5199< When {string} is an empty string the result is "^$", match an
5200 empty string.
5201 Note that the result depends on the system. On MS-Windows
5202 a backslash usually means a path separator.
5203
5204 Can also be used as a |method|: >
5205 GetExpr()->glob2regpat()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005206<
5207 Return type: |String|
5208
5209 *globpath()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005210globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
5211 Perform glob() for String {expr} on all directories in {path}
5212 and concatenate the results. Example: >
5213 :echo globpath(&rtp, "syntax/c.vim")
5214<
5215 {path} is a comma-separated list of directory names. Each
5216 directory name is prepended to {expr} and expanded like with
5217 |glob()|. A path separator is inserted when needed.
5218 To add a comma inside a directory name escape it with a
5219 backslash. Note that on MS-Windows a directory may have a
5220 trailing backslash, remove it if you put a comma after it.
5221 If the expansion fails for one of the directories, there is no
5222 error message.
5223
5224 Unless the optional {nosuf} argument is given and is |TRUE|,
5225 the 'suffixes' and 'wildignore' options apply: Names matching
5226 one of the patterns in 'wildignore' will be skipped and
5227 'suffixes' affect the ordering of matches.
5228
5229 When {list} is present and it is |TRUE| the result is a |List|
5230 with all matching files. The advantage of using a List is, you
5231 also get filenames containing newlines correctly. Otherwise
5232 the result is a String and when there are several matches,
5233 they are separated by <NL> characters. Example: >
5234 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
5235<
5236 {alllinks} is used as with |glob()|.
5237
5238 The "**" item can be used to search in a directory tree.
5239 For example, to find all "README.txt" files in the directories
5240 in 'runtimepath' and below: >
5241 :echo globpath(&rtp, "**/README.txt")
5242< Upwards search and limiting the depth of "**" is not
5243 supported, thus using 'path' will not always work properly.
5244
5245 Can also be used as a |method|, the base is passed as the
5246 second argument: >
5247 GetExpr()->globpath(&rtp)
5248<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005249 Return type: |String| or list<string> or list<any> depending
5250 on {list}
5251
5252
5253has({feature} [, {check}]) *has()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005254 When {check} is omitted or is zero: The result is a Number,
5255 which is 1 if the feature {feature} is supported, zero
5256 otherwise. The {feature} argument is a string, case is
5257 ignored. See |feature-list| below.
5258
5259 When {check} is present and not zero: The result is a Number,
5260 which is 1 if the feature {feature} could ever be supported,
5261 zero otherwise. This is useful to check for a typo in
5262 {feature} and to detect dead code. Keep in mind that an older
5263 Vim version will not know about a feature added later and
5264 features that have been abandoned will not be known by the
5265 current Vim version.
5266
5267 Also see |exists()| and |exists_compiled()|.
5268
5269 Note that to skip code that has a syntax error when the
5270 feature is not available, Vim may skip the rest of the line
5271 and miss a following `endif`. Therefore put the `endif` on a
5272 separate line: >
5273 if has('feature')
5274 let x = this->breaks->without->the->feature
5275 endif
5276< If the `endif` would be moved to the second line as "| endif" it
5277 would not be found.
5278
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005279 Return type: |Number|
5280
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005281
5282has_key({dict}, {key}) *has_key()*
5283 The result is a Number, which is TRUE if |Dictionary| {dict}
Bram Moolenaare8008642022-08-19 17:15:35 +01005284 has an entry with key {key}. FALSE otherwise.
5285 The {key} argument is a string. In |Vim9| script a number is
5286 also accepted (and converted to a string) but no other types.
5287 In legacy script the usual automatic conversion to string is
5288 done.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005289
5290 Can also be used as a |method|: >
5291 mydict->has_key(key)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005292<
5293 Return type: |Number|
5294
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005295
5296haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
5297 The result is a Number:
5298 1 when the window has set a local directory via |:lcd|
5299 2 when the tab-page has set a local directory via |:tcd|
5300 0 otherwise.
5301
5302 Without arguments use the current window.
5303 With {winnr} use this window in the current tab page.
5304 With {winnr} and {tabnr} use the window in the specified tab
5305 page.
5306 {winnr} can be the window number or the |window-ID|.
5307 If {winnr} is -1 it is ignored and only the tabpage is used.
5308 Return 0 if the arguments are invalid.
5309 Examples: >
5310 if haslocaldir() == 1
5311 " window local directory case
5312 elseif haslocaldir() == 2
5313 " tab-local directory case
5314 else
5315 " global directory case
5316 endif
5317
5318 " current window
5319 :echo haslocaldir()
5320 :echo haslocaldir(0)
5321 :echo haslocaldir(0, 0)
5322 " window n in current tab page
5323 :echo haslocaldir(n)
5324 :echo haslocaldir(n, 0)
5325 " window n in tab page m
5326 :echo haslocaldir(n, m)
5327 " tab page m
5328 :echo haslocaldir(-1, m)
5329<
5330 Can also be used as a |method|: >
5331 GetWinnr()->haslocaldir()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005332<
5333 Return type: |Number|
5334
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005335
5336hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
5337 The result is a Number, which is TRUE if there is a mapping
5338 that contains {what} in somewhere in the rhs (what it is
5339 mapped to) and this mapping exists in one of the modes
5340 indicated by {mode}.
5341 The arguments {what} and {mode} are strings.
5342 When {abbr} is there and it is |TRUE| use abbreviations
5343 instead of mappings. Don't forget to specify Insert and/or
5344 Command-line mode.
5345 Both the global mappings and the mappings local to the current
5346 buffer are checked for a match.
5347 If no matching mapping is found FALSE is returned.
5348 The following characters are recognized in {mode}:
5349 n Normal mode
5350 v Visual and Select mode
5351 x Visual mode
5352 s Select mode
5353 o Operator-pending mode
5354 i Insert mode
5355 l Language-Argument ("r", "f", "t", etc.)
5356 c Command-line mode
5357 When {mode} is omitted, "nvo" is used.
5358
5359 This function is useful to check if a mapping already exists
5360 to a function in a Vim script. Example: >
5361 :if !hasmapto('\ABCdoit')
5362 : map <Leader>d \ABCdoit
5363 :endif
5364< This installs the mapping to "\ABCdoit" only if there isn't
5365 already a mapping to "\ABCdoit".
5366
5367 Can also be used as a |method|: >
5368 GetRHS()->hasmapto()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005369<
5370 Return type: |Number|
5371
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005372
5373histadd({history}, {item}) *histadd()*
5374 Add the String {item} to the history {history} which can be
5375 one of: *hist-names*
5376 "cmd" or ":" command line history
5377 "search" or "/" search pattern history
5378 "expr" or "=" typed expression history
5379 "input" or "@" input line history
5380 "debug" or ">" debug command history
5381 empty the current or last used history
5382 The {history} string does not need to be the whole name, one
5383 character is sufficient.
5384 If {item} does already exist in the history, it will be
5385 shifted to become the newest entry.
5386 The result is a Number: TRUE if the operation was successful,
5387 otherwise FALSE is returned.
5388
5389 Example: >
5390 :call histadd("input", strftime("%Y %b %d"))
5391 :let date=input("Enter date: ")
5392< This function is not available in the |sandbox|.
5393
5394 Can also be used as a |method|, the base is passed as the
5395 second argument: >
5396 GetHistory()->histadd('search')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005397<
5398 Return type: |Number|
5399
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005400
5401histdel({history} [, {item}]) *histdel()*
5402 Clear {history}, i.e. delete all its entries. See |hist-names|
5403 for the possible values of {history}.
5404
5405 If the parameter {item} evaluates to a String, it is used as a
5406 regular expression. All entries matching that expression will
5407 be removed from the history (if there are any).
5408 Upper/lowercase must match, unless "\c" is used |/\c|.
5409 If {item} evaluates to a Number, it will be interpreted as
5410 an index, see |:history-indexing|. The respective entry will
5411 be removed if it exists.
5412
5413 The result is TRUE for a successful operation, otherwise FALSE
5414 is returned.
5415
5416 Examples:
5417 Clear expression register history: >
5418 :call histdel("expr")
5419<
5420 Remove all entries starting with "*" from the search history: >
5421 :call histdel("/", '^\*')
5422<
5423 The following three are equivalent: >
5424 :call histdel("search", histnr("search"))
5425 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005426 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005427<
5428 To delete the last search pattern and use the last-but-one for
5429 the "n" command and 'hlsearch': >
5430 :call histdel("search", -1)
5431 :let @/ = histget("search", -1)
5432<
5433 Can also be used as a |method|: >
5434 GetHistory()->histdel()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005435<
5436 Return type: |Number|
5437
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005438
5439histget({history} [, {index}]) *histget()*
5440 The result is a String, the entry with Number {index} from
5441 {history}. See |hist-names| for the possible values of
5442 {history}, and |:history-indexing| for {index}. If there is
5443 no such entry, an empty String is returned. When {index} is
5444 omitted, the most recent item from the history is used.
5445
5446 Examples:
5447 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005448 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005449
5450< Define an Ex command ":H {num}" that supports re-execution of
5451 the {num}th entry from the output of |:history|. >
5452 :command -nargs=1 H execute histget("cmd", 0+<args>)
5453<
5454 Can also be used as a |method|: >
5455 GetHistory()->histget()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005456<
5457 Return type: |String|
5458
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005459
5460histnr({history}) *histnr()*
5461 The result is the Number of the current entry in {history}.
5462 See |hist-names| for the possible values of {history}.
5463 If an error occurred, -1 is returned.
5464
5465 Example: >
5466 :let inp_index = histnr("expr")
5467
5468< Can also be used as a |method|: >
5469 GetHistory()->histnr()
5470<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005471 Return type: |Number|
5472
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005473hlexists({name}) *hlexists()*
5474 The result is a Number, which is TRUE if a highlight group
5475 called {name} exists. This is when the group has been
5476 defined in some way. Not necessarily when highlighting has
5477 been defined for it, it may also have been used for a syntax
5478 item.
5479 *highlight_exists()*
5480 Obsolete name: highlight_exists().
5481
5482 Can also be used as a |method|: >
5483 GetName()->hlexists()
5484<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005485 Return type: |Number|
5486
5487
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005488hlget([{name} [, {resolve}]]) *hlget()*
5489 Returns a List of all the highlight group attributes. If the
5490 optional {name} is specified, then returns a List with only
5491 the attributes of the specified highlight group. Returns an
5492 empty List if the highlight group {name} is not present.
5493
5494 If the optional {resolve} argument is set to v:true and the
5495 highlight group {name} is linked to another group, then the
5496 link is resolved recursively and the attributes of the
5497 resolved highlight group are returned.
5498
5499 Each entry in the returned List is a Dictionary with the
5500 following items:
5501 cleared boolean flag, set to v:true if the highlight
5502 group attributes are cleared or not yet
5503 specified. See |highlight-clear|.
5504 cterm cterm attributes. See |highlight-cterm|.
5505 ctermbg cterm background color.
5506 See |highlight-ctermbg|.
5507 ctermfg cterm foreground color.
5508 See |highlight-ctermfg|.
5509 ctermul cterm underline color. See |highlight-ctermul|.
5510 default boolean flag, set to v:true if the highlight
5511 group link is a default link. See
5512 |highlight-default|.
5513 font highlight group font. See |highlight-font|.
5514 gui gui attributes. See |highlight-gui|.
5515 guibg gui background color. See |highlight-guibg|.
5516 guifg gui foreground color. See |highlight-guifg|.
5517 guisp gui special color. See |highlight-guisp|.
5518 id highlight group ID.
5519 linksto linked highlight group name.
5520 See |:highlight-link|.
5521 name highlight group name. See |group-name|.
5522 start start terminal keycode. See |highlight-start|.
5523 stop stop terminal keycode. See |highlight-stop|.
5524 term term attributes. See |highlight-term|.
5525
5526 The 'term', 'cterm' and 'gui' items in the above Dictionary
5527 have a dictionary value with the following optional boolean
5528 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
5529 'reverse', 'inverse' and 'strikethrough'.
5530
5531 Example(s): >
5532 :echo hlget()
5533 :echo hlget('ModeMsg')
5534 :echo hlget('Number', v:true)
5535<
5536 Can also be used as a |method|: >
5537 GetName()->hlget()
5538<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005539 Return type: list<dict<any>>
5540
5541
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005542hlset({list}) *hlset()*
5543 Creates or modifies the attributes of a List of highlight
5544 groups. Each item in {list} is a dictionary containing the
5545 attributes of a highlight group. See |hlget()| for the list of
5546 supported items in this dictionary.
5547
5548 In addition to the items described in |hlget()|, the following
5549 additional items are supported in the dictionary:
5550
5551 force boolean flag to force the creation of
5552 a link for an existing highlight group
5553 with attributes.
5554
5555 The highlight group is identified using the 'name' item and
5556 the 'id' item (if supplied) is ignored. If a highlight group
5557 with a specified name doesn't exist, then it is created.
5558 Otherwise the attributes of an existing highlight group are
5559 modified.
5560
5561 If an empty dictionary value is used for the 'term' or 'cterm'
5562 or 'gui' entries, then the corresponding attributes are
5563 cleared. If the 'cleared' item is set to v:true, then all the
5564 attributes of the highlight group are cleared.
5565
5566 The 'linksto' item can be used to link a highlight group to
5567 another highlight group. See |:highlight-link|.
5568
5569 Returns zero for success, -1 for failure.
5570
5571 Example(s): >
5572 " add bold attribute to the Visual highlight group
5573 :call hlset([#{name: 'Visual',
5574 \ term: #{reverse: 1 , bold: 1}}])
5575 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
5576 :let l = hlget()
5577 :call hlset(l)
5578 " clear the Search highlight group
5579 :call hlset([#{name: 'Search', cleared: v:true}])
5580 " clear the 'term' attributes for a highlight group
5581 :call hlset([#{name: 'Title', term: {}}])
5582 " create the MyHlg group linking it to DiffAdd
5583 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
5584 " remove the MyHlg group link
5585 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
5586 " clear the attributes and a link
5587 :call hlset([#{name: 'MyHlg', cleared: v:true,
5588 \ linksto: 'NONE'}])
5589<
5590 Can also be used as a |method|: >
5591 GetAttrList()->hlset()
5592<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005593 Return type: |Number|
5594
5595hlID({name}) *hlID()*
5596 The result is a Number, which is the ID of the highlight group
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005597 with name {name}. When the highlight group doesn't exist,
5598 zero is returned.
5599 This can be used to retrieve information about the highlight
5600 group. For example, to get the background color of the
5601 "Comment" group: >
5602 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5603< *highlightID()*
5604 Obsolete name: highlightID().
5605
5606 Can also be used as a |method|: >
5607 GetName()->hlID()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005608<
5609 Return type: |Number|
5610
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005611
5612hostname() *hostname()*
5613 The result is a String, which is the name of the machine on
5614 which Vim is currently running. Machine names greater than
5615 256 characters long are truncated.
5616
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005617 Return type: |String|
5618
5619
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005620iconv({string}, {from}, {to}) *iconv()*
5621 The result is a String, which is the text {string} converted
5622 from encoding {from} to encoding {to}.
5623 When the conversion completely fails an empty string is
5624 returned. When some characters could not be converted they
5625 are replaced with "?".
5626 The encoding names are whatever the iconv() library function
5627 can accept, see ":!man 3 iconv".
5628 Most conversions require Vim to be compiled with the |+iconv|
5629 feature. Otherwise only UTF-8 to latin1 conversion and back
5630 can be done.
5631 This can be used to display messages with special characters,
5632 no matter what 'encoding' is set to. Write the message in
5633 UTF-8 and use: >
5634 echo iconv(utf8_str, "utf-8", &enc)
5635< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5636 from/to UCS-2 is automatically changed to use UTF-8. You
5637 cannot use UCS-2 in a string anyway, because of the NUL bytes.
5638
5639 Can also be used as a |method|: >
5640 GetText()->iconv('latin1', 'utf-8')
5641<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005642 Return type: |String|
5643
5644
Ernie Raelc8e158b2024-07-09 18:39:52 +02005645id({item}) *id()*
5646 The result is a unique String associated with the {item} and
5647 not with the {item}'s contents. It is only valid while the
5648 {item} exists and is referenced. It is valid only in the
5649 instance of vim that produces the result. The whole idea is
5650 that `id({item})` does not change if the contents of {item}
5651 changes. This is useful as a `key` for creating an identity
5652 dictionary, rather than one based on equals.
5653
5654 This operation does not reference {item} and there is no
5655 function to convert the `id` to the {item}. It may be useful to
5656 have a map of `id` to {item}. The following >
5657 var referenceMap: dict<any>
5658 var id = item->id()
5659 referenceMap[id] = item
5660< prevents {item} from being garbage collected and provides a
5661 way to get the {item} from the `id`.
5662
5663 {item} may be a List, Dictionary, Object, Job, Channel or
5664 Blob. If the item is not a permitted type, or it is a null
5665 value, then an empty String is returned.
5666
5667 Can also be used as a |method|: >
5668 GetItem()->id()
5669<
5670 Return type: |String|
5671
5672
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005673indent({lnum}) *indent()*
5674 The result is a Number, which is indent of line {lnum} in the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005675 current buffer. The indent is counted in spaces, the value
5676 of 'tabstop' is relevant. {lnum} is used just like in
5677 |getline()|.
5678 When {lnum} is invalid -1 is returned. In |Vim9| script an
5679 error is given.
5680
5681 Can also be used as a |method|: >
5682 GetLnum()->indent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005683<
5684 Return type: |Number|
5685
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005686
5687index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005688 Find {expr} in {object} and return its index. See
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005689 |indexof()| for using a lambda to select the item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005690
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005691 If {object} is a |List| return the lowest index where the item
5692 has a value equal to {expr}. There is no automatic
5693 conversion, so the String "4" is different from the Number 4.
5694 And the number 4 is different from the Float 4.0. The value
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005695 of 'ignorecase' is not used here, case matters as indicated by
5696 the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005697
5698 If {object} is |Blob| return the lowest index where the byte
5699 value is equal to {expr}.
5700
5701 If {start} is given then start looking at the item with index
5702 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005703
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005704 When {ic} is given and it is |TRUE|, ignore case. Otherwise
5705 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005706
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005707 -1 is returned when {expr} is not found in {object}.
5708 Example: >
5709 :let idx = index(words, "the")
5710 :if index(numbers, 123) >= 0
5711
5712< Can also be used as a |method|: >
5713 GetObject()->index(what)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005714<
5715 Return type: |Number|
5716
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005717
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005718indexof({object}, {expr} [, {opts}]) *indexof()*
5719 Returns the index of an item in {object} where {expr} is
5720 v:true. {object} must be a |List| or a |Blob|.
5721
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005722 If {object} is a |List|, evaluate {expr} for each item in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005723 List until the expression is v:true and return the index of
5724 this item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005725
5726 If {object} is a |Blob| evaluate {expr} for each byte in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005727 Blob until the expression is v:true and return the index of
5728 this byte.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005729
5730 {expr} must be a |string| or |Funcref|.
5731
5732 If {expr} is a |string|: If {object} is a |List|, inside
5733 {expr} |v:key| has the index of the current List item and
5734 |v:val| has the value of the item. If {object} is a |Blob|,
5735 inside {expr} |v:key| has the index of the current byte and
5736 |v:val| has the byte value.
5737
5738 If {expr} is a |Funcref| it must take two arguments:
5739 1. the key or the index of the current item.
5740 2. the value of the current item.
5741 The function must return |TRUE| if the item is found and the
5742 search should stop.
5743
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005744 The optional argument {opts} is a Dict and supports the
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005745 following items:
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005746 startidx start evaluating {expr} at the item with this
5747 index; may be negative for an item relative to
5748 the end
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005749 Returns -1 when {expr} evaluates to v:false for all the items.
5750 Example: >
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005751 :let l = [#{n: 10}, #{n: 20}, #{n: 30}]
5752 :echo indexof(l, "v:val.n == 20")
5753 :echo indexof(l, {i, v -> v.n == 30})
5754 :echo indexof(l, "v:val.n == 20", #{startidx: 1})
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005755
5756< Can also be used as a |method|: >
5757 mylist->indexof(expr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005758<
5759 Return type: |Number|
5760
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005761
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005762input({prompt} [, {text} [, {completion}]]) *input()*
5763 The result is a String, which is whatever the user typed on
5764 the command-line. The {prompt} argument is either a prompt
5765 string, or a blank string (for no prompt). A '\n' can be used
5766 in the prompt to start a new line.
5767 The highlighting set with |:echohl| is used for the prompt.
5768 The input is entered just like a command-line, with the same
5769 editing commands and mappings. There is a separate history
5770 for lines typed for input().
5771 Example: >
5772 :if input("Coffee or beer? ") == "beer"
5773 : echo "Cheers!"
5774 :endif
5775<
5776 If the optional {text} argument is present and not empty, this
5777 is used for the default reply, as if the user typed this.
5778 Example: >
5779 :let color = input("Color? ", "white")
5780
5781< The optional {completion} argument specifies the type of
5782 completion supported for the input. Without it completion is
5783 not performed. The supported completion types are the same as
5784 that can be supplied to a user-defined command using the
5785 "-complete=" argument. Refer to |:command-completion| for
5786 more information. Example: >
5787 let fname = input("File: ", "", "file")
5788<
5789 NOTE: This function must not be used in a startup file, for
5790 the versions that only run in GUI mode (e.g., the Win32 GUI).
5791 Note: When input() is called from within a mapping it will
5792 consume remaining characters from that mapping, because a
5793 mapping is handled like the characters were typed.
5794 Use |inputsave()| before input() and |inputrestore()|
5795 after input() to avoid that. Another solution is to avoid
5796 that further characters follow in the mapping, e.g., by using
5797 |:execute| or |:normal|.
5798
5799 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005800 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005801 :function GetFoo()
5802 : call inputsave()
5803 : let g:Foo = input("enter search pattern: ")
5804 : call inputrestore()
5805 :endfunction
5806
5807< Can also be used as a |method|: >
5808 GetPrompt()->input()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005809<
5810 Return type: |String|
5811
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005812
5813inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
5814 Like |input()|, but when the GUI is running and text dialogs
5815 are supported, a dialog window pops up to input the text.
5816 Example: >
5817 :let n = inputdialog("value for shiftwidth", shiftwidth())
5818 :if n != ""
5819 : let &sw = n
5820 :endif
5821< When the dialog is cancelled {cancelreturn} is returned. When
5822 omitted an empty string is returned.
5823 Hitting <Enter> works like pressing the OK button. Hitting
5824 <Esc> works like pressing the Cancel button.
5825 NOTE: Command-line completion is not supported.
5826
5827 Can also be used as a |method|: >
5828 GetPrompt()->inputdialog()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005829<
5830 Return type: |String|
5831
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005832
5833inputlist({textlist}) *inputlist()*
5834 {textlist} must be a |List| of strings. This |List| is
5835 displayed, one string per line. The user will be prompted to
5836 enter a number, which is returned.
5837 The user can also select an item by clicking on it with the
5838 mouse, if the mouse is enabled in the command line ('mouse' is
5839 "a" or includes "c"). For the first string 0 is returned.
5840 When clicking above the first item a negative number is
5841 returned. When clicking on the prompt one more than the
5842 length of {textlist} is returned.
5843 Make sure {textlist} has less than 'lines' entries, otherwise
5844 it won't work. It's a good idea to put the entry number at
5845 the start of the string. And put a prompt in the first item.
5846 Example: >
5847 let color = inputlist(['Select color:', '1. red',
5848 \ '2. green', '3. blue'])
5849
5850< Can also be used as a |method|: >
5851 GetChoices()->inputlist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005852<
5853 Return type: |Number|
5854
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005855
5856inputrestore() *inputrestore()*
5857 Restore typeahead that was saved with a previous |inputsave()|.
5858 Should be called the same number of times inputsave() is
5859 called. Calling it more often is harmless though.
5860 Returns TRUE when there is nothing to restore, FALSE otherwise.
5861
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005862 Return type: |Number|
5863
5864
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005865inputsave() *inputsave()*
5866 Preserve typeahead (also from mappings) and clear it, so that
5867 a following prompt gets input from the user. Should be
5868 followed by a matching inputrestore() after the prompt. Can
5869 be used several times, in which case there must be just as
5870 many inputrestore() calls.
5871 Returns TRUE when out of memory, FALSE otherwise.
5872
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005873 Return type: |Number|
5874
5875
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005876inputsecret({prompt} [, {text}]) *inputsecret()*
5877 This function acts much like the |input()| function with but
5878 two exceptions:
5879 a) the user's response will be displayed as a sequence of
5880 asterisks ("*") thereby keeping the entry secret, and
5881 b) the user's response will not be recorded on the input
5882 |history| stack.
5883 The result is a String, which is whatever the user actually
5884 typed on the command-line in response to the issued prompt.
5885 NOTE: Command-line completion is not supported.
5886
5887 Can also be used as a |method|: >
5888 GetPrompt()->inputsecret()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005889<
5890 Return type: |String|
5891
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005892
5893insert({object}, {item} [, {idx}]) *insert()*
5894 When {object} is a |List| or a |Blob| insert {item} at the start
5895 of it.
5896
5897 If {idx} is specified insert {item} before the item with index
5898 {idx}. If {idx} is zero it goes before the first item, just
5899 like omitting {idx}. A negative {idx} is also possible, see
5900 |list-index|. -1 inserts just before the last item.
5901
5902 Returns the resulting |List| or |Blob|. Examples: >
5903 :let mylist = insert([2, 3, 5], 1)
5904 :call insert(mylist, 4, -1)
5905 :call insert(mylist, 6, len(mylist))
5906< The last example can be done simpler with |add()|.
5907 Note that when {item} is a |List| it is inserted as a single
5908 item. Use |extend()| to concatenate |Lists|.
5909
5910 Can also be used as a |method|: >
5911 mylist->insert(item)
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005912<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005913 Return type: |Number|
5914
5915
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005916 *instanceof()* *E614* *E616* *E693*
5917instanceof({object}, {class})
5918 The result is a Number, which is |TRUE| when the {object}
Ernie Rael2025af12023-12-12 16:58:00 +01005919 argument is a direct or indirect instance of a |Class|,
5920 |Interface|, or class |:type| alias specified by {class}.
5921 If {class} is varargs, the function returns |TRUE| when
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005922 {object} is an instance of any of the specified classes.
LemonBoyafe04662023-08-23 21:08:11 +02005923 Example: >
Ernie Rael2025af12023-12-12 16:58:00 +01005924 instanceof(animal, Dog, Cat)
LemonBoyafe04662023-08-23 21:08:11 +02005925
5926< Can also be used as a |method|: >
5927 myobj->instanceof(mytype)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005928<
5929 Return type: |Number|
LemonBoyafe04662023-08-23 21:08:11 +02005930
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005931interrupt() *interrupt()*
5932 Interrupt script execution. It works more or less like the
5933 user typing CTRL-C, most commands won't execute and control
5934 returns to the user. This is useful to abort execution
5935 from lower down, e.g. in an autocommand. Example: >
5936 :function s:check_typoname(file)
5937 : if fnamemodify(a:file, ':t') == '['
5938 : echomsg 'Maybe typo'
5939 : call interrupt()
5940 : endif
5941 :endfunction
5942 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005943<
5944 Return type: void
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005945
5946invert({expr}) *invert()*
5947 Bitwise invert. The argument is converted to a number. A
5948 List, Dict or Float argument causes an error. Example: >
5949 :let bits = invert(bits)
5950< Can also be used as a |method|: >
5951 :let bits = bits->invert()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005952<
5953 Return type: |Number|
5954
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005955
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005956isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01005957 The result is a Number, which is |TRUE| when {path} is an
5958 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005959 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01005960 On MS-Windows, it is considered absolute when it starts with an
5961 optional drive prefix and is followed by a '\' or '/'. UNC paths
5962 are always absolute.
5963 Example: >
5964 echo isabsolutepath('/usr/share/') " 1
5965 echo isabsolutepath('./foobar') " 0
5966 echo isabsolutepath('C:\Windows') " 1
5967 echo isabsolutepath('foobar') " 0
5968 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005969<
LemonBoydca1d402022-04-28 15:26:33 +01005970 Can also be used as a |method|: >
5971 GetName()->isabsolutepath()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005972<
5973 Return type: |Number|
LemonBoydca1d402022-04-28 15:26:33 +01005974
5975
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005976isdirectory({directory}) *isdirectory()*
5977 The result is a Number, which is |TRUE| when a directory
5978 with the name {directory} exists. If {directory} doesn't
5979 exist, or isn't a directory, the result is |FALSE|. {directory}
5980 is any expression, which is used as a String.
5981
5982 Can also be used as a |method|: >
5983 GetName()->isdirectory()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005984<
5985 Return type: |Number|
5986
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005987
5988isinf({expr}) *isinf()*
5989 Return 1 if {expr} is a positive infinity, or -1 a negative
5990 infinity, otherwise 0. >
5991 :echo isinf(1.0 / 0.0)
5992< 1 >
5993 :echo isinf(-1.0 / 0.0)
5994< -1
5995
5996 Can also be used as a |method|: >
5997 Compute()->isinf()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005998<
5999 Return type: |Number|
6000
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006001
6002islocked({expr}) *islocked()* *E786*
6003 The result is a Number, which is |TRUE| when {expr} is the
6004 name of a locked variable.
6005 The string argument {expr} must be the name of a variable,
6006 |List| item or |Dictionary| entry, not the variable itself!
6007 Example: >
6008 :let alist = [0, ['a', 'b'], 2, 3]
6009 :lockvar 1 alist
6010 :echo islocked('alist') " 1
6011 :echo islocked('alist[1]') " 0
6012
Bram Moolenaar9da17d72022-02-09 21:50:44 +00006013< When {expr} is a variable that does not exist -1 is returned.
6014 If {expr} uses a range, list or dict index that is out of
6015 range or does not exist you get an error message. Use
6016 |exists()| to check for existence.
6017 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006018
6019 Can also be used as a |method|: >
6020 GetName()->islocked()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006021<
6022 Return type: |Number|
6023
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006024
6025isnan({expr}) *isnan()*
6026 Return |TRUE| if {expr} is a float with value NaN. >
6027 echo isnan(0.0 / 0.0)
6028< 1
6029
6030 Can also be used as a |method|: >
6031 Compute()->isnan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006032<
6033 Return type: |Number|
6034
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006035
6036items({dict}) *items()*
6037 Return a |List| with all the key-value pairs of {dict}. Each
6038 |List| item is a list with two items: the key of a {dict}
6039 entry and the value of this entry. The |List| is in arbitrary
6040 order. Also see |keys()| and |values()|.
6041 Example: >
6042 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006043 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006044 endfor
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01006045<
6046 A List or a String argument is also supported. In these
6047 cases, items() returns a List with the index and the value at
6048 the index.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006049
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01006050 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006051 mydict->items()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006052<
6053 Return type: list<list<any>> or list<any>
6054
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006055
6056job_ functions are documented here: |job-functions-details|
6057
6058
6059join({list} [, {sep}]) *join()*
6060 Join the items in {list} together into one String.
6061 When {sep} is specified it is put in between the items. If
6062 {sep} is omitted a single space is used.
6063 Note that {sep} is not added at the end. You might want to
6064 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006065 let lines = join(mylist, "\n") .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006066< String items are used as-is. |Lists| and |Dictionaries| are
6067 converted into a string like with |string()|.
6068 The opposite function is |split()|.
6069
6070 Can also be used as a |method|: >
6071 mylist->join()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006072<
6073 Return type: |String|
6074
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006075
6076js_decode({string}) *js_decode()*
6077 This is similar to |json_decode()| with these differences:
6078 - Object key names do not have to be in quotes.
6079 - Strings can be in single quotes.
6080 - Empty items in an array (between two commas) are allowed and
6081 result in v:none items.
6082
6083 Can also be used as a |method|: >
6084 ReadObject()->js_decode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006085<
6086 Return type: any, depending on {varname}
6087
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006088
6089js_encode({expr}) *js_encode()*
6090 This is similar to |json_encode()| with these differences:
6091 - Object key names are not in quotes.
6092 - v:none items in an array result in an empty item between
6093 commas.
6094 For example, the Vim object:
6095 [1,v:none,{"one":1},v:none] ~
6096 Will be encoded as:
6097 [1,,{one:1},,] ~
6098 While json_encode() would produce:
6099 [1,null,{"one":1},null] ~
6100 This encoding is valid for JavaScript. It is more efficient
6101 than JSON, especially when using an array with optional items.
6102
6103 Can also be used as a |method|: >
6104 GetObject()->js_encode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006105<
6106 Return type: |String|
6107
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006108
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00006109json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006110 This parses a JSON formatted string and returns the equivalent
6111 in Vim values. See |json_encode()| for the relation between
6112 JSON and Vim values.
6113 The decoding is permissive:
6114 - A trailing comma in an array and object is ignored, e.g.
6115 "[1, 2, ]" is the same as "[1, 2]".
6116 - Integer keys are accepted in objects, e.g. {1:2} is the
6117 same as {"1":2}.
6118 - More floating point numbers are recognized, e.g. "1." for
6119 "1.0", or "001.2" for "1.2". Special floating point values
6120 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
6121 are accepted.
6122 - Leading zeroes in integer numbers are ignored, e.g. "012"
6123 for "12" or "-012" for "-12".
6124 - Capitalization is ignored in literal names null, true or
6125 false, e.g. "NULL" for "null", "True" for "true".
6126 - Control characters U+0000 through U+001F which are not
6127 escaped in strings are accepted, e.g. " " (tab
6128 character in string) for "\t".
6129 - An empty JSON expression or made of only spaces is accepted
6130 and results in v:none.
6131 - Backslash in an invalid 2-character sequence escape is
6132 ignored, e.g. "\a" is decoded as "a".
6133 - A correct surrogate pair in JSON strings should normally be
6134 a 12 character sequence such as "\uD834\uDD1E", but
6135 json_decode() silently accepts truncated surrogate pairs
6136 such as "\uD834" or "\uD834\u"
6137 *E938*
6138 A duplicate key in an object, valid in rfc7159, is not
6139 accepted by json_decode() as the result must be a valid Vim
6140 type, e.g. this fails: {"a":"b", "a":"c"}
6141
6142 Can also be used as a |method|: >
6143 ReadObject()->json_decode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006144<
6145 Return type: any, depending on {varname}
6146
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006147
6148json_encode({expr}) *json_encode()*
6149 Encode {expr} as JSON and return this as a string.
6150 The encoding is specified in:
6151 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00006152 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006153 |Number| decimal number
6154 |Float| floating point number
6155 Float nan "NaN"
6156 Float inf "Infinity"
6157 Float -inf "-Infinity"
6158 |String| in double quotes (possibly null)
6159 |Funcref| not possible, error
6160 |List| as an array (possibly null); when
6161 used recursively: []
6162 |Dict| as an object (possibly null); when
6163 used recursively: {}
6164 |Blob| as an array of the individual bytes
6165 v:false "false"
6166 v:true "true"
6167 v:none "null"
6168 v:null "null"
6169 Note that NaN and Infinity are passed on as values. This is
6170 missing in the JSON standard, but several implementations do
6171 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006172 If a string contains an illegal character then the replacement
6173 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006174
6175 Can also be used as a |method|: >
6176 GetObject()->json_encode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006177<
6178 Return type: |String|
6179
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006180
6181keys({dict}) *keys()*
6182 Return a |List| with all the keys of {dict}. The |List| is in
6183 arbitrary order. Also see |items()| and |values()|.
6184
6185 Can also be used as a |method|: >
6186 mydict->keys()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006187<
6188 Return type: list<string>
6189
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006190
zeertzjqcdc83932022-09-12 13:38:41 +01006191keytrans({string}) *keytrans()*
6192 Turn the internal byte representation of keys into a form that
6193 can be used for |:map|. E.g. >
6194 :let xx = "\<C-Home>"
6195 :echo keytrans(xx)
6196< <C-Home>
6197
6198 Can also be used as a |method|: >
6199 "\<C-Home>"->keytrans()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006200<
6201 Return type: |String|
zeertzjqcdc83932022-09-12 13:38:41 +01006202
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006203
6204len({expr}) *len()* *E701*
6205 The result is a Number, which is the length of the argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006206 When {expr} is a String or a Number the length in bytes is
6207 used, as with |strlen()|.
6208 When {expr} is a |List| the number of items in the |List| is
6209 returned.
6210 When {expr} is a |Blob| the number of bytes is returned.
6211 When {expr} is a |Dictionary| the number of entries in the
6212 |Dictionary| is returned.
mityu7f0bba22024-03-29 10:14:41 +01006213 When {expr} is an |Object|, invokes the len() method in the
6214 object (if present) to get the length (|object-len()|).
6215 Otherwise returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006216
6217 Can also be used as a |method|: >
6218 mylist->len()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006219<
6220 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006221
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006222
6223 *libcall()* *E364* *E368*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006224libcall({libname}, {funcname}, {argument})
6225 Call function {funcname} in the run-time library {libname}
6226 with single argument {argument}.
6227 This is useful to call functions in a library that you
6228 especially made to be used with Vim. Since only one argument
6229 is possible, calling standard library functions is rather
6230 limited.
6231 The result is the String returned by the function. If the
6232 function returns NULL, this will appear as an empty string ""
6233 to Vim.
6234 If the function returns a number, use libcallnr()!
6235 If {argument} is a number, it is passed to the function as an
6236 int; if {argument} is a string, it is passed as a
6237 null-terminated string.
6238 This function will fail in |restricted-mode|.
6239
6240 libcall() allows you to write your own 'plug-in' extensions to
6241 Vim without having to recompile the program. It is NOT a
6242 means to call system functions! If you try to do so Vim will
6243 very probably crash.
6244
6245 For Win32, the functions you write must be placed in a DLL
6246 and use the normal C calling convention (NOT Pascal which is
6247 used in Windows System DLLs). The function must take exactly
6248 one parameter, either a character pointer or a long integer,
6249 and must return a character pointer or NULL. The character
6250 pointer returned must point to memory that will remain valid
6251 after the function has returned (e.g. in static data in the
6252 DLL). If it points to allocated memory, that memory will
6253 leak away. Using a static buffer in the function should work,
6254 it's then freed when the DLL is unloaded.
6255
6256 WARNING: If the function returns a non-valid pointer, Vim may
6257 crash! This also happens if the function returns a number,
6258 because Vim thinks it's a pointer.
6259 For Win32 systems, {libname} should be the filename of the DLL
6260 without the ".DLL" suffix. A full path is only required if
6261 the DLL is not in the usual places.
6262 For Unix: When compiling your own plugins, remember that the
6263 object code must be compiled as position-independent ('PIC').
6264 {only in Win32 and some Unix versions, when the |+libcall|
6265 feature is present}
6266 Examples: >
6267 :echo libcall("libc.so", "getenv", "HOME")
6268
6269< Can also be used as a |method|, the base is passed as the
6270 third argument: >
6271 GetValue()->libcall("libc.so", "getenv")
6272<
6273 *libcallnr()*
6274libcallnr({libname}, {funcname}, {argument})
6275 Just like |libcall()|, but used for a function that returns an
6276 int instead of a string.
6277 {only in Win32 on some Unix versions, when the |+libcall|
6278 feature is present}
6279 Examples: >
6280 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
6281 :call libcallnr("libc.so", "printf", "Hello World!\n")
6282 :call libcallnr("libc.so", "sleep", 10)
6283<
6284 Can also be used as a |method|, the base is passed as the
6285 third argument: >
6286 GetValue()->libcallnr("libc.so", "printf")
6287<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006288 Return type: |String|
6289
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006290
6291line({expr} [, {winid}]) *line()*
6292 The result is a Number, which is the line number of the file
6293 position given with {expr}. The {expr} argument is a string.
zeertzjq02f3eba2024-06-12 20:45:24 +02006294 See |getpos()| for accepted positions.
6295
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006296 To get the column number use |col()|. To get both use
6297 |getpos()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02006298
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006299 With the optional {winid} argument the values are obtained for
6300 that window instead of the current window.
zeertzjq02f3eba2024-06-12 20:45:24 +02006301
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006302 Returns 0 for invalid values of {expr} and {winid}.
zeertzjq02f3eba2024-06-12 20:45:24 +02006303
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006304 Examples: >
6305 line(".") line number of the cursor
6306 line(".", winid) idem, in window "winid"
6307 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006308 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006309<
6310 To jump to the last known position when opening a file see
6311 |last-position-jump|.
6312
6313 Can also be used as a |method|: >
6314 GetValue()->line()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006315<
6316 Return type: |Number|
6317
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006318
6319line2byte({lnum}) *line2byte()*
6320 Return the byte count from the start of the buffer for line
6321 {lnum}. This includes the end-of-line character, depending on
6322 the 'fileformat' option for the current buffer. The first
6323 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
6324 This can also be used to get the byte count for the line just
6325 below the last line: >
6326 line2byte(line("$") + 1)
6327< This is the buffer size plus one. If 'fileencoding' is empty
6328 it is the file size plus one. {lnum} is used like with
6329 |getline()|. When {lnum} is invalid, or the |+byte_offset|
6330 feature has been disabled at compile time, -1 is returned.
6331 Also see |byte2line()|, |go| and |:goto|.
6332
6333 Can also be used as a |method|: >
6334 GetLnum()->line2byte()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006335<
6336 Return type: |Number|
6337
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006338
6339lispindent({lnum}) *lispindent()*
6340 Get the amount of indent for line {lnum} according the lisp
6341 indenting rules, as with 'lisp'.
6342 The indent is counted in spaces, the value of 'tabstop' is
6343 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01006344 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006345 error is given.
6346
6347 Can also be used as a |method|: >
6348 GetLnum()->lispindent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006349<
6350 Return type: |Number|
6351
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006352
6353list2blob({list}) *list2blob()*
6354 Return a Blob concatenating all the number values in {list}.
6355 Examples: >
6356 list2blob([1, 2, 3, 4]) returns 0z01020304
6357 list2blob([]) returns 0z
6358< Returns an empty Blob on error. If one of the numbers is
6359 negative or more than 255 error *E1239* is given.
6360
6361 |blob2list()| does the opposite.
6362
6363 Can also be used as a |method|: >
6364 GetList()->list2blob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006365<
6366 Return type: |Blob|
6367
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006368
6369list2str({list} [, {utf8}]) *list2str()*
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006370 Convert each number in {list} to a character string and
6371 concatenates them all. Examples: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006372 list2str([32]) returns " "
6373 list2str([65, 66, 67]) returns "ABC"
6374< The same can be done (slowly) with: >
6375 join(map(list, {nr, val -> nr2char(val)}), '')
6376< |str2list()| does the opposite.
6377
6378 When {utf8} is omitted or zero, the current 'encoding' is used.
6379 When {utf8} is TRUE, always return UTF-8 characters.
6380 With UTF-8 composing characters work as expected: >
6381 list2str([97, 769]) returns "á"
6382<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006383 Returns an empty string on error.
6384
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006385 Can also be used as a |method|: >
6386 GetList()->list2str()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006387<
6388 Return type: |String|
6389
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006390
6391listener_add({callback} [, {buf}]) *listener_add()*
6392 Add a callback function that will be invoked when changes have
6393 been made to buffer {buf}.
6394 {buf} refers to a buffer name or number. For the accepted
6395 values, see |bufname()|. When {buf} is omitted the current
6396 buffer is used.
6397 Returns a unique ID that can be passed to |listener_remove()|.
6398
6399 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00006400 bufnr the buffer that was changed
6401 start first changed line number
6402 end first line number below the change
6403 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006404 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00006405 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006406
6407 Example: >
6408 func Listener(bufnr, start, end, added, changes)
6409 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
6410 endfunc
6411 call listener_add('Listener', bufnr)
6412
Bram Moolenaar944697a2022-02-20 19:48:20 +00006413< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006414 dictionary with these entries:
6415 lnum the first line number of the change
6416 end the first line below the change
6417 added number of lines added; negative if lines were
6418 deleted
6419 col first column in "lnum" that was affected by
6420 the change; one if unknown or the whole line
6421 was affected; this is a byte index, first
6422 character has a value of one.
Bram Moolenaar3c053a12022-10-16 13:11:12 +01006423 When lines are inserted (not when a line is split, e.g. by
6424 typing CR in Insert mode) the values are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006425 lnum line above which the new line is added
6426 end equal to "lnum"
6427 added number of lines inserted
6428 col 1
6429 When lines are deleted the values are:
6430 lnum the first deleted line
6431 end the line below the first deleted line, before
6432 the deletion was done
6433 added negative, number of lines deleted
6434 col 1
6435 When lines are changed:
6436 lnum the first changed line
6437 end the line below the last changed line
6438 added 0
6439 col first column with a change or 1
6440
6441 The entries are in the order the changes were made, thus the
6442 most recent change is at the end. The line numbers are valid
6443 when the callback is invoked, but later changes may make them
6444 invalid, thus keeping a copy for later might not work.
6445
6446 The {callback} is invoked just before the screen is updated,
6447 when |listener_flush()| is called or when a change is being
6448 made that changes the line count in a way it causes a line
6449 number in the list of changes to become invalid.
6450
6451 The {callback} is invoked with the text locked, see
6452 |textlock|. If you do need to make changes to the buffer, use
6453 a timer to do this later |timer_start()|.
6454
6455 The {callback} is not invoked when the buffer is first loaded.
6456 Use the |BufReadPost| autocmd event to handle the initial text
6457 of a buffer.
6458 The {callback} is also not invoked when the buffer is
6459 unloaded, use the |BufUnload| autocmd event for that.
6460
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006461 Returns zero if {callback} or {buf} is invalid.
6462
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006463 Can also be used as a |method|, the base is passed as the
6464 second argument: >
6465 GetBuffer()->listener_add(callback)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006466<
6467 Return type: |Number|
6468
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006469
6470listener_flush([{buf}]) *listener_flush()*
6471 Invoke listener callbacks for buffer {buf}. If there are no
6472 pending changes then no callbacks are invoked.
6473
6474 {buf} refers to a buffer name or number. For the accepted
6475 values, see |bufname()|. When {buf} is omitted the current
6476 buffer is used.
6477
6478 Can also be used as a |method|: >
6479 GetBuffer()->listener_flush()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006480<
6481 Return type: |Number|
6482
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006483
6484listener_remove({id}) *listener_remove()*
6485 Remove a listener previously added with listener_add().
6486 Returns FALSE when {id} could not be found, TRUE when {id} was
6487 removed.
6488
6489 Can also be used as a |method|: >
6490 GetListenerId()->listener_remove()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006491<
6492 Return type: |Number|
6493
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006494
6495localtime() *localtime()*
6496 Return the current time, measured as seconds since 1st Jan
6497 1970. See also |strftime()|, |strptime()| and |getftime()|.
6498
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006499 Return type: |Number|
6500
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006501
6502log({expr}) *log()*
6503 Return the natural logarithm (base e) of {expr} as a |Float|.
6504 {expr} must evaluate to a |Float| or a |Number| in the range
6505 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006506 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006507 Examples: >
6508 :echo log(10)
6509< 2.302585 >
6510 :echo log(exp(5))
6511< 5.0
6512
6513 Can also be used as a |method|: >
6514 Compute()->log()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006515<
6516 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006517
6518
6519log10({expr}) *log10()*
6520 Return the logarithm of Float {expr} to base 10 as a |Float|.
6521 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006522 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006523 Examples: >
6524 :echo log10(1000)
6525< 3.0 >
6526 :echo log10(0.01)
6527< -2.0
6528
6529 Can also be used as a |method|: >
6530 Compute()->log10()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006531<
6532 Return type: |Float|
6533
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006534
6535luaeval({expr} [, {expr}]) *luaeval()*
6536 Evaluate Lua expression {expr} and return its result converted
6537 to Vim data structures. Second {expr} may hold additional
6538 argument accessible as _A inside first {expr}.
6539 Strings are returned as they are.
6540 Boolean objects are converted to numbers.
Bram Moolenaar73e28dc2022-09-17 21:08:33 +01006541 Numbers are converted to |Float| values.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006542 Dictionaries and lists obtained by vim.eval() are returned
6543 as-is.
6544 Other objects are returned as zero without any errors.
6545 See |lua-luaeval| for more details.
6546 Note that in a `:def` function local variables are not visible
6547 to {expr}.
6548
6549 Can also be used as a |method|: >
6550 GetExpr()->luaeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006551<
6552 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006553
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006554 {only available when compiled with the |+lua| feature}
6555
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006556
6557map({expr1}, {expr2}) *map()*
6558 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00006559 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006560 item in {expr1} with the result of evaluating {expr2}.
6561 For a |Blob| each byte is replaced.
6562 For a |String|, each character, including composing
6563 characters, is replaced.
6564 If the item type changes you may want to use |mapnew()| to
6565 create a new List or Dictionary. This is required when using
6566 Vim9 script.
6567
6568 {expr2} must be a |String| or |Funcref|.
6569
6570 If {expr2} is a |String|, inside {expr2} |v:val| has the value
6571 of the current item. For a |Dictionary| |v:key| has the key
6572 of the current item and for a |List| |v:key| has the index of
6573 the current item. For a |Blob| |v:key| has the index of the
6574 current byte. For a |String| |v:key| has the index of the
6575 current character.
6576 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006577 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006578< This puts "> " before and " <" after each item in "mylist".
6579
6580 Note that {expr2} is the result of an expression and is then
6581 used as an expression again. Often it is good to use a
6582 |literal-string| to avoid having to double backslashes. You
6583 still have to double ' quotes
6584
6585 If {expr2} is a |Funcref| it is called with two arguments:
6586 1. The key or the index of the current item.
6587 2. the value of the current item.
Bram Moolenaarb59ae592022-11-23 23:46:31 +00006588 With a legacy script lambda you don't get an error if it only
6589 accepts one argument, but with a Vim9 lambda you get "E1106:
6590 One argument too many", the number of arguments must match.
6591
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006592 The function must return the new value of the item. Example
6593 that changes each value by "key-value": >
6594 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006595 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006596 endfunc
6597 call map(myDict, function('KeyValue'))
6598< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006599 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006600< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006601 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006602< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006603 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006604<
6605 The operation is done in-place for a |List| and |Dictionary|.
6606 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006607 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006608
6609< Returns {expr1}, the |List| or |Dictionary| that was filtered,
6610 or a new |Blob| or |String|.
6611 When an error is encountered while evaluating {expr2} no
6612 further items in {expr1} are processed.
6613 When {expr2} is a Funcref errors inside a function are ignored,
6614 unless it was defined with the "abort" flag.
6615
6616 Can also be used as a |method|: >
6617 mylist->map(expr2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006618<
6619 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
6620 depending on {expr1}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006621
6622
6623maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
6624 When {dict} is omitted or zero: Return the rhs of mapping
6625 {name} in mode {mode}. The returned String has special
6626 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01006627 listing. When {dict} is TRUE a dictionary is returned, see
6628 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006629
6630 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006631 returned if {dict} is FALSE, otherwise returns an empty Dict.
6632 When the mapping for {name} is empty, then "<Nop>" is
6633 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006634
6635 The {name} can have special key names, like in the ":map"
6636 command.
6637
6638 {mode} can be one of these strings:
6639 "n" Normal
6640 "v" Visual (including Select)
6641 "o" Operator-pending
6642 "i" Insert
6643 "c" Cmd-line
6644 "s" Select
6645 "x" Visual
6646 "l" langmap |language-mapping|
6647 "t" Terminal-Job
6648 "" Normal, Visual and Operator-pending
6649 When {mode} is omitted, the modes for "" are used.
6650
6651 When {abbr} is there and it is |TRUE| use abbreviations
6652 instead of mappings.
6653
6654 When {dict} is there and it is |TRUE| return a dictionary
6655 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01006656 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006657 "lhs" The {lhs} of the mapping as it would be typed
6658 "lhsraw" The {lhs} of the mapping as raw bytes
6659 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
6660 form, only present when it differs from "lhsraw"
6661 "rhs" The {rhs} of the mapping as typed.
6662 "silent" 1 for a |:map-silent| mapping, else 0.
6663 "noremap" 1 if the {rhs} of the mapping is not remappable.
6664 "script" 1 if mapping was defined with <script>.
6665 "expr" 1 for an expression mapping (|:map-<expr>|).
6666 "buffer" 1 for a buffer local mapping (|:map-local|).
6667 "mode" Modes for which the mapping is defined. In
6668 addition to the modes mentioned above, these
6669 characters will be used:
6670 " " Normal, Visual and Operator-pending
6671 "!" Insert and Commandline mode
6672 (|mapmode-ic|)
6673 "sid" The script local ID, used for <sid> mappings
Bram Moolenaar71badf92023-04-22 22:40:14 +01006674 (|<SID>|). Negative for special contexts.
Bram Moolenaara9528b32022-01-18 20:51:35 +00006675 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01006676 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006677 "lnum" The line number in "sid", zero if unknown.
6678 "nowait" Do not wait for other, longer mappings.
6679 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01006680 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01006681 "mode_bits" Vim's internal binary representation of "mode".
6682 |mapset()| ignores this; only "mode" is used.
6683 See |maplist()| for usage examples. The values
6684 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006685
6686 The dictionary can be used to restore a mapping with
6687 |mapset()|.
6688
6689 The mappings local to the current buffer are checked first,
6690 then the global mappings.
6691 This function can be used to map a key even when it's already
6692 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006693 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006694
6695< Can also be used as a |method|: >
6696 GetKey()->maparg('n')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006697<
6698 Return type: |String| or dict<any> depending on {dict}
6699
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006700
6701mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
6702 Check if there is a mapping that matches with {name} in mode
6703 {mode}. See |maparg()| for {mode} and special names in
6704 {name}.
6705 When {abbr} is there and it is |TRUE| use abbreviations
6706 instead of mappings.
6707 A match happens with a mapping that starts with {name} and
6708 with a mapping which is equal to the start of {name}.
6709
6710 matches mapping "a" "ab" "abc" ~
6711 mapcheck("a") yes yes yes
6712 mapcheck("abc") yes yes yes
6713 mapcheck("ax") yes no no
6714 mapcheck("b") no no no
6715
6716 The difference with maparg() is that mapcheck() finds a
6717 mapping that matches with {name}, while maparg() only finds a
6718 mapping for {name} exactly.
6719 When there is no mapping that starts with {name}, an empty
6720 String is returned. If there is one, the RHS of that mapping
6721 is returned. If there are several mappings that start with
6722 {name}, the RHS of one of them is returned. This will be
6723 "<Nop>" if the RHS is empty.
6724 The mappings local to the current buffer are checked first,
6725 then the global mappings.
6726 This function can be used to check if a mapping can be added
6727 without being ambiguous. Example: >
6728 :if mapcheck("_vv") == ""
6729 : map _vv :set guifont=7x13<CR>
6730 :endif
6731< This avoids adding the "_vv" mapping when there already is a
6732 mapping for "_v" or for "_vvv".
6733
6734 Can also be used as a |method|: >
6735 GetKey()->mapcheck('n')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006736<
6737 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006738
6739
Ernie Rael09661202022-04-25 14:40:44 +01006740maplist([{abbr}]) *maplist()*
6741 Returns a |List| of all mappings. Each List item is a |Dict|,
6742 the same as what is returned by |maparg()|, see
6743 |mapping-dict|. When {abbr} is there and it is |TRUE| use
6744 abbreviations instead of mappings.
6745
6746 Example to show all mappings with 'MultiMatch' in rhs: >
6747 vim9script
6748 echo maplist()->filter(
6749 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01006750< It can be tricky to find mappings for particular |:map-modes|.
6751 |mapping-dict|'s "mode_bits" can simplify this. For example,
6752 the mode_bits for Normal, Insert or Command-line modes are
6753 0x19. To find all the mappings available in those modes you
6754 can do: >
6755 vim9script
6756 var saved_maps = []
6757 for m in maplist()
6758 if and(m.mode_bits, 0x19) != 0
6759 saved_maps->add(m)
6760 endif
6761 endfor
6762 echo saved_maps->mapnew((_, m) => m.lhs)
6763< The values of the mode_bits are defined in Vim's src/vim.h
6764 file and they can be discovered at runtime using
6765 |:map-commands| and "maplist()". Example: >
6766 vim9script
6767 omap xyzzy <Nop>
6768 var op_bit = maplist()->filter(
6769 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
6770 ounmap xyzzy
6771 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006772<
6773 Return type: list<dict<any>>
Ernie Rael09661202022-04-25 14:40:44 +01006774
6775
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006776mapnew({expr1}, {expr2}) *mapnew()*
6777 Like |map()| but instead of replacing items in {expr1} a new
6778 List or Dictionary is created and returned. {expr1} remains
6779 unchanged. Items can still be changed by {expr2}, if you
6780 don't want that use |deepcopy()| first.
6781
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006782 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
6783 depending on {expr1}
6784
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006785
6786mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01006787mapset({dict})
6788 Restore a mapping from a dictionary, possibly returned by
6789 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
6790 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01006791 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01006792 feature allows copying mappings from one buffer to another.
6793 The dict.mode value may restore a single mapping that covers
6794 more than one mode, like with mode values of '!', ' ', 'nox',
6795 or 'v'. *E1276*
6796
6797 In the first form, {mode} and {abbr} should be the same as
6798 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006799 {mode} is used to define the mode in which the mapping is set,
6800 not the "mode" entry in {dict}.
6801 Example for saving and restoring a mapping: >
6802 let save_map = maparg('K', 'n', 0, 1)
6803 nnoremap K somethingelse
6804 ...
6805 call mapset('n', 0, save_map)
6806< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01006807 e.g. with `:map!`, you need to save/restore the mapping for
6808 all of them, when they might differ.
6809
6810 In the second form, with {dict} as the only argument, mode
6811 and abbr are taken from the dict.
6812 Example: >
6813 vim9script
6814 var save_maps = maplist()->filter(
6815 (_, m) => m.lhs == 'K')
6816 nnoremap K somethingelse
6817 cnoremap K somethingelse2
6818 # ...
6819 unmap K
6820 for d in save_maps
6821 mapset(d)
6822 endfor
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006823<
6824 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006825
6826
6827match({expr}, {pat} [, {start} [, {count}]]) *match()*
6828 When {expr} is a |List| then this returns the index of the
6829 first item where {pat} matches. Each item is used as a
6830 String, |Lists| and |Dictionaries| are used as echoed.
6831
6832 Otherwise, {expr} is used as a String. The result is a
6833 Number, which gives the index (byte offset) in {expr} where
6834 {pat} matches.
6835
6836 A match at the first character or |List| item returns zero.
6837 If there is no match -1 is returned.
6838
6839 For getting submatches see |matchlist()|.
6840 Example: >
6841 :echo match("testing", "ing") " results in 4
6842 :echo match([1, 'x'], '\a') " results in 1
6843< See |string-match| for how {pat} is used.
6844 *strpbrk()*
6845 Vim doesn't have a strpbrk() function. But you can do: >
6846 :let sepidx = match(line, '[.,;: \t]')
6847< *strcasestr()*
6848 Vim doesn't have a strcasestr() function. But you can add
6849 "\c" to the pattern to ignore case: >
6850 :let idx = match(haystack, '\cneedle')
6851<
6852 If {start} is given, the search starts from byte index
6853 {start} in a String or item {start} in a |List|.
6854 The result, however, is still the index counted from the
6855 first character/item. Example: >
6856 :echo match("testing", "ing", 2)
6857< result is again "4". >
6858 :echo match("testing", "ing", 4)
6859< result is again "4". >
6860 :echo match("testing", "t", 2)
6861< result is "3".
6862 For a String, if {start} > 0 then it is like the string starts
6863 {start} bytes later, thus "^" will match at {start}. Except
6864 when {count} is given, then it's like matches before the
6865 {start} byte are ignored (this is a bit complicated to keep it
6866 backwards compatible).
6867 For a String, if {start} < 0, it will be set to 0. For a list
6868 the index is counted from the end.
6869 If {start} is out of range ({start} > strlen({expr}) for a
6870 String or {start} > len({expr}) for a |List|) -1 is returned.
6871
6872 When {count} is given use the {count}'th match. When a match
6873 is found in a String the search for the next one starts one
6874 character further. Thus this example results in 1: >
6875 echo match("testing", "..", 0, 2)
6876< In a |List| the search continues in the next item.
6877 Note that when {count} is added the way {start} works changes,
6878 see above.
6879
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01006880 *match-pattern*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006881 See |pattern| for the patterns that are accepted.
6882 The 'ignorecase' option is used to set the ignore-caseness of
6883 the pattern. 'smartcase' is NOT used. The matching is always
6884 done like 'magic' is set and 'cpoptions' is empty.
6885 Note that a match at the start is preferred, thus when the
6886 pattern is using "*" (any number of matches) it tends to find
6887 zero matches at the start instead of a number of matches
6888 further down in the text.
6889
6890 Can also be used as a |method|: >
6891 GetText()->match('word')
6892 GetList()->match('word')
6893<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006894 Return type: |Number|
6895
6896
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00006897 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006898matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
6899 Defines a pattern to be highlighted in the current window (a
6900 "match"). It will be highlighted with {group}. Returns an
6901 identification number (ID), which can be used to delete the
6902 match using |matchdelete()|. The ID is bound to the window.
6903 Matching is case sensitive and magic, unless case sensitivity
6904 or magicness are explicitly overridden in {pattern}. The
6905 'magic', 'smartcase' and 'ignorecase' options are not used.
6906 The "Conceal" value is special, it causes the match to be
6907 concealed.
6908
6909 The optional {priority} argument assigns a priority to the
6910 match. A match with a high priority will have its
6911 highlighting overrule that of a match with a lower priority.
6912 A priority is specified as an integer (negative numbers are no
6913 exception). If the {priority} argument is not specified, the
6914 default priority is 10. The priority of 'hlsearch' is zero,
6915 hence all matches with a priority greater than zero will
6916 overrule it. Syntax highlighting (see 'syntax') is a separate
6917 mechanism, and regardless of the chosen priority a match will
6918 always overrule syntax highlighting.
6919
6920 The optional {id} argument allows the request for a specific
6921 match ID. If a specified ID is already taken, an error
6922 message will appear and the match will not be added. An ID
6923 is specified as a positive integer (zero excluded). IDs 1, 2
6924 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01006925 respectively. 3 is reserved for use by the |matchparen|
6926 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01006927 If the {id} argument is not specified or -1, |matchadd()|
Bram Moolenaar9f573a82022-09-29 13:50:08 +01006928 automatically chooses a free ID, which is at least 1000.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006929
6930 The optional {dict} argument allows for further custom
6931 values. Currently this is used to specify a match specific
6932 conceal character that will be shown for |hl-Conceal|
6933 highlighted matches. The dict can have the following members:
6934
6935 conceal Special character to show instead of the
6936 match (only for |hl-Conceal| highlighted
6937 matches, see |:syn-cchar|)
6938 window Instead of the current window use the
6939 window with this number or window ID.
6940
6941 The number of matches is not limited, as it is the case with
6942 the |:match| commands.
6943
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006944 Returns -1 on error.
6945
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006946 Example: >
6947 :highlight MyGroup ctermbg=green guibg=green
6948 :let m = matchadd("MyGroup", "TODO")
6949< Deletion of the pattern: >
6950 :call matchdelete(m)
6951
6952< A list of matches defined by |matchadd()| and |:match| are
6953 available from |getmatches()|. All matches can be deleted in
6954 one operation by |clearmatches()|.
6955
6956 Can also be used as a |method|: >
6957 GetGroup()->matchadd('TODO')
6958<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006959 Return type: |Number|
6960
6961
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006962 *matchaddpos()*
6963matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
6964 Same as |matchadd()|, but requires a list of positions {pos}
6965 instead of a pattern. This command is faster than |matchadd()|
Shane Harperc1b39842024-07-17 19:40:40 +02006966 because it does not handle regular expressions and it sets
6967 buffer line boundaries to redraw screen. It is supposed to be
6968 used when fast match additions and deletions are required, for
6969 example to highlight matching parentheses.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006970
6971 {pos} is a list of positions. Each position can be one of
6972 these:
6973 - A number. This whole line will be highlighted. The first
6974 line has number 1.
6975 - A list with one number, e.g., [23]. The whole line with this
6976 number will be highlighted.
6977 - A list with two numbers, e.g., [23, 11]. The first number is
6978 the line number, the second one is the column number (first
6979 column is 1, the value must correspond to the byte index as
6980 |col()| would return). The character at this position will
6981 be highlighted.
6982 - A list with three numbers, e.g., [23, 11, 3]. As above, but
6983 the third number gives the length of the highlight in bytes.
6984
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006985 Returns -1 on error.
6986
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006987 Example: >
6988 :highlight MyGroup ctermbg=green guibg=green
6989 :let m = matchaddpos("MyGroup", [[23, 24], 34])
6990< Deletion of the pattern: >
6991 :call matchdelete(m)
6992
6993< Matches added by |matchaddpos()| are returned by
6994 |getmatches()|.
6995
6996 Can also be used as a |method|: >
6997 GetGroup()->matchaddpos([23, 11])
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006998<
6999 Return type: |Number|
7000
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007001
7002matcharg({nr}) *matcharg()*
7003 Selects the {nr} match item, as set with a |:match|,
7004 |:2match| or |:3match| command.
7005 Return a |List| with two elements:
7006 The name of the highlight group used
7007 The pattern used.
7008 When {nr} is not 1, 2 or 3 returns an empty |List|.
7009 When there is no match item set returns ['', ''].
7010 This is useful to save and restore a |:match|.
7011 Highlighting matches using the |:match| commands are limited
7012 to three matches. |matchadd()| does not have this limitation.
7013
7014 Can also be used as a |method|: >
7015 GetMatch()->matcharg()
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007016<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007017 Return type: list<string>
7018
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007019 *matchbufline()*
7020matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])
7021 Returns the |List| of matches in lines from {lnum} to {end} in
7022 buffer {buf} where {pat} matches.
7023
7024 {lnum} and {end} can either be a line number or the string "$"
7025 to refer to the last line in {buf}.
7026
7027 The {dict} argument supports following items:
7028 submatches include submatch information (|/\(|)
7029
7030 For each match, a |Dict| with the following items is returned:
7031 byteidx starting byte index of the match
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007032 lnum line number where there is a match
7033 text matched string
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007034 Note that there can be multiple matches in a single line.
7035
7036 This function works only for loaded buffers. First call
7037 |bufload()| if needed.
7038
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007039 See |match-pattern| for information about the effect of some
7040 option settings on the pattern.
7041
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007042 When {buf} is not a valid buffer, the buffer is not loaded or
7043 {lnum} or {end} is not valid then an error is given and an
7044 empty |List| is returned.
7045
7046 Examples: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007047 " Assuming line 3 in buffer 5 contains "a"
7048 :echo matchbufline(5, '\<\k\+\>', 3, 3)
7049 [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
7050 " Assuming line 4 in buffer 10 contains "tik tok"
7051 :echo matchbufline(10, '\<\k\+\>', 1, 4)
7052 [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007053<
7054 If {submatch} is present and is v:true, then submatches like
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007055 "\1", "\2", etc. are also returned. Example: >
7056 " Assuming line 2 in buffer 2 contains "acd"
7057 :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007058 \ {'submatches': v:true})
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007059 [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007060< The "submatches" List always contains 9 items. If a submatch
7061 is not found, then an empty string is returned for that
7062 submatch.
7063
7064 Can also be used as a |method|: >
7065 GetBuffer()->matchbufline('mypat', 1, '$')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007066<
7067 Return type: list<dict<any>> or list<any>
7068
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007069
7070matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
7071 Deletes a match with ID {id} previously defined by |matchadd()|
7072 or one of the |:match| commands. Returns 0 if successful,
7073 otherwise -1. See example for |matchadd()|. All matches can
7074 be deleted in one operation by |clearmatches()|.
7075 If {win} is specified, use the window with this number or
7076 window ID instead of the current window.
7077
7078 Can also be used as a |method|: >
7079 GetMatch()->matchdelete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007080<
7081 Return type: |Number|
7082
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007083
7084matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
7085 Same as |match()|, but return the index of first character
7086 after the match. Example: >
7087 :echo matchend("testing", "ing")
7088< results in "7".
7089 *strspn()* *strcspn()*
7090 Vim doesn't have a strspn() or strcspn() function, but you can
7091 do it with matchend(): >
7092 :let span = matchend(line, '[a-zA-Z]')
7093 :let span = matchend(line, '[^a-zA-Z]')
7094< Except that -1 is returned when there are no matches.
7095
7096 The {start}, if given, has the same meaning as for |match()|. >
7097 :echo matchend("testing", "ing", 2)
7098< results in "7". >
7099 :echo matchend("testing", "ing", 5)
7100< result is "-1".
7101 When {expr} is a |List| the result is equal to |match()|.
7102
7103 Can also be used as a |method|: >
7104 GetText()->matchend('word')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007105<
7106 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007107
7108
7109matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
7110 If {list} is a list of strings, then returns a |List| with all
7111 the strings in {list} that fuzzy match {str}. The strings in
7112 the returned list are sorted based on the matching score.
7113
7114 The optional {dict} argument always supports the following
7115 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01007116 matchseq When this item is present return only matches
7117 that contain the characters in {str} in the
7118 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01007119 limit Maximum number of matches in {list} to be
7120 returned. Zero means no limit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007121
7122 If {list} is a list of dictionaries, then the optional {dict}
7123 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01007124 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007125 {str}. The value of this item should be a
7126 string.
7127 text_cb |Funcref| that will be called for every item
7128 in {list} to get the text for fuzzy matching.
7129 This should accept a dictionary item as the
7130 argument and return the text for that item to
7131 use for fuzzy matching.
7132
7133 {str} is treated as a literal string and regular expression
7134 matching is NOT supported. The maximum supported {str} length
7135 is 256.
7136
7137 When {str} has multiple words each separated by white space,
7138 then the list of strings that have all the words is returned.
7139
7140 If there are no matching strings or there is an error, then an
7141 empty list is returned. If length of {str} is greater than
7142 256, then returns an empty list.
7143
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01007144 When {limit} is given, matchfuzzy() will find up to this
7145 number of matches in {list} and return them in sorted order.
7146
Bram Moolenaar1588bc82022-03-08 21:35:07 +00007147 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007148 matching strings.
7149
7150 Example: >
7151 :echo matchfuzzy(["clay", "crow"], "cay")
7152< results in ["clay"]. >
7153 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
7154< results in a list of buffer names fuzzy matching "ndl". >
7155 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
7156< results in a list of buffer information dicts with buffer
7157 names fuzzy matching "ndl". >
7158 :echo getbufinfo()->matchfuzzy("spl",
7159 \ {'text_cb' : {v -> v.name}})
7160< results in a list of buffer information dicts with buffer
7161 names fuzzy matching "spl". >
7162 :echo v:oldfiles->matchfuzzy("test")
7163< results in a list of file names fuzzy matching "test". >
7164 :let l = readfile("buffer.c")->matchfuzzy("str")
7165< results in a list of lines in "buffer.c" fuzzy matching "str". >
7166 :echo ['one two', 'two one']->matchfuzzy('two one')
7167< results in ['two one', 'one two']. >
7168 :echo ['one two', 'two one']->matchfuzzy('two one',
7169 \ {'matchseq': 1})
7170< results in ['two one'].
7171
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007172 Return type: list<string> or list<any>
7173
7174
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007175matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
7176 Same as |matchfuzzy()|, but returns the list of matched
7177 strings, the list of character positions where characters
7178 in {str} matches and a list of matching scores. You can
7179 use |byteidx()| to convert a character position to a byte
7180 position.
7181
7182 If {str} matches multiple times in a string, then only the
7183 positions for the best match is returned.
7184
7185 If there are no matching strings or there is an error, then a
7186 list with three empty list items is returned.
7187
7188 Example: >
7189 :echo matchfuzzypos(['testing'], 'tsg')
7190< results in [['testing'], [[0, 2, 6]], [99]] >
7191 :echo matchfuzzypos(['clay', 'lacy'], 'la')
7192< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
7193 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
7194< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
7195
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007196 Return type: list<list<any>>
7197
7198
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007199matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
7200 Same as |match()|, but return a |List|. The first item in the
7201 list is the matched string, same as what matchstr() would
7202 return. Following items are submatches, like "\1", "\2", etc.
7203 in |:substitute|. When an optional submatch didn't match an
7204 empty string is used. Example: >
7205 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
7206< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
7207 When there is no match an empty list is returned.
7208
7209 You can pass in a List, but that is not very useful.
7210
7211 Can also be used as a |method|: >
7212 GetText()->matchlist('word')
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007213<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007214 Return type: list<string> or list<any>
7215
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007216 *matchstrlist()*
7217matchstrlist({list}, {pat} [, {dict}])
7218 Returns the |List| of matches in {list} where {pat} matches.
7219 {list} is a |List| of strings. {pat} is matched against each
7220 string in {list}.
7221
7222 The {dict} argument supports following items:
7223 submatches include submatch information (|/\(|)
7224
7225 For each match, a |Dict| with the following items is returned:
7226 byteidx starting byte index of the match.
7227 idx index in {list} of the match.
7228 text matched string
7229 submatches a List of submatches. Present only if
7230 "submatches" is set to v:true in {dict}.
7231
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007232 See |match-pattern| for information about the effect of some
7233 option settings on the pattern.
7234
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007235 Example: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007236 :echo matchstrlist(['tik tok'], '\<\k\+\>')
7237 [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
7238 :echo matchstrlist(['a', 'b'], '\<\k\+\>')
7239 [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007240<
7241 If "submatches" is present and is v:true, then submatches like
7242 "\1", "\2", etc. are also returned. Example: >
7243 :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
7244 \ #{submatches: v:true})
7245 [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
7246< The "submatches" List always contains 9 items. If a submatch
7247 is not found, then an empty string is returned for that
7248 submatch.
7249
7250 Can also be used as a |method|: >
7251 GetListOfStrings()->matchstrlist('mypat')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007252<
7253 Return type: list<dict<any>> or list<any>
7254
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007255
7256matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
7257 Same as |match()|, but return the matched string. Example: >
7258 :echo matchstr("testing", "ing")
7259< results in "ing".
7260 When there is no match "" is returned.
7261 The {start}, if given, has the same meaning as for |match()|. >
7262 :echo matchstr("testing", "ing", 2)
7263< results in "ing". >
7264 :echo matchstr("testing", "ing", 5)
7265< result is "".
7266 When {expr} is a |List| then the matching item is returned.
7267 The type isn't changed, it's not necessarily a String.
7268
7269 Can also be used as a |method|: >
7270 GetText()->matchstr('word')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007271<
7272 Return type: |String|
7273
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007274
7275matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
7276 Same as |matchstr()|, but return the matched string, the start
7277 position and the end position of the match. Example: >
7278 :echo matchstrpos("testing", "ing")
7279< results in ["ing", 4, 7].
7280 When there is no match ["", -1, -1] is returned.
7281 The {start}, if given, has the same meaning as for |match()|. >
7282 :echo matchstrpos("testing", "ing", 2)
7283< results in ["ing", 4, 7]. >
7284 :echo matchstrpos("testing", "ing", 5)
7285< result is ["", -1, -1].
7286 When {expr} is a |List| then the matching item, the index
7287 of first item where {pat} matches, the start position and the
7288 end position of the match are returned. >
7289 :echo matchstrpos([1, '__x'], '\a')
7290< result is ["x", 1, 2, 3].
7291 The type isn't changed, it's not necessarily a String.
7292
7293 Can also be used as a |method|: >
7294 GetText()->matchstrpos('word')
7295<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007296 Return type: list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007297
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007298
7299max({expr}) *max()*
7300 Return the maximum value of all items in {expr}. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007301 echo max([apples, pears, oranges])
7302
7303< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
7304 it returns the maximum of all values in the Dictionary.
7305 If {expr} is neither a List nor a Dictionary, or one of the
7306 items in {expr} cannot be used as a Number this results in
7307 an error. An empty |List| or |Dictionary| results in zero.
7308
7309 Can also be used as a |method|: >
7310 mylist->max()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007311<
7312 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007313
7314
7315menu_info({name} [, {mode}]) *menu_info()*
7316 Return information about the specified menu {name} in
7317 mode {mode}. The menu name should be specified without the
7318 shortcut character ('&'). If {name} is "", then the top-level
7319 menu names are returned.
7320
7321 {mode} can be one of these strings:
7322 "n" Normal
7323 "v" Visual (including Select)
7324 "o" Operator-pending
7325 "i" Insert
7326 "c" Cmd-line
7327 "s" Select
7328 "x" Visual
7329 "t" Terminal-Job
7330 "" Normal, Visual and Operator-pending
7331 "!" Insert and Cmd-line
7332 When {mode} is omitted, the modes for "" are used.
7333
7334 Returns a |Dictionary| containing the following items:
7335 accel menu item accelerator text |menu-text|
7336 display display name (name without '&')
7337 enabled v:true if this menu item is enabled
7338 Refer to |:menu-enable|
7339 icon name of the icon file (for toolbar)
7340 |toolbar-icon|
7341 iconidx index of a built-in icon
7342 modes modes for which the menu is defined. In
7343 addition to the modes mentioned above, these
7344 characters will be used:
7345 " " Normal, Visual and Operator-pending
7346 name menu item name.
7347 noremenu v:true if the {rhs} of the menu item is not
7348 remappable else v:false.
7349 priority menu order priority |menu-priority|
7350 rhs right-hand-side of the menu item. The returned
7351 string has special characters translated like
7352 in the output of the ":menu" command listing.
7353 When the {rhs} of a menu item is empty, then
7354 "<Nop>" is returned.
7355 script v:true if script-local remapping of {rhs} is
7356 allowed else v:false. See |:menu-script|.
7357 shortcut shortcut key (character after '&' in
7358 the menu name) |menu-shortcut|
7359 silent v:true if the menu item is created
7360 with <silent> argument |:menu-silent|
7361 submenus |List| containing the names of
7362 all the submenus. Present only if the menu
7363 item has submenus.
7364
7365 Returns an empty dictionary if the menu item is not found.
7366
7367 Examples: >
7368 :echo menu_info('Edit.Cut')
7369 :echo menu_info('File.Save', 'n')
7370
7371 " Display the entire menu hierarchy in a buffer
7372 func ShowMenu(name, pfx)
7373 let m = menu_info(a:name)
7374 call append(line('$'), a:pfx .. m.display)
7375 for child in m->get('submenus', [])
7376 call ShowMenu(a:name .. '.' .. escape(child, '.'),
7377 \ a:pfx .. ' ')
7378 endfor
7379 endfunc
7380 new
7381 for topmenu in menu_info('').submenus
7382 call ShowMenu(topmenu, '')
7383 endfor
7384<
7385 Can also be used as a |method|: >
7386 GetMenuName()->menu_info('v')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007387<
7388 Return type: dict<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007389
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007390min({expr}) *min()*
7391 Return the minimum value of all items in {expr}. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007392 echo min([apples, pears, oranges])
7393
7394< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
7395 it returns the minimum of all values in the Dictionary.
7396 If {expr} is neither a List nor a Dictionary, or one of the
7397 items in {expr} cannot be used as a Number this results in
7398 an error. An empty |List| or |Dictionary| results in zero.
7399
7400 Can also be used as a |method|: >
7401 mylist->min()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007402<
7403 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007404
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007405
7406mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E739*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007407 Create directory {name}.
7408
Bram Moolenaar938ae282023-02-20 20:44:55 +00007409 When {flags} is present it must be a string. An empty string
7410 has no effect.
Bram Moolenaar6f14da12022-09-07 21:30:44 +01007411
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007412 {flags} can contain these character flags:
7413 "p" intermediate directories will be created as necessary
7414 "D" {name} will be deleted at the end of the current
Christian Brabandtc509c002024-06-14 20:22:05 +02007415 function, but not recursively |:defer|
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007416 "R" {name} will be deleted recursively at the end of the
Christian Brabandtc509c002024-06-14 20:22:05 +02007417 current function |:defer|
Bram Moolenaar938ae282023-02-20 20:44:55 +00007418
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007419 Note that when {name} has more than one part and "p" is used
Bram Moolenaar6f14da12022-09-07 21:30:44 +01007420 some directories may already exist. Only the first one that
7421 is created and what it contains is scheduled to be deleted.
7422 E.g. when using: >
7423 call mkdir('subdir/tmp/autoload', 'pR')
7424< and "subdir" already exists then "subdir/tmp" will be
7425 scheduled for deletion, like with: >
7426 defer delete('subdir/tmp', 'rf')
7427< Note that if scheduling the defer fails the directory is not
7428 deleted. This should only happen when out of memory.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007429
7430 If {prot} is given it is used to set the protection bits of
7431 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
7432 the user, readable for others). Use 0o700 to make it
7433 unreadable for others. This is only used for the last part of
7434 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
7435 created with 0o755.
7436 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007437 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007438
7439< This function is not available in the |sandbox|.
7440
7441 There is no error if the directory already exists and the "p"
7442 flag is passed (since patch 8.0.1708). However, without the
7443 "p" option the call will fail.
7444
7445 The function result is a Number, which is TRUE if the call was
7446 successful or FALSE if the directory creation failed or partly
7447 failed.
7448
7449 Not available on all systems. To check use: >
7450 :if exists("*mkdir")
7451
7452< Can also be used as a |method|: >
7453 GetName()->mkdir()
7454<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007455 Return type: |Number|
7456
7457
7458mode([{expr}]) *mode()*
7459 Return a string that indicates the current mode.
Doug Kearns9cd9e752024-04-07 17:42:17 +02007460 If {expr} is supplied and it evaluates to a non-zero Number or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007461 a non-empty String (|non-zero-arg|), then the full mode is
7462 returned, otherwise only the first letter is returned.
7463 Also see |state()|.
7464
7465 n Normal
7466 no Operator-pending
7467 nov Operator-pending (forced characterwise |o_v|)
7468 noV Operator-pending (forced linewise |o_V|)
7469 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
7470 CTRL-V is one character
7471 niI Normal using |i_CTRL-O| in |Insert-mode|
7472 niR Normal using |i_CTRL-O| in |Replace-mode|
7473 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
7474 nt Terminal-Normal (insert goes to Terminal-Job mode)
7475 v Visual by character
7476 vs Visual by character using |v_CTRL-O| in Select mode
7477 V Visual by line
7478 Vs Visual by line using |v_CTRL-O| in Select mode
7479 CTRL-V Visual blockwise
7480 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
7481 s Select by character
7482 S Select by line
7483 CTRL-S Select blockwise
7484 i Insert
7485 ic Insert mode completion |compl-generic|
7486 ix Insert mode |i_CTRL-X| completion
7487 R Replace |R|
7488 Rc Replace mode completion |compl-generic|
7489 Rx Replace mode |i_CTRL-X| completion
7490 Rv Virtual Replace |gR|
7491 Rvc Virtual Replace mode completion |compl-generic|
7492 Rvx Virtual Replace mode |i_CTRL-X| completion
7493 c Command-line editing
h-east71ebf3b2023-09-03 17:12:55 +02007494 ct Command-line editing via Terminal-Job mode
zeertzjqfcaeb3d2023-11-28 20:46:29 +01007495 cr Command-line editing overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007496 cv Vim Ex mode |gQ|
zeertzjqfcaeb3d2023-11-28 20:46:29 +01007497 cvr Vim Ex mode while in overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007498 ce Normal Ex mode |Q|
7499 r Hit-enter prompt
7500 rm The -- more -- prompt
7501 r? A |:confirm| query of some sort
7502 ! Shell or external command is executing
7503 t Terminal-Job mode: keys go to the job
7504
7505 This is useful in the 'statusline' option or when used
7506 with |remote_expr()| In most other places it always returns
7507 "c" or "n".
7508 Note that in the future more modes and more specific modes may
7509 be added. It's better not to compare the whole string but only
7510 the leading character(s).
7511 Also see |visualmode()|.
7512
7513 Can also be used as a |method|: >
7514 DoFull()->mode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007515<
7516 Return type: |String|
7517
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007518
7519mzeval({expr}) *mzeval()*
7520 Evaluate MzScheme expression {expr} and return its result
7521 converted to Vim data structures.
7522 Numbers and strings are returned as they are.
7523 Pairs (including lists and improper lists) and vectors are
7524 returned as Vim |Lists|.
7525 Hash tables are represented as Vim |Dictionary| type with keys
7526 converted to strings.
7527 All other types are converted to string with display function.
7528 Examples: >
7529 :mz (define l (list 1 2 3))
7530 :mz (define h (make-hash)) (hash-set! h "list" l)
7531 :echo mzeval("l")
7532 :echo mzeval("h")
7533<
7534 Note that in a `:def` function local variables are not visible
7535 to {expr}.
7536
7537 Can also be used as a |method|: >
7538 GetExpr()->mzeval()
7539<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007540 Return type: any, depending on {expr}
7541
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007542 {only available when compiled with the |+mzscheme| feature}
7543
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007544
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007545nextnonblank({lnum}) *nextnonblank()*
7546 Return the line number of the first line at or below {lnum}
7547 that is not blank. Example: >
7548 if getline(nextnonblank(1)) =~ "Java"
7549< When {lnum} is invalid or there is no non-blank line at or
7550 below it, zero is returned.
7551 {lnum} is used like with |getline()|.
7552 See also |prevnonblank()|.
7553
7554 Can also be used as a |method|: >
7555 GetLnum()->nextnonblank()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007556<
7557 Return type: |Number|
7558
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007559
7560nr2char({expr} [, {utf8}]) *nr2char()*
7561 Return a string with a single character, which has the number
7562 value {expr}. Examples: >
7563 nr2char(64) returns "@"
7564 nr2char(32) returns " "
7565< When {utf8} is omitted or zero, the current 'encoding' is used.
7566 Example for "utf-8": >
7567 nr2char(300) returns I with bow character
7568< When {utf8} is TRUE, always return UTF-8 characters.
7569 Note that a NUL character in the file is specified with
7570 nr2char(10), because NULs are represented with newline
7571 characters. nr2char(0) is a real NUL and terminates the
7572 string, thus results in an empty string.
7573 To turn a list of character numbers into a string: >
7574 let list = [65, 66, 67]
7575 let str = join(map(list, {_, val -> nr2char(val)}), '')
7576< Result: "ABC"
7577
7578 Can also be used as a |method|: >
7579 GetNumber()->nr2char()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007580<
7581 Return type: |String|
7582
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007583
7584or({expr}, {expr}) *or()*
7585 Bitwise OR on the two arguments. The arguments are converted
7586 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01007587 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007588 Example: >
7589 :let bits = or(bits, 0x80)
7590< Can also be used as a |method|: >
7591 :let bits = bits->or(0x80)
7592
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01007593< Rationale: The reason this is a function and not using the "|"
7594 character like many languages, is that Vi has always used "|"
7595 to separate commands. In many places it would not be clear if
7596 "|" is an operator or a command separator.
7597
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007598 Return type: |Number|
7599
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007600
7601pathshorten({path} [, {len}]) *pathshorten()*
7602 Shorten directory names in the path {path} and return the
7603 result. The tail, the file name, is kept as-is. The other
7604 components in the path are reduced to {len} letters in length.
7605 If {len} is omitted or smaller than 1 then 1 is used (single
7606 letters). Leading '~' and '.' characters are kept. Examples: >
7607 :echo pathshorten('~/.vim/autoload/myfile.vim')
7608< ~/.v/a/myfile.vim ~
7609>
7610 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
7611< ~/.vi/au/myfile.vim ~
7612 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007613 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007614
7615 Can also be used as a |method|: >
7616 GetDirectories()->pathshorten()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007617<
7618 Return type: |String|
7619
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007620
7621perleval({expr}) *perleval()*
7622 Evaluate Perl expression {expr} in scalar context and return
7623 its result converted to Vim data structures. If value can't be
7624 converted, it is returned as a string Perl representation.
7625 Note: If you want an array or hash, {expr} must return a
7626 reference to it.
7627 Example: >
7628 :echo perleval('[1 .. 4]')
7629< [1, 2, 3, 4]
7630
7631 Note that in a `:def` function local variables are not visible
7632 to {expr}.
7633
7634 Can also be used as a |method|: >
7635 GetExpr()->perleval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007636<
7637 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007638
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007639 {only available when compiled with the |+perl| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007640
7641
7642popup_ functions are documented here: |popup-functions|
7643
7644
7645pow({x}, {y}) *pow()*
7646 Return the power of {x} to the exponent {y} as a |Float|.
7647 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007648 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007649 Examples: >
7650 :echo pow(3, 3)
7651< 27.0 >
7652 :echo pow(2, 16)
7653< 65536.0 >
7654 :echo pow(32, 0.20)
7655< 2.0
7656
7657 Can also be used as a |method|: >
7658 Compute()->pow(3)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007659<
7660 Return type: |Number|
7661
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007662
7663prevnonblank({lnum}) *prevnonblank()*
7664 Return the line number of the first line at or above {lnum}
7665 that is not blank. Example: >
7666 let ind = indent(prevnonblank(v:lnum - 1))
7667< When {lnum} is invalid or there is no non-blank line at or
7668 above it, zero is returned.
7669 {lnum} is used like with |getline()|.
7670 Also see |nextnonblank()|.
7671
7672 Can also be used as a |method|: >
7673 GetLnum()->prevnonblank()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007674<
7675 Return type: |Number|
7676
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007677
7678printf({fmt}, {expr1} ...) *printf()*
7679 Return a String with {fmt}, where "%" items are replaced by
7680 the formatted form of their respective arguments. Example: >
7681 printf("%4d: E%d %.30s", lnum, errno, msg)
7682< May result in:
7683 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
7684
7685 When used as a |method| the base is passed as the second
7686 argument: >
7687 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007688<
7689 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007690
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007691 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007692 %s string
7693 %6S string right-aligned in 6 display cells
7694 %6s string right-aligned in 6 bytes
7695 %.9s string truncated to 9 bytes
7696 %c single byte
7697 %d decimal number
7698 %5d decimal number padded with spaces to 5 characters
7699 %x hex number
7700 %04x hex number padded with zeros to at least 4 characters
7701 %X hex number using upper case letters
7702 %o octal number
7703 %08b binary number padded with zeros to at least 8 chars
7704 %f floating point number as 12.23, inf, -inf or nan
7705 %F floating point number as 12.23, INF, -INF or NAN
7706 %e floating point number as 1.23e3, inf, -inf or nan
7707 %E floating point number as 1.23E3, INF, -INF or NAN
7708 %g floating point number, as %f or %e depending on value
7709 %G floating point number, as %F or %E depending on value
7710 %% the % character itself
7711
7712 Conversion specifications start with '%' and end with the
7713 conversion type. All other characters are copied unchanged to
7714 the result.
7715
7716 The "%" starts a conversion specification. The following
7717 arguments appear in sequence:
7718
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007719 % [pos-argument] [flags] [field-width] [.precision] type
7720
7721 pos-argument
7722 At most one positional argument specifier. These
7723 take the form {n$}, where n is >= 1.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007724
7725 flags
7726 Zero or more of the following flags:
7727
7728 # The value should be converted to an "alternate
7729 form". For c, d, and s conversions, this option
7730 has no effect. For o conversions, the precision
7731 of the number is increased to force the first
7732 character of the output string to a zero (except
7733 if a zero value is printed with an explicit
7734 precision of zero).
7735 For b and B conversions, a non-zero result has
7736 the string "0b" (or "0B" for B conversions)
7737 prepended to it.
7738 For x and X conversions, a non-zero result has
7739 the string "0x" (or "0X" for X conversions)
7740 prepended to it.
7741
7742 0 (zero) Zero padding. For all conversions the converted
7743 value is padded on the left with zeros rather
7744 than blanks. If a precision is given with a
7745 numeric conversion (d, b, B, o, x, and X), the 0
7746 flag is ignored.
7747
7748 - A negative field width flag; the converted value
7749 is to be left adjusted on the field boundary.
7750 The converted value is padded on the right with
7751 blanks, rather than on the left with blanks or
7752 zeros. A - overrides a 0 if both are given.
7753
7754 ' ' (space) A blank should be left before a positive
7755 number produced by a signed conversion (d).
7756
7757 + A sign must always be placed before a number
7758 produced by a signed conversion. A + overrides
7759 a space if both are used.
7760
7761 field-width
7762 An optional decimal digit string specifying a minimum
7763 field width. If the converted value has fewer bytes
7764 than the field width, it will be padded with spaces on
7765 the left (or right, if the left-adjustment flag has
7766 been given) to fill out the field width. For the S
7767 conversion the count is in cells.
7768
7769 .precision
7770 An optional precision, in the form of a period '.'
7771 followed by an optional digit string. If the digit
7772 string is omitted, the precision is taken as zero.
7773 This gives the minimum number of digits to appear for
7774 d, o, x, and X conversions, the maximum number of
7775 bytes to be printed from a string for s conversions,
7776 or the maximum number of cells to be printed from a
7777 string for S conversions.
7778 For floating point it is the number of digits after
7779 the decimal point.
7780
7781 type
7782 A character that specifies the type of conversion to
7783 be applied, see below.
7784
7785 A field width or precision, or both, may be indicated by an
7786 asterisk '*' instead of a digit string. In this case, a
7787 Number argument supplies the field width or precision. A
7788 negative field width is treated as a left adjustment flag
7789 followed by a positive field width; a negative precision is
7790 treated as though it were missing. Example: >
7791 :echo printf("%d: %.*s", nr, width, line)
7792< This limits the length of the text used from "line" to
7793 "width" bytes.
7794
Dominique Pellé17dca3c2023-12-14 20:36:32 +01007795 If the argument to be formatted is specified using a
7796 positional argument specifier, and a '*' is used to indicate
7797 that a number argument is to be used to specify the width or
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007798 precision, the argument(s) to be used must also be specified
7799 using a {n$} positional argument specifier. See |printf-$|.
7800
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007801 The conversion specifiers and their meanings are:
7802
7803 *printf-d* *printf-b* *printf-B* *printf-o*
7804 *printf-x* *printf-X*
7805 dbBoxX The Number argument is converted to signed decimal
7806 (d), unsigned binary (b and B), unsigned octal (o), or
7807 unsigned hexadecimal (x and X) notation. The letters
7808 "abcdef" are used for x conversions; the letters
7809 "ABCDEF" are used for X conversions.
7810 The precision, if any, gives the minimum number of
7811 digits that must appear; if the converted value
7812 requires fewer digits, it is padded on the left with
7813 zeros.
7814 In no case does a non-existent or small field width
7815 cause truncation of a numeric field; if the result of
7816 a conversion is wider than the field width, the field
7817 is expanded to contain the conversion result.
7818 The 'h' modifier indicates the argument is 16 bits.
Christ van Willegenaa90d4f2023-09-03 17:22:37 +02007819 The 'l' modifier indicates the argument is a long
7820 integer. The size will be 32 bits or 64 bits
7821 depending on your platform.
7822 The "ll" modifier indicates the argument is 64 bits.
7823 The b and B conversion specifiers never take a width
7824 modifier and always assume their argument is a 64 bit
7825 integer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007826 Generally, these modifiers are not useful. They are
7827 ignored when type is known from the argument.
7828
7829 i alias for d
7830 D alias for ld
7831 U alias for lu
7832 O alias for lo
7833
7834 *printf-c*
7835 c The Number argument is converted to a byte, and the
7836 resulting character is written.
7837
7838 *printf-s*
7839 s The text of the String argument is used. If a
7840 precision is specified, no more bytes than the number
7841 specified are used.
7842 If the argument is not a String type, it is
7843 automatically converted to text with the same format
7844 as ":echo".
7845 *printf-S*
7846 S The text of the String argument is used. If a
7847 precision is specified, no more display cells than the
7848 number specified are used.
7849
7850 *printf-f* *E807*
7851 f F The Float argument is converted into a string of the
7852 form 123.456. The precision specifies the number of
7853 digits after the decimal point. When the precision is
7854 zero the decimal point is omitted. When the precision
7855 is not specified 6 is used. A really big number
7856 (out of range or dividing by zero) results in "inf"
7857 or "-inf" with %f (INF or -INF with %F).
7858 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
7859 Example: >
7860 echo printf("%.2f", 12.115)
7861< 12.12
7862 Note that roundoff depends on the system libraries.
7863 Use |round()| when in doubt.
7864
7865 *printf-e* *printf-E*
7866 e E The Float argument is converted into a string of the
7867 form 1.234e+03 or 1.234E+03 when using 'E'. The
7868 precision specifies the number of digits after the
7869 decimal point, like with 'f'.
7870
7871 *printf-g* *printf-G*
7872 g G The Float argument is converted like with 'f' if the
7873 value is between 0.001 (inclusive) and 10000000.0
7874 (exclusive). Otherwise 'e' is used for 'g' and 'E'
7875 for 'G'. When no precision is specified superfluous
7876 zeroes and '+' signs are removed, except for the zero
7877 immediately after the decimal point. Thus 10000000.0
7878 results in 1.0e7.
7879
7880 *printf-%*
7881 % A '%' is written. No argument is converted. The
7882 complete conversion specification is "%%".
7883
7884 When a Number argument is expected a String argument is also
7885 accepted and automatically converted.
7886 When a Float or String argument is expected a Number argument
7887 is also accepted and automatically converted.
7888 Any other argument type results in an error message.
7889
7890 *E766* *E767*
7891 The number of {exprN} arguments must exactly match the number
7892 of "%" items. If there are not sufficient or too many
7893 arguments an error is given. Up to 18 arguments can be used.
7894
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007895 *printf-$*
7896 In certain languages, error and informative messages are
7897 more readable when the order of words is different from the
Christian Brabandtee17b6f2023-09-09 11:23:50 +02007898 corresponding message in English. To accommodate translations
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007899 having a different word order, positional arguments may be
7900 used to indicate this. For instance: >
7901
h_east596a9f22023-11-21 21:24:23 +09007902 #, c-format
7903 msgid "%s returning %s"
7904 msgstr "waarde %2$s komt terug van %1$s"
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007905<
h_east596a9f22023-11-21 21:24:23 +09007906 In this example, the sentence has its 2 string arguments
7907 reversed in the output. >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007908
h_east596a9f22023-11-21 21:24:23 +09007909 echo printf(
7910 "In The Netherlands, vim's creator's name is: %1$s %2$s",
7911 "Bram", "Moolenaar")
7912< In The Netherlands, vim's creator's name is: Bram Moolenaar >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007913
h_east596a9f22023-11-21 21:24:23 +09007914 echo printf(
7915 "In Belgium, vim's creator's name is: %2$s %1$s",
7916 "Bram", "Moolenaar")
7917< In Belgium, vim's creator's name is: Moolenaar Bram
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007918
7919 Width (and precision) can be specified using the '*' specifier.
7920 In this case, you must specify the field width position in the
7921 argument list. >
7922
h_east596a9f22023-11-21 21:24:23 +09007923 echo printf("%1$*2$.*3$d", 1, 2, 3)
7924< 001 >
7925 echo printf("%2$*3$.*1$d", 1, 2, 3)
7926< 2 >
7927 echo printf("%3$*1$.*2$d", 1, 2, 3)
7928< 03 >
7929 echo printf("%1$*2$.*3$g", 1.4142, 2, 3)
7930< 1.414
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007931
7932 You can mix specifying the width and/or precision directly
7933 and via positional arguments: >
7934
h_east596a9f22023-11-21 21:24:23 +09007935 echo printf("%1$4.*2$f", 1.4142135, 6)
7936< 1.414214 >
7937 echo printf("%1$*2$.4f", 1.4142135, 6)
7938< 1.4142 >
7939 echo printf("%1$*2$.*3$f", 1.4142135, 6, 2)
7940< 1.41
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007941
Christ van Willegenc35fc032024-03-14 18:30:41 +01007942 You will get an overflow error |E1510|, when the field-width
7943 or precision will result in a string longer than 6400 chars.
7944
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007945 *E1500*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007946 You cannot mix positional and non-positional arguments: >
h_east596a9f22023-11-21 21:24:23 +09007947 echo printf("%s%1$s", "One", "Two")
7948< E1500: Cannot mix positional and non-positional arguments:
7949 %s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007950
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007951 *E1501*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007952 You cannot skip a positional argument in a format string: >
h_east596a9f22023-11-21 21:24:23 +09007953 echo printf("%3$s%1$s", "One", "Two", "Three")
7954< E1501: format argument 2 unused in $-style format:
7955 %3$s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007956
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007957 *E1502*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007958 You can re-use a [field-width] (or [precision]) argument: >
h_east596a9f22023-11-21 21:24:23 +09007959 echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2)
7960< 1 at width 2 is: 01
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007961
7962 However, you can't use it as a different type: >
h_east596a9f22023-11-21 21:24:23 +09007963 echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2)
7964< E1502: Positional argument 2 used as field width reused as
7965 different type: long int/int
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007966
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007967 *E1503*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007968 When a positional argument is used, but not the correct number
7969 or arguments is given, an error is raised: >
h_east596a9f22023-11-21 21:24:23 +09007970 echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2)
7971< E1503: Positional argument 3 out of bounds: %1$d at width
7972 %2$d is: %01$*2$.*3$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007973
7974 Only the first error is reported: >
h_east596a9f22023-11-21 21:24:23 +09007975 echo printf("%01$*2$.*3$d %4$d", 1, 2)
7976< E1503: Positional argument 3 out of bounds: %01$*2$.*3$d
7977 %4$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007978
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007979 *E1504*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007980 A positional argument can be used more than once: >
h_east596a9f22023-11-21 21:24:23 +09007981 echo printf("%1$s %2$s %1$s", "One", "Two")
7982< One Two One
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007983
7984 However, you can't use a different type the second time: >
h_east596a9f22023-11-21 21:24:23 +09007985 echo printf("%1$s %2$s %1$d", "One", "Two")
7986< E1504: Positional argument 1 type used inconsistently:
7987 int/string
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007988
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007989 *E1505*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007990 Various other errors that lead to a format string being
7991 wrongly formatted lead to: >
h_east596a9f22023-11-21 21:24:23 +09007992 echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2)
7993< E1505: Invalid format specifier: %1$d at width %2$d is:
7994 %01$*2$.3$d
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007995
Christ van Willegenea746f92023-10-05 20:48:36 +02007996 *E1507*
zeertzjq27e12c72023-10-07 01:34:04 +08007997 This internal error indicates that the logic to parse a
7998 positional format argument ran into a problem that couldn't be
7999 otherwise reported. Please file a bug against Vim if you run
8000 into this, copying the exact format string and parameters that
8001 were used.
Christ van Willegenea746f92023-10-05 20:48:36 +02008002
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008003 Return type: |String|
8004
Christ van Willegenea746f92023-10-05 20:48:36 +02008005
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008006prompt_getprompt({buf}) *prompt_getprompt()*
8007 Returns the effective prompt text for buffer {buf}. {buf} can
8008 be a buffer name or number. See |prompt-buffer|.
8009
8010 If the buffer doesn't exist or isn't a prompt buffer, an empty
8011 string is returned.
8012
8013 Can also be used as a |method|: >
8014 GetBuffer()->prompt_getprompt()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008015<
8016 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008017
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008018 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008019
8020
8021prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
8022 Set prompt callback for buffer {buf} to {expr}. When {expr}
8023 is an empty string the callback is removed. This has only
8024 effect if {buf} has 'buftype' set to "prompt".
8025
8026 The callback is invoked when pressing Enter. The current
8027 buffer will always be the prompt buffer. A new line for a
8028 prompt is added before invoking the callback, thus the prompt
8029 for which the callback was invoked will be in the last but one
8030 line.
8031 If the callback wants to add text to the buffer, it must
8032 insert it above the last line, since that is where the current
8033 prompt is. This can also be done asynchronously.
8034 The callback is invoked with one argument, which is the text
8035 that was entered at the prompt. This can be an empty string
8036 if the user only typed Enter.
8037 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008038 func s:TextEntered(text)
8039 if a:text == 'exit' || a:text == 'quit'
8040 stopinsert
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008041 " Reset 'modified' to allow the buffer to be closed.
8042 " We assume there is nothing useful to be saved.
8043 set nomodified
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008044 close
8045 else
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008046 " Do something useful with "a:text". In this example
8047 " we just repeat it.
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008048 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008049 endif
8050 endfunc
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008051 call prompt_setcallback(bufnr(), function('s:TextEntered'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008052
8053< Can also be used as a |method|: >
8054 GetBuffer()->prompt_setcallback(callback)
8055
8056< {only available when compiled with the |+channel| feature}
8057
8058prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
8059 Set a callback for buffer {buf} to {expr}. When {expr} is an
8060 empty string the callback is removed. This has only effect if
8061 {buf} has 'buftype' set to "prompt".
8062
8063 This callback will be invoked when pressing CTRL-C in Insert
8064 mode. Without setting a callback Vim will exit Insert mode,
8065 as in any buffer.
8066
8067 Can also be used as a |method|: >
8068 GetBuffer()->prompt_setinterrupt(callback)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008069<
8070 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008071
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008072 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008073
8074prompt_setprompt({buf}, {text}) *prompt_setprompt()*
8075 Set prompt for buffer {buf} to {text}. You most likely want
8076 {text} to end in a space.
8077 The result is only visible if {buf} has 'buftype' set to
8078 "prompt". Example: >
8079 call prompt_setprompt(bufnr(), 'command: ')
8080<
8081 Can also be used as a |method|: >
8082 GetBuffer()->prompt_setprompt('command: ')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008083<
8084 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008085
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008086 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008087
8088prop_ functions are documented here: |text-prop-functions|
8089
8090pum_getpos() *pum_getpos()*
8091 If the popup menu (see |ins-completion-menu|) is not visible,
8092 returns an empty |Dictionary|, otherwise, returns a
8093 |Dictionary| with the following keys:
8094 height nr of items visible
8095 width screen cells
8096 row top screen row (0 first row)
8097 col leftmost screen column (0 first col)
8098 size total nr of items
8099 scrollbar |TRUE| if scrollbar is visible
8100
8101 The values are the same as in |v:event| during
8102 |CompleteChanged|.
8103
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008104 Return type: dict<any>
8105
8106
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008107pumvisible() *pumvisible()*
8108 Returns non-zero when the popup menu is visible, zero
8109 otherwise. See |ins-completion-menu|.
8110 This can be used to avoid some things that would remove the
8111 popup menu.
8112
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008113 Return type: |Number|
8114
8115
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008116py3eval({expr}) *py3eval()*
8117 Evaluate Python expression {expr} and return its result
8118 converted to Vim data structures.
8119 Numbers and strings are returned as they are (strings are
8120 copied though, Unicode strings are additionally converted to
8121 'encoding').
8122 Lists are represented as Vim |List| type.
8123 Dictionaries are represented as Vim |Dictionary| type with
8124 keys converted to strings.
8125 Note that in a `:def` function local variables are not visible
8126 to {expr}.
8127
8128 Can also be used as a |method|: >
8129 GetExpr()->py3eval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008130<
8131 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008132
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008133 {only available when compiled with the |+python3| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008134
8135 *E858* *E859*
8136pyeval({expr}) *pyeval()*
8137 Evaluate Python expression {expr} and return its result
8138 converted to Vim data structures.
8139 Numbers and strings are returned as they are (strings are
8140 copied though).
8141 Lists are represented as Vim |List| type.
8142 Dictionaries are represented as Vim |Dictionary| type,
8143 non-string keys result in error.
8144 Note that in a `:def` function local variables are not visible
8145 to {expr}.
8146
8147 Can also be used as a |method|: >
8148 GetExpr()->pyeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008149<
8150 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008151
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008152 {only available when compiled with the |+python| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008153
8154pyxeval({expr}) *pyxeval()*
8155 Evaluate Python expression {expr} and return its result
8156 converted to Vim data structures.
8157 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
8158 See also: |pyeval()|, |py3eval()|
8159
8160 Can also be used as a |method|: >
h-east52e7cc22024-07-28 17:03:29 +02008161 GetExpr()->pyxeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008162<
8163 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008164
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008165 {only available when compiled with the |+python| or the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008166 |+python3| feature}
8167
8168rand([{expr}]) *rand()* *random*
8169 Return a pseudo-random Number generated with an xoshiro128**
8170 algorithm using seed {expr}. The returned number is 32 bits,
8171 also on 64 bits systems, for consistency.
8172 {expr} can be initialized by |srand()| and will be updated by
8173 rand(). If {expr} is omitted, an internal seed value is used
8174 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008175 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008176
8177 Examples: >
8178 :echo rand()
8179 :let seed = srand()
8180 :echo rand(seed)
8181 :echo rand(seed) % 16 " random number 0 - 15
8182<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008183 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008184
8185 *E726* *E727*
8186range({expr} [, {max} [, {stride}]]) *range()*
8187 Returns a |List| with Numbers:
8188 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
8189 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
8190 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
8191 {max}] (increasing {expr} with {stride} each time, not
8192 producing a value past {max}).
8193 When the maximum is one before the start the result is an
8194 empty list. When the maximum is more than one before the
8195 start this is an error.
8196 Examples: >
8197 range(4) " [0, 1, 2, 3]
8198 range(2, 4) " [2, 3, 4]
8199 range(2, 9, 3) " [2, 5, 8]
8200 range(2, -2, -1) " [2, 1, 0, -1, -2]
8201 range(0) " []
8202 range(2, 0) " error!
8203<
8204 Can also be used as a |method|: >
8205 GetExpr()->range()
8206<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008207 Return type: list<number>
8208
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008209
K.Takata11df3ae2022-10-19 14:02:40 +01008210readblob({fname} [, {offset} [, {size}]]) *readblob()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008211 Read file {fname} in binary mode and return a |Blob|.
K.Takata11df3ae2022-10-19 14:02:40 +01008212 If {offset} is specified, read the file from the specified
8213 offset. If it is a negative value, it is used as an offset
8214 from the end of the file. E.g., to read the last 12 bytes: >
8215 readblob('file.bin', -12)
8216< If {size} is specified, only the specified size will be read.
8217 E.g. to read the first 100 bytes of a file: >
8218 readblob('file.bin', 0, 100)
8219< If {size} is -1 or omitted, the whole data starting from
8220 {offset} will be read.
K.Takata43625762022-10-20 13:28:51 +01008221 This can be also used to read the data from a character device
8222 on Unix when {size} is explicitly set. Only if the device
8223 supports seeking {offset} can be used. Otherwise it should be
8224 zero. E.g. to read 10 bytes from a serial console: >
8225 readblob('/dev/ttyS0', 0, 10)
8226< When the file can't be opened an error message is given and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008227 the result is an empty |Blob|.
Bram Moolenaar5b2a3d72022-10-21 11:25:30 +01008228 When the offset is beyond the end of the file the result is an
8229 empty blob.
8230 When trying to read more bytes than are available the result
8231 is truncated.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008232 Also see |readfile()| and |writefile()|.
8233
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008234 Return type: |Blob|
8235
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008236
8237readdir({directory} [, {expr} [, {dict}]]) *readdir()*
8238 Return a list with file and directory names in {directory}.
8239 You can also use |glob()| if you don't need to do complicated
8240 things, such as limiting the number of matches.
8241 The list will be sorted (case sensitive), see the {dict}
8242 argument below for changing the sort order.
8243
8244 When {expr} is omitted all entries are included.
8245 When {expr} is given, it is evaluated to check what to do:
8246 If {expr} results in -1 then no further entries will
8247 be handled.
8248 If {expr} results in 0 then this entry will not be
8249 added to the list.
8250 If {expr} results in 1 then this entry will be added
8251 to the list.
8252 The entries "." and ".." are always excluded.
8253 Each time {expr} is evaluated |v:val| is set to the entry name.
8254 When {expr} is a function the name is passed as the argument.
8255 For example, to get a list of files ending in ".txt": >
8256 readdir(dirname, {n -> n =~ '.txt$'})
8257< To skip hidden and backup files: >
8258 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00008259< *E857*
8260 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008261 values. Currently this is used to specify if and how sorting
8262 should be performed. The dict can have the following members:
8263
8264 sort How to sort the result returned from the system.
8265 Valid values are:
8266 "none" do not sort (fastest method)
8267 "case" sort case sensitive (byte value of
8268 each character, technically, using
8269 strcmp()) (default)
8270 "icase" sort case insensitive (technically
8271 using strcasecmp())
8272 "collate" sort using the collation order
8273 of the "POSIX" or "C" |locale|
8274 (technically using strcoll())
8275 Other values are silently ignored.
8276
8277 For example, to get a list of all files in the current
8278 directory without sorting the individual entries: >
8279 readdir('.', '1', #{sort: 'none'})
8280< If you want to get a directory tree: >
8281 function! s:tree(dir)
8282 return {a:dir : map(readdir(a:dir),
8283 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008284 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008285 endfunction
8286 echo s:tree(".")
8287<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008288 Returns an empty List on error.
8289
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008290 Can also be used as a |method|: >
8291 GetDirName()->readdir()
8292<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008293 Return type: list<string> or list<any>
8294
8295
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008296readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
8297 Extended version of |readdir()|.
8298 Return a list of Dictionaries with file and directory
8299 information in {directory}.
8300 This is useful if you want to get the attributes of file and
8301 directory at the same time as getting a list of a directory.
8302 This is much faster than calling |readdir()| then calling
8303 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
8304 each file and directory especially on MS-Windows.
8305 The list will by default be sorted by name (case sensitive),
8306 the sorting can be changed by using the optional {dict}
8307 argument, see |readdir()|.
8308
8309 The Dictionary for file and directory information has the
8310 following items:
8311 group Group name of the entry. (Only on Unix)
8312 name Name of the entry.
8313 perm Permissions of the entry. See |getfperm()|.
8314 size Size of the entry. See |getfsize()|.
8315 time Timestamp of the entry. See |getftime()|.
8316 type Type of the entry.
8317 On Unix, almost same as |getftype()| except:
8318 Symlink to a dir "linkd"
8319 Other symlink "link"
8320 On MS-Windows:
8321 Normal file "file"
8322 Directory "dir"
8323 Junction "junction"
8324 Symlink to a dir "linkd"
8325 Other symlink "link"
8326 Other reparse point "reparse"
8327 user User name of the entry's owner. (Only on Unix)
8328 On Unix, if the entry is a symlink, the Dictionary includes
8329 the information of the target (except the "type" item).
8330 On MS-Windows, it includes the information of the symlink
8331 itself because of performance reasons.
8332
8333 When {expr} is omitted all entries are included.
8334 When {expr} is given, it is evaluated to check what to do:
8335 If {expr} results in -1 then no further entries will
8336 be handled.
8337 If {expr} results in 0 then this entry will not be
8338 added to the list.
8339 If {expr} results in 1 then this entry will be added
8340 to the list.
8341 The entries "." and ".." are always excluded.
8342 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
8343 of the entry.
8344 When {expr} is a function the entry is passed as the argument.
8345 For example, to get a list of files ending in ".txt": >
8346 readdirex(dirname, {e -> e.name =~ '.txt$'})
8347<
8348 For example, to get a list of all files in the current
8349 directory without sorting the individual entries: >
8350 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008351<
8352 Can also be used as a |method|: >
8353 GetDirName()->readdirex()
8354<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008355 Return type: list<dict<any>> or list<any>
8356
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008357
8358 *readfile()*
8359readfile({fname} [, {type} [, {max}]])
8360 Read file {fname} and return a |List|, each line of the file
8361 as an item. Lines are broken at NL characters. Macintosh
8362 files separated with CR will result in a single long line
8363 (unless a NL appears somewhere).
8364 All NUL characters are replaced with a NL character.
8365 When {type} contains "b" binary mode is used:
8366 - When the last line ends in a NL an extra empty list item is
8367 added.
8368 - No CR characters are removed.
8369 Otherwise:
8370 - CR characters that appear before a NL are removed.
8371 - Whether the last line ends in a NL or not does not matter.
8372 - When 'encoding' is Unicode any UTF-8 byte order mark is
8373 removed from the text.
8374 When {max} is given this specifies the maximum number of lines
8375 to be read. Useful if you only want to check the first ten
8376 lines of a file: >
8377 :for line in readfile(fname, '', 10)
8378 : if line =~ 'Date' | echo line | endif
8379 :endfor
8380< When {max} is negative -{max} lines from the end of the file
8381 are returned, or as many as there are.
8382 When {max} is zero the result is an empty list.
8383 Note that without {max} the whole file is read into memory.
8384 Also note that there is no recognition of encoding. Read a
8385 file into a buffer if you need to.
8386 Deprecated (use |readblob()| instead): When {type} contains
8387 "B" a |Blob| is returned with the binary data of the file
8388 unmodified.
8389 When the file can't be opened an error message is given and
8390 the result is an empty list.
8391 Also see |writefile()|.
8392
8393 Can also be used as a |method|: >
8394 GetFileName()->readfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008395<
8396 Return type: list<string> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008397
8398reduce({object}, {func} [, {initial}]) *reduce()* *E998*
8399 {func} is called for every item in {object}, which can be a
8400 |String|, |List| or a |Blob|. {func} is called with two
8401 arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00008402 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008403
8404 {initial} is the initial result. When omitted, the first item
8405 in {object} is used and {func} is first called for the second
8406 item. If {initial} is not given and {object} is empty no
8407 result can be computed, an E998 error is given.
8408
8409 Examples: >
8410 echo reduce([1, 3, 5], { acc, val -> acc + val })
8411 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
8412 echo reduce(0z1122, { acc, val -> 2 * acc + val })
8413 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
8414<
8415 Can also be used as a |method|: >
8416 echo mylist->reduce({ acc, val -> acc + val }, 0)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008417<
8418 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
8419 depending on {object} and {func}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008420
8421
8422reg_executing() *reg_executing()*
8423 Returns the single letter name of the register being executed.
8424 Returns an empty string when no register is being executed.
8425 See |@|.
8426
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008427 Return type: |String|
8428
8429
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008430reg_recording() *reg_recording()*
8431 Returns the single letter name of the register being recorded.
8432 Returns an empty string when not recording. See |q|.
8433
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008434 Return type: |String|
8435
8436
8437reltime() *reltime()*
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008438reltime({start})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008439reltime({start}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008440 Return an item that represents a time value. The item is a
8441 list with items that depend on the system. In Vim 9 script
Bram Moolenaar71badf92023-04-22 22:40:14 +01008442 the type list<any> can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008443 The item can be passed to |reltimestr()| to convert it to a
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008444 string or |reltimefloat()| to convert to a Float. For
8445 example, to see the time spent in function Work(): >
8446 var startTime = reltime()
8447 Work()
8448 echo startTime->reltime()->reltimestr()
8449<
Bram Moolenaar016188f2022-06-06 20:52:59 +01008450 Without an argument reltime() returns the current time (the
Lifepillar963fd7d2024-01-05 17:44:57 +01008451 representation is system-dependent, it cannot be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01008452 wall-clock time, see |localtime()| for that).
Lifepillar963fd7d2024-01-05 17:44:57 +01008453 With one argument it returns the time passed since the time
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008454 specified in the argument.
8455 With two arguments it returns the time passed between {start}
8456 and {end}.
8457
8458 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008459 reltime(). If there is an error an empty List is returned in
8460 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008461
8462 Can also be used as a |method|: >
8463 GetStart()->reltime()
8464<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008465 Return type: list<number>
8466
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008467 {only available when compiled with the |+reltime| feature}
8468
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008469
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008470reltimefloat({time}) *reltimefloat()*
8471 Return a Float that represents the time value of {time}.
8472 Example: >
8473 let start = reltime()
8474 call MyFunction()
8475 let seconds = reltimefloat(reltime(start))
8476< See the note of reltimestr() about overhead.
8477 Also see |profiling|.
8478 If there is an error 0.0 is returned in legacy script, in Vim9
8479 script an error is given.
8480
8481 Can also be used as a |method|: >
8482 reltime(start)->reltimefloat()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008483<
8484 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008485
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008486 {only available when compiled with the |+reltime| feature}
8487
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008488
8489reltimestr({time}) *reltimestr()*
8490 Return a String that represents the time value of {time}.
8491 This is the number of seconds, a dot and the number of
8492 microseconds. Example: >
8493 let start = reltime()
8494 call MyFunction()
8495 echo reltimestr(reltime(start))
8496< Note that overhead for the commands will be added to the time.
Ernie Rael076de792023-03-16 21:43:15 +00008497 The accuracy depends on the system. Use reltimefloat() for the
8498 greatest accuracy which is nanoseconds on some systems.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008499 Leading spaces are used to make the string align nicely. You
8500 can use split() to remove it. >
8501 echo split(reltimestr(reltime(start)))[0]
8502< Also see |profiling|.
8503 If there is an error an empty string is returned in legacy
8504 script, in Vim9 script an error is given.
8505
8506 Can also be used as a |method|: >
8507 reltime(start)->reltimestr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008508<
8509 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008510
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008511 {only available when compiled with the |+reltime| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008512
8513 *remote_expr()* *E449*
8514remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00008515 Send the {string} to {server}. The {server} argument is a
8516 string, also see |{server}|.
8517
8518 The string is sent as an expression and the result is returned
8519 after evaluation. The result must be a String or a |List|. A
8520 |List| is turned into a String by joining the items with a
8521 line break in between (not at the end), like with join(expr,
8522 "\n").
8523
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008524 If {idvar} is present and not empty, it is taken as the name
8525 of a variable and a {serverid} for later use with
8526 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008527
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008528 If {timeout} is given the read times out after this many
8529 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008530
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008531 See also |clientserver| |RemoteReply|.
8532 This function is not available in the |sandbox|.
8533 {only available when compiled with the |+clientserver| feature}
8534 Note: Any errors will cause a local error message to be issued
8535 and the result will be the empty string.
8536
8537 Variables will be evaluated in the global namespace,
8538 independent of a function currently being active. Except
8539 when in debug mode, then local function variables and
8540 arguments can be evaluated.
8541
8542 Examples: >
8543 :echo remote_expr("gvim", "2+2")
8544 :echo remote_expr("gvim1", "b:current_syntax")
8545<
8546 Can also be used as a |method|: >
8547 ServerName()->remote_expr(expr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008548<
8549 Return type: |String| or list<{type}>
8550
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008551
8552remote_foreground({server}) *remote_foreground()*
8553 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008554 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008555 This works like: >
8556 remote_expr({server}, "foreground()")
8557< Except that on Win32 systems the client does the work, to work
8558 around the problem that the OS doesn't always allow the server
8559 to bring itself to the foreground.
8560 Note: This does not restore the window if it was minimized,
8561 like foreground() does.
8562 This function is not available in the |sandbox|.
8563
8564 Can also be used as a |method|: >
8565 ServerName()->remote_foreground()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008566<
8567 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008568
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008569 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008570 Win32 console version}
8571
8572
8573remote_peek({serverid} [, {retvar}]) *remote_peek()*
8574 Returns a positive number if there are available strings
8575 from {serverid}. Copies any reply string into the variable
8576 {retvar} if specified. {retvar} must be a string with the
8577 name of a variable.
8578 Returns zero if none are available.
8579 Returns -1 if something is wrong.
8580 See also |clientserver|.
8581 This function is not available in the |sandbox|.
8582 {only available when compiled with the |+clientserver| feature}
8583 Examples: >
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008584 :let repl = ""
8585 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008586
8587< Can also be used as a |method|: >
8588 ServerId()->remote_peek()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008589<
8590 Return type: |Number|
8591
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008592
8593remote_read({serverid}, [{timeout}]) *remote_read()*
8594 Return the oldest available reply from {serverid} and consume
8595 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008596 reply is available. Returns an empty string, if a reply is
8597 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008598 See also |clientserver|.
8599 This function is not available in the |sandbox|.
8600 {only available when compiled with the |+clientserver| feature}
8601 Example: >
8602 :echo remote_read(id)
8603
8604< Can also be used as a |method|: >
8605 ServerId()->remote_read()
8606<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008607 Return type: |String|
8608
8609
8610remote_send({server}, {string} [, {idvar}]) *remote_send()* *E241*
Bram Moolenaar944697a2022-02-20 19:48:20 +00008611 Send the {string} to {server}. The {server} argument is a
8612 string, also see |{server}|.
8613
8614 The string is sent as input keys and the function returns
8615 immediately. At the Vim server the keys are not mapped
8616 |:map|.
8617
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008618 If {idvar} is present, it is taken as the name of a variable
8619 and a {serverid} for later use with remote_read() is stored
8620 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008621
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008622 See also |clientserver| |RemoteReply|.
8623 This function is not available in the |sandbox|.
8624 {only available when compiled with the |+clientserver| feature}
8625
8626 Note: Any errors will be reported in the server and may mess
8627 up the display.
8628 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008629 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008630 \ remote_read(serverid)
8631
8632 :autocmd NONE RemoteReply *
8633 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008634 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008635 \ 'server2client(expand("<client>"), "HELLO")<CR>')
8636<
8637 Can also be used as a |method|: >
8638 ServerName()->remote_send(keys)
8639<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008640 Return type: |String|
8641
8642
8643remote_startserver({name}) *remote_startserver()* *E941* *E942*
h-east17b69512023-05-01 22:36:56 +01008644 Become the server {name}. {name} must be a non-empty string.
8645 This fails if already running as a server, when |v:servername|
8646 is not empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008647
8648 Can also be used as a |method|: >
8649 ServerName()->remote_startserver()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008650<
8651 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008652
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008653 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008654
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008655
8656remove({list}, {idx}) *remove()*
8657remove({list}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008658 Without {end}: Remove the item at {idx} from |List| {list} and
8659 return the item.
8660 With {end}: Remove items from {idx} to {end} (inclusive) and
8661 return a |List| with these items. When {idx} points to the same
8662 item as {end} a list with one item is returned. When {end}
8663 points to an item before {idx} this is an error.
8664 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008665 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008666 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008667 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008668 :call remove(mylist, 0, 9)
8669<
8670 Use |delete()| to remove a file.
8671
8672 Can also be used as a |method|: >
8673 mylist->remove(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008674<
8675 Return type: any, depending on {list}
8676
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008677
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008678remove({blob}, {idx})
8679remove({blob}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008680 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
8681 return the byte.
8682 With {end}: Remove bytes from {idx} to {end} (inclusive) and
8683 return a |Blob| with these bytes. When {idx} points to the same
8684 byte as {end} a |Blob| with one byte is returned. When {end}
8685 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008686 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008687 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008688 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008689 :call remove(mylist, 0, 9)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008690<
8691 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008692
8693remove({dict}, {key})
8694 Remove the entry from {dict} with key {key} and return it.
8695 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008696 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008697< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008698 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008699
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008700 Return type: any, depending on {dict}
8701
8702
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008703rename({from}, {to}) *rename()*
8704 Rename the file by the name {from} to the name {to}. This
8705 should also work to move files across file systems. The
8706 result is a Number, which is 0 if the file was renamed
8707 successfully, and non-zero when the renaming failed.
8708 NOTE: If {to} exists it is overwritten without warning.
8709 This function is not available in the |sandbox|.
8710
8711 Can also be used as a |method|: >
8712 GetOldName()->rename(newname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008713<
8714 Return type: |Number|
8715
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008716
8717repeat({expr}, {count}) *repeat()*
8718 Repeat {expr} {count} times and return the concatenated
8719 result. Example: >
8720 :let separator = repeat('-', 80)
8721< When {count} is zero or negative the result is empty.
Bakudankun375141e2022-09-09 18:46:47 +01008722 When {expr} is a |List| or a |Blob| the result is {expr}
8723 concatenated {count} times. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008724 :let longlist = repeat(['a', 'b'], 3)
8725< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
8726
8727 Can also be used as a |method|: >
8728 mylist->repeat(count)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008729<
8730 Return type: |String|, |Blob| or list<{type}> depending on
8731 {expr}
8732
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008733
8734resolve({filename}) *resolve()* *E655*
8735 On MS-Windows, when {filename} is a shortcut (a .lnk file),
8736 returns the path the shortcut points to in a simplified form.
8737 When {filename} is a symbolic link or junction point, return
8738 the full path to the target. If the target of junction is
8739 removed, return {filename}.
8740 On Unix, repeat resolving symbolic links in all path
8741 components of {filename} and return the simplified result.
8742 To cope with link cycles, resolving of symbolic links is
8743 stopped after 100 iterations.
8744 On other systems, return the simplified {filename}.
8745 The simplification step is done as by |simplify()|.
8746 resolve() keeps a leading path component specifying the
8747 current directory (provided the result is still a relative
8748 path name) and also keeps a trailing path separator.
8749
8750 Can also be used as a |method|: >
8751 GetName()->resolve()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008752<
8753 Return type: |String|
8754
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008755
8756reverse({object}) *reverse()*
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +01008757 Reverse the order of items in {object}. {object} can be a
8758 |List|, a |Blob| or a |String|. For a List and a Blob the
8759 items are reversed in-place and {object} is returned.
8760 For a String a new String is returned.
8761 Returns zero if {object} is not a List, Blob or a String.
8762 If you want a List or Blob to remain unmodified make a copy
8763 first: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008764 :let revlist = reverse(copy(mylist))
8765< Can also be used as a |method|: >
8766 mylist->reverse()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008767<
8768 Return type: |String|, |Blob| or list<{type}> depending on
8769 {object}
8770
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008771
8772round({expr}) *round()*
8773 Round off {expr} to the nearest integral value and return it
8774 as a |Float|. If {expr} lies halfway between two integral
8775 values, then use the larger one (away from zero).
8776 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008777 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008778 Examples: >
8779 echo round(0.456)
8780< 0.0 >
8781 echo round(4.5)
8782< 5.0 >
8783 echo round(-4.5)
8784< -5.0
8785
8786 Can also be used as a |method|: >
8787 Compute()->round()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008788<
8789 Return type: |Float|
8790
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008791
8792rubyeval({expr}) *rubyeval()*
8793 Evaluate Ruby expression {expr} and return its result
8794 converted to Vim data structures.
8795 Numbers, floats and strings are returned as they are (strings
8796 are copied though).
8797 Arrays are represented as Vim |List| type.
8798 Hashes are represented as Vim |Dictionary| type.
8799 Other objects are represented as strings resulted from their
8800 "Object#to_s" method.
8801 Note that in a `:def` function local variables are not visible
8802 to {expr}.
8803
8804 Can also be used as a |method|: >
8805 GetRubyExpr()->rubyeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008806<
8807 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008808
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008809 {only available when compiled with the |+ruby| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008810
8811screenattr({row}, {col}) *screenattr()*
8812 Like |screenchar()|, but return the attribute. This is a rather
8813 arbitrary number that can only be used to compare to the
8814 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008815 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008816
8817 Can also be used as a |method|: >
8818 GetRow()->screenattr(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008819<
8820 Return type: |Number|
8821
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008822
8823screenchar({row}, {col}) *screenchar()*
8824 The result is a Number, which is the character at position
8825 [row, col] on the screen. This works for every possible
8826 screen position, also status lines, window separators and the
8827 command line. The top left position is row one, column one
8828 The character excludes composing characters. For double-byte
8829 encodings it may only be the first byte.
8830 This is mainly to be used for testing.
8831 Returns -1 when row or col is out of range.
8832
8833 Can also be used as a |method|: >
8834 GetRow()->screenchar(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008835<
8836 Return type: |Number|
8837
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008838
8839screenchars({row}, {col}) *screenchars()*
8840 The result is a |List| of Numbers. The first number is the same
8841 as what |screenchar()| returns. Further numbers are
8842 composing characters on top of the base character.
8843 This is mainly to be used for testing.
8844 Returns an empty List when row or col is out of range.
8845
8846 Can also be used as a |method|: >
8847 GetRow()->screenchars(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008848<
8849 Return type: list<number> or list<any>
8850
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008851
8852screencol() *screencol()*
8853 The result is a Number, which is the current screen column of
8854 the cursor. The leftmost column has number 1.
8855 This function is mainly used for testing.
8856
8857 Note: Always returns the current screen column, thus if used
8858 in a command (e.g. ":echo screencol()") it will return the
8859 column inside the command line, which is 1 when the command is
8860 executed. To get the cursor position in the file use one of
8861 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008862 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008863 nnoremap <silent> GG :echom screencol()<CR>
8864 nnoremap GG <Cmd>echom screencol()<CR>
8865<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008866 Return type: |Number|
8867
8868
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008869screenpos({winid}, {lnum}, {col}) *screenpos()*
8870 The result is a Dict with the screen position of the text
8871 character in window {winid} at buffer line {lnum} and column
8872 {col}. {col} is a one-based byte index.
8873 The Dict has these members:
8874 row screen row
8875 col first screen column
8876 endcol last screen column
8877 curscol cursor screen column
8878 If the specified position is not visible, all values are zero.
8879 The "endcol" value differs from "col" when the character
8880 occupies more than one screen cell. E.g. for a Tab "col" can
8881 be 1 and "endcol" can be 8.
8882 The "curscol" value is where the cursor would be placed. For
8883 a Tab it would be the same as "endcol", while for a double
8884 width character it would be the same as "col".
8885 The |conceal| feature is ignored here, the column numbers are
8886 as if 'conceallevel' is zero. You can set the cursor to the
8887 right position and use |screencol()| to get the value with
8888 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008889 If the position is in a closed fold the screen position of the
8890 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008891 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008892
8893 Can also be used as a |method|: >
8894 GetWinid()->screenpos(lnum, col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008895<
8896 Return type: dict<number> or dict<any>
8897
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008898
8899screenrow() *screenrow()*
8900 The result is a Number, which is the current screen row of the
8901 cursor. The top line has number one.
8902 This function is mainly used for testing.
8903 Alternatively you can use |winline()|.
8904
8905 Note: Same restrictions as with |screencol()|.
8906
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008907 Return type: |Number|
8908
8909
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008910screenstring({row}, {col}) *screenstring()*
8911 The result is a String that contains the base character and
8912 any composing characters at position [row, col] on the screen.
8913 This is like |screenchars()| but returning a String with the
8914 characters.
8915 This is mainly to be used for testing.
8916 Returns an empty String when row or col is out of range.
8917
8918 Can also be used as a |method|: >
8919 GetRow()->screenstring(col)
8920<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008921 Return type: |String|
8922
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008923 *search()*
8924search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
8925 Search for regexp pattern {pattern}. The search starts at the
8926 cursor position (you can use |cursor()| to set it).
8927
8928 When a match has been found its line number is returned.
8929 If there is no match a 0 is returned and the cursor doesn't
8930 move. No error message is given.
Christian Brabandt9a660d22024-03-12 22:03:09 +01008931 To get the matched string, use |matchbufline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008932
8933 {flags} is a String, which can contain these character flags:
8934 'b' search Backward instead of forward
8935 'c' accept a match at the Cursor position
8936 'e' move to the End of the match
8937 'n' do Not move the cursor
8938 'p' return number of matching sub-Pattern (see below)
8939 's' Set the ' mark at the previous location of the cursor
8940 'w' Wrap around the end of the file
8941 'W' don't Wrap around the end of the file
8942 'z' start searching at the cursor column instead of zero
8943 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
8944
8945 If the 's' flag is supplied, the ' mark is set, only if the
8946 cursor is moved. The 's' flag cannot be combined with the 'n'
8947 flag.
8948
8949 'ignorecase', 'smartcase' and 'magic' are used.
8950
8951 When the 'z' flag is not given, forward searching always
8952 starts in column zero and then matches before the cursor are
8953 skipped. When the 'c' flag is present in 'cpo' the next
8954 search starts after the match. Without the 'c' flag the next
Bram Moolenaarfd999452022-08-24 18:30:14 +01008955 search starts one column after the start of the match. This
8956 matters for overlapping matches. See |cpo-c|. You can also
8957 insert "\ze" to change where the match ends, see |/\ze|.
8958
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008959 When searching backwards and the 'z' flag is given then the
8960 search starts in column zero, thus no match in the current
8961 line will be found (unless wrapping around the end of the
8962 file).
8963
8964 When the {stopline} argument is given then the search stops
8965 after searching this line. This is useful to restrict the
8966 search to a range of lines. Examples: >
8967 let match = search('(', 'b', line("w0"))
8968 let end = search('END', '', line("w$"))
8969< When {stopline} is used and it is not zero this also implies
8970 that the search does not wrap around the end of the file.
8971 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01008972 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008973 When the {timeout} argument is given the search stops when
8974 more than this many milliseconds have passed. Thus when
8975 {timeout} is 500 the search stops after half a second.
8976 The value must not be negative. A zero value is like not
8977 giving the argument.
Christian Brabandtd657d3d2024-09-10 21:55:49 +02008978
8979 Note: the timeout is only considered when searching, not
8980 while evaluating the {skip} expression.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008981 {only available when compiled with the |+reltime| feature}
8982
8983 If the {skip} expression is given it is evaluated with the
8984 cursor positioned on the start of a match. If it evaluates to
8985 non-zero this match is skipped. This can be used, for
8986 example, to skip a match in a comment or a string.
8987 {skip} can be a string, which is evaluated as an expression, a
8988 function reference or a lambda.
8989 When {skip} is omitted or empty, every match is accepted.
8990 When evaluating {skip} causes an error the search is aborted
8991 and -1 returned.
8992 *search()-sub-match*
8993 With the 'p' flag the returned value is one more than the
8994 first sub-match in \(\). One if none of them matched but the
8995 whole pattern did match.
8996 To get the column number too use |searchpos()|.
8997
8998 The cursor will be positioned at the match, unless the 'n'
8999 flag is used.
9000
9001 Example (goes over all files in the argument list): >
9002 :let n = 1
9003 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009004 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009005 : " start at the last char in the file and wrap for the
9006 : " first search to find match at start of file
9007 : normal G$
9008 : let flags = "w"
9009 : while search("foo", flags) > 0
9010 : s/foo/bar/g
9011 : let flags = "W"
9012 : endwhile
9013 : update " write the file if modified
9014 : let n = n + 1
9015 :endwhile
9016<
9017 Example for using some flags: >
9018 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
9019< This will search for the keywords "if", "else", and "endif"
9020 under or after the cursor. Because of the 'p' flag, it
9021 returns 1, 2, or 3 depending on which keyword is found, or 0
9022 if the search fails. With the cursor on the first word of the
9023 line:
9024 if (foo == 0) | let foo = foo + 1 | endif ~
9025 the function returns 1. Without the 'c' flag, the function
9026 finds the "endif" and returns 3. The same thing happens
9027 without the 'e' flag if the cursor is on the "f" of "if".
9028 The 'n' flag tells the function not to move the cursor.
9029
9030 Can also be used as a |method|: >
9031 GetPattern()->search()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009032<
9033 Return type: |Number|
9034
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009035
9036searchcount([{options}]) *searchcount()*
9037 Get or update the last search count, like what is displayed
9038 without the "S" flag in 'shortmess'. This works even if
9039 'shortmess' does contain the "S" flag.
9040
9041 This returns a |Dictionary|. The dictionary is empty if the
9042 previous pattern was not set and "pattern" was not specified.
9043
9044 key type meaning ~
9045 current |Number| current position of match;
9046 0 if the cursor position is
9047 before the first match
9048 exact_match |Boolean| 1 if "current" is matched on
9049 "pos", otherwise 0
9050 total |Number| total count of matches found
9051 incomplete |Number| 0: search was fully completed
9052 1: recomputing was timed out
9053 2: max count exceeded
9054
9055 For {options} see further down.
9056
9057 To get the last search count when |n| or |N| was pressed, call
9058 this function with `recompute: 0` . This sometimes returns
9059 wrong information because |n| and |N|'s maximum count is 99.
9060 If it exceeded 99 the result must be max count + 1 (100). If
9061 you want to get correct information, specify `recompute: 1`: >
9062
9063 " result == maxcount + 1 (100) when many matches
9064 let result = searchcount(#{recompute: 0})
9065
9066 " Below returns correct result (recompute defaults
9067 " to 1)
9068 let result = searchcount()
9069<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01009070 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009071 function! LastSearchCount() abort
9072 let result = searchcount(#{recompute: 0})
9073 if empty(result)
9074 return ''
9075 endif
9076 if result.incomplete ==# 1 " timed out
9077 return printf(' /%s [?/??]', @/)
9078 elseif result.incomplete ==# 2 " max count exceeded
9079 if result.total > result.maxcount &&
9080 \ result.current > result.maxcount
9081 return printf(' /%s [>%d/>%d]', @/,
9082 \ result.current, result.total)
9083 elseif result.total > result.maxcount
9084 return printf(' /%s [%d/>%d]', @/,
9085 \ result.current, result.total)
9086 endif
9087 endif
9088 return printf(' /%s [%d/%d]', @/,
9089 \ result.current, result.total)
9090 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009091 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009092
9093 " Or if you want to show the count only when
9094 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009095 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009096 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
9097<
9098 You can also update the search count, which can be useful in a
9099 |CursorMoved| or |CursorMovedI| autocommand: >
9100
9101 autocmd CursorMoved,CursorMovedI *
9102 \ let s:searchcount_timer = timer_start(
9103 \ 200, function('s:update_searchcount'))
9104 function! s:update_searchcount(timer) abort
9105 if a:timer ==# s:searchcount_timer
9106 call searchcount(#{
9107 \ recompute: 1, maxcount: 0, timeout: 100})
9108 redrawstatus
9109 endif
9110 endfunction
9111<
9112 This can also be used to count matched texts with specified
9113 pattern in the current buffer using "pattern": >
9114
9115 " Count '\<foo\>' in this buffer
9116 " (Note that it also updates search count)
9117 let result = searchcount(#{pattern: '\<foo\>'})
9118
9119 " To restore old search count by old pattern,
9120 " search again
9121 call searchcount()
9122<
9123 {options} must be a |Dictionary|. It can contain:
9124 key type meaning ~
9125 recompute |Boolean| if |TRUE|, recompute the count
9126 like |n| or |N| was executed.
9127 otherwise returns the last
9128 computed result (when |n| or
9129 |N| was used when "S" is not
9130 in 'shortmess', or this
9131 function was called).
9132 (default: |TRUE|)
9133 pattern |String| recompute if this was given
9134 and different with |@/|.
9135 this works as same as the
9136 below command is executed
9137 before calling this function >
9138 let @/ = pattern
9139< (default: |@/|)
9140 timeout |Number| 0 or negative number is no
9141 timeout. timeout milliseconds
9142 for recomputing the result
9143 (default: 0)
9144 maxcount |Number| 0 or negative number is no
9145 limit. max count of matched
9146 text while recomputing the
9147 result. if search exceeded
9148 total count, "total" value
9149 becomes `maxcount + 1`
9150 (default: 99)
9151 pos |List| `[lnum, col, off]` value
9152 when recomputing the result.
9153 this changes "current" result
9154 value. see |cursor()|,
9155 |getpos()|
9156 (default: cursor's position)
9157
9158 Can also be used as a |method|: >
9159 GetSearchOpts()->searchcount()
9160<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009161 Return type: dict<number>
9162
9163
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009164searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
9165 Search for the declaration of {name}.
9166
9167 With a non-zero {global} argument it works like |gD|, find
9168 first match in the file. Otherwise it works like |gd|, find
9169 first match in the function.
9170
9171 With a non-zero {thisblock} argument matches in a {} block
9172 that ends before the cursor position are ignored. Avoids
9173 finding variable declarations only valid in another scope.
9174
9175 Moves the cursor to the found match.
9176 Returns zero for success, non-zero for failure.
9177 Example: >
9178 if searchdecl('myvar') == 0
9179 echo getline('.')
9180 endif
9181<
9182 Can also be used as a |method|: >
9183 GetName()->searchdecl()
9184<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009185 Return type: |Number|
9186
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009187 *searchpair()*
9188searchpair({start}, {middle}, {end} [, {flags} [, {skip}
9189 [, {stopline} [, {timeout}]]]])
9190 Search for the match of a nested start-end pair. This can be
9191 used to find the "endif" that matches an "if", while other
9192 if/endif pairs in between are ignored.
9193 The search starts at the cursor. The default is to search
9194 forward, include 'b' in {flags} to search backward.
9195 If a match is found, the cursor is positioned at it and the
9196 line number is returned. If no match is found 0 or -1 is
9197 returned and the cursor doesn't move. No error message is
9198 given.
9199
9200 {start}, {middle} and {end} are patterns, see |pattern|. They
9201 must not contain \( \) pairs. Use of \%( \) is allowed. When
9202 {middle} is not empty, it is found when searching from either
9203 direction, but only when not in a nested start-end pair. A
9204 typical use is: >
9205 searchpair('\<if\>', '\<else\>', '\<endif\>')
9206< By leaving {middle} empty the "else" is skipped.
9207
9208 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
9209 |search()|. Additionally:
9210 'r' Repeat until no more matches found; will find the
9211 outer pair. Implies the 'W' flag.
9212 'm' Return number of matches instead of line number with
9213 the match; will be > 1 when 'r' is used.
9214 Note: it's nearly always a good idea to use the 'W' flag, to
9215 avoid wrapping around the end of the file.
9216
9217 When a match for {start}, {middle} or {end} is found, the
9218 {skip} expression is evaluated with the cursor positioned on
9219 the start of the match. It should return non-zero if this
9220 match is to be skipped. E.g., because it is inside a comment
9221 or a string.
9222 When {skip} is omitted or empty, every match is accepted.
9223 When evaluating {skip} causes an error the search is aborted
9224 and -1 returned.
9225 {skip} can be a string, a lambda, a funcref or a partial.
9226 Anything else makes the function fail.
9227 In a `:def` function when the {skip} argument is a string
9228 constant it is compiled into instructions.
9229
9230 For {stopline} and {timeout} see |search()|.
9231
9232 The value of 'ignorecase' is used. 'magic' is ignored, the
9233 patterns are used like it's on.
9234
9235 The search starts exactly at the cursor. A match with
9236 {start}, {middle} or {end} at the next character, in the
9237 direction of searching, is the first one found. Example: >
9238 if 1
9239 if 2
9240 endif 2
9241 endif 1
9242< When starting at the "if 2", with the cursor on the "i", and
9243 searching forwards, the "endif 2" is found. When starting on
9244 the character just before the "if 2", the "endif 1" will be
9245 found. That's because the "if 2" will be found first, and
9246 then this is considered to be a nested if/endif from "if 2" to
9247 "endif 2".
9248 When searching backwards and {end} is more than one character,
9249 it may be useful to put "\zs" at the end of the pattern, so
9250 that when the cursor is inside a match with the end it finds
9251 the matching start.
9252
9253 Example, to find the "endif" command in a Vim script: >
9254
9255 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
9256 \ 'getline(".") =~ "^\\s*\""')
9257
9258< The cursor must be at or after the "if" for which a match is
9259 to be found. Note that single-quote strings are used to avoid
9260 having to double the backslashes. The skip expression only
9261 catches comments at the start of a line, not after a command.
9262 Also, a word "en" or "if" halfway a line is considered a
9263 match.
9264 Another example, to search for the matching "{" of a "}": >
9265
9266 :echo searchpair('{', '', '}', 'bW')
9267
9268< This works when the cursor is at or before the "}" for which a
9269 match is to be found. To reject matches that syntax
9270 highlighting recognized as strings: >
9271
9272 :echo searchpair('{', '', '}', 'bW',
9273 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
9274<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009275 Return type: |Number|
9276
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009277 *searchpairpos()*
9278searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
9279 [, {stopline} [, {timeout}]]]])
9280 Same as |searchpair()|, but returns a |List| with the line and
9281 column position of the match. The first element of the |List|
9282 is the line number and the second element is the byte index of
9283 the column position of the match. If no match is found,
9284 returns [0, 0]. >
9285
9286 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
9287<
9288 See |match-parens| for a bigger and more useful example.
9289
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009290 Return type: list<number>
9291
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009292 *searchpos()*
9293searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
9294 Same as |search()|, but returns a |List| with the line and
9295 column position of the match. The first element of the |List|
9296 is the line number and the second element is the byte index of
9297 the column position of the match. If no match is found,
9298 returns [0, 0].
9299 Example: >
9300 :let [lnum, col] = searchpos('mypattern', 'n')
9301
9302< When the 'p' flag is given then there is an extra item with
9303 the sub-pattern match number |search()-sub-match|. Example: >
9304 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
9305< In this example "submatch" is 2 when a lowercase letter is
9306 found |/\l|, 3 when an uppercase letter is found |/\u|.
9307
9308 Can also be used as a |method|: >
9309 GetPattern()->searchpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009310<
9311 Return type: list<number>
9312
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009313
9314server2client({clientid}, {string}) *server2client()*
9315 Send a reply string to {clientid}. The most recent {clientid}
9316 that sent a string can be retrieved with expand("<client>").
9317 {only available when compiled with the |+clientserver| feature}
9318 Returns zero for success, -1 for failure.
9319 Note:
9320 This id has to be stored before the next command can be
9321 received. I.e. before returning from the received command and
9322 before calling any commands that waits for input.
9323 See also |clientserver|.
9324 Example: >
9325 :echo server2client(expand("<client>"), "HELLO")
9326
9327< Can also be used as a |method|: >
9328 GetClientId()->server2client(string)
9329<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009330 Return type: |Number|
9331
9332
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009333serverlist() *serverlist()*
9334 Return a list of available server names, one per line.
9335 When there are no servers or the information is not available
9336 an empty string is returned. See also |clientserver|.
9337 {only available when compiled with the |+clientserver| feature}
9338 Example: >
9339 :echo serverlist()
9340<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009341 Return type: |String|
9342
9343
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009344setbufline({buf}, {lnum}, {text}) *setbufline()*
9345 Set line {lnum} to {text} in buffer {buf}. This works like
9346 |setline()| for the specified buffer.
9347
9348 This function works only for loaded buffers. First call
9349 |bufload()| if needed.
9350
9351 To insert lines use |appendbufline()|.
9352 Any text properties in {lnum} are cleared.
9353
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00009354 {text} can be a string to set one line, or a List of strings
9355 to set multiple lines. If the List extends below the last
9356 line then those lines are added. If the List is empty then
9357 nothing is changed and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009358
9359 For the use of {buf}, see |bufname()| above.
9360
9361 {lnum} is used like with |setline()|.
9362 Use "$" to refer to the last line in buffer {buf}.
9363 When {lnum} is just below the last line the {text} will be
9364 added below the last line.
9365
9366 When {buf} is not a valid buffer, the buffer is not loaded or
9367 {lnum} is not valid then 1 is returned. In |Vim9| script an
9368 error is given.
9369 On success 0 is returned.
9370
9371 Can also be used as a |method|, the base is passed as the
9372 third argument: >
9373 GetText()->setbufline(buf, lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009374<
9375 Return type: |Number|
9376
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009377
9378setbufvar({buf}, {varname}, {val}) *setbufvar()*
9379 Set option or local variable {varname} in buffer {buf} to
9380 {val}.
9381 This also works for a global or local window option, but it
9382 doesn't work for a global or local window variable.
9383 For a local window option the global value is unchanged.
9384 For the use of {buf}, see |bufname()| above.
9385 The {varname} argument is a string.
9386 Note that the variable name without "b:" must be used.
9387 Examples: >
9388 :call setbufvar(1, "&mod", 1)
9389 :call setbufvar("todo", "myvar", "foobar")
9390< This function is not available in the |sandbox|.
9391
9392 Can also be used as a |method|, the base is passed as the
9393 third argument: >
9394 GetValue()->setbufvar(buf, varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009395<
9396 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009397
9398
9399setcellwidths({list}) *setcellwidths()*
9400 Specify overrides for cell widths of character ranges. This
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009401 tells Vim how wide characters are when displayed in the
9402 terminal, counted in screen cells. The values override
9403 'ambiwidth'. Example: >
9404 call setcellwidths([
Bram Moolenaar938ae282023-02-20 20:44:55 +00009405 \ [0x111, 0x111, 1],
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009406 \ [0x2194, 0x2199, 2],
9407 \ ])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009408
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009409< The {list} argument is a List of Lists with each three
9410 numbers: [{low}, {high}, {width}]. *E1109* *E1110*
9411 {low} and {high} can be the same, in which case this refers to
9412 one character. Otherwise it is the range of characters from
9413 {low} to {high} (inclusive). *E1111* *E1114*
K.Takata71933232023-01-20 16:00:55 +00009414 Only characters with value 0x80 and higher can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009415
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009416 {width} must be either 1 or 2, indicating the character width
9417 in screen cells. *E1112*
9418 An error is given if the argument is invalid, also when a
Bram Moolenaar938ae282023-02-20 20:44:55 +00009419 range overlaps with another. *E1113*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009420
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009421 If the new value causes 'fillchars' or 'listchars' to become
9422 invalid it is rejected and an error is given.
9423
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009424 To clear the overrides pass an empty {list}: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009425 setcellwidths([]);
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009426
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009427< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009428 the effect for known emoji characters. Move the cursor
9429 through the text to check if the cell widths of your terminal
9430 match with what Vim knows about each emoji. If it doesn't
9431 look right you need to adjust the {list} argument.
9432
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009433 Return type: |Number|
9434
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009435
9436setcharpos({expr}, {list}) *setcharpos()*
9437 Same as |setpos()| but uses the specified column number as the
9438 character index instead of the byte index in the line.
9439
9440 Example:
9441 With the text "여보세요" in line 8: >
9442 call setcharpos('.', [0, 8, 4, 0])
9443< positions the cursor on the fourth character '요'. >
9444 call setpos('.', [0, 8, 4, 0])
9445< positions the cursor on the second character '보'.
9446
9447 Can also be used as a |method|: >
9448 GetPosition()->setcharpos('.')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009449<
9450 Return type: |Number|
9451
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009452
9453setcharsearch({dict}) *setcharsearch()*
9454 Set the current character search information to {dict},
9455 which contains one or more of the following entries:
9456
9457 char character which will be used for a subsequent
9458 |,| or |;| command; an empty string clears the
9459 character search
9460 forward direction of character search; 1 for forward,
9461 0 for backward
9462 until type of character search; 1 for a |t| or |T|
9463 character search, 0 for an |f| or |F|
9464 character search
9465
9466 This can be useful to save/restore a user's character search
9467 from a script: >
9468 :let prevsearch = getcharsearch()
9469 :" Perform a command which clobbers user's search
9470 :call setcharsearch(prevsearch)
9471< Also see |getcharsearch()|.
9472
9473 Can also be used as a |method|: >
9474 SavedSearch()->setcharsearch()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009475<
9476 Return type: dict<any>
9477
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009478
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009479setcmdline({str} [, {pos}]) *setcmdline()*
9480 Set the command line to {str} and set the cursor position to
9481 {pos}.
9482 If {pos} is omitted, the cursor is positioned after the text.
9483 Returns 0 when successful, 1 when not editing the command
9484 line.
9485
9486 Can also be used as a |method|: >
9487 GetText()->setcmdline()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009488<
9489 Return type: |Number|
9490
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009491
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009492setcmdpos({pos}) *setcmdpos()*
9493 Set the cursor position in the command line to byte position
9494 {pos}. The first position is 1.
9495 Use |getcmdpos()| to obtain the current position.
9496 Only works while editing the command line, thus you must use
9497 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
9498 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
9499 set after the command line is set to the expression. For
9500 |c_CTRL-R_=| it is set after evaluating the expression but
9501 before inserting the resulting text.
9502 When the number is too big the cursor is put at the end of the
9503 line. A number smaller than one has undefined results.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009504 Returns 0 when successful, 1 when not editing the command
9505 line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009506
9507 Can also be used as a |method|: >
9508 GetPos()->setcmdpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009509<
9510 Return type: |Number|
9511
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009512
9513setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
9514setcursorcharpos({list})
9515 Same as |cursor()| but uses the specified column number as the
9516 character index instead of the byte index in the line.
9517
9518 Example:
9519 With the text "여보세요" in line 4: >
9520 call setcursorcharpos(4, 3)
9521< positions the cursor on the third character '세'. >
9522 call cursor(4, 3)
9523< positions the cursor on the first character '여'.
9524
9525 Can also be used as a |method|: >
9526 GetCursorPos()->setcursorcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009527<
9528 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009529
9530
9531setenv({name}, {val}) *setenv()*
9532 Set environment variable {name} to {val}. Example: >
9533 call setenv('HOME', '/home/myhome')
9534
9535< When {val} is |v:null| the environment variable is deleted.
9536 See also |expr-env|.
9537
9538 Can also be used as a |method|, the base is passed as the
9539 second argument: >
9540 GetPath()->setenv('PATH')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009541<
9542 Return type: |Number|
9543
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009544
9545setfperm({fname}, {mode}) *setfperm()* *chmod*
9546 Set the file permissions for {fname} to {mode}.
9547 {mode} must be a string with 9 characters. It is of the form
9548 "rwxrwxrwx", where each group of "rwx" flags represent, in
9549 turn, the permissions of the owner of the file, the group the
9550 file belongs to, and other users. A '-' character means the
9551 permission is off, any other character means on. Multi-byte
9552 characters are not supported.
9553
9554 For example "rw-r-----" means read-write for the user,
9555 readable by the group, not accessible by others. "xx-x-----"
9556 would do the same thing.
9557
9558 Returns non-zero for success, zero for failure.
9559
9560 Can also be used as a |method|: >
9561 GetFilename()->setfperm(mode)
9562<
9563 To read permissions see |getfperm()|.
9564
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009565 Return type: |Number|
9566
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009567
9568setline({lnum}, {text}) *setline()*
9569 Set line {lnum} of the current buffer to {text}. To insert
9570 lines use |append()|. To set lines in another buffer use
Christian Brabandt946f61c2024-06-17 13:17:58 +02009571 |setbufline()|.
h-east52e7cc22024-07-28 17:03:29 +02009572 Any text properties in {lnum} are cleared. See
9573 |text-prop-cleared|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009574
9575 {lnum} is used like with |getline()|.
9576 When {lnum} is just below the last line the {text} will be
9577 added below the last line.
9578 {text} can be any type or a List of any type, each item is
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00009579 converted to a String. When {text} is an empty List then
9580 nothing is changed and FALSE is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009581
9582 If this succeeds, FALSE is returned. If this fails (most likely
9583 because {lnum} is invalid) TRUE is returned.
9584 In |Vim9| script an error is given if {lnum} is invalid.
9585
9586 Example: >
9587 :call setline(5, strftime("%c"))
9588
9589< When {text} is a |List| then line {lnum} and following lines
9590 will be set to the items in the list. Example: >
9591 :call setline(5, ['aaa', 'bbb', 'ccc'])
9592< This is equivalent to: >
9593 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
9594 : call setline(n, l)
9595 :endfor
9596
9597< Note: The '[ and '] marks are not set.
9598
9599 Can also be used as a |method|, the base is passed as the
9600 second argument: >
9601 GetText()->setline(lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009602<
9603 Return type: |Number|
9604
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009605
9606setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
9607 Create or replace or add to the location list for window {nr}.
9608 {nr} can be the window number or the |window-ID|.
9609 When {nr} is zero the current window is used.
9610
9611 For a location list window, the displayed location list is
9612 modified. For an invalid window number {nr}, -1 is returned.
9613 Otherwise, same as |setqflist()|.
9614 Also see |location-list|.
9615
9616 For {action} see |setqflist-action|.
9617
9618 If the optional {what} dictionary argument is supplied, then
9619 only the items listed in {what} are set. Refer to |setqflist()|
9620 for the list of supported keys in {what}.
9621
9622 Can also be used as a |method|, the base is passed as the
9623 second argument: >
9624 GetLoclist()->setloclist(winnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009625<
9626 Return type: |Number|
9627
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009628
9629setmatches({list} [, {win}]) *setmatches()*
9630 Restores a list of matches saved by |getmatches()| for the
9631 current window. Returns 0 if successful, otherwise -1. All
9632 current matches are cleared before the list is restored. See
9633 example for |getmatches()|.
9634 If {win} is specified, use the window with this number or
9635 window ID instead of the current window.
9636
9637 Can also be used as a |method|: >
9638 GetMatches()->setmatches()
9639<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009640 Return type: |Number|
9641
9642
9643setpos({expr}, {list}) *setpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009644 Set the position for String {expr}. Possible values:
9645 . the cursor
9646 'x mark x
9647
9648 {list} must be a |List| with four or five numbers:
9649 [bufnum, lnum, col, off]
9650 [bufnum, lnum, col, off, curswant]
9651
9652 "bufnum" is the buffer number. Zero can be used for the
9653 current buffer. When setting an uppercase mark "bufnum" is
9654 used for the mark position. For other marks it specifies the
9655 buffer to set the mark in. You can use the |bufnr()| function
9656 to turn a file name into a buffer number.
9657 For setting the cursor and the ' mark "bufnum" is ignored,
9658 since these are associated with a window, not a buffer.
9659 Does not change the jumplist.
9660
9661 "lnum" and "col" are the position in the buffer. The first
9662 column is 1. Use a zero "lnum" to delete a mark. If "col" is
9663 smaller than 1 then 1 is used. To use the character count
9664 instead of the byte count, use |setcharpos()|.
9665
9666 The "off" number is only used when 'virtualedit' is set. Then
9667 it is the offset in screen columns from the start of the
9668 character. E.g., a position within a <Tab> or after the last
9669 character.
9670
9671 The "curswant" number is only used when setting the cursor
9672 position. It sets the preferred column for when moving the
9673 cursor vertically. When the "curswant" number is missing the
9674 preferred column is not set. When it is present and setting a
9675 mark position it is not used.
9676
9677 Note that for '< and '> changing the line number may result in
9678 the marks to be effectively be swapped, so that '< is always
9679 before '>.
9680
9681 Returns 0 when the position could be set, -1 otherwise.
9682 An error message is given if {expr} is invalid.
9683
9684 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
9685
9686 This does not restore the preferred column for moving
9687 vertically; if you set the cursor position with this, |j| and
9688 |k| motions will jump to previous columns! Use |cursor()| to
9689 also set the preferred column. Also see the "curswant" key in
9690 |winrestview()|.
9691
9692 Can also be used as a |method|: >
9693 GetPosition()->setpos('.')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009694<
9695 Return type: |Number|
9696
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009697
9698setqflist({list} [, {action} [, {what}]]) *setqflist()*
9699 Create or replace or add to the quickfix list.
9700
9701 If the optional {what} dictionary argument is supplied, then
9702 only the items listed in {what} are set. The first {list}
9703 argument is ignored. See below for the supported items in
9704 {what}.
9705 *setqflist-what*
9706 When {what} is not present, the items in {list} are used. Each
9707 item must be a dictionary. Non-dictionary items in {list} are
9708 ignored. Each dictionary item can contain the following
9709 entries:
9710
9711 bufnr buffer number; must be the number of a valid
9712 buffer
9713 filename name of a file; only used when "bufnr" is not
9714 present or it is invalid.
9715 module name of a module; if given it will be used in
9716 quickfix error window instead of the filename.
9717 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +00009718 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009719 pattern search pattern used to locate the error
9720 col column number
9721 vcol when non-zero: "col" is visual column
9722 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +00009723 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009724 nr error number
9725 text description of the error
9726 type single-character error type, 'E', 'W', etc.
9727 valid recognized error message
Tom Praschanca6ac992023-08-11 23:26:12 +02009728 user_data custom data associated with the item, can be
9729 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009730
9731 The "col", "vcol", "nr", "type" and "text" entries are
9732 optional. Either "lnum" or "pattern" entry can be used to
9733 locate a matching error line.
9734 If the "filename" and "bufnr" entries are not present or
9735 neither the "lnum" or "pattern" entries are present, then the
9736 item will not be handled as an error line.
9737 If both "pattern" and "lnum" are present then "pattern" will
9738 be used.
9739 If the "valid" entry is not supplied, then the valid flag is
9740 set when "bufnr" is a valid buffer or "filename" exists.
9741 If you supply an empty {list}, the quickfix list will be
9742 cleared.
9743 Note that the list is not exactly the same as what
9744 |getqflist()| returns.
9745
9746 {action} values: *setqflist-action* *E927*
9747 'a' The items from {list} are added to the existing
9748 quickfix list. If there is no existing list, then a
9749 new list is created.
9750
9751 'r' The items from the current quickfix list are replaced
9752 with the items from {list}. This can also be used to
9753 clear the list: >
9754 :call setqflist([], 'r')
9755<
9756 'f' All the quickfix lists in the quickfix stack are
9757 freed.
9758
9759 If {action} is not present or is set to ' ', then a new list
9760 is created. The new quickfix list is added after the current
9761 quickfix list in the stack and all the following lists are
9762 freed. To add a new quickfix list at the end of the stack,
9763 set "nr" in {what} to "$".
9764
9765 The following items can be specified in dictionary {what}:
9766 context quickfix list context. See |quickfix-context|
9767 efm errorformat to use when parsing text from
9768 "lines". If this is not present, then the
9769 'errorformat' option value is used.
9770 See |quickfix-parse|
9771 id quickfix list identifier |quickfix-ID|
9772 idx index of the current entry in the quickfix
9773 list specified by 'id' or 'nr'. If set to '$',
9774 then the last entry in the list is set as the
9775 current entry. See |quickfix-index|
9776 items list of quickfix entries. Same as the {list}
9777 argument.
9778 lines use 'errorformat' to parse a list of lines and
9779 add the resulting entries to the quickfix list
9780 {nr} or {id}. Only a |List| value is supported.
9781 See |quickfix-parse|
9782 nr list number in the quickfix stack; zero
9783 means the current quickfix list and "$" means
9784 the last quickfix list.
9785 quickfixtextfunc
9786 function to get the text to display in the
9787 quickfix window. The value can be the name of
9788 a function or a funcref or a lambda. Refer to
9789 |quickfix-window-function| for an explanation
9790 of how to write the function and an example.
9791 title quickfix list title text. See |quickfix-title|
9792 Unsupported keys in {what} are ignored.
9793 If the "nr" item is not present, then the current quickfix list
9794 is modified. When creating a new quickfix list, "nr" can be
9795 set to a value one greater than the quickfix stack size.
9796 When modifying a quickfix list, to guarantee that the correct
9797 list is modified, "id" should be used instead of "nr" to
9798 specify the list.
9799
9800 Examples (See also |setqflist-examples|): >
9801 :call setqflist([], 'r', {'title': 'My search'})
9802 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
9803 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
9804<
9805 Returns zero for success, -1 for failure.
9806
9807 This function can be used to create a quickfix list
9808 independent of the 'errorformat' setting. Use a command like
9809 `:cc 1` to jump to the first position.
9810
9811 Can also be used as a |method|, the base is passed as the
9812 second argument: >
9813 GetErrorlist()->setqflist()
9814<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009815 Return type: |Number|
9816
9817
9818setreg({regname}, {value} [, {options}]) *setreg()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009819 Set the register {regname} to {value}.
9820 If {regname} is "" or "@", the unnamed register '"' is used.
9821 The {regname} argument is a string. In |Vim9-script|
9822 {regname} must be one character.
9823
9824 {value} may be any value returned by |getreg()| or
9825 |getreginfo()|, including a |List| or |Dict|.
9826 If {options} contains "a" or {regname} is upper case,
9827 then the value is appended.
9828
9829 {options} can also contain a register type specification:
9830 "c" or "v" |characterwise| mode
9831 "l" or "V" |linewise| mode
9832 "b" or "<CTRL-V>" |blockwise-visual| mode
9833 If a number immediately follows "b" or "<CTRL-V>" then this is
9834 used as the width of the selection - if it is not specified
9835 then the width of the block is set to the number of characters
9836 in the longest line (counting a <Tab> as 1 character).
9837
9838 If {options} contains no register settings, then the default
9839 is to use character mode unless {value} ends in a <NL> for
9840 string {value} and linewise mode for list {value}. Blockwise
9841 mode is never selected automatically.
9842 Returns zero for success, non-zero for failure.
9843
9844 *E883*
9845 Note: you may not use |List| containing more than one item to
9846 set search and expression registers. Lists containing no
9847 items act like empty strings.
9848
9849 Examples: >
9850 :call setreg(v:register, @*)
9851 :call setreg('*', @%, 'ac')
9852 :call setreg('a', "1\n2\n3", 'b5')
9853 :call setreg('"', { 'points_to': 'a'})
9854
9855< This example shows using the functions to save and restore a
9856 register: >
9857 :let var_a = getreginfo()
9858 :call setreg('a', var_a)
9859< or: >
9860 :let var_a = getreg('a', 1, 1)
9861 :let var_amode = getregtype('a')
9862 ....
9863 :call setreg('a', var_a, var_amode)
9864< Note: you may not reliably restore register value
9865 without using the third argument to |getreg()| as without it
9866 newlines are represented as newlines AND Nul bytes are
9867 represented as newlines as well, see |NL-used-for-Nul|.
9868
9869 You can also change the type of a register by appending
9870 nothing: >
9871 :call setreg('a', '', 'al')
9872
9873< Can also be used as a |method|, the base is passed as the
9874 second argument: >
9875 GetText()->setreg('a')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009876<
9877 Return type: |Number|
9878
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009879
9880settabvar({tabnr}, {varname}, {val}) *settabvar()*
9881 Set tab-local variable {varname} to {val} in tab page {tabnr}.
9882 |t:var|
9883 The {varname} argument is a string.
9884 Note that autocommands are blocked, side effects may not be
9885 triggered, e.g. when setting 'filetype'.
9886 Note that the variable name without "t:" must be used.
9887 Tabs are numbered starting with one.
9888 This function is not available in the |sandbox|.
9889
9890 Can also be used as a |method|, the base is passed as the
9891 third argument: >
9892 GetValue()->settabvar(tab, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009893<
9894 Return type: |Number|
9895
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009896
9897settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
9898 Set option or local variable {varname} in window {winnr} to
9899 {val}.
9900 Tabs are numbered starting with one. For the current tabpage
9901 use |setwinvar()|.
9902 {winnr} can be the window number or the |window-ID|.
9903 When {winnr} is zero the current window is used.
9904 Note that autocommands are blocked, side effects may not be
9905 triggered, e.g. when setting 'filetype' or 'syntax'.
9906 This also works for a global or local buffer option, but it
9907 doesn't work for a global or local buffer variable.
9908 For a local buffer option the global value is unchanged.
9909 Note that the variable name without "w:" must be used.
9910 Examples: >
9911 :call settabwinvar(1, 1, "&list", 0)
9912 :call settabwinvar(3, 2, "myvar", "foobar")
9913< This function is not available in the |sandbox|.
9914
9915 Can also be used as a |method|, the base is passed as the
9916 fourth argument: >
9917 GetValue()->settabwinvar(tab, winnr, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009918<
9919 Return type: |Number|
9920
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009921
9922settagstack({nr}, {dict} [, {action}]) *settagstack()*
9923 Modify the tag stack of the window {nr} using {dict}.
9924 {nr} can be the window number or the |window-ID|.
9925
9926 For a list of supported items in {dict}, refer to
9927 |gettagstack()|. "curidx" takes effect before changing the tag
9928 stack.
9929 *E962*
9930 How the tag stack is modified depends on the {action}
9931 argument:
9932 - If {action} is not present or is set to 'r', then the tag
9933 stack is replaced.
9934 - If {action} is set to 'a', then new entries from {dict} are
9935 pushed (added) onto the tag stack.
9936 - If {action} is set to 't', then all the entries from the
9937 current entry in the tag stack or "curidx" in {dict} are
9938 removed and then new entries are pushed to the stack.
9939
9940 The current index is set to one after the length of the tag
9941 stack after the modification.
9942
9943 Returns zero for success, -1 for failure.
9944
9945 Examples (for more examples see |tagstack-examples|):
9946 Empty the tag stack of window 3: >
9947 call settagstack(3, {'items' : []})
9948
9949< Save and restore the tag stack: >
9950 let stack = gettagstack(1003)
9951 " do something else
9952 call settagstack(1003, stack)
9953 unlet stack
9954<
9955 Can also be used as a |method|, the base is passed as the
9956 second argument: >
9957 GetStack()->settagstack(winnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009958<
9959 Return type: |Number|
9960
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009961
9962setwinvar({winnr}, {varname}, {val}) *setwinvar()*
9963 Like |settabwinvar()| for the current tab page.
9964 Examples: >
9965 :call setwinvar(1, "&list", 0)
9966 :call setwinvar(2, "myvar", "foobar")
9967
9968< Can also be used as a |method|, the base is passed as the
9969 third argument: >
9970 GetValue()->setwinvar(winnr, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009971<
9972 Return type: |Number|
9973
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009974
9975sha256({string}) *sha256()*
9976 Returns a String with 64 hex characters, which is the SHA256
9977 checksum of {string}.
9978
9979 Can also be used as a |method|: >
9980 GetText()->sha256()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009981<
9982 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009983
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009984 {only available when compiled with the |+cryptv| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009985
9986shellescape({string} [, {special}]) *shellescape()*
9987 Escape {string} for use as a shell command argument.
9988 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +00009989 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009990 in single quotes and will double up all internal single
9991 quotes.
9992 On MS-Windows, when 'shellslash' is not set, it will enclose
9993 {string} in double quotes and double all double quotes within
9994 {string}.
9995 Otherwise it will enclose {string} in single quotes and
9996 replace all "'" with "'\''".
9997
Enno5faeb602024-05-15 21:54:19 +02009998 The {special} argument adds additional escaping of keywords
9999 used in Vim commands. When it is not omitted and a non-zero
K.Takatac0e038b2024-05-16 12:39:01 +090010000 number or a non-empty String (|non-zero-arg|), then special
10001 items such as "!", "%", "#" and "<cword>" (as listed in
10002 |expand()|) will be preceded by a backslash.
Enno5faeb602024-05-15 21:54:19 +020010003 This backslash will be removed again by the |:!| command.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010004
10005 The "!" character will be escaped (again with a |non-zero-arg|
10006 {special}) when 'shell' contains "csh" in the tail. That is
10007 because for csh and tcsh "!" is used for history replacement
10008 even when inside single quotes.
10009
10010 With a |non-zero-arg| {special} the <NL> character is also
10011 escaped. When 'shell' containing "csh" in the tail it's
10012 escaped a second time.
10013
10014 The "\" character will be escaped when 'shell' contains "fish"
10015 in the tail. That is because for fish "\" is used as an escape
10016 character inside single quotes.
10017
10018 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010019 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010020< This results in a directory listing for the file under the
10021 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010022 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010023< See also |::S|.
10024
10025 Can also be used as a |method|: >
10026 GetCommand()->shellescape()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010027<
10028 Return type: |String|
10029
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010030
10031shiftwidth([{col}]) *shiftwidth()*
10032 Returns the effective value of 'shiftwidth'. This is the
10033 'shiftwidth' value unless it is zero, in which case it is the
10034 'tabstop' value. This function was introduced with patch
10035 7.3.694 in 2012, everybody should have it by now (however it
10036 did not allow for the optional {col} argument until 8.1.542).
10037
10038 When there is one argument {col} this is used as column number
10039 for which to return the 'shiftwidth' value. This matters for the
10040 'vartabstop' feature. If the 'vartabstop' setting is enabled and
10041 no {col} argument is given, column 1 will be assumed.
10042
10043 Can also be used as a |method|: >
10044 GetColumn()->shiftwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010045<
10046 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010047
10048sign_ functions are documented here: |sign-functions-details|
10049
10050
10051simplify({filename}) *simplify()*
10052 Simplify the file name as much as possible without changing
10053 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
10054 Unix) are not resolved. If the first path component in
10055 {filename} designates the current directory, this will be
10056 valid for the result as well. A trailing path separator is
10057 not removed either. On Unix "//path" is unchanged, but
10058 "///path" is simplified to "/path" (this follows the Posix
10059 standard).
10060 Example: >
10061 simplify("./dir/.././/file/") == "./file/"
10062< Note: The combination "dir/.." is only removed if "dir" is
10063 a searchable directory or does not exist. On Unix, it is also
10064 removed when "dir" is a symbolic link within the same
10065 directory. In order to resolve all the involved symbolic
10066 links before simplifying the path name, use |resolve()|.
10067
10068 Can also be used as a |method|: >
10069 GetName()->simplify()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010070<
10071 Return type: |String|
10072
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010073
10074sin({expr}) *sin()*
10075 Return the sine of {expr}, measured in radians, as a |Float|.
10076 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010077 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010078 Examples: >
10079 :echo sin(100)
10080< -0.506366 >
10081 :echo sin(-4.01)
10082< 0.763301
10083
10084 Can also be used as a |method|: >
10085 Compute()->sin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010086<
10087 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010088
10089
10090sinh({expr}) *sinh()*
10091 Return the hyperbolic sine of {expr} as a |Float| in the range
10092 [-inf, inf].
10093 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010094 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010095 Examples: >
10096 :echo sinh(0.5)
10097< 0.521095 >
10098 :echo sinh(-0.9)
10099< -1.026517
10100
10101 Can also be used as a |method|: >
10102 Compute()->sinh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010103<
10104 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010105
10106
10107slice({expr}, {start} [, {end}]) *slice()*
10108 Similar to using a |slice| "expr[start : end]", but "end" is
10109 used exclusive. And for a string the indexes are used as
10110 character indexes instead of byte indexes, like in
zeertzjqad387692024-03-23 08:23:48 +010010111 |vim9script|. Also, composing characters are treated as a
10112 part of the preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010113 When {end} is omitted the slice continues to the last item.
10114 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010115 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010116
10117 Can also be used as a |method|: >
10118 GetList()->slice(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010119<
10120 Return type: list<{type}>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010121
10122
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010123sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010124 Sort the items in {list} in-place. Returns {list}.
10125
10126 If you want a list to remain unmodified make a copy first: >
10127 :let sortedlist = sort(copy(mylist))
10128
Bram Moolenaar2d8ed022022-05-21 13:08:16 +010010129< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010130 string representation of each item to sort on. Numbers sort
10131 after Strings, |Lists| after Numbers. For sorting text in the
10132 current buffer use |:sort|.
10133
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010134 When {how} is given and it is 'i' then case is ignored.
10135 In legacy script, for backwards compatibility, the value one
10136 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010137
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010138 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010139 locale is used for ordering. Implementation details: strcoll()
10140 is used to compare strings. See |:language| check or set the
10141 collation locale. |v:collate| can also be used to check the
10142 current locale. Sorting using the locale typically ignores
10143 case. Example: >
10144 " ö is sorted similarly to o with English locale.
10145 :language collate en_US.UTF8
10146 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10147< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
10148>
10149 " ö is sorted after z with Swedish locale.
10150 :language collate sv_SE.UTF8
10151 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10152< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
10153 This does not work properly on Mac.
10154
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010155 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010156 sorted numerical (Implementation detail: this uses the
Bram Moolenaarbe19d782023-03-09 22:06:49 +000010157 strtod() function to parse numbers. Strings, Lists, Dicts and
10158 Funcrefs will be considered as being 0). Note that this won't
10159 sort a list of strings with numbers!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010160
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010161 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010162 sorted numerical. This is like 'n' but a string containing
10163 digits will be used as the number they represent.
10164
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010165 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010166 sorted numerical. All values must be a Number or a Float.
10167
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010168 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010169 is called to compare items. The function is invoked with two
10170 items as argument and must return zero if they are equal, 1 or
10171 bigger if the first one sorts after the second one, -1 or
10172 smaller if the first one sorts before the second one.
10173
10174 {dict} is for functions with the "dict" attribute. It will be
10175 used to set the local variable "self". |Dictionary-function|
10176
10177 The sort is stable, items which compare equal (as number or as
10178 string) will keep their relative position. E.g., when sorting
10179 on numbers, text strings will sort next to each other, in the
10180 same order as they were originally.
10181
10182 Can also be used as a |method|: >
10183 mylist->sort()
10184
10185< Also see |uniq()|.
10186
10187 Example: >
10188 func MyCompare(i1, i2)
10189 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
10190 endfunc
10191 eval mylist->sort("MyCompare")
10192< A shorter compare version for this specific simple case, which
10193 ignores overflow: >
10194 func MyCompare(i1, i2)
10195 return a:i1 - a:i2
10196 endfunc
10197< For a simple expression you can use a lambda: >
10198 eval mylist->sort({i1, i2 -> i1 - i2})
10199<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010200 Return type: list<{type}>
10201
10202
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010203sound_clear() *sound_clear()*
10204 Stop playing all sounds.
10205
10206 On some Linux systems you may need the libcanberra-pulse
10207 package, otherwise sound may not stop.
10208
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010209 Return type: |Number|
10210
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010211 {only available when compiled with the |+sound| feature}
10212
10213 *sound_playevent()*
10214sound_playevent({name} [, {callback}])
10215 Play a sound identified by {name}. Which event names are
10216 supported depends on the system. Often the XDG sound names
10217 are used. On Ubuntu they may be found in
10218 /usr/share/sounds/freedesktop/stereo. Example: >
10219 call sound_playevent('bell')
10220< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
10221 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
10222 SystemStart, SystemWelcome, etc.
Yee Cheng Chin4314e4f2022-10-08 13:50:05 +010010223 On macOS, {name} refers to files located in
10224 /System/Library/Sounds (e.g. "Tink"). It will also work for
10225 custom installed sounds in folders like ~/Library/Sounds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010226
10227 When {callback} is specified it is invoked when the sound is
10228 finished. The first argument is the sound ID, the second
10229 argument is the status:
10230 0 sound was played to the end
10231 1 sound was interrupted
10232 2 error occurred after sound started
10233 Example: >
10234 func Callback(id, status)
10235 echomsg "sound " .. a:id .. " finished with " .. a:status
10236 endfunc
10237 call sound_playevent('bell', 'Callback')
10238
10239< MS-Windows: {callback} doesn't work for this function.
10240
10241 Returns the sound ID, which can be passed to `sound_stop()`.
10242 Returns zero if the sound could not be played.
10243
10244 Can also be used as a |method|: >
10245 GetSoundName()->sound_playevent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010246<
10247 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010248
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010249 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010250
10251 *sound_playfile()*
10252sound_playfile({path} [, {callback}])
10253 Like `sound_playevent()` but play sound file {path}. {path}
10254 must be a full path. On Ubuntu you may find files to play
10255 with this command: >
10256 :!find /usr/share/sounds -type f | grep -v index.theme
10257
10258< Can also be used as a |method|: >
10259 GetSoundPath()->sound_playfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010260<
10261 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010262
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010263 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010264
10265
10266sound_stop({id}) *sound_stop()*
10267 Stop playing sound {id}. {id} must be previously returned by
10268 `sound_playevent()` or `sound_playfile()`.
10269
10270 On some Linux systems you may need the libcanberra-pulse
10271 package, otherwise sound may not stop.
10272
10273 On MS-Windows, this does not work for event sound started by
10274 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
10275
10276 Can also be used as a |method|: >
10277 soundid->sound_stop()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010278<
10279 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010280
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010281 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010282
10283 *soundfold()*
10284soundfold({word})
10285 Return the sound-folded equivalent of {word}. Uses the first
10286 language in 'spelllang' for the current window that supports
10287 soundfolding. 'spell' must be set. When no sound folding is
10288 possible the {word} is returned unmodified.
10289 This can be used for making spelling suggestions. Note that
10290 the method can be quite slow.
10291
10292 Can also be used as a |method|: >
10293 GetWord()->soundfold()
10294<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010295 Return type: |String|
10296
10297
10298spellbadword([{sentence}]) *spellbadword()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010299 Without argument: The result is the badly spelled word under
10300 or after the cursor. The cursor is moved to the start of the
10301 bad word. When no bad word is found in the cursor line the
10302 result is an empty string and the cursor doesn't move.
10303
10304 With argument: The result is the first word in {sentence} that
10305 is badly spelled. If there are no spelling mistakes the
10306 result is an empty string.
10307
10308 The return value is a list with two items:
10309 - The badly spelled word or an empty string.
10310 - The type of the spelling error:
10311 "bad" spelling mistake
10312 "rare" rare word
10313 "local" word only valid in another region
10314 "caps" word should start with Capital
10315 Example: >
10316 echo spellbadword("the quik brown fox")
10317< ['quik', 'bad'] ~
10318
10319 The spelling information for the current window and the value
10320 of 'spelllang' are used.
10321
10322 Can also be used as a |method|: >
10323 GetText()->spellbadword()
10324<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010325 Return type: list<string>
10326
10327
10328spellsuggest({word} [, {max} [, {capital}]]) *spellsuggest()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010329 Return a |List| with spelling suggestions to replace {word}.
10330 When {max} is given up to this number of suggestions are
10331 returned. Otherwise up to 25 suggestions are returned.
10332
10333 When the {capital} argument is given and it's non-zero only
10334 suggestions with a leading capital will be given. Use this
10335 after a match with 'spellcapcheck'.
10336
10337 {word} can be a badly spelled word followed by other text.
10338 This allows for joining two words that were split. The
10339 suggestions also include the following text, thus you can
10340 replace a line.
10341
10342 {word} may also be a good word. Similar words will then be
10343 returned. {word} itself is not included in the suggestions,
10344 although it may appear capitalized.
10345
10346 The spelling information for the current window is used. The
10347 values of 'spelllang' and 'spellsuggest' are used.
10348
10349 Can also be used as a |method|: >
10350 GetWord()->spellsuggest()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010351<
10352 Return type: list<string> or list<any>
10353
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010354
10355split({string} [, {pattern} [, {keepempty}]]) *split()*
10356 Make a |List| out of {string}. When {pattern} is omitted or
Shane Harperc1b39842024-07-17 19:40:40 +020010357 empty each white space separated sequence of characters
10358 becomes an item.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010359 Otherwise the string is split where {pattern} matches,
10360 removing the matched characters. 'ignorecase' is not used
10361 here, add \c to ignore case. |/\c|
10362 When the first or last item is empty it is omitted, unless the
10363 {keepempty} argument is given and it's non-zero.
10364 Other empty items are kept when {pattern} matches at least one
10365 character or when {keepempty} is non-zero.
10366 Example: >
10367 :let words = split(getline('.'), '\W\+')
10368< To split a string in individual characters: >
10369 :for c in split(mystring, '\zs')
10370< If you want to keep the separator you can also use '\zs' at
10371 the end of the pattern: >
10372 :echo split('abc:def:ghi', ':\zs')
10373< ['abc:', 'def:', 'ghi'] ~
10374 Splitting a table where the first element can be empty: >
10375 :let items = split(line, ':', 1)
10376< The opposite function is |join()|.
10377
10378 Can also be used as a |method|: >
10379 GetString()->split()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010380<
10381 Return type: list<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010382
10383sqrt({expr}) *sqrt()*
10384 Return the non-negative square root of Float {expr} as a
10385 |Float|.
10386 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010387 is negative the result is NaN (Not a Number). Returns 0.0 if
10388 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010389 Examples: >
10390 :echo sqrt(100)
10391< 10.0 >
10392 :echo sqrt(-4.01)
10393< nan
10394 "nan" may be different, it depends on system libraries.
10395
10396 Can also be used as a |method|: >
10397 Compute()->sqrt()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010398<
10399 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010400
10401
10402srand([{expr}]) *srand()*
10403 Initialize seed used by |rand()|:
10404 - If {expr} is not given, seed values are initialized by
10405 reading from /dev/urandom, if possible, or using time(NULL)
10406 a.k.a. epoch time otherwise; this only has second accuracy.
10407 - If {expr} is given it must be a Number. It is used to
10408 initialize the seed values. This is useful for testing or
10409 when a predictable sequence is intended.
10410
10411 Examples: >
10412 :let seed = srand()
10413 :let seed = srand(userinput)
10414 :echo rand(seed)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010415<
10416 Return type: list<number>
10417
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010418
10419state([{what}]) *state()*
10420 Return a string which contains characters indicating the
10421 current state. Mostly useful in callbacks that want to do
10422 work that may not always be safe. Roughly this works like:
10423 - callback uses state() to check if work is safe to do.
10424 Yes: then do it right away.
10425 No: add to work queue and add a |SafeState| and/or
10426 |SafeStateAgain| autocommand (|SafeState| triggers at
10427 toplevel, |SafeStateAgain| triggers after handling
10428 messages and callbacks).
10429 - When SafeState or SafeStateAgain is triggered and executes
10430 your autocommand, check with `state()` if the work can be
10431 done now, and if yes remove it from the queue and execute.
10432 Remove the autocommand if the queue is now empty.
10433 Also see |mode()|.
10434
10435 When {what} is given only characters in this string will be
10436 added. E.g, this checks if the screen has scrolled: >
10437 if state('s') == ''
10438 " screen has not scrolled
10439<
10440 These characters indicate the state, generally indicating that
10441 something is busy:
10442 m halfway a mapping, :normal command, feedkeys() or
10443 stuffed command
10444 o operator pending, e.g. after |d|
10445 a Insert mode autocomplete active
10446 x executing an autocommand
10447 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
10448 ch_readraw() when reading json
10449 S not triggering SafeState or SafeStateAgain, e.g. after
10450 |f| or a count
10451 c callback invoked, including timer (repeats for
10452 recursiveness up to "ccc")
10453 s screen has scrolled for messages
10454
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010455 Return type: |String|
10456
10457
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010458str2float({string} [, {quoted}]) *str2float()*
10459 Convert String {string} to a Float. This mostly works the
10460 same as when using a floating point number in an expression,
10461 see |floating-point-format|. But it's a bit more permissive.
10462 E.g., "1e40" is accepted, while in an expression you need to
10463 write "1.0e40". The hexadecimal form "0x123" is also
10464 accepted, but not others, like binary or octal.
10465 When {quoted} is present and non-zero then embedded single
10466 quotes before the dot are ignored, thus "1'000.0" is a
10467 thousand.
10468 Text after the number is silently ignored.
10469 The decimal point is always '.', no matter what the locale is
10470 set to. A comma ends the number: "12,345.67" is converted to
10471 12.0. You can strip out thousands separators with
10472 |substitute()|: >
10473 let f = str2float(substitute(text, ',', '', 'g'))
10474<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010475 Returns 0.0 if the conversion fails.
10476
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010477 Can also be used as a |method|: >
10478 let f = text->substitute(',', '', 'g')->str2float()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010479<
10480 Return type: |Float|
10481
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010482
10483str2list({string} [, {utf8}]) *str2list()*
10484 Return a list containing the number values which represent
10485 each character in String {string}. Examples: >
10486 str2list(" ") returns [32]
10487 str2list("ABC") returns [65, 66, 67]
10488< |list2str()| does the opposite.
10489
10490 When {utf8} is omitted or zero, the current 'encoding' is used.
10491 When {utf8} is TRUE, always treat the String as UTF-8
10492 characters. With UTF-8 composing characters are handled
10493 properly: >
10494 str2list("á") returns [97, 769]
10495
10496< Can also be used as a |method|: >
10497 GetString()->str2list()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010498<
10499 Return type: list<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010500
10501
10502str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
10503 Convert string {string} to a number.
10504 {base} is the conversion base, it can be 2, 8, 10 or 16.
10505 When {quoted} is present and non-zero then embedded single
10506 quotes are ignored, thus "1'000'000" is a million.
10507
10508 When {base} is omitted base 10 is used. This also means that
10509 a leading zero doesn't cause octal conversion to be used, as
10510 with the default String to Number conversion. Example: >
10511 let nr = str2nr('0123')
10512<
10513 When {base} is 16 a leading "0x" or "0X" is ignored. With a
10514 different base the result will be zero. Similarly, when
10515 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
10516 {base} is 2 a leading "0b" or "0B" is ignored.
10517 Text after the number is silently ignored.
10518
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010519 Returns 0 if {string} is empty or on error.
10520
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010521 Can also be used as a |method|: >
10522 GetText()->str2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010523<
10524 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010525
10526
10527strcharlen({string}) *strcharlen()*
10528 The result is a Number, which is the number of characters
10529 in String {string}. Composing characters are ignored.
10530 |strchars()| can count the number of characters, counting
10531 composing characters separately.
10532
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010533 Returns 0 if {string} is empty or on error.
10534
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010535 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10536
10537 Can also be used as a |method|: >
10538 GetText()->strcharlen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010539<
10540 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010541
10542
10543strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
10544 Like |strpart()| but using character index and length instead
10545 of byte index and length.
10546 When {skipcc} is omitted or zero, composing characters are
10547 counted separately.
zeertzjqad387692024-03-23 08:23:48 +010010548 When {skipcc} set to 1, composing characters are treated as a
10549 part of the preceding base character, similar to |slice()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010550 When a character index is used where a character does not
10551 exist it is omitted and counted as one character. For
10552 example: >
10553 strcharpart('abc', -1, 2)
10554< results in 'a'.
10555
Bram Moolenaard592deb2022-06-17 15:42:40 +010010556 Returns an empty string on error.
10557
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010558 Can also be used as a |method|: >
10559 GetText()->strcharpart(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010560<
10561 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010562
10563
10564strchars({string} [, {skipcc}]) *strchars()*
10565 The result is a Number, which is the number of characters
10566 in String {string}.
10567 When {skipcc} is omitted or zero, composing characters are
10568 counted separately.
zeertzjqad387692024-03-23 08:23:48 +010010569 When {skipcc} set to 1, composing characters are ignored.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010570 |strcharlen()| always does this.
10571
Bram Moolenaard592deb2022-06-17 15:42:40 +010010572 Returns zero on error.
10573
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010574 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10575
10576 {skipcc} is only available after 7.4.755. For backward
10577 compatibility, you can define a wrapper function: >
10578 if has("patch-7.4.755")
10579 function s:strchars(str, skipcc)
10580 return strchars(a:str, a:skipcc)
10581 endfunction
10582 else
10583 function s:strchars(str, skipcc)
10584 if a:skipcc
10585 return strlen(substitute(a:str, ".", "x", "g"))
10586 else
10587 return strchars(a:str)
10588 endif
10589 endfunction
10590 endif
10591<
10592 Can also be used as a |method|: >
10593 GetText()->strchars()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010594<
10595 Return type: |Number|
10596
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010597
10598strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
10599 The result is a Number, which is the number of display cells
10600 String {string} occupies on the screen when it starts at {col}
10601 (first column is zero). When {col} is omitted zero is used.
10602 Otherwise it is the screen column where to start. This
10603 matters for Tab characters.
10604 The option settings of the current window are used. This
10605 matters for anything that's displayed differently, such as
10606 'tabstop' and 'display'.
10607 When {string} contains characters with East Asian Width Class
10608 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010609 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010610 Also see |strlen()|, |strwidth()| and |strchars()|.
10611
10612 Can also be used as a |method|: >
10613 GetText()->strdisplaywidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010614<
10615 Return type: |Number|
10616
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010617
10618strftime({format} [, {time}]) *strftime()*
10619 The result is a String, which is a formatted date and time, as
10620 specified by the {format} string. The given {time} is used,
10621 or the current time if no time is given. The accepted
10622 {format} depends on your system, thus this is not portable!
10623 See the manual page of the C function strftime() for the
10624 format. The maximum length of the result is 80 characters.
10625 See also |localtime()|, |getftime()| and |strptime()|.
10626 The language can be changed with the |:language| command.
10627 Examples: >
10628 :echo strftime("%c") Sun Apr 27 11:49:23 1997
10629 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
10630 :echo strftime("%y%m%d %T") 970427 11:53:55
10631 :echo strftime("%H:%M") 11:55
10632 :echo strftime("%c", getftime("file.c"))
10633 Show mod time of file.c.
10634< Not available on all systems. To check use: >
10635 :if exists("*strftime")
10636
10637< Can also be used as a |method|: >
10638 GetFormat()->strftime()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010639<
10640 Return type: |String|
10641
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010642
10643strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +010010644 Get a Number corresponding to the character at {index} in
10645 {str}. This uses a zero-based character index, not a byte
10646 index. Composing characters are considered separate
10647 characters here. Use |nr2char()| to convert the Number to a
10648 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010649 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010650 Also see |strcharpart()| and |strchars()|.
10651
10652 Can also be used as a |method|: >
10653 GetText()->strgetchar(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010654<
10655 Return type: |Number|
10656
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010657
10658stridx({haystack}, {needle} [, {start}]) *stridx()*
10659 The result is a Number, which gives the byte index in
10660 {haystack} of the first occurrence of the String {needle}.
10661 If {start} is specified, the search starts at index {start}.
10662 This can be used to find a second match: >
10663 :let colon1 = stridx(line, ":")
10664 :let colon2 = stridx(line, ":", colon1 + 1)
10665< The search is done case-sensitive.
10666 For pattern searches use |match()|.
10667 -1 is returned if the {needle} does not occur in {haystack}.
10668 See also |strridx()|.
10669 Examples: >
10670 :echo stridx("An Example", "Example") 3
10671 :echo stridx("Starting point", "Start") 0
10672 :echo stridx("Starting point", "start") -1
10673< *strstr()* *strchr()*
10674 stridx() works similar to the C function strstr(). When used
10675 with a single character it works similar to strchr().
10676
10677 Can also be used as a |method|: >
10678 GetHaystack()->stridx(needle)
10679<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010680 Return type: |Number|
10681
10682
10683string({expr}) *string()*
10684 Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010685 Float, String, Blob or a composition of them, then the result
10686 can be parsed back with |eval()|.
10687 {expr} type result ~
10688 String 'string' (single quotes are doubled)
10689 Number 123
10690 Float 123.123456 or 1.123456e8
10691 Funcref function('name')
10692 Blob 0z00112233.44556677.8899
10693 List [item, item]
10694 Dictionary {key: value, key: value}
Bram Moolenaarf1dcd142022-12-31 15:30:45 +000010695 Class class SomeName
10696 Object object of SomeName {lnum: 1, col: 3}
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010010697 Enum enum EnumName
Yegappan Lakshmanan3cf121e2024-03-31 18:45:35 +020010698 EnumValue enum name.value {name: str, ordinal: nr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010699
10700 When a |List| or |Dictionary| has a recursive reference it is
10701 replaced by "[...]" or "{...}". Using eval() on the result
10702 will then fail.
10703
mityu7f0bba22024-03-29 10:14:41 +010010704 For an object, invokes the string() method to get a textual
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +010010705 representation of the object. If the method is not present,
mityu7f0bba22024-03-29 10:14:41 +010010706 then the default representation is used. |object-string()|
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +010010707
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010708 Can also be used as a |method|: >
10709 mylist->string()
10710
10711< Also see |strtrans()|.
10712
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010713 Return type: |String|
10714
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010715
10716strlen({string}) *strlen()*
10717 The result is a Number, which is the length of the String
10718 {string} in bytes.
10719 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010720 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010721 If you want to count the number of multibyte characters use
10722 |strchars()|.
10723 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
10724
10725 Can also be used as a |method|: >
10726 GetString()->strlen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010727<
10728 Return type: |Number|
10729
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010730
10731strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
10732 The result is a String, which is part of {src}, starting from
10733 byte {start}, with the byte length {len}.
10734 When {chars} is present and TRUE then {len} is the number of
10735 characters positions (composing characters are not counted
10736 separately, thus "1" means one base character and any
10737 following composing characters).
10738 To count {start} as characters instead of bytes use
10739 |strcharpart()|.
10740
10741 When bytes are selected which do not exist, this doesn't
10742 result in an error, the bytes are simply omitted.
10743 If {len} is missing, the copy continues from {start} till the
10744 end of the {src}. >
10745 strpart("abcdefg", 3, 2) == "de"
10746 strpart("abcdefg", -2, 4) == "ab"
10747 strpart("abcdefg", 5, 4) == "fg"
10748 strpart("abcdefg", 3) == "defg"
10749
10750< Note: To get the first character, {start} must be 0. For
10751 example, to get the character under the cursor: >
10752 strpart(getline("."), col(".") - 1, 1, v:true)
10753<
Bram Moolenaard592deb2022-06-17 15:42:40 +010010754 Returns an empty string on error.
10755
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010756 Can also be used as a |method|: >
10757 GetText()->strpart(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010758<
10759 Return type: |String|
10760
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010761
10762strptime({format}, {timestring}) *strptime()*
10763 The result is a Number, which is a unix timestamp representing
10764 the date and time in {timestring}, which is expected to match
10765 the format specified in {format}.
10766
10767 The accepted {format} depends on your system, thus this is not
10768 portable! See the manual page of the C function strptime()
10769 for the format. Especially avoid "%c". The value of $TZ also
10770 matters.
10771
10772 If the {timestring} cannot be parsed with {format} zero is
10773 returned. If you do not know the format of {timestring} you
10774 can try different {format} values until you get a non-zero
10775 result.
10776
10777 See also |strftime()|.
10778 Examples: >
10779 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
10780< 862156163 >
10781 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
10782< Sun Apr 27 11:53:55 1997 >
10783 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
10784< Sun Apr 27 12:53:55 1997
10785
10786 Can also be used as a |method|: >
10787 GetFormat()->strptime(timestring)
10788<
10789 Not available on all systems. To check use: >
10790 :if exists("*strptime")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010791<
10792 Return type: |Number|
10793
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010794
10795strridx({haystack}, {needle} [, {start}]) *strridx()*
10796 The result is a Number, which gives the byte index in
10797 {haystack} of the last occurrence of the String {needle}.
10798 When {start} is specified, matches beyond this index are
10799 ignored. This can be used to find a match before a previous
10800 match: >
10801 :let lastcomma = strridx(line, ",")
10802 :let comma2 = strridx(line, ",", lastcomma - 1)
10803< The search is done case-sensitive.
10804 For pattern searches use |match()|.
10805 -1 is returned if the {needle} does not occur in {haystack}.
10806 If the {needle} is empty the length of {haystack} is returned.
10807 See also |stridx()|. Examples: >
10808 :echo strridx("an angry armadillo", "an") 3
10809< *strrchr()*
10810 When used with a single character it works similar to the C
10811 function strrchr().
10812
10813 Can also be used as a |method|: >
10814 GetHaystack()->strridx(needle)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010815<
10816 Return type: |Number|
10817
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010818
10819strtrans({string}) *strtrans()*
10820 The result is a String, which is {string} with all unprintable
10821 characters translated into printable characters |'isprint'|.
10822 Like they are shown in a window. Example: >
10823 echo strtrans(@a)
10824< This displays a newline in register a as "^@" instead of
10825 starting a new line.
10826
Bram Moolenaard592deb2022-06-17 15:42:40 +010010827 Returns an empty string on error.
10828
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010829 Can also be used as a |method|: >
10830 GetString()->strtrans()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010831<
10832 Return type: |String|
10833
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010834
Christian Brabandt67672ef2023-04-24 21:09:54 +010010835strutf16len({string} [, {countcc}]) *strutf16len()*
10836 The result is a Number, which is the number of UTF-16 code
10837 units in String {string} (after converting it to UTF-16).
10838
10839 When {countcc} is TRUE, composing characters are counted
10840 separately.
10841 When {countcc} is omitted or FALSE, composing characters are
10842 ignored.
10843
10844 Returns zero on error.
10845
10846 Also see |strlen()| and |strcharlen()|.
10847 Examples: >
10848 echo strutf16len('a') returns 1
10849 echo strutf16len('©') returns 1
10850 echo strutf16len('😊') returns 2
10851 echo strutf16len('ą́') returns 1
10852 echo strutf16len('ą́', v:true) returns 3
a5ob7r790f9a82023-09-25 06:05:47 +090010853<
Christian Brabandt67672ef2023-04-24 21:09:54 +010010854 Can also be used as a |method|: >
10855 GetText()->strutf16len()
10856<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010857 Return type: |Number|
10858
10859
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010860strwidth({string}) *strwidth()*
10861 The result is a Number, which is the number of display cells
10862 String {string} occupies. A Tab character is counted as one
10863 cell, alternatively use |strdisplaywidth()|.
10864 When {string} contains characters with East Asian Width Class
10865 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010866 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010867 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
10868
10869 Can also be used as a |method|: >
10870 GetString()->strwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010871<
10872 Return type: |Number|
10873
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010874
10875submatch({nr} [, {list}]) *submatch()* *E935*
10876 Only for an expression in a |:substitute| command or
10877 substitute() function.
10878 Returns the {nr}'th submatch of the matched text. When {nr}
10879 is 0 the whole matched text is returned.
10880 Note that a NL in the string can stand for a line break of a
10881 multi-line match or a NUL character in the text.
10882 Also see |sub-replace-expression|.
10883
10884 If {list} is present and non-zero then submatch() returns
10885 a list of strings, similar to |getline()| with two arguments.
10886 NL characters in the text represent NUL characters in the
10887 text.
10888 Only returns more than one item for |:substitute|, inside
10889 |substitute()| this list will always contain one or zero
10890 items, since there are no real line breaks.
10891
10892 When substitute() is used recursively only the submatches in
10893 the current (deepest) call can be obtained.
10894
Bram Moolenaard592deb2022-06-17 15:42:40 +010010895 Returns an empty string or list on error.
10896
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010897 Examples: >
10898 :s/\d\+/\=submatch(0) + 1/
10899 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
10900< This finds the first number in the line and adds one to it.
10901 A line break is included as a newline character.
10902
10903 Can also be used as a |method|: >
10904 GetNr()->submatch()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010905<
10906 Return type: |String| or list<string> depending on {list}
10907
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010908
10909substitute({string}, {pat}, {sub}, {flags}) *substitute()*
10910 The result is a String, which is a copy of {string}, in which
10911 the first match of {pat} is replaced with {sub}.
10912 When {flags} is "g", all matches of {pat} in {string} are
10913 replaced. Otherwise {flags} should be "".
10914
10915 This works like the ":substitute" command (without any flags).
10916 But the matching with {pat} is always done like the 'magic'
10917 option is set and 'cpoptions' is empty (to make scripts
10918 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
10919 if you want to ignore or match case and ignore 'ignorecase'.
10920 'smartcase' is not used. See |string-match| for how {pat} is
10921 used.
10922
10923 A "~" in {sub} is not replaced with the previous {sub}.
10924 Note that some codes in {sub} have a special meaning
10925 |sub-replace-special|. For example, to replace something with
10926 "\n" (two characters), use "\\\\n" or '\\n'.
10927
10928 When {pat} does not match in {string}, {string} is returned
10929 unmodified.
10930
10931 Example: >
10932 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
10933< This removes the last component of the 'path' option. >
10934 :echo substitute("testing", ".*", "\\U\\0", "")
10935< results in "TESTING".
10936
10937 When {sub} starts with "\=", the remainder is interpreted as
10938 an expression. See |sub-replace-expression|. Example: >
10939 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010940 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010941
10942< When {sub} is a Funcref that function is called, with one
10943 optional argument. Example: >
10944 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
10945< The optional argument is a list which contains the whole
10946 matched string and up to nine submatches, like what
10947 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010948 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010949
Bram Moolenaard592deb2022-06-17 15:42:40 +010010950< Returns an empty string on error.
10951
10952 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010953 GetString()->substitute(pat, sub, flags)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010954<
10955 Return type: |String|
10956
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010957
Bram Moolenaarc216a7a2022-12-05 13:50:55 +000010958swapfilelist() *swapfilelist()*
10959 Returns a list of swap file names, like what "vim -r" shows.
10960 See the |-r| command argument. The 'directory' option is used
10961 for the directories to inspect. If you only want to get a
10962 list of swap files in the current directory then temporarily
10963 set 'directory' to a dot: >
10964 let save_dir = &directory
10965 let &directory = '.'
10966 let swapfiles = swapfilelist()
10967 let &directory = save_dir
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010968<
10969 Return type: list<string>
10970
Bram Moolenaarc216a7a2022-12-05 13:50:55 +000010971
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010972swapinfo({fname}) *swapinfo()*
10973 The result is a dictionary, which holds information about the
10974 swapfile {fname}. The available fields are:
10975 version Vim version
10976 user user name
10977 host host name
10978 fname original file name
10979 pid PID of the Vim process that created the swap
10980 file
10981 mtime last modification time in seconds
10982 inode Optional: INODE number of the file
10983 dirty 1 if file was modified, 0 if not
10984 Note that "user" and "host" are truncated to at most 39 bytes.
10985 In case of failure an "error" item is added with the reason:
10986 Cannot open file: file not found or in accessible
10987 Cannot read file: cannot read first block
10988 Not a swap file: does not contain correct block ID
10989 Magic number mismatch: Info in first block is invalid
10990
10991 Can also be used as a |method|: >
10992 GetFilename()->swapinfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010993<
10994 Return type: dict<any> or dict<string>
10995
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010996
10997swapname({buf}) *swapname()*
10998 The result is the swap file path of the buffer {expr}.
10999 For the use of {buf}, see |bufname()| above.
11000 If buffer {buf} is the current buffer, the result is equal to
11001 |:swapname| (unless there is no swap file).
11002 If buffer {buf} has no swap file, returns an empty string.
11003
11004 Can also be used as a |method|: >
11005 GetBufname()->swapname()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011006<
11007 Return type: |String|
11008
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011009
11010synID({lnum}, {col}, {trans}) *synID()*
11011 The result is a Number, which is the syntax ID at the position
11012 {lnum} and {col} in the current window.
11013 The syntax ID can be used with |synIDattr()| and
11014 |synIDtrans()| to obtain syntax information about text.
11015
11016 {col} is 1 for the leftmost column, {lnum} is 1 for the first
11017 line. 'synmaxcol' applies, in a longer line zero is returned.
11018 Note that when the position is after the last character,
11019 that's where the cursor can be in Insert mode, synID() returns
11020 zero. {lnum} is used like with |getline()|.
11021
11022 When {trans} is |TRUE|, transparent items are reduced to the
11023 item that they reveal. This is useful when wanting to know
11024 the effective color. When {trans} is |FALSE|, the transparent
11025 item is returned. This is useful when wanting to know which
11026 syntax item is effective (e.g. inside parens).
11027 Warning: This function can be very slow. Best speed is
11028 obtained by going through the file in forward direction.
11029
Bram Moolenaard592deb2022-06-17 15:42:40 +010011030 Returns zero on error.
11031
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011032 Example (echoes the name of the syntax item under the cursor): >
11033 :echo synIDattr(synID(line("."), col("."), 1), "name")
11034<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011035 Return type: |Number|
11036
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011037
11038synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
11039 The result is a String, which is the {what} attribute of
11040 syntax ID {synID}. This can be used to obtain information
11041 about a syntax item.
11042 {mode} can be "gui", "cterm" or "term", to get the attributes
11043 for that mode. When {mode} is omitted, or an invalid value is
11044 used, the attributes for the currently active highlighting are
11045 used (GUI, cterm or term).
11046 Use synIDtrans() to follow linked highlight groups.
11047 {what} result
11048 "name" the name of the syntax item
11049 "fg" foreground color (GUI: color name used to set
11050 the color, cterm: color number as a string,
11051 term: empty string)
11052 "bg" background color (as with "fg")
11053 "font" font name (only available in the GUI)
11054 |highlight-font|
11055 "sp" special color for the GUI (as with "fg")
11056 |highlight-guisp|
11057 "ul" underline color for cterm: number as a string
11058 "fg#" like "fg", but for the GUI and the GUI is
11059 running the name in "#RRGGBB" form
11060 "bg#" like "fg#" for "bg"
11061 "sp#" like "fg#" for "sp"
11062 "bold" "1" if bold
11063 "italic" "1" if italic
11064 "reverse" "1" if reverse
11065 "inverse" "1" if inverse (= reverse)
11066 "standout" "1" if standout
11067 "underline" "1" if underlined
11068 "undercurl" "1" if undercurled
11069 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +010011070 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011071
Bram Moolenaard592deb2022-06-17 15:42:40 +010011072 Returns an empty string on error.
11073
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011074 Example (echoes the color of the syntax item under the
11075 cursor): >
11076 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
11077<
11078 Can also be used as a |method|: >
11079 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011080<
11081 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011082
11083
11084synIDtrans({synID}) *synIDtrans()*
11085 The result is a Number, which is the translated syntax ID of
11086 {synID}. This is the syntax group ID of what is being used to
11087 highlight the character. Highlight links given with
11088 ":highlight link" are followed.
11089
Bram Moolenaard592deb2022-06-17 15:42:40 +010011090 Returns zero on error.
11091
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011092 Can also be used as a |method|: >
11093 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011094<
11095 Return type: |Number|
11096
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011097
11098synconcealed({lnum}, {col}) *synconcealed()*
11099 The result is a |List| with currently three items:
11100 1. The first item in the list is 0 if the character at the
11101 position {lnum} and {col} is not part of a concealable
11102 region, 1 if it is. {lnum} is used like with |getline()|.
11103 2. The second item in the list is a string. If the first item
11104 is 1, the second item contains the text which will be
11105 displayed in place of the concealed text, depending on the
11106 current setting of 'conceallevel' and 'listchars'.
11107 3. The third and final item in the list is a number
11108 representing the specific syntax region matched in the
11109 line. When the character is not concealed the value is
11110 zero. This allows detection of the beginning of a new
11111 concealable region if there are two consecutive regions
11112 with the same replacement character. For an example, if
11113 the text is "123456" and both "23" and "45" are concealed
11114 and replaced by the character "X", then:
11115 call returns ~
11116 synconcealed(lnum, 1) [0, '', 0]
11117 synconcealed(lnum, 2) [1, 'X', 1]
11118 synconcealed(lnum, 3) [1, 'X', 1]
11119 synconcealed(lnum, 4) [1, 'X', 2]
11120 synconcealed(lnum, 5) [1, 'X', 2]
11121 synconcealed(lnum, 6) [0, '', 0]
11122
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020011123 Note: Doesn't consider |matchadd()| highlighting items,
11124 since syntax and matching highlighting are two different
11125 mechanisms |syntax-vs-match|.
h-east52e7cc22024-07-28 17:03:29 +020011126
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011127 Return type: list<any>
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020011128
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011129
11130synstack({lnum}, {col}) *synstack()*
11131 Return a |List|, which is the stack of syntax items at the
11132 position {lnum} and {col} in the current window. {lnum} is
11133 used like with |getline()|. Each item in the List is an ID
11134 like what |synID()| returns.
11135 The first item in the List is the outer region, following are
11136 items contained in that one. The last one is what |synID()|
11137 returns, unless not the whole item is highlighted or it is a
11138 transparent item.
11139 This function is useful for debugging a syntax file.
11140 Example that shows the syntax stack under the cursor: >
11141 for id in synstack(line("."), col("."))
11142 echo synIDattr(id, "name")
11143 endfor
11144< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +010011145 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011146 character in a line and the first column in an empty line are
11147 valid positions.
11148
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011149 Return type: list<number> or list<any>
11150
11151
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011152system({expr} [, {input}]) *system()* *E677*
11153 Get the output of the shell command {expr} as a |String|. See
11154 |systemlist()| to get the output as a |List|.
11155
11156 When {input} is given and is a |String| this string is written
11157 to a file and passed as stdin to the command. The string is
11158 written as-is, you need to take care of using the correct line
11159 separators yourself.
11160 If {input} is given and is a |List| it is written to the file
11161 in a way |writefile()| does with {binary} set to "b" (i.e.
11162 with a newline between each list item with newlines inside
11163 list items converted to NULs).
11164 When {input} is given and is a number that is a valid id for
11165 an existing buffer then the content of the buffer is written
11166 to the file line by line, each line terminated by a NL and
11167 NULs characters where the text has a NL.
11168
11169 Pipes are not used, the 'shelltemp' option is not used.
11170
11171 When prepended by |:silent| the terminal will not be set to
11172 cooked mode. This is meant to be used for commands that do
11173 not need the user to type. It avoids stray characters showing
11174 up on the screen which require |CTRL-L| to remove. >
11175 :silent let f = system('ls *.vim')
11176<
11177 Note: Use |shellescape()| or |::S| with |expand()| or
11178 |fnamemodify()| to escape special characters in a command
11179 argument. Newlines in {expr} may cause the command to fail.
11180 The characters in 'shellquote' and 'shellxquote' may also
11181 cause trouble.
11182 This is not to be used for interactive commands.
11183
11184 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011185 :let files = system('ls ' .. shellescape(expand('%:h')))
11186 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011187
11188< To make the result more system-independent, the shell output
11189 is filtered to replace <CR> with <NL> for Macintosh, and
11190 <CR><NL> with <NL> for DOS-like systems.
11191 To avoid the string being truncated at a NUL, all NUL
11192 characters are replaced with SOH (0x01).
11193
11194 The command executed is constructed using several options:
11195 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
11196 ({tmp} is an automatically generated file name).
11197 For Unix, braces are put around {expr} to allow for
11198 concatenated commands.
11199
11200 The command will be executed in "cooked" mode, so that a
11201 CTRL-C will interrupt the command (on Unix at least).
11202
11203 The resulting error code can be found in |v:shell_error|.
11204 This function will fail in |restricted-mode|.
11205
11206 Note that any wrong value in the options mentioned above may
11207 make the function fail. It has also been reported to fail
11208 when using a security agent application.
11209 Unlike ":!cmd" there is no automatic check for changed files.
11210 Use |:checktime| to force a check.
11211
11212 Can also be used as a |method|: >
11213 :echo GetCmd()->system()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011214<
11215 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011216
11217
11218systemlist({expr} [, {input}]) *systemlist()*
11219 Same as |system()|, but returns a |List| with lines (parts of
11220 output separated by NL) with NULs transformed into NLs. Output
11221 is the same as |readfile()| will output with {binary} argument
11222 set to "b", except that there is no extra empty item when the
11223 result ends in a NL.
11224 Note that on MS-Windows you may get trailing CR characters.
11225
11226 To see the difference between "echo hello" and "echo -n hello"
11227 use |system()| and |split()|: >
11228 echo system('echo hello')->split('\n', 1)
11229<
11230 Returns an empty string on error.
11231
11232 Can also be used as a |method|: >
11233 :echo GetCmd()->systemlist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011234<
11235 Return type: list<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011236
11237
11238tabpagebuflist([{arg}]) *tabpagebuflist()*
11239 The result is a |List|, where each item is the number of the
11240 buffer associated with each window in the current tab page.
11241 {arg} specifies the number of the tab page to be used. When
11242 omitted the current tab page is used.
11243 When {arg} is invalid the number zero is returned.
11244 To get a list of all buffers in all tabs use this: >
11245 let buflist = []
11246 for i in range(tabpagenr('$'))
11247 call extend(buflist, tabpagebuflist(i + 1))
11248 endfor
11249< Note that a buffer may appear in more than one window.
11250
11251 Can also be used as a |method|: >
11252 GetTabpage()->tabpagebuflist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011253<
11254 Return type: list<number>
11255
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011256
11257tabpagenr([{arg}]) *tabpagenr()*
11258 The result is a Number, which is the number of the current
11259 tab page. The first tab page has number 1.
11260
11261 The optional argument {arg} supports the following values:
11262 $ the number of the last tab page (the tab page
11263 count).
11264 # the number of the last accessed tab page
11265 (where |g<Tab>| goes to). if there is no
11266 previous tab page 0 is returned.
11267 The number can be used with the |:tab| command.
11268
Bram Moolenaard592deb2022-06-17 15:42:40 +010011269 Returns zero on error.
11270
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011271 Return type: |Number|
11272
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011273
11274tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
11275 Like |winnr()| but for tab page {tabarg}.
11276 {tabarg} specifies the number of tab page to be used.
11277 {arg} is used like with |winnr()|:
11278 - When omitted the current window number is returned. This is
11279 the window which will be used when going to this tab page.
11280 - When "$" the number of windows is returned.
11281 - When "#" the previous window nr is returned.
11282 Useful examples: >
11283 tabpagewinnr(1) " current window of tab page 1
11284 tabpagewinnr(4, '$') " number of windows in tab page 4
11285< When {tabarg} is invalid zero is returned.
11286
11287 Can also be used as a |method|: >
11288 GetTabpage()->tabpagewinnr()
11289<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011290 Return type: |Number|
11291
11292
11293tagfiles() *tagfiles()*
11294 Returns a |List| with the file names used to search for tags
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011295 for the current buffer. This is the 'tags' option expanded.
11296
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011297 Return type: list<string> or list<any>
11298
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011299
11300taglist({expr} [, {filename}]) *taglist()*
11301 Returns a |List| of tags matching the regular expression {expr}.
11302
11303 If {filename} is passed it is used to prioritize the results
11304 in the same way that |:tselect| does. See |tag-priority|.
11305 {filename} should be the full path of the file.
11306
11307 Each list item is a dictionary with at least the following
11308 entries:
11309 name Name of the tag.
11310 filename Name of the file where the tag is
11311 defined. It is either relative to the
11312 current directory or a full path.
11313 cmd Ex command used to locate the tag in
11314 the file.
11315 kind Type of the tag. The value for this
11316 entry depends on the language specific
11317 kind values. Only available when
11318 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +000011319 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011320 static A file specific tag. Refer to
11321 |static-tag| for more information.
11322 More entries may be present, depending on the content of the
11323 tags file: access, implementation, inherits and signature.
11324 Refer to the ctags documentation for information about these
11325 fields. For C code the fields "struct", "class" and "enum"
11326 may appear, they give the name of the entity the tag is
11327 contained in.
11328
11329 The ex-command "cmd" can be either an ex search pattern, a
11330 line number or a line number followed by a byte number.
11331
11332 If there are no matching tags, then an empty list is returned.
11333
11334 To get an exact tag match, the anchors '^' and '$' should be
11335 used in {expr}. This also make the function work faster.
11336 Refer to |tag-regexp| for more information about the tag
11337 search regular expression pattern.
11338
11339 Refer to |'tags'| for information about how the tags file is
11340 located by Vim. Refer to |tags-file-format| for the format of
11341 the tags file generated by the different ctags tools.
11342
11343 Can also be used as a |method|: >
11344 GetTagpattern()->taglist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011345<
11346 Return type: list<dict<any>> or list<any>
11347
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011348
11349tan({expr}) *tan()*
11350 Return the tangent of {expr}, measured in radians, as a |Float|
11351 in the range [-inf, inf].
11352 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011353 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011354 Examples: >
11355 :echo tan(10)
11356< 0.648361 >
11357 :echo tan(-4.01)
11358< -1.181502
11359
11360 Can also be used as a |method|: >
11361 Compute()->tan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011362<
11363 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011364
11365
11366tanh({expr}) *tanh()*
11367 Return the hyperbolic tangent of {expr} as a |Float| in the
11368 range [-1, 1].
11369 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011370 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011371 Examples: >
11372 :echo tanh(0.5)
11373< 0.462117 >
11374 :echo tanh(-1)
11375< -0.761594
11376
11377 Can also be used as a |method|: >
11378 Compute()->tanh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011379<
11380 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011381
11382
11383tempname() *tempname()* *temp-file-name*
11384 The result is a String, which is the name of a file that
11385 doesn't exist. It can be used for a temporary file. The name
11386 is different for at least 26 consecutive calls. Example: >
11387 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011388 :exe "redir > " .. tmpfile
Christian Brabandt5cf53012024-05-18 10:13:11 +020011389< For Unix, the file will be in a private directory |tempfile|
11390 that is recursively deleted when Vim exits, on other systems
11391 temporary files are not cleaned up automatically on exit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011392 For MS-Windows forward slashes are used when the 'shellslash'
11393 option is set, or when 'shellcmdflag' starts with '-' and
11394 'shell' does not contain powershell or pwsh.
11395
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011396 Return type: |String|
11397
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011398
11399term_ functions are documented here: |terminal-function-details|
11400
11401
11402terminalprops() *terminalprops()*
11403 Returns a |Dictionary| with properties of the terminal that Vim
11404 detected from the response to |t_RV| request. See
11405 |v:termresponse| for the response itself. If |v:termresponse|
11406 is empty most values here will be 'u' for unknown.
11407 cursor_style whether sending |t_RS| works **
11408 cursor_blink_mode whether sending |t_RC| works **
11409 underline_rgb whether |t_8u| works **
11410 mouse mouse type supported
Bram Moolenaar4bc85f22022-10-21 14:17:24 +010011411 kitty whether Kitty terminal was detected
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011412
11413 ** value 'u' for unknown, 'y' for yes, 'n' for no
11414
11415 If the |+termresponse| feature is missing then the result is
11416 an empty dictionary.
11417
11418 If "cursor_style" is 'y' then |t_RS| will be sent to request the
11419 current cursor style.
11420 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
11421 request the cursor blink status.
11422 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
11423 is not empty, Vim will detect the working of sending |t_RS|
11424 and |t_RC| on startup.
11425
11426 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
11427 This avoids sending it to xterm, which would clear the colors.
11428
11429 For "mouse" the value 'u' is unknown
11430
11431 Also see:
11432 - 'ambiwidth' - detected by using |t_u7|.
11433 - |v:termstyleresp| and |v:termblinkresp| for the response to
11434 |t_RS| and |t_RC|.
11435
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011436 Return type: dict<string>
11437
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011438
11439test_ functions are documented here: |test-functions-details|
11440
11441
11442 *timer_info()*
11443timer_info([{id}])
11444 Return a list with information about timers.
11445 When {id} is given only information about this timer is
11446 returned. When timer {id} does not exist an empty list is
11447 returned.
11448 When {id} is omitted information about all timers is returned.
11449
11450 For each timer the information is stored in a |Dictionary| with
11451 these items:
11452 "id" the timer ID
11453 "time" time the timer was started with
11454 "remaining" time until the timer fires
11455 "repeat" number of times the timer will still fire;
11456 -1 means forever
11457 "callback" the callback
11458 "paused" 1 if the timer is paused, 0 otherwise
11459
11460 Can also be used as a |method|: >
11461 GetTimer()->timer_info()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011462<
11463 Return type: list<dict<any>> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011464
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011465 {only available when compiled with the |+timers| feature}
11466
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011467
11468timer_pause({timer}, {paused}) *timer_pause()*
11469 Pause or unpause a timer. A paused timer does not invoke its
11470 callback when its time expires. Unpausing a timer may cause
11471 the callback to be invoked almost immediately if enough time
11472 has passed.
11473
11474 Pausing a timer is useful to avoid the callback to be called
11475 for a short time.
11476
11477 If {paused} evaluates to a non-zero Number or a non-empty
11478 String, then the timer is paused, otherwise it is unpaused.
11479 See |non-zero-arg|.
11480
11481 Can also be used as a |method|: >
11482 GetTimer()->timer_pause(1)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011483<
11484 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011485
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011486 {only available when compiled with the |+timers| feature}
11487
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011488
11489 *timer_start()* *timer* *timers*
11490timer_start({time}, {callback} [, {options}])
11491 Create a timer and return the timer ID.
11492
11493 {time} is the waiting time in milliseconds. This is the
11494 minimum time before invoking the callback. When the system is
11495 busy or Vim is not waiting for input the time will be longer.
Bram Moolenaardd60c362023-02-27 15:49:53 +000011496 Zero can be used to execute the callback when Vim is back in
11497 the main loop.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011498
11499 {callback} is the function to call. It can be the name of a
11500 function or a |Funcref|. It is called with one argument, which
11501 is the timer ID. The callback is only invoked when Vim is
11502 waiting for input.
11503 If you want to show a message look at |popup_notification()|
11504 to avoid interfering with what the user is doing.
11505
11506 {options} is a dictionary. Supported entries:
11507 "repeat" Number of times to repeat calling the
11508 callback. -1 means forever. When not present
11509 the callback will be called once.
11510 If the timer causes an error three times in a
11511 row the repeat is cancelled. This avoids that
11512 Vim becomes unusable because of all the error
11513 messages.
11514
Bram Moolenaard592deb2022-06-17 15:42:40 +010011515 Returns -1 on error.
11516
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011517 Example: >
11518 func MyHandler(timer)
11519 echo 'Handler called'
11520 endfunc
11521 let timer = timer_start(500, 'MyHandler',
11522 \ {'repeat': 3})
11523< This will invoke MyHandler() three times at 500 msec
11524 intervals.
11525
11526 Can also be used as a |method|: >
11527 GetMsec()->timer_start(callback)
11528
11529< Not available in the |sandbox|.
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011530
11531 Return type: |Number|
11532
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011533 {only available when compiled with the |+timers| feature}
11534
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011535
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011536timer_stop({timer}) *timer_stop()*
11537 Stop a timer. The timer callback will no longer be invoked.
11538 {timer} is an ID returned by timer_start(), thus it must be a
11539 Number. If {timer} does not exist there is no error.
11540
11541 Can also be used as a |method|: >
11542 GetTimer()->timer_stop()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011543<
11544 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011545
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011546 {only available when compiled with the |+timers| feature}
11547
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011548
11549timer_stopall() *timer_stopall()*
11550 Stop all timers. The timer callbacks will no longer be
11551 invoked. Useful if a timer is misbehaving. If there are no
11552 timers there is no error.
11553
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011554 Return type: |Number|
11555
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011556 {only available when compiled with the |+timers| feature}
11557
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011558
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011559tolower({expr}) *tolower()*
11560 The result is a copy of the String given, with all uppercase
11561 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010011562 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011563
11564 Can also be used as a |method|: >
11565 GetText()->tolower()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011566<
11567 Return type: |String|
11568
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011569
11570toupper({expr}) *toupper()*
11571 The result is a copy of the String given, with all lowercase
11572 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010011573 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011574
11575 Can also be used as a |method|: >
11576 GetText()->toupper()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011577<
11578 Return type: |String|
11579
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011580
11581tr({src}, {fromstr}, {tostr}) *tr()*
11582 The result is a copy of the {src} string with all characters
11583 which appear in {fromstr} replaced by the character in that
11584 position in the {tostr} string. Thus the first character in
11585 {fromstr} is translated into the first character in {tostr}
11586 and so on. Exactly like the unix "tr" command.
11587 This code also deals with multibyte characters properly.
11588
Bram Moolenaard592deb2022-06-17 15:42:40 +010011589 Returns an empty string on error.
11590
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011591 Examples: >
11592 echo tr("hello there", "ht", "HT")
11593< returns "Hello THere" >
11594 echo tr("<blob>", "<>", "{}")
11595< returns "{blob}"
11596
11597 Can also be used as a |method|: >
11598 GetText()->tr(from, to)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011599<
11600 Return type: |String|
11601
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011602
11603trim({text} [, {mask} [, {dir}]]) *trim()*
11604 Return {text} as a String where any character in {mask} is
11605 removed from the beginning and/or end of {text}.
11606
Illia Bobyr80799172023-10-17 18:00:50 +020011607 If {mask} is not given, or is an empty string, {mask} is all
11608 characters up to 0x20, which includes Tab, space, NL and CR,
11609 plus the non-breaking space character 0xa0.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011610
11611 The optional {dir} argument specifies where to remove the
11612 characters:
11613 0 remove from the beginning and end of {text}
11614 1 remove only at the beginning of {text}
11615 2 remove only at the end of {text}
11616 When omitted both ends are trimmed.
11617
11618 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011619 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011620
11621 Examples: >
11622 echo trim(" some text ")
11623< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011624 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011625< returns "RESERVE_TAIL" >
11626 echo trim("rm<Xrm<>X>rrm", "rm<>")
11627< returns "Xrm<>X" (characters in the middle are not removed) >
11628 echo trim(" vim ", " ", 2)
11629< returns " vim"
11630
11631 Can also be used as a |method|: >
11632 GetText()->trim()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011633<
11634 Return type: |String|
11635
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011636
11637trunc({expr}) *trunc()*
11638 Return the largest integral value with magnitude less than or
11639 equal to {expr} as a |Float| (truncate towards zero).
11640 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011641 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011642 Examples: >
11643 echo trunc(1.456)
11644< 1.0 >
11645 echo trunc(-5.456)
11646< -5.0 >
11647 echo trunc(4.0)
11648< 4.0
11649
11650 Can also be used as a |method|: >
11651 Compute()->trunc()
11652<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011653 Return type: |Float|
11654
11655
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011656 *type()*
11657type({expr}) The result is a Number representing the type of {expr}.
11658 Instead of using the number directly, it is better to use the
11659 v:t_ variable that has the value:
11660 Number: 0 |v:t_number|
11661 String: 1 |v:t_string|
11662 Funcref: 2 |v:t_func|
11663 List: 3 |v:t_list|
11664 Dictionary: 4 |v:t_dict|
11665 Float: 5 |v:t_float|
11666 Boolean: 6 |v:t_bool| (v:false and v:true)
11667 None: 7 |v:t_none| (v:null and v:none)
11668 Job: 8 |v:t_job|
11669 Channel: 9 |v:t_channel|
11670 Blob: 10 |v:t_blob|
h_east596a9f22023-11-21 21:24:23 +090011671 Class: 12 |v:t_class|
11672 Object: 13 |v:t_object|
Yegappan Lakshmanan2a71b542023-12-14 20:03:03 +010011673 Typealias: 14 |v:t_typealias|
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010011674 Enum: 15 |v:t_enum|
11675 EnumValue: 16 |v:t_enumvalue|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011676 For backward compatibility, this method can be used: >
11677 :if type(myvar) == type(0)
11678 :if type(myvar) == type("")
11679 :if type(myvar) == type(function("tr"))
11680 :if type(myvar) == type([])
11681 :if type(myvar) == type({})
11682 :if type(myvar) == type(0.0)
11683 :if type(myvar) == type(v:false)
11684 :if type(myvar) == type(v:none)
11685< To check if the v:t_ variables exist use this: >
11686 :if exists('v:t_number')
11687
11688< Can also be used as a |method|: >
11689 mylist->type()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011690<
11691 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011692
11693
11694typename({expr}) *typename()*
11695 Return a string representation of the type of {expr}.
11696 Example: >
11697 echo typename([1, 2, 3])
Kota Kato66bb9ae2023-01-17 18:31:56 +000011698< list<number> ~
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011699
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011700 Return type: |String|
11701
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011702
11703undofile({name}) *undofile()*
11704 Return the name of the undo file that would be used for a file
11705 with name {name} when writing. This uses the 'undodir'
11706 option, finding directories that exist. It does not check if
11707 the undo file exists.
11708 {name} is always expanded to the full path, since that is what
11709 is used internally.
11710 If {name} is empty undofile() returns an empty string, since a
11711 buffer without a file name will not write an undo file.
11712 Useful in combination with |:wundo| and |:rundo|.
11713 When compiled without the |+persistent_undo| option this always
11714 returns an empty string.
11715
11716 Can also be used as a |method|: >
11717 GetFilename()->undofile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011718<
11719 Return type: |String|
11720
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011721
Devin J. Pohly5fee1112023-04-23 20:26:59 -050011722undotree([{buf}]) *undotree()*
11723 Return the current state of the undo tree for the current
11724 buffer, or for a specific buffer if {buf} is given. The
11725 result is a dictionary with the following items:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011726 "seq_last" The highest undo sequence number used.
11727 "seq_cur" The sequence number of the current position in
11728 the undo tree. This differs from "seq_last"
11729 when some changes were undone.
11730 "time_cur" Time last used for |:earlier| and related
11731 commands. Use |strftime()| to convert to
11732 something readable.
11733 "save_last" Number of the last file write. Zero when no
11734 write yet.
11735 "save_cur" Number of the current position in the undo
11736 tree.
11737 "synced" Non-zero when the last undo block was synced.
11738 This happens when waiting from input from the
11739 user. See |undo-blocks|.
11740 "entries" A list of dictionaries with information about
11741 undo blocks.
11742
11743 The first item in the "entries" list is the oldest undo item.
11744 Each List item is a |Dictionary| with these items:
11745 "seq" Undo sequence number. Same as what appears in
11746 |:undolist|.
11747 "time" Timestamp when the change happened. Use
11748 |strftime()| to convert to something readable.
11749 "newhead" Only appears in the item that is the last one
11750 that was added. This marks the last change
11751 and where further changes will be added.
11752 "curhead" Only appears in the item that is the last one
11753 that was undone. This marks the current
11754 position in the undo tree, the block that will
11755 be used by a redo command. When nothing was
11756 undone after the last change this item will
11757 not appear anywhere.
11758 "save" Only appears on the last block before a file
11759 write. The number is the write count. The
11760 first write has number 1, the last one the
11761 "save_last" mentioned above.
11762 "alt" Alternate entry. This is again a List of undo
11763 blocks. Each item may again have an "alt"
11764 item.
11765
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011766 Return type: dict<any>
11767
11768
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011769uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
11770 Remove second and succeeding copies of repeated adjacent
11771 {list} items in-place. Returns {list}. If you want a list
11772 to remain unmodified make a copy first: >
11773 :let newlist = uniq(copy(mylist))
11774< The default compare function uses the string representation of
11775 each item. For the use of {func} and {dict} see |sort()|.
11776
Bram Moolenaard592deb2022-06-17 15:42:40 +010011777 Returns zero if {list} is not a |List|.
11778
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011779 Can also be used as a |method|: >
11780 mylist->uniq()
Christian Brabandt67672ef2023-04-24 21:09:54 +010011781<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011782 Return type: list<{type}>
11783
11784
Christian Brabandt67672ef2023-04-24 21:09:54 +010011785 *utf16idx()*
11786utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010011787 Same as |charidx()| but returns the UTF-16 code unit index of
11788 the byte at {idx} in {string} (after converting it to UTF-16).
Christian Brabandt67672ef2023-04-24 21:09:54 +010011789
11790 When {charidx} is present and TRUE, {idx} is used as the
11791 character index in the String {string} instead of as the byte
11792 index.
Yegappan Lakshmanan95707032023-06-14 13:10:15 +010011793 An {idx} in the middle of a UTF-8 sequence is rounded
11794 downwards to the beginning of that sequence.
Christian Brabandt67672ef2023-04-24 21:09:54 +010011795
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010011796 Returns -1 if the arguments are invalid or if there are less
11797 than {idx} bytes in {string}. If there are exactly {idx} bytes
11798 the length of the string in UTF-16 code units is returned.
11799
Christian Brabandt67672ef2023-04-24 21:09:54 +010011800 See |byteidx()| and |byteidxcomp()| for getting the byte index
11801 from the UTF-16 index and |charidx()| for getting the
11802 character index from the UTF-16 index.
11803 Refer to |string-offset-encoding| for more information.
11804 Examples: >
11805 echo utf16idx('a😊😊', 3) returns 2
11806 echo utf16idx('a😊😊', 7) returns 4
11807 echo utf16idx('a😊😊', 1, 0, 1) returns 2
11808 echo utf16idx('a😊😊', 2, 0, 1) returns 4
11809 echo utf16idx('aą́c', 6) returns 2
11810 echo utf16idx('aą́c', 6, 1) returns 4
11811 echo utf16idx('a😊😊', 9) returns -1
11812<
11813 Can also be used as a |method|: >
11814 GetName()->utf16idx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011815<
11816 Return type: |Number|
Christian Brabandt67672ef2023-04-24 21:09:54 +010011817
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011818
11819values({dict}) *values()*
11820 Return a |List| with all the values of {dict}. The |List| is
11821 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011822 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011823
11824 Can also be used as a |method|: >
11825 mydict->values()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011826<
11827 Return type: list<any>
11828
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011829
zeertzjq825cf812023-08-17 22:55:25 +020011830virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011831 The result is a Number, which is the screen column of the file
11832 position given with {expr}. That is, the last screen position
11833 occupied by the character at that position, when the screen
11834 would be of unlimited width. When there is a <Tab> at the
11835 position, the returned Number will be the column at the end of
11836 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
11837 set to 8, it returns 8. |conceal| is ignored.
11838 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010011839
zeertzjq02f3eba2024-06-12 20:45:24 +020011840 For the use of {expr} see |getpos()| and |col()|.
zeertzjqd353d272024-06-13 23:00:25 +080011841 When {expr} is "$", it means the end of the cursor line, so
11842 the result is the number of cells in the cursor line plus one.
LemonBoy0f7a3e12022-05-26 12:10:37 +010011843
11844 When 'virtualedit' is used {expr} can be [lnum, col, off],
11845 where "off" is the offset in screen columns from the start of
11846 the character. E.g., a position within a <Tab> or after the
11847 last character. When "off" is omitted zero is used. When
11848 Virtual editing is active in the current mode, a position
11849 beyond the end of the line can be returned. Also see
11850 |'virtualedit'|
11851
zeertzjq825cf812023-08-17 22:55:25 +020011852 If {list} is present and non-zero then virtcol() returns a
11853 List with the first and last screen position occupied by the
LemonBoy0f7a3e12022-05-26 12:10:37 +010011854 character.
11855
zeertzjq825cf812023-08-17 22:55:25 +020011856 With the optional {winid} argument the values are obtained for
11857 that window instead of the current window.
11858
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011859 Note that only marks in the current file can be used.
zeertzjq02f3eba2024-06-12 20:45:24 +020011860
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011861 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +010011862 " With text "foo^Lbar" and cursor on the "^L":
11863
11864 virtcol(".") " returns 5
11865 virtcol(".", 1) " returns [4, 5]
11866 virtcol("$") " returns 9
11867
11868 " With text " there", with 't at 'h':
11869
11870 virtcol("'t") " returns 6
zeertzjq02f3eba2024-06-12 20:45:24 +020011871<
11872 The first column is 1. 0 or [0, 0] is returned for an error.
11873
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011874 A more advanced example that echoes the maximum length of
11875 all lines: >
11876 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
11877
11878< Can also be used as a |method|: >
11879 GetPos()->virtcol()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011880<
11881 Return type: |Number|
11882
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011883
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010011884virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
11885 The result is a Number, which is the byte index of the
11886 character in window {winid} at buffer line {lnum} and virtual
11887 column {col}.
11888
zeertzjqb583eda2023-10-14 11:32:28 +020011889 If buffer line {lnum} is an empty line, 0 is returned.
11890
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010011891 If {col} is greater than the last virtual column in line
11892 {lnum}, then the byte index of the character at the last
11893 virtual column is returned.
11894
Yegappan Lakshmananb209b862023-08-15 23:01:44 +020011895 For a multi-byte character, the column number of the first
11896 byte in the character is returned.
11897
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010011898 The {winid} argument can be the window number or the
11899 |window-ID|. If this is zero, then the current window is used.
11900
11901 Returns -1 if the window {winid} doesn't exist or the buffer
11902 line {lnum} or virtual column {col} is invalid.
11903
11904 See also |screenpos()|, |virtcol()| and |col()|.
11905
11906 Can also be used as a |method|: >
11907 GetWinid()->virtcol2col(lnum, col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011908<
11909 Return type: |Number|
11910
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011911
11912visualmode([{expr}]) *visualmode()*
11913 The result is a String, which describes the last Visual mode
11914 used in the current buffer. Initially it returns an empty
11915 string, but once Visual mode has been used, it returns "v",
11916 "V", or "<CTRL-V>" (a single CTRL-V character) for
11917 character-wise, line-wise, or block-wise Visual mode
11918 respectively.
11919 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011920 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011921< This enters the same Visual mode as before. It is also useful
11922 in scripts if you wish to act differently depending on the
11923 Visual mode that was used.
11924 If Visual mode is active, use |mode()| to get the Visual mode
11925 (e.g., in a |:vmap|).
11926 If {expr} is supplied and it evaluates to a non-zero Number or
11927 a non-empty String, then the Visual mode will be cleared and
11928 the old value is returned. See |non-zero-arg|.
11929
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011930 Return type: |String|
11931
11932
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011933wildmenumode() *wildmenumode()*
11934 Returns |TRUE| when the wildmenu is active and |FALSE|
11935 otherwise. See 'wildmenu' and 'wildmode'.
11936 This can be used in mappings to handle the 'wildcharm' option
11937 gracefully. (Makes only sense with |mapmode-c| mappings).
11938
11939 For example to make <c-j> work like <down> in wildmode, use: >
11940 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
11941<
11942 (Note, this needs the 'wildcharm' option set appropriately).
11943
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011944 Return type: |Number|
11945
11946
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011947win_execute({id}, {command} [, {silent}]) *win_execute()*
11948 Like `execute()` but in the context of window {id}.
11949 The window will temporarily be made the current window,
11950 without triggering autocommands or changing directory. When
11951 executing {command} autocommands will be triggered, this may
Bram Moolenaarb7398fe2023-05-14 18:50:25 +010011952 have unexpected side effects. Use `:noautocmd` if needed.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011953 Example: >
11954 call win_execute(winid, 'set syntax=python')
11955< Doing the same with `setwinvar()` would not trigger
11956 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011957 *E994*
11958 Not all commands are allowed in popup windows.
11959 When window {id} does not exist then no error is given and
11960 an empty string is returned.
11961
11962 Can also be used as a |method|, the base is passed as the
11963 second argument: >
11964 GetCommand()->win_execute(winid)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011965<
11966 Return type: |String|
11967
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011968
11969win_findbuf({bufnr}) *win_findbuf()*
11970 Returns a |List| with |window-ID|s for windows that contain
11971 buffer {bufnr}. When there is none the list is empty.
11972
11973 Can also be used as a |method|: >
11974 GetBufnr()->win_findbuf()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011975<
11976 Return type: list<number> or list<any>
11977
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011978
11979win_getid([{win} [, {tab}]]) *win_getid()*
11980 Get the |window-ID| for the specified window.
11981 When {win} is missing use the current window.
11982 With {win} this is the window number. The top window has
11983 number 1.
11984 Without {tab} use the current tab, otherwise the tab with
11985 number {tab}. The first tab has number one.
11986 Return zero if the window cannot be found.
11987
11988 Can also be used as a |method|: >
11989 GetWinnr()->win_getid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011990<
11991 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011992
11993
11994win_gettype([{nr}]) *win_gettype()*
11995 Return the type of the window:
11996 "autocmd" autocommand window. Temporary window
11997 used to execute autocommands.
11998 "command" command-line window |cmdwin|
11999 (empty) normal window
12000 "loclist" |location-list-window|
12001 "popup" popup window |popup|
12002 "preview" preview window |preview-window|
12003 "quickfix" |quickfix-window|
12004 "unknown" window {nr} not found
12005
12006 When {nr} is omitted return the type of the current window.
12007 When {nr} is given return the type of this window by number or
12008 |window-ID|.
12009
12010 Also see the 'buftype' option. When running a terminal in a
12011 popup window then 'buftype' is "terminal" and win_gettype()
12012 returns "popup".
12013
12014 Can also be used as a |method|: >
12015 GetWinid()->win_gettype()
12016<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012017 Return type: |String|
12018
12019
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012020win_gotoid({expr}) *win_gotoid()*
12021 Go to window with ID {expr}. This may also change the current
12022 tabpage.
12023 Return TRUE if successful, FALSE if the window cannot be found.
12024
12025 Can also be used as a |method|: >
12026 GetWinid()->win_gotoid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012027<
12028 Return type: |Number|
12029
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012030
12031win_id2tabwin({expr}) *win_id2tabwin()*
12032 Return a list with the tab number and window number of window
12033 with ID {expr}: [tabnr, winnr].
12034 Return [0, 0] if the window cannot be found.
12035
12036 Can also be used as a |method|: >
12037 GetWinid()->win_id2tabwin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012038<
12039 Return type: list<number>
12040
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012041
12042win_id2win({expr}) *win_id2win()*
12043 Return the window number of window with ID {expr}.
12044 Return 0 if the window cannot be found in the current tabpage.
12045
12046 Can also be used as a |method|: >
12047 GetWinid()->win_id2win()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012048<
12049 Return type: |Number|
12050
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012051
Daniel Steinbergee630312022-01-10 13:36:34 +000012052win_move_separator({nr}, {offset}) *win_move_separator()*
12053 Move window {nr}'s vertical separator (i.e., the right border)
12054 by {offset} columns, as if being dragged by the mouse. {nr}
12055 can be a window number or |window-ID|. A positive {offset}
12056 moves right and a negative {offset} moves left. Moving a
12057 window's vertical separator will change the width of the
12058 window and the width of other windows adjacent to the vertical
12059 separator. The magnitude of movement may be smaller than
12060 specified (e.g., as a consequence of maintaining
12061 'winminwidth'). Returns TRUE if the window can be found and
12062 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010012063 This will fail for the rightmost window and a full-width
12064 window, since it has no separator on the right.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000012065 Only works for the current tab page. *E1308*
Daniel Steinbergee630312022-01-10 13:36:34 +000012066
12067 Can also be used as a |method|: >
12068 GetWinnr()->win_move_separator(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012069<
12070 Return type: |Number|
12071
Daniel Steinbergee630312022-01-10 13:36:34 +000012072
12073win_move_statusline({nr}, {offset}) *win_move_statusline()*
12074 Move window {nr}'s status line (i.e., the bottom border) by
12075 {offset} rows, as if being dragged by the mouse. {nr} can be a
12076 window number or |window-ID|. A positive {offset} moves down
12077 and a negative {offset} moves up. Moving a window's status
12078 line will change the height of the window and the height of
12079 other windows adjacent to the status line. The magnitude of
12080 movement may be smaller than specified (e.g., as a consequence
12081 of maintaining 'winminheight'). Returns TRUE if the window can
12082 be found and FALSE otherwise.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000012083 Only works for the current tab page.
Daniel Steinbergee630312022-01-10 13:36:34 +000012084
12085 Can also be used as a |method|: >
12086 GetWinnr()->win_move_statusline(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012087<
12088 Return type: |Number|
12089
Daniel Steinbergee630312022-01-10 13:36:34 +000012090
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012091win_screenpos({nr}) *win_screenpos()*
12092 Return the screen position of window {nr} as a list with two
12093 numbers: [row, col]. The first window always has position
12094 [1, 1], unless there is a tabline, then it is [2, 1].
12095 {nr} can be the window number or the |window-ID|. Use zero
12096 for the current window.
Sean Dewar5866bc32024-03-13 20:17:24 +010012097 Returns [0, 0] if the window cannot be found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012098
12099 Can also be used as a |method|: >
12100 GetWinid()->win_screenpos()
12101<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012102 Return type: list<number>
12103
12104
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012105win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
Sean Dewar96cc4ae2024-02-20 21:52:31 +010012106 Temporarily switch to window {target}, then move window {nr}
12107 to a new split adjacent to {target}.
12108 Unlike commands such as |:split|, no new windows are created
12109 (the |window-ID| of window {nr} is unchanged after the move).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012110
12111 Both {nr} and {target} can be window numbers or |window-ID|s.
12112 Both must be in the current tab page.
12113
12114 Returns zero for success, non-zero for failure.
12115
12116 {options} is a |Dictionary| with the following optional entries:
12117 "vertical" When TRUE, the split is created vertically,
12118 like with |:vsplit|.
12119 "rightbelow" When TRUE, the split is made below or to the
12120 right (if vertical). When FALSE, it is done
12121 above or to the left (if vertical). When not
12122 present, the values of 'splitbelow' and
12123 'splitright' are used.
12124
12125 Can also be used as a |method|: >
12126 GetWinid()->win_splitmove(target)
12127<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012128 Return type: |Number|
12129
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012130
12131 *winbufnr()*
12132winbufnr({nr}) The result is a Number, which is the number of the buffer
12133 associated with window {nr}. {nr} can be the window number or
12134 the |window-ID|.
12135 When {nr} is zero, the number of the buffer in the current
12136 window is returned.
12137 When window {nr} doesn't exist, -1 is returned.
12138 Example: >
12139 :echo "The file in the current window is " . bufname(winbufnr(0))
12140<
12141 Can also be used as a |method|: >
12142 FindWindow()->winbufnr()->bufname()
12143<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012144 Return type: |Number|
12145
12146
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012147 *wincol()*
12148wincol() The result is a Number, which is the virtual column of the
12149 cursor in the window. This is counting screen cells from the
12150 left side of the window. The leftmost column is one.
12151
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012152 Return type: |Number|
12153
12154
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012155 *windowsversion()*
12156windowsversion()
12157 The result is a String. For MS-Windows it indicates the OS
12158 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
12159 Windows XP is "5.1". For non-MS-Windows systems the result is
12160 an empty string.
12161
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012162 Return type: |String|
12163
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012164winheight({nr}) *winheight()*
12165 The result is a Number, which is the height of window {nr}.
12166 {nr} can be the window number or the |window-ID|.
12167 When {nr} is zero, the height of the current window is
12168 returned. When window {nr} doesn't exist, -1 is returned.
12169 An existing window always has a height of zero or more.
12170 This excludes any window toolbar line.
12171 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012172 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012173
12174< Can also be used as a |method|: >
12175 GetWinid()->winheight()
12176<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012177 Return type: |Number|
12178
12179
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012180winlayout([{tabnr}]) *winlayout()*
12181 The result is a nested List containing the layout of windows
12182 in a tabpage.
12183
12184 Without {tabnr} use the current tabpage, otherwise the tabpage
12185 with number {tabnr}. If the tabpage {tabnr} is not found,
12186 returns an empty list.
12187
12188 For a leaf window, it returns:
12189 ['leaf', {winid}]
12190 For horizontally split windows, which form a column, it
12191 returns:
12192 ['col', [{nested list of windows}]]
12193 For vertically split windows, which form a row, it returns:
12194 ['row', [{nested list of windows}]]
12195
12196 Example: >
12197 " Only one window in the tab page
12198 :echo winlayout()
12199 ['leaf', 1000]
12200 " Two horizontally split windows
12201 :echo winlayout()
12202 ['col', [['leaf', 1000], ['leaf', 1001]]]
12203 " The second tab page, with three horizontally split
12204 " windows, with two vertically split windows in the
12205 " middle window
12206 :echo winlayout(2)
12207 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
12208 ['leaf', 1001]]], ['leaf', 1000]]]
12209<
12210 Can also be used as a |method|: >
12211 GetTabnr()->winlayout()
12212<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012213 Return type: list<any>
12214
12215
12216winline() *winline()*
12217 The result is a Number, which is the screen line of the cursor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012218 in the window. This is counting screen lines from the top of
12219 the window. The first line is one.
12220 If the cursor was moved the view on the file will be updated
12221 first, this may cause a scroll.
12222
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012223 Return type: |Number|
12224
12225
12226winnr([{arg}]) *winnr()*
12227 The result is a Number, which is the number of the current
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012228 window. The top window has number 1.
12229 Returns zero for a popup window.
12230
12231 The optional argument {arg} supports the following values:
12232 $ the number of the last window (the window
12233 count).
12234 # the number of the last accessed window (where
12235 |CTRL-W_p| goes to). If there is no previous
12236 window or it is in another tab page 0 is
Sean Deward64801e2024-03-12 20:46:12 +010012237 returned. May refer to the current window in
12238 some cases (e.g. when evaluating 'statusline'
12239 expressions).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012240 {N}j the number of the Nth window below the
12241 current window (where |CTRL-W_j| goes to).
12242 {N}k the number of the Nth window above the current
12243 window (where |CTRL-W_k| goes to).
12244 {N}h the number of the Nth window left of the
12245 current window (where |CTRL-W_h| goes to).
12246 {N}l the number of the Nth window right of the
12247 current window (where |CTRL-W_l| goes to).
12248 The number can be used with |CTRL-W_w| and ":wincmd w"
12249 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010012250 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012251 Also see |tabpagewinnr()| and |win_getid()|.
12252 Examples: >
12253 let window_count = winnr('$')
12254 let prev_window = winnr('#')
12255 let wnum = winnr('3k')
12256
12257< Can also be used as a |method|: >
12258 GetWinval()->winnr()
12259<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012260 Return type: |Number|
12261
12262
12263winrestcmd() *winrestcmd()*
12264 Returns a sequence of |:resize| commands that should restore
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012265 the current window sizes. Only works properly when no windows
12266 are opened or closed and the current window and tab page is
12267 unchanged.
12268 Example: >
12269 :let cmd = winrestcmd()
12270 :call MessWithWindowSizes()
12271 :exe cmd
12272<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012273 Return type: |String|
12274
12275
12276winrestview({dict}) *winrestview()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012277 Uses the |Dictionary| returned by |winsaveview()| to restore
12278 the view of the current window.
12279 Note: The {dict} does not have to contain all values, that are
12280 returned by |winsaveview()|. If values are missing, those
12281 settings won't be restored. So you can use: >
12282 :call winrestview({'curswant': 4})
12283<
12284 This will only set the curswant value (the column the cursor
12285 wants to move on vertical movements) of the cursor to column 5
12286 (yes, that is 5), while all other settings will remain the
12287 same. This is useful, if you set the cursor position manually.
12288
12289 If you have changed the values the result is unpredictable.
12290 If the window size changed the result won't be the same.
12291
12292 Can also be used as a |method|: >
12293 GetView()->winrestview()
12294<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012295 Return type: |Number|
12296
12297
12298winsaveview() *winsaveview()*
12299 Returns a |Dictionary| that contains information to restore
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012300 the view of the current window. Use |winrestview()| to
12301 restore the view.
12302 This is useful if you have a mapping that jumps around in the
12303 buffer and you want to go back to the original view.
12304 This does not save fold information. Use the 'foldenable'
12305 option to temporarily switch off folding, so that folds are
12306 not opened when moving around. This may have side effects.
12307 The return value includes:
12308 lnum cursor line number
12309 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000012310 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012311 returns)
12312 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000012313 curswant column for vertical movement (Note:
12314 the first column is zero, as opposed
12315 to what |getcurpos()| returns). After
12316 |$| command it will be a very large
12317 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012318 topline first line in the window
12319 topfill filler lines, only in diff mode
12320 leftcol first column displayed; only used when
12321 'wrap' is off
12322 skipcol columns skipped
12323 Note that no option values are saved.
12324
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012325 Return type: dict<number>
12326
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012327
12328winwidth({nr}) *winwidth()*
12329 The result is a Number, which is the width of window {nr}.
12330 {nr} can be the window number or the |window-ID|.
12331 When {nr} is zero, the width of the current window is
12332 returned. When window {nr} doesn't exist, -1 is returned.
12333 An existing window always has a width of zero or more.
12334 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012335 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012336 :if winwidth(0) <= 50
12337 : 50 wincmd |
12338 :endif
12339< For getting the terminal or screen size, see the 'columns'
12340 option.
12341
12342 Can also be used as a |method|: >
12343 GetWinid()->winwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012344<
12345 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012346
12347
12348wordcount() *wordcount()*
12349 The result is a dictionary of byte/chars/word statistics for
12350 the current buffer. This is the same info as provided by
12351 |g_CTRL-G|
12352 The return value includes:
12353 bytes Number of bytes in the buffer
12354 chars Number of chars in the buffer
12355 words Number of words in the buffer
12356 cursor_bytes Number of bytes before cursor position
12357 (not in Visual mode)
12358 cursor_chars Number of chars before cursor position
12359 (not in Visual mode)
12360 cursor_words Number of words before cursor position
12361 (not in Visual mode)
12362 visual_bytes Number of bytes visually selected
12363 (only in Visual mode)
12364 visual_chars Number of chars visually selected
12365 (only in Visual mode)
12366 visual_words Number of words visually selected
12367 (only in Visual mode)
12368
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012369 Return type: dict<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012370
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012371
12372writefile({object}, {fname} [, {flags}]) *writefile()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012373 When {object} is a |List| write it to file {fname}. Each list
12374 item is separated with a NL. Each list item must be a String
12375 or Number.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012376 All NL characters are replaced with a NUL character.
12377 Inserting CR characters needs to be done before passing {list}
12378 to writefile().
Bram Moolenaar806a2732022-09-04 15:40:36 +010012379
12380 When {object} is a |Blob| write the bytes to file {fname}
12381 unmodified, also when binary mode is not specified.
12382
12383 {flags} must be a String. These characters are recognized:
12384
12385 'b' Binary mode is used: There will not be a NL after the
12386 last list item. An empty item at the end does cause the
12387 last line in the file to end in a NL.
12388
12389 'a' Append mode is used, lines are appended to the file: >
12390 :call writefile(["foo"], "event.log", "a")
12391 :call writefile(["bar"], "event.log", "a")
12392<
12393 'D' Delete the file when the current function ends. This
12394 works like: >
Bram Moolenaar938ae282023-02-20 20:44:55 +000012395 :defer delete({fname})
Bram Moolenaar806a2732022-09-04 15:40:36 +010012396< Fails when not in a function. Also see |:defer|.
12397
12398 's' fsync() is called after writing the file. This flushes
12399 the file to disk, if possible. This takes more time but
12400 avoids losing the file if the system crashes.
12401
12402 'S' fsync() is not called, even when 'fsync' is set.
12403
12404 When {flags} does not contain "S" or "s" then fsync() is
12405 called if the 'fsync' option is set.
12406
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012407 An existing file is overwritten, if possible.
Bram Moolenaar806a2732022-09-04 15:40:36 +010012408
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012409 When the write fails -1 is returned, otherwise 0. There is an
12410 error message if the file can't be created or when writing
12411 fails.
Bram Moolenaar806a2732022-09-04 15:40:36 +010012412
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012413 Also see |readfile()|.
12414 To copy a file byte for byte: >
12415 :let fl = readfile("foo", "b")
12416 :call writefile(fl, "foocopy", "b")
12417
12418< Can also be used as a |method|: >
12419 GetText()->writefile("thefile")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012420<
12421 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012422
12423
12424xor({expr}, {expr}) *xor()*
12425 Bitwise XOR on the two arguments. The arguments are converted
12426 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012427 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012428 Example: >
12429 :let bits = xor(bits, 0x80)
12430<
12431 Can also be used as a |method|: >
12432 :let bits = bits->xor(0x80)
12433<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012434 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012435
12436==============================================================================
124373. Feature list *feature-list*
12438
12439There are three types of features:
124401. Features that are only supported when they have been enabled when Vim
12441 was compiled |+feature-list|. Example: >
12442 :if has("cindent")
12443< *gui_running*
124442. Features that are only supported when certain conditions have been met.
12445 Example: >
12446 :if has("gui_running")
12447< *has-patch*
124483. Beyond a certain version or at a certain version and including a specific
12449 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
12450 later, or it is version 7.4 and patch 248 was included. Example: >
12451 :if has("patch-7.4.248")
12452< Note that it's possible for patch 248 to be omitted even though 249 is
12453 included. Only happens when cherry-picking patches.
12454 Note that this form only works for patch 7.4.237 and later, before that
12455 you need to check for the patch and the v:version. Example (checking
12456 version 6.2.148 or later): >
12457 :if v:version > 602 || (v:version == 602 && has("patch148"))
12458
12459Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
12460use: `if exists('+shellslash')`
12461
12462
12463acl Compiled with |ACL| support.
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010012464all_builtin_terms Compiled with all builtin terminals enabled. (always
12465 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012466amiga Amiga version of Vim.
12467arabic Compiled with Arabic support |Arabic|.
12468arp Compiled with ARP support (Amiga).
12469autocmd Compiled with autocommand support. (always true)
12470autochdir Compiled with support for 'autochdir'
12471autoservername Automatically enable |clientserver|
12472balloon_eval Compiled with |balloon-eval| support.
12473balloon_multiline GUI supports multiline balloons.
12474beos BeOS version of Vim.
12475browse Compiled with |:browse| support, and browse() will
12476 work.
12477browsefilter Compiled with support for |browsefilter|.
12478bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010012479builtin_terms Compiled with some builtin terminals. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012480byte_offset Compiled with support for 'o' in 'statusline'
12481channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012482cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012483clientserver Compiled with remote invocation support |clientserver|.
12484clipboard Compiled with 'clipboard' support.
12485clipboard_working Compiled with 'clipboard' support and it can be used.
12486cmdline_compl Compiled with |cmdline-completion| support.
12487cmdline_hist Compiled with |cmdline-history| support.
12488cmdline_info Compiled with 'showcmd' and 'ruler' support.
12489comments Compiled with |'comments'| support.
12490compatible Compiled to be very Vi compatible.
12491conpty Platform where |ConPTY| can be used.
12492cryptv Compiled with encryption support |encryption|.
12493cscope Compiled with |cscope| support.
12494cursorbind Compiled with |'cursorbind'| (always true)
12495debug Compiled with "DEBUG" defined.
12496dialog_con Compiled with console dialog support.
glepnirdf461152024-04-04 22:23:29 +020012497dialog_con_gui Compiled with console and GUI dialog support.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012498dialog_gui Compiled with GUI dialog support.
12499diff Compiled with |vimdiff| and 'diff' support.
12500digraphs Compiled with support for digraphs.
12501directx Compiled with support for DirectX and 'renderoptions'.
12502dnd Compiled with support for the "~ register |quote_~|.
12503drop_file Compiled with |drop_file| support.
12504ebcdic Compiled on a machine with ebcdic character set.
12505emacs_tags Compiled with support for Emacs tags.
12506eval Compiled with expression evaluation support. Always
12507 true, of course!
12508ex_extra |+ex_extra| (always true)
12509extra_search Compiled with support for |'incsearch'| and
12510 |'hlsearch'|
12511farsi Support for Farsi was removed |farsi|.
Bram Moolenaarf80f40a2022-08-25 16:02:23 +010012512file_in_path Compiled with support for |gf| and |<cfile>| (always
12513 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012514filterpipe When 'shelltemp' is off pipes are used for shell
12515 read/write/filter commands
12516find_in_path Compiled with support for include file searches
12517 |+find_in_path|.
12518float Compiled with support for |Float|.
12519fname_case Case in file names matters (for Amiga and MS-Windows
12520 this is not present).
12521folding Compiled with |folding| support.
12522footer Compiled with GUI footer support. |gui-footer|
12523fork Compiled to use fork()/exec() instead of system().
12524gettext Compiled with message translation |multi-lang|
12525gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010012526gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012527gui_gnome Compiled with Gnome support (gui_gtk is also defined).
12528gui_gtk Compiled with GTK+ GUI (any version).
12529gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
12530gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
12531gui_haiku Compiled with Haiku GUI.
12532gui_mac Compiled with Macintosh GUI.
12533gui_motif Compiled with Motif GUI.
12534gui_photon Compiled with Photon GUI.
12535gui_running Vim is running in the GUI, or it will start soon.
12536gui_win32 Compiled with MS-Windows Win32 GUI.
12537gui_win32s idem, and Win32s system being used (Windows 3.1)
12538haiku Haiku version of Vim.
12539hangul_input Compiled with Hangul input support. |hangul|
12540hpux HP-UX version of Vim.
12541iconv Can use iconv() for conversion.
12542insert_expand Compiled with support for CTRL-X expansion commands in
12543 Insert mode. (always true)
12544job Compiled with support for |channel| and |job|
12545ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012546jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012547keymap Compiled with 'keymap' support.
12548lambda Compiled with |lambda| support.
12549langmap Compiled with 'langmap' support.
12550libcall Compiled with |libcall()| support.
12551linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
12552 'breakindent' support.
12553linux Linux version of Vim.
12554lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012555 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012556listcmds Compiled with commands for the buffer list |:files|
12557 and the argument list |arglist|.
12558localmap Compiled with local mappings and abbr. |:map-local|
12559lua Compiled with Lua interface |Lua|.
12560mac Any Macintosh version of Vim cf. osx
12561macunix Synonym for osxdarwin
12562menu Compiled with support for |:menu|.
12563mksession Compiled with support for |:mksession|.
12564modify_fname Compiled with file name modifiers. |filename-modifiers|
12565 (always true)
12566mouse Compiled with support for mouse.
12567mouse_dec Compiled with support for Dec terminal mouse.
12568mouse_gpm Compiled with support for gpm (Linux console mouse)
12569mouse_gpm_enabled GPM mouse is working
12570mouse_netterm Compiled with support for netterm mouse.
12571mouse_pterm Compiled with support for qnx pterm mouse.
12572mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
12573mouse_sgr Compiled with support for sgr mouse.
12574mouse_urxvt Compiled with support for urxvt mouse.
12575mouse_xterm Compiled with support for xterm mouse.
12576mouseshape Compiled with support for 'mouseshape'.
12577multi_byte Compiled with support for 'encoding' (always true)
12578multi_byte_encoding 'encoding' is set to a multibyte encoding.
12579multi_byte_ime Compiled with support for IME input method.
12580multi_lang Compiled with support for multiple languages.
12581mzscheme Compiled with MzScheme interface |mzscheme|.
12582nanotime Compiled with sub-second time stamp checks.
12583netbeans_enabled Compiled with support for |netbeans| and connected.
12584netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012585num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012586ole Compiled with OLE automation support for Win32.
12587osx Compiled for macOS cf. mac
12588osxdarwin Compiled for macOS, with |mac-darwin-feature|
12589packages Compiled with |packages| support.
12590path_extra Compiled with up/downwards search in 'path' and 'tags'
12591perl Compiled with Perl interface.
12592persistent_undo Compiled with support for persistent undo history.
12593postscript Compiled with PostScript file printing.
12594printer Compiled with |:hardcopy| support.
12595profile Compiled with |:profile| support.
Bram Moolenaar71badf92023-04-22 22:40:14 +010012596prof_nsec Profile results are in nanoseconds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012597python Python 2.x interface available. |has-python|
12598python_compiled Compiled with Python 2.x interface. |has-python|
12599python_dynamic Python 2.x interface is dynamically loaded. |has-python|
12600python3 Python 3.x interface available. |has-python|
12601python3_compiled Compiled with Python 3.x interface. |has-python|
12602python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Yee Cheng Chinc13b3d12023-08-20 21:18:38 +020012603python3_stable Python 3.x interface is using Python Stable ABI. |has-python|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012604pythonx Python 2.x and/or 3.x interface available. |python_x|
12605qnx QNX version of Vim.
12606quickfix Compiled with |quickfix| support.
12607reltime Compiled with |reltime()| support.
12608rightleft Compiled with 'rightleft' support.
12609ruby Compiled with Ruby interface |ruby|.
12610scrollbind Compiled with 'scrollbind' support. (always true)
12611showcmd Compiled with 'showcmd' support.
12612signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012613smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012614sodium Compiled with libsodium for better crypt support
12615sound Compiled with sound support, e.g. `sound_playevent()`
12616spell Compiled with spell checking support |spell|.
12617startuptime Compiled with |--startuptime| support.
12618statusline Compiled with support for 'statusline', 'rulerformat'
12619 and special formats of 'titlestring' and 'iconstring'.
12620sun SunOS version of Vim.
12621sun_workshop Support for Sun |workshop| has been removed.
12622syntax Compiled with syntax highlighting support |syntax|.
12623syntax_items There are active syntax highlighting items for the
12624 current buffer.
12625system Compiled to use system() instead of fork()/exec().
12626tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012627 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012628tag_old_static Support for old static tags was removed, see
12629 |tag-old-static|.
12630tcl Compiled with Tcl interface.
12631termguicolors Compiled with true color in terminal support.
12632terminal Compiled with |terminal| support.
12633terminfo Compiled with terminfo instead of termcap.
12634termresponse Compiled with support for |t_RV| and |v:termresponse|.
12635textobjects Compiled with support for |text-objects|.
12636textprop Compiled with support for |text-properties|.
12637tgetent Compiled with tgetent support, able to use a termcap
12638 or terminfo file.
12639timers Compiled with |timer_start()| support.
12640title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012641 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012642toolbar Compiled with support for |gui-toolbar|.
12643ttyin input is a terminal (tty)
12644ttyout output is a terminal (tty)
12645unix Unix version of Vim. *+unix*
12646unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
12647user_commands User-defined commands. (always true)
12648vartabs Compiled with variable tabstop support |'vartabstop'|.
12649vcon Win32: Virtual console support is working, can use
12650 'termguicolors'. Also see |+vtp|.
12651vertsplit Compiled with vertically split windows |:vsplit|.
12652 (always true)
12653vim_starting True while initial source'ing takes place. |startup|
12654 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000012655vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012656viminfo Compiled with viminfo support.
12657vimscript-1 Compiled Vim script version 1 support
12658vimscript-2 Compiled Vim script version 2 support
12659vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010012660vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012661virtualedit Compiled with 'virtualedit' option. (always true)
12662visual Compiled with Visual mode. (always true)
12663visualextra Compiled with extra Visual mode commands. (always
12664 true) |blockwise-operators|.
12665vms VMS version of Vim.
12666vreplace Compiled with |gR| and |gr| commands. (always true)
12667vtp Compiled for vcon support |+vtp| (check vcon to find
12668 out if it works in the current console).
12669wildignore Compiled with 'wildignore' option.
12670wildmenu Compiled with 'wildmenu' option.
12671win16 old version for MS-Windows 3.1 (always false)
12672win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
12673 64 bits)
12674win32unix Win32 version of Vim, using Unix files (Cygwin)
12675win64 Win64 version of Vim (MS-Windows 64 bit).
12676win95 Win32 version for MS-Windows 95/98/ME (always false)
12677winaltkeys Compiled with 'winaltkeys' option.
12678windows Compiled with support for more than one window.
12679 (always true)
12680writebackup Compiled with 'writebackup' default on.
Christian Brabandte085dfd2023-09-30 12:49:18 +020012681xattr Compiled with extended attributes support |xattr|
12682 (currently only supported on Linux).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012683xfontset Compiled with X fontset support |xfontset|.
12684xim Compiled with X input method support |xim|.
12685xpm Compiled with pixmap support.
12686xpm_w32 Compiled with pixmap support for Win32. (Only for
12687 backward compatibility. Use "xpm" instead.)
12688xsmp Compiled with X session management support.
12689xsmp_interact Compiled with interactive X session management support.
12690xterm_clipboard Compiled with support for xterm clipboard.
12691xterm_save Compiled with support for saving and restoring the
12692 xterm screen.
12693x11 Compiled with X11 support.
12694
12695
12696==============================================================================
126974. Matching a pattern in a String *string-match*
12698
12699This is common between several functions. A regexp pattern as explained at
12700|pattern| is normally used to find a match in the buffer lines. When a
12701pattern is used to find a match in a String, almost everything works in the
12702same way. The difference is that a String is handled like it is one line.
12703When it contains a "\n" character, this is not seen as a line break for the
12704pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
12705>
12706 :let a = "aaaa\nxxxx"
12707 :echo matchstr(a, "..\n..")
12708 aa
12709 xx
12710 :echo matchstr(a, "a.x")
12711 a
12712 x
12713
12714Don't forget that "^" will only match at the first character of the String and
12715"$" at the last character of the string. They don't match after or before a
12716"\n".
12717
12718 vim:tw=78:ts=8:noet:ft=help:norl: