blob: 60dbb4799f0f2829bdcff8531ce5908ec091e3f3 [file] [log] [blame]
zeertzjqe2c0f812025-07-06 20:26:56 +02001*builtin.txt* For Vim version 9.1. Last change: 2025 Jul 06
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
h-easte80f3452025-01-02 10:40:29 +010070base64_decode({string}) Blob base64 decode {string} characters
71base64_encode({blob}) String base64 encode the bytes in {blob}
Christ van Willegence0ef912024-06-20 23:41:59 +020072bindtextdomain({package}, {path})
Christ van Willegen8252ef12024-07-11 21:36:21 +020073 Bool bind text domain to specified path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000074blob2list({blob}) List convert {blob} into a list of numbers
Yegappan Lakshmanan166b1752025-01-17 11:48:12 +010075blob2str({blob} [, {options}]) List convert {blob} into a list of strings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000076browse({save}, {title}, {initdir}, {default})
77 String put up a file requester
78browsedir({title}, {initdir}) String put up a directory requester
79bufadd({name}) Number add a buffer to the buffer list
80bufexists({buf}) Number |TRUE| if buffer {buf} exists
81buflisted({buf}) Number |TRUE| if buffer {buf} is listed
82bufload({buf}) Number load buffer {buf} if not loaded yet
83bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
84bufname([{buf}]) String Name of the buffer {buf}
85bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
86bufwinid({buf}) Number window ID of buffer {buf}
87bufwinnr({buf}) Number window number of buffer {buf}
88byte2line({byte}) Number line number at byte count {byte}
Christian Brabandt67672ef2023-04-24 21:09:54 +010089byteidx({expr}, {nr} [, {utf16}])
90 Number byte index of {nr}'th char in {expr}
91byteidxcomp({expr}, {nr} [, {utf16}])
92 Number byte index of {nr}'th char in {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000093call({func}, {arglist} [, {dict}])
94 any call {func} with arguments {arglist}
95ceil({expr}) Float round {expr} up
96ch_canread({handle}) Number check if there is something to read
97ch_close({handle}) none close {handle}
98ch_close_in({handle}) none close in part of {handle}
99ch_evalexpr({handle}, {expr} [, {options}])
100 any evaluate {expr} on JSON {handle}
101ch_evalraw({handle}, {string} [, {options}])
102 any evaluate {string} on raw {handle}
103ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
104ch_getjob({channel}) Job get the Job of {channel}
105ch_info({handle}) String info about channel {handle}
106ch_log({msg} [, {handle}]) none write {msg} in the channel log file
107ch_logfile({fname} [, {mode}]) none start logging channel activity
108ch_open({address} [, {options}])
109 Channel open a channel to {address}
110ch_read({handle} [, {options}]) String read from {handle}
111ch_readblob({handle} [, {options}])
112 Blob read Blob from {handle}
113ch_readraw({handle} [, {options}])
114 String read raw from {handle}
115ch_sendexpr({handle}, {expr} [, {options}])
116 any send {expr} over JSON {handle}
117ch_sendraw({handle}, {expr} [, {options}])
118 any send {expr} over raw {handle}
119ch_setoptions({handle}, {options})
120 none set options for {handle}
121ch_status({handle} [, {options}])
122 String status of channel {handle}
123changenr() Number current change number
124char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
125charclass({string}) Number character class of {string}
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000126charcol({expr} [, {winid}]) Number column number of cursor or mark
Christian Brabandt67672ef2023-04-24 21:09:54 +0100127charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000128 Number char index of byte {idx} in {string}
129chdir({dir}) String change current working directory
130cindent({lnum}) Number C indent for line {lnum}
131clearmatches([{win}]) none clear all matches
Girish Palya92f68e22025-04-21 11:12:41 +0200132cmdcomplete_info() Dict get current cmdline completion
133 information
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000134col({expr} [, {winid}]) Number column byte index of cursor or mark
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000135complete({startcol}, {matches}) none set Insert mode completion
136complete_add({expr}) Number add completion match
137complete_check() Number check for key typed during completion
138complete_info([{what}]) Dict get current completion information
glepnirbcd59952025-04-24 21:48:35 +0200139complete_match([{lnum}, {col}]) List get completion column and trigger text
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000140confirm({msg} [, {choices} [, {default} [, {type}]]])
141 Number number of choice picked by user
142copy({expr}) any make a shallow copy of {expr}
143cos({expr}) Float cosine of {expr}
144cosh({expr}) Float hyperbolic cosine of {expr}
145count({comp}, {expr} [, {ic} [, {start}]])
146 Number count how many {expr} are in {comp}
147cscope_connection([{num}, {dbpath} [, {prepend}]])
148 Number checks existence of cscope connection
149cursor({lnum}, {col} [, {off}])
150 Number move cursor to {lnum}, {col}, {off}
151cursor({list}) Number move cursor to position in {list}
152debugbreak({pid}) Number interrupt process being debugged
153deepcopy({expr} [, {noref}]) any make a full copy of {expr}
154delete({fname} [, {flags}]) Number delete the file or directory {fname}
155deletebufline({buf}, {first} [, {last}])
156 Number delete lines from buffer {buf}
157did_filetype() Number |TRUE| if FileType autocmd event used
Yegappan Lakshmananfa378352024-02-01 22:05:27 +0100158diff({fromlist}, {tolist} [, {options}])
159 List diff two Lists of strings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000160diff_filler({lnum}) Number diff filler lines about {lnum}
161diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
162digraph_get({chars}) String get the |digraph| of {chars}
163digraph_getlist([{listall}]) List get all |digraph|s
Christian Brabandtfbc37f12024-06-18 20:50:58 +0200164digraph_set({chars}, {digraph}) Bool register |digraph|
165digraph_setlist({digraphlist}) Bool register multiple |digraph|s
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000166echoraw({expr}) none output {expr} as-is
167empty({expr}) Number |TRUE| if {expr} is empty
168environ() Dict return environment variables
Sean Dewarb0efa492023-07-08 10:35:19 +0100169err_teapot([{expr}]) none give E418, or E503 if {expr} is |TRUE|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000170escape({string}, {chars}) String escape {chars} in {string} with '\'
171eval({string}) any evaluate {string} into its value
172eventhandler() Number |TRUE| if inside an event handler
173executable({expr}) Number 1 if executable {expr} exists
174execute({command}) String execute {command} and get the output
175exepath({expr}) String full path of the command {expr}
176exists({expr}) Number |TRUE| if {expr} exists
177exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
178exp({expr}) Float exponential of {expr}
179expand({expr} [, {nosuf} [, {list}]])
180 any expand special keywords in {expr}
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +0100181expandcmd({string} [, {options}])
182 String expand {string} like with `:edit`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000183extend({expr1}, {expr2} [, {expr3}])
184 List/Dict insert items of {expr2} into {expr1}
185extendnew({expr1}, {expr2} [, {expr3}])
186 List/Dict like |extend()| but creates a new
187 List or Dictionary
188feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Shougo Matsushita60c87432024-06-03 22:59:27 +0200189filecopy({from}, {to}) Number |TRUE| if copying file {from} to {to}
190 worked
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000191filereadable({file}) Number |TRUE| if {file} is a readable file
192filewritable({file}) Number |TRUE| if {file} is a writable file
193filter({expr1}, {expr2}) List/Dict/Blob/String
194 remove items from {expr1} where
195 {expr2} is 0
196finddir({name} [, {path} [, {count}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000197findfile({name} [, {path} [, {count}]])
Christian Brabandt17ad8522025-05-09 00:03:20 +0200198 String/List find dir/file {name} in {path}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000199flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
200flattennew({list} [, {maxdepth}])
201 List flatten a copy of {list}
202float2nr({expr}) Number convert Float {expr} to a Number
203floor({expr}) Float round {expr} down
204fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
205fnameescape({fname}) String escape special characters in {fname}
206fnamemodify({fname}, {mods}) String modify file name
207foldclosed({lnum}) Number first line of fold at {lnum} if closed
208foldclosedend({lnum}) Number last line of fold at {lnum} if closed
209foldlevel({lnum}) Number fold level at {lnum}
210foldtext() String line displayed for closed fold
211foldtextresult({lnum}) String text for closed fold at {lnum}
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100212foreach({expr1}, {expr2}) List/Tuple/Dict/Blob/String
Ernie Raele79e2072024-01-13 11:47:33 +0100213 for each item in {expr1} call {expr2}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000214foreground() Number bring the Vim window to the foreground
Bram Moolenaaraa534142022-09-15 21:46:02 +0100215fullcommand({name} [, {vim9}]) String get full command from {name}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000216funcref({name} [, {arglist}] [, {dict}])
217 Funcref reference to function {name}
218function({name} [, {arglist}] [, {dict}])
219 Funcref named reference to function {name}
220garbagecollect([{atexit}]) none free memory, breaking cyclic references
221get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
222get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
223get({func}, {what}) any get property of funcref/partial {func}
224getbufinfo([{buf}]) List information about buffers
225getbufline({buf}, {lnum} [, {end}])
226 List lines {lnum} to {end} of buffer {buf}
Bram Moolenaarce30ccc2022-11-21 19:57:04 +0000227getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000228getbufvar({buf}, {varname} [, {def}])
229 any variable {varname} in buffer {buf}
mikoto20001083cae2024-11-11 21:24:14 +0100230getcellpixels() List get character cell pixel size
Kota Kato66bb9ae2023-01-17 18:31:56 +0000231getcellwidths() List get character cell width overrides
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000232getchangelist([{buf}]) List list of change list items
zeertzjqe0a2ab32025-02-02 09:14:35 +0100233getchar([{expr} [, {opts}]]) Number or String
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000234 get one character from the user
235getcharmod() Number modifiers for the last typed character
236getcharpos({expr}) List position of cursor, mark, etc.
237getcharsearch() Dict last character search
zeertzjqe0a2ab32025-02-02 09:14:35 +0100238getcharstr([{expr} [, {opts}]]) String get one character from the user
Ruslan Russkikh0407d622024-10-08 22:21:05 +0200239getcmdcomplpat() String return the completion pattern of the
240 current command-line completion
Hirohito Higashi96b3ef22025-07-05 15:31:23 +0200241getcmdcompltype() String return the type of the current
242 command-line completion
Shougo Matsushita69084282024-09-23 20:34:47 +0200243getcmdline() String return the current command-line input
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000244getcmdpos() Number return cursor position in command-line
Shougo Matsushita69084282024-09-23 20:34:47 +0200245getcmdprompt() String return the current command-line prompt
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100246getcmdscreenpos() Number return cursor screen position in
247 command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000248getcmdtype() String return current command-line type
249getcmdwintype() String return current command-line window type
250getcompletion({pat}, {type} [, {filtered}])
251 List list of cmdline completion matches
Hirohito Higashi96b3ef22025-07-05 15:31:23 +0200252getcompletiontype({pat}) String return the type of the command-line
253 completion using {pat}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000254getcurpos([{winnr}]) List position of the cursor
255getcursorcharpos([{winnr}]) List character position of the cursor
256getcwd([{winnr} [, {tabnr}]]) String get the current working directory
257getenv({name}) String return environment variable
258getfontname([{name}]) String name of font being used
259getfperm({fname}) String file permissions of file {fname}
260getfsize({fname}) Number size in bytes of file {fname}
261getftime({fname}) Number last modification time of file
262getftype({fname}) String description of type of file {fname}
263getimstatus() Number |TRUE| if the IME status is active
264getjumplist([{winnr} [, {tabnr}]])
265 List list of jump list items
266getline({lnum}) String line {lnum} of current buffer
267getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
268getloclist({nr}) List list of location list items
269getloclist({nr}, {what}) Dict get specific location list properties
270getmarklist([{buf}]) List list of global/local marks
271getmatches([{win}]) List list of current matches
272getmousepos() Dict last known mouse position
Bram Moolenaar24dc19c2022-11-14 19:49:15 +0000273getmouseshape() String current mouse shape name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000274getpid() Number process ID of Vim
275getpos({expr}) List position of cursor, mark, etc.
276getqflist() List list of quickfix items
277getqflist({what}) Dict get specific quickfix list properties
278getreg([{regname} [, 1 [, {list}]]])
279 String or List contents of a register
280getreginfo([{regname}]) Dict information about a register
Shougo Matsushita19b71882024-02-28 22:48:12 +0100281getregion({pos1}, {pos2} [, {opts}])
Shougo Matsushita3f905ab2024-02-21 00:02:45 +0100282 List get the text from {pos1} to {pos2}
Shougo Matsushitab4757e62024-05-07 20:49:24 +0200283getregionpos({pos1}, {pos2} [, {opts}])
284 List get a list of positions for a region
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000285getregtype([{regname}]) String type of a register
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +0100286getscriptinfo([{opts}]) List list of sourced scripts
ichizok663d18d2025-01-02 18:06:00 +0100287getstacktrace() List get current stack trace of Vim scripts
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000288gettabinfo([{expr}]) List list of tab pages
289gettabvar({nr}, {varname} [, {def}])
290 any variable {varname} in tab {nr} or {def}
291gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
292 any {name} in {winnr} in tab page {tabnr}
293gettagstack([{nr}]) Dict get the tag stack of window {nr}
h-east52e7cc22024-07-28 17:03:29 +0200294gettext({text} [, {package}]) String lookup translation of {text}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000295getwininfo([{winid}]) List list of info about each window
Bram Moolenaar938ae282023-02-20 20:44:55 +0000296getwinpos([{timeout}]) List X and Y coord in pixels of Vim window
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000297getwinposx() Number X coord in pixels of the Vim window
298getwinposy() Number Y coord in pixels of the Vim window
299getwinvar({nr}, {varname} [, {def}])
300 any variable {varname} in window {nr}
301glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
302 any expand file wildcards in {expr}
303glob2regpat({expr}) String convert a glob pat into a search pat
304globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
305 String do glob({expr}) for all dirs in {path}
306has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
307has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
308haslocaldir([{winnr} [, {tabnr}]])
309 Number |TRUE| if the window executed |:lcd|
310 or |:tcd|
311hasmapto({what} [, {mode} [, {abbr}]])
312 Number |TRUE| if mapping to {what} exists
313histadd({history}, {item}) Number add an item to a history
314histdel({history} [, {item}]) Number remove an item from a history
315histget({history} [, {index}]) String get the item {index} from a history
316histnr({history}) Number highest index of a history
317hlID({name}) Number syntax ID of highlight group {name}
318hlexists({name}) Number |TRUE| if highlight group {name} exists
319hlget([{name} [, {resolve}]]) List get highlight group attributes
320hlset({list}) Number set highlight group attributes
321hostname() String name of the machine Vim is running on
322iconv({expr}, {from}, {to}) String convert encoding of {expr}
Ernie Rael05124252024-07-11 22:10:45 +0200323id({item}) String get unique identity string of item
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000324indent({lnum}) Number indent of line {lnum}
325index({object}, {expr} [, {start} [, {ic}]])
326 Number index in {object} where {expr} appears
Yegappan Lakshmananb2186552022-08-13 13:09:20 +0100327indexof({object}, {expr} [, {opts}]])
328 Number index in {object} where {expr} is true
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000329input({prompt} [, {text} [, {completion}]])
330 String get input from the user
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100331inputdialog({prompt} [, {text} [, {cancelreturn}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000332 String like input() but in a GUI dialog
333inputlist({textlist}) Number let the user pick from a choice list
334inputrestore() Number restore typeahead
335inputsave() Number save and clear typeahead
336inputsecret({prompt} [, {text}]) String like input() but hiding the text
337insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
LemonBoyafe04662023-08-23 21:08:11 +0200338instanceof({object}, {class}) Number |TRUE| if {object} is an instance of {class}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000339interrupt() none interrupt script execution
340invert({expr}) Number bitwise invert
LemonBoydca1d402022-04-28 15:26:33 +0100341isabsolutepath({path}) Number |TRUE| if {path} is an absolute path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000342isdirectory({directory}) Number |TRUE| if {directory} is a directory
343isinf({expr}) Number determine if {expr} is infinity value
344 (positive or negative)
345islocked({expr}) Number |TRUE| if {expr} is locked
346isnan({expr}) Number |TRUE| if {expr} is NaN
347items({dict}) List key-value pairs in {dict}
348job_getchannel({job}) Channel get the channel handle for {job}
349job_info([{job}]) Dict get information about {job}
350job_setoptions({job}, {options}) none set options for {job}
351job_start({command} [, {options}])
352 Job start a job
353job_status({job}) String get the status of {job}
354job_stop({job} [, {how}]) Number stop {job}
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100355join({expr} [, {sep}]) String join items in {expr} into one String
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000356js_decode({string}) any decode JS style JSON
357js_encode({expr}) String encode JS style JSON
358json_decode({string}) any decode JSON
359json_encode({expr}) String encode JSON
360keys({dict}) List keys in {dict}
zeertzjqcdc83932022-09-12 13:38:41 +0100361keytrans({string}) String translate internal keycodes to a form
362 that can be used by |:map|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000363len({expr}) Number the length of {expr}
364libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
365libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
366line({expr} [, {winid}]) Number line nr of cursor, last line or mark
367line2byte({lnum}) Number byte count of line {lnum}
368lispindent({lnum}) Number Lisp indent for line {lnum}
369list2blob({list}) Blob turn {list} of numbers into a Blob
370list2str({list} [, {utf8}]) String turn {list} of numbers into a String
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100371list2tuple({list}) Tuple turn {list} of items into a tuple
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000372listener_add({callback} [, {buf}])
373 Number add a callback to listen to changes
374listener_flush([{buf}]) none invoke listener callbacks
375listener_remove({id}) none remove a listener callback
376localtime() Number current time
377log({expr}) Float natural logarithm (base e) of {expr}
378log10({expr}) Float logarithm of Float {expr} to base 10
379luaeval({expr} [, {expr}]) any evaluate |Lua| expression
380map({expr1}, {expr2}) List/Dict/Blob/String
381 change each item in {expr1} to {expr2}
382maparg({name} [, {mode} [, {abbr} [, {dict}]]])
383 String or Dict
384 rhs of mapping {name} in mode {mode}
385mapcheck({name} [, {mode} [, {abbr}]])
386 String check for mappings matching {name}
Ernie Rael09661202022-04-25 14:40:44 +0100387maplist([{abbr}]) List list of all mappings, a dict for each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000388mapnew({expr1}, {expr2}) List/Dict/Blob/String
389 like |map()| but creates a new List or
390 Dictionary
391mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
392match({expr}, {pat} [, {start} [, {count}]])
393 Number position where {pat} matches in {expr}
394matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
395 Number highlight {pattern} with {group}
396matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
397 Number highlight positions with {group}
398matcharg({nr}) List arguments of |:match|
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100399matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict})
400 List all the {pat} matches in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000401matchdelete({id} [, {win}]) Number delete match identified by {id}
402matchend({expr}, {pat} [, {start} [, {count}]])
403 Number position where {pat} ends in {expr}
404matchfuzzy({list}, {str} [, {dict}])
405 List fuzzy match {str} in {list}
406matchfuzzypos({list}, {str} [, {dict}])
407 List fuzzy match {str} in {list}
408matchlist({expr}, {pat} [, {start} [, {count}]])
409 List match and submatches of {pat} in {expr}
410matchstr({expr}, {pat} [, {start} [, {count}]])
411 String {count}'th match of {pat} in {expr}
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100412matchstrlist({list}, {pat} [, {dict})
413 List all the {pat} matches in {list}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000414matchstrpos({expr}, {pat} [, {start} [, {count}]])
415 List {count}'th match of {pat} in {expr}
416max({expr}) Number maximum value of items in {expr}
417menu_info({name} [, {mode}]) Dict get menu item information
418min({expr}) Number minimum value of items in {expr}
Bram Moolenaar938ae282023-02-20 20:44:55 +0000419mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000420 Number create directory {name}
Doug Kearns9cd9e752024-04-07 17:42:17 +0200421mode([{expr}]) String current editing mode
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000422mzeval({expr}) any evaluate |MzScheme| expression
423nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
Christ van Willegenc0786752025-02-01 15:42:16 +0100424ngettext({single}, {plural}, {number}[, {domain}])
425 String translate text based on {number}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000426nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
427or({expr}, {expr}) Number bitwise OR
428pathshorten({expr} [, {len}]) String shorten directory names in a path
429perleval({expr}) any evaluate |Perl| expression
430popup_atcursor({what}, {options}) Number create popup window near the cursor
431popup_beval({what}, {options}) Number create popup window for 'ballooneval'
432popup_clear() none close all popup windows
433popup_close({id} [, {result}]) none close popup window {id}
434popup_create({what}, {options}) Number create a popup window
435popup_dialog({what}, {options}) Number create a popup window used as a dialog
436popup_filter_menu({id}, {key}) Number filter for a menu popup window
437popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
Bram Moolenaarbdc09a12022-10-07 14:31:45 +0100438popup_findecho() Number get window ID of popup for `:echowin`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000439popup_findinfo() Number get window ID of info popup window
440popup_findpreview() Number get window ID of preview popup window
441popup_getoptions({id}) Dict get options of popup window {id}
442popup_getpos({id}) Dict get position of popup window {id}
443popup_hide({id}) none hide popup menu {id}
444popup_list() List get a list of window IDs of all popups
445popup_locate({row}, {col}) Number get window ID of popup at position
446popup_menu({what}, {options}) Number create a popup window used as a menu
447popup_move({id}, {options}) none set position of popup window {id}
448popup_notification({what}, {options})
449 Number create a notification popup window
Christian Brabandtfbc37f12024-06-18 20:50:58 +0200450popup_setbuf({id}, {buf}) Bool set the buffer for the popup window {id}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000451popup_setoptions({id}, {options})
452 none set options for popup window {id}
453popup_settext({id}, {text}) none set the text of popup window {id}
454popup_show({id}) none unhide popup window {id}
455pow({x}, {y}) Float {x} to the power of {y}
456prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
457printf({fmt}, {expr1}...) String format text
458prompt_getprompt({buf}) String get prompt text
459prompt_setcallback({buf}, {expr}) none set prompt callback function
460prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
461prompt_setprompt({buf}, {text}) none set prompt text
462prop_add({lnum}, {col}, {props}) none add one text property
463prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
464 none add multiple text properties
465prop_clear({lnum} [, {lnum-end} [, {props}]])
466 none remove all text properties
467prop_find({props} [, {direction}])
468 Dict search for a text property
469prop_list({lnum} [, {props}]) List text properties in {lnum}
470prop_remove({props} [, {lnum} [, {lnum-end}]])
471 Number remove a text property
472prop_type_add({name}, {props}) none define a new property type
473prop_type_change({name}, {props})
474 none change an existing property type
475prop_type_delete({name} [, {props}])
476 none delete a property type
477prop_type_get({name} [, {props}])
478 Dict get property type values
479prop_type_list([{props}]) List get list of property types
480pum_getpos() Dict position and size of pum if visible
481pumvisible() Number whether popup menu is visible
zeertzjq7c515282024-11-10 20:26:12 +0100482py3eval({expr} [, {locals}]) any evaluate |python3| expression
483pyeval({expr} [, {locals}]) any evaluate |Python| expression
484pyxeval({expr} [, {locals}]) any evaluate |python_x| expression
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000485rand([{expr}]) Number get pseudo-random number
486range({expr} [, {max} [, {stride}]])
487 List items from {expr} to {max}
K.Takata11df3ae2022-10-19 14:02:40 +0100488readblob({fname} [, {offset} [, {size}]])
489 Blob read a |Blob| from {fname}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000490readdir({dir} [, {expr} [, {dict}]])
491 List file names in {dir} selected by {expr}
492readdirex({dir} [, {expr} [, {dict}]])
493 List file info in {dir} selected by {expr}
494readfile({fname} [, {type} [, {max}]])
495 List get list of lines from file {fname}
496reduce({object}, {func} [, {initial}])
497 any reduce {object} using {func}
498reg_executing() String get the executing register name
499reg_recording() String get the recording register name
500reltime([{start} [, {end}]]) List get time value
501reltimefloat({time}) Float turn the time value into a Float
502reltimestr({time}) String turn time value into a String
503remote_expr({server}, {string} [, {idvar} [, {timeout}]])
504 String send expression
505remote_foreground({server}) Number bring Vim server to the foreground
506remote_peek({serverid} [, {retvar}])
507 Number check for reply string
508remote_read({serverid} [, {timeout}])
509 String read reply string
510remote_send({server}, {string} [, {idvar}])
511 String send key sequence
512remote_startserver({name}) none become server {name}
513remove({list}, {idx} [, {end}]) any/List
514 remove items {idx}-{end} from {list}
515remove({blob}, {idx} [, {end}]) Number/Blob
516 remove bytes {idx}-{end} from {blob}
517remove({dict}, {key}) any remove entry {key} from {dict}
518rename({from}, {to}) Number rename (move) file from {from} to {to}
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100519repeat({expr}, {count}) List/Tuple/Blob/String
Bakudankun375141e2022-09-09 18:46:47 +0100520 repeat {expr} {count} times
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000521resolve({filename}) String get filename a shortcut points to
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100522reverse({obj}) List/Tuple/Blob/String
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +0100523 reverse {obj}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000524round({expr}) Float round off {expr}
525rubyeval({expr}) any evaluate |Ruby| expression
526screenattr({row}, {col}) Number attribute at screen position
527screenchar({row}, {col}) Number character at screen position
528screenchars({row}, {col}) List List of characters at screen position
529screencol() Number current cursor column
530screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
531screenrow() Number current cursor row
532screenstring({row}, {col}) String characters at screen position
533search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
534 Number search for {pattern}
535searchcount([{options}]) Dict get or update search stats
536searchdecl({name} [, {global} [, {thisblock}]])
537 Number search for variable declaration
538searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
539 Number search for other end of start/end pair
540searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
541 List search for other end of start/end pair
542searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
543 List search for {pattern}
544server2client({clientid}, {string})
545 Number send reply string
546serverlist() String get a list of available servers
erraelf0837ba2024-06-24 12:27:01 -0700547setbufline({buf}, {lnum}, {text})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000548 Number set line {lnum} to {text} in buffer
erraelf0837ba2024-06-24 12:27:01 -0700549 {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000550setbufvar({buf}, {varname}, {val})
551 none set {varname} in buffer {buf} to {val}
552setcellwidths({list}) none set character cell width overrides
553setcharpos({expr}, {list}) Number set the {expr} position to {list}
554setcharsearch({dict}) Dict set character search from {dict}
Shougo Matsushita07ea5f12022-08-27 12:22:25 +0100555setcmdline({str} [, {pos}]) Number set command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000556setcmdpos({pos}) Number set cursor position in command-line
557setcursorcharpos({list}) Number move cursor to position in {list}
558setenv({name}, {val}) none set environment variable
559setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
560setline({lnum}, {line}) Number set line {lnum} to {line}
561setloclist({nr}, {list} [, {action}])
562 Number modify location list using {list}
563setloclist({nr}, {list}, {action}, {what})
564 Number modify specific location list props
565setmatches({list} [, {win}]) Number restore a list of matches
566setpos({expr}, {list}) Number set the {expr} position to {list}
567setqflist({list} [, {action}]) Number modify quickfix list using {list}
568setqflist({list}, {action}, {what})
569 Number modify specific quickfix list props
570setreg({n}, {v} [, {opt}]) Number set register to value and type
571settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
572settabwinvar({tabnr}, {winnr}, {varname}, {val})
573 none set {varname} in window {winnr} in tab
574 page {tabnr} to {val}
575settagstack({nr}, {dict} [, {action}])
576 Number modify tag stack using {dict}
577setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
578sha256({string}) String SHA256 checksum of {string}
579shellescape({string} [, {special}])
580 String escape {string} for use as shell
581 command argument
582shiftwidth([{col}]) Number effective value of 'shiftwidth'
583sign_define({name} [, {dict}]) Number define or update a sign
584sign_define({list}) List define or update a list of signs
585sign_getdefined([{name}]) List get a list of defined signs
586sign_getplaced([{buf} [, {dict}]])
587 List get a list of placed signs
588sign_jump({id}, {group}, {buf})
589 Number jump to a sign
590sign_place({id}, {group}, {name}, {buf} [, {dict}])
591 Number place a sign
592sign_placelist({list}) List place a list of signs
593sign_undefine([{name}]) Number undefine a sign
594sign_undefine({list}) List undefine a list of signs
595sign_unplace({group} [, {dict}])
596 Number unplace a sign
597sign_unplacelist({list}) List unplace a list of signs
598simplify({filename}) String simplify filename as much as possible
599sin({expr}) Float sine of {expr}
600sinh({expr}) Float hyperbolic sine of {expr}
601slice({expr}, {start} [, {end}]) String, List or Blob
602 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000603sort({list} [, {how} [, {dict}]])
604 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000605sound_clear() none stop playing all sounds
606sound_playevent({name} [, {callback}])
607 Number play an event sound
608sound_playfile({path} [, {callback}])
609 Number play sound file {path}
610sound_stop({id}) none stop playing sound {id}
611soundfold({word}) String sound-fold {word}
612spellbadword() String badly spelled word at cursor
613spellsuggest({word} [, {max} [, {capital}]])
614 List spelling suggestions
615split({expr} [, {pat} [, {keepempty}]])
616 List make |List| from {pat} separated {expr}
617sqrt({expr}) Float square root of {expr}
618srand([{expr}]) List get seed for |rand()|
619state([{what}]) String current state of Vim
Hirohito Higashi195fcc92025-02-01 10:26:58 +0100620str2blob({list} [, {options}]) Blob convert list of strings into a Blob
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000621str2float({expr} [, {quoted}]) Float convert String to Float
622str2list({expr} [, {utf8}]) List convert each character of {expr} to
623 ASCII/UTF-8 value
624str2nr({expr} [, {base} [, {quoted}]])
625 Number convert String to Number
626strcharlen({expr}) Number character length of the String {expr}
627strcharpart({str}, {start} [, {len} [, {skipcc}]])
628 String {len} characters of {str} at
629 character {start}
630strchars({expr} [, {skipcc}]) Number character count of the String {expr}
631strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
632strftime({format} [, {time}]) String format time with a specified format
633strgetchar({str}, {index}) Number get char {index} from {str}
634stridx({haystack}, {needle} [, {start}])
635 Number index of {needle} in {haystack}
636string({expr}) String String representation of {expr} value
637strlen({expr}) Number length of the String {expr}
638strpart({str}, {start} [, {len} [, {chars}]])
639 String {len} bytes/chars of {str} at
640 byte {start}
641strptime({format}, {timestring})
642 Number Convert {timestring} to unix timestamp
643strridx({haystack}, {needle} [, {start}])
644 Number last index of {needle} in {haystack}
645strtrans({expr}) String translate string to make it printable
Christian Brabandt67672ef2023-04-24 21:09:54 +0100646strutf16len({string} [, {countcc}])
647 Number number of UTF-16 code units in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000648strwidth({expr}) Number display cell length of the String {expr}
649submatch({nr} [, {list}]) String or List
650 specific match in ":s" or substitute()
651substitute({expr}, {pat}, {sub}, {flags})
652 String all {pat} in {expr} replaced with {sub}
Bram Moolenaarc216a7a2022-12-05 13:50:55 +0000653swapfilelist() List swap files found in 'directory'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000654swapinfo({fname}) Dict information about swap file {fname}
655swapname({buf}) String swap file of buffer {buf}
656synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
657synIDattr({synID}, {what} [, {mode}])
658 String attribute {what} of syntax ID {synID}
659synIDtrans({synID}) Number translated syntax ID of {synID}
660synconcealed({lnum}, {col}) List info about concealing
661synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
662system({expr} [, {input}]) String output of shell command/filter {expr}
663systemlist({expr} [, {input}]) List output of shell command/filter {expr}
664tabpagebuflist([{arg}]) List list of buffer numbers in tab page
665tabpagenr([{arg}]) Number number of current or last tab page
666tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
667tagfiles() List tags files used
668taglist({expr} [, {filename}]) List list of tags matching {expr}
669tan({expr}) Float tangent of {expr}
670tanh({expr}) Float hyperbolic tangent of {expr}
671tempname() String name for a temporary file
672term_dumpdiff({filename}, {filename} [, {options}])
673 Number display difference between two dumps
674term_dumpload({filename} [, {options}])
675 Number displaying a screen dump
676term_dumpwrite({buf}, {filename} [, {options}])
677 none dump terminal window contents
678term_getaltscreen({buf}) Number get the alternate screen flag
679term_getansicolors({buf}) List get ANSI palette in GUI color mode
680term_getattr({attr}, {what}) Number get the value of attribute {what}
681term_getcursor({buf}) List get the cursor position of a terminal
682term_getjob({buf}) Job get the job associated with a terminal
683term_getline({buf}, {row}) String get a line of text from a terminal
684term_getscrolled({buf}) Number get the scroll count of a terminal
685term_getsize({buf}) List get the size of a terminal
686term_getstatus({buf}) String get the status of a terminal
687term_gettitle({buf}) String get the title of a terminal
688term_gettty({buf}, [{input}]) String get the tty name of a terminal
689term_list() List get the list of terminal buffers
690term_scrape({buf}, {row}) List get row of a terminal screen
691term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
692term_setansicolors({buf}, {colors})
693 none set ANSI palette in GUI color mode
694term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
695term_setkill({buf}, {how}) none set signal to stop job in terminal
696term_setrestore({buf}, {command}) none set command to restore terminal
697term_setsize({buf}, {rows}, {cols})
698 none set the size of a terminal
699term_start({cmd} [, {options}]) Number open a terminal window and run a job
700term_wait({buf} [, {time}]) Number wait for screen to be updated
701terminalprops() Dict properties of the terminal
702test_alloc_fail({id}, {countdown}, {repeat})
703 none make memory allocation fail
704test_autochdir() none enable 'autochdir' during startup
705test_feedinput({string}) none add key sequence to input buffer
706test_garbagecollect_now() none free memory right now for testing
707test_garbagecollect_soon() none free memory soon for testing
708test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000709test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000710test_ignore_error({expr}) none ignore a specific error
Christopher Plewright20b795e2022-12-20 20:01:58 +0000711test_mswin_event({event}, {args})
712 bool generate MS-Windows event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000713test_null_blob() Blob null value for testing
714test_null_channel() Channel null value for testing
715test_null_dict() Dict null value for testing
716test_null_function() Funcref null value for testing
717test_null_job() Job null value for testing
718test_null_list() List null value for testing
719test_null_partial() Funcref null value for testing
720test_null_string() String null value for testing
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100721test_null_tuple() Tuple null value for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000722test_option_not_set({name}) none reset flag indicating option was set
723test_override({expr}, {val}) none test with Vim internal overrides
724test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000725test_setmouse({row}, {col}) none set the mouse position for testing
726test_settime({expr}) none set current time for testing
Doug Kearns9cd9e752024-04-07 17:42:17 +0200727test_srand_seed([{seed}]) none set seed for testing srand()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000728test_unknown() any unknown value for testing
729test_void() any void value for testing
730timer_info([{id}]) List information about timers
731timer_pause({id}, {pause}) none pause or unpause a timer
732timer_start({time}, {callback} [, {options}])
733 Number create a timer
734timer_stop({timer}) none stop a timer
735timer_stopall() none stop all timers
736tolower({expr}) String the String {expr} switched to lowercase
737toupper({expr}) String the String {expr} switched to uppercase
738tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
739 to chars in {tostr}
740trim({text} [, {mask} [, {dir}]])
741 String trim characters in {mask} from {text}
742trunc({expr}) Float truncate Float {expr}
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100743tuple2list({tuple}) List turn {tuple} of items into a list
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000744type({expr}) Number type of value {expr}
745typename({expr}) String representation of the type of {expr}
746undofile({name}) String undo file name for {name}
Devin J. Pohly5fee1112023-04-23 20:26:59 -0500747undotree([{buf}]) List undo file tree for buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000748uniq({list} [, {func} [, {dict}]])
749 List remove adjacent duplicates from a list
Christian Brabandt67672ef2023-04-24 21:09:54 +0100750utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
751 Number UTF-16 index of byte {idx} in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000752values({dict}) List values in {dict}
zeertzjq825cf812023-08-17 22:55:25 +0200753virtcol({expr} [, {list} [, {winid}])
754 Number or List
LemonBoy0f7a3e12022-05-26 12:10:37 +0100755 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100756virtcol2col({winid}, {lnum}, {col})
757 Number byte index of a character on screen
Doug Kearns9cd9e752024-04-07 17:42:17 +0200758visualmode([{expr}]) String last visual mode used
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000759wildmenumode() Number whether 'wildmenu' mode is active
760win_execute({id}, {command} [, {silent}])
761 String execute {command} in window {id}
762win_findbuf({bufnr}) List find windows containing {bufnr}
763win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
764win_gettype([{nr}]) String type of window {nr}
765win_gotoid({expr}) Number go to window with ID {expr}
766win_id2tabwin({expr}) List get tab and window nr from window ID
767win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000768win_move_separator({nr}) Number move window vertical separator
769win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000770win_screenpos({nr}) List get screen position of window {nr}
771win_splitmove({nr}, {target} [, {options}])
772 Number move window {nr} to split of {target}
773winbufnr({nr}) Number buffer number of window {nr}
774wincol() Number window column of the cursor
775windowsversion() String MS-Windows OS version
776winheight({nr}) Number height of window {nr}
777winlayout([{tabnr}]) List layout of windows in tab {tabnr}
778winline() Number window line of the cursor
779winnr([{expr}]) Number number of current window
780winrestcmd() String returns command to restore window sizes
781winrestview({dict}) none restore view of current window
782winsaveview() Dict save view of current window
783winwidth({nr}) Number width of window {nr}
784wordcount() Dict get byte/char/word statistics
785writefile({object}, {fname} [, {flags}])
786 Number write |Blob| or |List| of lines to file
787xor({expr}, {expr}) Number bitwise XOR
788
789==============================================================================
7902. Details *builtin-function-details*
791
792Not all functions are here, some have been moved to a help file covering the
793specific functionality.
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200794Return type specifies the type for |Vim9-script|, see |vim9-types|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000795
796abs({expr}) *abs()*
797 Return the absolute value of {expr}. When {expr} evaluates to
798 a |Float| abs() returns a |Float|. When {expr} can be
799 converted to a |Number| abs() returns a |Number|. Otherwise
800 abs() gives an error message and returns -1.
801 Examples: >
802 echo abs(1.456)
803< 1.456 >
804 echo abs(-5.456)
805< 5.456 >
806 echo abs(-4)
807< 4
808
809 Can also be used as a |method|: >
810 Compute()->abs()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200811<
812 Return type: |Number| or |Float| depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000813
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000814
815acos({expr}) *acos()*
816 Return the arc cosine of {expr} measured in radians, as a
817 |Float| in the range of [0, pi].
818 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100819 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000820 Examples: >
821 :echo acos(0)
822< 1.570796 >
823 :echo acos(-0.5)
824< 2.094395
825
826 Can also be used as a |method|: >
827 Compute()->acos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200828<
829 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000830
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000831
832add({object}, {expr}) *add()*
833 Append the item {expr} to |List| or |Blob| {object}. Returns
834 the resulting |List| or |Blob|. Examples: >
835 :let alist = add([1, 2, 3], item)
836 :call add(mylist, "woodstock")
837< Note that when {expr} is a |List| it is appended as a single
838 item. Use |extend()| to concatenate |Lists|.
839 When {object} is a |Blob| then {expr} must be a number.
840 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100841 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000842
843 Can also be used as a |method|: >
844 mylist->add(val1)->add(val2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200845<
846 Return type: list<{type}> (depending on the given |List|) or
847 |Blob|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000848
849
850and({expr}, {expr}) *and()*
851 Bitwise AND on the two arguments. The arguments are converted
852 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100853 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000854 Example: >
855 :let flag = and(bits, 0x80)
856< Can also be used as a |method|: >
857 :let flag = bits->and(0x80)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200858<
859 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000860
861
862append({lnum}, {text}) *append()*
863 When {text} is a |List|: Append each item of the |List| as a
864 text line below line {lnum} in the current buffer.
865 Otherwise append {text} as one text line below line {lnum} in
866 the current buffer.
867 Any type of item is accepted and converted to a String.
868 {lnum} can be zero to insert a line before the first one.
869 {lnum} is used like with |getline()|.
870 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000871 0 for success. When {text} is an empty list zero is returned,
872 no matter the value of {lnum}.
873 In |Vim9| script an invalid argument or negative number
874 results in an error. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000875 :let failed = append(line('$'), "# THE END")
876 :let failed = append(0, ["Chapter 1", "the beginning"])
877
878< Can also be used as a |method| after a List, the base is
879 passed as the second argument: >
880 mylist->append(lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200881<
882 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000883
884
885appendbufline({buf}, {lnum}, {text}) *appendbufline()*
886 Like |append()| but append the text in buffer {buf}.
887
888 This function works only for loaded buffers. First call
889 |bufload()| if needed.
890
891 For the use of {buf}, see |bufname()|.
892
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000893 {lnum} is the line number to append below. Note that using
894 |line()| would use the current buffer, not the one appending
895 to. Use "$" to append at the end of the buffer. Other string
896 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000897
898 On success 0 is returned, on failure 1 is returned.
899 In |Vim9| script an error is given for an invalid {lnum}.
900
901 If {buf} is not a valid buffer or {lnum} is not valid, an
902 error message is given. Example: >
903 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000904< However, when {text} is an empty list then no error is given
905 for an invalid {lnum}, since {lnum} isn't actually used.
906
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000907 Can also be used as a |method| after a List, the base is
908 passed as the second argument: >
909 mylist->appendbufline(buf, lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200910<
911 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000912
913
914argc([{winid}]) *argc()*
915 The result is the number of files in the argument list. See
916 |arglist|.
917 If {winid} is not supplied, the argument list of the current
918 window is used.
919 If {winid} is -1, the global argument list is used.
920 Otherwise {winid} specifies the window of which the argument
921 list is used: either the window number or the window ID.
922 Returns -1 if the {winid} argument is invalid.
923
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200924 Return type: |Number|
925
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000926 *argidx()*
927argidx() The result is the current index in the argument list. 0 is
928 the first file. argc() - 1 is the last one. See |arglist|.
929
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200930 Return type: |Number|
931
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000932 *arglistid()*
933arglistid([{winnr} [, {tabnr}]])
934 Return the argument list ID. This is a number which
935 identifies the argument list being used. Zero is used for the
936 global argument list. See |arglist|.
937 Returns -1 if the arguments are invalid.
938
939 Without arguments use the current window.
940 With {winnr} only use this window in the current tab page.
941 With {winnr} and {tabnr} use the window in the specified tab
942 page.
943 {winnr} can be the window number or the |window-ID|.
944
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200945 Return type: |Number|
946
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000947 *argv()*
948argv([{nr} [, {winid}]])
949 The result is the {nr}th file in the argument list. See
950 |arglist|. "argv(0)" is the first one. Example: >
951 :let i = 0
952 :while i < argc()
953 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000954 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000955 : let i = i + 1
956 :endwhile
957< Without the {nr} argument, or when {nr} is -1, a |List| with
958 the whole |arglist| is returned.
959
960 The {winid} argument specifies the window ID, see |argc()|.
961 For the Vim command line arguments see |v:argv|.
962
Bram Moolenaar016188f2022-06-06 20:52:59 +0100963 Returns an empty string if {nr}th argument is not present in
964 the argument list. Returns an empty List if the {winid}
965 argument is invalid.
966
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200967 Return type: |String|
968
969
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000970asin({expr}) *asin()*
971 Return the arc sine of {expr} measured in radians, as a |Float|
972 in the range of [-pi/2, pi/2].
973 {expr} must evaluate to a |Float| or a |Number| in the range
974 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100975 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
976 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000977 Examples: >
978 :echo asin(0.8)
979< 0.927295 >
980 :echo asin(-0.5)
981< -0.523599
982
983 Can also be used as a |method|: >
984 Compute()->asin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200985<
986 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000987
988assert_ functions are documented here: |assert-functions-details|
989
990
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000991atan({expr}) *atan()*
992 Return the principal value of the arc tangent of {expr}, in
993 the range [-pi/2, +pi/2] radians, as a |Float|.
994 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100995 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000996 Examples: >
997 :echo atan(100)
998< 1.560797 >
999 :echo atan(-4.01)
1000< -1.326405
1001
1002 Can also be used as a |method|: >
1003 Compute()->atan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001004<
1005 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001006
1007
1008atan2({expr1}, {expr2}) *atan2()*
1009 Return the arc tangent of {expr1} / {expr2}, measured in
1010 radians, as a |Float| in the range [-pi, pi].
1011 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001012 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
1013 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001014 Examples: >
1015 :echo atan2(-1, 1)
1016< -0.785398 >
1017 :echo atan2(1, -1)
1018< 2.356194
1019
1020 Can also be used as a |method|: >
1021 Compute()->atan2(1)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001022<
1023 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001024
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001025
1026autocmd_add({acmds}) *autocmd_add()*
1027 Adds a List of autocmds and autocmd groups.
1028
1029 The {acmds} argument is a List where each item is a Dict with
1030 the following optional items:
1031 bufnr buffer number to add a buffer-local autocmd.
1032 If this item is specified, then the "pattern"
1033 item is ignored.
1034 cmd Ex command to execute for this autocmd event
1035 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +01001036 This can be either a String with a single
1037 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001038 group autocmd group name. Refer to |autocmd-groups|.
1039 If this group doesn't exist then it is
1040 created. If not specified or empty, then the
1041 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001042 nested boolean flag, set to v:true to add a nested
1043 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +01001044 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001045 which executes only once. Refer to
1046 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001047 pattern autocmd pattern string. Refer to
1048 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +01001049 present, then this item is ignored. This can
1050 be a String with a single pattern or a List of
1051 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001052 replace boolean flag, set to v:true to remove all the
1053 commands associated with the specified autocmd
1054 event and group and add the {cmd}. This is
1055 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +01001056 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001057
1058 Returns v:true on success and v:false on failure.
1059 Examples: >
1060 " Create a buffer-local autocmd for buffer 5
1061 let acmd = {}
1062 let acmd.group = 'MyGroup'
1063 let acmd.event = 'BufEnter'
1064 let acmd.bufnr = 5
1065 let acmd.cmd = 'call BufEnterFunc()'
1066 call autocmd_add([acmd])
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00001067<
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001068 Can also be used as a |method|: >
1069 GetAutocmdList()->autocmd_add()
1070<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001071 Return type: |vim9-boolean|
1072
1073
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001074autocmd_delete({acmds}) *autocmd_delete()*
1075 Deletes a List of autocmds and autocmd groups.
1076
1077 The {acmds} argument is a List where each item is a Dict with
1078 the following optional items:
1079 bufnr buffer number to delete a buffer-local autocmd.
1080 If this item is specified, then the "pattern"
1081 item is ignored.
1082 cmd Ex command for this autocmd event
1083 event autocmd event name. Refer to |autocmd-events|.
1084 If '*' then all the autocmd events in this
1085 group are deleted.
1086 group autocmd group name. Refer to |autocmd-groups|.
1087 If not specified or empty, then the default
1088 group is used.
1089 nested set to v:true for a nested autocmd.
1090 Refer to |autocmd-nested|.
1091 once set to v:true for an autocmd which executes
1092 only once. Refer to |autocmd-once|.
1093 pattern autocmd pattern string. Refer to
1094 |autocmd-patterns|. If "bufnr" item is
1095 present, then this item is ignored.
1096
1097 If only {group} is specified in a {acmds} entry and {event},
1098 {pattern} and {cmd} are not specified, then that autocmd group
1099 is deleted.
1100
Bram Moolenaar016188f2022-06-06 20:52:59 +01001101 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001102 Examples: >
1103 " :autocmd! BufLeave *.vim
1104 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1105 call autocmd_delete([acmd]})
1106 " :autocmd! MyGroup1 BufLeave
1107 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1108 call autocmd_delete([acmd])
1109 " :autocmd! MyGroup2 BufEnter *.c
1110 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1111 \ pattern: '*.c'}
1112 " :autocmd! MyGroup2 * *.c
1113 let acmd = #{group: 'MyGroup2', event: '*',
1114 \ pattern: '*.c'}
1115 call autocmd_delete([acmd])
1116 " :autocmd! MyGroup3
1117 let acmd = #{group: 'MyGroup3'}
1118 call autocmd_delete([acmd])
1119<
1120 Can also be used as a |method|: >
1121 GetAutocmdList()->autocmd_delete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001122<
1123 Return type: |vim9-boolean|
1124
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001125
1126autocmd_get([{opts}]) *autocmd_get()*
1127 Returns a |List| of autocmds. If {opts} is not supplied, then
1128 returns the autocmds for all the events in all the groups.
1129
1130 The optional {opts} Dict argument supports the following
1131 items:
1132 group Autocmd group name. If specified, returns only
1133 the autocmds defined in this group. If the
1134 specified group doesn't exist, results in an
1135 error message. If set to an empty string,
1136 then the default autocmd group is used.
1137 event Autocmd event name. If specified, returns only
1138 the autocmds defined for this event. If set
1139 to "*", then returns autocmds for all the
1140 events. If the specified event doesn't exist,
1141 results in an error message.
1142 pattern Autocmd pattern. If specified, returns only
1143 the autocmds defined for this pattern.
1144 A combination of the above three times can be supplied in
1145 {opts}.
1146
1147 Each Dict in the returned List contains the following items:
1148 bufnr For buffer-local autocmds, buffer number where
1149 the autocmd is defined.
1150 cmd Command executed for this autocmd.
1151 event Autocmd event name.
1152 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001153 nested Boolean flag, set to v:true for a nested
1154 autocmd. See |autocmd-nested|.
1155 once Boolean flag, set to v:true, if the autocmd
1156 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001157 pattern Autocmd pattern. For a buffer-local
1158 autocmd, this will be of the form "<buffer=n>".
1159 If there are multiple commands for an autocmd event in a
1160 group, then separate items are returned for each command.
1161
Bram Moolenaar016188f2022-06-06 20:52:59 +01001162 Returns an empty List if an autocmd with the specified group
1163 or event or pattern is not found.
1164
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001165 Examples: >
1166 " :autocmd MyGroup
1167 echo autocmd_get(#{group: 'Mygroup'})
1168 " :autocmd G BufUnload
1169 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1170 " :autocmd G * *.ts
1171 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1172 echo autocmd_get(acmd)
1173 " :autocmd Syntax
1174 echo autocmd_get(#{event: 'Syntax'})
1175 " :autocmd G BufEnter *.ts
1176 let acmd = #{group: 'G', event: 'BufEnter',
1177 \ pattern: '*.ts'}
1178 echo autocmd_get(acmd)
1179<
1180 Can also be used as a |method|: >
1181 Getopts()->autocmd_get()
1182<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001183 Return type: list<dict<any>>
1184
1185
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001186balloon_gettext() *balloon_gettext()*
1187 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001188 not used for the List. Returns an empty string if balloon
1189 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001190
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001191 Return type: |String|
1192
1193
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001194balloon_show({expr}) *balloon_show()*
1195 Show {expr} inside the balloon. For the GUI {expr} is used as
1196 a string. For a terminal {expr} can be a list, which contains
1197 the lines of the balloon. If {expr} is not a list it will be
1198 split with |balloon_split()|.
1199 If {expr} is an empty string any existing balloon is removed.
1200
1201 Example: >
1202 func GetBalloonContent()
1203 " ... initiate getting the content
1204 return ''
1205 endfunc
1206 set balloonexpr=GetBalloonContent()
1207
1208 func BalloonCallback(result)
1209 call balloon_show(a:result)
1210 endfunc
1211< Can also be used as a |method|: >
1212 GetText()->balloon_show()
1213<
1214 The intended use is that fetching the content of the balloon
1215 is initiated from 'balloonexpr'. It will invoke an
1216 asynchronous method, in which a callback invokes
1217 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001218 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001219
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001220 When showing a balloon is not possible then nothing happens,
1221 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001222 {only available when compiled with the |+balloon_eval| or
1223 |+balloon_eval_term| feature}
1224
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001225 Return type: |Number|
1226
1227
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001228balloon_split({msg}) *balloon_split()*
1229 Split String {msg} into lines to be displayed in a balloon.
1230 The splits are made for the current window size and optimize
1231 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001232 Returns a |List| with the split lines. Returns an empty List
1233 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001234 Can also be used as a |method|: >
1235 GetText()->balloon_split()->balloon_show()
1236
1237< {only available when compiled with the |+balloon_eval_term|
1238 feature}
1239
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001240 Return type: list<any> or list<string>
1241
h-easte80f3452025-01-02 10:40:29 +01001242base64_decode({string}) *base64_decode()*
1243 Return a Blob containing the bytes decoded from the base64
1244 encoded characters in {string}.
1245
1246 The {string} argument should contain only base64-encoded
1247 characters and should have a length that is a multiple of 4.
1248
1249 Returns an empty blob on error.
1250
1251 Examples: >
1252 " Write the decoded contents to a binary file
1253 call writefile(base64_decode(s), 'tools.bmp')
1254 " Decode a base64-encoded string
Maxim Kim6472e582025-01-15 18:31:05 +01001255 echo blob2str(base64_decode(encodedstr))
h-easte80f3452025-01-02 10:40:29 +01001256<
1257 Can also be used as a |method|: >
1258 GetEncodedString()->base64_decode()
1259<
1260 Return type: |Blob|
1261
1262
1263base64_encode({blob}) *base64_encode()*
1264 Return a base64-encoded String representing the bytes in
1265 {blob}. The base64 alphabet defined in RFC 4648 is used.
1266
1267 Examples: >
1268 " Encode the contents of a binary file
1269 echo base64_encode(readblob('somefile.bin'))
1270 " Encode a string
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001271 echo base64_encode(str2blob([somestr]))
h-easte80f3452025-01-02 10:40:29 +01001272<
1273 Can also be used as a |method|: >
1274 GetBinaryData()->base64_encode()
1275<
1276 Return type: |String|
1277
1278
Christ van Willegence0ef912024-06-20 23:41:59 +02001279bindtextdomain({package}, {path}) *bindtextdomain()*
1280 Bind a specific {package} to a {path} so that the
1281 |gettext()| function can be used to get language-specific
1282 translations for a package. {path} is the directory name
h-east52e7cc22024-07-28 17:03:29 +02001283 for the translations. See |package-translation|.
Christ van Willegence0ef912024-06-20 23:41:59 +02001284
Christ van Willegen8252ef12024-07-11 21:36:21 +02001285 Returns v:true on success and v:false on failure (out of
1286 memory).
1287
1288 Return type: |vim9-boolean|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001289
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001290blob2list({blob}) *blob2list()*
1291 Return a List containing the number value of each byte in Blob
1292 {blob}. Examples: >
1293 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1294 blob2list(0z) returns []
1295< Returns an empty List on error. |list2blob()| does the
1296 opposite.
1297
1298 Can also be used as a |method|: >
1299 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001300<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001301 Return type: list<any> or list<number>
1302
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001303
1304blob2str({blob} [, {options}]) *blob2str()*
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001305 Return a List of Strings in the current 'encoding' by
1306 converting the bytes in {blob} into characters.
1307
1308 Each <NL> byte in the blob is interpreted as the end of a
1309 string and a new list item is added. Each <NUL> byte in the
1310 blob is converted into a <NL> character.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001311
1312 If {options} is not supplied, the current 'encoding' value is
1313 used to decode the bytes in {blob}.
1314
1315 The argument {options} is a |Dict| and supports the following
1316 items:
1317 encoding Decode the bytes in {blob} using this
1318 encoding. The value is a |String|. See
Bakudankunb3854bf2025-02-23 20:29:21 +01001319 |encoding-names| for the supported values
1320 (plus the special value "none").
Christian Brabandtd5afc742025-03-18 20:55:42 +01001321 *E1515* *E1516*
Bakudankunb3854bf2025-02-23 20:29:21 +01001322 When current 'encoding' is "utf-8", an error is given and an
1323 empty List is returned if an invalid byte sequence is
1324 encountered in {blob}. To suppress this validation and get
1325 potentially invalid string, set "encoding" in {options} to
1326 "none".
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001327
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001328 Returns an empty List if blob is empty.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001329
1330 See also |str2blob()|
1331
1332 Examples: >
Hirohito Higashi932a5352025-03-23 10:20:20 +01001333 blob2str(0z6162) returns ['ab']
1334 blob2str(0zC2ABC2BB) returns ['«»']
1335 blob2str(0z610A62) returns ['a', 'b']
1336 blob2str(0z610062) returns ['a\nb']
1337 blob2str(0zABBB, {'encoding': 'latin1'}) returns ['«»']
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001338<
1339 Can also be used as a |method|: >
1340 GetBlob()->blob2str()
1341<
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001342 Return type: list<string>
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001343
1344
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001345 *browse()*
1346browse({save}, {title}, {initdir}, {default})
1347 Put up a file requester. This only works when "has("browse")"
1348 returns |TRUE| (only in some GUI versions).
1349 The input fields are:
1350 {save} when |TRUE|, select file to write
1351 {title} title for the requester
1352 {initdir} directory to start browsing in
1353 {default} default file name
1354 An empty string is returned when the "Cancel" button is hit,
1355 something went wrong, or browsing is not possible.
1356
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001357 Return type: |String|
1358
1359
1360browsedir({title}, {initdir}) *browsedir()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001361 Put up a directory requester. This only works when
1362 "has("browse")" returns |TRUE| (only in some GUI versions).
1363 On systems where a directory browser is not supported a file
1364 browser is used. In that case: select a file in the directory
1365 to be used.
1366 The input fields are:
1367 {title} title for the requester
1368 {initdir} directory to start browsing in
1369 When the "Cancel" button is hit, something went wrong, or
1370 browsing is not possible, an empty string is returned.
1371
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001372 Return type: |String|
1373
1374
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001375bufadd({name}) *bufadd()*
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001376 Add a buffer to the buffer list with name {name} (must be a
1377 String).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001378 If a buffer for file {name} already exists, return that buffer
1379 number. Otherwise return the buffer number of the newly
1380 created buffer. When {name} is an empty string then a new
1381 buffer is always created.
1382 The buffer will not have 'buflisted' set and not be loaded
1383 yet. To add some text to the buffer use this: >
1384 let bufnr = bufadd('someName')
1385 call bufload(bufnr)
1386 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001387< Returns 0 on error.
1388 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001389 let bufnr = 'somename'->bufadd()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001390<
1391 Return type: |Number|
1392
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001393
1394bufexists({buf}) *bufexists()*
1395 The result is a Number, which is |TRUE| if a buffer called
1396 {buf} exists.
1397 If the {buf} argument is a number, buffer numbers are used.
1398 Number zero is the alternate buffer for the current window.
1399
1400 If the {buf} argument is a string it must match a buffer name
1401 exactly. The name can be:
1402 - Relative to the current directory.
1403 - A full path.
1404 - The name of a buffer with 'buftype' set to "nofile".
1405 - A URL name.
1406 Unlisted buffers will be found.
1407 Note that help files are listed by their short name in the
1408 output of |:buffers|, but bufexists() requires using their
1409 long name to be able to find them.
1410 bufexists() may report a buffer exists, but to use the name
1411 with a |:buffer| command you may need to use |expand()|. Esp
1412 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1413 Use "bufexists(0)" to test for the existence of an alternate
1414 file name.
1415
1416 Can also be used as a |method|: >
1417 let exists = 'somename'->bufexists()
1418<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001419 Return type: |Number|
1420
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001421 Obsolete name: buffer_exists(). *buffer_exists()*
1422
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001423
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001424buflisted({buf}) *buflisted()*
1425 The result is a Number, which is |TRUE| if a buffer called
1426 {buf} exists and is listed (has the 'buflisted' option set).
1427 The {buf} argument is used like with |bufexists()|.
1428
1429 Can also be used as a |method|: >
1430 let listed = 'somename'->buflisted()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001431<
1432 Return type: |Number|
1433
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001434
1435bufload({buf}) *bufload()*
1436 Ensure the buffer {buf} is loaded. When the buffer name
1437 refers to an existing file then the file is read. Otherwise
1438 the buffer will be empty. If the buffer was already loaded
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001439 then there is no change. If the buffer is not related to a
Daniel Steinbergc2bd2052023-08-09 12:10:59 -04001440 file then no file is read (e.g., when 'buftype' is "nofile").
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001441 If there is an existing swap file for the file of the buffer,
1442 there will be no dialog, the buffer will be loaded anyway.
1443 The {buf} argument is used like with |bufexists()|.
1444
1445 Can also be used as a |method|: >
1446 eval 'somename'->bufload()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001447<
1448 Return type: |Number|
1449
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001450
1451bufloaded({buf}) *bufloaded()*
1452 The result is a Number, which is |TRUE| if a buffer called
1453 {buf} exists and is loaded (shown in a window or hidden).
1454 The {buf} argument is used like with |bufexists()|.
1455
1456 Can also be used as a |method|: >
1457 let loaded = 'somename'->bufloaded()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001458<
1459 Return type: |Number|
1460
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001461
1462bufname([{buf}]) *bufname()*
1463 The result is the name of a buffer. Mostly as it is displayed
1464 by the `:ls` command, but not using special names such as
1465 "[No Name]".
1466 If {buf} is omitted the current buffer is used.
1467 If {buf} is a Number, that buffer number's name is given.
1468 Number zero is the alternate buffer for the current window.
1469 If {buf} is a String, it is used as a |file-pattern| to match
1470 with the buffer names. This is always done like 'magic' is
1471 set and 'cpoptions' is empty. When there is more than one
1472 match an empty string is returned.
1473 "" or "%" can be used for the current buffer, "#" for the
1474 alternate buffer.
1475 A full match is preferred, otherwise a match at the start, end
1476 or middle of the buffer name is accepted. If you only want a
1477 full match then put "^" at the start and "$" at the end of the
1478 pattern.
1479 Listed buffers are found first. If there is a single match
1480 with a listed buffer, that one is returned. Next unlisted
1481 buffers are searched for.
1482 If the {buf} is a String, but you want to use it as a buffer
1483 number, force it to be a Number by adding zero to it: >
1484 :echo bufname("3" + 0)
1485< Can also be used as a |method|: >
1486 echo bufnr->bufname()
1487
1488< If the buffer doesn't exist, or doesn't have a name, an empty
1489 string is returned. >
1490 bufname("#") alternate buffer name
1491 bufname(3) name of buffer 3
1492 bufname("%") name of current buffer
1493 bufname("file2") name of buffer where "file2" matches.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001494<
1495 Return type: |String|
1496 *buffer_name()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001497 Obsolete name: buffer_name().
1498
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001499
1500bufnr([{buf} [, {create}]]) *bufnr()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001501 The result is the number of a buffer, as it is displayed by
1502 the `:ls` command. For the use of {buf}, see |bufname()|
1503 above.
1504
1505 If the buffer doesn't exist, -1 is returned. Or, if the
1506 {create} argument is present and TRUE, a new, unlisted,
1507 buffer is created and its number is returned. Example: >
1508 let newbuf = bufnr('Scratch001', 1)
1509< Using an empty name uses the current buffer. To create a new
1510 buffer with an empty name use |bufadd()|.
1511
1512 bufnr("$") is the last buffer: >
1513 :let last_buffer = bufnr("$")
1514< The result is a Number, which is the highest buffer number
1515 of existing buffers. Note that not all buffers with a smaller
1516 number necessarily exist, because ":bwipeout" may have removed
1517 them. Use bufexists() to test for the existence of a buffer.
1518
1519 Can also be used as a |method|: >
1520 echo bufref->bufnr()
1521<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001522 Return type: |Number|
1523
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001524 Obsolete name: buffer_number(). *buffer_number()*
1525 *last_buffer_nr()*
1526 Obsolete name for bufnr("$"): last_buffer_nr().
1527
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001528
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001529bufwinid({buf}) *bufwinid()*
1530 The result is a Number, which is the |window-ID| of the first
1531 window associated with buffer {buf}. For the use of {buf},
1532 see |bufname()| above. If buffer {buf} doesn't exist or
1533 there is no such window, -1 is returned. Example: >
1534
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001535 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001536<
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001537 Only deals with the current tab page. See |win_findbuf()| for
1538 finding more.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001539
1540 Can also be used as a |method|: >
1541 FindBuffer()->bufwinid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001542<
1543 Return type: |Number|
1544
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001545
1546bufwinnr({buf}) *bufwinnr()*
1547 Like |bufwinid()| but return the window number instead of the
1548 |window-ID|.
1549 If buffer {buf} doesn't exist or there is no such window, -1
1550 is returned. Example: >
1551
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001552 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001553
1554< The number can be used with |CTRL-W_w| and ":wincmd w"
1555 |:wincmd|.
1556
1557 Can also be used as a |method|: >
1558 FindBuffer()->bufwinnr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001559<
1560 Return type: |Number|
1561
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001562
1563byte2line({byte}) *byte2line()*
1564 Return the line number that contains the character at byte
1565 count {byte} in the current buffer. This includes the
1566 end-of-line character, depending on the 'fileformat' option
1567 for the current buffer. The first character has byte count
1568 one.
1569 Also see |line2byte()|, |go| and |:goto|.
1570
Bram Moolenaar016188f2022-06-06 20:52:59 +01001571 Returns -1 if the {byte} value is invalid.
1572
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001573 Can also be used as a |method|: >
1574 GetOffset()->byte2line()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001575<
1576 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001577
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001578 {not available when compiled without the |+byte_offset|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001579 feature}
1580
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001581
Christian Brabandt67672ef2023-04-24 21:09:54 +01001582byteidx({expr}, {nr} [, {utf16}]) *byteidx()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001583 Return byte index of the {nr}'th character in the String
1584 {expr}. Use zero for the first character, it then returns
1585 zero.
1586 If there are no multibyte characters the returned value is
1587 equal to {nr}.
1588 Composing characters are not counted separately, their byte
1589 length is added to the preceding base character. See
1590 |byteidxcomp()| below for counting composing characters
1591 separately.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001592 When {utf16} is present and TRUE, {nr} is used as the UTF-16
1593 index in the String {expr} instead of as the character index.
1594 The UTF-16 index is the index in the string when it is encoded
1595 with 16-bit words. If the specified UTF-16 index is in the
1596 middle of a character (e.g. in a 4-byte character), then the
1597 byte index of the first byte in the character is returned.
1598 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001599 Example : >
1600 echo matchstr(str, ".", byteidx(str, 3))
1601< will display the fourth character. Another way to do the
1602 same: >
1603 let s = strpart(str, byteidx(str, 3))
1604 echo strpart(s, 0, byteidx(s, 1))
1605< Also see |strgetchar()| and |strcharpart()|.
1606
1607 If there are less than {nr} characters -1 is returned.
1608 If there are exactly {nr} characters the length of the string
1609 in bytes is returned.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001610 See |charidx()| and |utf16idx()| for getting the character and
1611 UTF-16 index respectively from the byte index.
1612 Examples: >
1613 echo byteidx('a😊😊', 2) returns 5
1614 echo byteidx('a😊😊', 2, 1) returns 1
1615 echo byteidx('a😊😊', 3, 1) returns 5
1616<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001617 Can also be used as a |method|: >
1618 GetName()->byteidx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001619<
1620 Return type: |Number|
1621
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001622
Christian Brabandt67672ef2023-04-24 21:09:54 +01001623byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001624 Like byteidx(), except that a composing character is counted
1625 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001626 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001627 echo byteidx(s, 1)
1628 echo byteidxcomp(s, 1)
1629 echo byteidxcomp(s, 2)
1630< The first and third echo result in 3 ('e' plus composing
1631 character is 3 bytes), the second echo results in 1 ('e' is
1632 one byte).
1633 Only works differently from byteidx() when 'encoding' is set
1634 to a Unicode encoding.
1635
1636 Can also be used as a |method|: >
1637 GetName()->byteidxcomp(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001638<
1639 Return type: |Number|
1640
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001641
1642call({func}, {arglist} [, {dict}]) *call()* *E699*
1643 Call function {func} with the items in |List| {arglist} as
1644 arguments.
1645 {func} can either be a |Funcref| or the name of a function.
1646 a:firstline and a:lastline are set to the cursor line.
1647 Returns the return value of the called function.
1648 {dict} is for functions with the "dict" attribute. It will be
1649 used to set the local variable "self". |Dictionary-function|
1650
1651 Can also be used as a |method|: >
1652 GetFunc()->call([arg, arg], dict)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001653<
1654 Return type: any, depending on {func}
1655
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001656
1657ceil({expr}) *ceil()*
1658 Return the smallest integral value greater than or equal to
1659 {expr} as a |Float| (round up).
1660 {expr} must evaluate to a |Float| or a |Number|.
1661 Examples: >
1662 echo ceil(1.456)
1663< 2.0 >
1664 echo ceil(-5.456)
1665< -5.0 >
1666 echo ceil(4.0)
1667< 4.0
1668
Bram Moolenaar016188f2022-06-06 20:52:59 +01001669 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1670
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001671 Can also be used as a |method|: >
1672 Compute()->ceil()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001673<
1674 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001675
1676
1677ch_ functions are documented here: |channel-functions-details|
1678
1679
1680changenr() *changenr()*
1681 Return the number of the most recent change. This is the same
1682 number as what is displayed with |:undolist| and can be used
1683 with the |:undo| command.
1684 When a change was made it is the number of that change. After
1685 redo it is the number of the redone change. After undo it is
1686 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001687 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001688
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001689 Return type: |Number|
1690
1691
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001692char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001693 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001694 Examples: >
1695 char2nr(" ") returns 32
1696 char2nr("ABC") returns 65
1697< When {utf8} is omitted or zero, the current 'encoding' is used.
1698 Example for "utf-8": >
1699 char2nr("á") returns 225
1700 char2nr("á"[0]) returns 195
1701< When {utf8} is TRUE, always treat as UTF-8 characters.
1702 A combining character is a separate character.
1703 |nr2char()| does the opposite.
1704 To turn a string into a list of character numbers: >
1705 let str = "ABC"
1706 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1707< Result: [65, 66, 67]
1708
Bram Moolenaar016188f2022-06-06 20:52:59 +01001709 Returns 0 if {string} is not a |String|.
1710
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001711 Can also be used as a |method|: >
1712 GetChar()->char2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001713<
1714 Return type: |Number|
1715
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001716
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001717charclass({string}) *charclass()*
1718 Return the character class of the first character in {string}.
1719 The character class is one of:
1720 0 blank
1721 1 punctuation
Christian Brabandtb5e7da12024-11-01 09:33:00 +01001722 2 word character (depends on 'iskeyword')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001723 3 emoji
1724 other specific Unicode class
1725 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001726 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001727
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001728 Return type: |Number|
1729
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001730
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001731charcol({expr} [, {winid}]) *charcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001732 Same as |col()| but returns the character index of the column
1733 position given with {expr} instead of the byte position.
1734
1735 Example:
1736 With the cursor on '세' in line 5 with text "여보세요": >
1737 charcol('.') returns 3
1738 col('.') returns 7
1739
1740< Can also be used as a |method|: >
1741 GetPos()->col()
1742<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001743 Return type: |Number|
1744
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001745 *charidx()*
Christian Brabandt67672ef2023-04-24 21:09:54 +01001746charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001747 Return the character index of the byte at {idx} in {string}.
1748 The index of the first character is zero.
1749 If there are no multibyte characters the returned value is
1750 equal to {idx}.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001751
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001752 When {countcc} is omitted or |FALSE|, then composing characters
Christian Brabandt67672ef2023-04-24 21:09:54 +01001753 are not counted separately, their byte length is added to the
1754 preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001755 When {countcc} is |TRUE|, then composing characters are
1756 counted as separate characters.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001757
1758 When {utf16} is present and TRUE, {idx} is used as the UTF-16
1759 index in the String {expr} instead of as the byte index.
1760
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +01001761 Returns -1 if the arguments are invalid or if there are less
1762 than {idx} bytes. If there are exactly {idx} bytes the length
1763 of the string in characters is returned.
1764
1765 An error is given and -1 is returned if the first argument is
1766 not a string, the second argument is not a number or when the
1767 third argument is present and is not zero or one.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001768
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001769 See |byteidx()| and |byteidxcomp()| for getting the byte index
Christian Brabandt67672ef2023-04-24 21:09:54 +01001770 from the character index and |utf16idx()| for getting the
1771 UTF-16 index from the character index.
1772 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001773 Examples: >
1774 echo charidx('áb́ć', 3) returns 1
1775 echo charidx('áb́ć', 6, 1) returns 4
1776 echo charidx('áb́ć', 16) returns -1
Christian Brabandt67672ef2023-04-24 21:09:54 +01001777 echo charidx('a😊😊', 4, 0, 1) returns 2
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001778<
1779 Can also be used as a |method|: >
1780 GetName()->charidx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001781<
1782 Return type: |Number|
1783
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001784
1785chdir({dir}) *chdir()*
1786 Change the current working directory to {dir}. The scope of
1787 the directory change depends on the directory of the current
1788 window:
1789 - If the current window has a window-local directory
1790 (|:lcd|), then changes the window local directory.
1791 - Otherwise, if the current tabpage has a local
1792 directory (|:tcd|) then changes the tabpage local
1793 directory.
1794 - Otherwise, changes the global directory.
1795 {dir} must be a String.
1796 If successful, returns the previous working directory. Pass
1797 this to another chdir() to restore the directory.
1798 On failure, returns an empty string.
1799
1800 Example: >
1801 let save_dir = chdir(newdir)
1802 if save_dir != ""
1803 " ... do some work
1804 call chdir(save_dir)
1805 endif
1806
1807< Can also be used as a |method|: >
1808 GetDir()->chdir()
1809<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001810 Return type: |String|
1811
1812
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001813cindent({lnum}) *cindent()*
1814 Get the amount of indent for line {lnum} according the C
1815 indenting rules, as with 'cindent'.
1816 The indent is counted in spaces, the value of 'tabstop' is
1817 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001818 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001819 See |C-indenting|.
1820
1821 Can also be used as a |method|: >
1822 GetLnum()->cindent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001823<
1824 Return type: |Number|
1825
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001826
1827clearmatches([{win}]) *clearmatches()*
1828 Clears all matches previously defined for the current window
1829 by |matchadd()| and the |:match| commands.
1830 If {win} is specified, use the window with this number or
1831 window ID instead of the current window.
1832
1833 Can also be used as a |method|: >
1834 GetWin()->clearmatches()
1835<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001836 Return type: |Number|
1837
1838
Girish Palya5c3d1e32025-04-22 19:52:16 +02001839cmdcomplete_info() *cmdcomplete_info()*
Girish Palya92f68e22025-04-21 11:12:41 +02001840 Returns a |Dictionary| with information about cmdline
1841 completion. See |cmdline-completion|.
1842 The items are:
1843 cmdline_orig The original command-line string before
1844 completion began.
1845 pum_visible |TRUE| if popup menu is visible.
1846 See |pumvisible()|.
1847 matches List of all completion candidates. Each item
1848 is a string.
1849 selected Selected item index. First index is zero.
1850 Index is -1 if no item is selected (showing
1851 typed text only, or the last completion after
1852 no item is selected when using the <Up> or
1853 <Down> keys)
1854
1855 Returns an empty |Dictionary| if no completion was attempted,
1856 if there was only one candidate and it was fully completed, or
1857 if an error occurred.
1858
1859 Return type: dict<any>
1860
1861
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001862col({expr} [, {winid}]) *col()*
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001863 The result is a Number, which is the byte index of the column
zeertzjq02f3eba2024-06-12 20:45:24 +02001864 position given with {expr}.
1865 For accepted positions see |getpos()|.
zeertzjqd353d272024-06-13 23:00:25 +08001866 When {expr} is "$", it means the end of the cursor line, so
1867 the result is the number of bytes in the cursor line plus one.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001868 Additionally {expr} can be [lnum, col]: a |List| with the line
1869 and column number. Most useful when the column is "$", to get
1870 the last column of a specific line. When "lnum" or "col" is
1871 out of range then col() returns zero.
zeertzjq02f3eba2024-06-12 20:45:24 +02001872
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001873 With the optional {winid} argument the values are obtained for
1874 that window instead of the current window.
zeertzjq02f3eba2024-06-12 20:45:24 +02001875
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001876 To get the line number use |line()|. To get both use
1877 |getpos()|.
1878 For the screen column position use |virtcol()|. For the
1879 character position use |charcol()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02001880
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001881 Note that only marks in the current file can be used.
zeertzjq02f3eba2024-06-12 20:45:24 +02001882
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001883 Examples: >
1884 col(".") column of cursor
1885 col("$") length of cursor line plus one
1886 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001887 col("'" .. markname) column of mark markname
zeertzjq02f3eba2024-06-12 20:45:24 +02001888<
1889 The first column is 1. Returns 0 if {expr} is invalid or when
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001890 the window with ID {winid} is not found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001891 For an uppercase mark the column may actually be in another
1892 buffer.
1893 For the cursor position, when 'virtualedit' is active, the
1894 column is one higher if the cursor is after the end of the
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01001895 line. Also, when using a <Cmd> mapping the cursor isn't
1896 moved, this can be used to obtain the column in Insert mode: >
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001897 :imap <F2> <Cmd>echowin col(".")<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001898
1899< Can also be used as a |method|: >
1900 GetPos()->col()
1901<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001902 Return type: |Number|
1903
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001904
1905complete({startcol}, {matches}) *complete()* *E785*
1906 Set the matches for Insert mode completion.
1907 Can only be used in Insert mode. You need to use a mapping
1908 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1909 or with an expression mapping.
1910 {startcol} is the byte offset in the line where the completed
1911 text start. The text up to the cursor is the original text
1912 that will be replaced by the matches. Use col('.') for an
1913 empty string. "col('.') - 1" will replace one character by a
1914 match.
1915 {matches} must be a |List|. Each |List| item is one match.
1916 See |complete-items| for the kind of items that are possible.
1917 "longest" in 'completeopt' is ignored.
1918 Note that the after calling this function you need to avoid
1919 inserting anything that would cause completion to stop.
1920 The match can be selected with CTRL-N and CTRL-P as usual with
1921 Insert mode completion. The popup menu will appear if
1922 specified, see |ins-completion-menu|.
1923 Example: >
1924 inoremap <F5> <C-R>=ListMonths()<CR>
1925
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001926 func ListMonths()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001927 call complete(col('.'), ['January', 'February', 'March',
1928 \ 'April', 'May', 'June', 'July', 'August', 'September',
1929 \ 'October', 'November', 'December'])
1930 return ''
1931 endfunc
1932< This isn't very useful, but it shows how it works. Note that
1933 an empty string is returned to avoid a zero being inserted.
1934
1935 Can also be used as a |method|, the base is passed as the
1936 second argument: >
1937 GetMatches()->complete(col('.'))
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001938<
1939 Return type: |Number|
1940
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001941
1942complete_add({expr}) *complete_add()*
1943 Add {expr} to the list of matches. Only to be used by the
1944 function specified with the 'completefunc' option.
1945 Returns 0 for failure (empty string or out of memory),
1946 1 when the match was added, 2 when the match was already in
1947 the list.
1948 See |complete-functions| for an explanation of {expr}. It is
1949 the same as one item in the list that 'omnifunc' would return.
1950
1951 Can also be used as a |method|: >
1952 GetMoreMatches()->complete_add()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001953<
1954 Return type: |Number|
1955
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001956
1957complete_check() *complete_check()*
1958 Check for a key typed while looking for completion matches.
1959 This is to be used when looking for matches takes some time.
1960 Returns |TRUE| when searching for matches is to be aborted,
1961 zero otherwise.
1962 Only to be used by the function specified with the
1963 'completefunc' option.
1964
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001965 Return type: |Number|
1966
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001967
1968complete_info([{what}]) *complete_info()*
1969 Returns a |Dictionary| with information about Insert mode
1970 completion. See |ins-completion|.
1971 The items are:
1972 mode Current completion mode name string.
1973 See |complete_info_mode| for the values.
1974 pum_visible |TRUE| if popup menu is visible.
1975 See |pumvisible()|.
glepnird4088ed2024-12-31 10:55:22 +01001976 items List of all completion candidates. Each item
1977 is a dictionary containing the entries "word",
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001978 "abbr", "menu", "kind", "info" and "user_data".
1979 See |complete-items|.
glepnird4088ed2024-12-31 10:55:22 +01001980 matches Same as "items", but only returns items that
1981 are matching current query. If both "matches"
1982 and "items" are in "what", the returned list
1983 will still be named "items", but each item
1984 will have an additional "match" field.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001985 selected Selected item index. First index is zero.
1986 Index is -1 if no item is selected (showing
1987 typed text only, or the last completion after
1988 no item is selected when using the <Up> or
1989 <Down> keys)
glepnir037b0282025-01-16 14:37:44 +01001990 completed Return a dictionary containing the entries of
1991 the currently selected index item.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001992
1993 *complete_info_mode*
1994 mode values are:
1995 "" Not in completion mode
1996 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1997 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1998 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1999 |i_CTRL-X_CTRL-Y|
2000 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
2001 "files" File names |i_CTRL-X_CTRL-F|
2002 "tags" Tags |i_CTRL-X_CTRL-]|
2003 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
2004 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
2005 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
2006 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
2007 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
2008 "function" User defined completion |i_CTRL-X_CTRL-U|
2009 "omni" Omni completion |i_CTRL-X_CTRL-O|
2010 "spell" Spelling suggestions |i_CTRL-X_s|
2011 "eval" |complete()| completion
glepnir49864ae2025-05-28 20:39:34 +02002012 "register" Words from registers |i_CTRL-X_CTRL-R|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002013 "unknown" Other internal modes
2014
2015 If the optional {what} list argument is supplied, then only
2016 the items listed in {what} are returned. Unsupported items in
2017 {what} are silently ignored.
2018
2019 To get the position and size of the popup menu, see
2020 |pum_getpos()|. It's also available in |v:event| during the
2021 |CompleteChanged| event.
2022
Bram Moolenaar016188f2022-06-06 20:52:59 +01002023 Returns an empty |Dictionary| on error.
2024
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002025 Examples: >
2026 " Get all items
2027 call complete_info()
2028 " Get only 'mode'
2029 call complete_info(['mode'])
2030 " Get only 'mode' and 'pum_visible'
2031 call complete_info(['mode', 'pum_visible'])
2032
2033< Can also be used as a |method|: >
2034 GetItems()->complete_info()
2035<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002036 Return type: dict<any>
2037
glepnirbcd59952025-04-24 21:48:35 +02002038complete_match([{lnum}, {col}]) *complete_match()*
glepnirffc89e42025-04-27 14:59:17 +02002039 Searches backward from the given position and returns a List
2040 of matches according to the 'isexpand' option. When no
2041 arguments are provided, uses the current cursor position.
2042
2043 Each match is represented as a List containing
glepnirbcd59952025-04-24 21:48:35 +02002044 [startcol, trigger_text] where:
2045 - startcol: column position where completion should start,
2046 or -1 if no trigger position is found. For multi-character
2047 triggers, returns the column of the first character.
2048 - trigger_text: the matching trigger string from 'isexpand',
2049 or empty string if no match was found or when using the
2050 default 'iskeyword' pattern.
2051
Hirohito Higashi8f7256a2025-06-07 18:31:42 +02002052 When 'isexpand' is empty, uses the 'iskeyword' pattern "\k\+$"
2053 to find the start of the current keyword.
glepnirbcd59952025-04-24 21:48:35 +02002054
glepnirbcd59952025-04-24 21:48:35 +02002055 Examples: >
2056 set isexpand=.,->,/,/*,abc
2057 func CustomComplete()
2058 let res = complete_match()
2059 if res->len() == 0 | return | endif
2060 let [col, trigger] = res[0]
2061 let items = []
2062 if trigger == '/*'
2063 let items = ['/** */']
2064 elseif trigger == '/'
2065 let items = ['/*! */', '// TODO:', '// fixme:']
2066 elseif trigger == '.'
2067 let items = ['length()']
2068 elseif trigger =~ '^\->'
2069 let items = ['map()', 'reduce()']
2070 elseif trigger =~ '^\abc'
2071 let items = ['def', 'ghk']
2072 endif
2073 if items->len() > 0
2074 let startcol = trigger =~ '^/' ? col : col + len(trigger)
2075 call complete(startcol, items)
2076 endif
2077 endfunc
2078 inoremap <Tab> <Cmd>call CustomComplete()<CR>
2079<
2080 Return type: list<list<any>>
2081
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002082 *confirm()*
2083confirm({msg} [, {choices} [, {default} [, {type}]]])
2084 confirm() offers the user a dialog, from which a choice can be
2085 made. It returns the number of the choice. For the first
2086 choice this is 1.
2087 Note: confirm() is only supported when compiled with dialog
glepnirdf461152024-04-04 22:23:29 +02002088 support, see |+dialog_con| |+dialog_con_gui| and |+dialog_gui|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002089
2090 {msg} is displayed in a |dialog| with {choices} as the
2091 alternatives. When {choices} is missing or empty, "&OK" is
2092 used (and translated).
2093 {msg} is a String, use '\n' to include a newline. Only on
2094 some systems the string is wrapped when it doesn't fit.
2095
2096 {choices} is a String, with the individual choices separated
2097 by '\n', e.g. >
2098 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2099< The letter after the '&' is the shortcut key for that choice.
2100 Thus you can type 'c' to select "Cancel". The shortcut does
2101 not need to be the first letter: >
2102 confirm("file has been modified", "&Save\nSave &All")
2103< For the console, the first letter of each choice is used as
2104 the default shortcut key. Case is ignored.
2105
2106 The optional {default} argument is the number of the choice
2107 that is made if the user hits <CR>. Use 1 to make the first
2108 choice the default one. Use 0 to not set a default. If
2109 {default} is omitted, 1 is used.
2110
2111 The optional {type} String argument gives the type of dialog.
2112 This is only used for the icon of the GTK, Mac, Motif and
2113 Win32 GUI. It can be one of these values: "Error",
2114 "Question", "Info", "Warning" or "Generic". Only the first
2115 character is relevant. When {type} is omitted, "Generic" is
2116 used.
2117
2118 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2119 or another valid interrupt key, confirm() returns 0.
2120
2121 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01002122 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002123 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01002124 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002125 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01002126 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002127 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01002128 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002129 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01002130 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002131< In a GUI dialog, buttons are used. The layout of the buttons
2132 depends on the 'v' flag in 'guioptions'. If it is included,
2133 the buttons are always put vertically. Otherwise, confirm()
2134 tries to put the buttons in one horizontal line. If they
2135 don't fit, a vertical layout is used anyway. For some systems
2136 the horizontal layout is always used.
2137
2138 Can also be used as a |method|in: >
2139 BuildMessage()->confirm("&Yes\n&No")
2140<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002141 Return type: |Number|
2142
2143
2144copy({expr}) *copy()*
2145 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002146 different from using {expr} directly.
2147 When {expr} is a |List| a shallow copy is created. This means
2148 that the original |List| can be changed without changing the
2149 copy, and vice versa. But the items are identical, thus
2150 changing an item changes the contents of both |Lists|.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01002151 A |Tuple| or |Dictionary| is copied in a similar way as a
2152 |List|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002153 Also see |deepcopy()|.
2154 Can also be used as a |method|: >
2155 mylist->copy()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002156<
2157 Return type: any, depending on {expr}
2158
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002159
2160cos({expr}) *cos()*
2161 Return the cosine of {expr}, measured in radians, as a |Float|.
2162 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002163 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002164 Examples: >
2165 :echo cos(100)
2166< 0.862319 >
2167 :echo cos(-4.01)
2168< -0.646043
2169
2170 Can also be used as a |method|: >
2171 Compute()->cos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002172<
2173 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002174
2175
2176cosh({expr}) *cosh()*
2177 Return the hyperbolic cosine of {expr} as a |Float| in the range
2178 [1, inf].
2179 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002180 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002181 Examples: >
2182 :echo cosh(0.5)
2183< 1.127626 >
2184 :echo cosh(-0.5)
2185< -1.127626
2186
2187 Can also be used as a |method|: >
2188 Compute()->cosh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002189<
2190 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002191
2192
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07002193count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002194 Return the number of times an item with value {expr} appears
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01002195 in |String|, |List|, |Tuple| or |Dictionary| {comp}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002196
2197 If {start} is given then start with the item with this index.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01002198 {start} can only be used with a |List| or a |Tuple|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002199
2200 When {ic} is given and it's |TRUE| then case is ignored.
2201
2202 When {comp} is a string then the number of not overlapping
2203 occurrences of {expr} is returned. Zero is returned when
2204 {expr} is an empty string.
2205
2206 Can also be used as a |method|: >
2207 mylist->count(val)
2208<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002209 Return type: |Number|
2210
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002211 *cscope_connection()*
2212cscope_connection([{num} , {dbpath} [, {prepend}]])
2213 Checks for the existence of a |cscope| connection. If no
2214 parameters are specified, then the function returns:
2215 0, if cscope was not available (not compiled in), or
2216 if there are no cscope connections;
2217 1, if there is at least one cscope connection.
2218
2219 If parameters are specified, then the value of {num}
2220 determines how existence of a cscope connection is checked:
2221
2222 {num} Description of existence check
2223 ----- ------------------------------
2224 0 Same as no parameters (e.g., "cscope_connection()").
2225 1 Ignore {prepend}, and use partial string matches for
2226 {dbpath}.
2227 2 Ignore {prepend}, and use exact string matches for
2228 {dbpath}.
2229 3 Use {prepend}, use partial string matches for both
2230 {dbpath} and {prepend}.
2231 4 Use {prepend}, use exact string matches for both
2232 {dbpath} and {prepend}.
2233
2234 Note: All string comparisons are case sensitive!
2235
2236 Examples. Suppose we had the following (from ":cs show"): >
2237
2238 # pid database name prepend path
2239 0 27664 cscope.out /usr/local
2240<
2241 Invocation Return Val ~
2242 ---------- ---------- >
2243 cscope_connection() 1
2244 cscope_connection(1, "out") 1
2245 cscope_connection(2, "out") 0
2246 cscope_connection(3, "out") 0
2247 cscope_connection(3, "out", "local") 1
2248 cscope_connection(4, "out") 0
2249 cscope_connection(4, "out", "local") 0
2250 cscope_connection(4, "cscope.out", "/usr/local") 1
2251<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002252 Return type: |Number|
2253
2254
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002255cursor({lnum}, {col} [, {off}]) *cursor()*
2256cursor({list})
2257 Positions the cursor at the column (byte count) {col} in the
2258 line {lnum}. The first column is one.
2259
2260 When there is one argument {list} this is used as a |List|
2261 with two, three or four item:
2262 [{lnum}, {col}]
2263 [{lnum}, {col}, {off}]
2264 [{lnum}, {col}, {off}, {curswant}]
2265 This is like the return value of |getpos()| or |getcurpos()|,
2266 but without the first item.
2267
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01002268 To position the cursor using {col} as the character count, use
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002269 |setcursorcharpos()|.
2270
2271 Does not change the jumplist.
Bram Moolenaar7c6cd442022-10-11 21:54:04 +01002272 {lnum} is used like with |getline()|, except that if {lnum} is
2273 zero, the cursor will stay in the current line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002274 If {lnum} is greater than the number of lines in the buffer,
2275 the cursor will be positioned at the last line in the buffer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002276 If {col} is greater than the number of bytes in the line,
2277 the cursor will be positioned at the last character in the
2278 line.
2279 If {col} is zero, the cursor will stay in the current column.
2280 If {curswant} is given it is used to set the preferred column
2281 for vertical movement. Otherwise {col} is used.
2282
2283 When 'virtualedit' is used {off} specifies the offset in
2284 screen columns from the start of the character. E.g., a
2285 position within a <Tab> or after the last character.
2286 Returns 0 when the position could be set, -1 otherwise.
2287
2288 Can also be used as a |method|: >
2289 GetCursorPos()->cursor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002290<
2291 Return type: |Number|
2292
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002293
2294debugbreak({pid}) *debugbreak()*
2295 Specifically used to interrupt a program being debugged. It
2296 will cause process {pid} to get a SIGTRAP. Behavior for other
2297 processes is undefined. See |terminal-debugger|.
2298 {only available on MS-Windows}
2299
Bram Moolenaar016188f2022-06-06 20:52:59 +01002300 Returns |TRUE| if successfully interrupted the program.
2301 Otherwise returns |FALSE|.
2302
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002303 Can also be used as a |method|: >
2304 GetPid()->debugbreak()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002305<
2306 Return type: |Number|
2307
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002308
2309deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
2310 Make a copy of {expr}. For Numbers and Strings this isn't
2311 different from using {expr} directly.
2312 When {expr} is a |List| a full copy is created. This means
2313 that the original |List| can be changed without changing the
2314 copy, and vice versa. When an item is a |List| or
2315 |Dictionary|, a copy for it is made, recursively. Thus
2316 changing an item in the copy does not change the contents of
2317 the original |List|.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01002318 A |Tuple| or |Dictionary| is copied in a similar way as a
2319 |List|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002320
2321 When {noref} is omitted or zero a contained |List| or
2322 |Dictionary| is only copied once. All references point to
2323 this single copy. With {noref} set to 1 every occurrence of a
2324 |List| or |Dictionary| results in a new copy. This also means
2325 that a cyclic reference causes deepcopy() to fail.
2326 *E724*
2327 Nesting is possible up to 100 levels. When there is an item
2328 that refers back to a higher level making a deep copy with
2329 {noref} set to 1 will fail.
2330 Also see |copy()|.
2331
2332 Can also be used as a |method|: >
2333 GetObject()->deepcopy()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002334<
2335 Return type: any, depending on {expr}
2336
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002337
2338delete({fname} [, {flags}]) *delete()*
2339 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002340 name {fname}.
2341
2342 This also works when {fname} is a symbolic link. The symbolic
2343 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002344
2345 When {flags} is "d": Deletes the directory by the name
2346 {fname}. This fails when directory {fname} is not empty.
2347
2348 When {flags} is "rf": Deletes the directory by the name
2349 {fname} and everything in it, recursively. BE CAREFUL!
2350 Note: on MS-Windows it is not possible to delete a directory
2351 that is being used.
2352
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002353 The result is a Number, which is 0/false if the delete
2354 operation was successful and -1/true when the deletion failed
2355 or partly failed.
2356
2357 Use |remove()| to delete an item from a |List|.
2358 To delete a line from the buffer use |:delete| or
2359 |deletebufline()|.
2360
2361 Can also be used as a |method|: >
2362 GetName()->delete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002363<
2364 Return type: |Number|
2365
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002366
2367deletebufline({buf}, {first} [, {last}]) *deletebufline()*
2368 Delete lines {first} to {last} (inclusive) from buffer {buf}.
2369 If {last} is omitted then delete line {first} only.
2370 On success 0 is returned, on failure 1 is returned.
2371
2372 This function works only for loaded buffers. First call
2373 |bufload()| if needed.
2374
2375 For the use of {buf}, see |bufname()| above.
2376
2377 {first} and {last} are used like with |getline()|. Note that
2378 when using |line()| this refers to the current buffer. Use "$"
2379 to refer to the last line in buffer {buf}.
2380
2381 Can also be used as a |method|: >
2382 GetBuffer()->deletebufline(1)
2383<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002384 Return type: |Number|
2385
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002386 *did_filetype()*
2387did_filetype() Returns |TRUE| when autocommands are being executed and the
2388 FileType event has been triggered at least once. Can be used
2389 to avoid triggering the FileType event again in the scripts
2390 that detect the file type. |FileType|
2391 Returns |FALSE| when `:setf FALLBACK` was used.
2392 When editing another file, the counter is reset, thus this
2393 really checks if the FileType event has been triggered for the
2394 current buffer. This allows an autocommand that starts
2395 editing another buffer to set 'filetype' and load a syntax
2396 file.
2397
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002398 Return type: |Number|
2399
2400
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002401diff({fromlist}, {tolist} [, {options}]) *diff()*
2402 Returns a String or a List containing the diff between the
2403 strings in {fromlist} and {tolist}. Uses the Vim internal
2404 diff library to compute the diff.
2405
2406 *E106*
2407 The optional "output" item in {options} specifies the returned
2408 diff format. The following values are supported:
2409 indices Return a List of the starting and ending
2410 indices and a count of the strings in each
2411 diff hunk.
2412 unified Return the unified diff output as a String.
2413 This is the default.
2414
2415 If the "output" item in {options} is "indices", then a List is
2416 returned. Each List item contains a Dict with the following
2417 items for each diff hunk:
2418 from_idx start index in {fromlist} for this diff hunk.
2419 from_count number of strings in {fromlist} that are
2420 added/removed/modified in this diff hunk.
2421 to_idx start index in {tolist} for this diff hunk.
2422 to_count number of strings in {tolist} that are
2423 added/removed/modified in this diff hunk.
2424
2425 The {options} Dict argument also specifies diff options
2426 (similar to 'diffopt') and supports the following items:
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002427 algorithm Dict specifying the diff algorithm to
2428 use. Supported boolean items are
2429 "myers", "minimal", "patience" and
2430 "histogram".
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002431 context diff context length. Default is 0.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002432 iblank ignore changes where lines are all
2433 blank.
2434 icase ignore changes in case of text.
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002435 indent-heuristic use the indent heuristic for the
2436 internal diff library.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002437 iwhite ignore changes in amount of white
2438 space.
2439 iwhiteall ignore all white space changes.
2440 iwhiteeol ignore white space changes at end of
2441 line.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002442 For more information about these options, refer to 'diffopt'.
2443
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002444 To compute the unified diff, all the items in {fromlist} are
2445 concatenated into a string using a newline separator and the
2446 same for {tolist}. The unified diff output uses line numbers.
2447
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002448 Returns an empty List or String if {fromlist} and {tolist} are
2449 identical.
2450
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002451 Examples: >
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002452 :echo diff(['abc'], ['xxx'])
2453 @@ -1 +1 @@
2454 -abc
2455 +xxx
2456
2457 :echo diff(['abc'], ['xxx'], {'output': 'indices'})
2458 [{'from_idx': 0, 'from_count': 1, 'to_idx': 0, 'to_count': 1}]
2459 :echo diff(readfile('oldfile'), readfile('newfile'))
2460 :echo diff(getbufline(5, 1, '$'), getbufline(6, 1, '$'))
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002461<
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002462 For more examples, refer to |diff-func-examples|
2463
2464 Can also be used as a |method|: >
2465 GetFromList->diff(to_list)
2466<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002467 Return type: |String| or list<dict<number>> or list<any>
2468 depending on {options}
2469
2470
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002471diff_filler({lnum}) *diff_filler()*
2472 Returns the number of filler lines above line {lnum}.
2473 These are the lines that were inserted at this point in
2474 another diff'ed window. These filler lines are shown in the
2475 display but don't exist in the buffer.
2476 {lnum} is used like with |getline()|. Thus "." is the current
2477 line, "'m" mark m, etc.
2478 Returns 0 if the current window is not in diff mode.
2479
2480 Can also be used as a |method|: >
2481 GetLnum()->diff_filler()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002482<
2483 Return type: |Number|
2484
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002485
2486diff_hlID({lnum}, {col}) *diff_hlID()*
2487 Returns the highlight ID for diff mode at line {lnum} column
2488 {col} (byte index). When the current line does not have a
2489 diff change zero is returned.
2490 {lnum} is used like with |getline()|. Thus "." is the current
2491 line, "'m" mark m, etc.
2492 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2493 line.
2494 The highlight ID can be used with |synIDattr()| to obtain
2495 syntax information about the highlighting.
2496
2497 Can also be used as a |method|: >
2498 GetLnum()->diff_hlID(col)
2499<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002500 Return type: |Number|
2501
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002502
2503digraph_get({chars}) *digraph_get()* *E1214*
2504 Return the digraph of {chars}. This should be a string with
2505 exactly two characters. If {chars} are not just two
2506 characters, or the digraph of {chars} does not exist, an error
2507 is given and an empty string is returned.
2508
2509 The character will be converted from Unicode to 'encoding'
2510 when needed. This does require the conversion to be
2511 available, it might fail.
2512
2513 Also see |digraph_getlist()|.
2514
2515 Examples: >
2516 " Get a built-in digraph
2517 :echo digraph_get('00') " Returns '∞'
2518
2519 " Get a user-defined digraph
2520 :call digraph_set('aa', 'あ')
2521 :echo digraph_get('aa') " Returns 'あ'
2522<
2523 Can also be used as a |method|: >
2524 GetChars()->digraph_get()
2525<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002526 Return type: |String|
2527
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002528 This function works only when compiled with the |+digraphs|
2529 feature. If this feature is disabled, this function will
2530 display an error message.
2531
2532
2533digraph_getlist([{listall}]) *digraph_getlist()*
2534 Return a list of digraphs. If the {listall} argument is given
2535 and it is TRUE, return all digraphs, including the default
2536 digraphs. Otherwise, return only user-defined digraphs.
2537
2538 The characters will be converted from Unicode to 'encoding'
2539 when needed. This does require the conservation to be
2540 available, it might fail.
2541
2542 Also see |digraph_get()|.
2543
2544 Examples: >
2545 " Get user-defined digraphs
2546 :echo digraph_getlist()
2547
2548 " Get all the digraphs, including default digraphs
2549 :echo digraph_getlist(1)
2550<
2551 Can also be used as a |method|: >
2552 GetNumber()->digraph_getlist()
2553<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002554 Return type: list<list<string>>
2555
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002556 This function works only when compiled with the |+digraphs|
2557 feature. If this feature is disabled, this function will
2558 display an error message.
2559
2560
Bram Moolenaara2baa732022-02-04 16:09:54 +00002561digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002562 Add digraph {chars} to the list. {chars} must be a string
2563 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002564 encoded character. *E1215*
2565 Be careful, composing characters are NOT ignored. This
2566 function is similar to |:digraphs| command, but useful to add
2567 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002568
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002569 The function returns v:true if |digraph| is registered. If
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002570 this fails an error message is given and v:false is returned.
2571
2572 If you want to define multiple digraphs at once, you can use
2573 |digraph_setlist()|.
2574
2575 Example: >
2576 call digraph_set(' ', 'あ')
2577<
2578 Can be used as a |method|: >
2579 GetString()->digraph_set('あ')
2580<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002581 Return type: |vim9-boolean|
2582
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002583 This function works only when compiled with the |+digraphs|
2584 feature. If this feature is disabled, this function will
2585 display an error message.
2586
2587
2588digraph_setlist({digraphlist}) *digraph_setlist()*
2589 Similar to |digraph_set()| but this function can add multiple
2590 digraphs at once. {digraphlist} is a list composed of lists,
2591 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002592 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002593 Example: >
2594 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2595<
2596 It is similar to the following: >
2597 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2598 call digraph_set(chars, digraph)
2599 endfor
2600< Except that the function returns after the first error,
2601 following digraphs will not be added.
2602
2603 Can be used as a |method|: >
2604 GetList()->digraph_setlist()
2605<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002606 Return type: |vim9-boolean|
2607
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002608 This function works only when compiled with the |+digraphs|
2609 feature. If this feature is disabled, this function will
2610 display an error message.
2611
2612
2613echoraw({string}) *echoraw()*
2614 Output {string} as-is, including unprintable characters.
2615 This can be used to output a terminal code. For example, to
2616 disable modifyOtherKeys: >
2617 call echoraw(&t_TE)
2618< and to enable it again: >
2619 call echoraw(&t_TI)
2620< Use with care, you can mess up the terminal this way.
2621
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002622 Return type: |Number|
2623
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002624
2625empty({expr}) *empty()*
2626 Return the Number 1 if {expr} is empty, zero otherwise.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01002627 - A |List|, |Tuple| or |Dictionary| is empty when it does
2628 not have any items.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002629 - A |String| is empty when its length is zero.
2630 - A |Number| and |Float| are empty when their value is zero.
2631 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2632 - A |Job| is empty when it failed to start.
2633 - A |Channel| is empty when it is closed.
2634 - A |Blob| is empty when its length is zero.
mityu7f0bba22024-03-29 10:14:41 +01002635 - An |Object| is empty, when the empty() method in the object
2636 (if present) returns true. |object-empty()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002637
2638 For a long |List| this is much faster than comparing the
2639 length with zero.
2640
2641 Can also be used as a |method|: >
2642 mylist->empty()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002643<
2644 Return type: |Number|
2645
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002646
2647environ() *environ()*
2648 Return all of environment variables as dictionary. You can
2649 check if an environment variable exists like this: >
2650 :echo has_key(environ(), 'HOME')
2651< Note that the variable name may be CamelCase; to ignore case
2652 use this: >
2653 :echo index(keys(environ()), 'HOME', 0, 1) != -1
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002654<
2655 Return type: dict<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002656
Bram Moolenaar416bd912023-07-07 23:19:18 +01002657
2658err_teapot([{expr}]) *err_teapot()*
2659 Produce an error with number 418, needed for implementation of
Christian Brabandtee17b6f2023-09-09 11:23:50 +02002660 RFC 2324.
Bram Moolenaar416bd912023-07-07 23:19:18 +01002661 If {expr} is present and it is TRUE error 503 is given,
2662 indicating that coffee is temporarily not available.
2663 If {expr} is present it must be a String.
2664
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002665 Return type: |Number|
2666
Bram Moolenaar416bd912023-07-07 23:19:18 +01002667
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002668escape({string}, {chars}) *escape()*
2669 Escape the characters in {chars} that occur in {string} with a
2670 backslash. Example: >
2671 :echo escape('c:\program files\vim', ' \')
2672< results in: >
2673 c:\\program\ files\\vim
2674< Also see |shellescape()| and |fnameescape()|.
2675
2676 Can also be used as a |method|: >
2677 GetText()->escape(' \')
2678<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002679 Return type: |String|
2680
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002681 *eval()*
2682eval({string}) Evaluate {string} and return the result. Especially useful to
2683 turn the result of |string()| back into the original value.
2684 This works for Numbers, Floats, Strings, Blobs and composites
2685 of them. Also works for |Funcref|s that refer to existing
Aliaksei Budavei95740222024-04-04 23:05:33 +03002686 functions. In |Vim9| script, it can be used to obtain |enum|
2687 values from their fully qualified names.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002688
2689 Can also be used as a |method|: >
2690 argv->join()->eval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002691<
2692 Return type: any, depending on {string}
2693
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002694
2695eventhandler() *eventhandler()*
2696 Returns 1 when inside an event handler. That is that Vim got
2697 interrupted while waiting for the user to type a character,
2698 e.g., when dropping a file on Vim. This means interactive
2699 commands cannot be used. Otherwise zero is returned.
2700
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002701 Return type: |Number|
2702
2703
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002704executable({expr}) *executable()*
2705 This function checks if an executable with the name {expr}
2706 exists. {expr} must be the name of the program without any
2707 arguments.
zeertzjq0cc5dce2024-08-08 21:12:15 +02002708
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002709 executable() uses the value of $PATH and/or the normal
zeertzjq0cc5dce2024-08-08 21:12:15 +02002710 searchpath for programs.
2711 *PATHEXT*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002712 On MS-Windows the ".exe", ".bat", etc. can optionally be
2713 included. Then the extensions in $PATHEXT are tried. Thus if
2714 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2715 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2716 by itself can be used in $PATHEXT to try using the name
2717 without an extension. When 'shell' looks like a Unix shell,
2718 then the name is also tried without adding an extension.
2719 On MS-Windows it only checks if the file exists and is not a
2720 directory, not if it's really executable.
zeertzjq0cc5dce2024-08-08 21:12:15 +02002721 On MS-Windows an executable in the same directory as the Vim
2722 executable is always found. Since this directory is added to
2723 $PATH it should also work to execute it |win32-PATH|.
2724 *NoDefaultCurrentDirectoryInExePath*
2725 On MS-Windows an executable in Vim's current working directory
2726 is also normally found, but this can be disabled by setting
2727 the $NoDefaultCurrentDirectoryInExePath environment variable.
2728
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002729 The result is a Number:
2730 1 exists
2731 0 does not exist
2732 -1 not implemented on this system
2733 |exepath()| can be used to get the full path of an executable.
2734
2735 Can also be used as a |method|: >
2736 GetCommand()->executable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002737<
2738 Return type: |Number|
2739
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002740
2741execute({command} [, {silent}]) *execute()*
2742 Execute an Ex command or commands and return the output as a
2743 string.
2744 {command} can be a string or a List. In case of a List the
2745 lines are executed one by one.
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002746 This is more or less equivalent to: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002747 redir => var
2748 {command}
2749 redir END
Bram Moolenaar71badf92023-04-22 22:40:14 +01002750< Except that line continuation in {command} is not recognized.
2751
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002752 The optional {silent} argument can have these values:
2753 "" no `:silent` used
2754 "silent" `:silent` used
2755 "silent!" `:silent!` used
2756 The default is "silent". Note that with "silent!", unlike
2757 `:redir`, error messages are dropped. When using an external
2758 command the screen may be messed up, use `system()` instead.
2759 *E930*
2760 It is not possible to use `:redir` anywhere in {command}.
2761
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002762 To get a list of lines use `split()` on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002763 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002764
2765< To execute a command in another window than the current one
2766 use `win_execute()`.
2767
2768 When used recursively the output of the recursive call is not
2769 included in the output of the higher level call.
2770
2771 Can also be used as a |method|: >
2772 GetCommand()->execute()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002773<
Marius Gedminasc98bfb92024-06-19 19:59:23 +02002774 Return type: |String|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002775
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002776
2777exepath({expr}) *exepath()*
2778 If {expr} is an executable and is either an absolute path, a
2779 relative path or found in $PATH, return the full path.
2780 Note that the current directory is used when {expr} starts
2781 with "./", which may be a problem for Vim: >
2782 echo exepath(v:progpath)
2783< If {expr} cannot be found in $PATH or is not executable then
2784 an empty string is returned.
2785
2786 Can also be used as a |method|: >
2787 GetCommand()->exepath()
2788<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002789 Return type: |String|
2790
2791
2792exists({expr}) *exists()*
2793 The result is a Number, which is |TRUE| if {expr} is defined,
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002794 zero otherwise.
2795
2796 Note: In a compiled |:def| function the evaluation is done at
2797 runtime. Use `exists_compiled()` to evaluate the expression
2798 at compile time.
2799
2800 For checking for a supported feature use |has()|.
2801 For checking if a file exists use |filereadable()|.
2802
2803 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002804 varname internal variable (see
2805 dict.key |internal-variables|). Also works
2806 list[i] for |curly-braces-names|, |Dictionary|
Yegappan Lakshmanana2ebb6e2024-02-25 08:40:10 +01002807 import.Func entries, |List| items, class and
2808 class.Func object methods, imported items, etc.
2809 object.Func Does not work for local variables in a
2810 class.varname compiled `:def` function.
2811 object.varname Also works for a function in |Vim9|
Bram Moolenaar944697a2022-02-20 19:48:20 +00002812 script, since it can be used as a
2813 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002814 Beware that evaluating an index may
2815 cause an error message for an invalid
2816 expression. E.g.: >
2817 :let l = [1, 2, 3]
2818 :echo exists("l[5]")
2819< 0 >
2820 :echo exists("l[xx]")
2821< E121: Undefined variable: xx
2822 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002823 &option-name Vim option (only checks if it exists,
2824 not if it really works)
2825 +option-name Vim option that works.
2826 $ENVNAME environment variable (could also be
2827 done by comparing with an empty
2828 string)
2829 *funcname built-in function (see |functions|)
2830 or user defined function (see
2831 |user-functions|) that is implemented.
2832 Also works for a variable that is a
2833 Funcref.
2834 ?funcname built-in function that could be
2835 implemented; to be used to check if
2836 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002837 :cmdname Ex command: built-in command, user
2838 command or command modifier |:command|.
2839 Returns:
2840 1 for match with start of a command
2841 2 full match with a command
2842 3 matches several user commands
2843 To check for a supported command
2844 always check the return value to be 2.
2845 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002846 :3match The |:3match| command (but you
2847 probably should not use it, it is
2848 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002849 #event autocommand defined for this event
2850 #event#pattern autocommand defined for this event and
2851 pattern (the pattern is taken
2852 literally and compared to the
2853 autocommand patterns character by
2854 character)
2855 #group autocommand group exists
2856 #group#event autocommand defined for this group and
2857 event.
2858 #group#event#pattern
2859 autocommand defined for this group,
2860 event and pattern.
2861 ##event autocommand for this event is
2862 supported.
2863
2864 Examples: >
2865 exists("&shortname")
2866 exists("$HOSTNAME")
2867 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002868 exists("*s:MyFunc") " only for legacy script
2869 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002870 exists("bufcount")
2871 exists(":Make")
2872 exists("#CursorHold")
2873 exists("#BufReadPre#*.gz")
2874 exists("#filetypeindent")
2875 exists("#filetypeindent#FileType")
2876 exists("#filetypeindent#FileType#*")
2877 exists("##ColorScheme")
2878< There must be no space between the symbol (&/$/*/#) and the
2879 name.
2880 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002881 a few cases this is ignored. That may become stricter in the
2882 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002883 Working example: >
2884 exists(":make")
2885< NOT working example: >
2886 exists(":make install")
2887
2888< Note that the argument must be a string, not the name of the
2889 variable itself. For example: >
2890 exists(bufcount)
2891< This doesn't check for existence of the "bufcount" variable,
2892 but gets the value of "bufcount", and checks if that exists.
2893
2894 Can also be used as a |method|: >
2895 Varname()->exists()
2896<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002897 Return type: |String|
2898
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002899
2900exists_compiled({expr}) *exists_compiled()*
2901 Like `exists()` but evaluated at compile time. This is useful
2902 to skip a block where a function is used that would otherwise
2903 give an error: >
2904 if exists_compiled('*ThatFunction')
2905 ThatFunction('works')
2906 endif
2907< If `exists()` were used then a compilation error would be
2908 given if ThatFunction() is not defined.
2909
2910 {expr} must be a literal string. *E1232*
2911 Can only be used in a |:def| function. *E1233*
2912 This does not work to check for arguments or local variables.
2913
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002914 Return type: |String|
2915
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002916
2917exp({expr}) *exp()*
2918 Return the exponential of {expr} as a |Float| in the range
2919 [0, inf].
2920 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002921 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002922 Examples: >
2923 :echo exp(2)
2924< 7.389056 >
2925 :echo exp(-1)
2926< 0.367879
2927
2928 Can also be used as a |method|: >
2929 Compute()->exp()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002930<
2931 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002932
2933
2934expand({string} [, {nosuf} [, {list}]]) *expand()*
2935 Expand wildcards and the following special keywords in
2936 {string}. 'wildignorecase' applies.
2937
2938 If {list} is given and it is |TRUE|, a List will be returned.
2939 Otherwise the result is a String and when there are several
2940 matches, they are separated by <NL> characters. [Note: in
2941 version 5.0 a space was used, which caused problems when a
2942 file name contains a space]
2943
2944 If the expansion fails, the result is an empty string. A name
2945 for a non-existing file is not included, unless {string} does
2946 not start with '%', '#' or '<', see below.
2947
Christian Brabandtec9c3262024-02-21 20:40:05 +01002948 For a |:terminal| window '%' expands to a '!' followed by
h-east53753f62024-05-05 18:42:31 +02002949 the command or shell that is run. |terminal-bufname|
Christian Brabandtec9c3262024-02-21 20:40:05 +01002950
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002951 When {string} starts with '%', '#' or '<', the expansion is
2952 done like for the |cmdline-special| variables with their
2953 associated modifiers. Here is a short overview:
2954
2955 % current file name
2956 # alternate file name
2957 #n alternate file name n
2958 <cfile> file name under the cursor
2959 <afile> autocmd file name
2960 <abuf> autocmd buffer number (as a String!)
2961 <amatch> autocmd matched name
2962 <cexpr> C expression under the cursor
2963 <sfile> sourced script file or function name
2964 <slnum> sourced script line number or function
2965 line number
2966 <sflnum> script file line number, also when in
2967 a function
2968 <SID> "<SNR>123_" where "123" is the
2969 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002970 <script> sourced script file, or script file
2971 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002972 <stack> call stack
2973 <cword> word under the cursor
2974 <cWORD> WORD under the cursor
2975 <client> the {clientid} of the last received
2976 message |server2client()|
2977 Modifiers:
2978 :p expand to full path
2979 :h head (last path component removed)
2980 :t tail (last path component only)
2981 :r root (one extension removed)
2982 :e extension only
2983
2984 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002985 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002986< Note that when expanding a string that starts with '%', '#' or
2987 '<', any following text is ignored. This does NOT work: >
2988 :let doesntwork = expand("%:h.bak")
2989< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002990 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002991< Also note that expanding "<cfile>" and others only returns the
2992 referenced file name without further expansion. If "<cfile>"
2993 is "~/.cshrc", you need to do another expand() to have the
2994 "~/" expanded into the path of the home directory: >
2995 :echo expand(expand("<cfile>"))
2996<
2997 There cannot be white space between the variables and the
2998 following modifier. The |fnamemodify()| function can be used
2999 to modify normal file names.
3000
3001 When using '%' or '#', and the current or alternate file name
3002 is not defined, an empty string is used. Using "%:p" in a
3003 buffer with no name, results in the current directory, with a
3004 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01003005 When 'verbose' is set then expanding '%', '#' and <> items
3006 will result in an error message if the argument cannot be
3007 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003008
3009 When {string} does not start with '%', '#' or '<', it is
3010 expanded like a file name is expanded on the command line.
3011 'suffixes' and 'wildignore' are used, unless the optional
3012 {nosuf} argument is given and it is |TRUE|.
3013 Names for non-existing files are included. The "**" item can
3014 be used to search in a directory tree. For example, to find
3015 all "README" files in the current directory and below: >
3016 :echo expand("**/README")
3017<
3018 expand() can also be used to expand variables and environment
3019 variables that are only known in a shell. But this can be
3020 slow, because a shell may be used to do the expansion. See
3021 |expr-env-expand|.
3022 The expanded variable is still handled like a list of file
3023 names. When an environment variable cannot be expanded, it is
3024 left unchanged. Thus ":echo expand('$FOOBAR')" results in
3025 "$FOOBAR".
3026
3027 See |glob()| for finding existing files. See |system()| for
3028 getting the raw output of an external command.
3029
3030 Can also be used as a |method|: >
3031 Getpattern()->expand()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003032<
3033 Return type: |String| or list<string> depending on {list}
3034
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003035
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01003036expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003037 Expand special items in String {string} like what is done for
3038 an Ex command such as `:edit`. This expands special keywords,
3039 like with |expand()|, and environment variables, anywhere in
3040 {string}. "~user" and "~/path" are only expanded at the
3041 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01003042
3043 The following items are supported in the {options} Dict
3044 argument:
3045 errmsg If set to TRUE, error messages are displayed
3046 if an error is encountered during expansion.
3047 By default, error messages are not displayed.
3048
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01003049 Returns the expanded string. If an error is encountered
3050 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01003051
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01003052 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003053 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01003054 make /path/runtime/doc/builtin.o
3055 :echo expandcmd('make %<.o', {'errmsg': v:true})
3056<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01003057 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003058 GetCommand()->expandcmd()
3059<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003060 Return type: |String| or list<string> depending on {list}
3061
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003062extend({expr1}, {expr2} [, {expr3}]) *extend()*
3063 {expr1} and {expr2} must be both |Lists| or both
3064 |Dictionaries|.
3065
3066 If they are |Lists|: Append {expr2} to {expr1}.
3067 If {expr3} is given insert the items of {expr2} before the
3068 item with index {expr3} in {expr1}. When {expr3} is zero
3069 insert before the first item. When {expr3} is equal to
3070 len({expr1}) then {expr2} is appended.
3071 Examples: >
3072 :echo sort(extend(mylist, [7, 5]))
3073 :call extend(mylist, [2, 3], 1)
3074< When {expr1} is the same List as {expr2} then the number of
3075 items copied is equal to the original length of the List.
3076 E.g., when {expr3} is 1 you get N new copies of the first item
3077 (where N is the original length of the List).
3078 Use |add()| to concatenate one item to a list. To concatenate
3079 two lists into a new list use the + operator: >
3080 :let newlist = [1, 2, 3] + [4, 5]
3081<
3082 If they are |Dictionaries|:
3083 Add all entries from {expr2} to {expr1}.
3084 If a key exists in both {expr1} and {expr2} then {expr3} is
3085 used to decide what to do:
3086 {expr3} = "keep": keep the value of {expr1}
3087 {expr3} = "force": use the value of {expr2}
3088 {expr3} = "error": give an error message *E737*
3089 When {expr3} is omitted then "force" is assumed.
3090
3091 {expr1} is changed when {expr2} is not empty. If necessary
Christian Brabandt5647c912025-02-17 21:33:30 +01003092 make a copy of {expr1} first or use |extendnew()| to return a
3093 new List/Dictionary.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003094 {expr2} remains unchanged.
3095 When {expr1} is locked and {expr2} is not empty the operation
3096 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003097 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003098
3099 Can also be used as a |method|: >
3100 mylist->extend(otherlist)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003101<
3102 Return type: list<{type}> or dict<{type}> depending on {expr1}
3103 and {expr2}, in case of error: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003104
3105
3106extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
3107 Like |extend()| but instead of adding items to {expr1} a new
3108 List or Dictionary is created and returned. {expr1} remains
Bram Moolenaardd60c362023-02-27 15:49:53 +00003109 unchanged.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003110
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003111 Return type: list<{type}> or dict<{type}> depending on {expr1}
3112 and {expr2}, in case of error: |Number|
3113
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003114
3115feedkeys({string} [, {mode}]) *feedkeys()*
3116 Characters in {string} are queued for processing as if they
3117 come from a mapping or were typed by the user.
3118
3119 By default the string is added to the end of the typeahead
3120 buffer, thus if a mapping is still being executed the
3121 characters come after them. Use the 'i' flag to insert before
3122 other characters, they will be executed next, before any
3123 characters from a mapping.
3124
3125 The function does not wait for processing of keys contained in
3126 {string}.
3127
3128 To include special keys into {string}, use double-quotes
3129 and "\..." notation |expr-quote|. For example,
3130 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
3131 feedkeys('\<CR>') pushes 5 characters.
3132 A special code that might be useful is <Ignore>, it exits the
3133 wait for a character without doing anything. *<Ignore>*
3134
3135 {mode} is a String, which can contain these character flags:
3136 'm' Remap keys. This is default. If {mode} is absent,
3137 keys are remapped.
3138 'n' Do not remap keys.
3139 't' Handle keys as if typed; otherwise they are handled as
3140 if coming from a mapping. This matters for undo,
3141 opening folds, etc.
3142 'L' Lowlevel input. Only works for Unix or when using the
3143 GUI. Keys are used as if they were coming from the
3144 terminal. Other flags are not used. *E980*
3145 When a CTRL-C interrupts and 't' is included it sets
3146 the internal "got_int" flag.
3147 'i' Insert the string instead of appending (see above).
3148 'x' Execute commands until typeahead is empty. This is
3149 similar to using ":normal!". You can call feedkeys()
3150 several times without 'x' and then one time with 'x'
3151 (possibly with an empty {string}) to execute all the
3152 typeahead. Note that when Vim ends in Insert mode it
3153 will behave as if <Esc> is typed, to avoid getting
3154 stuck, waiting for a character to be typed before the
3155 script continues.
3156 Note that if you manage to call feedkeys() while
3157 executing commands, thus calling it recursively, then
3158 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00003159 'c' Remove any script context when executing, so that
3160 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01003161 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01003162 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003163 '!' When used with 'x' will not end Insert mode. Can be
3164 used in a test when a timer is set to exit Insert mode
3165 a little later. Useful for testing CursorHoldI.
3166
3167 Return value is always 0.
3168
3169 Can also be used as a |method|: >
3170 GetInput()->feedkeys()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003171<
Christian Brabandt17ad8522025-05-09 00:03:20 +02003172 Return type: |Number|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003173
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003174
Shougo Matsushita60c87432024-06-03 22:59:27 +02003175filecopy({from}, {to}) *filecopy()*
3176 Copy the file pointed to by the name {from} to {to}. The
3177 result is a Number, which is |TRUE| if the file was copied
3178 successfully, and |FALSE| when it failed.
3179 If a file with name {to} already exists, it will fail.
3180 Note that it does not handle directories (yet).
3181
3182 This function is not available in the |sandbox|.
3183
3184 Can also be used as a |method|: >
3185 GetOldName()->filecopy(newname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003186<
3187 Return type: |Number|
3188
Shougo Matsushita60c87432024-06-03 22:59:27 +02003189
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003190filereadable({file}) *filereadable()*
3191 The result is a Number, which is |TRUE| when a file with the
3192 name {file} exists, and can be read. If {file} doesn't exist,
3193 or is a directory, the result is |FALSE|. {file} is any
3194 expression, which is used as a String.
3195 If you don't care about the file being readable you can use
3196 |glob()|.
3197 {file} is used as-is, you may want to expand wildcards first: >
3198 echo filereadable('~/.vimrc')
3199 0
3200 echo filereadable(expand('~/.vimrc'))
3201 1
3202
3203< Can also be used as a |method|: >
3204 GetName()->filereadable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003205<
3206 Return type: |Number|
3207
3208 *file_readable()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003209 Obsolete name: file_readable().
3210
3211
3212filewritable({file}) *filewritable()*
3213 The result is a Number, which is 1 when a file with the
3214 name {file} exists, and can be written. If {file} doesn't
3215 exist, or is not writable, the result is 0. If {file} is a
3216 directory, and we can write to it, the result is 2.
3217
3218 Can also be used as a |method|: >
3219 GetName()->filewritable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003220<
3221 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003222
3223
3224filter({expr1}, {expr2}) *filter()*
3225 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
3226 For each item in {expr1} evaluate {expr2} and when the result
3227 is zero or false remove the item from the |List| or
3228 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003229 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003230
3231 {expr2} must be a |string| or |Funcref|.
3232
3233 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3234 of the current item. For a |Dictionary| |v:key| has the key
3235 of the current item and for a |List| |v:key| has the index of
3236 the current item. For a |Blob| |v:key| has the index of the
3237 current byte. For a |String| |v:key| has the index of the
3238 current character.
3239 Examples: >
3240 call filter(mylist, 'v:val !~ "OLD"')
3241< Removes the items where "OLD" appears. >
3242 call filter(mydict, 'v:key >= 8')
3243< Removes the items with a key below 8. >
3244 call filter(var, 0)
3245< Removes all the items, thus clears the |List| or |Dictionary|.
3246
3247 Note that {expr2} is the result of expression and is then
3248 used as an expression again. Often it is good to use a
3249 |literal-string| to avoid having to double backslashes.
3250
3251 If {expr2} is a |Funcref| it must take two arguments:
3252 1. the key or the index of the current item.
3253 2. the value of the current item.
3254 The function must return |TRUE| if the item should be kept.
3255 Example that keeps the odd items of a list: >
3256 func Odd(idx, val)
3257 return a:idx % 2 == 1
3258 endfunc
3259 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003260< It is shorter when using a |lambda|. In |Vim9| syntax: >
3261 call filter(myList, (idx, val) => idx * val <= 42)
3262< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003263 call filter(myList, {idx, val -> idx * val <= 42})
3264< If you do not use "val" you can leave it out: >
3265 call filter(myList, {idx -> idx % 2 == 1})
3266<
3267 In |Vim9| script the result must be true, false, zero or one.
3268 Other values will result in a type error.
3269
3270 For a |List| and a |Dictionary| the operation is done
3271 in-place. If you want it to remain unmodified make a copy
3272 first: >
3273 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
3274
3275< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00003276 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003277 When an error is encountered while evaluating {expr2} no
3278 further items in {expr1} are processed.
3279 When {expr2} is a Funcref errors inside a function are ignored,
3280 unless it was defined with the "abort" flag.
3281
3282 Can also be used as a |method|: >
3283 mylist->filter(expr2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003284<
3285 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
3286 depending on {expr1}
3287
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003288
3289finddir({name} [, {path} [, {count}]]) *finddir()*
3290 Find directory {name} in {path}. Supports both downwards and
3291 upwards recursive directory searches. See |file-searching|
3292 for the syntax of {path}.
3293
3294 Returns the path of the first found match. When the found
3295 directory is below the current directory a relative path is
3296 returned. Otherwise a full path is returned.
3297 If {path} is omitted or empty then 'path' is used.
3298
3299 If the optional {count} is given, find {count}'s occurrence of
3300 {name} in {path} instead of the first one.
3301 When {count} is negative return all the matches in a |List|.
3302
Bram Moolenaar016188f2022-06-06 20:52:59 +01003303 Returns an empty string if the directory is not found.
3304
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003305 This is quite similar to the ex-command `:find`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003306
3307 Can also be used as a |method|: >
3308 GetName()->finddir()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003309<
Christian Brabandtb753d802025-04-21 11:31:58 +02003310 Return type: list<string> if {count} is negative, |String|
3311 otherwise
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003312
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003313
3314findfile({name} [, {path} [, {count}]]) *findfile()*
3315 Just like |finddir()|, but find a file instead of a directory.
3316 Uses 'suffixesadd'.
3317 Example: >
3318 :echo findfile("tags.vim", ".;")
3319< Searches from the directory of the current file upwards until
3320 it finds the file "tags.vim".
3321
3322 Can also be used as a |method|: >
3323 GetName()->findfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003324<
Christian Brabandtb753d802025-04-21 11:31:58 +02003325 Return type: list<string> if {count} is negative, |String|
3326 otherwise
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003327
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003328
3329flatten({list} [, {maxdepth}]) *flatten()*
3330 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
3331 the result is a |List| without nesting, as if {maxdepth} is
3332 a very large number.
3333 The {list} is changed in place, use |flattennew()| if you do
3334 not want that.
3335 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00003336 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003337 *E900*
3338 {maxdepth} means how deep in nested lists changes are made.
3339 {list} is not modified when {maxdepth} is 0.
3340 {maxdepth} must be positive number.
3341
3342 If there is an error the number zero is returned.
3343
3344 Example: >
3345 :echo flatten([1, [2, [3, 4]], 5])
3346< [1, 2, 3, 4, 5] >
3347 :echo flatten([1, [2, [3, 4]], 5], 1)
3348< [1, 2, [3, 4], 5]
3349
3350 Can also be used as a |method|: >
3351 mylist->flatten()
3352<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003353 Return type: list<{type}>
3354
3355
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003356flattennew({list} [, {maxdepth}]) *flattennew()*
3357 Like |flatten()| but first make a copy of {list}.
3358
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003359 Return type: list<{type}>
3360
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003361
3362float2nr({expr}) *float2nr()*
3363 Convert {expr} to a Number by omitting the part after the
3364 decimal point.
Bram Moolenaar76db9e02022-11-09 21:21:04 +00003365 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003366 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003367 When the value of {expr} is out of range for a |Number| the
3368 result is truncated to 0x7fffffff or -0x7fffffff (or when
3369 64-bit Number support is enabled, 0x7fffffffffffffff or
3370 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
3371 64-bit Number support is enabled, -0x8000000000000000).
3372 Examples: >
3373 echo float2nr(3.95)
3374< 3 >
3375 echo float2nr(-23.45)
3376< -23 >
3377 echo float2nr(1.0e100)
3378< 2147483647 (or 9223372036854775807) >
3379 echo float2nr(-1.0e150)
3380< -2147483647 (or -9223372036854775807) >
3381 echo float2nr(1.0e-100)
3382< 0
3383
3384 Can also be used as a |method|: >
3385 Compute()->float2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003386<
3387 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003388
3389
3390floor({expr}) *floor()*
3391 Return the largest integral value less than or equal to
3392 {expr} as a |Float| (round down).
3393 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003394 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003395 Examples: >
3396 echo floor(1.856)
3397< 1.0 >
3398 echo floor(-5.456)
3399< -6.0 >
3400 echo floor(4.0)
3401< 4.0
3402
3403 Can also be used as a |method|: >
3404 Compute()->floor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003405<
3406 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003407
3408
3409fmod({expr1}, {expr2}) *fmod()*
3410 Return the remainder of {expr1} / {expr2}, even if the
3411 division is not representable. Returns {expr1} - i * {expr2}
3412 for some integer i such that if {expr2} is non-zero, the
3413 result has the same sign as {expr1} and magnitude less than
3414 the magnitude of {expr2}. If {expr2} is zero, the value
3415 returned is zero. The value returned is a |Float|.
3416 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003417 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
3418 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003419 Examples: >
3420 :echo fmod(12.33, 1.22)
3421< 0.13 >
3422 :echo fmod(-12.33, 1.22)
3423< -0.13
3424
3425 Can also be used as a |method|: >
3426 Compute()->fmod(1.22)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003427<
3428 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003429
3430
3431fnameescape({string}) *fnameescape()*
3432 Escape {string} for use as file name command argument. All
3433 characters that have a special meaning, such as '%' and '|'
3434 are escaped with a backslash.
3435 For most systems the characters escaped are
3436 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3437 appears in a filename, it depends on the value of 'isfname'.
3438 A leading '+' and '>' is also escaped (special after |:edit|
3439 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01003440 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003441 Example: >
3442 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003443 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003444< results in executing: >
3445 edit \+some\ str\%nge\|name
3446<
3447 Can also be used as a |method|: >
3448 GetName()->fnameescape()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003449<
3450 Return type: |String|
3451
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003452
3453fnamemodify({fname}, {mods}) *fnamemodify()*
3454 Modify file name {fname} according to {mods}. {mods} is a
3455 string of characters like it is used for file names on the
3456 command line. See |filename-modifiers|.
3457 Example: >
3458 :echo fnamemodify("main.c", ":p:h")
3459< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01003460 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01003461< If {mods} is empty or an unsupported modifier is used then
3462 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01003463 When {fname} is empty then with {mods} ":h" returns ".", so
3464 that `:cd` can be used with it. This is different from
3465 expand('%:h') without a buffer name, which returns an empty
3466 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003467 Note: Environment variables don't work in {fname}, use
3468 |expand()| first then.
3469
3470 Can also be used as a |method|: >
3471 GetName()->fnamemodify(':p:h')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003472<
3473 Return type: |String|
3474
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003475
3476foldclosed({lnum}) *foldclosed()*
3477 The result is a Number. If the line {lnum} is in a closed
3478 fold, the result is the number of the first line in that fold.
3479 If the line {lnum} is not in a closed fold, -1 is returned.
3480 {lnum} is used like with |getline()|. Thus "." is the current
3481 line, "'m" mark m, etc.
3482
3483 Can also be used as a |method|: >
3484 GetLnum()->foldclosed()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003485<
3486 Return type: |Number|
3487
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003488
3489foldclosedend({lnum}) *foldclosedend()*
3490 The result is a Number. If the line {lnum} is in a closed
3491 fold, the result is the number of the last line in that fold.
3492 If the line {lnum} is not in a closed fold, -1 is returned.
3493 {lnum} is used like with |getline()|. Thus "." is the current
3494 line, "'m" mark m, etc.
3495
3496 Can also be used as a |method|: >
3497 GetLnum()->foldclosedend()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003498<
3499 Return type: |Number|
3500
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003501
3502foldlevel({lnum}) *foldlevel()*
3503 The result is a Number, which is the foldlevel of line {lnum}
3504 in the current buffer. For nested folds the deepest level is
3505 returned. If there is no fold at line {lnum}, zero is
3506 returned. It doesn't matter if the folds are open or closed.
3507 When used while updating folds (from 'foldexpr') -1 is
3508 returned for lines where folds are still to be updated and the
3509 foldlevel is unknown. As a special case the level of the
3510 previous line is usually available.
3511 {lnum} is used like with |getline()|. Thus "." is the current
3512 line, "'m" mark m, etc.
3513
3514 Can also be used as a |method|: >
3515 GetLnum()->foldlevel()
3516<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003517 Return type: |Number|
3518
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003519 *foldtext()*
3520foldtext() Returns a String, to be displayed for a closed fold. This is
3521 the default function used for the 'foldtext' option and should
3522 only be called from evaluating 'foldtext'. It uses the
3523 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3524 The returned string looks like this: >
3525 +-- 45 lines: abcdef
3526< The number of leading dashes depends on the foldlevel. The
3527 "45" is the number of lines in the fold. "abcdef" is the text
3528 in the first non-blank line of the fold. Leading white space,
3529 "//" or "/*" and the text from the 'foldmarker' and
3530 'commentstring' options is removed.
3531 When used to draw the actual foldtext, the rest of the line
3532 will be filled with the fold char from the 'fillchars'
3533 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003534 Returns an empty string when there is no fold.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003535
3536 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003537 {not available when compiled without the |+folding| feature}
3538
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003539
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003540foldtextresult({lnum}) *foldtextresult()*
3541 Returns the text that is displayed for the closed fold at line
3542 {lnum}. Evaluates 'foldtext' in the appropriate context.
3543 When there is no closed fold at {lnum} an empty string is
3544 returned.
3545 {lnum} is used like with |getline()|. Thus "." is the current
3546 line, "'m" mark m, etc.
3547 Useful when exporting folded text, e.g., to HTML.
3548 {not available when compiled without the |+folding| feature}
3549
3550
3551 Can also be used as a |method|: >
3552 GetLnum()->foldtextresult()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003553<
3554 Return type: |String|
3555
Ernie Raele79e2072024-01-13 11:47:33 +01003556
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01003557foreach({expr1}, {expr2}) *foreach()* *E1525*
3558 {expr1} must be a |List|, |Tuple|, |String|, |Blob| or
3559 |Dictionary|.
Ernie Raele79e2072024-01-13 11:47:33 +01003560 For each item in {expr1} execute {expr2}. {expr1} is not
erraelc92b8be2024-01-14 10:11:07 -08003561 modified; its values may be, as with |:lockvar| 1. |E741|
Ernie Raele79e2072024-01-13 11:47:33 +01003562 See |map()| and |filter()| to modify {expr1}.
3563
3564 {expr2} must be a |string| or |Funcref|.
3565
3566 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3567 of the current item. For a |Dictionary| |v:key| has the key
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01003568 of the current item and for a |List| or a |Tuple| |v:key| has
3569 the index of the current item. For a |Blob| |v:key| has the
3570 index of the current byte. For a |String| |v:key| has the
3571 index of the current character.
Ernie Raele79e2072024-01-13 11:47:33 +01003572 Examples: >
3573 call foreach(mylist, 'used[v:val] = true')
3574< This records the items that are in the {expr1} list.
3575
3576 Note that {expr2} is the result of expression and is then used
3577 as a command. Often it is good to use a |literal-string| to
3578 avoid having to double backslashes.
3579
3580 If {expr2} is a |Funcref| it must take two arguments:
3581 1. the key or the index of the current item.
3582 2. the value of the current item.
3583 With a legacy script lambda you don't get an error if it only
3584 accepts one argument, but with a Vim9 lambda you get "E1106:
3585 One argument too many", the number of arguments must match.
3586 If the function returns a value, it is ignored.
3587
3588 Returns {expr1} in all cases.
3589 When an error is encountered while executing {expr2} no
3590 further items in {expr1} are processed.
3591 When {expr2} is a Funcref errors inside a function are ignored,
3592 unless it was defined with the "abort" flag.
3593
3594 Can also be used as a |method|: >
3595 mylist->foreach(expr2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003596<
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01003597 Return type: |String|, |Blob|, list<{type}>, tuple<{type}> or
3598 dict<{type}> depending on {expr1}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003599
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003600 *foreground()*
3601foreground() Move the Vim window to the foreground. Useful when sent from
3602 a client to a Vim server. |remote_send()|
3603 On Win32 systems this might not work, the OS does not always
3604 allow a window to bring itself to the foreground. Use
3605 |remote_foreground()| instead.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003606
3607 Return type: |Number|
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003608 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003609 Win32 console version}
3610
Bram Moolenaaraa534142022-09-15 21:46:02 +01003611fullcommand({name} [, {vim9}]) *fullcommand()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003612 Get the full command name from a short abbreviated command
3613 name; see |20.2| for details on command abbreviations.
3614
3615 The string argument {name} may start with a `:` and can
3616 include a [range], these are skipped and not returned.
Bram Moolenaaraa534142022-09-15 21:46:02 +01003617 Returns an empty string if a command doesn't exist, if it's
3618 ambiguous (for user-defined commands) or cannot be shortened
3619 this way. |vim9-no-shorten|
3620
3621 Without the {vim9} argument uses the current script version.
3622 If {vim9} is present and FALSE then legacy script rules are
3623 used. When {vim9} is present and TRUE then Vim9 rules are
3624 used, e.g. "en" is not a short form of "endif".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003625
3626 For example `fullcommand('s')`, `fullcommand('sub')`,
3627 `fullcommand(':%substitute')` all return "substitute".
3628
3629 Can also be used as a |method|: >
3630 GetName()->fullcommand()
3631<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003632 Return type: |String|
3633
3634
3635funcref({name} [, {arglist}] [, {dict}]) *funcref()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003636 Just like |function()|, but the returned Funcref will lookup
3637 the function by reference, not by name. This matters when the
3638 function {name} is redefined later.
3639
3640 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003641 It only works for an autoloaded function if it has already
3642 been loaded (to avoid mistakenly loading the autoload script
3643 when only intending to use the function name, use |function()|
3644 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003645 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003646
3647 Can also be used as a |method|: >
3648 GetFuncname()->funcref([arg])
3649<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003650 Return type: func(...): any or |Number| on error
3651
Dominique Pellee764d1b2023-03-12 21:20:59 +00003652 *function()* *partial* *E700* *E923*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003653function({name} [, {arglist}] [, {dict}])
3654 Return a |Funcref| variable that refers to function {name}.
3655 {name} can be the name of a user defined function or an
3656 internal function.
3657
3658 {name} can also be a Funcref or a partial. When it is a
3659 partial the dict stored in it will be used and the {dict}
3660 argument is not allowed. E.g.: >
3661 let FuncWithArg = function(dict.Func, [arg])
3662 let Broken = function(dict.Func, [arg], dict)
3663<
3664 When using the Funcref the function will be found by {name},
3665 also when it was redefined later. Use |funcref()| to keep the
3666 same function.
3667
3668 When {arglist} or {dict} is present this creates a partial.
3669 That means the argument list and/or the dictionary is stored in
3670 the Funcref and will be used when the Funcref is called.
3671
3672 The arguments are passed to the function in front of other
3673 arguments, but after any argument from |method|. Example: >
3674 func Callback(arg1, arg2, name)
3675 ...
3676 let Partial = function('Callback', ['one', 'two'])
3677 ...
3678 call Partial('name')
3679< Invokes the function as with: >
3680 call Callback('one', 'two', 'name')
3681
3682< With a |method|: >
3683 func Callback(one, two, three)
3684 ...
3685 let Partial = function('Callback', ['two'])
3686 ...
3687 eval 'one'->Partial('three')
3688< Invokes the function as with: >
3689 call Callback('one', 'two', 'three')
3690
3691< The function() call can be nested to add more arguments to the
3692 Funcref. The extra arguments are appended to the list of
3693 arguments. Example: >
3694 func Callback(arg1, arg2, name)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003695 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003696 let Func = function('Callback', ['one'])
3697 let Func2 = function(Func, ['two'])
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003698 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003699 call Func2('name')
3700< Invokes the function as with: >
3701 call Callback('one', 'two', 'name')
3702
3703< The Dictionary is only useful when calling a "dict" function.
3704 In that case the {dict} is passed in as "self". Example: >
3705 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003706 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003707 endfunction
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003708 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003709 let context = {"name": "example"}
3710 let Func = function('Callback', context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003711 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003712 call Func() " will echo: called for example
3713< The use of function() is not needed when there are no extra
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003714 arguments, these two are equivalent, if Callback() is defined
3715 as context.Callback(): >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003716 let Func = function('Callback', context)
3717 let Func = context.Callback
3718
3719< The argument list and the Dictionary can be combined: >
3720 function Callback(arg1, count) dict
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003721 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003722 let context = {"name": "example"}
3723 let Func = function('Callback', ['one'], context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003724 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003725 call Func(500)
3726< Invokes the function as with: >
3727 call context.Callback('one', 500)
3728<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003729 Returns 0 on error.
3730
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003731 Can also be used as a |method|: >
3732 GetFuncname()->function([arg])
3733
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003734<
3735 Return type: func(...): any or |Number| on error
3736
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003737
3738garbagecollect([{atexit}]) *garbagecollect()*
3739 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3740 that have circular references.
3741
3742 There is hardly ever a need to invoke this function, as it is
3743 automatically done when Vim runs out of memory or is waiting
3744 for the user to press a key after 'updatetime'. Items without
3745 circular references are always freed when they become unused.
3746 This is useful if you have deleted a very big |List| and/or
3747 |Dictionary| with circular references in a script that runs
3748 for a long time.
3749
3750 When the optional {atexit} argument is one, garbage
3751 collection will also be done when exiting Vim, if it wasn't
3752 done before. This is useful when checking for memory leaks.
3753
3754 The garbage collection is not done immediately but only when
3755 it's safe to perform. This is when waiting for the user to
3756 type a character. To force garbage collection immediately use
3757 |test_garbagecollect_now()|.
3758
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003759 Return type: |String|
3760
3761
LemonBoy48b7d052024-07-09 18:24:59 +02003762get({list}, {idx} [, {default}]) *get()* *get()-list*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003763 Get item {idx} from |List| {list}. When this item is not
3764 available return {default}. Return zero when {default} is
3765 omitted.
3766 Preferably used as a |method|: >
3767 mylist->get(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003768<
3769 Return type: any, depending on {list}
3770
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01003771get({tuple}, {idx} [, {default}]) *get()-tuple*
3772 Get item {idx} from |Tuple| {tuple}. When this item is not
3773 available return {default}. Return zero when {default} is
3774 omitted.
3775 Preferably used as a |method|: >
3776 mytuple->get(idx)
3777<
3778 Return type: any, depending on {tuple}
3779
LemonBoy48b7d052024-07-09 18:24:59 +02003780get({blob}, {idx} [, {default}]) *get()-blob*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003781 Get byte {idx} from |Blob| {blob}. When this byte is not
3782 available return {default}. Return -1 when {default} is
3783 omitted.
3784 Preferably used as a |method|: >
3785 myblob->get(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003786<
3787 Return type: |Number|
3788
LemonBoy48b7d052024-07-09 18:24:59 +02003789get({dict}, {key} [, {default}]) *get()-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003790 Get item with key {key} from |Dictionary| {dict}. When this
3791 item is not available return {default}. Return zero when
3792 {default} is omitted. Useful example: >
3793 let val = get(g:, 'var_name', 'default')
3794< This gets the value of g:var_name if it exists, and uses
3795 'default' when it does not exist.
3796 Preferably used as a |method|: >
3797 mydict->get(key)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003798<
h-east84ac2122024-06-17 18:12:30 +02003799 Return type: any, depending on {dict}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003800
LemonBoy48b7d052024-07-09 18:24:59 +02003801get({func}, {what}) *get()-func*
3802 Get item {what} from |Funcref| {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003803 {what} are:
LemonBoy48b7d052024-07-09 18:24:59 +02003804 "name" The function name
3805 "func" The function
3806 "dict" The dictionary
3807 "args" The list with arguments
3808 "arity" A dictionary with information about the number of
3809 arguments accepted by the function (minus the
3810 {arglist}) with the following fields:
3811 required the number of positional arguments
3812 optional the number of optional arguments,
3813 in addition to the required ones
3814 varargs |TRUE| if the function accepts a
3815 variable number of arguments |...|
3816
3817 Note: There is no error, if the {arglist} of
3818 the Funcref contains more arguments than the
3819 Funcref expects, it's not validated.
3820
Bram Moolenaar016188f2022-06-06 20:52:59 +01003821 Returns zero on error.
LemonBoy48b7d052024-07-09 18:24:59 +02003822
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003823 Preferably used as a |method|: >
3824 myfunc->get(what)
3825<
LemonBoy48b7d052024-07-09 18:24:59 +02003826 Return type: any, depending on {func} and {what}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003827
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003828 *getbufinfo()*
3829getbufinfo([{buf}])
3830getbufinfo([{dict}])
3831 Get information about buffers as a List of Dictionaries.
3832
3833 Without an argument information about all the buffers is
3834 returned.
3835
3836 When the argument is a |Dictionary| only the buffers matching
3837 the specified criteria are returned. The following keys can
3838 be specified in {dict}:
3839 buflisted include only listed buffers.
3840 bufloaded include only loaded buffers.
3841 bufmodified include only modified buffers.
3842
3843 Otherwise, {buf} specifies a particular buffer to return
3844 information for. For the use of {buf}, see |bufname()|
3845 above. If the buffer is found the returned List has one item.
3846 Otherwise the result is an empty list.
3847
3848 Each returned List item is a dictionary with the following
3849 entries:
3850 bufnr Buffer number.
3851 changed TRUE if the buffer is modified.
3852 changedtick Number of changes made to the buffer.
Sean Dewar1fb41032023-08-16 17:15:05 +01003853 command TRUE if the buffer belongs to the
3854 command-line window |cmdwin|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003855 hidden TRUE if the buffer is hidden.
3856 lastused Timestamp in seconds, like
3857 |localtime()|, when the buffer was
3858 last used.
3859 {only with the |+viminfo| feature}
3860 listed TRUE if the buffer is listed.
3861 lnum Line number used for the buffer when
3862 opened in the current window.
3863 Only valid if the buffer has been
3864 displayed in the window in the past.
3865 If you want the line number of the
3866 last known cursor position in a given
3867 window, use |line()|: >
3868 :echo line('.', {winid})
3869<
3870 linecount Number of lines in the buffer (only
3871 valid when loaded)
3872 loaded TRUE if the buffer is loaded.
3873 name Full path to the file in the buffer.
3874 signs List of signs placed in the buffer.
3875 Each list item is a dictionary with
3876 the following fields:
3877 id sign identifier
3878 lnum line number
3879 name sign name
3880 variables A reference to the dictionary with
3881 buffer-local variables.
3882 windows List of |window-ID|s that display this
3883 buffer
3884 popups List of popup |window-ID|s that
3885 display this buffer
3886
3887 Examples: >
3888 for buf in getbufinfo()
3889 echo buf.name
3890 endfor
3891 for buf in getbufinfo({'buflisted':1})
3892 if buf.changed
3893 ....
3894 endif
3895 endfor
3896<
3897 To get buffer-local options use: >
3898 getbufvar({bufnr}, '&option_name')
3899<
3900 Can also be used as a |method|: >
3901 GetBufnr()->getbufinfo()
3902<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003903 Return type: list<dict<any>>
3904
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003905
3906 *getbufline()*
3907getbufline({buf}, {lnum} [, {end}])
3908 Return a |List| with the lines starting from {lnum} to {end}
3909 (inclusive) in the buffer {buf}. If {end} is omitted, a
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003910 |List| with only the line {lnum} is returned. See
3911 `getbufoneline()` for only getting the line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003912
3913 For the use of {buf}, see |bufname()| above.
3914
3915 For {lnum} and {end} "$" can be used for the last line of the
3916 buffer. Otherwise a number must be used.
3917
3918 When {lnum} is smaller than 1 or bigger than the number of
3919 lines in the buffer, an empty |List| is returned.
3920
3921 When {end} is greater than the number of lines in the buffer,
3922 it is treated as {end} is set to the number of lines in the
3923 buffer. When {end} is before {lnum} an empty |List| is
3924 returned.
3925
3926 This function works only for loaded buffers. For unloaded and
3927 non-existing buffers, an empty |List| is returned.
3928
3929 Example: >
3930 :let lines = getbufline(bufnr("myfile"), 1, "$")
3931
3932< Can also be used as a |method|: >
3933 GetBufnr()->getbufline(lnum)
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003934<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003935 Return type: list<string>
3936
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003937 *getbufoneline()*
3938getbufoneline({buf}, {lnum})
3939 Just like `getbufline()` but only get one line and return it
3940 as a string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003941
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003942 Return type: |String|
3943
3944
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003945getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3946 The result is the value of option or local buffer variable
3947 {varname} in buffer {buf}. Note that the name without "b:"
3948 must be used.
3949 The {varname} argument is a string.
3950 When {varname} is empty returns a |Dictionary| with all the
3951 buffer-local variables.
3952 When {varname} is equal to "&" returns a |Dictionary| with all
3953 the buffer-local options.
3954 Otherwise, when {varname} starts with "&" returns the value of
3955 a buffer-local option.
3956 This also works for a global or buffer-local option, but it
3957 doesn't work for a global variable, window-local variable or
3958 window-local option.
3959 For the use of {buf}, see |bufname()| above.
3960 When the buffer or variable doesn't exist {def} or an empty
3961 string is returned, there is no error message.
3962 Examples: >
3963 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003964 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003965
3966< Can also be used as a |method|: >
3967 GetBufnr()->getbufvar(varname)
3968<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003969 Return type: any, depending on {varname}
3970
3971
mikoto20001083cae2024-11-11 21:24:14 +01003972getcellpixels() *getcellpixels()*
3973 Returns a |List| of terminal cell pixel size.
h-eastb534e802024-12-03 20:37:52 +01003974 List format is [xpixel, ypixel].
mikoto2000a73dfc22024-11-18 21:12:21 +01003975
3976 Only works on Unix (terminal and gVim) and Windows (gVim only).
3977 Returns [] on other systems or on failure.
3978 Note that there could be variations across different terminals.
3979 On macOS, system Terminal.app returns sizes in points (before
3980 Retina scaling), whereas third-party terminals return raw pixel
3981 sizes (post Retina scaling).
mikoto20001083cae2024-11-11 21:24:14 +01003982
mikoto2000de094dc2024-11-14 22:13:48 +01003983 Return type: list<any>
mikoto20001083cae2024-11-11 21:24:14 +01003984
3985
Kota Kato66bb9ae2023-01-17 18:31:56 +00003986getcellwidths() *getcellwidths()*
3987 Returns a |List| of cell widths of character ranges overridden
3988 by |setcellwidths()|. The format is equal to the argument of
3989 |setcellwidths()|. If no character ranges have their cell
3990 widths overridden, an empty List is returned.
h-east84ac2122024-06-17 18:12:30 +02003991
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003992 Return type: list<any>
Kota Kato66bb9ae2023-01-17 18:31:56 +00003993
3994
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003995getchangelist([{buf}]) *getchangelist()*
3996 Returns the |changelist| for the buffer {buf}. For the use
3997 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3998 exist, an empty list is returned.
3999
4000 The returned list contains two entries: a list with the change
4001 locations and the current position in the list. Each
4002 entry in the change list is a dictionary with the following
4003 entries:
4004 col column number
4005 coladd column offset for 'virtualedit'
4006 lnum line number
4007 If buffer {buf} is the current buffer, then the current
4008 position refers to the position in the list. For other
4009 buffers, it is set to the length of the list.
4010
4011 Can also be used as a |method|: >
4012 GetBufnr()->getchangelist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004013<
4014 Return type: list<any>
4015
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004016
zeertzjqe0a2ab32025-02-02 09:14:35 +01004017getchar([{expr} [, {opts}]]) *getchar()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004018 Get a single character from the user or input stream.
zeertzjqe0a2ab32025-02-02 09:14:35 +01004019 If {expr} is omitted or is -1, wait until a character is
4020 available.
Doug Kearns9cd9e752024-04-07 17:42:17 +02004021 If {expr} is 0, only get a character when one is available.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004022 Return zero otherwise.
Doug Kearns9cd9e752024-04-07 17:42:17 +02004023 If {expr} is 1, only check if a character is available, it is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004024 not consumed. Return zero if no character available.
zeertzjqe0a2ab32025-02-02 09:14:35 +01004025 If you prefer always getting a string use |getcharstr()|, or
4026 specify |FALSE| as "number" in {opts}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004027
Doug Kearns9cd9e752024-04-07 17:42:17 +02004028 Without {expr} and when {expr} is 0 a whole character or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004029 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01004030 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004031 Otherwise a String is returned with the encoded character.
4032 For a special key it's a String with a sequence of bytes
4033 starting with 0x80 (decimal: 128). This is the same value as
4034 the String "\<Key>", e.g., "\<Left>". The returned value is
4035 also a String when a modifier (shift, control, alt) was used
zeertzjqe0a2ab32025-02-02 09:14:35 +01004036 that is not included in the character. |keytrans()| can also
4037 be used to convert a returned String into a readable form.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004038
Doug Kearns9cd9e752024-04-07 17:42:17 +02004039 When {expr} is 0 and Esc is typed, there will be a short delay
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004040 while Vim waits to see if this is the start of an escape
4041 sequence.
4042
Doug Kearns9cd9e752024-04-07 17:42:17 +02004043 When {expr} is 1 only the first byte is returned. For a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004044 one-byte character it is the character itself as a number.
4045 Use nr2char() to convert it to a String.
4046
4047 Use getcharmod() to obtain any additional modifiers.
4048
zeertzjqe0a2ab32025-02-02 09:14:35 +01004049 The optional argument {opts} is a Dict and supports the
4050 following items:
4051
zeertzjqedf0f7d2025-02-02 19:01:01 +01004052 cursor A String specifying cursor behavior
4053 when waiting for a character.
4054 "hide": hide the cursor.
4055 "keep": keep current cursor unchanged.
4056 "msg": move cursor to message area.
4057 (default: "msg")
4058
zeertzjqe0a2ab32025-02-02 09:14:35 +01004059 number If |TRUE|, return a Number when getting
4060 a single character.
4061 If |FALSE|, the return value is always
4062 converted to a String, and an empty
4063 String (instead of 0) is returned when
4064 no character is available.
4065 (default: |TRUE|)
4066
4067 simplify If |TRUE|, include modifiers in the
4068 character if possible. E.g., return
4069 the same value for CTRL-I and <Tab>.
4070 If |FALSE|, don't include modifiers in
4071 the character.
4072 (default: |TRUE|)
4073
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004074 When the user clicks a mouse button, the mouse event will be
4075 returned. The position can then be found in |v:mouse_col|,
4076 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
4077 |getmousepos()| can also be used. Mouse move events will be
4078 ignored.
4079 This example positions the mouse as it would normally happen: >
4080 let c = getchar()
4081 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004082 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004083 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004084 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004085 endif
4086<
4087 When using bracketed paste only the first character is
4088 returned, the rest of the pasted text is dropped.
4089 |xterm-bracketed-paste|.
4090
4091 There is no prompt, you will somehow have to make clear to the
4092 user that a character has to be typed. The screen is not
4093 redrawn, e.g. when resizing the window. When using a popup
4094 window it should work better with a |popup-filter|.
4095
4096 There is no mapping for the character.
4097 Key codes are replaced, thus when the user presses the <Del>
4098 key you get the code for the <Del> key, not the raw character
4099 sequence. Examples: >
4100 getchar() == "\<Del>"
4101 getchar() == "\<S-Left>"
4102< This example redefines "f" to ignore case: >
4103 :nmap f :call FindChar()<CR>
4104 :function FindChar()
4105 : let c = nr2char(getchar())
4106 : while col('.') < col('$') - 1
4107 : normal l
4108 : if getline('.')[col('.') - 1] ==? c
4109 : break
4110 : endif
4111 : endwhile
4112 :endfunction
4113<
4114 You may also receive synthetic characters, such as
4115 |<CursorHold>|. Often you will want to ignore this and get
4116 another character: >
4117 :function GetKey()
4118 : let c = getchar()
4119 : while c == "\<CursorHold>"
4120 : let c = getchar()
4121 : endwhile
4122 : return c
4123 :endfunction
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004124<
4125 Return type: |Number| or |String|
4126
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004127
4128getcharmod() *getcharmod()*
4129 The result is a Number which is the state of the modifiers for
4130 the last obtained character with getchar() or in another way.
4131 These values are added together:
4132 2 shift
4133 4 control
4134 8 alt (meta)
4135 16 meta (when it's different from ALT)
4136 32 mouse double click
4137 64 mouse triple click
4138 96 mouse quadruple click (== 32 + 64)
Casey Tucker92e90a12024-01-25 22:44:00 +01004139 128 command (Mac) or super (GTK)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004140 Only the modifiers that have not been included in the
4141 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01004142 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004143
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004144 Return type: |Number|
4145
4146
4147getcharpos({expr}) *getcharpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004148 Get the position for String {expr}. Same as |getpos()| but the
4149 column number in the returned List is a character index
4150 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00004151 If |getpos()| returns a very large column number, equal to
4152 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004153 of the last character.
4154
4155 Example:
4156 With the cursor on '세' in line 5 with text "여보세요": >
4157 getcharpos('.') returns [0, 5, 3, 0]
4158 getpos('.') returns [0, 5, 7, 0]
4159<
4160 Can also be used as a |method|: >
4161 GetMark()->getcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004162<
4163 Return type: list<number>
4164
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004165
4166getcharsearch() *getcharsearch()*
4167 Return the current character search information as a {dict}
4168 with the following entries:
4169
4170 char character previously used for a character
4171 search (|t|, |f|, |T|, or |F|); empty string
4172 if no character search has been performed
4173 forward direction of character search; 1 for forward,
4174 0 for backward
4175 until type of character search; 1 for a |t| or |T|
4176 character search, 0 for an |f| or |F|
4177 character search
4178
4179 This can be useful to always have |;| and |,| search
4180 forward/backward regardless of the direction of the previous
4181 character search: >
4182 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
4183 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
4184< Also see |setcharsearch()|.
4185
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004186 Return type: dict<any>
4187
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004188
zeertzjqe0a2ab32025-02-02 09:14:35 +01004189getcharstr([{expr} [, {opts}]]) *getcharstr()*
4190 The same as |getchar()|, except that this always returns a
4191 String, and "number" isn't allowed in {opts}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004192
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004193 Return type: |String|
4194
Ruslan Russkikh0407d622024-10-08 22:21:05 +02004195getcmdcomplpat() *getcmdcomplpat()*
4196 Return completion pattern of the current command-line.
4197 Only works when the command line is being edited, thus
4198 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
4199 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
4200 |getcmdprompt()|, |getcmdcompltype()| and |setcmdline()|.
4201 Returns an empty string when completion is not defined.
4202
4203 Return type: |String|
4204
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004205
Hirohito Higashi96b3ef22025-07-05 15:31:23 +02004206getcmdcompltype() *getcmdcompltype()*
4207 Return the type of the current command-line completion.
4208 Only works when the command line is being edited, thus
4209 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01004210 See |:command-completion| for the return string.
Shougo Matsushita69084282024-09-23 20:34:47 +02004211 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
Ruslan Russkikh0407d622024-10-08 22:21:05 +02004212 |getcmdprompt()|, |getcmdcomplpat()| and |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004213 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004214
zeertzjqe2c0f812025-07-06 20:26:56 +02004215 To get the type of the command-line completion for a specified
4216 string, use |getcompletiontype()|.
Hirohito Higashi96b3ef22025-07-05 15:31:23 +02004217
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004218 Return type: |String|
4219
4220
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004221getcmdline() *getcmdline()*
Shougo Matsushita69084282024-09-23 20:34:47 +02004222 Return the current command-line input. Only works when the
4223 command line is being edited, thus requires use of
4224 |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004225 Example: >
4226 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Shougo Matsushita69084282024-09-23 20:34:47 +02004227< Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()|,
4228 |getcmdprompt()| and |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004229 Returns an empty string when entering a password or using
4230 |inputsecret()|.
4231
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004232 Return type: |String|
4233
4234
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004235getcmdpos() *getcmdpos()*
4236 Return the position of the cursor in the command line as a
4237 byte count. The first column is 1.
4238 Only works when editing the command line, thus requires use of
4239 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4240 Returns 0 otherwise.
Shougo Matsushita69084282024-09-23 20:34:47 +02004241 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
4242 |getcmdprompt()| and |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004243
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004244 Return type: |Number|
4245
4246
Shougo Matsushita69084282024-09-23 20:34:47 +02004247getcmdprompt() *getcmdprompt()*
4248 Return the current command-line prompt when using functions
4249 like |input()| or |confirm()|.
4250 Only works when the command line is being edited, thus
4251 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
4252 Also see |getcmdtype()|, |getcmdline()|, |getcmdpos()|,
4253 |setcmdpos()| and |setcmdline()|.
4254
4255 Return type: |String|
4256
4257
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004258getcmdscreenpos() *getcmdscreenpos()*
4259 Return the screen position of the cursor in the command line
4260 as a byte count. The first column is 1.
4261 Instead of |getcmdpos()|, it adds the prompt position.
4262 Only works when editing the command line, thus requires use of
4263 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4264 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01004265 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
4266 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004267
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004268 Return type: |Number|
4269
4270
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004271getcmdtype() *getcmdtype()*
4272 Return the current command-line type. Possible return values
4273 are:
4274 : normal Ex command
4275 > debug mode command |debug-mode|
4276 / forward search command
4277 ? backward search command
4278 @ |input()| command
4279 - |:insert| or |:append| command
4280 = |i_CTRL-R_=|
4281 Only works when editing the command line, thus requires use of
4282 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4283 Returns an empty string otherwise.
4284 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
4285
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004286 Return type: |String|
4287
4288
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004289getcmdwintype() *getcmdwintype()*
4290 Return the current |command-line-window| type. Possible return
4291 values are the same as |getcmdtype()|. Returns an empty string
4292 when not in the command-line window.
4293
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004294 Return type: |String|
4295
4296
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004297getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
4298 Return a list of command-line completion matches. The String
4299 {type} argument specifies what for. The following completion
4300 types are supported:
4301
4302 arglist file names in argument list
4303 augroup autocmd groups
4304 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00004305 behave |:behave| suboptions
4306 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004307 color color schemes
4308 command Ex command
4309 cmdline |cmdline-completion| result
4310 compiler compilers
4311 cscope |:cscope| suboptions
Shougo Matsushita92997dd2023-08-20 20:55:55 +02004312 custom,{func} custom completion, defined via {func}
4313 customlist,{func} custom completion, defined via {func}
zeertzjq85f36d62024-10-10 19:14:13 +02004314 diff_buffer |:diffget| and |:diffput| completion
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004315 dir directory names
LemonBoya20bf692024-07-11 22:35:53 +02004316 dir_in_path directory names in |'cdpath'|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004317 environment environment variable names
4318 event autocommand events
4319 expression Vim expression
4320 file file and directory names
4321 file_in_path file and directory names in |'path'|
4322 filetype filetype names |'filetype'|
Christian Brabandta3422aa2025-04-23 21:04:24 +02004323 filetypecmd |:filetype| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004324 function function name
4325 help help subjects
4326 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00004327 history |:history| suboptions
Doug Kearns81642d92024-01-04 22:37:44 +01004328 keymap keyboard mappings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004329 locale locale names (as output of locale -a)
4330 mapclear buffer argument
4331 mapping mapping name
4332 menu menus
4333 messages |:messages| suboptions
4334 option options
4335 packadd optional package |pack-add| names
zeertzjq5c8771b2023-01-24 12:34:03 +00004336 runtime |:runtime| completion
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00004337 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004338 shellcmd Shell command
zeertzjq85f36d62024-10-10 19:14:13 +02004339 shellcmdline Shell command line with filename arguments
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004340 sign |:sign| suboptions
4341 syntax syntax file names |'syntax'|
4342 syntime |:syntime| suboptions
4343 tag tags
4344 tag_listfiles tags, file names
4345 user user names
4346 var user variables
4347
4348 If {pat} is an empty string, then all the matches are
4349 returned. Otherwise only items matching {pat} are returned.
4350 See |wildcards| for the use of special characters in {pat}.
4351
4352 If the optional {filtered} flag is set to 1, then 'wildignore'
4353 is applied to filter the results. Otherwise all the matches
4354 are returned. The 'wildignorecase' option always applies.
4355
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00004356 If the 'wildoptions' option contains 'fuzzy', then fuzzy
4357 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00004358 regular expression matching is used. Thus this function
4359 follows the user preference, what happens on the command line.
4360 If you do not want this you can make 'wildoptions' empty
4361 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00004362
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004363 If {type} is "cmdline", then the |cmdline-completion| result is
4364 returned. For example, to complete the possible values after
4365 a ":call" command: >
4366 echo getcompletion('call ', 'cmdline')
4367<
4368 If there are no matches, an empty list is returned. An
4369 invalid value for {type} produces an error.
4370
4371 Can also be used as a |method|: >
4372 GetPattern()->getcompletion('color')
4373<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004374 Return type: list<string>
4375
Hirohito Higashi96b3ef22025-07-05 15:31:23 +02004376getcompletiontype({pat}) *getcompletiontype()*
4377 Return the type of the command-line completion using {pat}.
4378 When no corresponding completion type is found, an empty
4379 string is returned.
4380 To get the current command-line completion type, use
4381 |getcmdcompltype()|.
4382
4383 Return type: |String|
4384
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004385 *getcurpos()*
4386getcurpos([{winid}])
4387 Get the position of the cursor. This is like getpos('.'), but
4388 includes an extra "curswant" item in the list:
4389 [0, lnum, col, off, curswant] ~
4390 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00004391 cursor vertically. After |$| command it will be a very large
4392 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004393 |getpos()|.
4394 The first "bufnum" item is always zero. The byte position of
4395 the cursor is returned in 'col'. To get the character
4396 position, use |getcursorcharpos()|.
4397
4398 The optional {winid} argument can specify the window. It can
4399 be the window number or the |window-ID|. The last known
4400 cursor position is returned, this may be invalid for the
4401 current value of the buffer if it is not the current window.
4402 If {winid} is invalid a list with zeroes is returned.
4403
4404 This can be used to save and restore the cursor position: >
4405 let save_cursor = getcurpos()
4406 MoveTheCursorAround
4407 call setpos('.', save_cursor)
4408< Note that this only works within the window. See
4409 |winrestview()| for restoring more state.
4410
4411 Can also be used as a |method|: >
4412 GetWinid()->getcurpos()
4413<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004414 Return type: list<number>
4415
4416
4417getcursorcharpos([{winid}]) *getcursorcharpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004418 Same as |getcurpos()| but the column number in the returned
4419 List is a character index instead of a byte index.
4420
4421 Example:
4422 With the cursor on '보' in line 3 with text "여보세요": >
4423 getcursorcharpos() returns [0, 3, 2, 0, 3]
4424 getcurpos() returns [0, 3, 4, 0, 3]
4425<
4426 Can also be used as a |method|: >
4427 GetWinid()->getcursorcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004428<
4429 Return type: list<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004430
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004431
4432getcwd([{winnr} [, {tabnr}]]) *getcwd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004433 The result is a String, which is the name of the current
4434 working directory. 'autochdir' is ignored.
4435
4436 With {winnr} return the local current directory of this window
4437 in the current tab page. {winnr} can be the window number or
4438 the |window-ID|.
4439 If {winnr} is -1 return the name of the global working
4440 directory. See also |haslocaldir()|.
4441
4442 With {winnr} and {tabnr} return the local current directory of
4443 the window in the specified tab page. If {winnr} is -1 return
4444 the working directory of the tabpage.
4445 If {winnr} is zero use the current window, if {tabnr} is zero
4446 use the current tabpage.
4447 Without any arguments, return the actual working directory of
4448 the current window.
4449 Return an empty string if the arguments are invalid.
4450
4451 Examples: >
4452 " Get the working directory of the current window
4453 :echo getcwd()
4454 :echo getcwd(0)
4455 :echo getcwd(0, 0)
4456 " Get the working directory of window 3 in tabpage 2
4457 :echo getcwd(3, 2)
4458 " Get the global working directory
4459 :echo getcwd(-1)
4460 " Get the working directory of tabpage 3
4461 :echo getcwd(-1, 3)
4462 " Get the working directory of current tabpage
4463 :echo getcwd(-1, 0)
4464
4465< Can also be used as a |method|: >
4466 GetWinnr()->getcwd()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004467<
4468 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004469
4470getenv({name}) *getenv()*
4471 Return the value of environment variable {name}. The {name}
4472 argument is a string, without a leading '$'. Example: >
4473 myHome = getenv('HOME')
4474
4475< When the variable does not exist |v:null| is returned. That
4476 is different from a variable set to an empty string, although
4477 some systems interpret the empty value as the variable being
4478 deleted. See also |expr-env|.
4479
4480 Can also be used as a |method|: >
4481 GetVarname()->getenv()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004482<
4483 Return type: |String| or |Number|
4484
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004485
4486getfontname([{name}]) *getfontname()*
4487 Without an argument returns the name of the normal font being
4488 used. Like what is used for the Normal highlight group
4489 |hl-Normal|.
4490 With an argument a check is done whether String {name} is a
4491 valid font name. If not then an empty string is returned.
4492 Otherwise the actual font name is returned, or {name} if the
4493 GUI does not support obtaining the real name.
4494 Only works when the GUI is running, thus not in your vimrc or
4495 gvimrc file. Use the |GUIEnter| autocommand to use this
4496 function just after the GUI has started.
4497 Note that the GTK GUI accepts any font name, thus checking for
4498 a valid name does not work.
4499
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004500 Return type: |String|
4501
4502
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004503getfperm({fname}) *getfperm()*
4504 The result is a String, which is the read, write, and execute
4505 permissions of the given file {fname}.
4506 If {fname} does not exist or its directory cannot be read, an
4507 empty string is returned.
4508 The result is of the form "rwxrwxrwx", where each group of
4509 "rwx" flags represent, in turn, the permissions of the owner
4510 of the file, the group the file belongs to, and other users.
4511 If a user does not have a given permission the flag for this
4512 is replaced with the string "-". Examples: >
4513 :echo getfperm("/etc/passwd")
4514 :echo getfperm(expand("~/.vimrc"))
4515< This will hopefully (from a security point of view) display
4516 the string "rw-r--r--" or even "rw-------".
4517
4518 Can also be used as a |method|: >
4519 GetFilename()->getfperm()
4520<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004521 Return type: |String|
4522
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004523 For setting permissions use |setfperm()|.
4524
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004525
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004526getfsize({fname}) *getfsize()*
4527 The result is a Number, which is the size in bytes of the
4528 given file {fname}.
4529 If {fname} is a directory, 0 is returned.
4530 If the file {fname} can't be found, -1 is returned.
4531 If the size of {fname} is too big to fit in a Number then -2
4532 is returned.
4533
4534 Can also be used as a |method|: >
4535 GetFilename()->getfsize()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004536<
4537 Return type: |Number|
4538
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004539
4540getftime({fname}) *getftime()*
4541 The result is a Number, which is the last modification time of
4542 the given file {fname}. The value is measured as seconds
4543 since 1st Jan 1970, and may be passed to strftime(). See also
4544 |localtime()| and |strftime()|.
4545 If the file {fname} can't be found -1 is returned.
4546
4547 Can also be used as a |method|: >
4548 GetFilename()->getftime()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004549<
4550 Return type: |Number|
4551
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004552
4553getftype({fname}) *getftype()*
4554 The result is a String, which is a description of the kind of
4555 file of the given file {fname}.
4556 If {fname} does not exist an empty string is returned.
4557 Here is a table over different kinds of files and their
4558 results:
4559 Normal file "file"
4560 Directory "dir"
4561 Symbolic link "link"
4562 Block device "bdev"
4563 Character device "cdev"
4564 Socket "socket"
4565 FIFO "fifo"
4566 All other "other"
4567 Example: >
4568 getftype("/home")
4569< Note that a type such as "link" will only be returned on
4570 systems that support it. On some systems only "dir" and
4571 "file" are returned. On MS-Windows a symbolic link to a
4572 directory returns "dir" instead of "link".
4573
4574 Can also be used as a |method|: >
4575 GetFilename()->getftype()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004576<
4577 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004578
4579getimstatus() *getimstatus()*
4580 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01004581 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004582 See 'imstatusfunc'.
4583
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004584 Return type: |Number|
4585
4586
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004587getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
4588 Returns the |jumplist| for the specified window.
4589
4590 Without arguments use the current window.
4591 With {winnr} only use this window in the current tab page.
4592 {winnr} can also be a |window-ID|.
4593 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01004594 page. If {winnr} or {tabnr} is invalid, an empty list is
4595 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004596
4597 The returned list contains two entries: a list with the jump
4598 locations and the last used jump position number in the list.
4599 Each entry in the jump location list is a dictionary with
4600 the following entries:
4601 bufnr buffer number
4602 col column number
4603 coladd column offset for 'virtualedit'
4604 filename filename if available
4605 lnum line number
4606
4607 Can also be used as a |method|: >
4608 GetWinnr()->getjumplist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004609<
4610 Return type: list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004611
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004612 *getline()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004613getline({lnum} [, {end}])
4614 Without {end} the result is a String, which is line {lnum}
4615 from the current buffer. Example: >
4616 getline(1)
4617< When {lnum} is a String that doesn't start with a
4618 digit, |line()| is called to translate the String into a Number.
4619 To get the line under the cursor: >
4620 getline(".")
4621< When {lnum} is a number smaller than 1 or bigger than the
4622 number of lines in the buffer, an empty string is returned.
4623
4624 When {end} is given the result is a |List| where each item is
4625 a line from the current buffer in the range {lnum} to {end},
4626 including line {end}.
4627 {end} is used in the same way as {lnum}.
4628 Non-existing lines are silently omitted.
4629 When {end} is before {lnum} an empty |List| is returned.
4630 Example: >
4631 :let start = line('.')
4632 :let end = search("^$") - 1
4633 :let lines = getline(start, end)
4634
4635< Can also be used as a |method|: >
4636 ComputeLnum()->getline()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004637<
4638 Return type: list<string> or |String| depending on {end}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004639
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004640 To get lines from another buffer see |getbufline()| and
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00004641 |getbufoneline()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004642
4643getloclist({nr} [, {what}]) *getloclist()*
4644 Returns a |List| with all the entries in the location list for
4645 window {nr}. {nr} can be the window number or the |window-ID|.
4646 When {nr} is zero the current window is used.
4647
4648 For a location list window, the displayed location list is
4649 returned. For an invalid window number {nr}, an empty list is
4650 returned. Otherwise, same as |getqflist()|.
4651
4652 If the optional {what} dictionary argument is supplied, then
4653 returns the items listed in {what} as a dictionary. Refer to
4654 |getqflist()| for the supported items in {what}.
4655
4656 In addition to the items supported by |getqflist()| in {what},
4657 the following item is supported by |getloclist()|:
4658
4659 filewinid id of the window used to display files
4660 from the location list. This field is
4661 applicable only when called from a
4662 location list window. See
4663 |location-list-file-window| for more
4664 details.
4665
4666 Returns a |Dictionary| with default values if there is no
4667 location list for the window {nr}.
4668 Returns an empty Dictionary if window {nr} does not exist.
4669
4670 Examples (See also |getqflist-examples|): >
4671 :echo getloclist(3, {'all': 0})
4672 :echo getloclist(5, {'filewinid': 0})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004673<
4674 Return type: list<dict<any>> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004675
4676
4677getmarklist([{buf}]) *getmarklist()*
4678 Without the {buf} argument returns a |List| with information
4679 about all the global marks. |mark|
4680
4681 If the optional {buf} argument is specified, returns the
4682 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01004683 see |bufname()|. If {buf} is invalid, an empty list is
4684 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004685
4686 Each item in the returned List is a |Dict| with the following:
4687 mark name of the mark prefixed by "'"
4688 pos a |List| with the position of the mark:
4689 [bufnum, lnum, col, off]
4690 Refer to |getpos()| for more information.
4691 file file name
4692
4693 Refer to |getpos()| for getting information about a specific
4694 mark.
4695
4696 Can also be used as a |method|: >
4697 GetBufnr()->getmarklist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004698<
4699 Return type: list<dict<any>> or list<any>
4700
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004701
4702getmatches([{win}]) *getmatches()*
4703 Returns a |List| with all matches previously defined for the
4704 current window by |matchadd()| and the |:match| commands.
4705 |getmatches()| is useful in combination with |setmatches()|,
4706 as |setmatches()| can restore a list of matches saved by
4707 |getmatches()|.
4708 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01004709 window ID instead of the current window. If {win} is invalid,
4710 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004711 Example: >
4712 :echo getmatches()
4713< [{'group': 'MyGroup1', 'pattern': 'TODO',
4714 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4715 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4716 :let m = getmatches()
4717 :call clearmatches()
4718 :echo getmatches()
4719< [] >
4720 :call setmatches(m)
4721 :echo getmatches()
4722< [{'group': 'MyGroup1', 'pattern': 'TODO',
4723 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4724 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4725 :unlet m
4726<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004727 Return type: list<dict<any>> or list<any>
4728
4729
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004730getmousepos() *getmousepos()*
4731 Returns a |Dictionary| with the last known position of the
4732 mouse. This can be used in a mapping for a mouse click or in
4733 a filter of a popup window. The items are:
4734 screenrow screen row
4735 screencol screen column
4736 winid Window ID of the click
4737 winrow row inside "winid"
4738 wincol column inside "winid"
4739 line text line inside "winid"
4740 column text column inside "winid"
zeertzjqf5a94d52023-10-15 10:03:30 +02004741 coladd offset (in screen columns) from the
4742 start of the clicked char
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004743 All numbers are 1-based.
4744
Hirohito Higashi3b9b95d2025-06-01 20:22:55 +02004745 If not over a window, e.g. when in the command line or within
4746 |tabpanel|, then only "screenrow" and "screencol" are valid,
4747 the others are zero.
Naruhiko Nishinobe5bd4d2025-05-14 21:20:28 +02004748
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004749 When on the status line below a window or the vertical
4750 separator right of a window, the "line" and "column" values
4751 are zero.
4752
4753 When the position is after the text then "column" is the
4754 length of the text in bytes plus one.
4755
4756 If the mouse is over a popup window then that window is used.
4757
4758 When using |getchar()| the Vim variables |v:mouse_lnum|,
4759 |v:mouse_col| and |v:mouse_winid| also provide these values.
4760
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004761 Return type: dict<number>
4762
4763
Bram Moolenaar24dc19c2022-11-14 19:49:15 +00004764getmouseshape() *getmouseshape()*
4765 Returns the name of the currently showing mouse pointer.
4766 When the |+mouseshape| feature is not supported or the shape
4767 is unknown an empty string is returned.
4768 This function is mainly intended for testing.
4769
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004770 Return type: |String|
4771
4772
4773getpid() *getpid()*
4774 Return a Number which is the process ID of the Vim process.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004775 On Unix and MS-Windows this is a unique number, until Vim
4776 exits.
4777
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004778 Return type: |Number|
4779
4780
4781getpos({expr}) *getpos()*
zeertzjq02f3eba2024-06-12 20:45:24 +02004782 Get the position for String {expr}.
4783 The accepted values for {expr} are: *E1209*
4784 . The cursor position.
4785 $ The last line in the current buffer.
4786 'x Position of mark x (if the mark is not set, 0 is
zeertzjqd353d272024-06-13 23:00:25 +08004787 returned for all values).
zeertzjq02f3eba2024-06-12 20:45:24 +02004788 w0 First line visible in current window (one if the
4789 display isn't updated, e.g. in silent Ex mode).
4790 w$ Last line visible in current window (this is one
4791 less than "w0" if no lines are visible).
4792 v When not in Visual mode, returns the cursor
4793 position. In Visual mode, returns the other end
4794 of the Visual area. A good way to think about
4795 this is that in Visual mode "v" and "." complement
4796 each other. While "." refers to the cursor
4797 position, "v" refers to where |v_o| would move the
4798 cursor. As a result, you can use "v" and "."
4799 together to work on all of a selection in
4800 characterwise Visual mode. If the cursor is at
4801 the end of a characterwise Visual area, "v" refers
4802 to the start of the same Visual area. And if the
4803 cursor is at the start of a characterwise Visual
4804 area, "v" refers to the end of the same Visual
4805 area. "v" differs from |'<| and |'>| in that it's
4806 updated right away.
4807 Note that a mark in another file can be used. The line number
4808 then applies to another buffer.
4809
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004810 The result is a |List| with four numbers:
4811 [bufnum, lnum, col, off]
4812 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4813 is the buffer number of the mark.
4814 "lnum" and "col" are the position in the buffer. The first
4815 column is 1.
4816 The "off" number is zero, unless 'virtualedit' is used. Then
4817 it is the offset in screen columns from the start of the
4818 character. E.g., a position within a <Tab> or after the last
4819 character.
zeertzjq02f3eba2024-06-12 20:45:24 +02004820
4821 For getting the cursor position see |getcurpos()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004822 The column number in the returned List is the byte position
4823 within the line. To get the character position in the line,
4824 use |getcharpos()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02004825
4826 Note that for '< and '> Visual mode matters: when it is "V"
4827 (visual line mode) the column of '< is zero and the column of
4828 '> is a large number equal to |v:maxcol|.
naohiro ono56200ee2022-01-01 14:59:44 +00004829 A very large column number equal to |v:maxcol| can be returned,
4830 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01004831 If {expr} is invalid, returns a list with all zeros.
zeertzjq02f3eba2024-06-12 20:45:24 +02004832
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004833 This can be used to save and restore the position of a mark: >
4834 let save_a_mark = getpos("'a")
4835 ...
4836 call setpos("'a", save_a_mark)
zeertzjqd353d272024-06-13 23:00:25 +08004837<
4838 Also see |getcharpos()|, |getcurpos()| and |setpos()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004839
4840 Can also be used as a |method|: >
4841 GetMark()->getpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004842<
4843 Return type: list<number>
4844
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004845
4846getqflist([{what}]) *getqflist()*
4847 Returns a |List| with all the current quickfix errors. Each
4848 list item is a dictionary with these entries:
4849 bufnr number of buffer that has the file name, use
4850 bufname() to get the name
4851 module module name
4852 lnum line number in the buffer (first line is 1)
4853 end_lnum
4854 end of line number if the item is multiline
4855 col column number (first column is 1)
4856 end_col end of column number if the item has range
4857 vcol |TRUE|: "col" is visual column
4858 |FALSE|: "col" is byte index
4859 nr error number
h-east84ac2122024-06-17 18:12:30 +02004860 pattern search pattern used to locate the error
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004861 text description of the error
4862 type type of the error, 'E', '1', etc.
4863 valid |TRUE|: recognized error message
h_east596a9f22023-11-21 21:24:23 +09004864 user_data
4865 custom data associated with the item, can be
Tom Praschanca6ac992023-08-11 23:26:12 +02004866 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004867
4868 When there is no error list or it's empty, an empty list is
4869 returned. Quickfix list entries with a non-existing buffer
4870 number are returned with "bufnr" set to zero (Note: some
4871 functions accept buffer number zero for the alternate buffer,
4872 you may need to explicitly check for zero).
4873
4874 Useful application: Find pattern matches in multiple files and
4875 do something with them: >
4876 :vimgrep /theword/jg *.c
4877 :for d in getqflist()
4878 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4879 :endfor
4880<
4881 If the optional {what} dictionary argument is supplied, then
4882 returns only the items listed in {what} as a dictionary. The
4883 following string items are supported in {what}:
4884 changedtick get the total number of changes made
4885 to the list |quickfix-changedtick|
4886 context get the |quickfix-context|
4887 efm errorformat to use when parsing "lines". If
4888 not present, then the 'errorformat' option
4889 value is used.
4890 id get information for the quickfix list with
4891 |quickfix-ID|; zero means the id for the
4892 current list or the list specified by "nr"
4893 idx get information for the quickfix entry at this
4894 index in the list specified by 'id' or 'nr'.
4895 If set to zero, then uses the current entry.
4896 See |quickfix-index|
4897 items quickfix list entries
4898 lines parse a list of lines using 'efm' and return
4899 the resulting entries. Only a |List| type is
4900 accepted. The current quickfix list is not
4901 modified. See |quickfix-parse|.
4902 nr get information for this quickfix list; zero
4903 means the current quickfix list and "$" means
4904 the last quickfix list
4905 qfbufnr number of the buffer displayed in the quickfix
4906 window. Returns 0 if the quickfix buffer is
4907 not present. See |quickfix-buffer|.
4908 size number of entries in the quickfix list
4909 title get the list title |quickfix-title|
4910 winid get the quickfix |window-ID|
4911 all all of the above quickfix properties
4912 Non-string items in {what} are ignored. To get the value of a
4913 particular item, set it to zero.
4914 If "nr" is not present then the current quickfix list is used.
4915 If both "nr" and a non-zero "id" are specified, then the list
4916 specified by "id" is used.
4917 To get the number of lists in the quickfix stack, set "nr" to
4918 "$" in {what}. The "nr" value in the returned dictionary
4919 contains the quickfix stack size.
4920 When "lines" is specified, all the other items except "efm"
4921 are ignored. The returned dictionary contains the entry
4922 "items" with the list of entries.
4923
4924 The returned dictionary contains the following entries:
4925 changedtick total number of changes made to the
4926 list |quickfix-changedtick|
4927 context quickfix list context. See |quickfix-context|
4928 If not present, set to "".
4929 id quickfix list ID |quickfix-ID|. If not
4930 present, set to 0.
4931 idx index of the quickfix entry in the list. If not
4932 present, set to 0.
4933 items quickfix list entries. If not present, set to
4934 an empty list.
4935 nr quickfix list number. If not present, set to 0
4936 qfbufnr number of the buffer displayed in the quickfix
4937 window. If not present, set to 0.
4938 size number of entries in the quickfix list. If not
4939 present, set to 0.
4940 title quickfix list title text. If not present, set
4941 to "".
4942 winid quickfix |window-ID|. If not present, set to 0
4943
4944 Examples (See also |getqflist-examples|): >
4945 :echo getqflist({'all': 1})
4946 :echo getqflist({'nr': 2, 'title': 1})
4947 :echo getqflist({'lines' : ["F1:10:L10"]})
4948<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004949 Return type: list<dict<any>> or list<any>
4950
4951
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004952getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4953 The result is a String, which is the contents of register
4954 {regname}. Example: >
4955 :let cliptext = getreg('*')
4956< When register {regname} was not set the result is an empty
4957 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004958 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004959
4960 getreg('=') returns the last evaluated value of the expression
4961 register. (For use in maps.)
4962 getreg('=', 1) returns the expression itself, so that it can
4963 be restored with |setreg()|. For other registers the extra
4964 argument is ignored, thus you can always give it.
4965
4966 If {list} is present and |TRUE|, the result type is changed
4967 to |List|. Each list item is one text line. Use it if you care
4968 about zero bytes possibly present inside register: without
4969 third argument both NLs and zero bytes are represented as NLs
4970 (see |NL-used-for-Nul|).
4971 When the register was not set an empty list is returned.
4972
4973 If {regname} is "", the unnamed register '"' is used.
4974 If {regname} is not specified, |v:register| is used.
4975 In |Vim9-script| {regname} must be one character.
4976
4977 Can also be used as a |method|: >
4978 GetRegname()->getreg()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004979<
Christian Brabandt17ad8522025-05-09 00:03:20 +02004980 Return type: |String| or list<string> depending on {list}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004981
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004982
4983getreginfo([{regname}]) *getreginfo()*
4984 Returns detailed information about register {regname} as a
4985 Dictionary with the following entries:
4986 regcontents List of lines contained in register
4987 {regname}, like
4988 |getreg|({regname}, 1, 1).
4989 regtype the type of register {regname}, as in
4990 |getregtype()|.
4991 isunnamed Boolean flag, v:true if this register
4992 is currently pointed to by the unnamed
4993 register.
4994 points_to for the unnamed register, gives the
4995 single letter name of the register
4996 currently pointed to (see |quotequote|).
4997 For example, after deleting a line
4998 with `dd`, this field will be "1",
4999 which is the register that got the
5000 deleted text.
5001
5002 The {regname} argument is a string. If {regname} is invalid
5003 or not set, an empty Dictionary will be returned.
5004 If {regname} is "" or "@", the unnamed register '"' is used.
5005 If {regname} is not specified, |v:register| is used.
5006 The returned Dictionary can be passed to |setreg()|.
5007 In |Vim9-script| {regname} must be one character.
5008
5009 Can also be used as a |method|: >
5010 GetRegname()->getreginfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005011<
5012 Return type: dict<any>
5013
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005014
Shougo Matsushita19b71882024-02-28 22:48:12 +01005015getregion({pos1}, {pos2} [, {opts}]) *getregion()*
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01005016 Returns the list of strings from {pos1} to {pos2} from a
Shougo Matsushita19b71882024-02-28 22:48:12 +01005017 buffer.
5018
5019 {pos1} and {pos2} must both be |List|s with four numbers.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01005020 See |getpos()| for the format of the list. It's possible
5021 to specify positions from a different buffer, but please
zeertzjq0df8f932024-03-07 21:40:53 +01005022 note the limitations at |getregion-notes|.
Shougo Matsushita19b71882024-02-28 22:48:12 +01005023
5024 The optional argument {opts} is a Dict and supports the
5025 following items:
5026
zeertzjqafc22952024-05-24 19:07:12 +02005027 type Specify the region's selection type.
5028 See |getregtype()| for possible values,
zeertzjqdff55a32024-05-25 10:25:36 +02005029 except that the width can be omitted
5030 and an empty string cannot be used.
zeertzjqafc22952024-05-24 19:07:12 +02005031 (default: "v")
Shougo Matsushita19b71882024-02-28 22:48:12 +01005032
zeertzjq87410ab2024-03-02 06:00:23 +08005033 exclusive If |TRUE|, use exclusive selection
zeertzjqafc22952024-05-24 19:07:12 +02005034 for the end position.
zeertzjq87410ab2024-03-02 06:00:23 +08005035 (default: follow 'selection')
Shougo Matsushita19b71882024-02-28 22:48:12 +01005036
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01005037 You can get the last selection type by |visualmode()|.
5038 If Visual mode is active, use |mode()| to get the Visual mode
5039 (e.g., in a |:vmap|).
zeertzjq87410ab2024-03-02 06:00:23 +08005040 This function is useful to get text starting and ending in
5041 different columns, such as a |characterwise-visual| selection.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01005042
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01005043 *getregion-notes*
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01005044 Note that:
5045 - Order of {pos1} and {pos2} doesn't matter, it will always
5046 return content from the upper left position to the lower
5047 right position.
zeertzjq87410ab2024-03-02 06:00:23 +08005048 - If 'virtualedit' is enabled and the region is past the end
5049 of the lines, resulting lines are padded with spaces.
5050 - If the region is blockwise and it starts or ends in the
5051 middle of a multi-cell character, it is not included but
5052 its selected part is substituted with spaces.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01005053 - If {pos1} and {pos2} are not in the same buffer, an empty
zeertzjq421b5972024-02-22 19:48:06 +01005054 list is returned.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01005055 - {pos1} and {pos2} must belong to a |bufloaded()| buffer.
zeertzjq0df8f932024-03-07 21:40:53 +01005056 - It is evaluated in current window context, which makes a
5057 difference if the buffer is displayed in a window with
5058 different 'virtualedit' or 'list' values.
Christian Brabandtbfeefc42025-06-02 19:56:57 +02005059 - When specifying an exclusive selection and {pos1} and {pos2}
5060 are equal, the returned list contains a single character as
5061 if selection is inclusive, to match the behavior of an empty
5062 exclusive selection in Visual mode.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01005063
5064 Examples: >
5065 :xnoremap <CR>
Shougo Matsushita19b71882024-02-28 22:48:12 +01005066 \ <Cmd>echow getregion(
5067 \ getpos('v'), getpos('.'), #{ type: mode() })<CR>
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01005068<
5069 Can also be used as a |method|: >
Shougo Matsushita19b71882024-02-28 22:48:12 +01005070 getpos('.')->getregion(getpos("'a"))
zeertzjqd4d12072024-07-16 20:34:16 +02005071<
5072 Return type: list<string>
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005073
Yee Cheng Chind52fb2f2024-10-31 09:25:09 +01005074
Shougo Matsushitab4757e62024-05-07 20:49:24 +02005075getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()*
5076 Same as |getregion()|, but returns a list of positions
5077 describing the buffer text segments bound by {pos1} and
5078 {pos2}.
5079 The segments are a pair of positions for every line: >
5080 [[{start_pos}, {end_pos}], ...]
5081<
5082 The position is a |List| with four numbers:
5083 [bufnum, lnum, col, off]
5084 "bufnum" is the buffer number.
5085 "lnum" and "col" are the position in the buffer. The first
5086 column is 1.
zeertzjqc95e64f2024-05-20 14:00:31 +02005087 If the "off" number of a starting position is non-zero, it is
5088 the offset in screen columns from the start of the character.
5089 E.g., a position within a <Tab> or after the last character.
5090 If the "off" number of an ending position is non-zero, it is
zeertzjq52a6f342024-05-22 16:42:44 +02005091 the offset of the character's first cell not included in the
5092 selection, otherwise all its cells are included.
Shougo Matsushitab4757e62024-05-07 20:49:24 +02005093
zeertzjq2b09de92024-05-24 07:48:51 +02005094 Apart from the options supported by |getregion()|, {opts} also
5095 supports the following:
5096
5097 eol If |TRUE|, indicate positions beyond
5098 the end of a line with "col" values
5099 one more than the length of the line.
5100 If |FALSE|, positions are limited
5101 within their lines, and if a line is
5102 empty or the selection is entirely
5103 beyond the end of a line, a "col"
5104 value of 0 is used for both positions.
5105 (default: |FALSE|)
5106
Shougo Matsushitab4757e62024-05-07 20:49:24 +02005107 Can also be used as a |method|: >
5108 getpos('.')->getregionpos(getpos("'a"))
5109<
Christian Brabandt83d74402025-03-19 21:55:59 +01005110 For an example, see the highlight-yank plugin |52.6|
5111
zeertzjqd4d12072024-07-16 20:34:16 +02005112 Return type: list<list<list<number>>>
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005113
5114
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005115getregtype([{regname}]) *getregtype()*
5116 The result is a String, which is type of register {regname}.
5117 The value will be one of:
5118 "v" for |characterwise| text
5119 "V" for |linewise| text
5120 "<CTRL-V>{width}" for |blockwise-visual| text
5121 "" for an empty or unknown register
5122 <CTRL-V> is one character with value 0x16.
5123 The {regname} argument is a string. If {regname} is "", the
5124 unnamed register '"' is used. If {regname} is not specified,
5125 |v:register| is used.
5126 In |Vim9-script| {regname} must be one character.
5127
5128 Can also be used as a |method|: >
5129 GetRegname()->getregtype()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005130<
5131 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005132
Yee Cheng Chind52fb2f2024-10-31 09:25:09 +01005133
Bram Moolenaar71badf92023-04-22 22:40:14 +01005134getscriptinfo([{opts}]) *getscriptinfo()*
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01005135 Returns a |List| with information about all the sourced Vim
Bram Moolenaar753885b2022-08-24 16:30:36 +01005136 scripts in the order they were sourced, like what
5137 `:scriptnames` shows.
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01005138
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005139 The optional Dict argument {opts} supports the following
5140 optional items:
5141 name Script name match pattern. If specified,
5142 and "sid" is not specified, information about
Bram Moolenaar71badf92023-04-22 22:40:14 +01005143 scripts with a name that match the pattern
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005144 "name" are returned.
5145 sid Script ID |<SID>|. If specified, only
5146 information about the script with ID "sid" is
5147 returned and "name" is ignored.
5148
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01005149 Each item in the returned List is a |Dict| with the following
5150 items:
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005151 autoload Set to TRUE for a script that was used with
Bram Moolenaar753885b2022-08-24 16:30:36 +01005152 `import autoload` but was not actually sourced
5153 yet (see |import-autoload|).
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005154 functions List of script-local function names defined in
5155 the script. Present only when a particular
5156 script is specified using the "sid" item in
5157 {opts}.
5158 name Vim script file name.
5159 sid Script ID |<SID>|.
5160 sourced Script ID of the actually sourced script that
Bram Moolenaarfd999452022-08-24 18:30:14 +01005161 this script name links to, if any, otherwise
5162 zero
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005163 variables A dictionary with the script-local variables.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00005164 Present only when a particular script is
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005165 specified using the "sid" item in {opts}.
5166 Note that this is a copy, the value of
5167 script-local variables cannot be changed using
5168 this dictionary.
h_east59858792023-10-25 22:47:05 +09005169 version Vim script version (|scriptversion|)
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01005170
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005171 Examples: >
5172 :echo getscriptinfo({'name': 'myscript'})
zeertzjqad4881c2024-05-04 15:35:30 +08005173 :echo getscriptinfo({'sid': 15})[0].variables
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005174<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005175 Return type: list<dict<any>>
5176
5177
ichizok663d18d2025-01-02 18:06:00 +01005178getstacktrace() *getstacktrace()*
5179 Returns the current stack trace of Vim scripts.
5180 Stack trace is a |List|, of which each item is a |Dictionary|
5181 with the following items:
zeertzjq6655bef2025-01-06 18:32:13 +01005182 funcref The funcref if the stack is at a function,
5183 otherwise this item is omitted.
ichizok663d18d2025-01-02 18:06:00 +01005184 event The string of the event description if the
zeertzjq6655bef2025-01-06 18:32:13 +01005185 stack is at an autocmd event, otherwise this
5186 item is omitted.
5187 lnum The line number in the script on the stack.
ichizok663d18d2025-01-02 18:06:00 +01005188 filepath The file path of the script on the stack.
5189
5190 Return type: list<dict<any>>
5191
5192
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005193gettabinfo([{tabnr}]) *gettabinfo()*
5194 If {tabnr} is not specified, then information about all the
5195 tab pages is returned as a |List|. Each List item is a
5196 |Dictionary|. Otherwise, {tabnr} specifies the tab page
5197 number and information about that one is returned. If the tab
5198 page does not exist an empty List is returned.
5199
5200 Each List item is a |Dictionary| with the following entries:
5201 tabnr tab page number.
5202 variables a reference to the dictionary with
5203 tabpage-local variables
5204 windows List of |window-ID|s in the tab page.
5205
5206 Can also be used as a |method|: >
5207 GetTabnr()->gettabinfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005208<
5209 Return type: list<dict<any>>
5210
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005211
5212gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
5213 Get the value of a tab-local variable {varname} in tab page
5214 {tabnr}. |t:var|
5215 Tabs are numbered starting with one.
5216 The {varname} argument is a string. When {varname} is empty a
5217 dictionary with all tab-local variables is returned.
5218 Note that the name without "t:" must be used.
5219 When the tab or variable doesn't exist {def} or an empty
5220 string is returned, there is no error message.
5221
5222 Can also be used as a |method|: >
5223 GetTabnr()->gettabvar(varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005224<
5225 Return type: any, depending on {varname}
5226
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005227
5228gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
5229 Get the value of window-local variable {varname} in window
5230 {winnr} in tab page {tabnr}.
5231 The {varname} argument is a string. When {varname} is empty a
5232 dictionary with all window-local variables is returned.
5233 When {varname} is equal to "&" get the values of all
5234 window-local options in a |Dictionary|.
5235 Otherwise, when {varname} starts with "&" get the value of a
5236 window-local option.
5237 Note that {varname} must be the name without "w:".
5238 Tabs are numbered starting with one. For the current tabpage
5239 use |getwinvar()|.
5240 {winnr} can be the window number or the |window-ID|.
5241 When {winnr} is zero the current window is used.
5242 This also works for a global option, buffer-local option and
5243 window-local option, but it doesn't work for a global variable
5244 or buffer-local variable.
5245 When the tab, window or variable doesn't exist {def} or an
5246 empty string is returned, there is no error message.
5247 Examples: >
5248 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005249 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005250<
5251 To obtain all window-local variables use: >
5252 gettabwinvar({tabnr}, {winnr}, '&')
5253
5254< Can also be used as a |method|: >
5255 GetTabnr()->gettabwinvar(winnr, varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005256<
5257 Return type: any, depending on {varname}
5258
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005259
5260gettagstack([{winnr}]) *gettagstack()*
5261 The result is a Dict, which is the tag stack of window {winnr}.
5262 {winnr} can be the window number or the |window-ID|.
5263 When {winnr} is not specified, the current window is used.
5264 When window {winnr} doesn't exist, an empty Dict is returned.
5265
5266 The returned dictionary contains the following entries:
5267 curidx Current index in the stack. When at
5268 top of the stack, set to (length + 1).
5269 Index of bottom of the stack is 1.
5270 items List of items in the stack. Each item
5271 is a dictionary containing the
5272 entries described below.
5273 length Number of entries in the stack.
5274
5275 Each item in the stack is a dictionary with the following
5276 entries:
5277 bufnr buffer number of the current jump
5278 from cursor position before the tag jump.
5279 See |getpos()| for the format of the
5280 returned list.
5281 matchnr current matching tag number. Used when
5282 multiple matching tags are found for a
5283 name.
5284 tagname name of the tag
5285
5286 See |tagstack| for more information about the tag stack.
5287
5288 Can also be used as a |method|: >
5289 GetWinnr()->gettagstack()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005290<
5291 Return type: dict<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005292
5293
Christ van Willegence0ef912024-06-20 23:41:59 +02005294gettext({text} [, {package}]) *gettext()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005295 Translate String {text} if possible.
RestorerZ96509102024-07-11 21:14:15 +02005296 This is intended for use in Vim scripts. When generating
5297 message translations the {text} is extracted by `xgettext`,
5298 the translator can add translated messages into the .po file
5299 and Vim will lookup the translation when gettext() is called.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005300 For {text} double quoted strings are preferred, because
RestorerZ96509102024-07-11 21:14:15 +02005301 `xgettext` does not support single quoted escaped text.
5302
Christ van Willegence0ef912024-06-20 23:41:59 +02005303 When the {package} is specified, the translation is looked up
RestorerZ96509102024-07-11 21:14:15 +02005304 for that specific package. This is mainly required for
5305 third-party Vim scripts. You need to specify a path to the
5306 translations with the |bindtextdomain()| function before
5307 using the gettext() function.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005308
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005309 Return type: |String|
5310
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005311
5312getwininfo([{winid}]) *getwininfo()*
5313 Returns information about windows as a |List| with Dictionaries.
5314
5315 If {winid} is given Information about the window with that ID
5316 is returned, as a |List| with one item. If the window does not
5317 exist the result is an empty list.
5318
5319 Without {winid} information about all the windows in all the
5320 tab pages is returned.
5321
5322 Each List item is a |Dictionary| with the following entries:
5323 botline last complete displayed buffer line
5324 bufnr number of buffer in the window
5325 height window height (excluding winbar)
glepnir0a850672024-11-25 19:39:04 +01005326 leftcol first column displayed; only used when
5327 'wrap' is off
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005328 loclist 1 if showing a location list
5329 {only with the +quickfix feature}
5330 quickfix 1 if quickfix or location list window
5331 {only with the +quickfix feature}
5332 terminal 1 if a terminal window
5333 {only with the +terminal feature}
5334 tabnr tab page number
5335 topline first displayed buffer line
5336 variables a reference to the dictionary with
5337 window-local variables
5338 width window width
5339 winbar 1 if the window has a toolbar, 0
5340 otherwise
5341 wincol leftmost screen column of the window;
5342 "col" from |win_screenpos()|
5343 textoff number of columns occupied by any
5344 'foldcolumn', 'signcolumn' and line
5345 number in front of the text
5346 winid |window-ID|
5347 winnr window number
5348 winrow topmost screen line of the window;
5349 "row" from |win_screenpos()|
5350
5351 Can also be used as a |method|: >
5352 GetWinnr()->getwininfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005353<
5354 Return type: list<dict<any>>
5355
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005356
5357getwinpos([{timeout}]) *getwinpos()*
5358 The result is a |List| with two numbers, the result of
5359 |getwinposx()| and |getwinposy()| combined:
5360 [x-pos, y-pos]
5361 {timeout} can be used to specify how long to wait in msec for
5362 a response from the terminal. When omitted 100 msec is used.
5363 Use a longer time for a remote terminal.
5364 When using a value less than 10 and no response is received
5365 within that time, a previously reported position is returned,
5366 if available. This can be used to poll for the position and
5367 do some work in the meantime: >
5368 while 1
5369 let res = getwinpos(1)
5370 if res[0] >= 0
5371 break
5372 endif
5373 " Do some work here
5374 endwhile
5375<
5376
5377 Can also be used as a |method|: >
5378 GetTimeout()->getwinpos()
5379<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005380 Return type: list<number>
5381
5382
5383getwinposx() *getwinposx()*
5384 The result is a Number, which is the X coordinate in pixels of
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005385 the left hand side of the GUI Vim window. Also works for an
5386 xterm (uses a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01005387 The result will be -1 if the information is not available
5388 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005389 The value can be used with `:winpos`.
5390
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005391 Return type: |Number|
5392
5393
5394getwinposy() *getwinposy()*
5395 The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005396 the top of the GUI Vim window. Also works for an xterm (uses
5397 a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01005398 The result will be -1 if the information is not available
5399 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005400 The value can be used with `:winpos`.
5401
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005402 Return type: |Number|
5403
5404
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005405getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
5406 Like |gettabwinvar()| for the current tabpage.
5407 Examples: >
5408 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005409 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005410
5411< Can also be used as a |method|: >
5412 GetWinnr()->getwinvar(varname)
5413<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005414 Return type: any, depending on {varname}
5415
5416
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005417glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
5418 Expand the file wildcards in {expr}. See |wildcards| for the
5419 use of special characters.
5420
5421 Unless the optional {nosuf} argument is given and is |TRUE|,
5422 the 'suffixes' and 'wildignore' options apply: Names matching
5423 one of the patterns in 'wildignore' will be skipped and
5424 'suffixes' affect the ordering of matches.
5425 'wildignorecase' always applies.
5426
5427 When {list} is present and it is |TRUE| the result is a |List|
5428 with all matching files. The advantage of using a List is,
5429 you also get filenames containing newlines correctly.
5430 Otherwise the result is a String and when there are several
5431 matches, they are separated by <NL> characters.
5432
5433 If the expansion fails, the result is an empty String or List.
5434
5435 You can also use |readdir()| if you need to do complicated
5436 things, such as limiting the number of matches.
5437
5438 A name for a non-existing file is not included. A symbolic
5439 link is only included if it points to an existing file.
5440 However, when the {alllinks} argument is present and it is
5441 |TRUE| then all symbolic links are included.
5442
5443 For most systems backticks can be used to get files names from
5444 any external command. Example: >
5445 :let tagfiles = glob("`find . -name tags -print`")
5446 :let &tags = substitute(tagfiles, "\n", ",", "g")
5447< The result of the program inside the backticks should be one
5448 item per line. Spaces inside an item are allowed.
5449
5450 See |expand()| for expanding special Vim variables. See
5451 |system()| for getting the raw output of an external command.
5452
5453 Can also be used as a |method|: >
5454 GetExpr()->glob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005455<
5456 Return type: |String| or list<string> or list<any> depending
5457 on {list}
5458
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005459
h-east624bb832024-11-09 18:37:32 +01005460glob2regpat({string}) *glob2regpat()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005461 Convert a file pattern, as used by glob(), into a search
5462 pattern. The result can be used to match with a string that
5463 is a file name. E.g. >
5464 if filename =~ glob2regpat('Make*.mak')
5465< This is equivalent to: >
5466 if filename =~ '^Make.*\.mak$'
5467< When {string} is an empty string the result is "^$", match an
5468 empty string.
5469 Note that the result depends on the system. On MS-Windows
5470 a backslash usually means a path separator.
5471
5472 Can also be used as a |method|: >
5473 GetExpr()->glob2regpat()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005474<
5475 Return type: |String|
5476
5477 *globpath()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005478globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
5479 Perform glob() for String {expr} on all directories in {path}
5480 and concatenate the results. Example: >
5481 :echo globpath(&rtp, "syntax/c.vim")
5482<
5483 {path} is a comma-separated list of directory names. Each
5484 directory name is prepended to {expr} and expanded like with
5485 |glob()|. A path separator is inserted when needed.
5486 To add a comma inside a directory name escape it with a
5487 backslash. Note that on MS-Windows a directory may have a
5488 trailing backslash, remove it if you put a comma after it.
5489 If the expansion fails for one of the directories, there is no
5490 error message.
5491
5492 Unless the optional {nosuf} argument is given and is |TRUE|,
5493 the 'suffixes' and 'wildignore' options apply: Names matching
5494 one of the patterns in 'wildignore' will be skipped and
5495 'suffixes' affect the ordering of matches.
5496
5497 When {list} is present and it is |TRUE| the result is a |List|
5498 with all matching files. The advantage of using a List is, you
5499 also get filenames containing newlines correctly. Otherwise
5500 the result is a String and when there are several matches,
5501 they are separated by <NL> characters. Example: >
5502 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
5503<
5504 {alllinks} is used as with |glob()|.
5505
5506 The "**" item can be used to search in a directory tree.
5507 For example, to find all "README.txt" files in the directories
5508 in 'runtimepath' and below: >
5509 :echo globpath(&rtp, "**/README.txt")
5510< Upwards search and limiting the depth of "**" is not
5511 supported, thus using 'path' will not always work properly.
5512
5513 Can also be used as a |method|, the base is passed as the
5514 second argument: >
5515 GetExpr()->globpath(&rtp)
5516<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005517 Return type: |String| or list<string> or list<any> depending
5518 on {list}
5519
5520
5521has({feature} [, {check}]) *has()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005522 When {check} is omitted or is zero: The result is a Number,
5523 which is 1 if the feature {feature} is supported, zero
5524 otherwise. The {feature} argument is a string, case is
5525 ignored. See |feature-list| below.
5526
5527 When {check} is present and not zero: The result is a Number,
5528 which is 1 if the feature {feature} could ever be supported,
5529 zero otherwise. This is useful to check for a typo in
5530 {feature} and to detect dead code. Keep in mind that an older
5531 Vim version will not know about a feature added later and
5532 features that have been abandoned will not be known by the
5533 current Vim version.
5534
5535 Also see |exists()| and |exists_compiled()|.
5536
5537 Note that to skip code that has a syntax error when the
5538 feature is not available, Vim may skip the rest of the line
5539 and miss a following `endif`. Therefore put the `endif` on a
5540 separate line: >
5541 if has('feature')
5542 let x = this->breaks->without->the->feature
5543 endif
5544< If the `endif` would be moved to the second line as "| endif" it
5545 would not be found.
5546
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005547 Return type: |Number|
5548
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005549
5550has_key({dict}, {key}) *has_key()*
5551 The result is a Number, which is TRUE if |Dictionary| {dict}
Bram Moolenaare8008642022-08-19 17:15:35 +01005552 has an entry with key {key}. FALSE otherwise.
5553 The {key} argument is a string. In |Vim9| script a number is
5554 also accepted (and converted to a string) but no other types.
5555 In legacy script the usual automatic conversion to string is
5556 done.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005557
5558 Can also be used as a |method|: >
5559 mydict->has_key(key)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005560<
5561 Return type: |Number|
5562
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005563
5564haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
5565 The result is a Number:
5566 1 when the window has set a local directory via |:lcd|
5567 2 when the tab-page has set a local directory via |:tcd|
5568 0 otherwise.
5569
5570 Without arguments use the current window.
5571 With {winnr} use this window in the current tab page.
5572 With {winnr} and {tabnr} use the window in the specified tab
5573 page.
5574 {winnr} can be the window number or the |window-ID|.
5575 If {winnr} is -1 it is ignored and only the tabpage is used.
5576 Return 0 if the arguments are invalid.
5577 Examples: >
5578 if haslocaldir() == 1
5579 " window local directory case
5580 elseif haslocaldir() == 2
5581 " tab-local directory case
5582 else
5583 " global directory case
5584 endif
5585
5586 " current window
5587 :echo haslocaldir()
5588 :echo haslocaldir(0)
5589 :echo haslocaldir(0, 0)
5590 " window n in current tab page
5591 :echo haslocaldir(n)
5592 :echo haslocaldir(n, 0)
5593 " window n in tab page m
5594 :echo haslocaldir(n, m)
5595 " tab page m
5596 :echo haslocaldir(-1, m)
5597<
5598 Can also be used as a |method|: >
5599 GetWinnr()->haslocaldir()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005600<
5601 Return type: |Number|
5602
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005603
5604hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
5605 The result is a Number, which is TRUE if there is a mapping
5606 that contains {what} in somewhere in the rhs (what it is
5607 mapped to) and this mapping exists in one of the modes
5608 indicated by {mode}.
5609 The arguments {what} and {mode} are strings.
5610 When {abbr} is there and it is |TRUE| use abbreviations
5611 instead of mappings. Don't forget to specify Insert and/or
5612 Command-line mode.
5613 Both the global mappings and the mappings local to the current
5614 buffer are checked for a match.
5615 If no matching mapping is found FALSE is returned.
5616 The following characters are recognized in {mode}:
5617 n Normal mode
5618 v Visual and Select mode
5619 x Visual mode
5620 s Select mode
5621 o Operator-pending mode
5622 i Insert mode
5623 l Language-Argument ("r", "f", "t", etc.)
5624 c Command-line mode
5625 When {mode} is omitted, "nvo" is used.
5626
5627 This function is useful to check if a mapping already exists
5628 to a function in a Vim script. Example: >
5629 :if !hasmapto('\ABCdoit')
5630 : map <Leader>d \ABCdoit
5631 :endif
5632< This installs the mapping to "\ABCdoit" only if there isn't
5633 already a mapping to "\ABCdoit".
5634
5635 Can also be used as a |method|: >
5636 GetRHS()->hasmapto()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005637<
5638 Return type: |Number|
5639
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005640
5641histadd({history}, {item}) *histadd()*
5642 Add the String {item} to the history {history} which can be
5643 one of: *hist-names*
5644 "cmd" or ":" command line history
5645 "search" or "/" search pattern history
5646 "expr" or "=" typed expression history
5647 "input" or "@" input line history
5648 "debug" or ">" debug command history
5649 empty the current or last used history
5650 The {history} string does not need to be the whole name, one
5651 character is sufficient.
5652 If {item} does already exist in the history, it will be
5653 shifted to become the newest entry.
5654 The result is a Number: TRUE if the operation was successful,
5655 otherwise FALSE is returned.
5656
5657 Example: >
5658 :call histadd("input", strftime("%Y %b %d"))
5659 :let date=input("Enter date: ")
5660< This function is not available in the |sandbox|.
5661
5662 Can also be used as a |method|, the base is passed as the
5663 second argument: >
5664 GetHistory()->histadd('search')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005665<
5666 Return type: |Number|
5667
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005668
5669histdel({history} [, {item}]) *histdel()*
5670 Clear {history}, i.e. delete all its entries. See |hist-names|
5671 for the possible values of {history}.
5672
5673 If the parameter {item} evaluates to a String, it is used as a
5674 regular expression. All entries matching that expression will
5675 be removed from the history (if there are any).
5676 Upper/lowercase must match, unless "\c" is used |/\c|.
5677 If {item} evaluates to a Number, it will be interpreted as
5678 an index, see |:history-indexing|. The respective entry will
5679 be removed if it exists.
5680
5681 The result is TRUE for a successful operation, otherwise FALSE
5682 is returned.
5683
5684 Examples:
5685 Clear expression register history: >
5686 :call histdel("expr")
5687<
5688 Remove all entries starting with "*" from the search history: >
5689 :call histdel("/", '^\*')
5690<
5691 The following three are equivalent: >
5692 :call histdel("search", histnr("search"))
5693 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005694 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005695<
5696 To delete the last search pattern and use the last-but-one for
5697 the "n" command and 'hlsearch': >
5698 :call histdel("search", -1)
5699 :let @/ = histget("search", -1)
5700<
5701 Can also be used as a |method|: >
5702 GetHistory()->histdel()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005703<
5704 Return type: |Number|
5705
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005706
5707histget({history} [, {index}]) *histget()*
5708 The result is a String, the entry with Number {index} from
5709 {history}. See |hist-names| for the possible values of
5710 {history}, and |:history-indexing| for {index}. If there is
5711 no such entry, an empty String is returned. When {index} is
5712 omitted, the most recent item from the history is used.
5713
5714 Examples:
5715 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005716 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005717
5718< Define an Ex command ":H {num}" that supports re-execution of
5719 the {num}th entry from the output of |:history|. >
5720 :command -nargs=1 H execute histget("cmd", 0+<args>)
5721<
5722 Can also be used as a |method|: >
5723 GetHistory()->histget()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005724<
5725 Return type: |String|
5726
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005727
5728histnr({history}) *histnr()*
5729 The result is the Number of the current entry in {history}.
5730 See |hist-names| for the possible values of {history}.
5731 If an error occurred, -1 is returned.
5732
5733 Example: >
5734 :let inp_index = histnr("expr")
5735
5736< Can also be used as a |method|: >
5737 GetHistory()->histnr()
5738<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005739 Return type: |Number|
5740
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005741hlexists({name}) *hlexists()*
5742 The result is a Number, which is TRUE if a highlight group
5743 called {name} exists. This is when the group has been
5744 defined in some way. Not necessarily when highlighting has
5745 been defined for it, it may also have been used for a syntax
5746 item.
5747 *highlight_exists()*
5748 Obsolete name: highlight_exists().
5749
5750 Can also be used as a |method|: >
5751 GetName()->hlexists()
5752<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005753 Return type: |Number|
5754
5755
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005756hlget([{name} [, {resolve}]]) *hlget()*
5757 Returns a List of all the highlight group attributes. If the
5758 optional {name} is specified, then returns a List with only
5759 the attributes of the specified highlight group. Returns an
5760 empty List if the highlight group {name} is not present.
5761
5762 If the optional {resolve} argument is set to v:true and the
5763 highlight group {name} is linked to another group, then the
5764 link is resolved recursively and the attributes of the
5765 resolved highlight group are returned.
5766
5767 Each entry in the returned List is a Dictionary with the
5768 following items:
5769 cleared boolean flag, set to v:true if the highlight
5770 group attributes are cleared or not yet
5771 specified. See |highlight-clear|.
5772 cterm cterm attributes. See |highlight-cterm|.
5773 ctermbg cterm background color.
5774 See |highlight-ctermbg|.
5775 ctermfg cterm foreground color.
5776 See |highlight-ctermfg|.
5777 ctermul cterm underline color. See |highlight-ctermul|.
5778 default boolean flag, set to v:true if the highlight
5779 group link is a default link. See
5780 |highlight-default|.
5781 font highlight group font. See |highlight-font|.
5782 gui gui attributes. See |highlight-gui|.
5783 guibg gui background color. See |highlight-guibg|.
5784 guifg gui foreground color. See |highlight-guifg|.
5785 guisp gui special color. See |highlight-guisp|.
5786 id highlight group ID.
5787 linksto linked highlight group name.
5788 See |:highlight-link|.
5789 name highlight group name. See |group-name|.
5790 start start terminal keycode. See |highlight-start|.
5791 stop stop terminal keycode. See |highlight-stop|.
5792 term term attributes. See |highlight-term|.
5793
5794 The 'term', 'cterm' and 'gui' items in the above Dictionary
5795 have a dictionary value with the following optional boolean
5796 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
5797 'reverse', 'inverse' and 'strikethrough'.
5798
5799 Example(s): >
5800 :echo hlget()
5801 :echo hlget('ModeMsg')
5802 :echo hlget('Number', v:true)
5803<
5804 Can also be used as a |method|: >
5805 GetName()->hlget()
5806<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005807 Return type: list<dict<any>>
5808
5809
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005810hlset({list}) *hlset()*
5811 Creates or modifies the attributes of a List of highlight
5812 groups. Each item in {list} is a dictionary containing the
5813 attributes of a highlight group. See |hlget()| for the list of
5814 supported items in this dictionary.
5815
5816 In addition to the items described in |hlget()|, the following
5817 additional items are supported in the dictionary:
5818
5819 force boolean flag to force the creation of
5820 a link for an existing highlight group
5821 with attributes.
5822
5823 The highlight group is identified using the 'name' item and
5824 the 'id' item (if supplied) is ignored. If a highlight group
5825 with a specified name doesn't exist, then it is created.
5826 Otherwise the attributes of an existing highlight group are
5827 modified.
5828
5829 If an empty dictionary value is used for the 'term' or 'cterm'
5830 or 'gui' entries, then the corresponding attributes are
5831 cleared. If the 'cleared' item is set to v:true, then all the
5832 attributes of the highlight group are cleared.
5833
5834 The 'linksto' item can be used to link a highlight group to
5835 another highlight group. See |:highlight-link|.
5836
5837 Returns zero for success, -1 for failure.
5838
5839 Example(s): >
5840 " add bold attribute to the Visual highlight group
5841 :call hlset([#{name: 'Visual',
5842 \ term: #{reverse: 1 , bold: 1}}])
5843 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
5844 :let l = hlget()
5845 :call hlset(l)
5846 " clear the Search highlight group
5847 :call hlset([#{name: 'Search', cleared: v:true}])
5848 " clear the 'term' attributes for a highlight group
5849 :call hlset([#{name: 'Title', term: {}}])
5850 " create the MyHlg group linking it to DiffAdd
5851 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
5852 " remove the MyHlg group link
5853 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
5854 " clear the attributes and a link
5855 :call hlset([#{name: 'MyHlg', cleared: v:true,
5856 \ linksto: 'NONE'}])
5857<
5858 Can also be used as a |method|: >
5859 GetAttrList()->hlset()
5860<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005861 Return type: |Number|
5862
5863hlID({name}) *hlID()*
5864 The result is a Number, which is the ID of the highlight group
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005865 with name {name}. When the highlight group doesn't exist,
5866 zero is returned.
5867 This can be used to retrieve information about the highlight
5868 group. For example, to get the background color of the
5869 "Comment" group: >
5870 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5871< *highlightID()*
5872 Obsolete name: highlightID().
5873
5874 Can also be used as a |method|: >
5875 GetName()->hlID()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005876<
5877 Return type: |Number|
5878
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005879
5880hostname() *hostname()*
5881 The result is a String, which is the name of the machine on
5882 which Vim is currently running. Machine names greater than
5883 256 characters long are truncated.
5884
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005885 Return type: |String|
5886
5887
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005888iconv({string}, {from}, {to}) *iconv()*
5889 The result is a String, which is the text {string} converted
5890 from encoding {from} to encoding {to}.
5891 When the conversion completely fails an empty string is
5892 returned. When some characters could not be converted they
5893 are replaced with "?".
5894 The encoding names are whatever the iconv() library function
5895 can accept, see ":!man 3 iconv".
5896 Most conversions require Vim to be compiled with the |+iconv|
5897 feature. Otherwise only UTF-8 to latin1 conversion and back
5898 can be done.
5899 This can be used to display messages with special characters,
5900 no matter what 'encoding' is set to. Write the message in
5901 UTF-8 and use: >
5902 echo iconv(utf8_str, "utf-8", &enc)
5903< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5904 from/to UCS-2 is automatically changed to use UTF-8. You
5905 cannot use UCS-2 in a string anyway, because of the NUL bytes.
5906
5907 Can also be used as a |method|: >
5908 GetText()->iconv('latin1', 'utf-8')
5909<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005910 Return type: |String|
5911
5912
h-east624bb832024-11-09 18:37:32 +01005913id({item}) *id()*
Ernie Raelc8e158b2024-07-09 18:39:52 +02005914 The result is a unique String associated with the {item} and
5915 not with the {item}'s contents. It is only valid while the
5916 {item} exists and is referenced. It is valid only in the
5917 instance of vim that produces the result. The whole idea is
5918 that `id({item})` does not change if the contents of {item}
5919 changes. This is useful as a `key` for creating an identity
5920 dictionary, rather than one based on equals.
5921
5922 This operation does not reference {item} and there is no
5923 function to convert the `id` to the {item}. It may be useful to
5924 have a map of `id` to {item}. The following >
5925 var referenceMap: dict<any>
5926 var id = item->id()
5927 referenceMap[id] = item
5928< prevents {item} from being garbage collected and provides a
5929 way to get the {item} from the `id`.
5930
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01005931 {item} may be a List, Tuple, Dictionary, Object, Job, Channel
5932 or Blob. If the item is not a permitted type, or it is a null
Ernie Raelc8e158b2024-07-09 18:39:52 +02005933 value, then an empty String is returned.
5934
5935 Can also be used as a |method|: >
5936 GetItem()->id()
5937<
5938 Return type: |String|
5939
5940
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005941indent({lnum}) *indent()*
5942 The result is a Number, which is indent of line {lnum} in the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005943 current buffer. The indent is counted in spaces, the value
5944 of 'tabstop' is relevant. {lnum} is used just like in
5945 |getline()|.
5946 When {lnum} is invalid -1 is returned. In |Vim9| script an
5947 error is given.
5948
5949 Can also be used as a |method|: >
5950 GetLnum()->indent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005951<
5952 Return type: |Number|
5953
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005954
5955index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005956 Find {expr} in {object} and return its index. See
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005957 |indexof()| for using a lambda to select the item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005958
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01005959 If {object} is a |List| or a |Tuple| return the lowest index
5960 where the item has a value equal to {expr}. There is no
5961 automatic conversion, so the String "4" is different from the
5962 Number 4. And the number 4 is different from the Float 4.0.
5963 The value of 'ignorecase' is not used here, case matters as
5964 indicated by the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005965
5966 If {object} is |Blob| return the lowest index where the byte
5967 value is equal to {expr}.
5968
5969 If {start} is given then start looking at the item with index
5970 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005971
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005972 When {ic} is given and it is |TRUE|, ignore case. Otherwise
5973 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005974
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005975 -1 is returned when {expr} is not found in {object}.
5976 Example: >
5977 :let idx = index(words, "the")
5978 :if index(numbers, 123) >= 0
5979
5980< Can also be used as a |method|: >
5981 GetObject()->index(what)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005982<
5983 Return type: |Number|
5984
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005985
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005986indexof({object}, {expr} [, {opts}]) *indexof()*
5987 Returns the index of an item in {object} where {expr} is
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01005988 v:true. {object} must be a |List|, a |Tuple| or a |Blob|.
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005989
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01005990 If {object} is a |List| or a |Tuple|, evaluate {expr} for each
Christ van Willegen92e109f2025-03-24 20:12:37 +01005991 item in the List or Tuple until the expression is v:true
5992 and return the index of this item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005993
5994 If {object} is a |Blob| evaluate {expr} for each byte in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005995 Blob until the expression is v:true and return the index of
5996 this byte.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005997
5998 {expr} must be a |string| or |Funcref|.
5999
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006000 If {expr} is a |string|: If {object} is a |List| or a |Tuple|,
6001 inside {expr} |v:key| has the index of the current List or
6002 Tuple item and |v:val| has the value of the item. If {object}
6003 is a |Blob|, inside {expr} |v:key| has the index of the
6004 current byte and |v:val| has the byte value.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01006005
6006 If {expr} is a |Funcref| it must take two arguments:
6007 1. the key or the index of the current item.
6008 2. the value of the current item.
6009 The function must return |TRUE| if the item is found and the
6010 search should stop.
6011
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01006012 The optional argument {opts} is a Dict and supports the
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01006013 following items:
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01006014 startidx start evaluating {expr} at the item with this
6015 index; may be negative for an item relative to
6016 the end
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01006017 Returns -1 when {expr} evaluates to v:false for all the items.
6018 Example: >
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01006019 :let l = [#{n: 10}, #{n: 20}, #{n: 30}]
6020 :echo indexof(l, "v:val.n == 20")
6021 :echo indexof(l, {i, v -> v.n == 30})
6022 :echo indexof(l, "v:val.n == 20", #{startidx: 1})
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01006023
6024< Can also be used as a |method|: >
6025 mylist->indexof(expr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006026<
6027 Return type: |Number|
6028
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01006029
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006030input({prompt} [, {text} [, {completion}]]) *input()*
6031 The result is a String, which is whatever the user typed on
6032 the command-line. The {prompt} argument is either a prompt
6033 string, or a blank string (for no prompt). A '\n' can be used
6034 in the prompt to start a new line.
6035 The highlighting set with |:echohl| is used for the prompt.
6036 The input is entered just like a command-line, with the same
6037 editing commands and mappings. There is a separate history
6038 for lines typed for input().
6039 Example: >
6040 :if input("Coffee or beer? ") == "beer"
6041 : echo "Cheers!"
6042 :endif
6043<
6044 If the optional {text} argument is present and not empty, this
6045 is used for the default reply, as if the user typed this.
6046 Example: >
6047 :let color = input("Color? ", "white")
6048
6049< The optional {completion} argument specifies the type of
6050 completion supported for the input. Without it completion is
6051 not performed. The supported completion types are the same as
6052 that can be supplied to a user-defined command using the
6053 "-complete=" argument. Refer to |:command-completion| for
6054 more information. Example: >
6055 let fname = input("File: ", "", "file")
6056<
6057 NOTE: This function must not be used in a startup file, for
6058 the versions that only run in GUI mode (e.g., the Win32 GUI).
6059 Note: When input() is called from within a mapping it will
6060 consume remaining characters from that mapping, because a
6061 mapping is handled like the characters were typed.
6062 Use |inputsave()| before input() and |inputrestore()|
6063 after input() to avoid that. Another solution is to avoid
6064 that further characters follow in the mapping, e.g., by using
6065 |:execute| or |:normal|.
6066
6067 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006068 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006069 :function GetFoo()
6070 : call inputsave()
6071 : let g:Foo = input("enter search pattern: ")
6072 : call inputrestore()
6073 :endfunction
6074
6075< Can also be used as a |method|: >
6076 GetPrompt()->input()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006077<
6078 Return type: |String|
6079
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006080
6081inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
6082 Like |input()|, but when the GUI is running and text dialogs
6083 are supported, a dialog window pops up to input the text.
6084 Example: >
6085 :let n = inputdialog("value for shiftwidth", shiftwidth())
6086 :if n != ""
6087 : let &sw = n
6088 :endif
6089< When the dialog is cancelled {cancelreturn} is returned. When
6090 omitted an empty string is returned.
6091 Hitting <Enter> works like pressing the OK button. Hitting
6092 <Esc> works like pressing the Cancel button.
6093 NOTE: Command-line completion is not supported.
6094
6095 Can also be used as a |method|: >
6096 GetPrompt()->inputdialog()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006097<
6098 Return type: |String|
6099
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006100
6101inputlist({textlist}) *inputlist()*
6102 {textlist} must be a |List| of strings. This |List| is
6103 displayed, one string per line. The user will be prompted to
6104 enter a number, which is returned.
6105 The user can also select an item by clicking on it with the
6106 mouse, if the mouse is enabled in the command line ('mouse' is
6107 "a" or includes "c"). For the first string 0 is returned.
6108 When clicking above the first item a negative number is
6109 returned. When clicking on the prompt one more than the
6110 length of {textlist} is returned.
6111 Make sure {textlist} has less than 'lines' entries, otherwise
6112 it won't work. It's a good idea to put the entry number at
6113 the start of the string. And put a prompt in the first item.
6114 Example: >
6115 let color = inputlist(['Select color:', '1. red',
6116 \ '2. green', '3. blue'])
6117
6118< Can also be used as a |method|: >
6119 GetChoices()->inputlist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006120<
6121 Return type: |Number|
6122
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006123
6124inputrestore() *inputrestore()*
6125 Restore typeahead that was saved with a previous |inputsave()|.
6126 Should be called the same number of times inputsave() is
6127 called. Calling it more often is harmless though.
6128 Returns TRUE when there is nothing to restore, FALSE otherwise.
6129
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006130 Return type: |Number|
6131
6132
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006133inputsave() *inputsave()*
6134 Preserve typeahead (also from mappings) and clear it, so that
6135 a following prompt gets input from the user. Should be
6136 followed by a matching inputrestore() after the prompt. Can
6137 be used several times, in which case there must be just as
6138 many inputrestore() calls.
6139 Returns TRUE when out of memory, FALSE otherwise.
6140
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006141 Return type: |Number|
6142
6143
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006144inputsecret({prompt} [, {text}]) *inputsecret()*
6145 This function acts much like the |input()| function with but
6146 two exceptions:
6147 a) the user's response will be displayed as a sequence of
6148 asterisks ("*") thereby keeping the entry secret, and
6149 b) the user's response will not be recorded on the input
6150 |history| stack.
6151 The result is a String, which is whatever the user actually
6152 typed on the command-line in response to the issued prompt.
6153 NOTE: Command-line completion is not supported.
6154
6155 Can also be used as a |method|: >
6156 GetPrompt()->inputsecret()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006157<
6158 Return type: |String|
6159
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006160
6161insert({object}, {item} [, {idx}]) *insert()*
6162 When {object} is a |List| or a |Blob| insert {item} at the start
6163 of it.
6164
6165 If {idx} is specified insert {item} before the item with index
6166 {idx}. If {idx} is zero it goes before the first item, just
6167 like omitting {idx}. A negative {idx} is also possible, see
6168 |list-index|. -1 inserts just before the last item.
6169
6170 Returns the resulting |List| or |Blob|. Examples: >
6171 :let mylist = insert([2, 3, 5], 1)
6172 :call insert(mylist, 4, -1)
6173 :call insert(mylist, 6, len(mylist))
6174< The last example can be done simpler with |add()|.
6175 Note that when {item} is a |List| it is inserted as a single
6176 item. Use |extend()| to concatenate |Lists|.
6177
6178 Can also be used as a |method|: >
6179 mylist->insert(item)
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07006180<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006181 Return type: |Number|
6182
6183
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07006184 *instanceof()* *E614* *E616* *E693*
6185instanceof({object}, {class})
6186 The result is a Number, which is |TRUE| when the {object}
Ernie Rael2025af12023-12-12 16:58:00 +01006187 argument is a direct or indirect instance of a |Class|,
6188 |Interface|, or class |:type| alias specified by {class}.
6189 If {class} is varargs, the function returns |TRUE| when
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07006190 {object} is an instance of any of the specified classes.
LemonBoyafe04662023-08-23 21:08:11 +02006191 Example: >
Ernie Rael2025af12023-12-12 16:58:00 +01006192 instanceof(animal, Dog, Cat)
LemonBoyafe04662023-08-23 21:08:11 +02006193
6194< Can also be used as a |method|: >
6195 myobj->instanceof(mytype)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006196<
6197 Return type: |Number|
LemonBoyafe04662023-08-23 21:08:11 +02006198
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006199interrupt() *interrupt()*
6200 Interrupt script execution. It works more or less like the
6201 user typing CTRL-C, most commands won't execute and control
6202 returns to the user. This is useful to abort execution
6203 from lower down, e.g. in an autocommand. Example: >
6204 :function s:check_typoname(file)
6205 : if fnamemodify(a:file, ':t') == '['
6206 : echomsg 'Maybe typo'
6207 : call interrupt()
6208 : endif
6209 :endfunction
6210 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006211<
6212 Return type: void
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006213
6214invert({expr}) *invert()*
6215 Bitwise invert. The argument is converted to a number. A
6216 List, Dict or Float argument causes an error. Example: >
6217 :let bits = invert(bits)
6218< Can also be used as a |method|: >
6219 :let bits = bits->invert()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006220<
6221 Return type: |Number|
6222
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006223
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01006224isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01006225 The result is a Number, which is |TRUE| when {path} is an
6226 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01006227 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01006228 On MS-Windows, it is considered absolute when it starts with an
6229 optional drive prefix and is followed by a '\' or '/'. UNC paths
6230 are always absolute.
6231 Example: >
6232 echo isabsolutepath('/usr/share/') " 1
6233 echo isabsolutepath('./foobar') " 0
6234 echo isabsolutepath('C:\Windows') " 1
6235 echo isabsolutepath('foobar') " 0
6236 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01006237<
LemonBoydca1d402022-04-28 15:26:33 +01006238 Can also be used as a |method|: >
6239 GetName()->isabsolutepath()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006240<
6241 Return type: |Number|
LemonBoydca1d402022-04-28 15:26:33 +01006242
6243
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006244isdirectory({directory}) *isdirectory()*
6245 The result is a Number, which is |TRUE| when a directory
6246 with the name {directory} exists. If {directory} doesn't
6247 exist, or isn't a directory, the result is |FALSE|. {directory}
6248 is any expression, which is used as a String.
6249
6250 Can also be used as a |method|: >
6251 GetName()->isdirectory()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006252<
6253 Return type: |Number|
6254
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006255
6256isinf({expr}) *isinf()*
6257 Return 1 if {expr} is a positive infinity, or -1 a negative
6258 infinity, otherwise 0. >
6259 :echo isinf(1.0 / 0.0)
6260< 1 >
6261 :echo isinf(-1.0 / 0.0)
6262< -1
6263
6264 Can also be used as a |method|: >
6265 Compute()->isinf()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006266<
6267 Return type: |Number|
6268
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006269
6270islocked({expr}) *islocked()* *E786*
6271 The result is a Number, which is |TRUE| when {expr} is the
6272 name of a locked variable.
6273 The string argument {expr} must be the name of a variable,
6274 |List| item or |Dictionary| entry, not the variable itself!
6275 Example: >
6276 :let alist = [0, ['a', 'b'], 2, 3]
6277 :lockvar 1 alist
6278 :echo islocked('alist') " 1
6279 :echo islocked('alist[1]') " 0
6280
Bram Moolenaar9da17d72022-02-09 21:50:44 +00006281< When {expr} is a variable that does not exist -1 is returned.
6282 If {expr} uses a range, list or dict index that is out of
6283 range or does not exist you get an error message. Use
6284 |exists()| to check for existence.
6285 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006286
6287 Can also be used as a |method|: >
6288 GetName()->islocked()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006289<
6290 Return type: |Number|
6291
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006292
6293isnan({expr}) *isnan()*
6294 Return |TRUE| if {expr} is a float with value NaN. >
6295 echo isnan(0.0 / 0.0)
6296< 1
6297
6298 Can also be used as a |method|: >
6299 Compute()->isnan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006300<
6301 Return type: |Number|
6302
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006303
6304items({dict}) *items()*
6305 Return a |List| with all the key-value pairs of {dict}. Each
6306 |List| item is a list with two items: the key of a {dict}
6307 entry and the value of this entry. The |List| is in arbitrary
6308 order. Also see |keys()| and |values()|.
6309 Example: >
6310 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006311 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006312 endfor
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01006313<
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006314 A |List|, a |Tuple| or a |String| argument is also supported.
6315 In these cases, items() returns a List with the index and the
6316 value at the index.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006317
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01006318 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006319 mydict->items()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006320<
6321 Return type: list<list<any>> or list<any>
6322
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006323
6324job_ functions are documented here: |job-functions-details|
6325
6326
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006327join({expr} [, {sep}]) *join()*
6328 Join the items in {expr} together into one String. {expr} can
6329 be a |List| or a |Tuple|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006330 When {sep} is specified it is put in between the items. If
6331 {sep} is omitted a single space is used.
6332 Note that {sep} is not added at the end. You might want to
6333 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006334 let lines = join(mylist, "\n") .. "\n"
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006335< String items are used as-is. |Lists|, |Tuples| and
6336 |Dictionaries| are converted into a string like with
6337 |string()|. The opposite function is |split()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006338
6339 Can also be used as a |method|: >
6340 mylist->join()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006341<
6342 Return type: |String|
6343
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006344
6345js_decode({string}) *js_decode()*
6346 This is similar to |json_decode()| with these differences:
6347 - Object key names do not have to be in quotes.
6348 - Strings can be in single quotes.
6349 - Empty items in an array (between two commas) are allowed and
6350 result in v:none items.
6351
6352 Can also be used as a |method|: >
6353 ReadObject()->js_decode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006354<
6355 Return type: any, depending on {varname}
6356
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006357
6358js_encode({expr}) *js_encode()*
6359 This is similar to |json_encode()| with these differences:
6360 - Object key names are not in quotes.
6361 - v:none items in an array result in an empty item between
6362 commas.
6363 For example, the Vim object:
6364 [1,v:none,{"one":1},v:none] ~
6365 Will be encoded as:
6366 [1,,{one:1},,] ~
6367 While json_encode() would produce:
6368 [1,null,{"one":1},null] ~
6369 This encoding is valid for JavaScript. It is more efficient
6370 than JSON, especially when using an array with optional items.
6371
6372 Can also be used as a |method|: >
6373 GetObject()->js_encode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006374<
6375 Return type: |String|
6376
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006377
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00006378json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006379 This parses a JSON formatted string and returns the equivalent
6380 in Vim values. See |json_encode()| for the relation between
6381 JSON and Vim values.
6382 The decoding is permissive:
6383 - A trailing comma in an array and object is ignored, e.g.
6384 "[1, 2, ]" is the same as "[1, 2]".
6385 - Integer keys are accepted in objects, e.g. {1:2} is the
6386 same as {"1":2}.
6387 - More floating point numbers are recognized, e.g. "1." for
6388 "1.0", or "001.2" for "1.2". Special floating point values
6389 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
6390 are accepted.
6391 - Leading zeroes in integer numbers are ignored, e.g. "012"
6392 for "12" or "-012" for "-12".
6393 - Capitalization is ignored in literal names null, true or
6394 false, e.g. "NULL" for "null", "True" for "true".
6395 - Control characters U+0000 through U+001F which are not
6396 escaped in strings are accepted, e.g. " " (tab
6397 character in string) for "\t".
6398 - An empty JSON expression or made of only spaces is accepted
6399 and results in v:none.
6400 - Backslash in an invalid 2-character sequence escape is
6401 ignored, e.g. "\a" is decoded as "a".
6402 - A correct surrogate pair in JSON strings should normally be
6403 a 12 character sequence such as "\uD834\uDD1E", but
6404 json_decode() silently accepts truncated surrogate pairs
6405 such as "\uD834" or "\uD834\u"
6406 *E938*
6407 A duplicate key in an object, valid in rfc7159, is not
6408 accepted by json_decode() as the result must be a valid Vim
6409 type, e.g. this fails: {"a":"b", "a":"c"}
6410
6411 Can also be used as a |method|: >
6412 ReadObject()->json_decode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006413<
6414 Return type: any, depending on {varname}
6415
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006416
6417json_encode({expr}) *json_encode()*
6418 Encode {expr} as JSON and return this as a string.
6419 The encoding is specified in:
6420 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00006421 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006422 |Number| decimal number
6423 |Float| floating point number
6424 Float nan "NaN"
6425 Float inf "Infinity"
6426 Float -inf "-Infinity"
6427 |String| in double quotes (possibly null)
6428 |Funcref| not possible, error
6429 |List| as an array (possibly null); when
6430 used recursively: []
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006431 |Tuple| as an array (possibly null); when
6432 used recursively: []
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006433 |Dict| as an object (possibly null); when
6434 used recursively: {}
6435 |Blob| as an array of the individual bytes
6436 v:false "false"
6437 v:true "true"
6438 v:none "null"
6439 v:null "null"
6440 Note that NaN and Infinity are passed on as values. This is
6441 missing in the JSON standard, but several implementations do
6442 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006443 If a string contains an illegal character then the replacement
6444 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006445
6446 Can also be used as a |method|: >
6447 GetObject()->json_encode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006448<
6449 Return type: |String|
6450
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006451
6452keys({dict}) *keys()*
6453 Return a |List| with all the keys of {dict}. The |List| is in
6454 arbitrary order. Also see |items()| and |values()|.
6455
6456 Can also be used as a |method|: >
6457 mydict->keys()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006458<
6459 Return type: list<string>
6460
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006461
zeertzjqcdc83932022-09-12 13:38:41 +01006462keytrans({string}) *keytrans()*
6463 Turn the internal byte representation of keys into a form that
6464 can be used for |:map|. E.g. >
6465 :let xx = "\<C-Home>"
6466 :echo keytrans(xx)
6467< <C-Home>
6468
6469 Can also be used as a |method|: >
6470 "\<C-Home>"->keytrans()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006471<
6472 Return type: |String|
zeertzjqcdc83932022-09-12 13:38:41 +01006473
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006474
6475len({expr}) *len()* *E701*
6476 The result is a Number, which is the length of the argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006477 When {expr} is a String or a Number the length in bytes is
6478 used, as with |strlen()|.
6479 When {expr} is a |List| the number of items in the |List| is
6480 returned.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006481 When {expr} is a |Tuple| the number of items in the |Tuple| is
6482 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006483 When {expr} is a |Blob| the number of bytes is returned.
6484 When {expr} is a |Dictionary| the number of entries in the
6485 |Dictionary| is returned.
mityu7f0bba22024-03-29 10:14:41 +01006486 When {expr} is an |Object|, invokes the len() method in the
6487 object (if present) to get the length (|object-len()|).
6488 Otherwise returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006489
6490 Can also be used as a |method|: >
6491 mylist->len()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006492<
6493 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006494
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006495
6496 *libcall()* *E364* *E368*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006497libcall({libname}, {funcname}, {argument})
6498 Call function {funcname} in the run-time library {libname}
6499 with single argument {argument}.
6500 This is useful to call functions in a library that you
6501 especially made to be used with Vim. Since only one argument
6502 is possible, calling standard library functions is rather
6503 limited.
6504 The result is the String returned by the function. If the
6505 function returns NULL, this will appear as an empty string ""
6506 to Vim.
6507 If the function returns a number, use libcallnr()!
6508 If {argument} is a number, it is passed to the function as an
6509 int; if {argument} is a string, it is passed as a
6510 null-terminated string.
6511 This function will fail in |restricted-mode|.
6512
6513 libcall() allows you to write your own 'plug-in' extensions to
6514 Vim without having to recompile the program. It is NOT a
6515 means to call system functions! If you try to do so Vim will
6516 very probably crash.
6517
6518 For Win32, the functions you write must be placed in a DLL
6519 and use the normal C calling convention (NOT Pascal which is
6520 used in Windows System DLLs). The function must take exactly
6521 one parameter, either a character pointer or a long integer,
6522 and must return a character pointer or NULL. The character
6523 pointer returned must point to memory that will remain valid
6524 after the function has returned (e.g. in static data in the
6525 DLL). If it points to allocated memory, that memory will
6526 leak away. Using a static buffer in the function should work,
6527 it's then freed when the DLL is unloaded.
6528
6529 WARNING: If the function returns a non-valid pointer, Vim may
6530 crash! This also happens if the function returns a number,
6531 because Vim thinks it's a pointer.
6532 For Win32 systems, {libname} should be the filename of the DLL
6533 without the ".DLL" suffix. A full path is only required if
6534 the DLL is not in the usual places.
6535 For Unix: When compiling your own plugins, remember that the
6536 object code must be compiled as position-independent ('PIC').
6537 {only in Win32 and some Unix versions, when the |+libcall|
6538 feature is present}
6539 Examples: >
6540 :echo libcall("libc.so", "getenv", "HOME")
6541
6542< Can also be used as a |method|, the base is passed as the
6543 third argument: >
6544 GetValue()->libcall("libc.so", "getenv")
6545<
6546 *libcallnr()*
6547libcallnr({libname}, {funcname}, {argument})
6548 Just like |libcall()|, but used for a function that returns an
6549 int instead of a string.
6550 {only in Win32 on some Unix versions, when the |+libcall|
6551 feature is present}
6552 Examples: >
6553 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
6554 :call libcallnr("libc.so", "printf", "Hello World!\n")
6555 :call libcallnr("libc.so", "sleep", 10)
6556<
6557 Can also be used as a |method|, the base is passed as the
6558 third argument: >
6559 GetValue()->libcallnr("libc.so", "printf")
6560<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006561 Return type: |String|
6562
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006563
6564line({expr} [, {winid}]) *line()*
6565 The result is a Number, which is the line number of the file
6566 position given with {expr}. The {expr} argument is a string.
zeertzjq02f3eba2024-06-12 20:45:24 +02006567 See |getpos()| for accepted positions.
6568
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006569 To get the column number use |col()|. To get both use
6570 |getpos()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02006571
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006572 With the optional {winid} argument the values are obtained for
6573 that window instead of the current window.
zeertzjq02f3eba2024-06-12 20:45:24 +02006574
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006575 Returns 0 for invalid values of {expr} and {winid}.
zeertzjq02f3eba2024-06-12 20:45:24 +02006576
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006577 Examples: >
6578 line(".") line number of the cursor
6579 line(".", winid) idem, in window "winid"
6580 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006581 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006582<
6583 To jump to the last known position when opening a file see
6584 |last-position-jump|.
6585
6586 Can also be used as a |method|: >
6587 GetValue()->line()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006588<
6589 Return type: |Number|
6590
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006591
6592line2byte({lnum}) *line2byte()*
6593 Return the byte count from the start of the buffer for line
6594 {lnum}. This includes the end-of-line character, depending on
6595 the 'fileformat' option for the current buffer. The first
6596 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
6597 This can also be used to get the byte count for the line just
6598 below the last line: >
6599 line2byte(line("$") + 1)
6600< This is the buffer size plus one. If 'fileencoding' is empty
6601 it is the file size plus one. {lnum} is used like with
6602 |getline()|. When {lnum} is invalid, or the |+byte_offset|
6603 feature has been disabled at compile time, -1 is returned.
6604 Also see |byte2line()|, |go| and |:goto|.
6605
6606 Can also be used as a |method|: >
6607 GetLnum()->line2byte()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006608<
6609 Return type: |Number|
6610
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006611
6612lispindent({lnum}) *lispindent()*
6613 Get the amount of indent for line {lnum} according the lisp
6614 indenting rules, as with 'lisp'.
6615 The indent is counted in spaces, the value of 'tabstop' is
6616 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01006617 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006618 error is given.
6619
6620 Can also be used as a |method|: >
6621 GetLnum()->lispindent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006622<
6623 Return type: |Number|
6624
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006625
6626list2blob({list}) *list2blob()*
6627 Return a Blob concatenating all the number values in {list}.
6628 Examples: >
6629 list2blob([1, 2, 3, 4]) returns 0z01020304
6630 list2blob([]) returns 0z
6631< Returns an empty Blob on error. If one of the numbers is
6632 negative or more than 255 error *E1239* is given.
6633
6634 |blob2list()| does the opposite.
6635
6636 Can also be used as a |method|: >
6637 GetList()->list2blob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006638<
6639 Return type: |Blob|
6640
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006641
6642list2str({list} [, {utf8}]) *list2str()*
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006643 Convert each number in {list} to a character string and
6644 concatenates them all. Examples: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006645 list2str([32]) returns " "
6646 list2str([65, 66, 67]) returns "ABC"
6647< The same can be done (slowly) with: >
6648 join(map(list, {nr, val -> nr2char(val)}), '')
6649< |str2list()| does the opposite.
6650
6651 When {utf8} is omitted or zero, the current 'encoding' is used.
6652 When {utf8} is TRUE, always return UTF-8 characters.
6653 With UTF-8 composing characters work as expected: >
6654 list2str([97, 769]) returns "á"
6655<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006656 Returns an empty string on error.
6657
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006658 Can also be used as a |method|: >
6659 GetList()->list2str()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006660<
6661 Return type: |String|
6662
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006663
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006664list2tuple({list}) *list2tuple()*
6665 Create a Tuple from a shallow copy of the list items.
6666 Examples: >
6667 list2tuple([1, 2, 3]) returns (1, 2, 3)
6668< |tuple2list()| does the opposite.
6669
6670 This function doesn't recursively convert all the List items
6671 in {list} to a Tuple. Note that the items are identical
6672 between the list and the tuple, changing an item changes the
6673 contents of both the tuple and the list.
6674
6675 Returns an empty tuple on error.
6676
6677 Can also be used as a |method|: >
6678 GetList()->list2tuple()
6679<
6680 Return type: tuple<{type}> (depending on the given |List|)
6681
6682
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006683listener_add({callback} [, {buf}]) *listener_add()*
6684 Add a callback function that will be invoked when changes have
6685 been made to buffer {buf}.
6686 {buf} refers to a buffer name or number. For the accepted
6687 values, see |bufname()|. When {buf} is omitted the current
6688 buffer is used.
6689 Returns a unique ID that can be passed to |listener_remove()|.
6690
6691 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00006692 bufnr the buffer that was changed
6693 start first changed line number
6694 end first line number below the change
6695 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006696 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00006697 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006698
6699 Example: >
6700 func Listener(bufnr, start, end, added, changes)
6701 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
6702 endfunc
6703 call listener_add('Listener', bufnr)
6704
Bram Moolenaar944697a2022-02-20 19:48:20 +00006705< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006706 dictionary with these entries:
6707 lnum the first line number of the change
6708 end the first line below the change
6709 added number of lines added; negative if lines were
6710 deleted
6711 col first column in "lnum" that was affected by
6712 the change; one if unknown or the whole line
6713 was affected; this is a byte index, first
6714 character has a value of one.
Bram Moolenaar3c053a12022-10-16 13:11:12 +01006715 When lines are inserted (not when a line is split, e.g. by
6716 typing CR in Insert mode) the values are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006717 lnum line above which the new line is added
6718 end equal to "lnum"
6719 added number of lines inserted
6720 col 1
6721 When lines are deleted the values are:
6722 lnum the first deleted line
6723 end the line below the first deleted line, before
6724 the deletion was done
6725 added negative, number of lines deleted
6726 col 1
6727 When lines are changed:
6728 lnum the first changed line
6729 end the line below the last changed line
6730 added 0
6731 col first column with a change or 1
6732
6733 The entries are in the order the changes were made, thus the
6734 most recent change is at the end. The line numbers are valid
6735 when the callback is invoked, but later changes may make them
6736 invalid, thus keeping a copy for later might not work.
6737
6738 The {callback} is invoked just before the screen is updated,
6739 when |listener_flush()| is called or when a change is being
6740 made that changes the line count in a way it causes a line
6741 number in the list of changes to become invalid.
6742
6743 The {callback} is invoked with the text locked, see
6744 |textlock|. If you do need to make changes to the buffer, use
6745 a timer to do this later |timer_start()|.
6746
6747 The {callback} is not invoked when the buffer is first loaded.
6748 Use the |BufReadPost| autocmd event to handle the initial text
6749 of a buffer.
6750 The {callback} is also not invoked when the buffer is
6751 unloaded, use the |BufUnload| autocmd event for that.
6752
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006753 Returns zero if {callback} or {buf} is invalid.
6754
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006755 Can also be used as a |method|, the base is passed as the
6756 second argument: >
6757 GetBuffer()->listener_add(callback)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006758<
6759 Return type: |Number|
6760
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006761
6762listener_flush([{buf}]) *listener_flush()*
6763 Invoke listener callbacks for buffer {buf}. If there are no
6764 pending changes then no callbacks are invoked.
6765
6766 {buf} refers to a buffer name or number. For the accepted
6767 values, see |bufname()|. When {buf} is omitted the current
6768 buffer is used.
6769
6770 Can also be used as a |method|: >
6771 GetBuffer()->listener_flush()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006772<
6773 Return type: |Number|
6774
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006775
6776listener_remove({id}) *listener_remove()*
6777 Remove a listener previously added with listener_add().
6778 Returns FALSE when {id} could not be found, TRUE when {id} was
6779 removed.
6780
6781 Can also be used as a |method|: >
6782 GetListenerId()->listener_remove()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006783<
6784 Return type: |Number|
6785
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006786
6787localtime() *localtime()*
6788 Return the current time, measured as seconds since 1st Jan
6789 1970. See also |strftime()|, |strptime()| and |getftime()|.
6790
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006791 Return type: |Number|
6792
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006793
6794log({expr}) *log()*
6795 Return the natural logarithm (base e) of {expr} as a |Float|.
6796 {expr} must evaluate to a |Float| or a |Number| in the range
6797 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006798 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006799 Examples: >
6800 :echo log(10)
6801< 2.302585 >
6802 :echo log(exp(5))
6803< 5.0
6804
6805 Can also be used as a |method|: >
6806 Compute()->log()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006807<
6808 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006809
6810
6811log10({expr}) *log10()*
6812 Return the logarithm of Float {expr} to base 10 as a |Float|.
6813 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006814 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006815 Examples: >
6816 :echo log10(1000)
6817< 3.0 >
6818 :echo log10(0.01)
6819< -2.0
6820
6821 Can also be used as a |method|: >
6822 Compute()->log10()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006823<
6824 Return type: |Float|
6825
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006826
6827luaeval({expr} [, {expr}]) *luaeval()*
6828 Evaluate Lua expression {expr} and return its result converted
6829 to Vim data structures. Second {expr} may hold additional
6830 argument accessible as _A inside first {expr}.
6831 Strings are returned as they are.
6832 Boolean objects are converted to numbers.
Bram Moolenaar73e28dc2022-09-17 21:08:33 +01006833 Numbers are converted to |Float| values.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006834 Dictionaries and lists obtained by vim.eval() are returned
6835 as-is.
6836 Other objects are returned as zero without any errors.
6837 See |lua-luaeval| for more details.
6838 Note that in a `:def` function local variables are not visible
6839 to {expr}.
6840
6841 Can also be used as a |method|: >
6842 GetExpr()->luaeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006843<
6844 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006845
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006846 {only available when compiled with the |+lua| feature}
6847
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006848
6849map({expr1}, {expr2}) *map()*
6850 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00006851 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006852 item in {expr1} with the result of evaluating {expr2}.
6853 For a |Blob| each byte is replaced.
6854 For a |String|, each character, including composing
6855 characters, is replaced.
6856 If the item type changes you may want to use |mapnew()| to
6857 create a new List or Dictionary. This is required when using
6858 Vim9 script.
6859
6860 {expr2} must be a |String| or |Funcref|.
6861
6862 If {expr2} is a |String|, inside {expr2} |v:val| has the value
6863 of the current item. For a |Dictionary| |v:key| has the key
6864 of the current item and for a |List| |v:key| has the index of
6865 the current item. For a |Blob| |v:key| has the index of the
6866 current byte. For a |String| |v:key| has the index of the
6867 current character.
6868 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006869 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006870< This puts "> " before and " <" after each item in "mylist".
6871
6872 Note that {expr2} is the result of an expression and is then
6873 used as an expression again. Often it is good to use a
6874 |literal-string| to avoid having to double backslashes. You
6875 still have to double ' quotes
6876
6877 If {expr2} is a |Funcref| it is called with two arguments:
6878 1. The key or the index of the current item.
6879 2. the value of the current item.
Bram Moolenaarb59ae592022-11-23 23:46:31 +00006880 With a legacy script lambda you don't get an error if it only
6881 accepts one argument, but with a Vim9 lambda you get "E1106:
6882 One argument too many", the number of arguments must match.
6883
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006884 The function must return the new value of the item. Example
6885 that changes each value by "key-value": >
6886 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006887 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006888 endfunc
6889 call map(myDict, function('KeyValue'))
6890< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006891 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006892< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006893 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006894< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006895 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006896<
6897 The operation is done in-place for a |List| and |Dictionary|.
6898 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006899 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006900
6901< Returns {expr1}, the |List| or |Dictionary| that was filtered,
6902 or a new |Blob| or |String|.
6903 When an error is encountered while evaluating {expr2} no
6904 further items in {expr1} are processed.
6905 When {expr2} is a Funcref errors inside a function are ignored,
6906 unless it was defined with the "abort" flag.
6907
6908 Can also be used as a |method|: >
6909 mylist->map(expr2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006910<
6911 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
6912 depending on {expr1}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006913
6914
6915maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
6916 When {dict} is omitted or zero: Return the rhs of mapping
6917 {name} in mode {mode}. The returned String has special
6918 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01006919 listing. When {dict} is TRUE a dictionary is returned, see
6920 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006921
6922 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006923 returned if {dict} is FALSE, otherwise returns an empty Dict.
6924 When the mapping for {name} is empty, then "<Nop>" is
6925 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006926
6927 The {name} can have special key names, like in the ":map"
6928 command.
6929
6930 {mode} can be one of these strings:
6931 "n" Normal
6932 "v" Visual (including Select)
6933 "o" Operator-pending
6934 "i" Insert
6935 "c" Cmd-line
6936 "s" Select
6937 "x" Visual
6938 "l" langmap |language-mapping|
6939 "t" Terminal-Job
6940 "" Normal, Visual and Operator-pending
6941 When {mode} is omitted, the modes for "" are used.
6942
6943 When {abbr} is there and it is |TRUE| use abbreviations
6944 instead of mappings.
6945
6946 When {dict} is there and it is |TRUE| return a dictionary
6947 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01006948 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006949 "lhs" The {lhs} of the mapping as it would be typed
6950 "lhsraw" The {lhs} of the mapping as raw bytes
6951 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
6952 form, only present when it differs from "lhsraw"
6953 "rhs" The {rhs} of the mapping as typed.
6954 "silent" 1 for a |:map-silent| mapping, else 0.
6955 "noremap" 1 if the {rhs} of the mapping is not remappable.
6956 "script" 1 if mapping was defined with <script>.
6957 "expr" 1 for an expression mapping (|:map-<expr>|).
6958 "buffer" 1 for a buffer local mapping (|:map-local|).
6959 "mode" Modes for which the mapping is defined. In
6960 addition to the modes mentioned above, these
6961 characters will be used:
6962 " " Normal, Visual and Operator-pending
6963 "!" Insert and Commandline mode
6964 (|mapmode-ic|)
6965 "sid" The script local ID, used for <sid> mappings
Bram Moolenaar71badf92023-04-22 22:40:14 +01006966 (|<SID>|). Negative for special contexts.
Bram Moolenaara9528b32022-01-18 20:51:35 +00006967 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01006968 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006969 "lnum" The line number in "sid", zero if unknown.
6970 "nowait" Do not wait for other, longer mappings.
6971 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01006972 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01006973 "mode_bits" Vim's internal binary representation of "mode".
6974 |mapset()| ignores this; only "mode" is used.
6975 See |maplist()| for usage examples. The values
6976 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006977
6978 The dictionary can be used to restore a mapping with
6979 |mapset()|.
6980
6981 The mappings local to the current buffer are checked first,
6982 then the global mappings.
6983 This function can be used to map a key even when it's already
6984 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006985 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006986
6987< Can also be used as a |method|: >
6988 GetKey()->maparg('n')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006989<
6990 Return type: |String| or dict<any> depending on {dict}
6991
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006992
6993mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
6994 Check if there is a mapping that matches with {name} in mode
6995 {mode}. See |maparg()| for {mode} and special names in
6996 {name}.
6997 When {abbr} is there and it is |TRUE| use abbreviations
6998 instead of mappings.
6999 A match happens with a mapping that starts with {name} and
7000 with a mapping which is equal to the start of {name}.
7001
7002 matches mapping "a" "ab" "abc" ~
7003 mapcheck("a") yes yes yes
7004 mapcheck("abc") yes yes yes
7005 mapcheck("ax") yes no no
7006 mapcheck("b") no no no
7007
7008 The difference with maparg() is that mapcheck() finds a
7009 mapping that matches with {name}, while maparg() only finds a
7010 mapping for {name} exactly.
7011 When there is no mapping that starts with {name}, an empty
7012 String is returned. If there is one, the RHS of that mapping
7013 is returned. If there are several mappings that start with
7014 {name}, the RHS of one of them is returned. This will be
7015 "<Nop>" if the RHS is empty.
7016 The mappings local to the current buffer are checked first,
7017 then the global mappings.
7018 This function can be used to check if a mapping can be added
7019 without being ambiguous. Example: >
7020 :if mapcheck("_vv") == ""
7021 : map _vv :set guifont=7x13<CR>
7022 :endif
7023< This avoids adding the "_vv" mapping when there already is a
7024 mapping for "_v" or for "_vvv".
7025
7026 Can also be used as a |method|: >
7027 GetKey()->mapcheck('n')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007028<
7029 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007030
7031
Ernie Rael09661202022-04-25 14:40:44 +01007032maplist([{abbr}]) *maplist()*
7033 Returns a |List| of all mappings. Each List item is a |Dict|,
7034 the same as what is returned by |maparg()|, see
7035 |mapping-dict|. When {abbr} is there and it is |TRUE| use
7036 abbreviations instead of mappings.
7037
7038 Example to show all mappings with 'MultiMatch' in rhs: >
7039 vim9script
7040 echo maplist()->filter(
7041 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01007042< It can be tricky to find mappings for particular |:map-modes|.
7043 |mapping-dict|'s "mode_bits" can simplify this. For example,
7044 the mode_bits for Normal, Insert or Command-line modes are
7045 0x19. To find all the mappings available in those modes you
7046 can do: >
7047 vim9script
7048 var saved_maps = []
7049 for m in maplist()
7050 if and(m.mode_bits, 0x19) != 0
7051 saved_maps->add(m)
7052 endif
7053 endfor
7054 echo saved_maps->mapnew((_, m) => m.lhs)
7055< The values of the mode_bits are defined in Vim's src/vim.h
7056 file and they can be discovered at runtime using
7057 |:map-commands| and "maplist()". Example: >
7058 vim9script
7059 omap xyzzy <Nop>
7060 var op_bit = maplist()->filter(
7061 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
7062 ounmap xyzzy
7063 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007064<
7065 Return type: list<dict<any>>
Ernie Rael09661202022-04-25 14:40:44 +01007066
7067
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007068mapnew({expr1}, {expr2}) *mapnew()*
7069 Like |map()| but instead of replacing items in {expr1} a new
7070 List or Dictionary is created and returned. {expr1} remains
7071 unchanged. Items can still be changed by {expr2}, if you
7072 don't want that use |deepcopy()| first.
7073
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007074 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
7075 depending on {expr1}
7076
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007077
7078mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01007079mapset({dict})
7080 Restore a mapping from a dictionary, possibly returned by
7081 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
7082 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01007083 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01007084 feature allows copying mappings from one buffer to another.
7085 The dict.mode value may restore a single mapping that covers
7086 more than one mode, like with mode values of '!', ' ', 'nox',
7087 or 'v'. *E1276*
7088
7089 In the first form, {mode} and {abbr} should be the same as
7090 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007091 {mode} is used to define the mode in which the mapping is set,
7092 not the "mode" entry in {dict}.
7093 Example for saving and restoring a mapping: >
7094 let save_map = maparg('K', 'n', 0, 1)
7095 nnoremap K somethingelse
7096 ...
7097 call mapset('n', 0, save_map)
7098< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01007099 e.g. with `:map!`, you need to save/restore the mapping for
7100 all of them, when they might differ.
7101
7102 In the second form, with {dict} as the only argument, mode
7103 and abbr are taken from the dict.
7104 Example: >
7105 vim9script
7106 var save_maps = maplist()->filter(
7107 (_, m) => m.lhs == 'K')
7108 nnoremap K somethingelse
7109 cnoremap K somethingelse2
7110 # ...
7111 unmap K
7112 for d in save_maps
7113 mapset(d)
7114 endfor
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007115<
7116 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007117
7118
7119match({expr}, {pat} [, {start} [, {count}]]) *match()*
7120 When {expr} is a |List| then this returns the index of the
7121 first item where {pat} matches. Each item is used as a
7122 String, |Lists| and |Dictionaries| are used as echoed.
7123
7124 Otherwise, {expr} is used as a String. The result is a
7125 Number, which gives the index (byte offset) in {expr} where
7126 {pat} matches.
7127
7128 A match at the first character or |List| item returns zero.
7129 If there is no match -1 is returned.
7130
7131 For getting submatches see |matchlist()|.
7132 Example: >
7133 :echo match("testing", "ing") " results in 4
7134 :echo match([1, 'x'], '\a') " results in 1
7135< See |string-match| for how {pat} is used.
7136 *strpbrk()*
7137 Vim doesn't have a strpbrk() function. But you can do: >
7138 :let sepidx = match(line, '[.,;: \t]')
7139< *strcasestr()*
7140 Vim doesn't have a strcasestr() function. But you can add
7141 "\c" to the pattern to ignore case: >
7142 :let idx = match(haystack, '\cneedle')
7143<
7144 If {start} is given, the search starts from byte index
7145 {start} in a String or item {start} in a |List|.
7146 The result, however, is still the index counted from the
7147 first character/item. Example: >
7148 :echo match("testing", "ing", 2)
7149< result is again "4". >
7150 :echo match("testing", "ing", 4)
7151< result is again "4". >
7152 :echo match("testing", "t", 2)
7153< result is "3".
7154 For a String, if {start} > 0 then it is like the string starts
7155 {start} bytes later, thus "^" will match at {start}. Except
7156 when {count} is given, then it's like matches before the
7157 {start} byte are ignored (this is a bit complicated to keep it
7158 backwards compatible).
7159 For a String, if {start} < 0, it will be set to 0. For a list
7160 the index is counted from the end.
7161 If {start} is out of range ({start} > strlen({expr}) for a
7162 String or {start} > len({expr}) for a |List|) -1 is returned.
7163
7164 When {count} is given use the {count}'th match. When a match
7165 is found in a String the search for the next one starts one
7166 character further. Thus this example results in 1: >
7167 echo match("testing", "..", 0, 2)
7168< In a |List| the search continues in the next item.
7169 Note that when {count} is added the way {start} works changes,
7170 see above.
7171
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007172 *match-pattern*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007173 See |pattern| for the patterns that are accepted.
7174 The 'ignorecase' option is used to set the ignore-caseness of
7175 the pattern. 'smartcase' is NOT used. The matching is always
7176 done like 'magic' is set and 'cpoptions' is empty.
7177 Note that a match at the start is preferred, thus when the
7178 pattern is using "*" (any number of matches) it tends to find
7179 zero matches at the start instead of a number of matches
7180 further down in the text.
7181
7182 Can also be used as a |method|: >
7183 GetText()->match('word')
7184 GetList()->match('word')
7185<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007186 Return type: |Number|
7187
7188
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00007189 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007190matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
7191 Defines a pattern to be highlighted in the current window (a
7192 "match"). It will be highlighted with {group}. Returns an
7193 identification number (ID), which can be used to delete the
7194 match using |matchdelete()|. The ID is bound to the window.
7195 Matching is case sensitive and magic, unless case sensitivity
7196 or magicness are explicitly overridden in {pattern}. The
7197 'magic', 'smartcase' and 'ignorecase' options are not used.
7198 The "Conceal" value is special, it causes the match to be
7199 concealed.
7200
7201 The optional {priority} argument assigns a priority to the
7202 match. A match with a high priority will have its
7203 highlighting overrule that of a match with a lower priority.
7204 A priority is specified as an integer (negative numbers are no
7205 exception). If the {priority} argument is not specified, the
7206 default priority is 10. The priority of 'hlsearch' is zero,
7207 hence all matches with a priority greater than zero will
7208 overrule it. Syntax highlighting (see 'syntax') is a separate
7209 mechanism, and regardless of the chosen priority a match will
7210 always overrule syntax highlighting.
7211
7212 The optional {id} argument allows the request for a specific
7213 match ID. If a specified ID is already taken, an error
7214 message will appear and the match will not be added. An ID
7215 is specified as a positive integer (zero excluded). IDs 1, 2
7216 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01007217 respectively. 3 is reserved for use by the |matchparen|
7218 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01007219 If the {id} argument is not specified or -1, |matchadd()|
Bram Moolenaar9f573a82022-09-29 13:50:08 +01007220 automatically chooses a free ID, which is at least 1000.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007221
7222 The optional {dict} argument allows for further custom
7223 values. Currently this is used to specify a match specific
7224 conceal character that will be shown for |hl-Conceal|
7225 highlighted matches. The dict can have the following members:
7226
7227 conceal Special character to show instead of the
7228 match (only for |hl-Conceal| highlighted
7229 matches, see |:syn-cchar|)
7230 window Instead of the current window use the
7231 window with this number or window ID.
7232
7233 The number of matches is not limited, as it is the case with
7234 the |:match| commands.
7235
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007236 Returns -1 on error.
7237
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007238 Example: >
7239 :highlight MyGroup ctermbg=green guibg=green
7240 :let m = matchadd("MyGroup", "TODO")
7241< Deletion of the pattern: >
7242 :call matchdelete(m)
7243
7244< A list of matches defined by |matchadd()| and |:match| are
7245 available from |getmatches()|. All matches can be deleted in
7246 one operation by |clearmatches()|.
7247
7248 Can also be used as a |method|: >
7249 GetGroup()->matchadd('TODO')
7250<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007251 Return type: |Number|
7252
7253
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007254 *matchaddpos()*
7255matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
7256 Same as |matchadd()|, but requires a list of positions {pos}
7257 instead of a pattern. This command is faster than |matchadd()|
Shane Harperc1b39842024-07-17 19:40:40 +02007258 because it does not handle regular expressions and it sets
7259 buffer line boundaries to redraw screen. It is supposed to be
7260 used when fast match additions and deletions are required, for
7261 example to highlight matching parentheses.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007262
7263 {pos} is a list of positions. Each position can be one of
7264 these:
7265 - A number. This whole line will be highlighted. The first
7266 line has number 1.
7267 - A list with one number, e.g., [23]. The whole line with this
7268 number will be highlighted.
7269 - A list with two numbers, e.g., [23, 11]. The first number is
7270 the line number, the second one is the column number (first
7271 column is 1, the value must correspond to the byte index as
7272 |col()| would return). The character at this position will
7273 be highlighted.
7274 - A list with three numbers, e.g., [23, 11, 3]. As above, but
7275 the third number gives the length of the highlight in bytes.
7276
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007277 Returns -1 on error.
7278
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007279 Example: >
7280 :highlight MyGroup ctermbg=green guibg=green
7281 :let m = matchaddpos("MyGroup", [[23, 24], 34])
7282< Deletion of the pattern: >
7283 :call matchdelete(m)
7284
7285< Matches added by |matchaddpos()| are returned by
7286 |getmatches()|.
7287
7288 Can also be used as a |method|: >
7289 GetGroup()->matchaddpos([23, 11])
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007290<
7291 Return type: |Number|
7292
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007293
7294matcharg({nr}) *matcharg()*
7295 Selects the {nr} match item, as set with a |:match|,
7296 |:2match| or |:3match| command.
7297 Return a |List| with two elements:
7298 The name of the highlight group used
7299 The pattern used.
7300 When {nr} is not 1, 2 or 3 returns an empty |List|.
7301 When there is no match item set returns ['', ''].
7302 This is useful to save and restore a |:match|.
7303 Highlighting matches using the |:match| commands are limited
7304 to three matches. |matchadd()| does not have this limitation.
7305
7306 Can also be used as a |method|: >
7307 GetMatch()->matcharg()
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007308<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007309 Return type: list<string>
7310
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007311 *matchbufline()*
7312matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])
7313 Returns the |List| of matches in lines from {lnum} to {end} in
7314 buffer {buf} where {pat} matches.
7315
7316 {lnum} and {end} can either be a line number or the string "$"
7317 to refer to the last line in {buf}.
7318
7319 The {dict} argument supports following items:
7320 submatches include submatch information (|/\(|)
7321
7322 For each match, a |Dict| with the following items is returned:
7323 byteidx starting byte index of the match
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007324 lnum line number where there is a match
7325 text matched string
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007326 Note that there can be multiple matches in a single line.
7327
7328 This function works only for loaded buffers. First call
7329 |bufload()| if needed.
7330
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007331 See |match-pattern| for information about the effect of some
7332 option settings on the pattern.
7333
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007334 When {buf} is not a valid buffer, the buffer is not loaded or
7335 {lnum} or {end} is not valid then an error is given and an
7336 empty |List| is returned.
7337
7338 Examples: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007339 " Assuming line 3 in buffer 5 contains "a"
7340 :echo matchbufline(5, '\<\k\+\>', 3, 3)
7341 [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
7342 " Assuming line 4 in buffer 10 contains "tik tok"
7343 :echo matchbufline(10, '\<\k\+\>', 1, 4)
7344 [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007345<
7346 If {submatch} is present and is v:true, then submatches like
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007347 "\1", "\2", etc. are also returned. Example: >
7348 " Assuming line 2 in buffer 2 contains "acd"
7349 :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007350 \ {'submatches': v:true})
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007351 [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007352< The "submatches" List always contains 9 items. If a submatch
7353 is not found, then an empty string is returned for that
7354 submatch.
7355
7356 Can also be used as a |method|: >
7357 GetBuffer()->matchbufline('mypat', 1, '$')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007358<
7359 Return type: list<dict<any>> or list<any>
7360
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007361
h-east624bb832024-11-09 18:37:32 +01007362matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007363 Deletes a match with ID {id} previously defined by |matchadd()|
7364 or one of the |:match| commands. Returns 0 if successful,
7365 otherwise -1. See example for |matchadd()|. All matches can
7366 be deleted in one operation by |clearmatches()|.
7367 If {win} is specified, use the window with this number or
7368 window ID instead of the current window.
7369
7370 Can also be used as a |method|: >
7371 GetMatch()->matchdelete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007372<
7373 Return type: |Number|
7374
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007375
7376matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
7377 Same as |match()|, but return the index of first character
7378 after the match. Example: >
7379 :echo matchend("testing", "ing")
7380< results in "7".
7381 *strspn()* *strcspn()*
7382 Vim doesn't have a strspn() or strcspn() function, but you can
7383 do it with matchend(): >
7384 :let span = matchend(line, '[a-zA-Z]')
7385 :let span = matchend(line, '[^a-zA-Z]')
7386< Except that -1 is returned when there are no matches.
7387
7388 The {start}, if given, has the same meaning as for |match()|. >
7389 :echo matchend("testing", "ing", 2)
7390< results in "7". >
7391 :echo matchend("testing", "ing", 5)
7392< result is "-1".
7393 When {expr} is a |List| the result is equal to |match()|.
7394
7395 Can also be used as a |method|: >
7396 GetText()->matchend('word')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007397<
7398 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007399
7400
7401matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
7402 If {list} is a list of strings, then returns a |List| with all
7403 the strings in {list} that fuzzy match {str}. The strings in
7404 the returned list are sorted based on the matching score.
7405
7406 The optional {dict} argument always supports the following
7407 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01007408 matchseq When this item is present return only matches
7409 that contain the characters in {str} in the
7410 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01007411 limit Maximum number of matches in {list} to be
7412 returned. Zero means no limit.
glepnir28e40a72025-03-16 21:24:22 +01007413 camelcase Use enhanced camel case scoring making results
7414 better suited for completion related to
zeertzjqc4815c12025-03-18 20:28:00 +01007415 programming languages. Defaults to v:true.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007416
7417 If {list} is a list of dictionaries, then the optional {dict}
7418 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01007419 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007420 {str}. The value of this item should be a
7421 string.
7422 text_cb |Funcref| that will be called for every item
7423 in {list} to get the text for fuzzy matching.
7424 This should accept a dictionary item as the
7425 argument and return the text for that item to
7426 use for fuzzy matching.
7427
7428 {str} is treated as a literal string and regular expression
7429 matching is NOT supported. The maximum supported {str} length
7430 is 256.
7431
7432 When {str} has multiple words each separated by white space,
7433 then the list of strings that have all the words is returned.
7434
7435 If there are no matching strings or there is an error, then an
7436 empty list is returned. If length of {str} is greater than
7437 256, then returns an empty list.
7438
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01007439 When {limit} is given, matchfuzzy() will find up to this
7440 number of matches in {list} and return them in sorted order.
7441
Bram Moolenaar1588bc82022-03-08 21:35:07 +00007442 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007443 matching strings.
7444
7445 Example: >
7446 :echo matchfuzzy(["clay", "crow"], "cay")
7447< results in ["clay"]. >
7448 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
7449< results in a list of buffer names fuzzy matching "ndl". >
7450 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
7451< results in a list of buffer information dicts with buffer
7452 names fuzzy matching "ndl". >
7453 :echo getbufinfo()->matchfuzzy("spl",
7454 \ {'text_cb' : {v -> v.name}})
7455< results in a list of buffer information dicts with buffer
7456 names fuzzy matching "spl". >
7457 :echo v:oldfiles->matchfuzzy("test")
7458< results in a list of file names fuzzy matching "test". >
7459 :let l = readfile("buffer.c")->matchfuzzy("str")
7460< results in a list of lines in "buffer.c" fuzzy matching "str". >
7461 :echo ['one two', 'two one']->matchfuzzy('two one')
7462< results in ['two one', 'one two']. >
7463 :echo ['one two', 'two one']->matchfuzzy('two one',
7464 \ {'matchseq': 1})
7465< results in ['two one'].
7466
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007467 Return type: list<string> or list<any>
7468
7469
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007470matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
7471 Same as |matchfuzzy()|, but returns the list of matched
7472 strings, the list of character positions where characters
7473 in {str} matches and a list of matching scores. You can
7474 use |byteidx()| to convert a character position to a byte
7475 position.
7476
7477 If {str} matches multiple times in a string, then only the
7478 positions for the best match is returned.
7479
7480 If there are no matching strings or there is an error, then a
7481 list with three empty list items is returned.
7482
7483 Example: >
7484 :echo matchfuzzypos(['testing'], 'tsg')
7485< results in [['testing'], [[0, 2, 6]], [99]] >
7486 :echo matchfuzzypos(['clay', 'lacy'], 'la')
7487< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
7488 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
7489< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
7490
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007491 Return type: list<list<any>>
7492
7493
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007494matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
7495 Same as |match()|, but return a |List|. The first item in the
7496 list is the matched string, same as what matchstr() would
7497 return. Following items are submatches, like "\1", "\2", etc.
7498 in |:substitute|. When an optional submatch didn't match an
7499 empty string is used. Example: >
7500 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
7501< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
7502 When there is no match an empty list is returned.
7503
7504 You can pass in a List, but that is not very useful.
7505
7506 Can also be used as a |method|: >
7507 GetText()->matchlist('word')
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007508<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007509 Return type: list<string> or list<any>
7510
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007511 *matchstrlist()*
7512matchstrlist({list}, {pat} [, {dict}])
7513 Returns the |List| of matches in {list} where {pat} matches.
7514 {list} is a |List| of strings. {pat} is matched against each
7515 string in {list}.
7516
7517 The {dict} argument supports following items:
7518 submatches include submatch information (|/\(|)
7519
7520 For each match, a |Dict| with the following items is returned:
7521 byteidx starting byte index of the match.
7522 idx index in {list} of the match.
7523 text matched string
7524 submatches a List of submatches. Present only if
7525 "submatches" is set to v:true in {dict}.
7526
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007527 See |match-pattern| for information about the effect of some
7528 option settings on the pattern.
7529
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007530 Example: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007531 :echo matchstrlist(['tik tok'], '\<\k\+\>')
7532 [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
7533 :echo matchstrlist(['a', 'b'], '\<\k\+\>')
7534 [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007535<
7536 If "submatches" is present and is v:true, then submatches like
7537 "\1", "\2", etc. are also returned. Example: >
7538 :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
7539 \ #{submatches: v:true})
7540 [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
7541< The "submatches" List always contains 9 items. If a submatch
7542 is not found, then an empty string is returned for that
7543 submatch.
7544
7545 Can also be used as a |method|: >
7546 GetListOfStrings()->matchstrlist('mypat')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007547<
7548 Return type: list<dict<any>> or list<any>
7549
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007550
7551matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
7552 Same as |match()|, but return the matched string. Example: >
7553 :echo matchstr("testing", "ing")
7554< results in "ing".
7555 When there is no match "" is returned.
7556 The {start}, if given, has the same meaning as for |match()|. >
7557 :echo matchstr("testing", "ing", 2)
7558< results in "ing". >
7559 :echo matchstr("testing", "ing", 5)
7560< result is "".
7561 When {expr} is a |List| then the matching item is returned.
7562 The type isn't changed, it's not necessarily a String.
7563
7564 Can also be used as a |method|: >
7565 GetText()->matchstr('word')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007566<
7567 Return type: |String|
7568
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007569
7570matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
7571 Same as |matchstr()|, but return the matched string, the start
7572 position and the end position of the match. Example: >
7573 :echo matchstrpos("testing", "ing")
7574< results in ["ing", 4, 7].
7575 When there is no match ["", -1, -1] is returned.
7576 The {start}, if given, has the same meaning as for |match()|. >
7577 :echo matchstrpos("testing", "ing", 2)
7578< results in ["ing", 4, 7]. >
7579 :echo matchstrpos("testing", "ing", 5)
7580< result is ["", -1, -1].
7581 When {expr} is a |List| then the matching item, the index
7582 of first item where {pat} matches, the start position and the
7583 end position of the match are returned. >
7584 :echo matchstrpos([1, '__x'], '\a')
7585< result is ["x", 1, 2, 3].
7586 The type isn't changed, it's not necessarily a String.
7587
7588 Can also be used as a |method|: >
7589 GetText()->matchstrpos('word')
7590<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007591 Return type: list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007592
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007593
7594max({expr}) *max()*
7595 Return the maximum value of all items in {expr}. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007596 echo max([apples, pears, oranges])
7597
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01007598< {expr} can be a |List|, a |Tuple| or a |Dictionary|. For a
7599 Dictionary, it returns the maximum of all values in the
7600 Dictionary. If {expr} is neither a List nor a Tuple nor a
7601 Dictionary, or one of the items in {expr} cannot be used as a
7602 Number this results in an error. An empty |List|, |Tuple|
7603 or |Dictionary| results in zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007604
7605 Can also be used as a |method|: >
7606 mylist->max()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007607<
7608 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007609
7610
7611menu_info({name} [, {mode}]) *menu_info()*
7612 Return information about the specified menu {name} in
7613 mode {mode}. The menu name should be specified without the
7614 shortcut character ('&'). If {name} is "", then the top-level
7615 menu names are returned.
7616
7617 {mode} can be one of these strings:
7618 "n" Normal
7619 "v" Visual (including Select)
7620 "o" Operator-pending
7621 "i" Insert
7622 "c" Cmd-line
7623 "s" Select
7624 "x" Visual
7625 "t" Terminal-Job
7626 "" Normal, Visual and Operator-pending
7627 "!" Insert and Cmd-line
7628 When {mode} is omitted, the modes for "" are used.
7629
7630 Returns a |Dictionary| containing the following items:
7631 accel menu item accelerator text |menu-text|
7632 display display name (name without '&')
7633 enabled v:true if this menu item is enabled
7634 Refer to |:menu-enable|
7635 icon name of the icon file (for toolbar)
7636 |toolbar-icon|
7637 iconidx index of a built-in icon
7638 modes modes for which the menu is defined. In
7639 addition to the modes mentioned above, these
7640 characters will be used:
7641 " " Normal, Visual and Operator-pending
7642 name menu item name.
7643 noremenu v:true if the {rhs} of the menu item is not
7644 remappable else v:false.
7645 priority menu order priority |menu-priority|
7646 rhs right-hand-side of the menu item. The returned
7647 string has special characters translated like
7648 in the output of the ":menu" command listing.
7649 When the {rhs} of a menu item is empty, then
7650 "<Nop>" is returned.
7651 script v:true if script-local remapping of {rhs} is
7652 allowed else v:false. See |:menu-script|.
7653 shortcut shortcut key (character after '&' in
7654 the menu name) |menu-shortcut|
7655 silent v:true if the menu item is created
7656 with <silent> argument |:menu-silent|
7657 submenus |List| containing the names of
7658 all the submenus. Present only if the menu
7659 item has submenus.
7660
7661 Returns an empty dictionary if the menu item is not found.
7662
7663 Examples: >
7664 :echo menu_info('Edit.Cut')
7665 :echo menu_info('File.Save', 'n')
7666
7667 " Display the entire menu hierarchy in a buffer
7668 func ShowMenu(name, pfx)
7669 let m = menu_info(a:name)
7670 call append(line('$'), a:pfx .. m.display)
7671 for child in m->get('submenus', [])
7672 call ShowMenu(a:name .. '.' .. escape(child, '.'),
7673 \ a:pfx .. ' ')
7674 endfor
7675 endfunc
7676 new
7677 for topmenu in menu_info('').submenus
7678 call ShowMenu(topmenu, '')
7679 endfor
7680<
7681 Can also be used as a |method|: >
7682 GetMenuName()->menu_info('v')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007683<
7684 Return type: dict<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007685
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007686min({expr}) *min()*
7687 Return the minimum value of all items in {expr}. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007688 echo min([apples, pears, oranges])
7689
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01007690< {expr} can be a |List|, a |Tuple| or a |Dictionary|. For a
7691 Dictionary, it returns the minimum of all values in the
7692 Dictionary. If {expr} is neither a List nor a Tuple nor a
7693 Dictionary, or one of the items in {expr} cannot be used as a
7694 Number this results in an error. An empty |List|, |Tuple| or
7695 |Dictionary| results in zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007696
7697 Can also be used as a |method|: >
7698 mylist->min()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007699<
7700 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007701
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007702
7703mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E739*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007704 Create directory {name}.
7705
Bram Moolenaar938ae282023-02-20 20:44:55 +00007706 When {flags} is present it must be a string. An empty string
7707 has no effect.
Bram Moolenaar6f14da12022-09-07 21:30:44 +01007708
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007709 {flags} can contain these character flags:
7710 "p" intermediate directories will be created as necessary
7711 "D" {name} will be deleted at the end of the current
Christian Brabandtc509c002024-06-14 20:22:05 +02007712 function, but not recursively |:defer|
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007713 "R" {name} will be deleted recursively at the end of the
Christian Brabandtc509c002024-06-14 20:22:05 +02007714 current function |:defer|
Bram Moolenaar938ae282023-02-20 20:44:55 +00007715
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007716 Note that when {name} has more than one part and "p" is used
Bram Moolenaar6f14da12022-09-07 21:30:44 +01007717 some directories may already exist. Only the first one that
7718 is created and what it contains is scheduled to be deleted.
7719 E.g. when using: >
7720 call mkdir('subdir/tmp/autoload', 'pR')
7721< and "subdir" already exists then "subdir/tmp" will be
7722 scheduled for deletion, like with: >
7723 defer delete('subdir/tmp', 'rf')
7724< Note that if scheduling the defer fails the directory is not
7725 deleted. This should only happen when out of memory.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007726
7727 If {prot} is given it is used to set the protection bits of
7728 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
7729 the user, readable for others). Use 0o700 to make it
Christian Brabandt0a336cc2025-03-11 21:14:31 +01007730 unreadable for others. This is used for the newly created
zeertzjqc1c3b5d2025-03-12 21:16:13 +01007731 directories. Note: umask is applied to {prot} (on Unix).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007732 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007733 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007734
7735< This function is not available in the |sandbox|.
7736
7737 There is no error if the directory already exists and the "p"
7738 flag is passed (since patch 8.0.1708). However, without the
7739 "p" option the call will fail.
7740
7741 The function result is a Number, which is TRUE if the call was
7742 successful or FALSE if the directory creation failed or partly
7743 failed.
7744
7745 Not available on all systems. To check use: >
7746 :if exists("*mkdir")
7747
7748< Can also be used as a |method|: >
7749 GetName()->mkdir()
7750<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007751 Return type: |Number|
7752
7753
7754mode([{expr}]) *mode()*
7755 Return a string that indicates the current mode.
Doug Kearns9cd9e752024-04-07 17:42:17 +02007756 If {expr} is supplied and it evaluates to a non-zero Number or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007757 a non-empty String (|non-zero-arg|), then the full mode is
7758 returned, otherwise only the first letter is returned.
7759 Also see |state()|.
7760
7761 n Normal
7762 no Operator-pending
7763 nov Operator-pending (forced characterwise |o_v|)
7764 noV Operator-pending (forced linewise |o_V|)
7765 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
7766 CTRL-V is one character
7767 niI Normal using |i_CTRL-O| in |Insert-mode|
7768 niR Normal using |i_CTRL-O| in |Replace-mode|
7769 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
7770 nt Terminal-Normal (insert goes to Terminal-Job mode)
7771 v Visual by character
7772 vs Visual by character using |v_CTRL-O| in Select mode
7773 V Visual by line
7774 Vs Visual by line using |v_CTRL-O| in Select mode
7775 CTRL-V Visual blockwise
7776 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
7777 s Select by character
7778 S Select by line
7779 CTRL-S Select blockwise
7780 i Insert
7781 ic Insert mode completion |compl-generic|
7782 ix Insert mode |i_CTRL-X| completion
7783 R Replace |R|
7784 Rc Replace mode completion |compl-generic|
7785 Rx Replace mode |i_CTRL-X| completion
7786 Rv Virtual Replace |gR|
7787 Rvc Virtual Replace mode completion |compl-generic|
7788 Rvx Virtual Replace mode |i_CTRL-X| completion
7789 c Command-line editing
h-east71ebf3b2023-09-03 17:12:55 +02007790 ct Command-line editing via Terminal-Job mode
zeertzjqfcaeb3d2023-11-28 20:46:29 +01007791 cr Command-line editing overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007792 cv Vim Ex mode |gQ|
zeertzjqfcaeb3d2023-11-28 20:46:29 +01007793 cvr Vim Ex mode while in overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007794 ce Normal Ex mode |Q|
7795 r Hit-enter prompt
7796 rm The -- more -- prompt
7797 r? A |:confirm| query of some sort
7798 ! Shell or external command is executing
7799 t Terminal-Job mode: keys go to the job
7800
7801 This is useful in the 'statusline' option or when used
7802 with |remote_expr()| In most other places it always returns
7803 "c" or "n".
7804 Note that in the future more modes and more specific modes may
7805 be added. It's better not to compare the whole string but only
7806 the leading character(s).
7807 Also see |visualmode()|.
7808
7809 Can also be used as a |method|: >
7810 DoFull()->mode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007811<
7812 Return type: |String|
7813
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007814
7815mzeval({expr}) *mzeval()*
7816 Evaluate MzScheme expression {expr} and return its result
7817 converted to Vim data structures.
7818 Numbers and strings are returned as they are.
7819 Pairs (including lists and improper lists) and vectors are
7820 returned as Vim |Lists|.
7821 Hash tables are represented as Vim |Dictionary| type with keys
7822 converted to strings.
7823 All other types are converted to string with display function.
7824 Examples: >
7825 :mz (define l (list 1 2 3))
7826 :mz (define h (make-hash)) (hash-set! h "list" l)
7827 :echo mzeval("l")
7828 :echo mzeval("h")
7829<
7830 Note that in a `:def` function local variables are not visible
7831 to {expr}.
7832
7833 Can also be used as a |method|: >
7834 GetExpr()->mzeval()
7835<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007836 Return type: any, depending on {expr}
7837
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007838 {only available when compiled with the |+mzscheme| feature}
7839
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007840
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007841nextnonblank({lnum}) *nextnonblank()*
7842 Return the line number of the first line at or below {lnum}
7843 that is not blank. Example: >
7844 if getline(nextnonblank(1)) =~ "Java"
7845< When {lnum} is invalid or there is no non-blank line at or
7846 below it, zero is returned.
7847 {lnum} is used like with |getline()|.
7848 See also |prevnonblank()|.
7849
7850 Can also be used as a |method|: >
7851 GetLnum()->nextnonblank()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007852<
7853 Return type: |Number|
7854
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007855
Christ van Willegenc0786752025-02-01 15:42:16 +01007856ngettext({single}, {plural}, {number}[, {domain}) *ngettext()*
7857 Return a string that contains the correct value for a
7858 message based on the rules for plural form(s) in
7859 a language. Examples: >
7860 ngettext("File", "Files", 2) # returns "Files"
7861<
7862 Can be used as a |method|: >
7863 1->ngettext("File", "Files") # returns "File"
7864<
7865 See |gettext()| for information on the domain parameter.
7866
7867 Return type: |String|
7868
7869
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007870nr2char({expr} [, {utf8}]) *nr2char()*
7871 Return a string with a single character, which has the number
7872 value {expr}. Examples: >
7873 nr2char(64) returns "@"
7874 nr2char(32) returns " "
7875< When {utf8} is omitted or zero, the current 'encoding' is used.
7876 Example for "utf-8": >
7877 nr2char(300) returns I with bow character
7878< When {utf8} is TRUE, always return UTF-8 characters.
7879 Note that a NUL character in the file is specified with
7880 nr2char(10), because NULs are represented with newline
7881 characters. nr2char(0) is a real NUL and terminates the
7882 string, thus results in an empty string.
7883 To turn a list of character numbers into a string: >
7884 let list = [65, 66, 67]
7885 let str = join(map(list, {_, val -> nr2char(val)}), '')
7886< Result: "ABC"
7887
7888 Can also be used as a |method|: >
7889 GetNumber()->nr2char()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007890<
7891 Return type: |String|
7892
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007893
7894or({expr}, {expr}) *or()*
7895 Bitwise OR on the two arguments. The arguments are converted
7896 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01007897 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007898 Example: >
7899 :let bits = or(bits, 0x80)
7900< Can also be used as a |method|: >
7901 :let bits = bits->or(0x80)
7902
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01007903< Rationale: The reason this is a function and not using the "|"
7904 character like many languages, is that Vi has always used "|"
7905 to separate commands. In many places it would not be clear if
7906 "|" is an operator or a command separator.
7907
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007908 Return type: |Number|
7909
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007910
7911pathshorten({path} [, {len}]) *pathshorten()*
7912 Shorten directory names in the path {path} and return the
7913 result. The tail, the file name, is kept as-is. The other
7914 components in the path are reduced to {len} letters in length.
7915 If {len} is omitted or smaller than 1 then 1 is used (single
7916 letters). Leading '~' and '.' characters are kept. Examples: >
7917 :echo pathshorten('~/.vim/autoload/myfile.vim')
7918< ~/.v/a/myfile.vim ~
7919>
7920 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
7921< ~/.vi/au/myfile.vim ~
7922 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007923 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007924
7925 Can also be used as a |method|: >
7926 GetDirectories()->pathshorten()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007927<
7928 Return type: |String|
7929
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007930
7931perleval({expr}) *perleval()*
7932 Evaluate Perl expression {expr} in scalar context and return
7933 its result converted to Vim data structures. If value can't be
7934 converted, it is returned as a string Perl representation.
7935 Note: If you want an array or hash, {expr} must return a
7936 reference to it.
7937 Example: >
7938 :echo perleval('[1 .. 4]')
7939< [1, 2, 3, 4]
7940
7941 Note that in a `:def` function local variables are not visible
7942 to {expr}.
7943
7944 Can also be used as a |method|: >
7945 GetExpr()->perleval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007946<
7947 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007948
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007949 {only available when compiled with the |+perl| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007950
7951
7952popup_ functions are documented here: |popup-functions|
7953
7954
7955pow({x}, {y}) *pow()*
7956 Return the power of {x} to the exponent {y} as a |Float|.
7957 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007958 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007959 Examples: >
7960 :echo pow(3, 3)
7961< 27.0 >
7962 :echo pow(2, 16)
7963< 65536.0 >
7964 :echo pow(32, 0.20)
7965< 2.0
7966
7967 Can also be used as a |method|: >
7968 Compute()->pow(3)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007969<
7970 Return type: |Number|
7971
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007972
7973prevnonblank({lnum}) *prevnonblank()*
7974 Return the line number of the first line at or above {lnum}
7975 that is not blank. Example: >
7976 let ind = indent(prevnonblank(v:lnum - 1))
7977< When {lnum} is invalid or there is no non-blank line at or
7978 above it, zero is returned.
7979 {lnum} is used like with |getline()|.
7980 Also see |nextnonblank()|.
7981
7982 Can also be used as a |method|: >
7983 GetLnum()->prevnonblank()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007984<
7985 Return type: |Number|
7986
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007987
7988printf({fmt}, {expr1} ...) *printf()*
7989 Return a String with {fmt}, where "%" items are replaced by
7990 the formatted form of their respective arguments. Example: >
7991 printf("%4d: E%d %.30s", lnum, errno, msg)
7992< May result in:
7993 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
7994
7995 When used as a |method| the base is passed as the second
7996 argument: >
7997 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007998<
7999 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008000
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01008001 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008002 %s string
8003 %6S string right-aligned in 6 display cells
8004 %6s string right-aligned in 6 bytes
8005 %.9s string truncated to 9 bytes
8006 %c single byte
8007 %d decimal number
8008 %5d decimal number padded with spaces to 5 characters
8009 %x hex number
8010 %04x hex number padded with zeros to at least 4 characters
8011 %X hex number using upper case letters
8012 %o octal number
8013 %08b binary number padded with zeros to at least 8 chars
8014 %f floating point number as 12.23, inf, -inf or nan
8015 %F floating point number as 12.23, INF, -INF or NAN
8016 %e floating point number as 1.23e3, inf, -inf or nan
8017 %E floating point number as 1.23E3, INF, -INF or NAN
8018 %g floating point number, as %f or %e depending on value
8019 %G floating point number, as %F or %E depending on value
8020 %% the % character itself
8021
8022 Conversion specifications start with '%' and end with the
8023 conversion type. All other characters are copied unchanged to
8024 the result.
8025
8026 The "%" starts a conversion specification. The following
8027 arguments appear in sequence:
8028
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008029 % [pos-argument] [flags] [field-width] [.precision] type
8030
8031 pos-argument
8032 At most one positional argument specifier. These
8033 take the form {n$}, where n is >= 1.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008034
8035 flags
8036 Zero or more of the following flags:
8037
8038 # The value should be converted to an "alternate
8039 form". For c, d, and s conversions, this option
8040 has no effect. For o conversions, the precision
8041 of the number is increased to force the first
8042 character of the output string to a zero (except
8043 if a zero value is printed with an explicit
8044 precision of zero).
8045 For b and B conversions, a non-zero result has
8046 the string "0b" (or "0B" for B conversions)
8047 prepended to it.
8048 For x and X conversions, a non-zero result has
8049 the string "0x" (or "0X" for X conversions)
8050 prepended to it.
8051
8052 0 (zero) Zero padding. For all conversions the converted
8053 value is padded on the left with zeros rather
8054 than blanks. If a precision is given with a
8055 numeric conversion (d, b, B, o, x, and X), the 0
8056 flag is ignored.
8057
8058 - A negative field width flag; the converted value
8059 is to be left adjusted on the field boundary.
8060 The converted value is padded on the right with
8061 blanks, rather than on the left with blanks or
8062 zeros. A - overrides a 0 if both are given.
8063
8064 ' ' (space) A blank should be left before a positive
8065 number produced by a signed conversion (d).
8066
8067 + A sign must always be placed before a number
8068 produced by a signed conversion. A + overrides
8069 a space if both are used.
8070
8071 field-width
8072 An optional decimal digit string specifying a minimum
8073 field width. If the converted value has fewer bytes
8074 than the field width, it will be padded with spaces on
8075 the left (or right, if the left-adjustment flag has
8076 been given) to fill out the field width. For the S
8077 conversion the count is in cells.
8078
8079 .precision
8080 An optional precision, in the form of a period '.'
8081 followed by an optional digit string. If the digit
8082 string is omitted, the precision is taken as zero.
8083 This gives the minimum number of digits to appear for
8084 d, o, x, and X conversions, the maximum number of
8085 bytes to be printed from a string for s conversions,
8086 or the maximum number of cells to be printed from a
8087 string for S conversions.
8088 For floating point it is the number of digits after
8089 the decimal point.
8090
8091 type
8092 A character that specifies the type of conversion to
8093 be applied, see below.
8094
8095 A field width or precision, or both, may be indicated by an
8096 asterisk '*' instead of a digit string. In this case, a
8097 Number argument supplies the field width or precision. A
8098 negative field width is treated as a left adjustment flag
8099 followed by a positive field width; a negative precision is
8100 treated as though it were missing. Example: >
8101 :echo printf("%d: %.*s", nr, width, line)
8102< This limits the length of the text used from "line" to
8103 "width" bytes.
8104
Dominique Pellé17dca3c2023-12-14 20:36:32 +01008105 If the argument to be formatted is specified using a
8106 positional argument specifier, and a '*' is used to indicate
8107 that a number argument is to be used to specify the width or
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008108 precision, the argument(s) to be used must also be specified
8109 using a {n$} positional argument specifier. See |printf-$|.
8110
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008111 The conversion specifiers and their meanings are:
8112
8113 *printf-d* *printf-b* *printf-B* *printf-o*
8114 *printf-x* *printf-X*
8115 dbBoxX The Number argument is converted to signed decimal
8116 (d), unsigned binary (b and B), unsigned octal (o), or
8117 unsigned hexadecimal (x and X) notation. The letters
8118 "abcdef" are used for x conversions; the letters
8119 "ABCDEF" are used for X conversions.
8120 The precision, if any, gives the minimum number of
8121 digits that must appear; if the converted value
8122 requires fewer digits, it is padded on the left with
8123 zeros.
8124 In no case does a non-existent or small field width
8125 cause truncation of a numeric field; if the result of
8126 a conversion is wider than the field width, the field
8127 is expanded to contain the conversion result.
8128 The 'h' modifier indicates the argument is 16 bits.
Christ van Willegenaa90d4f2023-09-03 17:22:37 +02008129 The 'l' modifier indicates the argument is a long
8130 integer. The size will be 32 bits or 64 bits
8131 depending on your platform.
8132 The "ll" modifier indicates the argument is 64 bits.
8133 The b and B conversion specifiers never take a width
8134 modifier and always assume their argument is a 64 bit
8135 integer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008136 Generally, these modifiers are not useful. They are
8137 ignored when type is known from the argument.
8138
8139 i alias for d
8140 D alias for ld
8141 U alias for lu
8142 O alias for lo
8143
8144 *printf-c*
8145 c The Number argument is converted to a byte, and the
8146 resulting character is written.
8147
8148 *printf-s*
8149 s The text of the String argument is used. If a
8150 precision is specified, no more bytes than the number
8151 specified are used.
8152 If the argument is not a String type, it is
8153 automatically converted to text with the same format
8154 as ":echo".
8155 *printf-S*
8156 S The text of the String argument is used. If a
8157 precision is specified, no more display cells than the
8158 number specified are used.
8159
8160 *printf-f* *E807*
8161 f F The Float argument is converted into a string of the
8162 form 123.456. The precision specifies the number of
8163 digits after the decimal point. When the precision is
8164 zero the decimal point is omitted. When the precision
8165 is not specified 6 is used. A really big number
8166 (out of range or dividing by zero) results in "inf"
8167 or "-inf" with %f (INF or -INF with %F).
8168 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
8169 Example: >
8170 echo printf("%.2f", 12.115)
8171< 12.12
8172 Note that roundoff depends on the system libraries.
8173 Use |round()| when in doubt.
8174
8175 *printf-e* *printf-E*
8176 e E The Float argument is converted into a string of the
8177 form 1.234e+03 or 1.234E+03 when using 'E'. The
8178 precision specifies the number of digits after the
8179 decimal point, like with 'f'.
8180
8181 *printf-g* *printf-G*
8182 g G The Float argument is converted like with 'f' if the
8183 value is between 0.001 (inclusive) and 10000000.0
8184 (exclusive). Otherwise 'e' is used for 'g' and 'E'
8185 for 'G'. When no precision is specified superfluous
8186 zeroes and '+' signs are removed, except for the zero
8187 immediately after the decimal point. Thus 10000000.0
8188 results in 1.0e7.
8189
8190 *printf-%*
8191 % A '%' is written. No argument is converted. The
8192 complete conversion specification is "%%".
8193
8194 When a Number argument is expected a String argument is also
8195 accepted and automatically converted.
8196 When a Float or String argument is expected a Number argument
8197 is also accepted and automatically converted.
8198 Any other argument type results in an error message.
8199
8200 *E766* *E767*
8201 The number of {exprN} arguments must exactly match the number
8202 of "%" items. If there are not sufficient or too many
8203 arguments an error is given. Up to 18 arguments can be used.
8204
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008205 *printf-$*
8206 In certain languages, error and informative messages are
8207 more readable when the order of words is different from the
Christian Brabandtee17b6f2023-09-09 11:23:50 +02008208 corresponding message in English. To accommodate translations
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008209 having a different word order, positional arguments may be
8210 used to indicate this. For instance: >
8211
h_east596a9f22023-11-21 21:24:23 +09008212 #, c-format
8213 msgid "%s returning %s"
8214 msgstr "waarde %2$s komt terug van %1$s"
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008215<
h_east596a9f22023-11-21 21:24:23 +09008216 In this example, the sentence has its 2 string arguments
8217 reversed in the output. >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008218
h_east596a9f22023-11-21 21:24:23 +09008219 echo printf(
8220 "In The Netherlands, vim's creator's name is: %1$s %2$s",
8221 "Bram", "Moolenaar")
8222< In The Netherlands, vim's creator's name is: Bram Moolenaar >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008223
h_east596a9f22023-11-21 21:24:23 +09008224 echo printf(
8225 "In Belgium, vim's creator's name is: %2$s %1$s",
8226 "Bram", "Moolenaar")
8227< In Belgium, vim's creator's name is: Moolenaar Bram
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008228
8229 Width (and precision) can be specified using the '*' specifier.
8230 In this case, you must specify the field width position in the
8231 argument list. >
8232
h_east596a9f22023-11-21 21:24:23 +09008233 echo printf("%1$*2$.*3$d", 1, 2, 3)
8234< 001 >
8235 echo printf("%2$*3$.*1$d", 1, 2, 3)
8236< 2 >
8237 echo printf("%3$*1$.*2$d", 1, 2, 3)
8238< 03 >
8239 echo printf("%1$*2$.*3$g", 1.4142, 2, 3)
8240< 1.414
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008241
8242 You can mix specifying the width and/or precision directly
8243 and via positional arguments: >
8244
h_east596a9f22023-11-21 21:24:23 +09008245 echo printf("%1$4.*2$f", 1.4142135, 6)
8246< 1.414214 >
8247 echo printf("%1$*2$.4f", 1.4142135, 6)
8248< 1.4142 >
8249 echo printf("%1$*2$.*3$f", 1.4142135, 6, 2)
8250< 1.41
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008251
Christ van Willegenc35fc032024-03-14 18:30:41 +01008252 You will get an overflow error |E1510|, when the field-width
Hirohito Higashi0ed11ba2025-04-18 18:45:31 +02008253 or precision will result in a string longer than 1 MiB
zeertzjqe9a27ef2025-04-18 10:45:45 +02008254 (1024*1024 = 1048576) chars.
Christ van Willegenc35fc032024-03-14 18:30:41 +01008255
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008256 *E1500*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008257 You cannot mix positional and non-positional arguments: >
h_east596a9f22023-11-21 21:24:23 +09008258 echo printf("%s%1$s", "One", "Two")
8259< E1500: Cannot mix positional and non-positional arguments:
8260 %s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008261
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008262 *E1501*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008263 You cannot skip a positional argument in a format string: >
h_east596a9f22023-11-21 21:24:23 +09008264 echo printf("%3$s%1$s", "One", "Two", "Three")
8265< E1501: format argument 2 unused in $-style format:
8266 %3$s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008267
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008268 *E1502*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008269 You can re-use a [field-width] (or [precision]) argument: >
h_east596a9f22023-11-21 21:24:23 +09008270 echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2)
8271< 1 at width 2 is: 01
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008272
8273 However, you can't use it as a different type: >
h_east596a9f22023-11-21 21:24:23 +09008274 echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2)
8275< E1502: Positional argument 2 used as field width reused as
8276 different type: long int/int
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008277
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008278 *E1503*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008279 When a positional argument is used, but not the correct number
8280 or arguments is given, an error is raised: >
h_east596a9f22023-11-21 21:24:23 +09008281 echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2)
8282< E1503: Positional argument 3 out of bounds: %1$d at width
8283 %2$d is: %01$*2$.*3$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008284
8285 Only the first error is reported: >
h_east596a9f22023-11-21 21:24:23 +09008286 echo printf("%01$*2$.*3$d %4$d", 1, 2)
8287< E1503: Positional argument 3 out of bounds: %01$*2$.*3$d
8288 %4$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008289
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008290 *E1504*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008291 A positional argument can be used more than once: >
h_east596a9f22023-11-21 21:24:23 +09008292 echo printf("%1$s %2$s %1$s", "One", "Two")
8293< One Two One
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008294
8295 However, you can't use a different type the second time: >
h_east596a9f22023-11-21 21:24:23 +09008296 echo printf("%1$s %2$s %1$d", "One", "Two")
8297< E1504: Positional argument 1 type used inconsistently:
8298 int/string
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008299
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008300 *E1505*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008301 Various other errors that lead to a format string being
8302 wrongly formatted lead to: >
h_east596a9f22023-11-21 21:24:23 +09008303 echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2)
8304< E1505: Invalid format specifier: %1$d at width %2$d is:
8305 %01$*2$.3$d
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008306
Christ van Willegenea746f92023-10-05 20:48:36 +02008307 *E1507*
zeertzjq27e12c72023-10-07 01:34:04 +08008308 This internal error indicates that the logic to parse a
8309 positional format argument ran into a problem that couldn't be
8310 otherwise reported. Please file a bug against Vim if you run
8311 into this, copying the exact format string and parameters that
8312 were used.
Christ van Willegenea746f92023-10-05 20:48:36 +02008313
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008314 Return type: |String|
8315
Christ van Willegenea746f92023-10-05 20:48:36 +02008316
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008317prompt_getprompt({buf}) *prompt_getprompt()*
8318 Returns the effective prompt text for buffer {buf}. {buf} can
8319 be a buffer name or number. See |prompt-buffer|.
8320
8321 If the buffer doesn't exist or isn't a prompt buffer, an empty
8322 string is returned.
8323
8324 Can also be used as a |method|: >
8325 GetBuffer()->prompt_getprompt()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008326<
8327 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008328
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008329 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008330
8331
8332prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
8333 Set prompt callback for buffer {buf} to {expr}. When {expr}
8334 is an empty string the callback is removed. This has only
8335 effect if {buf} has 'buftype' set to "prompt".
8336
8337 The callback is invoked when pressing Enter. The current
8338 buffer will always be the prompt buffer. A new line for a
8339 prompt is added before invoking the callback, thus the prompt
8340 for which the callback was invoked will be in the last but one
8341 line.
8342 If the callback wants to add text to the buffer, it must
8343 insert it above the last line, since that is where the current
8344 prompt is. This can also be done asynchronously.
8345 The callback is invoked with one argument, which is the text
8346 that was entered at the prompt. This can be an empty string
8347 if the user only typed Enter.
8348 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008349 func s:TextEntered(text)
8350 if a:text == 'exit' || a:text == 'quit'
8351 stopinsert
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008352 " Reset 'modified' to allow the buffer to be closed.
8353 " We assume there is nothing useful to be saved.
8354 set nomodified
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008355 close
8356 else
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008357 " Do something useful with "a:text". In this example
8358 " we just repeat it.
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008359 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008360 endif
8361 endfunc
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008362 call prompt_setcallback(bufnr(), function('s:TextEntered'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008363
8364< Can also be used as a |method|: >
8365 GetBuffer()->prompt_setcallback(callback)
8366
8367< {only available when compiled with the |+channel| feature}
8368
8369prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
8370 Set a callback for buffer {buf} to {expr}. When {expr} is an
8371 empty string the callback is removed. This has only effect if
8372 {buf} has 'buftype' set to "prompt".
8373
8374 This callback will be invoked when pressing CTRL-C in Insert
8375 mode. Without setting a callback Vim will exit Insert mode,
8376 as in any buffer.
8377
8378 Can also be used as a |method|: >
8379 GetBuffer()->prompt_setinterrupt(callback)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008380<
8381 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008382
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008383 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008384
8385prompt_setprompt({buf}, {text}) *prompt_setprompt()*
8386 Set prompt for buffer {buf} to {text}. You most likely want
8387 {text} to end in a space.
8388 The result is only visible if {buf} has 'buftype' set to
8389 "prompt". Example: >
8390 call prompt_setprompt(bufnr(), 'command: ')
8391<
8392 Can also be used as a |method|: >
8393 GetBuffer()->prompt_setprompt('command: ')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008394<
8395 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008396
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008397 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008398
8399prop_ functions are documented here: |text-prop-functions|
8400
8401pum_getpos() *pum_getpos()*
8402 If the popup menu (see |ins-completion-menu|) is not visible,
8403 returns an empty |Dictionary|, otherwise, returns a
8404 |Dictionary| with the following keys:
8405 height nr of items visible
8406 width screen cells
8407 row top screen row (0 first row)
8408 col leftmost screen column (0 first col)
8409 size total nr of items
8410 scrollbar |TRUE| if scrollbar is visible
8411
8412 The values are the same as in |v:event| during
8413 |CompleteChanged|.
8414
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008415 Return type: dict<any>
8416
8417
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008418pumvisible() *pumvisible()*
8419 Returns non-zero when the popup menu is visible, zero
8420 otherwise. See |ins-completion-menu|.
8421 This can be used to avoid some things that would remove the
8422 popup menu.
8423
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008424 Return type: |Number|
8425
8426
zeertzjq7c515282024-11-10 20:26:12 +01008427py3eval({expr} [, {locals}]) *py3eval()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008428 Evaluate Python expression {expr} and return its result
8429 converted to Vim data structures.
Ben Jacksonea19e782024-11-06 21:50:05 +01008430 If a {locals} |Dictionary| is given, it defines set of local
8431 variables available in the expression. The keys are variable
Yegappan Lakshmanan038be272025-03-26 18:46:21 +01008432 names and the values are the variable values. |Dictionary|,
8433 |List| and |Tuple| values are referenced, and may be updated
8434 by the expression (as if |python-bindeval| was used).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008435 Numbers and strings are returned as they are (strings are
8436 copied though, Unicode strings are additionally converted to
8437 'encoding').
8438 Lists are represented as Vim |List| type.
Yegappan Lakshmanan038be272025-03-26 18:46:21 +01008439 Tuples are represented as Vim |Tuple| type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008440 Dictionaries are represented as Vim |Dictionary| type with
8441 keys converted to strings.
8442 Note that in a `:def` function local variables are not visible
8443 to {expr}.
8444
8445 Can also be used as a |method|: >
8446 GetExpr()->py3eval()
Ben Jacksonea19e782024-11-06 21:50:05 +01008447 'b",".join(l)'->py3eval({'l': ['a', 'b', 'c']})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008448<
8449 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008450
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008451 {only available when compiled with the |+python3| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008452
8453 *E858* *E859*
zeertzjq7c515282024-11-10 20:26:12 +01008454pyeval({expr} [, {locals}]) *pyeval()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008455 Evaluate Python expression {expr} and return its result
8456 converted to Vim data structures.
Ben Jacksonea19e782024-11-06 21:50:05 +01008457 For {locals} see |py3eval()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008458 Numbers and strings are returned as they are (strings are
8459 copied though).
8460 Lists are represented as Vim |List| type.
Yegappan Lakshmanan038be272025-03-26 18:46:21 +01008461 Tuples are represented as Vim |Tuple| type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008462 Dictionaries are represented as Vim |Dictionary| type,
8463 non-string keys result in error.
8464 Note that in a `:def` function local variables are not visible
8465 to {expr}.
8466
8467 Can also be used as a |method|: >
8468 GetExpr()->pyeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008469<
8470 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008471
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008472 {only available when compiled with the |+python| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008473
zeertzjq7c515282024-11-10 20:26:12 +01008474pyxeval({expr} [, {locals}]) *pyxeval()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008475 Evaluate Python expression {expr} and return its result
8476 converted to Vim data structures.
Ben Jacksonea19e782024-11-06 21:50:05 +01008477 For {locals} see |py3eval()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008478 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
8479 See also: |pyeval()|, |py3eval()|
8480
8481 Can also be used as a |method|: >
h-east52e7cc22024-07-28 17:03:29 +02008482 GetExpr()->pyxeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008483<
8484 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008485
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008486 {only available when compiled with the |+python| or the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008487 |+python3| feature}
8488
8489rand([{expr}]) *rand()* *random*
8490 Return a pseudo-random Number generated with an xoshiro128**
8491 algorithm using seed {expr}. The returned number is 32 bits,
8492 also on 64 bits systems, for consistency.
8493 {expr} can be initialized by |srand()| and will be updated by
8494 rand(). If {expr} is omitted, an internal seed value is used
8495 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008496 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008497
8498 Examples: >
8499 :echo rand()
8500 :let seed = srand()
8501 :echo rand(seed)
8502 :echo rand(seed) % 16 " random number 0 - 15
8503<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008504 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008505
8506 *E726* *E727*
8507range({expr} [, {max} [, {stride}]]) *range()*
8508 Returns a |List| with Numbers:
8509 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
8510 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
8511 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
8512 {max}] (increasing {expr} with {stride} each time, not
8513 producing a value past {max}).
8514 When the maximum is one before the start the result is an
8515 empty list. When the maximum is more than one before the
8516 start this is an error.
8517 Examples: >
8518 range(4) " [0, 1, 2, 3]
8519 range(2, 4) " [2, 3, 4]
8520 range(2, 9, 3) " [2, 5, 8]
8521 range(2, -2, -1) " [2, 1, 0, -1, -2]
8522 range(0) " []
8523 range(2, 0) " error!
8524<
8525 Can also be used as a |method|: >
8526 GetExpr()->range()
8527<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008528 Return type: list<number>
8529
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008530
K.Takata11df3ae2022-10-19 14:02:40 +01008531readblob({fname} [, {offset} [, {size}]]) *readblob()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008532 Read file {fname} in binary mode and return a |Blob|.
K.Takata11df3ae2022-10-19 14:02:40 +01008533 If {offset} is specified, read the file from the specified
8534 offset. If it is a negative value, it is used as an offset
8535 from the end of the file. E.g., to read the last 12 bytes: >
8536 readblob('file.bin', -12)
8537< If {size} is specified, only the specified size will be read.
8538 E.g. to read the first 100 bytes of a file: >
8539 readblob('file.bin', 0, 100)
8540< If {size} is -1 or omitted, the whole data starting from
8541 {offset} will be read.
K.Takata43625762022-10-20 13:28:51 +01008542 This can be also used to read the data from a character device
8543 on Unix when {size} is explicitly set. Only if the device
8544 supports seeking {offset} can be used. Otherwise it should be
8545 zero. E.g. to read 10 bytes from a serial console: >
8546 readblob('/dev/ttyS0', 0, 10)
8547< When the file can't be opened an error message is given and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008548 the result is an empty |Blob|.
Bram Moolenaar5b2a3d72022-10-21 11:25:30 +01008549 When the offset is beyond the end of the file the result is an
8550 empty blob.
8551 When trying to read more bytes than are available the result
8552 is truncated.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008553 Also see |readfile()| and |writefile()|.
8554
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008555 Return type: |Blob|
8556
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008557
8558readdir({directory} [, {expr} [, {dict}]]) *readdir()*
8559 Return a list with file and directory names in {directory}.
8560 You can also use |glob()| if you don't need to do complicated
8561 things, such as limiting the number of matches.
8562 The list will be sorted (case sensitive), see the {dict}
8563 argument below for changing the sort order.
8564
8565 When {expr} is omitted all entries are included.
8566 When {expr} is given, it is evaluated to check what to do:
8567 If {expr} results in -1 then no further entries will
8568 be handled.
8569 If {expr} results in 0 then this entry will not be
8570 added to the list.
8571 If {expr} results in 1 then this entry will be added
8572 to the list.
8573 The entries "." and ".." are always excluded.
8574 Each time {expr} is evaluated |v:val| is set to the entry name.
8575 When {expr} is a function the name is passed as the argument.
8576 For example, to get a list of files ending in ".txt": >
8577 readdir(dirname, {n -> n =~ '.txt$'})
8578< To skip hidden and backup files: >
8579 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00008580< *E857*
8581 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008582 values. Currently this is used to specify if and how sorting
8583 should be performed. The dict can have the following members:
8584
8585 sort How to sort the result returned from the system.
8586 Valid values are:
8587 "none" do not sort (fastest method)
8588 "case" sort case sensitive (byte value of
8589 each character, technically, using
8590 strcmp()) (default)
8591 "icase" sort case insensitive (technically
8592 using strcasecmp())
8593 "collate" sort using the collation order
8594 of the "POSIX" or "C" |locale|
8595 (technically using strcoll())
8596 Other values are silently ignored.
8597
8598 For example, to get a list of all files in the current
8599 directory without sorting the individual entries: >
8600 readdir('.', '1', #{sort: 'none'})
8601< If you want to get a directory tree: >
8602 function! s:tree(dir)
8603 return {a:dir : map(readdir(a:dir),
8604 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008605 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008606 endfunction
8607 echo s:tree(".")
8608<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008609 Returns an empty List on error.
8610
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008611 Can also be used as a |method|: >
8612 GetDirName()->readdir()
8613<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008614 Return type: list<string> or list<any>
8615
8616
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008617readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
8618 Extended version of |readdir()|.
8619 Return a list of Dictionaries with file and directory
8620 information in {directory}.
8621 This is useful if you want to get the attributes of file and
8622 directory at the same time as getting a list of a directory.
8623 This is much faster than calling |readdir()| then calling
8624 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
8625 each file and directory especially on MS-Windows.
8626 The list will by default be sorted by name (case sensitive),
8627 the sorting can be changed by using the optional {dict}
8628 argument, see |readdir()|.
8629
8630 The Dictionary for file and directory information has the
8631 following items:
8632 group Group name of the entry. (Only on Unix)
8633 name Name of the entry.
8634 perm Permissions of the entry. See |getfperm()|.
8635 size Size of the entry. See |getfsize()|.
8636 time Timestamp of the entry. See |getftime()|.
8637 type Type of the entry.
8638 On Unix, almost same as |getftype()| except:
8639 Symlink to a dir "linkd"
8640 Other symlink "link"
8641 On MS-Windows:
8642 Normal file "file"
8643 Directory "dir"
8644 Junction "junction"
8645 Symlink to a dir "linkd"
8646 Other symlink "link"
8647 Other reparse point "reparse"
8648 user User name of the entry's owner. (Only on Unix)
8649 On Unix, if the entry is a symlink, the Dictionary includes
8650 the information of the target (except the "type" item).
8651 On MS-Windows, it includes the information of the symlink
8652 itself because of performance reasons.
8653
8654 When {expr} is omitted all entries are included.
8655 When {expr} is given, it is evaluated to check what to do:
8656 If {expr} results in -1 then no further entries will
8657 be handled.
8658 If {expr} results in 0 then this entry will not be
8659 added to the list.
8660 If {expr} results in 1 then this entry will be added
8661 to the list.
8662 The entries "." and ".." are always excluded.
8663 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
8664 of the entry.
8665 When {expr} is a function the entry is passed as the argument.
8666 For example, to get a list of files ending in ".txt": >
8667 readdirex(dirname, {e -> e.name =~ '.txt$'})
8668<
8669 For example, to get a list of all files in the current
8670 directory without sorting the individual entries: >
8671 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008672<
8673 Can also be used as a |method|: >
8674 GetDirName()->readdirex()
8675<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008676 Return type: list<dict<any>> or list<any>
8677
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008678
8679 *readfile()*
8680readfile({fname} [, {type} [, {max}]])
8681 Read file {fname} and return a |List|, each line of the file
8682 as an item. Lines are broken at NL characters. Macintosh
8683 files separated with CR will result in a single long line
8684 (unless a NL appears somewhere).
8685 All NUL characters are replaced with a NL character.
8686 When {type} contains "b" binary mode is used:
8687 - When the last line ends in a NL an extra empty list item is
8688 added.
8689 - No CR characters are removed.
8690 Otherwise:
8691 - CR characters that appear before a NL are removed.
8692 - Whether the last line ends in a NL or not does not matter.
8693 - When 'encoding' is Unicode any UTF-8 byte order mark is
8694 removed from the text.
8695 When {max} is given this specifies the maximum number of lines
8696 to be read. Useful if you only want to check the first ten
8697 lines of a file: >
8698 :for line in readfile(fname, '', 10)
8699 : if line =~ 'Date' | echo line | endif
8700 :endfor
8701< When {max} is negative -{max} lines from the end of the file
8702 are returned, or as many as there are.
8703 When {max} is zero the result is an empty list.
8704 Note that without {max} the whole file is read into memory.
8705 Also note that there is no recognition of encoding. Read a
8706 file into a buffer if you need to.
8707 Deprecated (use |readblob()| instead): When {type} contains
8708 "B" a |Blob| is returned with the binary data of the file
8709 unmodified.
8710 When the file can't be opened an error message is given and
8711 the result is an empty list.
8712 Also see |writefile()|.
8713
8714 Can also be used as a |method|: >
8715 GetFileName()->readfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008716<
8717 Return type: list<string> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008718
8719reduce({object}, {func} [, {initial}]) *reduce()* *E998*
8720 {func} is called for every item in {object}, which can be a
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01008721 |String|, |List|, |Tuple| or a |Blob|. {func} is called with
8722 two arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00008723 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008724
8725 {initial} is the initial result. When omitted, the first item
8726 in {object} is used and {func} is first called for the second
8727 item. If {initial} is not given and {object} is empty no
8728 result can be computed, an E998 error is given.
8729
8730 Examples: >
8731 echo reduce([1, 3, 5], { acc, val -> acc + val })
8732 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
8733 echo reduce(0z1122, { acc, val -> 2 * acc + val })
8734 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
8735<
8736 Can also be used as a |method|: >
8737 echo mylist->reduce({ acc, val -> acc + val }, 0)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008738<
8739 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
8740 depending on {object} and {func}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008741
8742
8743reg_executing() *reg_executing()*
8744 Returns the single letter name of the register being executed.
8745 Returns an empty string when no register is being executed.
8746 See |@|.
8747
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008748 Return type: |String|
8749
8750
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008751reg_recording() *reg_recording()*
8752 Returns the single letter name of the register being recorded.
8753 Returns an empty string when not recording. See |q|.
8754
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008755 Return type: |String|
8756
8757
8758reltime() *reltime()*
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008759reltime({start})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008760reltime({start}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008761 Return an item that represents a time value. The item is a
8762 list with items that depend on the system. In Vim 9 script
Bram Moolenaar71badf92023-04-22 22:40:14 +01008763 the type list<any> can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008764 The item can be passed to |reltimestr()| to convert it to a
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008765 string or |reltimefloat()| to convert to a Float. For
8766 example, to see the time spent in function Work(): >
8767 var startTime = reltime()
8768 Work()
8769 echo startTime->reltime()->reltimestr()
8770<
Bram Moolenaar016188f2022-06-06 20:52:59 +01008771 Without an argument reltime() returns the current time (the
Lifepillar963fd7d2024-01-05 17:44:57 +01008772 representation is system-dependent, it cannot be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01008773 wall-clock time, see |localtime()| for that).
Lifepillar963fd7d2024-01-05 17:44:57 +01008774 With one argument it returns the time passed since the time
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008775 specified in the argument.
8776 With two arguments it returns the time passed between {start}
8777 and {end}.
8778
8779 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008780 reltime(). If there is an error an empty List is returned in
8781 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008782
8783 Can also be used as a |method|: >
8784 GetStart()->reltime()
8785<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008786 Return type: list<number>
8787
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008788 {only available when compiled with the |+reltime| feature}
8789
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008790
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008791reltimefloat({time}) *reltimefloat()*
8792 Return a Float that represents the time value of {time}.
8793 Example: >
8794 let start = reltime()
8795 call MyFunction()
8796 let seconds = reltimefloat(reltime(start))
8797< See the note of reltimestr() about overhead.
8798 Also see |profiling|.
8799 If there is an error 0.0 is returned in legacy script, in Vim9
8800 script an error is given.
8801
8802 Can also be used as a |method|: >
8803 reltime(start)->reltimefloat()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008804<
8805 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008806
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008807 {only available when compiled with the |+reltime| feature}
8808
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008809
8810reltimestr({time}) *reltimestr()*
8811 Return a String that represents the time value of {time}.
8812 This is the number of seconds, a dot and the number of
8813 microseconds. Example: >
8814 let start = reltime()
8815 call MyFunction()
8816 echo reltimestr(reltime(start))
8817< Note that overhead for the commands will be added to the time.
Ernie Rael076de792023-03-16 21:43:15 +00008818 The accuracy depends on the system. Use reltimefloat() for the
8819 greatest accuracy which is nanoseconds on some systems.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008820 Leading spaces are used to make the string align nicely. You
8821 can use split() to remove it. >
8822 echo split(reltimestr(reltime(start)))[0]
8823< Also see |profiling|.
8824 If there is an error an empty string is returned in legacy
8825 script, in Vim9 script an error is given.
8826
8827 Can also be used as a |method|: >
8828 reltime(start)->reltimestr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008829<
8830 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008831
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008832 {only available when compiled with the |+reltime| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008833
8834 *remote_expr()* *E449*
8835remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00008836 Send the {string} to {server}. The {server} argument is a
8837 string, also see |{server}|.
8838
8839 The string is sent as an expression and the result is returned
Christian Brabandt1961caf2024-10-12 11:57:12 +02008840 after evaluation. The result must be a String or a |List|
8841 other types will be converted to String. A |List| is turned
8842 into a String by joining the items with a line break in
8843 between (not at the end), like with join(expr, "\n").
Bram Moolenaar944697a2022-02-20 19:48:20 +00008844
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008845 If {idvar} is present and not empty, it is taken as the name
8846 of a variable and a {serverid} for later use with
8847 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008848
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008849 If {timeout} is given the read times out after this many
8850 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008851
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008852 See also |clientserver| |RemoteReply|.
8853 This function is not available in the |sandbox|.
8854 {only available when compiled with the |+clientserver| feature}
8855 Note: Any errors will cause a local error message to be issued
8856 and the result will be the empty string.
8857
8858 Variables will be evaluated in the global namespace,
8859 independent of a function currently being active. Except
8860 when in debug mode, then local function variables and
8861 arguments can be evaluated.
8862
8863 Examples: >
8864 :echo remote_expr("gvim", "2+2")
8865 :echo remote_expr("gvim1", "b:current_syntax")
8866<
8867 Can also be used as a |method|: >
8868 ServerName()->remote_expr(expr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008869<
8870 Return type: |String| or list<{type}>
8871
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008872
8873remote_foreground({server}) *remote_foreground()*
8874 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008875 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008876 This works like: >
8877 remote_expr({server}, "foreground()")
8878< Except that on Win32 systems the client does the work, to work
8879 around the problem that the OS doesn't always allow the server
8880 to bring itself to the foreground.
8881 Note: This does not restore the window if it was minimized,
8882 like foreground() does.
8883 This function is not available in the |sandbox|.
8884
8885 Can also be used as a |method|: >
8886 ServerName()->remote_foreground()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008887<
8888 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008889
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008890 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008891 Win32 console version}
8892
8893
8894remote_peek({serverid} [, {retvar}]) *remote_peek()*
8895 Returns a positive number if there are available strings
8896 from {serverid}. Copies any reply string into the variable
8897 {retvar} if specified. {retvar} must be a string with the
8898 name of a variable.
8899 Returns zero if none are available.
8900 Returns -1 if something is wrong.
8901 See also |clientserver|.
8902 This function is not available in the |sandbox|.
8903 {only available when compiled with the |+clientserver| feature}
8904 Examples: >
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008905 :let repl = ""
8906 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008907
8908< Can also be used as a |method|: >
8909 ServerId()->remote_peek()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008910<
8911 Return type: |Number|
8912
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008913
8914remote_read({serverid}, [{timeout}]) *remote_read()*
8915 Return the oldest available reply from {serverid} and consume
8916 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008917 reply is available. Returns an empty string, if a reply is
8918 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008919 See also |clientserver|.
8920 This function is not available in the |sandbox|.
8921 {only available when compiled with the |+clientserver| feature}
8922 Example: >
8923 :echo remote_read(id)
8924
8925< Can also be used as a |method|: >
8926 ServerId()->remote_read()
8927<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008928 Return type: |String|
8929
8930
8931remote_send({server}, {string} [, {idvar}]) *remote_send()* *E241*
Bram Moolenaar944697a2022-02-20 19:48:20 +00008932 Send the {string} to {server}. The {server} argument is a
8933 string, also see |{server}|.
8934
8935 The string is sent as input keys and the function returns
8936 immediately. At the Vim server the keys are not mapped
8937 |:map|.
8938
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008939 If {idvar} is present, it is taken as the name of a variable
8940 and a {serverid} for later use with remote_read() is stored
8941 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008942
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008943 See also |clientserver| |RemoteReply|.
8944 This function is not available in the |sandbox|.
8945 {only available when compiled with the |+clientserver| feature}
8946
8947 Note: Any errors will be reported in the server and may mess
8948 up the display.
8949 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008950 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008951 \ remote_read(serverid)
8952
8953 :autocmd NONE RemoteReply *
8954 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008955 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008956 \ 'server2client(expand("<client>"), "HELLO")<CR>')
8957<
8958 Can also be used as a |method|: >
8959 ServerName()->remote_send(keys)
8960<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008961 Return type: |String|
8962
8963
8964remote_startserver({name}) *remote_startserver()* *E941* *E942*
h-east17b69512023-05-01 22:36:56 +01008965 Become the server {name}. {name} must be a non-empty string.
8966 This fails if already running as a server, when |v:servername|
8967 is not empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008968
8969 Can also be used as a |method|: >
8970 ServerName()->remote_startserver()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008971<
8972 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008973
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008974 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008975
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008976
8977remove({list}, {idx}) *remove()*
8978remove({list}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008979 Without {end}: Remove the item at {idx} from |List| {list} and
8980 return the item.
8981 With {end}: Remove items from {idx} to {end} (inclusive) and
8982 return a |List| with these items. When {idx} points to the same
8983 item as {end} a list with one item is returned. When {end}
8984 points to an item before {idx} this is an error.
8985 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008986 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008987 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008988 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008989 :call remove(mylist, 0, 9)
8990<
8991 Use |delete()| to remove a file.
8992
8993 Can also be used as a |method|: >
8994 mylist->remove(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008995<
8996 Return type: any, depending on {list}
8997
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008998
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008999remove({blob}, {idx})
9000remove({blob}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009001 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
9002 return the byte.
9003 With {end}: Remove bytes from {idx} to {end} (inclusive) and
9004 return a |Blob| with these bytes. When {idx} points to the same
9005 byte as {end} a |Blob| with one byte is returned. When {end}
9006 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009007 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009008 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009009 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009010 :call remove(mylist, 0, 9)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009011<
9012 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009013
9014remove({dict}, {key})
9015 Remove the entry from {dict} with key {key} and return it.
9016 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009017 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009018< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009019 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009020
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009021 Return type: any, depending on {dict}
9022
9023
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009024rename({from}, {to}) *rename()*
9025 Rename the file by the name {from} to the name {to}. This
9026 should also work to move files across file systems. The
9027 result is a Number, which is 0 if the file was renamed
9028 successfully, and non-zero when the renaming failed.
9029 NOTE: If {to} exists it is overwritten without warning.
9030 This function is not available in the |sandbox|.
9031
9032 Can also be used as a |method|: >
9033 GetOldName()->rename(newname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009034<
9035 Return type: |Number|
9036
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009037
9038repeat({expr}, {count}) *repeat()*
9039 Repeat {expr} {count} times and return the concatenated
9040 result. Example: >
9041 :let separator = repeat('-', 80)
9042< When {count} is zero or negative the result is empty.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01009043 When {expr} is a |List|, a |Tuple| or a |Blob| the result is
9044 {expr} concatenated {count} times. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009045 :let longlist = repeat(['a', 'b'], 3)
9046< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
9047
9048 Can also be used as a |method|: >
9049 mylist->repeat(count)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009050<
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01009051 Return type: |String|, |Blob|, list<{type}> or tuple<{type}>
9052 depending on {expr}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009053
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009054
9055resolve({filename}) *resolve()* *E655*
9056 On MS-Windows, when {filename} is a shortcut (a .lnk file),
9057 returns the path the shortcut points to in a simplified form.
9058 When {filename} is a symbolic link or junction point, return
9059 the full path to the target. If the target of junction is
9060 removed, return {filename}.
9061 On Unix, repeat resolving symbolic links in all path
9062 components of {filename} and return the simplified result.
9063 To cope with link cycles, resolving of symbolic links is
9064 stopped after 100 iterations.
9065 On other systems, return the simplified {filename}.
9066 The simplification step is done as by |simplify()|.
9067 resolve() keeps a leading path component specifying the
9068 current directory (provided the result is still a relative
9069 path name) and also keeps a trailing path separator.
9070
9071 Can also be used as a |method|: >
9072 GetName()->resolve()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009073<
9074 Return type: |String|
9075
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009076
9077reverse({object}) *reverse()*
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +01009078 Reverse the order of items in {object}. {object} can be a
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01009079 |List|, a |Tuple|, a |Blob| or a |String|. For a List and a
9080 Blob the items are reversed in-place and {object} is returned.
9081 For a Tuple, a new Tuple is returned.
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +01009082 For a String a new String is returned.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01009083 Returns zero if {object} is not a List, Tuple, Blob or a
9084 String. If you want a List or Blob to remain unmodified make
9085 a copy first: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009086 :let revlist = reverse(copy(mylist))
9087< Can also be used as a |method|: >
9088 mylist->reverse()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009089<
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01009090 Return type: |String|, |Blob|, list<{type}> or tuple<{type}>
9091 depending on {object}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009092
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009093
9094round({expr}) *round()*
9095 Round off {expr} to the nearest integral value and return it
9096 as a |Float|. If {expr} lies halfway between two integral
9097 values, then use the larger one (away from zero).
9098 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009099 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009100 Examples: >
9101 echo round(0.456)
9102< 0.0 >
9103 echo round(4.5)
9104< 5.0 >
9105 echo round(-4.5)
9106< -5.0
9107
9108 Can also be used as a |method|: >
9109 Compute()->round()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009110<
9111 Return type: |Float|
9112
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009113
9114rubyeval({expr}) *rubyeval()*
9115 Evaluate Ruby expression {expr} and return its result
9116 converted to Vim data structures.
9117 Numbers, floats and strings are returned as they are (strings
9118 are copied though).
9119 Arrays are represented as Vim |List| type.
9120 Hashes are represented as Vim |Dictionary| type.
9121 Other objects are represented as strings resulted from their
9122 "Object#to_s" method.
9123 Note that in a `:def` function local variables are not visible
9124 to {expr}.
9125
9126 Can also be used as a |method|: >
9127 GetRubyExpr()->rubyeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009128<
9129 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009130
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009131 {only available when compiled with the |+ruby| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009132
9133screenattr({row}, {col}) *screenattr()*
9134 Like |screenchar()|, but return the attribute. This is a rather
9135 arbitrary number that can only be used to compare to the
9136 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009137 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009138
9139 Can also be used as a |method|: >
9140 GetRow()->screenattr(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009141<
9142 Return type: |Number|
9143
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009144
9145screenchar({row}, {col}) *screenchar()*
9146 The result is a Number, which is the character at position
9147 [row, col] on the screen. This works for every possible
9148 screen position, also status lines, window separators and the
9149 command line. The top left position is row one, column one
9150 The character excludes composing characters. For double-byte
9151 encodings it may only be the first byte.
9152 This is mainly to be used for testing.
9153 Returns -1 when row or col is out of range.
9154
9155 Can also be used as a |method|: >
9156 GetRow()->screenchar(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009157<
9158 Return type: |Number|
9159
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009160
9161screenchars({row}, {col}) *screenchars()*
9162 The result is a |List| of Numbers. The first number is the same
9163 as what |screenchar()| returns. Further numbers are
9164 composing characters on top of the base character.
9165 This is mainly to be used for testing.
9166 Returns an empty List when row or col is out of range.
9167
9168 Can also be used as a |method|: >
9169 GetRow()->screenchars(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009170<
9171 Return type: list<number> or list<any>
9172
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009173
9174screencol() *screencol()*
9175 The result is a Number, which is the current screen column of
9176 the cursor. The leftmost column has number 1.
9177 This function is mainly used for testing.
9178
9179 Note: Always returns the current screen column, thus if used
9180 in a command (e.g. ":echo screencol()") it will return the
9181 column inside the command line, which is 1 when the command is
9182 executed. To get the cursor position in the file use one of
9183 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009184 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009185 nnoremap <silent> GG :echom screencol()<CR>
9186 nnoremap GG <Cmd>echom screencol()<CR>
9187<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009188 Return type: |Number|
9189
9190
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009191screenpos({winid}, {lnum}, {col}) *screenpos()*
9192 The result is a Dict with the screen position of the text
9193 character in window {winid} at buffer line {lnum} and column
9194 {col}. {col} is a one-based byte index.
9195 The Dict has these members:
9196 row screen row
9197 col first screen column
9198 endcol last screen column
9199 curscol cursor screen column
9200 If the specified position is not visible, all values are zero.
9201 The "endcol" value differs from "col" when the character
9202 occupies more than one screen cell. E.g. for a Tab "col" can
9203 be 1 and "endcol" can be 8.
9204 The "curscol" value is where the cursor would be placed. For
9205 a Tab it would be the same as "endcol", while for a double
9206 width character it would be the same as "col".
9207 The |conceal| feature is ignored here, the column numbers are
9208 as if 'conceallevel' is zero. You can set the cursor to the
9209 right position and use |screencol()| to get the value with
9210 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00009211 If the position is in a closed fold the screen position of the
9212 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009213 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009214
9215 Can also be used as a |method|: >
9216 GetWinid()->screenpos(lnum, col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009217<
9218 Return type: dict<number> or dict<any>
9219
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009220
9221screenrow() *screenrow()*
9222 The result is a Number, which is the current screen row of the
9223 cursor. The top line has number one.
9224 This function is mainly used for testing.
9225 Alternatively you can use |winline()|.
9226
9227 Note: Same restrictions as with |screencol()|.
9228
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009229 Return type: |Number|
9230
9231
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009232screenstring({row}, {col}) *screenstring()*
9233 The result is a String that contains the base character and
9234 any composing characters at position [row, col] on the screen.
9235 This is like |screenchars()| but returning a String with the
9236 characters.
9237 This is mainly to be used for testing.
9238 Returns an empty String when row or col is out of range.
9239
9240 Can also be used as a |method|: >
9241 GetRow()->screenstring(col)
9242<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009243 Return type: |String|
9244
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009245 *search()*
9246search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
9247 Search for regexp pattern {pattern}. The search starts at the
9248 cursor position (you can use |cursor()| to set it).
9249
9250 When a match has been found its line number is returned.
9251 If there is no match a 0 is returned and the cursor doesn't
9252 move. No error message is given.
Christian Brabandt9a660d22024-03-12 22:03:09 +01009253 To get the matched string, use |matchbufline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009254
9255 {flags} is a String, which can contain these character flags:
9256 'b' search Backward instead of forward
9257 'c' accept a match at the Cursor position
9258 'e' move to the End of the match
9259 'n' do Not move the cursor
9260 'p' return number of matching sub-Pattern (see below)
9261 's' Set the ' mark at the previous location of the cursor
9262 'w' Wrap around the end of the file
9263 'W' don't Wrap around the end of the file
Doug Kearns8a27d972025-01-05 15:56:57 +01009264 'z' start searching at the cursor column instead of Zero
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009265 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
9266
9267 If the 's' flag is supplied, the ' mark is set, only if the
9268 cursor is moved. The 's' flag cannot be combined with the 'n'
9269 flag.
9270
9271 'ignorecase', 'smartcase' and 'magic' are used.
9272
9273 When the 'z' flag is not given, forward searching always
9274 starts in column zero and then matches before the cursor are
9275 skipped. When the 'c' flag is present in 'cpo' the next
9276 search starts after the match. Without the 'c' flag the next
Bram Moolenaarfd999452022-08-24 18:30:14 +01009277 search starts one column after the start of the match. This
9278 matters for overlapping matches. See |cpo-c|. You can also
9279 insert "\ze" to change where the match ends, see |/\ze|.
9280
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009281 When searching backwards and the 'z' flag is given then the
9282 search starts in column zero, thus no match in the current
9283 line will be found (unless wrapping around the end of the
9284 file).
9285
9286 When the {stopline} argument is given then the search stops
9287 after searching this line. This is useful to restrict the
9288 search to a range of lines. Examples: >
9289 let match = search('(', 'b', line("w0"))
9290 let end = search('END', '', line("w$"))
9291< When {stopline} is used and it is not zero this also implies
9292 that the search does not wrap around the end of the file.
9293 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01009294 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009295 When the {timeout} argument is given the search stops when
9296 more than this many milliseconds have passed. Thus when
9297 {timeout} is 500 the search stops after half a second.
9298 The value must not be negative. A zero value is like not
9299 giving the argument.
Christian Brabandtd657d3d2024-09-10 21:55:49 +02009300
9301 Note: the timeout is only considered when searching, not
9302 while evaluating the {skip} expression.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009303 {only available when compiled with the |+reltime| feature}
9304
9305 If the {skip} expression is given it is evaluated with the
9306 cursor positioned on the start of a match. If it evaluates to
9307 non-zero this match is skipped. This can be used, for
9308 example, to skip a match in a comment or a string.
9309 {skip} can be a string, which is evaluated as an expression, a
9310 function reference or a lambda.
9311 When {skip} is omitted or empty, every match is accepted.
9312 When evaluating {skip} causes an error the search is aborted
9313 and -1 returned.
9314 *search()-sub-match*
9315 With the 'p' flag the returned value is one more than the
9316 first sub-match in \(\). One if none of them matched but the
9317 whole pattern did match.
9318 To get the column number too use |searchpos()|.
9319
9320 The cursor will be positioned at the match, unless the 'n'
9321 flag is used.
9322
9323 Example (goes over all files in the argument list): >
9324 :let n = 1
9325 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009326 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009327 : " start at the last char in the file and wrap for the
9328 : " first search to find match at start of file
9329 : normal G$
9330 : let flags = "w"
9331 : while search("foo", flags) > 0
9332 : s/foo/bar/g
9333 : let flags = "W"
9334 : endwhile
9335 : update " write the file if modified
9336 : let n = n + 1
9337 :endwhile
9338<
9339 Example for using some flags: >
9340 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
9341< This will search for the keywords "if", "else", and "endif"
9342 under or after the cursor. Because of the 'p' flag, it
9343 returns 1, 2, or 3 depending on which keyword is found, or 0
9344 if the search fails. With the cursor on the first word of the
9345 line:
9346 if (foo == 0) | let foo = foo + 1 | endif ~
9347 the function returns 1. Without the 'c' flag, the function
9348 finds the "endif" and returns 3. The same thing happens
9349 without the 'e' flag if the cursor is on the "f" of "if".
9350 The 'n' flag tells the function not to move the cursor.
9351
9352 Can also be used as a |method|: >
9353 GetPattern()->search()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009354<
9355 Return type: |Number|
9356
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009357
9358searchcount([{options}]) *searchcount()*
9359 Get or update the last search count, like what is displayed
9360 without the "S" flag in 'shortmess'. This works even if
9361 'shortmess' does contain the "S" flag.
9362
9363 This returns a |Dictionary|. The dictionary is empty if the
9364 previous pattern was not set and "pattern" was not specified.
9365
9366 key type meaning ~
9367 current |Number| current position of match;
9368 0 if the cursor position is
9369 before the first match
9370 exact_match |Boolean| 1 if "current" is matched on
9371 "pos", otherwise 0
9372 total |Number| total count of matches found
9373 incomplete |Number| 0: search was fully completed
9374 1: recomputing was timed out
9375 2: max count exceeded
9376
9377 For {options} see further down.
9378
9379 To get the last search count when |n| or |N| was pressed, call
9380 this function with `recompute: 0` . This sometimes returns
9381 wrong information because |n| and |N|'s maximum count is 99.
9382 If it exceeded 99 the result must be max count + 1 (100). If
9383 you want to get correct information, specify `recompute: 1`: >
9384
9385 " result == maxcount + 1 (100) when many matches
9386 let result = searchcount(#{recompute: 0})
9387
9388 " Below returns correct result (recompute defaults
9389 " to 1)
9390 let result = searchcount()
9391<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01009392 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009393 function! LastSearchCount() abort
9394 let result = searchcount(#{recompute: 0})
9395 if empty(result)
9396 return ''
9397 endif
9398 if result.incomplete ==# 1 " timed out
9399 return printf(' /%s [?/??]', @/)
9400 elseif result.incomplete ==# 2 " max count exceeded
9401 if result.total > result.maxcount &&
9402 \ result.current > result.maxcount
9403 return printf(' /%s [>%d/>%d]', @/,
9404 \ result.current, result.total)
9405 elseif result.total > result.maxcount
9406 return printf(' /%s [%d/>%d]', @/,
9407 \ result.current, result.total)
9408 endif
9409 endif
9410 return printf(' /%s [%d/%d]', @/,
9411 \ result.current, result.total)
9412 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009413 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009414
9415 " Or if you want to show the count only when
9416 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009417 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009418 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
9419<
9420 You can also update the search count, which can be useful in a
9421 |CursorMoved| or |CursorMovedI| autocommand: >
9422
9423 autocmd CursorMoved,CursorMovedI *
9424 \ let s:searchcount_timer = timer_start(
9425 \ 200, function('s:update_searchcount'))
9426 function! s:update_searchcount(timer) abort
9427 if a:timer ==# s:searchcount_timer
9428 call searchcount(#{
9429 \ recompute: 1, maxcount: 0, timeout: 100})
9430 redrawstatus
9431 endif
9432 endfunction
9433<
9434 This can also be used to count matched texts with specified
9435 pattern in the current buffer using "pattern": >
9436
9437 " Count '\<foo\>' in this buffer
9438 " (Note that it also updates search count)
9439 let result = searchcount(#{pattern: '\<foo\>'})
9440
9441 " To restore old search count by old pattern,
9442 " search again
9443 call searchcount()
9444<
9445 {options} must be a |Dictionary|. It can contain:
9446 key type meaning ~
9447 recompute |Boolean| if |TRUE|, recompute the count
9448 like |n| or |N| was executed.
9449 otherwise returns the last
9450 computed result (when |n| or
9451 |N| was used when "S" is not
9452 in 'shortmess', or this
9453 function was called).
9454 (default: |TRUE|)
9455 pattern |String| recompute if this was given
9456 and different with |@/|.
9457 this works as same as the
9458 below command is executed
9459 before calling this function >
9460 let @/ = pattern
9461< (default: |@/|)
9462 timeout |Number| 0 or negative number is no
9463 timeout. timeout milliseconds
9464 for recomputing the result
9465 (default: 0)
9466 maxcount |Number| 0 or negative number is no
9467 limit. max count of matched
9468 text while recomputing the
9469 result. if search exceeded
9470 total count, "total" value
9471 becomes `maxcount + 1`
9472 (default: 99)
9473 pos |List| `[lnum, col, off]` value
9474 when recomputing the result.
9475 this changes "current" result
9476 value. see |cursor()|,
9477 |getpos()|
9478 (default: cursor's position)
9479
9480 Can also be used as a |method|: >
9481 GetSearchOpts()->searchcount()
9482<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009483 Return type: dict<number>
9484
9485
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009486searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
9487 Search for the declaration of {name}.
9488
9489 With a non-zero {global} argument it works like |gD|, find
9490 first match in the file. Otherwise it works like |gd|, find
9491 first match in the function.
9492
9493 With a non-zero {thisblock} argument matches in a {} block
9494 that ends before the cursor position are ignored. Avoids
9495 finding variable declarations only valid in another scope.
9496
9497 Moves the cursor to the found match.
9498 Returns zero for success, non-zero for failure.
9499 Example: >
9500 if searchdecl('myvar') == 0
9501 echo getline('.')
9502 endif
9503<
9504 Can also be used as a |method|: >
9505 GetName()->searchdecl()
9506<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009507 Return type: |Number|
9508
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009509 *searchpair()*
9510searchpair({start}, {middle}, {end} [, {flags} [, {skip}
9511 [, {stopline} [, {timeout}]]]])
9512 Search for the match of a nested start-end pair. This can be
9513 used to find the "endif" that matches an "if", while other
9514 if/endif pairs in between are ignored.
9515 The search starts at the cursor. The default is to search
9516 forward, include 'b' in {flags} to search backward.
9517 If a match is found, the cursor is positioned at it and the
9518 line number is returned. If no match is found 0 or -1 is
9519 returned and the cursor doesn't move. No error message is
9520 given.
9521
9522 {start}, {middle} and {end} are patterns, see |pattern|. They
9523 must not contain \( \) pairs. Use of \%( \) is allowed. When
9524 {middle} is not empty, it is found when searching from either
9525 direction, but only when not in a nested start-end pair. A
9526 typical use is: >
9527 searchpair('\<if\>', '\<else\>', '\<endif\>')
9528< By leaving {middle} empty the "else" is skipped.
9529
9530 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
9531 |search()|. Additionally:
9532 'r' Repeat until no more matches found; will find the
9533 outer pair. Implies the 'W' flag.
9534 'm' Return number of matches instead of line number with
9535 the match; will be > 1 when 'r' is used.
9536 Note: it's nearly always a good idea to use the 'W' flag, to
9537 avoid wrapping around the end of the file.
9538
9539 When a match for {start}, {middle} or {end} is found, the
9540 {skip} expression is evaluated with the cursor positioned on
9541 the start of the match. It should return non-zero if this
9542 match is to be skipped. E.g., because it is inside a comment
9543 or a string.
9544 When {skip} is omitted or empty, every match is accepted.
9545 When evaluating {skip} causes an error the search is aborted
9546 and -1 returned.
9547 {skip} can be a string, a lambda, a funcref or a partial.
9548 Anything else makes the function fail.
9549 In a `:def` function when the {skip} argument is a string
9550 constant it is compiled into instructions.
9551
9552 For {stopline} and {timeout} see |search()|.
9553
9554 The value of 'ignorecase' is used. 'magic' is ignored, the
9555 patterns are used like it's on.
9556
9557 The search starts exactly at the cursor. A match with
9558 {start}, {middle} or {end} at the next character, in the
9559 direction of searching, is the first one found. Example: >
9560 if 1
9561 if 2
9562 endif 2
9563 endif 1
9564< When starting at the "if 2", with the cursor on the "i", and
9565 searching forwards, the "endif 2" is found. When starting on
9566 the character just before the "if 2", the "endif 1" will be
9567 found. That's because the "if 2" will be found first, and
9568 then this is considered to be a nested if/endif from "if 2" to
9569 "endif 2".
9570 When searching backwards and {end} is more than one character,
9571 it may be useful to put "\zs" at the end of the pattern, so
9572 that when the cursor is inside a match with the end it finds
9573 the matching start.
9574
9575 Example, to find the "endif" command in a Vim script: >
9576
9577 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
9578 \ 'getline(".") =~ "^\\s*\""')
9579
9580< The cursor must be at or after the "if" for which a match is
9581 to be found. Note that single-quote strings are used to avoid
9582 having to double the backslashes. The skip expression only
9583 catches comments at the start of a line, not after a command.
9584 Also, a word "en" or "if" halfway a line is considered a
9585 match.
9586 Another example, to search for the matching "{" of a "}": >
9587
9588 :echo searchpair('{', '', '}', 'bW')
9589
9590< This works when the cursor is at or before the "}" for which a
9591 match is to be found. To reject matches that syntax
9592 highlighting recognized as strings: >
9593
9594 :echo searchpair('{', '', '}', 'bW',
9595 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
9596<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009597 Return type: |Number|
9598
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009599 *searchpairpos()*
9600searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
9601 [, {stopline} [, {timeout}]]]])
9602 Same as |searchpair()|, but returns a |List| with the line and
9603 column position of the match. The first element of the |List|
9604 is the line number and the second element is the byte index of
9605 the column position of the match. If no match is found,
9606 returns [0, 0]. >
9607
9608 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
9609<
9610 See |match-parens| for a bigger and more useful example.
9611
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009612 Return type: list<number>
9613
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009614 *searchpos()*
9615searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
9616 Same as |search()|, but returns a |List| with the line and
9617 column position of the match. The first element of the |List|
9618 is the line number and the second element is the byte index of
9619 the column position of the match. If no match is found,
9620 returns [0, 0].
9621 Example: >
9622 :let [lnum, col] = searchpos('mypattern', 'n')
9623
9624< When the 'p' flag is given then there is an extra item with
9625 the sub-pattern match number |search()-sub-match|. Example: >
9626 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
9627< In this example "submatch" is 2 when a lowercase letter is
9628 found |/\l|, 3 when an uppercase letter is found |/\u|.
9629
9630 Can also be used as a |method|: >
9631 GetPattern()->searchpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009632<
9633 Return type: list<number>
9634
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009635
9636server2client({clientid}, {string}) *server2client()*
9637 Send a reply string to {clientid}. The most recent {clientid}
9638 that sent a string can be retrieved with expand("<client>").
9639 {only available when compiled with the |+clientserver| feature}
9640 Returns zero for success, -1 for failure.
9641 Note:
9642 This id has to be stored before the next command can be
9643 received. I.e. before returning from the received command and
9644 before calling any commands that waits for input.
9645 See also |clientserver|.
9646 Example: >
9647 :echo server2client(expand("<client>"), "HELLO")
9648
9649< Can also be used as a |method|: >
9650 GetClientId()->server2client(string)
9651<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009652 Return type: |Number|
9653
9654
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009655serverlist() *serverlist()*
9656 Return a list of available server names, one per line.
9657 When there are no servers or the information is not available
9658 an empty string is returned. See also |clientserver|.
9659 {only available when compiled with the |+clientserver| feature}
9660 Example: >
9661 :echo serverlist()
9662<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009663 Return type: |String|
9664
9665
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009666setbufline({buf}, {lnum}, {text}) *setbufline()*
9667 Set line {lnum} to {text} in buffer {buf}. This works like
9668 |setline()| for the specified buffer.
9669
9670 This function works only for loaded buffers. First call
9671 |bufload()| if needed.
9672
9673 To insert lines use |appendbufline()|.
9674 Any text properties in {lnum} are cleared.
9675
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00009676 {text} can be a string to set one line, or a List of strings
9677 to set multiple lines. If the List extends below the last
9678 line then those lines are added. If the List is empty then
9679 nothing is changed and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009680
9681 For the use of {buf}, see |bufname()| above.
9682
9683 {lnum} is used like with |setline()|.
9684 Use "$" to refer to the last line in buffer {buf}.
9685 When {lnum} is just below the last line the {text} will be
9686 added below the last line.
9687
9688 When {buf} is not a valid buffer, the buffer is not loaded or
9689 {lnum} is not valid then 1 is returned. In |Vim9| script an
9690 error is given.
9691 On success 0 is returned.
9692
9693 Can also be used as a |method|, the base is passed as the
9694 third argument: >
9695 GetText()->setbufline(buf, lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009696<
9697 Return type: |Number|
9698
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009699
9700setbufvar({buf}, {varname}, {val}) *setbufvar()*
9701 Set option or local variable {varname} in buffer {buf} to
9702 {val}.
9703 This also works for a global or local window option, but it
9704 doesn't work for a global or local window variable.
9705 For a local window option the global value is unchanged.
9706 For the use of {buf}, see |bufname()| above.
9707 The {varname} argument is a string.
9708 Note that the variable name without "b:" must be used.
9709 Examples: >
9710 :call setbufvar(1, "&mod", 1)
9711 :call setbufvar("todo", "myvar", "foobar")
9712< This function is not available in the |sandbox|.
9713
9714 Can also be used as a |method|, the base is passed as the
9715 third argument: >
9716 GetValue()->setbufvar(buf, varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009717<
9718 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009719
9720
9721setcellwidths({list}) *setcellwidths()*
9722 Specify overrides for cell widths of character ranges. This
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009723 tells Vim how wide characters are when displayed in the
9724 terminal, counted in screen cells. The values override
9725 'ambiwidth'. Example: >
9726 call setcellwidths([
Bram Moolenaar938ae282023-02-20 20:44:55 +00009727 \ [0x111, 0x111, 1],
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009728 \ [0x2194, 0x2199, 2],
9729 \ ])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009730
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009731< The {list} argument is a List of Lists with each three
9732 numbers: [{low}, {high}, {width}]. *E1109* *E1110*
9733 {low} and {high} can be the same, in which case this refers to
9734 one character. Otherwise it is the range of characters from
9735 {low} to {high} (inclusive). *E1111* *E1114*
K.Takata71933232023-01-20 16:00:55 +00009736 Only characters with value 0x80 and higher can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009737
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009738 {width} must be either 1 or 2, indicating the character width
9739 in screen cells. *E1112*
9740 An error is given if the argument is invalid, also when a
Bram Moolenaar938ae282023-02-20 20:44:55 +00009741 range overlaps with another. *E1113*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009742
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009743 If the new value causes 'fillchars' or 'listchars' to become
9744 invalid it is rejected and an error is given.
9745
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009746 To clear the overrides pass an empty {list}: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009747 setcellwidths([]);
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009748
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009749< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009750 the effect for known emoji characters. Move the cursor
9751 through the text to check if the cell widths of your terminal
9752 match with what Vim knows about each emoji. If it doesn't
9753 look right you need to adjust the {list} argument.
9754
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009755 Return type: |Number|
9756
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009757
9758setcharpos({expr}, {list}) *setcharpos()*
9759 Same as |setpos()| but uses the specified column number as the
9760 character index instead of the byte index in the line.
9761
9762 Example:
9763 With the text "여보세요" in line 8: >
9764 call setcharpos('.', [0, 8, 4, 0])
9765< positions the cursor on the fourth character '요'. >
9766 call setpos('.', [0, 8, 4, 0])
9767< positions the cursor on the second character '보'.
9768
9769 Can also be used as a |method|: >
9770 GetPosition()->setcharpos('.')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009771<
9772 Return type: |Number|
9773
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009774
9775setcharsearch({dict}) *setcharsearch()*
9776 Set the current character search information to {dict},
9777 which contains one or more of the following entries:
9778
9779 char character which will be used for a subsequent
9780 |,| or |;| command; an empty string clears the
9781 character search
9782 forward direction of character search; 1 for forward,
9783 0 for backward
9784 until type of character search; 1 for a |t| or |T|
9785 character search, 0 for an |f| or |F|
9786 character search
9787
9788 This can be useful to save/restore a user's character search
9789 from a script: >
9790 :let prevsearch = getcharsearch()
9791 :" Perform a command which clobbers user's search
9792 :call setcharsearch(prevsearch)
9793< Also see |getcharsearch()|.
9794
9795 Can also be used as a |method|: >
9796 SavedSearch()->setcharsearch()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009797<
9798 Return type: dict<any>
9799
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009800
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009801setcmdline({str} [, {pos}]) *setcmdline()*
9802 Set the command line to {str} and set the cursor position to
9803 {pos}.
9804 If {pos} is omitted, the cursor is positioned after the text.
9805 Returns 0 when successful, 1 when not editing the command
9806 line.
9807
9808 Can also be used as a |method|: >
9809 GetText()->setcmdline()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009810<
9811 Return type: |Number|
9812
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009813
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009814setcmdpos({pos}) *setcmdpos()*
9815 Set the cursor position in the command line to byte position
9816 {pos}. The first position is 1.
9817 Use |getcmdpos()| to obtain the current position.
9818 Only works while editing the command line, thus you must use
9819 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
9820 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
9821 set after the command line is set to the expression. For
9822 |c_CTRL-R_=| it is set after evaluating the expression but
9823 before inserting the resulting text.
9824 When the number is too big the cursor is put at the end of the
9825 line. A number smaller than one has undefined results.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009826 Returns 0 when successful, 1 when not editing the command
9827 line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009828
9829 Can also be used as a |method|: >
9830 GetPos()->setcmdpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009831<
9832 Return type: |Number|
9833
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009834
9835setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
9836setcursorcharpos({list})
9837 Same as |cursor()| but uses the specified column number as the
9838 character index instead of the byte index in the line.
9839
9840 Example:
9841 With the text "여보세요" in line 4: >
9842 call setcursorcharpos(4, 3)
9843< positions the cursor on the third character '세'. >
9844 call cursor(4, 3)
9845< positions the cursor on the first character '여'.
9846
9847 Can also be used as a |method|: >
9848 GetCursorPos()->setcursorcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009849<
Christian Brabandt17ad8522025-05-09 00:03:20 +02009850 Returns 0 when the position could be set, -1 otherwise.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009851 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009852
9853
9854setenv({name}, {val}) *setenv()*
9855 Set environment variable {name} to {val}. Example: >
9856 call setenv('HOME', '/home/myhome')
9857
9858< When {val} is |v:null| the environment variable is deleted.
9859 See also |expr-env|.
9860
9861 Can also be used as a |method|, the base is passed as the
9862 second argument: >
9863 GetPath()->setenv('PATH')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009864<
9865 Return type: |Number|
9866
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009867
9868setfperm({fname}, {mode}) *setfperm()* *chmod*
9869 Set the file permissions for {fname} to {mode}.
9870 {mode} must be a string with 9 characters. It is of the form
9871 "rwxrwxrwx", where each group of "rwx" flags represent, in
9872 turn, the permissions of the owner of the file, the group the
9873 file belongs to, and other users. A '-' character means the
9874 permission is off, any other character means on. Multi-byte
9875 characters are not supported.
9876
9877 For example "rw-r-----" means read-write for the user,
9878 readable by the group, not accessible by others. "xx-x-----"
9879 would do the same thing.
9880
9881 Returns non-zero for success, zero for failure.
9882
9883 Can also be used as a |method|: >
9884 GetFilename()->setfperm(mode)
9885<
9886 To read permissions see |getfperm()|.
9887
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009888 Return type: |Number|
9889
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009890
9891setline({lnum}, {text}) *setline()*
9892 Set line {lnum} of the current buffer to {text}. To insert
9893 lines use |append()|. To set lines in another buffer use
Christian Brabandt946f61c2024-06-17 13:17:58 +02009894 |setbufline()|.
h-east52e7cc22024-07-28 17:03:29 +02009895 Any text properties in {lnum} are cleared. See
9896 |text-prop-cleared|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009897
9898 {lnum} is used like with |getline()|.
9899 When {lnum} is just below the last line the {text} will be
9900 added below the last line.
9901 {text} can be any type or a List of any type, each item is
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00009902 converted to a String. When {text} is an empty List then
9903 nothing is changed and FALSE is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009904
9905 If this succeeds, FALSE is returned. If this fails (most likely
9906 because {lnum} is invalid) TRUE is returned.
9907 In |Vim9| script an error is given if {lnum} is invalid.
9908
9909 Example: >
9910 :call setline(5, strftime("%c"))
9911
9912< When {text} is a |List| then line {lnum} and following lines
9913 will be set to the items in the list. Example: >
9914 :call setline(5, ['aaa', 'bbb', 'ccc'])
9915< This is equivalent to: >
9916 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
9917 : call setline(n, l)
9918 :endfor
9919
9920< Note: The '[ and '] marks are not set.
9921
9922 Can also be used as a |method|, the base is passed as the
9923 second argument: >
9924 GetText()->setline(lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009925<
9926 Return type: |Number|
9927
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009928
9929setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
9930 Create or replace or add to the location list for window {nr}.
9931 {nr} can be the window number or the |window-ID|.
9932 When {nr} is zero the current window is used.
9933
9934 For a location list window, the displayed location list is
9935 modified. For an invalid window number {nr}, -1 is returned.
9936 Otherwise, same as |setqflist()|.
9937 Also see |location-list|.
9938
9939 For {action} see |setqflist-action|.
9940
9941 If the optional {what} dictionary argument is supplied, then
9942 only the items listed in {what} are set. Refer to |setqflist()|
9943 for the list of supported keys in {what}.
9944
9945 Can also be used as a |method|, the base is passed as the
9946 second argument: >
9947 GetLoclist()->setloclist(winnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009948<
9949 Return type: |Number|
9950
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009951
9952setmatches({list} [, {win}]) *setmatches()*
9953 Restores a list of matches saved by |getmatches()| for the
9954 current window. Returns 0 if successful, otherwise -1. All
9955 current matches are cleared before the list is restored. See
9956 example for |getmatches()|.
9957 If {win} is specified, use the window with this number or
9958 window ID instead of the current window.
9959
9960 Can also be used as a |method|: >
9961 GetMatches()->setmatches()
9962<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009963 Return type: |Number|
9964
9965
9966setpos({expr}, {list}) *setpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009967 Set the position for String {expr}. Possible values:
9968 . the cursor
9969 'x mark x
9970
9971 {list} must be a |List| with four or five numbers:
9972 [bufnum, lnum, col, off]
9973 [bufnum, lnum, col, off, curswant]
9974
9975 "bufnum" is the buffer number. Zero can be used for the
9976 current buffer. When setting an uppercase mark "bufnum" is
9977 used for the mark position. For other marks it specifies the
9978 buffer to set the mark in. You can use the |bufnr()| function
9979 to turn a file name into a buffer number.
9980 For setting the cursor and the ' mark "bufnum" is ignored,
9981 since these are associated with a window, not a buffer.
9982 Does not change the jumplist.
9983
9984 "lnum" and "col" are the position in the buffer. The first
9985 column is 1. Use a zero "lnum" to delete a mark. If "col" is
9986 smaller than 1 then 1 is used. To use the character count
9987 instead of the byte count, use |setcharpos()|.
9988
9989 The "off" number is only used when 'virtualedit' is set. Then
9990 it is the offset in screen columns from the start of the
9991 character. E.g., a position within a <Tab> or after the last
9992 character.
9993
9994 The "curswant" number is only used when setting the cursor
9995 position. It sets the preferred column for when moving the
9996 cursor vertically. When the "curswant" number is missing the
9997 preferred column is not set. When it is present and setting a
9998 mark position it is not used.
9999
10000 Note that for '< and '> changing the line number may result in
10001 the marks to be effectively be swapped, so that '< is always
10002 before '>.
10003
10004 Returns 0 when the position could be set, -1 otherwise.
10005 An error message is given if {expr} is invalid.
10006
10007 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
10008
10009 This does not restore the preferred column for moving
10010 vertically; if you set the cursor position with this, |j| and
10011 |k| motions will jump to previous columns! Use |cursor()| to
10012 also set the preferred column. Also see the "curswant" key in
10013 |winrestview()|.
10014
10015 Can also be used as a |method|: >
10016 GetPosition()->setpos('.')
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010017<
10018 Return type: |Number|
10019
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010020
10021setqflist({list} [, {action} [, {what}]]) *setqflist()*
10022 Create or replace or add to the quickfix list.
10023
10024 If the optional {what} dictionary argument is supplied, then
10025 only the items listed in {what} are set. The first {list}
10026 argument is ignored. See below for the supported items in
10027 {what}.
10028 *setqflist-what*
10029 When {what} is not present, the items in {list} are used. Each
10030 item must be a dictionary. Non-dictionary items in {list} are
10031 ignored. Each dictionary item can contain the following
10032 entries:
10033
10034 bufnr buffer number; must be the number of a valid
10035 buffer
10036 filename name of a file; only used when "bufnr" is not
10037 present or it is invalid.
10038 module name of a module; if given it will be used in
10039 quickfix error window instead of the filename.
10040 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +000010041 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010042 pattern search pattern used to locate the error
10043 col column number
10044 vcol when non-zero: "col" is visual column
10045 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +000010046 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010047 nr error number
10048 text description of the error
10049 type single-character error type, 'E', 'W', etc.
10050 valid recognized error message
Tom Praschanca6ac992023-08-11 23:26:12 +020010051 user_data custom data associated with the item, can be
10052 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010053
10054 The "col", "vcol", "nr", "type" and "text" entries are
10055 optional. Either "lnum" or "pattern" entry can be used to
10056 locate a matching error line.
10057 If the "filename" and "bufnr" entries are not present or
10058 neither the "lnum" or "pattern" entries are present, then the
10059 item will not be handled as an error line.
10060 If both "pattern" and "lnum" are present then "pattern" will
10061 be used.
10062 If the "valid" entry is not supplied, then the valid flag is
10063 set when "bufnr" is a valid buffer or "filename" exists.
10064 If you supply an empty {list}, the quickfix list will be
10065 cleared.
10066 Note that the list is not exactly the same as what
10067 |getqflist()| returns.
10068
10069 {action} values: *setqflist-action* *E927*
10070 'a' The items from {list} are added to the existing
10071 quickfix list. If there is no existing list, then a
10072 new list is created.
10073
10074 'r' The items from the current quickfix list are replaced
10075 with the items from {list}. This can also be used to
10076 clear the list: >
10077 :call setqflist([], 'r')
10078<
Jeremy Fleischman27fbf6e2024-10-14 20:46:27 +020010079 'u' Like 'r', but tries to preserve the current selection
10080 in the quickfix list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010081 'f' All the quickfix lists in the quickfix stack are
10082 freed.
10083
10084 If {action} is not present or is set to ' ', then a new list
10085 is created. The new quickfix list is added after the current
10086 quickfix list in the stack and all the following lists are
10087 freed. To add a new quickfix list at the end of the stack,
10088 set "nr" in {what} to "$".
10089
10090 The following items can be specified in dictionary {what}:
10091 context quickfix list context. See |quickfix-context|
10092 efm errorformat to use when parsing text from
10093 "lines". If this is not present, then the
10094 'errorformat' option value is used.
10095 See |quickfix-parse|
10096 id quickfix list identifier |quickfix-ID|
10097 idx index of the current entry in the quickfix
10098 list specified by 'id' or 'nr'. If set to '$',
10099 then the last entry in the list is set as the
10100 current entry. See |quickfix-index|
10101 items list of quickfix entries. Same as the {list}
10102 argument.
10103 lines use 'errorformat' to parse a list of lines and
10104 add the resulting entries to the quickfix list
10105 {nr} or {id}. Only a |List| value is supported.
10106 See |quickfix-parse|
10107 nr list number in the quickfix stack; zero
10108 means the current quickfix list and "$" means
10109 the last quickfix list.
10110 quickfixtextfunc
10111 function to get the text to display in the
10112 quickfix window. The value can be the name of
10113 a function or a funcref or a lambda. Refer to
10114 |quickfix-window-function| for an explanation
10115 of how to write the function and an example.
10116 title quickfix list title text. See |quickfix-title|
10117 Unsupported keys in {what} are ignored.
10118 If the "nr" item is not present, then the current quickfix list
10119 is modified. When creating a new quickfix list, "nr" can be
10120 set to a value one greater than the quickfix stack size.
10121 When modifying a quickfix list, to guarantee that the correct
10122 list is modified, "id" should be used instead of "nr" to
10123 specify the list.
10124
10125 Examples (See also |setqflist-examples|): >
10126 :call setqflist([], 'r', {'title': 'My search'})
10127 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
10128 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
10129<
10130 Returns zero for success, -1 for failure.
10131
10132 This function can be used to create a quickfix list
10133 independent of the 'errorformat' setting. Use a command like
10134 `:cc 1` to jump to the first position.
10135
10136 Can also be used as a |method|, the base is passed as the
10137 second argument: >
10138 GetErrorlist()->setqflist()
10139<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010140 Return type: |Number|
10141
10142
10143setreg({regname}, {value} [, {options}]) *setreg()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010144 Set the register {regname} to {value}.
10145 If {regname} is "" or "@", the unnamed register '"' is used.
10146 The {regname} argument is a string. In |Vim9-script|
10147 {regname} must be one character.
10148
10149 {value} may be any value returned by |getreg()| or
10150 |getreginfo()|, including a |List| or |Dict|.
10151 If {options} contains "a" or {regname} is upper case,
10152 then the value is appended.
10153
10154 {options} can also contain a register type specification:
10155 "c" or "v" |characterwise| mode
10156 "l" or "V" |linewise| mode
10157 "b" or "<CTRL-V>" |blockwise-visual| mode
10158 If a number immediately follows "b" or "<CTRL-V>" then this is
10159 used as the width of the selection - if it is not specified
10160 then the width of the block is set to the number of characters
10161 in the longest line (counting a <Tab> as 1 character).
10162
10163 If {options} contains no register settings, then the default
10164 is to use character mode unless {value} ends in a <NL> for
10165 string {value} and linewise mode for list {value}. Blockwise
10166 mode is never selected automatically.
10167 Returns zero for success, non-zero for failure.
10168
10169 *E883*
10170 Note: you may not use |List| containing more than one item to
10171 set search and expression registers. Lists containing no
10172 items act like empty strings.
10173
10174 Examples: >
10175 :call setreg(v:register, @*)
10176 :call setreg('*', @%, 'ac')
10177 :call setreg('a', "1\n2\n3", 'b5')
10178 :call setreg('"', { 'points_to': 'a'})
10179
10180< This example shows using the functions to save and restore a
10181 register: >
10182 :let var_a = getreginfo()
10183 :call setreg('a', var_a)
10184< or: >
10185 :let var_a = getreg('a', 1, 1)
10186 :let var_amode = getregtype('a')
10187 ....
10188 :call setreg('a', var_a, var_amode)
10189< Note: you may not reliably restore register value
10190 without using the third argument to |getreg()| as without it
10191 newlines are represented as newlines AND Nul bytes are
10192 represented as newlines as well, see |NL-used-for-Nul|.
10193
10194 You can also change the type of a register by appending
10195 nothing: >
10196 :call setreg('a', '', 'al')
10197
10198< Can also be used as a |method|, the base is passed as the
10199 second argument: >
10200 GetText()->setreg('a')
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010201<
10202 Return type: |Number|
10203
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010204
10205settabvar({tabnr}, {varname}, {val}) *settabvar()*
10206 Set tab-local variable {varname} to {val} in tab page {tabnr}.
10207 |t:var|
10208 The {varname} argument is a string.
10209 Note that autocommands are blocked, side effects may not be
10210 triggered, e.g. when setting 'filetype'.
10211 Note that the variable name without "t:" must be used.
10212 Tabs are numbered starting with one.
10213 This function is not available in the |sandbox|.
10214
10215 Can also be used as a |method|, the base is passed as the
10216 third argument: >
10217 GetValue()->settabvar(tab, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010218<
10219 Return type: |Number|
10220
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010221
10222settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
10223 Set option or local variable {varname} in window {winnr} to
10224 {val}.
10225 Tabs are numbered starting with one. For the current tabpage
10226 use |setwinvar()|.
10227 {winnr} can be the window number or the |window-ID|.
10228 When {winnr} is zero the current window is used.
10229 Note that autocommands are blocked, side effects may not be
10230 triggered, e.g. when setting 'filetype' or 'syntax'.
10231 This also works for a global or local buffer option, but it
10232 doesn't work for a global or local buffer variable.
10233 For a local buffer option the global value is unchanged.
10234 Note that the variable name without "w:" must be used.
10235 Examples: >
10236 :call settabwinvar(1, 1, "&list", 0)
10237 :call settabwinvar(3, 2, "myvar", "foobar")
10238< This function is not available in the |sandbox|.
10239
10240 Can also be used as a |method|, the base is passed as the
10241 fourth argument: >
10242 GetValue()->settabwinvar(tab, winnr, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010243<
10244 Return type: |Number|
10245
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010246
10247settagstack({nr}, {dict} [, {action}]) *settagstack()*
10248 Modify the tag stack of the window {nr} using {dict}.
10249 {nr} can be the window number or the |window-ID|.
10250
10251 For a list of supported items in {dict}, refer to
10252 |gettagstack()|. "curidx" takes effect before changing the tag
10253 stack.
10254 *E962*
10255 How the tag stack is modified depends on the {action}
10256 argument:
10257 - If {action} is not present or is set to 'r', then the tag
10258 stack is replaced.
10259 - If {action} is set to 'a', then new entries from {dict} are
10260 pushed (added) onto the tag stack.
10261 - If {action} is set to 't', then all the entries from the
10262 current entry in the tag stack or "curidx" in {dict} are
10263 removed and then new entries are pushed to the stack.
10264
10265 The current index is set to one after the length of the tag
10266 stack after the modification.
10267
10268 Returns zero for success, -1 for failure.
10269
10270 Examples (for more examples see |tagstack-examples|):
10271 Empty the tag stack of window 3: >
10272 call settagstack(3, {'items' : []})
10273
10274< Save and restore the tag stack: >
10275 let stack = gettagstack(1003)
10276 " do something else
10277 call settagstack(1003, stack)
10278 unlet stack
10279<
10280 Can also be used as a |method|, the base is passed as the
10281 second argument: >
10282 GetStack()->settagstack(winnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010283<
10284 Return type: |Number|
10285
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010286
10287setwinvar({winnr}, {varname}, {val}) *setwinvar()*
10288 Like |settabwinvar()| for the current tab page.
10289 Examples: >
10290 :call setwinvar(1, "&list", 0)
10291 :call setwinvar(2, "myvar", "foobar")
10292
10293< Can also be used as a |method|, the base is passed as the
10294 third argument: >
10295 GetValue()->setwinvar(winnr, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010296<
10297 Return type: |Number|
10298
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010299
10300sha256({string}) *sha256()*
10301 Returns a String with 64 hex characters, which is the SHA256
10302 checksum of {string}.
10303
10304 Can also be used as a |method|: >
10305 GetText()->sha256()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010306<
10307 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010308
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010309 {only available when compiled with the |+cryptv| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010310
10311shellescape({string} [, {special}]) *shellescape()*
10312 Escape {string} for use as a shell command argument.
10313 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +000010314 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010315 in single quotes and will double up all internal single
10316 quotes.
10317 On MS-Windows, when 'shellslash' is not set, it will enclose
10318 {string} in double quotes and double all double quotes within
10319 {string}.
10320 Otherwise it will enclose {string} in single quotes and
10321 replace all "'" with "'\''".
10322
Enno5faeb602024-05-15 21:54:19 +020010323 The {special} argument adds additional escaping of keywords
10324 used in Vim commands. When it is not omitted and a non-zero
K.Takatac0e038b2024-05-16 12:39:01 +090010325 number or a non-empty String (|non-zero-arg|), then special
10326 items such as "!", "%", "#" and "<cword>" (as listed in
10327 |expand()|) will be preceded by a backslash.
Enno5faeb602024-05-15 21:54:19 +020010328 This backslash will be removed again by the |:!| command.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010329
10330 The "!" character will be escaped (again with a |non-zero-arg|
10331 {special}) when 'shell' contains "csh" in the tail. That is
10332 because for csh and tcsh "!" is used for history replacement
10333 even when inside single quotes.
10334
10335 With a |non-zero-arg| {special} the <NL> character is also
10336 escaped. When 'shell' containing "csh" in the tail it's
10337 escaped a second time.
10338
10339 The "\" character will be escaped when 'shell' contains "fish"
10340 in the tail. That is because for fish "\" is used as an escape
10341 character inside single quotes.
10342
10343 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010344 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010345< This results in a directory listing for the file under the
10346 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010347 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010348< See also |::S|.
10349
10350 Can also be used as a |method|: >
10351 GetCommand()->shellescape()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010352<
10353 Return type: |String|
10354
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010355
10356shiftwidth([{col}]) *shiftwidth()*
10357 Returns the effective value of 'shiftwidth'. This is the
10358 'shiftwidth' value unless it is zero, in which case it is the
10359 'tabstop' value. This function was introduced with patch
10360 7.3.694 in 2012, everybody should have it by now (however it
10361 did not allow for the optional {col} argument until 8.1.542).
10362
10363 When there is one argument {col} this is used as column number
10364 for which to return the 'shiftwidth' value. This matters for the
10365 'vartabstop' feature. If the 'vartabstop' setting is enabled and
10366 no {col} argument is given, column 1 will be assumed.
10367
10368 Can also be used as a |method|: >
10369 GetColumn()->shiftwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010370<
10371 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010372
10373sign_ functions are documented here: |sign-functions-details|
10374
10375
10376simplify({filename}) *simplify()*
10377 Simplify the file name as much as possible without changing
10378 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
10379 Unix) are not resolved. If the first path component in
10380 {filename} designates the current directory, this will be
10381 valid for the result as well. A trailing path separator is
10382 not removed either. On Unix "//path" is unchanged, but
10383 "///path" is simplified to "/path" (this follows the Posix
10384 standard).
10385 Example: >
10386 simplify("./dir/.././/file/") == "./file/"
10387< Note: The combination "dir/.." is only removed if "dir" is
10388 a searchable directory or does not exist. On Unix, it is also
10389 removed when "dir" is a symbolic link within the same
10390 directory. In order to resolve all the involved symbolic
10391 links before simplifying the path name, use |resolve()|.
10392
10393 Can also be used as a |method|: >
10394 GetName()->simplify()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010395<
10396 Return type: |String|
10397
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010398
10399sin({expr}) *sin()*
10400 Return the sine of {expr}, measured in radians, as a |Float|.
10401 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010402 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010403 Examples: >
10404 :echo sin(100)
10405< -0.506366 >
10406 :echo sin(-4.01)
10407< 0.763301
10408
10409 Can also be used as a |method|: >
10410 Compute()->sin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010411<
10412 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010413
10414
10415sinh({expr}) *sinh()*
10416 Return the hyperbolic sine of {expr} as a |Float| in the range
10417 [-inf, inf].
10418 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010419 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010420 Examples: >
10421 :echo sinh(0.5)
10422< 0.521095 >
10423 :echo sinh(-0.9)
10424< -1.026517
10425
10426 Can also be used as a |method|: >
10427 Compute()->sinh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010428<
10429 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010430
10431
10432slice({expr}, {start} [, {end}]) *slice()*
10433 Similar to using a |slice| "expr[start : end]", but "end" is
10434 used exclusive. And for a string the indexes are used as
10435 character indexes instead of byte indexes, like in
zeertzjqad387692024-03-23 08:23:48 +010010436 |vim9script|. Also, composing characters are treated as a
10437 part of the preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010438 When {end} is omitted the slice continues to the last item.
10439 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010440 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010441
10442 Can also be used as a |method|: >
10443 GetList()->slice(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010444<
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +010010445 Return type: list<{type}> or tuple<{type}>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010446
10447
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010448sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010449 Sort the items in {list} in-place. Returns {list}.
10450
10451 If you want a list to remain unmodified make a copy first: >
10452 :let sortedlist = sort(copy(mylist))
10453
Bram Moolenaar2d8ed022022-05-21 13:08:16 +010010454< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010455 string representation of each item to sort on. Numbers sort
10456 after Strings, |Lists| after Numbers. For sorting text in the
10457 current buffer use |:sort|.
10458
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010459 When {how} is given and it is 'i' then case is ignored.
10460 In legacy script, for backwards compatibility, the value one
10461 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010462
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010463 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010464 locale is used for ordering. Implementation details: strcoll()
10465 is used to compare strings. See |:language| check or set the
10466 collation locale. |v:collate| can also be used to check the
10467 current locale. Sorting using the locale typically ignores
10468 case. Example: >
10469 " ö is sorted similarly to o with English locale.
10470 :language collate en_US.UTF8
10471 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10472< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
10473>
10474 " ö is sorted after z with Swedish locale.
10475 :language collate sv_SE.UTF8
10476 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10477< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
10478 This does not work properly on Mac.
10479
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010480 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010481 sorted numerical (Implementation detail: this uses the
Bram Moolenaarbe19d782023-03-09 22:06:49 +000010482 strtod() function to parse numbers. Strings, Lists, Dicts and
10483 Funcrefs will be considered as being 0). Note that this won't
10484 sort a list of strings with numbers!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010485
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010486 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010487 sorted numerical. This is like 'n' but a string containing
10488 digits will be used as the number they represent.
10489
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010490 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010491 sorted numerical. All values must be a Number or a Float.
10492
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010493 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010494 is called to compare items. The function is invoked with two
10495 items as argument and must return zero if they are equal, 1 or
10496 bigger if the first one sorts after the second one, -1 or
10497 smaller if the first one sorts before the second one.
10498
10499 {dict} is for functions with the "dict" attribute. It will be
10500 used to set the local variable "self". |Dictionary-function|
10501
10502 The sort is stable, items which compare equal (as number or as
10503 string) will keep their relative position. E.g., when sorting
10504 on numbers, text strings will sort next to each other, in the
10505 same order as they were originally.
10506
10507 Can also be used as a |method|: >
10508 mylist->sort()
10509
10510< Also see |uniq()|.
10511
10512 Example: >
10513 func MyCompare(i1, i2)
10514 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
10515 endfunc
10516 eval mylist->sort("MyCompare")
10517< A shorter compare version for this specific simple case, which
10518 ignores overflow: >
10519 func MyCompare(i1, i2)
10520 return a:i1 - a:i2
10521 endfunc
10522< For a simple expression you can use a lambda: >
10523 eval mylist->sort({i1, i2 -> i1 - i2})
10524<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010525 Return type: list<{type}>
10526
10527
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010528sound_clear() *sound_clear()*
10529 Stop playing all sounds.
10530
10531 On some Linux systems you may need the libcanberra-pulse
10532 package, otherwise sound may not stop.
10533
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010534 Return type: |Number|
10535
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010536 {only available when compiled with the |+sound| feature}
10537
10538 *sound_playevent()*
10539sound_playevent({name} [, {callback}])
10540 Play a sound identified by {name}. Which event names are
10541 supported depends on the system. Often the XDG sound names
10542 are used. On Ubuntu they may be found in
10543 /usr/share/sounds/freedesktop/stereo. Example: >
10544 call sound_playevent('bell')
10545< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
10546 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
10547 SystemStart, SystemWelcome, etc.
Yee Cheng Chin4314e4f2022-10-08 13:50:05 +010010548 On macOS, {name} refers to files located in
10549 /System/Library/Sounds (e.g. "Tink"). It will also work for
10550 custom installed sounds in folders like ~/Library/Sounds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010551
10552 When {callback} is specified it is invoked when the sound is
10553 finished. The first argument is the sound ID, the second
10554 argument is the status:
10555 0 sound was played to the end
10556 1 sound was interrupted
10557 2 error occurred after sound started
10558 Example: >
10559 func Callback(id, status)
10560 echomsg "sound " .. a:id .. " finished with " .. a:status
10561 endfunc
10562 call sound_playevent('bell', 'Callback')
10563
10564< MS-Windows: {callback} doesn't work for this function.
10565
10566 Returns the sound ID, which can be passed to `sound_stop()`.
10567 Returns zero if the sound could not be played.
10568
10569 Can also be used as a |method|: >
10570 GetSoundName()->sound_playevent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010571<
10572 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010573
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010574 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010575
10576 *sound_playfile()*
10577sound_playfile({path} [, {callback}])
10578 Like `sound_playevent()` but play sound file {path}. {path}
10579 must be a full path. On Ubuntu you may find files to play
10580 with this command: >
10581 :!find /usr/share/sounds -type f | grep -v index.theme
10582
10583< Can also be used as a |method|: >
10584 GetSoundPath()->sound_playfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010585<
10586 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010587
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010588 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010589
10590
10591sound_stop({id}) *sound_stop()*
10592 Stop playing sound {id}. {id} must be previously returned by
10593 `sound_playevent()` or `sound_playfile()`.
10594
10595 On some Linux systems you may need the libcanberra-pulse
10596 package, otherwise sound may not stop.
10597
10598 On MS-Windows, this does not work for event sound started by
10599 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
10600
10601 Can also be used as a |method|: >
10602 soundid->sound_stop()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010603<
10604 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010605
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010606 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010607
10608 *soundfold()*
10609soundfold({word})
10610 Return the sound-folded equivalent of {word}. Uses the first
10611 language in 'spelllang' for the current window that supports
10612 soundfolding. 'spell' must be set. When no sound folding is
10613 possible the {word} is returned unmodified.
10614 This can be used for making spelling suggestions. Note that
10615 the method can be quite slow.
10616
10617 Can also be used as a |method|: >
10618 GetWord()->soundfold()
10619<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010620 Return type: |String|
10621
10622
10623spellbadword([{sentence}]) *spellbadword()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010624 Without argument: The result is the badly spelled word under
10625 or after the cursor. The cursor is moved to the start of the
10626 bad word. When no bad word is found in the cursor line the
10627 result is an empty string and the cursor doesn't move.
10628
10629 With argument: The result is the first word in {sentence} that
10630 is badly spelled. If there are no spelling mistakes the
10631 result is an empty string.
10632
10633 The return value is a list with two items:
10634 - The badly spelled word or an empty string.
10635 - The type of the spelling error:
10636 "bad" spelling mistake
10637 "rare" rare word
10638 "local" word only valid in another region
10639 "caps" word should start with Capital
10640 Example: >
10641 echo spellbadword("the quik brown fox")
10642< ['quik', 'bad'] ~
10643
10644 The spelling information for the current window and the value
10645 of 'spelllang' are used.
10646
10647 Can also be used as a |method|: >
10648 GetText()->spellbadword()
10649<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010650 Return type: list<string>
10651
10652
10653spellsuggest({word} [, {max} [, {capital}]]) *spellsuggest()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010654 Return a |List| with spelling suggestions to replace {word}.
10655 When {max} is given up to this number of suggestions are
10656 returned. Otherwise up to 25 suggestions are returned.
10657
10658 When the {capital} argument is given and it's non-zero only
10659 suggestions with a leading capital will be given. Use this
10660 after a match with 'spellcapcheck'.
10661
10662 {word} can be a badly spelled word followed by other text.
10663 This allows for joining two words that were split. The
10664 suggestions also include the following text, thus you can
10665 replace a line.
10666
10667 {word} may also be a good word. Similar words will then be
10668 returned. {word} itself is not included in the suggestions,
10669 although it may appear capitalized.
10670
10671 The spelling information for the current window is used. The
10672 values of 'spelllang' and 'spellsuggest' are used.
10673
10674 Can also be used as a |method|: >
10675 GetWord()->spellsuggest()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010676<
10677 Return type: list<string> or list<any>
10678
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010679
10680split({string} [, {pattern} [, {keepempty}]]) *split()*
10681 Make a |List| out of {string}. When {pattern} is omitted or
Shane Harperc1b39842024-07-17 19:40:40 +020010682 empty each white space separated sequence of characters
10683 becomes an item.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010684 Otherwise the string is split where {pattern} matches,
10685 removing the matched characters. 'ignorecase' is not used
10686 here, add \c to ignore case. |/\c|
10687 When the first or last item is empty it is omitted, unless the
10688 {keepempty} argument is given and it's non-zero.
10689 Other empty items are kept when {pattern} matches at least one
10690 character or when {keepempty} is non-zero.
10691 Example: >
10692 :let words = split(getline('.'), '\W\+')
10693< To split a string in individual characters: >
10694 :for c in split(mystring, '\zs')
10695< If you want to keep the separator you can also use '\zs' at
10696 the end of the pattern: >
10697 :echo split('abc:def:ghi', ':\zs')
10698< ['abc:', 'def:', 'ghi'] ~
10699 Splitting a table where the first element can be empty: >
10700 :let items = split(line, ':', 1)
10701< The opposite function is |join()|.
10702
10703 Can also be used as a |method|: >
10704 GetString()->split()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010705<
10706 Return type: list<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010707
10708sqrt({expr}) *sqrt()*
10709 Return the non-negative square root of Float {expr} as a
10710 |Float|.
10711 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010712 is negative the result is NaN (Not a Number). Returns 0.0 if
10713 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010714 Examples: >
10715 :echo sqrt(100)
10716< 10.0 >
10717 :echo sqrt(-4.01)
10718< nan
10719 "nan" may be different, it depends on system libraries.
10720
10721 Can also be used as a |method|: >
10722 Compute()->sqrt()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010723<
10724 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010725
10726
10727srand([{expr}]) *srand()*
10728 Initialize seed used by |rand()|:
10729 - If {expr} is not given, seed values are initialized by
10730 reading from /dev/urandom, if possible, or using time(NULL)
10731 a.k.a. epoch time otherwise; this only has second accuracy.
10732 - If {expr} is given it must be a Number. It is used to
10733 initialize the seed values. This is useful for testing or
10734 when a predictable sequence is intended.
10735
10736 Examples: >
10737 :let seed = srand()
10738 :let seed = srand(userinput)
10739 :echo rand(seed)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010740<
10741 Return type: list<number>
10742
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010743
10744state([{what}]) *state()*
10745 Return a string which contains characters indicating the
10746 current state. Mostly useful in callbacks that want to do
10747 work that may not always be safe. Roughly this works like:
10748 - callback uses state() to check if work is safe to do.
10749 Yes: then do it right away.
10750 No: add to work queue and add a |SafeState| and/or
10751 |SafeStateAgain| autocommand (|SafeState| triggers at
10752 toplevel, |SafeStateAgain| triggers after handling
10753 messages and callbacks).
10754 - When SafeState or SafeStateAgain is triggered and executes
10755 your autocommand, check with `state()` if the work can be
10756 done now, and if yes remove it from the queue and execute.
10757 Remove the autocommand if the queue is now empty.
10758 Also see |mode()|.
10759
10760 When {what} is given only characters in this string will be
10761 added. E.g, this checks if the screen has scrolled: >
10762 if state('s') == ''
10763 " screen has not scrolled
10764<
10765 These characters indicate the state, generally indicating that
10766 something is busy:
10767 m halfway a mapping, :normal command, feedkeys() or
10768 stuffed command
10769 o operator pending, e.g. after |d|
10770 a Insert mode autocomplete active
10771 x executing an autocommand
10772 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
10773 ch_readraw() when reading json
10774 S not triggering SafeState or SafeStateAgain, e.g. after
10775 |f| or a count
10776 c callback invoked, including timer (repeats for
10777 recursiveness up to "ccc")
10778 s screen has scrolled for messages
10779
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010780 Return type: |String|
10781
10782
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010783str2blob({list} [, {options}]) *str2blob()*
10784 Return a Blob by converting the characters in the List of
10785 strings in {list} into bytes.
10786
10787 A <NL> byte is added to the blob after each list item. A
10788 newline character in the string is translated into a <NUL>
10789 byte in the blob.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010790
10791 If {options} is not supplied, the current 'encoding' value is
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010792 used to convert the characters into bytes.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010793
10794 The argument {options} is a |Dict| and supports the following
10795 items:
Bakudankunb3854bf2025-02-23 20:29:21 +010010796 encoding Convert the characters using this encoding
10797 before making the Blob.
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010798 The value is a |String|. See |encoding-names|
10799 for the supported values.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010800
10801 An error is given and an empty blob is returned if the
10802 character encoding fails.
10803
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010804 Returns an empty Blob if {list} is empty.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010805
10806 See also |blob2str()|
10807
10808 Examples: >
Hirohito Higashi932a5352025-03-23 10:20:20 +010010809 str2blob(["ab"]) returns 0z6162
10810 str2blob(["«»"]) returns 0zC2ABC2BB
10811 str2blob(["a\nb"]) returns 0z610062
10812 str2blob(["a","b"]) returns 0z610A62
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010813 str2blob(["«»"], {'encoding': 'latin1'}) returns 0zABBB
Hirohito Higashi932a5352025-03-23 10:20:20 +010010814 str2blob(readfile('myfile.txt'))
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010815<
10816 Can also be used as a |method|: >
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010817 GetListOfStrings()->str2blob()
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010818<
10819 Return type: |Blob|
10820
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010821str2float({string} [, {quoted}]) *str2float()*
10822 Convert String {string} to a Float. This mostly works the
10823 same as when using a floating point number in an expression,
10824 see |floating-point-format|. But it's a bit more permissive.
10825 E.g., "1e40" is accepted, while in an expression you need to
10826 write "1.0e40". The hexadecimal form "0x123" is also
10827 accepted, but not others, like binary or octal.
10828 When {quoted} is present and non-zero then embedded single
10829 quotes before the dot are ignored, thus "1'000.0" is a
10830 thousand.
10831 Text after the number is silently ignored.
10832 The decimal point is always '.', no matter what the locale is
10833 set to. A comma ends the number: "12,345.67" is converted to
10834 12.0. You can strip out thousands separators with
10835 |substitute()|: >
10836 let f = str2float(substitute(text, ',', '', 'g'))
10837<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010838 Returns 0.0 if the conversion fails.
10839
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010840 Can also be used as a |method|: >
10841 let f = text->substitute(',', '', 'g')->str2float()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010842<
10843 Return type: |Float|
10844
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010845
10846str2list({string} [, {utf8}]) *str2list()*
10847 Return a list containing the number values which represent
10848 each character in String {string}. Examples: >
10849 str2list(" ") returns [32]
10850 str2list("ABC") returns [65, 66, 67]
10851< |list2str()| does the opposite.
10852
10853 When {utf8} is omitted or zero, the current 'encoding' is used.
10854 When {utf8} is TRUE, always treat the String as UTF-8
10855 characters. With UTF-8 composing characters are handled
10856 properly: >
10857 str2list("á") returns [97, 769]
10858
10859< Can also be used as a |method|: >
10860 GetString()->str2list()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010861<
10862 Return type: list<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010863
10864
10865str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
10866 Convert string {string} to a number.
10867 {base} is the conversion base, it can be 2, 8, 10 or 16.
10868 When {quoted} is present and non-zero then embedded single
10869 quotes are ignored, thus "1'000'000" is a million.
10870
10871 When {base} is omitted base 10 is used. This also means that
10872 a leading zero doesn't cause octal conversion to be used, as
10873 with the default String to Number conversion. Example: >
10874 let nr = str2nr('0123')
10875<
10876 When {base} is 16 a leading "0x" or "0X" is ignored. With a
10877 different base the result will be zero. Similarly, when
10878 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
10879 {base} is 2 a leading "0b" or "0B" is ignored.
10880 Text after the number is silently ignored.
10881
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010882 Returns 0 if {string} is empty or on error.
10883
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010884 Can also be used as a |method|: >
10885 GetText()->str2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010886<
10887 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010888
10889
10890strcharlen({string}) *strcharlen()*
10891 The result is a Number, which is the number of characters
10892 in String {string}. Composing characters are ignored.
10893 |strchars()| can count the number of characters, counting
10894 composing characters separately.
10895
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010896 Returns 0 if {string} is empty or on error.
10897
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010898 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10899
10900 Can also be used as a |method|: >
10901 GetText()->strcharlen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010902<
10903 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010904
10905
10906strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
10907 Like |strpart()| but using character index and length instead
10908 of byte index and length.
10909 When {skipcc} is omitted or zero, composing characters are
10910 counted separately.
zeertzjqad387692024-03-23 08:23:48 +010010911 When {skipcc} set to 1, composing characters are treated as a
10912 part of the preceding base character, similar to |slice()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010913 When a character index is used where a character does not
10914 exist it is omitted and counted as one character. For
10915 example: >
10916 strcharpart('abc', -1, 2)
10917< results in 'a'.
10918
Bram Moolenaard592deb2022-06-17 15:42:40 +010010919 Returns an empty string on error.
10920
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010921 Can also be used as a |method|: >
10922 GetText()->strcharpart(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010923<
10924 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010925
10926
10927strchars({string} [, {skipcc}]) *strchars()*
10928 The result is a Number, which is the number of characters
10929 in String {string}.
10930 When {skipcc} is omitted or zero, composing characters are
10931 counted separately.
zeertzjqad387692024-03-23 08:23:48 +010010932 When {skipcc} set to 1, composing characters are ignored.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010933 |strcharlen()| always does this.
10934
Bram Moolenaard592deb2022-06-17 15:42:40 +010010935 Returns zero on error.
10936
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010937 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10938
10939 {skipcc} is only available after 7.4.755. For backward
10940 compatibility, you can define a wrapper function: >
10941 if has("patch-7.4.755")
10942 function s:strchars(str, skipcc)
10943 return strchars(a:str, a:skipcc)
10944 endfunction
10945 else
10946 function s:strchars(str, skipcc)
10947 if a:skipcc
10948 return strlen(substitute(a:str, ".", "x", "g"))
10949 else
10950 return strchars(a:str)
10951 endif
10952 endfunction
10953 endif
10954<
10955 Can also be used as a |method|: >
10956 GetText()->strchars()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010957<
10958 Return type: |Number|
10959
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010960
10961strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
10962 The result is a Number, which is the number of display cells
10963 String {string} occupies on the screen when it starts at {col}
10964 (first column is zero). When {col} is omitted zero is used.
10965 Otherwise it is the screen column where to start. This
10966 matters for Tab characters.
10967 The option settings of the current window are used. This
10968 matters for anything that's displayed differently, such as
10969 'tabstop' and 'display'.
10970 When {string} contains characters with East Asian Width Class
10971 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010972 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010973 Also see |strlen()|, |strwidth()| and |strchars()|.
10974
10975 Can also be used as a |method|: >
10976 GetText()->strdisplaywidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010977<
10978 Return type: |Number|
10979
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010980
10981strftime({format} [, {time}]) *strftime()*
10982 The result is a String, which is a formatted date and time, as
10983 specified by the {format} string. The given {time} is used,
10984 or the current time if no time is given. The accepted
10985 {format} depends on your system, thus this is not portable!
10986 See the manual page of the C function strftime() for the
10987 format. The maximum length of the result is 80 characters.
10988 See also |localtime()|, |getftime()| and |strptime()|.
10989 The language can be changed with the |:language| command.
10990 Examples: >
10991 :echo strftime("%c") Sun Apr 27 11:49:23 1997
10992 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
10993 :echo strftime("%y%m%d %T") 970427 11:53:55
10994 :echo strftime("%H:%M") 11:55
10995 :echo strftime("%c", getftime("file.c"))
10996 Show mod time of file.c.
10997< Not available on all systems. To check use: >
10998 :if exists("*strftime")
10999
11000< Can also be used as a |method|: >
11001 GetFormat()->strftime()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011002<
11003 Return type: |String|
11004
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011005
11006strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +010011007 Get a Number corresponding to the character at {index} in
11008 {str}. This uses a zero-based character index, not a byte
11009 index. Composing characters are considered separate
11010 characters here. Use |nr2char()| to convert the Number to a
11011 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011012 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011013 Also see |strcharpart()| and |strchars()|.
11014
11015 Can also be used as a |method|: >
11016 GetText()->strgetchar(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011017<
11018 Return type: |Number|
11019
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011020
11021stridx({haystack}, {needle} [, {start}]) *stridx()*
11022 The result is a Number, which gives the byte index in
11023 {haystack} of the first occurrence of the String {needle}.
11024 If {start} is specified, the search starts at index {start}.
11025 This can be used to find a second match: >
11026 :let colon1 = stridx(line, ":")
11027 :let colon2 = stridx(line, ":", colon1 + 1)
11028< The search is done case-sensitive.
11029 For pattern searches use |match()|.
11030 -1 is returned if the {needle} does not occur in {haystack}.
11031 See also |strridx()|.
11032 Examples: >
11033 :echo stridx("An Example", "Example") 3
11034 :echo stridx("Starting point", "Start") 0
11035 :echo stridx("Starting point", "start") -1
11036< *strstr()* *strchr()*
11037 stridx() works similar to the C function strstr(). When used
11038 with a single character it works similar to strchr().
11039
11040 Can also be used as a |method|: >
11041 GetHaystack()->stridx(needle)
11042<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011043 Return type: |Number|
11044
11045
11046string({expr}) *string()*
11047 Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011048 Float, String, Blob or a composition of them, then the result
11049 can be parsed back with |eval()|.
11050 {expr} type result ~
11051 String 'string' (single quotes are doubled)
11052 Number 123
11053 Float 123.123456 or 1.123456e8
11054 Funcref function('name')
11055 Blob 0z00112233.44556677.8899
11056 List [item, item]
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +010011057 Tuple (item, item)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011058 Dictionary {key: value, key: value}
Bram Moolenaarf1dcd142022-12-31 15:30:45 +000011059 Class class SomeName
11060 Object object of SomeName {lnum: 1, col: 3}
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010011061 Enum enum EnumName
Yegappan Lakshmanan3cf121e2024-03-31 18:45:35 +020011062 EnumValue enum name.value {name: str, ordinal: nr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011063
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +010011064 When a |List|, |Tuple| or |Dictionary| has a recursive
11065 reference it is replaced by "[...]" or "(...)" or "{...}".
11066 Using eval() on the result will then fail.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011067
mityu7f0bba22024-03-29 10:14:41 +010011068 For an object, invokes the string() method to get a textual
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +010011069 representation of the object. If the method is not present,
mityu7f0bba22024-03-29 10:14:41 +010011070 then the default representation is used. |object-string()|
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +010011071
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011072 Can also be used as a |method|: >
11073 mylist->string()
11074
11075< Also see |strtrans()|.
11076
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011077 Return type: |String|
11078
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011079
11080strlen({string}) *strlen()*
11081 The result is a Number, which is the length of the String
11082 {string} in bytes.
11083 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011084 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011085 If you want to count the number of multibyte characters use
11086 |strchars()|.
11087 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
11088
11089 Can also be used as a |method|: >
11090 GetString()->strlen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011091<
11092 Return type: |Number|
11093
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011094
11095strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
11096 The result is a String, which is part of {src}, starting from
11097 byte {start}, with the byte length {len}.
11098 When {chars} is present and TRUE then {len} is the number of
11099 characters positions (composing characters are not counted
11100 separately, thus "1" means one base character and any
11101 following composing characters).
11102 To count {start} as characters instead of bytes use
11103 |strcharpart()|.
11104
11105 When bytes are selected which do not exist, this doesn't
11106 result in an error, the bytes are simply omitted.
11107 If {len} is missing, the copy continues from {start} till the
11108 end of the {src}. >
11109 strpart("abcdefg", 3, 2) == "de"
11110 strpart("abcdefg", -2, 4) == "ab"
11111 strpart("abcdefg", 5, 4) == "fg"
11112 strpart("abcdefg", 3) == "defg"
11113
11114< Note: To get the first character, {start} must be 0. For
11115 example, to get the character under the cursor: >
11116 strpart(getline("."), col(".") - 1, 1, v:true)
11117<
Bram Moolenaard592deb2022-06-17 15:42:40 +010011118 Returns an empty string on error.
11119
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011120 Can also be used as a |method|: >
11121 GetText()->strpart(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011122<
11123 Return type: |String|
11124
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011125
11126strptime({format}, {timestring}) *strptime()*
11127 The result is a Number, which is a unix timestamp representing
11128 the date and time in {timestring}, which is expected to match
11129 the format specified in {format}.
11130
11131 The accepted {format} depends on your system, thus this is not
11132 portable! See the manual page of the C function strptime()
11133 for the format. Especially avoid "%c". The value of $TZ also
11134 matters.
11135
11136 If the {timestring} cannot be parsed with {format} zero is
11137 returned. If you do not know the format of {timestring} you
11138 can try different {format} values until you get a non-zero
11139 result.
11140
11141 See also |strftime()|.
11142 Examples: >
11143 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
11144< 862156163 >
11145 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
11146< Sun Apr 27 11:53:55 1997 >
11147 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
11148< Sun Apr 27 12:53:55 1997
11149
11150 Can also be used as a |method|: >
11151 GetFormat()->strptime(timestring)
11152<
11153 Not available on all systems. To check use: >
11154 :if exists("*strptime")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011155<
11156 Return type: |Number|
11157
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011158
11159strridx({haystack}, {needle} [, {start}]) *strridx()*
11160 The result is a Number, which gives the byte index in
11161 {haystack} of the last occurrence of the String {needle}.
11162 When {start} is specified, matches beyond this index are
11163 ignored. This can be used to find a match before a previous
11164 match: >
11165 :let lastcomma = strridx(line, ",")
11166 :let comma2 = strridx(line, ",", lastcomma - 1)
11167< The search is done case-sensitive.
11168 For pattern searches use |match()|.
11169 -1 is returned if the {needle} does not occur in {haystack}.
11170 If the {needle} is empty the length of {haystack} is returned.
11171 See also |stridx()|. Examples: >
11172 :echo strridx("an angry armadillo", "an") 3
11173< *strrchr()*
11174 When used with a single character it works similar to the C
11175 function strrchr().
11176
11177 Can also be used as a |method|: >
11178 GetHaystack()->strridx(needle)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011179<
11180 Return type: |Number|
11181
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011182
11183strtrans({string}) *strtrans()*
11184 The result is a String, which is {string} with all unprintable
11185 characters translated into printable characters |'isprint'|.
11186 Like they are shown in a window. Example: >
11187 echo strtrans(@a)
11188< This displays a newline in register a as "^@" instead of
11189 starting a new line.
11190
Bram Moolenaard592deb2022-06-17 15:42:40 +010011191 Returns an empty string on error.
11192
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011193 Can also be used as a |method|: >
11194 GetString()->strtrans()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011195<
11196 Return type: |String|
11197
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011198
Christian Brabandt67672ef2023-04-24 21:09:54 +010011199strutf16len({string} [, {countcc}]) *strutf16len()*
11200 The result is a Number, which is the number of UTF-16 code
11201 units in String {string} (after converting it to UTF-16).
11202
11203 When {countcc} is TRUE, composing characters are counted
11204 separately.
11205 When {countcc} is omitted or FALSE, composing characters are
11206 ignored.
11207
11208 Returns zero on error.
11209
11210 Also see |strlen()| and |strcharlen()|.
11211 Examples: >
11212 echo strutf16len('a') returns 1
11213 echo strutf16len('©') returns 1
11214 echo strutf16len('😊') returns 2
11215 echo strutf16len('ą́') returns 1
11216 echo strutf16len('ą́', v:true) returns 3
a5ob7r790f9a82023-09-25 06:05:47 +090011217<
Christian Brabandt67672ef2023-04-24 21:09:54 +010011218 Can also be used as a |method|: >
11219 GetText()->strutf16len()
11220<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011221 Return type: |Number|
11222
11223
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011224strwidth({string}) *strwidth()*
11225 The result is a Number, which is the number of display cells
11226 String {string} occupies. A Tab character is counted as one
11227 cell, alternatively use |strdisplaywidth()|.
11228 When {string} contains characters with East Asian Width Class
11229 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011230 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011231 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
11232
11233 Can also be used as a |method|: >
11234 GetString()->strwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011235<
11236 Return type: |Number|
11237
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011238
11239submatch({nr} [, {list}]) *submatch()* *E935*
11240 Only for an expression in a |:substitute| command or
11241 substitute() function.
11242 Returns the {nr}'th submatch of the matched text. When {nr}
11243 is 0 the whole matched text is returned.
11244 Note that a NL in the string can stand for a line break of a
11245 multi-line match or a NUL character in the text.
11246 Also see |sub-replace-expression|.
11247
11248 If {list} is present and non-zero then submatch() returns
11249 a list of strings, similar to |getline()| with two arguments.
11250 NL characters in the text represent NUL characters in the
11251 text.
11252 Only returns more than one item for |:substitute|, inside
11253 |substitute()| this list will always contain one or zero
11254 items, since there are no real line breaks.
11255
11256 When substitute() is used recursively only the submatches in
11257 the current (deepest) call can be obtained.
11258
Bram Moolenaard592deb2022-06-17 15:42:40 +010011259 Returns an empty string or list on error.
11260
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011261 Examples: >
11262 :s/\d\+/\=submatch(0) + 1/
11263 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
11264< This finds the first number in the line and adds one to it.
11265 A line break is included as a newline character.
11266
11267 Can also be used as a |method|: >
11268 GetNr()->submatch()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011269<
11270 Return type: |String| or list<string> depending on {list}
11271
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011272
11273substitute({string}, {pat}, {sub}, {flags}) *substitute()*
11274 The result is a String, which is a copy of {string}, in which
11275 the first match of {pat} is replaced with {sub}.
11276 When {flags} is "g", all matches of {pat} in {string} are
11277 replaced. Otherwise {flags} should be "".
11278
11279 This works like the ":substitute" command (without any flags).
11280 But the matching with {pat} is always done like the 'magic'
11281 option is set and 'cpoptions' is empty (to make scripts
11282 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
11283 if you want to ignore or match case and ignore 'ignorecase'.
11284 'smartcase' is not used. See |string-match| for how {pat} is
11285 used.
11286
11287 A "~" in {sub} is not replaced with the previous {sub}.
11288 Note that some codes in {sub} have a special meaning
11289 |sub-replace-special|. For example, to replace something with
11290 "\n" (two characters), use "\\\\n" or '\\n'.
11291
11292 When {pat} does not match in {string}, {string} is returned
11293 unmodified.
11294
11295 Example: >
11296 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
11297< This removes the last component of the 'path' option. >
11298 :echo substitute("testing", ".*", "\\U\\0", "")
11299< results in "TESTING".
11300
11301 When {sub} starts with "\=", the remainder is interpreted as
11302 an expression. See |sub-replace-expression|. Example: >
11303 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011304 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011305
11306< When {sub} is a Funcref that function is called, with one
11307 optional argument. Example: >
11308 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
11309< The optional argument is a list which contains the whole
11310 matched string and up to nine submatches, like what
11311 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011312 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011313
Bram Moolenaard592deb2022-06-17 15:42:40 +010011314< Returns an empty string on error.
11315
11316 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011317 GetString()->substitute(pat, sub, flags)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011318<
11319 Return type: |String|
11320
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011321
Bram Moolenaarc216a7a2022-12-05 13:50:55 +000011322swapfilelist() *swapfilelist()*
11323 Returns a list of swap file names, like what "vim -r" shows.
11324 See the |-r| command argument. The 'directory' option is used
11325 for the directories to inspect. If you only want to get a
11326 list of swap files in the current directory then temporarily
11327 set 'directory' to a dot: >
11328 let save_dir = &directory
11329 let &directory = '.'
11330 let swapfiles = swapfilelist()
11331 let &directory = save_dir
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011332<
11333 Return type: list<string>
11334
Bram Moolenaarc216a7a2022-12-05 13:50:55 +000011335
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011336swapinfo({fname}) *swapinfo()*
11337 The result is a dictionary, which holds information about the
11338 swapfile {fname}. The available fields are:
11339 version Vim version
11340 user user name
11341 host host name
11342 fname original file name
11343 pid PID of the Vim process that created the swap
11344 file
11345 mtime last modification time in seconds
11346 inode Optional: INODE number of the file
11347 dirty 1 if file was modified, 0 if not
11348 Note that "user" and "host" are truncated to at most 39 bytes.
11349 In case of failure an "error" item is added with the reason:
11350 Cannot open file: file not found or in accessible
11351 Cannot read file: cannot read first block
11352 Not a swap file: does not contain correct block ID
11353 Magic number mismatch: Info in first block is invalid
11354
11355 Can also be used as a |method|: >
11356 GetFilename()->swapinfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011357<
11358 Return type: dict<any> or dict<string>
11359
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011360
11361swapname({buf}) *swapname()*
11362 The result is the swap file path of the buffer {expr}.
11363 For the use of {buf}, see |bufname()| above.
11364 If buffer {buf} is the current buffer, the result is equal to
11365 |:swapname| (unless there is no swap file).
11366 If buffer {buf} has no swap file, returns an empty string.
11367
11368 Can also be used as a |method|: >
11369 GetBufname()->swapname()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011370<
11371 Return type: |String|
11372
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011373
11374synID({lnum}, {col}, {trans}) *synID()*
11375 The result is a Number, which is the syntax ID at the position
11376 {lnum} and {col} in the current window.
11377 The syntax ID can be used with |synIDattr()| and
11378 |synIDtrans()| to obtain syntax information about text.
11379
11380 {col} is 1 for the leftmost column, {lnum} is 1 for the first
11381 line. 'synmaxcol' applies, in a longer line zero is returned.
11382 Note that when the position is after the last character,
11383 that's where the cursor can be in Insert mode, synID() returns
11384 zero. {lnum} is used like with |getline()|.
11385
11386 When {trans} is |TRUE|, transparent items are reduced to the
11387 item that they reveal. This is useful when wanting to know
11388 the effective color. When {trans} is |FALSE|, the transparent
11389 item is returned. This is useful when wanting to know which
11390 syntax item is effective (e.g. inside parens).
11391 Warning: This function can be very slow. Best speed is
11392 obtained by going through the file in forward direction.
11393
Bram Moolenaard592deb2022-06-17 15:42:40 +010011394 Returns zero on error.
11395
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011396 Example (echoes the name of the syntax item under the cursor): >
11397 :echo synIDattr(synID(line("."), col("."), 1), "name")
11398<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011399 Return type: |Number|
11400
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011401
11402synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
11403 The result is a String, which is the {what} attribute of
11404 syntax ID {synID}. This can be used to obtain information
11405 about a syntax item.
11406 {mode} can be "gui", "cterm" or "term", to get the attributes
11407 for that mode. When {mode} is omitted, or an invalid value is
11408 used, the attributes for the currently active highlighting are
11409 used (GUI, cterm or term).
11410 Use synIDtrans() to follow linked highlight groups.
11411 {what} result
11412 "name" the name of the syntax item
11413 "fg" foreground color (GUI: color name used to set
11414 the color, cterm: color number as a string,
11415 term: empty string)
11416 "bg" background color (as with "fg")
11417 "font" font name (only available in the GUI)
11418 |highlight-font|
11419 "sp" special color for the GUI (as with "fg")
11420 |highlight-guisp|
11421 "ul" underline color for cterm: number as a string
11422 "fg#" like "fg", but for the GUI and the GUI is
11423 running the name in "#RRGGBB" form
11424 "bg#" like "fg#" for "bg"
11425 "sp#" like "fg#" for "sp"
11426 "bold" "1" if bold
11427 "italic" "1" if italic
11428 "reverse" "1" if reverse
11429 "inverse" "1" if inverse (= reverse)
11430 "standout" "1" if standout
11431 "underline" "1" if underlined
11432 "undercurl" "1" if undercurled
11433 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +010011434 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011435
Bram Moolenaard592deb2022-06-17 15:42:40 +010011436 Returns an empty string on error.
11437
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011438 Example (echoes the color of the syntax item under the
11439 cursor): >
11440 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
11441<
11442 Can also be used as a |method|: >
11443 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011444<
11445 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011446
11447
11448synIDtrans({synID}) *synIDtrans()*
11449 The result is a Number, which is the translated syntax ID of
11450 {synID}. This is the syntax group ID of what is being used to
11451 highlight the character. Highlight links given with
11452 ":highlight link" are followed.
11453
Bram Moolenaard592deb2022-06-17 15:42:40 +010011454 Returns zero on error.
11455
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011456 Can also be used as a |method|: >
11457 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011458<
11459 Return type: |Number|
11460
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011461
11462synconcealed({lnum}, {col}) *synconcealed()*
11463 The result is a |List| with currently three items:
11464 1. The first item in the list is 0 if the character at the
11465 position {lnum} and {col} is not part of a concealable
11466 region, 1 if it is. {lnum} is used like with |getline()|.
11467 2. The second item in the list is a string. If the first item
11468 is 1, the second item contains the text which will be
11469 displayed in place of the concealed text, depending on the
11470 current setting of 'conceallevel' and 'listchars'.
11471 3. The third and final item in the list is a number
11472 representing the specific syntax region matched in the
11473 line. When the character is not concealed the value is
11474 zero. This allows detection of the beginning of a new
11475 concealable region if there are two consecutive regions
11476 with the same replacement character. For an example, if
11477 the text is "123456" and both "23" and "45" are concealed
11478 and replaced by the character "X", then:
11479 call returns ~
11480 synconcealed(lnum, 1) [0, '', 0]
11481 synconcealed(lnum, 2) [1, 'X', 1]
11482 synconcealed(lnum, 3) [1, 'X', 1]
11483 synconcealed(lnum, 4) [1, 'X', 2]
11484 synconcealed(lnum, 5) [1, 'X', 2]
11485 synconcealed(lnum, 6) [0, '', 0]
11486
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020011487 Note: Doesn't consider |matchadd()| highlighting items,
11488 since syntax and matching highlighting are two different
11489 mechanisms |syntax-vs-match|.
h-east52e7cc22024-07-28 17:03:29 +020011490
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011491 Return type: list<any>
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020011492
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011493
11494synstack({lnum}, {col}) *synstack()*
11495 Return a |List|, which is the stack of syntax items at the
11496 position {lnum} and {col} in the current window. {lnum} is
11497 used like with |getline()|. Each item in the List is an ID
11498 like what |synID()| returns.
11499 The first item in the List is the outer region, following are
11500 items contained in that one. The last one is what |synID()|
11501 returns, unless not the whole item is highlighted or it is a
11502 transparent item.
11503 This function is useful for debugging a syntax file.
11504 Example that shows the syntax stack under the cursor: >
11505 for id in synstack(line("."), col("."))
11506 echo synIDattr(id, "name")
11507 endfor
11508< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +010011509 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011510 character in a line and the first column in an empty line are
11511 valid positions.
11512
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011513 Return type: list<number> or list<any>
11514
11515
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011516system({expr} [, {input}]) *system()* *E677*
11517 Get the output of the shell command {expr} as a |String|. See
11518 |systemlist()| to get the output as a |List|.
11519
11520 When {input} is given and is a |String| this string is written
11521 to a file and passed as stdin to the command. The string is
11522 written as-is, you need to take care of using the correct line
11523 separators yourself.
11524 If {input} is given and is a |List| it is written to the file
11525 in a way |writefile()| does with {binary} set to "b" (i.e.
11526 with a newline between each list item with newlines inside
11527 list items converted to NULs).
11528 When {input} is given and is a number that is a valid id for
11529 an existing buffer then the content of the buffer is written
11530 to the file line by line, each line terminated by a NL and
11531 NULs characters where the text has a NL.
11532
11533 Pipes are not used, the 'shelltemp' option is not used.
11534
11535 When prepended by |:silent| the terminal will not be set to
11536 cooked mode. This is meant to be used for commands that do
11537 not need the user to type. It avoids stray characters showing
11538 up on the screen which require |CTRL-L| to remove. >
11539 :silent let f = system('ls *.vim')
11540<
11541 Note: Use |shellescape()| or |::S| with |expand()| or
11542 |fnamemodify()| to escape special characters in a command
11543 argument. Newlines in {expr} may cause the command to fail.
11544 The characters in 'shellquote' and 'shellxquote' may also
11545 cause trouble.
11546 This is not to be used for interactive commands.
11547
11548 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011549 :let files = system('ls ' .. shellescape(expand('%:h')))
11550 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011551
11552< To make the result more system-independent, the shell output
11553 is filtered to replace <CR> with <NL> for Macintosh, and
11554 <CR><NL> with <NL> for DOS-like systems.
11555 To avoid the string being truncated at a NUL, all NUL
11556 characters are replaced with SOH (0x01).
11557
11558 The command executed is constructed using several options:
11559 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
11560 ({tmp} is an automatically generated file name).
11561 For Unix, braces are put around {expr} to allow for
11562 concatenated commands.
11563
11564 The command will be executed in "cooked" mode, so that a
11565 CTRL-C will interrupt the command (on Unix at least).
11566
11567 The resulting error code can be found in |v:shell_error|.
11568 This function will fail in |restricted-mode|.
11569
11570 Note that any wrong value in the options mentioned above may
11571 make the function fail. It has also been reported to fail
11572 when using a security agent application.
11573 Unlike ":!cmd" there is no automatic check for changed files.
11574 Use |:checktime| to force a check.
11575
11576 Can also be used as a |method|: >
11577 :echo GetCmd()->system()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011578<
11579 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011580
11581
11582systemlist({expr} [, {input}]) *systemlist()*
11583 Same as |system()|, but returns a |List| with lines (parts of
11584 output separated by NL) with NULs transformed into NLs. Output
11585 is the same as |readfile()| will output with {binary} argument
11586 set to "b", except that there is no extra empty item when the
11587 result ends in a NL.
11588 Note that on MS-Windows you may get trailing CR characters.
11589
11590 To see the difference between "echo hello" and "echo -n hello"
11591 use |system()| and |split()|: >
11592 echo system('echo hello')->split('\n', 1)
11593<
11594 Returns an empty string on error.
11595
11596 Can also be used as a |method|: >
11597 :echo GetCmd()->systemlist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011598<
11599 Return type: list<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011600
11601
11602tabpagebuflist([{arg}]) *tabpagebuflist()*
11603 The result is a |List|, where each item is the number of the
11604 buffer associated with each window in the current tab page.
11605 {arg} specifies the number of the tab page to be used. When
11606 omitted the current tab page is used.
11607 When {arg} is invalid the number zero is returned.
11608 To get a list of all buffers in all tabs use this: >
11609 let buflist = []
11610 for i in range(tabpagenr('$'))
11611 call extend(buflist, tabpagebuflist(i + 1))
11612 endfor
11613< Note that a buffer may appear in more than one window.
11614
11615 Can also be used as a |method|: >
11616 GetTabpage()->tabpagebuflist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011617<
11618 Return type: list<number>
11619
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011620
11621tabpagenr([{arg}]) *tabpagenr()*
11622 The result is a Number, which is the number of the current
11623 tab page. The first tab page has number 1.
11624
11625 The optional argument {arg} supports the following values:
11626 $ the number of the last tab page (the tab page
11627 count).
11628 # the number of the last accessed tab page
11629 (where |g<Tab>| goes to). if there is no
11630 previous tab page 0 is returned.
11631 The number can be used with the |:tab| command.
11632
Bram Moolenaard592deb2022-06-17 15:42:40 +010011633 Returns zero on error.
11634
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011635 Return type: |Number|
11636
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011637
11638tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
11639 Like |winnr()| but for tab page {tabarg}.
11640 {tabarg} specifies the number of tab page to be used.
11641 {arg} is used like with |winnr()|:
11642 - When omitted the current window number is returned. This is
11643 the window which will be used when going to this tab page.
11644 - When "$" the number of windows is returned.
11645 - When "#" the previous window nr is returned.
11646 Useful examples: >
11647 tabpagewinnr(1) " current window of tab page 1
11648 tabpagewinnr(4, '$') " number of windows in tab page 4
11649< When {tabarg} is invalid zero is returned.
11650
11651 Can also be used as a |method|: >
11652 GetTabpage()->tabpagewinnr()
11653<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011654 Return type: |Number|
11655
11656
11657tagfiles() *tagfiles()*
11658 Returns a |List| with the file names used to search for tags
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011659 for the current buffer. This is the 'tags' option expanded.
11660
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011661 Return type: list<string> or list<any>
11662
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011663
11664taglist({expr} [, {filename}]) *taglist()*
11665 Returns a |List| of tags matching the regular expression {expr}.
11666
11667 If {filename} is passed it is used to prioritize the results
11668 in the same way that |:tselect| does. See |tag-priority|.
11669 {filename} should be the full path of the file.
11670
11671 Each list item is a dictionary with at least the following
11672 entries:
11673 name Name of the tag.
11674 filename Name of the file where the tag is
11675 defined. It is either relative to the
11676 current directory or a full path.
11677 cmd Ex command used to locate the tag in
11678 the file.
11679 kind Type of the tag. The value for this
11680 entry depends on the language specific
11681 kind values. Only available when
11682 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +000011683 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011684 static A file specific tag. Refer to
11685 |static-tag| for more information.
11686 More entries may be present, depending on the content of the
11687 tags file: access, implementation, inherits and signature.
11688 Refer to the ctags documentation for information about these
11689 fields. For C code the fields "struct", "class" and "enum"
11690 may appear, they give the name of the entity the tag is
11691 contained in.
11692
11693 The ex-command "cmd" can be either an ex search pattern, a
11694 line number or a line number followed by a byte number.
11695
11696 If there are no matching tags, then an empty list is returned.
11697
11698 To get an exact tag match, the anchors '^' and '$' should be
11699 used in {expr}. This also make the function work faster.
11700 Refer to |tag-regexp| for more information about the tag
11701 search regular expression pattern.
11702
11703 Refer to |'tags'| for information about how the tags file is
11704 located by Vim. Refer to |tags-file-format| for the format of
11705 the tags file generated by the different ctags tools.
11706
11707 Can also be used as a |method|: >
11708 GetTagpattern()->taglist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011709<
11710 Return type: list<dict<any>> or list<any>
11711
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011712
11713tan({expr}) *tan()*
11714 Return the tangent of {expr}, measured in radians, as a |Float|
11715 in the range [-inf, inf].
11716 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011717 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011718 Examples: >
11719 :echo tan(10)
11720< 0.648361 >
11721 :echo tan(-4.01)
11722< -1.181502
11723
11724 Can also be used as a |method|: >
11725 Compute()->tan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011726<
11727 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011728
11729
11730tanh({expr}) *tanh()*
11731 Return the hyperbolic tangent of {expr} as a |Float| in the
11732 range [-1, 1].
11733 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011734 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011735 Examples: >
11736 :echo tanh(0.5)
11737< 0.462117 >
11738 :echo tanh(-1)
11739< -0.761594
11740
11741 Can also be used as a |method|: >
11742 Compute()->tanh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011743<
11744 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011745
11746
11747tempname() *tempname()* *temp-file-name*
11748 The result is a String, which is the name of a file that
11749 doesn't exist. It can be used for a temporary file. The name
11750 is different for at least 26 consecutive calls. Example: >
11751 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011752 :exe "redir > " .. tmpfile
Christian Brabandt5cf53012024-05-18 10:13:11 +020011753< For Unix, the file will be in a private directory |tempfile|
11754 that is recursively deleted when Vim exits, on other systems
11755 temporary files are not cleaned up automatically on exit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011756 For MS-Windows forward slashes are used when the 'shellslash'
11757 option is set, or when 'shellcmdflag' starts with '-' and
11758 'shell' does not contain powershell or pwsh.
11759
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011760 Return type: |String|
11761
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011762
11763term_ functions are documented here: |terminal-function-details|
11764
11765
11766terminalprops() *terminalprops()*
11767 Returns a |Dictionary| with properties of the terminal that Vim
11768 detected from the response to |t_RV| request. See
11769 |v:termresponse| for the response itself. If |v:termresponse|
11770 is empty most values here will be 'u' for unknown.
11771 cursor_style whether sending |t_RS| works **
11772 cursor_blink_mode whether sending |t_RC| works **
11773 underline_rgb whether |t_8u| works **
11774 mouse mouse type supported
Bram Moolenaar4bc85f22022-10-21 14:17:24 +010011775 kitty whether Kitty terminal was detected
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011776
11777 ** value 'u' for unknown, 'y' for yes, 'n' for no
11778
11779 If the |+termresponse| feature is missing then the result is
11780 an empty dictionary.
11781
11782 If "cursor_style" is 'y' then |t_RS| will be sent to request the
11783 current cursor style.
11784 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
11785 request the cursor blink status.
11786 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
11787 is not empty, Vim will detect the working of sending |t_RS|
11788 and |t_RC| on startup.
11789
11790 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
11791 This avoids sending it to xterm, which would clear the colors.
11792
11793 For "mouse" the value 'u' is unknown
11794
11795 Also see:
11796 - 'ambiwidth' - detected by using |t_u7|.
11797 - |v:termstyleresp| and |v:termblinkresp| for the response to
11798 |t_RS| and |t_RC|.
11799
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011800 Return type: dict<string>
11801
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011802
11803test_ functions are documented here: |test-functions-details|
11804
11805
11806 *timer_info()*
11807timer_info([{id}])
11808 Return a list with information about timers.
11809 When {id} is given only information about this timer is
11810 returned. When timer {id} does not exist an empty list is
11811 returned.
11812 When {id} is omitted information about all timers is returned.
11813
11814 For each timer the information is stored in a |Dictionary| with
11815 these items:
11816 "id" the timer ID
11817 "time" time the timer was started with
11818 "remaining" time until the timer fires
11819 "repeat" number of times the timer will still fire;
11820 -1 means forever
11821 "callback" the callback
11822 "paused" 1 if the timer is paused, 0 otherwise
11823
11824 Can also be used as a |method|: >
11825 GetTimer()->timer_info()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011826<
11827 Return type: list<dict<any>> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011828
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011829 {only available when compiled with the |+timers| feature}
11830
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011831
11832timer_pause({timer}, {paused}) *timer_pause()*
11833 Pause or unpause a timer. A paused timer does not invoke its
11834 callback when its time expires. Unpausing a timer may cause
11835 the callback to be invoked almost immediately if enough time
11836 has passed.
11837
11838 Pausing a timer is useful to avoid the callback to be called
11839 for a short time.
11840
11841 If {paused} evaluates to a non-zero Number or a non-empty
11842 String, then the timer is paused, otherwise it is unpaused.
11843 See |non-zero-arg|.
11844
11845 Can also be used as a |method|: >
11846 GetTimer()->timer_pause(1)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011847<
11848 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011849
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011850 {only available when compiled with the |+timers| feature}
11851
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011852
11853 *timer_start()* *timer* *timers*
11854timer_start({time}, {callback} [, {options}])
11855 Create a timer and return the timer ID.
11856
11857 {time} is the waiting time in milliseconds. This is the
11858 minimum time before invoking the callback. When the system is
11859 busy or Vim is not waiting for input the time will be longer.
Bram Moolenaardd60c362023-02-27 15:49:53 +000011860 Zero can be used to execute the callback when Vim is back in
11861 the main loop.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011862
11863 {callback} is the function to call. It can be the name of a
11864 function or a |Funcref|. It is called with one argument, which
11865 is the timer ID. The callback is only invoked when Vim is
11866 waiting for input.
11867 If you want to show a message look at |popup_notification()|
11868 to avoid interfering with what the user is doing.
11869
11870 {options} is a dictionary. Supported entries:
11871 "repeat" Number of times to repeat calling the
11872 callback. -1 means forever. When not present
11873 the callback will be called once.
11874 If the timer causes an error three times in a
11875 row the repeat is cancelled. This avoids that
11876 Vim becomes unusable because of all the error
11877 messages.
11878
Bram Moolenaard592deb2022-06-17 15:42:40 +010011879 Returns -1 on error.
11880
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011881 Example: >
11882 func MyHandler(timer)
11883 echo 'Handler called'
11884 endfunc
11885 let timer = timer_start(500, 'MyHandler',
11886 \ {'repeat': 3})
11887< This will invoke MyHandler() three times at 500 msec
11888 intervals.
11889
11890 Can also be used as a |method|: >
11891 GetMsec()->timer_start(callback)
11892
11893< Not available in the |sandbox|.
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011894
11895 Return type: |Number|
11896
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011897 {only available when compiled with the |+timers| feature}
11898
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011899
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011900timer_stop({timer}) *timer_stop()*
11901 Stop a timer. The timer callback will no longer be invoked.
11902 {timer} is an ID returned by timer_start(), thus it must be a
11903 Number. If {timer} does not exist there is no error.
11904
11905 Can also be used as a |method|: >
11906 GetTimer()->timer_stop()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011907<
11908 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011909
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011910 {only available when compiled with the |+timers| feature}
11911
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011912
11913timer_stopall() *timer_stopall()*
11914 Stop all timers. The timer callbacks will no longer be
11915 invoked. Useful if a timer is misbehaving. If there are no
11916 timers there is no error.
11917
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011918 Return type: |Number|
11919
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011920 {only available when compiled with the |+timers| feature}
11921
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011922
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011923tolower({expr}) *tolower()*
11924 The result is a copy of the String given, with all uppercase
11925 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010011926 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011927
11928 Can also be used as a |method|: >
11929 GetText()->tolower()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011930<
11931 Return type: |String|
11932
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011933
11934toupper({expr}) *toupper()*
11935 The result is a copy of the String given, with all lowercase
11936 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010011937 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011938
11939 Can also be used as a |method|: >
11940 GetText()->toupper()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011941<
11942 Return type: |String|
11943
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011944
11945tr({src}, {fromstr}, {tostr}) *tr()*
11946 The result is a copy of the {src} string with all characters
11947 which appear in {fromstr} replaced by the character in that
11948 position in the {tostr} string. Thus the first character in
11949 {fromstr} is translated into the first character in {tostr}
11950 and so on. Exactly like the unix "tr" command.
11951 This code also deals with multibyte characters properly.
11952
Bram Moolenaard592deb2022-06-17 15:42:40 +010011953 Returns an empty string on error.
11954
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011955 Examples: >
11956 echo tr("hello there", "ht", "HT")
11957< returns "Hello THere" >
11958 echo tr("<blob>", "<>", "{}")
11959< returns "{blob}"
11960
11961 Can also be used as a |method|: >
11962 GetText()->tr(from, to)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011963<
11964 Return type: |String|
11965
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011966
11967trim({text} [, {mask} [, {dir}]]) *trim()*
11968 Return {text} as a String where any character in {mask} is
11969 removed from the beginning and/or end of {text}.
11970
Illia Bobyr80799172023-10-17 18:00:50 +020011971 If {mask} is not given, or is an empty string, {mask} is all
11972 characters up to 0x20, which includes Tab, space, NL and CR,
11973 plus the non-breaking space character 0xa0.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011974
11975 The optional {dir} argument specifies where to remove the
11976 characters:
11977 0 remove from the beginning and end of {text}
11978 1 remove only at the beginning of {text}
11979 2 remove only at the end of {text}
11980 When omitted both ends are trimmed.
11981
11982 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011983 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011984
11985 Examples: >
11986 echo trim(" some text ")
11987< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011988 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011989< returns "RESERVE_TAIL" >
11990 echo trim("rm<Xrm<>X>rrm", "rm<>")
11991< returns "Xrm<>X" (characters in the middle are not removed) >
11992 echo trim(" vim ", " ", 2)
11993< returns " vim"
11994
11995 Can also be used as a |method|: >
11996 GetText()->trim()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011997<
11998 Return type: |String|
11999
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012000
12001trunc({expr}) *trunc()*
12002 Return the largest integral value with magnitude less than or
12003 equal to {expr} as a |Float| (truncate towards zero).
12004 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010012005 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012006 Examples: >
12007 echo trunc(1.456)
12008< 1.0 >
12009 echo trunc(-5.456)
12010< -5.0 >
12011 echo trunc(4.0)
12012< 4.0
12013
12014 Can also be used as a |method|: >
12015 Compute()->trunc()
12016<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012017 Return type: |Float|
12018
12019
Yegappan Lakshmanan1c2f4752025-03-30 15:37:24 +020012020tuple2list({tuple}) *tuple2list()*
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +010012021 Create a List from a shallow copy of the tuple items.
12022 Examples: >
12023 tuple2list((1, 2, 3)) returns [1, 2, 3]
12024< |list2tuple()| does the opposite.
12025
12026 This function doesn't recursively convert all the Tuple items
12027 in {tuple} to a List. Note that the items are identical
12028 between the list and the tuple, changing an item changes the
12029 contents of both the tuple and the list.
12030
12031 Returns an empty list on error.
12032
12033 Can also be used as a |method|: >
12034 GetTuple()->tuple2list()
12035<
12036 Return type: list<{type}> (depending on the given |Tuple|)
12037
12038
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012039 *type()*
12040type({expr}) The result is a Number representing the type of {expr}.
12041 Instead of using the number directly, it is better to use the
12042 v:t_ variable that has the value:
12043 Number: 0 |v:t_number|
12044 String: 1 |v:t_string|
12045 Funcref: 2 |v:t_func|
12046 List: 3 |v:t_list|
12047 Dictionary: 4 |v:t_dict|
12048 Float: 5 |v:t_float|
12049 Boolean: 6 |v:t_bool| (v:false and v:true)
12050 None: 7 |v:t_none| (v:null and v:none)
12051 Job: 8 |v:t_job|
12052 Channel: 9 |v:t_channel|
12053 Blob: 10 |v:t_blob|
h_east596a9f22023-11-21 21:24:23 +090012054 Class: 12 |v:t_class|
12055 Object: 13 |v:t_object|
Yegappan Lakshmanan2a71b542023-12-14 20:03:03 +010012056 Typealias: 14 |v:t_typealias|
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010012057 Enum: 15 |v:t_enum|
12058 EnumValue: 16 |v:t_enumvalue|
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +010012059 Tuple: 17 |v:t_tuple|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012060 For backward compatibility, this method can be used: >
12061 :if type(myvar) == type(0)
12062 :if type(myvar) == type("")
12063 :if type(myvar) == type(function("tr"))
12064 :if type(myvar) == type([])
12065 :if type(myvar) == type({})
12066 :if type(myvar) == type(0.0)
12067 :if type(myvar) == type(v:false)
12068 :if type(myvar) == type(v:none)
12069< To check if the v:t_ variables exist use this: >
12070 :if exists('v:t_number')
12071
12072< Can also be used as a |method|: >
12073 mylist->type()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012074<
12075 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012076
12077
12078typename({expr}) *typename()*
12079 Return a string representation of the type of {expr}.
12080 Example: >
12081 echo typename([1, 2, 3])
Kota Kato66bb9ae2023-01-17 18:31:56 +000012082< list<number> ~
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012083
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012084 Return type: |String|
12085
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012086
12087undofile({name}) *undofile()*
12088 Return the name of the undo file that would be used for a file
12089 with name {name} when writing. This uses the 'undodir'
12090 option, finding directories that exist. It does not check if
12091 the undo file exists.
12092 {name} is always expanded to the full path, since that is what
12093 is used internally.
12094 If {name} is empty undofile() returns an empty string, since a
12095 buffer without a file name will not write an undo file.
12096 Useful in combination with |:wundo| and |:rundo|.
12097 When compiled without the |+persistent_undo| option this always
12098 returns an empty string.
12099
12100 Can also be used as a |method|: >
12101 GetFilename()->undofile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012102<
12103 Return type: |String|
12104
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012105
Devin J. Pohly5fee1112023-04-23 20:26:59 -050012106undotree([{buf}]) *undotree()*
12107 Return the current state of the undo tree for the current
12108 buffer, or for a specific buffer if {buf} is given. The
12109 result is a dictionary with the following items:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012110 "seq_last" The highest undo sequence number used.
12111 "seq_cur" The sequence number of the current position in
12112 the undo tree. This differs from "seq_last"
12113 when some changes were undone.
12114 "time_cur" Time last used for |:earlier| and related
12115 commands. Use |strftime()| to convert to
12116 something readable.
12117 "save_last" Number of the last file write. Zero when no
12118 write yet.
12119 "save_cur" Number of the current position in the undo
12120 tree.
12121 "synced" Non-zero when the last undo block was synced.
12122 This happens when waiting from input from the
12123 user. See |undo-blocks|.
12124 "entries" A list of dictionaries with information about
12125 undo blocks.
12126
12127 The first item in the "entries" list is the oldest undo item.
12128 Each List item is a |Dictionary| with these items:
12129 "seq" Undo sequence number. Same as what appears in
12130 |:undolist|.
12131 "time" Timestamp when the change happened. Use
12132 |strftime()| to convert to something readable.
12133 "newhead" Only appears in the item that is the last one
12134 that was added. This marks the last change
12135 and where further changes will be added.
12136 "curhead" Only appears in the item that is the last one
12137 that was undone. This marks the current
12138 position in the undo tree, the block that will
12139 be used by a redo command. When nothing was
12140 undone after the last change this item will
12141 not appear anywhere.
12142 "save" Only appears on the last block before a file
12143 write. The number is the write count. The
12144 first write has number 1, the last one the
12145 "save_last" mentioned above.
12146 "alt" Alternate entry. This is again a List of undo
12147 blocks. Each item may again have an "alt"
12148 item.
12149
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012150 Return type: dict<any>
12151
12152
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012153uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
12154 Remove second and succeeding copies of repeated adjacent
12155 {list} items in-place. Returns {list}. If you want a list
12156 to remain unmodified make a copy first: >
12157 :let newlist = uniq(copy(mylist))
12158< The default compare function uses the string representation of
12159 each item. For the use of {func} and {dict} see |sort()|.
Hirohito Higashi74f0a772025-06-23 21:42:36 +020012160 For deduplicating text in the current buffer see |:uniq|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012161
Bram Moolenaard592deb2022-06-17 15:42:40 +010012162 Returns zero if {list} is not a |List|.
12163
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012164 Can also be used as a |method|: >
12165 mylist->uniq()
Christian Brabandt67672ef2023-04-24 21:09:54 +010012166<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012167 Return type: list<{type}>
12168
12169
Christian Brabandt67672ef2023-04-24 21:09:54 +010012170 *utf16idx()*
12171utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010012172 Same as |charidx()| but returns the UTF-16 code unit index of
12173 the byte at {idx} in {string} (after converting it to UTF-16).
Christian Brabandt67672ef2023-04-24 21:09:54 +010012174
12175 When {charidx} is present and TRUE, {idx} is used as the
12176 character index in the String {string} instead of as the byte
12177 index.
Yegappan Lakshmanan95707032023-06-14 13:10:15 +010012178 An {idx} in the middle of a UTF-8 sequence is rounded
12179 downwards to the beginning of that sequence.
Christian Brabandt67672ef2023-04-24 21:09:54 +010012180
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010012181 Returns -1 if the arguments are invalid or if there are less
12182 than {idx} bytes in {string}. If there are exactly {idx} bytes
12183 the length of the string in UTF-16 code units is returned.
12184
Christian Brabandt67672ef2023-04-24 21:09:54 +010012185 See |byteidx()| and |byteidxcomp()| for getting the byte index
12186 from the UTF-16 index and |charidx()| for getting the
12187 character index from the UTF-16 index.
12188 Refer to |string-offset-encoding| for more information.
12189 Examples: >
12190 echo utf16idx('a😊😊', 3) returns 2
12191 echo utf16idx('a😊😊', 7) returns 4
12192 echo utf16idx('a😊😊', 1, 0, 1) returns 2
12193 echo utf16idx('a😊😊', 2, 0, 1) returns 4
12194 echo utf16idx('aą́c', 6) returns 2
12195 echo utf16idx('aą́c', 6, 1) returns 4
12196 echo utf16idx('a😊😊', 9) returns -1
12197<
12198 Can also be used as a |method|: >
12199 GetName()->utf16idx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012200<
12201 Return type: |Number|
Christian Brabandt67672ef2023-04-24 21:09:54 +010012202
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012203
12204values({dict}) *values()*
12205 Return a |List| with all the values of {dict}. The |List| is
12206 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010012207 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012208
12209 Can also be used as a |method|: >
12210 mydict->values()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012211<
12212 Return type: list<any>
12213
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012214
zeertzjq825cf812023-08-17 22:55:25 +020012215virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012216 The result is a Number, which is the screen column of the file
12217 position given with {expr}. That is, the last screen position
12218 occupied by the character at that position, when the screen
12219 would be of unlimited width. When there is a <Tab> at the
12220 position, the returned Number will be the column at the end of
12221 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
12222 set to 8, it returns 8. |conceal| is ignored.
12223 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010012224
zeertzjq02f3eba2024-06-12 20:45:24 +020012225 For the use of {expr} see |getpos()| and |col()|.
zeertzjqd353d272024-06-13 23:00:25 +080012226 When {expr} is "$", it means the end of the cursor line, so
12227 the result is the number of cells in the cursor line plus one.
LemonBoy0f7a3e12022-05-26 12:10:37 +010012228
12229 When 'virtualedit' is used {expr} can be [lnum, col, off],
12230 where "off" is the offset in screen columns from the start of
12231 the character. E.g., a position within a <Tab> or after the
12232 last character. When "off" is omitted zero is used. When
12233 Virtual editing is active in the current mode, a position
12234 beyond the end of the line can be returned. Also see
12235 |'virtualedit'|
12236
zeertzjq825cf812023-08-17 22:55:25 +020012237 If {list} is present and non-zero then virtcol() returns a
12238 List with the first and last screen position occupied by the
LemonBoy0f7a3e12022-05-26 12:10:37 +010012239 character.
12240
zeertzjq825cf812023-08-17 22:55:25 +020012241 With the optional {winid} argument the values are obtained for
12242 that window instead of the current window.
12243
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012244 Note that only marks in the current file can be used.
zeertzjq02f3eba2024-06-12 20:45:24 +020012245
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012246 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +010012247 " With text "foo^Lbar" and cursor on the "^L":
12248
12249 virtcol(".") " returns 5
12250 virtcol(".", 1) " returns [4, 5]
12251 virtcol("$") " returns 9
12252
12253 " With text " there", with 't at 'h':
12254
12255 virtcol("'t") " returns 6
zeertzjq02f3eba2024-06-12 20:45:24 +020012256<
12257 The first column is 1. 0 or [0, 0] is returned for an error.
12258
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012259 A more advanced example that echoes the maximum length of
12260 all lines: >
12261 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
12262
12263< Can also be used as a |method|: >
12264 GetPos()->virtcol()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012265<
12266 Return type: |Number|
12267
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012268
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012269virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
12270 The result is a Number, which is the byte index of the
12271 character in window {winid} at buffer line {lnum} and virtual
12272 column {col}.
12273
zeertzjqb583eda2023-10-14 11:32:28 +020012274 If buffer line {lnum} is an empty line, 0 is returned.
12275
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012276 If {col} is greater than the last virtual column in line
12277 {lnum}, then the byte index of the character at the last
12278 virtual column is returned.
12279
Yegappan Lakshmananb209b862023-08-15 23:01:44 +020012280 For a multi-byte character, the column number of the first
12281 byte in the character is returned.
12282
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012283 The {winid} argument can be the window number or the
12284 |window-ID|. If this is zero, then the current window is used.
12285
12286 Returns -1 if the window {winid} doesn't exist or the buffer
12287 line {lnum} or virtual column {col} is invalid.
12288
12289 See also |screenpos()|, |virtcol()| and |col()|.
12290
12291 Can also be used as a |method|: >
12292 GetWinid()->virtcol2col(lnum, col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012293<
12294 Return type: |Number|
12295
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012296
12297visualmode([{expr}]) *visualmode()*
12298 The result is a String, which describes the last Visual mode
12299 used in the current buffer. Initially it returns an empty
12300 string, but once Visual mode has been used, it returns "v",
12301 "V", or "<CTRL-V>" (a single CTRL-V character) for
12302 character-wise, line-wise, or block-wise Visual mode
12303 respectively.
12304 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012305 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012306< This enters the same Visual mode as before. It is also useful
12307 in scripts if you wish to act differently depending on the
12308 Visual mode that was used.
12309 If Visual mode is active, use |mode()| to get the Visual mode
12310 (e.g., in a |:vmap|).
12311 If {expr} is supplied and it evaluates to a non-zero Number or
12312 a non-empty String, then the Visual mode will be cleared and
12313 the old value is returned. See |non-zero-arg|.
12314
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012315 Return type: |String|
12316
12317
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012318wildmenumode() *wildmenumode()*
12319 Returns |TRUE| when the wildmenu is active and |FALSE|
12320 otherwise. See 'wildmenu' and 'wildmode'.
12321 This can be used in mappings to handle the 'wildcharm' option
12322 gracefully. (Makes only sense with |mapmode-c| mappings).
12323
12324 For example to make <c-j> work like <down> in wildmode, use: >
12325 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
12326<
Milly6c2fc372024-10-16 22:11:17 +020012327 (Note: this needs the 'wildcharm' option set appropriately).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012328
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012329 Return type: |Number|
12330
12331
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012332win_execute({id}, {command} [, {silent}]) *win_execute()*
12333 Like `execute()` but in the context of window {id}.
12334 The window will temporarily be made the current window,
12335 without triggering autocommands or changing directory. When
12336 executing {command} autocommands will be triggered, this may
Bram Moolenaarb7398fe2023-05-14 18:50:25 +010012337 have unexpected side effects. Use `:noautocmd` if needed.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012338 Example: >
12339 call win_execute(winid, 'set syntax=python')
12340< Doing the same with `setwinvar()` would not trigger
12341 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012342 *E994*
12343 Not all commands are allowed in popup windows.
12344 When window {id} does not exist then no error is given and
12345 an empty string is returned.
12346
12347 Can also be used as a |method|, the base is passed as the
12348 second argument: >
12349 GetCommand()->win_execute(winid)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012350<
12351 Return type: |String|
12352
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012353
12354win_findbuf({bufnr}) *win_findbuf()*
12355 Returns a |List| with |window-ID|s for windows that contain
12356 buffer {bufnr}. When there is none the list is empty.
12357
12358 Can also be used as a |method|: >
12359 GetBufnr()->win_findbuf()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012360<
12361 Return type: list<number> or list<any>
12362
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012363
12364win_getid([{win} [, {tab}]]) *win_getid()*
12365 Get the |window-ID| for the specified window.
12366 When {win} is missing use the current window.
12367 With {win} this is the window number. The top window has
12368 number 1.
12369 Without {tab} use the current tab, otherwise the tab with
12370 number {tab}. The first tab has number one.
12371 Return zero if the window cannot be found.
12372
12373 Can also be used as a |method|: >
12374 GetWinnr()->win_getid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012375<
12376 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012377
12378
12379win_gettype([{nr}]) *win_gettype()*
12380 Return the type of the window:
12381 "autocmd" autocommand window. Temporary window
12382 used to execute autocommands.
12383 "command" command-line window |cmdwin|
12384 (empty) normal window
12385 "loclist" |location-list-window|
12386 "popup" popup window |popup|
12387 "preview" preview window |preview-window|
12388 "quickfix" |quickfix-window|
12389 "unknown" window {nr} not found
12390
12391 When {nr} is omitted return the type of the current window.
12392 When {nr} is given return the type of this window by number or
12393 |window-ID|.
12394
12395 Also see the 'buftype' option. When running a terminal in a
12396 popup window then 'buftype' is "terminal" and win_gettype()
12397 returns "popup".
12398
12399 Can also be used as a |method|: >
12400 GetWinid()->win_gettype()
12401<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012402 Return type: |String|
12403
12404
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012405win_gotoid({expr}) *win_gotoid()*
12406 Go to window with ID {expr}. This may also change the current
12407 tabpage.
12408 Return TRUE if successful, FALSE if the window cannot be found.
12409
12410 Can also be used as a |method|: >
12411 GetWinid()->win_gotoid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012412<
12413 Return type: |Number|
12414
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012415
12416win_id2tabwin({expr}) *win_id2tabwin()*
12417 Return a list with the tab number and window number of window
12418 with ID {expr}: [tabnr, winnr].
12419 Return [0, 0] if the window cannot be found.
12420
12421 Can also be used as a |method|: >
12422 GetWinid()->win_id2tabwin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012423<
12424 Return type: list<number>
12425
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012426
12427win_id2win({expr}) *win_id2win()*
12428 Return the window number of window with ID {expr}.
12429 Return 0 if the window cannot be found in the current tabpage.
12430
12431 Can also be used as a |method|: >
12432 GetWinid()->win_id2win()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012433<
12434 Return type: |Number|
12435
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012436
Daniel Steinbergee630312022-01-10 13:36:34 +000012437win_move_separator({nr}, {offset}) *win_move_separator()*
12438 Move window {nr}'s vertical separator (i.e., the right border)
12439 by {offset} columns, as if being dragged by the mouse. {nr}
12440 can be a window number or |window-ID|. A positive {offset}
12441 moves right and a negative {offset} moves left. Moving a
12442 window's vertical separator will change the width of the
12443 window and the width of other windows adjacent to the vertical
12444 separator. The magnitude of movement may be smaller than
12445 specified (e.g., as a consequence of maintaining
12446 'winminwidth'). Returns TRUE if the window can be found and
12447 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010012448 This will fail for the rightmost window and a full-width
12449 window, since it has no separator on the right.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000012450 Only works for the current tab page. *E1308*
Daniel Steinbergee630312022-01-10 13:36:34 +000012451
12452 Can also be used as a |method|: >
12453 GetWinnr()->win_move_separator(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012454<
12455 Return type: |Number|
12456
Daniel Steinbergee630312022-01-10 13:36:34 +000012457
12458win_move_statusline({nr}, {offset}) *win_move_statusline()*
12459 Move window {nr}'s status line (i.e., the bottom border) by
12460 {offset} rows, as if being dragged by the mouse. {nr} can be a
12461 window number or |window-ID|. A positive {offset} moves down
12462 and a negative {offset} moves up. Moving a window's status
12463 line will change the height of the window and the height of
12464 other windows adjacent to the status line. The magnitude of
12465 movement may be smaller than specified (e.g., as a consequence
12466 of maintaining 'winminheight'). Returns TRUE if the window can
12467 be found and FALSE otherwise.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000012468 Only works for the current tab page.
Daniel Steinbergee630312022-01-10 13:36:34 +000012469
12470 Can also be used as a |method|: >
12471 GetWinnr()->win_move_statusline(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012472<
12473 Return type: |Number|
12474
Daniel Steinbergee630312022-01-10 13:36:34 +000012475
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012476win_screenpos({nr}) *win_screenpos()*
12477 Return the screen position of window {nr} as a list with two
12478 numbers: [row, col]. The first window always has position
12479 [1, 1], unless there is a tabline, then it is [2, 1].
12480 {nr} can be the window number or the |window-ID|. Use zero
12481 for the current window.
Sean Dewar5866bc32024-03-13 20:17:24 +010012482 Returns [0, 0] if the window cannot be found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012483
12484 Can also be used as a |method|: >
12485 GetWinid()->win_screenpos()
12486<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012487 Return type: list<number>
12488
12489
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012490win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
Sean Dewar96cc4ae2024-02-20 21:52:31 +010012491 Temporarily switch to window {target}, then move window {nr}
12492 to a new split adjacent to {target}.
12493 Unlike commands such as |:split|, no new windows are created
12494 (the |window-ID| of window {nr} is unchanged after the move).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012495
12496 Both {nr} and {target} can be window numbers or |window-ID|s.
12497 Both must be in the current tab page.
12498
12499 Returns zero for success, non-zero for failure.
12500
12501 {options} is a |Dictionary| with the following optional entries:
12502 "vertical" When TRUE, the split is created vertically,
12503 like with |:vsplit|.
12504 "rightbelow" When TRUE, the split is made below or to the
12505 right (if vertical). When FALSE, it is done
12506 above or to the left (if vertical). When not
12507 present, the values of 'splitbelow' and
12508 'splitright' are used.
12509
12510 Can also be used as a |method|: >
12511 GetWinid()->win_splitmove(target)
12512<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012513 Return type: |Number|
12514
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012515
12516 *winbufnr()*
12517winbufnr({nr}) The result is a Number, which is the number of the buffer
12518 associated with window {nr}. {nr} can be the window number or
12519 the |window-ID|.
12520 When {nr} is zero, the number of the buffer in the current
12521 window is returned.
12522 When window {nr} doesn't exist, -1 is returned.
12523 Example: >
12524 :echo "The file in the current window is " . bufname(winbufnr(0))
12525<
12526 Can also be used as a |method|: >
12527 FindWindow()->winbufnr()->bufname()
12528<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012529 Return type: |Number|
12530
12531
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012532 *wincol()*
12533wincol() The result is a Number, which is the virtual column of the
12534 cursor in the window. This is counting screen cells from the
12535 left side of the window. The leftmost column is one.
12536
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012537 Return type: |Number|
12538
12539
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012540 *windowsversion()*
12541windowsversion()
12542 The result is a String. For MS-Windows it indicates the OS
12543 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
12544 Windows XP is "5.1". For non-MS-Windows systems the result is
12545 an empty string.
12546
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012547 Return type: |String|
12548
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012549winheight({nr}) *winheight()*
12550 The result is a Number, which is the height of window {nr}.
12551 {nr} can be the window number or the |window-ID|.
12552 When {nr} is zero, the height of the current window is
12553 returned. When window {nr} doesn't exist, -1 is returned.
12554 An existing window always has a height of zero or more.
12555 This excludes any window toolbar line.
12556 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012557 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012558
12559< Can also be used as a |method|: >
12560 GetWinid()->winheight()
12561<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012562 Return type: |Number|
12563
12564
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012565winlayout([{tabnr}]) *winlayout()*
12566 The result is a nested List containing the layout of windows
12567 in a tabpage.
12568
12569 Without {tabnr} use the current tabpage, otherwise the tabpage
12570 with number {tabnr}. If the tabpage {tabnr} is not found,
12571 returns an empty list.
12572
12573 For a leaf window, it returns:
12574 ['leaf', {winid}]
12575 For horizontally split windows, which form a column, it
12576 returns:
12577 ['col', [{nested list of windows}]]
12578 For vertically split windows, which form a row, it returns:
12579 ['row', [{nested list of windows}]]
12580
12581 Example: >
12582 " Only one window in the tab page
12583 :echo winlayout()
12584 ['leaf', 1000]
12585 " Two horizontally split windows
12586 :echo winlayout()
12587 ['col', [['leaf', 1000], ['leaf', 1001]]]
12588 " The second tab page, with three horizontally split
12589 " windows, with two vertically split windows in the
12590 " middle window
12591 :echo winlayout(2)
12592 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
12593 ['leaf', 1001]]], ['leaf', 1000]]]
12594<
12595 Can also be used as a |method|: >
12596 GetTabnr()->winlayout()
12597<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012598 Return type: list<any>
12599
12600
12601winline() *winline()*
12602 The result is a Number, which is the screen line of the cursor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012603 in the window. This is counting screen lines from the top of
12604 the window. The first line is one.
12605 If the cursor was moved the view on the file will be updated
12606 first, this may cause a scroll.
12607
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012608 Return type: |Number|
12609
12610
12611winnr([{arg}]) *winnr()*
12612 The result is a Number, which is the number of the current
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012613 window. The top window has number 1.
12614 Returns zero for a popup window.
12615
12616 The optional argument {arg} supports the following values:
12617 $ the number of the last window (the window
12618 count).
12619 # the number of the last accessed window (where
12620 |CTRL-W_p| goes to). If there is no previous
12621 window or it is in another tab page 0 is
Sean Deward64801e2024-03-12 20:46:12 +010012622 returned. May refer to the current window in
12623 some cases (e.g. when evaluating 'statusline'
12624 expressions).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012625 {N}j the number of the Nth window below the
12626 current window (where |CTRL-W_j| goes to).
12627 {N}k the number of the Nth window above the current
12628 window (where |CTRL-W_k| goes to).
12629 {N}h the number of the Nth window left of the
12630 current window (where |CTRL-W_h| goes to).
12631 {N}l the number of the Nth window right of the
12632 current window (where |CTRL-W_l| goes to).
12633 The number can be used with |CTRL-W_w| and ":wincmd w"
12634 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010012635 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012636 Also see |tabpagewinnr()| and |win_getid()|.
12637 Examples: >
12638 let window_count = winnr('$')
12639 let prev_window = winnr('#')
12640 let wnum = winnr('3k')
12641
12642< Can also be used as a |method|: >
12643 GetWinval()->winnr()
12644<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012645 Return type: |Number|
12646
12647
12648winrestcmd() *winrestcmd()*
12649 Returns a sequence of |:resize| commands that should restore
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012650 the current window sizes. Only works properly when no windows
12651 are opened or closed and the current window and tab page is
12652 unchanged.
12653 Example: >
12654 :let cmd = winrestcmd()
12655 :call MessWithWindowSizes()
12656 :exe cmd
12657<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012658 Return type: |String|
12659
12660
12661winrestview({dict}) *winrestview()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012662 Uses the |Dictionary| returned by |winsaveview()| to restore
12663 the view of the current window.
12664 Note: The {dict} does not have to contain all values, that are
12665 returned by |winsaveview()|. If values are missing, those
12666 settings won't be restored. So you can use: >
12667 :call winrestview({'curswant': 4})
12668<
12669 This will only set the curswant value (the column the cursor
12670 wants to move on vertical movements) of the cursor to column 5
12671 (yes, that is 5), while all other settings will remain the
12672 same. This is useful, if you set the cursor position manually.
12673
12674 If you have changed the values the result is unpredictable.
12675 If the window size changed the result won't be the same.
12676
12677 Can also be used as a |method|: >
12678 GetView()->winrestview()
12679<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012680 Return type: |Number|
12681
12682
12683winsaveview() *winsaveview()*
12684 Returns a |Dictionary| that contains information to restore
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012685 the view of the current window. Use |winrestview()| to
12686 restore the view.
12687 This is useful if you have a mapping that jumps around in the
12688 buffer and you want to go back to the original view.
12689 This does not save fold information. Use the 'foldenable'
12690 option to temporarily switch off folding, so that folds are
12691 not opened when moving around. This may have side effects.
12692 The return value includes:
12693 lnum cursor line number
12694 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000012695 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012696 returns)
12697 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000012698 curswant column for vertical movement (Note:
12699 the first column is zero, as opposed
12700 to what |getcurpos()| returns). After
12701 |$| command it will be a very large
12702 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012703 topline first line in the window
12704 topfill filler lines, only in diff mode
12705 leftcol first column displayed; only used when
12706 'wrap' is off
12707 skipcol columns skipped
12708 Note that no option values are saved.
12709
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012710 Return type: dict<number>
12711
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012712
12713winwidth({nr}) *winwidth()*
12714 The result is a Number, which is the width of window {nr}.
12715 {nr} can be the window number or the |window-ID|.
12716 When {nr} is zero, the width of the current window is
12717 returned. When window {nr} doesn't exist, -1 is returned.
12718 An existing window always has a width of zero or more.
12719 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012720 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012721 :if winwidth(0) <= 50
12722 : 50 wincmd |
12723 :endif
12724< For getting the terminal or screen size, see the 'columns'
12725 option.
12726
12727 Can also be used as a |method|: >
12728 GetWinid()->winwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012729<
12730 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012731
12732
12733wordcount() *wordcount()*
12734 The result is a dictionary of byte/chars/word statistics for
12735 the current buffer. This is the same info as provided by
12736 |g_CTRL-G|
12737 The return value includes:
12738 bytes Number of bytes in the buffer
12739 chars Number of chars in the buffer
12740 words Number of words in the buffer
12741 cursor_bytes Number of bytes before cursor position
12742 (not in Visual mode)
12743 cursor_chars Number of chars before cursor position
12744 (not in Visual mode)
12745 cursor_words Number of words before cursor position
12746 (not in Visual mode)
12747 visual_bytes Number of bytes visually selected
12748 (only in Visual mode)
12749 visual_chars Number of chars visually selected
12750 (only in Visual mode)
12751 visual_words Number of words visually selected
12752 (only in Visual mode)
12753
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012754 Return type: dict<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012755
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012756
12757writefile({object}, {fname} [, {flags}]) *writefile()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012758 When {object} is a |List| write it to file {fname}. Each list
12759 item is separated with a NL. Each list item must be a String
12760 or Number.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012761 All NL characters are replaced with a NUL character.
12762 Inserting CR characters needs to be done before passing {list}
12763 to writefile().
Bram Moolenaar806a2732022-09-04 15:40:36 +010012764
12765 When {object} is a |Blob| write the bytes to file {fname}
12766 unmodified, also when binary mode is not specified.
12767
12768 {flags} must be a String. These characters are recognized:
12769
12770 'b' Binary mode is used: There will not be a NL after the
12771 last list item. An empty item at the end does cause the
12772 last line in the file to end in a NL.
12773
12774 'a' Append mode is used, lines are appended to the file: >
12775 :call writefile(["foo"], "event.log", "a")
12776 :call writefile(["bar"], "event.log", "a")
12777<
12778 'D' Delete the file when the current function ends. This
12779 works like: >
Bram Moolenaar938ae282023-02-20 20:44:55 +000012780 :defer delete({fname})
Bram Moolenaar806a2732022-09-04 15:40:36 +010012781< Fails when not in a function. Also see |:defer|.
12782
12783 's' fsync() is called after writing the file. This flushes
12784 the file to disk, if possible. This takes more time but
12785 avoids losing the file if the system crashes.
12786
12787 'S' fsync() is not called, even when 'fsync' is set.
12788
12789 When {flags} does not contain "S" or "s" then fsync() is
12790 called if the 'fsync' option is set.
12791
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012792 An existing file is overwritten, if possible.
Bram Moolenaar806a2732022-09-04 15:40:36 +010012793
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012794 When the write fails -1 is returned, otherwise 0. There is an
12795 error message if the file can't be created or when writing
12796 fails.
Bram Moolenaar806a2732022-09-04 15:40:36 +010012797
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012798 Also see |readfile()|.
12799 To copy a file byte for byte: >
12800 :let fl = readfile("foo", "b")
12801 :call writefile(fl, "foocopy", "b")
12802
12803< Can also be used as a |method|: >
12804 GetText()->writefile("thefile")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012805<
12806 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012807
12808
12809xor({expr}, {expr}) *xor()*
12810 Bitwise XOR on the two arguments. The arguments are converted
12811 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012812 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012813 Example: >
12814 :let bits = xor(bits, 0x80)
12815<
12816 Can also be used as a |method|: >
12817 :let bits = bits->xor(0x80)
12818<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012819 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012820
12821==============================================================================
128223. Feature list *feature-list*
12823
12824There are three types of features:
128251. Features that are only supported when they have been enabled when Vim
12826 was compiled |+feature-list|. Example: >
12827 :if has("cindent")
12828< *gui_running*
128292. Features that are only supported when certain conditions have been met.
12830 Example: >
12831 :if has("gui_running")
12832< *has-patch*
128333. Beyond a certain version or at a certain version and including a specific
12834 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
12835 later, or it is version 7.4 and patch 248 was included. Example: >
12836 :if has("patch-7.4.248")
12837< Note that it's possible for patch 248 to be omitted even though 249 is
12838 included. Only happens when cherry-picking patches.
12839 Note that this form only works for patch 7.4.237 and later, before that
12840 you need to check for the patch and the v:version. Example (checking
12841 version 6.2.148 or later): >
12842 :if v:version > 602 || (v:version == 602 && has("patch148"))
12843
12844Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
12845use: `if exists('+shellslash')`
12846
12847
12848acl Compiled with |ACL| support.
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010012849all_builtin_terms Compiled with all builtin terminals enabled. (always
12850 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012851amiga Amiga version of Vim.
12852arabic Compiled with Arabic support |Arabic|.
12853arp Compiled with ARP support (Amiga).
12854autocmd Compiled with autocommand support. (always true)
12855autochdir Compiled with support for 'autochdir'
12856autoservername Automatically enable |clientserver|
12857balloon_eval Compiled with |balloon-eval| support.
12858balloon_multiline GUI supports multiline balloons.
12859beos BeOS version of Vim.
12860browse Compiled with |:browse| support, and browse() will
12861 work.
12862browsefilter Compiled with support for |browsefilter|.
12863bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010012864builtin_terms Compiled with some builtin terminals. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012865byte_offset Compiled with support for 'o' in 'statusline'
12866channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012867cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012868clientserver Compiled with remote invocation support |clientserver|.
12869clipboard Compiled with 'clipboard' support.
12870clipboard_working Compiled with 'clipboard' support and it can be used.
12871cmdline_compl Compiled with |cmdline-completion| support.
12872cmdline_hist Compiled with |cmdline-history| support.
12873cmdline_info Compiled with 'showcmd' and 'ruler' support.
12874comments Compiled with |'comments'| support.
12875compatible Compiled to be very Vi compatible.
12876conpty Platform where |ConPTY| can be used.
12877cryptv Compiled with encryption support |encryption|.
12878cscope Compiled with |cscope| support.
12879cursorbind Compiled with |'cursorbind'| (always true)
12880debug Compiled with "DEBUG" defined.
12881dialog_con Compiled with console dialog support.
glepnirdf461152024-04-04 22:23:29 +020012882dialog_con_gui Compiled with console and GUI dialog support.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012883dialog_gui Compiled with GUI dialog support.
12884diff Compiled with |vimdiff| and 'diff' support.
12885digraphs Compiled with support for digraphs.
12886directx Compiled with support for DirectX and 'renderoptions'.
12887dnd Compiled with support for the "~ register |quote_~|.
12888drop_file Compiled with |drop_file| support.
12889ebcdic Compiled on a machine with ebcdic character set.
12890emacs_tags Compiled with support for Emacs tags.
12891eval Compiled with expression evaluation support. Always
12892 true, of course!
12893ex_extra |+ex_extra| (always true)
12894extra_search Compiled with support for |'incsearch'| and
12895 |'hlsearch'|
12896farsi Support for Farsi was removed |farsi|.
Bram Moolenaarf80f40a2022-08-25 16:02:23 +010012897file_in_path Compiled with support for |gf| and |<cfile>| (always
12898 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012899filterpipe When 'shelltemp' is off pipes are used for shell
12900 read/write/filter commands
12901find_in_path Compiled with support for include file searches
12902 |+find_in_path|.
12903float Compiled with support for |Float|.
12904fname_case Case in file names matters (for Amiga and MS-Windows
12905 this is not present).
12906folding Compiled with |folding| support.
12907footer Compiled with GUI footer support. |gui-footer|
12908fork Compiled to use fork()/exec() instead of system().
12909gettext Compiled with message translation |multi-lang|
12910gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010012911gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012912gui_gnome Compiled with Gnome support (gui_gtk is also defined).
12913gui_gtk Compiled with GTK+ GUI (any version).
12914gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
12915gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
12916gui_haiku Compiled with Haiku GUI.
12917gui_mac Compiled with Macintosh GUI.
12918gui_motif Compiled with Motif GUI.
12919gui_photon Compiled with Photon GUI.
12920gui_running Vim is running in the GUI, or it will start soon.
12921gui_win32 Compiled with MS-Windows Win32 GUI.
12922gui_win32s idem, and Win32s system being used (Windows 3.1)
12923haiku Haiku version of Vim.
12924hangul_input Compiled with Hangul input support. |hangul|
12925hpux HP-UX version of Vim.
Zhaoming Luoa41dfcd2025-02-06 21:39:35 +010012926hurd GNU/Hurd version of Vim
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012927iconv Can use iconv() for conversion.
12928insert_expand Compiled with support for CTRL-X expansion commands in
12929 Insert mode. (always true)
12930job Compiled with support for |channel| and |job|
12931ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012932jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012933keymap Compiled with 'keymap' support.
12934lambda Compiled with |lambda| support.
12935langmap Compiled with 'langmap' support.
12936libcall Compiled with |libcall()| support.
12937linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
12938 'breakindent' support.
12939linux Linux version of Vim.
12940lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012941 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012942listcmds Compiled with commands for the buffer list |:files|
12943 and the argument list |arglist|.
12944localmap Compiled with local mappings and abbr. |:map-local|
12945lua Compiled with Lua interface |Lua|.
12946mac Any Macintosh version of Vim cf. osx
12947macunix Synonym for osxdarwin
12948menu Compiled with support for |:menu|.
12949mksession Compiled with support for |:mksession|.
12950modify_fname Compiled with file name modifiers. |filename-modifiers|
12951 (always true)
12952mouse Compiled with support for mouse.
12953mouse_dec Compiled with support for Dec terminal mouse.
12954mouse_gpm Compiled with support for gpm (Linux console mouse)
12955mouse_gpm_enabled GPM mouse is working
12956mouse_netterm Compiled with support for netterm mouse.
12957mouse_pterm Compiled with support for qnx pterm mouse.
12958mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
12959mouse_sgr Compiled with support for sgr mouse.
12960mouse_urxvt Compiled with support for urxvt mouse.
12961mouse_xterm Compiled with support for xterm mouse.
12962mouseshape Compiled with support for 'mouseshape'.
12963multi_byte Compiled with support for 'encoding' (always true)
12964multi_byte_encoding 'encoding' is set to a multibyte encoding.
12965multi_byte_ime Compiled with support for IME input method.
12966multi_lang Compiled with support for multiple languages.
12967mzscheme Compiled with MzScheme interface |mzscheme|.
12968nanotime Compiled with sub-second time stamp checks.
12969netbeans_enabled Compiled with support for |netbeans| and connected.
12970netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012971num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012972ole Compiled with OLE automation support for Win32.
12973osx Compiled for macOS cf. mac
12974osxdarwin Compiled for macOS, with |mac-darwin-feature|
12975packages Compiled with |packages| support.
12976path_extra Compiled with up/downwards search in 'path' and 'tags'
12977perl Compiled with Perl interface.
12978persistent_undo Compiled with support for persistent undo history.
12979postscript Compiled with PostScript file printing.
12980printer Compiled with |:hardcopy| support.
12981profile Compiled with |:profile| support.
Bram Moolenaar71badf92023-04-22 22:40:14 +010012982prof_nsec Profile results are in nanoseconds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012983python Python 2.x interface available. |has-python|
12984python_compiled Compiled with Python 2.x interface. |has-python|
12985python_dynamic Python 2.x interface is dynamically loaded. |has-python|
12986python3 Python 3.x interface available. |has-python|
12987python3_compiled Compiled with Python 3.x interface. |has-python|
12988python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Yee Cheng Chinc13b3d12023-08-20 21:18:38 +020012989python3_stable Python 3.x interface is using Python Stable ABI. |has-python|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012990pythonx Python 2.x and/or 3.x interface available. |python_x|
12991qnx QNX version of Vim.
12992quickfix Compiled with |quickfix| support.
12993reltime Compiled with |reltime()| support.
12994rightleft Compiled with 'rightleft' support.
12995ruby Compiled with Ruby interface |ruby|.
12996scrollbind Compiled with 'scrollbind' support. (always true)
12997showcmd Compiled with 'showcmd' support.
12998signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012999smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013000sodium Compiled with libsodium for better crypt support
13001sound Compiled with sound support, e.g. `sound_playevent()`
13002spell Compiled with spell checking support |spell|.
13003startuptime Compiled with |--startuptime| support.
13004statusline Compiled with support for 'statusline', 'rulerformat'
13005 and special formats of 'titlestring' and 'iconstring'.
13006sun SunOS version of Vim.
13007sun_workshop Support for Sun |workshop| has been removed.
13008syntax Compiled with syntax highlighting support |syntax|.
13009syntax_items There are active syntax highlighting items for the
13010 current buffer.
13011system Compiled to use system() instead of fork()/exec().
13012tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010013013 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013014tag_old_static Support for old static tags was removed, see
13015 |tag-old-static|.
13016tcl Compiled with Tcl interface.
13017termguicolors Compiled with true color in terminal support.
13018terminal Compiled with |terminal| support.
13019terminfo Compiled with terminfo instead of termcap.
13020termresponse Compiled with support for |t_RV| and |v:termresponse|.
13021textobjects Compiled with support for |text-objects|.
13022textprop Compiled with support for |text-properties|.
13023tgetent Compiled with tgetent support, able to use a termcap
13024 or terminfo file.
13025timers Compiled with |timer_start()| support.
13026title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010013027 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013028toolbar Compiled with support for |gui-toolbar|.
13029ttyin input is a terminal (tty)
13030ttyout output is a terminal (tty)
13031unix Unix version of Vim. *+unix*
13032unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
13033user_commands User-defined commands. (always true)
13034vartabs Compiled with variable tabstop support |'vartabstop'|.
13035vcon Win32: Virtual console support is working, can use
13036 'termguicolors'. Also see |+vtp|.
13037vertsplit Compiled with vertically split windows |:vsplit|.
13038 (always true)
13039vim_starting True while initial source'ing takes place. |startup|
13040 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000013041vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013042viminfo Compiled with viminfo support.
13043vimscript-1 Compiled Vim script version 1 support
13044vimscript-2 Compiled Vim script version 2 support
13045vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010013046vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013047virtualedit Compiled with 'virtualedit' option. (always true)
13048visual Compiled with Visual mode. (always true)
13049visualextra Compiled with extra Visual mode commands. (always
13050 true) |blockwise-operators|.
13051vms VMS version of Vim.
13052vreplace Compiled with |gR| and |gr| commands. (always true)
13053vtp Compiled for vcon support |+vtp| (check vcon to find
13054 out if it works in the current console).
Foxe Chenb90c2392025-06-27 21:10:35 +020013055wayland Compiled with Wayland protocol support.
Hirohito Higashi73b96502025-06-28 18:18:21 +020013056wayland_clipboard Compiled with support for Wayland selections/clipboard
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013057wildignore Compiled with 'wildignore' option.
13058wildmenu Compiled with 'wildmenu' option.
13059win16 old version for MS-Windows 3.1 (always false)
13060win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
13061 64 bits)
13062win32unix Win32 version of Vim, using Unix files (Cygwin)
13063win64 Win64 version of Vim (MS-Windows 64 bit).
13064win95 Win32 version for MS-Windows 95/98/ME (always false)
13065winaltkeys Compiled with 'winaltkeys' option.
13066windows Compiled with support for more than one window.
13067 (always true)
13068writebackup Compiled with 'writebackup' default on.
Christian Brabandte085dfd2023-09-30 12:49:18 +020013069xattr Compiled with extended attributes support |xattr|
13070 (currently only supported on Linux).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013071xfontset Compiled with X fontset support |xfontset|.
13072xim Compiled with X input method support |xim|.
13073xpm Compiled with pixmap support.
13074xpm_w32 Compiled with pixmap support for Win32. (Only for
13075 backward compatibility. Use "xpm" instead.)
13076xsmp Compiled with X session management support.
13077xsmp_interact Compiled with interactive X session management support.
13078xterm_clipboard Compiled with support for xterm clipboard.
13079xterm_save Compiled with support for saving and restoring the
13080 xterm screen.
13081x11 Compiled with X11 support.
13082
13083
13084==============================================================================
130854. Matching a pattern in a String *string-match*
13086
13087This is common between several functions. A regexp pattern as explained at
13088|pattern| is normally used to find a match in the buffer lines. When a
13089pattern is used to find a match in a String, almost everything works in the
13090same way. The difference is that a String is handled like it is one line.
13091When it contains a "\n" character, this is not seen as a line break for the
13092pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
13093>
13094 :let a = "aaaa\nxxxx"
13095 :echo matchstr(a, "..\n..")
13096 aa
13097 xx
13098 :echo matchstr(a, "a.x")
13099 a
13100 x
13101
13102Don't forget that "^" will only match at the first character of the String and
13103"$" at the last character of the string. They don't match after or before a
13104"\n".
13105
13106 vim:tw=78:ts=8:noet:ft=help:norl: