blob: af918d1a95955bb004836054fcbcd89a9c7403d2 [file] [log] [blame]
Christian Brabandtd657d3d2024-09-10 21:55:49 +02001*builtin.txt* For Vim version 9.1. Last change: 2024 Sep 10
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Builtin functions *builtin-functions*
8
Bram Moolenaarf269eab2022-10-03 18:04:35 +01009Note: Expression evaluation can be disabled at compile time, the builtin
10functions are not available then. See |+eval| and |no-eval-feature|.
11
12For functions grouped by what they are used for see |function-list|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013
141. Overview |builtin-function-list|
152. Details |builtin-function-details|
163. Feature list |feature-list|
174. Matching a pattern in a String |string-match|
18
19==============================================================================
201. Overview *builtin-function-list*
21
22Use CTRL-] on the function name to jump to the full explanation.
23
24USAGE RESULT DESCRIPTION ~
25
26abs({expr}) Float or Number absolute value of {expr}
27acos({expr}) Float arc cosine of {expr}
28add({object}, {item}) List/Blob append {item} to {object}
29and({expr}, {expr}) Number bitwise AND
30append({lnum}, {text}) Number append {text} below line {lnum}
erraelf0837ba2024-06-24 12:27:01 -070031appendbufline({buf}, {lnum}, {text})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000032 Number append {text} below line {lnum}
erraelf0837ba2024-06-24 12:27:01 -070033 in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000034argc([{winid}]) Number number of files in the argument list
35argidx() Number current index in the argument list
36arglistid([{winnr} [, {tabnr}]]) Number argument list id
37argv({nr} [, {winid}]) String {nr} entry of the argument list
38argv([-1, {winid}]) List the argument list
39asin({expr}) Float arc sine of {expr}
40assert_beeps({cmd}) Number assert {cmd} causes a beep
41assert_equal({exp}, {act} [, {msg}])
42 Number assert {exp} is equal to {act}
43assert_equalfile({fname-one}, {fname-two} [, {msg}])
44 Number assert file contents are equal
45assert_exception({error} [, {msg}])
46 Number assert {error} is in v:exception
47assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])
48 Number assert {cmd} fails
49assert_false({actual} [, {msg}])
50 Number assert {actual} is false
51assert_inrange({lower}, {upper}, {actual} [, {msg}])
52 Number assert {actual} is inside the range
53assert_match({pat}, {text} [, {msg}])
54 Number assert {pat} matches {text}
55assert_nobeep({cmd}) Number assert {cmd} does not cause a beep
56assert_notequal({exp}, {act} [, {msg}])
57 Number assert {exp} is not equal {act}
58assert_notmatch({pat}, {text} [, {msg}])
59 Number assert {pat} not matches {text}
60assert_report({msg}) Number report a test failure
61assert_true({actual} [, {msg}]) Number assert {actual} is true
62atan({expr}) Float arc tangent of {expr}
63atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +010064autocmd_add({acmds}) Bool add a list of autocmds and groups
65autocmd_delete({acmds}) Bool delete a list of autocmds and groups
66autocmd_get([{opts}]) List return a list of autocmds
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000067balloon_gettext() String current text in the balloon
68balloon_show({expr}) none show {expr} inside the balloon
69balloon_split({msg}) List split {msg} as used for a balloon
Christ van Willegence0ef912024-06-20 23:41:59 +020070bindtextdomain({package}, {path})
Christ van Willegen8252ef12024-07-11 21:36:21 +020071 Bool bind text domain to specified path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000072blob2list({blob}) List convert {blob} into a list of numbers
73browse({save}, {title}, {initdir}, {default})
74 String put up a file requester
75browsedir({title}, {initdir}) String put up a directory requester
76bufadd({name}) Number add a buffer to the buffer list
77bufexists({buf}) Number |TRUE| if buffer {buf} exists
78buflisted({buf}) Number |TRUE| if buffer {buf} is listed
79bufload({buf}) Number load buffer {buf} if not loaded yet
80bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
81bufname([{buf}]) String Name of the buffer {buf}
82bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
83bufwinid({buf}) Number window ID of buffer {buf}
84bufwinnr({buf}) Number window number of buffer {buf}
85byte2line({byte}) Number line number at byte count {byte}
Christian Brabandt67672ef2023-04-24 21:09:54 +010086byteidx({expr}, {nr} [, {utf16}])
87 Number byte index of {nr}'th char in {expr}
88byteidxcomp({expr}, {nr} [, {utf16}])
89 Number byte index of {nr}'th char in {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000090call({func}, {arglist} [, {dict}])
91 any call {func} with arguments {arglist}
92ceil({expr}) Float round {expr} up
93ch_canread({handle}) Number check if there is something to read
94ch_close({handle}) none close {handle}
95ch_close_in({handle}) none close in part of {handle}
96ch_evalexpr({handle}, {expr} [, {options}])
97 any evaluate {expr} on JSON {handle}
98ch_evalraw({handle}, {string} [, {options}])
99 any evaluate {string} on raw {handle}
100ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
101ch_getjob({channel}) Job get the Job of {channel}
102ch_info({handle}) String info about channel {handle}
103ch_log({msg} [, {handle}]) none write {msg} in the channel log file
104ch_logfile({fname} [, {mode}]) none start logging channel activity
105ch_open({address} [, {options}])
106 Channel open a channel to {address}
107ch_read({handle} [, {options}]) String read from {handle}
108ch_readblob({handle} [, {options}])
109 Blob read Blob from {handle}
110ch_readraw({handle} [, {options}])
111 String read raw from {handle}
112ch_sendexpr({handle}, {expr} [, {options}])
113 any send {expr} over JSON {handle}
114ch_sendraw({handle}, {expr} [, {options}])
115 any send {expr} over raw {handle}
116ch_setoptions({handle}, {options})
117 none set options for {handle}
118ch_status({handle} [, {options}])
119 String status of channel {handle}
120changenr() Number current change number
121char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
122charclass({string}) Number character class of {string}
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000123charcol({expr} [, {winid}]) Number column number of cursor or mark
Christian Brabandt67672ef2023-04-24 21:09:54 +0100124charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000125 Number char index of byte {idx} in {string}
126chdir({dir}) String change current working directory
127cindent({lnum}) Number C indent for line {lnum}
128clearmatches([{win}]) none clear all matches
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000129col({expr} [, {winid}]) Number column byte index of cursor or mark
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000130complete({startcol}, {matches}) none set Insert mode completion
131complete_add({expr}) Number add completion match
132complete_check() Number check for key typed during completion
133complete_info([{what}]) Dict get current completion information
134confirm({msg} [, {choices} [, {default} [, {type}]]])
135 Number number of choice picked by user
136copy({expr}) any make a shallow copy of {expr}
137cos({expr}) Float cosine of {expr}
138cosh({expr}) Float hyperbolic cosine of {expr}
139count({comp}, {expr} [, {ic} [, {start}]])
140 Number count how many {expr} are in {comp}
141cscope_connection([{num}, {dbpath} [, {prepend}]])
142 Number checks existence of cscope connection
143cursor({lnum}, {col} [, {off}])
144 Number move cursor to {lnum}, {col}, {off}
145cursor({list}) Number move cursor to position in {list}
146debugbreak({pid}) Number interrupt process being debugged
147deepcopy({expr} [, {noref}]) any make a full copy of {expr}
148delete({fname} [, {flags}]) Number delete the file or directory {fname}
149deletebufline({buf}, {first} [, {last}])
150 Number delete lines from buffer {buf}
151did_filetype() Number |TRUE| if FileType autocmd event used
Yegappan Lakshmananfa378352024-02-01 22:05:27 +0100152diff({fromlist}, {tolist} [, {options}])
153 List diff two Lists of strings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000154diff_filler({lnum}) Number diff filler lines about {lnum}
155diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
156digraph_get({chars}) String get the |digraph| of {chars}
157digraph_getlist([{listall}]) List get all |digraph|s
Christian Brabandtfbc37f12024-06-18 20:50:58 +0200158digraph_set({chars}, {digraph}) Bool register |digraph|
159digraph_setlist({digraphlist}) Bool register multiple |digraph|s
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000160echoraw({expr}) none output {expr} as-is
161empty({expr}) Number |TRUE| if {expr} is empty
162environ() Dict return environment variables
Sean Dewarb0efa492023-07-08 10:35:19 +0100163err_teapot([{expr}]) none give E418, or E503 if {expr} is |TRUE|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000164escape({string}, {chars}) String escape {chars} in {string} with '\'
165eval({string}) any evaluate {string} into its value
166eventhandler() Number |TRUE| if inside an event handler
167executable({expr}) Number 1 if executable {expr} exists
168execute({command}) String execute {command} and get the output
169exepath({expr}) String full path of the command {expr}
170exists({expr}) Number |TRUE| if {expr} exists
171exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
172exp({expr}) Float exponential of {expr}
173expand({expr} [, {nosuf} [, {list}]])
174 any expand special keywords in {expr}
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +0100175expandcmd({string} [, {options}])
176 String expand {string} like with `:edit`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000177extend({expr1}, {expr2} [, {expr3}])
178 List/Dict insert items of {expr2} into {expr1}
179extendnew({expr1}, {expr2} [, {expr3}])
180 List/Dict like |extend()| but creates a new
181 List or Dictionary
182feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Shougo Matsushita60c87432024-06-03 22:59:27 +0200183filecopy({from}, {to}) Number |TRUE| if copying file {from} to {to}
184 worked
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000185filereadable({file}) Number |TRUE| if {file} is a readable file
186filewritable({file}) Number |TRUE| if {file} is a writable file
187filter({expr1}, {expr2}) List/Dict/Blob/String
188 remove items from {expr1} where
189 {expr2} is 0
190finddir({name} [, {path} [, {count}]])
191 String find directory {name} in {path}
192findfile({name} [, {path} [, {count}]])
193 String find file {name} in {path}
194flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
195flattennew({list} [, {maxdepth}])
196 List flatten a copy of {list}
197float2nr({expr}) Number convert Float {expr} to a Number
198floor({expr}) Float round {expr} down
199fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
200fnameescape({fname}) String escape special characters in {fname}
201fnamemodify({fname}, {mods}) String modify file name
202foldclosed({lnum}) Number first line of fold at {lnum} if closed
203foldclosedend({lnum}) Number last line of fold at {lnum} if closed
204foldlevel({lnum}) Number fold level at {lnum}
205foldtext() String line displayed for closed fold
206foldtextresult({lnum}) String text for closed fold at {lnum}
Ernie Raele79e2072024-01-13 11:47:33 +0100207foreach({expr1}, {expr2}) List/Dict/Blob/String
208 for each item in {expr1} call {expr2}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000209foreground() Number bring the Vim window to the foreground
Bram Moolenaaraa534142022-09-15 21:46:02 +0100210fullcommand({name} [, {vim9}]) String get full command from {name}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000211funcref({name} [, {arglist}] [, {dict}])
212 Funcref reference to function {name}
213function({name} [, {arglist}] [, {dict}])
214 Funcref named reference to function {name}
215garbagecollect([{atexit}]) none free memory, breaking cyclic references
216get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
217get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
218get({func}, {what}) any get property of funcref/partial {func}
219getbufinfo([{buf}]) List information about buffers
220getbufline({buf}, {lnum} [, {end}])
221 List lines {lnum} to {end} of buffer {buf}
Bram Moolenaarce30ccc2022-11-21 19:57:04 +0000222getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000223getbufvar({buf}, {varname} [, {def}])
224 any variable {varname} in buffer {buf}
Kota Kato66bb9ae2023-01-17 18:31:56 +0000225getcellwidths() List get character cell width overrides
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000226getchangelist([{buf}]) List list of change list items
Doug Kearns9cd9e752024-04-07 17:42:17 +0200227getchar([{expr}]) Number or String
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000228 get one character from the user
229getcharmod() Number modifiers for the last typed character
230getcharpos({expr}) List position of cursor, mark, etc.
231getcharsearch() Dict last character search
Doug Kearns9cd9e752024-04-07 17:42:17 +0200232getcharstr([{expr}]) String get one character from the user
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100233getcmdcompltype() String return the type of the current
234 command-line completion
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000235getcmdline() String return the current command-line
236getcmdpos() Number return cursor position in command-line
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100237getcmdscreenpos() Number return cursor screen position in
238 command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000239getcmdtype() String return current command-line type
240getcmdwintype() String return current command-line window type
241getcompletion({pat}, {type} [, {filtered}])
242 List list of cmdline completion matches
243getcurpos([{winnr}]) List position of the cursor
244getcursorcharpos([{winnr}]) List character position of the cursor
245getcwd([{winnr} [, {tabnr}]]) String get the current working directory
246getenv({name}) String return environment variable
247getfontname([{name}]) String name of font being used
248getfperm({fname}) String file permissions of file {fname}
249getfsize({fname}) Number size in bytes of file {fname}
250getftime({fname}) Number last modification time of file
251getftype({fname}) String description of type of file {fname}
252getimstatus() Number |TRUE| if the IME status is active
253getjumplist([{winnr} [, {tabnr}]])
254 List list of jump list items
255getline({lnum}) String line {lnum} of current buffer
256getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
257getloclist({nr}) List list of location list items
258getloclist({nr}, {what}) Dict get specific location list properties
259getmarklist([{buf}]) List list of global/local marks
260getmatches([{win}]) List list of current matches
261getmousepos() Dict last known mouse position
Bram Moolenaar24dc19c2022-11-14 19:49:15 +0000262getmouseshape() String current mouse shape name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000263getpid() Number process ID of Vim
264getpos({expr}) List position of cursor, mark, etc.
265getqflist() List list of quickfix items
266getqflist({what}) Dict get specific quickfix list properties
267getreg([{regname} [, 1 [, {list}]]])
268 String or List contents of a register
269getreginfo([{regname}]) Dict information about a register
Shougo Matsushita19b71882024-02-28 22:48:12 +0100270getregion({pos1}, {pos2} [, {opts}])
Shougo Matsushita3f905ab2024-02-21 00:02:45 +0100271 List get the text from {pos1} to {pos2}
Shougo Matsushitab4757e62024-05-07 20:49:24 +0200272getregionpos({pos1}, {pos2} [, {opts}])
273 List get a list of positions for a region
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000274getregtype([{regname}]) String type of a register
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +0100275getscriptinfo([{opts}]) List list of sourced scripts
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000276gettabinfo([{expr}]) List list of tab pages
277gettabvar({nr}, {varname} [, {def}])
278 any variable {varname} in tab {nr} or {def}
279gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
280 any {name} in {winnr} in tab page {tabnr}
281gettagstack([{nr}]) Dict get the tag stack of window {nr}
h-east52e7cc22024-07-28 17:03:29 +0200282gettext({text} [, {package}]) String lookup translation of {text}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000283getwininfo([{winid}]) List list of info about each window
Bram Moolenaar938ae282023-02-20 20:44:55 +0000284getwinpos([{timeout}]) List X and Y coord in pixels of Vim window
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000285getwinposx() Number X coord in pixels of the Vim window
286getwinposy() Number Y coord in pixels of the Vim window
287getwinvar({nr}, {varname} [, {def}])
288 any variable {varname} in window {nr}
289glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
290 any expand file wildcards in {expr}
291glob2regpat({expr}) String convert a glob pat into a search pat
292globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
293 String do glob({expr}) for all dirs in {path}
294has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
295has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
296haslocaldir([{winnr} [, {tabnr}]])
297 Number |TRUE| if the window executed |:lcd|
298 or |:tcd|
299hasmapto({what} [, {mode} [, {abbr}]])
300 Number |TRUE| if mapping to {what} exists
301histadd({history}, {item}) Number add an item to a history
302histdel({history} [, {item}]) Number remove an item from a history
303histget({history} [, {index}]) String get the item {index} from a history
304histnr({history}) Number highest index of a history
305hlID({name}) Number syntax ID of highlight group {name}
306hlexists({name}) Number |TRUE| if highlight group {name} exists
307hlget([{name} [, {resolve}]]) List get highlight group attributes
308hlset({list}) Number set highlight group attributes
309hostname() String name of the machine Vim is running on
310iconv({expr}, {from}, {to}) String convert encoding of {expr}
Ernie Rael05124252024-07-11 22:10:45 +0200311id({item}) String get unique identity string of item
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000312indent({lnum}) Number indent of line {lnum}
313index({object}, {expr} [, {start} [, {ic}]])
314 Number index in {object} where {expr} appears
Yegappan Lakshmananb2186552022-08-13 13:09:20 +0100315indexof({object}, {expr} [, {opts}]])
316 Number index in {object} where {expr} is true
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000317input({prompt} [, {text} [, {completion}]])
318 String get input from the user
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100319inputdialog({prompt} [, {text} [, {cancelreturn}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000320 String like input() but in a GUI dialog
321inputlist({textlist}) Number let the user pick from a choice list
322inputrestore() Number restore typeahead
323inputsave() Number save and clear typeahead
324inputsecret({prompt} [, {text}]) String like input() but hiding the text
325insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
LemonBoyafe04662023-08-23 21:08:11 +0200326instanceof({object}, {class}) Number |TRUE| if {object} is an instance of {class}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000327interrupt() none interrupt script execution
328invert({expr}) Number bitwise invert
LemonBoydca1d402022-04-28 15:26:33 +0100329isabsolutepath({path}) Number |TRUE| if {path} is an absolute path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000330isdirectory({directory}) Number |TRUE| if {directory} is a directory
331isinf({expr}) Number determine if {expr} is infinity value
332 (positive or negative)
333islocked({expr}) Number |TRUE| if {expr} is locked
334isnan({expr}) Number |TRUE| if {expr} is NaN
335items({dict}) List key-value pairs in {dict}
336job_getchannel({job}) Channel get the channel handle for {job}
337job_info([{job}]) Dict get information about {job}
338job_setoptions({job}, {options}) none set options for {job}
339job_start({command} [, {options}])
340 Job start a job
341job_status({job}) String get the status of {job}
342job_stop({job} [, {how}]) Number stop {job}
343join({list} [, {sep}]) String join {list} items into one String
344js_decode({string}) any decode JS style JSON
345js_encode({expr}) String encode JS style JSON
346json_decode({string}) any decode JSON
347json_encode({expr}) String encode JSON
348keys({dict}) List keys in {dict}
zeertzjqcdc83932022-09-12 13:38:41 +0100349keytrans({string}) String translate internal keycodes to a form
350 that can be used by |:map|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000351len({expr}) Number the length of {expr}
352libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
353libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
354line({expr} [, {winid}]) Number line nr of cursor, last line or mark
355line2byte({lnum}) Number byte count of line {lnum}
356lispindent({lnum}) Number Lisp indent for line {lnum}
357list2blob({list}) Blob turn {list} of numbers into a Blob
358list2str({list} [, {utf8}]) String turn {list} of numbers into a String
359listener_add({callback} [, {buf}])
360 Number add a callback to listen to changes
361listener_flush([{buf}]) none invoke listener callbacks
362listener_remove({id}) none remove a listener callback
363localtime() Number current time
364log({expr}) Float natural logarithm (base e) of {expr}
365log10({expr}) Float logarithm of Float {expr} to base 10
366luaeval({expr} [, {expr}]) any evaluate |Lua| expression
367map({expr1}, {expr2}) List/Dict/Blob/String
368 change each item in {expr1} to {expr2}
369maparg({name} [, {mode} [, {abbr} [, {dict}]]])
370 String or Dict
371 rhs of mapping {name} in mode {mode}
372mapcheck({name} [, {mode} [, {abbr}]])
373 String check for mappings matching {name}
Ernie Rael09661202022-04-25 14:40:44 +0100374maplist([{abbr}]) List list of all mappings, a dict for each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000375mapnew({expr1}, {expr2}) List/Dict/Blob/String
376 like |map()| but creates a new List or
377 Dictionary
378mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
379match({expr}, {pat} [, {start} [, {count}]])
380 Number position where {pat} matches in {expr}
381matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
382 Number highlight {pattern} with {group}
383matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
384 Number highlight positions with {group}
385matcharg({nr}) List arguments of |:match|
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100386matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict})
387 List all the {pat} matches in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000388matchdelete({id} [, {win}]) Number delete match identified by {id}
389matchend({expr}, {pat} [, {start} [, {count}]])
390 Number position where {pat} ends in {expr}
391matchfuzzy({list}, {str} [, {dict}])
392 List fuzzy match {str} in {list}
393matchfuzzypos({list}, {str} [, {dict}])
394 List fuzzy match {str} in {list}
395matchlist({expr}, {pat} [, {start} [, {count}]])
396 List match and submatches of {pat} in {expr}
397matchstr({expr}, {pat} [, {start} [, {count}]])
398 String {count}'th match of {pat} in {expr}
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100399matchstrlist({list}, {pat} [, {dict})
400 List all the {pat} matches in {list}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000401matchstrpos({expr}, {pat} [, {start} [, {count}]])
402 List {count}'th match of {pat} in {expr}
403max({expr}) Number maximum value of items in {expr}
404menu_info({name} [, {mode}]) Dict get menu item information
405min({expr}) Number minimum value of items in {expr}
Bram Moolenaar938ae282023-02-20 20:44:55 +0000406mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000407 Number create directory {name}
Doug Kearns9cd9e752024-04-07 17:42:17 +0200408mode([{expr}]) String current editing mode
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000409mzeval({expr}) any evaluate |MzScheme| expression
410nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
411nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
412or({expr}, {expr}) Number bitwise OR
413pathshorten({expr} [, {len}]) String shorten directory names in a path
414perleval({expr}) any evaluate |Perl| expression
415popup_atcursor({what}, {options}) Number create popup window near the cursor
416popup_beval({what}, {options}) Number create popup window for 'ballooneval'
417popup_clear() none close all popup windows
418popup_close({id} [, {result}]) none close popup window {id}
419popup_create({what}, {options}) Number create a popup window
420popup_dialog({what}, {options}) Number create a popup window used as a dialog
421popup_filter_menu({id}, {key}) Number filter for a menu popup window
422popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
Bram Moolenaarbdc09a12022-10-07 14:31:45 +0100423popup_findecho() Number get window ID of popup for `:echowin`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000424popup_findinfo() Number get window ID of info popup window
425popup_findpreview() Number get window ID of preview popup window
426popup_getoptions({id}) Dict get options of popup window {id}
427popup_getpos({id}) Dict get position of popup window {id}
428popup_hide({id}) none hide popup menu {id}
429popup_list() List get a list of window IDs of all popups
430popup_locate({row}, {col}) Number get window ID of popup at position
431popup_menu({what}, {options}) Number create a popup window used as a menu
432popup_move({id}, {options}) none set position of popup window {id}
433popup_notification({what}, {options})
434 Number create a notification popup window
Christian Brabandtfbc37f12024-06-18 20:50:58 +0200435popup_setbuf({id}, {buf}) Bool set the buffer for the popup window {id}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000436popup_setoptions({id}, {options})
437 none set options for popup window {id}
438popup_settext({id}, {text}) none set the text of popup window {id}
439popup_show({id}) none unhide popup window {id}
440pow({x}, {y}) Float {x} to the power of {y}
441prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
442printf({fmt}, {expr1}...) String format text
443prompt_getprompt({buf}) String get prompt text
444prompt_setcallback({buf}, {expr}) none set prompt callback function
445prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
446prompt_setprompt({buf}, {text}) none set prompt text
447prop_add({lnum}, {col}, {props}) none add one text property
448prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
449 none add multiple text properties
450prop_clear({lnum} [, {lnum-end} [, {props}]])
451 none remove all text properties
452prop_find({props} [, {direction}])
453 Dict search for a text property
454prop_list({lnum} [, {props}]) List text properties in {lnum}
455prop_remove({props} [, {lnum} [, {lnum-end}]])
456 Number remove a text property
457prop_type_add({name}, {props}) none define a new property type
458prop_type_change({name}, {props})
459 none change an existing property type
460prop_type_delete({name} [, {props}])
461 none delete a property type
462prop_type_get({name} [, {props}])
463 Dict get property type values
464prop_type_list([{props}]) List get list of property types
465pum_getpos() Dict position and size of pum if visible
466pumvisible() Number whether popup menu is visible
467py3eval({expr}) any evaluate |python3| expression
468pyeval({expr}) any evaluate |Python| expression
469pyxeval({expr}) any evaluate |python_x| expression
470rand([{expr}]) Number get pseudo-random number
471range({expr} [, {max} [, {stride}]])
472 List items from {expr} to {max}
K.Takata11df3ae2022-10-19 14:02:40 +0100473readblob({fname} [, {offset} [, {size}]])
474 Blob read a |Blob| from {fname}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000475readdir({dir} [, {expr} [, {dict}]])
476 List file names in {dir} selected by {expr}
477readdirex({dir} [, {expr} [, {dict}]])
478 List file info in {dir} selected by {expr}
479readfile({fname} [, {type} [, {max}]])
480 List get list of lines from file {fname}
481reduce({object}, {func} [, {initial}])
482 any reduce {object} using {func}
483reg_executing() String get the executing register name
484reg_recording() String get the recording register name
485reltime([{start} [, {end}]]) List get time value
486reltimefloat({time}) Float turn the time value into a Float
487reltimestr({time}) String turn time value into a String
488remote_expr({server}, {string} [, {idvar} [, {timeout}]])
489 String send expression
490remote_foreground({server}) Number bring Vim server to the foreground
491remote_peek({serverid} [, {retvar}])
492 Number check for reply string
493remote_read({serverid} [, {timeout}])
494 String read reply string
495remote_send({server}, {string} [, {idvar}])
496 String send key sequence
497remote_startserver({name}) none become server {name}
498remove({list}, {idx} [, {end}]) any/List
499 remove items {idx}-{end} from {list}
500remove({blob}, {idx} [, {end}]) Number/Blob
501 remove bytes {idx}-{end} from {blob}
502remove({dict}, {key}) any remove entry {key} from {dict}
503rename({from}, {to}) Number rename (move) file from {from} to {to}
Bakudankun375141e2022-09-09 18:46:47 +0100504repeat({expr}, {count}) List/Blob/String
505 repeat {expr} {count} times
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000506resolve({filename}) String get filename a shortcut points to
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +0100507reverse({obj}) List/Blob/String
508 reverse {obj}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000509round({expr}) Float round off {expr}
510rubyeval({expr}) any evaluate |Ruby| expression
511screenattr({row}, {col}) Number attribute at screen position
512screenchar({row}, {col}) Number character at screen position
513screenchars({row}, {col}) List List of characters at screen position
514screencol() Number current cursor column
515screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
516screenrow() Number current cursor row
517screenstring({row}, {col}) String characters at screen position
518search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
519 Number search for {pattern}
520searchcount([{options}]) Dict get or update search stats
521searchdecl({name} [, {global} [, {thisblock}]])
522 Number search for variable declaration
523searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
524 Number search for other end of start/end pair
525searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
526 List search for other end of start/end pair
527searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
528 List search for {pattern}
529server2client({clientid}, {string})
530 Number send reply string
531serverlist() String get a list of available servers
erraelf0837ba2024-06-24 12:27:01 -0700532setbufline({buf}, {lnum}, {text})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000533 Number set line {lnum} to {text} in buffer
erraelf0837ba2024-06-24 12:27:01 -0700534 {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000535setbufvar({buf}, {varname}, {val})
536 none set {varname} in buffer {buf} to {val}
537setcellwidths({list}) none set character cell width overrides
538setcharpos({expr}, {list}) Number set the {expr} position to {list}
539setcharsearch({dict}) Dict set character search from {dict}
Shougo Matsushita07ea5f12022-08-27 12:22:25 +0100540setcmdline({str} [, {pos}]) Number set command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000541setcmdpos({pos}) Number set cursor position in command-line
542setcursorcharpos({list}) Number move cursor to position in {list}
543setenv({name}, {val}) none set environment variable
544setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
545setline({lnum}, {line}) Number set line {lnum} to {line}
546setloclist({nr}, {list} [, {action}])
547 Number modify location list using {list}
548setloclist({nr}, {list}, {action}, {what})
549 Number modify specific location list props
550setmatches({list} [, {win}]) Number restore a list of matches
551setpos({expr}, {list}) Number set the {expr} position to {list}
552setqflist({list} [, {action}]) Number modify quickfix list using {list}
553setqflist({list}, {action}, {what})
554 Number modify specific quickfix list props
555setreg({n}, {v} [, {opt}]) Number set register to value and type
556settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
557settabwinvar({tabnr}, {winnr}, {varname}, {val})
558 none set {varname} in window {winnr} in tab
559 page {tabnr} to {val}
560settagstack({nr}, {dict} [, {action}])
561 Number modify tag stack using {dict}
562setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
563sha256({string}) String SHA256 checksum of {string}
564shellescape({string} [, {special}])
565 String escape {string} for use as shell
566 command argument
567shiftwidth([{col}]) Number effective value of 'shiftwidth'
568sign_define({name} [, {dict}]) Number define or update a sign
569sign_define({list}) List define or update a list of signs
570sign_getdefined([{name}]) List get a list of defined signs
571sign_getplaced([{buf} [, {dict}]])
572 List get a list of placed signs
573sign_jump({id}, {group}, {buf})
574 Number jump to a sign
575sign_place({id}, {group}, {name}, {buf} [, {dict}])
576 Number place a sign
577sign_placelist({list}) List place a list of signs
578sign_undefine([{name}]) Number undefine a sign
579sign_undefine({list}) List undefine a list of signs
580sign_unplace({group} [, {dict}])
581 Number unplace a sign
582sign_unplacelist({list}) List unplace a list of signs
583simplify({filename}) String simplify filename as much as possible
584sin({expr}) Float sine of {expr}
585sinh({expr}) Float hyperbolic sine of {expr}
586slice({expr}, {start} [, {end}]) String, List or Blob
587 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000588sort({list} [, {how} [, {dict}]])
589 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000590sound_clear() none stop playing all sounds
591sound_playevent({name} [, {callback}])
592 Number play an event sound
593sound_playfile({path} [, {callback}])
594 Number play sound file {path}
595sound_stop({id}) none stop playing sound {id}
596soundfold({word}) String sound-fold {word}
597spellbadword() String badly spelled word at cursor
598spellsuggest({word} [, {max} [, {capital}]])
599 List spelling suggestions
600split({expr} [, {pat} [, {keepempty}]])
601 List make |List| from {pat} separated {expr}
602sqrt({expr}) Float square root of {expr}
603srand([{expr}]) List get seed for |rand()|
604state([{what}]) String current state of Vim
605str2float({expr} [, {quoted}]) Float convert String to Float
606str2list({expr} [, {utf8}]) List convert each character of {expr} to
607 ASCII/UTF-8 value
608str2nr({expr} [, {base} [, {quoted}]])
609 Number convert String to Number
610strcharlen({expr}) Number character length of the String {expr}
611strcharpart({str}, {start} [, {len} [, {skipcc}]])
612 String {len} characters of {str} at
613 character {start}
614strchars({expr} [, {skipcc}]) Number character count of the String {expr}
615strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
616strftime({format} [, {time}]) String format time with a specified format
617strgetchar({str}, {index}) Number get char {index} from {str}
618stridx({haystack}, {needle} [, {start}])
619 Number index of {needle} in {haystack}
620string({expr}) String String representation of {expr} value
621strlen({expr}) Number length of the String {expr}
622strpart({str}, {start} [, {len} [, {chars}]])
623 String {len} bytes/chars of {str} at
624 byte {start}
625strptime({format}, {timestring})
626 Number Convert {timestring} to unix timestamp
627strridx({haystack}, {needle} [, {start}])
628 Number last index of {needle} in {haystack}
629strtrans({expr}) String translate string to make it printable
Christian Brabandt67672ef2023-04-24 21:09:54 +0100630strutf16len({string} [, {countcc}])
631 Number number of UTF-16 code units in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000632strwidth({expr}) Number display cell length of the String {expr}
633submatch({nr} [, {list}]) String or List
634 specific match in ":s" or substitute()
635substitute({expr}, {pat}, {sub}, {flags})
636 String all {pat} in {expr} replaced with {sub}
Bram Moolenaarc216a7a2022-12-05 13:50:55 +0000637swapfilelist() List swap files found in 'directory'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000638swapinfo({fname}) Dict information about swap file {fname}
639swapname({buf}) String swap file of buffer {buf}
640synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
641synIDattr({synID}, {what} [, {mode}])
642 String attribute {what} of syntax ID {synID}
643synIDtrans({synID}) Number translated syntax ID of {synID}
644synconcealed({lnum}, {col}) List info about concealing
645synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
646system({expr} [, {input}]) String output of shell command/filter {expr}
647systemlist({expr} [, {input}]) List output of shell command/filter {expr}
648tabpagebuflist([{arg}]) List list of buffer numbers in tab page
649tabpagenr([{arg}]) Number number of current or last tab page
650tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
651tagfiles() List tags files used
652taglist({expr} [, {filename}]) List list of tags matching {expr}
653tan({expr}) Float tangent of {expr}
654tanh({expr}) Float hyperbolic tangent of {expr}
655tempname() String name for a temporary file
656term_dumpdiff({filename}, {filename} [, {options}])
657 Number display difference between two dumps
658term_dumpload({filename} [, {options}])
659 Number displaying a screen dump
660term_dumpwrite({buf}, {filename} [, {options}])
661 none dump terminal window contents
662term_getaltscreen({buf}) Number get the alternate screen flag
663term_getansicolors({buf}) List get ANSI palette in GUI color mode
664term_getattr({attr}, {what}) Number get the value of attribute {what}
665term_getcursor({buf}) List get the cursor position of a terminal
666term_getjob({buf}) Job get the job associated with a terminal
667term_getline({buf}, {row}) String get a line of text from a terminal
668term_getscrolled({buf}) Number get the scroll count of a terminal
669term_getsize({buf}) List get the size of a terminal
670term_getstatus({buf}) String get the status of a terminal
671term_gettitle({buf}) String get the title of a terminal
672term_gettty({buf}, [{input}]) String get the tty name of a terminal
673term_list() List get the list of terminal buffers
674term_scrape({buf}, {row}) List get row of a terminal screen
675term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
676term_setansicolors({buf}, {colors})
677 none set ANSI palette in GUI color mode
678term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
679term_setkill({buf}, {how}) none set signal to stop job in terminal
680term_setrestore({buf}, {command}) none set command to restore terminal
681term_setsize({buf}, {rows}, {cols})
682 none set the size of a terminal
683term_start({cmd} [, {options}]) Number open a terminal window and run a job
684term_wait({buf} [, {time}]) Number wait for screen to be updated
685terminalprops() Dict properties of the terminal
686test_alloc_fail({id}, {countdown}, {repeat})
687 none make memory allocation fail
688test_autochdir() none enable 'autochdir' during startup
689test_feedinput({string}) none add key sequence to input buffer
690test_garbagecollect_now() none free memory right now for testing
691test_garbagecollect_soon() none free memory soon for testing
692test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000693test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000694test_ignore_error({expr}) none ignore a specific error
Christopher Plewright20b795e2022-12-20 20:01:58 +0000695test_mswin_event({event}, {args})
696 bool generate MS-Windows event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000697test_null_blob() Blob null value for testing
698test_null_channel() Channel null value for testing
699test_null_dict() Dict null value for testing
700test_null_function() Funcref null value for testing
701test_null_job() Job null value for testing
702test_null_list() List null value for testing
703test_null_partial() Funcref null value for testing
704test_null_string() String null value for testing
705test_option_not_set({name}) none reset flag indicating option was set
706test_override({expr}, {val}) none test with Vim internal overrides
707test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000708test_setmouse({row}, {col}) none set the mouse position for testing
709test_settime({expr}) none set current time for testing
Doug Kearns9cd9e752024-04-07 17:42:17 +0200710test_srand_seed([{seed}]) none set seed for testing srand()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000711test_unknown() any unknown value for testing
712test_void() any void value for testing
713timer_info([{id}]) List information about timers
714timer_pause({id}, {pause}) none pause or unpause a timer
715timer_start({time}, {callback} [, {options}])
716 Number create a timer
717timer_stop({timer}) none stop a timer
718timer_stopall() none stop all timers
719tolower({expr}) String the String {expr} switched to lowercase
720toupper({expr}) String the String {expr} switched to uppercase
721tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
722 to chars in {tostr}
723trim({text} [, {mask} [, {dir}]])
724 String trim characters in {mask} from {text}
725trunc({expr}) Float truncate Float {expr}
726type({expr}) Number type of value {expr}
727typename({expr}) String representation of the type of {expr}
728undofile({name}) String undo file name for {name}
Devin J. Pohly5fee1112023-04-23 20:26:59 -0500729undotree([{buf}]) List undo file tree for buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000730uniq({list} [, {func} [, {dict}]])
731 List remove adjacent duplicates from a list
Christian Brabandt67672ef2023-04-24 21:09:54 +0100732utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
733 Number UTF-16 index of byte {idx} in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000734values({dict}) List values in {dict}
zeertzjq825cf812023-08-17 22:55:25 +0200735virtcol({expr} [, {list} [, {winid}])
736 Number or List
LemonBoy0f7a3e12022-05-26 12:10:37 +0100737 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100738virtcol2col({winid}, {lnum}, {col})
739 Number byte index of a character on screen
Doug Kearns9cd9e752024-04-07 17:42:17 +0200740visualmode([{expr}]) String last visual mode used
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000741wildmenumode() Number whether 'wildmenu' mode is active
742win_execute({id}, {command} [, {silent}])
743 String execute {command} in window {id}
744win_findbuf({bufnr}) List find windows containing {bufnr}
745win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
746win_gettype([{nr}]) String type of window {nr}
747win_gotoid({expr}) Number go to window with ID {expr}
748win_id2tabwin({expr}) List get tab and window nr from window ID
749win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000750win_move_separator({nr}) Number move window vertical separator
751win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000752win_screenpos({nr}) List get screen position of window {nr}
753win_splitmove({nr}, {target} [, {options}])
754 Number move window {nr} to split of {target}
755winbufnr({nr}) Number buffer number of window {nr}
756wincol() Number window column of the cursor
757windowsversion() String MS-Windows OS version
758winheight({nr}) Number height of window {nr}
759winlayout([{tabnr}]) List layout of windows in tab {tabnr}
760winline() Number window line of the cursor
761winnr([{expr}]) Number number of current window
762winrestcmd() String returns command to restore window sizes
763winrestview({dict}) none restore view of current window
764winsaveview() Dict save view of current window
765winwidth({nr}) Number width of window {nr}
766wordcount() Dict get byte/char/word statistics
767writefile({object}, {fname} [, {flags}])
768 Number write |Blob| or |List| of lines to file
769xor({expr}, {expr}) Number bitwise XOR
770
771==============================================================================
7722. Details *builtin-function-details*
773
774Not all functions are here, some have been moved to a help file covering the
775specific functionality.
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200776Return type specifies the type for |Vim9-script|, see |vim9-types|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000777
778abs({expr}) *abs()*
779 Return the absolute value of {expr}. When {expr} evaluates to
780 a |Float| abs() returns a |Float|. When {expr} can be
781 converted to a |Number| abs() returns a |Number|. Otherwise
782 abs() gives an error message and returns -1.
783 Examples: >
784 echo abs(1.456)
785< 1.456 >
786 echo abs(-5.456)
787< 5.456 >
788 echo abs(-4)
789< 4
790
791 Can also be used as a |method|: >
792 Compute()->abs()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200793<
794 Return type: |Number| or |Float| depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000795
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000796
797acos({expr}) *acos()*
798 Return the arc cosine of {expr} measured in radians, as a
799 |Float| in the range of [0, pi].
800 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100801 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000802 Examples: >
803 :echo acos(0)
804< 1.570796 >
805 :echo acos(-0.5)
806< 2.094395
807
808 Can also be used as a |method|: >
809 Compute()->acos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200810<
811 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000812
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000813
814add({object}, {expr}) *add()*
815 Append the item {expr} to |List| or |Blob| {object}. Returns
816 the resulting |List| or |Blob|. Examples: >
817 :let alist = add([1, 2, 3], item)
818 :call add(mylist, "woodstock")
819< Note that when {expr} is a |List| it is appended as a single
820 item. Use |extend()| to concatenate |Lists|.
821 When {object} is a |Blob| then {expr} must be a number.
822 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100823 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000824
825 Can also be used as a |method|: >
826 mylist->add(val1)->add(val2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200827<
828 Return type: list<{type}> (depending on the given |List|) or
829 |Blob|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000830
831
832and({expr}, {expr}) *and()*
833 Bitwise AND on the two arguments. The arguments are converted
834 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100835 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000836 Example: >
837 :let flag = and(bits, 0x80)
838< Can also be used as a |method|: >
839 :let flag = bits->and(0x80)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200840<
841 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000842
843
844append({lnum}, {text}) *append()*
845 When {text} is a |List|: Append each item of the |List| as a
846 text line below line {lnum} in the current buffer.
847 Otherwise append {text} as one text line below line {lnum} in
848 the current buffer.
849 Any type of item is accepted and converted to a String.
850 {lnum} can be zero to insert a line before the first one.
851 {lnum} is used like with |getline()|.
852 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000853 0 for success. When {text} is an empty list zero is returned,
854 no matter the value of {lnum}.
855 In |Vim9| script an invalid argument or negative number
856 results in an error. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000857 :let failed = append(line('$'), "# THE END")
858 :let failed = append(0, ["Chapter 1", "the beginning"])
859
860< Can also be used as a |method| after a List, the base is
861 passed as the second argument: >
862 mylist->append(lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200863<
864 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000865
866
867appendbufline({buf}, {lnum}, {text}) *appendbufline()*
868 Like |append()| but append the text in buffer {buf}.
869
870 This function works only for loaded buffers. First call
871 |bufload()| if needed.
872
873 For the use of {buf}, see |bufname()|.
874
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000875 {lnum} is the line number to append below. Note that using
876 |line()| would use the current buffer, not the one appending
877 to. Use "$" to append at the end of the buffer. Other string
878 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000879
880 On success 0 is returned, on failure 1 is returned.
881 In |Vim9| script an error is given for an invalid {lnum}.
882
883 If {buf} is not a valid buffer or {lnum} is not valid, an
884 error message is given. Example: >
885 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000886< However, when {text} is an empty list then no error is given
887 for an invalid {lnum}, since {lnum} isn't actually used.
888
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000889 Can also be used as a |method| after a List, the base is
890 passed as the second argument: >
891 mylist->appendbufline(buf, lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200892<
893 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000894
895
896argc([{winid}]) *argc()*
897 The result is the number of files in the argument list. See
898 |arglist|.
899 If {winid} is not supplied, the argument list of the current
900 window is used.
901 If {winid} is -1, the global argument list is used.
902 Otherwise {winid} specifies the window of which the argument
903 list is used: either the window number or the window ID.
904 Returns -1 if the {winid} argument is invalid.
905
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200906 Return type: |Number|
907
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000908 *argidx()*
909argidx() The result is the current index in the argument list. 0 is
910 the first file. argc() - 1 is the last one. See |arglist|.
911
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200912 Return type: |Number|
913
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000914 *arglistid()*
915arglistid([{winnr} [, {tabnr}]])
916 Return the argument list ID. This is a number which
917 identifies the argument list being used. Zero is used for the
918 global argument list. See |arglist|.
919 Returns -1 if the arguments are invalid.
920
921 Without arguments use the current window.
922 With {winnr} only use this window in the current tab page.
923 With {winnr} and {tabnr} use the window in the specified tab
924 page.
925 {winnr} can be the window number or the |window-ID|.
926
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200927 Return type: |Number|
928
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000929 *argv()*
930argv([{nr} [, {winid}]])
931 The result is the {nr}th file in the argument list. See
932 |arglist|. "argv(0)" is the first one. Example: >
933 :let i = 0
934 :while i < argc()
935 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000936 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000937 : let i = i + 1
938 :endwhile
939< Without the {nr} argument, or when {nr} is -1, a |List| with
940 the whole |arglist| is returned.
941
942 The {winid} argument specifies the window ID, see |argc()|.
943 For the Vim command line arguments see |v:argv|.
944
Bram Moolenaar016188f2022-06-06 20:52:59 +0100945 Returns an empty string if {nr}th argument is not present in
946 the argument list. Returns an empty List if the {winid}
947 argument is invalid.
948
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200949 Return type: |String|
950
951
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000952asin({expr}) *asin()*
953 Return the arc sine of {expr} measured in radians, as a |Float|
954 in the range of [-pi/2, pi/2].
955 {expr} must evaluate to a |Float| or a |Number| in the range
956 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100957 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
958 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000959 Examples: >
960 :echo asin(0.8)
961< 0.927295 >
962 :echo asin(-0.5)
963< -0.523599
964
965 Can also be used as a |method|: >
966 Compute()->asin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200967<
968 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000969
970assert_ functions are documented here: |assert-functions-details|
971
972
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000973atan({expr}) *atan()*
974 Return the principal value of the arc tangent of {expr}, in
975 the range [-pi/2, +pi/2] radians, as a |Float|.
976 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100977 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000978 Examples: >
979 :echo atan(100)
980< 1.560797 >
981 :echo atan(-4.01)
982< -1.326405
983
984 Can also be used as a |method|: >
985 Compute()->atan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200986<
987 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000988
989
990atan2({expr1}, {expr2}) *atan2()*
991 Return the arc tangent of {expr1} / {expr2}, measured in
992 radians, as a |Float| in the range [-pi, pi].
993 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100994 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
995 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000996 Examples: >
997 :echo atan2(-1, 1)
998< -0.785398 >
999 :echo atan2(1, -1)
1000< 2.356194
1001
1002 Can also be used as a |method|: >
1003 Compute()->atan2(1)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001004<
1005 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001006
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001007
1008autocmd_add({acmds}) *autocmd_add()*
1009 Adds a List of autocmds and autocmd groups.
1010
1011 The {acmds} argument is a List where each item is a Dict with
1012 the following optional items:
1013 bufnr buffer number to add a buffer-local autocmd.
1014 If this item is specified, then the "pattern"
1015 item is ignored.
1016 cmd Ex command to execute for this autocmd event
1017 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +01001018 This can be either a String with a single
1019 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001020 group autocmd group name. Refer to |autocmd-groups|.
1021 If this group doesn't exist then it is
1022 created. If not specified or empty, then the
1023 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001024 nested boolean flag, set to v:true to add a nested
1025 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +01001026 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001027 which executes only once. Refer to
1028 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001029 pattern autocmd pattern string. Refer to
1030 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +01001031 present, then this item is ignored. This can
1032 be a String with a single pattern or a List of
1033 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001034 replace boolean flag, set to v:true to remove all the
1035 commands associated with the specified autocmd
1036 event and group and add the {cmd}. This is
1037 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +01001038 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001039
1040 Returns v:true on success and v:false on failure.
1041 Examples: >
1042 " Create a buffer-local autocmd for buffer 5
1043 let acmd = {}
1044 let acmd.group = 'MyGroup'
1045 let acmd.event = 'BufEnter'
1046 let acmd.bufnr = 5
1047 let acmd.cmd = 'call BufEnterFunc()'
1048 call autocmd_add([acmd])
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00001049<
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001050 Can also be used as a |method|: >
1051 GetAutocmdList()->autocmd_add()
1052<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001053 Return type: |vim9-boolean|
1054
1055
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001056autocmd_delete({acmds}) *autocmd_delete()*
1057 Deletes a List of autocmds and autocmd groups.
1058
1059 The {acmds} argument is a List where each item is a Dict with
1060 the following optional items:
1061 bufnr buffer number to delete a buffer-local autocmd.
1062 If this item is specified, then the "pattern"
1063 item is ignored.
1064 cmd Ex command for this autocmd event
1065 event autocmd event name. Refer to |autocmd-events|.
1066 If '*' then all the autocmd events in this
1067 group are deleted.
1068 group autocmd group name. Refer to |autocmd-groups|.
1069 If not specified or empty, then the default
1070 group is used.
1071 nested set to v:true for a nested autocmd.
1072 Refer to |autocmd-nested|.
1073 once set to v:true for an autocmd which executes
1074 only once. Refer to |autocmd-once|.
1075 pattern autocmd pattern string. Refer to
1076 |autocmd-patterns|. If "bufnr" item is
1077 present, then this item is ignored.
1078
1079 If only {group} is specified in a {acmds} entry and {event},
1080 {pattern} and {cmd} are not specified, then that autocmd group
1081 is deleted.
1082
Bram Moolenaar016188f2022-06-06 20:52:59 +01001083 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001084 Examples: >
1085 " :autocmd! BufLeave *.vim
1086 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1087 call autocmd_delete([acmd]})
1088 " :autocmd! MyGroup1 BufLeave
1089 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1090 call autocmd_delete([acmd])
1091 " :autocmd! MyGroup2 BufEnter *.c
1092 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1093 \ pattern: '*.c'}
1094 " :autocmd! MyGroup2 * *.c
1095 let acmd = #{group: 'MyGroup2', event: '*',
1096 \ pattern: '*.c'}
1097 call autocmd_delete([acmd])
1098 " :autocmd! MyGroup3
1099 let acmd = #{group: 'MyGroup3'}
1100 call autocmd_delete([acmd])
1101<
1102 Can also be used as a |method|: >
1103 GetAutocmdList()->autocmd_delete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001104<
1105 Return type: |vim9-boolean|
1106
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001107
1108autocmd_get([{opts}]) *autocmd_get()*
1109 Returns a |List| of autocmds. If {opts} is not supplied, then
1110 returns the autocmds for all the events in all the groups.
1111
1112 The optional {opts} Dict argument supports the following
1113 items:
1114 group Autocmd group name. If specified, returns only
1115 the autocmds defined in this group. If the
1116 specified group doesn't exist, results in an
1117 error message. If set to an empty string,
1118 then the default autocmd group is used.
1119 event Autocmd event name. If specified, returns only
1120 the autocmds defined for this event. If set
1121 to "*", then returns autocmds for all the
1122 events. If the specified event doesn't exist,
1123 results in an error message.
1124 pattern Autocmd pattern. If specified, returns only
1125 the autocmds defined for this pattern.
1126 A combination of the above three times can be supplied in
1127 {opts}.
1128
1129 Each Dict in the returned List contains the following items:
1130 bufnr For buffer-local autocmds, buffer number where
1131 the autocmd is defined.
1132 cmd Command executed for this autocmd.
1133 event Autocmd event name.
1134 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001135 nested Boolean flag, set to v:true for a nested
1136 autocmd. See |autocmd-nested|.
1137 once Boolean flag, set to v:true, if the autocmd
1138 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001139 pattern Autocmd pattern. For a buffer-local
1140 autocmd, this will be of the form "<buffer=n>".
1141 If there are multiple commands for an autocmd event in a
1142 group, then separate items are returned for each command.
1143
Bram Moolenaar016188f2022-06-06 20:52:59 +01001144 Returns an empty List if an autocmd with the specified group
1145 or event or pattern is not found.
1146
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001147 Examples: >
1148 " :autocmd MyGroup
1149 echo autocmd_get(#{group: 'Mygroup'})
1150 " :autocmd G BufUnload
1151 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1152 " :autocmd G * *.ts
1153 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1154 echo autocmd_get(acmd)
1155 " :autocmd Syntax
1156 echo autocmd_get(#{event: 'Syntax'})
1157 " :autocmd G BufEnter *.ts
1158 let acmd = #{group: 'G', event: 'BufEnter',
1159 \ pattern: '*.ts'}
1160 echo autocmd_get(acmd)
1161<
1162 Can also be used as a |method|: >
1163 Getopts()->autocmd_get()
1164<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001165 Return type: list<dict<any>>
1166
1167
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001168balloon_gettext() *balloon_gettext()*
1169 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001170 not used for the List. Returns an empty string if balloon
1171 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001172
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001173 Return type: |String|
1174
1175
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001176balloon_show({expr}) *balloon_show()*
1177 Show {expr} inside the balloon. For the GUI {expr} is used as
1178 a string. For a terminal {expr} can be a list, which contains
1179 the lines of the balloon. If {expr} is not a list it will be
1180 split with |balloon_split()|.
1181 If {expr} is an empty string any existing balloon is removed.
1182
1183 Example: >
1184 func GetBalloonContent()
1185 " ... initiate getting the content
1186 return ''
1187 endfunc
1188 set balloonexpr=GetBalloonContent()
1189
1190 func BalloonCallback(result)
1191 call balloon_show(a:result)
1192 endfunc
1193< Can also be used as a |method|: >
1194 GetText()->balloon_show()
1195<
1196 The intended use is that fetching the content of the balloon
1197 is initiated from 'balloonexpr'. It will invoke an
1198 asynchronous method, in which a callback invokes
1199 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001200 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001201
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001202 When showing a balloon is not possible then nothing happens,
1203 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001204 {only available when compiled with the |+balloon_eval| or
1205 |+balloon_eval_term| feature}
1206
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001207 Return type: |Number|
1208
1209
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001210balloon_split({msg}) *balloon_split()*
1211 Split String {msg} into lines to be displayed in a balloon.
1212 The splits are made for the current window size and optimize
1213 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001214 Returns a |List| with the split lines. Returns an empty List
1215 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001216 Can also be used as a |method|: >
1217 GetText()->balloon_split()->balloon_show()
1218
1219< {only available when compiled with the |+balloon_eval_term|
1220 feature}
1221
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001222 Return type: list<any> or list<string>
1223
Christ van Willegence0ef912024-06-20 23:41:59 +02001224bindtextdomain({package}, {path}) *bindtextdomain()*
1225 Bind a specific {package} to a {path} so that the
1226 |gettext()| function can be used to get language-specific
1227 translations for a package. {path} is the directory name
h-east52e7cc22024-07-28 17:03:29 +02001228 for the translations. See |package-translation|.
Christ van Willegence0ef912024-06-20 23:41:59 +02001229
Christ van Willegen8252ef12024-07-11 21:36:21 +02001230 Returns v:true on success and v:false on failure (out of
1231 memory).
1232
1233 Return type: |vim9-boolean|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001234
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001235blob2list({blob}) *blob2list()*
1236 Return a List containing the number value of each byte in Blob
1237 {blob}. Examples: >
1238 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1239 blob2list(0z) returns []
1240< Returns an empty List on error. |list2blob()| does the
1241 opposite.
1242
1243 Can also be used as a |method|: >
1244 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001245<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001246 Return type: list<any> or list<number>
1247
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001248 *browse()*
1249browse({save}, {title}, {initdir}, {default})
1250 Put up a file requester. This only works when "has("browse")"
1251 returns |TRUE| (only in some GUI versions).
1252 The input fields are:
1253 {save} when |TRUE|, select file to write
1254 {title} title for the requester
1255 {initdir} directory to start browsing in
1256 {default} default file name
1257 An empty string is returned when the "Cancel" button is hit,
1258 something went wrong, or browsing is not possible.
1259
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001260 Return type: |String|
1261
1262
1263browsedir({title}, {initdir}) *browsedir()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001264 Put up a directory requester. This only works when
1265 "has("browse")" returns |TRUE| (only in some GUI versions).
1266 On systems where a directory browser is not supported a file
1267 browser is used. In that case: select a file in the directory
1268 to be used.
1269 The input fields are:
1270 {title} title for the requester
1271 {initdir} directory to start browsing in
1272 When the "Cancel" button is hit, something went wrong, or
1273 browsing is not possible, an empty string is returned.
1274
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001275 Return type: |String|
1276
1277
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001278bufadd({name}) *bufadd()*
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001279 Add a buffer to the buffer list with name {name} (must be a
1280 String).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001281 If a buffer for file {name} already exists, return that buffer
1282 number. Otherwise return the buffer number of the newly
1283 created buffer. When {name} is an empty string then a new
1284 buffer is always created.
1285 The buffer will not have 'buflisted' set and not be loaded
1286 yet. To add some text to the buffer use this: >
1287 let bufnr = bufadd('someName')
1288 call bufload(bufnr)
1289 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001290< Returns 0 on error.
1291 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001292 let bufnr = 'somename'->bufadd()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001293<
1294 Return type: |Number|
1295
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001296
1297bufexists({buf}) *bufexists()*
1298 The result is a Number, which is |TRUE| if a buffer called
1299 {buf} exists.
1300 If the {buf} argument is a number, buffer numbers are used.
1301 Number zero is the alternate buffer for the current window.
1302
1303 If the {buf} argument is a string it must match a buffer name
1304 exactly. The name can be:
1305 - Relative to the current directory.
1306 - A full path.
1307 - The name of a buffer with 'buftype' set to "nofile".
1308 - A URL name.
1309 Unlisted buffers will be found.
1310 Note that help files are listed by their short name in the
1311 output of |:buffers|, but bufexists() requires using their
1312 long name to be able to find them.
1313 bufexists() may report a buffer exists, but to use the name
1314 with a |:buffer| command you may need to use |expand()|. Esp
1315 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1316 Use "bufexists(0)" to test for the existence of an alternate
1317 file name.
1318
1319 Can also be used as a |method|: >
1320 let exists = 'somename'->bufexists()
1321<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001322 Return type: |Number|
1323
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001324 Obsolete name: buffer_exists(). *buffer_exists()*
1325
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001326
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001327buflisted({buf}) *buflisted()*
1328 The result is a Number, which is |TRUE| if a buffer called
1329 {buf} exists and is listed (has the 'buflisted' option set).
1330 The {buf} argument is used like with |bufexists()|.
1331
1332 Can also be used as a |method|: >
1333 let listed = 'somename'->buflisted()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001334<
1335 Return type: |Number|
1336
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001337
1338bufload({buf}) *bufload()*
1339 Ensure the buffer {buf} is loaded. When the buffer name
1340 refers to an existing file then the file is read. Otherwise
1341 the buffer will be empty. If the buffer was already loaded
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001342 then there is no change. If the buffer is not related to a
Daniel Steinbergc2bd2052023-08-09 12:10:59 -04001343 file then no file is read (e.g., when 'buftype' is "nofile").
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001344 If there is an existing swap file for the file of the buffer,
1345 there will be no dialog, the buffer will be loaded anyway.
1346 The {buf} argument is used like with |bufexists()|.
1347
1348 Can also be used as a |method|: >
1349 eval 'somename'->bufload()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001350<
1351 Return type: |Number|
1352
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001353
1354bufloaded({buf}) *bufloaded()*
1355 The result is a Number, which is |TRUE| if a buffer called
1356 {buf} exists and is loaded (shown in a window or hidden).
1357 The {buf} argument is used like with |bufexists()|.
1358
1359 Can also be used as a |method|: >
1360 let loaded = 'somename'->bufloaded()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001361<
1362 Return type: |Number|
1363
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001364
1365bufname([{buf}]) *bufname()*
1366 The result is the name of a buffer. Mostly as it is displayed
1367 by the `:ls` command, but not using special names such as
1368 "[No Name]".
1369 If {buf} is omitted the current buffer is used.
1370 If {buf} is a Number, that buffer number's name is given.
1371 Number zero is the alternate buffer for the current window.
1372 If {buf} is a String, it is used as a |file-pattern| to match
1373 with the buffer names. This is always done like 'magic' is
1374 set and 'cpoptions' is empty. When there is more than one
1375 match an empty string is returned.
1376 "" or "%" can be used for the current buffer, "#" for the
1377 alternate buffer.
1378 A full match is preferred, otherwise a match at the start, end
1379 or middle of the buffer name is accepted. If you only want a
1380 full match then put "^" at the start and "$" at the end of the
1381 pattern.
1382 Listed buffers are found first. If there is a single match
1383 with a listed buffer, that one is returned. Next unlisted
1384 buffers are searched for.
1385 If the {buf} is a String, but you want to use it as a buffer
1386 number, force it to be a Number by adding zero to it: >
1387 :echo bufname("3" + 0)
1388< Can also be used as a |method|: >
1389 echo bufnr->bufname()
1390
1391< If the buffer doesn't exist, or doesn't have a name, an empty
1392 string is returned. >
1393 bufname("#") alternate buffer name
1394 bufname(3) name of buffer 3
1395 bufname("%") name of current buffer
1396 bufname("file2") name of buffer where "file2" matches.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001397<
1398 Return type: |String|
1399 *buffer_name()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001400 Obsolete name: buffer_name().
1401
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001402
1403bufnr([{buf} [, {create}]]) *bufnr()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001404 The result is the number of a buffer, as it is displayed by
1405 the `:ls` command. For the use of {buf}, see |bufname()|
1406 above.
1407
1408 If the buffer doesn't exist, -1 is returned. Or, if the
1409 {create} argument is present and TRUE, a new, unlisted,
1410 buffer is created and its number is returned. Example: >
1411 let newbuf = bufnr('Scratch001', 1)
1412< Using an empty name uses the current buffer. To create a new
1413 buffer with an empty name use |bufadd()|.
1414
1415 bufnr("$") is the last buffer: >
1416 :let last_buffer = bufnr("$")
1417< The result is a Number, which is the highest buffer number
1418 of existing buffers. Note that not all buffers with a smaller
1419 number necessarily exist, because ":bwipeout" may have removed
1420 them. Use bufexists() to test for the existence of a buffer.
1421
1422 Can also be used as a |method|: >
1423 echo bufref->bufnr()
1424<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001425 Return type: |Number|
1426
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001427 Obsolete name: buffer_number(). *buffer_number()*
1428 *last_buffer_nr()*
1429 Obsolete name for bufnr("$"): last_buffer_nr().
1430
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001431
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001432bufwinid({buf}) *bufwinid()*
1433 The result is a Number, which is the |window-ID| of the first
1434 window associated with buffer {buf}. For the use of {buf},
1435 see |bufname()| above. If buffer {buf} doesn't exist or
1436 there is no such window, -1 is returned. Example: >
1437
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001438 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001439<
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001440 Only deals with the current tab page. See |win_findbuf()| for
1441 finding more.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001442
1443 Can also be used as a |method|: >
1444 FindBuffer()->bufwinid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001445<
1446 Return type: |Number|
1447
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001448
1449bufwinnr({buf}) *bufwinnr()*
1450 Like |bufwinid()| but return the window number instead of the
1451 |window-ID|.
1452 If buffer {buf} doesn't exist or there is no such window, -1
1453 is returned. Example: >
1454
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001455 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001456
1457< The number can be used with |CTRL-W_w| and ":wincmd w"
1458 |:wincmd|.
1459
1460 Can also be used as a |method|: >
1461 FindBuffer()->bufwinnr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001462<
1463 Return type: |Number|
1464
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001465
1466byte2line({byte}) *byte2line()*
1467 Return the line number that contains the character at byte
1468 count {byte} in the current buffer. This includes the
1469 end-of-line character, depending on the 'fileformat' option
1470 for the current buffer. The first character has byte count
1471 one.
1472 Also see |line2byte()|, |go| and |:goto|.
1473
Bram Moolenaar016188f2022-06-06 20:52:59 +01001474 Returns -1 if the {byte} value is invalid.
1475
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001476 Can also be used as a |method|: >
1477 GetOffset()->byte2line()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001478<
1479 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001480
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001481 {not available when compiled without the |+byte_offset|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001482 feature}
1483
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001484
Christian Brabandt67672ef2023-04-24 21:09:54 +01001485byteidx({expr}, {nr} [, {utf16}]) *byteidx()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001486 Return byte index of the {nr}'th character in the String
1487 {expr}. Use zero for the first character, it then returns
1488 zero.
1489 If there are no multibyte characters the returned value is
1490 equal to {nr}.
1491 Composing characters are not counted separately, their byte
1492 length is added to the preceding base character. See
1493 |byteidxcomp()| below for counting composing characters
1494 separately.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001495 When {utf16} is present and TRUE, {nr} is used as the UTF-16
1496 index in the String {expr} instead of as the character index.
1497 The UTF-16 index is the index in the string when it is encoded
1498 with 16-bit words. If the specified UTF-16 index is in the
1499 middle of a character (e.g. in a 4-byte character), then the
1500 byte index of the first byte in the character is returned.
1501 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001502 Example : >
1503 echo matchstr(str, ".", byteidx(str, 3))
1504< will display the fourth character. Another way to do the
1505 same: >
1506 let s = strpart(str, byteidx(str, 3))
1507 echo strpart(s, 0, byteidx(s, 1))
1508< Also see |strgetchar()| and |strcharpart()|.
1509
1510 If there are less than {nr} characters -1 is returned.
1511 If there are exactly {nr} characters the length of the string
1512 in bytes is returned.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001513 See |charidx()| and |utf16idx()| for getting the character and
1514 UTF-16 index respectively from the byte index.
1515 Examples: >
1516 echo byteidx('a😊😊', 2) returns 5
1517 echo byteidx('a😊😊', 2, 1) returns 1
1518 echo byteidx('a😊😊', 3, 1) returns 5
1519<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001520 Can also be used as a |method|: >
1521 GetName()->byteidx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001522<
1523 Return type: |Number|
1524
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001525
Christian Brabandt67672ef2023-04-24 21:09:54 +01001526byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001527 Like byteidx(), except that a composing character is counted
1528 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001529 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001530 echo byteidx(s, 1)
1531 echo byteidxcomp(s, 1)
1532 echo byteidxcomp(s, 2)
1533< The first and third echo result in 3 ('e' plus composing
1534 character is 3 bytes), the second echo results in 1 ('e' is
1535 one byte).
1536 Only works differently from byteidx() when 'encoding' is set
1537 to a Unicode encoding.
1538
1539 Can also be used as a |method|: >
1540 GetName()->byteidxcomp(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001541<
1542 Return type: |Number|
1543
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001544
1545call({func}, {arglist} [, {dict}]) *call()* *E699*
1546 Call function {func} with the items in |List| {arglist} as
1547 arguments.
1548 {func} can either be a |Funcref| or the name of a function.
1549 a:firstline and a:lastline are set to the cursor line.
1550 Returns the return value of the called function.
1551 {dict} is for functions with the "dict" attribute. It will be
1552 used to set the local variable "self". |Dictionary-function|
1553
1554 Can also be used as a |method|: >
1555 GetFunc()->call([arg, arg], dict)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001556<
1557 Return type: any, depending on {func}
1558
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001559
1560ceil({expr}) *ceil()*
1561 Return the smallest integral value greater than or equal to
1562 {expr} as a |Float| (round up).
1563 {expr} must evaluate to a |Float| or a |Number|.
1564 Examples: >
1565 echo ceil(1.456)
1566< 2.0 >
1567 echo ceil(-5.456)
1568< -5.0 >
1569 echo ceil(4.0)
1570< 4.0
1571
Bram Moolenaar016188f2022-06-06 20:52:59 +01001572 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1573
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001574 Can also be used as a |method|: >
1575 Compute()->ceil()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001576<
1577 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001578
1579
1580ch_ functions are documented here: |channel-functions-details|
1581
1582
1583changenr() *changenr()*
1584 Return the number of the most recent change. This is the same
1585 number as what is displayed with |:undolist| and can be used
1586 with the |:undo| command.
1587 When a change was made it is the number of that change. After
1588 redo it is the number of the redone change. After undo it is
1589 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001590 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001591
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001592 Return type: |Number|
1593
1594
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001595char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001596 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001597 Examples: >
1598 char2nr(" ") returns 32
1599 char2nr("ABC") returns 65
1600< When {utf8} is omitted or zero, the current 'encoding' is used.
1601 Example for "utf-8": >
1602 char2nr("á") returns 225
1603 char2nr("á"[0]) returns 195
1604< When {utf8} is TRUE, always treat as UTF-8 characters.
1605 A combining character is a separate character.
1606 |nr2char()| does the opposite.
1607 To turn a string into a list of character numbers: >
1608 let str = "ABC"
1609 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1610< Result: [65, 66, 67]
1611
Bram Moolenaar016188f2022-06-06 20:52:59 +01001612 Returns 0 if {string} is not a |String|.
1613
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001614 Can also be used as a |method|: >
1615 GetChar()->char2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001616<
1617 Return type: |Number|
1618
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001619
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001620charclass({string}) *charclass()*
1621 Return the character class of the first character in {string}.
1622 The character class is one of:
1623 0 blank
1624 1 punctuation
1625 2 word character
1626 3 emoji
1627 other specific Unicode class
1628 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001629 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001630
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001631 Return type: |Number|
1632
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001633
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001634charcol({expr} [, {winid}]) *charcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001635 Same as |col()| but returns the character index of the column
1636 position given with {expr} instead of the byte position.
1637
1638 Example:
1639 With the cursor on '세' in line 5 with text "여보세요": >
1640 charcol('.') returns 3
1641 col('.') returns 7
1642
1643< Can also be used as a |method|: >
1644 GetPos()->col()
1645<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001646 Return type: |Number|
1647
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001648 *charidx()*
Christian Brabandt67672ef2023-04-24 21:09:54 +01001649charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001650 Return the character index of the byte at {idx} in {string}.
1651 The index of the first character is zero.
1652 If there are no multibyte characters the returned value is
1653 equal to {idx}.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001654
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001655 When {countcc} is omitted or |FALSE|, then composing characters
Christian Brabandt67672ef2023-04-24 21:09:54 +01001656 are not counted separately, their byte length is added to the
1657 preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001658 When {countcc} is |TRUE|, then composing characters are
1659 counted as separate characters.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001660
1661 When {utf16} is present and TRUE, {idx} is used as the UTF-16
1662 index in the String {expr} instead of as the byte index.
1663
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +01001664 Returns -1 if the arguments are invalid or if there are less
1665 than {idx} bytes. If there are exactly {idx} bytes the length
1666 of the string in characters is returned.
1667
1668 An error is given and -1 is returned if the first argument is
1669 not a string, the second argument is not a number or when the
1670 third argument is present and is not zero or one.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001671
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001672 See |byteidx()| and |byteidxcomp()| for getting the byte index
Christian Brabandt67672ef2023-04-24 21:09:54 +01001673 from the character index and |utf16idx()| for getting the
1674 UTF-16 index from the character index.
1675 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001676 Examples: >
1677 echo charidx('áb́ć', 3) returns 1
1678 echo charidx('áb́ć', 6, 1) returns 4
1679 echo charidx('áb́ć', 16) returns -1
Christian Brabandt67672ef2023-04-24 21:09:54 +01001680 echo charidx('a😊😊', 4, 0, 1) returns 2
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001681<
1682 Can also be used as a |method|: >
1683 GetName()->charidx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001684<
1685 Return type: |Number|
1686
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001687
1688chdir({dir}) *chdir()*
1689 Change the current working directory to {dir}. The scope of
1690 the directory change depends on the directory of the current
1691 window:
1692 - If the current window has a window-local directory
1693 (|:lcd|), then changes the window local directory.
1694 - Otherwise, if the current tabpage has a local
1695 directory (|:tcd|) then changes the tabpage local
1696 directory.
1697 - Otherwise, changes the global directory.
1698 {dir} must be a String.
1699 If successful, returns the previous working directory. Pass
1700 this to another chdir() to restore the directory.
1701 On failure, returns an empty string.
1702
1703 Example: >
1704 let save_dir = chdir(newdir)
1705 if save_dir != ""
1706 " ... do some work
1707 call chdir(save_dir)
1708 endif
1709
1710< Can also be used as a |method|: >
1711 GetDir()->chdir()
1712<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001713 Return type: |String|
1714
1715
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001716cindent({lnum}) *cindent()*
1717 Get the amount of indent for line {lnum} according the C
1718 indenting rules, as with 'cindent'.
1719 The indent is counted in spaces, the value of 'tabstop' is
1720 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001721 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001722 See |C-indenting|.
1723
1724 Can also be used as a |method|: >
1725 GetLnum()->cindent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001726<
1727 Return type: |Number|
1728
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001729
1730clearmatches([{win}]) *clearmatches()*
1731 Clears all matches previously defined for the current window
1732 by |matchadd()| and the |:match| commands.
1733 If {win} is specified, use the window with this number or
1734 window ID instead of the current window.
1735
1736 Can also be used as a |method|: >
1737 GetWin()->clearmatches()
1738<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001739 Return type: |Number|
1740
1741
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001742col({expr} [, {winid}]) *col()*
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001743 The result is a Number, which is the byte index of the column
zeertzjq02f3eba2024-06-12 20:45:24 +02001744 position given with {expr}.
1745 For accepted positions see |getpos()|.
zeertzjqd353d272024-06-13 23:00:25 +08001746 When {expr} is "$", it means the end of the cursor line, so
1747 the result is the number of bytes in the cursor line plus one.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001748 Additionally {expr} can be [lnum, col]: a |List| with the line
1749 and column number. Most useful when the column is "$", to get
1750 the last column of a specific line. When "lnum" or "col" is
1751 out of range then col() returns zero.
zeertzjq02f3eba2024-06-12 20:45:24 +02001752
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001753 With the optional {winid} argument the values are obtained for
1754 that window instead of the current window.
zeertzjq02f3eba2024-06-12 20:45:24 +02001755
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001756 To get the line number use |line()|. To get both use
1757 |getpos()|.
1758 For the screen column position use |virtcol()|. For the
1759 character position use |charcol()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02001760
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001761 Note that only marks in the current file can be used.
zeertzjq02f3eba2024-06-12 20:45:24 +02001762
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001763 Examples: >
1764 col(".") column of cursor
1765 col("$") length of cursor line plus one
1766 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001767 col("'" .. markname) column of mark markname
zeertzjq02f3eba2024-06-12 20:45:24 +02001768<
1769 The first column is 1. Returns 0 if {expr} is invalid or when
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001770 the window with ID {winid} is not found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001771 For an uppercase mark the column may actually be in another
1772 buffer.
1773 For the cursor position, when 'virtualedit' is active, the
1774 column is one higher if the cursor is after the end of the
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01001775 line. Also, when using a <Cmd> mapping the cursor isn't
1776 moved, this can be used to obtain the column in Insert mode: >
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001777 :imap <F2> <Cmd>echowin col(".")<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001778
1779< Can also be used as a |method|: >
1780 GetPos()->col()
1781<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001782 Return type: |Number|
1783
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001784
1785complete({startcol}, {matches}) *complete()* *E785*
1786 Set the matches for Insert mode completion.
1787 Can only be used in Insert mode. You need to use a mapping
1788 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1789 or with an expression mapping.
1790 {startcol} is the byte offset in the line where the completed
1791 text start. The text up to the cursor is the original text
1792 that will be replaced by the matches. Use col('.') for an
1793 empty string. "col('.') - 1" will replace one character by a
1794 match.
1795 {matches} must be a |List|. Each |List| item is one match.
1796 See |complete-items| for the kind of items that are possible.
1797 "longest" in 'completeopt' is ignored.
1798 Note that the after calling this function you need to avoid
1799 inserting anything that would cause completion to stop.
1800 The match can be selected with CTRL-N and CTRL-P as usual with
1801 Insert mode completion. The popup menu will appear if
1802 specified, see |ins-completion-menu|.
1803 Example: >
1804 inoremap <F5> <C-R>=ListMonths()<CR>
1805
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001806 func ListMonths()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001807 call complete(col('.'), ['January', 'February', 'March',
1808 \ 'April', 'May', 'June', 'July', 'August', 'September',
1809 \ 'October', 'November', 'December'])
1810 return ''
1811 endfunc
1812< This isn't very useful, but it shows how it works. Note that
1813 an empty string is returned to avoid a zero being inserted.
1814
1815 Can also be used as a |method|, the base is passed as the
1816 second argument: >
1817 GetMatches()->complete(col('.'))
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001818<
1819 Return type: |Number|
1820
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001821
1822complete_add({expr}) *complete_add()*
1823 Add {expr} to the list of matches. Only to be used by the
1824 function specified with the 'completefunc' option.
1825 Returns 0 for failure (empty string or out of memory),
1826 1 when the match was added, 2 when the match was already in
1827 the list.
1828 See |complete-functions| for an explanation of {expr}. It is
1829 the same as one item in the list that 'omnifunc' would return.
1830
1831 Can also be used as a |method|: >
1832 GetMoreMatches()->complete_add()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001833<
1834 Return type: |Number|
1835
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001836
1837complete_check() *complete_check()*
1838 Check for a key typed while looking for completion matches.
1839 This is to be used when looking for matches takes some time.
1840 Returns |TRUE| when searching for matches is to be aborted,
1841 zero otherwise.
1842 Only to be used by the function specified with the
1843 'completefunc' option.
1844
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001845 Return type: |Number|
1846
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001847
1848complete_info([{what}]) *complete_info()*
1849 Returns a |Dictionary| with information about Insert mode
1850 completion. See |ins-completion|.
1851 The items are:
1852 mode Current completion mode name string.
1853 See |complete_info_mode| for the values.
1854 pum_visible |TRUE| if popup menu is visible.
1855 See |pumvisible()|.
1856 items List of completion matches. Each item is a
1857 dictionary containing the entries "word",
1858 "abbr", "menu", "kind", "info" and "user_data".
1859 See |complete-items|.
1860 selected Selected item index. First index is zero.
1861 Index is -1 if no item is selected (showing
1862 typed text only, or the last completion after
1863 no item is selected when using the <Up> or
1864 <Down> keys)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01001865 inserted Inserted string. [NOT IMPLEMENTED YET]
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001866
1867 *complete_info_mode*
1868 mode values are:
1869 "" Not in completion mode
1870 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1871 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1872 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1873 |i_CTRL-X_CTRL-Y|
1874 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1875 "files" File names |i_CTRL-X_CTRL-F|
1876 "tags" Tags |i_CTRL-X_CTRL-]|
1877 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1878 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1879 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1880 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1881 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1882 "function" User defined completion |i_CTRL-X_CTRL-U|
1883 "omni" Omni completion |i_CTRL-X_CTRL-O|
1884 "spell" Spelling suggestions |i_CTRL-X_s|
1885 "eval" |complete()| completion
1886 "unknown" Other internal modes
1887
1888 If the optional {what} list argument is supplied, then only
1889 the items listed in {what} are returned. Unsupported items in
1890 {what} are silently ignored.
1891
1892 To get the position and size of the popup menu, see
1893 |pum_getpos()|. It's also available in |v:event| during the
1894 |CompleteChanged| event.
1895
Bram Moolenaar016188f2022-06-06 20:52:59 +01001896 Returns an empty |Dictionary| on error.
1897
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001898 Examples: >
1899 " Get all items
1900 call complete_info()
1901 " Get only 'mode'
1902 call complete_info(['mode'])
1903 " Get only 'mode' and 'pum_visible'
1904 call complete_info(['mode', 'pum_visible'])
1905
1906< Can also be used as a |method|: >
1907 GetItems()->complete_info()
1908<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001909 Return type: dict<any>
1910
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001911 *confirm()*
1912confirm({msg} [, {choices} [, {default} [, {type}]]])
1913 confirm() offers the user a dialog, from which a choice can be
1914 made. It returns the number of the choice. For the first
1915 choice this is 1.
1916 Note: confirm() is only supported when compiled with dialog
glepnirdf461152024-04-04 22:23:29 +02001917 support, see |+dialog_con| |+dialog_con_gui| and |+dialog_gui|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001918
1919 {msg} is displayed in a |dialog| with {choices} as the
1920 alternatives. When {choices} is missing or empty, "&OK" is
1921 used (and translated).
1922 {msg} is a String, use '\n' to include a newline. Only on
1923 some systems the string is wrapped when it doesn't fit.
1924
1925 {choices} is a String, with the individual choices separated
1926 by '\n', e.g. >
1927 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1928< The letter after the '&' is the shortcut key for that choice.
1929 Thus you can type 'c' to select "Cancel". The shortcut does
1930 not need to be the first letter: >
1931 confirm("file has been modified", "&Save\nSave &All")
1932< For the console, the first letter of each choice is used as
1933 the default shortcut key. Case is ignored.
1934
1935 The optional {default} argument is the number of the choice
1936 that is made if the user hits <CR>. Use 1 to make the first
1937 choice the default one. Use 0 to not set a default. If
1938 {default} is omitted, 1 is used.
1939
1940 The optional {type} String argument gives the type of dialog.
1941 This is only used for the icon of the GTK, Mac, Motif and
1942 Win32 GUI. It can be one of these values: "Error",
1943 "Question", "Info", "Warning" or "Generic". Only the first
1944 character is relevant. When {type} is omitted, "Generic" is
1945 used.
1946
1947 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1948 or another valid interrupt key, confirm() returns 0.
1949
1950 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01001951 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001952 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01001953 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001954 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001955 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001956 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001957 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001958 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01001959 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001960< In a GUI dialog, buttons are used. The layout of the buttons
1961 depends on the 'v' flag in 'guioptions'. If it is included,
1962 the buttons are always put vertically. Otherwise, confirm()
1963 tries to put the buttons in one horizontal line. If they
1964 don't fit, a vertical layout is used anyway. For some systems
1965 the horizontal layout is always used.
1966
1967 Can also be used as a |method|in: >
1968 BuildMessage()->confirm("&Yes\n&No")
1969<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001970 Return type: |Number|
1971
1972
1973copy({expr}) *copy()*
1974 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001975 different from using {expr} directly.
1976 When {expr} is a |List| a shallow copy is created. This means
1977 that the original |List| can be changed without changing the
1978 copy, and vice versa. But the items are identical, thus
1979 changing an item changes the contents of both |Lists|.
1980 A |Dictionary| is copied in a similar way as a |List|.
1981 Also see |deepcopy()|.
1982 Can also be used as a |method|: >
1983 mylist->copy()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001984<
1985 Return type: any, depending on {expr}
1986
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001987
1988cos({expr}) *cos()*
1989 Return the cosine of {expr}, measured in radians, as a |Float|.
1990 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001991 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001992 Examples: >
1993 :echo cos(100)
1994< 0.862319 >
1995 :echo cos(-4.01)
1996< -0.646043
1997
1998 Can also be used as a |method|: >
1999 Compute()->cos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002000<
2001 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002002
2003
2004cosh({expr}) *cosh()*
2005 Return the hyperbolic cosine of {expr} as a |Float| in the range
2006 [1, inf].
2007 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002008 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002009 Examples: >
2010 :echo cosh(0.5)
2011< 1.127626 >
2012 :echo cosh(-0.5)
2013< -1.127626
2014
2015 Can also be used as a |method|: >
2016 Compute()->cosh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002017<
2018 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002019
2020
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07002021count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002022 Return the number of times an item with value {expr} appears
2023 in |String|, |List| or |Dictionary| {comp}.
2024
2025 If {start} is given then start with the item with this index.
2026 {start} can only be used with a |List|.
2027
2028 When {ic} is given and it's |TRUE| then case is ignored.
2029
2030 When {comp} is a string then the number of not overlapping
2031 occurrences of {expr} is returned. Zero is returned when
2032 {expr} is an empty string.
2033
2034 Can also be used as a |method|: >
2035 mylist->count(val)
2036<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002037 Return type: |Number|
2038
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002039 *cscope_connection()*
2040cscope_connection([{num} , {dbpath} [, {prepend}]])
2041 Checks for the existence of a |cscope| connection. If no
2042 parameters are specified, then the function returns:
2043 0, if cscope was not available (not compiled in), or
2044 if there are no cscope connections;
2045 1, if there is at least one cscope connection.
2046
2047 If parameters are specified, then the value of {num}
2048 determines how existence of a cscope connection is checked:
2049
2050 {num} Description of existence check
2051 ----- ------------------------------
2052 0 Same as no parameters (e.g., "cscope_connection()").
2053 1 Ignore {prepend}, and use partial string matches for
2054 {dbpath}.
2055 2 Ignore {prepend}, and use exact string matches for
2056 {dbpath}.
2057 3 Use {prepend}, use partial string matches for both
2058 {dbpath} and {prepend}.
2059 4 Use {prepend}, use exact string matches for both
2060 {dbpath} and {prepend}.
2061
2062 Note: All string comparisons are case sensitive!
2063
2064 Examples. Suppose we had the following (from ":cs show"): >
2065
2066 # pid database name prepend path
2067 0 27664 cscope.out /usr/local
2068<
2069 Invocation Return Val ~
2070 ---------- ---------- >
2071 cscope_connection() 1
2072 cscope_connection(1, "out") 1
2073 cscope_connection(2, "out") 0
2074 cscope_connection(3, "out") 0
2075 cscope_connection(3, "out", "local") 1
2076 cscope_connection(4, "out") 0
2077 cscope_connection(4, "out", "local") 0
2078 cscope_connection(4, "cscope.out", "/usr/local") 1
2079<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002080 Return type: |Number|
2081
2082
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002083cursor({lnum}, {col} [, {off}]) *cursor()*
2084cursor({list})
2085 Positions the cursor at the column (byte count) {col} in the
2086 line {lnum}. The first column is one.
2087
2088 When there is one argument {list} this is used as a |List|
2089 with two, three or four item:
2090 [{lnum}, {col}]
2091 [{lnum}, {col}, {off}]
2092 [{lnum}, {col}, {off}, {curswant}]
2093 This is like the return value of |getpos()| or |getcurpos()|,
2094 but without the first item.
2095
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01002096 To position the cursor using {col} as the character count, use
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002097 |setcursorcharpos()|.
2098
2099 Does not change the jumplist.
Bram Moolenaar7c6cd442022-10-11 21:54:04 +01002100 {lnum} is used like with |getline()|, except that if {lnum} is
2101 zero, the cursor will stay in the current line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002102 If {lnum} is greater than the number of lines in the buffer,
2103 the cursor will be positioned at the last line in the buffer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002104 If {col} is greater than the number of bytes in the line,
2105 the cursor will be positioned at the last character in the
2106 line.
2107 If {col} is zero, the cursor will stay in the current column.
2108 If {curswant} is given it is used to set the preferred column
2109 for vertical movement. Otherwise {col} is used.
2110
2111 When 'virtualedit' is used {off} specifies the offset in
2112 screen columns from the start of the character. E.g., a
2113 position within a <Tab> or after the last character.
2114 Returns 0 when the position could be set, -1 otherwise.
2115
2116 Can also be used as a |method|: >
2117 GetCursorPos()->cursor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002118<
2119 Return type: |Number|
2120
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002121
2122debugbreak({pid}) *debugbreak()*
2123 Specifically used to interrupt a program being debugged. It
2124 will cause process {pid} to get a SIGTRAP. Behavior for other
2125 processes is undefined. See |terminal-debugger|.
2126 {only available on MS-Windows}
2127
Bram Moolenaar016188f2022-06-06 20:52:59 +01002128 Returns |TRUE| if successfully interrupted the program.
2129 Otherwise returns |FALSE|.
2130
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002131 Can also be used as a |method|: >
2132 GetPid()->debugbreak()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002133<
2134 Return type: |Number|
2135
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002136
2137deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
2138 Make a copy of {expr}. For Numbers and Strings this isn't
2139 different from using {expr} directly.
2140 When {expr} is a |List| a full copy is created. This means
2141 that the original |List| can be changed without changing the
2142 copy, and vice versa. When an item is a |List| or
2143 |Dictionary|, a copy for it is made, recursively. Thus
2144 changing an item in the copy does not change the contents of
2145 the original |List|.
2146 A |Dictionary| is copied in a similar way as a |List|.
2147
2148 When {noref} is omitted or zero a contained |List| or
2149 |Dictionary| is only copied once. All references point to
2150 this single copy. With {noref} set to 1 every occurrence of a
2151 |List| or |Dictionary| results in a new copy. This also means
2152 that a cyclic reference causes deepcopy() to fail.
2153 *E724*
2154 Nesting is possible up to 100 levels. When there is an item
2155 that refers back to a higher level making a deep copy with
2156 {noref} set to 1 will fail.
2157 Also see |copy()|.
2158
2159 Can also be used as a |method|: >
2160 GetObject()->deepcopy()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002161<
2162 Return type: any, depending on {expr}
2163
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002164
2165delete({fname} [, {flags}]) *delete()*
2166 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002167 name {fname}.
2168
2169 This also works when {fname} is a symbolic link. The symbolic
2170 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002171
2172 When {flags} is "d": Deletes the directory by the name
2173 {fname}. This fails when directory {fname} is not empty.
2174
2175 When {flags} is "rf": Deletes the directory by the name
2176 {fname} and everything in it, recursively. BE CAREFUL!
2177 Note: on MS-Windows it is not possible to delete a directory
2178 that is being used.
2179
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002180 The result is a Number, which is 0/false if the delete
2181 operation was successful and -1/true when the deletion failed
2182 or partly failed.
2183
2184 Use |remove()| to delete an item from a |List|.
2185 To delete a line from the buffer use |:delete| or
2186 |deletebufline()|.
2187
2188 Can also be used as a |method|: >
2189 GetName()->delete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002190<
2191 Return type: |Number|
2192
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002193
2194deletebufline({buf}, {first} [, {last}]) *deletebufline()*
2195 Delete lines {first} to {last} (inclusive) from buffer {buf}.
2196 If {last} is omitted then delete line {first} only.
2197 On success 0 is returned, on failure 1 is returned.
2198
2199 This function works only for loaded buffers. First call
2200 |bufload()| if needed.
2201
2202 For the use of {buf}, see |bufname()| above.
2203
2204 {first} and {last} are used like with |getline()|. Note that
2205 when using |line()| this refers to the current buffer. Use "$"
2206 to refer to the last line in buffer {buf}.
2207
2208 Can also be used as a |method|: >
2209 GetBuffer()->deletebufline(1)
2210<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002211 Return type: |Number|
2212
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002213 *did_filetype()*
2214did_filetype() Returns |TRUE| when autocommands are being executed and the
2215 FileType event has been triggered at least once. Can be used
2216 to avoid triggering the FileType event again in the scripts
2217 that detect the file type. |FileType|
2218 Returns |FALSE| when `:setf FALLBACK` was used.
2219 When editing another file, the counter is reset, thus this
2220 really checks if the FileType event has been triggered for the
2221 current buffer. This allows an autocommand that starts
2222 editing another buffer to set 'filetype' and load a syntax
2223 file.
2224
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002225 Return type: |Number|
2226
2227
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002228diff({fromlist}, {tolist} [, {options}]) *diff()*
2229 Returns a String or a List containing the diff between the
2230 strings in {fromlist} and {tolist}. Uses the Vim internal
2231 diff library to compute the diff.
2232
2233 *E106*
2234 The optional "output" item in {options} specifies the returned
2235 diff format. The following values are supported:
2236 indices Return a List of the starting and ending
2237 indices and a count of the strings in each
2238 diff hunk.
2239 unified Return the unified diff output as a String.
2240 This is the default.
2241
2242 If the "output" item in {options} is "indices", then a List is
2243 returned. Each List item contains a Dict with the following
2244 items for each diff hunk:
2245 from_idx start index in {fromlist} for this diff hunk.
2246 from_count number of strings in {fromlist} that are
2247 added/removed/modified in this diff hunk.
2248 to_idx start index in {tolist} for this diff hunk.
2249 to_count number of strings in {tolist} that are
2250 added/removed/modified in this diff hunk.
2251
2252 The {options} Dict argument also specifies diff options
2253 (similar to 'diffopt') and supports the following items:
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002254 algorithm Dict specifying the diff algorithm to
2255 use. Supported boolean items are
2256 "myers", "minimal", "patience" and
2257 "histogram".
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002258 context diff context length. Default is 0.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002259 iblank ignore changes where lines are all
2260 blank.
2261 icase ignore changes in case of text.
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002262 indent-heuristic use the indent heuristic for the
2263 internal diff library.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002264 iwhite ignore changes in amount of white
2265 space.
2266 iwhiteall ignore all white space changes.
2267 iwhiteeol ignore white space changes at end of
2268 line.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002269 For more information about these options, refer to 'diffopt'.
2270
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002271 To compute the unified diff, all the items in {fromlist} are
2272 concatenated into a string using a newline separator and the
2273 same for {tolist}. The unified diff output uses line numbers.
2274
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002275 Returns an empty List or String if {fromlist} and {tolist} are
2276 identical.
2277
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002278 Examples: >
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002279 :echo diff(['abc'], ['xxx'])
2280 @@ -1 +1 @@
2281 -abc
2282 +xxx
2283
2284 :echo diff(['abc'], ['xxx'], {'output': 'indices'})
2285 [{'from_idx': 0, 'from_count': 1, 'to_idx': 0, 'to_count': 1}]
2286 :echo diff(readfile('oldfile'), readfile('newfile'))
2287 :echo diff(getbufline(5, 1, '$'), getbufline(6, 1, '$'))
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002288<
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002289 For more examples, refer to |diff-func-examples|
2290
2291 Can also be used as a |method|: >
2292 GetFromList->diff(to_list)
2293<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002294 Return type: |String| or list<dict<number>> or list<any>
2295 depending on {options}
2296
2297
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002298diff_filler({lnum}) *diff_filler()*
2299 Returns the number of filler lines above line {lnum}.
2300 These are the lines that were inserted at this point in
2301 another diff'ed window. These filler lines are shown in the
2302 display but don't exist in the buffer.
2303 {lnum} is used like with |getline()|. Thus "." is the current
2304 line, "'m" mark m, etc.
2305 Returns 0 if the current window is not in diff mode.
2306
2307 Can also be used as a |method|: >
2308 GetLnum()->diff_filler()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002309<
2310 Return type: |Number|
2311
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002312
2313diff_hlID({lnum}, {col}) *diff_hlID()*
2314 Returns the highlight ID for diff mode at line {lnum} column
2315 {col} (byte index). When the current line does not have a
2316 diff change zero is returned.
2317 {lnum} is used like with |getline()|. Thus "." is the current
2318 line, "'m" mark m, etc.
2319 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2320 line.
2321 The highlight ID can be used with |synIDattr()| to obtain
2322 syntax information about the highlighting.
2323
2324 Can also be used as a |method|: >
2325 GetLnum()->diff_hlID(col)
2326<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002327 Return type: |Number|
2328
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002329
2330digraph_get({chars}) *digraph_get()* *E1214*
2331 Return the digraph of {chars}. This should be a string with
2332 exactly two characters. If {chars} are not just two
2333 characters, or the digraph of {chars} does not exist, an error
2334 is given and an empty string is returned.
2335
2336 The character will be converted from Unicode to 'encoding'
2337 when needed. This does require the conversion to be
2338 available, it might fail.
2339
2340 Also see |digraph_getlist()|.
2341
2342 Examples: >
2343 " Get a built-in digraph
2344 :echo digraph_get('00') " Returns '∞'
2345
2346 " Get a user-defined digraph
2347 :call digraph_set('aa', 'あ')
2348 :echo digraph_get('aa') " Returns 'あ'
2349<
2350 Can also be used as a |method|: >
2351 GetChars()->digraph_get()
2352<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002353 Return type: |String|
2354
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002355 This function works only when compiled with the |+digraphs|
2356 feature. If this feature is disabled, this function will
2357 display an error message.
2358
2359
2360digraph_getlist([{listall}]) *digraph_getlist()*
2361 Return a list of digraphs. If the {listall} argument is given
2362 and it is TRUE, return all digraphs, including the default
2363 digraphs. Otherwise, return only user-defined digraphs.
2364
2365 The characters will be converted from Unicode to 'encoding'
2366 when needed. This does require the conservation to be
2367 available, it might fail.
2368
2369 Also see |digraph_get()|.
2370
2371 Examples: >
2372 " Get user-defined digraphs
2373 :echo digraph_getlist()
2374
2375 " Get all the digraphs, including default digraphs
2376 :echo digraph_getlist(1)
2377<
2378 Can also be used as a |method|: >
2379 GetNumber()->digraph_getlist()
2380<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002381 Return type: list<list<string>>
2382
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002383 This function works only when compiled with the |+digraphs|
2384 feature. If this feature is disabled, this function will
2385 display an error message.
2386
2387
Bram Moolenaara2baa732022-02-04 16:09:54 +00002388digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002389 Add digraph {chars} to the list. {chars} must be a string
2390 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002391 encoded character. *E1215*
2392 Be careful, composing characters are NOT ignored. This
2393 function is similar to |:digraphs| command, but useful to add
2394 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002395
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002396 The function returns v:true if |digraph| is registered. If
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002397 this fails an error message is given and v:false is returned.
2398
2399 If you want to define multiple digraphs at once, you can use
2400 |digraph_setlist()|.
2401
2402 Example: >
2403 call digraph_set(' ', 'あ')
2404<
2405 Can be used as a |method|: >
2406 GetString()->digraph_set('あ')
2407<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002408 Return type: |vim9-boolean|
2409
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002410 This function works only when compiled with the |+digraphs|
2411 feature. If this feature is disabled, this function will
2412 display an error message.
2413
2414
2415digraph_setlist({digraphlist}) *digraph_setlist()*
2416 Similar to |digraph_set()| but this function can add multiple
2417 digraphs at once. {digraphlist} is a list composed of lists,
2418 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002419 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002420 Example: >
2421 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2422<
2423 It is similar to the following: >
2424 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2425 call digraph_set(chars, digraph)
2426 endfor
2427< Except that the function returns after the first error,
2428 following digraphs will not be added.
2429
2430 Can be used as a |method|: >
2431 GetList()->digraph_setlist()
2432<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002433 Return type: |vim9-boolean|
2434
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002435 This function works only when compiled with the |+digraphs|
2436 feature. If this feature is disabled, this function will
2437 display an error message.
2438
2439
2440echoraw({string}) *echoraw()*
2441 Output {string} as-is, including unprintable characters.
2442 This can be used to output a terminal code. For example, to
2443 disable modifyOtherKeys: >
2444 call echoraw(&t_TE)
2445< and to enable it again: >
2446 call echoraw(&t_TI)
2447< Use with care, you can mess up the terminal this way.
2448
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002449 Return type: |Number|
2450
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002451
2452empty({expr}) *empty()*
2453 Return the Number 1 if {expr} is empty, zero otherwise.
2454 - A |List| or |Dictionary| is empty when it does not have any
2455 items.
2456 - A |String| is empty when its length is zero.
2457 - A |Number| and |Float| are empty when their value is zero.
2458 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2459 - A |Job| is empty when it failed to start.
2460 - A |Channel| is empty when it is closed.
2461 - A |Blob| is empty when its length is zero.
mityu7f0bba22024-03-29 10:14:41 +01002462 - An |Object| is empty, when the empty() method in the object
2463 (if present) returns true. |object-empty()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002464
2465 For a long |List| this is much faster than comparing the
2466 length with zero.
2467
2468 Can also be used as a |method|: >
2469 mylist->empty()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002470<
2471 Return type: |Number|
2472
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002473
2474environ() *environ()*
2475 Return all of environment variables as dictionary. You can
2476 check if an environment variable exists like this: >
2477 :echo has_key(environ(), 'HOME')
2478< Note that the variable name may be CamelCase; to ignore case
2479 use this: >
2480 :echo index(keys(environ()), 'HOME', 0, 1) != -1
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002481<
2482 Return type: dict<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002483
Bram Moolenaar416bd912023-07-07 23:19:18 +01002484
2485err_teapot([{expr}]) *err_teapot()*
2486 Produce an error with number 418, needed for implementation of
Christian Brabandtee17b6f2023-09-09 11:23:50 +02002487 RFC 2324.
Bram Moolenaar416bd912023-07-07 23:19:18 +01002488 If {expr} is present and it is TRUE error 503 is given,
2489 indicating that coffee is temporarily not available.
2490 If {expr} is present it must be a String.
2491
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002492 Return type: |Number|
2493
Bram Moolenaar416bd912023-07-07 23:19:18 +01002494
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002495escape({string}, {chars}) *escape()*
2496 Escape the characters in {chars} that occur in {string} with a
2497 backslash. Example: >
2498 :echo escape('c:\program files\vim', ' \')
2499< results in: >
2500 c:\\program\ files\\vim
2501< Also see |shellescape()| and |fnameescape()|.
2502
2503 Can also be used as a |method|: >
2504 GetText()->escape(' \')
2505<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002506 Return type: |String|
2507
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002508 *eval()*
2509eval({string}) Evaluate {string} and return the result. Especially useful to
2510 turn the result of |string()| back into the original value.
2511 This works for Numbers, Floats, Strings, Blobs and composites
2512 of them. Also works for |Funcref|s that refer to existing
Aliaksei Budavei95740222024-04-04 23:05:33 +03002513 functions. In |Vim9| script, it can be used to obtain |enum|
2514 values from their fully qualified names.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002515
2516 Can also be used as a |method|: >
2517 argv->join()->eval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002518<
2519 Return type: any, depending on {string}
2520
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002521
2522eventhandler() *eventhandler()*
2523 Returns 1 when inside an event handler. That is that Vim got
2524 interrupted while waiting for the user to type a character,
2525 e.g., when dropping a file on Vim. This means interactive
2526 commands cannot be used. Otherwise zero is returned.
2527
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002528 Return type: |Number|
2529
2530
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002531executable({expr}) *executable()*
2532 This function checks if an executable with the name {expr}
2533 exists. {expr} must be the name of the program without any
2534 arguments.
zeertzjq0cc5dce2024-08-08 21:12:15 +02002535
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002536 executable() uses the value of $PATH and/or the normal
zeertzjq0cc5dce2024-08-08 21:12:15 +02002537 searchpath for programs.
2538 *PATHEXT*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002539 On MS-Windows the ".exe", ".bat", etc. can optionally be
2540 included. Then the extensions in $PATHEXT are tried. Thus if
2541 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2542 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2543 by itself can be used in $PATHEXT to try using the name
2544 without an extension. When 'shell' looks like a Unix shell,
2545 then the name is also tried without adding an extension.
2546 On MS-Windows it only checks if the file exists and is not a
2547 directory, not if it's really executable.
zeertzjq0cc5dce2024-08-08 21:12:15 +02002548 On MS-Windows an executable in the same directory as the Vim
2549 executable is always found. Since this directory is added to
2550 $PATH it should also work to execute it |win32-PATH|.
2551 *NoDefaultCurrentDirectoryInExePath*
2552 On MS-Windows an executable in Vim's current working directory
2553 is also normally found, but this can be disabled by setting
2554 the $NoDefaultCurrentDirectoryInExePath environment variable.
2555
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002556 The result is a Number:
2557 1 exists
2558 0 does not exist
2559 -1 not implemented on this system
2560 |exepath()| can be used to get the full path of an executable.
2561
2562 Can also be used as a |method|: >
2563 GetCommand()->executable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002564<
2565 Return type: |Number|
2566
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002567
2568execute({command} [, {silent}]) *execute()*
2569 Execute an Ex command or commands and return the output as a
2570 string.
2571 {command} can be a string or a List. In case of a List the
2572 lines are executed one by one.
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002573 This is more or less equivalent to: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002574 redir => var
2575 {command}
2576 redir END
Bram Moolenaar71badf92023-04-22 22:40:14 +01002577< Except that line continuation in {command} is not recognized.
2578
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002579 The optional {silent} argument can have these values:
2580 "" no `:silent` used
2581 "silent" `:silent` used
2582 "silent!" `:silent!` used
2583 The default is "silent". Note that with "silent!", unlike
2584 `:redir`, error messages are dropped. When using an external
2585 command the screen may be messed up, use `system()` instead.
2586 *E930*
2587 It is not possible to use `:redir` anywhere in {command}.
2588
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002589 To get a list of lines use `split()` on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002590 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002591
2592< To execute a command in another window than the current one
2593 use `win_execute()`.
2594
2595 When used recursively the output of the recursive call is not
2596 included in the output of the higher level call.
2597
2598 Can also be used as a |method|: >
2599 GetCommand()->execute()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002600<
Marius Gedminasc98bfb92024-06-19 19:59:23 +02002601 Return type: |String|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002602
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002603
2604exepath({expr}) *exepath()*
2605 If {expr} is an executable and is either an absolute path, a
2606 relative path or found in $PATH, return the full path.
2607 Note that the current directory is used when {expr} starts
2608 with "./", which may be a problem for Vim: >
2609 echo exepath(v:progpath)
2610< If {expr} cannot be found in $PATH or is not executable then
2611 an empty string is returned.
2612
2613 Can also be used as a |method|: >
2614 GetCommand()->exepath()
2615<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002616 Return type: |String|
2617
2618
2619exists({expr}) *exists()*
2620 The result is a Number, which is |TRUE| if {expr} is defined,
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002621 zero otherwise.
2622
2623 Note: In a compiled |:def| function the evaluation is done at
2624 runtime. Use `exists_compiled()` to evaluate the expression
2625 at compile time.
2626
2627 For checking for a supported feature use |has()|.
2628 For checking if a file exists use |filereadable()|.
2629
2630 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002631 varname internal variable (see
2632 dict.key |internal-variables|). Also works
2633 list[i] for |curly-braces-names|, |Dictionary|
Yegappan Lakshmanana2ebb6e2024-02-25 08:40:10 +01002634 import.Func entries, |List| items, class and
2635 class.Func object methods, imported items, etc.
2636 object.Func Does not work for local variables in a
2637 class.varname compiled `:def` function.
2638 object.varname Also works for a function in |Vim9|
Bram Moolenaar944697a2022-02-20 19:48:20 +00002639 script, since it can be used as a
2640 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002641 Beware that evaluating an index may
2642 cause an error message for an invalid
2643 expression. E.g.: >
2644 :let l = [1, 2, 3]
2645 :echo exists("l[5]")
2646< 0 >
2647 :echo exists("l[xx]")
2648< E121: Undefined variable: xx
2649 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002650 &option-name Vim option (only checks if it exists,
2651 not if it really works)
2652 +option-name Vim option that works.
2653 $ENVNAME environment variable (could also be
2654 done by comparing with an empty
2655 string)
2656 *funcname built-in function (see |functions|)
2657 or user defined function (see
2658 |user-functions|) that is implemented.
2659 Also works for a variable that is a
2660 Funcref.
2661 ?funcname built-in function that could be
2662 implemented; to be used to check if
2663 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002664 :cmdname Ex command: built-in command, user
2665 command or command modifier |:command|.
2666 Returns:
2667 1 for match with start of a command
2668 2 full match with a command
2669 3 matches several user commands
2670 To check for a supported command
2671 always check the return value to be 2.
2672 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002673 :3match The |:3match| command (but you
2674 probably should not use it, it is
2675 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002676 #event autocommand defined for this event
2677 #event#pattern autocommand defined for this event and
2678 pattern (the pattern is taken
2679 literally and compared to the
2680 autocommand patterns character by
2681 character)
2682 #group autocommand group exists
2683 #group#event autocommand defined for this group and
2684 event.
2685 #group#event#pattern
2686 autocommand defined for this group,
2687 event and pattern.
2688 ##event autocommand for this event is
2689 supported.
2690
2691 Examples: >
2692 exists("&shortname")
2693 exists("$HOSTNAME")
2694 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002695 exists("*s:MyFunc") " only for legacy script
2696 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002697 exists("bufcount")
2698 exists(":Make")
2699 exists("#CursorHold")
2700 exists("#BufReadPre#*.gz")
2701 exists("#filetypeindent")
2702 exists("#filetypeindent#FileType")
2703 exists("#filetypeindent#FileType#*")
2704 exists("##ColorScheme")
2705< There must be no space between the symbol (&/$/*/#) and the
2706 name.
2707 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002708 a few cases this is ignored. That may become stricter in the
2709 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002710 Working example: >
2711 exists(":make")
2712< NOT working example: >
2713 exists(":make install")
2714
2715< Note that the argument must be a string, not the name of the
2716 variable itself. For example: >
2717 exists(bufcount)
2718< This doesn't check for existence of the "bufcount" variable,
2719 but gets the value of "bufcount", and checks if that exists.
2720
2721 Can also be used as a |method|: >
2722 Varname()->exists()
2723<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002724 Return type: |String|
2725
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002726
2727exists_compiled({expr}) *exists_compiled()*
2728 Like `exists()` but evaluated at compile time. This is useful
2729 to skip a block where a function is used that would otherwise
2730 give an error: >
2731 if exists_compiled('*ThatFunction')
2732 ThatFunction('works')
2733 endif
2734< If `exists()` were used then a compilation error would be
2735 given if ThatFunction() is not defined.
2736
2737 {expr} must be a literal string. *E1232*
2738 Can only be used in a |:def| function. *E1233*
2739 This does not work to check for arguments or local variables.
2740
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002741 Return type: |String|
2742
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002743
2744exp({expr}) *exp()*
2745 Return the exponential of {expr} as a |Float| in the range
2746 [0, inf].
2747 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002748 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002749 Examples: >
2750 :echo exp(2)
2751< 7.389056 >
2752 :echo exp(-1)
2753< 0.367879
2754
2755 Can also be used as a |method|: >
2756 Compute()->exp()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002757<
2758 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002759
2760
2761expand({string} [, {nosuf} [, {list}]]) *expand()*
2762 Expand wildcards and the following special keywords in
2763 {string}. 'wildignorecase' applies.
2764
2765 If {list} is given and it is |TRUE|, a List will be returned.
2766 Otherwise the result is a String and when there are several
2767 matches, they are separated by <NL> characters. [Note: in
2768 version 5.0 a space was used, which caused problems when a
2769 file name contains a space]
2770
2771 If the expansion fails, the result is an empty string. A name
2772 for a non-existing file is not included, unless {string} does
2773 not start with '%', '#' or '<', see below.
2774
Christian Brabandtec9c3262024-02-21 20:40:05 +01002775 For a |:terminal| window '%' expands to a '!' followed by
h-east53753f62024-05-05 18:42:31 +02002776 the command or shell that is run. |terminal-bufname|
Christian Brabandtec9c3262024-02-21 20:40:05 +01002777
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002778 When {string} starts with '%', '#' or '<', the expansion is
2779 done like for the |cmdline-special| variables with their
2780 associated modifiers. Here is a short overview:
2781
2782 % current file name
2783 # alternate file name
2784 #n alternate file name n
2785 <cfile> file name under the cursor
2786 <afile> autocmd file name
2787 <abuf> autocmd buffer number (as a String!)
2788 <amatch> autocmd matched name
2789 <cexpr> C expression under the cursor
2790 <sfile> sourced script file or function name
2791 <slnum> sourced script line number or function
2792 line number
2793 <sflnum> script file line number, also when in
2794 a function
2795 <SID> "<SNR>123_" where "123" is the
2796 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002797 <script> sourced script file, or script file
2798 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002799 <stack> call stack
2800 <cword> word under the cursor
2801 <cWORD> WORD under the cursor
2802 <client> the {clientid} of the last received
2803 message |server2client()|
2804 Modifiers:
2805 :p expand to full path
2806 :h head (last path component removed)
2807 :t tail (last path component only)
2808 :r root (one extension removed)
2809 :e extension only
2810
2811 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002812 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002813< Note that when expanding a string that starts with '%', '#' or
2814 '<', any following text is ignored. This does NOT work: >
2815 :let doesntwork = expand("%:h.bak")
2816< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002817 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002818< Also note that expanding "<cfile>" and others only returns the
2819 referenced file name without further expansion. If "<cfile>"
2820 is "~/.cshrc", you need to do another expand() to have the
2821 "~/" expanded into the path of the home directory: >
2822 :echo expand(expand("<cfile>"))
2823<
2824 There cannot be white space between the variables and the
2825 following modifier. The |fnamemodify()| function can be used
2826 to modify normal file names.
2827
2828 When using '%' or '#', and the current or alternate file name
2829 is not defined, an empty string is used. Using "%:p" in a
2830 buffer with no name, results in the current directory, with a
2831 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01002832 When 'verbose' is set then expanding '%', '#' and <> items
2833 will result in an error message if the argument cannot be
2834 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002835
2836 When {string} does not start with '%', '#' or '<', it is
2837 expanded like a file name is expanded on the command line.
2838 'suffixes' and 'wildignore' are used, unless the optional
2839 {nosuf} argument is given and it is |TRUE|.
2840 Names for non-existing files are included. The "**" item can
2841 be used to search in a directory tree. For example, to find
2842 all "README" files in the current directory and below: >
2843 :echo expand("**/README")
2844<
2845 expand() can also be used to expand variables and environment
2846 variables that are only known in a shell. But this can be
2847 slow, because a shell may be used to do the expansion. See
2848 |expr-env-expand|.
2849 The expanded variable is still handled like a list of file
2850 names. When an environment variable cannot be expanded, it is
2851 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2852 "$FOOBAR".
2853
2854 See |glob()| for finding existing files. See |system()| for
2855 getting the raw output of an external command.
2856
2857 Can also be used as a |method|: >
2858 Getpattern()->expand()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002859<
2860 Return type: |String| or list<string> depending on {list}
2861
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002862
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002863expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002864 Expand special items in String {string} like what is done for
2865 an Ex command such as `:edit`. This expands special keywords,
2866 like with |expand()|, and environment variables, anywhere in
2867 {string}. "~user" and "~/path" are only expanded at the
2868 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002869
2870 The following items are supported in the {options} Dict
2871 argument:
2872 errmsg If set to TRUE, error messages are displayed
2873 if an error is encountered during expansion.
2874 By default, error messages are not displayed.
2875
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002876 Returns the expanded string. If an error is encountered
2877 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002878
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002879 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002880 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002881 make /path/runtime/doc/builtin.o
2882 :echo expandcmd('make %<.o', {'errmsg': v:true})
2883<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002884 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002885 GetCommand()->expandcmd()
2886<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002887 Return type: |String| or list<string> depending on {list}
2888
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002889extend({expr1}, {expr2} [, {expr3}]) *extend()*
2890 {expr1} and {expr2} must be both |Lists| or both
2891 |Dictionaries|.
2892
2893 If they are |Lists|: Append {expr2} to {expr1}.
2894 If {expr3} is given insert the items of {expr2} before the
2895 item with index {expr3} in {expr1}. When {expr3} is zero
2896 insert before the first item. When {expr3} is equal to
2897 len({expr1}) then {expr2} is appended.
2898 Examples: >
2899 :echo sort(extend(mylist, [7, 5]))
2900 :call extend(mylist, [2, 3], 1)
2901< When {expr1} is the same List as {expr2} then the number of
2902 items copied is equal to the original length of the List.
2903 E.g., when {expr3} is 1 you get N new copies of the first item
2904 (where N is the original length of the List).
2905 Use |add()| to concatenate one item to a list. To concatenate
2906 two lists into a new list use the + operator: >
2907 :let newlist = [1, 2, 3] + [4, 5]
2908<
2909 If they are |Dictionaries|:
2910 Add all entries from {expr2} to {expr1}.
2911 If a key exists in both {expr1} and {expr2} then {expr3} is
2912 used to decide what to do:
2913 {expr3} = "keep": keep the value of {expr1}
2914 {expr3} = "force": use the value of {expr2}
2915 {expr3} = "error": give an error message *E737*
2916 When {expr3} is omitted then "force" is assumed.
2917
2918 {expr1} is changed when {expr2} is not empty. If necessary
2919 make a copy of {expr1} first.
2920 {expr2} remains unchanged.
2921 When {expr1} is locked and {expr2} is not empty the operation
2922 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002923 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002924
2925 Can also be used as a |method|: >
2926 mylist->extend(otherlist)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002927<
2928 Return type: list<{type}> or dict<{type}> depending on {expr1}
2929 and {expr2}, in case of error: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002930
2931
2932extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2933 Like |extend()| but instead of adding items to {expr1} a new
2934 List or Dictionary is created and returned. {expr1} remains
Bram Moolenaardd60c362023-02-27 15:49:53 +00002935 unchanged.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002936
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002937 Return type: list<{type}> or dict<{type}> depending on {expr1}
2938 and {expr2}, in case of error: |Number|
2939
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002940
2941feedkeys({string} [, {mode}]) *feedkeys()*
2942 Characters in {string} are queued for processing as if they
2943 come from a mapping or were typed by the user.
2944
2945 By default the string is added to the end of the typeahead
2946 buffer, thus if a mapping is still being executed the
2947 characters come after them. Use the 'i' flag to insert before
2948 other characters, they will be executed next, before any
2949 characters from a mapping.
2950
2951 The function does not wait for processing of keys contained in
2952 {string}.
2953
2954 To include special keys into {string}, use double-quotes
2955 and "\..." notation |expr-quote|. For example,
2956 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2957 feedkeys('\<CR>') pushes 5 characters.
2958 A special code that might be useful is <Ignore>, it exits the
2959 wait for a character without doing anything. *<Ignore>*
2960
2961 {mode} is a String, which can contain these character flags:
2962 'm' Remap keys. This is default. If {mode} is absent,
2963 keys are remapped.
2964 'n' Do not remap keys.
2965 't' Handle keys as if typed; otherwise they are handled as
2966 if coming from a mapping. This matters for undo,
2967 opening folds, etc.
2968 'L' Lowlevel input. Only works for Unix or when using the
2969 GUI. Keys are used as if they were coming from the
2970 terminal. Other flags are not used. *E980*
2971 When a CTRL-C interrupts and 't' is included it sets
2972 the internal "got_int" flag.
2973 'i' Insert the string instead of appending (see above).
2974 'x' Execute commands until typeahead is empty. This is
2975 similar to using ":normal!". You can call feedkeys()
2976 several times without 'x' and then one time with 'x'
2977 (possibly with an empty {string}) to execute all the
2978 typeahead. Note that when Vim ends in Insert mode it
2979 will behave as if <Esc> is typed, to avoid getting
2980 stuck, waiting for a character to be typed before the
2981 script continues.
2982 Note that if you manage to call feedkeys() while
2983 executing commands, thus calling it recursively, then
2984 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00002985 'c' Remove any script context when executing, so that
2986 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01002987 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01002988 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002989 '!' When used with 'x' will not end Insert mode. Can be
2990 used in a test when a timer is set to exit Insert mode
2991 a little later. Useful for testing CursorHoldI.
2992
2993 Return value is always 0.
2994
2995 Can also be used as a |method|: >
2996 GetInput()->feedkeys()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002997<
2998 Return type: |String| or list<string> depending on {list}
2999
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003000
Shougo Matsushita60c87432024-06-03 22:59:27 +02003001filecopy({from}, {to}) *filecopy()*
3002 Copy the file pointed to by the name {from} to {to}. The
3003 result is a Number, which is |TRUE| if the file was copied
3004 successfully, and |FALSE| when it failed.
3005 If a file with name {to} already exists, it will fail.
3006 Note that it does not handle directories (yet).
3007
3008 This function is not available in the |sandbox|.
3009
3010 Can also be used as a |method|: >
3011 GetOldName()->filecopy(newname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003012<
3013 Return type: |Number|
3014
Shougo Matsushita60c87432024-06-03 22:59:27 +02003015
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003016filereadable({file}) *filereadable()*
3017 The result is a Number, which is |TRUE| when a file with the
3018 name {file} exists, and can be read. If {file} doesn't exist,
3019 or is a directory, the result is |FALSE|. {file} is any
3020 expression, which is used as a String.
3021 If you don't care about the file being readable you can use
3022 |glob()|.
3023 {file} is used as-is, you may want to expand wildcards first: >
3024 echo filereadable('~/.vimrc')
3025 0
3026 echo filereadable(expand('~/.vimrc'))
3027 1
3028
3029< Can also be used as a |method|: >
3030 GetName()->filereadable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003031<
3032 Return type: |Number|
3033
3034 *file_readable()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003035 Obsolete name: file_readable().
3036
3037
3038filewritable({file}) *filewritable()*
3039 The result is a Number, which is 1 when a file with the
3040 name {file} exists, and can be written. If {file} doesn't
3041 exist, or is not writable, the result is 0. If {file} is a
3042 directory, and we can write to it, the result is 2.
3043
3044 Can also be used as a |method|: >
3045 GetName()->filewritable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003046<
3047 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003048
3049
3050filter({expr1}, {expr2}) *filter()*
3051 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
3052 For each item in {expr1} evaluate {expr2} and when the result
3053 is zero or false remove the item from the |List| or
3054 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003055 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003056
3057 {expr2} must be a |string| or |Funcref|.
3058
3059 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3060 of the current item. For a |Dictionary| |v:key| has the key
3061 of the current item and for a |List| |v:key| has the index of
3062 the current item. For a |Blob| |v:key| has the index of the
3063 current byte. For a |String| |v:key| has the index of the
3064 current character.
3065 Examples: >
3066 call filter(mylist, 'v:val !~ "OLD"')
3067< Removes the items where "OLD" appears. >
3068 call filter(mydict, 'v:key >= 8')
3069< Removes the items with a key below 8. >
3070 call filter(var, 0)
3071< Removes all the items, thus clears the |List| or |Dictionary|.
3072
3073 Note that {expr2} is the result of expression and is then
3074 used as an expression again. Often it is good to use a
3075 |literal-string| to avoid having to double backslashes.
3076
3077 If {expr2} is a |Funcref| it must take two arguments:
3078 1. the key or the index of the current item.
3079 2. the value of the current item.
3080 The function must return |TRUE| if the item should be kept.
3081 Example that keeps the odd items of a list: >
3082 func Odd(idx, val)
3083 return a:idx % 2 == 1
3084 endfunc
3085 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003086< It is shorter when using a |lambda|. In |Vim9| syntax: >
3087 call filter(myList, (idx, val) => idx * val <= 42)
3088< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003089 call filter(myList, {idx, val -> idx * val <= 42})
3090< If you do not use "val" you can leave it out: >
3091 call filter(myList, {idx -> idx % 2 == 1})
3092<
3093 In |Vim9| script the result must be true, false, zero or one.
3094 Other values will result in a type error.
3095
3096 For a |List| and a |Dictionary| the operation is done
3097 in-place. If you want it to remain unmodified make a copy
3098 first: >
3099 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
3100
3101< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00003102 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003103 When an error is encountered while evaluating {expr2} no
3104 further items in {expr1} are processed.
3105 When {expr2} is a Funcref errors inside a function are ignored,
3106 unless it was defined with the "abort" flag.
3107
3108 Can also be used as a |method|: >
3109 mylist->filter(expr2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003110<
3111 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
3112 depending on {expr1}
3113
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003114
3115finddir({name} [, {path} [, {count}]]) *finddir()*
3116 Find directory {name} in {path}. Supports both downwards and
3117 upwards recursive directory searches. See |file-searching|
3118 for the syntax of {path}.
3119
3120 Returns the path of the first found match. When the found
3121 directory is below the current directory a relative path is
3122 returned. Otherwise a full path is returned.
3123 If {path} is omitted or empty then 'path' is used.
3124
3125 If the optional {count} is given, find {count}'s occurrence of
3126 {name} in {path} instead of the first one.
3127 When {count} is negative return all the matches in a |List|.
3128
Bram Moolenaar016188f2022-06-06 20:52:59 +01003129 Returns an empty string if the directory is not found.
3130
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003131 This is quite similar to the ex-command `:find`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003132
3133 Can also be used as a |method|: >
3134 GetName()->finddir()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003135<
3136 Return type: |String|
3137
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003138
3139findfile({name} [, {path} [, {count}]]) *findfile()*
3140 Just like |finddir()|, but find a file instead of a directory.
3141 Uses 'suffixesadd'.
3142 Example: >
3143 :echo findfile("tags.vim", ".;")
3144< Searches from the directory of the current file upwards until
3145 it finds the file "tags.vim".
3146
3147 Can also be used as a |method|: >
3148 GetName()->findfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003149<
3150 Return type: |String|
3151
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003152
3153flatten({list} [, {maxdepth}]) *flatten()*
3154 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
3155 the result is a |List| without nesting, as if {maxdepth} is
3156 a very large number.
3157 The {list} is changed in place, use |flattennew()| if you do
3158 not want that.
3159 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00003160 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003161 *E900*
3162 {maxdepth} means how deep in nested lists changes are made.
3163 {list} is not modified when {maxdepth} is 0.
3164 {maxdepth} must be positive number.
3165
3166 If there is an error the number zero is returned.
3167
3168 Example: >
3169 :echo flatten([1, [2, [3, 4]], 5])
3170< [1, 2, 3, 4, 5] >
3171 :echo flatten([1, [2, [3, 4]], 5], 1)
3172< [1, 2, [3, 4], 5]
3173
3174 Can also be used as a |method|: >
3175 mylist->flatten()
3176<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003177 Return type: list<{type}>
3178
3179
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003180flattennew({list} [, {maxdepth}]) *flattennew()*
3181 Like |flatten()| but first make a copy of {list}.
3182
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003183 Return type: list<{type}>
3184
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003185
3186float2nr({expr}) *float2nr()*
3187 Convert {expr} to a Number by omitting the part after the
3188 decimal point.
Bram Moolenaar76db9e02022-11-09 21:21:04 +00003189 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003190 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003191 When the value of {expr} is out of range for a |Number| the
3192 result is truncated to 0x7fffffff or -0x7fffffff (or when
3193 64-bit Number support is enabled, 0x7fffffffffffffff or
3194 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
3195 64-bit Number support is enabled, -0x8000000000000000).
3196 Examples: >
3197 echo float2nr(3.95)
3198< 3 >
3199 echo float2nr(-23.45)
3200< -23 >
3201 echo float2nr(1.0e100)
3202< 2147483647 (or 9223372036854775807) >
3203 echo float2nr(-1.0e150)
3204< -2147483647 (or -9223372036854775807) >
3205 echo float2nr(1.0e-100)
3206< 0
3207
3208 Can also be used as a |method|: >
3209 Compute()->float2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003210<
3211 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003212
3213
3214floor({expr}) *floor()*
3215 Return the largest integral value less than or equal to
3216 {expr} as a |Float| (round down).
3217 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003218 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003219 Examples: >
3220 echo floor(1.856)
3221< 1.0 >
3222 echo floor(-5.456)
3223< -6.0 >
3224 echo floor(4.0)
3225< 4.0
3226
3227 Can also be used as a |method|: >
3228 Compute()->floor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003229<
3230 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003231
3232
3233fmod({expr1}, {expr2}) *fmod()*
3234 Return the remainder of {expr1} / {expr2}, even if the
3235 division is not representable. Returns {expr1} - i * {expr2}
3236 for some integer i such that if {expr2} is non-zero, the
3237 result has the same sign as {expr1} and magnitude less than
3238 the magnitude of {expr2}. If {expr2} is zero, the value
3239 returned is zero. The value returned is a |Float|.
3240 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003241 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
3242 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003243 Examples: >
3244 :echo fmod(12.33, 1.22)
3245< 0.13 >
3246 :echo fmod(-12.33, 1.22)
3247< -0.13
3248
3249 Can also be used as a |method|: >
3250 Compute()->fmod(1.22)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003251<
3252 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003253
3254
3255fnameescape({string}) *fnameescape()*
3256 Escape {string} for use as file name command argument. All
3257 characters that have a special meaning, such as '%' and '|'
3258 are escaped with a backslash.
3259 For most systems the characters escaped are
3260 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3261 appears in a filename, it depends on the value of 'isfname'.
3262 A leading '+' and '>' is also escaped (special after |:edit|
3263 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01003264 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003265 Example: >
3266 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003267 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003268< results in executing: >
3269 edit \+some\ str\%nge\|name
3270<
3271 Can also be used as a |method|: >
3272 GetName()->fnameescape()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003273<
3274 Return type: |String|
3275
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003276
3277fnamemodify({fname}, {mods}) *fnamemodify()*
3278 Modify file name {fname} according to {mods}. {mods} is a
3279 string of characters like it is used for file names on the
3280 command line. See |filename-modifiers|.
3281 Example: >
3282 :echo fnamemodify("main.c", ":p:h")
3283< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01003284 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01003285< If {mods} is empty or an unsupported modifier is used then
3286 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01003287 When {fname} is empty then with {mods} ":h" returns ".", so
3288 that `:cd` can be used with it. This is different from
3289 expand('%:h') without a buffer name, which returns an empty
3290 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003291 Note: Environment variables don't work in {fname}, use
3292 |expand()| first then.
3293
3294 Can also be used as a |method|: >
3295 GetName()->fnamemodify(':p:h')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003296<
3297 Return type: |String|
3298
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003299
3300foldclosed({lnum}) *foldclosed()*
3301 The result is a Number. If the line {lnum} is in a closed
3302 fold, the result is the number of the first line in that fold.
3303 If the line {lnum} is not in a closed fold, -1 is returned.
3304 {lnum} is used like with |getline()|. Thus "." is the current
3305 line, "'m" mark m, etc.
3306
3307 Can also be used as a |method|: >
3308 GetLnum()->foldclosed()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003309<
3310 Return type: |Number|
3311
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003312
3313foldclosedend({lnum}) *foldclosedend()*
3314 The result is a Number. If the line {lnum} is in a closed
3315 fold, the result is the number of the last line in that fold.
3316 If the line {lnum} is not in a closed fold, -1 is returned.
3317 {lnum} is used like with |getline()|. Thus "." is the current
3318 line, "'m" mark m, etc.
3319
3320 Can also be used as a |method|: >
3321 GetLnum()->foldclosedend()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003322<
3323 Return type: |Number|
3324
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003325
3326foldlevel({lnum}) *foldlevel()*
3327 The result is a Number, which is the foldlevel of line {lnum}
3328 in the current buffer. For nested folds the deepest level is
3329 returned. If there is no fold at line {lnum}, zero is
3330 returned. It doesn't matter if the folds are open or closed.
3331 When used while updating folds (from 'foldexpr') -1 is
3332 returned for lines where folds are still to be updated and the
3333 foldlevel is unknown. As a special case the level of the
3334 previous line is usually available.
3335 {lnum} is used like with |getline()|. Thus "." is the current
3336 line, "'m" mark m, etc.
3337
3338 Can also be used as a |method|: >
3339 GetLnum()->foldlevel()
3340<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003341 Return type: |Number|
3342
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003343 *foldtext()*
3344foldtext() Returns a String, to be displayed for a closed fold. This is
3345 the default function used for the 'foldtext' option and should
3346 only be called from evaluating 'foldtext'. It uses the
3347 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3348 The returned string looks like this: >
3349 +-- 45 lines: abcdef
3350< The number of leading dashes depends on the foldlevel. The
3351 "45" is the number of lines in the fold. "abcdef" is the text
3352 in the first non-blank line of the fold. Leading white space,
3353 "//" or "/*" and the text from the 'foldmarker' and
3354 'commentstring' options is removed.
3355 When used to draw the actual foldtext, the rest of the line
3356 will be filled with the fold char from the 'fillchars'
3357 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003358 Returns an empty string when there is no fold.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003359
3360 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003361 {not available when compiled without the |+folding| feature}
3362
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003363
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003364foldtextresult({lnum}) *foldtextresult()*
3365 Returns the text that is displayed for the closed fold at line
3366 {lnum}. Evaluates 'foldtext' in the appropriate context.
3367 When there is no closed fold at {lnum} an empty string is
3368 returned.
3369 {lnum} is used like with |getline()|. Thus "." is the current
3370 line, "'m" mark m, etc.
3371 Useful when exporting folded text, e.g., to HTML.
3372 {not available when compiled without the |+folding| feature}
3373
3374
3375 Can also be used as a |method|: >
3376 GetLnum()->foldtextresult()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003377<
3378 Return type: |String|
3379
Ernie Raele79e2072024-01-13 11:47:33 +01003380
3381foreach({expr1}, {expr2}) *foreach()*
3382 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
3383 For each item in {expr1} execute {expr2}. {expr1} is not
erraelc92b8be2024-01-14 10:11:07 -08003384 modified; its values may be, as with |:lockvar| 1. |E741|
Ernie Raele79e2072024-01-13 11:47:33 +01003385 See |map()| and |filter()| to modify {expr1}.
3386
3387 {expr2} must be a |string| or |Funcref|.
3388
3389 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3390 of the current item. For a |Dictionary| |v:key| has the key
3391 of the current item and for a |List| |v:key| has the index of
3392 the current item. For a |Blob| |v:key| has the index of the
3393 current byte. For a |String| |v:key| has the index of the
3394 current character.
3395 Examples: >
3396 call foreach(mylist, 'used[v:val] = true')
3397< This records the items that are in the {expr1} list.
3398
3399 Note that {expr2} is the result of expression and is then used
3400 as a command. Often it is good to use a |literal-string| to
3401 avoid having to double backslashes.
3402
3403 If {expr2} is a |Funcref| it must take two arguments:
3404 1. the key or the index of the current item.
3405 2. the value of the current item.
3406 With a legacy script lambda you don't get an error if it only
3407 accepts one argument, but with a Vim9 lambda you get "E1106:
3408 One argument too many", the number of arguments must match.
3409 If the function returns a value, it is ignored.
3410
3411 Returns {expr1} in all cases.
3412 When an error is encountered while executing {expr2} no
3413 further items in {expr1} are processed.
3414 When {expr2} is a Funcref errors inside a function are ignored,
3415 unless it was defined with the "abort" flag.
3416
3417 Can also be used as a |method|: >
3418 mylist->foreach(expr2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003419<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003420 Return type: |String|, |Blob| list<{type}> or dict<{type}>
3421 depending on {expr1}
3422
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003423 *foreground()*
3424foreground() Move the Vim window to the foreground. Useful when sent from
3425 a client to a Vim server. |remote_send()|
3426 On Win32 systems this might not work, the OS does not always
3427 allow a window to bring itself to the foreground. Use
3428 |remote_foreground()| instead.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003429
3430 Return type: |Number|
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003431 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003432 Win32 console version}
3433
Bram Moolenaaraa534142022-09-15 21:46:02 +01003434fullcommand({name} [, {vim9}]) *fullcommand()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003435 Get the full command name from a short abbreviated command
3436 name; see |20.2| for details on command abbreviations.
3437
3438 The string argument {name} may start with a `:` and can
3439 include a [range], these are skipped and not returned.
Bram Moolenaaraa534142022-09-15 21:46:02 +01003440 Returns an empty string if a command doesn't exist, if it's
3441 ambiguous (for user-defined commands) or cannot be shortened
3442 this way. |vim9-no-shorten|
3443
3444 Without the {vim9} argument uses the current script version.
3445 If {vim9} is present and FALSE then legacy script rules are
3446 used. When {vim9} is present and TRUE then Vim9 rules are
3447 used, e.g. "en" is not a short form of "endif".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003448
3449 For example `fullcommand('s')`, `fullcommand('sub')`,
3450 `fullcommand(':%substitute')` all return "substitute".
3451
3452 Can also be used as a |method|: >
3453 GetName()->fullcommand()
3454<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003455 Return type: |String|
3456
3457
3458funcref({name} [, {arglist}] [, {dict}]) *funcref()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003459 Just like |function()|, but the returned Funcref will lookup
3460 the function by reference, not by name. This matters when the
3461 function {name} is redefined later.
3462
3463 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003464 It only works for an autoloaded function if it has already
3465 been loaded (to avoid mistakenly loading the autoload script
3466 when only intending to use the function name, use |function()|
3467 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003468 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003469
3470 Can also be used as a |method|: >
3471 GetFuncname()->funcref([arg])
3472<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003473 Return type: func(...): any or |Number| on error
3474
Dominique Pellee764d1b2023-03-12 21:20:59 +00003475 *function()* *partial* *E700* *E923*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003476function({name} [, {arglist}] [, {dict}])
3477 Return a |Funcref| variable that refers to function {name}.
3478 {name} can be the name of a user defined function or an
3479 internal function.
3480
3481 {name} can also be a Funcref or a partial. When it is a
3482 partial the dict stored in it will be used and the {dict}
3483 argument is not allowed. E.g.: >
3484 let FuncWithArg = function(dict.Func, [arg])
3485 let Broken = function(dict.Func, [arg], dict)
3486<
3487 When using the Funcref the function will be found by {name},
3488 also when it was redefined later. Use |funcref()| to keep the
3489 same function.
3490
3491 When {arglist} or {dict} is present this creates a partial.
3492 That means the argument list and/or the dictionary is stored in
3493 the Funcref and will be used when the Funcref is called.
3494
3495 The arguments are passed to the function in front of other
3496 arguments, but after any argument from |method|. Example: >
3497 func Callback(arg1, arg2, name)
3498 ...
3499 let Partial = function('Callback', ['one', 'two'])
3500 ...
3501 call Partial('name')
3502< Invokes the function as with: >
3503 call Callback('one', 'two', 'name')
3504
3505< With a |method|: >
3506 func Callback(one, two, three)
3507 ...
3508 let Partial = function('Callback', ['two'])
3509 ...
3510 eval 'one'->Partial('three')
3511< Invokes the function as with: >
3512 call Callback('one', 'two', 'three')
3513
3514< The function() call can be nested to add more arguments to the
3515 Funcref. The extra arguments are appended to the list of
3516 arguments. Example: >
3517 func Callback(arg1, arg2, name)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003518 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003519 let Func = function('Callback', ['one'])
3520 let Func2 = function(Func, ['two'])
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003521 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003522 call Func2('name')
3523< Invokes the function as with: >
3524 call Callback('one', 'two', 'name')
3525
3526< The Dictionary is only useful when calling a "dict" function.
3527 In that case the {dict} is passed in as "self". Example: >
3528 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003529 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003530 endfunction
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003531 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003532 let context = {"name": "example"}
3533 let Func = function('Callback', context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003534 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003535 call Func() " will echo: called for example
3536< The use of function() is not needed when there are no extra
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003537 arguments, these two are equivalent, if Callback() is defined
3538 as context.Callback(): >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003539 let Func = function('Callback', context)
3540 let Func = context.Callback
3541
3542< The argument list and the Dictionary can be combined: >
3543 function Callback(arg1, count) dict
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003544 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003545 let context = {"name": "example"}
3546 let Func = function('Callback', ['one'], context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003547 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003548 call Func(500)
3549< Invokes the function as with: >
3550 call context.Callback('one', 500)
3551<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003552 Returns 0 on error.
3553
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003554 Can also be used as a |method|: >
3555 GetFuncname()->function([arg])
3556
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003557<
3558 Return type: func(...): any or |Number| on error
3559
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003560
3561garbagecollect([{atexit}]) *garbagecollect()*
3562 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3563 that have circular references.
3564
3565 There is hardly ever a need to invoke this function, as it is
3566 automatically done when Vim runs out of memory or is waiting
3567 for the user to press a key after 'updatetime'. Items without
3568 circular references are always freed when they become unused.
3569 This is useful if you have deleted a very big |List| and/or
3570 |Dictionary| with circular references in a script that runs
3571 for a long time.
3572
3573 When the optional {atexit} argument is one, garbage
3574 collection will also be done when exiting Vim, if it wasn't
3575 done before. This is useful when checking for memory leaks.
3576
3577 The garbage collection is not done immediately but only when
3578 it's safe to perform. This is when waiting for the user to
3579 type a character. To force garbage collection immediately use
3580 |test_garbagecollect_now()|.
3581
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003582 Return type: |String|
3583
3584
LemonBoy48b7d052024-07-09 18:24:59 +02003585get({list}, {idx} [, {default}]) *get()* *get()-list*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003586 Get item {idx} from |List| {list}. When this item is not
3587 available return {default}. Return zero when {default} is
3588 omitted.
3589 Preferably used as a |method|: >
3590 mylist->get(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003591<
3592 Return type: any, depending on {list}
3593
LemonBoy48b7d052024-07-09 18:24:59 +02003594get({blob}, {idx} [, {default}]) *get()-blob*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003595 Get byte {idx} from |Blob| {blob}. When this byte is not
3596 available return {default}. Return -1 when {default} is
3597 omitted.
3598 Preferably used as a |method|: >
3599 myblob->get(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003600<
3601 Return type: |Number|
3602
LemonBoy48b7d052024-07-09 18:24:59 +02003603get({dict}, {key} [, {default}]) *get()-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003604 Get item with key {key} from |Dictionary| {dict}. When this
3605 item is not available return {default}. Return zero when
3606 {default} is omitted. Useful example: >
3607 let val = get(g:, 'var_name', 'default')
3608< This gets the value of g:var_name if it exists, and uses
3609 'default' when it does not exist.
3610 Preferably used as a |method|: >
3611 mydict->get(key)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003612<
h-east84ac2122024-06-17 18:12:30 +02003613 Return type: any, depending on {dict}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003614
LemonBoy48b7d052024-07-09 18:24:59 +02003615get({func}, {what}) *get()-func*
3616 Get item {what} from |Funcref| {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003617 {what} are:
LemonBoy48b7d052024-07-09 18:24:59 +02003618 "name" The function name
3619 "func" The function
3620 "dict" The dictionary
3621 "args" The list with arguments
3622 "arity" A dictionary with information about the number of
3623 arguments accepted by the function (minus the
3624 {arglist}) with the following fields:
3625 required the number of positional arguments
3626 optional the number of optional arguments,
3627 in addition to the required ones
3628 varargs |TRUE| if the function accepts a
3629 variable number of arguments |...|
3630
3631 Note: There is no error, if the {arglist} of
3632 the Funcref contains more arguments than the
3633 Funcref expects, it's not validated.
3634
Bram Moolenaar016188f2022-06-06 20:52:59 +01003635 Returns zero on error.
LemonBoy48b7d052024-07-09 18:24:59 +02003636
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003637 Preferably used as a |method|: >
3638 myfunc->get(what)
3639<
LemonBoy48b7d052024-07-09 18:24:59 +02003640 Return type: any, depending on {func} and {what}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003641
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003642 *getbufinfo()*
3643getbufinfo([{buf}])
3644getbufinfo([{dict}])
3645 Get information about buffers as a List of Dictionaries.
3646
3647 Without an argument information about all the buffers is
3648 returned.
3649
3650 When the argument is a |Dictionary| only the buffers matching
3651 the specified criteria are returned. The following keys can
3652 be specified in {dict}:
3653 buflisted include only listed buffers.
3654 bufloaded include only loaded buffers.
3655 bufmodified include only modified buffers.
3656
3657 Otherwise, {buf} specifies a particular buffer to return
3658 information for. For the use of {buf}, see |bufname()|
3659 above. If the buffer is found the returned List has one item.
3660 Otherwise the result is an empty list.
3661
3662 Each returned List item is a dictionary with the following
3663 entries:
3664 bufnr Buffer number.
3665 changed TRUE if the buffer is modified.
3666 changedtick Number of changes made to the buffer.
Sean Dewar1fb41032023-08-16 17:15:05 +01003667 command TRUE if the buffer belongs to the
3668 command-line window |cmdwin|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003669 hidden TRUE if the buffer is hidden.
3670 lastused Timestamp in seconds, like
3671 |localtime()|, when the buffer was
3672 last used.
3673 {only with the |+viminfo| feature}
3674 listed TRUE if the buffer is listed.
3675 lnum Line number used for the buffer when
3676 opened in the current window.
3677 Only valid if the buffer has been
3678 displayed in the window in the past.
3679 If you want the line number of the
3680 last known cursor position in a given
3681 window, use |line()|: >
3682 :echo line('.', {winid})
3683<
3684 linecount Number of lines in the buffer (only
3685 valid when loaded)
3686 loaded TRUE if the buffer is loaded.
3687 name Full path to the file in the buffer.
3688 signs List of signs placed in the buffer.
3689 Each list item is a dictionary with
3690 the following fields:
3691 id sign identifier
3692 lnum line number
3693 name sign name
3694 variables A reference to the dictionary with
3695 buffer-local variables.
3696 windows List of |window-ID|s that display this
3697 buffer
3698 popups List of popup |window-ID|s that
3699 display this buffer
3700
3701 Examples: >
3702 for buf in getbufinfo()
3703 echo buf.name
3704 endfor
3705 for buf in getbufinfo({'buflisted':1})
3706 if buf.changed
3707 ....
3708 endif
3709 endfor
3710<
3711 To get buffer-local options use: >
3712 getbufvar({bufnr}, '&option_name')
3713<
3714 Can also be used as a |method|: >
3715 GetBufnr()->getbufinfo()
3716<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003717 Return type: list<dict<any>>
3718
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003719
3720 *getbufline()*
3721getbufline({buf}, {lnum} [, {end}])
3722 Return a |List| with the lines starting from {lnum} to {end}
3723 (inclusive) in the buffer {buf}. If {end} is omitted, a
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003724 |List| with only the line {lnum} is returned. See
3725 `getbufoneline()` for only getting the line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003726
3727 For the use of {buf}, see |bufname()| above.
3728
3729 For {lnum} and {end} "$" can be used for the last line of the
3730 buffer. Otherwise a number must be used.
3731
3732 When {lnum} is smaller than 1 or bigger than the number of
3733 lines in the buffer, an empty |List| is returned.
3734
3735 When {end} is greater than the number of lines in the buffer,
3736 it is treated as {end} is set to the number of lines in the
3737 buffer. When {end} is before {lnum} an empty |List| is
3738 returned.
3739
3740 This function works only for loaded buffers. For unloaded and
3741 non-existing buffers, an empty |List| is returned.
3742
3743 Example: >
3744 :let lines = getbufline(bufnr("myfile"), 1, "$")
3745
3746< Can also be used as a |method|: >
3747 GetBufnr()->getbufline(lnum)
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003748<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003749 Return type: list<string>
3750
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003751 *getbufoneline()*
3752getbufoneline({buf}, {lnum})
3753 Just like `getbufline()` but only get one line and return it
3754 as a string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003755
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003756 Return type: |String|
3757
3758
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003759getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3760 The result is the value of option or local buffer variable
3761 {varname} in buffer {buf}. Note that the name without "b:"
3762 must be used.
3763 The {varname} argument is a string.
3764 When {varname} is empty returns a |Dictionary| with all the
3765 buffer-local variables.
3766 When {varname} is equal to "&" returns a |Dictionary| with all
3767 the buffer-local options.
3768 Otherwise, when {varname} starts with "&" returns the value of
3769 a buffer-local option.
3770 This also works for a global or buffer-local option, but it
3771 doesn't work for a global variable, window-local variable or
3772 window-local option.
3773 For the use of {buf}, see |bufname()| above.
3774 When the buffer or variable doesn't exist {def} or an empty
3775 string is returned, there is no error message.
3776 Examples: >
3777 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003778 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003779
3780< Can also be used as a |method|: >
3781 GetBufnr()->getbufvar(varname)
3782<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003783 Return type: any, depending on {varname}
3784
3785
Kota Kato66bb9ae2023-01-17 18:31:56 +00003786getcellwidths() *getcellwidths()*
3787 Returns a |List| of cell widths of character ranges overridden
3788 by |setcellwidths()|. The format is equal to the argument of
3789 |setcellwidths()|. If no character ranges have their cell
3790 widths overridden, an empty List is returned.
h-east84ac2122024-06-17 18:12:30 +02003791
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003792 Return type: list<any>
Kota Kato66bb9ae2023-01-17 18:31:56 +00003793
3794
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003795getchangelist([{buf}]) *getchangelist()*
3796 Returns the |changelist| for the buffer {buf}. For the use
3797 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3798 exist, an empty list is returned.
3799
3800 The returned list contains two entries: a list with the change
3801 locations and the current position in the list. Each
3802 entry in the change list is a dictionary with the following
3803 entries:
3804 col column number
3805 coladd column offset for 'virtualedit'
3806 lnum line number
3807 If buffer {buf} is the current buffer, then the current
3808 position refers to the position in the list. For other
3809 buffers, it is set to the length of the list.
3810
3811 Can also be used as a |method|: >
3812 GetBufnr()->getchangelist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003813<
3814 Return type: list<any>
3815
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003816
Doug Kearns9cd9e752024-04-07 17:42:17 +02003817getchar([{expr}]) *getchar()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003818 Get a single character from the user or input stream.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003819 If {expr} is omitted, wait until a character is available.
3820 If {expr} is 0, only get a character when one is available.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003821 Return zero otherwise.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003822 If {expr} is 1, only check if a character is available, it is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003823 not consumed. Return zero if no character available.
3824 If you prefer always getting a string use |getcharstr()|.
3825
Doug Kearns9cd9e752024-04-07 17:42:17 +02003826 Without {expr} and when {expr} is 0 a whole character or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003827 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01003828 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003829 Otherwise a String is returned with the encoded character.
3830 For a special key it's a String with a sequence of bytes
3831 starting with 0x80 (decimal: 128). This is the same value as
3832 the String "\<Key>", e.g., "\<Left>". The returned value is
3833 also a String when a modifier (shift, control, alt) was used
3834 that is not included in the character.
3835
Doug Kearns9cd9e752024-04-07 17:42:17 +02003836 When {expr} is 0 and Esc is typed, there will be a short delay
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003837 while Vim waits to see if this is the start of an escape
3838 sequence.
3839
Doug Kearns9cd9e752024-04-07 17:42:17 +02003840 When {expr} is 1 only the first byte is returned. For a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003841 one-byte character it is the character itself as a number.
3842 Use nr2char() to convert it to a String.
3843
3844 Use getcharmod() to obtain any additional modifiers.
3845
3846 When the user clicks a mouse button, the mouse event will be
3847 returned. The position can then be found in |v:mouse_col|,
3848 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3849 |getmousepos()| can also be used. Mouse move events will be
3850 ignored.
3851 This example positions the mouse as it would normally happen: >
3852 let c = getchar()
3853 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003854 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003855 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003856 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003857 endif
3858<
3859 When using bracketed paste only the first character is
3860 returned, the rest of the pasted text is dropped.
3861 |xterm-bracketed-paste|.
3862
3863 There is no prompt, you will somehow have to make clear to the
3864 user that a character has to be typed. The screen is not
3865 redrawn, e.g. when resizing the window. When using a popup
3866 window it should work better with a |popup-filter|.
3867
3868 There is no mapping for the character.
3869 Key codes are replaced, thus when the user presses the <Del>
3870 key you get the code for the <Del> key, not the raw character
3871 sequence. Examples: >
3872 getchar() == "\<Del>"
3873 getchar() == "\<S-Left>"
3874< This example redefines "f" to ignore case: >
3875 :nmap f :call FindChar()<CR>
3876 :function FindChar()
3877 : let c = nr2char(getchar())
3878 : while col('.') < col('$') - 1
3879 : normal l
3880 : if getline('.')[col('.') - 1] ==? c
3881 : break
3882 : endif
3883 : endwhile
3884 :endfunction
3885<
3886 You may also receive synthetic characters, such as
3887 |<CursorHold>|. Often you will want to ignore this and get
3888 another character: >
3889 :function GetKey()
3890 : let c = getchar()
3891 : while c == "\<CursorHold>"
3892 : let c = getchar()
3893 : endwhile
3894 : return c
3895 :endfunction
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003896<
3897 Return type: |Number| or |String|
3898
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003899
3900getcharmod() *getcharmod()*
3901 The result is a Number which is the state of the modifiers for
3902 the last obtained character with getchar() or in another way.
3903 These values are added together:
3904 2 shift
3905 4 control
3906 8 alt (meta)
3907 16 meta (when it's different from ALT)
3908 32 mouse double click
3909 64 mouse triple click
3910 96 mouse quadruple click (== 32 + 64)
Casey Tucker92e90a12024-01-25 22:44:00 +01003911 128 command (Mac) or super (GTK)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003912 Only the modifiers that have not been included in the
3913 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01003914 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003915
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003916 Return type: |Number|
3917
3918
3919getcharpos({expr}) *getcharpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003920 Get the position for String {expr}. Same as |getpos()| but the
3921 column number in the returned List is a character index
3922 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00003923 If |getpos()| returns a very large column number, equal to
3924 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003925 of the last character.
3926
3927 Example:
3928 With the cursor on '세' in line 5 with text "여보세요": >
3929 getcharpos('.') returns [0, 5, 3, 0]
3930 getpos('.') returns [0, 5, 7, 0]
3931<
3932 Can also be used as a |method|: >
3933 GetMark()->getcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003934<
3935 Return type: list<number>
3936
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003937
3938getcharsearch() *getcharsearch()*
3939 Return the current character search information as a {dict}
3940 with the following entries:
3941
3942 char character previously used for a character
3943 search (|t|, |f|, |T|, or |F|); empty string
3944 if no character search has been performed
3945 forward direction of character search; 1 for forward,
3946 0 for backward
3947 until type of character search; 1 for a |t| or |T|
3948 character search, 0 for an |f| or |F|
3949 character search
3950
3951 This can be useful to always have |;| and |,| search
3952 forward/backward regardless of the direction of the previous
3953 character search: >
3954 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3955 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3956< Also see |setcharsearch()|.
3957
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003958 Return type: dict<any>
3959
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003960
Doug Kearns9cd9e752024-04-07 17:42:17 +02003961getcharstr([{expr}]) *getcharstr()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003962 Get a single character from the user or input stream as a
3963 string.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003964 If {expr} is omitted, wait until a character is available.
3965 If {expr} is 0 or false, only get a character when one is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003966 available. Return an empty string otherwise.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003967 If {expr} is 1 or true, only check if a character is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003968 available, it is not consumed. Return an empty string
3969 if no character is available.
3970 Otherwise this works like |getchar()|, except that a number
3971 result is converted to a string.
3972
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003973 Return type: |String|
3974
3975
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003976getcmdcompltype() *getcmdcompltype()*
3977 Return the type of the current command-line completion.
3978 Only works when the command line is being edited, thus
3979 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01003980 See |:command-completion| for the return string.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003981 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3982 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003983 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003984
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003985 Return type: |String|
3986
3987
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003988getcmdline() *getcmdline()*
3989 Return the current command-line. Only works when the command
3990 line is being edited, thus requires use of |c_CTRL-\_e| or
3991 |c_CTRL-R_=|.
3992 Example: >
3993 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003994< Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and
3995 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003996 Returns an empty string when entering a password or using
3997 |inputsecret()|.
3998
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003999 Return type: |String|
4000
4001
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004002getcmdpos() *getcmdpos()*
4003 Return the position of the cursor in the command line as a
4004 byte count. The first column is 1.
4005 Only works when editing the command line, thus requires use of
4006 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4007 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01004008 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
4009 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004010
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004011 Return type: |Number|
4012
4013
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004014getcmdscreenpos() *getcmdscreenpos()*
4015 Return the screen position of the cursor in the command line
4016 as a byte count. The first column is 1.
4017 Instead of |getcmdpos()|, it adds the prompt position.
4018 Only works when editing the command line, thus requires use of
4019 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4020 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01004021 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
4022 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004023
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004024 Return type: |Number|
4025
4026
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004027getcmdtype() *getcmdtype()*
4028 Return the current command-line type. Possible return values
4029 are:
4030 : normal Ex command
4031 > debug mode command |debug-mode|
4032 / forward search command
4033 ? backward search command
4034 @ |input()| command
4035 - |:insert| or |:append| command
4036 = |i_CTRL-R_=|
4037 Only works when editing the command line, thus requires use of
4038 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4039 Returns an empty string otherwise.
4040 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
4041
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004042 Return type: |String|
4043
4044
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004045getcmdwintype() *getcmdwintype()*
4046 Return the current |command-line-window| type. Possible return
4047 values are the same as |getcmdtype()|. Returns an empty string
4048 when not in the command-line window.
4049
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004050 Return type: |String|
4051
4052
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004053getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
4054 Return a list of command-line completion matches. The String
4055 {type} argument specifies what for. The following completion
4056 types are supported:
4057
4058 arglist file names in argument list
4059 augroup autocmd groups
4060 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00004061 behave |:behave| suboptions
4062 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004063 color color schemes
4064 command Ex command
4065 cmdline |cmdline-completion| result
4066 compiler compilers
4067 cscope |:cscope| suboptions
Shougo Matsushita92997dd2023-08-20 20:55:55 +02004068 custom,{func} custom completion, defined via {func}
4069 customlist,{func} custom completion, defined via {func}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004070 diff_buffer |:diffget| and |:diffput| completion
4071 dir directory names
LemonBoya20bf692024-07-11 22:35:53 +02004072 dir_in_path directory names in |'cdpath'|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004073 environment environment variable names
4074 event autocommand events
4075 expression Vim expression
4076 file file and directory names
4077 file_in_path file and directory names in |'path'|
4078 filetype filetype names |'filetype'|
4079 function function name
4080 help help subjects
4081 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00004082 history |:history| suboptions
Doug Kearns81642d92024-01-04 22:37:44 +01004083 keymap keyboard mappings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004084 locale locale names (as output of locale -a)
4085 mapclear buffer argument
4086 mapping mapping name
4087 menu menus
4088 messages |:messages| suboptions
4089 option options
4090 packadd optional package |pack-add| names
zeertzjq5c8771b2023-01-24 12:34:03 +00004091 runtime |:runtime| completion
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00004092 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004093 shellcmd Shell command
4094 sign |:sign| suboptions
4095 syntax syntax file names |'syntax'|
4096 syntime |:syntime| suboptions
4097 tag tags
4098 tag_listfiles tags, file names
4099 user user names
4100 var user variables
4101
4102 If {pat} is an empty string, then all the matches are
4103 returned. Otherwise only items matching {pat} are returned.
4104 See |wildcards| for the use of special characters in {pat}.
4105
4106 If the optional {filtered} flag is set to 1, then 'wildignore'
4107 is applied to filter the results. Otherwise all the matches
4108 are returned. The 'wildignorecase' option always applies.
4109
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00004110 If the 'wildoptions' option contains 'fuzzy', then fuzzy
4111 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00004112 regular expression matching is used. Thus this function
4113 follows the user preference, what happens on the command line.
4114 If you do not want this you can make 'wildoptions' empty
4115 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00004116
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004117 If {type} is "cmdline", then the |cmdline-completion| result is
4118 returned. For example, to complete the possible values after
4119 a ":call" command: >
4120 echo getcompletion('call ', 'cmdline')
4121<
4122 If there are no matches, an empty list is returned. An
4123 invalid value for {type} produces an error.
4124
4125 Can also be used as a |method|: >
4126 GetPattern()->getcompletion('color')
4127<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004128 Return type: list<string>
4129
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004130 *getcurpos()*
4131getcurpos([{winid}])
4132 Get the position of the cursor. This is like getpos('.'), but
4133 includes an extra "curswant" item in the list:
4134 [0, lnum, col, off, curswant] ~
4135 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00004136 cursor vertically. After |$| command it will be a very large
4137 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004138 |getpos()|.
4139 The first "bufnum" item is always zero. The byte position of
4140 the cursor is returned in 'col'. To get the character
4141 position, use |getcursorcharpos()|.
4142
4143 The optional {winid} argument can specify the window. It can
4144 be the window number or the |window-ID|. The last known
4145 cursor position is returned, this may be invalid for the
4146 current value of the buffer if it is not the current window.
4147 If {winid} is invalid a list with zeroes is returned.
4148
4149 This can be used to save and restore the cursor position: >
4150 let save_cursor = getcurpos()
4151 MoveTheCursorAround
4152 call setpos('.', save_cursor)
4153< Note that this only works within the window. See
4154 |winrestview()| for restoring more state.
4155
4156 Can also be used as a |method|: >
4157 GetWinid()->getcurpos()
4158<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004159 Return type: list<number>
4160
4161
4162getcursorcharpos([{winid}]) *getcursorcharpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004163 Same as |getcurpos()| but the column number in the returned
4164 List is a character index instead of a byte index.
4165
4166 Example:
4167 With the cursor on '보' in line 3 with text "여보세요": >
4168 getcursorcharpos() returns [0, 3, 2, 0, 3]
4169 getcurpos() returns [0, 3, 4, 0, 3]
4170<
4171 Can also be used as a |method|: >
4172 GetWinid()->getcursorcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004173<
4174 Return type: list<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004175
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004176
4177getcwd([{winnr} [, {tabnr}]]) *getcwd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004178 The result is a String, which is the name of the current
4179 working directory. 'autochdir' is ignored.
4180
4181 With {winnr} return the local current directory of this window
4182 in the current tab page. {winnr} can be the window number or
4183 the |window-ID|.
4184 If {winnr} is -1 return the name of the global working
4185 directory. See also |haslocaldir()|.
4186
4187 With {winnr} and {tabnr} return the local current directory of
4188 the window in the specified tab page. If {winnr} is -1 return
4189 the working directory of the tabpage.
4190 If {winnr} is zero use the current window, if {tabnr} is zero
4191 use the current tabpage.
4192 Without any arguments, return the actual working directory of
4193 the current window.
4194 Return an empty string if the arguments are invalid.
4195
4196 Examples: >
4197 " Get the working directory of the current window
4198 :echo getcwd()
4199 :echo getcwd(0)
4200 :echo getcwd(0, 0)
4201 " Get the working directory of window 3 in tabpage 2
4202 :echo getcwd(3, 2)
4203 " Get the global working directory
4204 :echo getcwd(-1)
4205 " Get the working directory of tabpage 3
4206 :echo getcwd(-1, 3)
4207 " Get the working directory of current tabpage
4208 :echo getcwd(-1, 0)
4209
4210< Can also be used as a |method|: >
4211 GetWinnr()->getcwd()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004212<
4213 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004214
4215getenv({name}) *getenv()*
4216 Return the value of environment variable {name}. The {name}
4217 argument is a string, without a leading '$'. Example: >
4218 myHome = getenv('HOME')
4219
4220< When the variable does not exist |v:null| is returned. That
4221 is different from a variable set to an empty string, although
4222 some systems interpret the empty value as the variable being
4223 deleted. See also |expr-env|.
4224
4225 Can also be used as a |method|: >
4226 GetVarname()->getenv()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004227<
4228 Return type: |String| or |Number|
4229
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004230
4231getfontname([{name}]) *getfontname()*
4232 Without an argument returns the name of the normal font being
4233 used. Like what is used for the Normal highlight group
4234 |hl-Normal|.
4235 With an argument a check is done whether String {name} is a
4236 valid font name. If not then an empty string is returned.
4237 Otherwise the actual font name is returned, or {name} if the
4238 GUI does not support obtaining the real name.
4239 Only works when the GUI is running, thus not in your vimrc or
4240 gvimrc file. Use the |GUIEnter| autocommand to use this
4241 function just after the GUI has started.
4242 Note that the GTK GUI accepts any font name, thus checking for
4243 a valid name does not work.
4244
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004245 Return type: |String|
4246
4247
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004248getfperm({fname}) *getfperm()*
4249 The result is a String, which is the read, write, and execute
4250 permissions of the given file {fname}.
4251 If {fname} does not exist or its directory cannot be read, an
4252 empty string is returned.
4253 The result is of the form "rwxrwxrwx", where each group of
4254 "rwx" flags represent, in turn, the permissions of the owner
4255 of the file, the group the file belongs to, and other users.
4256 If a user does not have a given permission the flag for this
4257 is replaced with the string "-". Examples: >
4258 :echo getfperm("/etc/passwd")
4259 :echo getfperm(expand("~/.vimrc"))
4260< This will hopefully (from a security point of view) display
4261 the string "rw-r--r--" or even "rw-------".
4262
4263 Can also be used as a |method|: >
4264 GetFilename()->getfperm()
4265<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004266 Return type: |String|
4267
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004268 For setting permissions use |setfperm()|.
4269
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004270
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004271getfsize({fname}) *getfsize()*
4272 The result is a Number, which is the size in bytes of the
4273 given file {fname}.
4274 If {fname} is a directory, 0 is returned.
4275 If the file {fname} can't be found, -1 is returned.
4276 If the size of {fname} is too big to fit in a Number then -2
4277 is returned.
4278
4279 Can also be used as a |method|: >
4280 GetFilename()->getfsize()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004281<
4282 Return type: |Number|
4283
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004284
4285getftime({fname}) *getftime()*
4286 The result is a Number, which is the last modification time of
4287 the given file {fname}. The value is measured as seconds
4288 since 1st Jan 1970, and may be passed to strftime(). See also
4289 |localtime()| and |strftime()|.
4290 If the file {fname} can't be found -1 is returned.
4291
4292 Can also be used as a |method|: >
4293 GetFilename()->getftime()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004294<
4295 Return type: |Number|
4296
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004297
4298getftype({fname}) *getftype()*
4299 The result is a String, which is a description of the kind of
4300 file of the given file {fname}.
4301 If {fname} does not exist an empty string is returned.
4302 Here is a table over different kinds of files and their
4303 results:
4304 Normal file "file"
4305 Directory "dir"
4306 Symbolic link "link"
4307 Block device "bdev"
4308 Character device "cdev"
4309 Socket "socket"
4310 FIFO "fifo"
4311 All other "other"
4312 Example: >
4313 getftype("/home")
4314< Note that a type such as "link" will only be returned on
4315 systems that support it. On some systems only "dir" and
4316 "file" are returned. On MS-Windows a symbolic link to a
4317 directory returns "dir" instead of "link".
4318
4319 Can also be used as a |method|: >
4320 GetFilename()->getftype()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004321<
4322 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004323
4324getimstatus() *getimstatus()*
4325 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01004326 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004327 See 'imstatusfunc'.
4328
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004329 Return type: |Number|
4330
4331
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004332getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
4333 Returns the |jumplist| for the specified window.
4334
4335 Without arguments use the current window.
4336 With {winnr} only use this window in the current tab page.
4337 {winnr} can also be a |window-ID|.
4338 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01004339 page. If {winnr} or {tabnr} is invalid, an empty list is
4340 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004341
4342 The returned list contains two entries: a list with the jump
4343 locations and the last used jump position number in the list.
4344 Each entry in the jump location list is a dictionary with
4345 the following entries:
4346 bufnr buffer number
4347 col column number
4348 coladd column offset for 'virtualedit'
4349 filename filename if available
4350 lnum line number
4351
4352 Can also be used as a |method|: >
4353 GetWinnr()->getjumplist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004354<
4355 Return type: list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004356
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004357 *getline()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004358getline({lnum} [, {end}])
4359 Without {end} the result is a String, which is line {lnum}
4360 from the current buffer. Example: >
4361 getline(1)
4362< When {lnum} is a String that doesn't start with a
4363 digit, |line()| is called to translate the String into a Number.
4364 To get the line under the cursor: >
4365 getline(".")
4366< When {lnum} is a number smaller than 1 or bigger than the
4367 number of lines in the buffer, an empty string is returned.
4368
4369 When {end} is given the result is a |List| where each item is
4370 a line from the current buffer in the range {lnum} to {end},
4371 including line {end}.
4372 {end} is used in the same way as {lnum}.
4373 Non-existing lines are silently omitted.
4374 When {end} is before {lnum} an empty |List| is returned.
4375 Example: >
4376 :let start = line('.')
4377 :let end = search("^$") - 1
4378 :let lines = getline(start, end)
4379
4380< Can also be used as a |method|: >
4381 ComputeLnum()->getline()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004382<
4383 Return type: list<string> or |String| depending on {end}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004384
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004385 To get lines from another buffer see |getbufline()| and
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00004386 |getbufoneline()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004387
4388getloclist({nr} [, {what}]) *getloclist()*
4389 Returns a |List| with all the entries in the location list for
4390 window {nr}. {nr} can be the window number or the |window-ID|.
4391 When {nr} is zero the current window is used.
4392
4393 For a location list window, the displayed location list is
4394 returned. For an invalid window number {nr}, an empty list is
4395 returned. Otherwise, same as |getqflist()|.
4396
4397 If the optional {what} dictionary argument is supplied, then
4398 returns the items listed in {what} as a dictionary. Refer to
4399 |getqflist()| for the supported items in {what}.
4400
4401 In addition to the items supported by |getqflist()| in {what},
4402 the following item is supported by |getloclist()|:
4403
4404 filewinid id of the window used to display files
4405 from the location list. This field is
4406 applicable only when called from a
4407 location list window. See
4408 |location-list-file-window| for more
4409 details.
4410
4411 Returns a |Dictionary| with default values if there is no
4412 location list for the window {nr}.
4413 Returns an empty Dictionary if window {nr} does not exist.
4414
4415 Examples (See also |getqflist-examples|): >
4416 :echo getloclist(3, {'all': 0})
4417 :echo getloclist(5, {'filewinid': 0})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004418<
4419 Return type: list<dict<any>> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004420
4421
4422getmarklist([{buf}]) *getmarklist()*
4423 Without the {buf} argument returns a |List| with information
4424 about all the global marks. |mark|
4425
4426 If the optional {buf} argument is specified, returns the
4427 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01004428 see |bufname()|. If {buf} is invalid, an empty list is
4429 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004430
4431 Each item in the returned List is a |Dict| with the following:
4432 mark name of the mark prefixed by "'"
4433 pos a |List| with the position of the mark:
4434 [bufnum, lnum, col, off]
4435 Refer to |getpos()| for more information.
4436 file file name
4437
4438 Refer to |getpos()| for getting information about a specific
4439 mark.
4440
4441 Can also be used as a |method|: >
4442 GetBufnr()->getmarklist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004443<
4444 Return type: list<dict<any>> or list<any>
4445
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004446
4447getmatches([{win}]) *getmatches()*
4448 Returns a |List| with all matches previously defined for the
4449 current window by |matchadd()| and the |:match| commands.
4450 |getmatches()| is useful in combination with |setmatches()|,
4451 as |setmatches()| can restore a list of matches saved by
4452 |getmatches()|.
4453 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01004454 window ID instead of the current window. If {win} is invalid,
4455 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004456 Example: >
4457 :echo getmatches()
4458< [{'group': 'MyGroup1', 'pattern': 'TODO',
4459 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4460 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4461 :let m = getmatches()
4462 :call clearmatches()
4463 :echo getmatches()
4464< [] >
4465 :call setmatches(m)
4466 :echo getmatches()
4467< [{'group': 'MyGroup1', 'pattern': 'TODO',
4468 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4469 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4470 :unlet m
4471<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004472 Return type: list<dict<any>> or list<any>
4473
4474
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004475getmousepos() *getmousepos()*
4476 Returns a |Dictionary| with the last known position of the
4477 mouse. This can be used in a mapping for a mouse click or in
4478 a filter of a popup window. The items are:
4479 screenrow screen row
4480 screencol screen column
4481 winid Window ID of the click
4482 winrow row inside "winid"
4483 wincol column inside "winid"
4484 line text line inside "winid"
4485 column text column inside "winid"
zeertzjqf5a94d52023-10-15 10:03:30 +02004486 coladd offset (in screen columns) from the
4487 start of the clicked char
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004488 All numbers are 1-based.
4489
4490 If not over a window, e.g. when in the command line, then only
4491 "screenrow" and "screencol" are valid, the others are zero.
4492
4493 When on the status line below a window or the vertical
4494 separator right of a window, the "line" and "column" values
4495 are zero.
4496
4497 When the position is after the text then "column" is the
4498 length of the text in bytes plus one.
4499
4500 If the mouse is over a popup window then that window is used.
4501
4502 When using |getchar()| the Vim variables |v:mouse_lnum|,
4503 |v:mouse_col| and |v:mouse_winid| also provide these values.
4504
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004505 Return type: dict<number>
4506
4507
Bram Moolenaar24dc19c2022-11-14 19:49:15 +00004508getmouseshape() *getmouseshape()*
4509 Returns the name of the currently showing mouse pointer.
4510 When the |+mouseshape| feature is not supported or the shape
4511 is unknown an empty string is returned.
4512 This function is mainly intended for testing.
4513
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004514 Return type: |String|
4515
4516
4517getpid() *getpid()*
4518 Return a Number which is the process ID of the Vim process.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004519 On Unix and MS-Windows this is a unique number, until Vim
4520 exits.
4521
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004522 Return type: |Number|
4523
4524
4525getpos({expr}) *getpos()*
zeertzjq02f3eba2024-06-12 20:45:24 +02004526 Get the position for String {expr}.
4527 The accepted values for {expr} are: *E1209*
4528 . The cursor position.
4529 $ The last line in the current buffer.
4530 'x Position of mark x (if the mark is not set, 0 is
zeertzjqd353d272024-06-13 23:00:25 +08004531 returned for all values).
zeertzjq02f3eba2024-06-12 20:45:24 +02004532 w0 First line visible in current window (one if the
4533 display isn't updated, e.g. in silent Ex mode).
4534 w$ Last line visible in current window (this is one
4535 less than "w0" if no lines are visible).
4536 v When not in Visual mode, returns the cursor
4537 position. In Visual mode, returns the other end
4538 of the Visual area. A good way to think about
4539 this is that in Visual mode "v" and "." complement
4540 each other. While "." refers to the cursor
4541 position, "v" refers to where |v_o| would move the
4542 cursor. As a result, you can use "v" and "."
4543 together to work on all of a selection in
4544 characterwise Visual mode. If the cursor is at
4545 the end of a characterwise Visual area, "v" refers
4546 to the start of the same Visual area. And if the
4547 cursor is at the start of a characterwise Visual
4548 area, "v" refers to the end of the same Visual
4549 area. "v" differs from |'<| and |'>| in that it's
4550 updated right away.
4551 Note that a mark in another file can be used. The line number
4552 then applies to another buffer.
4553
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004554 The result is a |List| with four numbers:
4555 [bufnum, lnum, col, off]
4556 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4557 is the buffer number of the mark.
4558 "lnum" and "col" are the position in the buffer. The first
4559 column is 1.
4560 The "off" number is zero, unless 'virtualedit' is used. Then
4561 it is the offset in screen columns from the start of the
4562 character. E.g., a position within a <Tab> or after the last
4563 character.
zeertzjq02f3eba2024-06-12 20:45:24 +02004564
4565 For getting the cursor position see |getcurpos()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004566 The column number in the returned List is the byte position
4567 within the line. To get the character position in the line,
4568 use |getcharpos()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02004569
4570 Note that for '< and '> Visual mode matters: when it is "V"
4571 (visual line mode) the column of '< is zero and the column of
4572 '> is a large number equal to |v:maxcol|.
naohiro ono56200ee2022-01-01 14:59:44 +00004573 A very large column number equal to |v:maxcol| can be returned,
4574 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01004575 If {expr} is invalid, returns a list with all zeros.
zeertzjq02f3eba2024-06-12 20:45:24 +02004576
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004577 This can be used to save and restore the position of a mark: >
4578 let save_a_mark = getpos("'a")
4579 ...
4580 call setpos("'a", save_a_mark)
zeertzjqd353d272024-06-13 23:00:25 +08004581<
4582 Also see |getcharpos()|, |getcurpos()| and |setpos()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004583
4584 Can also be used as a |method|: >
4585 GetMark()->getpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004586<
4587 Return type: list<number>
4588
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004589
4590getqflist([{what}]) *getqflist()*
4591 Returns a |List| with all the current quickfix errors. Each
4592 list item is a dictionary with these entries:
4593 bufnr number of buffer that has the file name, use
4594 bufname() to get the name
4595 module module name
4596 lnum line number in the buffer (first line is 1)
4597 end_lnum
4598 end of line number if the item is multiline
4599 col column number (first column is 1)
4600 end_col end of column number if the item has range
4601 vcol |TRUE|: "col" is visual column
4602 |FALSE|: "col" is byte index
4603 nr error number
h-east84ac2122024-06-17 18:12:30 +02004604 pattern search pattern used to locate the error
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004605 text description of the error
4606 type type of the error, 'E', '1', etc.
4607 valid |TRUE|: recognized error message
h_east596a9f22023-11-21 21:24:23 +09004608 user_data
4609 custom data associated with the item, can be
Tom Praschanca6ac992023-08-11 23:26:12 +02004610 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004611
4612 When there is no error list or it's empty, an empty list is
4613 returned. Quickfix list entries with a non-existing buffer
4614 number are returned with "bufnr" set to zero (Note: some
4615 functions accept buffer number zero for the alternate buffer,
4616 you may need to explicitly check for zero).
4617
4618 Useful application: Find pattern matches in multiple files and
4619 do something with them: >
4620 :vimgrep /theword/jg *.c
4621 :for d in getqflist()
4622 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4623 :endfor
4624<
4625 If the optional {what} dictionary argument is supplied, then
4626 returns only the items listed in {what} as a dictionary. The
4627 following string items are supported in {what}:
4628 changedtick get the total number of changes made
4629 to the list |quickfix-changedtick|
4630 context get the |quickfix-context|
4631 efm errorformat to use when parsing "lines". If
4632 not present, then the 'errorformat' option
4633 value is used.
4634 id get information for the quickfix list with
4635 |quickfix-ID|; zero means the id for the
4636 current list or the list specified by "nr"
4637 idx get information for the quickfix entry at this
4638 index in the list specified by 'id' or 'nr'.
4639 If set to zero, then uses the current entry.
4640 See |quickfix-index|
4641 items quickfix list entries
4642 lines parse a list of lines using 'efm' and return
4643 the resulting entries. Only a |List| type is
4644 accepted. The current quickfix list is not
4645 modified. See |quickfix-parse|.
4646 nr get information for this quickfix list; zero
4647 means the current quickfix list and "$" means
4648 the last quickfix list
4649 qfbufnr number of the buffer displayed in the quickfix
4650 window. Returns 0 if the quickfix buffer is
4651 not present. See |quickfix-buffer|.
4652 size number of entries in the quickfix list
4653 title get the list title |quickfix-title|
4654 winid get the quickfix |window-ID|
4655 all all of the above quickfix properties
4656 Non-string items in {what} are ignored. To get the value of a
4657 particular item, set it to zero.
4658 If "nr" is not present then the current quickfix list is used.
4659 If both "nr" and a non-zero "id" are specified, then the list
4660 specified by "id" is used.
4661 To get the number of lists in the quickfix stack, set "nr" to
4662 "$" in {what}. The "nr" value in the returned dictionary
4663 contains the quickfix stack size.
4664 When "lines" is specified, all the other items except "efm"
4665 are ignored. The returned dictionary contains the entry
4666 "items" with the list of entries.
4667
4668 The returned dictionary contains the following entries:
4669 changedtick total number of changes made to the
4670 list |quickfix-changedtick|
4671 context quickfix list context. See |quickfix-context|
4672 If not present, set to "".
4673 id quickfix list ID |quickfix-ID|. If not
4674 present, set to 0.
4675 idx index of the quickfix entry in the list. If not
4676 present, set to 0.
4677 items quickfix list entries. If not present, set to
4678 an empty list.
4679 nr quickfix list number. If not present, set to 0
4680 qfbufnr number of the buffer displayed in the quickfix
4681 window. If not present, set to 0.
4682 size number of entries in the quickfix list. If not
4683 present, set to 0.
4684 title quickfix list title text. If not present, set
4685 to "".
4686 winid quickfix |window-ID|. If not present, set to 0
4687
4688 Examples (See also |getqflist-examples|): >
4689 :echo getqflist({'all': 1})
4690 :echo getqflist({'nr': 2, 'title': 1})
4691 :echo getqflist({'lines' : ["F1:10:L10"]})
4692<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004693 Return type: list<dict<any>> or list<any>
4694
4695
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004696getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4697 The result is a String, which is the contents of register
4698 {regname}. Example: >
4699 :let cliptext = getreg('*')
4700< When register {regname} was not set the result is an empty
4701 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004702 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004703
4704 getreg('=') returns the last evaluated value of the expression
4705 register. (For use in maps.)
4706 getreg('=', 1) returns the expression itself, so that it can
4707 be restored with |setreg()|. For other registers the extra
4708 argument is ignored, thus you can always give it.
4709
4710 If {list} is present and |TRUE|, the result type is changed
4711 to |List|. Each list item is one text line. Use it if you care
4712 about zero bytes possibly present inside register: without
4713 third argument both NLs and zero bytes are represented as NLs
4714 (see |NL-used-for-Nul|).
4715 When the register was not set an empty list is returned.
4716
4717 If {regname} is "", the unnamed register '"' is used.
4718 If {regname} is not specified, |v:register| is used.
4719 In |Vim9-script| {regname} must be one character.
4720
4721 Can also be used as a |method|: >
4722 GetRegname()->getreg()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004723<
4724 Return type: |String|
4725
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004726
4727getreginfo([{regname}]) *getreginfo()*
4728 Returns detailed information about register {regname} as a
4729 Dictionary with the following entries:
4730 regcontents List of lines contained in register
4731 {regname}, like
4732 |getreg|({regname}, 1, 1).
4733 regtype the type of register {regname}, as in
4734 |getregtype()|.
4735 isunnamed Boolean flag, v:true if this register
4736 is currently pointed to by the unnamed
4737 register.
4738 points_to for the unnamed register, gives the
4739 single letter name of the register
4740 currently pointed to (see |quotequote|).
4741 For example, after deleting a line
4742 with `dd`, this field will be "1",
4743 which is the register that got the
4744 deleted text.
4745
4746 The {regname} argument is a string. If {regname} is invalid
4747 or not set, an empty Dictionary will be returned.
4748 If {regname} is "" or "@", the unnamed register '"' is used.
4749 If {regname} is not specified, |v:register| is used.
4750 The returned Dictionary can be passed to |setreg()|.
4751 In |Vim9-script| {regname} must be one character.
4752
4753 Can also be used as a |method|: >
4754 GetRegname()->getreginfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004755<
4756 Return type: dict<any>
4757
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004758
Shougo Matsushita19b71882024-02-28 22:48:12 +01004759getregion({pos1}, {pos2} [, {opts}]) *getregion()*
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004760 Returns the list of strings from {pos1} to {pos2} from a
Shougo Matsushita19b71882024-02-28 22:48:12 +01004761 buffer.
4762
4763 {pos1} and {pos2} must both be |List|s with four numbers.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004764 See |getpos()| for the format of the list. It's possible
4765 to specify positions from a different buffer, but please
zeertzjq0df8f932024-03-07 21:40:53 +01004766 note the limitations at |getregion-notes|.
Shougo Matsushita19b71882024-02-28 22:48:12 +01004767
4768 The optional argument {opts} is a Dict and supports the
4769 following items:
4770
zeertzjqafc22952024-05-24 19:07:12 +02004771 type Specify the region's selection type.
4772 See |getregtype()| for possible values,
zeertzjqdff55a32024-05-25 10:25:36 +02004773 except that the width can be omitted
4774 and an empty string cannot be used.
zeertzjqafc22952024-05-24 19:07:12 +02004775 (default: "v")
Shougo Matsushita19b71882024-02-28 22:48:12 +01004776
zeertzjq87410ab2024-03-02 06:00:23 +08004777 exclusive If |TRUE|, use exclusive selection
zeertzjqafc22952024-05-24 19:07:12 +02004778 for the end position.
zeertzjq87410ab2024-03-02 06:00:23 +08004779 (default: follow 'selection')
Shougo Matsushita19b71882024-02-28 22:48:12 +01004780
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004781 You can get the last selection type by |visualmode()|.
4782 If Visual mode is active, use |mode()| to get the Visual mode
4783 (e.g., in a |:vmap|).
zeertzjq87410ab2024-03-02 06:00:23 +08004784 This function is useful to get text starting and ending in
4785 different columns, such as a |characterwise-visual| selection.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004786
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004787 *getregion-notes*
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004788 Note that:
4789 - Order of {pos1} and {pos2} doesn't matter, it will always
4790 return content from the upper left position to the lower
4791 right position.
zeertzjq87410ab2024-03-02 06:00:23 +08004792 - If 'virtualedit' is enabled and the region is past the end
4793 of the lines, resulting lines are padded with spaces.
4794 - If the region is blockwise and it starts or ends in the
4795 middle of a multi-cell character, it is not included but
4796 its selected part is substituted with spaces.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004797 - If {pos1} and {pos2} are not in the same buffer, an empty
zeertzjq421b5972024-02-22 19:48:06 +01004798 list is returned.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004799 - {pos1} and {pos2} must belong to a |bufloaded()| buffer.
zeertzjq0df8f932024-03-07 21:40:53 +01004800 - It is evaluated in current window context, which makes a
4801 difference if the buffer is displayed in a window with
4802 different 'virtualedit' or 'list' values.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004803
4804 Examples: >
4805 :xnoremap <CR>
Shougo Matsushita19b71882024-02-28 22:48:12 +01004806 \ <Cmd>echow getregion(
4807 \ getpos('v'), getpos('.'), #{ type: mode() })<CR>
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004808<
4809 Can also be used as a |method|: >
Shougo Matsushita19b71882024-02-28 22:48:12 +01004810 getpos('.')->getregion(getpos("'a"))
zeertzjqd4d12072024-07-16 20:34:16 +02004811<
4812 Return type: list<string>
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004813
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004814<
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004815getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()*
4816 Same as |getregion()|, but returns a list of positions
4817 describing the buffer text segments bound by {pos1} and
4818 {pos2}.
4819 The segments are a pair of positions for every line: >
4820 [[{start_pos}, {end_pos}], ...]
4821<
4822 The position is a |List| with four numbers:
4823 [bufnum, lnum, col, off]
4824 "bufnum" is the buffer number.
4825 "lnum" and "col" are the position in the buffer. The first
4826 column is 1.
zeertzjqc95e64f2024-05-20 14:00:31 +02004827 If the "off" number of a starting position is non-zero, it is
4828 the offset in screen columns from the start of the character.
4829 E.g., a position within a <Tab> or after the last character.
4830 If the "off" number of an ending position is non-zero, it is
zeertzjq52a6f342024-05-22 16:42:44 +02004831 the offset of the character's first cell not included in the
4832 selection, otherwise all its cells are included.
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004833
zeertzjq2b09de92024-05-24 07:48:51 +02004834 Apart from the options supported by |getregion()|, {opts} also
4835 supports the following:
4836
4837 eol If |TRUE|, indicate positions beyond
4838 the end of a line with "col" values
4839 one more than the length of the line.
4840 If |FALSE|, positions are limited
4841 within their lines, and if a line is
4842 empty or the selection is entirely
4843 beyond the end of a line, a "col"
4844 value of 0 is used for both positions.
4845 (default: |FALSE|)
4846
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004847 Can also be used as a |method|: >
4848 getpos('.')->getregionpos(getpos("'a"))
4849<
zeertzjqd4d12072024-07-16 20:34:16 +02004850 Return type: list<list<list<number>>>
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004851
4852
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004853getregtype([{regname}]) *getregtype()*
4854 The result is a String, which is type of register {regname}.
4855 The value will be one of:
4856 "v" for |characterwise| text
4857 "V" for |linewise| text
4858 "<CTRL-V>{width}" for |blockwise-visual| text
4859 "" for an empty or unknown register
4860 <CTRL-V> is one character with value 0x16.
4861 The {regname} argument is a string. If {regname} is "", the
4862 unnamed register '"' is used. If {regname} is not specified,
4863 |v:register| is used.
4864 In |Vim9-script| {regname} must be one character.
4865
4866 Can also be used as a |method|: >
4867 GetRegname()->getregtype()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004868<
4869 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004870
Bram Moolenaar71badf92023-04-22 22:40:14 +01004871getscriptinfo([{opts}]) *getscriptinfo()*
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004872 Returns a |List| with information about all the sourced Vim
Bram Moolenaar753885b2022-08-24 16:30:36 +01004873 scripts in the order they were sourced, like what
4874 `:scriptnames` shows.
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004875
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004876 The optional Dict argument {opts} supports the following
4877 optional items:
4878 name Script name match pattern. If specified,
4879 and "sid" is not specified, information about
Bram Moolenaar71badf92023-04-22 22:40:14 +01004880 scripts with a name that match the pattern
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004881 "name" are returned.
4882 sid Script ID |<SID>|. If specified, only
4883 information about the script with ID "sid" is
4884 returned and "name" is ignored.
4885
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004886 Each item in the returned List is a |Dict| with the following
4887 items:
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004888 autoload Set to TRUE for a script that was used with
Bram Moolenaar753885b2022-08-24 16:30:36 +01004889 `import autoload` but was not actually sourced
4890 yet (see |import-autoload|).
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004891 functions List of script-local function names defined in
4892 the script. Present only when a particular
4893 script is specified using the "sid" item in
4894 {opts}.
4895 name Vim script file name.
4896 sid Script ID |<SID>|.
4897 sourced Script ID of the actually sourced script that
Bram Moolenaarfd999452022-08-24 18:30:14 +01004898 this script name links to, if any, otherwise
4899 zero
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004900 variables A dictionary with the script-local variables.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00004901 Present only when a particular script is
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004902 specified using the "sid" item in {opts}.
4903 Note that this is a copy, the value of
4904 script-local variables cannot be changed using
4905 this dictionary.
h_east59858792023-10-25 22:47:05 +09004906 version Vim script version (|scriptversion|)
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01004907
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004908 Examples: >
4909 :echo getscriptinfo({'name': 'myscript'})
zeertzjqad4881c2024-05-04 15:35:30 +08004910 :echo getscriptinfo({'sid': 15})[0].variables
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004911<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004912 Return type: list<dict<any>>
4913
4914
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004915gettabinfo([{tabnr}]) *gettabinfo()*
4916 If {tabnr} is not specified, then information about all the
4917 tab pages is returned as a |List|. Each List item is a
4918 |Dictionary|. Otherwise, {tabnr} specifies the tab page
4919 number and information about that one is returned. If the tab
4920 page does not exist an empty List is returned.
4921
4922 Each List item is a |Dictionary| with the following entries:
4923 tabnr tab page number.
4924 variables a reference to the dictionary with
4925 tabpage-local variables
4926 windows List of |window-ID|s in the tab page.
4927
4928 Can also be used as a |method|: >
4929 GetTabnr()->gettabinfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004930<
4931 Return type: list<dict<any>>
4932
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004933
4934gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
4935 Get the value of a tab-local variable {varname} in tab page
4936 {tabnr}. |t:var|
4937 Tabs are numbered starting with one.
4938 The {varname} argument is a string. When {varname} is empty a
4939 dictionary with all tab-local variables is returned.
4940 Note that the name without "t:" must be used.
4941 When the tab or variable doesn't exist {def} or an empty
4942 string is returned, there is no error message.
4943
4944 Can also be used as a |method|: >
4945 GetTabnr()->gettabvar(varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004946<
4947 Return type: any, depending on {varname}
4948
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004949
4950gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
4951 Get the value of window-local variable {varname} in window
4952 {winnr} in tab page {tabnr}.
4953 The {varname} argument is a string. When {varname} is empty a
4954 dictionary with all window-local variables is returned.
4955 When {varname} is equal to "&" get the values of all
4956 window-local options in a |Dictionary|.
4957 Otherwise, when {varname} starts with "&" get the value of a
4958 window-local option.
4959 Note that {varname} must be the name without "w:".
4960 Tabs are numbered starting with one. For the current tabpage
4961 use |getwinvar()|.
4962 {winnr} can be the window number or the |window-ID|.
4963 When {winnr} is zero the current window is used.
4964 This also works for a global option, buffer-local option and
4965 window-local option, but it doesn't work for a global variable
4966 or buffer-local variable.
4967 When the tab, window or variable doesn't exist {def} or an
4968 empty string is returned, there is no error message.
4969 Examples: >
4970 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004971 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004972<
4973 To obtain all window-local variables use: >
4974 gettabwinvar({tabnr}, {winnr}, '&')
4975
4976< Can also be used as a |method|: >
4977 GetTabnr()->gettabwinvar(winnr, varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004978<
4979 Return type: any, depending on {varname}
4980
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004981
4982gettagstack([{winnr}]) *gettagstack()*
4983 The result is a Dict, which is the tag stack of window {winnr}.
4984 {winnr} can be the window number or the |window-ID|.
4985 When {winnr} is not specified, the current window is used.
4986 When window {winnr} doesn't exist, an empty Dict is returned.
4987
4988 The returned dictionary contains the following entries:
4989 curidx Current index in the stack. When at
4990 top of the stack, set to (length + 1).
4991 Index of bottom of the stack is 1.
4992 items List of items in the stack. Each item
4993 is a dictionary containing the
4994 entries described below.
4995 length Number of entries in the stack.
4996
4997 Each item in the stack is a dictionary with the following
4998 entries:
4999 bufnr buffer number of the current jump
5000 from cursor position before the tag jump.
5001 See |getpos()| for the format of the
5002 returned list.
5003 matchnr current matching tag number. Used when
5004 multiple matching tags are found for a
5005 name.
5006 tagname name of the tag
5007
5008 See |tagstack| for more information about the tag stack.
5009
5010 Can also be used as a |method|: >
5011 GetWinnr()->gettagstack()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005012<
5013 Return type: dict<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005014
5015
Christ van Willegence0ef912024-06-20 23:41:59 +02005016gettext({text} [, {package}]) *gettext()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005017 Translate String {text} if possible.
RestorerZ96509102024-07-11 21:14:15 +02005018 This is intended for use in Vim scripts. When generating
5019 message translations the {text} is extracted by `xgettext`,
5020 the translator can add translated messages into the .po file
5021 and Vim will lookup the translation when gettext() is called.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005022 For {text} double quoted strings are preferred, because
RestorerZ96509102024-07-11 21:14:15 +02005023 `xgettext` does not support single quoted escaped text.
5024
Christ van Willegence0ef912024-06-20 23:41:59 +02005025 When the {package} is specified, the translation is looked up
RestorerZ96509102024-07-11 21:14:15 +02005026 for that specific package. This is mainly required for
5027 third-party Vim scripts. You need to specify a path to the
5028 translations with the |bindtextdomain()| function before
5029 using the gettext() function.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005030
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005031 Return type: |String|
5032
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005033
5034getwininfo([{winid}]) *getwininfo()*
5035 Returns information about windows as a |List| with Dictionaries.
5036
5037 If {winid} is given Information about the window with that ID
5038 is returned, as a |List| with one item. If the window does not
5039 exist the result is an empty list.
5040
5041 Without {winid} information about all the windows in all the
5042 tab pages is returned.
5043
5044 Each List item is a |Dictionary| with the following entries:
5045 botline last complete displayed buffer line
5046 bufnr number of buffer in the window
5047 height window height (excluding winbar)
5048 loclist 1 if showing a location list
5049 {only with the +quickfix feature}
5050 quickfix 1 if quickfix or location list window
5051 {only with the +quickfix feature}
5052 terminal 1 if a terminal window
5053 {only with the +terminal feature}
5054 tabnr tab page number
5055 topline first displayed buffer line
5056 variables a reference to the dictionary with
5057 window-local variables
5058 width window width
5059 winbar 1 if the window has a toolbar, 0
5060 otherwise
5061 wincol leftmost screen column of the window;
5062 "col" from |win_screenpos()|
5063 textoff number of columns occupied by any
5064 'foldcolumn', 'signcolumn' and line
5065 number in front of the text
5066 winid |window-ID|
5067 winnr window number
5068 winrow topmost screen line of the window;
5069 "row" from |win_screenpos()|
5070
5071 Can also be used as a |method|: >
5072 GetWinnr()->getwininfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005073<
5074 Return type: list<dict<any>>
5075
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005076
5077getwinpos([{timeout}]) *getwinpos()*
5078 The result is a |List| with two numbers, the result of
5079 |getwinposx()| and |getwinposy()| combined:
5080 [x-pos, y-pos]
5081 {timeout} can be used to specify how long to wait in msec for
5082 a response from the terminal. When omitted 100 msec is used.
5083 Use a longer time for a remote terminal.
5084 When using a value less than 10 and no response is received
5085 within that time, a previously reported position is returned,
5086 if available. This can be used to poll for the position and
5087 do some work in the meantime: >
5088 while 1
5089 let res = getwinpos(1)
5090 if res[0] >= 0
5091 break
5092 endif
5093 " Do some work here
5094 endwhile
5095<
5096
5097 Can also be used as a |method|: >
5098 GetTimeout()->getwinpos()
5099<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005100 Return type: list<number>
5101
5102
5103getwinposx() *getwinposx()*
5104 The result is a Number, which is the X coordinate in pixels of
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005105 the left hand side of the GUI Vim window. Also works for an
5106 xterm (uses a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01005107 The result will be -1 if the information is not available
5108 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005109 The value can be used with `:winpos`.
5110
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005111 Return type: |Number|
5112
5113
5114getwinposy() *getwinposy()*
5115 The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005116 the top of the GUI Vim window. Also works for an xterm (uses
5117 a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01005118 The result will be -1 if the information is not available
5119 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005120 The value can be used with `:winpos`.
5121
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005122 Return type: |Number|
5123
5124
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005125getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
5126 Like |gettabwinvar()| for the current tabpage.
5127 Examples: >
5128 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005129 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005130
5131< Can also be used as a |method|: >
5132 GetWinnr()->getwinvar(varname)
5133<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005134 Return type: any, depending on {varname}
5135
5136
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005137glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
5138 Expand the file wildcards in {expr}. See |wildcards| for the
5139 use of special characters.
5140
5141 Unless the optional {nosuf} argument is given and is |TRUE|,
5142 the 'suffixes' and 'wildignore' options apply: Names matching
5143 one of the patterns in 'wildignore' will be skipped and
5144 'suffixes' affect the ordering of matches.
5145 'wildignorecase' always applies.
5146
5147 When {list} is present and it is |TRUE| the result is a |List|
5148 with all matching files. The advantage of using a List is,
5149 you also get filenames containing newlines correctly.
5150 Otherwise the result is a String and when there are several
5151 matches, they are separated by <NL> characters.
5152
5153 If the expansion fails, the result is an empty String or List.
5154
5155 You can also use |readdir()| if you need to do complicated
5156 things, such as limiting the number of matches.
5157
5158 A name for a non-existing file is not included. A symbolic
5159 link is only included if it points to an existing file.
5160 However, when the {alllinks} argument is present and it is
5161 |TRUE| then all symbolic links are included.
5162
5163 For most systems backticks can be used to get files names from
5164 any external command. Example: >
5165 :let tagfiles = glob("`find . -name tags -print`")
5166 :let &tags = substitute(tagfiles, "\n", ",", "g")
5167< The result of the program inside the backticks should be one
5168 item per line. Spaces inside an item are allowed.
5169
5170 See |expand()| for expanding special Vim variables. See
5171 |system()| for getting the raw output of an external command.
5172
5173 Can also be used as a |method|: >
5174 GetExpr()->glob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005175<
5176 Return type: |String| or list<string> or list<any> depending
5177 on {list}
5178
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005179
5180glob2regpat({string}) *glob2regpat()*
5181 Convert a file pattern, as used by glob(), into a search
5182 pattern. The result can be used to match with a string that
5183 is a file name. E.g. >
5184 if filename =~ glob2regpat('Make*.mak')
5185< This is equivalent to: >
5186 if filename =~ '^Make.*\.mak$'
5187< When {string} is an empty string the result is "^$", match an
5188 empty string.
5189 Note that the result depends on the system. On MS-Windows
5190 a backslash usually means a path separator.
5191
5192 Can also be used as a |method|: >
5193 GetExpr()->glob2regpat()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005194<
5195 Return type: |String|
5196
5197 *globpath()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005198globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
5199 Perform glob() for String {expr} on all directories in {path}
5200 and concatenate the results. Example: >
5201 :echo globpath(&rtp, "syntax/c.vim")
5202<
5203 {path} is a comma-separated list of directory names. Each
5204 directory name is prepended to {expr} and expanded like with
5205 |glob()|. A path separator is inserted when needed.
5206 To add a comma inside a directory name escape it with a
5207 backslash. Note that on MS-Windows a directory may have a
5208 trailing backslash, remove it if you put a comma after it.
5209 If the expansion fails for one of the directories, there is no
5210 error message.
5211
5212 Unless the optional {nosuf} argument is given and is |TRUE|,
5213 the 'suffixes' and 'wildignore' options apply: Names matching
5214 one of the patterns in 'wildignore' will be skipped and
5215 'suffixes' affect the ordering of matches.
5216
5217 When {list} is present and it is |TRUE| the result is a |List|
5218 with all matching files. The advantage of using a List is, you
5219 also get filenames containing newlines correctly. Otherwise
5220 the result is a String and when there are several matches,
5221 they are separated by <NL> characters. Example: >
5222 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
5223<
5224 {alllinks} is used as with |glob()|.
5225
5226 The "**" item can be used to search in a directory tree.
5227 For example, to find all "README.txt" files in the directories
5228 in 'runtimepath' and below: >
5229 :echo globpath(&rtp, "**/README.txt")
5230< Upwards search and limiting the depth of "**" is not
5231 supported, thus using 'path' will not always work properly.
5232
5233 Can also be used as a |method|, the base is passed as the
5234 second argument: >
5235 GetExpr()->globpath(&rtp)
5236<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005237 Return type: |String| or list<string> or list<any> depending
5238 on {list}
5239
5240
5241has({feature} [, {check}]) *has()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005242 When {check} is omitted or is zero: The result is a Number,
5243 which is 1 if the feature {feature} is supported, zero
5244 otherwise. The {feature} argument is a string, case is
5245 ignored. See |feature-list| below.
5246
5247 When {check} is present and not zero: The result is a Number,
5248 which is 1 if the feature {feature} could ever be supported,
5249 zero otherwise. This is useful to check for a typo in
5250 {feature} and to detect dead code. Keep in mind that an older
5251 Vim version will not know about a feature added later and
5252 features that have been abandoned will not be known by the
5253 current Vim version.
5254
5255 Also see |exists()| and |exists_compiled()|.
5256
5257 Note that to skip code that has a syntax error when the
5258 feature is not available, Vim may skip the rest of the line
5259 and miss a following `endif`. Therefore put the `endif` on a
5260 separate line: >
5261 if has('feature')
5262 let x = this->breaks->without->the->feature
5263 endif
5264< If the `endif` would be moved to the second line as "| endif" it
5265 would not be found.
5266
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005267 Return type: |Number|
5268
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005269
5270has_key({dict}, {key}) *has_key()*
5271 The result is a Number, which is TRUE if |Dictionary| {dict}
Bram Moolenaare8008642022-08-19 17:15:35 +01005272 has an entry with key {key}. FALSE otherwise.
5273 The {key} argument is a string. In |Vim9| script a number is
5274 also accepted (and converted to a string) but no other types.
5275 In legacy script the usual automatic conversion to string is
5276 done.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005277
5278 Can also be used as a |method|: >
5279 mydict->has_key(key)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005280<
5281 Return type: |Number|
5282
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005283
5284haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
5285 The result is a Number:
5286 1 when the window has set a local directory via |:lcd|
5287 2 when the tab-page has set a local directory via |:tcd|
5288 0 otherwise.
5289
5290 Without arguments use the current window.
5291 With {winnr} use this window in the current tab page.
5292 With {winnr} and {tabnr} use the window in the specified tab
5293 page.
5294 {winnr} can be the window number or the |window-ID|.
5295 If {winnr} is -1 it is ignored and only the tabpage is used.
5296 Return 0 if the arguments are invalid.
5297 Examples: >
5298 if haslocaldir() == 1
5299 " window local directory case
5300 elseif haslocaldir() == 2
5301 " tab-local directory case
5302 else
5303 " global directory case
5304 endif
5305
5306 " current window
5307 :echo haslocaldir()
5308 :echo haslocaldir(0)
5309 :echo haslocaldir(0, 0)
5310 " window n in current tab page
5311 :echo haslocaldir(n)
5312 :echo haslocaldir(n, 0)
5313 " window n in tab page m
5314 :echo haslocaldir(n, m)
5315 " tab page m
5316 :echo haslocaldir(-1, m)
5317<
5318 Can also be used as a |method|: >
5319 GetWinnr()->haslocaldir()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005320<
5321 Return type: |Number|
5322
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005323
5324hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
5325 The result is a Number, which is TRUE if there is a mapping
5326 that contains {what} in somewhere in the rhs (what it is
5327 mapped to) and this mapping exists in one of the modes
5328 indicated by {mode}.
5329 The arguments {what} and {mode} are strings.
5330 When {abbr} is there and it is |TRUE| use abbreviations
5331 instead of mappings. Don't forget to specify Insert and/or
5332 Command-line mode.
5333 Both the global mappings and the mappings local to the current
5334 buffer are checked for a match.
5335 If no matching mapping is found FALSE is returned.
5336 The following characters are recognized in {mode}:
5337 n Normal mode
5338 v Visual and Select mode
5339 x Visual mode
5340 s Select mode
5341 o Operator-pending mode
5342 i Insert mode
5343 l Language-Argument ("r", "f", "t", etc.)
5344 c Command-line mode
5345 When {mode} is omitted, "nvo" is used.
5346
5347 This function is useful to check if a mapping already exists
5348 to a function in a Vim script. Example: >
5349 :if !hasmapto('\ABCdoit')
5350 : map <Leader>d \ABCdoit
5351 :endif
5352< This installs the mapping to "\ABCdoit" only if there isn't
5353 already a mapping to "\ABCdoit".
5354
5355 Can also be used as a |method|: >
5356 GetRHS()->hasmapto()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005357<
5358 Return type: |Number|
5359
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005360
5361histadd({history}, {item}) *histadd()*
5362 Add the String {item} to the history {history} which can be
5363 one of: *hist-names*
5364 "cmd" or ":" command line history
5365 "search" or "/" search pattern history
5366 "expr" or "=" typed expression history
5367 "input" or "@" input line history
5368 "debug" or ">" debug command history
5369 empty the current or last used history
5370 The {history} string does not need to be the whole name, one
5371 character is sufficient.
5372 If {item} does already exist in the history, it will be
5373 shifted to become the newest entry.
5374 The result is a Number: TRUE if the operation was successful,
5375 otherwise FALSE is returned.
5376
5377 Example: >
5378 :call histadd("input", strftime("%Y %b %d"))
5379 :let date=input("Enter date: ")
5380< This function is not available in the |sandbox|.
5381
5382 Can also be used as a |method|, the base is passed as the
5383 second argument: >
5384 GetHistory()->histadd('search')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005385<
5386 Return type: |Number|
5387
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005388
5389histdel({history} [, {item}]) *histdel()*
5390 Clear {history}, i.e. delete all its entries. See |hist-names|
5391 for the possible values of {history}.
5392
5393 If the parameter {item} evaluates to a String, it is used as a
5394 regular expression. All entries matching that expression will
5395 be removed from the history (if there are any).
5396 Upper/lowercase must match, unless "\c" is used |/\c|.
5397 If {item} evaluates to a Number, it will be interpreted as
5398 an index, see |:history-indexing|. The respective entry will
5399 be removed if it exists.
5400
5401 The result is TRUE for a successful operation, otherwise FALSE
5402 is returned.
5403
5404 Examples:
5405 Clear expression register history: >
5406 :call histdel("expr")
5407<
5408 Remove all entries starting with "*" from the search history: >
5409 :call histdel("/", '^\*')
5410<
5411 The following three are equivalent: >
5412 :call histdel("search", histnr("search"))
5413 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005414 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005415<
5416 To delete the last search pattern and use the last-but-one for
5417 the "n" command and 'hlsearch': >
5418 :call histdel("search", -1)
5419 :let @/ = histget("search", -1)
5420<
5421 Can also be used as a |method|: >
5422 GetHistory()->histdel()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005423<
5424 Return type: |Number|
5425
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005426
5427histget({history} [, {index}]) *histget()*
5428 The result is a String, the entry with Number {index} from
5429 {history}. See |hist-names| for the possible values of
5430 {history}, and |:history-indexing| for {index}. If there is
5431 no such entry, an empty String is returned. When {index} is
5432 omitted, the most recent item from the history is used.
5433
5434 Examples:
5435 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005436 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005437
5438< Define an Ex command ":H {num}" that supports re-execution of
5439 the {num}th entry from the output of |:history|. >
5440 :command -nargs=1 H execute histget("cmd", 0+<args>)
5441<
5442 Can also be used as a |method|: >
5443 GetHistory()->histget()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005444<
5445 Return type: |String|
5446
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005447
5448histnr({history}) *histnr()*
5449 The result is the Number of the current entry in {history}.
5450 See |hist-names| for the possible values of {history}.
5451 If an error occurred, -1 is returned.
5452
5453 Example: >
5454 :let inp_index = histnr("expr")
5455
5456< Can also be used as a |method|: >
5457 GetHistory()->histnr()
5458<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005459 Return type: |Number|
5460
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005461hlexists({name}) *hlexists()*
5462 The result is a Number, which is TRUE if a highlight group
5463 called {name} exists. This is when the group has been
5464 defined in some way. Not necessarily when highlighting has
5465 been defined for it, it may also have been used for a syntax
5466 item.
5467 *highlight_exists()*
5468 Obsolete name: highlight_exists().
5469
5470 Can also be used as a |method|: >
5471 GetName()->hlexists()
5472<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005473 Return type: |Number|
5474
5475
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005476hlget([{name} [, {resolve}]]) *hlget()*
5477 Returns a List of all the highlight group attributes. If the
5478 optional {name} is specified, then returns a List with only
5479 the attributes of the specified highlight group. Returns an
5480 empty List if the highlight group {name} is not present.
5481
5482 If the optional {resolve} argument is set to v:true and the
5483 highlight group {name} is linked to another group, then the
5484 link is resolved recursively and the attributes of the
5485 resolved highlight group are returned.
5486
5487 Each entry in the returned List is a Dictionary with the
5488 following items:
5489 cleared boolean flag, set to v:true if the highlight
5490 group attributes are cleared or not yet
5491 specified. See |highlight-clear|.
5492 cterm cterm attributes. See |highlight-cterm|.
5493 ctermbg cterm background color.
5494 See |highlight-ctermbg|.
5495 ctermfg cterm foreground color.
5496 See |highlight-ctermfg|.
5497 ctermul cterm underline color. See |highlight-ctermul|.
5498 default boolean flag, set to v:true if the highlight
5499 group link is a default link. See
5500 |highlight-default|.
5501 font highlight group font. See |highlight-font|.
5502 gui gui attributes. See |highlight-gui|.
5503 guibg gui background color. See |highlight-guibg|.
5504 guifg gui foreground color. See |highlight-guifg|.
5505 guisp gui special color. See |highlight-guisp|.
5506 id highlight group ID.
5507 linksto linked highlight group name.
5508 See |:highlight-link|.
5509 name highlight group name. See |group-name|.
5510 start start terminal keycode. See |highlight-start|.
5511 stop stop terminal keycode. See |highlight-stop|.
5512 term term attributes. See |highlight-term|.
5513
5514 The 'term', 'cterm' and 'gui' items in the above Dictionary
5515 have a dictionary value with the following optional boolean
5516 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
5517 'reverse', 'inverse' and 'strikethrough'.
5518
5519 Example(s): >
5520 :echo hlget()
5521 :echo hlget('ModeMsg')
5522 :echo hlget('Number', v:true)
5523<
5524 Can also be used as a |method|: >
5525 GetName()->hlget()
5526<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005527 Return type: list<dict<any>>
5528
5529
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005530hlset({list}) *hlset()*
5531 Creates or modifies the attributes of a List of highlight
5532 groups. Each item in {list} is a dictionary containing the
5533 attributes of a highlight group. See |hlget()| for the list of
5534 supported items in this dictionary.
5535
5536 In addition to the items described in |hlget()|, the following
5537 additional items are supported in the dictionary:
5538
5539 force boolean flag to force the creation of
5540 a link for an existing highlight group
5541 with attributes.
5542
5543 The highlight group is identified using the 'name' item and
5544 the 'id' item (if supplied) is ignored. If a highlight group
5545 with a specified name doesn't exist, then it is created.
5546 Otherwise the attributes of an existing highlight group are
5547 modified.
5548
5549 If an empty dictionary value is used for the 'term' or 'cterm'
5550 or 'gui' entries, then the corresponding attributes are
5551 cleared. If the 'cleared' item is set to v:true, then all the
5552 attributes of the highlight group are cleared.
5553
5554 The 'linksto' item can be used to link a highlight group to
5555 another highlight group. See |:highlight-link|.
5556
5557 Returns zero for success, -1 for failure.
5558
5559 Example(s): >
5560 " add bold attribute to the Visual highlight group
5561 :call hlset([#{name: 'Visual',
5562 \ term: #{reverse: 1 , bold: 1}}])
5563 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
5564 :let l = hlget()
5565 :call hlset(l)
5566 " clear the Search highlight group
5567 :call hlset([#{name: 'Search', cleared: v:true}])
5568 " clear the 'term' attributes for a highlight group
5569 :call hlset([#{name: 'Title', term: {}}])
5570 " create the MyHlg group linking it to DiffAdd
5571 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
5572 " remove the MyHlg group link
5573 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
5574 " clear the attributes and a link
5575 :call hlset([#{name: 'MyHlg', cleared: v:true,
5576 \ linksto: 'NONE'}])
5577<
5578 Can also be used as a |method|: >
5579 GetAttrList()->hlset()
5580<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005581 Return type: |Number|
5582
5583hlID({name}) *hlID()*
5584 The result is a Number, which is the ID of the highlight group
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005585 with name {name}. When the highlight group doesn't exist,
5586 zero is returned.
5587 This can be used to retrieve information about the highlight
5588 group. For example, to get the background color of the
5589 "Comment" group: >
5590 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5591< *highlightID()*
5592 Obsolete name: highlightID().
5593
5594 Can also be used as a |method|: >
5595 GetName()->hlID()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005596<
5597 Return type: |Number|
5598
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005599
5600hostname() *hostname()*
5601 The result is a String, which is the name of the machine on
5602 which Vim is currently running. Machine names greater than
5603 256 characters long are truncated.
5604
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005605 Return type: |String|
5606
5607
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005608iconv({string}, {from}, {to}) *iconv()*
5609 The result is a String, which is the text {string} converted
5610 from encoding {from} to encoding {to}.
5611 When the conversion completely fails an empty string is
5612 returned. When some characters could not be converted they
5613 are replaced with "?".
5614 The encoding names are whatever the iconv() library function
5615 can accept, see ":!man 3 iconv".
5616 Most conversions require Vim to be compiled with the |+iconv|
5617 feature. Otherwise only UTF-8 to latin1 conversion and back
5618 can be done.
5619 This can be used to display messages with special characters,
5620 no matter what 'encoding' is set to. Write the message in
5621 UTF-8 and use: >
5622 echo iconv(utf8_str, "utf-8", &enc)
5623< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5624 from/to UCS-2 is automatically changed to use UTF-8. You
5625 cannot use UCS-2 in a string anyway, because of the NUL bytes.
5626
5627 Can also be used as a |method|: >
5628 GetText()->iconv('latin1', 'utf-8')
5629<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005630 Return type: |String|
5631
5632
Ernie Raelc8e158b2024-07-09 18:39:52 +02005633id({item}) *id()*
5634 The result is a unique String associated with the {item} and
5635 not with the {item}'s contents. It is only valid while the
5636 {item} exists and is referenced. It is valid only in the
5637 instance of vim that produces the result. The whole idea is
5638 that `id({item})` does not change if the contents of {item}
5639 changes. This is useful as a `key` for creating an identity
5640 dictionary, rather than one based on equals.
5641
5642 This operation does not reference {item} and there is no
5643 function to convert the `id` to the {item}. It may be useful to
5644 have a map of `id` to {item}. The following >
5645 var referenceMap: dict<any>
5646 var id = item->id()
5647 referenceMap[id] = item
5648< prevents {item} from being garbage collected and provides a
5649 way to get the {item} from the `id`.
5650
5651 {item} may be a List, Dictionary, Object, Job, Channel or
5652 Blob. If the item is not a permitted type, or it is a null
5653 value, then an empty String is returned.
5654
5655 Can also be used as a |method|: >
5656 GetItem()->id()
5657<
5658 Return type: |String|
5659
5660
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005661indent({lnum}) *indent()*
5662 The result is a Number, which is indent of line {lnum} in the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005663 current buffer. The indent is counted in spaces, the value
5664 of 'tabstop' is relevant. {lnum} is used just like in
5665 |getline()|.
5666 When {lnum} is invalid -1 is returned. In |Vim9| script an
5667 error is given.
5668
5669 Can also be used as a |method|: >
5670 GetLnum()->indent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005671<
5672 Return type: |Number|
5673
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005674
5675index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005676 Find {expr} in {object} and return its index. See
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005677 |indexof()| for using a lambda to select the item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005678
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005679 If {object} is a |List| return the lowest index where the item
5680 has a value equal to {expr}. There is no automatic
5681 conversion, so the String "4" is different from the Number 4.
5682 And the number 4 is different from the Float 4.0. The value
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005683 of 'ignorecase' is not used here, case matters as indicated by
5684 the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005685
5686 If {object} is |Blob| return the lowest index where the byte
5687 value is equal to {expr}.
5688
5689 If {start} is given then start looking at the item with index
5690 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005691
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005692 When {ic} is given and it is |TRUE|, ignore case. Otherwise
5693 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005694
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005695 -1 is returned when {expr} is not found in {object}.
5696 Example: >
5697 :let idx = index(words, "the")
5698 :if index(numbers, 123) >= 0
5699
5700< Can also be used as a |method|: >
5701 GetObject()->index(what)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005702<
5703 Return type: |Number|
5704
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005705
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005706indexof({object}, {expr} [, {opts}]) *indexof()*
5707 Returns the index of an item in {object} where {expr} is
5708 v:true. {object} must be a |List| or a |Blob|.
5709
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005710 If {object} is a |List|, evaluate {expr} for each item in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005711 List until the expression is v:true and return the index of
5712 this item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005713
5714 If {object} is a |Blob| evaluate {expr} for each byte in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005715 Blob until the expression is v:true and return the index of
5716 this byte.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005717
5718 {expr} must be a |string| or |Funcref|.
5719
5720 If {expr} is a |string|: If {object} is a |List|, inside
5721 {expr} |v:key| has the index of the current List item and
5722 |v:val| has the value of the item. If {object} is a |Blob|,
5723 inside {expr} |v:key| has the index of the current byte and
5724 |v:val| has the byte value.
5725
5726 If {expr} is a |Funcref| it must take two arguments:
5727 1. the key or the index of the current item.
5728 2. the value of the current item.
5729 The function must return |TRUE| if the item is found and the
5730 search should stop.
5731
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005732 The optional argument {opts} is a Dict and supports the
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005733 following items:
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005734 startidx start evaluating {expr} at the item with this
5735 index; may be negative for an item relative to
5736 the end
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005737 Returns -1 when {expr} evaluates to v:false for all the items.
5738 Example: >
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005739 :let l = [#{n: 10}, #{n: 20}, #{n: 30}]
5740 :echo indexof(l, "v:val.n == 20")
5741 :echo indexof(l, {i, v -> v.n == 30})
5742 :echo indexof(l, "v:val.n == 20", #{startidx: 1})
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005743
5744< Can also be used as a |method|: >
5745 mylist->indexof(expr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005746<
5747 Return type: |Number|
5748
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005749
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005750input({prompt} [, {text} [, {completion}]]) *input()*
5751 The result is a String, which is whatever the user typed on
5752 the command-line. The {prompt} argument is either a prompt
5753 string, or a blank string (for no prompt). A '\n' can be used
5754 in the prompt to start a new line.
5755 The highlighting set with |:echohl| is used for the prompt.
5756 The input is entered just like a command-line, with the same
5757 editing commands and mappings. There is a separate history
5758 for lines typed for input().
5759 Example: >
5760 :if input("Coffee or beer? ") == "beer"
5761 : echo "Cheers!"
5762 :endif
5763<
5764 If the optional {text} argument is present and not empty, this
5765 is used for the default reply, as if the user typed this.
5766 Example: >
5767 :let color = input("Color? ", "white")
5768
5769< The optional {completion} argument specifies the type of
5770 completion supported for the input. Without it completion is
5771 not performed. The supported completion types are the same as
5772 that can be supplied to a user-defined command using the
5773 "-complete=" argument. Refer to |:command-completion| for
5774 more information. Example: >
5775 let fname = input("File: ", "", "file")
5776<
5777 NOTE: This function must not be used in a startup file, for
5778 the versions that only run in GUI mode (e.g., the Win32 GUI).
5779 Note: When input() is called from within a mapping it will
5780 consume remaining characters from that mapping, because a
5781 mapping is handled like the characters were typed.
5782 Use |inputsave()| before input() and |inputrestore()|
5783 after input() to avoid that. Another solution is to avoid
5784 that further characters follow in the mapping, e.g., by using
5785 |:execute| or |:normal|.
5786
5787 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005788 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005789 :function GetFoo()
5790 : call inputsave()
5791 : let g:Foo = input("enter search pattern: ")
5792 : call inputrestore()
5793 :endfunction
5794
5795< Can also be used as a |method|: >
5796 GetPrompt()->input()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005797<
5798 Return type: |String|
5799
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005800
5801inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
5802 Like |input()|, but when the GUI is running and text dialogs
5803 are supported, a dialog window pops up to input the text.
5804 Example: >
5805 :let n = inputdialog("value for shiftwidth", shiftwidth())
5806 :if n != ""
5807 : let &sw = n
5808 :endif
5809< When the dialog is cancelled {cancelreturn} is returned. When
5810 omitted an empty string is returned.
5811 Hitting <Enter> works like pressing the OK button. Hitting
5812 <Esc> works like pressing the Cancel button.
5813 NOTE: Command-line completion is not supported.
5814
5815 Can also be used as a |method|: >
5816 GetPrompt()->inputdialog()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005817<
5818 Return type: |String|
5819
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005820
5821inputlist({textlist}) *inputlist()*
5822 {textlist} must be a |List| of strings. This |List| is
5823 displayed, one string per line. The user will be prompted to
5824 enter a number, which is returned.
5825 The user can also select an item by clicking on it with the
5826 mouse, if the mouse is enabled in the command line ('mouse' is
5827 "a" or includes "c"). For the first string 0 is returned.
5828 When clicking above the first item a negative number is
5829 returned. When clicking on the prompt one more than the
5830 length of {textlist} is returned.
5831 Make sure {textlist} has less than 'lines' entries, otherwise
5832 it won't work. It's a good idea to put the entry number at
5833 the start of the string. And put a prompt in the first item.
5834 Example: >
5835 let color = inputlist(['Select color:', '1. red',
5836 \ '2. green', '3. blue'])
5837
5838< Can also be used as a |method|: >
5839 GetChoices()->inputlist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005840<
5841 Return type: |Number|
5842
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005843
5844inputrestore() *inputrestore()*
5845 Restore typeahead that was saved with a previous |inputsave()|.
5846 Should be called the same number of times inputsave() is
5847 called. Calling it more often is harmless though.
5848 Returns TRUE when there is nothing to restore, FALSE otherwise.
5849
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005850 Return type: |Number|
5851
5852
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005853inputsave() *inputsave()*
5854 Preserve typeahead (also from mappings) and clear it, so that
5855 a following prompt gets input from the user. Should be
5856 followed by a matching inputrestore() after the prompt. Can
5857 be used several times, in which case there must be just as
5858 many inputrestore() calls.
5859 Returns TRUE when out of memory, FALSE otherwise.
5860
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005861 Return type: |Number|
5862
5863
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005864inputsecret({prompt} [, {text}]) *inputsecret()*
5865 This function acts much like the |input()| function with but
5866 two exceptions:
5867 a) the user's response will be displayed as a sequence of
5868 asterisks ("*") thereby keeping the entry secret, and
5869 b) the user's response will not be recorded on the input
5870 |history| stack.
5871 The result is a String, which is whatever the user actually
5872 typed on the command-line in response to the issued prompt.
5873 NOTE: Command-line completion is not supported.
5874
5875 Can also be used as a |method|: >
5876 GetPrompt()->inputsecret()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005877<
5878 Return type: |String|
5879
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005880
5881insert({object}, {item} [, {idx}]) *insert()*
5882 When {object} is a |List| or a |Blob| insert {item} at the start
5883 of it.
5884
5885 If {idx} is specified insert {item} before the item with index
5886 {idx}. If {idx} is zero it goes before the first item, just
5887 like omitting {idx}. A negative {idx} is also possible, see
5888 |list-index|. -1 inserts just before the last item.
5889
5890 Returns the resulting |List| or |Blob|. Examples: >
5891 :let mylist = insert([2, 3, 5], 1)
5892 :call insert(mylist, 4, -1)
5893 :call insert(mylist, 6, len(mylist))
5894< The last example can be done simpler with |add()|.
5895 Note that when {item} is a |List| it is inserted as a single
5896 item. Use |extend()| to concatenate |Lists|.
5897
5898 Can also be used as a |method|: >
5899 mylist->insert(item)
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005900<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005901 Return type: |Number|
5902
5903
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005904 *instanceof()* *E614* *E616* *E693*
5905instanceof({object}, {class})
5906 The result is a Number, which is |TRUE| when the {object}
Ernie Rael2025af12023-12-12 16:58:00 +01005907 argument is a direct or indirect instance of a |Class|,
5908 |Interface|, or class |:type| alias specified by {class}.
5909 If {class} is varargs, the function returns |TRUE| when
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005910 {object} is an instance of any of the specified classes.
LemonBoyafe04662023-08-23 21:08:11 +02005911 Example: >
Ernie Rael2025af12023-12-12 16:58:00 +01005912 instanceof(animal, Dog, Cat)
LemonBoyafe04662023-08-23 21:08:11 +02005913
5914< Can also be used as a |method|: >
5915 myobj->instanceof(mytype)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005916<
5917 Return type: |Number|
LemonBoyafe04662023-08-23 21:08:11 +02005918
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005919interrupt() *interrupt()*
5920 Interrupt script execution. It works more or less like the
5921 user typing CTRL-C, most commands won't execute and control
5922 returns to the user. This is useful to abort execution
5923 from lower down, e.g. in an autocommand. Example: >
5924 :function s:check_typoname(file)
5925 : if fnamemodify(a:file, ':t') == '['
5926 : echomsg 'Maybe typo'
5927 : call interrupt()
5928 : endif
5929 :endfunction
5930 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005931<
5932 Return type: void
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005933
5934invert({expr}) *invert()*
5935 Bitwise invert. The argument is converted to a number. A
5936 List, Dict or Float argument causes an error. Example: >
5937 :let bits = invert(bits)
5938< Can also be used as a |method|: >
5939 :let bits = bits->invert()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005940<
5941 Return type: |Number|
5942
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005943
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005944isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01005945 The result is a Number, which is |TRUE| when {path} is an
5946 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005947 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01005948 On MS-Windows, it is considered absolute when it starts with an
5949 optional drive prefix and is followed by a '\' or '/'. UNC paths
5950 are always absolute.
5951 Example: >
5952 echo isabsolutepath('/usr/share/') " 1
5953 echo isabsolutepath('./foobar') " 0
5954 echo isabsolutepath('C:\Windows') " 1
5955 echo isabsolutepath('foobar') " 0
5956 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005957<
LemonBoydca1d402022-04-28 15:26:33 +01005958 Can also be used as a |method|: >
5959 GetName()->isabsolutepath()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005960<
5961 Return type: |Number|
LemonBoydca1d402022-04-28 15:26:33 +01005962
5963
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005964isdirectory({directory}) *isdirectory()*
5965 The result is a Number, which is |TRUE| when a directory
5966 with the name {directory} exists. If {directory} doesn't
5967 exist, or isn't a directory, the result is |FALSE|. {directory}
5968 is any expression, which is used as a String.
5969
5970 Can also be used as a |method|: >
5971 GetName()->isdirectory()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005972<
5973 Return type: |Number|
5974
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005975
5976isinf({expr}) *isinf()*
5977 Return 1 if {expr} is a positive infinity, or -1 a negative
5978 infinity, otherwise 0. >
5979 :echo isinf(1.0 / 0.0)
5980< 1 >
5981 :echo isinf(-1.0 / 0.0)
5982< -1
5983
5984 Can also be used as a |method|: >
5985 Compute()->isinf()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005986<
5987 Return type: |Number|
5988
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005989
5990islocked({expr}) *islocked()* *E786*
5991 The result is a Number, which is |TRUE| when {expr} is the
5992 name of a locked variable.
5993 The string argument {expr} must be the name of a variable,
5994 |List| item or |Dictionary| entry, not the variable itself!
5995 Example: >
5996 :let alist = [0, ['a', 'b'], 2, 3]
5997 :lockvar 1 alist
5998 :echo islocked('alist') " 1
5999 :echo islocked('alist[1]') " 0
6000
Bram Moolenaar9da17d72022-02-09 21:50:44 +00006001< When {expr} is a variable that does not exist -1 is returned.
6002 If {expr} uses a range, list or dict index that is out of
6003 range or does not exist you get an error message. Use
6004 |exists()| to check for existence.
6005 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006006
6007 Can also be used as a |method|: >
6008 GetName()->islocked()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006009<
6010 Return type: |Number|
6011
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006012
6013isnan({expr}) *isnan()*
6014 Return |TRUE| if {expr} is a float with value NaN. >
6015 echo isnan(0.0 / 0.0)
6016< 1
6017
6018 Can also be used as a |method|: >
6019 Compute()->isnan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006020<
6021 Return type: |Number|
6022
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006023
6024items({dict}) *items()*
6025 Return a |List| with all the key-value pairs of {dict}. Each
6026 |List| item is a list with two items: the key of a {dict}
6027 entry and the value of this entry. The |List| is in arbitrary
6028 order. Also see |keys()| and |values()|.
6029 Example: >
6030 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006031 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006032 endfor
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01006033<
6034 A List or a String argument is also supported. In these
6035 cases, items() returns a List with the index and the value at
6036 the index.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006037
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01006038 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006039 mydict->items()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006040<
6041 Return type: list<list<any>> or list<any>
6042
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006043
6044job_ functions are documented here: |job-functions-details|
6045
6046
6047join({list} [, {sep}]) *join()*
6048 Join the items in {list} together into one String.
6049 When {sep} is specified it is put in between the items. If
6050 {sep} is omitted a single space is used.
6051 Note that {sep} is not added at the end. You might want to
6052 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006053 let lines = join(mylist, "\n") .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006054< String items are used as-is. |Lists| and |Dictionaries| are
6055 converted into a string like with |string()|.
6056 The opposite function is |split()|.
6057
6058 Can also be used as a |method|: >
6059 mylist->join()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006060<
6061 Return type: |String|
6062
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006063
6064js_decode({string}) *js_decode()*
6065 This is similar to |json_decode()| with these differences:
6066 - Object key names do not have to be in quotes.
6067 - Strings can be in single quotes.
6068 - Empty items in an array (between two commas) are allowed and
6069 result in v:none items.
6070
6071 Can also be used as a |method|: >
6072 ReadObject()->js_decode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006073<
6074 Return type: any, depending on {varname}
6075
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006076
6077js_encode({expr}) *js_encode()*
6078 This is similar to |json_encode()| with these differences:
6079 - Object key names are not in quotes.
6080 - v:none items in an array result in an empty item between
6081 commas.
6082 For example, the Vim object:
6083 [1,v:none,{"one":1},v:none] ~
6084 Will be encoded as:
6085 [1,,{one:1},,] ~
6086 While json_encode() would produce:
6087 [1,null,{"one":1},null] ~
6088 This encoding is valid for JavaScript. It is more efficient
6089 than JSON, especially when using an array with optional items.
6090
6091 Can also be used as a |method|: >
6092 GetObject()->js_encode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006093<
6094 Return type: |String|
6095
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006096
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00006097json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006098 This parses a JSON formatted string and returns the equivalent
6099 in Vim values. See |json_encode()| for the relation between
6100 JSON and Vim values.
6101 The decoding is permissive:
6102 - A trailing comma in an array and object is ignored, e.g.
6103 "[1, 2, ]" is the same as "[1, 2]".
6104 - Integer keys are accepted in objects, e.g. {1:2} is the
6105 same as {"1":2}.
6106 - More floating point numbers are recognized, e.g. "1." for
6107 "1.0", or "001.2" for "1.2". Special floating point values
6108 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
6109 are accepted.
6110 - Leading zeroes in integer numbers are ignored, e.g. "012"
6111 for "12" or "-012" for "-12".
6112 - Capitalization is ignored in literal names null, true or
6113 false, e.g. "NULL" for "null", "True" for "true".
6114 - Control characters U+0000 through U+001F which are not
6115 escaped in strings are accepted, e.g. " " (tab
6116 character in string) for "\t".
6117 - An empty JSON expression or made of only spaces is accepted
6118 and results in v:none.
6119 - Backslash in an invalid 2-character sequence escape is
6120 ignored, e.g. "\a" is decoded as "a".
6121 - A correct surrogate pair in JSON strings should normally be
6122 a 12 character sequence such as "\uD834\uDD1E", but
6123 json_decode() silently accepts truncated surrogate pairs
6124 such as "\uD834" or "\uD834\u"
6125 *E938*
6126 A duplicate key in an object, valid in rfc7159, is not
6127 accepted by json_decode() as the result must be a valid Vim
6128 type, e.g. this fails: {"a":"b", "a":"c"}
6129
6130 Can also be used as a |method|: >
6131 ReadObject()->json_decode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006132<
6133 Return type: any, depending on {varname}
6134
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006135
6136json_encode({expr}) *json_encode()*
6137 Encode {expr} as JSON and return this as a string.
6138 The encoding is specified in:
6139 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00006140 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006141 |Number| decimal number
6142 |Float| floating point number
6143 Float nan "NaN"
6144 Float inf "Infinity"
6145 Float -inf "-Infinity"
6146 |String| in double quotes (possibly null)
6147 |Funcref| not possible, error
6148 |List| as an array (possibly null); when
6149 used recursively: []
6150 |Dict| as an object (possibly null); when
6151 used recursively: {}
6152 |Blob| as an array of the individual bytes
6153 v:false "false"
6154 v:true "true"
6155 v:none "null"
6156 v:null "null"
6157 Note that NaN and Infinity are passed on as values. This is
6158 missing in the JSON standard, but several implementations do
6159 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006160 If a string contains an illegal character then the replacement
6161 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006162
6163 Can also be used as a |method|: >
6164 GetObject()->json_encode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006165<
6166 Return type: |String|
6167
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006168
6169keys({dict}) *keys()*
6170 Return a |List| with all the keys of {dict}. The |List| is in
6171 arbitrary order. Also see |items()| and |values()|.
6172
6173 Can also be used as a |method|: >
6174 mydict->keys()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006175<
6176 Return type: list<string>
6177
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006178
zeertzjqcdc83932022-09-12 13:38:41 +01006179keytrans({string}) *keytrans()*
6180 Turn the internal byte representation of keys into a form that
6181 can be used for |:map|. E.g. >
6182 :let xx = "\<C-Home>"
6183 :echo keytrans(xx)
6184< <C-Home>
6185
6186 Can also be used as a |method|: >
6187 "\<C-Home>"->keytrans()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006188<
6189 Return type: |String|
zeertzjqcdc83932022-09-12 13:38:41 +01006190
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006191
6192len({expr}) *len()* *E701*
6193 The result is a Number, which is the length of the argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006194 When {expr} is a String or a Number the length in bytes is
6195 used, as with |strlen()|.
6196 When {expr} is a |List| the number of items in the |List| is
6197 returned.
6198 When {expr} is a |Blob| the number of bytes is returned.
6199 When {expr} is a |Dictionary| the number of entries in the
6200 |Dictionary| is returned.
mityu7f0bba22024-03-29 10:14:41 +01006201 When {expr} is an |Object|, invokes the len() method in the
6202 object (if present) to get the length (|object-len()|).
6203 Otherwise returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006204
6205 Can also be used as a |method|: >
6206 mylist->len()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006207<
6208 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006209
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006210
6211 *libcall()* *E364* *E368*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006212libcall({libname}, {funcname}, {argument})
6213 Call function {funcname} in the run-time library {libname}
6214 with single argument {argument}.
6215 This is useful to call functions in a library that you
6216 especially made to be used with Vim. Since only one argument
6217 is possible, calling standard library functions is rather
6218 limited.
6219 The result is the String returned by the function. If the
6220 function returns NULL, this will appear as an empty string ""
6221 to Vim.
6222 If the function returns a number, use libcallnr()!
6223 If {argument} is a number, it is passed to the function as an
6224 int; if {argument} is a string, it is passed as a
6225 null-terminated string.
6226 This function will fail in |restricted-mode|.
6227
6228 libcall() allows you to write your own 'plug-in' extensions to
6229 Vim without having to recompile the program. It is NOT a
6230 means to call system functions! If you try to do so Vim will
6231 very probably crash.
6232
6233 For Win32, the functions you write must be placed in a DLL
6234 and use the normal C calling convention (NOT Pascal which is
6235 used in Windows System DLLs). The function must take exactly
6236 one parameter, either a character pointer or a long integer,
6237 and must return a character pointer or NULL. The character
6238 pointer returned must point to memory that will remain valid
6239 after the function has returned (e.g. in static data in the
6240 DLL). If it points to allocated memory, that memory will
6241 leak away. Using a static buffer in the function should work,
6242 it's then freed when the DLL is unloaded.
6243
6244 WARNING: If the function returns a non-valid pointer, Vim may
6245 crash! This also happens if the function returns a number,
6246 because Vim thinks it's a pointer.
6247 For Win32 systems, {libname} should be the filename of the DLL
6248 without the ".DLL" suffix. A full path is only required if
6249 the DLL is not in the usual places.
6250 For Unix: When compiling your own plugins, remember that the
6251 object code must be compiled as position-independent ('PIC').
6252 {only in Win32 and some Unix versions, when the |+libcall|
6253 feature is present}
6254 Examples: >
6255 :echo libcall("libc.so", "getenv", "HOME")
6256
6257< Can also be used as a |method|, the base is passed as the
6258 third argument: >
6259 GetValue()->libcall("libc.so", "getenv")
6260<
6261 *libcallnr()*
6262libcallnr({libname}, {funcname}, {argument})
6263 Just like |libcall()|, but used for a function that returns an
6264 int instead of a string.
6265 {only in Win32 on some Unix versions, when the |+libcall|
6266 feature is present}
6267 Examples: >
6268 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
6269 :call libcallnr("libc.so", "printf", "Hello World!\n")
6270 :call libcallnr("libc.so", "sleep", 10)
6271<
6272 Can also be used as a |method|, the base is passed as the
6273 third argument: >
6274 GetValue()->libcallnr("libc.so", "printf")
6275<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006276 Return type: |String|
6277
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006278
6279line({expr} [, {winid}]) *line()*
6280 The result is a Number, which is the line number of the file
6281 position given with {expr}. The {expr} argument is a string.
zeertzjq02f3eba2024-06-12 20:45:24 +02006282 See |getpos()| for accepted positions.
6283
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006284 To get the column number use |col()|. To get both use
6285 |getpos()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02006286
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006287 With the optional {winid} argument the values are obtained for
6288 that window instead of the current window.
zeertzjq02f3eba2024-06-12 20:45:24 +02006289
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006290 Returns 0 for invalid values of {expr} and {winid}.
zeertzjq02f3eba2024-06-12 20:45:24 +02006291
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006292 Examples: >
6293 line(".") line number of the cursor
6294 line(".", winid) idem, in window "winid"
6295 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006296 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006297<
6298 To jump to the last known position when opening a file see
6299 |last-position-jump|.
6300
6301 Can also be used as a |method|: >
6302 GetValue()->line()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006303<
6304 Return type: |Number|
6305
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006306
6307line2byte({lnum}) *line2byte()*
6308 Return the byte count from the start of the buffer for line
6309 {lnum}. This includes the end-of-line character, depending on
6310 the 'fileformat' option for the current buffer. The first
6311 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
6312 This can also be used to get the byte count for the line just
6313 below the last line: >
6314 line2byte(line("$") + 1)
6315< This is the buffer size plus one. If 'fileencoding' is empty
6316 it is the file size plus one. {lnum} is used like with
6317 |getline()|. When {lnum} is invalid, or the |+byte_offset|
6318 feature has been disabled at compile time, -1 is returned.
6319 Also see |byte2line()|, |go| and |:goto|.
6320
6321 Can also be used as a |method|: >
6322 GetLnum()->line2byte()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006323<
6324 Return type: |Number|
6325
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006326
6327lispindent({lnum}) *lispindent()*
6328 Get the amount of indent for line {lnum} according the lisp
6329 indenting rules, as with 'lisp'.
6330 The indent is counted in spaces, the value of 'tabstop' is
6331 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01006332 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006333 error is given.
6334
6335 Can also be used as a |method|: >
6336 GetLnum()->lispindent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006337<
6338 Return type: |Number|
6339
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006340
6341list2blob({list}) *list2blob()*
6342 Return a Blob concatenating all the number values in {list}.
6343 Examples: >
6344 list2blob([1, 2, 3, 4]) returns 0z01020304
6345 list2blob([]) returns 0z
6346< Returns an empty Blob on error. If one of the numbers is
6347 negative or more than 255 error *E1239* is given.
6348
6349 |blob2list()| does the opposite.
6350
6351 Can also be used as a |method|: >
6352 GetList()->list2blob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006353<
6354 Return type: |Blob|
6355
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006356
6357list2str({list} [, {utf8}]) *list2str()*
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006358 Convert each number in {list} to a character string and
6359 concatenates them all. Examples: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006360 list2str([32]) returns " "
6361 list2str([65, 66, 67]) returns "ABC"
6362< The same can be done (slowly) with: >
6363 join(map(list, {nr, val -> nr2char(val)}), '')
6364< |str2list()| does the opposite.
6365
6366 When {utf8} is omitted or zero, the current 'encoding' is used.
6367 When {utf8} is TRUE, always return UTF-8 characters.
6368 With UTF-8 composing characters work as expected: >
6369 list2str([97, 769]) returns "á"
6370<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006371 Returns an empty string on error.
6372
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006373 Can also be used as a |method|: >
6374 GetList()->list2str()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006375<
6376 Return type: |String|
6377
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006378
6379listener_add({callback} [, {buf}]) *listener_add()*
6380 Add a callback function that will be invoked when changes have
6381 been made to buffer {buf}.
6382 {buf} refers to a buffer name or number. For the accepted
6383 values, see |bufname()|. When {buf} is omitted the current
6384 buffer is used.
6385 Returns a unique ID that can be passed to |listener_remove()|.
6386
6387 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00006388 bufnr the buffer that was changed
6389 start first changed line number
6390 end first line number below the change
6391 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006392 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00006393 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006394
6395 Example: >
6396 func Listener(bufnr, start, end, added, changes)
6397 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
6398 endfunc
6399 call listener_add('Listener', bufnr)
6400
Bram Moolenaar944697a2022-02-20 19:48:20 +00006401< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006402 dictionary with these entries:
6403 lnum the first line number of the change
6404 end the first line below the change
6405 added number of lines added; negative if lines were
6406 deleted
6407 col first column in "lnum" that was affected by
6408 the change; one if unknown or the whole line
6409 was affected; this is a byte index, first
6410 character has a value of one.
Bram Moolenaar3c053a12022-10-16 13:11:12 +01006411 When lines are inserted (not when a line is split, e.g. by
6412 typing CR in Insert mode) the values are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006413 lnum line above which the new line is added
6414 end equal to "lnum"
6415 added number of lines inserted
6416 col 1
6417 When lines are deleted the values are:
6418 lnum the first deleted line
6419 end the line below the first deleted line, before
6420 the deletion was done
6421 added negative, number of lines deleted
6422 col 1
6423 When lines are changed:
6424 lnum the first changed line
6425 end the line below the last changed line
6426 added 0
6427 col first column with a change or 1
6428
6429 The entries are in the order the changes were made, thus the
6430 most recent change is at the end. The line numbers are valid
6431 when the callback is invoked, but later changes may make them
6432 invalid, thus keeping a copy for later might not work.
6433
6434 The {callback} is invoked just before the screen is updated,
6435 when |listener_flush()| is called or when a change is being
6436 made that changes the line count in a way it causes a line
6437 number in the list of changes to become invalid.
6438
6439 The {callback} is invoked with the text locked, see
6440 |textlock|. If you do need to make changes to the buffer, use
6441 a timer to do this later |timer_start()|.
6442
6443 The {callback} is not invoked when the buffer is first loaded.
6444 Use the |BufReadPost| autocmd event to handle the initial text
6445 of a buffer.
6446 The {callback} is also not invoked when the buffer is
6447 unloaded, use the |BufUnload| autocmd event for that.
6448
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006449 Returns zero if {callback} or {buf} is invalid.
6450
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006451 Can also be used as a |method|, the base is passed as the
6452 second argument: >
6453 GetBuffer()->listener_add(callback)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006454<
6455 Return type: |Number|
6456
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006457
6458listener_flush([{buf}]) *listener_flush()*
6459 Invoke listener callbacks for buffer {buf}. If there are no
6460 pending changes then no callbacks are invoked.
6461
6462 {buf} refers to a buffer name or number. For the accepted
6463 values, see |bufname()|. When {buf} is omitted the current
6464 buffer is used.
6465
6466 Can also be used as a |method|: >
6467 GetBuffer()->listener_flush()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006468<
6469 Return type: |Number|
6470
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006471
6472listener_remove({id}) *listener_remove()*
6473 Remove a listener previously added with listener_add().
6474 Returns FALSE when {id} could not be found, TRUE when {id} was
6475 removed.
6476
6477 Can also be used as a |method|: >
6478 GetListenerId()->listener_remove()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006479<
6480 Return type: |Number|
6481
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006482
6483localtime() *localtime()*
6484 Return the current time, measured as seconds since 1st Jan
6485 1970. See also |strftime()|, |strptime()| and |getftime()|.
6486
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006487 Return type: |Number|
6488
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006489
6490log({expr}) *log()*
6491 Return the natural logarithm (base e) of {expr} as a |Float|.
6492 {expr} must evaluate to a |Float| or a |Number| in the range
6493 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006494 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006495 Examples: >
6496 :echo log(10)
6497< 2.302585 >
6498 :echo log(exp(5))
6499< 5.0
6500
6501 Can also be used as a |method|: >
6502 Compute()->log()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006503<
6504 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006505
6506
6507log10({expr}) *log10()*
6508 Return the logarithm of Float {expr} to base 10 as a |Float|.
6509 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006510 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006511 Examples: >
6512 :echo log10(1000)
6513< 3.0 >
6514 :echo log10(0.01)
6515< -2.0
6516
6517 Can also be used as a |method|: >
6518 Compute()->log10()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006519<
6520 Return type: |Float|
6521
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006522
6523luaeval({expr} [, {expr}]) *luaeval()*
6524 Evaluate Lua expression {expr} and return its result converted
6525 to Vim data structures. Second {expr} may hold additional
6526 argument accessible as _A inside first {expr}.
6527 Strings are returned as they are.
6528 Boolean objects are converted to numbers.
Bram Moolenaar73e28dc2022-09-17 21:08:33 +01006529 Numbers are converted to |Float| values.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006530 Dictionaries and lists obtained by vim.eval() are returned
6531 as-is.
6532 Other objects are returned as zero without any errors.
6533 See |lua-luaeval| for more details.
6534 Note that in a `:def` function local variables are not visible
6535 to {expr}.
6536
6537 Can also be used as a |method|: >
6538 GetExpr()->luaeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006539<
6540 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006541
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006542 {only available when compiled with the |+lua| feature}
6543
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006544
6545map({expr1}, {expr2}) *map()*
6546 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00006547 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006548 item in {expr1} with the result of evaluating {expr2}.
6549 For a |Blob| each byte is replaced.
6550 For a |String|, each character, including composing
6551 characters, is replaced.
6552 If the item type changes you may want to use |mapnew()| to
6553 create a new List or Dictionary. This is required when using
6554 Vim9 script.
6555
6556 {expr2} must be a |String| or |Funcref|.
6557
6558 If {expr2} is a |String|, inside {expr2} |v:val| has the value
6559 of the current item. For a |Dictionary| |v:key| has the key
6560 of the current item and for a |List| |v:key| has the index of
6561 the current item. For a |Blob| |v:key| has the index of the
6562 current byte. For a |String| |v:key| has the index of the
6563 current character.
6564 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006565 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006566< This puts "> " before and " <" after each item in "mylist".
6567
6568 Note that {expr2} is the result of an expression and is then
6569 used as an expression again. Often it is good to use a
6570 |literal-string| to avoid having to double backslashes. You
6571 still have to double ' quotes
6572
6573 If {expr2} is a |Funcref| it is called with two arguments:
6574 1. The key or the index of the current item.
6575 2. the value of the current item.
Bram Moolenaarb59ae592022-11-23 23:46:31 +00006576 With a legacy script lambda you don't get an error if it only
6577 accepts one argument, but with a Vim9 lambda you get "E1106:
6578 One argument too many", the number of arguments must match.
6579
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006580 The function must return the new value of the item. Example
6581 that changes each value by "key-value": >
6582 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006583 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006584 endfunc
6585 call map(myDict, function('KeyValue'))
6586< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006587 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006588< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006589 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006590< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006591 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006592<
6593 The operation is done in-place for a |List| and |Dictionary|.
6594 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006595 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006596
6597< Returns {expr1}, the |List| or |Dictionary| that was filtered,
6598 or a new |Blob| or |String|.
6599 When an error is encountered while evaluating {expr2} no
6600 further items in {expr1} are processed.
6601 When {expr2} is a Funcref errors inside a function are ignored,
6602 unless it was defined with the "abort" flag.
6603
6604 Can also be used as a |method|: >
6605 mylist->map(expr2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006606<
6607 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
6608 depending on {expr1}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006609
6610
6611maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
6612 When {dict} is omitted or zero: Return the rhs of mapping
6613 {name} in mode {mode}. The returned String has special
6614 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01006615 listing. When {dict} is TRUE a dictionary is returned, see
6616 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006617
6618 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006619 returned if {dict} is FALSE, otherwise returns an empty Dict.
6620 When the mapping for {name} is empty, then "<Nop>" is
6621 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006622
6623 The {name} can have special key names, like in the ":map"
6624 command.
6625
6626 {mode} can be one of these strings:
6627 "n" Normal
6628 "v" Visual (including Select)
6629 "o" Operator-pending
6630 "i" Insert
6631 "c" Cmd-line
6632 "s" Select
6633 "x" Visual
6634 "l" langmap |language-mapping|
6635 "t" Terminal-Job
6636 "" Normal, Visual and Operator-pending
6637 When {mode} is omitted, the modes for "" are used.
6638
6639 When {abbr} is there and it is |TRUE| use abbreviations
6640 instead of mappings.
6641
6642 When {dict} is there and it is |TRUE| return a dictionary
6643 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01006644 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006645 "lhs" The {lhs} of the mapping as it would be typed
6646 "lhsraw" The {lhs} of the mapping as raw bytes
6647 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
6648 form, only present when it differs from "lhsraw"
6649 "rhs" The {rhs} of the mapping as typed.
6650 "silent" 1 for a |:map-silent| mapping, else 0.
6651 "noremap" 1 if the {rhs} of the mapping is not remappable.
6652 "script" 1 if mapping was defined with <script>.
6653 "expr" 1 for an expression mapping (|:map-<expr>|).
6654 "buffer" 1 for a buffer local mapping (|:map-local|).
6655 "mode" Modes for which the mapping is defined. In
6656 addition to the modes mentioned above, these
6657 characters will be used:
6658 " " Normal, Visual and Operator-pending
6659 "!" Insert and Commandline mode
6660 (|mapmode-ic|)
6661 "sid" The script local ID, used for <sid> mappings
Bram Moolenaar71badf92023-04-22 22:40:14 +01006662 (|<SID>|). Negative for special contexts.
Bram Moolenaara9528b32022-01-18 20:51:35 +00006663 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01006664 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006665 "lnum" The line number in "sid", zero if unknown.
6666 "nowait" Do not wait for other, longer mappings.
6667 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01006668 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01006669 "mode_bits" Vim's internal binary representation of "mode".
6670 |mapset()| ignores this; only "mode" is used.
6671 See |maplist()| for usage examples. The values
6672 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006673
6674 The dictionary can be used to restore a mapping with
6675 |mapset()|.
6676
6677 The mappings local to the current buffer are checked first,
6678 then the global mappings.
6679 This function can be used to map a key even when it's already
6680 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006681 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006682
6683< Can also be used as a |method|: >
6684 GetKey()->maparg('n')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006685<
6686 Return type: |String| or dict<any> depending on {dict}
6687
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006688
6689mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
6690 Check if there is a mapping that matches with {name} in mode
6691 {mode}. See |maparg()| for {mode} and special names in
6692 {name}.
6693 When {abbr} is there and it is |TRUE| use abbreviations
6694 instead of mappings.
6695 A match happens with a mapping that starts with {name} and
6696 with a mapping which is equal to the start of {name}.
6697
6698 matches mapping "a" "ab" "abc" ~
6699 mapcheck("a") yes yes yes
6700 mapcheck("abc") yes yes yes
6701 mapcheck("ax") yes no no
6702 mapcheck("b") no no no
6703
6704 The difference with maparg() is that mapcheck() finds a
6705 mapping that matches with {name}, while maparg() only finds a
6706 mapping for {name} exactly.
6707 When there is no mapping that starts with {name}, an empty
6708 String is returned. If there is one, the RHS of that mapping
6709 is returned. If there are several mappings that start with
6710 {name}, the RHS of one of them is returned. This will be
6711 "<Nop>" if the RHS is empty.
6712 The mappings local to the current buffer are checked first,
6713 then the global mappings.
6714 This function can be used to check if a mapping can be added
6715 without being ambiguous. Example: >
6716 :if mapcheck("_vv") == ""
6717 : map _vv :set guifont=7x13<CR>
6718 :endif
6719< This avoids adding the "_vv" mapping when there already is a
6720 mapping for "_v" or for "_vvv".
6721
6722 Can also be used as a |method|: >
6723 GetKey()->mapcheck('n')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006724<
6725 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006726
6727
Ernie Rael09661202022-04-25 14:40:44 +01006728maplist([{abbr}]) *maplist()*
6729 Returns a |List| of all mappings. Each List item is a |Dict|,
6730 the same as what is returned by |maparg()|, see
6731 |mapping-dict|. When {abbr} is there and it is |TRUE| use
6732 abbreviations instead of mappings.
6733
6734 Example to show all mappings with 'MultiMatch' in rhs: >
6735 vim9script
6736 echo maplist()->filter(
6737 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01006738< It can be tricky to find mappings for particular |:map-modes|.
6739 |mapping-dict|'s "mode_bits" can simplify this. For example,
6740 the mode_bits for Normal, Insert or Command-line modes are
6741 0x19. To find all the mappings available in those modes you
6742 can do: >
6743 vim9script
6744 var saved_maps = []
6745 for m in maplist()
6746 if and(m.mode_bits, 0x19) != 0
6747 saved_maps->add(m)
6748 endif
6749 endfor
6750 echo saved_maps->mapnew((_, m) => m.lhs)
6751< The values of the mode_bits are defined in Vim's src/vim.h
6752 file and they can be discovered at runtime using
6753 |:map-commands| and "maplist()". Example: >
6754 vim9script
6755 omap xyzzy <Nop>
6756 var op_bit = maplist()->filter(
6757 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
6758 ounmap xyzzy
6759 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006760<
6761 Return type: list<dict<any>>
Ernie Rael09661202022-04-25 14:40:44 +01006762
6763
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006764mapnew({expr1}, {expr2}) *mapnew()*
6765 Like |map()| but instead of replacing items in {expr1} a new
6766 List or Dictionary is created and returned. {expr1} remains
6767 unchanged. Items can still be changed by {expr2}, if you
6768 don't want that use |deepcopy()| first.
6769
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006770 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
6771 depending on {expr1}
6772
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006773
6774mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01006775mapset({dict})
6776 Restore a mapping from a dictionary, possibly returned by
6777 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
6778 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01006779 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01006780 feature allows copying mappings from one buffer to another.
6781 The dict.mode value may restore a single mapping that covers
6782 more than one mode, like with mode values of '!', ' ', 'nox',
6783 or 'v'. *E1276*
6784
6785 In the first form, {mode} and {abbr} should be the same as
6786 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006787 {mode} is used to define the mode in which the mapping is set,
6788 not the "mode" entry in {dict}.
6789 Example for saving and restoring a mapping: >
6790 let save_map = maparg('K', 'n', 0, 1)
6791 nnoremap K somethingelse
6792 ...
6793 call mapset('n', 0, save_map)
6794< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01006795 e.g. with `:map!`, you need to save/restore the mapping for
6796 all of them, when they might differ.
6797
6798 In the second form, with {dict} as the only argument, mode
6799 and abbr are taken from the dict.
6800 Example: >
6801 vim9script
6802 var save_maps = maplist()->filter(
6803 (_, m) => m.lhs == 'K')
6804 nnoremap K somethingelse
6805 cnoremap K somethingelse2
6806 # ...
6807 unmap K
6808 for d in save_maps
6809 mapset(d)
6810 endfor
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006811<
6812 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006813
6814
6815match({expr}, {pat} [, {start} [, {count}]]) *match()*
6816 When {expr} is a |List| then this returns the index of the
6817 first item where {pat} matches. Each item is used as a
6818 String, |Lists| and |Dictionaries| are used as echoed.
6819
6820 Otherwise, {expr} is used as a String. The result is a
6821 Number, which gives the index (byte offset) in {expr} where
6822 {pat} matches.
6823
6824 A match at the first character or |List| item returns zero.
6825 If there is no match -1 is returned.
6826
6827 For getting submatches see |matchlist()|.
6828 Example: >
6829 :echo match("testing", "ing") " results in 4
6830 :echo match([1, 'x'], '\a') " results in 1
6831< See |string-match| for how {pat} is used.
6832 *strpbrk()*
6833 Vim doesn't have a strpbrk() function. But you can do: >
6834 :let sepidx = match(line, '[.,;: \t]')
6835< *strcasestr()*
6836 Vim doesn't have a strcasestr() function. But you can add
6837 "\c" to the pattern to ignore case: >
6838 :let idx = match(haystack, '\cneedle')
6839<
6840 If {start} is given, the search starts from byte index
6841 {start} in a String or item {start} in a |List|.
6842 The result, however, is still the index counted from the
6843 first character/item. Example: >
6844 :echo match("testing", "ing", 2)
6845< result is again "4". >
6846 :echo match("testing", "ing", 4)
6847< result is again "4". >
6848 :echo match("testing", "t", 2)
6849< result is "3".
6850 For a String, if {start} > 0 then it is like the string starts
6851 {start} bytes later, thus "^" will match at {start}. Except
6852 when {count} is given, then it's like matches before the
6853 {start} byte are ignored (this is a bit complicated to keep it
6854 backwards compatible).
6855 For a String, if {start} < 0, it will be set to 0. For a list
6856 the index is counted from the end.
6857 If {start} is out of range ({start} > strlen({expr}) for a
6858 String or {start} > len({expr}) for a |List|) -1 is returned.
6859
6860 When {count} is given use the {count}'th match. When a match
6861 is found in a String the search for the next one starts one
6862 character further. Thus this example results in 1: >
6863 echo match("testing", "..", 0, 2)
6864< In a |List| the search continues in the next item.
6865 Note that when {count} is added the way {start} works changes,
6866 see above.
6867
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01006868 *match-pattern*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006869 See |pattern| for the patterns that are accepted.
6870 The 'ignorecase' option is used to set the ignore-caseness of
6871 the pattern. 'smartcase' is NOT used. The matching is always
6872 done like 'magic' is set and 'cpoptions' is empty.
6873 Note that a match at the start is preferred, thus when the
6874 pattern is using "*" (any number of matches) it tends to find
6875 zero matches at the start instead of a number of matches
6876 further down in the text.
6877
6878 Can also be used as a |method|: >
6879 GetText()->match('word')
6880 GetList()->match('word')
6881<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006882 Return type: |Number|
6883
6884
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00006885 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006886matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
6887 Defines a pattern to be highlighted in the current window (a
6888 "match"). It will be highlighted with {group}. Returns an
6889 identification number (ID), which can be used to delete the
6890 match using |matchdelete()|. The ID is bound to the window.
6891 Matching is case sensitive and magic, unless case sensitivity
6892 or magicness are explicitly overridden in {pattern}. The
6893 'magic', 'smartcase' and 'ignorecase' options are not used.
6894 The "Conceal" value is special, it causes the match to be
6895 concealed.
6896
6897 The optional {priority} argument assigns a priority to the
6898 match. A match with a high priority will have its
6899 highlighting overrule that of a match with a lower priority.
6900 A priority is specified as an integer (negative numbers are no
6901 exception). If the {priority} argument is not specified, the
6902 default priority is 10. The priority of 'hlsearch' is zero,
6903 hence all matches with a priority greater than zero will
6904 overrule it. Syntax highlighting (see 'syntax') is a separate
6905 mechanism, and regardless of the chosen priority a match will
6906 always overrule syntax highlighting.
6907
6908 The optional {id} argument allows the request for a specific
6909 match ID. If a specified ID is already taken, an error
6910 message will appear and the match will not be added. An ID
6911 is specified as a positive integer (zero excluded). IDs 1, 2
6912 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01006913 respectively. 3 is reserved for use by the |matchparen|
6914 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01006915 If the {id} argument is not specified or -1, |matchadd()|
Bram Moolenaar9f573a82022-09-29 13:50:08 +01006916 automatically chooses a free ID, which is at least 1000.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006917
6918 The optional {dict} argument allows for further custom
6919 values. Currently this is used to specify a match specific
6920 conceal character that will be shown for |hl-Conceal|
6921 highlighted matches. The dict can have the following members:
6922
6923 conceal Special character to show instead of the
6924 match (only for |hl-Conceal| highlighted
6925 matches, see |:syn-cchar|)
6926 window Instead of the current window use the
6927 window with this number or window ID.
6928
6929 The number of matches is not limited, as it is the case with
6930 the |:match| commands.
6931
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006932 Returns -1 on error.
6933
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006934 Example: >
6935 :highlight MyGroup ctermbg=green guibg=green
6936 :let m = matchadd("MyGroup", "TODO")
6937< Deletion of the pattern: >
6938 :call matchdelete(m)
6939
6940< A list of matches defined by |matchadd()| and |:match| are
6941 available from |getmatches()|. All matches can be deleted in
6942 one operation by |clearmatches()|.
6943
6944 Can also be used as a |method|: >
6945 GetGroup()->matchadd('TODO')
6946<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006947 Return type: |Number|
6948
6949
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006950 *matchaddpos()*
6951matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
6952 Same as |matchadd()|, but requires a list of positions {pos}
6953 instead of a pattern. This command is faster than |matchadd()|
Shane Harperc1b39842024-07-17 19:40:40 +02006954 because it does not handle regular expressions and it sets
6955 buffer line boundaries to redraw screen. It is supposed to be
6956 used when fast match additions and deletions are required, for
6957 example to highlight matching parentheses.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006958
6959 {pos} is a list of positions. Each position can be one of
6960 these:
6961 - A number. This whole line will be highlighted. The first
6962 line has number 1.
6963 - A list with one number, e.g., [23]. The whole line with this
6964 number will be highlighted.
6965 - A list with two numbers, e.g., [23, 11]. The first number is
6966 the line number, the second one is the column number (first
6967 column is 1, the value must correspond to the byte index as
6968 |col()| would return). The character at this position will
6969 be highlighted.
6970 - A list with three numbers, e.g., [23, 11, 3]. As above, but
6971 the third number gives the length of the highlight in bytes.
6972
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006973 Returns -1 on error.
6974
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006975 Example: >
6976 :highlight MyGroup ctermbg=green guibg=green
6977 :let m = matchaddpos("MyGroup", [[23, 24], 34])
6978< Deletion of the pattern: >
6979 :call matchdelete(m)
6980
6981< Matches added by |matchaddpos()| are returned by
6982 |getmatches()|.
6983
6984 Can also be used as a |method|: >
6985 GetGroup()->matchaddpos([23, 11])
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006986<
6987 Return type: |Number|
6988
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006989
6990matcharg({nr}) *matcharg()*
6991 Selects the {nr} match item, as set with a |:match|,
6992 |:2match| or |:3match| command.
6993 Return a |List| with two elements:
6994 The name of the highlight group used
6995 The pattern used.
6996 When {nr} is not 1, 2 or 3 returns an empty |List|.
6997 When there is no match item set returns ['', ''].
6998 This is useful to save and restore a |:match|.
6999 Highlighting matches using the |:match| commands are limited
7000 to three matches. |matchadd()| does not have this limitation.
7001
7002 Can also be used as a |method|: >
7003 GetMatch()->matcharg()
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007004<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007005 Return type: list<string>
7006
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007007 *matchbufline()*
7008matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])
7009 Returns the |List| of matches in lines from {lnum} to {end} in
7010 buffer {buf} where {pat} matches.
7011
7012 {lnum} and {end} can either be a line number or the string "$"
7013 to refer to the last line in {buf}.
7014
7015 The {dict} argument supports following items:
7016 submatches include submatch information (|/\(|)
7017
7018 For each match, a |Dict| with the following items is returned:
7019 byteidx starting byte index of the match
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007020 lnum line number where there is a match
7021 text matched string
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007022 Note that there can be multiple matches in a single line.
7023
7024 This function works only for loaded buffers. First call
7025 |bufload()| if needed.
7026
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007027 See |match-pattern| for information about the effect of some
7028 option settings on the pattern.
7029
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007030 When {buf} is not a valid buffer, the buffer is not loaded or
7031 {lnum} or {end} is not valid then an error is given and an
7032 empty |List| is returned.
7033
7034 Examples: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007035 " Assuming line 3 in buffer 5 contains "a"
7036 :echo matchbufline(5, '\<\k\+\>', 3, 3)
7037 [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
7038 " Assuming line 4 in buffer 10 contains "tik tok"
7039 :echo matchbufline(10, '\<\k\+\>', 1, 4)
7040 [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007041<
7042 If {submatch} is present and is v:true, then submatches like
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007043 "\1", "\2", etc. are also returned. Example: >
7044 " Assuming line 2 in buffer 2 contains "acd"
7045 :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007046 \ {'submatches': v:true})
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007047 [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007048< The "submatches" List always contains 9 items. If a submatch
7049 is not found, then an empty string is returned for that
7050 submatch.
7051
7052 Can also be used as a |method|: >
7053 GetBuffer()->matchbufline('mypat', 1, '$')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007054<
7055 Return type: list<dict<any>> or list<any>
7056
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007057
7058matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
7059 Deletes a match with ID {id} previously defined by |matchadd()|
7060 or one of the |:match| commands. Returns 0 if successful,
7061 otherwise -1. See example for |matchadd()|. All matches can
7062 be deleted in one operation by |clearmatches()|.
7063 If {win} is specified, use the window with this number or
7064 window ID instead of the current window.
7065
7066 Can also be used as a |method|: >
7067 GetMatch()->matchdelete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007068<
7069 Return type: |Number|
7070
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007071
7072matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
7073 Same as |match()|, but return the index of first character
7074 after the match. Example: >
7075 :echo matchend("testing", "ing")
7076< results in "7".
7077 *strspn()* *strcspn()*
7078 Vim doesn't have a strspn() or strcspn() function, but you can
7079 do it with matchend(): >
7080 :let span = matchend(line, '[a-zA-Z]')
7081 :let span = matchend(line, '[^a-zA-Z]')
7082< Except that -1 is returned when there are no matches.
7083
7084 The {start}, if given, has the same meaning as for |match()|. >
7085 :echo matchend("testing", "ing", 2)
7086< results in "7". >
7087 :echo matchend("testing", "ing", 5)
7088< result is "-1".
7089 When {expr} is a |List| the result is equal to |match()|.
7090
7091 Can also be used as a |method|: >
7092 GetText()->matchend('word')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007093<
7094 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007095
7096
7097matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
7098 If {list} is a list of strings, then returns a |List| with all
7099 the strings in {list} that fuzzy match {str}. The strings in
7100 the returned list are sorted based on the matching score.
7101
7102 The optional {dict} argument always supports the following
7103 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01007104 matchseq When this item is present return only matches
7105 that contain the characters in {str} in the
7106 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01007107 limit Maximum number of matches in {list} to be
7108 returned. Zero means no limit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007109
7110 If {list} is a list of dictionaries, then the optional {dict}
7111 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01007112 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007113 {str}. The value of this item should be a
7114 string.
7115 text_cb |Funcref| that will be called for every item
7116 in {list} to get the text for fuzzy matching.
7117 This should accept a dictionary item as the
7118 argument and return the text for that item to
7119 use for fuzzy matching.
7120
7121 {str} is treated as a literal string and regular expression
7122 matching is NOT supported. The maximum supported {str} length
7123 is 256.
7124
7125 When {str} has multiple words each separated by white space,
7126 then the list of strings that have all the words is returned.
7127
7128 If there are no matching strings or there is an error, then an
7129 empty list is returned. If length of {str} is greater than
7130 256, then returns an empty list.
7131
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01007132 When {limit} is given, matchfuzzy() will find up to this
7133 number of matches in {list} and return them in sorted order.
7134
Bram Moolenaar1588bc82022-03-08 21:35:07 +00007135 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007136 matching strings.
7137
7138 Example: >
7139 :echo matchfuzzy(["clay", "crow"], "cay")
7140< results in ["clay"]. >
7141 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
7142< results in a list of buffer names fuzzy matching "ndl". >
7143 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
7144< results in a list of buffer information dicts with buffer
7145 names fuzzy matching "ndl". >
7146 :echo getbufinfo()->matchfuzzy("spl",
7147 \ {'text_cb' : {v -> v.name}})
7148< results in a list of buffer information dicts with buffer
7149 names fuzzy matching "spl". >
7150 :echo v:oldfiles->matchfuzzy("test")
7151< results in a list of file names fuzzy matching "test". >
7152 :let l = readfile("buffer.c")->matchfuzzy("str")
7153< results in a list of lines in "buffer.c" fuzzy matching "str". >
7154 :echo ['one two', 'two one']->matchfuzzy('two one')
7155< results in ['two one', 'one two']. >
7156 :echo ['one two', 'two one']->matchfuzzy('two one',
7157 \ {'matchseq': 1})
7158< results in ['two one'].
7159
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007160 Return type: list<string> or list<any>
7161
7162
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007163matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
7164 Same as |matchfuzzy()|, but returns the list of matched
7165 strings, the list of character positions where characters
7166 in {str} matches and a list of matching scores. You can
7167 use |byteidx()| to convert a character position to a byte
7168 position.
7169
7170 If {str} matches multiple times in a string, then only the
7171 positions for the best match is returned.
7172
7173 If there are no matching strings or there is an error, then a
7174 list with three empty list items is returned.
7175
7176 Example: >
7177 :echo matchfuzzypos(['testing'], 'tsg')
7178< results in [['testing'], [[0, 2, 6]], [99]] >
7179 :echo matchfuzzypos(['clay', 'lacy'], 'la')
7180< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
7181 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
7182< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
7183
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007184 Return type: list<list<any>>
7185
7186
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007187matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
7188 Same as |match()|, but return a |List|. The first item in the
7189 list is the matched string, same as what matchstr() would
7190 return. Following items are submatches, like "\1", "\2", etc.
7191 in |:substitute|. When an optional submatch didn't match an
7192 empty string is used. Example: >
7193 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
7194< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
7195 When there is no match an empty list is returned.
7196
7197 You can pass in a List, but that is not very useful.
7198
7199 Can also be used as a |method|: >
7200 GetText()->matchlist('word')
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007201<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007202 Return type: list<string> or list<any>
7203
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007204 *matchstrlist()*
7205matchstrlist({list}, {pat} [, {dict}])
7206 Returns the |List| of matches in {list} where {pat} matches.
7207 {list} is a |List| of strings. {pat} is matched against each
7208 string in {list}.
7209
7210 The {dict} argument supports following items:
7211 submatches include submatch information (|/\(|)
7212
7213 For each match, a |Dict| with the following items is returned:
7214 byteidx starting byte index of the match.
7215 idx index in {list} of the match.
7216 text matched string
7217 submatches a List of submatches. Present only if
7218 "submatches" is set to v:true in {dict}.
7219
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007220 See |match-pattern| for information about the effect of some
7221 option settings on the pattern.
7222
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007223 Example: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007224 :echo matchstrlist(['tik tok'], '\<\k\+\>')
7225 [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
7226 :echo matchstrlist(['a', 'b'], '\<\k\+\>')
7227 [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007228<
7229 If "submatches" is present and is v:true, then submatches like
7230 "\1", "\2", etc. are also returned. Example: >
7231 :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
7232 \ #{submatches: v:true})
7233 [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
7234< The "submatches" List always contains 9 items. If a submatch
7235 is not found, then an empty string is returned for that
7236 submatch.
7237
7238 Can also be used as a |method|: >
7239 GetListOfStrings()->matchstrlist('mypat')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007240<
7241 Return type: list<dict<any>> or list<any>
7242
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007243
7244matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
7245 Same as |match()|, but return the matched string. Example: >
7246 :echo matchstr("testing", "ing")
7247< results in "ing".
7248 When there is no match "" is returned.
7249 The {start}, if given, has the same meaning as for |match()|. >
7250 :echo matchstr("testing", "ing", 2)
7251< results in "ing". >
7252 :echo matchstr("testing", "ing", 5)
7253< result is "".
7254 When {expr} is a |List| then the matching item is returned.
7255 The type isn't changed, it's not necessarily a String.
7256
7257 Can also be used as a |method|: >
7258 GetText()->matchstr('word')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007259<
7260 Return type: |String|
7261
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007262
7263matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
7264 Same as |matchstr()|, but return the matched string, the start
7265 position and the end position of the match. Example: >
7266 :echo matchstrpos("testing", "ing")
7267< results in ["ing", 4, 7].
7268 When there is no match ["", -1, -1] is returned.
7269 The {start}, if given, has the same meaning as for |match()|. >
7270 :echo matchstrpos("testing", "ing", 2)
7271< results in ["ing", 4, 7]. >
7272 :echo matchstrpos("testing", "ing", 5)
7273< result is ["", -1, -1].
7274 When {expr} is a |List| then the matching item, the index
7275 of first item where {pat} matches, the start position and the
7276 end position of the match are returned. >
7277 :echo matchstrpos([1, '__x'], '\a')
7278< result is ["x", 1, 2, 3].
7279 The type isn't changed, it's not necessarily a String.
7280
7281 Can also be used as a |method|: >
7282 GetText()->matchstrpos('word')
7283<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007284 Return type: list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007285
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007286
7287max({expr}) *max()*
7288 Return the maximum value of all items in {expr}. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007289 echo max([apples, pears, oranges])
7290
7291< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
7292 it returns the maximum of all values in the Dictionary.
7293 If {expr} is neither a List nor a Dictionary, or one of the
7294 items in {expr} cannot be used as a Number this results in
7295 an error. An empty |List| or |Dictionary| results in zero.
7296
7297 Can also be used as a |method|: >
7298 mylist->max()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007299<
7300 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007301
7302
7303menu_info({name} [, {mode}]) *menu_info()*
7304 Return information about the specified menu {name} in
7305 mode {mode}. The menu name should be specified without the
7306 shortcut character ('&'). If {name} is "", then the top-level
7307 menu names are returned.
7308
7309 {mode} can be one of these strings:
7310 "n" Normal
7311 "v" Visual (including Select)
7312 "o" Operator-pending
7313 "i" Insert
7314 "c" Cmd-line
7315 "s" Select
7316 "x" Visual
7317 "t" Terminal-Job
7318 "" Normal, Visual and Operator-pending
7319 "!" Insert and Cmd-line
7320 When {mode} is omitted, the modes for "" are used.
7321
7322 Returns a |Dictionary| containing the following items:
7323 accel menu item accelerator text |menu-text|
7324 display display name (name without '&')
7325 enabled v:true if this menu item is enabled
7326 Refer to |:menu-enable|
7327 icon name of the icon file (for toolbar)
7328 |toolbar-icon|
7329 iconidx index of a built-in icon
7330 modes modes for which the menu is defined. In
7331 addition to the modes mentioned above, these
7332 characters will be used:
7333 " " Normal, Visual and Operator-pending
7334 name menu item name.
7335 noremenu v:true if the {rhs} of the menu item is not
7336 remappable else v:false.
7337 priority menu order priority |menu-priority|
7338 rhs right-hand-side of the menu item. The returned
7339 string has special characters translated like
7340 in the output of the ":menu" command listing.
7341 When the {rhs} of a menu item is empty, then
7342 "<Nop>" is returned.
7343 script v:true if script-local remapping of {rhs} is
7344 allowed else v:false. See |:menu-script|.
7345 shortcut shortcut key (character after '&' in
7346 the menu name) |menu-shortcut|
7347 silent v:true if the menu item is created
7348 with <silent> argument |:menu-silent|
7349 submenus |List| containing the names of
7350 all the submenus. Present only if the menu
7351 item has submenus.
7352
7353 Returns an empty dictionary if the menu item is not found.
7354
7355 Examples: >
7356 :echo menu_info('Edit.Cut')
7357 :echo menu_info('File.Save', 'n')
7358
7359 " Display the entire menu hierarchy in a buffer
7360 func ShowMenu(name, pfx)
7361 let m = menu_info(a:name)
7362 call append(line('$'), a:pfx .. m.display)
7363 for child in m->get('submenus', [])
7364 call ShowMenu(a:name .. '.' .. escape(child, '.'),
7365 \ a:pfx .. ' ')
7366 endfor
7367 endfunc
7368 new
7369 for topmenu in menu_info('').submenus
7370 call ShowMenu(topmenu, '')
7371 endfor
7372<
7373 Can also be used as a |method|: >
7374 GetMenuName()->menu_info('v')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007375<
7376 Return type: dict<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007377
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007378min({expr}) *min()*
7379 Return the minimum value of all items in {expr}. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007380 echo min([apples, pears, oranges])
7381
7382< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
7383 it returns the minimum of all values in the Dictionary.
7384 If {expr} is neither a List nor a Dictionary, or one of the
7385 items in {expr} cannot be used as a Number this results in
7386 an error. An empty |List| or |Dictionary| results in zero.
7387
7388 Can also be used as a |method|: >
7389 mylist->min()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007390<
7391 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007392
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007393
7394mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E739*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007395 Create directory {name}.
7396
Bram Moolenaar938ae282023-02-20 20:44:55 +00007397 When {flags} is present it must be a string. An empty string
7398 has no effect.
Bram Moolenaar6f14da12022-09-07 21:30:44 +01007399
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007400 {flags} can contain these character flags:
7401 "p" intermediate directories will be created as necessary
7402 "D" {name} will be deleted at the end of the current
Christian Brabandtc509c002024-06-14 20:22:05 +02007403 function, but not recursively |:defer|
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007404 "R" {name} will be deleted recursively at the end of the
Christian Brabandtc509c002024-06-14 20:22:05 +02007405 current function |:defer|
Bram Moolenaar938ae282023-02-20 20:44:55 +00007406
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007407 Note that when {name} has more than one part and "p" is used
Bram Moolenaar6f14da12022-09-07 21:30:44 +01007408 some directories may already exist. Only the first one that
7409 is created and what it contains is scheduled to be deleted.
7410 E.g. when using: >
7411 call mkdir('subdir/tmp/autoload', 'pR')
7412< and "subdir" already exists then "subdir/tmp" will be
7413 scheduled for deletion, like with: >
7414 defer delete('subdir/tmp', 'rf')
7415< Note that if scheduling the defer fails the directory is not
7416 deleted. This should only happen when out of memory.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007417
7418 If {prot} is given it is used to set the protection bits of
7419 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
7420 the user, readable for others). Use 0o700 to make it
7421 unreadable for others. This is only used for the last part of
7422 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
7423 created with 0o755.
7424 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007425 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007426
7427< This function is not available in the |sandbox|.
7428
7429 There is no error if the directory already exists and the "p"
7430 flag is passed (since patch 8.0.1708). However, without the
7431 "p" option the call will fail.
7432
7433 The function result is a Number, which is TRUE if the call was
7434 successful or FALSE if the directory creation failed or partly
7435 failed.
7436
7437 Not available on all systems. To check use: >
7438 :if exists("*mkdir")
7439
7440< Can also be used as a |method|: >
7441 GetName()->mkdir()
7442<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007443 Return type: |Number|
7444
7445
7446mode([{expr}]) *mode()*
7447 Return a string that indicates the current mode.
Doug Kearns9cd9e752024-04-07 17:42:17 +02007448 If {expr} is supplied and it evaluates to a non-zero Number or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007449 a non-empty String (|non-zero-arg|), then the full mode is
7450 returned, otherwise only the first letter is returned.
7451 Also see |state()|.
7452
7453 n Normal
7454 no Operator-pending
7455 nov Operator-pending (forced characterwise |o_v|)
7456 noV Operator-pending (forced linewise |o_V|)
7457 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
7458 CTRL-V is one character
7459 niI Normal using |i_CTRL-O| in |Insert-mode|
7460 niR Normal using |i_CTRL-O| in |Replace-mode|
7461 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
7462 nt Terminal-Normal (insert goes to Terminal-Job mode)
7463 v Visual by character
7464 vs Visual by character using |v_CTRL-O| in Select mode
7465 V Visual by line
7466 Vs Visual by line using |v_CTRL-O| in Select mode
7467 CTRL-V Visual blockwise
7468 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
7469 s Select by character
7470 S Select by line
7471 CTRL-S Select blockwise
7472 i Insert
7473 ic Insert mode completion |compl-generic|
7474 ix Insert mode |i_CTRL-X| completion
7475 R Replace |R|
7476 Rc Replace mode completion |compl-generic|
7477 Rx Replace mode |i_CTRL-X| completion
7478 Rv Virtual Replace |gR|
7479 Rvc Virtual Replace mode completion |compl-generic|
7480 Rvx Virtual Replace mode |i_CTRL-X| completion
7481 c Command-line editing
h-east71ebf3b2023-09-03 17:12:55 +02007482 ct Command-line editing via Terminal-Job mode
zeertzjqfcaeb3d2023-11-28 20:46:29 +01007483 cr Command-line editing overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007484 cv Vim Ex mode |gQ|
zeertzjqfcaeb3d2023-11-28 20:46:29 +01007485 cvr Vim Ex mode while in overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007486 ce Normal Ex mode |Q|
7487 r Hit-enter prompt
7488 rm The -- more -- prompt
7489 r? A |:confirm| query of some sort
7490 ! Shell or external command is executing
7491 t Terminal-Job mode: keys go to the job
7492
7493 This is useful in the 'statusline' option or when used
7494 with |remote_expr()| In most other places it always returns
7495 "c" or "n".
7496 Note that in the future more modes and more specific modes may
7497 be added. It's better not to compare the whole string but only
7498 the leading character(s).
7499 Also see |visualmode()|.
7500
7501 Can also be used as a |method|: >
7502 DoFull()->mode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007503<
7504 Return type: |String|
7505
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007506
7507mzeval({expr}) *mzeval()*
7508 Evaluate MzScheme expression {expr} and return its result
7509 converted to Vim data structures.
7510 Numbers and strings are returned as they are.
7511 Pairs (including lists and improper lists) and vectors are
7512 returned as Vim |Lists|.
7513 Hash tables are represented as Vim |Dictionary| type with keys
7514 converted to strings.
7515 All other types are converted to string with display function.
7516 Examples: >
7517 :mz (define l (list 1 2 3))
7518 :mz (define h (make-hash)) (hash-set! h "list" l)
7519 :echo mzeval("l")
7520 :echo mzeval("h")
7521<
7522 Note that in a `:def` function local variables are not visible
7523 to {expr}.
7524
7525 Can also be used as a |method|: >
7526 GetExpr()->mzeval()
7527<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007528 Return type: any, depending on {expr}
7529
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007530 {only available when compiled with the |+mzscheme| feature}
7531
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007532
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007533nextnonblank({lnum}) *nextnonblank()*
7534 Return the line number of the first line at or below {lnum}
7535 that is not blank. Example: >
7536 if getline(nextnonblank(1)) =~ "Java"
7537< When {lnum} is invalid or there is no non-blank line at or
7538 below it, zero is returned.
7539 {lnum} is used like with |getline()|.
7540 See also |prevnonblank()|.
7541
7542 Can also be used as a |method|: >
7543 GetLnum()->nextnonblank()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007544<
7545 Return type: |Number|
7546
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007547
7548nr2char({expr} [, {utf8}]) *nr2char()*
7549 Return a string with a single character, which has the number
7550 value {expr}. Examples: >
7551 nr2char(64) returns "@"
7552 nr2char(32) returns " "
7553< When {utf8} is omitted or zero, the current 'encoding' is used.
7554 Example for "utf-8": >
7555 nr2char(300) returns I with bow character
7556< When {utf8} is TRUE, always return UTF-8 characters.
7557 Note that a NUL character in the file is specified with
7558 nr2char(10), because NULs are represented with newline
7559 characters. nr2char(0) is a real NUL and terminates the
7560 string, thus results in an empty string.
7561 To turn a list of character numbers into a string: >
7562 let list = [65, 66, 67]
7563 let str = join(map(list, {_, val -> nr2char(val)}), '')
7564< Result: "ABC"
7565
7566 Can also be used as a |method|: >
7567 GetNumber()->nr2char()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007568<
7569 Return type: |String|
7570
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007571
7572or({expr}, {expr}) *or()*
7573 Bitwise OR on the two arguments. The arguments are converted
7574 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01007575 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007576 Example: >
7577 :let bits = or(bits, 0x80)
7578< Can also be used as a |method|: >
7579 :let bits = bits->or(0x80)
7580
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01007581< Rationale: The reason this is a function and not using the "|"
7582 character like many languages, is that Vi has always used "|"
7583 to separate commands. In many places it would not be clear if
7584 "|" is an operator or a command separator.
7585
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007586 Return type: |Number|
7587
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007588
7589pathshorten({path} [, {len}]) *pathshorten()*
7590 Shorten directory names in the path {path} and return the
7591 result. The tail, the file name, is kept as-is. The other
7592 components in the path are reduced to {len} letters in length.
7593 If {len} is omitted or smaller than 1 then 1 is used (single
7594 letters). Leading '~' and '.' characters are kept. Examples: >
7595 :echo pathshorten('~/.vim/autoload/myfile.vim')
7596< ~/.v/a/myfile.vim ~
7597>
7598 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
7599< ~/.vi/au/myfile.vim ~
7600 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007601 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007602
7603 Can also be used as a |method|: >
7604 GetDirectories()->pathshorten()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007605<
7606 Return type: |String|
7607
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007608
7609perleval({expr}) *perleval()*
7610 Evaluate Perl expression {expr} in scalar context and return
7611 its result converted to Vim data structures. If value can't be
7612 converted, it is returned as a string Perl representation.
7613 Note: If you want an array or hash, {expr} must return a
7614 reference to it.
7615 Example: >
7616 :echo perleval('[1 .. 4]')
7617< [1, 2, 3, 4]
7618
7619 Note that in a `:def` function local variables are not visible
7620 to {expr}.
7621
7622 Can also be used as a |method|: >
7623 GetExpr()->perleval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007624<
7625 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007626
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007627 {only available when compiled with the |+perl| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007628
7629
7630popup_ functions are documented here: |popup-functions|
7631
7632
7633pow({x}, {y}) *pow()*
7634 Return the power of {x} to the exponent {y} as a |Float|.
7635 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007636 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007637 Examples: >
7638 :echo pow(3, 3)
7639< 27.0 >
7640 :echo pow(2, 16)
7641< 65536.0 >
7642 :echo pow(32, 0.20)
7643< 2.0
7644
7645 Can also be used as a |method|: >
7646 Compute()->pow(3)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007647<
7648 Return type: |Number|
7649
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007650
7651prevnonblank({lnum}) *prevnonblank()*
7652 Return the line number of the first line at or above {lnum}
7653 that is not blank. Example: >
7654 let ind = indent(prevnonblank(v:lnum - 1))
7655< When {lnum} is invalid or there is no non-blank line at or
7656 above it, zero is returned.
7657 {lnum} is used like with |getline()|.
7658 Also see |nextnonblank()|.
7659
7660 Can also be used as a |method|: >
7661 GetLnum()->prevnonblank()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007662<
7663 Return type: |Number|
7664
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007665
7666printf({fmt}, {expr1} ...) *printf()*
7667 Return a String with {fmt}, where "%" items are replaced by
7668 the formatted form of their respective arguments. Example: >
7669 printf("%4d: E%d %.30s", lnum, errno, msg)
7670< May result in:
7671 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
7672
7673 When used as a |method| the base is passed as the second
7674 argument: >
7675 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007676<
7677 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007678
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007679 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007680 %s string
7681 %6S string right-aligned in 6 display cells
7682 %6s string right-aligned in 6 bytes
7683 %.9s string truncated to 9 bytes
7684 %c single byte
7685 %d decimal number
7686 %5d decimal number padded with spaces to 5 characters
7687 %x hex number
7688 %04x hex number padded with zeros to at least 4 characters
7689 %X hex number using upper case letters
7690 %o octal number
7691 %08b binary number padded with zeros to at least 8 chars
7692 %f floating point number as 12.23, inf, -inf or nan
7693 %F floating point number as 12.23, INF, -INF or NAN
7694 %e floating point number as 1.23e3, inf, -inf or nan
7695 %E floating point number as 1.23E3, INF, -INF or NAN
7696 %g floating point number, as %f or %e depending on value
7697 %G floating point number, as %F or %E depending on value
7698 %% the % character itself
7699
7700 Conversion specifications start with '%' and end with the
7701 conversion type. All other characters are copied unchanged to
7702 the result.
7703
7704 The "%" starts a conversion specification. The following
7705 arguments appear in sequence:
7706
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007707 % [pos-argument] [flags] [field-width] [.precision] type
7708
7709 pos-argument
7710 At most one positional argument specifier. These
7711 take the form {n$}, where n is >= 1.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007712
7713 flags
7714 Zero or more of the following flags:
7715
7716 # The value should be converted to an "alternate
7717 form". For c, d, and s conversions, this option
7718 has no effect. For o conversions, the precision
7719 of the number is increased to force the first
7720 character of the output string to a zero (except
7721 if a zero value is printed with an explicit
7722 precision of zero).
7723 For b and B conversions, a non-zero result has
7724 the string "0b" (or "0B" for B conversions)
7725 prepended to it.
7726 For x and X conversions, a non-zero result has
7727 the string "0x" (or "0X" for X conversions)
7728 prepended to it.
7729
7730 0 (zero) Zero padding. For all conversions the converted
7731 value is padded on the left with zeros rather
7732 than blanks. If a precision is given with a
7733 numeric conversion (d, b, B, o, x, and X), the 0
7734 flag is ignored.
7735
7736 - A negative field width flag; the converted value
7737 is to be left adjusted on the field boundary.
7738 The converted value is padded on the right with
7739 blanks, rather than on the left with blanks or
7740 zeros. A - overrides a 0 if both are given.
7741
7742 ' ' (space) A blank should be left before a positive
7743 number produced by a signed conversion (d).
7744
7745 + A sign must always be placed before a number
7746 produced by a signed conversion. A + overrides
7747 a space if both are used.
7748
7749 field-width
7750 An optional decimal digit string specifying a minimum
7751 field width. If the converted value has fewer bytes
7752 than the field width, it will be padded with spaces on
7753 the left (or right, if the left-adjustment flag has
7754 been given) to fill out the field width. For the S
7755 conversion the count is in cells.
7756
7757 .precision
7758 An optional precision, in the form of a period '.'
7759 followed by an optional digit string. If the digit
7760 string is omitted, the precision is taken as zero.
7761 This gives the minimum number of digits to appear for
7762 d, o, x, and X conversions, the maximum number of
7763 bytes to be printed from a string for s conversions,
7764 or the maximum number of cells to be printed from a
7765 string for S conversions.
7766 For floating point it is the number of digits after
7767 the decimal point.
7768
7769 type
7770 A character that specifies the type of conversion to
7771 be applied, see below.
7772
7773 A field width or precision, or both, may be indicated by an
7774 asterisk '*' instead of a digit string. In this case, a
7775 Number argument supplies the field width or precision. A
7776 negative field width is treated as a left adjustment flag
7777 followed by a positive field width; a negative precision is
7778 treated as though it were missing. Example: >
7779 :echo printf("%d: %.*s", nr, width, line)
7780< This limits the length of the text used from "line" to
7781 "width" bytes.
7782
Dominique Pellé17dca3c2023-12-14 20:36:32 +01007783 If the argument to be formatted is specified using a
7784 positional argument specifier, and a '*' is used to indicate
7785 that a number argument is to be used to specify the width or
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007786 precision, the argument(s) to be used must also be specified
7787 using a {n$} positional argument specifier. See |printf-$|.
7788
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007789 The conversion specifiers and their meanings are:
7790
7791 *printf-d* *printf-b* *printf-B* *printf-o*
7792 *printf-x* *printf-X*
7793 dbBoxX The Number argument is converted to signed decimal
7794 (d), unsigned binary (b and B), unsigned octal (o), or
7795 unsigned hexadecimal (x and X) notation. The letters
7796 "abcdef" are used for x conversions; the letters
7797 "ABCDEF" are used for X conversions.
7798 The precision, if any, gives the minimum number of
7799 digits that must appear; if the converted value
7800 requires fewer digits, it is padded on the left with
7801 zeros.
7802 In no case does a non-existent or small field width
7803 cause truncation of a numeric field; if the result of
7804 a conversion is wider than the field width, the field
7805 is expanded to contain the conversion result.
7806 The 'h' modifier indicates the argument is 16 bits.
Christ van Willegenaa90d4f2023-09-03 17:22:37 +02007807 The 'l' modifier indicates the argument is a long
7808 integer. The size will be 32 bits or 64 bits
7809 depending on your platform.
7810 The "ll" modifier indicates the argument is 64 bits.
7811 The b and B conversion specifiers never take a width
7812 modifier and always assume their argument is a 64 bit
7813 integer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007814 Generally, these modifiers are not useful. They are
7815 ignored when type is known from the argument.
7816
7817 i alias for d
7818 D alias for ld
7819 U alias for lu
7820 O alias for lo
7821
7822 *printf-c*
7823 c The Number argument is converted to a byte, and the
7824 resulting character is written.
7825
7826 *printf-s*
7827 s The text of the String argument is used. If a
7828 precision is specified, no more bytes than the number
7829 specified are used.
7830 If the argument is not a String type, it is
7831 automatically converted to text with the same format
7832 as ":echo".
7833 *printf-S*
7834 S The text of the String argument is used. If a
7835 precision is specified, no more display cells than the
7836 number specified are used.
7837
7838 *printf-f* *E807*
7839 f F The Float argument is converted into a string of the
7840 form 123.456. The precision specifies the number of
7841 digits after the decimal point. When the precision is
7842 zero the decimal point is omitted. When the precision
7843 is not specified 6 is used. A really big number
7844 (out of range or dividing by zero) results in "inf"
7845 or "-inf" with %f (INF or -INF with %F).
7846 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
7847 Example: >
7848 echo printf("%.2f", 12.115)
7849< 12.12
7850 Note that roundoff depends on the system libraries.
7851 Use |round()| when in doubt.
7852
7853 *printf-e* *printf-E*
7854 e E The Float argument is converted into a string of the
7855 form 1.234e+03 or 1.234E+03 when using 'E'. The
7856 precision specifies the number of digits after the
7857 decimal point, like with 'f'.
7858
7859 *printf-g* *printf-G*
7860 g G The Float argument is converted like with 'f' if the
7861 value is between 0.001 (inclusive) and 10000000.0
7862 (exclusive). Otherwise 'e' is used for 'g' and 'E'
7863 for 'G'. When no precision is specified superfluous
7864 zeroes and '+' signs are removed, except for the zero
7865 immediately after the decimal point. Thus 10000000.0
7866 results in 1.0e7.
7867
7868 *printf-%*
7869 % A '%' is written. No argument is converted. The
7870 complete conversion specification is "%%".
7871
7872 When a Number argument is expected a String argument is also
7873 accepted and automatically converted.
7874 When a Float or String argument is expected a Number argument
7875 is also accepted and automatically converted.
7876 Any other argument type results in an error message.
7877
7878 *E766* *E767*
7879 The number of {exprN} arguments must exactly match the number
7880 of "%" items. If there are not sufficient or too many
7881 arguments an error is given. Up to 18 arguments can be used.
7882
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007883 *printf-$*
7884 In certain languages, error and informative messages are
7885 more readable when the order of words is different from the
Christian Brabandtee17b6f2023-09-09 11:23:50 +02007886 corresponding message in English. To accommodate translations
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007887 having a different word order, positional arguments may be
7888 used to indicate this. For instance: >
7889
h_east596a9f22023-11-21 21:24:23 +09007890 #, c-format
7891 msgid "%s returning %s"
7892 msgstr "waarde %2$s komt terug van %1$s"
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007893<
h_east596a9f22023-11-21 21:24:23 +09007894 In this example, the sentence has its 2 string arguments
7895 reversed in the output. >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007896
h_east596a9f22023-11-21 21:24:23 +09007897 echo printf(
7898 "In The Netherlands, vim's creator's name is: %1$s %2$s",
7899 "Bram", "Moolenaar")
7900< In The Netherlands, vim's creator's name is: Bram Moolenaar >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007901
h_east596a9f22023-11-21 21:24:23 +09007902 echo printf(
7903 "In Belgium, vim's creator's name is: %2$s %1$s",
7904 "Bram", "Moolenaar")
7905< In Belgium, vim's creator's name is: Moolenaar Bram
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007906
7907 Width (and precision) can be specified using the '*' specifier.
7908 In this case, you must specify the field width position in the
7909 argument list. >
7910
h_east596a9f22023-11-21 21:24:23 +09007911 echo printf("%1$*2$.*3$d", 1, 2, 3)
7912< 001 >
7913 echo printf("%2$*3$.*1$d", 1, 2, 3)
7914< 2 >
7915 echo printf("%3$*1$.*2$d", 1, 2, 3)
7916< 03 >
7917 echo printf("%1$*2$.*3$g", 1.4142, 2, 3)
7918< 1.414
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007919
7920 You can mix specifying the width and/or precision directly
7921 and via positional arguments: >
7922
h_east596a9f22023-11-21 21:24:23 +09007923 echo printf("%1$4.*2$f", 1.4142135, 6)
7924< 1.414214 >
7925 echo printf("%1$*2$.4f", 1.4142135, 6)
7926< 1.4142 >
7927 echo printf("%1$*2$.*3$f", 1.4142135, 6, 2)
7928< 1.41
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007929
Christ van Willegenc35fc032024-03-14 18:30:41 +01007930 You will get an overflow error |E1510|, when the field-width
7931 or precision will result in a string longer than 6400 chars.
7932
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007933 *E1500*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007934 You cannot mix positional and non-positional arguments: >
h_east596a9f22023-11-21 21:24:23 +09007935 echo printf("%s%1$s", "One", "Two")
7936< E1500: Cannot mix positional and non-positional arguments:
7937 %s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007938
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007939 *E1501*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007940 You cannot skip a positional argument in a format string: >
h_east596a9f22023-11-21 21:24:23 +09007941 echo printf("%3$s%1$s", "One", "Two", "Three")
7942< E1501: format argument 2 unused in $-style format:
7943 %3$s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007944
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007945 *E1502*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007946 You can re-use a [field-width] (or [precision]) argument: >
h_east596a9f22023-11-21 21:24:23 +09007947 echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2)
7948< 1 at width 2 is: 01
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007949
7950 However, you can't use it as a different type: >
h_east596a9f22023-11-21 21:24:23 +09007951 echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2)
7952< E1502: Positional argument 2 used as field width reused as
7953 different type: long int/int
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007954
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007955 *E1503*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007956 When a positional argument is used, but not the correct number
7957 or arguments is given, an error is raised: >
h_east596a9f22023-11-21 21:24:23 +09007958 echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2)
7959< E1503: Positional argument 3 out of bounds: %1$d at width
7960 %2$d is: %01$*2$.*3$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007961
7962 Only the first error is reported: >
h_east596a9f22023-11-21 21:24:23 +09007963 echo printf("%01$*2$.*3$d %4$d", 1, 2)
7964< E1503: Positional argument 3 out of bounds: %01$*2$.*3$d
7965 %4$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007966
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007967 *E1504*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007968 A positional argument can be used more than once: >
h_east596a9f22023-11-21 21:24:23 +09007969 echo printf("%1$s %2$s %1$s", "One", "Two")
7970< One Two One
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007971
7972 However, you can't use a different type the second time: >
h_east596a9f22023-11-21 21:24:23 +09007973 echo printf("%1$s %2$s %1$d", "One", "Two")
7974< E1504: Positional argument 1 type used inconsistently:
7975 int/string
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007976
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007977 *E1505*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007978 Various other errors that lead to a format string being
7979 wrongly formatted lead to: >
h_east596a9f22023-11-21 21:24:23 +09007980 echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2)
7981< E1505: Invalid format specifier: %1$d at width %2$d is:
7982 %01$*2$.3$d
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007983
Christ van Willegenea746f92023-10-05 20:48:36 +02007984 *E1507*
zeertzjq27e12c72023-10-07 01:34:04 +08007985 This internal error indicates that the logic to parse a
7986 positional format argument ran into a problem that couldn't be
7987 otherwise reported. Please file a bug against Vim if you run
7988 into this, copying the exact format string and parameters that
7989 were used.
Christ van Willegenea746f92023-10-05 20:48:36 +02007990
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007991 Return type: |String|
7992
Christ van Willegenea746f92023-10-05 20:48:36 +02007993
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007994prompt_getprompt({buf}) *prompt_getprompt()*
7995 Returns the effective prompt text for buffer {buf}. {buf} can
7996 be a buffer name or number. See |prompt-buffer|.
7997
7998 If the buffer doesn't exist or isn't a prompt buffer, an empty
7999 string is returned.
8000
8001 Can also be used as a |method|: >
8002 GetBuffer()->prompt_getprompt()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008003<
8004 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008005
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008006 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008007
8008
8009prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
8010 Set prompt callback for buffer {buf} to {expr}. When {expr}
8011 is an empty string the callback is removed. This has only
8012 effect if {buf} has 'buftype' set to "prompt".
8013
8014 The callback is invoked when pressing Enter. The current
8015 buffer will always be the prompt buffer. A new line for a
8016 prompt is added before invoking the callback, thus the prompt
8017 for which the callback was invoked will be in the last but one
8018 line.
8019 If the callback wants to add text to the buffer, it must
8020 insert it above the last line, since that is where the current
8021 prompt is. This can also be done asynchronously.
8022 The callback is invoked with one argument, which is the text
8023 that was entered at the prompt. This can be an empty string
8024 if the user only typed Enter.
8025 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008026 func s:TextEntered(text)
8027 if a:text == 'exit' || a:text == 'quit'
8028 stopinsert
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008029 " Reset 'modified' to allow the buffer to be closed.
8030 " We assume there is nothing useful to be saved.
8031 set nomodified
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008032 close
8033 else
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008034 " Do something useful with "a:text". In this example
8035 " we just repeat it.
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008036 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008037 endif
8038 endfunc
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008039 call prompt_setcallback(bufnr(), function('s:TextEntered'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008040
8041< Can also be used as a |method|: >
8042 GetBuffer()->prompt_setcallback(callback)
8043
8044< {only available when compiled with the |+channel| feature}
8045
8046prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
8047 Set a callback for buffer {buf} to {expr}. When {expr} is an
8048 empty string the callback is removed. This has only effect if
8049 {buf} has 'buftype' set to "prompt".
8050
8051 This callback will be invoked when pressing CTRL-C in Insert
8052 mode. Without setting a callback Vim will exit Insert mode,
8053 as in any buffer.
8054
8055 Can also be used as a |method|: >
8056 GetBuffer()->prompt_setinterrupt(callback)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008057<
8058 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008059
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008060 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008061
8062prompt_setprompt({buf}, {text}) *prompt_setprompt()*
8063 Set prompt for buffer {buf} to {text}. You most likely want
8064 {text} to end in a space.
8065 The result is only visible if {buf} has 'buftype' set to
8066 "prompt". Example: >
8067 call prompt_setprompt(bufnr(), 'command: ')
8068<
8069 Can also be used as a |method|: >
8070 GetBuffer()->prompt_setprompt('command: ')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008071<
8072 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008073
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008074 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008075
8076prop_ functions are documented here: |text-prop-functions|
8077
8078pum_getpos() *pum_getpos()*
8079 If the popup menu (see |ins-completion-menu|) is not visible,
8080 returns an empty |Dictionary|, otherwise, returns a
8081 |Dictionary| with the following keys:
8082 height nr of items visible
8083 width screen cells
8084 row top screen row (0 first row)
8085 col leftmost screen column (0 first col)
8086 size total nr of items
8087 scrollbar |TRUE| if scrollbar is visible
8088
8089 The values are the same as in |v:event| during
8090 |CompleteChanged|.
8091
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008092 Return type: dict<any>
8093
8094
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008095pumvisible() *pumvisible()*
8096 Returns non-zero when the popup menu is visible, zero
8097 otherwise. See |ins-completion-menu|.
8098 This can be used to avoid some things that would remove the
8099 popup menu.
8100
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008101 Return type: |Number|
8102
8103
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008104py3eval({expr}) *py3eval()*
8105 Evaluate Python expression {expr} and return its result
8106 converted to Vim data structures.
8107 Numbers and strings are returned as they are (strings are
8108 copied though, Unicode strings are additionally converted to
8109 'encoding').
8110 Lists are represented as Vim |List| type.
8111 Dictionaries are represented as Vim |Dictionary| type with
8112 keys converted to strings.
8113 Note that in a `:def` function local variables are not visible
8114 to {expr}.
8115
8116 Can also be used as a |method|: >
8117 GetExpr()->py3eval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008118<
8119 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008120
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008121 {only available when compiled with the |+python3| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008122
8123 *E858* *E859*
8124pyeval({expr}) *pyeval()*
8125 Evaluate Python expression {expr} and return its result
8126 converted to Vim data structures.
8127 Numbers and strings are returned as they are (strings are
8128 copied though).
8129 Lists are represented as Vim |List| type.
8130 Dictionaries are represented as Vim |Dictionary| type,
8131 non-string keys result in error.
8132 Note that in a `:def` function local variables are not visible
8133 to {expr}.
8134
8135 Can also be used as a |method|: >
8136 GetExpr()->pyeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008137<
8138 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008139
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008140 {only available when compiled with the |+python| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008141
8142pyxeval({expr}) *pyxeval()*
8143 Evaluate Python expression {expr} and return its result
8144 converted to Vim data structures.
8145 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
8146 See also: |pyeval()|, |py3eval()|
8147
8148 Can also be used as a |method|: >
h-east52e7cc22024-07-28 17:03:29 +02008149 GetExpr()->pyxeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008150<
8151 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008152
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008153 {only available when compiled with the |+python| or the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008154 |+python3| feature}
8155
8156rand([{expr}]) *rand()* *random*
8157 Return a pseudo-random Number generated with an xoshiro128**
8158 algorithm using seed {expr}. The returned number is 32 bits,
8159 also on 64 bits systems, for consistency.
8160 {expr} can be initialized by |srand()| and will be updated by
8161 rand(). If {expr} is omitted, an internal seed value is used
8162 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008163 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008164
8165 Examples: >
8166 :echo rand()
8167 :let seed = srand()
8168 :echo rand(seed)
8169 :echo rand(seed) % 16 " random number 0 - 15
8170<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008171 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008172
8173 *E726* *E727*
8174range({expr} [, {max} [, {stride}]]) *range()*
8175 Returns a |List| with Numbers:
8176 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
8177 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
8178 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
8179 {max}] (increasing {expr} with {stride} each time, not
8180 producing a value past {max}).
8181 When the maximum is one before the start the result is an
8182 empty list. When the maximum is more than one before the
8183 start this is an error.
8184 Examples: >
8185 range(4) " [0, 1, 2, 3]
8186 range(2, 4) " [2, 3, 4]
8187 range(2, 9, 3) " [2, 5, 8]
8188 range(2, -2, -1) " [2, 1, 0, -1, -2]
8189 range(0) " []
8190 range(2, 0) " error!
8191<
8192 Can also be used as a |method|: >
8193 GetExpr()->range()
8194<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008195 Return type: list<number>
8196
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008197
K.Takata11df3ae2022-10-19 14:02:40 +01008198readblob({fname} [, {offset} [, {size}]]) *readblob()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008199 Read file {fname} in binary mode and return a |Blob|.
K.Takata11df3ae2022-10-19 14:02:40 +01008200 If {offset} is specified, read the file from the specified
8201 offset. If it is a negative value, it is used as an offset
8202 from the end of the file. E.g., to read the last 12 bytes: >
8203 readblob('file.bin', -12)
8204< If {size} is specified, only the specified size will be read.
8205 E.g. to read the first 100 bytes of a file: >
8206 readblob('file.bin', 0, 100)
8207< If {size} is -1 or omitted, the whole data starting from
8208 {offset} will be read.
K.Takata43625762022-10-20 13:28:51 +01008209 This can be also used to read the data from a character device
8210 on Unix when {size} is explicitly set. Only if the device
8211 supports seeking {offset} can be used. Otherwise it should be
8212 zero. E.g. to read 10 bytes from a serial console: >
8213 readblob('/dev/ttyS0', 0, 10)
8214< When the file can't be opened an error message is given and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008215 the result is an empty |Blob|.
Bram Moolenaar5b2a3d72022-10-21 11:25:30 +01008216 When the offset is beyond the end of the file the result is an
8217 empty blob.
8218 When trying to read more bytes than are available the result
8219 is truncated.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008220 Also see |readfile()| and |writefile()|.
8221
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008222 Return type: |Blob|
8223
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008224
8225readdir({directory} [, {expr} [, {dict}]]) *readdir()*
8226 Return a list with file and directory names in {directory}.
8227 You can also use |glob()| if you don't need to do complicated
8228 things, such as limiting the number of matches.
8229 The list will be sorted (case sensitive), see the {dict}
8230 argument below for changing the sort order.
8231
8232 When {expr} is omitted all entries are included.
8233 When {expr} is given, it is evaluated to check what to do:
8234 If {expr} results in -1 then no further entries will
8235 be handled.
8236 If {expr} results in 0 then this entry will not be
8237 added to the list.
8238 If {expr} results in 1 then this entry will be added
8239 to the list.
8240 The entries "." and ".." are always excluded.
8241 Each time {expr} is evaluated |v:val| is set to the entry name.
8242 When {expr} is a function the name is passed as the argument.
8243 For example, to get a list of files ending in ".txt": >
8244 readdir(dirname, {n -> n =~ '.txt$'})
8245< To skip hidden and backup files: >
8246 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00008247< *E857*
8248 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008249 values. Currently this is used to specify if and how sorting
8250 should be performed. The dict can have the following members:
8251
8252 sort How to sort the result returned from the system.
8253 Valid values are:
8254 "none" do not sort (fastest method)
8255 "case" sort case sensitive (byte value of
8256 each character, technically, using
8257 strcmp()) (default)
8258 "icase" sort case insensitive (technically
8259 using strcasecmp())
8260 "collate" sort using the collation order
8261 of the "POSIX" or "C" |locale|
8262 (technically using strcoll())
8263 Other values are silently ignored.
8264
8265 For example, to get a list of all files in the current
8266 directory without sorting the individual entries: >
8267 readdir('.', '1', #{sort: 'none'})
8268< If you want to get a directory tree: >
8269 function! s:tree(dir)
8270 return {a:dir : map(readdir(a:dir),
8271 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008272 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008273 endfunction
8274 echo s:tree(".")
8275<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008276 Returns an empty List on error.
8277
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008278 Can also be used as a |method|: >
8279 GetDirName()->readdir()
8280<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008281 Return type: list<string> or list<any>
8282
8283
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008284readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
8285 Extended version of |readdir()|.
8286 Return a list of Dictionaries with file and directory
8287 information in {directory}.
8288 This is useful if you want to get the attributes of file and
8289 directory at the same time as getting a list of a directory.
8290 This is much faster than calling |readdir()| then calling
8291 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
8292 each file and directory especially on MS-Windows.
8293 The list will by default be sorted by name (case sensitive),
8294 the sorting can be changed by using the optional {dict}
8295 argument, see |readdir()|.
8296
8297 The Dictionary for file and directory information has the
8298 following items:
8299 group Group name of the entry. (Only on Unix)
8300 name Name of the entry.
8301 perm Permissions of the entry. See |getfperm()|.
8302 size Size of the entry. See |getfsize()|.
8303 time Timestamp of the entry. See |getftime()|.
8304 type Type of the entry.
8305 On Unix, almost same as |getftype()| except:
8306 Symlink to a dir "linkd"
8307 Other symlink "link"
8308 On MS-Windows:
8309 Normal file "file"
8310 Directory "dir"
8311 Junction "junction"
8312 Symlink to a dir "linkd"
8313 Other symlink "link"
8314 Other reparse point "reparse"
8315 user User name of the entry's owner. (Only on Unix)
8316 On Unix, if the entry is a symlink, the Dictionary includes
8317 the information of the target (except the "type" item).
8318 On MS-Windows, it includes the information of the symlink
8319 itself because of performance reasons.
8320
8321 When {expr} is omitted all entries are included.
8322 When {expr} is given, it is evaluated to check what to do:
8323 If {expr} results in -1 then no further entries will
8324 be handled.
8325 If {expr} results in 0 then this entry will not be
8326 added to the list.
8327 If {expr} results in 1 then this entry will be added
8328 to the list.
8329 The entries "." and ".." are always excluded.
8330 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
8331 of the entry.
8332 When {expr} is a function the entry is passed as the argument.
8333 For example, to get a list of files ending in ".txt": >
8334 readdirex(dirname, {e -> e.name =~ '.txt$'})
8335<
8336 For example, to get a list of all files in the current
8337 directory without sorting the individual entries: >
8338 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008339<
8340 Can also be used as a |method|: >
8341 GetDirName()->readdirex()
8342<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008343 Return type: list<dict<any>> or list<any>
8344
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008345
8346 *readfile()*
8347readfile({fname} [, {type} [, {max}]])
8348 Read file {fname} and return a |List|, each line of the file
8349 as an item. Lines are broken at NL characters. Macintosh
8350 files separated with CR will result in a single long line
8351 (unless a NL appears somewhere).
8352 All NUL characters are replaced with a NL character.
8353 When {type} contains "b" binary mode is used:
8354 - When the last line ends in a NL an extra empty list item is
8355 added.
8356 - No CR characters are removed.
8357 Otherwise:
8358 - CR characters that appear before a NL are removed.
8359 - Whether the last line ends in a NL or not does not matter.
8360 - When 'encoding' is Unicode any UTF-8 byte order mark is
8361 removed from the text.
8362 When {max} is given this specifies the maximum number of lines
8363 to be read. Useful if you only want to check the first ten
8364 lines of a file: >
8365 :for line in readfile(fname, '', 10)
8366 : if line =~ 'Date' | echo line | endif
8367 :endfor
8368< When {max} is negative -{max} lines from the end of the file
8369 are returned, or as many as there are.
8370 When {max} is zero the result is an empty list.
8371 Note that without {max} the whole file is read into memory.
8372 Also note that there is no recognition of encoding. Read a
8373 file into a buffer if you need to.
8374 Deprecated (use |readblob()| instead): When {type} contains
8375 "B" a |Blob| is returned with the binary data of the file
8376 unmodified.
8377 When the file can't be opened an error message is given and
8378 the result is an empty list.
8379 Also see |writefile()|.
8380
8381 Can also be used as a |method|: >
8382 GetFileName()->readfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008383<
8384 Return type: list<string> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008385
8386reduce({object}, {func} [, {initial}]) *reduce()* *E998*
8387 {func} is called for every item in {object}, which can be a
8388 |String|, |List| or a |Blob|. {func} is called with two
8389 arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00008390 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008391
8392 {initial} is the initial result. When omitted, the first item
8393 in {object} is used and {func} is first called for the second
8394 item. If {initial} is not given and {object} is empty no
8395 result can be computed, an E998 error is given.
8396
8397 Examples: >
8398 echo reduce([1, 3, 5], { acc, val -> acc + val })
8399 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
8400 echo reduce(0z1122, { acc, val -> 2 * acc + val })
8401 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
8402<
8403 Can also be used as a |method|: >
8404 echo mylist->reduce({ acc, val -> acc + val }, 0)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008405<
8406 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
8407 depending on {object} and {func}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008408
8409
8410reg_executing() *reg_executing()*
8411 Returns the single letter name of the register being executed.
8412 Returns an empty string when no register is being executed.
8413 See |@|.
8414
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008415 Return type: |String|
8416
8417
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008418reg_recording() *reg_recording()*
8419 Returns the single letter name of the register being recorded.
8420 Returns an empty string when not recording. See |q|.
8421
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008422 Return type: |String|
8423
8424
8425reltime() *reltime()*
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008426reltime({start})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008427reltime({start}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008428 Return an item that represents a time value. The item is a
8429 list with items that depend on the system. In Vim 9 script
Bram Moolenaar71badf92023-04-22 22:40:14 +01008430 the type list<any> can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008431 The item can be passed to |reltimestr()| to convert it to a
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008432 string or |reltimefloat()| to convert to a Float. For
8433 example, to see the time spent in function Work(): >
8434 var startTime = reltime()
8435 Work()
8436 echo startTime->reltime()->reltimestr()
8437<
Bram Moolenaar016188f2022-06-06 20:52:59 +01008438 Without an argument reltime() returns the current time (the
Lifepillar963fd7d2024-01-05 17:44:57 +01008439 representation is system-dependent, it cannot be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01008440 wall-clock time, see |localtime()| for that).
Lifepillar963fd7d2024-01-05 17:44:57 +01008441 With one argument it returns the time passed since the time
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008442 specified in the argument.
8443 With two arguments it returns the time passed between {start}
8444 and {end}.
8445
8446 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008447 reltime(). If there is an error an empty List is returned in
8448 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008449
8450 Can also be used as a |method|: >
8451 GetStart()->reltime()
8452<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008453 Return type: list<number>
8454
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008455 {only available when compiled with the |+reltime| feature}
8456
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008457
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008458reltimefloat({time}) *reltimefloat()*
8459 Return a Float that represents the time value of {time}.
8460 Example: >
8461 let start = reltime()
8462 call MyFunction()
8463 let seconds = reltimefloat(reltime(start))
8464< See the note of reltimestr() about overhead.
8465 Also see |profiling|.
8466 If there is an error 0.0 is returned in legacy script, in Vim9
8467 script an error is given.
8468
8469 Can also be used as a |method|: >
8470 reltime(start)->reltimefloat()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008471<
8472 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008473
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008474 {only available when compiled with the |+reltime| feature}
8475
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008476
8477reltimestr({time}) *reltimestr()*
8478 Return a String that represents the time value of {time}.
8479 This is the number of seconds, a dot and the number of
8480 microseconds. Example: >
8481 let start = reltime()
8482 call MyFunction()
8483 echo reltimestr(reltime(start))
8484< Note that overhead for the commands will be added to the time.
Ernie Rael076de792023-03-16 21:43:15 +00008485 The accuracy depends on the system. Use reltimefloat() for the
8486 greatest accuracy which is nanoseconds on some systems.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008487 Leading spaces are used to make the string align nicely. You
8488 can use split() to remove it. >
8489 echo split(reltimestr(reltime(start)))[0]
8490< Also see |profiling|.
8491 If there is an error an empty string is returned in legacy
8492 script, in Vim9 script an error is given.
8493
8494 Can also be used as a |method|: >
8495 reltime(start)->reltimestr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008496<
8497 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008498
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008499 {only available when compiled with the |+reltime| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008500
8501 *remote_expr()* *E449*
8502remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00008503 Send the {string} to {server}. The {server} argument is a
8504 string, also see |{server}|.
8505
8506 The string is sent as an expression and the result is returned
8507 after evaluation. The result must be a String or a |List|. A
8508 |List| is turned into a String by joining the items with a
8509 line break in between (not at the end), like with join(expr,
8510 "\n").
8511
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008512 If {idvar} is present and not empty, it is taken as the name
8513 of a variable and a {serverid} for later use with
8514 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008515
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008516 If {timeout} is given the read times out after this many
8517 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008518
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008519 See also |clientserver| |RemoteReply|.
8520 This function is not available in the |sandbox|.
8521 {only available when compiled with the |+clientserver| feature}
8522 Note: Any errors will cause a local error message to be issued
8523 and the result will be the empty string.
8524
8525 Variables will be evaluated in the global namespace,
8526 independent of a function currently being active. Except
8527 when in debug mode, then local function variables and
8528 arguments can be evaluated.
8529
8530 Examples: >
8531 :echo remote_expr("gvim", "2+2")
8532 :echo remote_expr("gvim1", "b:current_syntax")
8533<
8534 Can also be used as a |method|: >
8535 ServerName()->remote_expr(expr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008536<
8537 Return type: |String| or list<{type}>
8538
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008539
8540remote_foreground({server}) *remote_foreground()*
8541 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008542 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008543 This works like: >
8544 remote_expr({server}, "foreground()")
8545< Except that on Win32 systems the client does the work, to work
8546 around the problem that the OS doesn't always allow the server
8547 to bring itself to the foreground.
8548 Note: This does not restore the window if it was minimized,
8549 like foreground() does.
8550 This function is not available in the |sandbox|.
8551
8552 Can also be used as a |method|: >
8553 ServerName()->remote_foreground()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008554<
8555 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008556
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008557 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008558 Win32 console version}
8559
8560
8561remote_peek({serverid} [, {retvar}]) *remote_peek()*
8562 Returns a positive number if there are available strings
8563 from {serverid}. Copies any reply string into the variable
8564 {retvar} if specified. {retvar} must be a string with the
8565 name of a variable.
8566 Returns zero if none are available.
8567 Returns -1 if something is wrong.
8568 See also |clientserver|.
8569 This function is not available in the |sandbox|.
8570 {only available when compiled with the |+clientserver| feature}
8571 Examples: >
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008572 :let repl = ""
8573 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008574
8575< Can also be used as a |method|: >
8576 ServerId()->remote_peek()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008577<
8578 Return type: |Number|
8579
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008580
8581remote_read({serverid}, [{timeout}]) *remote_read()*
8582 Return the oldest available reply from {serverid} and consume
8583 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008584 reply is available. Returns an empty string, if a reply is
8585 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008586 See also |clientserver|.
8587 This function is not available in the |sandbox|.
8588 {only available when compiled with the |+clientserver| feature}
8589 Example: >
8590 :echo remote_read(id)
8591
8592< Can also be used as a |method|: >
8593 ServerId()->remote_read()
8594<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008595 Return type: |String|
8596
8597
8598remote_send({server}, {string} [, {idvar}]) *remote_send()* *E241*
Bram Moolenaar944697a2022-02-20 19:48:20 +00008599 Send the {string} to {server}. The {server} argument is a
8600 string, also see |{server}|.
8601
8602 The string is sent as input keys and the function returns
8603 immediately. At the Vim server the keys are not mapped
8604 |:map|.
8605
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008606 If {idvar} is present, it is taken as the name of a variable
8607 and a {serverid} for later use with remote_read() is stored
8608 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008609
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008610 See also |clientserver| |RemoteReply|.
8611 This function is not available in the |sandbox|.
8612 {only available when compiled with the |+clientserver| feature}
8613
8614 Note: Any errors will be reported in the server and may mess
8615 up the display.
8616 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008617 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008618 \ remote_read(serverid)
8619
8620 :autocmd NONE RemoteReply *
8621 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008622 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008623 \ 'server2client(expand("<client>"), "HELLO")<CR>')
8624<
8625 Can also be used as a |method|: >
8626 ServerName()->remote_send(keys)
8627<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008628 Return type: |String|
8629
8630
8631remote_startserver({name}) *remote_startserver()* *E941* *E942*
h-east17b69512023-05-01 22:36:56 +01008632 Become the server {name}. {name} must be a non-empty string.
8633 This fails if already running as a server, when |v:servername|
8634 is not empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008635
8636 Can also be used as a |method|: >
8637 ServerName()->remote_startserver()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008638<
8639 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008640
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008641 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008642
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008643
8644remove({list}, {idx}) *remove()*
8645remove({list}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008646 Without {end}: Remove the item at {idx} from |List| {list} and
8647 return the item.
8648 With {end}: Remove items from {idx} to {end} (inclusive) and
8649 return a |List| with these items. When {idx} points to the same
8650 item as {end} a list with one item is returned. When {end}
8651 points to an item before {idx} this is an error.
8652 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008653 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008654 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008655 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008656 :call remove(mylist, 0, 9)
8657<
8658 Use |delete()| to remove a file.
8659
8660 Can also be used as a |method|: >
8661 mylist->remove(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008662<
8663 Return type: any, depending on {list}
8664
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008665
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008666remove({blob}, {idx})
8667remove({blob}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008668 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
8669 return the byte.
8670 With {end}: Remove bytes from {idx} to {end} (inclusive) and
8671 return a |Blob| with these bytes. When {idx} points to the same
8672 byte as {end} a |Blob| with one byte is returned. When {end}
8673 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008674 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008675 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008676 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008677 :call remove(mylist, 0, 9)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008678<
8679 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008680
8681remove({dict}, {key})
8682 Remove the entry from {dict} with key {key} and return it.
8683 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008684 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008685< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008686 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008687
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008688 Return type: any, depending on {dict}
8689
8690
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008691rename({from}, {to}) *rename()*
8692 Rename the file by the name {from} to the name {to}. This
8693 should also work to move files across file systems. The
8694 result is a Number, which is 0 if the file was renamed
8695 successfully, and non-zero when the renaming failed.
8696 NOTE: If {to} exists it is overwritten without warning.
8697 This function is not available in the |sandbox|.
8698
8699 Can also be used as a |method|: >
8700 GetOldName()->rename(newname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008701<
8702 Return type: |Number|
8703
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008704
8705repeat({expr}, {count}) *repeat()*
8706 Repeat {expr} {count} times and return the concatenated
8707 result. Example: >
8708 :let separator = repeat('-', 80)
8709< When {count} is zero or negative the result is empty.
Bakudankun375141e2022-09-09 18:46:47 +01008710 When {expr} is a |List| or a |Blob| the result is {expr}
8711 concatenated {count} times. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008712 :let longlist = repeat(['a', 'b'], 3)
8713< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
8714
8715 Can also be used as a |method|: >
8716 mylist->repeat(count)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008717<
8718 Return type: |String|, |Blob| or list<{type}> depending on
8719 {expr}
8720
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008721
8722resolve({filename}) *resolve()* *E655*
8723 On MS-Windows, when {filename} is a shortcut (a .lnk file),
8724 returns the path the shortcut points to in a simplified form.
8725 When {filename} is a symbolic link or junction point, return
8726 the full path to the target. If the target of junction is
8727 removed, return {filename}.
8728 On Unix, repeat resolving symbolic links in all path
8729 components of {filename} and return the simplified result.
8730 To cope with link cycles, resolving of symbolic links is
8731 stopped after 100 iterations.
8732 On other systems, return the simplified {filename}.
8733 The simplification step is done as by |simplify()|.
8734 resolve() keeps a leading path component specifying the
8735 current directory (provided the result is still a relative
8736 path name) and also keeps a trailing path separator.
8737
8738 Can also be used as a |method|: >
8739 GetName()->resolve()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008740<
8741 Return type: |String|
8742
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008743
8744reverse({object}) *reverse()*
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +01008745 Reverse the order of items in {object}. {object} can be a
8746 |List|, a |Blob| or a |String|. For a List and a Blob the
8747 items are reversed in-place and {object} is returned.
8748 For a String a new String is returned.
8749 Returns zero if {object} is not a List, Blob or a String.
8750 If you want a List or Blob to remain unmodified make a copy
8751 first: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008752 :let revlist = reverse(copy(mylist))
8753< Can also be used as a |method|: >
8754 mylist->reverse()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008755<
8756 Return type: |String|, |Blob| or list<{type}> depending on
8757 {object}
8758
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008759
8760round({expr}) *round()*
8761 Round off {expr} to the nearest integral value and return it
8762 as a |Float|. If {expr} lies halfway between two integral
8763 values, then use the larger one (away from zero).
8764 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008765 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008766 Examples: >
8767 echo round(0.456)
8768< 0.0 >
8769 echo round(4.5)
8770< 5.0 >
8771 echo round(-4.5)
8772< -5.0
8773
8774 Can also be used as a |method|: >
8775 Compute()->round()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008776<
8777 Return type: |Float|
8778
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008779
8780rubyeval({expr}) *rubyeval()*
8781 Evaluate Ruby expression {expr} and return its result
8782 converted to Vim data structures.
8783 Numbers, floats and strings are returned as they are (strings
8784 are copied though).
8785 Arrays are represented as Vim |List| type.
8786 Hashes are represented as Vim |Dictionary| type.
8787 Other objects are represented as strings resulted from their
8788 "Object#to_s" method.
8789 Note that in a `:def` function local variables are not visible
8790 to {expr}.
8791
8792 Can also be used as a |method|: >
8793 GetRubyExpr()->rubyeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008794<
8795 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008796
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008797 {only available when compiled with the |+ruby| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008798
8799screenattr({row}, {col}) *screenattr()*
8800 Like |screenchar()|, but return the attribute. This is a rather
8801 arbitrary number that can only be used to compare to the
8802 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008803 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008804
8805 Can also be used as a |method|: >
8806 GetRow()->screenattr(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008807<
8808 Return type: |Number|
8809
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008810
8811screenchar({row}, {col}) *screenchar()*
8812 The result is a Number, which is the character at position
8813 [row, col] on the screen. This works for every possible
8814 screen position, also status lines, window separators and the
8815 command line. The top left position is row one, column one
8816 The character excludes composing characters. For double-byte
8817 encodings it may only be the first byte.
8818 This is mainly to be used for testing.
8819 Returns -1 when row or col is out of range.
8820
8821 Can also be used as a |method|: >
8822 GetRow()->screenchar(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008823<
8824 Return type: |Number|
8825
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008826
8827screenchars({row}, {col}) *screenchars()*
8828 The result is a |List| of Numbers. The first number is the same
8829 as what |screenchar()| returns. Further numbers are
8830 composing characters on top of the base character.
8831 This is mainly to be used for testing.
8832 Returns an empty List when row or col is out of range.
8833
8834 Can also be used as a |method|: >
8835 GetRow()->screenchars(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008836<
8837 Return type: list<number> or list<any>
8838
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008839
8840screencol() *screencol()*
8841 The result is a Number, which is the current screen column of
8842 the cursor. The leftmost column has number 1.
8843 This function is mainly used for testing.
8844
8845 Note: Always returns the current screen column, thus if used
8846 in a command (e.g. ":echo screencol()") it will return the
8847 column inside the command line, which is 1 when the command is
8848 executed. To get the cursor position in the file use one of
8849 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008850 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008851 nnoremap <silent> GG :echom screencol()<CR>
8852 nnoremap GG <Cmd>echom screencol()<CR>
8853<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008854 Return type: |Number|
8855
8856
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008857screenpos({winid}, {lnum}, {col}) *screenpos()*
8858 The result is a Dict with the screen position of the text
8859 character in window {winid} at buffer line {lnum} and column
8860 {col}. {col} is a one-based byte index.
8861 The Dict has these members:
8862 row screen row
8863 col first screen column
8864 endcol last screen column
8865 curscol cursor screen column
8866 If the specified position is not visible, all values are zero.
8867 The "endcol" value differs from "col" when the character
8868 occupies more than one screen cell. E.g. for a Tab "col" can
8869 be 1 and "endcol" can be 8.
8870 The "curscol" value is where the cursor would be placed. For
8871 a Tab it would be the same as "endcol", while for a double
8872 width character it would be the same as "col".
8873 The |conceal| feature is ignored here, the column numbers are
8874 as if 'conceallevel' is zero. You can set the cursor to the
8875 right position and use |screencol()| to get the value with
8876 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008877 If the position is in a closed fold the screen position of the
8878 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008879 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008880
8881 Can also be used as a |method|: >
8882 GetWinid()->screenpos(lnum, col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008883<
8884 Return type: dict<number> or dict<any>
8885
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008886
8887screenrow() *screenrow()*
8888 The result is a Number, which is the current screen row of the
8889 cursor. The top line has number one.
8890 This function is mainly used for testing.
8891 Alternatively you can use |winline()|.
8892
8893 Note: Same restrictions as with |screencol()|.
8894
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008895 Return type: |Number|
8896
8897
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008898screenstring({row}, {col}) *screenstring()*
8899 The result is a String that contains the base character and
8900 any composing characters at position [row, col] on the screen.
8901 This is like |screenchars()| but returning a String with the
8902 characters.
8903 This is mainly to be used for testing.
8904 Returns an empty String when row or col is out of range.
8905
8906 Can also be used as a |method|: >
8907 GetRow()->screenstring(col)
8908<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008909 Return type: |String|
8910
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008911 *search()*
8912search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
8913 Search for regexp pattern {pattern}. The search starts at the
8914 cursor position (you can use |cursor()| to set it).
8915
8916 When a match has been found its line number is returned.
8917 If there is no match a 0 is returned and the cursor doesn't
8918 move. No error message is given.
Christian Brabandt9a660d22024-03-12 22:03:09 +01008919 To get the matched string, use |matchbufline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008920
8921 {flags} is a String, which can contain these character flags:
8922 'b' search Backward instead of forward
8923 'c' accept a match at the Cursor position
8924 'e' move to the End of the match
8925 'n' do Not move the cursor
8926 'p' return number of matching sub-Pattern (see below)
8927 's' Set the ' mark at the previous location of the cursor
8928 'w' Wrap around the end of the file
8929 'W' don't Wrap around the end of the file
8930 'z' start searching at the cursor column instead of zero
8931 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
8932
8933 If the 's' flag is supplied, the ' mark is set, only if the
8934 cursor is moved. The 's' flag cannot be combined with the 'n'
8935 flag.
8936
8937 'ignorecase', 'smartcase' and 'magic' are used.
8938
8939 When the 'z' flag is not given, forward searching always
8940 starts in column zero and then matches before the cursor are
8941 skipped. When the 'c' flag is present in 'cpo' the next
8942 search starts after the match. Without the 'c' flag the next
Bram Moolenaarfd999452022-08-24 18:30:14 +01008943 search starts one column after the start of the match. This
8944 matters for overlapping matches. See |cpo-c|. You can also
8945 insert "\ze" to change where the match ends, see |/\ze|.
8946
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008947 When searching backwards and the 'z' flag is given then the
8948 search starts in column zero, thus no match in the current
8949 line will be found (unless wrapping around the end of the
8950 file).
8951
8952 When the {stopline} argument is given then the search stops
8953 after searching this line. This is useful to restrict the
8954 search to a range of lines. Examples: >
8955 let match = search('(', 'b', line("w0"))
8956 let end = search('END', '', line("w$"))
8957< When {stopline} is used and it is not zero this also implies
8958 that the search does not wrap around the end of the file.
8959 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01008960 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008961 When the {timeout} argument is given the search stops when
8962 more than this many milliseconds have passed. Thus when
8963 {timeout} is 500 the search stops after half a second.
8964 The value must not be negative. A zero value is like not
8965 giving the argument.
Christian Brabandtd657d3d2024-09-10 21:55:49 +02008966
8967 Note: the timeout is only considered when searching, not
8968 while evaluating the {skip} expression.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008969 {only available when compiled with the |+reltime| feature}
8970
8971 If the {skip} expression is given it is evaluated with the
8972 cursor positioned on the start of a match. If it evaluates to
8973 non-zero this match is skipped. This can be used, for
8974 example, to skip a match in a comment or a string.
8975 {skip} can be a string, which is evaluated as an expression, a
8976 function reference or a lambda.
8977 When {skip} is omitted or empty, every match is accepted.
8978 When evaluating {skip} causes an error the search is aborted
8979 and -1 returned.
8980 *search()-sub-match*
8981 With the 'p' flag the returned value is one more than the
8982 first sub-match in \(\). One if none of them matched but the
8983 whole pattern did match.
8984 To get the column number too use |searchpos()|.
8985
8986 The cursor will be positioned at the match, unless the 'n'
8987 flag is used.
8988
8989 Example (goes over all files in the argument list): >
8990 :let n = 1
8991 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008992 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008993 : " start at the last char in the file and wrap for the
8994 : " first search to find match at start of file
8995 : normal G$
8996 : let flags = "w"
8997 : while search("foo", flags) > 0
8998 : s/foo/bar/g
8999 : let flags = "W"
9000 : endwhile
9001 : update " write the file if modified
9002 : let n = n + 1
9003 :endwhile
9004<
9005 Example for using some flags: >
9006 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
9007< This will search for the keywords "if", "else", and "endif"
9008 under or after the cursor. Because of the 'p' flag, it
9009 returns 1, 2, or 3 depending on which keyword is found, or 0
9010 if the search fails. With the cursor on the first word of the
9011 line:
9012 if (foo == 0) | let foo = foo + 1 | endif ~
9013 the function returns 1. Without the 'c' flag, the function
9014 finds the "endif" and returns 3. The same thing happens
9015 without the 'e' flag if the cursor is on the "f" of "if".
9016 The 'n' flag tells the function not to move the cursor.
9017
9018 Can also be used as a |method|: >
9019 GetPattern()->search()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009020<
9021 Return type: |Number|
9022
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009023
9024searchcount([{options}]) *searchcount()*
9025 Get or update the last search count, like what is displayed
9026 without the "S" flag in 'shortmess'. This works even if
9027 'shortmess' does contain the "S" flag.
9028
9029 This returns a |Dictionary|. The dictionary is empty if the
9030 previous pattern was not set and "pattern" was not specified.
9031
9032 key type meaning ~
9033 current |Number| current position of match;
9034 0 if the cursor position is
9035 before the first match
9036 exact_match |Boolean| 1 if "current" is matched on
9037 "pos", otherwise 0
9038 total |Number| total count of matches found
9039 incomplete |Number| 0: search was fully completed
9040 1: recomputing was timed out
9041 2: max count exceeded
9042
9043 For {options} see further down.
9044
9045 To get the last search count when |n| or |N| was pressed, call
9046 this function with `recompute: 0` . This sometimes returns
9047 wrong information because |n| and |N|'s maximum count is 99.
9048 If it exceeded 99 the result must be max count + 1 (100). If
9049 you want to get correct information, specify `recompute: 1`: >
9050
9051 " result == maxcount + 1 (100) when many matches
9052 let result = searchcount(#{recompute: 0})
9053
9054 " Below returns correct result (recompute defaults
9055 " to 1)
9056 let result = searchcount()
9057<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01009058 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009059 function! LastSearchCount() abort
9060 let result = searchcount(#{recompute: 0})
9061 if empty(result)
9062 return ''
9063 endif
9064 if result.incomplete ==# 1 " timed out
9065 return printf(' /%s [?/??]', @/)
9066 elseif result.incomplete ==# 2 " max count exceeded
9067 if result.total > result.maxcount &&
9068 \ result.current > result.maxcount
9069 return printf(' /%s [>%d/>%d]', @/,
9070 \ result.current, result.total)
9071 elseif result.total > result.maxcount
9072 return printf(' /%s [%d/>%d]', @/,
9073 \ result.current, result.total)
9074 endif
9075 endif
9076 return printf(' /%s [%d/%d]', @/,
9077 \ result.current, result.total)
9078 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009079 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009080
9081 " Or if you want to show the count only when
9082 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009083 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009084 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
9085<
9086 You can also update the search count, which can be useful in a
9087 |CursorMoved| or |CursorMovedI| autocommand: >
9088
9089 autocmd CursorMoved,CursorMovedI *
9090 \ let s:searchcount_timer = timer_start(
9091 \ 200, function('s:update_searchcount'))
9092 function! s:update_searchcount(timer) abort
9093 if a:timer ==# s:searchcount_timer
9094 call searchcount(#{
9095 \ recompute: 1, maxcount: 0, timeout: 100})
9096 redrawstatus
9097 endif
9098 endfunction
9099<
9100 This can also be used to count matched texts with specified
9101 pattern in the current buffer using "pattern": >
9102
9103 " Count '\<foo\>' in this buffer
9104 " (Note that it also updates search count)
9105 let result = searchcount(#{pattern: '\<foo\>'})
9106
9107 " To restore old search count by old pattern,
9108 " search again
9109 call searchcount()
9110<
9111 {options} must be a |Dictionary|. It can contain:
9112 key type meaning ~
9113 recompute |Boolean| if |TRUE|, recompute the count
9114 like |n| or |N| was executed.
9115 otherwise returns the last
9116 computed result (when |n| or
9117 |N| was used when "S" is not
9118 in 'shortmess', or this
9119 function was called).
9120 (default: |TRUE|)
9121 pattern |String| recompute if this was given
9122 and different with |@/|.
9123 this works as same as the
9124 below command is executed
9125 before calling this function >
9126 let @/ = pattern
9127< (default: |@/|)
9128 timeout |Number| 0 or negative number is no
9129 timeout. timeout milliseconds
9130 for recomputing the result
9131 (default: 0)
9132 maxcount |Number| 0 or negative number is no
9133 limit. max count of matched
9134 text while recomputing the
9135 result. if search exceeded
9136 total count, "total" value
9137 becomes `maxcount + 1`
9138 (default: 99)
9139 pos |List| `[lnum, col, off]` value
9140 when recomputing the result.
9141 this changes "current" result
9142 value. see |cursor()|,
9143 |getpos()|
9144 (default: cursor's position)
9145
9146 Can also be used as a |method|: >
9147 GetSearchOpts()->searchcount()
9148<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009149 Return type: dict<number>
9150
9151
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009152searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
9153 Search for the declaration of {name}.
9154
9155 With a non-zero {global} argument it works like |gD|, find
9156 first match in the file. Otherwise it works like |gd|, find
9157 first match in the function.
9158
9159 With a non-zero {thisblock} argument matches in a {} block
9160 that ends before the cursor position are ignored. Avoids
9161 finding variable declarations only valid in another scope.
9162
9163 Moves the cursor to the found match.
9164 Returns zero for success, non-zero for failure.
9165 Example: >
9166 if searchdecl('myvar') == 0
9167 echo getline('.')
9168 endif
9169<
9170 Can also be used as a |method|: >
9171 GetName()->searchdecl()
9172<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009173 Return type: |Number|
9174
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009175 *searchpair()*
9176searchpair({start}, {middle}, {end} [, {flags} [, {skip}
9177 [, {stopline} [, {timeout}]]]])
9178 Search for the match of a nested start-end pair. This can be
9179 used to find the "endif" that matches an "if", while other
9180 if/endif pairs in between are ignored.
9181 The search starts at the cursor. The default is to search
9182 forward, include 'b' in {flags} to search backward.
9183 If a match is found, the cursor is positioned at it and the
9184 line number is returned. If no match is found 0 or -1 is
9185 returned and the cursor doesn't move. No error message is
9186 given.
9187
9188 {start}, {middle} and {end} are patterns, see |pattern|. They
9189 must not contain \( \) pairs. Use of \%( \) is allowed. When
9190 {middle} is not empty, it is found when searching from either
9191 direction, but only when not in a nested start-end pair. A
9192 typical use is: >
9193 searchpair('\<if\>', '\<else\>', '\<endif\>')
9194< By leaving {middle} empty the "else" is skipped.
9195
9196 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
9197 |search()|. Additionally:
9198 'r' Repeat until no more matches found; will find the
9199 outer pair. Implies the 'W' flag.
9200 'm' Return number of matches instead of line number with
9201 the match; will be > 1 when 'r' is used.
9202 Note: it's nearly always a good idea to use the 'W' flag, to
9203 avoid wrapping around the end of the file.
9204
9205 When a match for {start}, {middle} or {end} is found, the
9206 {skip} expression is evaluated with the cursor positioned on
9207 the start of the match. It should return non-zero if this
9208 match is to be skipped. E.g., because it is inside a comment
9209 or a string.
9210 When {skip} is omitted or empty, every match is accepted.
9211 When evaluating {skip} causes an error the search is aborted
9212 and -1 returned.
9213 {skip} can be a string, a lambda, a funcref or a partial.
9214 Anything else makes the function fail.
9215 In a `:def` function when the {skip} argument is a string
9216 constant it is compiled into instructions.
9217
9218 For {stopline} and {timeout} see |search()|.
9219
9220 The value of 'ignorecase' is used. 'magic' is ignored, the
9221 patterns are used like it's on.
9222
9223 The search starts exactly at the cursor. A match with
9224 {start}, {middle} or {end} at the next character, in the
9225 direction of searching, is the first one found. Example: >
9226 if 1
9227 if 2
9228 endif 2
9229 endif 1
9230< When starting at the "if 2", with the cursor on the "i", and
9231 searching forwards, the "endif 2" is found. When starting on
9232 the character just before the "if 2", the "endif 1" will be
9233 found. That's because the "if 2" will be found first, and
9234 then this is considered to be a nested if/endif from "if 2" to
9235 "endif 2".
9236 When searching backwards and {end} is more than one character,
9237 it may be useful to put "\zs" at the end of the pattern, so
9238 that when the cursor is inside a match with the end it finds
9239 the matching start.
9240
9241 Example, to find the "endif" command in a Vim script: >
9242
9243 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
9244 \ 'getline(".") =~ "^\\s*\""')
9245
9246< The cursor must be at or after the "if" for which a match is
9247 to be found. Note that single-quote strings are used to avoid
9248 having to double the backslashes. The skip expression only
9249 catches comments at the start of a line, not after a command.
9250 Also, a word "en" or "if" halfway a line is considered a
9251 match.
9252 Another example, to search for the matching "{" of a "}": >
9253
9254 :echo searchpair('{', '', '}', 'bW')
9255
9256< This works when the cursor is at or before the "}" for which a
9257 match is to be found. To reject matches that syntax
9258 highlighting recognized as strings: >
9259
9260 :echo searchpair('{', '', '}', 'bW',
9261 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
9262<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009263 Return type: |Number|
9264
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009265 *searchpairpos()*
9266searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
9267 [, {stopline} [, {timeout}]]]])
9268 Same as |searchpair()|, but returns a |List| with the line and
9269 column position of the match. The first element of the |List|
9270 is the line number and the second element is the byte index of
9271 the column position of the match. If no match is found,
9272 returns [0, 0]. >
9273
9274 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
9275<
9276 See |match-parens| for a bigger and more useful example.
9277
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009278 Return type: list<number>
9279
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009280 *searchpos()*
9281searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
9282 Same as |search()|, but returns a |List| with the line and
9283 column position of the match. The first element of the |List|
9284 is the line number and the second element is the byte index of
9285 the column position of the match. If no match is found,
9286 returns [0, 0].
9287 Example: >
9288 :let [lnum, col] = searchpos('mypattern', 'n')
9289
9290< When the 'p' flag is given then there is an extra item with
9291 the sub-pattern match number |search()-sub-match|. Example: >
9292 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
9293< In this example "submatch" is 2 when a lowercase letter is
9294 found |/\l|, 3 when an uppercase letter is found |/\u|.
9295
9296 Can also be used as a |method|: >
9297 GetPattern()->searchpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009298<
9299 Return type: list<number>
9300
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009301
9302server2client({clientid}, {string}) *server2client()*
9303 Send a reply string to {clientid}. The most recent {clientid}
9304 that sent a string can be retrieved with expand("<client>").
9305 {only available when compiled with the |+clientserver| feature}
9306 Returns zero for success, -1 for failure.
9307 Note:
9308 This id has to be stored before the next command can be
9309 received. I.e. before returning from the received command and
9310 before calling any commands that waits for input.
9311 See also |clientserver|.
9312 Example: >
9313 :echo server2client(expand("<client>"), "HELLO")
9314
9315< Can also be used as a |method|: >
9316 GetClientId()->server2client(string)
9317<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009318 Return type: |Number|
9319
9320
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009321serverlist() *serverlist()*
9322 Return a list of available server names, one per line.
9323 When there are no servers or the information is not available
9324 an empty string is returned. See also |clientserver|.
9325 {only available when compiled with the |+clientserver| feature}
9326 Example: >
9327 :echo serverlist()
9328<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009329 Return type: |String|
9330
9331
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009332setbufline({buf}, {lnum}, {text}) *setbufline()*
9333 Set line {lnum} to {text} in buffer {buf}. This works like
9334 |setline()| for the specified buffer.
9335
9336 This function works only for loaded buffers. First call
9337 |bufload()| if needed.
9338
9339 To insert lines use |appendbufline()|.
9340 Any text properties in {lnum} are cleared.
9341
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00009342 {text} can be a string to set one line, or a List of strings
9343 to set multiple lines. If the List extends below the last
9344 line then those lines are added. If the List is empty then
9345 nothing is changed and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009346
9347 For the use of {buf}, see |bufname()| above.
9348
9349 {lnum} is used like with |setline()|.
9350 Use "$" to refer to the last line in buffer {buf}.
9351 When {lnum} is just below the last line the {text} will be
9352 added below the last line.
9353
9354 When {buf} is not a valid buffer, the buffer is not loaded or
9355 {lnum} is not valid then 1 is returned. In |Vim9| script an
9356 error is given.
9357 On success 0 is returned.
9358
9359 Can also be used as a |method|, the base is passed as the
9360 third argument: >
9361 GetText()->setbufline(buf, lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009362<
9363 Return type: |Number|
9364
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009365
9366setbufvar({buf}, {varname}, {val}) *setbufvar()*
9367 Set option or local variable {varname} in buffer {buf} to
9368 {val}.
9369 This also works for a global or local window option, but it
9370 doesn't work for a global or local window variable.
9371 For a local window option the global value is unchanged.
9372 For the use of {buf}, see |bufname()| above.
9373 The {varname} argument is a string.
9374 Note that the variable name without "b:" must be used.
9375 Examples: >
9376 :call setbufvar(1, "&mod", 1)
9377 :call setbufvar("todo", "myvar", "foobar")
9378< This function is not available in the |sandbox|.
9379
9380 Can also be used as a |method|, the base is passed as the
9381 third argument: >
9382 GetValue()->setbufvar(buf, varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009383<
9384 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009385
9386
9387setcellwidths({list}) *setcellwidths()*
9388 Specify overrides for cell widths of character ranges. This
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009389 tells Vim how wide characters are when displayed in the
9390 terminal, counted in screen cells. The values override
9391 'ambiwidth'. Example: >
9392 call setcellwidths([
Bram Moolenaar938ae282023-02-20 20:44:55 +00009393 \ [0x111, 0x111, 1],
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009394 \ [0x2194, 0x2199, 2],
9395 \ ])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009396
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009397< The {list} argument is a List of Lists with each three
9398 numbers: [{low}, {high}, {width}]. *E1109* *E1110*
9399 {low} and {high} can be the same, in which case this refers to
9400 one character. Otherwise it is the range of characters from
9401 {low} to {high} (inclusive). *E1111* *E1114*
K.Takata71933232023-01-20 16:00:55 +00009402 Only characters with value 0x80 and higher can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009403
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009404 {width} must be either 1 or 2, indicating the character width
9405 in screen cells. *E1112*
9406 An error is given if the argument is invalid, also when a
Bram Moolenaar938ae282023-02-20 20:44:55 +00009407 range overlaps with another. *E1113*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009408
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009409 If the new value causes 'fillchars' or 'listchars' to become
9410 invalid it is rejected and an error is given.
9411
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009412 To clear the overrides pass an empty {list}: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009413 setcellwidths([]);
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009414
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009415< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009416 the effect for known emoji characters. Move the cursor
9417 through the text to check if the cell widths of your terminal
9418 match with what Vim knows about each emoji. If it doesn't
9419 look right you need to adjust the {list} argument.
9420
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009421 Return type: |Number|
9422
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009423
9424setcharpos({expr}, {list}) *setcharpos()*
9425 Same as |setpos()| but uses the specified column number as the
9426 character index instead of the byte index in the line.
9427
9428 Example:
9429 With the text "여보세요" in line 8: >
9430 call setcharpos('.', [0, 8, 4, 0])
9431< positions the cursor on the fourth character '요'. >
9432 call setpos('.', [0, 8, 4, 0])
9433< positions the cursor on the second character '보'.
9434
9435 Can also be used as a |method|: >
9436 GetPosition()->setcharpos('.')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009437<
9438 Return type: |Number|
9439
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009440
9441setcharsearch({dict}) *setcharsearch()*
9442 Set the current character search information to {dict},
9443 which contains one or more of the following entries:
9444
9445 char character which will be used for a subsequent
9446 |,| or |;| command; an empty string clears the
9447 character search
9448 forward direction of character search; 1 for forward,
9449 0 for backward
9450 until type of character search; 1 for a |t| or |T|
9451 character search, 0 for an |f| or |F|
9452 character search
9453
9454 This can be useful to save/restore a user's character search
9455 from a script: >
9456 :let prevsearch = getcharsearch()
9457 :" Perform a command which clobbers user's search
9458 :call setcharsearch(prevsearch)
9459< Also see |getcharsearch()|.
9460
9461 Can also be used as a |method|: >
9462 SavedSearch()->setcharsearch()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009463<
9464 Return type: dict<any>
9465
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009466
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009467setcmdline({str} [, {pos}]) *setcmdline()*
9468 Set the command line to {str} and set the cursor position to
9469 {pos}.
9470 If {pos} is omitted, the cursor is positioned after the text.
9471 Returns 0 when successful, 1 when not editing the command
9472 line.
9473
9474 Can also be used as a |method|: >
9475 GetText()->setcmdline()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009476<
9477 Return type: |Number|
9478
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009479
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009480setcmdpos({pos}) *setcmdpos()*
9481 Set the cursor position in the command line to byte position
9482 {pos}. The first position is 1.
9483 Use |getcmdpos()| to obtain the current position.
9484 Only works while editing the command line, thus you must use
9485 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
9486 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
9487 set after the command line is set to the expression. For
9488 |c_CTRL-R_=| it is set after evaluating the expression but
9489 before inserting the resulting text.
9490 When the number is too big the cursor is put at the end of the
9491 line. A number smaller than one has undefined results.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009492 Returns 0 when successful, 1 when not editing the command
9493 line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009494
9495 Can also be used as a |method|: >
9496 GetPos()->setcmdpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009497<
9498 Return type: |Number|
9499
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009500
9501setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
9502setcursorcharpos({list})
9503 Same as |cursor()| but uses the specified column number as the
9504 character index instead of the byte index in the line.
9505
9506 Example:
9507 With the text "여보세요" in line 4: >
9508 call setcursorcharpos(4, 3)
9509< positions the cursor on the third character '세'. >
9510 call cursor(4, 3)
9511< positions the cursor on the first character '여'.
9512
9513 Can also be used as a |method|: >
9514 GetCursorPos()->setcursorcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009515<
9516 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009517
9518
9519setenv({name}, {val}) *setenv()*
9520 Set environment variable {name} to {val}. Example: >
9521 call setenv('HOME', '/home/myhome')
9522
9523< When {val} is |v:null| the environment variable is deleted.
9524 See also |expr-env|.
9525
9526 Can also be used as a |method|, the base is passed as the
9527 second argument: >
9528 GetPath()->setenv('PATH')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009529<
9530 Return type: |Number|
9531
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009532
9533setfperm({fname}, {mode}) *setfperm()* *chmod*
9534 Set the file permissions for {fname} to {mode}.
9535 {mode} must be a string with 9 characters. It is of the form
9536 "rwxrwxrwx", where each group of "rwx" flags represent, in
9537 turn, the permissions of the owner of the file, the group the
9538 file belongs to, and other users. A '-' character means the
9539 permission is off, any other character means on. Multi-byte
9540 characters are not supported.
9541
9542 For example "rw-r-----" means read-write for the user,
9543 readable by the group, not accessible by others. "xx-x-----"
9544 would do the same thing.
9545
9546 Returns non-zero for success, zero for failure.
9547
9548 Can also be used as a |method|: >
9549 GetFilename()->setfperm(mode)
9550<
9551 To read permissions see |getfperm()|.
9552
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009553 Return type: |Number|
9554
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009555
9556setline({lnum}, {text}) *setline()*
9557 Set line {lnum} of the current buffer to {text}. To insert
9558 lines use |append()|. To set lines in another buffer use
Christian Brabandt946f61c2024-06-17 13:17:58 +02009559 |setbufline()|.
h-east52e7cc22024-07-28 17:03:29 +02009560 Any text properties in {lnum} are cleared. See
9561 |text-prop-cleared|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009562
9563 {lnum} is used like with |getline()|.
9564 When {lnum} is just below the last line the {text} will be
9565 added below the last line.
9566 {text} can be any type or a List of any type, each item is
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00009567 converted to a String. When {text} is an empty List then
9568 nothing is changed and FALSE is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009569
9570 If this succeeds, FALSE is returned. If this fails (most likely
9571 because {lnum} is invalid) TRUE is returned.
9572 In |Vim9| script an error is given if {lnum} is invalid.
9573
9574 Example: >
9575 :call setline(5, strftime("%c"))
9576
9577< When {text} is a |List| then line {lnum} and following lines
9578 will be set to the items in the list. Example: >
9579 :call setline(5, ['aaa', 'bbb', 'ccc'])
9580< This is equivalent to: >
9581 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
9582 : call setline(n, l)
9583 :endfor
9584
9585< Note: The '[ and '] marks are not set.
9586
9587 Can also be used as a |method|, the base is passed as the
9588 second argument: >
9589 GetText()->setline(lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009590<
9591 Return type: |Number|
9592
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009593
9594setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
9595 Create or replace or add to the location list for window {nr}.
9596 {nr} can be the window number or the |window-ID|.
9597 When {nr} is zero the current window is used.
9598
9599 For a location list window, the displayed location list is
9600 modified. For an invalid window number {nr}, -1 is returned.
9601 Otherwise, same as |setqflist()|.
9602 Also see |location-list|.
9603
9604 For {action} see |setqflist-action|.
9605
9606 If the optional {what} dictionary argument is supplied, then
9607 only the items listed in {what} are set. Refer to |setqflist()|
9608 for the list of supported keys in {what}.
9609
9610 Can also be used as a |method|, the base is passed as the
9611 second argument: >
9612 GetLoclist()->setloclist(winnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009613<
9614 Return type: |Number|
9615
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009616
9617setmatches({list} [, {win}]) *setmatches()*
9618 Restores a list of matches saved by |getmatches()| for the
9619 current window. Returns 0 if successful, otherwise -1. All
9620 current matches are cleared before the list is restored. See
9621 example for |getmatches()|.
9622 If {win} is specified, use the window with this number or
9623 window ID instead of the current window.
9624
9625 Can also be used as a |method|: >
9626 GetMatches()->setmatches()
9627<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009628 Return type: |Number|
9629
9630
9631setpos({expr}, {list}) *setpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009632 Set the position for String {expr}. Possible values:
9633 . the cursor
9634 'x mark x
9635
9636 {list} must be a |List| with four or five numbers:
9637 [bufnum, lnum, col, off]
9638 [bufnum, lnum, col, off, curswant]
9639
9640 "bufnum" is the buffer number. Zero can be used for the
9641 current buffer. When setting an uppercase mark "bufnum" is
9642 used for the mark position. For other marks it specifies the
9643 buffer to set the mark in. You can use the |bufnr()| function
9644 to turn a file name into a buffer number.
9645 For setting the cursor and the ' mark "bufnum" is ignored,
9646 since these are associated with a window, not a buffer.
9647 Does not change the jumplist.
9648
9649 "lnum" and "col" are the position in the buffer. The first
9650 column is 1. Use a zero "lnum" to delete a mark. If "col" is
9651 smaller than 1 then 1 is used. To use the character count
9652 instead of the byte count, use |setcharpos()|.
9653
9654 The "off" number is only used when 'virtualedit' is set. Then
9655 it is the offset in screen columns from the start of the
9656 character. E.g., a position within a <Tab> or after the last
9657 character.
9658
9659 The "curswant" number is only used when setting the cursor
9660 position. It sets the preferred column for when moving the
9661 cursor vertically. When the "curswant" number is missing the
9662 preferred column is not set. When it is present and setting a
9663 mark position it is not used.
9664
9665 Note that for '< and '> changing the line number may result in
9666 the marks to be effectively be swapped, so that '< is always
9667 before '>.
9668
9669 Returns 0 when the position could be set, -1 otherwise.
9670 An error message is given if {expr} is invalid.
9671
9672 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
9673
9674 This does not restore the preferred column for moving
9675 vertically; if you set the cursor position with this, |j| and
9676 |k| motions will jump to previous columns! Use |cursor()| to
9677 also set the preferred column. Also see the "curswant" key in
9678 |winrestview()|.
9679
9680 Can also be used as a |method|: >
9681 GetPosition()->setpos('.')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009682<
9683 Return type: |Number|
9684
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009685
9686setqflist({list} [, {action} [, {what}]]) *setqflist()*
9687 Create or replace or add to the quickfix list.
9688
9689 If the optional {what} dictionary argument is supplied, then
9690 only the items listed in {what} are set. The first {list}
9691 argument is ignored. See below for the supported items in
9692 {what}.
9693 *setqflist-what*
9694 When {what} is not present, the items in {list} are used. Each
9695 item must be a dictionary. Non-dictionary items in {list} are
9696 ignored. Each dictionary item can contain the following
9697 entries:
9698
9699 bufnr buffer number; must be the number of a valid
9700 buffer
9701 filename name of a file; only used when "bufnr" is not
9702 present or it is invalid.
9703 module name of a module; if given it will be used in
9704 quickfix error window instead of the filename.
9705 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +00009706 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009707 pattern search pattern used to locate the error
9708 col column number
9709 vcol when non-zero: "col" is visual column
9710 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +00009711 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009712 nr error number
9713 text description of the error
9714 type single-character error type, 'E', 'W', etc.
9715 valid recognized error message
Tom Praschanca6ac992023-08-11 23:26:12 +02009716 user_data custom data associated with the item, can be
9717 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009718
9719 The "col", "vcol", "nr", "type" and "text" entries are
9720 optional. Either "lnum" or "pattern" entry can be used to
9721 locate a matching error line.
9722 If the "filename" and "bufnr" entries are not present or
9723 neither the "lnum" or "pattern" entries are present, then the
9724 item will not be handled as an error line.
9725 If both "pattern" and "lnum" are present then "pattern" will
9726 be used.
9727 If the "valid" entry is not supplied, then the valid flag is
9728 set when "bufnr" is a valid buffer or "filename" exists.
9729 If you supply an empty {list}, the quickfix list will be
9730 cleared.
9731 Note that the list is not exactly the same as what
9732 |getqflist()| returns.
9733
9734 {action} values: *setqflist-action* *E927*
9735 'a' The items from {list} are added to the existing
9736 quickfix list. If there is no existing list, then a
9737 new list is created.
9738
9739 'r' The items from the current quickfix list are replaced
9740 with the items from {list}. This can also be used to
9741 clear the list: >
9742 :call setqflist([], 'r')
9743<
9744 'f' All the quickfix lists in the quickfix stack are
9745 freed.
9746
9747 If {action} is not present or is set to ' ', then a new list
9748 is created. The new quickfix list is added after the current
9749 quickfix list in the stack and all the following lists are
9750 freed. To add a new quickfix list at the end of the stack,
9751 set "nr" in {what} to "$".
9752
9753 The following items can be specified in dictionary {what}:
9754 context quickfix list context. See |quickfix-context|
9755 efm errorformat to use when parsing text from
9756 "lines". If this is not present, then the
9757 'errorformat' option value is used.
9758 See |quickfix-parse|
9759 id quickfix list identifier |quickfix-ID|
9760 idx index of the current entry in the quickfix
9761 list specified by 'id' or 'nr'. If set to '$',
9762 then the last entry in the list is set as the
9763 current entry. See |quickfix-index|
9764 items list of quickfix entries. Same as the {list}
9765 argument.
9766 lines use 'errorformat' to parse a list of lines and
9767 add the resulting entries to the quickfix list
9768 {nr} or {id}. Only a |List| value is supported.
9769 See |quickfix-parse|
9770 nr list number in the quickfix stack; zero
9771 means the current quickfix list and "$" means
9772 the last quickfix list.
9773 quickfixtextfunc
9774 function to get the text to display in the
9775 quickfix window. The value can be the name of
9776 a function or a funcref or a lambda. Refer to
9777 |quickfix-window-function| for an explanation
9778 of how to write the function and an example.
9779 title quickfix list title text. See |quickfix-title|
9780 Unsupported keys in {what} are ignored.
9781 If the "nr" item is not present, then the current quickfix list
9782 is modified. When creating a new quickfix list, "nr" can be
9783 set to a value one greater than the quickfix stack size.
9784 When modifying a quickfix list, to guarantee that the correct
9785 list is modified, "id" should be used instead of "nr" to
9786 specify the list.
9787
9788 Examples (See also |setqflist-examples|): >
9789 :call setqflist([], 'r', {'title': 'My search'})
9790 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
9791 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
9792<
9793 Returns zero for success, -1 for failure.
9794
9795 This function can be used to create a quickfix list
9796 independent of the 'errorformat' setting. Use a command like
9797 `:cc 1` to jump to the first position.
9798
9799 Can also be used as a |method|, the base is passed as the
9800 second argument: >
9801 GetErrorlist()->setqflist()
9802<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009803 Return type: |Number|
9804
9805
9806setreg({regname}, {value} [, {options}]) *setreg()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009807 Set the register {regname} to {value}.
9808 If {regname} is "" or "@", the unnamed register '"' is used.
9809 The {regname} argument is a string. In |Vim9-script|
9810 {regname} must be one character.
9811
9812 {value} may be any value returned by |getreg()| or
9813 |getreginfo()|, including a |List| or |Dict|.
9814 If {options} contains "a" or {regname} is upper case,
9815 then the value is appended.
9816
9817 {options} can also contain a register type specification:
9818 "c" or "v" |characterwise| mode
9819 "l" or "V" |linewise| mode
9820 "b" or "<CTRL-V>" |blockwise-visual| mode
9821 If a number immediately follows "b" or "<CTRL-V>" then this is
9822 used as the width of the selection - if it is not specified
9823 then the width of the block is set to the number of characters
9824 in the longest line (counting a <Tab> as 1 character).
9825
9826 If {options} contains no register settings, then the default
9827 is to use character mode unless {value} ends in a <NL> for
9828 string {value} and linewise mode for list {value}. Blockwise
9829 mode is never selected automatically.
9830 Returns zero for success, non-zero for failure.
9831
9832 *E883*
9833 Note: you may not use |List| containing more than one item to
9834 set search and expression registers. Lists containing no
9835 items act like empty strings.
9836
9837 Examples: >
9838 :call setreg(v:register, @*)
9839 :call setreg('*', @%, 'ac')
9840 :call setreg('a', "1\n2\n3", 'b5')
9841 :call setreg('"', { 'points_to': 'a'})
9842
9843< This example shows using the functions to save and restore a
9844 register: >
9845 :let var_a = getreginfo()
9846 :call setreg('a', var_a)
9847< or: >
9848 :let var_a = getreg('a', 1, 1)
9849 :let var_amode = getregtype('a')
9850 ....
9851 :call setreg('a', var_a, var_amode)
9852< Note: you may not reliably restore register value
9853 without using the third argument to |getreg()| as without it
9854 newlines are represented as newlines AND Nul bytes are
9855 represented as newlines as well, see |NL-used-for-Nul|.
9856
9857 You can also change the type of a register by appending
9858 nothing: >
9859 :call setreg('a', '', 'al')
9860
9861< Can also be used as a |method|, the base is passed as the
9862 second argument: >
9863 GetText()->setreg('a')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009864<
9865 Return type: |Number|
9866
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009867
9868settabvar({tabnr}, {varname}, {val}) *settabvar()*
9869 Set tab-local variable {varname} to {val} in tab page {tabnr}.
9870 |t:var|
9871 The {varname} argument is a string.
9872 Note that autocommands are blocked, side effects may not be
9873 triggered, e.g. when setting 'filetype'.
9874 Note that the variable name without "t:" must be used.
9875 Tabs are numbered starting with one.
9876 This function is not available in the |sandbox|.
9877
9878 Can also be used as a |method|, the base is passed as the
9879 third argument: >
9880 GetValue()->settabvar(tab, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009881<
9882 Return type: |Number|
9883
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009884
9885settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
9886 Set option or local variable {varname} in window {winnr} to
9887 {val}.
9888 Tabs are numbered starting with one. For the current tabpage
9889 use |setwinvar()|.
9890 {winnr} can be the window number or the |window-ID|.
9891 When {winnr} is zero the current window is used.
9892 Note that autocommands are blocked, side effects may not be
9893 triggered, e.g. when setting 'filetype' or 'syntax'.
9894 This also works for a global or local buffer option, but it
9895 doesn't work for a global or local buffer variable.
9896 For a local buffer option the global value is unchanged.
9897 Note that the variable name without "w:" must be used.
9898 Examples: >
9899 :call settabwinvar(1, 1, "&list", 0)
9900 :call settabwinvar(3, 2, "myvar", "foobar")
9901< This function is not available in the |sandbox|.
9902
9903 Can also be used as a |method|, the base is passed as the
9904 fourth argument: >
9905 GetValue()->settabwinvar(tab, winnr, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009906<
9907 Return type: |Number|
9908
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009909
9910settagstack({nr}, {dict} [, {action}]) *settagstack()*
9911 Modify the tag stack of the window {nr} using {dict}.
9912 {nr} can be the window number or the |window-ID|.
9913
9914 For a list of supported items in {dict}, refer to
9915 |gettagstack()|. "curidx" takes effect before changing the tag
9916 stack.
9917 *E962*
9918 How the tag stack is modified depends on the {action}
9919 argument:
9920 - If {action} is not present or is set to 'r', then the tag
9921 stack is replaced.
9922 - If {action} is set to 'a', then new entries from {dict} are
9923 pushed (added) onto the tag stack.
9924 - If {action} is set to 't', then all the entries from the
9925 current entry in the tag stack or "curidx" in {dict} are
9926 removed and then new entries are pushed to the stack.
9927
9928 The current index is set to one after the length of the tag
9929 stack after the modification.
9930
9931 Returns zero for success, -1 for failure.
9932
9933 Examples (for more examples see |tagstack-examples|):
9934 Empty the tag stack of window 3: >
9935 call settagstack(3, {'items' : []})
9936
9937< Save and restore the tag stack: >
9938 let stack = gettagstack(1003)
9939 " do something else
9940 call settagstack(1003, stack)
9941 unlet stack
9942<
9943 Can also be used as a |method|, the base is passed as the
9944 second argument: >
9945 GetStack()->settagstack(winnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009946<
9947 Return type: |Number|
9948
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009949
9950setwinvar({winnr}, {varname}, {val}) *setwinvar()*
9951 Like |settabwinvar()| for the current tab page.
9952 Examples: >
9953 :call setwinvar(1, "&list", 0)
9954 :call setwinvar(2, "myvar", "foobar")
9955
9956< Can also be used as a |method|, the base is passed as the
9957 third argument: >
9958 GetValue()->setwinvar(winnr, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009959<
9960 Return type: |Number|
9961
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009962
9963sha256({string}) *sha256()*
9964 Returns a String with 64 hex characters, which is the SHA256
9965 checksum of {string}.
9966
9967 Can also be used as a |method|: >
9968 GetText()->sha256()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009969<
9970 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009971
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009972 {only available when compiled with the |+cryptv| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009973
9974shellescape({string} [, {special}]) *shellescape()*
9975 Escape {string} for use as a shell command argument.
9976 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +00009977 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009978 in single quotes and will double up all internal single
9979 quotes.
9980 On MS-Windows, when 'shellslash' is not set, it will enclose
9981 {string} in double quotes and double all double quotes within
9982 {string}.
9983 Otherwise it will enclose {string} in single quotes and
9984 replace all "'" with "'\''".
9985
Enno5faeb602024-05-15 21:54:19 +02009986 The {special} argument adds additional escaping of keywords
9987 used in Vim commands. When it is not omitted and a non-zero
K.Takatac0e038b2024-05-16 12:39:01 +09009988 number or a non-empty String (|non-zero-arg|), then special
9989 items such as "!", "%", "#" and "<cword>" (as listed in
9990 |expand()|) will be preceded by a backslash.
Enno5faeb602024-05-15 21:54:19 +02009991 This backslash will be removed again by the |:!| command.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009992
9993 The "!" character will be escaped (again with a |non-zero-arg|
9994 {special}) when 'shell' contains "csh" in the tail. That is
9995 because for csh and tcsh "!" is used for history replacement
9996 even when inside single quotes.
9997
9998 With a |non-zero-arg| {special} the <NL> character is also
9999 escaped. When 'shell' containing "csh" in the tail it's
10000 escaped a second time.
10001
10002 The "\" character will be escaped when 'shell' contains "fish"
10003 in the tail. That is because for fish "\" is used as an escape
10004 character inside single quotes.
10005
10006 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010007 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010008< This results in a directory listing for the file under the
10009 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010010 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010011< See also |::S|.
10012
10013 Can also be used as a |method|: >
10014 GetCommand()->shellescape()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010015<
10016 Return type: |String|
10017
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010018
10019shiftwidth([{col}]) *shiftwidth()*
10020 Returns the effective value of 'shiftwidth'. This is the
10021 'shiftwidth' value unless it is zero, in which case it is the
10022 'tabstop' value. This function was introduced with patch
10023 7.3.694 in 2012, everybody should have it by now (however it
10024 did not allow for the optional {col} argument until 8.1.542).
10025
10026 When there is one argument {col} this is used as column number
10027 for which to return the 'shiftwidth' value. This matters for the
10028 'vartabstop' feature. If the 'vartabstop' setting is enabled and
10029 no {col} argument is given, column 1 will be assumed.
10030
10031 Can also be used as a |method|: >
10032 GetColumn()->shiftwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010033<
10034 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010035
10036sign_ functions are documented here: |sign-functions-details|
10037
10038
10039simplify({filename}) *simplify()*
10040 Simplify the file name as much as possible without changing
10041 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
10042 Unix) are not resolved. If the first path component in
10043 {filename} designates the current directory, this will be
10044 valid for the result as well. A trailing path separator is
10045 not removed either. On Unix "//path" is unchanged, but
10046 "///path" is simplified to "/path" (this follows the Posix
10047 standard).
10048 Example: >
10049 simplify("./dir/.././/file/") == "./file/"
10050< Note: The combination "dir/.." is only removed if "dir" is
10051 a searchable directory or does not exist. On Unix, it is also
10052 removed when "dir" is a symbolic link within the same
10053 directory. In order to resolve all the involved symbolic
10054 links before simplifying the path name, use |resolve()|.
10055
10056 Can also be used as a |method|: >
10057 GetName()->simplify()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010058<
10059 Return type: |String|
10060
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010061
10062sin({expr}) *sin()*
10063 Return the sine of {expr}, measured in radians, as a |Float|.
10064 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010065 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010066 Examples: >
10067 :echo sin(100)
10068< -0.506366 >
10069 :echo sin(-4.01)
10070< 0.763301
10071
10072 Can also be used as a |method|: >
10073 Compute()->sin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010074<
10075 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010076
10077
10078sinh({expr}) *sinh()*
10079 Return the hyperbolic sine of {expr} as a |Float| in the range
10080 [-inf, inf].
10081 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010082 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010083 Examples: >
10084 :echo sinh(0.5)
10085< 0.521095 >
10086 :echo sinh(-0.9)
10087< -1.026517
10088
10089 Can also be used as a |method|: >
10090 Compute()->sinh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010091<
10092 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010093
10094
10095slice({expr}, {start} [, {end}]) *slice()*
10096 Similar to using a |slice| "expr[start : end]", but "end" is
10097 used exclusive. And for a string the indexes are used as
10098 character indexes instead of byte indexes, like in
zeertzjqad387692024-03-23 08:23:48 +010010099 |vim9script|. Also, composing characters are treated as a
10100 part of the preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010101 When {end} is omitted the slice continues to the last item.
10102 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010103 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010104
10105 Can also be used as a |method|: >
10106 GetList()->slice(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010107<
10108 Return type: list<{type}>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010109
10110
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010111sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010112 Sort the items in {list} in-place. Returns {list}.
10113
10114 If you want a list to remain unmodified make a copy first: >
10115 :let sortedlist = sort(copy(mylist))
10116
Bram Moolenaar2d8ed022022-05-21 13:08:16 +010010117< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010118 string representation of each item to sort on. Numbers sort
10119 after Strings, |Lists| after Numbers. For sorting text in the
10120 current buffer use |:sort|.
10121
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010122 When {how} is given and it is 'i' then case is ignored.
10123 In legacy script, for backwards compatibility, the value one
10124 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010125
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010126 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010127 locale is used for ordering. Implementation details: strcoll()
10128 is used to compare strings. See |:language| check or set the
10129 collation locale. |v:collate| can also be used to check the
10130 current locale. Sorting using the locale typically ignores
10131 case. Example: >
10132 " ö is sorted similarly to o with English locale.
10133 :language collate en_US.UTF8
10134 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10135< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
10136>
10137 " ö is sorted after z with Swedish locale.
10138 :language collate sv_SE.UTF8
10139 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10140< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
10141 This does not work properly on Mac.
10142
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010143 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010144 sorted numerical (Implementation detail: this uses the
Bram Moolenaarbe19d782023-03-09 22:06:49 +000010145 strtod() function to parse numbers. Strings, Lists, Dicts and
10146 Funcrefs will be considered as being 0). Note that this won't
10147 sort a list of strings with numbers!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010148
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010149 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010150 sorted numerical. This is like 'n' but a string containing
10151 digits will be used as the number they represent.
10152
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010153 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010154 sorted numerical. All values must be a Number or a Float.
10155
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010156 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010157 is called to compare items. The function is invoked with two
10158 items as argument and must return zero if they are equal, 1 or
10159 bigger if the first one sorts after the second one, -1 or
10160 smaller if the first one sorts before the second one.
10161
10162 {dict} is for functions with the "dict" attribute. It will be
10163 used to set the local variable "self". |Dictionary-function|
10164
10165 The sort is stable, items which compare equal (as number or as
10166 string) will keep their relative position. E.g., when sorting
10167 on numbers, text strings will sort next to each other, in the
10168 same order as they were originally.
10169
10170 Can also be used as a |method|: >
10171 mylist->sort()
10172
10173< Also see |uniq()|.
10174
10175 Example: >
10176 func MyCompare(i1, i2)
10177 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
10178 endfunc
10179 eval mylist->sort("MyCompare")
10180< A shorter compare version for this specific simple case, which
10181 ignores overflow: >
10182 func MyCompare(i1, i2)
10183 return a:i1 - a:i2
10184 endfunc
10185< For a simple expression you can use a lambda: >
10186 eval mylist->sort({i1, i2 -> i1 - i2})
10187<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010188 Return type: list<{type}>
10189
10190
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010191sound_clear() *sound_clear()*
10192 Stop playing all sounds.
10193
10194 On some Linux systems you may need the libcanberra-pulse
10195 package, otherwise sound may not stop.
10196
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010197 Return type: |Number|
10198
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010199 {only available when compiled with the |+sound| feature}
10200
10201 *sound_playevent()*
10202sound_playevent({name} [, {callback}])
10203 Play a sound identified by {name}. Which event names are
10204 supported depends on the system. Often the XDG sound names
10205 are used. On Ubuntu they may be found in
10206 /usr/share/sounds/freedesktop/stereo. Example: >
10207 call sound_playevent('bell')
10208< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
10209 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
10210 SystemStart, SystemWelcome, etc.
Yee Cheng Chin4314e4f2022-10-08 13:50:05 +010010211 On macOS, {name} refers to files located in
10212 /System/Library/Sounds (e.g. "Tink"). It will also work for
10213 custom installed sounds in folders like ~/Library/Sounds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010214
10215 When {callback} is specified it is invoked when the sound is
10216 finished. The first argument is the sound ID, the second
10217 argument is the status:
10218 0 sound was played to the end
10219 1 sound was interrupted
10220 2 error occurred after sound started
10221 Example: >
10222 func Callback(id, status)
10223 echomsg "sound " .. a:id .. " finished with " .. a:status
10224 endfunc
10225 call sound_playevent('bell', 'Callback')
10226
10227< MS-Windows: {callback} doesn't work for this function.
10228
10229 Returns the sound ID, which can be passed to `sound_stop()`.
10230 Returns zero if the sound could not be played.
10231
10232 Can also be used as a |method|: >
10233 GetSoundName()->sound_playevent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010234<
10235 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010236
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010237 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010238
10239 *sound_playfile()*
10240sound_playfile({path} [, {callback}])
10241 Like `sound_playevent()` but play sound file {path}. {path}
10242 must be a full path. On Ubuntu you may find files to play
10243 with this command: >
10244 :!find /usr/share/sounds -type f | grep -v index.theme
10245
10246< Can also be used as a |method|: >
10247 GetSoundPath()->sound_playfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010248<
10249 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010250
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010251 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010252
10253
10254sound_stop({id}) *sound_stop()*
10255 Stop playing sound {id}. {id} must be previously returned by
10256 `sound_playevent()` or `sound_playfile()`.
10257
10258 On some Linux systems you may need the libcanberra-pulse
10259 package, otherwise sound may not stop.
10260
10261 On MS-Windows, this does not work for event sound started by
10262 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
10263
10264 Can also be used as a |method|: >
10265 soundid->sound_stop()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010266<
10267 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010268
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010269 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010270
10271 *soundfold()*
10272soundfold({word})
10273 Return the sound-folded equivalent of {word}. Uses the first
10274 language in 'spelllang' for the current window that supports
10275 soundfolding. 'spell' must be set. When no sound folding is
10276 possible the {word} is returned unmodified.
10277 This can be used for making spelling suggestions. Note that
10278 the method can be quite slow.
10279
10280 Can also be used as a |method|: >
10281 GetWord()->soundfold()
10282<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010283 Return type: |String|
10284
10285
10286spellbadword([{sentence}]) *spellbadword()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010287 Without argument: The result is the badly spelled word under
10288 or after the cursor. The cursor is moved to the start of the
10289 bad word. When no bad word is found in the cursor line the
10290 result is an empty string and the cursor doesn't move.
10291
10292 With argument: The result is the first word in {sentence} that
10293 is badly spelled. If there are no spelling mistakes the
10294 result is an empty string.
10295
10296 The return value is a list with two items:
10297 - The badly spelled word or an empty string.
10298 - The type of the spelling error:
10299 "bad" spelling mistake
10300 "rare" rare word
10301 "local" word only valid in another region
10302 "caps" word should start with Capital
10303 Example: >
10304 echo spellbadword("the quik brown fox")
10305< ['quik', 'bad'] ~
10306
10307 The spelling information for the current window and the value
10308 of 'spelllang' are used.
10309
10310 Can also be used as a |method|: >
10311 GetText()->spellbadword()
10312<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010313 Return type: list<string>
10314
10315
10316spellsuggest({word} [, {max} [, {capital}]]) *spellsuggest()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010317 Return a |List| with spelling suggestions to replace {word}.
10318 When {max} is given up to this number of suggestions are
10319 returned. Otherwise up to 25 suggestions are returned.
10320
10321 When the {capital} argument is given and it's non-zero only
10322 suggestions with a leading capital will be given. Use this
10323 after a match with 'spellcapcheck'.
10324
10325 {word} can be a badly spelled word followed by other text.
10326 This allows for joining two words that were split. The
10327 suggestions also include the following text, thus you can
10328 replace a line.
10329
10330 {word} may also be a good word. Similar words will then be
10331 returned. {word} itself is not included in the suggestions,
10332 although it may appear capitalized.
10333
10334 The spelling information for the current window is used. The
10335 values of 'spelllang' and 'spellsuggest' are used.
10336
10337 Can also be used as a |method|: >
10338 GetWord()->spellsuggest()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010339<
10340 Return type: list<string> or list<any>
10341
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010342
10343split({string} [, {pattern} [, {keepempty}]]) *split()*
10344 Make a |List| out of {string}. When {pattern} is omitted or
Shane Harperc1b39842024-07-17 19:40:40 +020010345 empty each white space separated sequence of characters
10346 becomes an item.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010347 Otherwise the string is split where {pattern} matches,
10348 removing the matched characters. 'ignorecase' is not used
10349 here, add \c to ignore case. |/\c|
10350 When the first or last item is empty it is omitted, unless the
10351 {keepempty} argument is given and it's non-zero.
10352 Other empty items are kept when {pattern} matches at least one
10353 character or when {keepempty} is non-zero.
10354 Example: >
10355 :let words = split(getline('.'), '\W\+')
10356< To split a string in individual characters: >
10357 :for c in split(mystring, '\zs')
10358< If you want to keep the separator you can also use '\zs' at
10359 the end of the pattern: >
10360 :echo split('abc:def:ghi', ':\zs')
10361< ['abc:', 'def:', 'ghi'] ~
10362 Splitting a table where the first element can be empty: >
10363 :let items = split(line, ':', 1)
10364< The opposite function is |join()|.
10365
10366 Can also be used as a |method|: >
10367 GetString()->split()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010368<
10369 Return type: list<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010370
10371sqrt({expr}) *sqrt()*
10372 Return the non-negative square root of Float {expr} as a
10373 |Float|.
10374 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010375 is negative the result is NaN (Not a Number). Returns 0.0 if
10376 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010377 Examples: >
10378 :echo sqrt(100)
10379< 10.0 >
10380 :echo sqrt(-4.01)
10381< nan
10382 "nan" may be different, it depends on system libraries.
10383
10384 Can also be used as a |method|: >
10385 Compute()->sqrt()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010386<
10387 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010388
10389
10390srand([{expr}]) *srand()*
10391 Initialize seed used by |rand()|:
10392 - If {expr} is not given, seed values are initialized by
10393 reading from /dev/urandom, if possible, or using time(NULL)
10394 a.k.a. epoch time otherwise; this only has second accuracy.
10395 - If {expr} is given it must be a Number. It is used to
10396 initialize the seed values. This is useful for testing or
10397 when a predictable sequence is intended.
10398
10399 Examples: >
10400 :let seed = srand()
10401 :let seed = srand(userinput)
10402 :echo rand(seed)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010403<
10404 Return type: list<number>
10405
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010406
10407state([{what}]) *state()*
10408 Return a string which contains characters indicating the
10409 current state. Mostly useful in callbacks that want to do
10410 work that may not always be safe. Roughly this works like:
10411 - callback uses state() to check if work is safe to do.
10412 Yes: then do it right away.
10413 No: add to work queue and add a |SafeState| and/or
10414 |SafeStateAgain| autocommand (|SafeState| triggers at
10415 toplevel, |SafeStateAgain| triggers after handling
10416 messages and callbacks).
10417 - When SafeState or SafeStateAgain is triggered and executes
10418 your autocommand, check with `state()` if the work can be
10419 done now, and if yes remove it from the queue and execute.
10420 Remove the autocommand if the queue is now empty.
10421 Also see |mode()|.
10422
10423 When {what} is given only characters in this string will be
10424 added. E.g, this checks if the screen has scrolled: >
10425 if state('s') == ''
10426 " screen has not scrolled
10427<
10428 These characters indicate the state, generally indicating that
10429 something is busy:
10430 m halfway a mapping, :normal command, feedkeys() or
10431 stuffed command
10432 o operator pending, e.g. after |d|
10433 a Insert mode autocomplete active
10434 x executing an autocommand
10435 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
10436 ch_readraw() when reading json
10437 S not triggering SafeState or SafeStateAgain, e.g. after
10438 |f| or a count
10439 c callback invoked, including timer (repeats for
10440 recursiveness up to "ccc")
10441 s screen has scrolled for messages
10442
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010443 Return type: |String|
10444
10445
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010446str2float({string} [, {quoted}]) *str2float()*
10447 Convert String {string} to a Float. This mostly works the
10448 same as when using a floating point number in an expression,
10449 see |floating-point-format|. But it's a bit more permissive.
10450 E.g., "1e40" is accepted, while in an expression you need to
10451 write "1.0e40". The hexadecimal form "0x123" is also
10452 accepted, but not others, like binary or octal.
10453 When {quoted} is present and non-zero then embedded single
10454 quotes before the dot are ignored, thus "1'000.0" is a
10455 thousand.
10456 Text after the number is silently ignored.
10457 The decimal point is always '.', no matter what the locale is
10458 set to. A comma ends the number: "12,345.67" is converted to
10459 12.0. You can strip out thousands separators with
10460 |substitute()|: >
10461 let f = str2float(substitute(text, ',', '', 'g'))
10462<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010463 Returns 0.0 if the conversion fails.
10464
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010465 Can also be used as a |method|: >
10466 let f = text->substitute(',', '', 'g')->str2float()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010467<
10468 Return type: |Float|
10469
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010470
10471str2list({string} [, {utf8}]) *str2list()*
10472 Return a list containing the number values which represent
10473 each character in String {string}. Examples: >
10474 str2list(" ") returns [32]
10475 str2list("ABC") returns [65, 66, 67]
10476< |list2str()| does the opposite.
10477
10478 When {utf8} is omitted or zero, the current 'encoding' is used.
10479 When {utf8} is TRUE, always treat the String as UTF-8
10480 characters. With UTF-8 composing characters are handled
10481 properly: >
10482 str2list("á") returns [97, 769]
10483
10484< Can also be used as a |method|: >
10485 GetString()->str2list()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010486<
10487 Return type: list<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010488
10489
10490str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
10491 Convert string {string} to a number.
10492 {base} is the conversion base, it can be 2, 8, 10 or 16.
10493 When {quoted} is present and non-zero then embedded single
10494 quotes are ignored, thus "1'000'000" is a million.
10495
10496 When {base} is omitted base 10 is used. This also means that
10497 a leading zero doesn't cause octal conversion to be used, as
10498 with the default String to Number conversion. Example: >
10499 let nr = str2nr('0123')
10500<
10501 When {base} is 16 a leading "0x" or "0X" is ignored. With a
10502 different base the result will be zero. Similarly, when
10503 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
10504 {base} is 2 a leading "0b" or "0B" is ignored.
10505 Text after the number is silently ignored.
10506
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010507 Returns 0 if {string} is empty or on error.
10508
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010509 Can also be used as a |method|: >
10510 GetText()->str2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010511<
10512 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010513
10514
10515strcharlen({string}) *strcharlen()*
10516 The result is a Number, which is the number of characters
10517 in String {string}. Composing characters are ignored.
10518 |strchars()| can count the number of characters, counting
10519 composing characters separately.
10520
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010521 Returns 0 if {string} is empty or on error.
10522
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010523 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10524
10525 Can also be used as a |method|: >
10526 GetText()->strcharlen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010527<
10528 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010529
10530
10531strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
10532 Like |strpart()| but using character index and length instead
10533 of byte index and length.
10534 When {skipcc} is omitted or zero, composing characters are
10535 counted separately.
zeertzjqad387692024-03-23 08:23:48 +010010536 When {skipcc} set to 1, composing characters are treated as a
10537 part of the preceding base character, similar to |slice()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010538 When a character index is used where a character does not
10539 exist it is omitted and counted as one character. For
10540 example: >
10541 strcharpart('abc', -1, 2)
10542< results in 'a'.
10543
Bram Moolenaard592deb2022-06-17 15:42:40 +010010544 Returns an empty string on error.
10545
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010546 Can also be used as a |method|: >
10547 GetText()->strcharpart(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010548<
10549 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010550
10551
10552strchars({string} [, {skipcc}]) *strchars()*
10553 The result is a Number, which is the number of characters
10554 in String {string}.
10555 When {skipcc} is omitted or zero, composing characters are
10556 counted separately.
zeertzjqad387692024-03-23 08:23:48 +010010557 When {skipcc} set to 1, composing characters are ignored.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010558 |strcharlen()| always does this.
10559
Bram Moolenaard592deb2022-06-17 15:42:40 +010010560 Returns zero on error.
10561
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010562 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10563
10564 {skipcc} is only available after 7.4.755. For backward
10565 compatibility, you can define a wrapper function: >
10566 if has("patch-7.4.755")
10567 function s:strchars(str, skipcc)
10568 return strchars(a:str, a:skipcc)
10569 endfunction
10570 else
10571 function s:strchars(str, skipcc)
10572 if a:skipcc
10573 return strlen(substitute(a:str, ".", "x", "g"))
10574 else
10575 return strchars(a:str)
10576 endif
10577 endfunction
10578 endif
10579<
10580 Can also be used as a |method|: >
10581 GetText()->strchars()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010582<
10583 Return type: |Number|
10584
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010585
10586strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
10587 The result is a Number, which is the number of display cells
10588 String {string} occupies on the screen when it starts at {col}
10589 (first column is zero). When {col} is omitted zero is used.
10590 Otherwise it is the screen column where to start. This
10591 matters for Tab characters.
10592 The option settings of the current window are used. This
10593 matters for anything that's displayed differently, such as
10594 'tabstop' and 'display'.
10595 When {string} contains characters with East Asian Width Class
10596 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010597 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010598 Also see |strlen()|, |strwidth()| and |strchars()|.
10599
10600 Can also be used as a |method|: >
10601 GetText()->strdisplaywidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010602<
10603 Return type: |Number|
10604
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010605
10606strftime({format} [, {time}]) *strftime()*
10607 The result is a String, which is a formatted date and time, as
10608 specified by the {format} string. The given {time} is used,
10609 or the current time if no time is given. The accepted
10610 {format} depends on your system, thus this is not portable!
10611 See the manual page of the C function strftime() for the
10612 format. The maximum length of the result is 80 characters.
10613 See also |localtime()|, |getftime()| and |strptime()|.
10614 The language can be changed with the |:language| command.
10615 Examples: >
10616 :echo strftime("%c") Sun Apr 27 11:49:23 1997
10617 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
10618 :echo strftime("%y%m%d %T") 970427 11:53:55
10619 :echo strftime("%H:%M") 11:55
10620 :echo strftime("%c", getftime("file.c"))
10621 Show mod time of file.c.
10622< Not available on all systems. To check use: >
10623 :if exists("*strftime")
10624
10625< Can also be used as a |method|: >
10626 GetFormat()->strftime()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010627<
10628 Return type: |String|
10629
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010630
10631strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +010010632 Get a Number corresponding to the character at {index} in
10633 {str}. This uses a zero-based character index, not a byte
10634 index. Composing characters are considered separate
10635 characters here. Use |nr2char()| to convert the Number to a
10636 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010637 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010638 Also see |strcharpart()| and |strchars()|.
10639
10640 Can also be used as a |method|: >
10641 GetText()->strgetchar(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010642<
10643 Return type: |Number|
10644
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010645
10646stridx({haystack}, {needle} [, {start}]) *stridx()*
10647 The result is a Number, which gives the byte index in
10648 {haystack} of the first occurrence of the String {needle}.
10649 If {start} is specified, the search starts at index {start}.
10650 This can be used to find a second match: >
10651 :let colon1 = stridx(line, ":")
10652 :let colon2 = stridx(line, ":", colon1 + 1)
10653< The search is done case-sensitive.
10654 For pattern searches use |match()|.
10655 -1 is returned if the {needle} does not occur in {haystack}.
10656 See also |strridx()|.
10657 Examples: >
10658 :echo stridx("An Example", "Example") 3
10659 :echo stridx("Starting point", "Start") 0
10660 :echo stridx("Starting point", "start") -1
10661< *strstr()* *strchr()*
10662 stridx() works similar to the C function strstr(). When used
10663 with a single character it works similar to strchr().
10664
10665 Can also be used as a |method|: >
10666 GetHaystack()->stridx(needle)
10667<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010668 Return type: |Number|
10669
10670
10671string({expr}) *string()*
10672 Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010673 Float, String, Blob or a composition of them, then the result
10674 can be parsed back with |eval()|.
10675 {expr} type result ~
10676 String 'string' (single quotes are doubled)
10677 Number 123
10678 Float 123.123456 or 1.123456e8
10679 Funcref function('name')
10680 Blob 0z00112233.44556677.8899
10681 List [item, item]
10682 Dictionary {key: value, key: value}
Bram Moolenaarf1dcd142022-12-31 15:30:45 +000010683 Class class SomeName
10684 Object object of SomeName {lnum: 1, col: 3}
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010010685 Enum enum EnumName
Yegappan Lakshmanan3cf121e2024-03-31 18:45:35 +020010686 EnumValue enum name.value {name: str, ordinal: nr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010687
10688 When a |List| or |Dictionary| has a recursive reference it is
10689 replaced by "[...]" or "{...}". Using eval() on the result
10690 will then fail.
10691
mityu7f0bba22024-03-29 10:14:41 +010010692 For an object, invokes the string() method to get a textual
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +010010693 representation of the object. If the method is not present,
mityu7f0bba22024-03-29 10:14:41 +010010694 then the default representation is used. |object-string()|
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +010010695
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010696 Can also be used as a |method|: >
10697 mylist->string()
10698
10699< Also see |strtrans()|.
10700
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010701 Return type: |String|
10702
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010703
10704strlen({string}) *strlen()*
10705 The result is a Number, which is the length of the String
10706 {string} in bytes.
10707 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010708 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010709 If you want to count the number of multibyte characters use
10710 |strchars()|.
10711 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
10712
10713 Can also be used as a |method|: >
10714 GetString()->strlen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010715<
10716 Return type: |Number|
10717
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010718
10719strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
10720 The result is a String, which is part of {src}, starting from
10721 byte {start}, with the byte length {len}.
10722 When {chars} is present and TRUE then {len} is the number of
10723 characters positions (composing characters are not counted
10724 separately, thus "1" means one base character and any
10725 following composing characters).
10726 To count {start} as characters instead of bytes use
10727 |strcharpart()|.
10728
10729 When bytes are selected which do not exist, this doesn't
10730 result in an error, the bytes are simply omitted.
10731 If {len} is missing, the copy continues from {start} till the
10732 end of the {src}. >
10733 strpart("abcdefg", 3, 2) == "de"
10734 strpart("abcdefg", -2, 4) == "ab"
10735 strpart("abcdefg", 5, 4) == "fg"
10736 strpart("abcdefg", 3) == "defg"
10737
10738< Note: To get the first character, {start} must be 0. For
10739 example, to get the character under the cursor: >
10740 strpart(getline("."), col(".") - 1, 1, v:true)
10741<
Bram Moolenaard592deb2022-06-17 15:42:40 +010010742 Returns an empty string on error.
10743
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010744 Can also be used as a |method|: >
10745 GetText()->strpart(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010746<
10747 Return type: |String|
10748
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010749
10750strptime({format}, {timestring}) *strptime()*
10751 The result is a Number, which is a unix timestamp representing
10752 the date and time in {timestring}, which is expected to match
10753 the format specified in {format}.
10754
10755 The accepted {format} depends on your system, thus this is not
10756 portable! See the manual page of the C function strptime()
10757 for the format. Especially avoid "%c". The value of $TZ also
10758 matters.
10759
10760 If the {timestring} cannot be parsed with {format} zero is
10761 returned. If you do not know the format of {timestring} you
10762 can try different {format} values until you get a non-zero
10763 result.
10764
10765 See also |strftime()|.
10766 Examples: >
10767 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
10768< 862156163 >
10769 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
10770< Sun Apr 27 11:53:55 1997 >
10771 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
10772< Sun Apr 27 12:53:55 1997
10773
10774 Can also be used as a |method|: >
10775 GetFormat()->strptime(timestring)
10776<
10777 Not available on all systems. To check use: >
10778 :if exists("*strptime")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010779<
10780 Return type: |Number|
10781
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010782
10783strridx({haystack}, {needle} [, {start}]) *strridx()*
10784 The result is a Number, which gives the byte index in
10785 {haystack} of the last occurrence of the String {needle}.
10786 When {start} is specified, matches beyond this index are
10787 ignored. This can be used to find a match before a previous
10788 match: >
10789 :let lastcomma = strridx(line, ",")
10790 :let comma2 = strridx(line, ",", lastcomma - 1)
10791< The search is done case-sensitive.
10792 For pattern searches use |match()|.
10793 -1 is returned if the {needle} does not occur in {haystack}.
10794 If the {needle} is empty the length of {haystack} is returned.
10795 See also |stridx()|. Examples: >
10796 :echo strridx("an angry armadillo", "an") 3
10797< *strrchr()*
10798 When used with a single character it works similar to the C
10799 function strrchr().
10800
10801 Can also be used as a |method|: >
10802 GetHaystack()->strridx(needle)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010803<
10804 Return type: |Number|
10805
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010806
10807strtrans({string}) *strtrans()*
10808 The result is a String, which is {string} with all unprintable
10809 characters translated into printable characters |'isprint'|.
10810 Like they are shown in a window. Example: >
10811 echo strtrans(@a)
10812< This displays a newline in register a as "^@" instead of
10813 starting a new line.
10814
Bram Moolenaard592deb2022-06-17 15:42:40 +010010815 Returns an empty string on error.
10816
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010817 Can also be used as a |method|: >
10818 GetString()->strtrans()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010819<
10820 Return type: |String|
10821
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010822
Christian Brabandt67672ef2023-04-24 21:09:54 +010010823strutf16len({string} [, {countcc}]) *strutf16len()*
10824 The result is a Number, which is the number of UTF-16 code
10825 units in String {string} (after converting it to UTF-16).
10826
10827 When {countcc} is TRUE, composing characters are counted
10828 separately.
10829 When {countcc} is omitted or FALSE, composing characters are
10830 ignored.
10831
10832 Returns zero on error.
10833
10834 Also see |strlen()| and |strcharlen()|.
10835 Examples: >
10836 echo strutf16len('a') returns 1
10837 echo strutf16len('©') returns 1
10838 echo strutf16len('😊') returns 2
10839 echo strutf16len('ą́') returns 1
10840 echo strutf16len('ą́', v:true) returns 3
a5ob7r790f9a82023-09-25 06:05:47 +090010841<
Christian Brabandt67672ef2023-04-24 21:09:54 +010010842 Can also be used as a |method|: >
10843 GetText()->strutf16len()
10844<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010845 Return type: |Number|
10846
10847
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010848strwidth({string}) *strwidth()*
10849 The result is a Number, which is the number of display cells
10850 String {string} occupies. A Tab character is counted as one
10851 cell, alternatively use |strdisplaywidth()|.
10852 When {string} contains characters with East Asian Width Class
10853 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010854 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010855 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
10856
10857 Can also be used as a |method|: >
10858 GetString()->strwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010859<
10860 Return type: |Number|
10861
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010862
10863submatch({nr} [, {list}]) *submatch()* *E935*
10864 Only for an expression in a |:substitute| command or
10865 substitute() function.
10866 Returns the {nr}'th submatch of the matched text. When {nr}
10867 is 0 the whole matched text is returned.
10868 Note that a NL in the string can stand for a line break of a
10869 multi-line match or a NUL character in the text.
10870 Also see |sub-replace-expression|.
10871
10872 If {list} is present and non-zero then submatch() returns
10873 a list of strings, similar to |getline()| with two arguments.
10874 NL characters in the text represent NUL characters in the
10875 text.
10876 Only returns more than one item for |:substitute|, inside
10877 |substitute()| this list will always contain one or zero
10878 items, since there are no real line breaks.
10879
10880 When substitute() is used recursively only the submatches in
10881 the current (deepest) call can be obtained.
10882
Bram Moolenaard592deb2022-06-17 15:42:40 +010010883 Returns an empty string or list on error.
10884
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010885 Examples: >
10886 :s/\d\+/\=submatch(0) + 1/
10887 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
10888< This finds the first number in the line and adds one to it.
10889 A line break is included as a newline character.
10890
10891 Can also be used as a |method|: >
10892 GetNr()->submatch()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010893<
10894 Return type: |String| or list<string> depending on {list}
10895
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010896
10897substitute({string}, {pat}, {sub}, {flags}) *substitute()*
10898 The result is a String, which is a copy of {string}, in which
10899 the first match of {pat} is replaced with {sub}.
10900 When {flags} is "g", all matches of {pat} in {string} are
10901 replaced. Otherwise {flags} should be "".
10902
10903 This works like the ":substitute" command (without any flags).
10904 But the matching with {pat} is always done like the 'magic'
10905 option is set and 'cpoptions' is empty (to make scripts
10906 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
10907 if you want to ignore or match case and ignore 'ignorecase'.
10908 'smartcase' is not used. See |string-match| for how {pat} is
10909 used.
10910
10911 A "~" in {sub} is not replaced with the previous {sub}.
10912 Note that some codes in {sub} have a special meaning
10913 |sub-replace-special|. For example, to replace something with
10914 "\n" (two characters), use "\\\\n" or '\\n'.
10915
10916 When {pat} does not match in {string}, {string} is returned
10917 unmodified.
10918
10919 Example: >
10920 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
10921< This removes the last component of the 'path' option. >
10922 :echo substitute("testing", ".*", "\\U\\0", "")
10923< results in "TESTING".
10924
10925 When {sub} starts with "\=", the remainder is interpreted as
10926 an expression. See |sub-replace-expression|. Example: >
10927 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010928 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010929
10930< When {sub} is a Funcref that function is called, with one
10931 optional argument. Example: >
10932 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
10933< The optional argument is a list which contains the whole
10934 matched string and up to nine submatches, like what
10935 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010936 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010937
Bram Moolenaard592deb2022-06-17 15:42:40 +010010938< Returns an empty string on error.
10939
10940 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010941 GetString()->substitute(pat, sub, flags)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010942<
10943 Return type: |String|
10944
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010945
Bram Moolenaarc216a7a2022-12-05 13:50:55 +000010946swapfilelist() *swapfilelist()*
10947 Returns a list of swap file names, like what "vim -r" shows.
10948 See the |-r| command argument. The 'directory' option is used
10949 for the directories to inspect. If you only want to get a
10950 list of swap files in the current directory then temporarily
10951 set 'directory' to a dot: >
10952 let save_dir = &directory
10953 let &directory = '.'
10954 let swapfiles = swapfilelist()
10955 let &directory = save_dir
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010956<
10957 Return type: list<string>
10958
Bram Moolenaarc216a7a2022-12-05 13:50:55 +000010959
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010960swapinfo({fname}) *swapinfo()*
10961 The result is a dictionary, which holds information about the
10962 swapfile {fname}. The available fields are:
10963 version Vim version
10964 user user name
10965 host host name
10966 fname original file name
10967 pid PID of the Vim process that created the swap
10968 file
10969 mtime last modification time in seconds
10970 inode Optional: INODE number of the file
10971 dirty 1 if file was modified, 0 if not
10972 Note that "user" and "host" are truncated to at most 39 bytes.
10973 In case of failure an "error" item is added with the reason:
10974 Cannot open file: file not found or in accessible
10975 Cannot read file: cannot read first block
10976 Not a swap file: does not contain correct block ID
10977 Magic number mismatch: Info in first block is invalid
10978
10979 Can also be used as a |method|: >
10980 GetFilename()->swapinfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010981<
10982 Return type: dict<any> or dict<string>
10983
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010984
10985swapname({buf}) *swapname()*
10986 The result is the swap file path of the buffer {expr}.
10987 For the use of {buf}, see |bufname()| above.
10988 If buffer {buf} is the current buffer, the result is equal to
10989 |:swapname| (unless there is no swap file).
10990 If buffer {buf} has no swap file, returns an empty string.
10991
10992 Can also be used as a |method|: >
10993 GetBufname()->swapname()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010994<
10995 Return type: |String|
10996
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010997
10998synID({lnum}, {col}, {trans}) *synID()*
10999 The result is a Number, which is the syntax ID at the position
11000 {lnum} and {col} in the current window.
11001 The syntax ID can be used with |synIDattr()| and
11002 |synIDtrans()| to obtain syntax information about text.
11003
11004 {col} is 1 for the leftmost column, {lnum} is 1 for the first
11005 line. 'synmaxcol' applies, in a longer line zero is returned.
11006 Note that when the position is after the last character,
11007 that's where the cursor can be in Insert mode, synID() returns
11008 zero. {lnum} is used like with |getline()|.
11009
11010 When {trans} is |TRUE|, transparent items are reduced to the
11011 item that they reveal. This is useful when wanting to know
11012 the effective color. When {trans} is |FALSE|, the transparent
11013 item is returned. This is useful when wanting to know which
11014 syntax item is effective (e.g. inside parens).
11015 Warning: This function can be very slow. Best speed is
11016 obtained by going through the file in forward direction.
11017
Bram Moolenaard592deb2022-06-17 15:42:40 +010011018 Returns zero on error.
11019
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011020 Example (echoes the name of the syntax item under the cursor): >
11021 :echo synIDattr(synID(line("."), col("."), 1), "name")
11022<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011023 Return type: |Number|
11024
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011025
11026synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
11027 The result is a String, which is the {what} attribute of
11028 syntax ID {synID}. This can be used to obtain information
11029 about a syntax item.
11030 {mode} can be "gui", "cterm" or "term", to get the attributes
11031 for that mode. When {mode} is omitted, or an invalid value is
11032 used, the attributes for the currently active highlighting are
11033 used (GUI, cterm or term).
11034 Use synIDtrans() to follow linked highlight groups.
11035 {what} result
11036 "name" the name of the syntax item
11037 "fg" foreground color (GUI: color name used to set
11038 the color, cterm: color number as a string,
11039 term: empty string)
11040 "bg" background color (as with "fg")
11041 "font" font name (only available in the GUI)
11042 |highlight-font|
11043 "sp" special color for the GUI (as with "fg")
11044 |highlight-guisp|
11045 "ul" underline color for cterm: number as a string
11046 "fg#" like "fg", but for the GUI and the GUI is
11047 running the name in "#RRGGBB" form
11048 "bg#" like "fg#" for "bg"
11049 "sp#" like "fg#" for "sp"
11050 "bold" "1" if bold
11051 "italic" "1" if italic
11052 "reverse" "1" if reverse
11053 "inverse" "1" if inverse (= reverse)
11054 "standout" "1" if standout
11055 "underline" "1" if underlined
11056 "undercurl" "1" if undercurled
11057 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +010011058 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011059
Bram Moolenaard592deb2022-06-17 15:42:40 +010011060 Returns an empty string on error.
11061
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011062 Example (echoes the color of the syntax item under the
11063 cursor): >
11064 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
11065<
11066 Can also be used as a |method|: >
11067 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011068<
11069 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011070
11071
11072synIDtrans({synID}) *synIDtrans()*
11073 The result is a Number, which is the translated syntax ID of
11074 {synID}. This is the syntax group ID of what is being used to
11075 highlight the character. Highlight links given with
11076 ":highlight link" are followed.
11077
Bram Moolenaard592deb2022-06-17 15:42:40 +010011078 Returns zero on error.
11079
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011080 Can also be used as a |method|: >
11081 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011082<
11083 Return type: |Number|
11084
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011085
11086synconcealed({lnum}, {col}) *synconcealed()*
11087 The result is a |List| with currently three items:
11088 1. The first item in the list is 0 if the character at the
11089 position {lnum} and {col} is not part of a concealable
11090 region, 1 if it is. {lnum} is used like with |getline()|.
11091 2. The second item in the list is a string. If the first item
11092 is 1, the second item contains the text which will be
11093 displayed in place of the concealed text, depending on the
11094 current setting of 'conceallevel' and 'listchars'.
11095 3. The third and final item in the list is a number
11096 representing the specific syntax region matched in the
11097 line. When the character is not concealed the value is
11098 zero. This allows detection of the beginning of a new
11099 concealable region if there are two consecutive regions
11100 with the same replacement character. For an example, if
11101 the text is "123456" and both "23" and "45" are concealed
11102 and replaced by the character "X", then:
11103 call returns ~
11104 synconcealed(lnum, 1) [0, '', 0]
11105 synconcealed(lnum, 2) [1, 'X', 1]
11106 synconcealed(lnum, 3) [1, 'X', 1]
11107 synconcealed(lnum, 4) [1, 'X', 2]
11108 synconcealed(lnum, 5) [1, 'X', 2]
11109 synconcealed(lnum, 6) [0, '', 0]
11110
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020011111 Note: Doesn't consider |matchadd()| highlighting items,
11112 since syntax and matching highlighting are two different
11113 mechanisms |syntax-vs-match|.
h-east52e7cc22024-07-28 17:03:29 +020011114
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011115 Return type: list<any>
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020011116
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011117
11118synstack({lnum}, {col}) *synstack()*
11119 Return a |List|, which is the stack of syntax items at the
11120 position {lnum} and {col} in the current window. {lnum} is
11121 used like with |getline()|. Each item in the List is an ID
11122 like what |synID()| returns.
11123 The first item in the List is the outer region, following are
11124 items contained in that one. The last one is what |synID()|
11125 returns, unless not the whole item is highlighted or it is a
11126 transparent item.
11127 This function is useful for debugging a syntax file.
11128 Example that shows the syntax stack under the cursor: >
11129 for id in synstack(line("."), col("."))
11130 echo synIDattr(id, "name")
11131 endfor
11132< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +010011133 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011134 character in a line and the first column in an empty line are
11135 valid positions.
11136
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011137 Return type: list<number> or list<any>
11138
11139
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011140system({expr} [, {input}]) *system()* *E677*
11141 Get the output of the shell command {expr} as a |String|. See
11142 |systemlist()| to get the output as a |List|.
11143
11144 When {input} is given and is a |String| this string is written
11145 to a file and passed as stdin to the command. The string is
11146 written as-is, you need to take care of using the correct line
11147 separators yourself.
11148 If {input} is given and is a |List| it is written to the file
11149 in a way |writefile()| does with {binary} set to "b" (i.e.
11150 with a newline between each list item with newlines inside
11151 list items converted to NULs).
11152 When {input} is given and is a number that is a valid id for
11153 an existing buffer then the content of the buffer is written
11154 to the file line by line, each line terminated by a NL and
11155 NULs characters where the text has a NL.
11156
11157 Pipes are not used, the 'shelltemp' option is not used.
11158
11159 When prepended by |:silent| the terminal will not be set to
11160 cooked mode. This is meant to be used for commands that do
11161 not need the user to type. It avoids stray characters showing
11162 up on the screen which require |CTRL-L| to remove. >
11163 :silent let f = system('ls *.vim')
11164<
11165 Note: Use |shellescape()| or |::S| with |expand()| or
11166 |fnamemodify()| to escape special characters in a command
11167 argument. Newlines in {expr} may cause the command to fail.
11168 The characters in 'shellquote' and 'shellxquote' may also
11169 cause trouble.
11170 This is not to be used for interactive commands.
11171
11172 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011173 :let files = system('ls ' .. shellescape(expand('%:h')))
11174 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011175
11176< To make the result more system-independent, the shell output
11177 is filtered to replace <CR> with <NL> for Macintosh, and
11178 <CR><NL> with <NL> for DOS-like systems.
11179 To avoid the string being truncated at a NUL, all NUL
11180 characters are replaced with SOH (0x01).
11181
11182 The command executed is constructed using several options:
11183 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
11184 ({tmp} is an automatically generated file name).
11185 For Unix, braces are put around {expr} to allow for
11186 concatenated commands.
11187
11188 The command will be executed in "cooked" mode, so that a
11189 CTRL-C will interrupt the command (on Unix at least).
11190
11191 The resulting error code can be found in |v:shell_error|.
11192 This function will fail in |restricted-mode|.
11193
11194 Note that any wrong value in the options mentioned above may
11195 make the function fail. It has also been reported to fail
11196 when using a security agent application.
11197 Unlike ":!cmd" there is no automatic check for changed files.
11198 Use |:checktime| to force a check.
11199
11200 Can also be used as a |method|: >
11201 :echo GetCmd()->system()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011202<
11203 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011204
11205
11206systemlist({expr} [, {input}]) *systemlist()*
11207 Same as |system()|, but returns a |List| with lines (parts of
11208 output separated by NL) with NULs transformed into NLs. Output
11209 is the same as |readfile()| will output with {binary} argument
11210 set to "b", except that there is no extra empty item when the
11211 result ends in a NL.
11212 Note that on MS-Windows you may get trailing CR characters.
11213
11214 To see the difference between "echo hello" and "echo -n hello"
11215 use |system()| and |split()|: >
11216 echo system('echo hello')->split('\n', 1)
11217<
11218 Returns an empty string on error.
11219
11220 Can also be used as a |method|: >
11221 :echo GetCmd()->systemlist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011222<
11223 Return type: list<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011224
11225
11226tabpagebuflist([{arg}]) *tabpagebuflist()*
11227 The result is a |List|, where each item is the number of the
11228 buffer associated with each window in the current tab page.
11229 {arg} specifies the number of the tab page to be used. When
11230 omitted the current tab page is used.
11231 When {arg} is invalid the number zero is returned.
11232 To get a list of all buffers in all tabs use this: >
11233 let buflist = []
11234 for i in range(tabpagenr('$'))
11235 call extend(buflist, tabpagebuflist(i + 1))
11236 endfor
11237< Note that a buffer may appear in more than one window.
11238
11239 Can also be used as a |method|: >
11240 GetTabpage()->tabpagebuflist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011241<
11242 Return type: list<number>
11243
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011244
11245tabpagenr([{arg}]) *tabpagenr()*
11246 The result is a Number, which is the number of the current
11247 tab page. The first tab page has number 1.
11248
11249 The optional argument {arg} supports the following values:
11250 $ the number of the last tab page (the tab page
11251 count).
11252 # the number of the last accessed tab page
11253 (where |g<Tab>| goes to). if there is no
11254 previous tab page 0 is returned.
11255 The number can be used with the |:tab| command.
11256
Bram Moolenaard592deb2022-06-17 15:42:40 +010011257 Returns zero on error.
11258
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011259 Return type: |Number|
11260
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011261
11262tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
11263 Like |winnr()| but for tab page {tabarg}.
11264 {tabarg} specifies the number of tab page to be used.
11265 {arg} is used like with |winnr()|:
11266 - When omitted the current window number is returned. This is
11267 the window which will be used when going to this tab page.
11268 - When "$" the number of windows is returned.
11269 - When "#" the previous window nr is returned.
11270 Useful examples: >
11271 tabpagewinnr(1) " current window of tab page 1
11272 tabpagewinnr(4, '$') " number of windows in tab page 4
11273< When {tabarg} is invalid zero is returned.
11274
11275 Can also be used as a |method|: >
11276 GetTabpage()->tabpagewinnr()
11277<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011278 Return type: |Number|
11279
11280
11281tagfiles() *tagfiles()*
11282 Returns a |List| with the file names used to search for tags
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011283 for the current buffer. This is the 'tags' option expanded.
11284
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011285 Return type: list<string> or list<any>
11286
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011287
11288taglist({expr} [, {filename}]) *taglist()*
11289 Returns a |List| of tags matching the regular expression {expr}.
11290
11291 If {filename} is passed it is used to prioritize the results
11292 in the same way that |:tselect| does. See |tag-priority|.
11293 {filename} should be the full path of the file.
11294
11295 Each list item is a dictionary with at least the following
11296 entries:
11297 name Name of the tag.
11298 filename Name of the file where the tag is
11299 defined. It is either relative to the
11300 current directory or a full path.
11301 cmd Ex command used to locate the tag in
11302 the file.
11303 kind Type of the tag. The value for this
11304 entry depends on the language specific
11305 kind values. Only available when
11306 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +000011307 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011308 static A file specific tag. Refer to
11309 |static-tag| for more information.
11310 More entries may be present, depending on the content of the
11311 tags file: access, implementation, inherits and signature.
11312 Refer to the ctags documentation for information about these
11313 fields. For C code the fields "struct", "class" and "enum"
11314 may appear, they give the name of the entity the tag is
11315 contained in.
11316
11317 The ex-command "cmd" can be either an ex search pattern, a
11318 line number or a line number followed by a byte number.
11319
11320 If there are no matching tags, then an empty list is returned.
11321
11322 To get an exact tag match, the anchors '^' and '$' should be
11323 used in {expr}. This also make the function work faster.
11324 Refer to |tag-regexp| for more information about the tag
11325 search regular expression pattern.
11326
11327 Refer to |'tags'| for information about how the tags file is
11328 located by Vim. Refer to |tags-file-format| for the format of
11329 the tags file generated by the different ctags tools.
11330
11331 Can also be used as a |method|: >
11332 GetTagpattern()->taglist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011333<
11334 Return type: list<dict<any>> or list<any>
11335
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011336
11337tan({expr}) *tan()*
11338 Return the tangent of {expr}, measured in radians, as a |Float|
11339 in the range [-inf, inf].
11340 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011341 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011342 Examples: >
11343 :echo tan(10)
11344< 0.648361 >
11345 :echo tan(-4.01)
11346< -1.181502
11347
11348 Can also be used as a |method|: >
11349 Compute()->tan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011350<
11351 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011352
11353
11354tanh({expr}) *tanh()*
11355 Return the hyperbolic tangent of {expr} as a |Float| in the
11356 range [-1, 1].
11357 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011358 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011359 Examples: >
11360 :echo tanh(0.5)
11361< 0.462117 >
11362 :echo tanh(-1)
11363< -0.761594
11364
11365 Can also be used as a |method|: >
11366 Compute()->tanh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011367<
11368 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011369
11370
11371tempname() *tempname()* *temp-file-name*
11372 The result is a String, which is the name of a file that
11373 doesn't exist. It can be used for a temporary file. The name
11374 is different for at least 26 consecutive calls. Example: >
11375 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011376 :exe "redir > " .. tmpfile
Christian Brabandt5cf53012024-05-18 10:13:11 +020011377< For Unix, the file will be in a private directory |tempfile|
11378 that is recursively deleted when Vim exits, on other systems
11379 temporary files are not cleaned up automatically on exit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011380 For MS-Windows forward slashes are used when the 'shellslash'
11381 option is set, or when 'shellcmdflag' starts with '-' and
11382 'shell' does not contain powershell or pwsh.
11383
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011384 Return type: |String|
11385
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011386
11387term_ functions are documented here: |terminal-function-details|
11388
11389
11390terminalprops() *terminalprops()*
11391 Returns a |Dictionary| with properties of the terminal that Vim
11392 detected from the response to |t_RV| request. See
11393 |v:termresponse| for the response itself. If |v:termresponse|
11394 is empty most values here will be 'u' for unknown.
11395 cursor_style whether sending |t_RS| works **
11396 cursor_blink_mode whether sending |t_RC| works **
11397 underline_rgb whether |t_8u| works **
11398 mouse mouse type supported
Bram Moolenaar4bc85f22022-10-21 14:17:24 +010011399 kitty whether Kitty terminal was detected
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011400
11401 ** value 'u' for unknown, 'y' for yes, 'n' for no
11402
11403 If the |+termresponse| feature is missing then the result is
11404 an empty dictionary.
11405
11406 If "cursor_style" is 'y' then |t_RS| will be sent to request the
11407 current cursor style.
11408 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
11409 request the cursor blink status.
11410 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
11411 is not empty, Vim will detect the working of sending |t_RS|
11412 and |t_RC| on startup.
11413
11414 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
11415 This avoids sending it to xterm, which would clear the colors.
11416
11417 For "mouse" the value 'u' is unknown
11418
11419 Also see:
11420 - 'ambiwidth' - detected by using |t_u7|.
11421 - |v:termstyleresp| and |v:termblinkresp| for the response to
11422 |t_RS| and |t_RC|.
11423
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011424 Return type: dict<string>
11425
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011426
11427test_ functions are documented here: |test-functions-details|
11428
11429
11430 *timer_info()*
11431timer_info([{id}])
11432 Return a list with information about timers.
11433 When {id} is given only information about this timer is
11434 returned. When timer {id} does not exist an empty list is
11435 returned.
11436 When {id} is omitted information about all timers is returned.
11437
11438 For each timer the information is stored in a |Dictionary| with
11439 these items:
11440 "id" the timer ID
11441 "time" time the timer was started with
11442 "remaining" time until the timer fires
11443 "repeat" number of times the timer will still fire;
11444 -1 means forever
11445 "callback" the callback
11446 "paused" 1 if the timer is paused, 0 otherwise
11447
11448 Can also be used as a |method|: >
11449 GetTimer()->timer_info()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011450<
11451 Return type: list<dict<any>> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011452
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011453 {only available when compiled with the |+timers| feature}
11454
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011455
11456timer_pause({timer}, {paused}) *timer_pause()*
11457 Pause or unpause a timer. A paused timer does not invoke its
11458 callback when its time expires. Unpausing a timer may cause
11459 the callback to be invoked almost immediately if enough time
11460 has passed.
11461
11462 Pausing a timer is useful to avoid the callback to be called
11463 for a short time.
11464
11465 If {paused} evaluates to a non-zero Number or a non-empty
11466 String, then the timer is paused, otherwise it is unpaused.
11467 See |non-zero-arg|.
11468
11469 Can also be used as a |method|: >
11470 GetTimer()->timer_pause(1)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011471<
11472 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011473
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011474 {only available when compiled with the |+timers| feature}
11475
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011476
11477 *timer_start()* *timer* *timers*
11478timer_start({time}, {callback} [, {options}])
11479 Create a timer and return the timer ID.
11480
11481 {time} is the waiting time in milliseconds. This is the
11482 minimum time before invoking the callback. When the system is
11483 busy or Vim is not waiting for input the time will be longer.
Bram Moolenaardd60c362023-02-27 15:49:53 +000011484 Zero can be used to execute the callback when Vim is back in
11485 the main loop.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011486
11487 {callback} is the function to call. It can be the name of a
11488 function or a |Funcref|. It is called with one argument, which
11489 is the timer ID. The callback is only invoked when Vim is
11490 waiting for input.
11491 If you want to show a message look at |popup_notification()|
11492 to avoid interfering with what the user is doing.
11493
11494 {options} is a dictionary. Supported entries:
11495 "repeat" Number of times to repeat calling the
11496 callback. -1 means forever. When not present
11497 the callback will be called once.
11498 If the timer causes an error three times in a
11499 row the repeat is cancelled. This avoids that
11500 Vim becomes unusable because of all the error
11501 messages.
11502
Bram Moolenaard592deb2022-06-17 15:42:40 +010011503 Returns -1 on error.
11504
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011505 Example: >
11506 func MyHandler(timer)
11507 echo 'Handler called'
11508 endfunc
11509 let timer = timer_start(500, 'MyHandler',
11510 \ {'repeat': 3})
11511< This will invoke MyHandler() three times at 500 msec
11512 intervals.
11513
11514 Can also be used as a |method|: >
11515 GetMsec()->timer_start(callback)
11516
11517< Not available in the |sandbox|.
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011518
11519 Return type: |Number|
11520
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011521 {only available when compiled with the |+timers| feature}
11522
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011523
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011524timer_stop({timer}) *timer_stop()*
11525 Stop a timer. The timer callback will no longer be invoked.
11526 {timer} is an ID returned by timer_start(), thus it must be a
11527 Number. If {timer} does not exist there is no error.
11528
11529 Can also be used as a |method|: >
11530 GetTimer()->timer_stop()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011531<
11532 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011533
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011534 {only available when compiled with the |+timers| feature}
11535
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011536
11537timer_stopall() *timer_stopall()*
11538 Stop all timers. The timer callbacks will no longer be
11539 invoked. Useful if a timer is misbehaving. If there are no
11540 timers there is no error.
11541
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011542 Return type: |Number|
11543
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011544 {only available when compiled with the |+timers| feature}
11545
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011546
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011547tolower({expr}) *tolower()*
11548 The result is a copy of the String given, with all uppercase
11549 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010011550 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011551
11552 Can also be used as a |method|: >
11553 GetText()->tolower()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011554<
11555 Return type: |String|
11556
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011557
11558toupper({expr}) *toupper()*
11559 The result is a copy of the String given, with all lowercase
11560 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010011561 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011562
11563 Can also be used as a |method|: >
11564 GetText()->toupper()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011565<
11566 Return type: |String|
11567
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011568
11569tr({src}, {fromstr}, {tostr}) *tr()*
11570 The result is a copy of the {src} string with all characters
11571 which appear in {fromstr} replaced by the character in that
11572 position in the {tostr} string. Thus the first character in
11573 {fromstr} is translated into the first character in {tostr}
11574 and so on. Exactly like the unix "tr" command.
11575 This code also deals with multibyte characters properly.
11576
Bram Moolenaard592deb2022-06-17 15:42:40 +010011577 Returns an empty string on error.
11578
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011579 Examples: >
11580 echo tr("hello there", "ht", "HT")
11581< returns "Hello THere" >
11582 echo tr("<blob>", "<>", "{}")
11583< returns "{blob}"
11584
11585 Can also be used as a |method|: >
11586 GetText()->tr(from, to)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011587<
11588 Return type: |String|
11589
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011590
11591trim({text} [, {mask} [, {dir}]]) *trim()*
11592 Return {text} as a String where any character in {mask} is
11593 removed from the beginning and/or end of {text}.
11594
Illia Bobyr80799172023-10-17 18:00:50 +020011595 If {mask} is not given, or is an empty string, {mask} is all
11596 characters up to 0x20, which includes Tab, space, NL and CR,
11597 plus the non-breaking space character 0xa0.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011598
11599 The optional {dir} argument specifies where to remove the
11600 characters:
11601 0 remove from the beginning and end of {text}
11602 1 remove only at the beginning of {text}
11603 2 remove only at the end of {text}
11604 When omitted both ends are trimmed.
11605
11606 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011607 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011608
11609 Examples: >
11610 echo trim(" some text ")
11611< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011612 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011613< returns "RESERVE_TAIL" >
11614 echo trim("rm<Xrm<>X>rrm", "rm<>")
11615< returns "Xrm<>X" (characters in the middle are not removed) >
11616 echo trim(" vim ", " ", 2)
11617< returns " vim"
11618
11619 Can also be used as a |method|: >
11620 GetText()->trim()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011621<
11622 Return type: |String|
11623
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011624
11625trunc({expr}) *trunc()*
11626 Return the largest integral value with magnitude less than or
11627 equal to {expr} as a |Float| (truncate towards zero).
11628 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011629 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011630 Examples: >
11631 echo trunc(1.456)
11632< 1.0 >
11633 echo trunc(-5.456)
11634< -5.0 >
11635 echo trunc(4.0)
11636< 4.0
11637
11638 Can also be used as a |method|: >
11639 Compute()->trunc()
11640<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011641 Return type: |Float|
11642
11643
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011644 *type()*
11645type({expr}) The result is a Number representing the type of {expr}.
11646 Instead of using the number directly, it is better to use the
11647 v:t_ variable that has the value:
11648 Number: 0 |v:t_number|
11649 String: 1 |v:t_string|
11650 Funcref: 2 |v:t_func|
11651 List: 3 |v:t_list|
11652 Dictionary: 4 |v:t_dict|
11653 Float: 5 |v:t_float|
11654 Boolean: 6 |v:t_bool| (v:false and v:true)
11655 None: 7 |v:t_none| (v:null and v:none)
11656 Job: 8 |v:t_job|
11657 Channel: 9 |v:t_channel|
11658 Blob: 10 |v:t_blob|
h_east596a9f22023-11-21 21:24:23 +090011659 Class: 12 |v:t_class|
11660 Object: 13 |v:t_object|
Yegappan Lakshmanan2a71b542023-12-14 20:03:03 +010011661 Typealias: 14 |v:t_typealias|
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010011662 Enum: 15 |v:t_enum|
11663 EnumValue: 16 |v:t_enumvalue|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011664 For backward compatibility, this method can be used: >
11665 :if type(myvar) == type(0)
11666 :if type(myvar) == type("")
11667 :if type(myvar) == type(function("tr"))
11668 :if type(myvar) == type([])
11669 :if type(myvar) == type({})
11670 :if type(myvar) == type(0.0)
11671 :if type(myvar) == type(v:false)
11672 :if type(myvar) == type(v:none)
11673< To check if the v:t_ variables exist use this: >
11674 :if exists('v:t_number')
11675
11676< Can also be used as a |method|: >
11677 mylist->type()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011678<
11679 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011680
11681
11682typename({expr}) *typename()*
11683 Return a string representation of the type of {expr}.
11684 Example: >
11685 echo typename([1, 2, 3])
Kota Kato66bb9ae2023-01-17 18:31:56 +000011686< list<number> ~
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011687
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011688 Return type: |String|
11689
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011690
11691undofile({name}) *undofile()*
11692 Return the name of the undo file that would be used for a file
11693 with name {name} when writing. This uses the 'undodir'
11694 option, finding directories that exist. It does not check if
11695 the undo file exists.
11696 {name} is always expanded to the full path, since that is what
11697 is used internally.
11698 If {name} is empty undofile() returns an empty string, since a
11699 buffer without a file name will not write an undo file.
11700 Useful in combination with |:wundo| and |:rundo|.
11701 When compiled without the |+persistent_undo| option this always
11702 returns an empty string.
11703
11704 Can also be used as a |method|: >
11705 GetFilename()->undofile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011706<
11707 Return type: |String|
11708
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011709
Devin J. Pohly5fee1112023-04-23 20:26:59 -050011710undotree([{buf}]) *undotree()*
11711 Return the current state of the undo tree for the current
11712 buffer, or for a specific buffer if {buf} is given. The
11713 result is a dictionary with the following items:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011714 "seq_last" The highest undo sequence number used.
11715 "seq_cur" The sequence number of the current position in
11716 the undo tree. This differs from "seq_last"
11717 when some changes were undone.
11718 "time_cur" Time last used for |:earlier| and related
11719 commands. Use |strftime()| to convert to
11720 something readable.
11721 "save_last" Number of the last file write. Zero when no
11722 write yet.
11723 "save_cur" Number of the current position in the undo
11724 tree.
11725 "synced" Non-zero when the last undo block was synced.
11726 This happens when waiting from input from the
11727 user. See |undo-blocks|.
11728 "entries" A list of dictionaries with information about
11729 undo blocks.
11730
11731 The first item in the "entries" list is the oldest undo item.
11732 Each List item is a |Dictionary| with these items:
11733 "seq" Undo sequence number. Same as what appears in
11734 |:undolist|.
11735 "time" Timestamp when the change happened. Use
11736 |strftime()| to convert to something readable.
11737 "newhead" Only appears in the item that is the last one
11738 that was added. This marks the last change
11739 and where further changes will be added.
11740 "curhead" Only appears in the item that is the last one
11741 that was undone. This marks the current
11742 position in the undo tree, the block that will
11743 be used by a redo command. When nothing was
11744 undone after the last change this item will
11745 not appear anywhere.
11746 "save" Only appears on the last block before a file
11747 write. The number is the write count. The
11748 first write has number 1, the last one the
11749 "save_last" mentioned above.
11750 "alt" Alternate entry. This is again a List of undo
11751 blocks. Each item may again have an "alt"
11752 item.
11753
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011754 Return type: dict<any>
11755
11756
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011757uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
11758 Remove second and succeeding copies of repeated adjacent
11759 {list} items in-place. Returns {list}. If you want a list
11760 to remain unmodified make a copy first: >
11761 :let newlist = uniq(copy(mylist))
11762< The default compare function uses the string representation of
11763 each item. For the use of {func} and {dict} see |sort()|.
11764
Bram Moolenaard592deb2022-06-17 15:42:40 +010011765 Returns zero if {list} is not a |List|.
11766
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011767 Can also be used as a |method|: >
11768 mylist->uniq()
Christian Brabandt67672ef2023-04-24 21:09:54 +010011769<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011770 Return type: list<{type}>
11771
11772
Christian Brabandt67672ef2023-04-24 21:09:54 +010011773 *utf16idx()*
11774utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010011775 Same as |charidx()| but returns the UTF-16 code unit index of
11776 the byte at {idx} in {string} (after converting it to UTF-16).
Christian Brabandt67672ef2023-04-24 21:09:54 +010011777
11778 When {charidx} is present and TRUE, {idx} is used as the
11779 character index in the String {string} instead of as the byte
11780 index.
Yegappan Lakshmanan95707032023-06-14 13:10:15 +010011781 An {idx} in the middle of a UTF-8 sequence is rounded
11782 downwards to the beginning of that sequence.
Christian Brabandt67672ef2023-04-24 21:09:54 +010011783
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010011784 Returns -1 if the arguments are invalid or if there are less
11785 than {idx} bytes in {string}. If there are exactly {idx} bytes
11786 the length of the string in UTF-16 code units is returned.
11787
Christian Brabandt67672ef2023-04-24 21:09:54 +010011788 See |byteidx()| and |byteidxcomp()| for getting the byte index
11789 from the UTF-16 index and |charidx()| for getting the
11790 character index from the UTF-16 index.
11791 Refer to |string-offset-encoding| for more information.
11792 Examples: >
11793 echo utf16idx('a😊😊', 3) returns 2
11794 echo utf16idx('a😊😊', 7) returns 4
11795 echo utf16idx('a😊😊', 1, 0, 1) returns 2
11796 echo utf16idx('a😊😊', 2, 0, 1) returns 4
11797 echo utf16idx('aą́c', 6) returns 2
11798 echo utf16idx('aą́c', 6, 1) returns 4
11799 echo utf16idx('a😊😊', 9) returns -1
11800<
11801 Can also be used as a |method|: >
11802 GetName()->utf16idx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011803<
11804 Return type: |Number|
Christian Brabandt67672ef2023-04-24 21:09:54 +010011805
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011806
11807values({dict}) *values()*
11808 Return a |List| with all the values of {dict}. The |List| is
11809 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011810 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011811
11812 Can also be used as a |method|: >
11813 mydict->values()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011814<
11815 Return type: list<any>
11816
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011817
zeertzjq825cf812023-08-17 22:55:25 +020011818virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011819 The result is a Number, which is the screen column of the file
11820 position given with {expr}. That is, the last screen position
11821 occupied by the character at that position, when the screen
11822 would be of unlimited width. When there is a <Tab> at the
11823 position, the returned Number will be the column at the end of
11824 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
11825 set to 8, it returns 8. |conceal| is ignored.
11826 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010011827
zeertzjq02f3eba2024-06-12 20:45:24 +020011828 For the use of {expr} see |getpos()| and |col()|.
zeertzjqd353d272024-06-13 23:00:25 +080011829 When {expr} is "$", it means the end of the cursor line, so
11830 the result is the number of cells in the cursor line plus one.
LemonBoy0f7a3e12022-05-26 12:10:37 +010011831
11832 When 'virtualedit' is used {expr} can be [lnum, col, off],
11833 where "off" is the offset in screen columns from the start of
11834 the character. E.g., a position within a <Tab> or after the
11835 last character. When "off" is omitted zero is used. When
11836 Virtual editing is active in the current mode, a position
11837 beyond the end of the line can be returned. Also see
11838 |'virtualedit'|
11839
zeertzjq825cf812023-08-17 22:55:25 +020011840 If {list} is present and non-zero then virtcol() returns a
11841 List with the first and last screen position occupied by the
LemonBoy0f7a3e12022-05-26 12:10:37 +010011842 character.
11843
zeertzjq825cf812023-08-17 22:55:25 +020011844 With the optional {winid} argument the values are obtained for
11845 that window instead of the current window.
11846
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011847 Note that only marks in the current file can be used.
zeertzjq02f3eba2024-06-12 20:45:24 +020011848
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011849 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +010011850 " With text "foo^Lbar" and cursor on the "^L":
11851
11852 virtcol(".") " returns 5
11853 virtcol(".", 1) " returns [4, 5]
11854 virtcol("$") " returns 9
11855
11856 " With text " there", with 't at 'h':
11857
11858 virtcol("'t") " returns 6
zeertzjq02f3eba2024-06-12 20:45:24 +020011859<
11860 The first column is 1. 0 or [0, 0] is returned for an error.
11861
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011862 A more advanced example that echoes the maximum length of
11863 all lines: >
11864 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
11865
11866< Can also be used as a |method|: >
11867 GetPos()->virtcol()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011868<
11869 Return type: |Number|
11870
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011871
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010011872virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
11873 The result is a Number, which is the byte index of the
11874 character in window {winid} at buffer line {lnum} and virtual
11875 column {col}.
11876
zeertzjqb583eda2023-10-14 11:32:28 +020011877 If buffer line {lnum} is an empty line, 0 is returned.
11878
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010011879 If {col} is greater than the last virtual column in line
11880 {lnum}, then the byte index of the character at the last
11881 virtual column is returned.
11882
Yegappan Lakshmananb209b862023-08-15 23:01:44 +020011883 For a multi-byte character, the column number of the first
11884 byte in the character is returned.
11885
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010011886 The {winid} argument can be the window number or the
11887 |window-ID|. If this is zero, then the current window is used.
11888
11889 Returns -1 if the window {winid} doesn't exist or the buffer
11890 line {lnum} or virtual column {col} is invalid.
11891
11892 See also |screenpos()|, |virtcol()| and |col()|.
11893
11894 Can also be used as a |method|: >
11895 GetWinid()->virtcol2col(lnum, col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011896<
11897 Return type: |Number|
11898
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011899
11900visualmode([{expr}]) *visualmode()*
11901 The result is a String, which describes the last Visual mode
11902 used in the current buffer. Initially it returns an empty
11903 string, but once Visual mode has been used, it returns "v",
11904 "V", or "<CTRL-V>" (a single CTRL-V character) for
11905 character-wise, line-wise, or block-wise Visual mode
11906 respectively.
11907 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011908 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011909< This enters the same Visual mode as before. It is also useful
11910 in scripts if you wish to act differently depending on the
11911 Visual mode that was used.
11912 If Visual mode is active, use |mode()| to get the Visual mode
11913 (e.g., in a |:vmap|).
11914 If {expr} is supplied and it evaluates to a non-zero Number or
11915 a non-empty String, then the Visual mode will be cleared and
11916 the old value is returned. See |non-zero-arg|.
11917
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011918 Return type: |String|
11919
11920
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011921wildmenumode() *wildmenumode()*
11922 Returns |TRUE| when the wildmenu is active and |FALSE|
11923 otherwise. See 'wildmenu' and 'wildmode'.
11924 This can be used in mappings to handle the 'wildcharm' option
11925 gracefully. (Makes only sense with |mapmode-c| mappings).
11926
11927 For example to make <c-j> work like <down> in wildmode, use: >
11928 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
11929<
11930 (Note, this needs the 'wildcharm' option set appropriately).
11931
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011932 Return type: |Number|
11933
11934
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011935win_execute({id}, {command} [, {silent}]) *win_execute()*
11936 Like `execute()` but in the context of window {id}.
11937 The window will temporarily be made the current window,
11938 without triggering autocommands or changing directory. When
11939 executing {command} autocommands will be triggered, this may
Bram Moolenaarb7398fe2023-05-14 18:50:25 +010011940 have unexpected side effects. Use `:noautocmd` if needed.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011941 Example: >
11942 call win_execute(winid, 'set syntax=python')
11943< Doing the same with `setwinvar()` would not trigger
11944 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011945 *E994*
11946 Not all commands are allowed in popup windows.
11947 When window {id} does not exist then no error is given and
11948 an empty string is returned.
11949
11950 Can also be used as a |method|, the base is passed as the
11951 second argument: >
11952 GetCommand()->win_execute(winid)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011953<
11954 Return type: |String|
11955
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011956
11957win_findbuf({bufnr}) *win_findbuf()*
11958 Returns a |List| with |window-ID|s for windows that contain
11959 buffer {bufnr}. When there is none the list is empty.
11960
11961 Can also be used as a |method|: >
11962 GetBufnr()->win_findbuf()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011963<
11964 Return type: list<number> or list<any>
11965
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011966
11967win_getid([{win} [, {tab}]]) *win_getid()*
11968 Get the |window-ID| for the specified window.
11969 When {win} is missing use the current window.
11970 With {win} this is the window number. The top window has
11971 number 1.
11972 Without {tab} use the current tab, otherwise the tab with
11973 number {tab}. The first tab has number one.
11974 Return zero if the window cannot be found.
11975
11976 Can also be used as a |method|: >
11977 GetWinnr()->win_getid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011978<
11979 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011980
11981
11982win_gettype([{nr}]) *win_gettype()*
11983 Return the type of the window:
11984 "autocmd" autocommand window. Temporary window
11985 used to execute autocommands.
11986 "command" command-line window |cmdwin|
11987 (empty) normal window
11988 "loclist" |location-list-window|
11989 "popup" popup window |popup|
11990 "preview" preview window |preview-window|
11991 "quickfix" |quickfix-window|
11992 "unknown" window {nr} not found
11993
11994 When {nr} is omitted return the type of the current window.
11995 When {nr} is given return the type of this window by number or
11996 |window-ID|.
11997
11998 Also see the 'buftype' option. When running a terminal in a
11999 popup window then 'buftype' is "terminal" and win_gettype()
12000 returns "popup".
12001
12002 Can also be used as a |method|: >
12003 GetWinid()->win_gettype()
12004<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012005 Return type: |String|
12006
12007
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012008win_gotoid({expr}) *win_gotoid()*
12009 Go to window with ID {expr}. This may also change the current
12010 tabpage.
12011 Return TRUE if successful, FALSE if the window cannot be found.
12012
12013 Can also be used as a |method|: >
12014 GetWinid()->win_gotoid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012015<
12016 Return type: |Number|
12017
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012018
12019win_id2tabwin({expr}) *win_id2tabwin()*
12020 Return a list with the tab number and window number of window
12021 with ID {expr}: [tabnr, winnr].
12022 Return [0, 0] if the window cannot be found.
12023
12024 Can also be used as a |method|: >
12025 GetWinid()->win_id2tabwin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012026<
12027 Return type: list<number>
12028
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012029
12030win_id2win({expr}) *win_id2win()*
12031 Return the window number of window with ID {expr}.
12032 Return 0 if the window cannot be found in the current tabpage.
12033
12034 Can also be used as a |method|: >
12035 GetWinid()->win_id2win()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012036<
12037 Return type: |Number|
12038
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012039
Daniel Steinbergee630312022-01-10 13:36:34 +000012040win_move_separator({nr}, {offset}) *win_move_separator()*
12041 Move window {nr}'s vertical separator (i.e., the right border)
12042 by {offset} columns, as if being dragged by the mouse. {nr}
12043 can be a window number or |window-ID|. A positive {offset}
12044 moves right and a negative {offset} moves left. Moving a
12045 window's vertical separator will change the width of the
12046 window and the width of other windows adjacent to the vertical
12047 separator. The magnitude of movement may be smaller than
12048 specified (e.g., as a consequence of maintaining
12049 'winminwidth'). Returns TRUE if the window can be found and
12050 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010012051 This will fail for the rightmost window and a full-width
12052 window, since it has no separator on the right.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000012053 Only works for the current tab page. *E1308*
Daniel Steinbergee630312022-01-10 13:36:34 +000012054
12055 Can also be used as a |method|: >
12056 GetWinnr()->win_move_separator(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012057<
12058 Return type: |Number|
12059
Daniel Steinbergee630312022-01-10 13:36:34 +000012060
12061win_move_statusline({nr}, {offset}) *win_move_statusline()*
12062 Move window {nr}'s status line (i.e., the bottom border) by
12063 {offset} rows, as if being dragged by the mouse. {nr} can be a
12064 window number or |window-ID|. A positive {offset} moves down
12065 and a negative {offset} moves up. Moving a window's status
12066 line will change the height of the window and the height of
12067 other windows adjacent to the status line. The magnitude of
12068 movement may be smaller than specified (e.g., as a consequence
12069 of maintaining 'winminheight'). Returns TRUE if the window can
12070 be found and FALSE otherwise.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000012071 Only works for the current tab page.
Daniel Steinbergee630312022-01-10 13:36:34 +000012072
12073 Can also be used as a |method|: >
12074 GetWinnr()->win_move_statusline(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012075<
12076 Return type: |Number|
12077
Daniel Steinbergee630312022-01-10 13:36:34 +000012078
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012079win_screenpos({nr}) *win_screenpos()*
12080 Return the screen position of window {nr} as a list with two
12081 numbers: [row, col]. The first window always has position
12082 [1, 1], unless there is a tabline, then it is [2, 1].
12083 {nr} can be the window number or the |window-ID|. Use zero
12084 for the current window.
Sean Dewar5866bc32024-03-13 20:17:24 +010012085 Returns [0, 0] if the window cannot be found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012086
12087 Can also be used as a |method|: >
12088 GetWinid()->win_screenpos()
12089<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012090 Return type: list<number>
12091
12092
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012093win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
Sean Dewar96cc4ae2024-02-20 21:52:31 +010012094 Temporarily switch to window {target}, then move window {nr}
12095 to a new split adjacent to {target}.
12096 Unlike commands such as |:split|, no new windows are created
12097 (the |window-ID| of window {nr} is unchanged after the move).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012098
12099 Both {nr} and {target} can be window numbers or |window-ID|s.
12100 Both must be in the current tab page.
12101
12102 Returns zero for success, non-zero for failure.
12103
12104 {options} is a |Dictionary| with the following optional entries:
12105 "vertical" When TRUE, the split is created vertically,
12106 like with |:vsplit|.
12107 "rightbelow" When TRUE, the split is made below or to the
12108 right (if vertical). When FALSE, it is done
12109 above or to the left (if vertical). When not
12110 present, the values of 'splitbelow' and
12111 'splitright' are used.
12112
12113 Can also be used as a |method|: >
12114 GetWinid()->win_splitmove(target)
12115<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012116 Return type: |Number|
12117
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012118
12119 *winbufnr()*
12120winbufnr({nr}) The result is a Number, which is the number of the buffer
12121 associated with window {nr}. {nr} can be the window number or
12122 the |window-ID|.
12123 When {nr} is zero, the number of the buffer in the current
12124 window is returned.
12125 When window {nr} doesn't exist, -1 is returned.
12126 Example: >
12127 :echo "The file in the current window is " . bufname(winbufnr(0))
12128<
12129 Can also be used as a |method|: >
12130 FindWindow()->winbufnr()->bufname()
12131<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012132 Return type: |Number|
12133
12134
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012135 *wincol()*
12136wincol() The result is a Number, which is the virtual column of the
12137 cursor in the window. This is counting screen cells from the
12138 left side of the window. The leftmost column is one.
12139
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012140 Return type: |Number|
12141
12142
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012143 *windowsversion()*
12144windowsversion()
12145 The result is a String. For MS-Windows it indicates the OS
12146 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
12147 Windows XP is "5.1". For non-MS-Windows systems the result is
12148 an empty string.
12149
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012150 Return type: |String|
12151
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012152winheight({nr}) *winheight()*
12153 The result is a Number, which is the height of window {nr}.
12154 {nr} can be the window number or the |window-ID|.
12155 When {nr} is zero, the height of the current window is
12156 returned. When window {nr} doesn't exist, -1 is returned.
12157 An existing window always has a height of zero or more.
12158 This excludes any window toolbar line.
12159 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012160 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012161
12162< Can also be used as a |method|: >
12163 GetWinid()->winheight()
12164<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012165 Return type: |Number|
12166
12167
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012168winlayout([{tabnr}]) *winlayout()*
12169 The result is a nested List containing the layout of windows
12170 in a tabpage.
12171
12172 Without {tabnr} use the current tabpage, otherwise the tabpage
12173 with number {tabnr}. If the tabpage {tabnr} is not found,
12174 returns an empty list.
12175
12176 For a leaf window, it returns:
12177 ['leaf', {winid}]
12178 For horizontally split windows, which form a column, it
12179 returns:
12180 ['col', [{nested list of windows}]]
12181 For vertically split windows, which form a row, it returns:
12182 ['row', [{nested list of windows}]]
12183
12184 Example: >
12185 " Only one window in the tab page
12186 :echo winlayout()
12187 ['leaf', 1000]
12188 " Two horizontally split windows
12189 :echo winlayout()
12190 ['col', [['leaf', 1000], ['leaf', 1001]]]
12191 " The second tab page, with three horizontally split
12192 " windows, with two vertically split windows in the
12193 " middle window
12194 :echo winlayout(2)
12195 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
12196 ['leaf', 1001]]], ['leaf', 1000]]]
12197<
12198 Can also be used as a |method|: >
12199 GetTabnr()->winlayout()
12200<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012201 Return type: list<any>
12202
12203
12204winline() *winline()*
12205 The result is a Number, which is the screen line of the cursor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012206 in the window. This is counting screen lines from the top of
12207 the window. The first line is one.
12208 If the cursor was moved the view on the file will be updated
12209 first, this may cause a scroll.
12210
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012211 Return type: |Number|
12212
12213
12214winnr([{arg}]) *winnr()*
12215 The result is a Number, which is the number of the current
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012216 window. The top window has number 1.
12217 Returns zero for a popup window.
12218
12219 The optional argument {arg} supports the following values:
12220 $ the number of the last window (the window
12221 count).
12222 # the number of the last accessed window (where
12223 |CTRL-W_p| goes to). If there is no previous
12224 window or it is in another tab page 0 is
Sean Deward64801e2024-03-12 20:46:12 +010012225 returned. May refer to the current window in
12226 some cases (e.g. when evaluating 'statusline'
12227 expressions).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012228 {N}j the number of the Nth window below the
12229 current window (where |CTRL-W_j| goes to).
12230 {N}k the number of the Nth window above the current
12231 window (where |CTRL-W_k| goes to).
12232 {N}h the number of the Nth window left of the
12233 current window (where |CTRL-W_h| goes to).
12234 {N}l the number of the Nth window right of the
12235 current window (where |CTRL-W_l| goes to).
12236 The number can be used with |CTRL-W_w| and ":wincmd w"
12237 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010012238 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012239 Also see |tabpagewinnr()| and |win_getid()|.
12240 Examples: >
12241 let window_count = winnr('$')
12242 let prev_window = winnr('#')
12243 let wnum = winnr('3k')
12244
12245< Can also be used as a |method|: >
12246 GetWinval()->winnr()
12247<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012248 Return type: |Number|
12249
12250
12251winrestcmd() *winrestcmd()*
12252 Returns a sequence of |:resize| commands that should restore
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012253 the current window sizes. Only works properly when no windows
12254 are opened or closed and the current window and tab page is
12255 unchanged.
12256 Example: >
12257 :let cmd = winrestcmd()
12258 :call MessWithWindowSizes()
12259 :exe cmd
12260<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012261 Return type: |String|
12262
12263
12264winrestview({dict}) *winrestview()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012265 Uses the |Dictionary| returned by |winsaveview()| to restore
12266 the view of the current window.
12267 Note: The {dict} does not have to contain all values, that are
12268 returned by |winsaveview()|. If values are missing, those
12269 settings won't be restored. So you can use: >
12270 :call winrestview({'curswant': 4})
12271<
12272 This will only set the curswant value (the column the cursor
12273 wants to move on vertical movements) of the cursor to column 5
12274 (yes, that is 5), while all other settings will remain the
12275 same. This is useful, if you set the cursor position manually.
12276
12277 If you have changed the values the result is unpredictable.
12278 If the window size changed the result won't be the same.
12279
12280 Can also be used as a |method|: >
12281 GetView()->winrestview()
12282<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012283 Return type: |Number|
12284
12285
12286winsaveview() *winsaveview()*
12287 Returns a |Dictionary| that contains information to restore
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012288 the view of the current window. Use |winrestview()| to
12289 restore the view.
12290 This is useful if you have a mapping that jumps around in the
12291 buffer and you want to go back to the original view.
12292 This does not save fold information. Use the 'foldenable'
12293 option to temporarily switch off folding, so that folds are
12294 not opened when moving around. This may have side effects.
12295 The return value includes:
12296 lnum cursor line number
12297 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000012298 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012299 returns)
12300 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000012301 curswant column for vertical movement (Note:
12302 the first column is zero, as opposed
12303 to what |getcurpos()| returns). After
12304 |$| command it will be a very large
12305 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012306 topline first line in the window
12307 topfill filler lines, only in diff mode
12308 leftcol first column displayed; only used when
12309 'wrap' is off
12310 skipcol columns skipped
12311 Note that no option values are saved.
12312
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012313 Return type: dict<number>
12314
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012315
12316winwidth({nr}) *winwidth()*
12317 The result is a Number, which is the width of window {nr}.
12318 {nr} can be the window number or the |window-ID|.
12319 When {nr} is zero, the width of the current window is
12320 returned. When window {nr} doesn't exist, -1 is returned.
12321 An existing window always has a width of zero or more.
12322 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012323 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012324 :if winwidth(0) <= 50
12325 : 50 wincmd |
12326 :endif
12327< For getting the terminal or screen size, see the 'columns'
12328 option.
12329
12330 Can also be used as a |method|: >
12331 GetWinid()->winwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012332<
12333 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012334
12335
12336wordcount() *wordcount()*
12337 The result is a dictionary of byte/chars/word statistics for
12338 the current buffer. This is the same info as provided by
12339 |g_CTRL-G|
12340 The return value includes:
12341 bytes Number of bytes in the buffer
12342 chars Number of chars in the buffer
12343 words Number of words in the buffer
12344 cursor_bytes Number of bytes before cursor position
12345 (not in Visual mode)
12346 cursor_chars Number of chars before cursor position
12347 (not in Visual mode)
12348 cursor_words Number of words before cursor position
12349 (not in Visual mode)
12350 visual_bytes Number of bytes visually selected
12351 (only in Visual mode)
12352 visual_chars Number of chars visually selected
12353 (only in Visual mode)
12354 visual_words Number of words visually selected
12355 (only in Visual mode)
12356
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012357 Return type: dict<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012358
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012359
12360writefile({object}, {fname} [, {flags}]) *writefile()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012361 When {object} is a |List| write it to file {fname}. Each list
12362 item is separated with a NL. Each list item must be a String
12363 or Number.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012364 All NL characters are replaced with a NUL character.
12365 Inserting CR characters needs to be done before passing {list}
12366 to writefile().
Bram Moolenaar806a2732022-09-04 15:40:36 +010012367
12368 When {object} is a |Blob| write the bytes to file {fname}
12369 unmodified, also when binary mode is not specified.
12370
12371 {flags} must be a String. These characters are recognized:
12372
12373 'b' Binary mode is used: There will not be a NL after the
12374 last list item. An empty item at the end does cause the
12375 last line in the file to end in a NL.
12376
12377 'a' Append mode is used, lines are appended to the file: >
12378 :call writefile(["foo"], "event.log", "a")
12379 :call writefile(["bar"], "event.log", "a")
12380<
12381 'D' Delete the file when the current function ends. This
12382 works like: >
Bram Moolenaar938ae282023-02-20 20:44:55 +000012383 :defer delete({fname})
Bram Moolenaar806a2732022-09-04 15:40:36 +010012384< Fails when not in a function. Also see |:defer|.
12385
12386 's' fsync() is called after writing the file. This flushes
12387 the file to disk, if possible. This takes more time but
12388 avoids losing the file if the system crashes.
12389
12390 'S' fsync() is not called, even when 'fsync' is set.
12391
12392 When {flags} does not contain "S" or "s" then fsync() is
12393 called if the 'fsync' option is set.
12394
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012395 An existing file is overwritten, if possible.
Bram Moolenaar806a2732022-09-04 15:40:36 +010012396
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012397 When the write fails -1 is returned, otherwise 0. There is an
12398 error message if the file can't be created or when writing
12399 fails.
Bram Moolenaar806a2732022-09-04 15:40:36 +010012400
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012401 Also see |readfile()|.
12402 To copy a file byte for byte: >
12403 :let fl = readfile("foo", "b")
12404 :call writefile(fl, "foocopy", "b")
12405
12406< Can also be used as a |method|: >
12407 GetText()->writefile("thefile")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012408<
12409 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012410
12411
12412xor({expr}, {expr}) *xor()*
12413 Bitwise XOR on the two arguments. The arguments are converted
12414 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012415 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012416 Example: >
12417 :let bits = xor(bits, 0x80)
12418<
12419 Can also be used as a |method|: >
12420 :let bits = bits->xor(0x80)
12421<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012422 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012423
12424==============================================================================
124253. Feature list *feature-list*
12426
12427There are three types of features:
124281. Features that are only supported when they have been enabled when Vim
12429 was compiled |+feature-list|. Example: >
12430 :if has("cindent")
12431< *gui_running*
124322. Features that are only supported when certain conditions have been met.
12433 Example: >
12434 :if has("gui_running")
12435< *has-patch*
124363. Beyond a certain version or at a certain version and including a specific
12437 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
12438 later, or it is version 7.4 and patch 248 was included. Example: >
12439 :if has("patch-7.4.248")
12440< Note that it's possible for patch 248 to be omitted even though 249 is
12441 included. Only happens when cherry-picking patches.
12442 Note that this form only works for patch 7.4.237 and later, before that
12443 you need to check for the patch and the v:version. Example (checking
12444 version 6.2.148 or later): >
12445 :if v:version > 602 || (v:version == 602 && has("patch148"))
12446
12447Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
12448use: `if exists('+shellslash')`
12449
12450
12451acl Compiled with |ACL| support.
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010012452all_builtin_terms Compiled with all builtin terminals enabled. (always
12453 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012454amiga Amiga version of Vim.
12455arabic Compiled with Arabic support |Arabic|.
12456arp Compiled with ARP support (Amiga).
12457autocmd Compiled with autocommand support. (always true)
12458autochdir Compiled with support for 'autochdir'
12459autoservername Automatically enable |clientserver|
12460balloon_eval Compiled with |balloon-eval| support.
12461balloon_multiline GUI supports multiline balloons.
12462beos BeOS version of Vim.
12463browse Compiled with |:browse| support, and browse() will
12464 work.
12465browsefilter Compiled with support for |browsefilter|.
12466bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010012467builtin_terms Compiled with some builtin terminals. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012468byte_offset Compiled with support for 'o' in 'statusline'
12469channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012470cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012471clientserver Compiled with remote invocation support |clientserver|.
12472clipboard Compiled with 'clipboard' support.
12473clipboard_working Compiled with 'clipboard' support and it can be used.
12474cmdline_compl Compiled with |cmdline-completion| support.
12475cmdline_hist Compiled with |cmdline-history| support.
12476cmdline_info Compiled with 'showcmd' and 'ruler' support.
12477comments Compiled with |'comments'| support.
12478compatible Compiled to be very Vi compatible.
12479conpty Platform where |ConPTY| can be used.
12480cryptv Compiled with encryption support |encryption|.
12481cscope Compiled with |cscope| support.
12482cursorbind Compiled with |'cursorbind'| (always true)
12483debug Compiled with "DEBUG" defined.
12484dialog_con Compiled with console dialog support.
glepnirdf461152024-04-04 22:23:29 +020012485dialog_con_gui Compiled with console and GUI dialog support.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012486dialog_gui Compiled with GUI dialog support.
12487diff Compiled with |vimdiff| and 'diff' support.
12488digraphs Compiled with support for digraphs.
12489directx Compiled with support for DirectX and 'renderoptions'.
12490dnd Compiled with support for the "~ register |quote_~|.
12491drop_file Compiled with |drop_file| support.
12492ebcdic Compiled on a machine with ebcdic character set.
12493emacs_tags Compiled with support for Emacs tags.
12494eval Compiled with expression evaluation support. Always
12495 true, of course!
12496ex_extra |+ex_extra| (always true)
12497extra_search Compiled with support for |'incsearch'| and
12498 |'hlsearch'|
12499farsi Support for Farsi was removed |farsi|.
Bram Moolenaarf80f40a2022-08-25 16:02:23 +010012500file_in_path Compiled with support for |gf| and |<cfile>| (always
12501 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012502filterpipe When 'shelltemp' is off pipes are used for shell
12503 read/write/filter commands
12504find_in_path Compiled with support for include file searches
12505 |+find_in_path|.
12506float Compiled with support for |Float|.
12507fname_case Case in file names matters (for Amiga and MS-Windows
12508 this is not present).
12509folding Compiled with |folding| support.
12510footer Compiled with GUI footer support. |gui-footer|
12511fork Compiled to use fork()/exec() instead of system().
12512gettext Compiled with message translation |multi-lang|
12513gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010012514gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012515gui_gnome Compiled with Gnome support (gui_gtk is also defined).
12516gui_gtk Compiled with GTK+ GUI (any version).
12517gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
12518gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
12519gui_haiku Compiled with Haiku GUI.
12520gui_mac Compiled with Macintosh GUI.
12521gui_motif Compiled with Motif GUI.
12522gui_photon Compiled with Photon GUI.
12523gui_running Vim is running in the GUI, or it will start soon.
12524gui_win32 Compiled with MS-Windows Win32 GUI.
12525gui_win32s idem, and Win32s system being used (Windows 3.1)
12526haiku Haiku version of Vim.
12527hangul_input Compiled with Hangul input support. |hangul|
12528hpux HP-UX version of Vim.
12529iconv Can use iconv() for conversion.
12530insert_expand Compiled with support for CTRL-X expansion commands in
12531 Insert mode. (always true)
12532job Compiled with support for |channel| and |job|
12533ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012534jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012535keymap Compiled with 'keymap' support.
12536lambda Compiled with |lambda| support.
12537langmap Compiled with 'langmap' support.
12538libcall Compiled with |libcall()| support.
12539linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
12540 'breakindent' support.
12541linux Linux version of Vim.
12542lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012543 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012544listcmds Compiled with commands for the buffer list |:files|
12545 and the argument list |arglist|.
12546localmap Compiled with local mappings and abbr. |:map-local|
12547lua Compiled with Lua interface |Lua|.
12548mac Any Macintosh version of Vim cf. osx
12549macunix Synonym for osxdarwin
12550menu Compiled with support for |:menu|.
12551mksession Compiled with support for |:mksession|.
12552modify_fname Compiled with file name modifiers. |filename-modifiers|
12553 (always true)
12554mouse Compiled with support for mouse.
12555mouse_dec Compiled with support for Dec terminal mouse.
12556mouse_gpm Compiled with support for gpm (Linux console mouse)
12557mouse_gpm_enabled GPM mouse is working
12558mouse_netterm Compiled with support for netterm mouse.
12559mouse_pterm Compiled with support for qnx pterm mouse.
12560mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
12561mouse_sgr Compiled with support for sgr mouse.
12562mouse_urxvt Compiled with support for urxvt mouse.
12563mouse_xterm Compiled with support for xterm mouse.
12564mouseshape Compiled with support for 'mouseshape'.
12565multi_byte Compiled with support for 'encoding' (always true)
12566multi_byte_encoding 'encoding' is set to a multibyte encoding.
12567multi_byte_ime Compiled with support for IME input method.
12568multi_lang Compiled with support for multiple languages.
12569mzscheme Compiled with MzScheme interface |mzscheme|.
12570nanotime Compiled with sub-second time stamp checks.
12571netbeans_enabled Compiled with support for |netbeans| and connected.
12572netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012573num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012574ole Compiled with OLE automation support for Win32.
12575osx Compiled for macOS cf. mac
12576osxdarwin Compiled for macOS, with |mac-darwin-feature|
12577packages Compiled with |packages| support.
12578path_extra Compiled with up/downwards search in 'path' and 'tags'
12579perl Compiled with Perl interface.
12580persistent_undo Compiled with support for persistent undo history.
12581postscript Compiled with PostScript file printing.
12582printer Compiled with |:hardcopy| support.
12583profile Compiled with |:profile| support.
Bram Moolenaar71badf92023-04-22 22:40:14 +010012584prof_nsec Profile results are in nanoseconds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012585python Python 2.x interface available. |has-python|
12586python_compiled Compiled with Python 2.x interface. |has-python|
12587python_dynamic Python 2.x interface is dynamically loaded. |has-python|
12588python3 Python 3.x interface available. |has-python|
12589python3_compiled Compiled with Python 3.x interface. |has-python|
12590python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Yee Cheng Chinc13b3d12023-08-20 21:18:38 +020012591python3_stable Python 3.x interface is using Python Stable ABI. |has-python|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012592pythonx Python 2.x and/or 3.x interface available. |python_x|
12593qnx QNX version of Vim.
12594quickfix Compiled with |quickfix| support.
12595reltime Compiled with |reltime()| support.
12596rightleft Compiled with 'rightleft' support.
12597ruby Compiled with Ruby interface |ruby|.
12598scrollbind Compiled with 'scrollbind' support. (always true)
12599showcmd Compiled with 'showcmd' support.
12600signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012601smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012602sodium Compiled with libsodium for better crypt support
12603sound Compiled with sound support, e.g. `sound_playevent()`
12604spell Compiled with spell checking support |spell|.
12605startuptime Compiled with |--startuptime| support.
12606statusline Compiled with support for 'statusline', 'rulerformat'
12607 and special formats of 'titlestring' and 'iconstring'.
12608sun SunOS version of Vim.
12609sun_workshop Support for Sun |workshop| has been removed.
12610syntax Compiled with syntax highlighting support |syntax|.
12611syntax_items There are active syntax highlighting items for the
12612 current buffer.
12613system Compiled to use system() instead of fork()/exec().
12614tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012615 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012616tag_old_static Support for old static tags was removed, see
12617 |tag-old-static|.
12618tcl Compiled with Tcl interface.
12619termguicolors Compiled with true color in terminal support.
12620terminal Compiled with |terminal| support.
12621terminfo Compiled with terminfo instead of termcap.
12622termresponse Compiled with support for |t_RV| and |v:termresponse|.
12623textobjects Compiled with support for |text-objects|.
12624textprop Compiled with support for |text-properties|.
12625tgetent Compiled with tgetent support, able to use a termcap
12626 or terminfo file.
12627timers Compiled with |timer_start()| support.
12628title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012629 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012630toolbar Compiled with support for |gui-toolbar|.
12631ttyin input is a terminal (tty)
12632ttyout output is a terminal (tty)
12633unix Unix version of Vim. *+unix*
12634unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
12635user_commands User-defined commands. (always true)
12636vartabs Compiled with variable tabstop support |'vartabstop'|.
12637vcon Win32: Virtual console support is working, can use
12638 'termguicolors'. Also see |+vtp|.
12639vertsplit Compiled with vertically split windows |:vsplit|.
12640 (always true)
12641vim_starting True while initial source'ing takes place. |startup|
12642 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000012643vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012644viminfo Compiled with viminfo support.
12645vimscript-1 Compiled Vim script version 1 support
12646vimscript-2 Compiled Vim script version 2 support
12647vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010012648vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012649virtualedit Compiled with 'virtualedit' option. (always true)
12650visual Compiled with Visual mode. (always true)
12651visualextra Compiled with extra Visual mode commands. (always
12652 true) |blockwise-operators|.
12653vms VMS version of Vim.
12654vreplace Compiled with |gR| and |gr| commands. (always true)
12655vtp Compiled for vcon support |+vtp| (check vcon to find
12656 out if it works in the current console).
12657wildignore Compiled with 'wildignore' option.
12658wildmenu Compiled with 'wildmenu' option.
12659win16 old version for MS-Windows 3.1 (always false)
12660win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
12661 64 bits)
12662win32unix Win32 version of Vim, using Unix files (Cygwin)
12663win64 Win64 version of Vim (MS-Windows 64 bit).
12664win95 Win32 version for MS-Windows 95/98/ME (always false)
12665winaltkeys Compiled with 'winaltkeys' option.
12666windows Compiled with support for more than one window.
12667 (always true)
12668writebackup Compiled with 'writebackup' default on.
Christian Brabandte085dfd2023-09-30 12:49:18 +020012669xattr Compiled with extended attributes support |xattr|
12670 (currently only supported on Linux).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012671xfontset Compiled with X fontset support |xfontset|.
12672xim Compiled with X input method support |xim|.
12673xpm Compiled with pixmap support.
12674xpm_w32 Compiled with pixmap support for Win32. (Only for
12675 backward compatibility. Use "xpm" instead.)
12676xsmp Compiled with X session management support.
12677xsmp_interact Compiled with interactive X session management support.
12678xterm_clipboard Compiled with support for xterm clipboard.
12679xterm_save Compiled with support for saving and restoring the
12680 xterm screen.
12681x11 Compiled with X11 support.
12682
12683
12684==============================================================================
126854. Matching a pattern in a String *string-match*
12686
12687This is common between several functions. A regexp pattern as explained at
12688|pattern| is normally used to find a match in the buffer lines. When a
12689pattern is used to find a match in a String, almost everything works in the
12690same way. The difference is that a String is handled like it is one line.
12691When it contains a "\n" character, this is not seen as a line break for the
12692pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
12693>
12694 :let a = "aaaa\nxxxx"
12695 :echo matchstr(a, "..\n..")
12696 aa
12697 xx
12698 :echo matchstr(a, "a.x")
12699 a
12700 x
12701
12702Don't forget that "^" will only match at the first character of the String and
12703"$" at the last character of the string. They don't match after or before a
12704"\n".
12705
12706 vim:tw=78:ts=8:noet:ft=help:norl: