blob: 5001205ea648e4475b1b63b36873cfc71e85c335 [file] [log] [blame]
lilydjwg6e0a18f2024-01-29 20:54:28 +01001*builtin.txt* For Vim version 9.1. Last change: 2024 Jan 29
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Builtin functions *builtin-functions*
8
Bram Moolenaarf269eab2022-10-03 18:04:35 +01009Note: Expression evaluation can be disabled at compile time, the builtin
10functions are not available then. See |+eval| and |no-eval-feature|.
11
12For functions grouped by what they are used for see |function-list|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013
141. Overview |builtin-function-list|
152. Details |builtin-function-details|
163. Feature list |feature-list|
174. Matching a pattern in a String |string-match|
18
19==============================================================================
201. Overview *builtin-function-list*
21
22Use CTRL-] on the function name to jump to the full explanation.
23
24USAGE RESULT DESCRIPTION ~
25
26abs({expr}) Float or Number absolute value of {expr}
27acos({expr}) Float arc cosine of {expr}
28add({object}, {item}) List/Blob append {item} to {object}
29and({expr}, {expr}) Number bitwise AND
30append({lnum}, {text}) Number append {text} below line {lnum}
31appendbufline({expr}, {lnum}, {text})
32 Number append {text} below line {lnum}
33 in buffer {expr}
34argc([{winid}]) Number number of files in the argument list
35argidx() Number current index in the argument list
36arglistid([{winnr} [, {tabnr}]]) Number argument list id
37argv({nr} [, {winid}]) String {nr} entry of the argument list
38argv([-1, {winid}]) List the argument list
39asin({expr}) Float arc sine of {expr}
40assert_beeps({cmd}) Number assert {cmd} causes a beep
41assert_equal({exp}, {act} [, {msg}])
42 Number assert {exp} is equal to {act}
43assert_equalfile({fname-one}, {fname-two} [, {msg}])
44 Number assert file contents are equal
45assert_exception({error} [, {msg}])
46 Number assert {error} is in v:exception
47assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])
48 Number assert {cmd} fails
49assert_false({actual} [, {msg}])
50 Number assert {actual} is false
51assert_inrange({lower}, {upper}, {actual} [, {msg}])
52 Number assert {actual} is inside the range
53assert_match({pat}, {text} [, {msg}])
54 Number assert {pat} matches {text}
55assert_nobeep({cmd}) Number assert {cmd} does not cause a beep
56assert_notequal({exp}, {act} [, {msg}])
57 Number assert {exp} is not equal {act}
58assert_notmatch({pat}, {text} [, {msg}])
59 Number assert {pat} not matches {text}
60assert_report({msg}) Number report a test failure
61assert_true({actual} [, {msg}]) Number assert {actual} is true
62atan({expr}) Float arc tangent of {expr}
63atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +010064autocmd_add({acmds}) Bool add a list of autocmds and groups
65autocmd_delete({acmds}) Bool delete a list of autocmds and groups
66autocmd_get([{opts}]) List return a list of autocmds
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000067balloon_gettext() String current text in the balloon
68balloon_show({expr}) none show {expr} inside the balloon
69balloon_split({msg}) List split {msg} as used for a balloon
70blob2list({blob}) List convert {blob} into a list of numbers
71browse({save}, {title}, {initdir}, {default})
72 String put up a file requester
73browsedir({title}, {initdir}) String put up a directory requester
74bufadd({name}) Number add a buffer to the buffer list
75bufexists({buf}) Number |TRUE| if buffer {buf} exists
76buflisted({buf}) Number |TRUE| if buffer {buf} is listed
77bufload({buf}) Number load buffer {buf} if not loaded yet
78bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
79bufname([{buf}]) String Name of the buffer {buf}
80bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
81bufwinid({buf}) Number window ID of buffer {buf}
82bufwinnr({buf}) Number window number of buffer {buf}
83byte2line({byte}) Number line number at byte count {byte}
Christian Brabandt67672ef2023-04-24 21:09:54 +010084byteidx({expr}, {nr} [, {utf16}])
85 Number byte index of {nr}'th char in {expr}
86byteidxcomp({expr}, {nr} [, {utf16}])
87 Number byte index of {nr}'th char in {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000088call({func}, {arglist} [, {dict}])
89 any call {func} with arguments {arglist}
90ceil({expr}) Float round {expr} up
91ch_canread({handle}) Number check if there is something to read
92ch_close({handle}) none close {handle}
93ch_close_in({handle}) none close in part of {handle}
94ch_evalexpr({handle}, {expr} [, {options}])
95 any evaluate {expr} on JSON {handle}
96ch_evalraw({handle}, {string} [, {options}])
97 any evaluate {string} on raw {handle}
98ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
99ch_getjob({channel}) Job get the Job of {channel}
100ch_info({handle}) String info about channel {handle}
101ch_log({msg} [, {handle}]) none write {msg} in the channel log file
102ch_logfile({fname} [, {mode}]) none start logging channel activity
103ch_open({address} [, {options}])
104 Channel open a channel to {address}
105ch_read({handle} [, {options}]) String read from {handle}
106ch_readblob({handle} [, {options}])
107 Blob read Blob from {handle}
108ch_readraw({handle} [, {options}])
109 String read raw from {handle}
110ch_sendexpr({handle}, {expr} [, {options}])
111 any send {expr} over JSON {handle}
112ch_sendraw({handle}, {expr} [, {options}])
113 any send {expr} over raw {handle}
114ch_setoptions({handle}, {options})
115 none set options for {handle}
116ch_status({handle} [, {options}])
117 String status of channel {handle}
118changenr() Number current change number
119char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
120charclass({string}) Number character class of {string}
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000121charcol({expr} [, {winid}]) Number column number of cursor or mark
Christian Brabandt67672ef2023-04-24 21:09:54 +0100122charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000123 Number char index of byte {idx} in {string}
124chdir({dir}) String change current working directory
125cindent({lnum}) Number C indent for line {lnum}
126clearmatches([{win}]) none clear all matches
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000127col({expr} [, {winid}]) Number column byte index of cursor or mark
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000128complete({startcol}, {matches}) none set Insert mode completion
129complete_add({expr}) Number add completion match
130complete_check() Number check for key typed during completion
131complete_info([{what}]) Dict get current completion information
132confirm({msg} [, {choices} [, {default} [, {type}]]])
133 Number number of choice picked by user
134copy({expr}) any make a shallow copy of {expr}
135cos({expr}) Float cosine of {expr}
136cosh({expr}) Float hyperbolic cosine of {expr}
137count({comp}, {expr} [, {ic} [, {start}]])
138 Number count how many {expr} are in {comp}
139cscope_connection([{num}, {dbpath} [, {prepend}]])
140 Number checks existence of cscope connection
141cursor({lnum}, {col} [, {off}])
142 Number move cursor to {lnum}, {col}, {off}
143cursor({list}) Number move cursor to position in {list}
144debugbreak({pid}) Number interrupt process being debugged
145deepcopy({expr} [, {noref}]) any make a full copy of {expr}
146delete({fname} [, {flags}]) Number delete the file or directory {fname}
147deletebufline({buf}, {first} [, {last}])
148 Number delete lines from buffer {buf}
149did_filetype() Number |TRUE| if FileType autocmd event used
150diff_filler({lnum}) Number diff filler lines about {lnum}
151diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
152digraph_get({chars}) String get the |digraph| of {chars}
153digraph_getlist([{listall}]) List get all |digraph|s
154digraph_set({chars}, {digraph}) Boolean register |digraph|
155digraph_setlist({digraphlist}) Boolean register multiple |digraph|s
156echoraw({expr}) none output {expr} as-is
157empty({expr}) Number |TRUE| if {expr} is empty
158environ() Dict return environment variables
Sean Dewarb0efa492023-07-08 10:35:19 +0100159err_teapot([{expr}]) none give E418, or E503 if {expr} is |TRUE|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000160escape({string}, {chars}) String escape {chars} in {string} with '\'
161eval({string}) any evaluate {string} into its value
162eventhandler() Number |TRUE| if inside an event handler
163executable({expr}) Number 1 if executable {expr} exists
164execute({command}) String execute {command} and get the output
165exepath({expr}) String full path of the command {expr}
166exists({expr}) Number |TRUE| if {expr} exists
167exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
168exp({expr}) Float exponential of {expr}
169expand({expr} [, {nosuf} [, {list}]])
170 any expand special keywords in {expr}
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +0100171expandcmd({string} [, {options}])
172 String expand {string} like with `:edit`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000173extend({expr1}, {expr2} [, {expr3}])
174 List/Dict insert items of {expr2} into {expr1}
175extendnew({expr1}, {expr2} [, {expr3}])
176 List/Dict like |extend()| but creates a new
177 List or Dictionary
178feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
179filereadable({file}) Number |TRUE| if {file} is a readable file
180filewritable({file}) Number |TRUE| if {file} is a writable file
181filter({expr1}, {expr2}) List/Dict/Blob/String
182 remove items from {expr1} where
183 {expr2} is 0
184finddir({name} [, {path} [, {count}]])
185 String find directory {name} in {path}
186findfile({name} [, {path} [, {count}]])
187 String find file {name} in {path}
188flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
189flattennew({list} [, {maxdepth}])
190 List flatten a copy of {list}
191float2nr({expr}) Number convert Float {expr} to a Number
192floor({expr}) Float round {expr} down
193fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
194fnameescape({fname}) String escape special characters in {fname}
195fnamemodify({fname}, {mods}) String modify file name
196foldclosed({lnum}) Number first line of fold at {lnum} if closed
197foldclosedend({lnum}) Number last line of fold at {lnum} if closed
198foldlevel({lnum}) Number fold level at {lnum}
199foldtext() String line displayed for closed fold
200foldtextresult({lnum}) String text for closed fold at {lnum}
Ernie Raele79e2072024-01-13 11:47:33 +0100201foreach({expr1}, {expr2}) List/Dict/Blob/String
202 for each item in {expr1} call {expr2}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000203foreground() Number bring the Vim window to the foreground
Bram Moolenaaraa534142022-09-15 21:46:02 +0100204fullcommand({name} [, {vim9}]) String get full command from {name}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000205funcref({name} [, {arglist}] [, {dict}])
206 Funcref reference to function {name}
207function({name} [, {arglist}] [, {dict}])
208 Funcref named reference to function {name}
209garbagecollect([{atexit}]) none free memory, breaking cyclic references
210get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
211get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
212get({func}, {what}) any get property of funcref/partial {func}
213getbufinfo([{buf}]) List information about buffers
214getbufline({buf}, {lnum} [, {end}])
215 List lines {lnum} to {end} of buffer {buf}
Bram Moolenaarce30ccc2022-11-21 19:57:04 +0000216getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000217getbufvar({buf}, {varname} [, {def}])
218 any variable {varname} in buffer {buf}
Kota Kato66bb9ae2023-01-17 18:31:56 +0000219getcellwidths() List get character cell width overrides
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000220getchangelist([{buf}]) List list of change list items
221getchar([expr]) Number or String
222 get one character from the user
223getcharmod() Number modifiers for the last typed character
224getcharpos({expr}) List position of cursor, mark, etc.
225getcharsearch() Dict last character search
226getcharstr([expr]) String get one character from the user
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100227getcmdcompltype() String return the type of the current
228 command-line completion
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000229getcmdline() String return the current command-line
230getcmdpos() Number return cursor position in command-line
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100231getcmdscreenpos() Number return cursor screen position in
232 command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000233getcmdtype() String return current command-line type
234getcmdwintype() String return current command-line window type
235getcompletion({pat}, {type} [, {filtered}])
236 List list of cmdline completion matches
237getcurpos([{winnr}]) List position of the cursor
238getcursorcharpos([{winnr}]) List character position of the cursor
239getcwd([{winnr} [, {tabnr}]]) String get the current working directory
240getenv({name}) String return environment variable
241getfontname([{name}]) String name of font being used
242getfperm({fname}) String file permissions of file {fname}
243getfsize({fname}) Number size in bytes of file {fname}
244getftime({fname}) Number last modification time of file
245getftype({fname}) String description of type of file {fname}
246getimstatus() Number |TRUE| if the IME status is active
247getjumplist([{winnr} [, {tabnr}]])
248 List list of jump list items
249getline({lnum}) String line {lnum} of current buffer
250getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
251getloclist({nr}) List list of location list items
252getloclist({nr}, {what}) Dict get specific location list properties
253getmarklist([{buf}]) List list of global/local marks
254getmatches([{win}]) List list of current matches
255getmousepos() Dict last known mouse position
Bram Moolenaar24dc19c2022-11-14 19:49:15 +0000256getmouseshape() String current mouse shape name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000257getpid() Number process ID of Vim
258getpos({expr}) List position of cursor, mark, etc.
259getqflist() List list of quickfix items
260getqflist({what}) Dict get specific quickfix list properties
261getreg([{regname} [, 1 [, {list}]]])
262 String or List contents of a register
263getreginfo([{regname}]) Dict information about a register
264getregtype([{regname}]) String type of a register
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +0100265getscriptinfo([{opts}]) List list of sourced scripts
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000266gettabinfo([{expr}]) List list of tab pages
267gettabvar({nr}, {varname} [, {def}])
268 any variable {varname} in tab {nr} or {def}
269gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
270 any {name} in {winnr} in tab page {tabnr}
271gettagstack([{nr}]) Dict get the tag stack of window {nr}
272gettext({text}) String lookup translation of {text}
273getwininfo([{winid}]) List list of info about each window
Bram Moolenaar938ae282023-02-20 20:44:55 +0000274getwinpos([{timeout}]) List X and Y coord in pixels of Vim window
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000275getwinposx() Number X coord in pixels of the Vim window
276getwinposy() Number Y coord in pixels of the Vim window
277getwinvar({nr}, {varname} [, {def}])
278 any variable {varname} in window {nr}
279glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
280 any expand file wildcards in {expr}
281glob2regpat({expr}) String convert a glob pat into a search pat
282globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
283 String do glob({expr}) for all dirs in {path}
284has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
285has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
286haslocaldir([{winnr} [, {tabnr}]])
287 Number |TRUE| if the window executed |:lcd|
288 or |:tcd|
289hasmapto({what} [, {mode} [, {abbr}]])
290 Number |TRUE| if mapping to {what} exists
291histadd({history}, {item}) Number add an item to a history
292histdel({history} [, {item}]) Number remove an item from a history
293histget({history} [, {index}]) String get the item {index} from a history
294histnr({history}) Number highest index of a history
295hlID({name}) Number syntax ID of highlight group {name}
296hlexists({name}) Number |TRUE| if highlight group {name} exists
297hlget([{name} [, {resolve}]]) List get highlight group attributes
298hlset({list}) Number set highlight group attributes
299hostname() String name of the machine Vim is running on
300iconv({expr}, {from}, {to}) String convert encoding of {expr}
301indent({lnum}) Number indent of line {lnum}
302index({object}, {expr} [, {start} [, {ic}]])
303 Number index in {object} where {expr} appears
Yegappan Lakshmananb2186552022-08-13 13:09:20 +0100304indexof({object}, {expr} [, {opts}]])
305 Number index in {object} where {expr} is true
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000306input({prompt} [, {text} [, {completion}]])
307 String get input from the user
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100308inputdialog({prompt} [, {text} [, {cancelreturn}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000309 String like input() but in a GUI dialog
310inputlist({textlist}) Number let the user pick from a choice list
311inputrestore() Number restore typeahead
312inputsave() Number save and clear typeahead
313inputsecret({prompt} [, {text}]) String like input() but hiding the text
314insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
LemonBoyafe04662023-08-23 21:08:11 +0200315instanceof({object}, {class}) Number |TRUE| if {object} is an instance of {class}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000316interrupt() none interrupt script execution
317invert({expr}) Number bitwise invert
LemonBoydca1d402022-04-28 15:26:33 +0100318isabsolutepath({path}) Number |TRUE| if {path} is an absolute path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000319isdirectory({directory}) Number |TRUE| if {directory} is a directory
320isinf({expr}) Number determine if {expr} is infinity value
321 (positive or negative)
322islocked({expr}) Number |TRUE| if {expr} is locked
323isnan({expr}) Number |TRUE| if {expr} is NaN
324items({dict}) List key-value pairs in {dict}
325job_getchannel({job}) Channel get the channel handle for {job}
326job_info([{job}]) Dict get information about {job}
327job_setoptions({job}, {options}) none set options for {job}
328job_start({command} [, {options}])
329 Job start a job
330job_status({job}) String get the status of {job}
331job_stop({job} [, {how}]) Number stop {job}
332join({list} [, {sep}]) String join {list} items into one String
333js_decode({string}) any decode JS style JSON
334js_encode({expr}) String encode JS style JSON
335json_decode({string}) any decode JSON
336json_encode({expr}) String encode JSON
337keys({dict}) List keys in {dict}
zeertzjqcdc83932022-09-12 13:38:41 +0100338keytrans({string}) String translate internal keycodes to a form
339 that can be used by |:map|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000340len({expr}) Number the length of {expr}
341libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
342libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
343line({expr} [, {winid}]) Number line nr of cursor, last line or mark
344line2byte({lnum}) Number byte count of line {lnum}
345lispindent({lnum}) Number Lisp indent for line {lnum}
346list2blob({list}) Blob turn {list} of numbers into a Blob
347list2str({list} [, {utf8}]) String turn {list} of numbers into a String
348listener_add({callback} [, {buf}])
349 Number add a callback to listen to changes
350listener_flush([{buf}]) none invoke listener callbacks
351listener_remove({id}) none remove a listener callback
352localtime() Number current time
353log({expr}) Float natural logarithm (base e) of {expr}
354log10({expr}) Float logarithm of Float {expr} to base 10
355luaeval({expr} [, {expr}]) any evaluate |Lua| expression
356map({expr1}, {expr2}) List/Dict/Blob/String
357 change each item in {expr1} to {expr2}
358maparg({name} [, {mode} [, {abbr} [, {dict}]]])
359 String or Dict
360 rhs of mapping {name} in mode {mode}
361mapcheck({name} [, {mode} [, {abbr}]])
362 String check for mappings matching {name}
Ernie Rael09661202022-04-25 14:40:44 +0100363maplist([{abbr}]) List list of all mappings, a dict for each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000364mapnew({expr1}, {expr2}) List/Dict/Blob/String
365 like |map()| but creates a new List or
366 Dictionary
367mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
368match({expr}, {pat} [, {start} [, {count}]])
369 Number position where {pat} matches in {expr}
370matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
371 Number highlight {pattern} with {group}
372matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
373 Number highlight positions with {group}
374matcharg({nr}) List arguments of |:match|
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100375matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict})
376 List all the {pat} matches in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000377matchdelete({id} [, {win}]) Number delete match identified by {id}
378matchend({expr}, {pat} [, {start} [, {count}]])
379 Number position where {pat} ends in {expr}
380matchfuzzy({list}, {str} [, {dict}])
381 List fuzzy match {str} in {list}
382matchfuzzypos({list}, {str} [, {dict}])
383 List fuzzy match {str} in {list}
384matchlist({expr}, {pat} [, {start} [, {count}]])
385 List match and submatches of {pat} in {expr}
386matchstr({expr}, {pat} [, {start} [, {count}]])
387 String {count}'th match of {pat} in {expr}
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100388matchstrlist({list}, {pat} [, {dict})
389 List all the {pat} matches in {list}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000390matchstrpos({expr}, {pat} [, {start} [, {count}]])
391 List {count}'th match of {pat} in {expr}
392max({expr}) Number maximum value of items in {expr}
393menu_info({name} [, {mode}]) Dict get menu item information
394min({expr}) Number minimum value of items in {expr}
Bram Moolenaar938ae282023-02-20 20:44:55 +0000395mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000396 Number create directory {name}
397mode([expr]) String current editing mode
398mzeval({expr}) any evaluate |MzScheme| expression
399nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
400nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
401or({expr}, {expr}) Number bitwise OR
402pathshorten({expr} [, {len}]) String shorten directory names in a path
403perleval({expr}) any evaluate |Perl| expression
404popup_atcursor({what}, {options}) Number create popup window near the cursor
405popup_beval({what}, {options}) Number create popup window for 'ballooneval'
406popup_clear() none close all popup windows
407popup_close({id} [, {result}]) none close popup window {id}
408popup_create({what}, {options}) Number create a popup window
409popup_dialog({what}, {options}) Number create a popup window used as a dialog
410popup_filter_menu({id}, {key}) Number filter for a menu popup window
411popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
Bram Moolenaarbdc09a12022-10-07 14:31:45 +0100412popup_findecho() Number get window ID of popup for `:echowin`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000413popup_findinfo() Number get window ID of info popup window
414popup_findpreview() Number get window ID of preview popup window
415popup_getoptions({id}) Dict get options of popup window {id}
416popup_getpos({id}) Dict get position of popup window {id}
417popup_hide({id}) none hide popup menu {id}
418popup_list() List get a list of window IDs of all popups
419popup_locate({row}, {col}) Number get window ID of popup at position
420popup_menu({what}, {options}) Number create a popup window used as a menu
421popup_move({id}, {options}) none set position of popup window {id}
422popup_notification({what}, {options})
423 Number create a notification popup window
424popup_setoptions({id}, {options})
425 none set options for popup window {id}
426popup_settext({id}, {text}) none set the text of popup window {id}
427popup_show({id}) none unhide popup window {id}
428pow({x}, {y}) Float {x} to the power of {y}
429prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
430printf({fmt}, {expr1}...) String format text
431prompt_getprompt({buf}) String get prompt text
432prompt_setcallback({buf}, {expr}) none set prompt callback function
433prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
434prompt_setprompt({buf}, {text}) none set prompt text
435prop_add({lnum}, {col}, {props}) none add one text property
436prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
437 none add multiple text properties
438prop_clear({lnum} [, {lnum-end} [, {props}]])
439 none remove all text properties
440prop_find({props} [, {direction}])
441 Dict search for a text property
442prop_list({lnum} [, {props}]) List text properties in {lnum}
443prop_remove({props} [, {lnum} [, {lnum-end}]])
444 Number remove a text property
445prop_type_add({name}, {props}) none define a new property type
446prop_type_change({name}, {props})
447 none change an existing property type
448prop_type_delete({name} [, {props}])
449 none delete a property type
450prop_type_get({name} [, {props}])
451 Dict get property type values
452prop_type_list([{props}]) List get list of property types
453pum_getpos() Dict position and size of pum if visible
454pumvisible() Number whether popup menu is visible
455py3eval({expr}) any evaluate |python3| expression
456pyeval({expr}) any evaluate |Python| expression
457pyxeval({expr}) any evaluate |python_x| expression
458rand([{expr}]) Number get pseudo-random number
459range({expr} [, {max} [, {stride}]])
460 List items from {expr} to {max}
K.Takata11df3ae2022-10-19 14:02:40 +0100461readblob({fname} [, {offset} [, {size}]])
462 Blob read a |Blob| from {fname}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000463readdir({dir} [, {expr} [, {dict}]])
464 List file names in {dir} selected by {expr}
465readdirex({dir} [, {expr} [, {dict}]])
466 List file info in {dir} selected by {expr}
467readfile({fname} [, {type} [, {max}]])
468 List get list of lines from file {fname}
469reduce({object}, {func} [, {initial}])
470 any reduce {object} using {func}
471reg_executing() String get the executing register name
472reg_recording() String get the recording register name
473reltime([{start} [, {end}]]) List get time value
474reltimefloat({time}) Float turn the time value into a Float
475reltimestr({time}) String turn time value into a String
476remote_expr({server}, {string} [, {idvar} [, {timeout}]])
477 String send expression
478remote_foreground({server}) Number bring Vim server to the foreground
479remote_peek({serverid} [, {retvar}])
480 Number check for reply string
481remote_read({serverid} [, {timeout}])
482 String read reply string
483remote_send({server}, {string} [, {idvar}])
484 String send key sequence
485remote_startserver({name}) none become server {name}
486remove({list}, {idx} [, {end}]) any/List
487 remove items {idx}-{end} from {list}
488remove({blob}, {idx} [, {end}]) Number/Blob
489 remove bytes {idx}-{end} from {blob}
490remove({dict}, {key}) any remove entry {key} from {dict}
491rename({from}, {to}) Number rename (move) file from {from} to {to}
Bakudankun375141e2022-09-09 18:46:47 +0100492repeat({expr}, {count}) List/Blob/String
493 repeat {expr} {count} times
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000494resolve({filename}) String get filename a shortcut points to
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +0100495reverse({obj}) List/Blob/String
496 reverse {obj}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000497round({expr}) Float round off {expr}
498rubyeval({expr}) any evaluate |Ruby| expression
499screenattr({row}, {col}) Number attribute at screen position
500screenchar({row}, {col}) Number character at screen position
501screenchars({row}, {col}) List List of characters at screen position
502screencol() Number current cursor column
503screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
504screenrow() Number current cursor row
505screenstring({row}, {col}) String characters at screen position
506search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
507 Number search for {pattern}
508searchcount([{options}]) Dict get or update search stats
509searchdecl({name} [, {global} [, {thisblock}]])
510 Number search for variable declaration
511searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
512 Number search for other end of start/end pair
513searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
514 List search for other end of start/end pair
515searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
516 List search for {pattern}
517server2client({clientid}, {string})
518 Number send reply string
519serverlist() String get a list of available servers
520setbufline({expr}, {lnum}, {text})
521 Number set line {lnum} to {text} in buffer
522 {expr}
523setbufvar({buf}, {varname}, {val})
524 none set {varname} in buffer {buf} to {val}
525setcellwidths({list}) none set character cell width overrides
526setcharpos({expr}, {list}) Number set the {expr} position to {list}
527setcharsearch({dict}) Dict set character search from {dict}
Shougo Matsushita07ea5f12022-08-27 12:22:25 +0100528setcmdline({str} [, {pos}]) Number set command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000529setcmdpos({pos}) Number set cursor position in command-line
530setcursorcharpos({list}) Number move cursor to position in {list}
531setenv({name}, {val}) none set environment variable
532setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
533setline({lnum}, {line}) Number set line {lnum} to {line}
534setloclist({nr}, {list} [, {action}])
535 Number modify location list using {list}
536setloclist({nr}, {list}, {action}, {what})
537 Number modify specific location list props
538setmatches({list} [, {win}]) Number restore a list of matches
539setpos({expr}, {list}) Number set the {expr} position to {list}
540setqflist({list} [, {action}]) Number modify quickfix list using {list}
541setqflist({list}, {action}, {what})
542 Number modify specific quickfix list props
543setreg({n}, {v} [, {opt}]) Number set register to value and type
544settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
545settabwinvar({tabnr}, {winnr}, {varname}, {val})
546 none set {varname} in window {winnr} in tab
547 page {tabnr} to {val}
548settagstack({nr}, {dict} [, {action}])
549 Number modify tag stack using {dict}
550setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
551sha256({string}) String SHA256 checksum of {string}
552shellescape({string} [, {special}])
553 String escape {string} for use as shell
554 command argument
555shiftwidth([{col}]) Number effective value of 'shiftwidth'
556sign_define({name} [, {dict}]) Number define or update a sign
557sign_define({list}) List define or update a list of signs
558sign_getdefined([{name}]) List get a list of defined signs
559sign_getplaced([{buf} [, {dict}]])
560 List get a list of placed signs
561sign_jump({id}, {group}, {buf})
562 Number jump to a sign
563sign_place({id}, {group}, {name}, {buf} [, {dict}])
564 Number place a sign
565sign_placelist({list}) List place a list of signs
566sign_undefine([{name}]) Number undefine a sign
567sign_undefine({list}) List undefine a list of signs
568sign_unplace({group} [, {dict}])
569 Number unplace a sign
570sign_unplacelist({list}) List unplace a list of signs
571simplify({filename}) String simplify filename as much as possible
572sin({expr}) Float sine of {expr}
573sinh({expr}) Float hyperbolic sine of {expr}
574slice({expr}, {start} [, {end}]) String, List or Blob
575 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000576sort({list} [, {how} [, {dict}]])
577 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000578sound_clear() none stop playing all sounds
579sound_playevent({name} [, {callback}])
580 Number play an event sound
581sound_playfile({path} [, {callback}])
582 Number play sound file {path}
583sound_stop({id}) none stop playing sound {id}
584soundfold({word}) String sound-fold {word}
585spellbadword() String badly spelled word at cursor
586spellsuggest({word} [, {max} [, {capital}]])
587 List spelling suggestions
588split({expr} [, {pat} [, {keepempty}]])
589 List make |List| from {pat} separated {expr}
590sqrt({expr}) Float square root of {expr}
591srand([{expr}]) List get seed for |rand()|
592state([{what}]) String current state of Vim
593str2float({expr} [, {quoted}]) Float convert String to Float
594str2list({expr} [, {utf8}]) List convert each character of {expr} to
595 ASCII/UTF-8 value
596str2nr({expr} [, {base} [, {quoted}]])
597 Number convert String to Number
598strcharlen({expr}) Number character length of the String {expr}
599strcharpart({str}, {start} [, {len} [, {skipcc}]])
600 String {len} characters of {str} at
601 character {start}
602strchars({expr} [, {skipcc}]) Number character count of the String {expr}
603strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
604strftime({format} [, {time}]) String format time with a specified format
605strgetchar({str}, {index}) Number get char {index} from {str}
606stridx({haystack}, {needle} [, {start}])
607 Number index of {needle} in {haystack}
608string({expr}) String String representation of {expr} value
609strlen({expr}) Number length of the String {expr}
610strpart({str}, {start} [, {len} [, {chars}]])
611 String {len} bytes/chars of {str} at
612 byte {start}
613strptime({format}, {timestring})
614 Number Convert {timestring} to unix timestamp
615strridx({haystack}, {needle} [, {start}])
616 Number last index of {needle} in {haystack}
617strtrans({expr}) String translate string to make it printable
Christian Brabandt67672ef2023-04-24 21:09:54 +0100618strutf16len({string} [, {countcc}])
619 Number number of UTF-16 code units in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000620strwidth({expr}) Number display cell length of the String {expr}
621submatch({nr} [, {list}]) String or List
622 specific match in ":s" or substitute()
623substitute({expr}, {pat}, {sub}, {flags})
624 String all {pat} in {expr} replaced with {sub}
Bram Moolenaarc216a7a2022-12-05 13:50:55 +0000625swapfilelist() List swap files found in 'directory'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000626swapinfo({fname}) Dict information about swap file {fname}
627swapname({buf}) String swap file of buffer {buf}
628synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
629synIDattr({synID}, {what} [, {mode}])
630 String attribute {what} of syntax ID {synID}
631synIDtrans({synID}) Number translated syntax ID of {synID}
632synconcealed({lnum}, {col}) List info about concealing
633synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
634system({expr} [, {input}]) String output of shell command/filter {expr}
635systemlist({expr} [, {input}]) List output of shell command/filter {expr}
636tabpagebuflist([{arg}]) List list of buffer numbers in tab page
637tabpagenr([{arg}]) Number number of current or last tab page
638tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
639tagfiles() List tags files used
640taglist({expr} [, {filename}]) List list of tags matching {expr}
641tan({expr}) Float tangent of {expr}
642tanh({expr}) Float hyperbolic tangent of {expr}
643tempname() String name for a temporary file
644term_dumpdiff({filename}, {filename} [, {options}])
645 Number display difference between two dumps
646term_dumpload({filename} [, {options}])
647 Number displaying a screen dump
648term_dumpwrite({buf}, {filename} [, {options}])
649 none dump terminal window contents
650term_getaltscreen({buf}) Number get the alternate screen flag
651term_getansicolors({buf}) List get ANSI palette in GUI color mode
652term_getattr({attr}, {what}) Number get the value of attribute {what}
653term_getcursor({buf}) List get the cursor position of a terminal
654term_getjob({buf}) Job get the job associated with a terminal
655term_getline({buf}, {row}) String get a line of text from a terminal
656term_getscrolled({buf}) Number get the scroll count of a terminal
657term_getsize({buf}) List get the size of a terminal
658term_getstatus({buf}) String get the status of a terminal
659term_gettitle({buf}) String get the title of a terminal
660term_gettty({buf}, [{input}]) String get the tty name of a terminal
661term_list() List get the list of terminal buffers
662term_scrape({buf}, {row}) List get row of a terminal screen
663term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
664term_setansicolors({buf}, {colors})
665 none set ANSI palette in GUI color mode
666term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
667term_setkill({buf}, {how}) none set signal to stop job in terminal
668term_setrestore({buf}, {command}) none set command to restore terminal
669term_setsize({buf}, {rows}, {cols})
670 none set the size of a terminal
671term_start({cmd} [, {options}]) Number open a terminal window and run a job
672term_wait({buf} [, {time}]) Number wait for screen to be updated
673terminalprops() Dict properties of the terminal
674test_alloc_fail({id}, {countdown}, {repeat})
675 none make memory allocation fail
676test_autochdir() none enable 'autochdir' during startup
677test_feedinput({string}) none add key sequence to input buffer
678test_garbagecollect_now() none free memory right now for testing
679test_garbagecollect_soon() none free memory soon for testing
680test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000681test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000682test_ignore_error({expr}) none ignore a specific error
Christopher Plewright20b795e2022-12-20 20:01:58 +0000683test_mswin_event({event}, {args})
684 bool generate MS-Windows event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000685test_null_blob() Blob null value for testing
686test_null_channel() Channel null value for testing
687test_null_dict() Dict null value for testing
688test_null_function() Funcref null value for testing
689test_null_job() Job null value for testing
690test_null_list() List null value for testing
691test_null_partial() Funcref null value for testing
692test_null_string() String null value for testing
693test_option_not_set({name}) none reset flag indicating option was set
694test_override({expr}, {val}) none test with Vim internal overrides
695test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000696test_setmouse({row}, {col}) none set the mouse position for testing
697test_settime({expr}) none set current time for testing
698test_srand_seed([seed]) none set seed for testing srand()
699test_unknown() any unknown value for testing
700test_void() any void value for testing
701timer_info([{id}]) List information about timers
702timer_pause({id}, {pause}) none pause or unpause a timer
703timer_start({time}, {callback} [, {options}])
704 Number create a timer
705timer_stop({timer}) none stop a timer
706timer_stopall() none stop all timers
707tolower({expr}) String the String {expr} switched to lowercase
708toupper({expr}) String the String {expr} switched to uppercase
709tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
710 to chars in {tostr}
711trim({text} [, {mask} [, {dir}]])
712 String trim characters in {mask} from {text}
713trunc({expr}) Float truncate Float {expr}
714type({expr}) Number type of value {expr}
715typename({expr}) String representation of the type of {expr}
716undofile({name}) String undo file name for {name}
Devin J. Pohly5fee1112023-04-23 20:26:59 -0500717undotree([{buf}]) List undo file tree for buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000718uniq({list} [, {func} [, {dict}]])
719 List remove adjacent duplicates from a list
Christian Brabandt67672ef2023-04-24 21:09:54 +0100720utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
721 Number UTF-16 index of byte {idx} in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000722values({dict}) List values in {dict}
zeertzjq825cf812023-08-17 22:55:25 +0200723virtcol({expr} [, {list} [, {winid}])
724 Number or List
LemonBoy0f7a3e12022-05-26 12:10:37 +0100725 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100726virtcol2col({winid}, {lnum}, {col})
727 Number byte index of a character on screen
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000728visualmode([expr]) String last visual mode used
729wildmenumode() Number whether 'wildmenu' mode is active
730win_execute({id}, {command} [, {silent}])
731 String execute {command} in window {id}
732win_findbuf({bufnr}) List find windows containing {bufnr}
733win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
734win_gettype([{nr}]) String type of window {nr}
735win_gotoid({expr}) Number go to window with ID {expr}
736win_id2tabwin({expr}) List get tab and window nr from window ID
737win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000738win_move_separator({nr}) Number move window vertical separator
739win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000740win_screenpos({nr}) List get screen position of window {nr}
741win_splitmove({nr}, {target} [, {options}])
742 Number move window {nr} to split of {target}
743winbufnr({nr}) Number buffer number of window {nr}
744wincol() Number window column of the cursor
745windowsversion() String MS-Windows OS version
746winheight({nr}) Number height of window {nr}
747winlayout([{tabnr}]) List layout of windows in tab {tabnr}
748winline() Number window line of the cursor
749winnr([{expr}]) Number number of current window
750winrestcmd() String returns command to restore window sizes
751winrestview({dict}) none restore view of current window
752winsaveview() Dict save view of current window
753winwidth({nr}) Number width of window {nr}
754wordcount() Dict get byte/char/word statistics
755writefile({object}, {fname} [, {flags}])
756 Number write |Blob| or |List| of lines to file
757xor({expr}, {expr}) Number bitwise XOR
758
759==============================================================================
7602. Details *builtin-function-details*
761
762Not all functions are here, some have been moved to a help file covering the
763specific functionality.
764
765abs({expr}) *abs()*
766 Return the absolute value of {expr}. When {expr} evaluates to
767 a |Float| abs() returns a |Float|. When {expr} can be
768 converted to a |Number| abs() returns a |Number|. Otherwise
769 abs() gives an error message and returns -1.
770 Examples: >
771 echo abs(1.456)
772< 1.456 >
773 echo abs(-5.456)
774< 5.456 >
775 echo abs(-4)
776< 4
777
778 Can also be used as a |method|: >
779 Compute()->abs()
780
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000781
782acos({expr}) *acos()*
783 Return the arc cosine of {expr} measured in radians, as a
784 |Float| in the range of [0, pi].
785 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100786 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000787 Examples: >
788 :echo acos(0)
789< 1.570796 >
790 :echo acos(-0.5)
791< 2.094395
792
793 Can also be used as a |method|: >
794 Compute()->acos()
795
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000796
797add({object}, {expr}) *add()*
798 Append the item {expr} to |List| or |Blob| {object}. Returns
799 the resulting |List| or |Blob|. Examples: >
800 :let alist = add([1, 2, 3], item)
801 :call add(mylist, "woodstock")
802< Note that when {expr} is a |List| it is appended as a single
803 item. Use |extend()| to concatenate |Lists|.
804 When {object} is a |Blob| then {expr} must be a number.
805 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100806 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000807
808 Can also be used as a |method|: >
809 mylist->add(val1)->add(val2)
810
811
812and({expr}, {expr}) *and()*
813 Bitwise AND on the two arguments. The arguments are converted
814 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100815 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000816 Example: >
817 :let flag = and(bits, 0x80)
818< Can also be used as a |method|: >
819 :let flag = bits->and(0x80)
820
821
822append({lnum}, {text}) *append()*
823 When {text} is a |List|: Append each item of the |List| as a
824 text line below line {lnum} in the current buffer.
825 Otherwise append {text} as one text line below line {lnum} in
826 the current buffer.
827 Any type of item is accepted and converted to a String.
828 {lnum} can be zero to insert a line before the first one.
829 {lnum} is used like with |getline()|.
830 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000831 0 for success. When {text} is an empty list zero is returned,
832 no matter the value of {lnum}.
833 In |Vim9| script an invalid argument or negative number
834 results in an error. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000835 :let failed = append(line('$'), "# THE END")
836 :let failed = append(0, ["Chapter 1", "the beginning"])
837
838< Can also be used as a |method| after a List, the base is
839 passed as the second argument: >
840 mylist->append(lnum)
841
842
843appendbufline({buf}, {lnum}, {text}) *appendbufline()*
844 Like |append()| but append the text in buffer {buf}.
845
846 This function works only for loaded buffers. First call
847 |bufload()| if needed.
848
849 For the use of {buf}, see |bufname()|.
850
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000851 {lnum} is the line number to append below. Note that using
852 |line()| would use the current buffer, not the one appending
853 to. Use "$" to append at the end of the buffer. Other string
854 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000855
856 On success 0 is returned, on failure 1 is returned.
857 In |Vim9| script an error is given for an invalid {lnum}.
858
859 If {buf} is not a valid buffer or {lnum} is not valid, an
860 error message is given. Example: >
861 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000862< However, when {text} is an empty list then no error is given
863 for an invalid {lnum}, since {lnum} isn't actually used.
864
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000865 Can also be used as a |method| after a List, the base is
866 passed as the second argument: >
867 mylist->appendbufline(buf, lnum)
868
869
870argc([{winid}]) *argc()*
871 The result is the number of files in the argument list. See
872 |arglist|.
873 If {winid} is not supplied, the argument list of the current
874 window is used.
875 If {winid} is -1, the global argument list is used.
876 Otherwise {winid} specifies the window of which the argument
877 list is used: either the window number or the window ID.
878 Returns -1 if the {winid} argument is invalid.
879
880 *argidx()*
881argidx() The result is the current index in the argument list. 0 is
882 the first file. argc() - 1 is the last one. See |arglist|.
883
884 *arglistid()*
885arglistid([{winnr} [, {tabnr}]])
886 Return the argument list ID. This is a number which
887 identifies the argument list being used. Zero is used for the
888 global argument list. See |arglist|.
889 Returns -1 if the arguments are invalid.
890
891 Without arguments use the current window.
892 With {winnr} only use this window in the current tab page.
893 With {winnr} and {tabnr} use the window in the specified tab
894 page.
895 {winnr} can be the window number or the |window-ID|.
896
897 *argv()*
898argv([{nr} [, {winid}]])
899 The result is the {nr}th file in the argument list. See
900 |arglist|. "argv(0)" is the first one. Example: >
901 :let i = 0
902 :while i < argc()
903 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000904 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000905 : let i = i + 1
906 :endwhile
907< Without the {nr} argument, or when {nr} is -1, a |List| with
908 the whole |arglist| is returned.
909
910 The {winid} argument specifies the window ID, see |argc()|.
911 For the Vim command line arguments see |v:argv|.
912
Bram Moolenaar016188f2022-06-06 20:52:59 +0100913 Returns an empty string if {nr}th argument is not present in
914 the argument list. Returns an empty List if the {winid}
915 argument is invalid.
916
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000917asin({expr}) *asin()*
918 Return the arc sine of {expr} measured in radians, as a |Float|
919 in the range of [-pi/2, pi/2].
920 {expr} must evaluate to a |Float| or a |Number| in the range
921 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100922 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
923 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000924 Examples: >
925 :echo asin(0.8)
926< 0.927295 >
927 :echo asin(-0.5)
928< -0.523599
929
930 Can also be used as a |method|: >
931 Compute()->asin()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000932
933
934assert_ functions are documented here: |assert-functions-details|
935
936
937
938atan({expr}) *atan()*
939 Return the principal value of the arc tangent of {expr}, in
940 the range [-pi/2, +pi/2] radians, as a |Float|.
941 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100942 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000943 Examples: >
944 :echo atan(100)
945< 1.560797 >
946 :echo atan(-4.01)
947< -1.326405
948
949 Can also be used as a |method|: >
950 Compute()->atan()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000951
952
953atan2({expr1}, {expr2}) *atan2()*
954 Return the arc tangent of {expr1} / {expr2}, measured in
955 radians, as a |Float| in the range [-pi, pi].
956 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100957 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
958 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000959 Examples: >
960 :echo atan2(-1, 1)
961< -0.785398 >
962 :echo atan2(1, -1)
963< 2.356194
964
965 Can also be used as a |method|: >
966 Compute()->atan2(1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000967
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100968
969autocmd_add({acmds}) *autocmd_add()*
970 Adds a List of autocmds and autocmd groups.
971
972 The {acmds} argument is a List where each item is a Dict with
973 the following optional items:
974 bufnr buffer number to add a buffer-local autocmd.
975 If this item is specified, then the "pattern"
976 item is ignored.
977 cmd Ex command to execute for this autocmd event
978 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100979 This can be either a String with a single
980 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100981 group autocmd group name. Refer to |autocmd-groups|.
982 If this group doesn't exist then it is
983 created. If not specified or empty, then the
984 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100985 nested boolean flag, set to v:true to add a nested
986 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100987 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100988 which executes only once. Refer to
989 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100990 pattern autocmd pattern string. Refer to
991 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100992 present, then this item is ignored. This can
993 be a String with a single pattern or a List of
994 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100995 replace boolean flag, set to v:true to remove all the
996 commands associated with the specified autocmd
997 event and group and add the {cmd}. This is
998 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +0100999 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001000
1001 Returns v:true on success and v:false on failure.
1002 Examples: >
1003 " Create a buffer-local autocmd for buffer 5
1004 let acmd = {}
1005 let acmd.group = 'MyGroup'
1006 let acmd.event = 'BufEnter'
1007 let acmd.bufnr = 5
1008 let acmd.cmd = 'call BufEnterFunc()'
1009 call autocmd_add([acmd])
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00001010<
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001011 Can also be used as a |method|: >
1012 GetAutocmdList()->autocmd_add()
1013<
1014autocmd_delete({acmds}) *autocmd_delete()*
1015 Deletes a List of autocmds and autocmd groups.
1016
1017 The {acmds} argument is a List where each item is a Dict with
1018 the following optional items:
1019 bufnr buffer number to delete a buffer-local autocmd.
1020 If this item is specified, then the "pattern"
1021 item is ignored.
1022 cmd Ex command for this autocmd event
1023 event autocmd event name. Refer to |autocmd-events|.
1024 If '*' then all the autocmd events in this
1025 group are deleted.
1026 group autocmd group name. Refer to |autocmd-groups|.
1027 If not specified or empty, then the default
1028 group is used.
1029 nested set to v:true for a nested autocmd.
1030 Refer to |autocmd-nested|.
1031 once set to v:true for an autocmd which executes
1032 only once. Refer to |autocmd-once|.
1033 pattern autocmd pattern string. Refer to
1034 |autocmd-patterns|. If "bufnr" item is
1035 present, then this item is ignored.
1036
1037 If only {group} is specified in a {acmds} entry and {event},
1038 {pattern} and {cmd} are not specified, then that autocmd group
1039 is deleted.
1040
Bram Moolenaar016188f2022-06-06 20:52:59 +01001041 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001042 Examples: >
1043 " :autocmd! BufLeave *.vim
1044 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1045 call autocmd_delete([acmd]})
1046 " :autocmd! MyGroup1 BufLeave
1047 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1048 call autocmd_delete([acmd])
1049 " :autocmd! MyGroup2 BufEnter *.c
1050 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1051 \ pattern: '*.c'}
1052 " :autocmd! MyGroup2 * *.c
1053 let acmd = #{group: 'MyGroup2', event: '*',
1054 \ pattern: '*.c'}
1055 call autocmd_delete([acmd])
1056 " :autocmd! MyGroup3
1057 let acmd = #{group: 'MyGroup3'}
1058 call autocmd_delete([acmd])
1059<
1060 Can also be used as a |method|: >
1061 GetAutocmdList()->autocmd_delete()
1062
1063autocmd_get([{opts}]) *autocmd_get()*
1064 Returns a |List| of autocmds. If {opts} is not supplied, then
1065 returns the autocmds for all the events in all the groups.
1066
1067 The optional {opts} Dict argument supports the following
1068 items:
1069 group Autocmd group name. If specified, returns only
1070 the autocmds defined in this group. If the
1071 specified group doesn't exist, results in an
1072 error message. If set to an empty string,
1073 then the default autocmd group is used.
1074 event Autocmd event name. If specified, returns only
1075 the autocmds defined for this event. If set
1076 to "*", then returns autocmds for all the
1077 events. If the specified event doesn't exist,
1078 results in an error message.
1079 pattern Autocmd pattern. If specified, returns only
1080 the autocmds defined for this pattern.
1081 A combination of the above three times can be supplied in
1082 {opts}.
1083
1084 Each Dict in the returned List contains the following items:
1085 bufnr For buffer-local autocmds, buffer number where
1086 the autocmd is defined.
1087 cmd Command executed for this autocmd.
1088 event Autocmd event name.
1089 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001090 nested Boolean flag, set to v:true for a nested
1091 autocmd. See |autocmd-nested|.
1092 once Boolean flag, set to v:true, if the autocmd
1093 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001094 pattern Autocmd pattern. For a buffer-local
1095 autocmd, this will be of the form "<buffer=n>".
1096 If there are multiple commands for an autocmd event in a
1097 group, then separate items are returned for each command.
1098
Bram Moolenaar016188f2022-06-06 20:52:59 +01001099 Returns an empty List if an autocmd with the specified group
1100 or event or pattern is not found.
1101
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001102 Examples: >
1103 " :autocmd MyGroup
1104 echo autocmd_get(#{group: 'Mygroup'})
1105 " :autocmd G BufUnload
1106 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1107 " :autocmd G * *.ts
1108 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1109 echo autocmd_get(acmd)
1110 " :autocmd Syntax
1111 echo autocmd_get(#{event: 'Syntax'})
1112 " :autocmd G BufEnter *.ts
1113 let acmd = #{group: 'G', event: 'BufEnter',
1114 \ pattern: '*.ts'}
1115 echo autocmd_get(acmd)
1116<
1117 Can also be used as a |method|: >
1118 Getopts()->autocmd_get()
1119<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001120balloon_gettext() *balloon_gettext()*
1121 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001122 not used for the List. Returns an empty string if balloon
1123 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001124
1125balloon_show({expr}) *balloon_show()*
1126 Show {expr} inside the balloon. For the GUI {expr} is used as
1127 a string. For a terminal {expr} can be a list, which contains
1128 the lines of the balloon. If {expr} is not a list it will be
1129 split with |balloon_split()|.
1130 If {expr} is an empty string any existing balloon is removed.
1131
1132 Example: >
1133 func GetBalloonContent()
1134 " ... initiate getting the content
1135 return ''
1136 endfunc
1137 set balloonexpr=GetBalloonContent()
1138
1139 func BalloonCallback(result)
1140 call balloon_show(a:result)
1141 endfunc
1142< Can also be used as a |method|: >
1143 GetText()->balloon_show()
1144<
1145 The intended use is that fetching the content of the balloon
1146 is initiated from 'balloonexpr'. It will invoke an
1147 asynchronous method, in which a callback invokes
1148 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001149 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001150
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001151 When showing a balloon is not possible then nothing happens,
1152 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001153 {only available when compiled with the |+balloon_eval| or
1154 |+balloon_eval_term| feature}
1155
1156balloon_split({msg}) *balloon_split()*
1157 Split String {msg} into lines to be displayed in a balloon.
1158 The splits are made for the current window size and optimize
1159 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001160 Returns a |List| with the split lines. Returns an empty List
1161 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001162 Can also be used as a |method|: >
1163 GetText()->balloon_split()->balloon_show()
1164
1165< {only available when compiled with the |+balloon_eval_term|
1166 feature}
1167
1168blob2list({blob}) *blob2list()*
1169 Return a List containing the number value of each byte in Blob
1170 {blob}. Examples: >
1171 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1172 blob2list(0z) returns []
1173< Returns an empty List on error. |list2blob()| does the
1174 opposite.
1175
1176 Can also be used as a |method|: >
1177 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001178<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001179 *browse()*
1180browse({save}, {title}, {initdir}, {default})
1181 Put up a file requester. This only works when "has("browse")"
1182 returns |TRUE| (only in some GUI versions).
1183 The input fields are:
1184 {save} when |TRUE|, select file to write
1185 {title} title for the requester
1186 {initdir} directory to start browsing in
1187 {default} default file name
1188 An empty string is returned when the "Cancel" button is hit,
1189 something went wrong, or browsing is not possible.
1190
1191 *browsedir()*
1192browsedir({title}, {initdir})
1193 Put up a directory requester. This only works when
1194 "has("browse")" returns |TRUE| (only in some GUI versions).
1195 On systems where a directory browser is not supported a file
1196 browser is used. In that case: select a file in the directory
1197 to be used.
1198 The input fields are:
1199 {title} title for the requester
1200 {initdir} directory to start browsing in
1201 When the "Cancel" button is hit, something went wrong, or
1202 browsing is not possible, an empty string is returned.
1203
1204bufadd({name}) *bufadd()*
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001205 Add a buffer to the buffer list with name {name} (must be a
1206 String).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001207 If a buffer for file {name} already exists, return that buffer
1208 number. Otherwise return the buffer number of the newly
1209 created buffer. When {name} is an empty string then a new
1210 buffer is always created.
1211 The buffer will not have 'buflisted' set and not be loaded
1212 yet. To add some text to the buffer use this: >
1213 let bufnr = bufadd('someName')
1214 call bufload(bufnr)
1215 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001216< Returns 0 on error.
1217 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001218 let bufnr = 'somename'->bufadd()
1219
1220bufexists({buf}) *bufexists()*
1221 The result is a Number, which is |TRUE| if a buffer called
1222 {buf} exists.
1223 If the {buf} argument is a number, buffer numbers are used.
1224 Number zero is the alternate buffer for the current window.
1225
1226 If the {buf} argument is a string it must match a buffer name
1227 exactly. The name can be:
1228 - Relative to the current directory.
1229 - A full path.
1230 - The name of a buffer with 'buftype' set to "nofile".
1231 - A URL name.
1232 Unlisted buffers will be found.
1233 Note that help files are listed by their short name in the
1234 output of |:buffers|, but bufexists() requires using their
1235 long name to be able to find them.
1236 bufexists() may report a buffer exists, but to use the name
1237 with a |:buffer| command you may need to use |expand()|. Esp
1238 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1239 Use "bufexists(0)" to test for the existence of an alternate
1240 file name.
1241
1242 Can also be used as a |method|: >
1243 let exists = 'somename'->bufexists()
1244<
1245 Obsolete name: buffer_exists(). *buffer_exists()*
1246
1247buflisted({buf}) *buflisted()*
1248 The result is a Number, which is |TRUE| if a buffer called
1249 {buf} exists and is listed (has the 'buflisted' option set).
1250 The {buf} argument is used like with |bufexists()|.
1251
1252 Can also be used as a |method|: >
1253 let listed = 'somename'->buflisted()
1254
1255bufload({buf}) *bufload()*
1256 Ensure the buffer {buf} is loaded. When the buffer name
1257 refers to an existing file then the file is read. Otherwise
1258 the buffer will be empty. If the buffer was already loaded
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001259 then there is no change. If the buffer is not related to a
Daniel Steinbergc2bd2052023-08-09 12:10:59 -04001260 file then no file is read (e.g., when 'buftype' is "nofile").
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001261 If there is an existing swap file for the file of the buffer,
1262 there will be no dialog, the buffer will be loaded anyway.
1263 The {buf} argument is used like with |bufexists()|.
1264
1265 Can also be used as a |method|: >
1266 eval 'somename'->bufload()
1267
1268bufloaded({buf}) *bufloaded()*
1269 The result is a Number, which is |TRUE| if a buffer called
1270 {buf} exists and is loaded (shown in a window or hidden).
1271 The {buf} argument is used like with |bufexists()|.
1272
1273 Can also be used as a |method|: >
1274 let loaded = 'somename'->bufloaded()
1275
1276bufname([{buf}]) *bufname()*
1277 The result is the name of a buffer. Mostly as it is displayed
1278 by the `:ls` command, but not using special names such as
1279 "[No Name]".
1280 If {buf} is omitted the current buffer is used.
1281 If {buf} is a Number, that buffer number's name is given.
1282 Number zero is the alternate buffer for the current window.
1283 If {buf} is a String, it is used as a |file-pattern| to match
1284 with the buffer names. This is always done like 'magic' is
1285 set and 'cpoptions' is empty. When there is more than one
1286 match an empty string is returned.
1287 "" or "%" can be used for the current buffer, "#" for the
1288 alternate buffer.
1289 A full match is preferred, otherwise a match at the start, end
1290 or middle of the buffer name is accepted. If you only want a
1291 full match then put "^" at the start and "$" at the end of the
1292 pattern.
1293 Listed buffers are found first. If there is a single match
1294 with a listed buffer, that one is returned. Next unlisted
1295 buffers are searched for.
1296 If the {buf} is a String, but you want to use it as a buffer
1297 number, force it to be a Number by adding zero to it: >
1298 :echo bufname("3" + 0)
1299< Can also be used as a |method|: >
1300 echo bufnr->bufname()
1301
1302< If the buffer doesn't exist, or doesn't have a name, an empty
1303 string is returned. >
1304 bufname("#") alternate buffer name
1305 bufname(3) name of buffer 3
1306 bufname("%") name of current buffer
1307 bufname("file2") name of buffer where "file2" matches.
1308< *buffer_name()*
1309 Obsolete name: buffer_name().
1310
1311 *bufnr()*
1312bufnr([{buf} [, {create}]])
1313 The result is the number of a buffer, as it is displayed by
1314 the `:ls` command. For the use of {buf}, see |bufname()|
1315 above.
1316
1317 If the buffer doesn't exist, -1 is returned. Or, if the
1318 {create} argument is present and TRUE, a new, unlisted,
1319 buffer is created and its number is returned. Example: >
1320 let newbuf = bufnr('Scratch001', 1)
1321< Using an empty name uses the current buffer. To create a new
1322 buffer with an empty name use |bufadd()|.
1323
1324 bufnr("$") is the last buffer: >
1325 :let last_buffer = bufnr("$")
1326< The result is a Number, which is the highest buffer number
1327 of existing buffers. Note that not all buffers with a smaller
1328 number necessarily exist, because ":bwipeout" may have removed
1329 them. Use bufexists() to test for the existence of a buffer.
1330
1331 Can also be used as a |method|: >
1332 echo bufref->bufnr()
1333<
1334 Obsolete name: buffer_number(). *buffer_number()*
1335 *last_buffer_nr()*
1336 Obsolete name for bufnr("$"): last_buffer_nr().
1337
1338bufwinid({buf}) *bufwinid()*
1339 The result is a Number, which is the |window-ID| of the first
1340 window associated with buffer {buf}. For the use of {buf},
1341 see |bufname()| above. If buffer {buf} doesn't exist or
1342 there is no such window, -1 is returned. Example: >
1343
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001344 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001345<
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001346 Only deals with the current tab page. See |win_findbuf()| for
1347 finding more.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001348
1349 Can also be used as a |method|: >
1350 FindBuffer()->bufwinid()
1351
1352bufwinnr({buf}) *bufwinnr()*
1353 Like |bufwinid()| but return the window number instead of the
1354 |window-ID|.
1355 If buffer {buf} doesn't exist or there is no such window, -1
1356 is returned. Example: >
1357
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001358 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001359
1360< The number can be used with |CTRL-W_w| and ":wincmd w"
1361 |:wincmd|.
1362
1363 Can also be used as a |method|: >
1364 FindBuffer()->bufwinnr()
1365
1366byte2line({byte}) *byte2line()*
1367 Return the line number that contains the character at byte
1368 count {byte} in the current buffer. This includes the
1369 end-of-line character, depending on the 'fileformat' option
1370 for the current buffer. The first character has byte count
1371 one.
1372 Also see |line2byte()|, |go| and |:goto|.
1373
Bram Moolenaar016188f2022-06-06 20:52:59 +01001374 Returns -1 if the {byte} value is invalid.
1375
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001376 Can also be used as a |method|: >
1377 GetOffset()->byte2line()
1378
1379< {not available when compiled without the |+byte_offset|
1380 feature}
1381
Christian Brabandt67672ef2023-04-24 21:09:54 +01001382byteidx({expr}, {nr} [, {utf16}]) *byteidx()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001383 Return byte index of the {nr}'th character in the String
1384 {expr}. Use zero for the first character, it then returns
1385 zero.
1386 If there are no multibyte characters the returned value is
1387 equal to {nr}.
1388 Composing characters are not counted separately, their byte
1389 length is added to the preceding base character. See
1390 |byteidxcomp()| below for counting composing characters
1391 separately.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001392 When {utf16} is present and TRUE, {nr} is used as the UTF-16
1393 index in the String {expr} instead of as the character index.
1394 The UTF-16 index is the index in the string when it is encoded
1395 with 16-bit words. If the specified UTF-16 index is in the
1396 middle of a character (e.g. in a 4-byte character), then the
1397 byte index of the first byte in the character is returned.
1398 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001399 Example : >
1400 echo matchstr(str, ".", byteidx(str, 3))
1401< will display the fourth character. Another way to do the
1402 same: >
1403 let s = strpart(str, byteidx(str, 3))
1404 echo strpart(s, 0, byteidx(s, 1))
1405< Also see |strgetchar()| and |strcharpart()|.
1406
1407 If there are less than {nr} characters -1 is returned.
1408 If there are exactly {nr} characters the length of the string
1409 in bytes is returned.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001410 See |charidx()| and |utf16idx()| for getting the character and
1411 UTF-16 index respectively from the byte index.
1412 Examples: >
1413 echo byteidx('a😊😊', 2) returns 5
1414 echo byteidx('a😊😊', 2, 1) returns 1
1415 echo byteidx('a😊😊', 3, 1) returns 5
1416<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001417 Can also be used as a |method|: >
1418 GetName()->byteidx(idx)
1419
Christian Brabandt67672ef2023-04-24 21:09:54 +01001420byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001421 Like byteidx(), except that a composing character is counted
1422 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001423 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001424 echo byteidx(s, 1)
1425 echo byteidxcomp(s, 1)
1426 echo byteidxcomp(s, 2)
1427< The first and third echo result in 3 ('e' plus composing
1428 character is 3 bytes), the second echo results in 1 ('e' is
1429 one byte).
1430 Only works differently from byteidx() when 'encoding' is set
1431 to a Unicode encoding.
1432
1433 Can also be used as a |method|: >
1434 GetName()->byteidxcomp(idx)
1435
1436call({func}, {arglist} [, {dict}]) *call()* *E699*
1437 Call function {func} with the items in |List| {arglist} as
1438 arguments.
1439 {func} can either be a |Funcref| or the name of a function.
1440 a:firstline and a:lastline are set to the cursor line.
1441 Returns the return value of the called function.
1442 {dict} is for functions with the "dict" attribute. It will be
1443 used to set the local variable "self". |Dictionary-function|
1444
1445 Can also be used as a |method|: >
1446 GetFunc()->call([arg, arg], dict)
1447
1448ceil({expr}) *ceil()*
1449 Return the smallest integral value greater than or equal to
1450 {expr} as a |Float| (round up).
1451 {expr} must evaluate to a |Float| or a |Number|.
1452 Examples: >
1453 echo ceil(1.456)
1454< 2.0 >
1455 echo ceil(-5.456)
1456< -5.0 >
1457 echo ceil(4.0)
1458< 4.0
1459
Bram Moolenaar016188f2022-06-06 20:52:59 +01001460 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1461
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001462 Can also be used as a |method|: >
1463 Compute()->ceil()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001464
1465
1466ch_ functions are documented here: |channel-functions-details|
1467
1468
1469changenr() *changenr()*
1470 Return the number of the most recent change. This is the same
1471 number as what is displayed with |:undolist| and can be used
1472 with the |:undo| command.
1473 When a change was made it is the number of that change. After
1474 redo it is the number of the redone change. After undo it is
1475 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001476 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001477
1478char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001479 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001480 Examples: >
1481 char2nr(" ") returns 32
1482 char2nr("ABC") returns 65
1483< When {utf8} is omitted or zero, the current 'encoding' is used.
1484 Example for "utf-8": >
1485 char2nr("á") returns 225
1486 char2nr("á"[0]) returns 195
1487< When {utf8} is TRUE, always treat as UTF-8 characters.
1488 A combining character is a separate character.
1489 |nr2char()| does the opposite.
1490 To turn a string into a list of character numbers: >
1491 let str = "ABC"
1492 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1493< Result: [65, 66, 67]
1494
Bram Moolenaar016188f2022-06-06 20:52:59 +01001495 Returns 0 if {string} is not a |String|.
1496
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001497 Can also be used as a |method|: >
1498 GetChar()->char2nr()
1499
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001500charclass({string}) *charclass()*
1501 Return the character class of the first character in {string}.
1502 The character class is one of:
1503 0 blank
1504 1 punctuation
1505 2 word character
1506 3 emoji
1507 other specific Unicode class
1508 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001509 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001510
1511
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001512charcol({expr} [, {winid}]) *charcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001513 Same as |col()| but returns the character index of the column
1514 position given with {expr} instead of the byte position.
1515
1516 Example:
1517 With the cursor on '세' in line 5 with text "여보세요": >
1518 charcol('.') returns 3
1519 col('.') returns 7
1520
1521< Can also be used as a |method|: >
1522 GetPos()->col()
1523<
1524 *charidx()*
Christian Brabandt67672ef2023-04-24 21:09:54 +01001525charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001526 Return the character index of the byte at {idx} in {string}.
1527 The index of the first character is zero.
1528 If there are no multibyte characters the returned value is
1529 equal to {idx}.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001530
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001531 When {countcc} is omitted or |FALSE|, then composing characters
Christian Brabandt67672ef2023-04-24 21:09:54 +01001532 are not counted separately, their byte length is added to the
1533 preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001534 When {countcc} is |TRUE|, then composing characters are
1535 counted as separate characters.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001536
1537 When {utf16} is present and TRUE, {idx} is used as the UTF-16
1538 index in the String {expr} instead of as the byte index.
1539
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +01001540 Returns -1 if the arguments are invalid or if there are less
1541 than {idx} bytes. If there are exactly {idx} bytes the length
1542 of the string in characters is returned.
1543
1544 An error is given and -1 is returned if the first argument is
1545 not a string, the second argument is not a number or when the
1546 third argument is present and is not zero or one.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001547
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001548 See |byteidx()| and |byteidxcomp()| for getting the byte index
Christian Brabandt67672ef2023-04-24 21:09:54 +01001549 from the character index and |utf16idx()| for getting the
1550 UTF-16 index from the character index.
1551 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001552 Examples: >
1553 echo charidx('áb́ć', 3) returns 1
1554 echo charidx('áb́ć', 6, 1) returns 4
1555 echo charidx('áb́ć', 16) returns -1
Christian Brabandt67672ef2023-04-24 21:09:54 +01001556 echo charidx('a😊😊', 4, 0, 1) returns 2
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001557<
1558 Can also be used as a |method|: >
1559 GetName()->charidx(idx)
1560
1561chdir({dir}) *chdir()*
1562 Change the current working directory to {dir}. The scope of
1563 the directory change depends on the directory of the current
1564 window:
1565 - If the current window has a window-local directory
1566 (|:lcd|), then changes the window local directory.
1567 - Otherwise, if the current tabpage has a local
1568 directory (|:tcd|) then changes the tabpage local
1569 directory.
1570 - Otherwise, changes the global directory.
1571 {dir} must be a String.
1572 If successful, returns the previous working directory. Pass
1573 this to another chdir() to restore the directory.
1574 On failure, returns an empty string.
1575
1576 Example: >
1577 let save_dir = chdir(newdir)
1578 if save_dir != ""
1579 " ... do some work
1580 call chdir(save_dir)
1581 endif
1582
1583< Can also be used as a |method|: >
1584 GetDir()->chdir()
1585<
1586cindent({lnum}) *cindent()*
1587 Get the amount of indent for line {lnum} according the C
1588 indenting rules, as with 'cindent'.
1589 The indent is counted in spaces, the value of 'tabstop' is
1590 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001591 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001592 See |C-indenting|.
1593
1594 Can also be used as a |method|: >
1595 GetLnum()->cindent()
1596
1597clearmatches([{win}]) *clearmatches()*
1598 Clears all matches previously defined for the current window
1599 by |matchadd()| and the |:match| commands.
1600 If {win} is specified, use the window with this number or
1601 window ID instead of the current window.
1602
1603 Can also be used as a |method|: >
1604 GetWin()->clearmatches()
1605<
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001606col({expr} [, {winid}]) *col()*
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001607 The result is a Number, which is the byte index of the column
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001608 position given with {expr}. The accepted positions are:
1609 . the cursor position
1610 $ the end of the cursor line (the result is the
1611 number of bytes in the cursor line plus one)
1612 'x position of mark x (if the mark is not set, 0 is
1613 returned)
1614 v In Visual mode: the start of the Visual area (the
1615 cursor is the end). When not in Visual mode
1616 returns the cursor position. Differs from |'<| in
1617 that it's updated right away.
1618 Additionally {expr} can be [lnum, col]: a |List| with the line
1619 and column number. Most useful when the column is "$", to get
1620 the last column of a specific line. When "lnum" or "col" is
1621 out of range then col() returns zero.
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001622 With the optional {winid} argument the values are obtained for
1623 that window instead of the current window.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001624 To get the line number use |line()|. To get both use
1625 |getpos()|.
1626 For the screen column position use |virtcol()|. For the
1627 character position use |charcol()|.
1628 Note that only marks in the current file can be used.
1629 Examples: >
1630 col(".") column of cursor
1631 col("$") length of cursor line plus one
1632 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001633 col("'" .. markname) column of mark markname
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001634< The first column is 1. Returns 0 if {expr} is invalid or when
1635 the window with ID {winid} is not found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001636 For an uppercase mark the column may actually be in another
1637 buffer.
1638 For the cursor position, when 'virtualedit' is active, the
1639 column is one higher if the cursor is after the end of the
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01001640 line. Also, when using a <Cmd> mapping the cursor isn't
1641 moved, this can be used to obtain the column in Insert mode: >
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001642 :imap <F2> <Cmd>echowin col(".")<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001643
1644< Can also be used as a |method|: >
1645 GetPos()->col()
1646<
1647
1648complete({startcol}, {matches}) *complete()* *E785*
1649 Set the matches for Insert mode completion.
1650 Can only be used in Insert mode. You need to use a mapping
1651 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1652 or with an expression mapping.
1653 {startcol} is the byte offset in the line where the completed
1654 text start. The text up to the cursor is the original text
1655 that will be replaced by the matches. Use col('.') for an
1656 empty string. "col('.') - 1" will replace one character by a
1657 match.
1658 {matches} must be a |List|. Each |List| item is one match.
1659 See |complete-items| for the kind of items that are possible.
1660 "longest" in 'completeopt' is ignored.
1661 Note that the after calling this function you need to avoid
1662 inserting anything that would cause completion to stop.
1663 The match can be selected with CTRL-N and CTRL-P as usual with
1664 Insert mode completion. The popup menu will appear if
1665 specified, see |ins-completion-menu|.
1666 Example: >
1667 inoremap <F5> <C-R>=ListMonths()<CR>
1668
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001669 func ListMonths()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001670 call complete(col('.'), ['January', 'February', 'March',
1671 \ 'April', 'May', 'June', 'July', 'August', 'September',
1672 \ 'October', 'November', 'December'])
1673 return ''
1674 endfunc
1675< This isn't very useful, but it shows how it works. Note that
1676 an empty string is returned to avoid a zero being inserted.
1677
1678 Can also be used as a |method|, the base is passed as the
1679 second argument: >
1680 GetMatches()->complete(col('.'))
1681
1682complete_add({expr}) *complete_add()*
1683 Add {expr} to the list of matches. Only to be used by the
1684 function specified with the 'completefunc' option.
1685 Returns 0 for failure (empty string or out of memory),
1686 1 when the match was added, 2 when the match was already in
1687 the list.
1688 See |complete-functions| for an explanation of {expr}. It is
1689 the same as one item in the list that 'omnifunc' would return.
1690
1691 Can also be used as a |method|: >
1692 GetMoreMatches()->complete_add()
1693
1694complete_check() *complete_check()*
1695 Check for a key typed while looking for completion matches.
1696 This is to be used when looking for matches takes some time.
1697 Returns |TRUE| when searching for matches is to be aborted,
1698 zero otherwise.
1699 Only to be used by the function specified with the
1700 'completefunc' option.
1701
1702
1703complete_info([{what}]) *complete_info()*
1704 Returns a |Dictionary| with information about Insert mode
1705 completion. See |ins-completion|.
1706 The items are:
1707 mode Current completion mode name string.
1708 See |complete_info_mode| for the values.
1709 pum_visible |TRUE| if popup menu is visible.
1710 See |pumvisible()|.
1711 items List of completion matches. Each item is a
1712 dictionary containing the entries "word",
1713 "abbr", "menu", "kind", "info" and "user_data".
1714 See |complete-items|.
1715 selected Selected item index. First index is zero.
1716 Index is -1 if no item is selected (showing
1717 typed text only, or the last completion after
1718 no item is selected when using the <Up> or
1719 <Down> keys)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01001720 inserted Inserted string. [NOT IMPLEMENTED YET]
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001721
1722 *complete_info_mode*
1723 mode values are:
1724 "" Not in completion mode
1725 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1726 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1727 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1728 |i_CTRL-X_CTRL-Y|
1729 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1730 "files" File names |i_CTRL-X_CTRL-F|
1731 "tags" Tags |i_CTRL-X_CTRL-]|
1732 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1733 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1734 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1735 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1736 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1737 "function" User defined completion |i_CTRL-X_CTRL-U|
1738 "omni" Omni completion |i_CTRL-X_CTRL-O|
1739 "spell" Spelling suggestions |i_CTRL-X_s|
1740 "eval" |complete()| completion
1741 "unknown" Other internal modes
1742
1743 If the optional {what} list argument is supplied, then only
1744 the items listed in {what} are returned. Unsupported items in
1745 {what} are silently ignored.
1746
1747 To get the position and size of the popup menu, see
1748 |pum_getpos()|. It's also available in |v:event| during the
1749 |CompleteChanged| event.
1750
Bram Moolenaar016188f2022-06-06 20:52:59 +01001751 Returns an empty |Dictionary| on error.
1752
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001753 Examples: >
1754 " Get all items
1755 call complete_info()
1756 " Get only 'mode'
1757 call complete_info(['mode'])
1758 " Get only 'mode' and 'pum_visible'
1759 call complete_info(['mode', 'pum_visible'])
1760
1761< Can also be used as a |method|: >
1762 GetItems()->complete_info()
1763<
1764 *confirm()*
1765confirm({msg} [, {choices} [, {default} [, {type}]]])
1766 confirm() offers the user a dialog, from which a choice can be
1767 made. It returns the number of the choice. For the first
1768 choice this is 1.
1769 Note: confirm() is only supported when compiled with dialog
1770 support, see |+dialog_con| and |+dialog_gui|.
1771
1772 {msg} is displayed in a |dialog| with {choices} as the
1773 alternatives. When {choices} is missing or empty, "&OK" is
1774 used (and translated).
1775 {msg} is a String, use '\n' to include a newline. Only on
1776 some systems the string is wrapped when it doesn't fit.
1777
1778 {choices} is a String, with the individual choices separated
1779 by '\n', e.g. >
1780 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1781< The letter after the '&' is the shortcut key for that choice.
1782 Thus you can type 'c' to select "Cancel". The shortcut does
1783 not need to be the first letter: >
1784 confirm("file has been modified", "&Save\nSave &All")
1785< For the console, the first letter of each choice is used as
1786 the default shortcut key. Case is ignored.
1787
1788 The optional {default} argument is the number of the choice
1789 that is made if the user hits <CR>. Use 1 to make the first
1790 choice the default one. Use 0 to not set a default. If
1791 {default} is omitted, 1 is used.
1792
1793 The optional {type} String argument gives the type of dialog.
1794 This is only used for the icon of the GTK, Mac, Motif and
1795 Win32 GUI. It can be one of these values: "Error",
1796 "Question", "Info", "Warning" or "Generic". Only the first
1797 character is relevant. When {type} is omitted, "Generic" is
1798 used.
1799
1800 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1801 or another valid interrupt key, confirm() returns 0.
1802
1803 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01001804 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001805 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01001806 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001807 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001808 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001809 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001810 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001811 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01001812 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001813< In a GUI dialog, buttons are used. The layout of the buttons
1814 depends on the 'v' flag in 'guioptions'. If it is included,
1815 the buttons are always put vertically. Otherwise, confirm()
1816 tries to put the buttons in one horizontal line. If they
1817 don't fit, a vertical layout is used anyway. For some systems
1818 the horizontal layout is always used.
1819
1820 Can also be used as a |method|in: >
1821 BuildMessage()->confirm("&Yes\n&No")
1822<
1823 *copy()*
1824copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1825 different from using {expr} directly.
1826 When {expr} is a |List| a shallow copy is created. This means
1827 that the original |List| can be changed without changing the
1828 copy, and vice versa. But the items are identical, thus
1829 changing an item changes the contents of both |Lists|.
1830 A |Dictionary| is copied in a similar way as a |List|.
1831 Also see |deepcopy()|.
1832 Can also be used as a |method|: >
1833 mylist->copy()
1834
1835cos({expr}) *cos()*
1836 Return the cosine of {expr}, measured in radians, as a |Float|.
1837 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001838 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001839 Examples: >
1840 :echo cos(100)
1841< 0.862319 >
1842 :echo cos(-4.01)
1843< -0.646043
1844
1845 Can also be used as a |method|: >
1846 Compute()->cos()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001847
1848
1849cosh({expr}) *cosh()*
1850 Return the hyperbolic cosine of {expr} as a |Float| in the range
1851 [1, inf].
1852 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001853 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001854 Examples: >
1855 :echo cosh(0.5)
1856< 1.127626 >
1857 :echo cosh(-0.5)
1858< -1.127626
1859
1860 Can also be used as a |method|: >
1861 Compute()->cosh()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001862
1863
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07001864count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001865 Return the number of times an item with value {expr} appears
1866 in |String|, |List| or |Dictionary| {comp}.
1867
1868 If {start} is given then start with the item with this index.
1869 {start} can only be used with a |List|.
1870
1871 When {ic} is given and it's |TRUE| then case is ignored.
1872
1873 When {comp} is a string then the number of not overlapping
1874 occurrences of {expr} is returned. Zero is returned when
1875 {expr} is an empty string.
1876
1877 Can also be used as a |method|: >
1878 mylist->count(val)
1879<
1880 *cscope_connection()*
1881cscope_connection([{num} , {dbpath} [, {prepend}]])
1882 Checks for the existence of a |cscope| connection. If no
1883 parameters are specified, then the function returns:
1884 0, if cscope was not available (not compiled in), or
1885 if there are no cscope connections;
1886 1, if there is at least one cscope connection.
1887
1888 If parameters are specified, then the value of {num}
1889 determines how existence of a cscope connection is checked:
1890
1891 {num} Description of existence check
1892 ----- ------------------------------
1893 0 Same as no parameters (e.g., "cscope_connection()").
1894 1 Ignore {prepend}, and use partial string matches for
1895 {dbpath}.
1896 2 Ignore {prepend}, and use exact string matches for
1897 {dbpath}.
1898 3 Use {prepend}, use partial string matches for both
1899 {dbpath} and {prepend}.
1900 4 Use {prepend}, use exact string matches for both
1901 {dbpath} and {prepend}.
1902
1903 Note: All string comparisons are case sensitive!
1904
1905 Examples. Suppose we had the following (from ":cs show"): >
1906
1907 # pid database name prepend path
1908 0 27664 cscope.out /usr/local
1909<
1910 Invocation Return Val ~
1911 ---------- ---------- >
1912 cscope_connection() 1
1913 cscope_connection(1, "out") 1
1914 cscope_connection(2, "out") 0
1915 cscope_connection(3, "out") 0
1916 cscope_connection(3, "out", "local") 1
1917 cscope_connection(4, "out") 0
1918 cscope_connection(4, "out", "local") 0
1919 cscope_connection(4, "cscope.out", "/usr/local") 1
1920<
1921cursor({lnum}, {col} [, {off}]) *cursor()*
1922cursor({list})
1923 Positions the cursor at the column (byte count) {col} in the
1924 line {lnum}. The first column is one.
1925
1926 When there is one argument {list} this is used as a |List|
1927 with two, three or four item:
1928 [{lnum}, {col}]
1929 [{lnum}, {col}, {off}]
1930 [{lnum}, {col}, {off}, {curswant}]
1931 This is like the return value of |getpos()| or |getcurpos()|,
1932 but without the first item.
1933
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001934 To position the cursor using {col} as the character count, use
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001935 |setcursorcharpos()|.
1936
1937 Does not change the jumplist.
Bram Moolenaar7c6cd442022-10-11 21:54:04 +01001938 {lnum} is used like with |getline()|, except that if {lnum} is
1939 zero, the cursor will stay in the current line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001940 If {lnum} is greater than the number of lines in the buffer,
1941 the cursor will be positioned at the last line in the buffer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001942 If {col} is greater than the number of bytes in the line,
1943 the cursor will be positioned at the last character in the
1944 line.
1945 If {col} is zero, the cursor will stay in the current column.
1946 If {curswant} is given it is used to set the preferred column
1947 for vertical movement. Otherwise {col} is used.
1948
1949 When 'virtualedit' is used {off} specifies the offset in
1950 screen columns from the start of the character. E.g., a
1951 position within a <Tab> or after the last character.
1952 Returns 0 when the position could be set, -1 otherwise.
1953
1954 Can also be used as a |method|: >
1955 GetCursorPos()->cursor()
1956
1957debugbreak({pid}) *debugbreak()*
1958 Specifically used to interrupt a program being debugged. It
1959 will cause process {pid} to get a SIGTRAP. Behavior for other
1960 processes is undefined. See |terminal-debugger|.
1961 {only available on MS-Windows}
1962
Bram Moolenaar016188f2022-06-06 20:52:59 +01001963 Returns |TRUE| if successfully interrupted the program.
1964 Otherwise returns |FALSE|.
1965
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001966 Can also be used as a |method|: >
1967 GetPid()->debugbreak()
1968
1969deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
1970 Make a copy of {expr}. For Numbers and Strings this isn't
1971 different from using {expr} directly.
1972 When {expr} is a |List| a full copy is created. This means
1973 that the original |List| can be changed without changing the
1974 copy, and vice versa. When an item is a |List| or
1975 |Dictionary|, a copy for it is made, recursively. Thus
1976 changing an item in the copy does not change the contents of
1977 the original |List|.
1978 A |Dictionary| is copied in a similar way as a |List|.
1979
1980 When {noref} is omitted or zero a contained |List| or
1981 |Dictionary| is only copied once. All references point to
1982 this single copy. With {noref} set to 1 every occurrence of a
1983 |List| or |Dictionary| results in a new copy. This also means
1984 that a cyclic reference causes deepcopy() to fail.
1985 *E724*
1986 Nesting is possible up to 100 levels. When there is an item
1987 that refers back to a higher level making a deep copy with
1988 {noref} set to 1 will fail.
1989 Also see |copy()|.
1990
1991 Can also be used as a |method|: >
1992 GetObject()->deepcopy()
1993
1994delete({fname} [, {flags}]) *delete()*
1995 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001996 name {fname}.
1997
1998 This also works when {fname} is a symbolic link. The symbolic
1999 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002000
2001 When {flags} is "d": Deletes the directory by the name
2002 {fname}. This fails when directory {fname} is not empty.
2003
2004 When {flags} is "rf": Deletes the directory by the name
2005 {fname} and everything in it, recursively. BE CAREFUL!
2006 Note: on MS-Windows it is not possible to delete a directory
2007 that is being used.
2008
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002009 The result is a Number, which is 0/false if the delete
2010 operation was successful and -1/true when the deletion failed
2011 or partly failed.
2012
2013 Use |remove()| to delete an item from a |List|.
2014 To delete a line from the buffer use |:delete| or
2015 |deletebufline()|.
2016
2017 Can also be used as a |method|: >
2018 GetName()->delete()
2019
2020deletebufline({buf}, {first} [, {last}]) *deletebufline()*
2021 Delete lines {first} to {last} (inclusive) from buffer {buf}.
2022 If {last} is omitted then delete line {first} only.
2023 On success 0 is returned, on failure 1 is returned.
2024
2025 This function works only for loaded buffers. First call
2026 |bufload()| if needed.
2027
2028 For the use of {buf}, see |bufname()| above.
2029
2030 {first} and {last} are used like with |getline()|. Note that
2031 when using |line()| this refers to the current buffer. Use "$"
2032 to refer to the last line in buffer {buf}.
2033
2034 Can also be used as a |method|: >
2035 GetBuffer()->deletebufline(1)
2036<
2037 *did_filetype()*
2038did_filetype() Returns |TRUE| when autocommands are being executed and the
2039 FileType event has been triggered at least once. Can be used
2040 to avoid triggering the FileType event again in the scripts
2041 that detect the file type. |FileType|
2042 Returns |FALSE| when `:setf FALLBACK` was used.
2043 When editing another file, the counter is reset, thus this
2044 really checks if the FileType event has been triggered for the
2045 current buffer. This allows an autocommand that starts
2046 editing another buffer to set 'filetype' and load a syntax
2047 file.
2048
2049diff_filler({lnum}) *diff_filler()*
2050 Returns the number of filler lines above line {lnum}.
2051 These are the lines that were inserted at this point in
2052 another diff'ed window. These filler lines are shown in the
2053 display but don't exist in the buffer.
2054 {lnum} is used like with |getline()|. Thus "." is the current
2055 line, "'m" mark m, etc.
2056 Returns 0 if the current window is not in diff mode.
2057
2058 Can also be used as a |method|: >
2059 GetLnum()->diff_filler()
2060
2061diff_hlID({lnum}, {col}) *diff_hlID()*
2062 Returns the highlight ID for diff mode at line {lnum} column
2063 {col} (byte index). When the current line does not have a
2064 diff change zero is returned.
2065 {lnum} is used like with |getline()|. Thus "." is the current
2066 line, "'m" mark m, etc.
2067 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2068 line.
2069 The highlight ID can be used with |synIDattr()| to obtain
2070 syntax information about the highlighting.
2071
2072 Can also be used as a |method|: >
2073 GetLnum()->diff_hlID(col)
2074<
2075
2076digraph_get({chars}) *digraph_get()* *E1214*
2077 Return the digraph of {chars}. This should be a string with
2078 exactly two characters. If {chars} are not just two
2079 characters, or the digraph of {chars} does not exist, an error
2080 is given and an empty string is returned.
2081
2082 The character will be converted from Unicode to 'encoding'
2083 when needed. This does require the conversion to be
2084 available, it might fail.
2085
2086 Also see |digraph_getlist()|.
2087
2088 Examples: >
2089 " Get a built-in digraph
2090 :echo digraph_get('00') " Returns '∞'
2091
2092 " Get a user-defined digraph
2093 :call digraph_set('aa', 'あ')
2094 :echo digraph_get('aa') " Returns 'あ'
2095<
2096 Can also be used as a |method|: >
2097 GetChars()->digraph_get()
2098<
2099 This function works only when compiled with the |+digraphs|
2100 feature. If this feature is disabled, this function will
2101 display an error message.
2102
2103
2104digraph_getlist([{listall}]) *digraph_getlist()*
2105 Return a list of digraphs. If the {listall} argument is given
2106 and it is TRUE, return all digraphs, including the default
2107 digraphs. Otherwise, return only user-defined digraphs.
2108
2109 The characters will be converted from Unicode to 'encoding'
2110 when needed. This does require the conservation to be
2111 available, it might fail.
2112
2113 Also see |digraph_get()|.
2114
2115 Examples: >
2116 " Get user-defined digraphs
2117 :echo digraph_getlist()
2118
2119 " Get all the digraphs, including default digraphs
2120 :echo digraph_getlist(1)
2121<
2122 Can also be used as a |method|: >
2123 GetNumber()->digraph_getlist()
2124<
2125 This function works only when compiled with the |+digraphs|
2126 feature. If this feature is disabled, this function will
2127 display an error message.
2128
2129
Bram Moolenaara2baa732022-02-04 16:09:54 +00002130digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002131 Add digraph {chars} to the list. {chars} must be a string
2132 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002133 encoded character. *E1215*
2134 Be careful, composing characters are NOT ignored. This
2135 function is similar to |:digraphs| command, but useful to add
2136 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002137
2138 The function result is v:true if |digraph| is registered. If
2139 this fails an error message is given and v:false is returned.
2140
2141 If you want to define multiple digraphs at once, you can use
2142 |digraph_setlist()|.
2143
2144 Example: >
2145 call digraph_set(' ', 'あ')
2146<
2147 Can be used as a |method|: >
2148 GetString()->digraph_set('あ')
2149<
2150 This function works only when compiled with the |+digraphs|
2151 feature. If this feature is disabled, this function will
2152 display an error message.
2153
2154
2155digraph_setlist({digraphlist}) *digraph_setlist()*
2156 Similar to |digraph_set()| but this function can add multiple
2157 digraphs at once. {digraphlist} is a list composed of lists,
2158 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002159 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002160 Example: >
2161 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2162<
2163 It is similar to the following: >
2164 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2165 call digraph_set(chars, digraph)
2166 endfor
2167< Except that the function returns after the first error,
2168 following digraphs will not be added.
2169
2170 Can be used as a |method|: >
2171 GetList()->digraph_setlist()
2172<
2173 This function works only when compiled with the |+digraphs|
2174 feature. If this feature is disabled, this function will
2175 display an error message.
2176
2177
2178echoraw({string}) *echoraw()*
2179 Output {string} as-is, including unprintable characters.
2180 This can be used to output a terminal code. For example, to
2181 disable modifyOtherKeys: >
2182 call echoraw(&t_TE)
2183< and to enable it again: >
2184 call echoraw(&t_TI)
2185< Use with care, you can mess up the terminal this way.
2186
2187
2188empty({expr}) *empty()*
2189 Return the Number 1 if {expr} is empty, zero otherwise.
2190 - A |List| or |Dictionary| is empty when it does not have any
2191 items.
2192 - A |String| is empty when its length is zero.
2193 - A |Number| and |Float| are empty when their value is zero.
2194 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2195 - A |Job| is empty when it failed to start.
2196 - A |Channel| is empty when it is closed.
2197 - A |Blob| is empty when its length is zero.
2198
2199 For a long |List| this is much faster than comparing the
2200 length with zero.
2201
2202 Can also be used as a |method|: >
2203 mylist->empty()
2204
2205environ() *environ()*
2206 Return all of environment variables as dictionary. You can
2207 check if an environment variable exists like this: >
2208 :echo has_key(environ(), 'HOME')
2209< Note that the variable name may be CamelCase; to ignore case
2210 use this: >
2211 :echo index(keys(environ()), 'HOME', 0, 1) != -1
2212
Bram Moolenaar416bd912023-07-07 23:19:18 +01002213
2214err_teapot([{expr}]) *err_teapot()*
2215 Produce an error with number 418, needed for implementation of
Christian Brabandtee17b6f2023-09-09 11:23:50 +02002216 RFC 2324.
Bram Moolenaar416bd912023-07-07 23:19:18 +01002217 If {expr} is present and it is TRUE error 503 is given,
2218 indicating that coffee is temporarily not available.
2219 If {expr} is present it must be a String.
2220
2221
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002222escape({string}, {chars}) *escape()*
2223 Escape the characters in {chars} that occur in {string} with a
2224 backslash. Example: >
2225 :echo escape('c:\program files\vim', ' \')
2226< results in: >
2227 c:\\program\ files\\vim
2228< Also see |shellescape()| and |fnameescape()|.
2229
2230 Can also be used as a |method|: >
2231 GetText()->escape(' \')
2232<
2233 *eval()*
2234eval({string}) Evaluate {string} and return the result. Especially useful to
2235 turn the result of |string()| back into the original value.
2236 This works for Numbers, Floats, Strings, Blobs and composites
2237 of them. Also works for |Funcref|s that refer to existing
2238 functions.
2239
2240 Can also be used as a |method|: >
2241 argv->join()->eval()
2242
2243eventhandler() *eventhandler()*
2244 Returns 1 when inside an event handler. That is that Vim got
2245 interrupted while waiting for the user to type a character,
2246 e.g., when dropping a file on Vim. This means interactive
2247 commands cannot be used. Otherwise zero is returned.
2248
2249executable({expr}) *executable()*
2250 This function checks if an executable with the name {expr}
2251 exists. {expr} must be the name of the program without any
2252 arguments.
2253 executable() uses the value of $PATH and/or the normal
2254 searchpath for programs. *PATHEXT*
2255 On MS-Windows the ".exe", ".bat", etc. can optionally be
2256 included. Then the extensions in $PATHEXT are tried. Thus if
2257 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2258 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2259 by itself can be used in $PATHEXT to try using the name
2260 without an extension. When 'shell' looks like a Unix shell,
2261 then the name is also tried without adding an extension.
2262 On MS-Windows it only checks if the file exists and is not a
2263 directory, not if it's really executable.
2264 On MS-Windows an executable in the same directory as Vim is
Yasuhiro Matsumoto05cf63e2022-05-03 11:02:28 +01002265 normally found. Since this directory is added to $PATH it
2266 should also work to execute it |win32-PATH|. This can be
2267 disabled by setting the $NoDefaultCurrentDirectoryInExePath
2268 environment variable. *NoDefaultCurrentDirectoryInExePath*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002269 The result is a Number:
2270 1 exists
2271 0 does not exist
2272 -1 not implemented on this system
2273 |exepath()| can be used to get the full path of an executable.
2274
2275 Can also be used as a |method|: >
2276 GetCommand()->executable()
2277
2278execute({command} [, {silent}]) *execute()*
2279 Execute an Ex command or commands and return the output as a
2280 string.
2281 {command} can be a string or a List. In case of a List the
2282 lines are executed one by one.
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002283 This is more or less equivalent to: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002284 redir => var
2285 {command}
2286 redir END
Bram Moolenaar71badf92023-04-22 22:40:14 +01002287< Except that line continuation in {command} is not recognized.
2288
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002289 The optional {silent} argument can have these values:
2290 "" no `:silent` used
2291 "silent" `:silent` used
2292 "silent!" `:silent!` used
2293 The default is "silent". Note that with "silent!", unlike
2294 `:redir`, error messages are dropped. When using an external
2295 command the screen may be messed up, use `system()` instead.
2296 *E930*
2297 It is not possible to use `:redir` anywhere in {command}.
2298
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002299 To get a list of lines use `split()` on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002300 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002301
2302< To execute a command in another window than the current one
2303 use `win_execute()`.
2304
2305 When used recursively the output of the recursive call is not
2306 included in the output of the higher level call.
2307
2308 Can also be used as a |method|: >
2309 GetCommand()->execute()
2310
2311exepath({expr}) *exepath()*
2312 If {expr} is an executable and is either an absolute path, a
2313 relative path or found in $PATH, return the full path.
2314 Note that the current directory is used when {expr} starts
2315 with "./", which may be a problem for Vim: >
2316 echo exepath(v:progpath)
2317< If {expr} cannot be found in $PATH or is not executable then
2318 an empty string is returned.
2319
2320 Can also be used as a |method|: >
2321 GetCommand()->exepath()
2322<
2323 *exists()*
2324exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
2325 zero otherwise.
2326
2327 Note: In a compiled |:def| function the evaluation is done at
2328 runtime. Use `exists_compiled()` to evaluate the expression
2329 at compile time.
2330
2331 For checking for a supported feature use |has()|.
2332 For checking if a file exists use |filereadable()|.
2333
2334 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002335 varname internal variable (see
2336 dict.key |internal-variables|). Also works
2337 list[i] for |curly-braces-names|, |Dictionary|
2338 import.Func entries, |List| items, imported
Bram Moolenaar944697a2022-02-20 19:48:20 +00002339 items, etc.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002340 Does not work for local variables in a
2341 compiled `:def` function.
Bram Moolenaar944697a2022-02-20 19:48:20 +00002342 Also works for a function in |Vim9|
2343 script, since it can be used as a
2344 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002345 Beware that evaluating an index may
2346 cause an error message for an invalid
2347 expression. E.g.: >
2348 :let l = [1, 2, 3]
2349 :echo exists("l[5]")
2350< 0 >
2351 :echo exists("l[xx]")
2352< E121: Undefined variable: xx
2353 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002354 &option-name Vim option (only checks if it exists,
2355 not if it really works)
2356 +option-name Vim option that works.
2357 $ENVNAME environment variable (could also be
2358 done by comparing with an empty
2359 string)
2360 *funcname built-in function (see |functions|)
2361 or user defined function (see
2362 |user-functions|) that is implemented.
2363 Also works for a variable that is a
2364 Funcref.
2365 ?funcname built-in function that could be
2366 implemented; to be used to check if
2367 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002368 :cmdname Ex command: built-in command, user
2369 command or command modifier |:command|.
2370 Returns:
2371 1 for match with start of a command
2372 2 full match with a command
2373 3 matches several user commands
2374 To check for a supported command
2375 always check the return value to be 2.
2376 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002377 :3match The |:3match| command (but you
2378 probably should not use it, it is
2379 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002380 #event autocommand defined for this event
2381 #event#pattern autocommand defined for this event and
2382 pattern (the pattern is taken
2383 literally and compared to the
2384 autocommand patterns character by
2385 character)
2386 #group autocommand group exists
2387 #group#event autocommand defined for this group and
2388 event.
2389 #group#event#pattern
2390 autocommand defined for this group,
2391 event and pattern.
2392 ##event autocommand for this event is
2393 supported.
2394
2395 Examples: >
2396 exists("&shortname")
2397 exists("$HOSTNAME")
2398 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002399 exists("*s:MyFunc") " only for legacy script
2400 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002401 exists("bufcount")
2402 exists(":Make")
2403 exists("#CursorHold")
2404 exists("#BufReadPre#*.gz")
2405 exists("#filetypeindent")
2406 exists("#filetypeindent#FileType")
2407 exists("#filetypeindent#FileType#*")
2408 exists("##ColorScheme")
2409< There must be no space between the symbol (&/$/*/#) and the
2410 name.
2411 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002412 a few cases this is ignored. That may become stricter in the
2413 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002414 Working example: >
2415 exists(":make")
2416< NOT working example: >
2417 exists(":make install")
2418
2419< Note that the argument must be a string, not the name of the
2420 variable itself. For example: >
2421 exists(bufcount)
2422< This doesn't check for existence of the "bufcount" variable,
2423 but gets the value of "bufcount", and checks if that exists.
2424
2425 Can also be used as a |method|: >
2426 Varname()->exists()
2427<
2428
2429exists_compiled({expr}) *exists_compiled()*
2430 Like `exists()` but evaluated at compile time. This is useful
2431 to skip a block where a function is used that would otherwise
2432 give an error: >
2433 if exists_compiled('*ThatFunction')
2434 ThatFunction('works')
2435 endif
2436< If `exists()` were used then a compilation error would be
2437 given if ThatFunction() is not defined.
2438
2439 {expr} must be a literal string. *E1232*
2440 Can only be used in a |:def| function. *E1233*
2441 This does not work to check for arguments or local variables.
2442
2443
2444exp({expr}) *exp()*
2445 Return the exponential of {expr} as a |Float| in the range
2446 [0, inf].
2447 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002448 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002449 Examples: >
2450 :echo exp(2)
2451< 7.389056 >
2452 :echo exp(-1)
2453< 0.367879
2454
2455 Can also be used as a |method|: >
2456 Compute()->exp()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002457
2458
2459expand({string} [, {nosuf} [, {list}]]) *expand()*
2460 Expand wildcards and the following special keywords in
2461 {string}. 'wildignorecase' applies.
2462
2463 If {list} is given and it is |TRUE|, a List will be returned.
2464 Otherwise the result is a String and when there are several
2465 matches, they are separated by <NL> characters. [Note: in
2466 version 5.0 a space was used, which caused problems when a
2467 file name contains a space]
2468
2469 If the expansion fails, the result is an empty string. A name
2470 for a non-existing file is not included, unless {string} does
2471 not start with '%', '#' or '<', see below.
2472
2473 When {string} starts with '%', '#' or '<', the expansion is
2474 done like for the |cmdline-special| variables with their
2475 associated modifiers. Here is a short overview:
2476
2477 % current file name
2478 # alternate file name
2479 #n alternate file name n
2480 <cfile> file name under the cursor
2481 <afile> autocmd file name
2482 <abuf> autocmd buffer number (as a String!)
2483 <amatch> autocmd matched name
2484 <cexpr> C expression under the cursor
2485 <sfile> sourced script file or function name
2486 <slnum> sourced script line number or function
2487 line number
2488 <sflnum> script file line number, also when in
2489 a function
2490 <SID> "<SNR>123_" where "123" is the
2491 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002492 <script> sourced script file, or script file
2493 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002494 <stack> call stack
2495 <cword> word under the cursor
2496 <cWORD> WORD under the cursor
2497 <client> the {clientid} of the last received
2498 message |server2client()|
2499 Modifiers:
2500 :p expand to full path
2501 :h head (last path component removed)
2502 :t tail (last path component only)
2503 :r root (one extension removed)
2504 :e extension only
2505
2506 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002507 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002508< Note that when expanding a string that starts with '%', '#' or
2509 '<', any following text is ignored. This does NOT work: >
2510 :let doesntwork = expand("%:h.bak")
2511< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002512 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002513< Also note that expanding "<cfile>" and others only returns the
2514 referenced file name without further expansion. If "<cfile>"
2515 is "~/.cshrc", you need to do another expand() to have the
2516 "~/" expanded into the path of the home directory: >
2517 :echo expand(expand("<cfile>"))
2518<
2519 There cannot be white space between the variables and the
2520 following modifier. The |fnamemodify()| function can be used
2521 to modify normal file names.
2522
2523 When using '%' or '#', and the current or alternate file name
2524 is not defined, an empty string is used. Using "%:p" in a
2525 buffer with no name, results in the current directory, with a
2526 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01002527 When 'verbose' is set then expanding '%', '#' and <> items
2528 will result in an error message if the argument cannot be
2529 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002530
2531 When {string} does not start with '%', '#' or '<', it is
2532 expanded like a file name is expanded on the command line.
2533 'suffixes' and 'wildignore' are used, unless the optional
2534 {nosuf} argument is given and it is |TRUE|.
2535 Names for non-existing files are included. The "**" item can
2536 be used to search in a directory tree. For example, to find
2537 all "README" files in the current directory and below: >
2538 :echo expand("**/README")
2539<
2540 expand() can also be used to expand variables and environment
2541 variables that are only known in a shell. But this can be
2542 slow, because a shell may be used to do the expansion. See
2543 |expr-env-expand|.
2544 The expanded variable is still handled like a list of file
2545 names. When an environment variable cannot be expanded, it is
2546 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2547 "$FOOBAR".
2548
2549 See |glob()| for finding existing files. See |system()| for
2550 getting the raw output of an external command.
2551
2552 Can also be used as a |method|: >
2553 Getpattern()->expand()
2554
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002555expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002556 Expand special items in String {string} like what is done for
2557 an Ex command such as `:edit`. This expands special keywords,
2558 like with |expand()|, and environment variables, anywhere in
2559 {string}. "~user" and "~/path" are only expanded at the
2560 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002561
2562 The following items are supported in the {options} Dict
2563 argument:
2564 errmsg If set to TRUE, error messages are displayed
2565 if an error is encountered during expansion.
2566 By default, error messages are not displayed.
2567
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002568 Returns the expanded string. If an error is encountered
2569 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002570
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002571 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002572 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002573 make /path/runtime/doc/builtin.o
2574 :echo expandcmd('make %<.o', {'errmsg': v:true})
2575<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002576 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002577 GetCommand()->expandcmd()
2578<
2579extend({expr1}, {expr2} [, {expr3}]) *extend()*
2580 {expr1} and {expr2} must be both |Lists| or both
2581 |Dictionaries|.
2582
2583 If they are |Lists|: Append {expr2} to {expr1}.
2584 If {expr3} is given insert the items of {expr2} before the
2585 item with index {expr3} in {expr1}. When {expr3} is zero
2586 insert before the first item. When {expr3} is equal to
2587 len({expr1}) then {expr2} is appended.
2588 Examples: >
2589 :echo sort(extend(mylist, [7, 5]))
2590 :call extend(mylist, [2, 3], 1)
2591< When {expr1} is the same List as {expr2} then the number of
2592 items copied is equal to the original length of the List.
2593 E.g., when {expr3} is 1 you get N new copies of the first item
2594 (where N is the original length of the List).
2595 Use |add()| to concatenate one item to a list. To concatenate
2596 two lists into a new list use the + operator: >
2597 :let newlist = [1, 2, 3] + [4, 5]
2598<
2599 If they are |Dictionaries|:
2600 Add all entries from {expr2} to {expr1}.
2601 If a key exists in both {expr1} and {expr2} then {expr3} is
2602 used to decide what to do:
2603 {expr3} = "keep": keep the value of {expr1}
2604 {expr3} = "force": use the value of {expr2}
2605 {expr3} = "error": give an error message *E737*
2606 When {expr3} is omitted then "force" is assumed.
2607
2608 {expr1} is changed when {expr2} is not empty. If necessary
2609 make a copy of {expr1} first.
2610 {expr2} remains unchanged.
2611 When {expr1} is locked and {expr2} is not empty the operation
2612 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002613 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002614
2615 Can also be used as a |method|: >
2616 mylist->extend(otherlist)
2617
2618
2619extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2620 Like |extend()| but instead of adding items to {expr1} a new
2621 List or Dictionary is created and returned. {expr1} remains
Bram Moolenaardd60c362023-02-27 15:49:53 +00002622 unchanged.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002623
2624
2625feedkeys({string} [, {mode}]) *feedkeys()*
2626 Characters in {string} are queued for processing as if they
2627 come from a mapping or were typed by the user.
2628
2629 By default the string is added to the end of the typeahead
2630 buffer, thus if a mapping is still being executed the
2631 characters come after them. Use the 'i' flag to insert before
2632 other characters, they will be executed next, before any
2633 characters from a mapping.
2634
2635 The function does not wait for processing of keys contained in
2636 {string}.
2637
2638 To include special keys into {string}, use double-quotes
2639 and "\..." notation |expr-quote|. For example,
2640 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2641 feedkeys('\<CR>') pushes 5 characters.
2642 A special code that might be useful is <Ignore>, it exits the
2643 wait for a character without doing anything. *<Ignore>*
2644
2645 {mode} is a String, which can contain these character flags:
2646 'm' Remap keys. This is default. If {mode} is absent,
2647 keys are remapped.
2648 'n' Do not remap keys.
2649 't' Handle keys as if typed; otherwise they are handled as
2650 if coming from a mapping. This matters for undo,
2651 opening folds, etc.
2652 'L' Lowlevel input. Only works for Unix or when using the
2653 GUI. Keys are used as if they were coming from the
2654 terminal. Other flags are not used. *E980*
2655 When a CTRL-C interrupts and 't' is included it sets
2656 the internal "got_int" flag.
2657 'i' Insert the string instead of appending (see above).
2658 'x' Execute commands until typeahead is empty. This is
2659 similar to using ":normal!". You can call feedkeys()
2660 several times without 'x' and then one time with 'x'
2661 (possibly with an empty {string}) to execute all the
2662 typeahead. Note that when Vim ends in Insert mode it
2663 will behave as if <Esc> is typed, to avoid getting
2664 stuck, waiting for a character to be typed before the
2665 script continues.
2666 Note that if you manage to call feedkeys() while
2667 executing commands, thus calling it recursively, then
2668 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00002669 'c' Remove any script context when executing, so that
2670 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01002671 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01002672 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002673 '!' When used with 'x' will not end Insert mode. Can be
2674 used in a test when a timer is set to exit Insert mode
2675 a little later. Useful for testing CursorHoldI.
2676
2677 Return value is always 0.
2678
2679 Can also be used as a |method|: >
2680 GetInput()->feedkeys()
2681
2682filereadable({file}) *filereadable()*
2683 The result is a Number, which is |TRUE| when a file with the
2684 name {file} exists, and can be read. If {file} doesn't exist,
2685 or is a directory, the result is |FALSE|. {file} is any
2686 expression, which is used as a String.
2687 If you don't care about the file being readable you can use
2688 |glob()|.
2689 {file} is used as-is, you may want to expand wildcards first: >
2690 echo filereadable('~/.vimrc')
2691 0
2692 echo filereadable(expand('~/.vimrc'))
2693 1
2694
2695< Can also be used as a |method|: >
2696 GetName()->filereadable()
2697< *file_readable()*
2698 Obsolete name: file_readable().
2699
2700
2701filewritable({file}) *filewritable()*
2702 The result is a Number, which is 1 when a file with the
2703 name {file} exists, and can be written. If {file} doesn't
2704 exist, or is not writable, the result is 0. If {file} is a
2705 directory, and we can write to it, the result is 2.
2706
2707 Can also be used as a |method|: >
2708 GetName()->filewritable()
2709
2710
2711filter({expr1}, {expr2}) *filter()*
2712 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
2713 For each item in {expr1} evaluate {expr2} and when the result
2714 is zero or false remove the item from the |List| or
2715 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002716 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002717
2718 {expr2} must be a |string| or |Funcref|.
2719
2720 If {expr2} is a |string|, inside {expr2} |v:val| has the value
2721 of the current item. For a |Dictionary| |v:key| has the key
2722 of the current item and for a |List| |v:key| has the index of
2723 the current item. For a |Blob| |v:key| has the index of the
2724 current byte. For a |String| |v:key| has the index of the
2725 current character.
2726 Examples: >
2727 call filter(mylist, 'v:val !~ "OLD"')
2728< Removes the items where "OLD" appears. >
2729 call filter(mydict, 'v:key >= 8')
2730< Removes the items with a key below 8. >
2731 call filter(var, 0)
2732< Removes all the items, thus clears the |List| or |Dictionary|.
2733
2734 Note that {expr2} is the result of expression and is then
2735 used as an expression again. Often it is good to use a
2736 |literal-string| to avoid having to double backslashes.
2737
2738 If {expr2} is a |Funcref| it must take two arguments:
2739 1. the key or the index of the current item.
2740 2. the value of the current item.
2741 The function must return |TRUE| if the item should be kept.
2742 Example that keeps the odd items of a list: >
2743 func Odd(idx, val)
2744 return a:idx % 2 == 1
2745 endfunc
2746 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002747< It is shorter when using a |lambda|. In |Vim9| syntax: >
2748 call filter(myList, (idx, val) => idx * val <= 42)
2749< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002750 call filter(myList, {idx, val -> idx * val <= 42})
2751< If you do not use "val" you can leave it out: >
2752 call filter(myList, {idx -> idx % 2 == 1})
2753<
2754 In |Vim9| script the result must be true, false, zero or one.
2755 Other values will result in a type error.
2756
2757 For a |List| and a |Dictionary| the operation is done
2758 in-place. If you want it to remain unmodified make a copy
2759 first: >
2760 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2761
2762< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00002763 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002764 When an error is encountered while evaluating {expr2} no
2765 further items in {expr1} are processed.
2766 When {expr2} is a Funcref errors inside a function are ignored,
2767 unless it was defined with the "abort" flag.
2768
2769 Can also be used as a |method|: >
2770 mylist->filter(expr2)
2771
2772finddir({name} [, {path} [, {count}]]) *finddir()*
2773 Find directory {name} in {path}. Supports both downwards and
2774 upwards recursive directory searches. See |file-searching|
2775 for the syntax of {path}.
2776
2777 Returns the path of the first found match. When the found
2778 directory is below the current directory a relative path is
2779 returned. Otherwise a full path is returned.
2780 If {path} is omitted or empty then 'path' is used.
2781
2782 If the optional {count} is given, find {count}'s occurrence of
2783 {name} in {path} instead of the first one.
2784 When {count} is negative return all the matches in a |List|.
2785
Bram Moolenaar016188f2022-06-06 20:52:59 +01002786 Returns an empty string if the directory is not found.
2787
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002788 This is quite similar to the ex-command `:find`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002789
2790 Can also be used as a |method|: >
2791 GetName()->finddir()
2792
2793findfile({name} [, {path} [, {count}]]) *findfile()*
2794 Just like |finddir()|, but find a file instead of a directory.
2795 Uses 'suffixesadd'.
2796 Example: >
2797 :echo findfile("tags.vim", ".;")
2798< Searches from the directory of the current file upwards until
2799 it finds the file "tags.vim".
2800
2801 Can also be used as a |method|: >
2802 GetName()->findfile()
2803
2804flatten({list} [, {maxdepth}]) *flatten()*
2805 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
2806 the result is a |List| without nesting, as if {maxdepth} is
2807 a very large number.
2808 The {list} is changed in place, use |flattennew()| if you do
2809 not want that.
2810 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00002811 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002812 *E900*
2813 {maxdepth} means how deep in nested lists changes are made.
2814 {list} is not modified when {maxdepth} is 0.
2815 {maxdepth} must be positive number.
2816
2817 If there is an error the number zero is returned.
2818
2819 Example: >
2820 :echo flatten([1, [2, [3, 4]], 5])
2821< [1, 2, 3, 4, 5] >
2822 :echo flatten([1, [2, [3, 4]], 5], 1)
2823< [1, 2, [3, 4], 5]
2824
2825 Can also be used as a |method|: >
2826 mylist->flatten()
2827<
2828flattennew({list} [, {maxdepth}]) *flattennew()*
2829 Like |flatten()| but first make a copy of {list}.
2830
2831
2832float2nr({expr}) *float2nr()*
2833 Convert {expr} to a Number by omitting the part after the
2834 decimal point.
Bram Moolenaar76db9e02022-11-09 21:21:04 +00002835 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002836 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002837 When the value of {expr} is out of range for a |Number| the
2838 result is truncated to 0x7fffffff or -0x7fffffff (or when
2839 64-bit Number support is enabled, 0x7fffffffffffffff or
2840 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
2841 64-bit Number support is enabled, -0x8000000000000000).
2842 Examples: >
2843 echo float2nr(3.95)
2844< 3 >
2845 echo float2nr(-23.45)
2846< -23 >
2847 echo float2nr(1.0e100)
2848< 2147483647 (or 9223372036854775807) >
2849 echo float2nr(-1.0e150)
2850< -2147483647 (or -9223372036854775807) >
2851 echo float2nr(1.0e-100)
2852< 0
2853
2854 Can also be used as a |method|: >
2855 Compute()->float2nr()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002856
2857
2858floor({expr}) *floor()*
2859 Return the largest integral value less than or equal to
2860 {expr} as a |Float| (round down).
2861 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002862 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002863 Examples: >
2864 echo floor(1.856)
2865< 1.0 >
2866 echo floor(-5.456)
2867< -6.0 >
2868 echo floor(4.0)
2869< 4.0
2870
2871 Can also be used as a |method|: >
2872 Compute()->floor()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002873
2874
2875fmod({expr1}, {expr2}) *fmod()*
2876 Return the remainder of {expr1} / {expr2}, even if the
2877 division is not representable. Returns {expr1} - i * {expr2}
2878 for some integer i such that if {expr2} is non-zero, the
2879 result has the same sign as {expr1} and magnitude less than
2880 the magnitude of {expr2}. If {expr2} is zero, the value
2881 returned is zero. The value returned is a |Float|.
2882 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002883 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
2884 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002885 Examples: >
2886 :echo fmod(12.33, 1.22)
2887< 0.13 >
2888 :echo fmod(-12.33, 1.22)
2889< -0.13
2890
2891 Can also be used as a |method|: >
2892 Compute()->fmod(1.22)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002893
2894
2895fnameescape({string}) *fnameescape()*
2896 Escape {string} for use as file name command argument. All
2897 characters that have a special meaning, such as '%' and '|'
2898 are escaped with a backslash.
2899 For most systems the characters escaped are
2900 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2901 appears in a filename, it depends on the value of 'isfname'.
2902 A leading '+' and '>' is also escaped (special after |:edit|
2903 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01002904 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002905 Example: >
2906 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002907 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002908< results in executing: >
2909 edit \+some\ str\%nge\|name
2910<
2911 Can also be used as a |method|: >
2912 GetName()->fnameescape()
2913
2914fnamemodify({fname}, {mods}) *fnamemodify()*
2915 Modify file name {fname} according to {mods}. {mods} is a
2916 string of characters like it is used for file names on the
2917 command line. See |filename-modifiers|.
2918 Example: >
2919 :echo fnamemodify("main.c", ":p:h")
2920< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01002921 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01002922< If {mods} is empty or an unsupported modifier is used then
2923 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01002924 When {fname} is empty then with {mods} ":h" returns ".", so
2925 that `:cd` can be used with it. This is different from
2926 expand('%:h') without a buffer name, which returns an empty
2927 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002928 Note: Environment variables don't work in {fname}, use
2929 |expand()| first then.
2930
2931 Can also be used as a |method|: >
2932 GetName()->fnamemodify(':p:h')
2933
2934foldclosed({lnum}) *foldclosed()*
2935 The result is a Number. If the line {lnum} is in a closed
2936 fold, the result is the number of the first line in that fold.
2937 If the line {lnum} is not in a closed fold, -1 is returned.
2938 {lnum} is used like with |getline()|. Thus "." is the current
2939 line, "'m" mark m, etc.
2940
2941 Can also be used as a |method|: >
2942 GetLnum()->foldclosed()
2943
2944foldclosedend({lnum}) *foldclosedend()*
2945 The result is a Number. If the line {lnum} is in a closed
2946 fold, the result is the number of the last line in that fold.
2947 If the line {lnum} is not in a closed fold, -1 is returned.
2948 {lnum} is used like with |getline()|. Thus "." is the current
2949 line, "'m" mark m, etc.
2950
2951 Can also be used as a |method|: >
2952 GetLnum()->foldclosedend()
2953
2954foldlevel({lnum}) *foldlevel()*
2955 The result is a Number, which is the foldlevel of line {lnum}
2956 in the current buffer. For nested folds the deepest level is
2957 returned. If there is no fold at line {lnum}, zero is
2958 returned. It doesn't matter if the folds are open or closed.
2959 When used while updating folds (from 'foldexpr') -1 is
2960 returned for lines where folds are still to be updated and the
2961 foldlevel is unknown. As a special case the level of the
2962 previous line is usually available.
2963 {lnum} is used like with |getline()|. Thus "." is the current
2964 line, "'m" mark m, etc.
2965
2966 Can also be used as a |method|: >
2967 GetLnum()->foldlevel()
2968<
2969 *foldtext()*
2970foldtext() Returns a String, to be displayed for a closed fold. This is
2971 the default function used for the 'foldtext' option and should
2972 only be called from evaluating 'foldtext'. It uses the
2973 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2974 The returned string looks like this: >
2975 +-- 45 lines: abcdef
2976< The number of leading dashes depends on the foldlevel. The
2977 "45" is the number of lines in the fold. "abcdef" is the text
2978 in the first non-blank line of the fold. Leading white space,
2979 "//" or "/*" and the text from the 'foldmarker' and
2980 'commentstring' options is removed.
2981 When used to draw the actual foldtext, the rest of the line
2982 will be filled with the fold char from the 'fillchars'
2983 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002984 Returns an empty string when there is no fold.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002985 {not available when compiled without the |+folding| feature}
2986
2987foldtextresult({lnum}) *foldtextresult()*
2988 Returns the text that is displayed for the closed fold at line
2989 {lnum}. Evaluates 'foldtext' in the appropriate context.
2990 When there is no closed fold at {lnum} an empty string is
2991 returned.
2992 {lnum} is used like with |getline()|. Thus "." is the current
2993 line, "'m" mark m, etc.
2994 Useful when exporting folded text, e.g., to HTML.
2995 {not available when compiled without the |+folding| feature}
2996
2997
2998 Can also be used as a |method|: >
2999 GetLnum()->foldtextresult()
Ernie Raele79e2072024-01-13 11:47:33 +01003000
3001foreach({expr1}, {expr2}) *foreach()*
3002 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
3003 For each item in {expr1} execute {expr2}. {expr1} is not
erraelc92b8be2024-01-14 10:11:07 -08003004 modified; its values may be, as with |:lockvar| 1. |E741|
Ernie Raele79e2072024-01-13 11:47:33 +01003005 See |map()| and |filter()| to modify {expr1}.
3006
3007 {expr2} must be a |string| or |Funcref|.
3008
3009 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3010 of the current item. For a |Dictionary| |v:key| has the key
3011 of the current item and for a |List| |v:key| has the index of
3012 the current item. For a |Blob| |v:key| has the index of the
3013 current byte. For a |String| |v:key| has the index of the
3014 current character.
3015 Examples: >
3016 call foreach(mylist, 'used[v:val] = true')
3017< This records the items that are in the {expr1} list.
3018
3019 Note that {expr2} is the result of expression and is then used
3020 as a command. Often it is good to use a |literal-string| to
3021 avoid having to double backslashes.
3022
3023 If {expr2} is a |Funcref| it must take two arguments:
3024 1. the key or the index of the current item.
3025 2. the value of the current item.
3026 With a legacy script lambda you don't get an error if it only
3027 accepts one argument, but with a Vim9 lambda you get "E1106:
3028 One argument too many", the number of arguments must match.
3029 If the function returns a value, it is ignored.
3030
3031 Returns {expr1} in all cases.
3032 When an error is encountered while executing {expr2} no
3033 further items in {expr1} are processed.
3034 When {expr2} is a Funcref errors inside a function are ignored,
3035 unless it was defined with the "abort" flag.
3036
3037 Can also be used as a |method|: >
3038 mylist->foreach(expr2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003039<
3040 *foreground()*
3041foreground() Move the Vim window to the foreground. Useful when sent from
3042 a client to a Vim server. |remote_send()|
3043 On Win32 systems this might not work, the OS does not always
3044 allow a window to bring itself to the foreground. Use
3045 |remote_foreground()| instead.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003046 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003047 Win32 console version}
3048
Bram Moolenaaraa534142022-09-15 21:46:02 +01003049fullcommand({name} [, {vim9}]) *fullcommand()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003050 Get the full command name from a short abbreviated command
3051 name; see |20.2| for details on command abbreviations.
3052
3053 The string argument {name} may start with a `:` and can
3054 include a [range], these are skipped and not returned.
Bram Moolenaaraa534142022-09-15 21:46:02 +01003055 Returns an empty string if a command doesn't exist, if it's
3056 ambiguous (for user-defined commands) or cannot be shortened
3057 this way. |vim9-no-shorten|
3058
3059 Without the {vim9} argument uses the current script version.
3060 If {vim9} is present and FALSE then legacy script rules are
3061 used. When {vim9} is present and TRUE then Vim9 rules are
3062 used, e.g. "en" is not a short form of "endif".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003063
3064 For example `fullcommand('s')`, `fullcommand('sub')`,
3065 `fullcommand(':%substitute')` all return "substitute".
3066
3067 Can also be used as a |method|: >
3068 GetName()->fullcommand()
3069<
3070 *funcref()*
3071funcref({name} [, {arglist}] [, {dict}])
3072 Just like |function()|, but the returned Funcref will lookup
3073 the function by reference, not by name. This matters when the
3074 function {name} is redefined later.
3075
3076 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003077 It only works for an autoloaded function if it has already
3078 been loaded (to avoid mistakenly loading the autoload script
3079 when only intending to use the function name, use |function()|
3080 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003081 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003082
3083 Can also be used as a |method|: >
3084 GetFuncname()->funcref([arg])
3085<
Dominique Pellee764d1b2023-03-12 21:20:59 +00003086 *function()* *partial* *E700* *E923*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003087function({name} [, {arglist}] [, {dict}])
3088 Return a |Funcref| variable that refers to function {name}.
3089 {name} can be the name of a user defined function or an
3090 internal function.
3091
3092 {name} can also be a Funcref or a partial. When it is a
3093 partial the dict stored in it will be used and the {dict}
3094 argument is not allowed. E.g.: >
3095 let FuncWithArg = function(dict.Func, [arg])
3096 let Broken = function(dict.Func, [arg], dict)
3097<
3098 When using the Funcref the function will be found by {name},
3099 also when it was redefined later. Use |funcref()| to keep the
3100 same function.
3101
3102 When {arglist} or {dict} is present this creates a partial.
3103 That means the argument list and/or the dictionary is stored in
3104 the Funcref and will be used when the Funcref is called.
3105
3106 The arguments are passed to the function in front of other
3107 arguments, but after any argument from |method|. Example: >
3108 func Callback(arg1, arg2, name)
3109 ...
3110 let Partial = function('Callback', ['one', 'two'])
3111 ...
3112 call Partial('name')
3113< Invokes the function as with: >
3114 call Callback('one', 'two', 'name')
3115
3116< With a |method|: >
3117 func Callback(one, two, three)
3118 ...
3119 let Partial = function('Callback', ['two'])
3120 ...
3121 eval 'one'->Partial('three')
3122< Invokes the function as with: >
3123 call Callback('one', 'two', 'three')
3124
3125< The function() call can be nested to add more arguments to the
3126 Funcref. The extra arguments are appended to the list of
3127 arguments. Example: >
3128 func Callback(arg1, arg2, name)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003129 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003130 let Func = function('Callback', ['one'])
3131 let Func2 = function(Func, ['two'])
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003132 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003133 call Func2('name')
3134< Invokes the function as with: >
3135 call Callback('one', 'two', 'name')
3136
3137< The Dictionary is only useful when calling a "dict" function.
3138 In that case the {dict} is passed in as "self". Example: >
3139 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003140 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003141 endfunction
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003142 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003143 let context = {"name": "example"}
3144 let Func = function('Callback', context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003145 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003146 call Func() " will echo: called for example
3147< The use of function() is not needed when there are no extra
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003148 arguments, these two are equivalent, if Callback() is defined
3149 as context.Callback(): >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003150 let Func = function('Callback', context)
3151 let Func = context.Callback
3152
3153< The argument list and the Dictionary can be combined: >
3154 function Callback(arg1, count) dict
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003155 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003156 let context = {"name": "example"}
3157 let Func = function('Callback', ['one'], context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003158 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003159 call Func(500)
3160< Invokes the function as with: >
3161 call context.Callback('one', 500)
3162<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003163 Returns 0 on error.
3164
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003165 Can also be used as a |method|: >
3166 GetFuncname()->function([arg])
3167
3168
3169garbagecollect([{atexit}]) *garbagecollect()*
3170 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3171 that have circular references.
3172
3173 There is hardly ever a need to invoke this function, as it is
3174 automatically done when Vim runs out of memory or is waiting
3175 for the user to press a key after 'updatetime'. Items without
3176 circular references are always freed when they become unused.
3177 This is useful if you have deleted a very big |List| and/or
3178 |Dictionary| with circular references in a script that runs
3179 for a long time.
3180
3181 When the optional {atexit} argument is one, garbage
3182 collection will also be done when exiting Vim, if it wasn't
3183 done before. This is useful when checking for memory leaks.
3184
3185 The garbage collection is not done immediately but only when
3186 it's safe to perform. This is when waiting for the user to
3187 type a character. To force garbage collection immediately use
3188 |test_garbagecollect_now()|.
3189
3190get({list}, {idx} [, {default}]) *get()*
3191 Get item {idx} from |List| {list}. When this item is not
3192 available return {default}. Return zero when {default} is
3193 omitted.
3194 Preferably used as a |method|: >
3195 mylist->get(idx)
3196get({blob}, {idx} [, {default}])
3197 Get byte {idx} from |Blob| {blob}. When this byte is not
3198 available return {default}. Return -1 when {default} is
3199 omitted.
3200 Preferably used as a |method|: >
3201 myblob->get(idx)
3202get({dict}, {key} [, {default}])
3203 Get item with key {key} from |Dictionary| {dict}. When this
3204 item is not available return {default}. Return zero when
3205 {default} is omitted. Useful example: >
3206 let val = get(g:, 'var_name', 'default')
3207< This gets the value of g:var_name if it exists, and uses
3208 'default' when it does not exist.
3209 Preferably used as a |method|: >
3210 mydict->get(key)
3211get({func}, {what})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003212 Get item {what} from Funcref {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003213 {what} are:
3214 "name" The function name
3215 "func" The function
3216 "dict" The dictionary
3217 "args" The list with arguments
Bram Moolenaar016188f2022-06-06 20:52:59 +01003218 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003219 Preferably used as a |method|: >
3220 myfunc->get(what)
3221<
3222 *getbufinfo()*
3223getbufinfo([{buf}])
3224getbufinfo([{dict}])
3225 Get information about buffers as a List of Dictionaries.
3226
3227 Without an argument information about all the buffers is
3228 returned.
3229
3230 When the argument is a |Dictionary| only the buffers matching
3231 the specified criteria are returned. The following keys can
3232 be specified in {dict}:
3233 buflisted include only listed buffers.
3234 bufloaded include only loaded buffers.
3235 bufmodified include only modified buffers.
3236
3237 Otherwise, {buf} specifies a particular buffer to return
3238 information for. For the use of {buf}, see |bufname()|
3239 above. If the buffer is found the returned List has one item.
3240 Otherwise the result is an empty list.
3241
3242 Each returned List item is a dictionary with the following
3243 entries:
3244 bufnr Buffer number.
3245 changed TRUE if the buffer is modified.
3246 changedtick Number of changes made to the buffer.
Sean Dewar1fb41032023-08-16 17:15:05 +01003247 command TRUE if the buffer belongs to the
3248 command-line window |cmdwin|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003249 hidden TRUE if the buffer is hidden.
3250 lastused Timestamp in seconds, like
3251 |localtime()|, when the buffer was
3252 last used.
3253 {only with the |+viminfo| feature}
3254 listed TRUE if the buffer is listed.
3255 lnum Line number used for the buffer when
3256 opened in the current window.
3257 Only valid if the buffer has been
3258 displayed in the window in the past.
3259 If you want the line number of the
3260 last known cursor position in a given
3261 window, use |line()|: >
3262 :echo line('.', {winid})
3263<
3264 linecount Number of lines in the buffer (only
3265 valid when loaded)
3266 loaded TRUE if the buffer is loaded.
3267 name Full path to the file in the buffer.
3268 signs List of signs placed in the buffer.
3269 Each list item is a dictionary with
3270 the following fields:
3271 id sign identifier
3272 lnum line number
3273 name sign name
3274 variables A reference to the dictionary with
3275 buffer-local variables.
3276 windows List of |window-ID|s that display this
3277 buffer
3278 popups List of popup |window-ID|s that
3279 display this buffer
3280
3281 Examples: >
3282 for buf in getbufinfo()
3283 echo buf.name
3284 endfor
3285 for buf in getbufinfo({'buflisted':1})
3286 if buf.changed
3287 ....
3288 endif
3289 endfor
3290<
3291 To get buffer-local options use: >
3292 getbufvar({bufnr}, '&option_name')
3293<
3294 Can also be used as a |method|: >
3295 GetBufnr()->getbufinfo()
3296<
3297
3298 *getbufline()*
3299getbufline({buf}, {lnum} [, {end}])
3300 Return a |List| with the lines starting from {lnum} to {end}
3301 (inclusive) in the buffer {buf}. If {end} is omitted, a
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003302 |List| with only the line {lnum} is returned. See
3303 `getbufoneline()` for only getting the line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003304
3305 For the use of {buf}, see |bufname()| above.
3306
3307 For {lnum} and {end} "$" can be used for the last line of the
3308 buffer. Otherwise a number must be used.
3309
3310 When {lnum} is smaller than 1 or bigger than the number of
3311 lines in the buffer, an empty |List| is returned.
3312
3313 When {end} is greater than the number of lines in the buffer,
3314 it is treated as {end} is set to the number of lines in the
3315 buffer. When {end} is before {lnum} an empty |List| is
3316 returned.
3317
3318 This function works only for loaded buffers. For unloaded and
3319 non-existing buffers, an empty |List| is returned.
3320
3321 Example: >
3322 :let lines = getbufline(bufnr("myfile"), 1, "$")
3323
3324< Can also be used as a |method|: >
3325 GetBufnr()->getbufline(lnum)
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003326<
3327 *getbufoneline()*
3328getbufoneline({buf}, {lnum})
3329 Just like `getbufline()` but only get one line and return it
3330 as a string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003331
3332getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3333 The result is the value of option or local buffer variable
3334 {varname} in buffer {buf}. Note that the name without "b:"
3335 must be used.
3336 The {varname} argument is a string.
3337 When {varname} is empty returns a |Dictionary| with all the
3338 buffer-local variables.
3339 When {varname} is equal to "&" returns a |Dictionary| with all
3340 the buffer-local options.
3341 Otherwise, when {varname} starts with "&" returns the value of
3342 a buffer-local option.
3343 This also works for a global or buffer-local option, but it
3344 doesn't work for a global variable, window-local variable or
3345 window-local option.
3346 For the use of {buf}, see |bufname()| above.
3347 When the buffer or variable doesn't exist {def} or an empty
3348 string is returned, there is no error message.
3349 Examples: >
3350 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003351 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003352
3353< Can also be used as a |method|: >
3354 GetBufnr()->getbufvar(varname)
3355<
Kota Kato66bb9ae2023-01-17 18:31:56 +00003356getcellwidths() *getcellwidths()*
3357 Returns a |List| of cell widths of character ranges overridden
3358 by |setcellwidths()|. The format is equal to the argument of
3359 |setcellwidths()|. If no character ranges have their cell
3360 widths overridden, an empty List is returned.
3361
3362
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003363getchangelist([{buf}]) *getchangelist()*
3364 Returns the |changelist| for the buffer {buf}. For the use
3365 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3366 exist, an empty list is returned.
3367
3368 The returned list contains two entries: a list with the change
3369 locations and the current position in the list. Each
3370 entry in the change list is a dictionary with the following
3371 entries:
3372 col column number
3373 coladd column offset for 'virtualedit'
3374 lnum line number
3375 If buffer {buf} is the current buffer, then the current
3376 position refers to the position in the list. For other
3377 buffers, it is set to the length of the list.
3378
3379 Can also be used as a |method|: >
3380 GetBufnr()->getchangelist()
3381
3382getchar([expr]) *getchar()*
3383 Get a single character from the user or input stream.
3384 If [expr] is omitted, wait until a character is available.
3385 If [expr] is 0, only get a character when one is available.
3386 Return zero otherwise.
3387 If [expr] is 1, only check if a character is available, it is
3388 not consumed. Return zero if no character available.
3389 If you prefer always getting a string use |getcharstr()|.
3390
3391 Without [expr] and when [expr] is 0 a whole character or
3392 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01003393 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003394 Otherwise a String is returned with the encoded character.
3395 For a special key it's a String with a sequence of bytes
3396 starting with 0x80 (decimal: 128). This is the same value as
3397 the String "\<Key>", e.g., "\<Left>". The returned value is
3398 also a String when a modifier (shift, control, alt) was used
3399 that is not included in the character.
3400
3401 When [expr] is 0 and Esc is typed, there will be a short delay
3402 while Vim waits to see if this is the start of an escape
3403 sequence.
3404
3405 When [expr] is 1 only the first byte is returned. For a
3406 one-byte character it is the character itself as a number.
3407 Use nr2char() to convert it to a String.
3408
3409 Use getcharmod() to obtain any additional modifiers.
3410
3411 When the user clicks a mouse button, the mouse event will be
3412 returned. The position can then be found in |v:mouse_col|,
3413 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3414 |getmousepos()| can also be used. Mouse move events will be
3415 ignored.
3416 This example positions the mouse as it would normally happen: >
3417 let c = getchar()
3418 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003419 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003420 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003421 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003422 endif
3423<
3424 When using bracketed paste only the first character is
3425 returned, the rest of the pasted text is dropped.
3426 |xterm-bracketed-paste|.
3427
3428 There is no prompt, you will somehow have to make clear to the
3429 user that a character has to be typed. The screen is not
3430 redrawn, e.g. when resizing the window. When using a popup
3431 window it should work better with a |popup-filter|.
3432
3433 There is no mapping for the character.
3434 Key codes are replaced, thus when the user presses the <Del>
3435 key you get the code for the <Del> key, not the raw character
3436 sequence. Examples: >
3437 getchar() == "\<Del>"
3438 getchar() == "\<S-Left>"
3439< This example redefines "f" to ignore case: >
3440 :nmap f :call FindChar()<CR>
3441 :function FindChar()
3442 : let c = nr2char(getchar())
3443 : while col('.') < col('$') - 1
3444 : normal l
3445 : if getline('.')[col('.') - 1] ==? c
3446 : break
3447 : endif
3448 : endwhile
3449 :endfunction
3450<
3451 You may also receive synthetic characters, such as
3452 |<CursorHold>|. Often you will want to ignore this and get
3453 another character: >
3454 :function GetKey()
3455 : let c = getchar()
3456 : while c == "\<CursorHold>"
3457 : let c = getchar()
3458 : endwhile
3459 : return c
3460 :endfunction
3461
3462getcharmod() *getcharmod()*
3463 The result is a Number which is the state of the modifiers for
3464 the last obtained character with getchar() or in another way.
3465 These values are added together:
3466 2 shift
3467 4 control
3468 8 alt (meta)
3469 16 meta (when it's different from ALT)
3470 32 mouse double click
3471 64 mouse triple click
3472 96 mouse quadruple click (== 32 + 64)
Casey Tucker92e90a12024-01-25 22:44:00 +01003473 128 command (Mac) or super (GTK)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003474 Only the modifiers that have not been included in the
3475 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01003476 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003477
3478 *getcharpos()*
3479getcharpos({expr})
3480 Get the position for String {expr}. Same as |getpos()| but the
3481 column number in the returned List is a character index
3482 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00003483 If |getpos()| returns a very large column number, equal to
3484 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003485 of the last character.
3486
3487 Example:
3488 With the cursor on '세' in line 5 with text "여보세요": >
3489 getcharpos('.') returns [0, 5, 3, 0]
3490 getpos('.') returns [0, 5, 7, 0]
3491<
3492 Can also be used as a |method|: >
3493 GetMark()->getcharpos()
3494
3495getcharsearch() *getcharsearch()*
3496 Return the current character search information as a {dict}
3497 with the following entries:
3498
3499 char character previously used for a character
3500 search (|t|, |f|, |T|, or |F|); empty string
3501 if no character search has been performed
3502 forward direction of character search; 1 for forward,
3503 0 for backward
3504 until type of character search; 1 for a |t| or |T|
3505 character search, 0 for an |f| or |F|
3506 character search
3507
3508 This can be useful to always have |;| and |,| search
3509 forward/backward regardless of the direction of the previous
3510 character search: >
3511 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3512 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3513< Also see |setcharsearch()|.
3514
3515
3516getcharstr([expr]) *getcharstr()*
3517 Get a single character from the user or input stream as a
3518 string.
3519 If [expr] is omitted, wait until a character is available.
3520 If [expr] is 0 or false, only get a character when one is
3521 available. Return an empty string otherwise.
3522 If [expr] is 1 or true, only check if a character is
3523 available, it is not consumed. Return an empty string
3524 if no character is available.
3525 Otherwise this works like |getchar()|, except that a number
3526 result is converted to a string.
3527
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003528getcmdcompltype() *getcmdcompltype()*
3529 Return the type of the current command-line completion.
3530 Only works when the command line is being edited, thus
3531 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01003532 See |:command-completion| for the return string.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003533 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3534 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003535 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003536
3537getcmdline() *getcmdline()*
3538 Return the current command-line. Only works when the command
3539 line is being edited, thus requires use of |c_CTRL-\_e| or
3540 |c_CTRL-R_=|.
3541 Example: >
3542 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003543< Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and
3544 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003545 Returns an empty string when entering a password or using
3546 |inputsecret()|.
3547
3548getcmdpos() *getcmdpos()*
3549 Return the position of the cursor in the command line as a
3550 byte count. The first column is 1.
3551 Only works when editing the command line, thus requires use of
3552 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3553 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003554 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3555 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003556
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003557getcmdscreenpos() *getcmdscreenpos()*
3558 Return the screen position of the cursor in the command line
3559 as a byte count. The first column is 1.
3560 Instead of |getcmdpos()|, it adds the prompt position.
3561 Only works when editing the command line, thus requires use of
3562 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3563 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003564 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
3565 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003566
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003567getcmdtype() *getcmdtype()*
3568 Return the current command-line type. Possible return values
3569 are:
3570 : normal Ex command
3571 > debug mode command |debug-mode|
3572 / forward search command
3573 ? backward search command
3574 @ |input()| command
3575 - |:insert| or |:append| command
3576 = |i_CTRL-R_=|
3577 Only works when editing the command line, thus requires use of
3578 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3579 Returns an empty string otherwise.
3580 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3581
3582getcmdwintype() *getcmdwintype()*
3583 Return the current |command-line-window| type. Possible return
3584 values are the same as |getcmdtype()|. Returns an empty string
3585 when not in the command-line window.
3586
3587getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
3588 Return a list of command-line completion matches. The String
3589 {type} argument specifies what for. The following completion
3590 types are supported:
3591
3592 arglist file names in argument list
3593 augroup autocmd groups
3594 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003595 behave |:behave| suboptions
3596 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003597 color color schemes
3598 command Ex command
3599 cmdline |cmdline-completion| result
3600 compiler compilers
3601 cscope |:cscope| suboptions
Shougo Matsushita92997dd2023-08-20 20:55:55 +02003602 custom,{func} custom completion, defined via {func}
3603 customlist,{func} custom completion, defined via {func}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003604 diff_buffer |:diffget| and |:diffput| completion
3605 dir directory names
3606 environment environment variable names
3607 event autocommand events
3608 expression Vim expression
3609 file file and directory names
3610 file_in_path file and directory names in |'path'|
3611 filetype filetype names |'filetype'|
3612 function function name
3613 help help subjects
3614 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003615 history |:history| suboptions
Doug Kearns81642d92024-01-04 22:37:44 +01003616 keymap keyboard mappings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003617 locale locale names (as output of locale -a)
3618 mapclear buffer argument
3619 mapping mapping name
3620 menu menus
3621 messages |:messages| suboptions
3622 option options
3623 packadd optional package |pack-add| names
zeertzjq5c8771b2023-01-24 12:34:03 +00003624 runtime |:runtime| completion
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003625 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003626 shellcmd Shell command
3627 sign |:sign| suboptions
3628 syntax syntax file names |'syntax'|
3629 syntime |:syntime| suboptions
3630 tag tags
3631 tag_listfiles tags, file names
3632 user user names
3633 var user variables
3634
3635 If {pat} is an empty string, then all the matches are
3636 returned. Otherwise only items matching {pat} are returned.
3637 See |wildcards| for the use of special characters in {pat}.
3638
3639 If the optional {filtered} flag is set to 1, then 'wildignore'
3640 is applied to filter the results. Otherwise all the matches
3641 are returned. The 'wildignorecase' option always applies.
3642
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003643 If the 'wildoptions' option contains 'fuzzy', then fuzzy
3644 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003645 regular expression matching is used. Thus this function
3646 follows the user preference, what happens on the command line.
3647 If you do not want this you can make 'wildoptions' empty
3648 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003649
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003650 If {type} is "cmdline", then the |cmdline-completion| result is
3651 returned. For example, to complete the possible values after
3652 a ":call" command: >
3653 echo getcompletion('call ', 'cmdline')
3654<
3655 If there are no matches, an empty list is returned. An
3656 invalid value for {type} produces an error.
3657
3658 Can also be used as a |method|: >
3659 GetPattern()->getcompletion('color')
3660<
3661 *getcurpos()*
3662getcurpos([{winid}])
3663 Get the position of the cursor. This is like getpos('.'), but
3664 includes an extra "curswant" item in the list:
3665 [0, lnum, col, off, curswant] ~
3666 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00003667 cursor vertically. After |$| command it will be a very large
3668 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003669 |getpos()|.
3670 The first "bufnum" item is always zero. The byte position of
3671 the cursor is returned in 'col'. To get the character
3672 position, use |getcursorcharpos()|.
3673
3674 The optional {winid} argument can specify the window. It can
3675 be the window number or the |window-ID|. The last known
3676 cursor position is returned, this may be invalid for the
3677 current value of the buffer if it is not the current window.
3678 If {winid} is invalid a list with zeroes is returned.
3679
3680 This can be used to save and restore the cursor position: >
3681 let save_cursor = getcurpos()
3682 MoveTheCursorAround
3683 call setpos('.', save_cursor)
3684< Note that this only works within the window. See
3685 |winrestview()| for restoring more state.
3686
3687 Can also be used as a |method|: >
3688 GetWinid()->getcurpos()
3689<
3690 *getcursorcharpos()*
3691getcursorcharpos([{winid}])
3692 Same as |getcurpos()| but the column number in the returned
3693 List is a character index instead of a byte index.
3694
3695 Example:
3696 With the cursor on '보' in line 3 with text "여보세요": >
3697 getcursorcharpos() returns [0, 3, 2, 0, 3]
3698 getcurpos() returns [0, 3, 4, 0, 3]
3699<
3700 Can also be used as a |method|: >
3701 GetWinid()->getcursorcharpos()
3702
3703< *getcwd()*
3704getcwd([{winnr} [, {tabnr}]])
3705 The result is a String, which is the name of the current
3706 working directory. 'autochdir' is ignored.
3707
3708 With {winnr} return the local current directory of this window
3709 in the current tab page. {winnr} can be the window number or
3710 the |window-ID|.
3711 If {winnr} is -1 return the name of the global working
3712 directory. See also |haslocaldir()|.
3713
3714 With {winnr} and {tabnr} return the local current directory of
3715 the window in the specified tab page. If {winnr} is -1 return
3716 the working directory of the tabpage.
3717 If {winnr} is zero use the current window, if {tabnr} is zero
3718 use the current tabpage.
3719 Without any arguments, return the actual working directory of
3720 the current window.
3721 Return an empty string if the arguments are invalid.
3722
3723 Examples: >
3724 " Get the working directory of the current window
3725 :echo getcwd()
3726 :echo getcwd(0)
3727 :echo getcwd(0, 0)
3728 " Get the working directory of window 3 in tabpage 2
3729 :echo getcwd(3, 2)
3730 " Get the global working directory
3731 :echo getcwd(-1)
3732 " Get the working directory of tabpage 3
3733 :echo getcwd(-1, 3)
3734 " Get the working directory of current tabpage
3735 :echo getcwd(-1, 0)
3736
3737< Can also be used as a |method|: >
3738 GetWinnr()->getcwd()
3739
3740getenv({name}) *getenv()*
3741 Return the value of environment variable {name}. The {name}
3742 argument is a string, without a leading '$'. Example: >
3743 myHome = getenv('HOME')
3744
3745< When the variable does not exist |v:null| is returned. That
3746 is different from a variable set to an empty string, although
3747 some systems interpret the empty value as the variable being
3748 deleted. See also |expr-env|.
3749
3750 Can also be used as a |method|: >
3751 GetVarname()->getenv()
3752
3753getfontname([{name}]) *getfontname()*
3754 Without an argument returns the name of the normal font being
3755 used. Like what is used for the Normal highlight group
3756 |hl-Normal|.
3757 With an argument a check is done whether String {name} is a
3758 valid font name. If not then an empty string is returned.
3759 Otherwise the actual font name is returned, or {name} if the
3760 GUI does not support obtaining the real name.
3761 Only works when the GUI is running, thus not in your vimrc or
3762 gvimrc file. Use the |GUIEnter| autocommand to use this
3763 function just after the GUI has started.
3764 Note that the GTK GUI accepts any font name, thus checking for
3765 a valid name does not work.
3766
3767getfperm({fname}) *getfperm()*
3768 The result is a String, which is the read, write, and execute
3769 permissions of the given file {fname}.
3770 If {fname} does not exist or its directory cannot be read, an
3771 empty string is returned.
3772 The result is of the form "rwxrwxrwx", where each group of
3773 "rwx" flags represent, in turn, the permissions of the owner
3774 of the file, the group the file belongs to, and other users.
3775 If a user does not have a given permission the flag for this
3776 is replaced with the string "-". Examples: >
3777 :echo getfperm("/etc/passwd")
3778 :echo getfperm(expand("~/.vimrc"))
3779< This will hopefully (from a security point of view) display
3780 the string "rw-r--r--" or even "rw-------".
3781
3782 Can also be used as a |method|: >
3783 GetFilename()->getfperm()
3784<
3785 For setting permissions use |setfperm()|.
3786
3787getfsize({fname}) *getfsize()*
3788 The result is a Number, which is the size in bytes of the
3789 given file {fname}.
3790 If {fname} is a directory, 0 is returned.
3791 If the file {fname} can't be found, -1 is returned.
3792 If the size of {fname} is too big to fit in a Number then -2
3793 is returned.
3794
3795 Can also be used as a |method|: >
3796 GetFilename()->getfsize()
3797
3798getftime({fname}) *getftime()*
3799 The result is a Number, which is the last modification time of
3800 the given file {fname}. The value is measured as seconds
3801 since 1st Jan 1970, and may be passed to strftime(). See also
3802 |localtime()| and |strftime()|.
3803 If the file {fname} can't be found -1 is returned.
3804
3805 Can also be used as a |method|: >
3806 GetFilename()->getftime()
3807
3808getftype({fname}) *getftype()*
3809 The result is a String, which is a description of the kind of
3810 file of the given file {fname}.
3811 If {fname} does not exist an empty string is returned.
3812 Here is a table over different kinds of files and their
3813 results:
3814 Normal file "file"
3815 Directory "dir"
3816 Symbolic link "link"
3817 Block device "bdev"
3818 Character device "cdev"
3819 Socket "socket"
3820 FIFO "fifo"
3821 All other "other"
3822 Example: >
3823 getftype("/home")
3824< Note that a type such as "link" will only be returned on
3825 systems that support it. On some systems only "dir" and
3826 "file" are returned. On MS-Windows a symbolic link to a
3827 directory returns "dir" instead of "link".
3828
3829 Can also be used as a |method|: >
3830 GetFilename()->getftype()
3831
3832getimstatus() *getimstatus()*
3833 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01003834 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003835 See 'imstatusfunc'.
3836
3837getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
3838 Returns the |jumplist| for the specified window.
3839
3840 Without arguments use the current window.
3841 With {winnr} only use this window in the current tab page.
3842 {winnr} can also be a |window-ID|.
3843 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01003844 page. If {winnr} or {tabnr} is invalid, an empty list is
3845 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003846
3847 The returned list contains two entries: a list with the jump
3848 locations and the last used jump position number in the list.
3849 Each entry in the jump location list is a dictionary with
3850 the following entries:
3851 bufnr buffer number
3852 col column number
3853 coladd column offset for 'virtualedit'
3854 filename filename if available
3855 lnum line number
3856
3857 Can also be used as a |method|: >
3858 GetWinnr()->getjumplist()
3859
3860< *getline()*
3861getline({lnum} [, {end}])
3862 Without {end} the result is a String, which is line {lnum}
3863 from the current buffer. Example: >
3864 getline(1)
3865< When {lnum} is a String that doesn't start with a
3866 digit, |line()| is called to translate the String into a Number.
3867 To get the line under the cursor: >
3868 getline(".")
3869< When {lnum} is a number smaller than 1 or bigger than the
3870 number of lines in the buffer, an empty string is returned.
3871
3872 When {end} is given the result is a |List| where each item is
3873 a line from the current buffer in the range {lnum} to {end},
3874 including line {end}.
3875 {end} is used in the same way as {lnum}.
3876 Non-existing lines are silently omitted.
3877 When {end} is before {lnum} an empty |List| is returned.
3878 Example: >
3879 :let start = line('.')
3880 :let end = search("^$") - 1
3881 :let lines = getline(start, end)
3882
3883< Can also be used as a |method|: >
3884 ComputeLnum()->getline()
3885
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003886< To get lines from another buffer see |getbufline()| and
3887 |getbufoneline()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003888
3889getloclist({nr} [, {what}]) *getloclist()*
3890 Returns a |List| with all the entries in the location list for
3891 window {nr}. {nr} can be the window number or the |window-ID|.
3892 When {nr} is zero the current window is used.
3893
3894 For a location list window, the displayed location list is
3895 returned. For an invalid window number {nr}, an empty list is
3896 returned. Otherwise, same as |getqflist()|.
3897
3898 If the optional {what} dictionary argument is supplied, then
3899 returns the items listed in {what} as a dictionary. Refer to
3900 |getqflist()| for the supported items in {what}.
3901
3902 In addition to the items supported by |getqflist()| in {what},
3903 the following item is supported by |getloclist()|:
3904
3905 filewinid id of the window used to display files
3906 from the location list. This field is
3907 applicable only when called from a
3908 location list window. See
3909 |location-list-file-window| for more
3910 details.
3911
3912 Returns a |Dictionary| with default values if there is no
3913 location list for the window {nr}.
3914 Returns an empty Dictionary if window {nr} does not exist.
3915
3916 Examples (See also |getqflist-examples|): >
3917 :echo getloclist(3, {'all': 0})
3918 :echo getloclist(5, {'filewinid': 0})
3919
3920
3921getmarklist([{buf}]) *getmarklist()*
3922 Without the {buf} argument returns a |List| with information
3923 about all the global marks. |mark|
3924
3925 If the optional {buf} argument is specified, returns the
3926 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01003927 see |bufname()|. If {buf} is invalid, an empty list is
3928 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003929
3930 Each item in the returned List is a |Dict| with the following:
3931 mark name of the mark prefixed by "'"
3932 pos a |List| with the position of the mark:
3933 [bufnum, lnum, col, off]
3934 Refer to |getpos()| for more information.
3935 file file name
3936
3937 Refer to |getpos()| for getting information about a specific
3938 mark.
3939
3940 Can also be used as a |method|: >
3941 GetBufnr()->getmarklist()
3942
3943getmatches([{win}]) *getmatches()*
3944 Returns a |List| with all matches previously defined for the
3945 current window by |matchadd()| and the |:match| commands.
3946 |getmatches()| is useful in combination with |setmatches()|,
3947 as |setmatches()| can restore a list of matches saved by
3948 |getmatches()|.
3949 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01003950 window ID instead of the current window. If {win} is invalid,
3951 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003952 Example: >
3953 :echo getmatches()
3954< [{'group': 'MyGroup1', 'pattern': 'TODO',
3955 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3956 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3957 :let m = getmatches()
3958 :call clearmatches()
3959 :echo getmatches()
3960< [] >
3961 :call setmatches(m)
3962 :echo getmatches()
3963< [{'group': 'MyGroup1', 'pattern': 'TODO',
3964 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3965 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3966 :unlet m
3967<
3968getmousepos() *getmousepos()*
3969 Returns a |Dictionary| with the last known position of the
3970 mouse. This can be used in a mapping for a mouse click or in
3971 a filter of a popup window. The items are:
3972 screenrow screen row
3973 screencol screen column
3974 winid Window ID of the click
3975 winrow row inside "winid"
3976 wincol column inside "winid"
3977 line text line inside "winid"
3978 column text column inside "winid"
zeertzjqf5a94d52023-10-15 10:03:30 +02003979 coladd offset (in screen columns) from the
3980 start of the clicked char
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003981 All numbers are 1-based.
3982
3983 If not over a window, e.g. when in the command line, then only
3984 "screenrow" and "screencol" are valid, the others are zero.
3985
3986 When on the status line below a window or the vertical
3987 separator right of a window, the "line" and "column" values
3988 are zero.
3989
3990 When the position is after the text then "column" is the
3991 length of the text in bytes plus one.
3992
3993 If the mouse is over a popup window then that window is used.
3994
3995 When using |getchar()| the Vim variables |v:mouse_lnum|,
3996 |v:mouse_col| and |v:mouse_winid| also provide these values.
3997
Bram Moolenaar24dc19c2022-11-14 19:49:15 +00003998getmouseshape() *getmouseshape()*
3999 Returns the name of the currently showing mouse pointer.
4000 When the |+mouseshape| feature is not supported or the shape
4001 is unknown an empty string is returned.
4002 This function is mainly intended for testing.
4003
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004004 *getpid()*
4005getpid() Return a Number which is the process ID of the Vim process.
4006 On Unix and MS-Windows this is a unique number, until Vim
4007 exits.
4008
4009 *getpos()*
4010getpos({expr}) Get the position for String {expr}. For possible values of
4011 {expr} see |line()|. For getting the cursor position see
4012 |getcurpos()|.
4013 The result is a |List| with four numbers:
4014 [bufnum, lnum, col, off]
4015 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4016 is the buffer number of the mark.
4017 "lnum" and "col" are the position in the buffer. The first
4018 column is 1.
4019 The "off" number is zero, unless 'virtualedit' is used. Then
4020 it is the offset in screen columns from the start of the
4021 character. E.g., a position within a <Tab> or after the last
4022 character.
4023 Note that for '< and '> Visual mode matters: when it is "V"
4024 (visual line mode) the column of '< is zero and the column of
naohiro ono56200ee2022-01-01 14:59:44 +00004025 '> is a large number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004026 The column number in the returned List is the byte position
4027 within the line. To get the character position in the line,
4028 use |getcharpos()|.
naohiro ono56200ee2022-01-01 14:59:44 +00004029 A very large column number equal to |v:maxcol| can be returned,
4030 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01004031 If {expr} is invalid, returns a list with all zeros.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004032 This can be used to save and restore the position of a mark: >
4033 let save_a_mark = getpos("'a")
4034 ...
4035 call setpos("'a", save_a_mark)
4036< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
4037
4038 Can also be used as a |method|: >
4039 GetMark()->getpos()
4040
4041getqflist([{what}]) *getqflist()*
4042 Returns a |List| with all the current quickfix errors. Each
4043 list item is a dictionary with these entries:
4044 bufnr number of buffer that has the file name, use
4045 bufname() to get the name
4046 module module name
4047 lnum line number in the buffer (first line is 1)
4048 end_lnum
4049 end of line number if the item is multiline
4050 col column number (first column is 1)
4051 end_col end of column number if the item has range
4052 vcol |TRUE|: "col" is visual column
4053 |FALSE|: "col" is byte index
4054 nr error number
4055 pattern search pattern used to locate the error
4056 text description of the error
4057 type type of the error, 'E', '1', etc.
4058 valid |TRUE|: recognized error message
h_east596a9f22023-11-21 21:24:23 +09004059 user_data
4060 custom data associated with the item, can be
Tom Praschanca6ac992023-08-11 23:26:12 +02004061 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004062
4063 When there is no error list or it's empty, an empty list is
4064 returned. Quickfix list entries with a non-existing buffer
4065 number are returned with "bufnr" set to zero (Note: some
4066 functions accept buffer number zero for the alternate buffer,
4067 you may need to explicitly check for zero).
4068
4069 Useful application: Find pattern matches in multiple files and
4070 do something with them: >
4071 :vimgrep /theword/jg *.c
4072 :for d in getqflist()
4073 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4074 :endfor
4075<
4076 If the optional {what} dictionary argument is supplied, then
4077 returns only the items listed in {what} as a dictionary. The
4078 following string items are supported in {what}:
4079 changedtick get the total number of changes made
4080 to the list |quickfix-changedtick|
4081 context get the |quickfix-context|
4082 efm errorformat to use when parsing "lines". If
4083 not present, then the 'errorformat' option
4084 value is used.
4085 id get information for the quickfix list with
4086 |quickfix-ID|; zero means the id for the
4087 current list or the list specified by "nr"
4088 idx get information for the quickfix entry at this
4089 index in the list specified by 'id' or 'nr'.
4090 If set to zero, then uses the current entry.
4091 See |quickfix-index|
4092 items quickfix list entries
4093 lines parse a list of lines using 'efm' and return
4094 the resulting entries. Only a |List| type is
4095 accepted. The current quickfix list is not
4096 modified. See |quickfix-parse|.
4097 nr get information for this quickfix list; zero
4098 means the current quickfix list and "$" means
4099 the last quickfix list
4100 qfbufnr number of the buffer displayed in the quickfix
4101 window. Returns 0 if the quickfix buffer is
4102 not present. See |quickfix-buffer|.
4103 size number of entries in the quickfix list
4104 title get the list title |quickfix-title|
4105 winid get the quickfix |window-ID|
4106 all all of the above quickfix properties
4107 Non-string items in {what} are ignored. To get the value of a
4108 particular item, set it to zero.
4109 If "nr" is not present then the current quickfix list is used.
4110 If both "nr" and a non-zero "id" are specified, then the list
4111 specified by "id" is used.
4112 To get the number of lists in the quickfix stack, set "nr" to
4113 "$" in {what}. The "nr" value in the returned dictionary
4114 contains the quickfix stack size.
4115 When "lines" is specified, all the other items except "efm"
4116 are ignored. The returned dictionary contains the entry
4117 "items" with the list of entries.
4118
4119 The returned dictionary contains the following entries:
4120 changedtick total number of changes made to the
4121 list |quickfix-changedtick|
4122 context quickfix list context. See |quickfix-context|
4123 If not present, set to "".
4124 id quickfix list ID |quickfix-ID|. If not
4125 present, set to 0.
4126 idx index of the quickfix entry in the list. If not
4127 present, set to 0.
4128 items quickfix list entries. If not present, set to
4129 an empty list.
4130 nr quickfix list number. If not present, set to 0
4131 qfbufnr number of the buffer displayed in the quickfix
4132 window. If not present, set to 0.
4133 size number of entries in the quickfix list. If not
4134 present, set to 0.
4135 title quickfix list title text. If not present, set
4136 to "".
4137 winid quickfix |window-ID|. If not present, set to 0
4138
4139 Examples (See also |getqflist-examples|): >
4140 :echo getqflist({'all': 1})
4141 :echo getqflist({'nr': 2, 'title': 1})
4142 :echo getqflist({'lines' : ["F1:10:L10"]})
4143<
4144getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4145 The result is a String, which is the contents of register
4146 {regname}. Example: >
4147 :let cliptext = getreg('*')
4148< When register {regname} was not set the result is an empty
4149 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004150 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004151
4152 getreg('=') returns the last evaluated value of the expression
4153 register. (For use in maps.)
4154 getreg('=', 1) returns the expression itself, so that it can
4155 be restored with |setreg()|. For other registers the extra
4156 argument is ignored, thus you can always give it.
4157
4158 If {list} is present and |TRUE|, the result type is changed
4159 to |List|. Each list item is one text line. Use it if you care
4160 about zero bytes possibly present inside register: without
4161 third argument both NLs and zero bytes are represented as NLs
4162 (see |NL-used-for-Nul|).
4163 When the register was not set an empty list is returned.
4164
4165 If {regname} is "", the unnamed register '"' is used.
4166 If {regname} is not specified, |v:register| is used.
4167 In |Vim9-script| {regname} must be one character.
4168
4169 Can also be used as a |method|: >
4170 GetRegname()->getreg()
4171
4172getreginfo([{regname}]) *getreginfo()*
4173 Returns detailed information about register {regname} as a
4174 Dictionary with the following entries:
4175 regcontents List of lines contained in register
4176 {regname}, like
4177 |getreg|({regname}, 1, 1).
4178 regtype the type of register {regname}, as in
4179 |getregtype()|.
4180 isunnamed Boolean flag, v:true if this register
4181 is currently pointed to by the unnamed
4182 register.
4183 points_to for the unnamed register, gives the
4184 single letter name of the register
4185 currently pointed to (see |quotequote|).
4186 For example, after deleting a line
4187 with `dd`, this field will be "1",
4188 which is the register that got the
4189 deleted text.
4190
4191 The {regname} argument is a string. If {regname} is invalid
4192 or not set, an empty Dictionary will be returned.
4193 If {regname} is "" or "@", the unnamed register '"' is used.
4194 If {regname} is not specified, |v:register| is used.
4195 The returned Dictionary can be passed to |setreg()|.
4196 In |Vim9-script| {regname} must be one character.
4197
4198 Can also be used as a |method|: >
4199 GetRegname()->getreginfo()
4200
4201getregtype([{regname}]) *getregtype()*
4202 The result is a String, which is type of register {regname}.
4203 The value will be one of:
4204 "v" for |characterwise| text
4205 "V" for |linewise| text
4206 "<CTRL-V>{width}" for |blockwise-visual| text
4207 "" for an empty or unknown register
4208 <CTRL-V> is one character with value 0x16.
4209 The {regname} argument is a string. If {regname} is "", the
4210 unnamed register '"' is used. If {regname} is not specified,
4211 |v:register| is used.
4212 In |Vim9-script| {regname} must be one character.
4213
4214 Can also be used as a |method|: >
4215 GetRegname()->getregtype()
4216
Bram Moolenaar71badf92023-04-22 22:40:14 +01004217getscriptinfo([{opts}]) *getscriptinfo()*
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004218 Returns a |List| with information about all the sourced Vim
Bram Moolenaar753885b2022-08-24 16:30:36 +01004219 scripts in the order they were sourced, like what
4220 `:scriptnames` shows.
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004221
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004222 The optional Dict argument {opts} supports the following
4223 optional items:
4224 name Script name match pattern. If specified,
4225 and "sid" is not specified, information about
Bram Moolenaar71badf92023-04-22 22:40:14 +01004226 scripts with a name that match the pattern
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004227 "name" are returned.
4228 sid Script ID |<SID>|. If specified, only
4229 information about the script with ID "sid" is
4230 returned and "name" is ignored.
4231
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004232 Each item in the returned List is a |Dict| with the following
4233 items:
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004234 autoload Set to TRUE for a script that was used with
Bram Moolenaar753885b2022-08-24 16:30:36 +01004235 `import autoload` but was not actually sourced
4236 yet (see |import-autoload|).
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004237 functions List of script-local function names defined in
4238 the script. Present only when a particular
4239 script is specified using the "sid" item in
4240 {opts}.
4241 name Vim script file name.
4242 sid Script ID |<SID>|.
4243 sourced Script ID of the actually sourced script that
Bram Moolenaarfd999452022-08-24 18:30:14 +01004244 this script name links to, if any, otherwise
4245 zero
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004246 variables A dictionary with the script-local variables.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00004247 Present only when a particular script is
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004248 specified using the "sid" item in {opts}.
4249 Note that this is a copy, the value of
4250 script-local variables cannot be changed using
4251 this dictionary.
h_east59858792023-10-25 22:47:05 +09004252 version Vim script version (|scriptversion|)
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01004253
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004254 Examples: >
4255 :echo getscriptinfo({'name': 'myscript'})
4256 :echo getscriptinfo({'sid': 15}).variables
4257<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004258gettabinfo([{tabnr}]) *gettabinfo()*
4259 If {tabnr} is not specified, then information about all the
4260 tab pages is returned as a |List|. Each List item is a
4261 |Dictionary|. Otherwise, {tabnr} specifies the tab page
4262 number and information about that one is returned. If the tab
4263 page does not exist an empty List is returned.
4264
4265 Each List item is a |Dictionary| with the following entries:
4266 tabnr tab page number.
4267 variables a reference to the dictionary with
4268 tabpage-local variables
4269 windows List of |window-ID|s in the tab page.
4270
4271 Can also be used as a |method|: >
4272 GetTabnr()->gettabinfo()
4273
4274gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
4275 Get the value of a tab-local variable {varname} in tab page
4276 {tabnr}. |t:var|
4277 Tabs are numbered starting with one.
4278 The {varname} argument is a string. When {varname} is empty a
4279 dictionary with all tab-local variables is returned.
4280 Note that the name without "t:" must be used.
4281 When the tab or variable doesn't exist {def} or an empty
4282 string is returned, there is no error message.
4283
4284 Can also be used as a |method|: >
4285 GetTabnr()->gettabvar(varname)
4286
4287gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
4288 Get the value of window-local variable {varname} in window
4289 {winnr} in tab page {tabnr}.
4290 The {varname} argument is a string. When {varname} is empty a
4291 dictionary with all window-local variables is returned.
4292 When {varname} is equal to "&" get the values of all
4293 window-local options in a |Dictionary|.
4294 Otherwise, when {varname} starts with "&" get the value of a
4295 window-local option.
4296 Note that {varname} must be the name without "w:".
4297 Tabs are numbered starting with one. For the current tabpage
4298 use |getwinvar()|.
4299 {winnr} can be the window number or the |window-ID|.
4300 When {winnr} is zero the current window is used.
4301 This also works for a global option, buffer-local option and
4302 window-local option, but it doesn't work for a global variable
4303 or buffer-local variable.
4304 When the tab, window or variable doesn't exist {def} or an
4305 empty string is returned, there is no error message.
4306 Examples: >
4307 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004308 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004309<
4310 To obtain all window-local variables use: >
4311 gettabwinvar({tabnr}, {winnr}, '&')
4312
4313< Can also be used as a |method|: >
4314 GetTabnr()->gettabwinvar(winnr, varname)
4315
4316gettagstack([{winnr}]) *gettagstack()*
4317 The result is a Dict, which is the tag stack of window {winnr}.
4318 {winnr} can be the window number or the |window-ID|.
4319 When {winnr} is not specified, the current window is used.
4320 When window {winnr} doesn't exist, an empty Dict is returned.
4321
4322 The returned dictionary contains the following entries:
4323 curidx Current index in the stack. When at
4324 top of the stack, set to (length + 1).
4325 Index of bottom of the stack is 1.
4326 items List of items in the stack. Each item
4327 is a dictionary containing the
4328 entries described below.
4329 length Number of entries in the stack.
4330
4331 Each item in the stack is a dictionary with the following
4332 entries:
4333 bufnr buffer number of the current jump
4334 from cursor position before the tag jump.
4335 See |getpos()| for the format of the
4336 returned list.
4337 matchnr current matching tag number. Used when
4338 multiple matching tags are found for a
4339 name.
4340 tagname name of the tag
4341
4342 See |tagstack| for more information about the tag stack.
4343
4344 Can also be used as a |method|: >
4345 GetWinnr()->gettagstack()
4346
4347
4348gettext({text}) *gettext()*
4349 Translate String {text} if possible.
4350 This is mainly for use in the distributed Vim scripts. When
4351 generating message translations the {text} is extracted by
4352 xgettext, the translator can add the translated message in the
4353 .po file and Vim will lookup the translation when gettext() is
4354 called.
4355 For {text} double quoted strings are preferred, because
4356 xgettext does not understand escaping in single quoted
4357 strings.
4358
4359
4360getwininfo([{winid}]) *getwininfo()*
4361 Returns information about windows as a |List| with Dictionaries.
4362
4363 If {winid} is given Information about the window with that ID
4364 is returned, as a |List| with one item. If the window does not
4365 exist the result is an empty list.
4366
4367 Without {winid} information about all the windows in all the
4368 tab pages is returned.
4369
4370 Each List item is a |Dictionary| with the following entries:
4371 botline last complete displayed buffer line
4372 bufnr number of buffer in the window
4373 height window height (excluding winbar)
4374 loclist 1 if showing a location list
4375 {only with the +quickfix feature}
4376 quickfix 1 if quickfix or location list window
4377 {only with the +quickfix feature}
4378 terminal 1 if a terminal window
4379 {only with the +terminal feature}
4380 tabnr tab page number
4381 topline first displayed buffer line
4382 variables a reference to the dictionary with
4383 window-local variables
4384 width window width
4385 winbar 1 if the window has a toolbar, 0
4386 otherwise
4387 wincol leftmost screen column of the window;
4388 "col" from |win_screenpos()|
4389 textoff number of columns occupied by any
4390 'foldcolumn', 'signcolumn' and line
4391 number in front of the text
4392 winid |window-ID|
4393 winnr window number
4394 winrow topmost screen line of the window;
4395 "row" from |win_screenpos()|
4396
4397 Can also be used as a |method|: >
4398 GetWinnr()->getwininfo()
4399
4400getwinpos([{timeout}]) *getwinpos()*
4401 The result is a |List| with two numbers, the result of
4402 |getwinposx()| and |getwinposy()| combined:
4403 [x-pos, y-pos]
4404 {timeout} can be used to specify how long to wait in msec for
4405 a response from the terminal. When omitted 100 msec is used.
4406 Use a longer time for a remote terminal.
4407 When using a value less than 10 and no response is received
4408 within that time, a previously reported position is returned,
4409 if available. This can be used to poll for the position and
4410 do some work in the meantime: >
4411 while 1
4412 let res = getwinpos(1)
4413 if res[0] >= 0
4414 break
4415 endif
4416 " Do some work here
4417 endwhile
4418<
4419
4420 Can also be used as a |method|: >
4421 GetTimeout()->getwinpos()
4422<
4423 *getwinposx()*
4424getwinposx() The result is a Number, which is the X coordinate in pixels of
4425 the left hand side of the GUI Vim window. Also works for an
4426 xterm (uses a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01004427 The result will be -1 if the information is not available
4428 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004429 The value can be used with `:winpos`.
4430
4431 *getwinposy()*
4432getwinposy() The result is a Number, which is the Y coordinate in pixels of
4433 the top of the GUI Vim window. Also works for an xterm (uses
4434 a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01004435 The result will be -1 if the information is not available
4436 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004437 The value can be used with `:winpos`.
4438
4439getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
4440 Like |gettabwinvar()| for the current tabpage.
4441 Examples: >
4442 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004443 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004444
4445< Can also be used as a |method|: >
4446 GetWinnr()->getwinvar(varname)
4447<
4448glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
4449 Expand the file wildcards in {expr}. See |wildcards| for the
4450 use of special characters.
4451
4452 Unless the optional {nosuf} argument is given and is |TRUE|,
4453 the 'suffixes' and 'wildignore' options apply: Names matching
4454 one of the patterns in 'wildignore' will be skipped and
4455 'suffixes' affect the ordering of matches.
4456 'wildignorecase' always applies.
4457
4458 When {list} is present and it is |TRUE| the result is a |List|
4459 with all matching files. The advantage of using a List is,
4460 you also get filenames containing newlines correctly.
4461 Otherwise the result is a String and when there are several
4462 matches, they are separated by <NL> characters.
4463
4464 If the expansion fails, the result is an empty String or List.
4465
4466 You can also use |readdir()| if you need to do complicated
4467 things, such as limiting the number of matches.
4468
4469 A name for a non-existing file is not included. A symbolic
4470 link is only included if it points to an existing file.
4471 However, when the {alllinks} argument is present and it is
4472 |TRUE| then all symbolic links are included.
4473
4474 For most systems backticks can be used to get files names from
4475 any external command. Example: >
4476 :let tagfiles = glob("`find . -name tags -print`")
4477 :let &tags = substitute(tagfiles, "\n", ",", "g")
4478< The result of the program inside the backticks should be one
4479 item per line. Spaces inside an item are allowed.
4480
4481 See |expand()| for expanding special Vim variables. See
4482 |system()| for getting the raw output of an external command.
4483
4484 Can also be used as a |method|: >
4485 GetExpr()->glob()
4486
4487glob2regpat({string}) *glob2regpat()*
4488 Convert a file pattern, as used by glob(), into a search
4489 pattern. The result can be used to match with a string that
4490 is a file name. E.g. >
4491 if filename =~ glob2regpat('Make*.mak')
4492< This is equivalent to: >
4493 if filename =~ '^Make.*\.mak$'
4494< When {string} is an empty string the result is "^$", match an
4495 empty string.
4496 Note that the result depends on the system. On MS-Windows
4497 a backslash usually means a path separator.
4498
4499 Can also be used as a |method|: >
4500 GetExpr()->glob2regpat()
4501< *globpath()*
4502globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
4503 Perform glob() for String {expr} on all directories in {path}
4504 and concatenate the results. Example: >
4505 :echo globpath(&rtp, "syntax/c.vim")
4506<
4507 {path} is a comma-separated list of directory names. Each
4508 directory name is prepended to {expr} and expanded like with
4509 |glob()|. A path separator is inserted when needed.
4510 To add a comma inside a directory name escape it with a
4511 backslash. Note that on MS-Windows a directory may have a
4512 trailing backslash, remove it if you put a comma after it.
4513 If the expansion fails for one of the directories, there is no
4514 error message.
4515
4516 Unless the optional {nosuf} argument is given and is |TRUE|,
4517 the 'suffixes' and 'wildignore' options apply: Names matching
4518 one of the patterns in 'wildignore' will be skipped and
4519 'suffixes' affect the ordering of matches.
4520
4521 When {list} is present and it is |TRUE| the result is a |List|
4522 with all matching files. The advantage of using a List is, you
4523 also get filenames containing newlines correctly. Otherwise
4524 the result is a String and when there are several matches,
4525 they are separated by <NL> characters. Example: >
4526 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4527<
4528 {alllinks} is used as with |glob()|.
4529
4530 The "**" item can be used to search in a directory tree.
4531 For example, to find all "README.txt" files in the directories
4532 in 'runtimepath' and below: >
4533 :echo globpath(&rtp, "**/README.txt")
4534< Upwards search and limiting the depth of "**" is not
4535 supported, thus using 'path' will not always work properly.
4536
4537 Can also be used as a |method|, the base is passed as the
4538 second argument: >
4539 GetExpr()->globpath(&rtp)
4540<
4541 *has()*
4542has({feature} [, {check}])
4543 When {check} is omitted or is zero: The result is a Number,
4544 which is 1 if the feature {feature} is supported, zero
4545 otherwise. The {feature} argument is a string, case is
4546 ignored. See |feature-list| below.
4547
4548 When {check} is present and not zero: The result is a Number,
4549 which is 1 if the feature {feature} could ever be supported,
4550 zero otherwise. This is useful to check for a typo in
4551 {feature} and to detect dead code. Keep in mind that an older
4552 Vim version will not know about a feature added later and
4553 features that have been abandoned will not be known by the
4554 current Vim version.
4555
4556 Also see |exists()| and |exists_compiled()|.
4557
4558 Note that to skip code that has a syntax error when the
4559 feature is not available, Vim may skip the rest of the line
4560 and miss a following `endif`. Therefore put the `endif` on a
4561 separate line: >
4562 if has('feature')
4563 let x = this->breaks->without->the->feature
4564 endif
4565< If the `endif` would be moved to the second line as "| endif" it
4566 would not be found.
4567
4568
4569has_key({dict}, {key}) *has_key()*
4570 The result is a Number, which is TRUE if |Dictionary| {dict}
Bram Moolenaare8008642022-08-19 17:15:35 +01004571 has an entry with key {key}. FALSE otherwise.
4572 The {key} argument is a string. In |Vim9| script a number is
4573 also accepted (and converted to a string) but no other types.
4574 In legacy script the usual automatic conversion to string is
4575 done.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004576
4577 Can also be used as a |method|: >
4578 mydict->has_key(key)
4579
4580haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4581 The result is a Number:
4582 1 when the window has set a local directory via |:lcd|
4583 2 when the tab-page has set a local directory via |:tcd|
4584 0 otherwise.
4585
4586 Without arguments use the current window.
4587 With {winnr} use this window in the current tab page.
4588 With {winnr} and {tabnr} use the window in the specified tab
4589 page.
4590 {winnr} can be the window number or the |window-ID|.
4591 If {winnr} is -1 it is ignored and only the tabpage is used.
4592 Return 0 if the arguments are invalid.
4593 Examples: >
4594 if haslocaldir() == 1
4595 " window local directory case
4596 elseif haslocaldir() == 2
4597 " tab-local directory case
4598 else
4599 " global directory case
4600 endif
4601
4602 " current window
4603 :echo haslocaldir()
4604 :echo haslocaldir(0)
4605 :echo haslocaldir(0, 0)
4606 " window n in current tab page
4607 :echo haslocaldir(n)
4608 :echo haslocaldir(n, 0)
4609 " window n in tab page m
4610 :echo haslocaldir(n, m)
4611 " tab page m
4612 :echo haslocaldir(-1, m)
4613<
4614 Can also be used as a |method|: >
4615 GetWinnr()->haslocaldir()
4616
4617hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
4618 The result is a Number, which is TRUE if there is a mapping
4619 that contains {what} in somewhere in the rhs (what it is
4620 mapped to) and this mapping exists in one of the modes
4621 indicated by {mode}.
4622 The arguments {what} and {mode} are strings.
4623 When {abbr} is there and it is |TRUE| use abbreviations
4624 instead of mappings. Don't forget to specify Insert and/or
4625 Command-line mode.
4626 Both the global mappings and the mappings local to the current
4627 buffer are checked for a match.
4628 If no matching mapping is found FALSE is returned.
4629 The following characters are recognized in {mode}:
4630 n Normal mode
4631 v Visual and Select mode
4632 x Visual mode
4633 s Select mode
4634 o Operator-pending mode
4635 i Insert mode
4636 l Language-Argument ("r", "f", "t", etc.)
4637 c Command-line mode
4638 When {mode} is omitted, "nvo" is used.
4639
4640 This function is useful to check if a mapping already exists
4641 to a function in a Vim script. Example: >
4642 :if !hasmapto('\ABCdoit')
4643 : map <Leader>d \ABCdoit
4644 :endif
4645< This installs the mapping to "\ABCdoit" only if there isn't
4646 already a mapping to "\ABCdoit".
4647
4648 Can also be used as a |method|: >
4649 GetRHS()->hasmapto()
4650
4651histadd({history}, {item}) *histadd()*
4652 Add the String {item} to the history {history} which can be
4653 one of: *hist-names*
4654 "cmd" or ":" command line history
4655 "search" or "/" search pattern history
4656 "expr" or "=" typed expression history
4657 "input" or "@" input line history
4658 "debug" or ">" debug command history
4659 empty the current or last used history
4660 The {history} string does not need to be the whole name, one
4661 character is sufficient.
4662 If {item} does already exist in the history, it will be
4663 shifted to become the newest entry.
4664 The result is a Number: TRUE if the operation was successful,
4665 otherwise FALSE is returned.
4666
4667 Example: >
4668 :call histadd("input", strftime("%Y %b %d"))
4669 :let date=input("Enter date: ")
4670< This function is not available in the |sandbox|.
4671
4672 Can also be used as a |method|, the base is passed as the
4673 second argument: >
4674 GetHistory()->histadd('search')
4675
4676histdel({history} [, {item}]) *histdel()*
4677 Clear {history}, i.e. delete all its entries. See |hist-names|
4678 for the possible values of {history}.
4679
4680 If the parameter {item} evaluates to a String, it is used as a
4681 regular expression. All entries matching that expression will
4682 be removed from the history (if there are any).
4683 Upper/lowercase must match, unless "\c" is used |/\c|.
4684 If {item} evaluates to a Number, it will be interpreted as
4685 an index, see |:history-indexing|. The respective entry will
4686 be removed if it exists.
4687
4688 The result is TRUE for a successful operation, otherwise FALSE
4689 is returned.
4690
4691 Examples:
4692 Clear expression register history: >
4693 :call histdel("expr")
4694<
4695 Remove all entries starting with "*" from the search history: >
4696 :call histdel("/", '^\*')
4697<
4698 The following three are equivalent: >
4699 :call histdel("search", histnr("search"))
4700 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004701 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004702<
4703 To delete the last search pattern and use the last-but-one for
4704 the "n" command and 'hlsearch': >
4705 :call histdel("search", -1)
4706 :let @/ = histget("search", -1)
4707<
4708 Can also be used as a |method|: >
4709 GetHistory()->histdel()
4710
4711histget({history} [, {index}]) *histget()*
4712 The result is a String, the entry with Number {index} from
4713 {history}. See |hist-names| for the possible values of
4714 {history}, and |:history-indexing| for {index}. If there is
4715 no such entry, an empty String is returned. When {index} is
4716 omitted, the most recent item from the history is used.
4717
4718 Examples:
4719 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004720 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004721
4722< Define an Ex command ":H {num}" that supports re-execution of
4723 the {num}th entry from the output of |:history|. >
4724 :command -nargs=1 H execute histget("cmd", 0+<args>)
4725<
4726 Can also be used as a |method|: >
4727 GetHistory()->histget()
4728
4729histnr({history}) *histnr()*
4730 The result is the Number of the current entry in {history}.
4731 See |hist-names| for the possible values of {history}.
4732 If an error occurred, -1 is returned.
4733
4734 Example: >
4735 :let inp_index = histnr("expr")
4736
4737< Can also be used as a |method|: >
4738 GetHistory()->histnr()
4739<
4740hlexists({name}) *hlexists()*
4741 The result is a Number, which is TRUE if a highlight group
4742 called {name} exists. This is when the group has been
4743 defined in some way. Not necessarily when highlighting has
4744 been defined for it, it may also have been used for a syntax
4745 item.
4746 *highlight_exists()*
4747 Obsolete name: highlight_exists().
4748
4749 Can also be used as a |method|: >
4750 GetName()->hlexists()
4751<
4752hlget([{name} [, {resolve}]]) *hlget()*
4753 Returns a List of all the highlight group attributes. If the
4754 optional {name} is specified, then returns a List with only
4755 the attributes of the specified highlight group. Returns an
4756 empty List if the highlight group {name} is not present.
4757
4758 If the optional {resolve} argument is set to v:true and the
4759 highlight group {name} is linked to another group, then the
4760 link is resolved recursively and the attributes of the
4761 resolved highlight group are returned.
4762
4763 Each entry in the returned List is a Dictionary with the
4764 following items:
4765 cleared boolean flag, set to v:true if the highlight
4766 group attributes are cleared or not yet
4767 specified. See |highlight-clear|.
4768 cterm cterm attributes. See |highlight-cterm|.
4769 ctermbg cterm background color.
4770 See |highlight-ctermbg|.
4771 ctermfg cterm foreground color.
4772 See |highlight-ctermfg|.
4773 ctermul cterm underline color. See |highlight-ctermul|.
4774 default boolean flag, set to v:true if the highlight
4775 group link is a default link. See
4776 |highlight-default|.
4777 font highlight group font. See |highlight-font|.
4778 gui gui attributes. See |highlight-gui|.
4779 guibg gui background color. See |highlight-guibg|.
4780 guifg gui foreground color. See |highlight-guifg|.
4781 guisp gui special color. See |highlight-guisp|.
4782 id highlight group ID.
4783 linksto linked highlight group name.
4784 See |:highlight-link|.
4785 name highlight group name. See |group-name|.
4786 start start terminal keycode. See |highlight-start|.
4787 stop stop terminal keycode. See |highlight-stop|.
4788 term term attributes. See |highlight-term|.
4789
4790 The 'term', 'cterm' and 'gui' items in the above Dictionary
4791 have a dictionary value with the following optional boolean
4792 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
4793 'reverse', 'inverse' and 'strikethrough'.
4794
4795 Example(s): >
4796 :echo hlget()
4797 :echo hlget('ModeMsg')
4798 :echo hlget('Number', v:true)
4799<
4800 Can also be used as a |method|: >
4801 GetName()->hlget()
4802<
4803hlset({list}) *hlset()*
4804 Creates or modifies the attributes of a List of highlight
4805 groups. Each item in {list} is a dictionary containing the
4806 attributes of a highlight group. See |hlget()| for the list of
4807 supported items in this dictionary.
4808
4809 In addition to the items described in |hlget()|, the following
4810 additional items are supported in the dictionary:
4811
4812 force boolean flag to force the creation of
4813 a link for an existing highlight group
4814 with attributes.
4815
4816 The highlight group is identified using the 'name' item and
4817 the 'id' item (if supplied) is ignored. If a highlight group
4818 with a specified name doesn't exist, then it is created.
4819 Otherwise the attributes of an existing highlight group are
4820 modified.
4821
4822 If an empty dictionary value is used for the 'term' or 'cterm'
4823 or 'gui' entries, then the corresponding attributes are
4824 cleared. If the 'cleared' item is set to v:true, then all the
4825 attributes of the highlight group are cleared.
4826
4827 The 'linksto' item can be used to link a highlight group to
4828 another highlight group. See |:highlight-link|.
4829
4830 Returns zero for success, -1 for failure.
4831
4832 Example(s): >
4833 " add bold attribute to the Visual highlight group
4834 :call hlset([#{name: 'Visual',
4835 \ term: #{reverse: 1 , bold: 1}}])
4836 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
4837 :let l = hlget()
4838 :call hlset(l)
4839 " clear the Search highlight group
4840 :call hlset([#{name: 'Search', cleared: v:true}])
4841 " clear the 'term' attributes for a highlight group
4842 :call hlset([#{name: 'Title', term: {}}])
4843 " create the MyHlg group linking it to DiffAdd
4844 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
4845 " remove the MyHlg group link
4846 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
4847 " clear the attributes and a link
4848 :call hlset([#{name: 'MyHlg', cleared: v:true,
4849 \ linksto: 'NONE'}])
4850<
4851 Can also be used as a |method|: >
4852 GetAttrList()->hlset()
4853<
4854 *hlID()*
4855hlID({name}) The result is a Number, which is the ID of the highlight group
4856 with name {name}. When the highlight group doesn't exist,
4857 zero is returned.
4858 This can be used to retrieve information about the highlight
4859 group. For example, to get the background color of the
4860 "Comment" group: >
4861 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4862< *highlightID()*
4863 Obsolete name: highlightID().
4864
4865 Can also be used as a |method|: >
4866 GetName()->hlID()
4867
4868hostname() *hostname()*
4869 The result is a String, which is the name of the machine on
4870 which Vim is currently running. Machine names greater than
4871 256 characters long are truncated.
4872
4873iconv({string}, {from}, {to}) *iconv()*
4874 The result is a String, which is the text {string} converted
4875 from encoding {from} to encoding {to}.
4876 When the conversion completely fails an empty string is
4877 returned. When some characters could not be converted they
4878 are replaced with "?".
4879 The encoding names are whatever the iconv() library function
4880 can accept, see ":!man 3 iconv".
4881 Most conversions require Vim to be compiled with the |+iconv|
4882 feature. Otherwise only UTF-8 to latin1 conversion and back
4883 can be done.
4884 This can be used to display messages with special characters,
4885 no matter what 'encoding' is set to. Write the message in
4886 UTF-8 and use: >
4887 echo iconv(utf8_str, "utf-8", &enc)
4888< Note that Vim uses UTF-8 for all Unicode encodings, conversion
4889 from/to UCS-2 is automatically changed to use UTF-8. You
4890 cannot use UCS-2 in a string anyway, because of the NUL bytes.
4891
4892 Can also be used as a |method|: >
4893 GetText()->iconv('latin1', 'utf-8')
4894<
4895 *indent()*
4896indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4897 current buffer. The indent is counted in spaces, the value
4898 of 'tabstop' is relevant. {lnum} is used just like in
4899 |getline()|.
4900 When {lnum} is invalid -1 is returned. In |Vim9| script an
4901 error is given.
4902
4903 Can also be used as a |method|: >
4904 GetLnum()->indent()
4905
4906index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004907 Find {expr} in {object} and return its index. See
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004908 |indexof()| for using a lambda to select the item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004909
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004910 If {object} is a |List| return the lowest index where the item
4911 has a value equal to {expr}. There is no automatic
4912 conversion, so the String "4" is different from the Number 4.
4913 And the number 4 is different from the Float 4.0. The value
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004914 of 'ignorecase' is not used here, case matters as indicated by
4915 the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004916
4917 If {object} is |Blob| return the lowest index where the byte
4918 value is equal to {expr}.
4919
4920 If {start} is given then start looking at the item with index
4921 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004922
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004923 When {ic} is given and it is |TRUE|, ignore case. Otherwise
4924 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004925
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004926 -1 is returned when {expr} is not found in {object}.
4927 Example: >
4928 :let idx = index(words, "the")
4929 :if index(numbers, 123) >= 0
4930
4931< Can also be used as a |method|: >
4932 GetObject()->index(what)
4933
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004934indexof({object}, {expr} [, {opts}]) *indexof()*
4935 Returns the index of an item in {object} where {expr} is
4936 v:true. {object} must be a |List| or a |Blob|.
4937
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004938 If {object} is a |List|, evaluate {expr} for each item in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004939 List until the expression is v:true and return the index of
4940 this item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004941
4942 If {object} is a |Blob| evaluate {expr} for each byte in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004943 Blob until the expression is v:true and return the index of
4944 this byte.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004945
4946 {expr} must be a |string| or |Funcref|.
4947
4948 If {expr} is a |string|: If {object} is a |List|, inside
4949 {expr} |v:key| has the index of the current List item and
4950 |v:val| has the value of the item. If {object} is a |Blob|,
4951 inside {expr} |v:key| has the index of the current byte and
4952 |v:val| has the byte value.
4953
4954 If {expr} is a |Funcref| it must take two arguments:
4955 1. the key or the index of the current item.
4956 2. the value of the current item.
4957 The function must return |TRUE| if the item is found and the
4958 search should stop.
4959
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004960 The optional argument {opts} is a Dict and supports the
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004961 following items:
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004962 startidx start evaluating {expr} at the item with this
4963 index; may be negative for an item relative to
4964 the end
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004965 Returns -1 when {expr} evaluates to v:false for all the items.
4966 Example: >
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004967 :let l = [#{n: 10}, #{n: 20}, #{n: 30}]
4968 :echo indexof(l, "v:val.n == 20")
4969 :echo indexof(l, {i, v -> v.n == 30})
4970 :echo indexof(l, "v:val.n == 20", #{startidx: 1})
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004971
4972< Can also be used as a |method|: >
4973 mylist->indexof(expr)
4974
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004975input({prompt} [, {text} [, {completion}]]) *input()*
4976 The result is a String, which is whatever the user typed on
4977 the command-line. The {prompt} argument is either a prompt
4978 string, or a blank string (for no prompt). A '\n' can be used
4979 in the prompt to start a new line.
4980 The highlighting set with |:echohl| is used for the prompt.
4981 The input is entered just like a command-line, with the same
4982 editing commands and mappings. There is a separate history
4983 for lines typed for input().
4984 Example: >
4985 :if input("Coffee or beer? ") == "beer"
4986 : echo "Cheers!"
4987 :endif
4988<
4989 If the optional {text} argument is present and not empty, this
4990 is used for the default reply, as if the user typed this.
4991 Example: >
4992 :let color = input("Color? ", "white")
4993
4994< The optional {completion} argument specifies the type of
4995 completion supported for the input. Without it completion is
4996 not performed. The supported completion types are the same as
4997 that can be supplied to a user-defined command using the
4998 "-complete=" argument. Refer to |:command-completion| for
4999 more information. Example: >
5000 let fname = input("File: ", "", "file")
5001<
5002 NOTE: This function must not be used in a startup file, for
5003 the versions that only run in GUI mode (e.g., the Win32 GUI).
5004 Note: When input() is called from within a mapping it will
5005 consume remaining characters from that mapping, because a
5006 mapping is handled like the characters were typed.
5007 Use |inputsave()| before input() and |inputrestore()|
5008 after input() to avoid that. Another solution is to avoid
5009 that further characters follow in the mapping, e.g., by using
5010 |:execute| or |:normal|.
5011
5012 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005013 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005014 :function GetFoo()
5015 : call inputsave()
5016 : let g:Foo = input("enter search pattern: ")
5017 : call inputrestore()
5018 :endfunction
5019
5020< Can also be used as a |method|: >
5021 GetPrompt()->input()
5022
5023inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
5024 Like |input()|, but when the GUI is running and text dialogs
5025 are supported, a dialog window pops up to input the text.
5026 Example: >
5027 :let n = inputdialog("value for shiftwidth", shiftwidth())
5028 :if n != ""
5029 : let &sw = n
5030 :endif
5031< When the dialog is cancelled {cancelreturn} is returned. When
5032 omitted an empty string is returned.
5033 Hitting <Enter> works like pressing the OK button. Hitting
5034 <Esc> works like pressing the Cancel button.
5035 NOTE: Command-line completion is not supported.
5036
5037 Can also be used as a |method|: >
5038 GetPrompt()->inputdialog()
5039
5040inputlist({textlist}) *inputlist()*
5041 {textlist} must be a |List| of strings. This |List| is
5042 displayed, one string per line. The user will be prompted to
5043 enter a number, which is returned.
5044 The user can also select an item by clicking on it with the
5045 mouse, if the mouse is enabled in the command line ('mouse' is
5046 "a" or includes "c"). For the first string 0 is returned.
5047 When clicking above the first item a negative number is
5048 returned. When clicking on the prompt one more than the
5049 length of {textlist} is returned.
5050 Make sure {textlist} has less than 'lines' entries, otherwise
5051 it won't work. It's a good idea to put the entry number at
5052 the start of the string. And put a prompt in the first item.
5053 Example: >
5054 let color = inputlist(['Select color:', '1. red',
5055 \ '2. green', '3. blue'])
5056
5057< Can also be used as a |method|: >
5058 GetChoices()->inputlist()
5059
5060inputrestore() *inputrestore()*
5061 Restore typeahead that was saved with a previous |inputsave()|.
5062 Should be called the same number of times inputsave() is
5063 called. Calling it more often is harmless though.
5064 Returns TRUE when there is nothing to restore, FALSE otherwise.
5065
5066inputsave() *inputsave()*
5067 Preserve typeahead (also from mappings) and clear it, so that
5068 a following prompt gets input from the user. Should be
5069 followed by a matching inputrestore() after the prompt. Can
5070 be used several times, in which case there must be just as
5071 many inputrestore() calls.
5072 Returns TRUE when out of memory, FALSE otherwise.
5073
5074inputsecret({prompt} [, {text}]) *inputsecret()*
5075 This function acts much like the |input()| function with but
5076 two exceptions:
5077 a) the user's response will be displayed as a sequence of
5078 asterisks ("*") thereby keeping the entry secret, and
5079 b) the user's response will not be recorded on the input
5080 |history| stack.
5081 The result is a String, which is whatever the user actually
5082 typed on the command-line in response to the issued prompt.
5083 NOTE: Command-line completion is not supported.
5084
5085 Can also be used as a |method|: >
5086 GetPrompt()->inputsecret()
5087
5088insert({object}, {item} [, {idx}]) *insert()*
5089 When {object} is a |List| or a |Blob| insert {item} at the start
5090 of it.
5091
5092 If {idx} is specified insert {item} before the item with index
5093 {idx}. If {idx} is zero it goes before the first item, just
5094 like omitting {idx}. A negative {idx} is also possible, see
5095 |list-index|. -1 inserts just before the last item.
5096
5097 Returns the resulting |List| or |Blob|. Examples: >
5098 :let mylist = insert([2, 3, 5], 1)
5099 :call insert(mylist, 4, -1)
5100 :call insert(mylist, 6, len(mylist))
5101< The last example can be done simpler with |add()|.
5102 Note that when {item} is a |List| it is inserted as a single
5103 item. Use |extend()| to concatenate |Lists|.
5104
5105 Can also be used as a |method|: >
5106 mylist->insert(item)
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005107<
5108 *instanceof()* *E614* *E616* *E693*
5109instanceof({object}, {class})
5110 The result is a Number, which is |TRUE| when the {object}
Ernie Rael2025af12023-12-12 16:58:00 +01005111 argument is a direct or indirect instance of a |Class|,
5112 |Interface|, or class |:type| alias specified by {class}.
5113 If {class} is varargs, the function returns |TRUE| when
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005114 {object} is an instance of any of the specified classes.
LemonBoyafe04662023-08-23 21:08:11 +02005115 Example: >
Ernie Rael2025af12023-12-12 16:58:00 +01005116 instanceof(animal, Dog, Cat)
LemonBoyafe04662023-08-23 21:08:11 +02005117
5118< Can also be used as a |method|: >
5119 myobj->instanceof(mytype)
5120
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005121interrupt() *interrupt()*
5122 Interrupt script execution. It works more or less like the
5123 user typing CTRL-C, most commands won't execute and control
5124 returns to the user. This is useful to abort execution
5125 from lower down, e.g. in an autocommand. Example: >
5126 :function s:check_typoname(file)
5127 : if fnamemodify(a:file, ':t') == '['
5128 : echomsg 'Maybe typo'
5129 : call interrupt()
5130 : endif
5131 :endfunction
5132 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
5133
5134invert({expr}) *invert()*
5135 Bitwise invert. The argument is converted to a number. A
5136 List, Dict or Float argument causes an error. Example: >
5137 :let bits = invert(bits)
5138< Can also be used as a |method|: >
5139 :let bits = bits->invert()
5140
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005141isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01005142 The result is a Number, which is |TRUE| when {path} is an
5143 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005144 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01005145 On MS-Windows, it is considered absolute when it starts with an
5146 optional drive prefix and is followed by a '\' or '/'. UNC paths
5147 are always absolute.
5148 Example: >
5149 echo isabsolutepath('/usr/share/') " 1
5150 echo isabsolutepath('./foobar') " 0
5151 echo isabsolutepath('C:\Windows') " 1
5152 echo isabsolutepath('foobar') " 0
5153 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005154<
LemonBoydca1d402022-04-28 15:26:33 +01005155 Can also be used as a |method|: >
5156 GetName()->isabsolutepath()
5157
5158
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005159isdirectory({directory}) *isdirectory()*
5160 The result is a Number, which is |TRUE| when a directory
5161 with the name {directory} exists. If {directory} doesn't
5162 exist, or isn't a directory, the result is |FALSE|. {directory}
5163 is any expression, which is used as a String.
5164
5165 Can also be used as a |method|: >
5166 GetName()->isdirectory()
5167
5168isinf({expr}) *isinf()*
5169 Return 1 if {expr} is a positive infinity, or -1 a negative
5170 infinity, otherwise 0. >
5171 :echo isinf(1.0 / 0.0)
5172< 1 >
5173 :echo isinf(-1.0 / 0.0)
5174< -1
5175
5176 Can also be used as a |method|: >
5177 Compute()->isinf()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005178
5179islocked({expr}) *islocked()* *E786*
5180 The result is a Number, which is |TRUE| when {expr} is the
5181 name of a locked variable.
5182 The string argument {expr} must be the name of a variable,
5183 |List| item or |Dictionary| entry, not the variable itself!
5184 Example: >
5185 :let alist = [0, ['a', 'b'], 2, 3]
5186 :lockvar 1 alist
5187 :echo islocked('alist') " 1
5188 :echo islocked('alist[1]') " 0
5189
Bram Moolenaar9da17d72022-02-09 21:50:44 +00005190< When {expr} is a variable that does not exist -1 is returned.
5191 If {expr} uses a range, list or dict index that is out of
5192 range or does not exist you get an error message. Use
5193 |exists()| to check for existence.
5194 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005195
5196 Can also be used as a |method|: >
5197 GetName()->islocked()
5198
5199isnan({expr}) *isnan()*
5200 Return |TRUE| if {expr} is a float with value NaN. >
5201 echo isnan(0.0 / 0.0)
5202< 1
5203
5204 Can also be used as a |method|: >
5205 Compute()->isnan()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005206
5207items({dict}) *items()*
5208 Return a |List| with all the key-value pairs of {dict}. Each
5209 |List| item is a list with two items: the key of a {dict}
5210 entry and the value of this entry. The |List| is in arbitrary
5211 order. Also see |keys()| and |values()|.
5212 Example: >
5213 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005214 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005215 endfor
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01005216<
5217 A List or a String argument is also supported. In these
5218 cases, items() returns a List with the index and the value at
5219 the index.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005220
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01005221 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005222 mydict->items()
5223
5224job_ functions are documented here: |job-functions-details|
5225
5226
5227join({list} [, {sep}]) *join()*
5228 Join the items in {list} together into one String.
5229 When {sep} is specified it is put in between the items. If
5230 {sep} is omitted a single space is used.
5231 Note that {sep} is not added at the end. You might want to
5232 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005233 let lines = join(mylist, "\n") .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005234< String items are used as-is. |Lists| and |Dictionaries| are
5235 converted into a string like with |string()|.
5236 The opposite function is |split()|.
5237
5238 Can also be used as a |method|: >
5239 mylist->join()
5240
5241js_decode({string}) *js_decode()*
5242 This is similar to |json_decode()| with these differences:
5243 - Object key names do not have to be in quotes.
5244 - Strings can be in single quotes.
5245 - Empty items in an array (between two commas) are allowed and
5246 result in v:none items.
5247
5248 Can also be used as a |method|: >
5249 ReadObject()->js_decode()
5250
5251js_encode({expr}) *js_encode()*
5252 This is similar to |json_encode()| with these differences:
5253 - Object key names are not in quotes.
5254 - v:none items in an array result in an empty item between
5255 commas.
5256 For example, the Vim object:
5257 [1,v:none,{"one":1},v:none] ~
5258 Will be encoded as:
5259 [1,,{one:1},,] ~
5260 While json_encode() would produce:
5261 [1,null,{"one":1},null] ~
5262 This encoding is valid for JavaScript. It is more efficient
5263 than JSON, especially when using an array with optional items.
5264
5265 Can also be used as a |method|: >
5266 GetObject()->js_encode()
5267
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005268json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005269 This parses a JSON formatted string and returns the equivalent
5270 in Vim values. See |json_encode()| for the relation between
5271 JSON and Vim values.
5272 The decoding is permissive:
5273 - A trailing comma in an array and object is ignored, e.g.
5274 "[1, 2, ]" is the same as "[1, 2]".
5275 - Integer keys are accepted in objects, e.g. {1:2} is the
5276 same as {"1":2}.
5277 - More floating point numbers are recognized, e.g. "1." for
5278 "1.0", or "001.2" for "1.2". Special floating point values
5279 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
5280 are accepted.
5281 - Leading zeroes in integer numbers are ignored, e.g. "012"
5282 for "12" or "-012" for "-12".
5283 - Capitalization is ignored in literal names null, true or
5284 false, e.g. "NULL" for "null", "True" for "true".
5285 - Control characters U+0000 through U+001F which are not
5286 escaped in strings are accepted, e.g. " " (tab
5287 character in string) for "\t".
5288 - An empty JSON expression or made of only spaces is accepted
5289 and results in v:none.
5290 - Backslash in an invalid 2-character sequence escape is
5291 ignored, e.g. "\a" is decoded as "a".
5292 - A correct surrogate pair in JSON strings should normally be
5293 a 12 character sequence such as "\uD834\uDD1E", but
5294 json_decode() silently accepts truncated surrogate pairs
5295 such as "\uD834" or "\uD834\u"
5296 *E938*
5297 A duplicate key in an object, valid in rfc7159, is not
5298 accepted by json_decode() as the result must be a valid Vim
5299 type, e.g. this fails: {"a":"b", "a":"c"}
5300
5301 Can also be used as a |method|: >
5302 ReadObject()->json_decode()
5303
5304json_encode({expr}) *json_encode()*
5305 Encode {expr} as JSON and return this as a string.
5306 The encoding is specified in:
5307 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00005308 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005309 |Number| decimal number
5310 |Float| floating point number
5311 Float nan "NaN"
5312 Float inf "Infinity"
5313 Float -inf "-Infinity"
5314 |String| in double quotes (possibly null)
5315 |Funcref| not possible, error
5316 |List| as an array (possibly null); when
5317 used recursively: []
5318 |Dict| as an object (possibly null); when
5319 used recursively: {}
5320 |Blob| as an array of the individual bytes
5321 v:false "false"
5322 v:true "true"
5323 v:none "null"
5324 v:null "null"
5325 Note that NaN and Infinity are passed on as values. This is
5326 missing in the JSON standard, but several implementations do
5327 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01005328 If a string contains an illegal character then the replacement
5329 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005330
5331 Can also be used as a |method|: >
5332 GetObject()->json_encode()
5333
5334keys({dict}) *keys()*
5335 Return a |List| with all the keys of {dict}. The |List| is in
5336 arbitrary order. Also see |items()| and |values()|.
5337
5338 Can also be used as a |method|: >
5339 mydict->keys()
5340
zeertzjqcdc83932022-09-12 13:38:41 +01005341keytrans({string}) *keytrans()*
5342 Turn the internal byte representation of keys into a form that
5343 can be used for |:map|. E.g. >
5344 :let xx = "\<C-Home>"
5345 :echo keytrans(xx)
5346< <C-Home>
5347
5348 Can also be used as a |method|: >
5349 "\<C-Home>"->keytrans()
5350
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005351< *len()* *E701*
5352len({expr}) The result is a Number, which is the length of the argument.
5353 When {expr} is a String or a Number the length in bytes is
5354 used, as with |strlen()|.
5355 When {expr} is a |List| the number of items in the |List| is
5356 returned.
5357 When {expr} is a |Blob| the number of bytes is returned.
5358 When {expr} is a |Dictionary| the number of entries in the
5359 |Dictionary| is returned.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005360 Otherwise an error is given and returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005361
5362 Can also be used as a |method|: >
5363 mylist->len()
5364
5365< *libcall()* *E364* *E368*
5366libcall({libname}, {funcname}, {argument})
5367 Call function {funcname} in the run-time library {libname}
5368 with single argument {argument}.
5369 This is useful to call functions in a library that you
5370 especially made to be used with Vim. Since only one argument
5371 is possible, calling standard library functions is rather
5372 limited.
5373 The result is the String returned by the function. If the
5374 function returns NULL, this will appear as an empty string ""
5375 to Vim.
5376 If the function returns a number, use libcallnr()!
5377 If {argument} is a number, it is passed to the function as an
5378 int; if {argument} is a string, it is passed as a
5379 null-terminated string.
5380 This function will fail in |restricted-mode|.
5381
5382 libcall() allows you to write your own 'plug-in' extensions to
5383 Vim without having to recompile the program. It is NOT a
5384 means to call system functions! If you try to do so Vim will
5385 very probably crash.
5386
5387 For Win32, the functions you write must be placed in a DLL
5388 and use the normal C calling convention (NOT Pascal which is
5389 used in Windows System DLLs). The function must take exactly
5390 one parameter, either a character pointer or a long integer,
5391 and must return a character pointer or NULL. The character
5392 pointer returned must point to memory that will remain valid
5393 after the function has returned (e.g. in static data in the
5394 DLL). If it points to allocated memory, that memory will
5395 leak away. Using a static buffer in the function should work,
5396 it's then freed when the DLL is unloaded.
5397
5398 WARNING: If the function returns a non-valid pointer, Vim may
5399 crash! This also happens if the function returns a number,
5400 because Vim thinks it's a pointer.
5401 For Win32 systems, {libname} should be the filename of the DLL
5402 without the ".DLL" suffix. A full path is only required if
5403 the DLL is not in the usual places.
5404 For Unix: When compiling your own plugins, remember that the
5405 object code must be compiled as position-independent ('PIC').
5406 {only in Win32 and some Unix versions, when the |+libcall|
5407 feature is present}
5408 Examples: >
5409 :echo libcall("libc.so", "getenv", "HOME")
5410
5411< Can also be used as a |method|, the base is passed as the
5412 third argument: >
5413 GetValue()->libcall("libc.so", "getenv")
5414<
5415 *libcallnr()*
5416libcallnr({libname}, {funcname}, {argument})
5417 Just like |libcall()|, but used for a function that returns an
5418 int instead of a string.
5419 {only in Win32 on some Unix versions, when the |+libcall|
5420 feature is present}
5421 Examples: >
5422 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
5423 :call libcallnr("libc.so", "printf", "Hello World!\n")
5424 :call libcallnr("libc.so", "sleep", 10)
5425<
5426 Can also be used as a |method|, the base is passed as the
5427 third argument: >
5428 GetValue()->libcallnr("libc.so", "printf")
5429<
5430
5431line({expr} [, {winid}]) *line()*
5432 The result is a Number, which is the line number of the file
5433 position given with {expr}. The {expr} argument is a string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00005434 The accepted positions are: *E1209*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005435 . the cursor position
5436 $ the last line in the current buffer
5437 'x position of mark x (if the mark is not set, 0 is
5438 returned)
5439 w0 first line visible in current window (one if the
5440 display isn't updated, e.g. in silent Ex mode)
5441 w$ last line visible in current window (this is one
5442 less than "w0" if no lines are visible)
5443 v In Visual mode: the start of the Visual area (the
5444 cursor is the end). When not in Visual mode
5445 returns the cursor position. Differs from |'<| in
5446 that it's updated right away.
5447 Note that a mark in another file can be used. The line number
5448 then applies to another buffer.
5449 To get the column number use |col()|. To get both use
5450 |getpos()|.
5451 With the optional {winid} argument the values are obtained for
5452 that window instead of the current window.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005453 Returns 0 for invalid values of {expr} and {winid}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005454 Examples: >
5455 line(".") line number of the cursor
5456 line(".", winid) idem, in window "winid"
5457 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005458 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005459<
5460 To jump to the last known position when opening a file see
5461 |last-position-jump|.
5462
5463 Can also be used as a |method|: >
5464 GetValue()->line()
5465
5466line2byte({lnum}) *line2byte()*
5467 Return the byte count from the start of the buffer for line
5468 {lnum}. This includes the end-of-line character, depending on
5469 the 'fileformat' option for the current buffer. The first
5470 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
5471 This can also be used to get the byte count for the line just
5472 below the last line: >
5473 line2byte(line("$") + 1)
5474< This is the buffer size plus one. If 'fileencoding' is empty
5475 it is the file size plus one. {lnum} is used like with
5476 |getline()|. When {lnum} is invalid, or the |+byte_offset|
5477 feature has been disabled at compile time, -1 is returned.
5478 Also see |byte2line()|, |go| and |:goto|.
5479
5480 Can also be used as a |method|: >
5481 GetLnum()->line2byte()
5482
5483lispindent({lnum}) *lispindent()*
5484 Get the amount of indent for line {lnum} according the lisp
5485 indenting rules, as with 'lisp'.
5486 The indent is counted in spaces, the value of 'tabstop' is
5487 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01005488 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005489 error is given.
5490
5491 Can also be used as a |method|: >
5492 GetLnum()->lispindent()
5493
5494list2blob({list}) *list2blob()*
5495 Return a Blob concatenating all the number values in {list}.
5496 Examples: >
5497 list2blob([1, 2, 3, 4]) returns 0z01020304
5498 list2blob([]) returns 0z
5499< Returns an empty Blob on error. If one of the numbers is
5500 negative or more than 255 error *E1239* is given.
5501
5502 |blob2list()| does the opposite.
5503
5504 Can also be used as a |method|: >
5505 GetList()->list2blob()
5506
5507list2str({list} [, {utf8}]) *list2str()*
5508 Convert each number in {list} to a character string can
5509 concatenate them all. Examples: >
5510 list2str([32]) returns " "
5511 list2str([65, 66, 67]) returns "ABC"
5512< The same can be done (slowly) with: >
5513 join(map(list, {nr, val -> nr2char(val)}), '')
5514< |str2list()| does the opposite.
5515
5516 When {utf8} is omitted or zero, the current 'encoding' is used.
5517 When {utf8} is TRUE, always return UTF-8 characters.
5518 With UTF-8 composing characters work as expected: >
5519 list2str([97, 769]) returns "á"
5520<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005521 Returns an empty string on error.
5522
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005523 Can also be used as a |method|: >
5524 GetList()->list2str()
5525
5526listener_add({callback} [, {buf}]) *listener_add()*
5527 Add a callback function that will be invoked when changes have
5528 been made to buffer {buf}.
5529 {buf} refers to a buffer name or number. For the accepted
5530 values, see |bufname()|. When {buf} is omitted the current
5531 buffer is used.
5532 Returns a unique ID that can be passed to |listener_remove()|.
5533
5534 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00005535 bufnr the buffer that was changed
5536 start first changed line number
5537 end first line number below the change
5538 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005539 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00005540 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005541
5542 Example: >
5543 func Listener(bufnr, start, end, added, changes)
5544 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
5545 endfunc
5546 call listener_add('Listener', bufnr)
5547
Bram Moolenaar944697a2022-02-20 19:48:20 +00005548< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005549 dictionary with these entries:
5550 lnum the first line number of the change
5551 end the first line below the change
5552 added number of lines added; negative if lines were
5553 deleted
5554 col first column in "lnum" that was affected by
5555 the change; one if unknown or the whole line
5556 was affected; this is a byte index, first
5557 character has a value of one.
Bram Moolenaar3c053a12022-10-16 13:11:12 +01005558 When lines are inserted (not when a line is split, e.g. by
5559 typing CR in Insert mode) the values are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005560 lnum line above which the new line is added
5561 end equal to "lnum"
5562 added number of lines inserted
5563 col 1
5564 When lines are deleted the values are:
5565 lnum the first deleted line
5566 end the line below the first deleted line, before
5567 the deletion was done
5568 added negative, number of lines deleted
5569 col 1
5570 When lines are changed:
5571 lnum the first changed line
5572 end the line below the last changed line
5573 added 0
5574 col first column with a change or 1
5575
5576 The entries are in the order the changes were made, thus the
5577 most recent change is at the end. The line numbers are valid
5578 when the callback is invoked, but later changes may make them
5579 invalid, thus keeping a copy for later might not work.
5580
5581 The {callback} is invoked just before the screen is updated,
5582 when |listener_flush()| is called or when a change is being
5583 made that changes the line count in a way it causes a line
5584 number in the list of changes to become invalid.
5585
5586 The {callback} is invoked with the text locked, see
5587 |textlock|. If you do need to make changes to the buffer, use
5588 a timer to do this later |timer_start()|.
5589
5590 The {callback} is not invoked when the buffer is first loaded.
5591 Use the |BufReadPost| autocmd event to handle the initial text
5592 of a buffer.
5593 The {callback} is also not invoked when the buffer is
5594 unloaded, use the |BufUnload| autocmd event for that.
5595
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005596 Returns zero if {callback} or {buf} is invalid.
5597
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005598 Can also be used as a |method|, the base is passed as the
5599 second argument: >
5600 GetBuffer()->listener_add(callback)
5601
5602listener_flush([{buf}]) *listener_flush()*
5603 Invoke listener callbacks for buffer {buf}. If there are no
5604 pending changes then no callbacks are invoked.
5605
5606 {buf} refers to a buffer name or number. For the accepted
5607 values, see |bufname()|. When {buf} is omitted the current
5608 buffer is used.
5609
5610 Can also be used as a |method|: >
5611 GetBuffer()->listener_flush()
5612
5613listener_remove({id}) *listener_remove()*
5614 Remove a listener previously added with listener_add().
5615 Returns FALSE when {id} could not be found, TRUE when {id} was
5616 removed.
5617
5618 Can also be used as a |method|: >
5619 GetListenerId()->listener_remove()
5620
5621localtime() *localtime()*
5622 Return the current time, measured as seconds since 1st Jan
5623 1970. See also |strftime()|, |strptime()| and |getftime()|.
5624
5625
5626log({expr}) *log()*
5627 Return the natural logarithm (base e) of {expr} as a |Float|.
5628 {expr} must evaluate to a |Float| or a |Number| in the range
5629 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005630 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005631 Examples: >
5632 :echo log(10)
5633< 2.302585 >
5634 :echo log(exp(5))
5635< 5.0
5636
5637 Can also be used as a |method|: >
5638 Compute()->log()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005639
5640
5641log10({expr}) *log10()*
5642 Return the logarithm of Float {expr} to base 10 as a |Float|.
5643 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005644 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005645 Examples: >
5646 :echo log10(1000)
5647< 3.0 >
5648 :echo log10(0.01)
5649< -2.0
5650
5651 Can also be used as a |method|: >
5652 Compute()->log10()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005653
5654luaeval({expr} [, {expr}]) *luaeval()*
5655 Evaluate Lua expression {expr} and return its result converted
5656 to Vim data structures. Second {expr} may hold additional
5657 argument accessible as _A inside first {expr}.
5658 Strings are returned as they are.
5659 Boolean objects are converted to numbers.
Bram Moolenaar73e28dc2022-09-17 21:08:33 +01005660 Numbers are converted to |Float| values.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005661 Dictionaries and lists obtained by vim.eval() are returned
5662 as-is.
5663 Other objects are returned as zero without any errors.
5664 See |lua-luaeval| for more details.
5665 Note that in a `:def` function local variables are not visible
5666 to {expr}.
5667
5668 Can also be used as a |method|: >
5669 GetExpr()->luaeval()
5670
5671< {only available when compiled with the |+lua| feature}
5672
5673map({expr1}, {expr2}) *map()*
5674 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00005675 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005676 item in {expr1} with the result of evaluating {expr2}.
5677 For a |Blob| each byte is replaced.
5678 For a |String|, each character, including composing
5679 characters, is replaced.
5680 If the item type changes you may want to use |mapnew()| to
5681 create a new List or Dictionary. This is required when using
5682 Vim9 script.
5683
5684 {expr2} must be a |String| or |Funcref|.
5685
5686 If {expr2} is a |String|, inside {expr2} |v:val| has the value
5687 of the current item. For a |Dictionary| |v:key| has the key
5688 of the current item and for a |List| |v:key| has the index of
5689 the current item. For a |Blob| |v:key| has the index of the
5690 current byte. For a |String| |v:key| has the index of the
5691 current character.
5692 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005693 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005694< This puts "> " before and " <" after each item in "mylist".
5695
5696 Note that {expr2} is the result of an expression and is then
5697 used as an expression again. Often it is good to use a
5698 |literal-string| to avoid having to double backslashes. You
5699 still have to double ' quotes
5700
5701 If {expr2} is a |Funcref| it is called with two arguments:
5702 1. The key or the index of the current item.
5703 2. the value of the current item.
Bram Moolenaarb59ae592022-11-23 23:46:31 +00005704 With a legacy script lambda you don't get an error if it only
5705 accepts one argument, but with a Vim9 lambda you get "E1106:
5706 One argument too many", the number of arguments must match.
5707
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005708 The function must return the new value of the item. Example
5709 that changes each value by "key-value": >
5710 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005711 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005712 endfunc
5713 call map(myDict, function('KeyValue'))
5714< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005715 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005716< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005717 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005718< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005719 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005720<
5721 The operation is done in-place for a |List| and |Dictionary|.
5722 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005723 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005724
5725< Returns {expr1}, the |List| or |Dictionary| that was filtered,
5726 or a new |Blob| or |String|.
5727 When an error is encountered while evaluating {expr2} no
5728 further items in {expr1} are processed.
5729 When {expr2} is a Funcref errors inside a function are ignored,
5730 unless it was defined with the "abort" flag.
5731
5732 Can also be used as a |method|: >
5733 mylist->map(expr2)
5734
5735
5736maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
5737 When {dict} is omitted or zero: Return the rhs of mapping
5738 {name} in mode {mode}. The returned String has special
5739 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01005740 listing. When {dict} is TRUE a dictionary is returned, see
5741 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005742
5743 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005744 returned if {dict} is FALSE, otherwise returns an empty Dict.
5745 When the mapping for {name} is empty, then "<Nop>" is
5746 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005747
5748 The {name} can have special key names, like in the ":map"
5749 command.
5750
5751 {mode} can be one of these strings:
5752 "n" Normal
5753 "v" Visual (including Select)
5754 "o" Operator-pending
5755 "i" Insert
5756 "c" Cmd-line
5757 "s" Select
5758 "x" Visual
5759 "l" langmap |language-mapping|
5760 "t" Terminal-Job
5761 "" Normal, Visual and Operator-pending
5762 When {mode} is omitted, the modes for "" are used.
5763
5764 When {abbr} is there and it is |TRUE| use abbreviations
5765 instead of mappings.
5766
5767 When {dict} is there and it is |TRUE| return a dictionary
5768 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01005769 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005770 "lhs" The {lhs} of the mapping as it would be typed
5771 "lhsraw" The {lhs} of the mapping as raw bytes
5772 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
5773 form, only present when it differs from "lhsraw"
5774 "rhs" The {rhs} of the mapping as typed.
5775 "silent" 1 for a |:map-silent| mapping, else 0.
5776 "noremap" 1 if the {rhs} of the mapping is not remappable.
5777 "script" 1 if mapping was defined with <script>.
5778 "expr" 1 for an expression mapping (|:map-<expr>|).
5779 "buffer" 1 for a buffer local mapping (|:map-local|).
5780 "mode" Modes for which the mapping is defined. In
5781 addition to the modes mentioned above, these
5782 characters will be used:
5783 " " Normal, Visual and Operator-pending
5784 "!" Insert and Commandline mode
5785 (|mapmode-ic|)
5786 "sid" The script local ID, used for <sid> mappings
Bram Moolenaar71badf92023-04-22 22:40:14 +01005787 (|<SID>|). Negative for special contexts.
Bram Moolenaara9528b32022-01-18 20:51:35 +00005788 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005789 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005790 "lnum" The line number in "sid", zero if unknown.
5791 "nowait" Do not wait for other, longer mappings.
5792 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01005793 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01005794 "mode_bits" Vim's internal binary representation of "mode".
5795 |mapset()| ignores this; only "mode" is used.
5796 See |maplist()| for usage examples. The values
5797 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005798
5799 The dictionary can be used to restore a mapping with
5800 |mapset()|.
5801
5802 The mappings local to the current buffer are checked first,
5803 then the global mappings.
5804 This function can be used to map a key even when it's already
5805 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005806 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005807
5808< Can also be used as a |method|: >
5809 GetKey()->maparg('n')
5810
5811mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
5812 Check if there is a mapping that matches with {name} in mode
5813 {mode}. See |maparg()| for {mode} and special names in
5814 {name}.
5815 When {abbr} is there and it is |TRUE| use abbreviations
5816 instead of mappings.
5817 A match happens with a mapping that starts with {name} and
5818 with a mapping which is equal to the start of {name}.
5819
5820 matches mapping "a" "ab" "abc" ~
5821 mapcheck("a") yes yes yes
5822 mapcheck("abc") yes yes yes
5823 mapcheck("ax") yes no no
5824 mapcheck("b") no no no
5825
5826 The difference with maparg() is that mapcheck() finds a
5827 mapping that matches with {name}, while maparg() only finds a
5828 mapping for {name} exactly.
5829 When there is no mapping that starts with {name}, an empty
5830 String is returned. If there is one, the RHS of that mapping
5831 is returned. If there are several mappings that start with
5832 {name}, the RHS of one of them is returned. This will be
5833 "<Nop>" if the RHS is empty.
5834 The mappings local to the current buffer are checked first,
5835 then the global mappings.
5836 This function can be used to check if a mapping can be added
5837 without being ambiguous. Example: >
5838 :if mapcheck("_vv") == ""
5839 : map _vv :set guifont=7x13<CR>
5840 :endif
5841< This avoids adding the "_vv" mapping when there already is a
5842 mapping for "_v" or for "_vvv".
5843
5844 Can also be used as a |method|: >
5845 GetKey()->mapcheck('n')
5846
5847
Ernie Rael09661202022-04-25 14:40:44 +01005848maplist([{abbr}]) *maplist()*
5849 Returns a |List| of all mappings. Each List item is a |Dict|,
5850 the same as what is returned by |maparg()|, see
5851 |mapping-dict|. When {abbr} is there and it is |TRUE| use
5852 abbreviations instead of mappings.
5853
5854 Example to show all mappings with 'MultiMatch' in rhs: >
5855 vim9script
5856 echo maplist()->filter(
5857 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01005858< It can be tricky to find mappings for particular |:map-modes|.
5859 |mapping-dict|'s "mode_bits" can simplify this. For example,
5860 the mode_bits for Normal, Insert or Command-line modes are
5861 0x19. To find all the mappings available in those modes you
5862 can do: >
5863 vim9script
5864 var saved_maps = []
5865 for m in maplist()
5866 if and(m.mode_bits, 0x19) != 0
5867 saved_maps->add(m)
5868 endif
5869 endfor
5870 echo saved_maps->mapnew((_, m) => m.lhs)
5871< The values of the mode_bits are defined in Vim's src/vim.h
5872 file and they can be discovered at runtime using
5873 |:map-commands| and "maplist()". Example: >
5874 vim9script
5875 omap xyzzy <Nop>
5876 var op_bit = maplist()->filter(
5877 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
5878 ounmap xyzzy
5879 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Ernie Rael09661202022-04-25 14:40:44 +01005880
5881
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005882mapnew({expr1}, {expr2}) *mapnew()*
5883 Like |map()| but instead of replacing items in {expr1} a new
5884 List or Dictionary is created and returned. {expr1} remains
5885 unchanged. Items can still be changed by {expr2}, if you
5886 don't want that use |deepcopy()| first.
5887
5888
5889mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01005890mapset({dict})
5891 Restore a mapping from a dictionary, possibly returned by
5892 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
5893 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005894 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01005895 feature allows copying mappings from one buffer to another.
5896 The dict.mode value may restore a single mapping that covers
5897 more than one mode, like with mode values of '!', ' ', 'nox',
5898 or 'v'. *E1276*
5899
5900 In the first form, {mode} and {abbr} should be the same as
5901 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005902 {mode} is used to define the mode in which the mapping is set,
5903 not the "mode" entry in {dict}.
5904 Example for saving and restoring a mapping: >
5905 let save_map = maparg('K', 'n', 0, 1)
5906 nnoremap K somethingelse
5907 ...
5908 call mapset('n', 0, save_map)
5909< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01005910 e.g. with `:map!`, you need to save/restore the mapping for
5911 all of them, when they might differ.
5912
5913 In the second form, with {dict} as the only argument, mode
5914 and abbr are taken from the dict.
5915 Example: >
5916 vim9script
5917 var save_maps = maplist()->filter(
5918 (_, m) => m.lhs == 'K')
5919 nnoremap K somethingelse
5920 cnoremap K somethingelse2
5921 # ...
5922 unmap K
5923 for d in save_maps
5924 mapset(d)
5925 endfor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005926
5927
5928match({expr}, {pat} [, {start} [, {count}]]) *match()*
5929 When {expr} is a |List| then this returns the index of the
5930 first item where {pat} matches. Each item is used as a
5931 String, |Lists| and |Dictionaries| are used as echoed.
5932
5933 Otherwise, {expr} is used as a String. The result is a
5934 Number, which gives the index (byte offset) in {expr} where
5935 {pat} matches.
5936
5937 A match at the first character or |List| item returns zero.
5938 If there is no match -1 is returned.
5939
5940 For getting submatches see |matchlist()|.
5941 Example: >
5942 :echo match("testing", "ing") " results in 4
5943 :echo match([1, 'x'], '\a') " results in 1
5944< See |string-match| for how {pat} is used.
5945 *strpbrk()*
5946 Vim doesn't have a strpbrk() function. But you can do: >
5947 :let sepidx = match(line, '[.,;: \t]')
5948< *strcasestr()*
5949 Vim doesn't have a strcasestr() function. But you can add
5950 "\c" to the pattern to ignore case: >
5951 :let idx = match(haystack, '\cneedle')
5952<
5953 If {start} is given, the search starts from byte index
5954 {start} in a String or item {start} in a |List|.
5955 The result, however, is still the index counted from the
5956 first character/item. Example: >
5957 :echo match("testing", "ing", 2)
5958< result is again "4". >
5959 :echo match("testing", "ing", 4)
5960< result is again "4". >
5961 :echo match("testing", "t", 2)
5962< result is "3".
5963 For a String, if {start} > 0 then it is like the string starts
5964 {start} bytes later, thus "^" will match at {start}. Except
5965 when {count} is given, then it's like matches before the
5966 {start} byte are ignored (this is a bit complicated to keep it
5967 backwards compatible).
5968 For a String, if {start} < 0, it will be set to 0. For a list
5969 the index is counted from the end.
5970 If {start} is out of range ({start} > strlen({expr}) for a
5971 String or {start} > len({expr}) for a |List|) -1 is returned.
5972
5973 When {count} is given use the {count}'th match. When a match
5974 is found in a String the search for the next one starts one
5975 character further. Thus this example results in 1: >
5976 echo match("testing", "..", 0, 2)
5977< In a |List| the search continues in the next item.
5978 Note that when {count} is added the way {start} works changes,
5979 see above.
5980
5981 See |pattern| for the patterns that are accepted.
5982 The 'ignorecase' option is used to set the ignore-caseness of
5983 the pattern. 'smartcase' is NOT used. The matching is always
5984 done like 'magic' is set and 'cpoptions' is empty.
5985 Note that a match at the start is preferred, thus when the
5986 pattern is using "*" (any number of matches) it tends to find
5987 zero matches at the start instead of a number of matches
5988 further down in the text.
5989
5990 Can also be used as a |method|: >
5991 GetText()->match('word')
5992 GetList()->match('word')
5993<
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005994 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005995matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
5996 Defines a pattern to be highlighted in the current window (a
5997 "match"). It will be highlighted with {group}. Returns an
5998 identification number (ID), which can be used to delete the
5999 match using |matchdelete()|. The ID is bound to the window.
6000 Matching is case sensitive and magic, unless case sensitivity
6001 or magicness are explicitly overridden in {pattern}. The
6002 'magic', 'smartcase' and 'ignorecase' options are not used.
6003 The "Conceal" value is special, it causes the match to be
6004 concealed.
6005
6006 The optional {priority} argument assigns a priority to the
6007 match. A match with a high priority will have its
6008 highlighting overrule that of a match with a lower priority.
6009 A priority is specified as an integer (negative numbers are no
6010 exception). If the {priority} argument is not specified, the
6011 default priority is 10. The priority of 'hlsearch' is zero,
6012 hence all matches with a priority greater than zero will
6013 overrule it. Syntax highlighting (see 'syntax') is a separate
6014 mechanism, and regardless of the chosen priority a match will
6015 always overrule syntax highlighting.
6016
6017 The optional {id} argument allows the request for a specific
6018 match ID. If a specified ID is already taken, an error
6019 message will appear and the match will not be added. An ID
6020 is specified as a positive integer (zero excluded). IDs 1, 2
6021 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01006022 respectively. 3 is reserved for use by the |matchparen|
6023 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01006024 If the {id} argument is not specified or -1, |matchadd()|
Bram Moolenaar9f573a82022-09-29 13:50:08 +01006025 automatically chooses a free ID, which is at least 1000.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006026
6027 The optional {dict} argument allows for further custom
6028 values. Currently this is used to specify a match specific
6029 conceal character that will be shown for |hl-Conceal|
6030 highlighted matches. The dict can have the following members:
6031
6032 conceal Special character to show instead of the
6033 match (only for |hl-Conceal| highlighted
6034 matches, see |:syn-cchar|)
6035 window Instead of the current window use the
6036 window with this number or window ID.
6037
6038 The number of matches is not limited, as it is the case with
6039 the |:match| commands.
6040
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006041 Returns -1 on error.
6042
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006043 Example: >
6044 :highlight MyGroup ctermbg=green guibg=green
6045 :let m = matchadd("MyGroup", "TODO")
6046< Deletion of the pattern: >
6047 :call matchdelete(m)
6048
6049< A list of matches defined by |matchadd()| and |:match| are
6050 available from |getmatches()|. All matches can be deleted in
6051 one operation by |clearmatches()|.
6052
6053 Can also be used as a |method|: >
6054 GetGroup()->matchadd('TODO')
6055<
6056 *matchaddpos()*
6057matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
6058 Same as |matchadd()|, but requires a list of positions {pos}
6059 instead of a pattern. This command is faster than |matchadd()|
6060 because it does not require to handle regular expressions and
6061 sets buffer line boundaries to redraw screen. It is supposed
6062 to be used when fast match additions and deletions are
6063 required, for example to highlight matching parentheses.
6064
6065 {pos} is a list of positions. Each position can be one of
6066 these:
6067 - A number. This whole line will be highlighted. The first
6068 line has number 1.
6069 - A list with one number, e.g., [23]. The whole line with this
6070 number will be highlighted.
6071 - A list with two numbers, e.g., [23, 11]. The first number is
6072 the line number, the second one is the column number (first
6073 column is 1, the value must correspond to the byte index as
6074 |col()| would return). The character at this position will
6075 be highlighted.
6076 - A list with three numbers, e.g., [23, 11, 3]. As above, but
6077 the third number gives the length of the highlight in bytes.
6078
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006079 Returns -1 on error.
6080
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006081 Example: >
6082 :highlight MyGroup ctermbg=green guibg=green
6083 :let m = matchaddpos("MyGroup", [[23, 24], 34])
6084< Deletion of the pattern: >
6085 :call matchdelete(m)
6086
6087< Matches added by |matchaddpos()| are returned by
6088 |getmatches()|.
6089
6090 Can also be used as a |method|: >
6091 GetGroup()->matchaddpos([23, 11])
6092
6093matcharg({nr}) *matcharg()*
6094 Selects the {nr} match item, as set with a |:match|,
6095 |:2match| or |:3match| command.
6096 Return a |List| with two elements:
6097 The name of the highlight group used
6098 The pattern used.
6099 When {nr} is not 1, 2 or 3 returns an empty |List|.
6100 When there is no match item set returns ['', ''].
6101 This is useful to save and restore a |:match|.
6102 Highlighting matches using the |:match| commands are limited
6103 to three matches. |matchadd()| does not have this limitation.
6104
6105 Can also be used as a |method|: >
6106 GetMatch()->matcharg()
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006107<
6108 *matchbufline()*
6109matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])
6110 Returns the |List| of matches in lines from {lnum} to {end} in
6111 buffer {buf} where {pat} matches.
6112
6113 {lnum} and {end} can either be a line number or the string "$"
6114 to refer to the last line in {buf}.
6115
6116 The {dict} argument supports following items:
6117 submatches include submatch information (|/\(|)
6118
6119 For each match, a |Dict| with the following items is returned:
6120 byteidx starting byte index of the match
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08006121 lnum line number where there is a match
6122 text matched string
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006123 Note that there can be multiple matches in a single line.
6124
6125 This function works only for loaded buffers. First call
6126 |bufload()| if needed.
6127
6128 When {buf} is not a valid buffer, the buffer is not loaded or
6129 {lnum} or {end} is not valid then an error is given and an
6130 empty |List| is returned.
6131
6132 Examples: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08006133 " Assuming line 3 in buffer 5 contains "a"
6134 :echo matchbufline(5, '\<\k\+\>', 3, 3)
6135 [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
6136 " Assuming line 4 in buffer 10 contains "tik tok"
6137 :echo matchbufline(10, '\<\k\+\>', 1, 4)
6138 [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006139<
6140 If {submatch} is present and is v:true, then submatches like
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08006141 "\1", "\2", etc. are also returned. Example: >
6142 " Assuming line 2 in buffer 2 contains "acd"
6143 :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006144 \ {'submatches': v:true})
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08006145 [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006146< The "submatches" List always contains 9 items. If a submatch
6147 is not found, then an empty string is returned for that
6148 submatch.
6149
6150 Can also be used as a |method|: >
6151 GetBuffer()->matchbufline('mypat', 1, '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006152
6153matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
6154 Deletes a match with ID {id} previously defined by |matchadd()|
6155 or one of the |:match| commands. Returns 0 if successful,
6156 otherwise -1. See example for |matchadd()|. All matches can
6157 be deleted in one operation by |clearmatches()|.
6158 If {win} is specified, use the window with this number or
6159 window ID instead of the current window.
6160
6161 Can also be used as a |method|: >
6162 GetMatch()->matchdelete()
6163
6164matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
6165 Same as |match()|, but return the index of first character
6166 after the match. Example: >
6167 :echo matchend("testing", "ing")
6168< results in "7".
6169 *strspn()* *strcspn()*
6170 Vim doesn't have a strspn() or strcspn() function, but you can
6171 do it with matchend(): >
6172 :let span = matchend(line, '[a-zA-Z]')
6173 :let span = matchend(line, '[^a-zA-Z]')
6174< Except that -1 is returned when there are no matches.
6175
6176 The {start}, if given, has the same meaning as for |match()|. >
6177 :echo matchend("testing", "ing", 2)
6178< results in "7". >
6179 :echo matchend("testing", "ing", 5)
6180< result is "-1".
6181 When {expr} is a |List| the result is equal to |match()|.
6182
6183 Can also be used as a |method|: >
6184 GetText()->matchend('word')
6185
6186
6187matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
6188 If {list} is a list of strings, then returns a |List| with all
6189 the strings in {list} that fuzzy match {str}. The strings in
6190 the returned list are sorted based on the matching score.
6191
6192 The optional {dict} argument always supports the following
6193 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01006194 matchseq When this item is present return only matches
6195 that contain the characters in {str} in the
6196 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01006197 limit Maximum number of matches in {list} to be
6198 returned. Zero means no limit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006199
6200 If {list} is a list of dictionaries, then the optional {dict}
6201 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01006202 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006203 {str}. The value of this item should be a
6204 string.
6205 text_cb |Funcref| that will be called for every item
6206 in {list} to get the text for fuzzy matching.
6207 This should accept a dictionary item as the
6208 argument and return the text for that item to
6209 use for fuzzy matching.
6210
6211 {str} is treated as a literal string and regular expression
6212 matching is NOT supported. The maximum supported {str} length
6213 is 256.
6214
6215 When {str} has multiple words each separated by white space,
6216 then the list of strings that have all the words is returned.
6217
6218 If there are no matching strings or there is an error, then an
6219 empty list is returned. If length of {str} is greater than
6220 256, then returns an empty list.
6221
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01006222 When {limit} is given, matchfuzzy() will find up to this
6223 number of matches in {list} and return them in sorted order.
6224
Bram Moolenaar1588bc82022-03-08 21:35:07 +00006225 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006226 matching strings.
6227
6228 Example: >
6229 :echo matchfuzzy(["clay", "crow"], "cay")
6230< results in ["clay"]. >
6231 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
6232< results in a list of buffer names fuzzy matching "ndl". >
6233 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
6234< results in a list of buffer information dicts with buffer
6235 names fuzzy matching "ndl". >
6236 :echo getbufinfo()->matchfuzzy("spl",
6237 \ {'text_cb' : {v -> v.name}})
6238< results in a list of buffer information dicts with buffer
6239 names fuzzy matching "spl". >
6240 :echo v:oldfiles->matchfuzzy("test")
6241< results in a list of file names fuzzy matching "test". >
6242 :let l = readfile("buffer.c")->matchfuzzy("str")
6243< results in a list of lines in "buffer.c" fuzzy matching "str". >
6244 :echo ['one two', 'two one']->matchfuzzy('two one')
6245< results in ['two one', 'one two']. >
6246 :echo ['one two', 'two one']->matchfuzzy('two one',
6247 \ {'matchseq': 1})
6248< results in ['two one'].
6249
6250matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
6251 Same as |matchfuzzy()|, but returns the list of matched
6252 strings, the list of character positions where characters
6253 in {str} matches and a list of matching scores. You can
6254 use |byteidx()| to convert a character position to a byte
6255 position.
6256
6257 If {str} matches multiple times in a string, then only the
6258 positions for the best match is returned.
6259
6260 If there are no matching strings or there is an error, then a
6261 list with three empty list items is returned.
6262
6263 Example: >
6264 :echo matchfuzzypos(['testing'], 'tsg')
6265< results in [['testing'], [[0, 2, 6]], [99]] >
6266 :echo matchfuzzypos(['clay', 'lacy'], 'la')
6267< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
6268 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
6269< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
6270
6271matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
6272 Same as |match()|, but return a |List|. The first item in the
6273 list is the matched string, same as what matchstr() would
6274 return. Following items are submatches, like "\1", "\2", etc.
6275 in |:substitute|. When an optional submatch didn't match an
6276 empty string is used. Example: >
6277 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
6278< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
6279 When there is no match an empty list is returned.
6280
6281 You can pass in a List, but that is not very useful.
6282
6283 Can also be used as a |method|: >
6284 GetText()->matchlist('word')
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006285<
6286 *matchstrlist()*
6287matchstrlist({list}, {pat} [, {dict}])
6288 Returns the |List| of matches in {list} where {pat} matches.
6289 {list} is a |List| of strings. {pat} is matched against each
6290 string in {list}.
6291
6292 The {dict} argument supports following items:
6293 submatches include submatch information (|/\(|)
6294
6295 For each match, a |Dict| with the following items is returned:
6296 byteidx starting byte index of the match.
6297 idx index in {list} of the match.
6298 text matched string
6299 submatches a List of submatches. Present only if
6300 "submatches" is set to v:true in {dict}.
6301
6302 Example: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08006303 :echo matchstrlist(['tik tok'], '\<\k\+\>')
6304 [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
6305 :echo matchstrlist(['a', 'b'], '\<\k\+\>')
6306 [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006307<
6308 If "submatches" is present and is v:true, then submatches like
6309 "\1", "\2", etc. are also returned. Example: >
6310 :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
6311 \ #{submatches: v:true})
6312 [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
6313< The "submatches" List always contains 9 items. If a submatch
6314 is not found, then an empty string is returned for that
6315 submatch.
6316
6317 Can also be used as a |method|: >
6318 GetListOfStrings()->matchstrlist('mypat')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006319
6320matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
6321 Same as |match()|, but return the matched string. Example: >
6322 :echo matchstr("testing", "ing")
6323< results in "ing".
6324 When there is no match "" is returned.
6325 The {start}, if given, has the same meaning as for |match()|. >
6326 :echo matchstr("testing", "ing", 2)
6327< results in "ing". >
6328 :echo matchstr("testing", "ing", 5)
6329< result is "".
6330 When {expr} is a |List| then the matching item is returned.
6331 The type isn't changed, it's not necessarily a String.
6332
6333 Can also be used as a |method|: >
6334 GetText()->matchstr('word')
6335
6336matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
6337 Same as |matchstr()|, but return the matched string, the start
6338 position and the end position of the match. Example: >
6339 :echo matchstrpos("testing", "ing")
6340< results in ["ing", 4, 7].
6341 When there is no match ["", -1, -1] is returned.
6342 The {start}, if given, has the same meaning as for |match()|. >
6343 :echo matchstrpos("testing", "ing", 2)
6344< results in ["ing", 4, 7]. >
6345 :echo matchstrpos("testing", "ing", 5)
6346< result is ["", -1, -1].
6347 When {expr} is a |List| then the matching item, the index
6348 of first item where {pat} matches, the start position and the
6349 end position of the match are returned. >
6350 :echo matchstrpos([1, '__x'], '\a')
6351< result is ["x", 1, 2, 3].
6352 The type isn't changed, it's not necessarily a String.
6353
6354 Can also be used as a |method|: >
6355 GetText()->matchstrpos('word')
6356<
6357
6358 *max()*
6359max({expr}) Return the maximum value of all items in {expr}. Example: >
6360 echo max([apples, pears, oranges])
6361
6362< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6363 it returns the maximum of all values in the Dictionary.
6364 If {expr} is neither a List nor a Dictionary, or one of the
6365 items in {expr} cannot be used as a Number this results in
6366 an error. An empty |List| or |Dictionary| results in zero.
6367
6368 Can also be used as a |method|: >
6369 mylist->max()
6370
6371
6372menu_info({name} [, {mode}]) *menu_info()*
6373 Return information about the specified menu {name} in
6374 mode {mode}. The menu name should be specified without the
6375 shortcut character ('&'). If {name} is "", then the top-level
6376 menu names are returned.
6377
6378 {mode} can be one of these strings:
6379 "n" Normal
6380 "v" Visual (including Select)
6381 "o" Operator-pending
6382 "i" Insert
6383 "c" Cmd-line
6384 "s" Select
6385 "x" Visual
6386 "t" Terminal-Job
6387 "" Normal, Visual and Operator-pending
6388 "!" Insert and Cmd-line
6389 When {mode} is omitted, the modes for "" are used.
6390
6391 Returns a |Dictionary| containing the following items:
6392 accel menu item accelerator text |menu-text|
6393 display display name (name without '&')
6394 enabled v:true if this menu item is enabled
6395 Refer to |:menu-enable|
6396 icon name of the icon file (for toolbar)
6397 |toolbar-icon|
6398 iconidx index of a built-in icon
6399 modes modes for which the menu is defined. In
6400 addition to the modes mentioned above, these
6401 characters will be used:
6402 " " Normal, Visual and Operator-pending
6403 name menu item name.
6404 noremenu v:true if the {rhs} of the menu item is not
6405 remappable else v:false.
6406 priority menu order priority |menu-priority|
6407 rhs right-hand-side of the menu item. The returned
6408 string has special characters translated like
6409 in the output of the ":menu" command listing.
6410 When the {rhs} of a menu item is empty, then
6411 "<Nop>" is returned.
6412 script v:true if script-local remapping of {rhs} is
6413 allowed else v:false. See |:menu-script|.
6414 shortcut shortcut key (character after '&' in
6415 the menu name) |menu-shortcut|
6416 silent v:true if the menu item is created
6417 with <silent> argument |:menu-silent|
6418 submenus |List| containing the names of
6419 all the submenus. Present only if the menu
6420 item has submenus.
6421
6422 Returns an empty dictionary if the menu item is not found.
6423
6424 Examples: >
6425 :echo menu_info('Edit.Cut')
6426 :echo menu_info('File.Save', 'n')
6427
6428 " Display the entire menu hierarchy in a buffer
6429 func ShowMenu(name, pfx)
6430 let m = menu_info(a:name)
6431 call append(line('$'), a:pfx .. m.display)
6432 for child in m->get('submenus', [])
6433 call ShowMenu(a:name .. '.' .. escape(child, '.'),
6434 \ a:pfx .. ' ')
6435 endfor
6436 endfunc
6437 new
6438 for topmenu in menu_info('').submenus
6439 call ShowMenu(topmenu, '')
6440 endfor
6441<
6442 Can also be used as a |method|: >
6443 GetMenuName()->menu_info('v')
6444
6445
6446< *min()*
6447min({expr}) Return the minimum value of all items in {expr}. Example: >
6448 echo min([apples, pears, oranges])
6449
6450< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6451 it returns the minimum of all values in the Dictionary.
6452 If {expr} is neither a List nor a Dictionary, or one of the
6453 items in {expr} cannot be used as a Number this results in
6454 an error. An empty |List| or |Dictionary| results in zero.
6455
6456 Can also be used as a |method|: >
6457 mylist->min()
6458
6459< *mkdir()* *E739*
Bram Moolenaar938ae282023-02-20 20:44:55 +00006460mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006461 Create directory {name}.
6462
Bram Moolenaar938ae282023-02-20 20:44:55 +00006463 When {flags} is present it must be a string. An empty string
6464 has no effect.
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006465
Bram Moolenaar938ae282023-02-20 20:44:55 +00006466 If {flags} contains "p" then intermediate directories are
6467 created as necessary.
6468
6469 If {flags} contains "D" then {name} is deleted at the end of
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006470 the current function, as with: >
6471 defer delete({name}, 'd')
6472<
Bram Moolenaar938ae282023-02-20 20:44:55 +00006473 If {flags} contains "R" then {name} is deleted recursively at
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006474 the end of the current function, as with: >
6475 defer delete({name}, 'rf')
6476< Note that when {name} has more than one part and "p" is used
6477 some directories may already exist. Only the first one that
6478 is created and what it contains is scheduled to be deleted.
6479 E.g. when using: >
6480 call mkdir('subdir/tmp/autoload', 'pR')
6481< and "subdir" already exists then "subdir/tmp" will be
6482 scheduled for deletion, like with: >
6483 defer delete('subdir/tmp', 'rf')
6484< Note that if scheduling the defer fails the directory is not
6485 deleted. This should only happen when out of memory.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006486
6487 If {prot} is given it is used to set the protection bits of
6488 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
6489 the user, readable for others). Use 0o700 to make it
6490 unreadable for others. This is only used for the last part of
6491 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
6492 created with 0o755.
6493 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006494 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006495
6496< This function is not available in the |sandbox|.
6497
6498 There is no error if the directory already exists and the "p"
6499 flag is passed (since patch 8.0.1708). However, without the
6500 "p" option the call will fail.
6501
6502 The function result is a Number, which is TRUE if the call was
6503 successful or FALSE if the directory creation failed or partly
6504 failed.
6505
6506 Not available on all systems. To check use: >
6507 :if exists("*mkdir")
6508
6509< Can also be used as a |method|: >
6510 GetName()->mkdir()
6511<
6512 *mode()*
6513mode([expr]) Return a string that indicates the current mode.
6514 If [expr] is supplied and it evaluates to a non-zero Number or
6515 a non-empty String (|non-zero-arg|), then the full mode is
6516 returned, otherwise only the first letter is returned.
6517 Also see |state()|.
6518
6519 n Normal
6520 no Operator-pending
6521 nov Operator-pending (forced characterwise |o_v|)
6522 noV Operator-pending (forced linewise |o_V|)
6523 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
6524 CTRL-V is one character
6525 niI Normal using |i_CTRL-O| in |Insert-mode|
6526 niR Normal using |i_CTRL-O| in |Replace-mode|
6527 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
6528 nt Terminal-Normal (insert goes to Terminal-Job mode)
6529 v Visual by character
6530 vs Visual by character using |v_CTRL-O| in Select mode
6531 V Visual by line
6532 Vs Visual by line using |v_CTRL-O| in Select mode
6533 CTRL-V Visual blockwise
6534 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
6535 s Select by character
6536 S Select by line
6537 CTRL-S Select blockwise
6538 i Insert
6539 ic Insert mode completion |compl-generic|
6540 ix Insert mode |i_CTRL-X| completion
6541 R Replace |R|
6542 Rc Replace mode completion |compl-generic|
6543 Rx Replace mode |i_CTRL-X| completion
6544 Rv Virtual Replace |gR|
6545 Rvc Virtual Replace mode completion |compl-generic|
6546 Rvx Virtual Replace mode |i_CTRL-X| completion
6547 c Command-line editing
h-east71ebf3b2023-09-03 17:12:55 +02006548 ct Command-line editing via Terminal-Job mode
zeertzjqfcaeb3d2023-11-28 20:46:29 +01006549 cr Command-line editing overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006550 cv Vim Ex mode |gQ|
zeertzjqfcaeb3d2023-11-28 20:46:29 +01006551 cvr Vim Ex mode while in overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006552 ce Normal Ex mode |Q|
6553 r Hit-enter prompt
6554 rm The -- more -- prompt
6555 r? A |:confirm| query of some sort
6556 ! Shell or external command is executing
6557 t Terminal-Job mode: keys go to the job
6558
6559 This is useful in the 'statusline' option or when used
6560 with |remote_expr()| In most other places it always returns
6561 "c" or "n".
6562 Note that in the future more modes and more specific modes may
6563 be added. It's better not to compare the whole string but only
6564 the leading character(s).
6565 Also see |visualmode()|.
6566
6567 Can also be used as a |method|: >
6568 DoFull()->mode()
6569
6570mzeval({expr}) *mzeval()*
6571 Evaluate MzScheme expression {expr} and return its result
6572 converted to Vim data structures.
6573 Numbers and strings are returned as they are.
6574 Pairs (including lists and improper lists) and vectors are
6575 returned as Vim |Lists|.
6576 Hash tables are represented as Vim |Dictionary| type with keys
6577 converted to strings.
6578 All other types are converted to string with display function.
6579 Examples: >
6580 :mz (define l (list 1 2 3))
6581 :mz (define h (make-hash)) (hash-set! h "list" l)
6582 :echo mzeval("l")
6583 :echo mzeval("h")
6584<
6585 Note that in a `:def` function local variables are not visible
6586 to {expr}.
6587
6588 Can also be used as a |method|: >
6589 GetExpr()->mzeval()
6590<
6591 {only available when compiled with the |+mzscheme| feature}
6592
6593nextnonblank({lnum}) *nextnonblank()*
6594 Return the line number of the first line at or below {lnum}
6595 that is not blank. Example: >
6596 if getline(nextnonblank(1)) =~ "Java"
6597< When {lnum} is invalid or there is no non-blank line at or
6598 below it, zero is returned.
6599 {lnum} is used like with |getline()|.
6600 See also |prevnonblank()|.
6601
6602 Can also be used as a |method|: >
6603 GetLnum()->nextnonblank()
6604
6605nr2char({expr} [, {utf8}]) *nr2char()*
6606 Return a string with a single character, which has the number
6607 value {expr}. Examples: >
6608 nr2char(64) returns "@"
6609 nr2char(32) returns " "
6610< When {utf8} is omitted or zero, the current 'encoding' is used.
6611 Example for "utf-8": >
6612 nr2char(300) returns I with bow character
6613< When {utf8} is TRUE, always return UTF-8 characters.
6614 Note that a NUL character in the file is specified with
6615 nr2char(10), because NULs are represented with newline
6616 characters. nr2char(0) is a real NUL and terminates the
6617 string, thus results in an empty string.
6618 To turn a list of character numbers into a string: >
6619 let list = [65, 66, 67]
6620 let str = join(map(list, {_, val -> nr2char(val)}), '')
6621< Result: "ABC"
6622
6623 Can also be used as a |method|: >
6624 GetNumber()->nr2char()
6625
6626or({expr}, {expr}) *or()*
6627 Bitwise OR on the two arguments. The arguments are converted
6628 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006629 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006630 Example: >
6631 :let bits = or(bits, 0x80)
6632< Can also be used as a |method|: >
6633 :let bits = bits->or(0x80)
6634
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006635< Rationale: The reason this is a function and not using the "|"
6636 character like many languages, is that Vi has always used "|"
6637 to separate commands. In many places it would not be clear if
6638 "|" is an operator or a command separator.
6639
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006640
6641pathshorten({path} [, {len}]) *pathshorten()*
6642 Shorten directory names in the path {path} and return the
6643 result. The tail, the file name, is kept as-is. The other
6644 components in the path are reduced to {len} letters in length.
6645 If {len} is omitted or smaller than 1 then 1 is used (single
6646 letters). Leading '~' and '.' characters are kept. Examples: >
6647 :echo pathshorten('~/.vim/autoload/myfile.vim')
6648< ~/.v/a/myfile.vim ~
6649>
6650 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
6651< ~/.vi/au/myfile.vim ~
6652 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006653 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006654
6655 Can also be used as a |method|: >
6656 GetDirectories()->pathshorten()
6657
6658perleval({expr}) *perleval()*
6659 Evaluate Perl expression {expr} in scalar context and return
6660 its result converted to Vim data structures. If value can't be
6661 converted, it is returned as a string Perl representation.
6662 Note: If you want an array or hash, {expr} must return a
6663 reference to it.
6664 Example: >
6665 :echo perleval('[1 .. 4]')
6666< [1, 2, 3, 4]
6667
6668 Note that in a `:def` function local variables are not visible
6669 to {expr}.
6670
6671 Can also be used as a |method|: >
6672 GetExpr()->perleval()
6673
6674< {only available when compiled with the |+perl| feature}
6675
6676
6677popup_ functions are documented here: |popup-functions|
6678
6679
6680pow({x}, {y}) *pow()*
6681 Return the power of {x} to the exponent {y} as a |Float|.
6682 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006683 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006684 Examples: >
6685 :echo pow(3, 3)
6686< 27.0 >
6687 :echo pow(2, 16)
6688< 65536.0 >
6689 :echo pow(32, 0.20)
6690< 2.0
6691
6692 Can also be used as a |method|: >
6693 Compute()->pow(3)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006694
6695prevnonblank({lnum}) *prevnonblank()*
6696 Return the line number of the first line at or above {lnum}
6697 that is not blank. Example: >
6698 let ind = indent(prevnonblank(v:lnum - 1))
6699< When {lnum} is invalid or there is no non-blank line at or
6700 above it, zero is returned.
6701 {lnum} is used like with |getline()|.
6702 Also see |nextnonblank()|.
6703
6704 Can also be used as a |method|: >
6705 GetLnum()->prevnonblank()
6706
6707printf({fmt}, {expr1} ...) *printf()*
6708 Return a String with {fmt}, where "%" items are replaced by
6709 the formatted form of their respective arguments. Example: >
6710 printf("%4d: E%d %.30s", lnum, errno, msg)
6711< May result in:
6712 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
6713
6714 When used as a |method| the base is passed as the second
6715 argument: >
6716 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006717<
6718 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006719
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006720 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006721 %s string
6722 %6S string right-aligned in 6 display cells
6723 %6s string right-aligned in 6 bytes
6724 %.9s string truncated to 9 bytes
6725 %c single byte
6726 %d decimal number
6727 %5d decimal number padded with spaces to 5 characters
6728 %x hex number
6729 %04x hex number padded with zeros to at least 4 characters
6730 %X hex number using upper case letters
6731 %o octal number
6732 %08b binary number padded with zeros to at least 8 chars
6733 %f floating point number as 12.23, inf, -inf or nan
6734 %F floating point number as 12.23, INF, -INF or NAN
6735 %e floating point number as 1.23e3, inf, -inf or nan
6736 %E floating point number as 1.23E3, INF, -INF or NAN
6737 %g floating point number, as %f or %e depending on value
6738 %G floating point number, as %F or %E depending on value
6739 %% the % character itself
6740
6741 Conversion specifications start with '%' and end with the
6742 conversion type. All other characters are copied unchanged to
6743 the result.
6744
6745 The "%" starts a conversion specification. The following
6746 arguments appear in sequence:
6747
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006748 % [pos-argument] [flags] [field-width] [.precision] type
6749
6750 pos-argument
6751 At most one positional argument specifier. These
6752 take the form {n$}, where n is >= 1.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006753
6754 flags
6755 Zero or more of the following flags:
6756
6757 # The value should be converted to an "alternate
6758 form". For c, d, and s conversions, this option
6759 has no effect. For o conversions, the precision
6760 of the number is increased to force the first
6761 character of the output string to a zero (except
6762 if a zero value is printed with an explicit
6763 precision of zero).
6764 For b and B conversions, a non-zero result has
6765 the string "0b" (or "0B" for B conversions)
6766 prepended to it.
6767 For x and X conversions, a non-zero result has
6768 the string "0x" (or "0X" for X conversions)
6769 prepended to it.
6770
6771 0 (zero) Zero padding. For all conversions the converted
6772 value is padded on the left with zeros rather
6773 than blanks. If a precision is given with a
6774 numeric conversion (d, b, B, o, x, and X), the 0
6775 flag is ignored.
6776
6777 - A negative field width flag; the converted value
6778 is to be left adjusted on the field boundary.
6779 The converted value is padded on the right with
6780 blanks, rather than on the left with blanks or
6781 zeros. A - overrides a 0 if both are given.
6782
6783 ' ' (space) A blank should be left before a positive
6784 number produced by a signed conversion (d).
6785
6786 + A sign must always be placed before a number
6787 produced by a signed conversion. A + overrides
6788 a space if both are used.
6789
6790 field-width
6791 An optional decimal digit string specifying a minimum
6792 field width. If the converted value has fewer bytes
6793 than the field width, it will be padded with spaces on
6794 the left (or right, if the left-adjustment flag has
6795 been given) to fill out the field width. For the S
6796 conversion the count is in cells.
6797
6798 .precision
6799 An optional precision, in the form of a period '.'
6800 followed by an optional digit string. If the digit
6801 string is omitted, the precision is taken as zero.
6802 This gives the minimum number of digits to appear for
6803 d, o, x, and X conversions, the maximum number of
6804 bytes to be printed from a string for s conversions,
6805 or the maximum number of cells to be printed from a
6806 string for S conversions.
6807 For floating point it is the number of digits after
6808 the decimal point.
6809
6810 type
6811 A character that specifies the type of conversion to
6812 be applied, see below.
6813
6814 A field width or precision, or both, may be indicated by an
6815 asterisk '*' instead of a digit string. In this case, a
6816 Number argument supplies the field width or precision. A
6817 negative field width is treated as a left adjustment flag
6818 followed by a positive field width; a negative precision is
6819 treated as though it were missing. Example: >
6820 :echo printf("%d: %.*s", nr, width, line)
6821< This limits the length of the text used from "line" to
6822 "width" bytes.
6823
Dominique Pellé17dca3c2023-12-14 20:36:32 +01006824 If the argument to be formatted is specified using a
6825 positional argument specifier, and a '*' is used to indicate
6826 that a number argument is to be used to specify the width or
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006827 precision, the argument(s) to be used must also be specified
6828 using a {n$} positional argument specifier. See |printf-$|.
6829
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006830 The conversion specifiers and their meanings are:
6831
6832 *printf-d* *printf-b* *printf-B* *printf-o*
6833 *printf-x* *printf-X*
6834 dbBoxX The Number argument is converted to signed decimal
6835 (d), unsigned binary (b and B), unsigned octal (o), or
6836 unsigned hexadecimal (x and X) notation. The letters
6837 "abcdef" are used for x conversions; the letters
6838 "ABCDEF" are used for X conversions.
6839 The precision, if any, gives the minimum number of
6840 digits that must appear; if the converted value
6841 requires fewer digits, it is padded on the left with
6842 zeros.
6843 In no case does a non-existent or small field width
6844 cause truncation of a numeric field; if the result of
6845 a conversion is wider than the field width, the field
6846 is expanded to contain the conversion result.
6847 The 'h' modifier indicates the argument is 16 bits.
Christ van Willegenaa90d4f2023-09-03 17:22:37 +02006848 The 'l' modifier indicates the argument is a long
6849 integer. The size will be 32 bits or 64 bits
6850 depending on your platform.
6851 The "ll" modifier indicates the argument is 64 bits.
6852 The b and B conversion specifiers never take a width
6853 modifier and always assume their argument is a 64 bit
6854 integer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006855 Generally, these modifiers are not useful. They are
6856 ignored when type is known from the argument.
6857
6858 i alias for d
6859 D alias for ld
6860 U alias for lu
6861 O alias for lo
6862
6863 *printf-c*
6864 c The Number argument is converted to a byte, and the
6865 resulting character is written.
6866
6867 *printf-s*
6868 s The text of the String argument is used. If a
6869 precision is specified, no more bytes than the number
6870 specified are used.
6871 If the argument is not a String type, it is
6872 automatically converted to text with the same format
6873 as ":echo".
6874 *printf-S*
6875 S The text of the String argument is used. If a
6876 precision is specified, no more display cells than the
6877 number specified are used.
6878
6879 *printf-f* *E807*
6880 f F The Float argument is converted into a string of the
6881 form 123.456. The precision specifies the number of
6882 digits after the decimal point. When the precision is
6883 zero the decimal point is omitted. When the precision
6884 is not specified 6 is used. A really big number
6885 (out of range or dividing by zero) results in "inf"
6886 or "-inf" with %f (INF or -INF with %F).
6887 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
6888 Example: >
6889 echo printf("%.2f", 12.115)
6890< 12.12
6891 Note that roundoff depends on the system libraries.
6892 Use |round()| when in doubt.
6893
6894 *printf-e* *printf-E*
6895 e E The Float argument is converted into a string of the
6896 form 1.234e+03 or 1.234E+03 when using 'E'. The
6897 precision specifies the number of digits after the
6898 decimal point, like with 'f'.
6899
6900 *printf-g* *printf-G*
6901 g G The Float argument is converted like with 'f' if the
6902 value is between 0.001 (inclusive) and 10000000.0
6903 (exclusive). Otherwise 'e' is used for 'g' and 'E'
6904 for 'G'. When no precision is specified superfluous
6905 zeroes and '+' signs are removed, except for the zero
6906 immediately after the decimal point. Thus 10000000.0
6907 results in 1.0e7.
6908
6909 *printf-%*
6910 % A '%' is written. No argument is converted. The
6911 complete conversion specification is "%%".
6912
6913 When a Number argument is expected a String argument is also
6914 accepted and automatically converted.
6915 When a Float or String argument is expected a Number argument
6916 is also accepted and automatically converted.
6917 Any other argument type results in an error message.
6918
6919 *E766* *E767*
6920 The number of {exprN} arguments must exactly match the number
6921 of "%" items. If there are not sufficient or too many
6922 arguments an error is given. Up to 18 arguments can be used.
6923
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006924 *printf-$*
6925 In certain languages, error and informative messages are
6926 more readable when the order of words is different from the
Christian Brabandtee17b6f2023-09-09 11:23:50 +02006927 corresponding message in English. To accommodate translations
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006928 having a different word order, positional arguments may be
6929 used to indicate this. For instance: >
6930
h_east596a9f22023-11-21 21:24:23 +09006931 #, c-format
6932 msgid "%s returning %s"
6933 msgstr "waarde %2$s komt terug van %1$s"
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006934<
h_east596a9f22023-11-21 21:24:23 +09006935 In this example, the sentence has its 2 string arguments
6936 reversed in the output. >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006937
h_east596a9f22023-11-21 21:24:23 +09006938 echo printf(
6939 "In The Netherlands, vim's creator's name is: %1$s %2$s",
6940 "Bram", "Moolenaar")
6941< In The Netherlands, vim's creator's name is: Bram Moolenaar >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006942
h_east596a9f22023-11-21 21:24:23 +09006943 echo printf(
6944 "In Belgium, vim's creator's name is: %2$s %1$s",
6945 "Bram", "Moolenaar")
6946< In Belgium, vim's creator's name is: Moolenaar Bram
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006947
6948 Width (and precision) can be specified using the '*' specifier.
6949 In this case, you must specify the field width position in the
6950 argument list. >
6951
h_east596a9f22023-11-21 21:24:23 +09006952 echo printf("%1$*2$.*3$d", 1, 2, 3)
6953< 001 >
6954 echo printf("%2$*3$.*1$d", 1, 2, 3)
6955< 2 >
6956 echo printf("%3$*1$.*2$d", 1, 2, 3)
6957< 03 >
6958 echo printf("%1$*2$.*3$g", 1.4142, 2, 3)
6959< 1.414
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006960
6961 You can mix specifying the width and/or precision directly
6962 and via positional arguments: >
6963
h_east596a9f22023-11-21 21:24:23 +09006964 echo printf("%1$4.*2$f", 1.4142135, 6)
6965< 1.414214 >
6966 echo printf("%1$*2$.4f", 1.4142135, 6)
6967< 1.4142 >
6968 echo printf("%1$*2$.*3$f", 1.4142135, 6, 2)
6969< 1.41
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006970
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02006971 *E1500*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006972 You cannot mix positional and non-positional arguments: >
h_east596a9f22023-11-21 21:24:23 +09006973 echo printf("%s%1$s", "One", "Two")
6974< E1500: Cannot mix positional and non-positional arguments:
6975 %s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006976
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02006977 *E1501*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006978 You cannot skip a positional argument in a format string: >
h_east596a9f22023-11-21 21:24:23 +09006979 echo printf("%3$s%1$s", "One", "Two", "Three")
6980< E1501: format argument 2 unused in $-style format:
6981 %3$s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006982
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02006983 *E1502*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006984 You can re-use a [field-width] (or [precision]) argument: >
h_east596a9f22023-11-21 21:24:23 +09006985 echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2)
6986< 1 at width 2 is: 01
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006987
6988 However, you can't use it as a different type: >
h_east596a9f22023-11-21 21:24:23 +09006989 echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2)
6990< E1502: Positional argument 2 used as field width reused as
6991 different type: long int/int
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006992
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02006993 *E1503*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006994 When a positional argument is used, but not the correct number
6995 or arguments is given, an error is raised: >
h_east596a9f22023-11-21 21:24:23 +09006996 echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2)
6997< E1503: Positional argument 3 out of bounds: %1$d at width
6998 %2$d is: %01$*2$.*3$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006999
7000 Only the first error is reported: >
h_east596a9f22023-11-21 21:24:23 +09007001 echo printf("%01$*2$.*3$d %4$d", 1, 2)
7002< E1503: Positional argument 3 out of bounds: %01$*2$.*3$d
7003 %4$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007004
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007005 *E1504*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007006 A positional argument can be used more than once: >
h_east596a9f22023-11-21 21:24:23 +09007007 echo printf("%1$s %2$s %1$s", "One", "Two")
7008< One Two One
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007009
7010 However, you can't use a different type the second time: >
h_east596a9f22023-11-21 21:24:23 +09007011 echo printf("%1$s %2$s %1$d", "One", "Two")
7012< E1504: Positional argument 1 type used inconsistently:
7013 int/string
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007014
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02007015 *E1505*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007016 Various other errors that lead to a format string being
7017 wrongly formatted lead to: >
h_east596a9f22023-11-21 21:24:23 +09007018 echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2)
7019< E1505: Invalid format specifier: %1$d at width %2$d is:
7020 %01$*2$.3$d
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007021
Christ van Willegenea746f92023-10-05 20:48:36 +02007022 *E1507*
zeertzjq27e12c72023-10-07 01:34:04 +08007023 This internal error indicates that the logic to parse a
7024 positional format argument ran into a problem that couldn't be
7025 otherwise reported. Please file a bug against Vim if you run
7026 into this, copying the exact format string and parameters that
7027 were used.
Christ van Willegenea746f92023-10-05 20:48:36 +02007028
7029
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007030prompt_getprompt({buf}) *prompt_getprompt()*
7031 Returns the effective prompt text for buffer {buf}. {buf} can
7032 be a buffer name or number. See |prompt-buffer|.
7033
7034 If the buffer doesn't exist or isn't a prompt buffer, an empty
7035 string is returned.
7036
7037 Can also be used as a |method|: >
7038 GetBuffer()->prompt_getprompt()
7039
7040< {only available when compiled with the |+channel| feature}
7041
7042
7043prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
7044 Set prompt callback for buffer {buf} to {expr}. When {expr}
7045 is an empty string the callback is removed. This has only
7046 effect if {buf} has 'buftype' set to "prompt".
7047
7048 The callback is invoked when pressing Enter. The current
7049 buffer will always be the prompt buffer. A new line for a
7050 prompt is added before invoking the callback, thus the prompt
7051 for which the callback was invoked will be in the last but one
7052 line.
7053 If the callback wants to add text to the buffer, it must
7054 insert it above the last line, since that is where the current
7055 prompt is. This can also be done asynchronously.
7056 The callback is invoked with one argument, which is the text
7057 that was entered at the prompt. This can be an empty string
7058 if the user only typed Enter.
7059 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007060 func s:TextEntered(text)
7061 if a:text == 'exit' || a:text == 'quit'
7062 stopinsert
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01007063 " Reset 'modified' to allow the buffer to be closed.
7064 " We assume there is nothing useful to be saved.
7065 set nomodified
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007066 close
7067 else
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01007068 " Do something useful with "a:text". In this example
7069 " we just repeat it.
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007070 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007071 endif
7072 endfunc
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01007073 call prompt_setcallback(bufnr(), function('s:TextEntered'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007074
7075< Can also be used as a |method|: >
7076 GetBuffer()->prompt_setcallback(callback)
7077
7078< {only available when compiled with the |+channel| feature}
7079
7080prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
7081 Set a callback for buffer {buf} to {expr}. When {expr} is an
7082 empty string the callback is removed. This has only effect if
7083 {buf} has 'buftype' set to "prompt".
7084
7085 This callback will be invoked when pressing CTRL-C in Insert
7086 mode. Without setting a callback Vim will exit Insert mode,
7087 as in any buffer.
7088
7089 Can also be used as a |method|: >
7090 GetBuffer()->prompt_setinterrupt(callback)
7091
7092< {only available when compiled with the |+channel| feature}
7093
7094prompt_setprompt({buf}, {text}) *prompt_setprompt()*
7095 Set prompt for buffer {buf} to {text}. You most likely want
7096 {text} to end in a space.
7097 The result is only visible if {buf} has 'buftype' set to
7098 "prompt". Example: >
7099 call prompt_setprompt(bufnr(), 'command: ')
7100<
7101 Can also be used as a |method|: >
7102 GetBuffer()->prompt_setprompt('command: ')
7103
7104< {only available when compiled with the |+channel| feature}
7105
7106prop_ functions are documented here: |text-prop-functions|
7107
7108pum_getpos() *pum_getpos()*
7109 If the popup menu (see |ins-completion-menu|) is not visible,
7110 returns an empty |Dictionary|, otherwise, returns a
7111 |Dictionary| with the following keys:
7112 height nr of items visible
7113 width screen cells
7114 row top screen row (0 first row)
7115 col leftmost screen column (0 first col)
7116 size total nr of items
7117 scrollbar |TRUE| if scrollbar is visible
7118
7119 The values are the same as in |v:event| during
7120 |CompleteChanged|.
7121
7122pumvisible() *pumvisible()*
7123 Returns non-zero when the popup menu is visible, zero
7124 otherwise. See |ins-completion-menu|.
7125 This can be used to avoid some things that would remove the
7126 popup menu.
7127
7128py3eval({expr}) *py3eval()*
7129 Evaluate Python expression {expr} and return its result
7130 converted to Vim data structures.
7131 Numbers and strings are returned as they are (strings are
7132 copied though, Unicode strings are additionally converted to
7133 'encoding').
7134 Lists are represented as Vim |List| type.
7135 Dictionaries are represented as Vim |Dictionary| type with
7136 keys converted to strings.
7137 Note that in a `:def` function local variables are not visible
7138 to {expr}.
7139
7140 Can also be used as a |method|: >
7141 GetExpr()->py3eval()
7142
7143< {only available when compiled with the |+python3| feature}
7144
7145 *E858* *E859*
7146pyeval({expr}) *pyeval()*
7147 Evaluate Python expression {expr} and return its result
7148 converted to Vim data structures.
7149 Numbers and strings are returned as they are (strings are
7150 copied though).
7151 Lists are represented as Vim |List| type.
7152 Dictionaries are represented as Vim |Dictionary| type,
7153 non-string keys result in error.
7154 Note that in a `:def` function local variables are not visible
7155 to {expr}.
7156
7157 Can also be used as a |method|: >
7158 GetExpr()->pyeval()
7159
7160< {only available when compiled with the |+python| feature}
7161
7162pyxeval({expr}) *pyxeval()*
7163 Evaluate Python expression {expr} and return its result
7164 converted to Vim data structures.
7165 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
7166 See also: |pyeval()|, |py3eval()|
7167
7168 Can also be used as a |method|: >
7169 GetExpr()->pyxeval()
7170
7171< {only available when compiled with the |+python| or the
7172 |+python3| feature}
7173
7174rand([{expr}]) *rand()* *random*
7175 Return a pseudo-random Number generated with an xoshiro128**
7176 algorithm using seed {expr}. The returned number is 32 bits,
7177 also on 64 bits systems, for consistency.
7178 {expr} can be initialized by |srand()| and will be updated by
7179 rand(). If {expr} is omitted, an internal seed value is used
7180 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007181 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007182
7183 Examples: >
7184 :echo rand()
7185 :let seed = srand()
7186 :echo rand(seed)
7187 :echo rand(seed) % 16 " random number 0 - 15
7188<
7189
7190 *E726* *E727*
7191range({expr} [, {max} [, {stride}]]) *range()*
7192 Returns a |List| with Numbers:
7193 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
7194 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
7195 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
7196 {max}] (increasing {expr} with {stride} each time, not
7197 producing a value past {max}).
7198 When the maximum is one before the start the result is an
7199 empty list. When the maximum is more than one before the
7200 start this is an error.
7201 Examples: >
7202 range(4) " [0, 1, 2, 3]
7203 range(2, 4) " [2, 3, 4]
7204 range(2, 9, 3) " [2, 5, 8]
7205 range(2, -2, -1) " [2, 1, 0, -1, -2]
7206 range(0) " []
7207 range(2, 0) " error!
7208<
7209 Can also be used as a |method|: >
7210 GetExpr()->range()
7211<
7212
K.Takata11df3ae2022-10-19 14:02:40 +01007213readblob({fname} [, {offset} [, {size}]]) *readblob()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007214 Read file {fname} in binary mode and return a |Blob|.
K.Takata11df3ae2022-10-19 14:02:40 +01007215 If {offset} is specified, read the file from the specified
7216 offset. If it is a negative value, it is used as an offset
7217 from the end of the file. E.g., to read the last 12 bytes: >
7218 readblob('file.bin', -12)
7219< If {size} is specified, only the specified size will be read.
7220 E.g. to read the first 100 bytes of a file: >
7221 readblob('file.bin', 0, 100)
7222< If {size} is -1 or omitted, the whole data starting from
7223 {offset} will be read.
K.Takata43625762022-10-20 13:28:51 +01007224 This can be also used to read the data from a character device
7225 on Unix when {size} is explicitly set. Only if the device
7226 supports seeking {offset} can be used. Otherwise it should be
7227 zero. E.g. to read 10 bytes from a serial console: >
7228 readblob('/dev/ttyS0', 0, 10)
7229< When the file can't be opened an error message is given and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007230 the result is an empty |Blob|.
Bram Moolenaar5b2a3d72022-10-21 11:25:30 +01007231 When the offset is beyond the end of the file the result is an
7232 empty blob.
7233 When trying to read more bytes than are available the result
7234 is truncated.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007235 Also see |readfile()| and |writefile()|.
7236
7237
7238readdir({directory} [, {expr} [, {dict}]]) *readdir()*
7239 Return a list with file and directory names in {directory}.
7240 You can also use |glob()| if you don't need to do complicated
7241 things, such as limiting the number of matches.
7242 The list will be sorted (case sensitive), see the {dict}
7243 argument below for changing the sort order.
7244
7245 When {expr} is omitted all entries are included.
7246 When {expr} is given, it is evaluated to check what to do:
7247 If {expr} results in -1 then no further entries will
7248 be handled.
7249 If {expr} results in 0 then this entry will not be
7250 added to the list.
7251 If {expr} results in 1 then this entry will be added
7252 to the list.
7253 The entries "." and ".." are always excluded.
7254 Each time {expr} is evaluated |v:val| is set to the entry name.
7255 When {expr} is a function the name is passed as the argument.
7256 For example, to get a list of files ending in ".txt": >
7257 readdir(dirname, {n -> n =~ '.txt$'})
7258< To skip hidden and backup files: >
7259 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00007260< *E857*
7261 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007262 values. Currently this is used to specify if and how sorting
7263 should be performed. The dict can have the following members:
7264
7265 sort How to sort the result returned from the system.
7266 Valid values are:
7267 "none" do not sort (fastest method)
7268 "case" sort case sensitive (byte value of
7269 each character, technically, using
7270 strcmp()) (default)
7271 "icase" sort case insensitive (technically
7272 using strcasecmp())
7273 "collate" sort using the collation order
7274 of the "POSIX" or "C" |locale|
7275 (technically using strcoll())
7276 Other values are silently ignored.
7277
7278 For example, to get a list of all files in the current
7279 directory without sorting the individual entries: >
7280 readdir('.', '1', #{sort: 'none'})
7281< If you want to get a directory tree: >
7282 function! s:tree(dir)
7283 return {a:dir : map(readdir(a:dir),
7284 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007285 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007286 endfunction
7287 echo s:tree(".")
7288<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007289 Returns an empty List on error.
7290
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007291 Can also be used as a |method|: >
7292 GetDirName()->readdir()
7293<
7294readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
7295 Extended version of |readdir()|.
7296 Return a list of Dictionaries with file and directory
7297 information in {directory}.
7298 This is useful if you want to get the attributes of file and
7299 directory at the same time as getting a list of a directory.
7300 This is much faster than calling |readdir()| then calling
7301 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
7302 each file and directory especially on MS-Windows.
7303 The list will by default be sorted by name (case sensitive),
7304 the sorting can be changed by using the optional {dict}
7305 argument, see |readdir()|.
7306
7307 The Dictionary for file and directory information has the
7308 following items:
7309 group Group name of the entry. (Only on Unix)
7310 name Name of the entry.
7311 perm Permissions of the entry. See |getfperm()|.
7312 size Size of the entry. See |getfsize()|.
7313 time Timestamp of the entry. See |getftime()|.
7314 type Type of the entry.
7315 On Unix, almost same as |getftype()| except:
7316 Symlink to a dir "linkd"
7317 Other symlink "link"
7318 On MS-Windows:
7319 Normal file "file"
7320 Directory "dir"
7321 Junction "junction"
7322 Symlink to a dir "linkd"
7323 Other symlink "link"
7324 Other reparse point "reparse"
7325 user User name of the entry's owner. (Only on Unix)
7326 On Unix, if the entry is a symlink, the Dictionary includes
7327 the information of the target (except the "type" item).
7328 On MS-Windows, it includes the information of the symlink
7329 itself because of performance reasons.
7330
7331 When {expr} is omitted all entries are included.
7332 When {expr} is given, it is evaluated to check what to do:
7333 If {expr} results in -1 then no further entries will
7334 be handled.
7335 If {expr} results in 0 then this entry will not be
7336 added to the list.
7337 If {expr} results in 1 then this entry will be added
7338 to the list.
7339 The entries "." and ".." are always excluded.
7340 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
7341 of the entry.
7342 When {expr} is a function the entry is passed as the argument.
7343 For example, to get a list of files ending in ".txt": >
7344 readdirex(dirname, {e -> e.name =~ '.txt$'})
7345<
7346 For example, to get a list of all files in the current
7347 directory without sorting the individual entries: >
7348 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007349<
7350 Can also be used as a |method|: >
7351 GetDirName()->readdirex()
7352<
7353
7354 *readfile()*
7355readfile({fname} [, {type} [, {max}]])
7356 Read file {fname} and return a |List|, each line of the file
7357 as an item. Lines are broken at NL characters. Macintosh
7358 files separated with CR will result in a single long line
7359 (unless a NL appears somewhere).
7360 All NUL characters are replaced with a NL character.
7361 When {type} contains "b" binary mode is used:
7362 - When the last line ends in a NL an extra empty list item is
7363 added.
7364 - No CR characters are removed.
7365 Otherwise:
7366 - CR characters that appear before a NL are removed.
7367 - Whether the last line ends in a NL or not does not matter.
7368 - When 'encoding' is Unicode any UTF-8 byte order mark is
7369 removed from the text.
7370 When {max} is given this specifies the maximum number of lines
7371 to be read. Useful if you only want to check the first ten
7372 lines of a file: >
7373 :for line in readfile(fname, '', 10)
7374 : if line =~ 'Date' | echo line | endif
7375 :endfor
7376< When {max} is negative -{max} lines from the end of the file
7377 are returned, or as many as there are.
7378 When {max} is zero the result is an empty list.
7379 Note that without {max} the whole file is read into memory.
7380 Also note that there is no recognition of encoding. Read a
7381 file into a buffer if you need to.
7382 Deprecated (use |readblob()| instead): When {type} contains
7383 "B" a |Blob| is returned with the binary data of the file
7384 unmodified.
7385 When the file can't be opened an error message is given and
7386 the result is an empty list.
7387 Also see |writefile()|.
7388
7389 Can also be used as a |method|: >
7390 GetFileName()->readfile()
7391
7392reduce({object}, {func} [, {initial}]) *reduce()* *E998*
7393 {func} is called for every item in {object}, which can be a
7394 |String|, |List| or a |Blob|. {func} is called with two
7395 arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00007396 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007397
7398 {initial} is the initial result. When omitted, the first item
7399 in {object} is used and {func} is first called for the second
7400 item. If {initial} is not given and {object} is empty no
7401 result can be computed, an E998 error is given.
7402
7403 Examples: >
7404 echo reduce([1, 3, 5], { acc, val -> acc + val })
7405 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
7406 echo reduce(0z1122, { acc, val -> 2 * acc + val })
7407 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
7408<
7409 Can also be used as a |method|: >
7410 echo mylist->reduce({ acc, val -> acc + val }, 0)
7411
7412
7413reg_executing() *reg_executing()*
7414 Returns the single letter name of the register being executed.
7415 Returns an empty string when no register is being executed.
7416 See |@|.
7417
7418reg_recording() *reg_recording()*
7419 Returns the single letter name of the register being recorded.
7420 Returns an empty string when not recording. See |q|.
7421
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007422reltime()
7423reltime({start})
7424reltime({start}, {end}) *reltime()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007425 Return an item that represents a time value. The item is a
7426 list with items that depend on the system. In Vim 9 script
Bram Moolenaar71badf92023-04-22 22:40:14 +01007427 the type list<any> can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007428 The item can be passed to |reltimestr()| to convert it to a
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007429 string or |reltimefloat()| to convert to a Float. For
7430 example, to see the time spent in function Work(): >
7431 var startTime = reltime()
7432 Work()
7433 echo startTime->reltime()->reltimestr()
7434<
Bram Moolenaar016188f2022-06-06 20:52:59 +01007435 Without an argument reltime() returns the current time (the
Lifepillar963fd7d2024-01-05 17:44:57 +01007436 representation is system-dependent, it cannot be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01007437 wall-clock time, see |localtime()| for that).
Lifepillar963fd7d2024-01-05 17:44:57 +01007438 With one argument it returns the time passed since the time
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007439 specified in the argument.
7440 With two arguments it returns the time passed between {start}
7441 and {end}.
7442
7443 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007444 reltime(). If there is an error an empty List is returned in
7445 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007446
7447 Can also be used as a |method|: >
7448 GetStart()->reltime()
7449<
7450 {only available when compiled with the |+reltime| feature}
7451
7452reltimefloat({time}) *reltimefloat()*
7453 Return a Float that represents the time value of {time}.
7454 Example: >
7455 let start = reltime()
7456 call MyFunction()
7457 let seconds = reltimefloat(reltime(start))
7458< See the note of reltimestr() about overhead.
7459 Also see |profiling|.
7460 If there is an error 0.0 is returned in legacy script, in Vim9
7461 script an error is given.
7462
7463 Can also be used as a |method|: >
7464 reltime(start)->reltimefloat()
7465
7466< {only available when compiled with the |+reltime| feature}
7467
7468reltimestr({time}) *reltimestr()*
7469 Return a String that represents the time value of {time}.
7470 This is the number of seconds, a dot and the number of
7471 microseconds. Example: >
7472 let start = reltime()
7473 call MyFunction()
7474 echo reltimestr(reltime(start))
7475< Note that overhead for the commands will be added to the time.
Ernie Rael076de792023-03-16 21:43:15 +00007476 The accuracy depends on the system. Use reltimefloat() for the
7477 greatest accuracy which is nanoseconds on some systems.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007478 Leading spaces are used to make the string align nicely. You
7479 can use split() to remove it. >
7480 echo split(reltimestr(reltime(start)))[0]
7481< Also see |profiling|.
7482 If there is an error an empty string is returned in legacy
7483 script, in Vim9 script an error is given.
7484
7485 Can also be used as a |method|: >
7486 reltime(start)->reltimestr()
7487
7488< {only available when compiled with the |+reltime| feature}
7489
7490 *remote_expr()* *E449*
7491remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007492 Send the {string} to {server}. The {server} argument is a
7493 string, also see |{server}|.
7494
7495 The string is sent as an expression and the result is returned
7496 after evaluation. The result must be a String or a |List|. A
7497 |List| is turned into a String by joining the items with a
7498 line break in between (not at the end), like with join(expr,
7499 "\n").
7500
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007501 If {idvar} is present and not empty, it is taken as the name
7502 of a variable and a {serverid} for later use with
7503 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007504
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007505 If {timeout} is given the read times out after this many
7506 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007507
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007508 See also |clientserver| |RemoteReply|.
7509 This function is not available in the |sandbox|.
7510 {only available when compiled with the |+clientserver| feature}
7511 Note: Any errors will cause a local error message to be issued
7512 and the result will be the empty string.
7513
7514 Variables will be evaluated in the global namespace,
7515 independent of a function currently being active. Except
7516 when in debug mode, then local function variables and
7517 arguments can be evaluated.
7518
7519 Examples: >
7520 :echo remote_expr("gvim", "2+2")
7521 :echo remote_expr("gvim1", "b:current_syntax")
7522<
7523 Can also be used as a |method|: >
7524 ServerName()->remote_expr(expr)
7525
7526remote_foreground({server}) *remote_foreground()*
7527 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007528 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007529 This works like: >
7530 remote_expr({server}, "foreground()")
7531< Except that on Win32 systems the client does the work, to work
7532 around the problem that the OS doesn't always allow the server
7533 to bring itself to the foreground.
7534 Note: This does not restore the window if it was minimized,
7535 like foreground() does.
7536 This function is not available in the |sandbox|.
7537
7538 Can also be used as a |method|: >
7539 ServerName()->remote_foreground()
7540
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007541< {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007542 Win32 console version}
7543
7544
7545remote_peek({serverid} [, {retvar}]) *remote_peek()*
7546 Returns a positive number if there are available strings
7547 from {serverid}. Copies any reply string into the variable
7548 {retvar} if specified. {retvar} must be a string with the
7549 name of a variable.
7550 Returns zero if none are available.
7551 Returns -1 if something is wrong.
7552 See also |clientserver|.
7553 This function is not available in the |sandbox|.
7554 {only available when compiled with the |+clientserver| feature}
7555 Examples: >
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007556 :let repl = ""
7557 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007558
7559< Can also be used as a |method|: >
7560 ServerId()->remote_peek()
7561
7562remote_read({serverid}, [{timeout}]) *remote_read()*
7563 Return the oldest available reply from {serverid} and consume
7564 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007565 reply is available. Returns an empty string, if a reply is
7566 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007567 See also |clientserver|.
7568 This function is not available in the |sandbox|.
7569 {only available when compiled with the |+clientserver| feature}
7570 Example: >
7571 :echo remote_read(id)
7572
7573< Can also be used as a |method|: >
7574 ServerId()->remote_read()
7575<
7576 *remote_send()* *E241*
7577remote_send({server}, {string} [, {idvar}])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007578 Send the {string} to {server}. The {server} argument is a
7579 string, also see |{server}|.
7580
7581 The string is sent as input keys and the function returns
7582 immediately. At the Vim server the keys are not mapped
7583 |:map|.
7584
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007585 If {idvar} is present, it is taken as the name of a variable
7586 and a {serverid} for later use with remote_read() is stored
7587 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007588
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007589 See also |clientserver| |RemoteReply|.
7590 This function is not available in the |sandbox|.
7591 {only available when compiled with the |+clientserver| feature}
7592
7593 Note: Any errors will be reported in the server and may mess
7594 up the display.
7595 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007596 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007597 \ remote_read(serverid)
7598
7599 :autocmd NONE RemoteReply *
7600 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007601 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007602 \ 'server2client(expand("<client>"), "HELLO")<CR>')
7603<
7604 Can also be used as a |method|: >
7605 ServerName()->remote_send(keys)
7606<
7607 *remote_startserver()* *E941* *E942*
7608remote_startserver({name})
h-east17b69512023-05-01 22:36:56 +01007609 Become the server {name}. {name} must be a non-empty string.
7610 This fails if already running as a server, when |v:servername|
7611 is not empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007612
7613 Can also be used as a |method|: >
7614 ServerName()->remote_startserver()
7615
7616< {only available when compiled with the |+clientserver| feature}
7617
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007618remove({list}, {idx})
7619remove({list}, {idx}, {end}) *remove()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007620 Without {end}: Remove the item at {idx} from |List| {list} and
7621 return the item.
7622 With {end}: Remove items from {idx} to {end} (inclusive) and
7623 return a |List| with these items. When {idx} points to the same
7624 item as {end} a list with one item is returned. When {end}
7625 points to an item before {idx} this is an error.
7626 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007627 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007628 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007629 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007630 :call remove(mylist, 0, 9)
7631<
7632 Use |delete()| to remove a file.
7633
7634 Can also be used as a |method|: >
7635 mylist->remove(idx)
7636
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007637remove({blob}, {idx})
7638remove({blob}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007639 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
7640 return the byte.
7641 With {end}: Remove bytes from {idx} to {end} (inclusive) and
7642 return a |Blob| with these bytes. When {idx} points to the same
7643 byte as {end} a |Blob| with one byte is returned. When {end}
7644 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007645 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007646 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007647 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007648 :call remove(mylist, 0, 9)
7649
7650remove({dict}, {key})
7651 Remove the entry from {dict} with key {key} and return it.
7652 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007653 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007654< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007655 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007656
7657rename({from}, {to}) *rename()*
7658 Rename the file by the name {from} to the name {to}. This
7659 should also work to move files across file systems. The
7660 result is a Number, which is 0 if the file was renamed
7661 successfully, and non-zero when the renaming failed.
7662 NOTE: If {to} exists it is overwritten without warning.
7663 This function is not available in the |sandbox|.
7664
7665 Can also be used as a |method|: >
7666 GetOldName()->rename(newname)
7667
7668repeat({expr}, {count}) *repeat()*
7669 Repeat {expr} {count} times and return the concatenated
7670 result. Example: >
7671 :let separator = repeat('-', 80)
7672< When {count} is zero or negative the result is empty.
Bakudankun375141e2022-09-09 18:46:47 +01007673 When {expr} is a |List| or a |Blob| the result is {expr}
7674 concatenated {count} times. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007675 :let longlist = repeat(['a', 'b'], 3)
7676< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
7677
7678 Can also be used as a |method|: >
7679 mylist->repeat(count)
7680
7681resolve({filename}) *resolve()* *E655*
7682 On MS-Windows, when {filename} is a shortcut (a .lnk file),
7683 returns the path the shortcut points to in a simplified form.
7684 When {filename} is a symbolic link or junction point, return
7685 the full path to the target. If the target of junction is
7686 removed, return {filename}.
7687 On Unix, repeat resolving symbolic links in all path
7688 components of {filename} and return the simplified result.
7689 To cope with link cycles, resolving of symbolic links is
7690 stopped after 100 iterations.
7691 On other systems, return the simplified {filename}.
7692 The simplification step is done as by |simplify()|.
7693 resolve() keeps a leading path component specifying the
7694 current directory (provided the result is still a relative
7695 path name) and also keeps a trailing path separator.
7696
7697 Can also be used as a |method|: >
7698 GetName()->resolve()
7699
7700reverse({object}) *reverse()*
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +01007701 Reverse the order of items in {object}. {object} can be a
7702 |List|, a |Blob| or a |String|. For a List and a Blob the
7703 items are reversed in-place and {object} is returned.
7704 For a String a new String is returned.
7705 Returns zero if {object} is not a List, Blob or a String.
7706 If you want a List or Blob to remain unmodified make a copy
7707 first: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007708 :let revlist = reverse(copy(mylist))
7709< Can also be used as a |method|: >
7710 mylist->reverse()
7711
7712round({expr}) *round()*
7713 Round off {expr} to the nearest integral value and return it
7714 as a |Float|. If {expr} lies halfway between two integral
7715 values, then use the larger one (away from zero).
7716 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007717 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007718 Examples: >
7719 echo round(0.456)
7720< 0.0 >
7721 echo round(4.5)
7722< 5.0 >
7723 echo round(-4.5)
7724< -5.0
7725
7726 Can also be used as a |method|: >
7727 Compute()->round()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007728
7729rubyeval({expr}) *rubyeval()*
7730 Evaluate Ruby expression {expr} and return its result
7731 converted to Vim data structures.
7732 Numbers, floats and strings are returned as they are (strings
7733 are copied though).
7734 Arrays are represented as Vim |List| type.
7735 Hashes are represented as Vim |Dictionary| type.
7736 Other objects are represented as strings resulted from their
7737 "Object#to_s" method.
7738 Note that in a `:def` function local variables are not visible
7739 to {expr}.
7740
7741 Can also be used as a |method|: >
7742 GetRubyExpr()->rubyeval()
7743
7744< {only available when compiled with the |+ruby| feature}
7745
7746screenattr({row}, {col}) *screenattr()*
7747 Like |screenchar()|, but return the attribute. This is a rather
7748 arbitrary number that can only be used to compare to the
7749 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007750 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007751
7752 Can also be used as a |method|: >
7753 GetRow()->screenattr(col)
7754
7755screenchar({row}, {col}) *screenchar()*
7756 The result is a Number, which is the character at position
7757 [row, col] on the screen. This works for every possible
7758 screen position, also status lines, window separators and the
7759 command line. The top left position is row one, column one
7760 The character excludes composing characters. For double-byte
7761 encodings it may only be the first byte.
7762 This is mainly to be used for testing.
7763 Returns -1 when row or col is out of range.
7764
7765 Can also be used as a |method|: >
7766 GetRow()->screenchar(col)
7767
7768screenchars({row}, {col}) *screenchars()*
7769 The result is a |List| of Numbers. The first number is the same
7770 as what |screenchar()| returns. Further numbers are
7771 composing characters on top of the base character.
7772 This is mainly to be used for testing.
7773 Returns an empty List when row or col is out of range.
7774
7775 Can also be used as a |method|: >
7776 GetRow()->screenchars(col)
7777
7778screencol() *screencol()*
7779 The result is a Number, which is the current screen column of
7780 the cursor. The leftmost column has number 1.
7781 This function is mainly used for testing.
7782
7783 Note: Always returns the current screen column, thus if used
7784 in a command (e.g. ":echo screencol()") it will return the
7785 column inside the command line, which is 1 when the command is
7786 executed. To get the cursor position in the file use one of
7787 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007788 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007789 nnoremap <silent> GG :echom screencol()<CR>
7790 nnoremap GG <Cmd>echom screencol()<CR>
7791<
7792screenpos({winid}, {lnum}, {col}) *screenpos()*
7793 The result is a Dict with the screen position of the text
7794 character in window {winid} at buffer line {lnum} and column
7795 {col}. {col} is a one-based byte index.
7796 The Dict has these members:
7797 row screen row
7798 col first screen column
7799 endcol last screen column
7800 curscol cursor screen column
7801 If the specified position is not visible, all values are zero.
7802 The "endcol" value differs from "col" when the character
7803 occupies more than one screen cell. E.g. for a Tab "col" can
7804 be 1 and "endcol" can be 8.
7805 The "curscol" value is where the cursor would be placed. For
7806 a Tab it would be the same as "endcol", while for a double
7807 width character it would be the same as "col".
7808 The |conceal| feature is ignored here, the column numbers are
7809 as if 'conceallevel' is zero. You can set the cursor to the
7810 right position and use |screencol()| to get the value with
7811 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007812 If the position is in a closed fold the screen position of the
7813 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007814 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007815
7816 Can also be used as a |method|: >
7817 GetWinid()->screenpos(lnum, col)
7818
7819screenrow() *screenrow()*
7820 The result is a Number, which is the current screen row of the
7821 cursor. The top line has number one.
7822 This function is mainly used for testing.
7823 Alternatively you can use |winline()|.
7824
7825 Note: Same restrictions as with |screencol()|.
7826
7827screenstring({row}, {col}) *screenstring()*
7828 The result is a String that contains the base character and
7829 any composing characters at position [row, col] on the screen.
7830 This is like |screenchars()| but returning a String with the
7831 characters.
7832 This is mainly to be used for testing.
7833 Returns an empty String when row or col is out of range.
7834
7835 Can also be used as a |method|: >
7836 GetRow()->screenstring(col)
7837<
7838 *search()*
7839search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7840 Search for regexp pattern {pattern}. The search starts at the
7841 cursor position (you can use |cursor()| to set it).
7842
7843 When a match has been found its line number is returned.
7844 If there is no match a 0 is returned and the cursor doesn't
7845 move. No error message is given.
7846
7847 {flags} is a String, which can contain these character flags:
7848 'b' search Backward instead of forward
7849 'c' accept a match at the Cursor position
7850 'e' move to the End of the match
7851 'n' do Not move the cursor
7852 'p' return number of matching sub-Pattern (see below)
7853 's' Set the ' mark at the previous location of the cursor
7854 'w' Wrap around the end of the file
7855 'W' don't Wrap around the end of the file
7856 'z' start searching at the cursor column instead of zero
7857 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
7858
7859 If the 's' flag is supplied, the ' mark is set, only if the
7860 cursor is moved. The 's' flag cannot be combined with the 'n'
7861 flag.
7862
7863 'ignorecase', 'smartcase' and 'magic' are used.
7864
7865 When the 'z' flag is not given, forward searching always
7866 starts in column zero and then matches before the cursor are
7867 skipped. When the 'c' flag is present in 'cpo' the next
7868 search starts after the match. Without the 'c' flag the next
Bram Moolenaarfd999452022-08-24 18:30:14 +01007869 search starts one column after the start of the match. This
7870 matters for overlapping matches. See |cpo-c|. You can also
7871 insert "\ze" to change where the match ends, see |/\ze|.
7872
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007873 When searching backwards and the 'z' flag is given then the
7874 search starts in column zero, thus no match in the current
7875 line will be found (unless wrapping around the end of the
7876 file).
7877
7878 When the {stopline} argument is given then the search stops
7879 after searching this line. This is useful to restrict the
7880 search to a range of lines. Examples: >
7881 let match = search('(', 'b', line("w0"))
7882 let end = search('END', '', line("w$"))
7883< When {stopline} is used and it is not zero this also implies
7884 that the search does not wrap around the end of the file.
7885 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01007886 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007887 When the {timeout} argument is given the search stops when
7888 more than this many milliseconds have passed. Thus when
7889 {timeout} is 500 the search stops after half a second.
7890 The value must not be negative. A zero value is like not
7891 giving the argument.
7892 {only available when compiled with the |+reltime| feature}
7893
7894 If the {skip} expression is given it is evaluated with the
7895 cursor positioned on the start of a match. If it evaluates to
7896 non-zero this match is skipped. This can be used, for
7897 example, to skip a match in a comment or a string.
7898 {skip} can be a string, which is evaluated as an expression, a
7899 function reference or a lambda.
7900 When {skip} is omitted or empty, every match is accepted.
7901 When evaluating {skip} causes an error the search is aborted
7902 and -1 returned.
7903 *search()-sub-match*
7904 With the 'p' flag the returned value is one more than the
7905 first sub-match in \(\). One if none of them matched but the
7906 whole pattern did match.
7907 To get the column number too use |searchpos()|.
7908
7909 The cursor will be positioned at the match, unless the 'n'
7910 flag is used.
7911
7912 Example (goes over all files in the argument list): >
7913 :let n = 1
7914 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007915 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007916 : " start at the last char in the file and wrap for the
7917 : " first search to find match at start of file
7918 : normal G$
7919 : let flags = "w"
7920 : while search("foo", flags) > 0
7921 : s/foo/bar/g
7922 : let flags = "W"
7923 : endwhile
7924 : update " write the file if modified
7925 : let n = n + 1
7926 :endwhile
7927<
7928 Example for using some flags: >
7929 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7930< This will search for the keywords "if", "else", and "endif"
7931 under or after the cursor. Because of the 'p' flag, it
7932 returns 1, 2, or 3 depending on which keyword is found, or 0
7933 if the search fails. With the cursor on the first word of the
7934 line:
7935 if (foo == 0) | let foo = foo + 1 | endif ~
7936 the function returns 1. Without the 'c' flag, the function
7937 finds the "endif" and returns 3. The same thing happens
7938 without the 'e' flag if the cursor is on the "f" of "if".
7939 The 'n' flag tells the function not to move the cursor.
7940
7941 Can also be used as a |method|: >
7942 GetPattern()->search()
7943
7944searchcount([{options}]) *searchcount()*
7945 Get or update the last search count, like what is displayed
7946 without the "S" flag in 'shortmess'. This works even if
7947 'shortmess' does contain the "S" flag.
7948
7949 This returns a |Dictionary|. The dictionary is empty if the
7950 previous pattern was not set and "pattern" was not specified.
7951
7952 key type meaning ~
7953 current |Number| current position of match;
7954 0 if the cursor position is
7955 before the first match
7956 exact_match |Boolean| 1 if "current" is matched on
7957 "pos", otherwise 0
7958 total |Number| total count of matches found
7959 incomplete |Number| 0: search was fully completed
7960 1: recomputing was timed out
7961 2: max count exceeded
7962
7963 For {options} see further down.
7964
7965 To get the last search count when |n| or |N| was pressed, call
7966 this function with `recompute: 0` . This sometimes returns
7967 wrong information because |n| and |N|'s maximum count is 99.
7968 If it exceeded 99 the result must be max count + 1 (100). If
7969 you want to get correct information, specify `recompute: 1`: >
7970
7971 " result == maxcount + 1 (100) when many matches
7972 let result = searchcount(#{recompute: 0})
7973
7974 " Below returns correct result (recompute defaults
7975 " to 1)
7976 let result = searchcount()
7977<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01007978 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007979 function! LastSearchCount() abort
7980 let result = searchcount(#{recompute: 0})
7981 if empty(result)
7982 return ''
7983 endif
7984 if result.incomplete ==# 1 " timed out
7985 return printf(' /%s [?/??]', @/)
7986 elseif result.incomplete ==# 2 " max count exceeded
7987 if result.total > result.maxcount &&
7988 \ result.current > result.maxcount
7989 return printf(' /%s [>%d/>%d]', @/,
7990 \ result.current, result.total)
7991 elseif result.total > result.maxcount
7992 return printf(' /%s [%d/>%d]', @/,
7993 \ result.current, result.total)
7994 endif
7995 endif
7996 return printf(' /%s [%d/%d]', @/,
7997 \ result.current, result.total)
7998 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007999 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008000
8001 " Or if you want to show the count only when
8002 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008003 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008004 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
8005<
8006 You can also update the search count, which can be useful in a
8007 |CursorMoved| or |CursorMovedI| autocommand: >
8008
8009 autocmd CursorMoved,CursorMovedI *
8010 \ let s:searchcount_timer = timer_start(
8011 \ 200, function('s:update_searchcount'))
8012 function! s:update_searchcount(timer) abort
8013 if a:timer ==# s:searchcount_timer
8014 call searchcount(#{
8015 \ recompute: 1, maxcount: 0, timeout: 100})
8016 redrawstatus
8017 endif
8018 endfunction
8019<
8020 This can also be used to count matched texts with specified
8021 pattern in the current buffer using "pattern": >
8022
8023 " Count '\<foo\>' in this buffer
8024 " (Note that it also updates search count)
8025 let result = searchcount(#{pattern: '\<foo\>'})
8026
8027 " To restore old search count by old pattern,
8028 " search again
8029 call searchcount()
8030<
8031 {options} must be a |Dictionary|. It can contain:
8032 key type meaning ~
8033 recompute |Boolean| if |TRUE|, recompute the count
8034 like |n| or |N| was executed.
8035 otherwise returns the last
8036 computed result (when |n| or
8037 |N| was used when "S" is not
8038 in 'shortmess', or this
8039 function was called).
8040 (default: |TRUE|)
8041 pattern |String| recompute if this was given
8042 and different with |@/|.
8043 this works as same as the
8044 below command is executed
8045 before calling this function >
8046 let @/ = pattern
8047< (default: |@/|)
8048 timeout |Number| 0 or negative number is no
8049 timeout. timeout milliseconds
8050 for recomputing the result
8051 (default: 0)
8052 maxcount |Number| 0 or negative number is no
8053 limit. max count of matched
8054 text while recomputing the
8055 result. if search exceeded
8056 total count, "total" value
8057 becomes `maxcount + 1`
8058 (default: 99)
8059 pos |List| `[lnum, col, off]` value
8060 when recomputing the result.
8061 this changes "current" result
8062 value. see |cursor()|,
8063 |getpos()|
8064 (default: cursor's position)
8065
8066 Can also be used as a |method|: >
8067 GetSearchOpts()->searchcount()
8068<
8069searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
8070 Search for the declaration of {name}.
8071
8072 With a non-zero {global} argument it works like |gD|, find
8073 first match in the file. Otherwise it works like |gd|, find
8074 first match in the function.
8075
8076 With a non-zero {thisblock} argument matches in a {} block
8077 that ends before the cursor position are ignored. Avoids
8078 finding variable declarations only valid in another scope.
8079
8080 Moves the cursor to the found match.
8081 Returns zero for success, non-zero for failure.
8082 Example: >
8083 if searchdecl('myvar') == 0
8084 echo getline('.')
8085 endif
8086<
8087 Can also be used as a |method|: >
8088 GetName()->searchdecl()
8089<
8090 *searchpair()*
8091searchpair({start}, {middle}, {end} [, {flags} [, {skip}
8092 [, {stopline} [, {timeout}]]]])
8093 Search for the match of a nested start-end pair. This can be
8094 used to find the "endif" that matches an "if", while other
8095 if/endif pairs in between are ignored.
8096 The search starts at the cursor. The default is to search
8097 forward, include 'b' in {flags} to search backward.
8098 If a match is found, the cursor is positioned at it and the
8099 line number is returned. If no match is found 0 or -1 is
8100 returned and the cursor doesn't move. No error message is
8101 given.
8102
8103 {start}, {middle} and {end} are patterns, see |pattern|. They
8104 must not contain \( \) pairs. Use of \%( \) is allowed. When
8105 {middle} is not empty, it is found when searching from either
8106 direction, but only when not in a nested start-end pair. A
8107 typical use is: >
8108 searchpair('\<if\>', '\<else\>', '\<endif\>')
8109< By leaving {middle} empty the "else" is skipped.
8110
8111 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
8112 |search()|. Additionally:
8113 'r' Repeat until no more matches found; will find the
8114 outer pair. Implies the 'W' flag.
8115 'm' Return number of matches instead of line number with
8116 the match; will be > 1 when 'r' is used.
8117 Note: it's nearly always a good idea to use the 'W' flag, to
8118 avoid wrapping around the end of the file.
8119
8120 When a match for {start}, {middle} or {end} is found, the
8121 {skip} expression is evaluated with the cursor positioned on
8122 the start of the match. It should return non-zero if this
8123 match is to be skipped. E.g., because it is inside a comment
8124 or a string.
8125 When {skip} is omitted or empty, every match is accepted.
8126 When evaluating {skip} causes an error the search is aborted
8127 and -1 returned.
8128 {skip} can be a string, a lambda, a funcref or a partial.
8129 Anything else makes the function fail.
8130 In a `:def` function when the {skip} argument is a string
8131 constant it is compiled into instructions.
8132
8133 For {stopline} and {timeout} see |search()|.
8134
8135 The value of 'ignorecase' is used. 'magic' is ignored, the
8136 patterns are used like it's on.
8137
8138 The search starts exactly at the cursor. A match with
8139 {start}, {middle} or {end} at the next character, in the
8140 direction of searching, is the first one found. Example: >
8141 if 1
8142 if 2
8143 endif 2
8144 endif 1
8145< When starting at the "if 2", with the cursor on the "i", and
8146 searching forwards, the "endif 2" is found. When starting on
8147 the character just before the "if 2", the "endif 1" will be
8148 found. That's because the "if 2" will be found first, and
8149 then this is considered to be a nested if/endif from "if 2" to
8150 "endif 2".
8151 When searching backwards and {end} is more than one character,
8152 it may be useful to put "\zs" at the end of the pattern, so
8153 that when the cursor is inside a match with the end it finds
8154 the matching start.
8155
8156 Example, to find the "endif" command in a Vim script: >
8157
8158 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
8159 \ 'getline(".") =~ "^\\s*\""')
8160
8161< The cursor must be at or after the "if" for which a match is
8162 to be found. Note that single-quote strings are used to avoid
8163 having to double the backslashes. The skip expression only
8164 catches comments at the start of a line, not after a command.
8165 Also, a word "en" or "if" halfway a line is considered a
8166 match.
8167 Another example, to search for the matching "{" of a "}": >
8168
8169 :echo searchpair('{', '', '}', 'bW')
8170
8171< This works when the cursor is at or before the "}" for which a
8172 match is to be found. To reject matches that syntax
8173 highlighting recognized as strings: >
8174
8175 :echo searchpair('{', '', '}', 'bW',
8176 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
8177<
8178 *searchpairpos()*
8179searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
8180 [, {stopline} [, {timeout}]]]])
8181 Same as |searchpair()|, but returns a |List| with the line and
8182 column position of the match. The first element of the |List|
8183 is the line number and the second element is the byte index of
8184 the column position of the match. If no match is found,
8185 returns [0, 0]. >
8186
8187 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
8188<
8189 See |match-parens| for a bigger and more useful example.
8190
8191 *searchpos()*
8192searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
8193 Same as |search()|, but returns a |List| with the line and
8194 column position of the match. The first element of the |List|
8195 is the line number and the second element is the byte index of
8196 the column position of the match. If no match is found,
8197 returns [0, 0].
8198 Example: >
8199 :let [lnum, col] = searchpos('mypattern', 'n')
8200
8201< When the 'p' flag is given then there is an extra item with
8202 the sub-pattern match number |search()-sub-match|. Example: >
8203 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
8204< In this example "submatch" is 2 when a lowercase letter is
8205 found |/\l|, 3 when an uppercase letter is found |/\u|.
8206
8207 Can also be used as a |method|: >
8208 GetPattern()->searchpos()
8209
8210server2client({clientid}, {string}) *server2client()*
8211 Send a reply string to {clientid}. The most recent {clientid}
8212 that sent a string can be retrieved with expand("<client>").
8213 {only available when compiled with the |+clientserver| feature}
8214 Returns zero for success, -1 for failure.
8215 Note:
8216 This id has to be stored before the next command can be
8217 received. I.e. before returning from the received command and
8218 before calling any commands that waits for input.
8219 See also |clientserver|.
8220 Example: >
8221 :echo server2client(expand("<client>"), "HELLO")
8222
8223< Can also be used as a |method|: >
8224 GetClientId()->server2client(string)
8225<
8226serverlist() *serverlist()*
8227 Return a list of available server names, one per line.
8228 When there are no servers or the information is not available
8229 an empty string is returned. See also |clientserver|.
8230 {only available when compiled with the |+clientserver| feature}
8231 Example: >
8232 :echo serverlist()
8233<
8234setbufline({buf}, {lnum}, {text}) *setbufline()*
8235 Set line {lnum} to {text} in buffer {buf}. This works like
8236 |setline()| for the specified buffer.
8237
8238 This function works only for loaded buffers. First call
8239 |bufload()| if needed.
8240
8241 To insert lines use |appendbufline()|.
8242 Any text properties in {lnum} are cleared.
8243
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00008244 {text} can be a string to set one line, or a List of strings
8245 to set multiple lines. If the List extends below the last
8246 line then those lines are added. If the List is empty then
8247 nothing is changed and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008248
8249 For the use of {buf}, see |bufname()| above.
8250
8251 {lnum} is used like with |setline()|.
8252 Use "$" to refer to the last line in buffer {buf}.
8253 When {lnum} is just below the last line the {text} will be
8254 added below the last line.
8255
8256 When {buf} is not a valid buffer, the buffer is not loaded or
8257 {lnum} is not valid then 1 is returned. In |Vim9| script an
8258 error is given.
8259 On success 0 is returned.
8260
8261 Can also be used as a |method|, the base is passed as the
8262 third argument: >
8263 GetText()->setbufline(buf, lnum)
8264
8265setbufvar({buf}, {varname}, {val}) *setbufvar()*
8266 Set option or local variable {varname} in buffer {buf} to
8267 {val}.
8268 This also works for a global or local window option, but it
8269 doesn't work for a global or local window variable.
8270 For a local window option the global value is unchanged.
8271 For the use of {buf}, see |bufname()| above.
8272 The {varname} argument is a string.
8273 Note that the variable name without "b:" must be used.
8274 Examples: >
8275 :call setbufvar(1, "&mod", 1)
8276 :call setbufvar("todo", "myvar", "foobar")
8277< This function is not available in the |sandbox|.
8278
8279 Can also be used as a |method|, the base is passed as the
8280 third argument: >
8281 GetValue()->setbufvar(buf, varname)
8282
8283
8284setcellwidths({list}) *setcellwidths()*
8285 Specify overrides for cell widths of character ranges. This
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008286 tells Vim how wide characters are when displayed in the
8287 terminal, counted in screen cells. The values override
8288 'ambiwidth'. Example: >
8289 call setcellwidths([
Bram Moolenaar938ae282023-02-20 20:44:55 +00008290 \ [0x111, 0x111, 1],
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008291 \ [0x2194, 0x2199, 2],
8292 \ ])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008293
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008294< The {list} argument is a List of Lists with each three
8295 numbers: [{low}, {high}, {width}]. *E1109* *E1110*
8296 {low} and {high} can be the same, in which case this refers to
8297 one character. Otherwise it is the range of characters from
8298 {low} to {high} (inclusive). *E1111* *E1114*
K.Takata71933232023-01-20 16:00:55 +00008299 Only characters with value 0x80 and higher can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008300
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008301 {width} must be either 1 or 2, indicating the character width
8302 in screen cells. *E1112*
8303 An error is given if the argument is invalid, also when a
Bram Moolenaar938ae282023-02-20 20:44:55 +00008304 range overlaps with another. *E1113*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008305
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008306 If the new value causes 'fillchars' or 'listchars' to become
8307 invalid it is rejected and an error is given.
8308
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008309 To clear the overrides pass an empty {list}: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008310 setcellwidths([]);
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008311
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008312< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008313 the effect for known emoji characters. Move the cursor
8314 through the text to check if the cell widths of your terminal
8315 match with what Vim knows about each emoji. If it doesn't
8316 look right you need to adjust the {list} argument.
8317
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008318
8319setcharpos({expr}, {list}) *setcharpos()*
8320 Same as |setpos()| but uses the specified column number as the
8321 character index instead of the byte index in the line.
8322
8323 Example:
8324 With the text "여보세요" in line 8: >
8325 call setcharpos('.', [0, 8, 4, 0])
8326< positions the cursor on the fourth character '요'. >
8327 call setpos('.', [0, 8, 4, 0])
8328< positions the cursor on the second character '보'.
8329
8330 Can also be used as a |method|: >
8331 GetPosition()->setcharpos('.')
8332
8333setcharsearch({dict}) *setcharsearch()*
8334 Set the current character search information to {dict},
8335 which contains one or more of the following entries:
8336
8337 char character which will be used for a subsequent
8338 |,| or |;| command; an empty string clears the
8339 character search
8340 forward direction of character search; 1 for forward,
8341 0 for backward
8342 until type of character search; 1 for a |t| or |T|
8343 character search, 0 for an |f| or |F|
8344 character search
8345
8346 This can be useful to save/restore a user's character search
8347 from a script: >
8348 :let prevsearch = getcharsearch()
8349 :" Perform a command which clobbers user's search
8350 :call setcharsearch(prevsearch)
8351< Also see |getcharsearch()|.
8352
8353 Can also be used as a |method|: >
8354 SavedSearch()->setcharsearch()
8355
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01008356setcmdline({str} [, {pos}]) *setcmdline()*
8357 Set the command line to {str} and set the cursor position to
8358 {pos}.
8359 If {pos} is omitted, the cursor is positioned after the text.
8360 Returns 0 when successful, 1 when not editing the command
8361 line.
8362
8363 Can also be used as a |method|: >
8364 GetText()->setcmdline()
8365
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008366setcmdpos({pos}) *setcmdpos()*
8367 Set the cursor position in the command line to byte position
8368 {pos}. The first position is 1.
8369 Use |getcmdpos()| to obtain the current position.
8370 Only works while editing the command line, thus you must use
8371 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
8372 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
8373 set after the command line is set to the expression. For
8374 |c_CTRL-R_=| it is set after evaluating the expression but
8375 before inserting the resulting text.
8376 When the number is too big the cursor is put at the end of the
8377 line. A number smaller than one has undefined results.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01008378 Returns 0 when successful, 1 when not editing the command
8379 line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008380
8381 Can also be used as a |method|: >
8382 GetPos()->setcmdpos()
8383
8384setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
8385setcursorcharpos({list})
8386 Same as |cursor()| but uses the specified column number as the
8387 character index instead of the byte index in the line.
8388
8389 Example:
8390 With the text "여보세요" in line 4: >
8391 call setcursorcharpos(4, 3)
8392< positions the cursor on the third character '세'. >
8393 call cursor(4, 3)
8394< positions the cursor on the first character '여'.
8395
8396 Can also be used as a |method|: >
8397 GetCursorPos()->setcursorcharpos()
8398
8399
8400setenv({name}, {val}) *setenv()*
8401 Set environment variable {name} to {val}. Example: >
8402 call setenv('HOME', '/home/myhome')
8403
8404< When {val} is |v:null| the environment variable is deleted.
8405 See also |expr-env|.
8406
8407 Can also be used as a |method|, the base is passed as the
8408 second argument: >
8409 GetPath()->setenv('PATH')
8410
8411setfperm({fname}, {mode}) *setfperm()* *chmod*
8412 Set the file permissions for {fname} to {mode}.
8413 {mode} must be a string with 9 characters. It is of the form
8414 "rwxrwxrwx", where each group of "rwx" flags represent, in
8415 turn, the permissions of the owner of the file, the group the
8416 file belongs to, and other users. A '-' character means the
8417 permission is off, any other character means on. Multi-byte
8418 characters are not supported.
8419
8420 For example "rw-r-----" means read-write for the user,
8421 readable by the group, not accessible by others. "xx-x-----"
8422 would do the same thing.
8423
8424 Returns non-zero for success, zero for failure.
8425
8426 Can also be used as a |method|: >
8427 GetFilename()->setfperm(mode)
8428<
8429 To read permissions see |getfperm()|.
8430
8431
8432setline({lnum}, {text}) *setline()*
8433 Set line {lnum} of the current buffer to {text}. To insert
8434 lines use |append()|. To set lines in another buffer use
8435 |setbufline()|. Any text properties in {lnum} are cleared.
8436
8437 {lnum} is used like with |getline()|.
8438 When {lnum} is just below the last line the {text} will be
8439 added below the last line.
8440 {text} can be any type or a List of any type, each item is
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00008441 converted to a String. When {text} is an empty List then
8442 nothing is changed and FALSE is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008443
8444 If this succeeds, FALSE is returned. If this fails (most likely
8445 because {lnum} is invalid) TRUE is returned.
8446 In |Vim9| script an error is given if {lnum} is invalid.
8447
8448 Example: >
8449 :call setline(5, strftime("%c"))
8450
8451< When {text} is a |List| then line {lnum} and following lines
8452 will be set to the items in the list. Example: >
8453 :call setline(5, ['aaa', 'bbb', 'ccc'])
8454< This is equivalent to: >
8455 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
8456 : call setline(n, l)
8457 :endfor
8458
8459< Note: The '[ and '] marks are not set.
8460
8461 Can also be used as a |method|, the base is passed as the
8462 second argument: >
8463 GetText()->setline(lnum)
8464
8465setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
8466 Create or replace or add to the location list for window {nr}.
8467 {nr} can be the window number or the |window-ID|.
8468 When {nr} is zero the current window is used.
8469
8470 For a location list window, the displayed location list is
8471 modified. For an invalid window number {nr}, -1 is returned.
8472 Otherwise, same as |setqflist()|.
8473 Also see |location-list|.
8474
8475 For {action} see |setqflist-action|.
8476
8477 If the optional {what} dictionary argument is supplied, then
8478 only the items listed in {what} are set. Refer to |setqflist()|
8479 for the list of supported keys in {what}.
8480
8481 Can also be used as a |method|, the base is passed as the
8482 second argument: >
8483 GetLoclist()->setloclist(winnr)
8484
8485setmatches({list} [, {win}]) *setmatches()*
8486 Restores a list of matches saved by |getmatches()| for the
8487 current window. Returns 0 if successful, otherwise -1. All
8488 current matches are cleared before the list is restored. See
8489 example for |getmatches()|.
8490 If {win} is specified, use the window with this number or
8491 window ID instead of the current window.
8492
8493 Can also be used as a |method|: >
8494 GetMatches()->setmatches()
8495<
8496 *setpos()*
8497setpos({expr}, {list})
8498 Set the position for String {expr}. Possible values:
8499 . the cursor
8500 'x mark x
8501
8502 {list} must be a |List| with four or five numbers:
8503 [bufnum, lnum, col, off]
8504 [bufnum, lnum, col, off, curswant]
8505
8506 "bufnum" is the buffer number. Zero can be used for the
8507 current buffer. When setting an uppercase mark "bufnum" is
8508 used for the mark position. For other marks it specifies the
8509 buffer to set the mark in. You can use the |bufnr()| function
8510 to turn a file name into a buffer number.
8511 For setting the cursor and the ' mark "bufnum" is ignored,
8512 since these are associated with a window, not a buffer.
8513 Does not change the jumplist.
8514
8515 "lnum" and "col" are the position in the buffer. The first
8516 column is 1. Use a zero "lnum" to delete a mark. If "col" is
8517 smaller than 1 then 1 is used. To use the character count
8518 instead of the byte count, use |setcharpos()|.
8519
8520 The "off" number is only used when 'virtualedit' is set. Then
8521 it is the offset in screen columns from the start of the
8522 character. E.g., a position within a <Tab> or after the last
8523 character.
8524
8525 The "curswant" number is only used when setting the cursor
8526 position. It sets the preferred column for when moving the
8527 cursor vertically. When the "curswant" number is missing the
8528 preferred column is not set. When it is present and setting a
8529 mark position it is not used.
8530
8531 Note that for '< and '> changing the line number may result in
8532 the marks to be effectively be swapped, so that '< is always
8533 before '>.
8534
8535 Returns 0 when the position could be set, -1 otherwise.
8536 An error message is given if {expr} is invalid.
8537
8538 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
8539
8540 This does not restore the preferred column for moving
8541 vertically; if you set the cursor position with this, |j| and
8542 |k| motions will jump to previous columns! Use |cursor()| to
8543 also set the preferred column. Also see the "curswant" key in
8544 |winrestview()|.
8545
8546 Can also be used as a |method|: >
8547 GetPosition()->setpos('.')
8548
8549setqflist({list} [, {action} [, {what}]]) *setqflist()*
8550 Create or replace or add to the quickfix list.
8551
8552 If the optional {what} dictionary argument is supplied, then
8553 only the items listed in {what} are set. The first {list}
8554 argument is ignored. See below for the supported items in
8555 {what}.
8556 *setqflist-what*
8557 When {what} is not present, the items in {list} are used. Each
8558 item must be a dictionary. Non-dictionary items in {list} are
8559 ignored. Each dictionary item can contain the following
8560 entries:
8561
8562 bufnr buffer number; must be the number of a valid
8563 buffer
8564 filename name of a file; only used when "bufnr" is not
8565 present or it is invalid.
8566 module name of a module; if given it will be used in
8567 quickfix error window instead of the filename.
8568 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +00008569 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008570 pattern search pattern used to locate the error
8571 col column number
8572 vcol when non-zero: "col" is visual column
8573 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +00008574 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008575 nr error number
8576 text description of the error
8577 type single-character error type, 'E', 'W', etc.
8578 valid recognized error message
Tom Praschanca6ac992023-08-11 23:26:12 +02008579 user_data custom data associated with the item, can be
8580 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008581
8582 The "col", "vcol", "nr", "type" and "text" entries are
8583 optional. Either "lnum" or "pattern" entry can be used to
8584 locate a matching error line.
8585 If the "filename" and "bufnr" entries are not present or
8586 neither the "lnum" or "pattern" entries are present, then the
8587 item will not be handled as an error line.
8588 If both "pattern" and "lnum" are present then "pattern" will
8589 be used.
8590 If the "valid" entry is not supplied, then the valid flag is
8591 set when "bufnr" is a valid buffer or "filename" exists.
8592 If you supply an empty {list}, the quickfix list will be
8593 cleared.
8594 Note that the list is not exactly the same as what
8595 |getqflist()| returns.
8596
8597 {action} values: *setqflist-action* *E927*
8598 'a' The items from {list} are added to the existing
8599 quickfix list. If there is no existing list, then a
8600 new list is created.
8601
8602 'r' The items from the current quickfix list are replaced
8603 with the items from {list}. This can also be used to
8604 clear the list: >
8605 :call setqflist([], 'r')
8606<
8607 'f' All the quickfix lists in the quickfix stack are
8608 freed.
8609
8610 If {action} is not present or is set to ' ', then a new list
8611 is created. The new quickfix list is added after the current
8612 quickfix list in the stack and all the following lists are
8613 freed. To add a new quickfix list at the end of the stack,
8614 set "nr" in {what} to "$".
8615
8616 The following items can be specified in dictionary {what}:
8617 context quickfix list context. See |quickfix-context|
8618 efm errorformat to use when parsing text from
8619 "lines". If this is not present, then the
8620 'errorformat' option value is used.
8621 See |quickfix-parse|
8622 id quickfix list identifier |quickfix-ID|
8623 idx index of the current entry in the quickfix
8624 list specified by 'id' or 'nr'. If set to '$',
8625 then the last entry in the list is set as the
8626 current entry. See |quickfix-index|
8627 items list of quickfix entries. Same as the {list}
8628 argument.
8629 lines use 'errorformat' to parse a list of lines and
8630 add the resulting entries to the quickfix list
8631 {nr} or {id}. Only a |List| value is supported.
8632 See |quickfix-parse|
8633 nr list number in the quickfix stack; zero
8634 means the current quickfix list and "$" means
8635 the last quickfix list.
8636 quickfixtextfunc
8637 function to get the text to display in the
8638 quickfix window. The value can be the name of
8639 a function or a funcref or a lambda. Refer to
8640 |quickfix-window-function| for an explanation
8641 of how to write the function and an example.
8642 title quickfix list title text. See |quickfix-title|
8643 Unsupported keys in {what} are ignored.
8644 If the "nr" item is not present, then the current quickfix list
8645 is modified. When creating a new quickfix list, "nr" can be
8646 set to a value one greater than the quickfix stack size.
8647 When modifying a quickfix list, to guarantee that the correct
8648 list is modified, "id" should be used instead of "nr" to
8649 specify the list.
8650
8651 Examples (See also |setqflist-examples|): >
8652 :call setqflist([], 'r', {'title': 'My search'})
8653 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
8654 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
8655<
8656 Returns zero for success, -1 for failure.
8657
8658 This function can be used to create a quickfix list
8659 independent of the 'errorformat' setting. Use a command like
8660 `:cc 1` to jump to the first position.
8661
8662 Can also be used as a |method|, the base is passed as the
8663 second argument: >
8664 GetErrorlist()->setqflist()
8665<
8666 *setreg()*
8667setreg({regname}, {value} [, {options}])
8668 Set the register {regname} to {value}.
8669 If {regname} is "" or "@", the unnamed register '"' is used.
8670 The {regname} argument is a string. In |Vim9-script|
8671 {regname} must be one character.
8672
8673 {value} may be any value returned by |getreg()| or
8674 |getreginfo()|, including a |List| or |Dict|.
8675 If {options} contains "a" or {regname} is upper case,
8676 then the value is appended.
8677
8678 {options} can also contain a register type specification:
8679 "c" or "v" |characterwise| mode
8680 "l" or "V" |linewise| mode
8681 "b" or "<CTRL-V>" |blockwise-visual| mode
8682 If a number immediately follows "b" or "<CTRL-V>" then this is
8683 used as the width of the selection - if it is not specified
8684 then the width of the block is set to the number of characters
8685 in the longest line (counting a <Tab> as 1 character).
8686
8687 If {options} contains no register settings, then the default
8688 is to use character mode unless {value} ends in a <NL> for
8689 string {value} and linewise mode for list {value}. Blockwise
8690 mode is never selected automatically.
8691 Returns zero for success, non-zero for failure.
8692
8693 *E883*
8694 Note: you may not use |List| containing more than one item to
8695 set search and expression registers. Lists containing no
8696 items act like empty strings.
8697
8698 Examples: >
8699 :call setreg(v:register, @*)
8700 :call setreg('*', @%, 'ac')
8701 :call setreg('a', "1\n2\n3", 'b5')
8702 :call setreg('"', { 'points_to': 'a'})
8703
8704< This example shows using the functions to save and restore a
8705 register: >
8706 :let var_a = getreginfo()
8707 :call setreg('a', var_a)
8708< or: >
8709 :let var_a = getreg('a', 1, 1)
8710 :let var_amode = getregtype('a')
8711 ....
8712 :call setreg('a', var_a, var_amode)
8713< Note: you may not reliably restore register value
8714 without using the third argument to |getreg()| as without it
8715 newlines are represented as newlines AND Nul bytes are
8716 represented as newlines as well, see |NL-used-for-Nul|.
8717
8718 You can also change the type of a register by appending
8719 nothing: >
8720 :call setreg('a', '', 'al')
8721
8722< Can also be used as a |method|, the base is passed as the
8723 second argument: >
8724 GetText()->setreg('a')
8725
8726settabvar({tabnr}, {varname}, {val}) *settabvar()*
8727 Set tab-local variable {varname} to {val} in tab page {tabnr}.
8728 |t:var|
8729 The {varname} argument is a string.
8730 Note that autocommands are blocked, side effects may not be
8731 triggered, e.g. when setting 'filetype'.
8732 Note that the variable name without "t:" must be used.
8733 Tabs are numbered starting with one.
8734 This function is not available in the |sandbox|.
8735
8736 Can also be used as a |method|, the base is passed as the
8737 third argument: >
8738 GetValue()->settabvar(tab, name)
8739
8740settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
8741 Set option or local variable {varname} in window {winnr} to
8742 {val}.
8743 Tabs are numbered starting with one. For the current tabpage
8744 use |setwinvar()|.
8745 {winnr} can be the window number or the |window-ID|.
8746 When {winnr} is zero the current window is used.
8747 Note that autocommands are blocked, side effects may not be
8748 triggered, e.g. when setting 'filetype' or 'syntax'.
8749 This also works for a global or local buffer option, but it
8750 doesn't work for a global or local buffer variable.
8751 For a local buffer option the global value is unchanged.
8752 Note that the variable name without "w:" must be used.
8753 Examples: >
8754 :call settabwinvar(1, 1, "&list", 0)
8755 :call settabwinvar(3, 2, "myvar", "foobar")
8756< This function is not available in the |sandbox|.
8757
8758 Can also be used as a |method|, the base is passed as the
8759 fourth argument: >
8760 GetValue()->settabwinvar(tab, winnr, name)
8761
8762settagstack({nr}, {dict} [, {action}]) *settagstack()*
8763 Modify the tag stack of the window {nr} using {dict}.
8764 {nr} can be the window number or the |window-ID|.
8765
8766 For a list of supported items in {dict}, refer to
8767 |gettagstack()|. "curidx" takes effect before changing the tag
8768 stack.
8769 *E962*
8770 How the tag stack is modified depends on the {action}
8771 argument:
8772 - If {action} is not present or is set to 'r', then the tag
8773 stack is replaced.
8774 - If {action} is set to 'a', then new entries from {dict} are
8775 pushed (added) onto the tag stack.
8776 - If {action} is set to 't', then all the entries from the
8777 current entry in the tag stack or "curidx" in {dict} are
8778 removed and then new entries are pushed to the stack.
8779
8780 The current index is set to one after the length of the tag
8781 stack after the modification.
8782
8783 Returns zero for success, -1 for failure.
8784
8785 Examples (for more examples see |tagstack-examples|):
8786 Empty the tag stack of window 3: >
8787 call settagstack(3, {'items' : []})
8788
8789< Save and restore the tag stack: >
8790 let stack = gettagstack(1003)
8791 " do something else
8792 call settagstack(1003, stack)
8793 unlet stack
8794<
8795 Can also be used as a |method|, the base is passed as the
8796 second argument: >
8797 GetStack()->settagstack(winnr)
8798
8799setwinvar({winnr}, {varname}, {val}) *setwinvar()*
8800 Like |settabwinvar()| for the current tab page.
8801 Examples: >
8802 :call setwinvar(1, "&list", 0)
8803 :call setwinvar(2, "myvar", "foobar")
8804
8805< Can also be used as a |method|, the base is passed as the
8806 third argument: >
8807 GetValue()->setwinvar(winnr, name)
8808
8809sha256({string}) *sha256()*
8810 Returns a String with 64 hex characters, which is the SHA256
8811 checksum of {string}.
8812
8813 Can also be used as a |method|: >
8814 GetText()->sha256()
8815
8816< {only available when compiled with the |+cryptv| feature}
8817
8818shellescape({string} [, {special}]) *shellescape()*
8819 Escape {string} for use as a shell command argument.
8820 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +00008821 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008822 in single quotes and will double up all internal single
8823 quotes.
8824 On MS-Windows, when 'shellslash' is not set, it will enclose
8825 {string} in double quotes and double all double quotes within
8826 {string}.
8827 Otherwise it will enclose {string} in single quotes and
8828 replace all "'" with "'\''".
8829
8830 When the {special} argument is present and it's a non-zero
8831 Number or a non-empty String (|non-zero-arg|), then special
8832 items such as "!", "%", "#" and "<cword>" will be preceded by
8833 a backslash. This backslash will be removed again by the |:!|
8834 command.
8835
8836 The "!" character will be escaped (again with a |non-zero-arg|
8837 {special}) when 'shell' contains "csh" in the tail. That is
8838 because for csh and tcsh "!" is used for history replacement
8839 even when inside single quotes.
8840
8841 With a |non-zero-arg| {special} the <NL> character is also
8842 escaped. When 'shell' containing "csh" in the tail it's
8843 escaped a second time.
8844
8845 The "\" character will be escaped when 'shell' contains "fish"
8846 in the tail. That is because for fish "\" is used as an escape
8847 character inside single quotes.
8848
8849 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008850 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008851< This results in a directory listing for the file under the
8852 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008853 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008854< See also |::S|.
8855
8856 Can also be used as a |method|: >
8857 GetCommand()->shellescape()
8858
8859shiftwidth([{col}]) *shiftwidth()*
8860 Returns the effective value of 'shiftwidth'. This is the
8861 'shiftwidth' value unless it is zero, in which case it is the
8862 'tabstop' value. This function was introduced with patch
8863 7.3.694 in 2012, everybody should have it by now (however it
8864 did not allow for the optional {col} argument until 8.1.542).
8865
8866 When there is one argument {col} this is used as column number
8867 for which to return the 'shiftwidth' value. This matters for the
8868 'vartabstop' feature. If the 'vartabstop' setting is enabled and
8869 no {col} argument is given, column 1 will be assumed.
8870
8871 Can also be used as a |method|: >
8872 GetColumn()->shiftwidth()
8873
8874sign_ functions are documented here: |sign-functions-details|
8875
8876
8877simplify({filename}) *simplify()*
8878 Simplify the file name as much as possible without changing
8879 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
8880 Unix) are not resolved. If the first path component in
8881 {filename} designates the current directory, this will be
8882 valid for the result as well. A trailing path separator is
8883 not removed either. On Unix "//path" is unchanged, but
8884 "///path" is simplified to "/path" (this follows the Posix
8885 standard).
8886 Example: >
8887 simplify("./dir/.././/file/") == "./file/"
8888< Note: The combination "dir/.." is only removed if "dir" is
8889 a searchable directory or does not exist. On Unix, it is also
8890 removed when "dir" is a symbolic link within the same
8891 directory. In order to resolve all the involved symbolic
8892 links before simplifying the path name, use |resolve()|.
8893
8894 Can also be used as a |method|: >
8895 GetName()->simplify()
8896
8897sin({expr}) *sin()*
8898 Return the sine of {expr}, measured in radians, as a |Float|.
8899 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008900 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008901 Examples: >
8902 :echo sin(100)
8903< -0.506366 >
8904 :echo sin(-4.01)
8905< 0.763301
8906
8907 Can also be used as a |method|: >
8908 Compute()->sin()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008909
8910
8911sinh({expr}) *sinh()*
8912 Return the hyperbolic sine of {expr} as a |Float| in the range
8913 [-inf, inf].
8914 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008915 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008916 Examples: >
8917 :echo sinh(0.5)
8918< 0.521095 >
8919 :echo sinh(-0.9)
8920< -1.026517
8921
8922 Can also be used as a |method|: >
8923 Compute()->sinh()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008924
8925
8926slice({expr}, {start} [, {end}]) *slice()*
8927 Similar to using a |slice| "expr[start : end]", but "end" is
8928 used exclusive. And for a string the indexes are used as
8929 character indexes instead of byte indexes, like in
8930 |vim9script|. Also, composing characters are not counted.
8931 When {end} is omitted the slice continues to the last item.
8932 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008933 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008934
8935 Can also be used as a |method|: >
8936 GetList()->slice(offset)
8937
8938
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008939sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008940 Sort the items in {list} in-place. Returns {list}.
8941
8942 If you want a list to remain unmodified make a copy first: >
8943 :let sortedlist = sort(copy(mylist))
8944
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01008945< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008946 string representation of each item to sort on. Numbers sort
8947 after Strings, |Lists| after Numbers. For sorting text in the
8948 current buffer use |:sort|.
8949
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008950 When {how} is given and it is 'i' then case is ignored.
8951 In legacy script, for backwards compatibility, the value one
8952 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008953
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008954 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008955 locale is used for ordering. Implementation details: strcoll()
8956 is used to compare strings. See |:language| check or set the
8957 collation locale. |v:collate| can also be used to check the
8958 current locale. Sorting using the locale typically ignores
8959 case. Example: >
8960 " ö is sorted similarly to o with English locale.
8961 :language collate en_US.UTF8
8962 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8963< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
8964>
8965 " ö is sorted after z with Swedish locale.
8966 :language collate sv_SE.UTF8
8967 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8968< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
8969 This does not work properly on Mac.
8970
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008971 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008972 sorted numerical (Implementation detail: this uses the
Bram Moolenaarbe19d782023-03-09 22:06:49 +00008973 strtod() function to parse numbers. Strings, Lists, Dicts and
8974 Funcrefs will be considered as being 0). Note that this won't
8975 sort a list of strings with numbers!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008976
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008977 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008978 sorted numerical. This is like 'n' but a string containing
8979 digits will be used as the number they represent.
8980
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008981 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008982 sorted numerical. All values must be a Number or a Float.
8983
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008984 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008985 is called to compare items. The function is invoked with two
8986 items as argument and must return zero if they are equal, 1 or
8987 bigger if the first one sorts after the second one, -1 or
8988 smaller if the first one sorts before the second one.
8989
8990 {dict} is for functions with the "dict" attribute. It will be
8991 used to set the local variable "self". |Dictionary-function|
8992
8993 The sort is stable, items which compare equal (as number or as
8994 string) will keep their relative position. E.g., when sorting
8995 on numbers, text strings will sort next to each other, in the
8996 same order as they were originally.
8997
8998 Can also be used as a |method|: >
8999 mylist->sort()
9000
9001< Also see |uniq()|.
9002
9003 Example: >
9004 func MyCompare(i1, i2)
9005 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
9006 endfunc
9007 eval mylist->sort("MyCompare")
9008< A shorter compare version for this specific simple case, which
9009 ignores overflow: >
9010 func MyCompare(i1, i2)
9011 return a:i1 - a:i2
9012 endfunc
9013< For a simple expression you can use a lambda: >
9014 eval mylist->sort({i1, i2 -> i1 - i2})
9015<
9016sound_clear() *sound_clear()*
9017 Stop playing all sounds.
9018
9019 On some Linux systems you may need the libcanberra-pulse
9020 package, otherwise sound may not stop.
9021
9022 {only available when compiled with the |+sound| feature}
9023
9024 *sound_playevent()*
9025sound_playevent({name} [, {callback}])
9026 Play a sound identified by {name}. Which event names are
9027 supported depends on the system. Often the XDG sound names
9028 are used. On Ubuntu they may be found in
9029 /usr/share/sounds/freedesktop/stereo. Example: >
9030 call sound_playevent('bell')
9031< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
9032 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
9033 SystemStart, SystemWelcome, etc.
Yee Cheng Chin4314e4f2022-10-08 13:50:05 +01009034 On macOS, {name} refers to files located in
9035 /System/Library/Sounds (e.g. "Tink"). It will also work for
9036 custom installed sounds in folders like ~/Library/Sounds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009037
9038 When {callback} is specified it is invoked when the sound is
9039 finished. The first argument is the sound ID, the second
9040 argument is the status:
9041 0 sound was played to the end
9042 1 sound was interrupted
9043 2 error occurred after sound started
9044 Example: >
9045 func Callback(id, status)
9046 echomsg "sound " .. a:id .. " finished with " .. a:status
9047 endfunc
9048 call sound_playevent('bell', 'Callback')
9049
9050< MS-Windows: {callback} doesn't work for this function.
9051
9052 Returns the sound ID, which can be passed to `sound_stop()`.
9053 Returns zero if the sound could not be played.
9054
9055 Can also be used as a |method|: >
9056 GetSoundName()->sound_playevent()
9057
9058< {only available when compiled with the |+sound| feature}
9059
9060 *sound_playfile()*
9061sound_playfile({path} [, {callback}])
9062 Like `sound_playevent()` but play sound file {path}. {path}
9063 must be a full path. On Ubuntu you may find files to play
9064 with this command: >
9065 :!find /usr/share/sounds -type f | grep -v index.theme
9066
9067< Can also be used as a |method|: >
9068 GetSoundPath()->sound_playfile()
9069
Bram Moolenaar1588bc82022-03-08 21:35:07 +00009070< {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009071
9072
9073sound_stop({id}) *sound_stop()*
9074 Stop playing sound {id}. {id} must be previously returned by
9075 `sound_playevent()` or `sound_playfile()`.
9076
9077 On some Linux systems you may need the libcanberra-pulse
9078 package, otherwise sound may not stop.
9079
9080 On MS-Windows, this does not work for event sound started by
9081 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
9082
9083 Can also be used as a |method|: >
9084 soundid->sound_stop()
9085
9086< {only available when compiled with the |+sound| feature}
9087
9088 *soundfold()*
9089soundfold({word})
9090 Return the sound-folded equivalent of {word}. Uses the first
9091 language in 'spelllang' for the current window that supports
9092 soundfolding. 'spell' must be set. When no sound folding is
9093 possible the {word} is returned unmodified.
9094 This can be used for making spelling suggestions. Note that
9095 the method can be quite slow.
9096
9097 Can also be used as a |method|: >
9098 GetWord()->soundfold()
9099<
9100 *spellbadword()*
9101spellbadword([{sentence}])
9102 Without argument: The result is the badly spelled word under
9103 or after the cursor. The cursor is moved to the start of the
9104 bad word. When no bad word is found in the cursor line the
9105 result is an empty string and the cursor doesn't move.
9106
9107 With argument: The result is the first word in {sentence} that
9108 is badly spelled. If there are no spelling mistakes the
9109 result is an empty string.
9110
9111 The return value is a list with two items:
9112 - The badly spelled word or an empty string.
9113 - The type of the spelling error:
9114 "bad" spelling mistake
9115 "rare" rare word
9116 "local" word only valid in another region
9117 "caps" word should start with Capital
9118 Example: >
9119 echo spellbadword("the quik brown fox")
9120< ['quik', 'bad'] ~
9121
9122 The spelling information for the current window and the value
9123 of 'spelllang' are used.
9124
9125 Can also be used as a |method|: >
9126 GetText()->spellbadword()
9127<
9128 *spellsuggest()*
9129spellsuggest({word} [, {max} [, {capital}]])
9130 Return a |List| with spelling suggestions to replace {word}.
9131 When {max} is given up to this number of suggestions are
9132 returned. Otherwise up to 25 suggestions are returned.
9133
9134 When the {capital} argument is given and it's non-zero only
9135 suggestions with a leading capital will be given. Use this
9136 after a match with 'spellcapcheck'.
9137
9138 {word} can be a badly spelled word followed by other text.
9139 This allows for joining two words that were split. The
9140 suggestions also include the following text, thus you can
9141 replace a line.
9142
9143 {word} may also be a good word. Similar words will then be
9144 returned. {word} itself is not included in the suggestions,
9145 although it may appear capitalized.
9146
9147 The spelling information for the current window is used. The
9148 values of 'spelllang' and 'spellsuggest' are used.
9149
9150 Can also be used as a |method|: >
9151 GetWord()->spellsuggest()
9152
9153split({string} [, {pattern} [, {keepempty}]]) *split()*
9154 Make a |List| out of {string}. When {pattern} is omitted or
9155 empty each white-separated sequence of characters becomes an
9156 item.
9157 Otherwise the string is split where {pattern} matches,
9158 removing the matched characters. 'ignorecase' is not used
9159 here, add \c to ignore case. |/\c|
9160 When the first or last item is empty it is omitted, unless the
9161 {keepempty} argument is given and it's non-zero.
9162 Other empty items are kept when {pattern} matches at least one
9163 character or when {keepempty} is non-zero.
9164 Example: >
9165 :let words = split(getline('.'), '\W\+')
9166< To split a string in individual characters: >
9167 :for c in split(mystring, '\zs')
9168< If you want to keep the separator you can also use '\zs' at
9169 the end of the pattern: >
9170 :echo split('abc:def:ghi', ':\zs')
9171< ['abc:', 'def:', 'ghi'] ~
9172 Splitting a table where the first element can be empty: >
9173 :let items = split(line, ':', 1)
9174< The opposite function is |join()|.
9175
9176 Can also be used as a |method|: >
9177 GetString()->split()
9178
9179sqrt({expr}) *sqrt()*
9180 Return the non-negative square root of Float {expr} as a
9181 |Float|.
9182 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009183 is negative the result is NaN (Not a Number). Returns 0.0 if
9184 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009185 Examples: >
9186 :echo sqrt(100)
9187< 10.0 >
9188 :echo sqrt(-4.01)
9189< nan
9190 "nan" may be different, it depends on system libraries.
9191
9192 Can also be used as a |method|: >
9193 Compute()->sqrt()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009194
9195
9196srand([{expr}]) *srand()*
9197 Initialize seed used by |rand()|:
9198 - If {expr} is not given, seed values are initialized by
9199 reading from /dev/urandom, if possible, or using time(NULL)
9200 a.k.a. epoch time otherwise; this only has second accuracy.
9201 - If {expr} is given it must be a Number. It is used to
9202 initialize the seed values. This is useful for testing or
9203 when a predictable sequence is intended.
9204
9205 Examples: >
9206 :let seed = srand()
9207 :let seed = srand(userinput)
9208 :echo rand(seed)
9209
9210state([{what}]) *state()*
9211 Return a string which contains characters indicating the
9212 current state. Mostly useful in callbacks that want to do
9213 work that may not always be safe. Roughly this works like:
9214 - callback uses state() to check if work is safe to do.
9215 Yes: then do it right away.
9216 No: add to work queue and add a |SafeState| and/or
9217 |SafeStateAgain| autocommand (|SafeState| triggers at
9218 toplevel, |SafeStateAgain| triggers after handling
9219 messages and callbacks).
9220 - When SafeState or SafeStateAgain is triggered and executes
9221 your autocommand, check with `state()` if the work can be
9222 done now, and if yes remove it from the queue and execute.
9223 Remove the autocommand if the queue is now empty.
9224 Also see |mode()|.
9225
9226 When {what} is given only characters in this string will be
9227 added. E.g, this checks if the screen has scrolled: >
9228 if state('s') == ''
9229 " screen has not scrolled
9230<
9231 These characters indicate the state, generally indicating that
9232 something is busy:
9233 m halfway a mapping, :normal command, feedkeys() or
9234 stuffed command
9235 o operator pending, e.g. after |d|
9236 a Insert mode autocomplete active
9237 x executing an autocommand
9238 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
9239 ch_readraw() when reading json
9240 S not triggering SafeState or SafeStateAgain, e.g. after
9241 |f| or a count
9242 c callback invoked, including timer (repeats for
9243 recursiveness up to "ccc")
9244 s screen has scrolled for messages
9245
9246str2float({string} [, {quoted}]) *str2float()*
9247 Convert String {string} to a Float. This mostly works the
9248 same as when using a floating point number in an expression,
9249 see |floating-point-format|. But it's a bit more permissive.
9250 E.g., "1e40" is accepted, while in an expression you need to
9251 write "1.0e40". The hexadecimal form "0x123" is also
9252 accepted, but not others, like binary or octal.
9253 When {quoted} is present and non-zero then embedded single
9254 quotes before the dot are ignored, thus "1'000.0" is a
9255 thousand.
9256 Text after the number is silently ignored.
9257 The decimal point is always '.', no matter what the locale is
9258 set to. A comma ends the number: "12,345.67" is converted to
9259 12.0. You can strip out thousands separators with
9260 |substitute()|: >
9261 let f = str2float(substitute(text, ',', '', 'g'))
9262<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009263 Returns 0.0 if the conversion fails.
9264
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009265 Can also be used as a |method|: >
9266 let f = text->substitute(',', '', 'g')->str2float()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009267
9268str2list({string} [, {utf8}]) *str2list()*
9269 Return a list containing the number values which represent
9270 each character in String {string}. Examples: >
9271 str2list(" ") returns [32]
9272 str2list("ABC") returns [65, 66, 67]
9273< |list2str()| does the opposite.
9274
9275 When {utf8} is omitted or zero, the current 'encoding' is used.
9276 When {utf8} is TRUE, always treat the String as UTF-8
9277 characters. With UTF-8 composing characters are handled
9278 properly: >
9279 str2list("á") returns [97, 769]
9280
9281< Can also be used as a |method|: >
9282 GetString()->str2list()
9283
9284
9285str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
9286 Convert string {string} to a number.
9287 {base} is the conversion base, it can be 2, 8, 10 or 16.
9288 When {quoted} is present and non-zero then embedded single
9289 quotes are ignored, thus "1'000'000" is a million.
9290
9291 When {base} is omitted base 10 is used. This also means that
9292 a leading zero doesn't cause octal conversion to be used, as
9293 with the default String to Number conversion. Example: >
9294 let nr = str2nr('0123')
9295<
9296 When {base} is 16 a leading "0x" or "0X" is ignored. With a
9297 different base the result will be zero. Similarly, when
9298 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
9299 {base} is 2 a leading "0b" or "0B" is ignored.
9300 Text after the number is silently ignored.
9301
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009302 Returns 0 if {string} is empty or on error.
9303
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009304 Can also be used as a |method|: >
9305 GetText()->str2nr()
9306
9307
9308strcharlen({string}) *strcharlen()*
9309 The result is a Number, which is the number of characters
9310 in String {string}. Composing characters are ignored.
9311 |strchars()| can count the number of characters, counting
9312 composing characters separately.
9313
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009314 Returns 0 if {string} is empty or on error.
9315
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009316 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
9317
9318 Can also be used as a |method|: >
9319 GetText()->strcharlen()
9320
9321
9322strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
9323 Like |strpart()| but using character index and length instead
9324 of byte index and length.
9325 When {skipcc} is omitted or zero, composing characters are
9326 counted separately.
9327 When {skipcc} set to 1, Composing characters are ignored,
9328 similar to |slice()|.
9329 When a character index is used where a character does not
9330 exist it is omitted and counted as one character. For
9331 example: >
9332 strcharpart('abc', -1, 2)
9333< results in 'a'.
9334
Bram Moolenaard592deb2022-06-17 15:42:40 +01009335 Returns an empty string on error.
9336
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009337 Can also be used as a |method|: >
9338 GetText()->strcharpart(5)
9339
9340
9341strchars({string} [, {skipcc}]) *strchars()*
9342 The result is a Number, which is the number of characters
9343 in String {string}.
9344 When {skipcc} is omitted or zero, composing characters are
9345 counted separately.
9346 When {skipcc} set to 1, Composing characters are ignored.
9347 |strcharlen()| always does this.
9348
Bram Moolenaard592deb2022-06-17 15:42:40 +01009349 Returns zero on error.
9350
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009351 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
9352
9353 {skipcc} is only available after 7.4.755. For backward
9354 compatibility, you can define a wrapper function: >
9355 if has("patch-7.4.755")
9356 function s:strchars(str, skipcc)
9357 return strchars(a:str, a:skipcc)
9358 endfunction
9359 else
9360 function s:strchars(str, skipcc)
9361 if a:skipcc
9362 return strlen(substitute(a:str, ".", "x", "g"))
9363 else
9364 return strchars(a:str)
9365 endif
9366 endfunction
9367 endif
9368<
9369 Can also be used as a |method|: >
9370 GetText()->strchars()
9371
9372strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
9373 The result is a Number, which is the number of display cells
9374 String {string} occupies on the screen when it starts at {col}
9375 (first column is zero). When {col} is omitted zero is used.
9376 Otherwise it is the screen column where to start. This
9377 matters for Tab characters.
9378 The option settings of the current window are used. This
9379 matters for anything that's displayed differently, such as
9380 'tabstop' and 'display'.
9381 When {string} contains characters with East Asian Width Class
9382 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009383 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009384 Also see |strlen()|, |strwidth()| and |strchars()|.
9385
9386 Can also be used as a |method|: >
9387 GetText()->strdisplaywidth()
9388
9389strftime({format} [, {time}]) *strftime()*
9390 The result is a String, which is a formatted date and time, as
9391 specified by the {format} string. The given {time} is used,
9392 or the current time if no time is given. The accepted
9393 {format} depends on your system, thus this is not portable!
9394 See the manual page of the C function strftime() for the
9395 format. The maximum length of the result is 80 characters.
9396 See also |localtime()|, |getftime()| and |strptime()|.
9397 The language can be changed with the |:language| command.
9398 Examples: >
9399 :echo strftime("%c") Sun Apr 27 11:49:23 1997
9400 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
9401 :echo strftime("%y%m%d %T") 970427 11:53:55
9402 :echo strftime("%H:%M") 11:55
9403 :echo strftime("%c", getftime("file.c"))
9404 Show mod time of file.c.
9405< Not available on all systems. To check use: >
9406 :if exists("*strftime")
9407
9408< Can also be used as a |method|: >
9409 GetFormat()->strftime()
9410
9411strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01009412 Get a Number corresponding to the character at {index} in
9413 {str}. This uses a zero-based character index, not a byte
9414 index. Composing characters are considered separate
9415 characters here. Use |nr2char()| to convert the Number to a
9416 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009417 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009418 Also see |strcharpart()| and |strchars()|.
9419
9420 Can also be used as a |method|: >
9421 GetText()->strgetchar(5)
9422
9423stridx({haystack}, {needle} [, {start}]) *stridx()*
9424 The result is a Number, which gives the byte index in
9425 {haystack} of the first occurrence of the String {needle}.
9426 If {start} is specified, the search starts at index {start}.
9427 This can be used to find a second match: >
9428 :let colon1 = stridx(line, ":")
9429 :let colon2 = stridx(line, ":", colon1 + 1)
9430< The search is done case-sensitive.
9431 For pattern searches use |match()|.
9432 -1 is returned if the {needle} does not occur in {haystack}.
9433 See also |strridx()|.
9434 Examples: >
9435 :echo stridx("An Example", "Example") 3
9436 :echo stridx("Starting point", "Start") 0
9437 :echo stridx("Starting point", "start") -1
9438< *strstr()* *strchr()*
9439 stridx() works similar to the C function strstr(). When used
9440 with a single character it works similar to strchr().
9441
9442 Can also be used as a |method|: >
9443 GetHaystack()->stridx(needle)
9444<
9445 *string()*
9446string({expr}) Return {expr} converted to a String. If {expr} is a Number,
9447 Float, String, Blob or a composition of them, then the result
9448 can be parsed back with |eval()|.
9449 {expr} type result ~
9450 String 'string' (single quotes are doubled)
9451 Number 123
9452 Float 123.123456 or 1.123456e8
9453 Funcref function('name')
9454 Blob 0z00112233.44556677.8899
9455 List [item, item]
9456 Dictionary {key: value, key: value}
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00009457 Class class SomeName
9458 Object object of SomeName {lnum: 1, col: 3}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009459
9460 When a |List| or |Dictionary| has a recursive reference it is
9461 replaced by "[...]" or "{...}". Using eval() on the result
9462 will then fail.
9463
9464 Can also be used as a |method|: >
9465 mylist->string()
9466
9467< Also see |strtrans()|.
9468
9469
9470strlen({string}) *strlen()*
9471 The result is a Number, which is the length of the String
9472 {string} in bytes.
9473 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009474 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009475 If you want to count the number of multibyte characters use
9476 |strchars()|.
9477 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
9478
9479 Can also be used as a |method|: >
9480 GetString()->strlen()
9481
9482strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
9483 The result is a String, which is part of {src}, starting from
9484 byte {start}, with the byte length {len}.
9485 When {chars} is present and TRUE then {len} is the number of
9486 characters positions (composing characters are not counted
9487 separately, thus "1" means one base character and any
9488 following composing characters).
9489 To count {start} as characters instead of bytes use
9490 |strcharpart()|.
9491
9492 When bytes are selected which do not exist, this doesn't
9493 result in an error, the bytes are simply omitted.
9494 If {len} is missing, the copy continues from {start} till the
9495 end of the {src}. >
9496 strpart("abcdefg", 3, 2) == "de"
9497 strpart("abcdefg", -2, 4) == "ab"
9498 strpart("abcdefg", 5, 4) == "fg"
9499 strpart("abcdefg", 3) == "defg"
9500
9501< Note: To get the first character, {start} must be 0. For
9502 example, to get the character under the cursor: >
9503 strpart(getline("."), col(".") - 1, 1, v:true)
9504<
Bram Moolenaard592deb2022-06-17 15:42:40 +01009505 Returns an empty string on error.
9506
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009507 Can also be used as a |method|: >
9508 GetText()->strpart(5)
9509
9510strptime({format}, {timestring}) *strptime()*
9511 The result is a Number, which is a unix timestamp representing
9512 the date and time in {timestring}, which is expected to match
9513 the format specified in {format}.
9514
9515 The accepted {format} depends on your system, thus this is not
9516 portable! See the manual page of the C function strptime()
9517 for the format. Especially avoid "%c". The value of $TZ also
9518 matters.
9519
9520 If the {timestring} cannot be parsed with {format} zero is
9521 returned. If you do not know the format of {timestring} you
9522 can try different {format} values until you get a non-zero
9523 result.
9524
9525 See also |strftime()|.
9526 Examples: >
9527 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
9528< 862156163 >
9529 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
9530< Sun Apr 27 11:53:55 1997 >
9531 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
9532< Sun Apr 27 12:53:55 1997
9533
9534 Can also be used as a |method|: >
9535 GetFormat()->strptime(timestring)
9536<
9537 Not available on all systems. To check use: >
9538 :if exists("*strptime")
9539
9540strridx({haystack}, {needle} [, {start}]) *strridx()*
9541 The result is a Number, which gives the byte index in
9542 {haystack} of the last occurrence of the String {needle}.
9543 When {start} is specified, matches beyond this index are
9544 ignored. This can be used to find a match before a previous
9545 match: >
9546 :let lastcomma = strridx(line, ",")
9547 :let comma2 = strridx(line, ",", lastcomma - 1)
9548< The search is done case-sensitive.
9549 For pattern searches use |match()|.
9550 -1 is returned if the {needle} does not occur in {haystack}.
9551 If the {needle} is empty the length of {haystack} is returned.
9552 See also |stridx()|. Examples: >
9553 :echo strridx("an angry armadillo", "an") 3
9554< *strrchr()*
9555 When used with a single character it works similar to the C
9556 function strrchr().
9557
9558 Can also be used as a |method|: >
9559 GetHaystack()->strridx(needle)
9560
9561strtrans({string}) *strtrans()*
9562 The result is a String, which is {string} with all unprintable
9563 characters translated into printable characters |'isprint'|.
9564 Like they are shown in a window. Example: >
9565 echo strtrans(@a)
9566< This displays a newline in register a as "^@" instead of
9567 starting a new line.
9568
Bram Moolenaard592deb2022-06-17 15:42:40 +01009569 Returns an empty string on error.
9570
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009571 Can also be used as a |method|: >
9572 GetString()->strtrans()
9573
Christian Brabandt67672ef2023-04-24 21:09:54 +01009574strutf16len({string} [, {countcc}]) *strutf16len()*
9575 The result is a Number, which is the number of UTF-16 code
9576 units in String {string} (after converting it to UTF-16).
9577
9578 When {countcc} is TRUE, composing characters are counted
9579 separately.
9580 When {countcc} is omitted or FALSE, composing characters are
9581 ignored.
9582
9583 Returns zero on error.
9584
9585 Also see |strlen()| and |strcharlen()|.
9586 Examples: >
9587 echo strutf16len('a') returns 1
9588 echo strutf16len('©') returns 1
9589 echo strutf16len('😊') returns 2
9590 echo strutf16len('ą́') returns 1
9591 echo strutf16len('ą́', v:true) returns 3
a5ob7r790f9a82023-09-25 06:05:47 +09009592<
Christian Brabandt67672ef2023-04-24 21:09:54 +01009593 Can also be used as a |method|: >
9594 GetText()->strutf16len()
9595<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009596strwidth({string}) *strwidth()*
9597 The result is a Number, which is the number of display cells
9598 String {string} occupies. A Tab character is counted as one
9599 cell, alternatively use |strdisplaywidth()|.
9600 When {string} contains characters with East Asian Width Class
9601 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009602 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009603 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
9604
9605 Can also be used as a |method|: >
9606 GetString()->strwidth()
9607
9608submatch({nr} [, {list}]) *submatch()* *E935*
9609 Only for an expression in a |:substitute| command or
9610 substitute() function.
9611 Returns the {nr}'th submatch of the matched text. When {nr}
9612 is 0 the whole matched text is returned.
9613 Note that a NL in the string can stand for a line break of a
9614 multi-line match or a NUL character in the text.
9615 Also see |sub-replace-expression|.
9616
9617 If {list} is present and non-zero then submatch() returns
9618 a list of strings, similar to |getline()| with two arguments.
9619 NL characters in the text represent NUL characters in the
9620 text.
9621 Only returns more than one item for |:substitute|, inside
9622 |substitute()| this list will always contain one or zero
9623 items, since there are no real line breaks.
9624
9625 When substitute() is used recursively only the submatches in
9626 the current (deepest) call can be obtained.
9627
Bram Moolenaard592deb2022-06-17 15:42:40 +01009628 Returns an empty string or list on error.
9629
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009630 Examples: >
9631 :s/\d\+/\=submatch(0) + 1/
9632 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
9633< This finds the first number in the line and adds one to it.
9634 A line break is included as a newline character.
9635
9636 Can also be used as a |method|: >
9637 GetNr()->submatch()
9638
9639substitute({string}, {pat}, {sub}, {flags}) *substitute()*
9640 The result is a String, which is a copy of {string}, in which
9641 the first match of {pat} is replaced with {sub}.
9642 When {flags} is "g", all matches of {pat} in {string} are
9643 replaced. Otherwise {flags} should be "".
9644
9645 This works like the ":substitute" command (without any flags).
9646 But the matching with {pat} is always done like the 'magic'
9647 option is set and 'cpoptions' is empty (to make scripts
9648 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
9649 if you want to ignore or match case and ignore 'ignorecase'.
9650 'smartcase' is not used. See |string-match| for how {pat} is
9651 used.
9652
9653 A "~" in {sub} is not replaced with the previous {sub}.
9654 Note that some codes in {sub} have a special meaning
9655 |sub-replace-special|. For example, to replace something with
9656 "\n" (two characters), use "\\\\n" or '\\n'.
9657
9658 When {pat} does not match in {string}, {string} is returned
9659 unmodified.
9660
9661 Example: >
9662 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
9663< This removes the last component of the 'path' option. >
9664 :echo substitute("testing", ".*", "\\U\\0", "")
9665< results in "TESTING".
9666
9667 When {sub} starts with "\=", the remainder is interpreted as
9668 an expression. See |sub-replace-expression|. Example: >
9669 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009670 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009671
9672< When {sub} is a Funcref that function is called, with one
9673 optional argument. Example: >
9674 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
9675< The optional argument is a list which contains the whole
9676 matched string and up to nine submatches, like what
9677 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009678 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009679
Bram Moolenaard592deb2022-06-17 15:42:40 +01009680< Returns an empty string on error.
9681
9682 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009683 GetString()->substitute(pat, sub, flags)
9684
Bram Moolenaarc216a7a2022-12-05 13:50:55 +00009685swapfilelist() *swapfilelist()*
9686 Returns a list of swap file names, like what "vim -r" shows.
9687 See the |-r| command argument. The 'directory' option is used
9688 for the directories to inspect. If you only want to get a
9689 list of swap files in the current directory then temporarily
9690 set 'directory' to a dot: >
9691 let save_dir = &directory
9692 let &directory = '.'
9693 let swapfiles = swapfilelist()
9694 let &directory = save_dir
9695
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009696swapinfo({fname}) *swapinfo()*
9697 The result is a dictionary, which holds information about the
9698 swapfile {fname}. The available fields are:
9699 version Vim version
9700 user user name
9701 host host name
9702 fname original file name
9703 pid PID of the Vim process that created the swap
9704 file
9705 mtime last modification time in seconds
9706 inode Optional: INODE number of the file
9707 dirty 1 if file was modified, 0 if not
9708 Note that "user" and "host" are truncated to at most 39 bytes.
9709 In case of failure an "error" item is added with the reason:
9710 Cannot open file: file not found or in accessible
9711 Cannot read file: cannot read first block
9712 Not a swap file: does not contain correct block ID
9713 Magic number mismatch: Info in first block is invalid
9714
9715 Can also be used as a |method|: >
9716 GetFilename()->swapinfo()
9717
9718swapname({buf}) *swapname()*
9719 The result is the swap file path of the buffer {expr}.
9720 For the use of {buf}, see |bufname()| above.
9721 If buffer {buf} is the current buffer, the result is equal to
9722 |:swapname| (unless there is no swap file).
9723 If buffer {buf} has no swap file, returns an empty string.
9724
9725 Can also be used as a |method|: >
9726 GetBufname()->swapname()
9727
9728synID({lnum}, {col}, {trans}) *synID()*
9729 The result is a Number, which is the syntax ID at the position
9730 {lnum} and {col} in the current window.
9731 The syntax ID can be used with |synIDattr()| and
9732 |synIDtrans()| to obtain syntax information about text.
9733
9734 {col} is 1 for the leftmost column, {lnum} is 1 for the first
9735 line. 'synmaxcol' applies, in a longer line zero is returned.
9736 Note that when the position is after the last character,
9737 that's where the cursor can be in Insert mode, synID() returns
9738 zero. {lnum} is used like with |getline()|.
9739
9740 When {trans} is |TRUE|, transparent items are reduced to the
9741 item that they reveal. This is useful when wanting to know
9742 the effective color. When {trans} is |FALSE|, the transparent
9743 item is returned. This is useful when wanting to know which
9744 syntax item is effective (e.g. inside parens).
9745 Warning: This function can be very slow. Best speed is
9746 obtained by going through the file in forward direction.
9747
Bram Moolenaard592deb2022-06-17 15:42:40 +01009748 Returns zero on error.
9749
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009750 Example (echoes the name of the syntax item under the cursor): >
9751 :echo synIDattr(synID(line("."), col("."), 1), "name")
9752<
9753
9754synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
9755 The result is a String, which is the {what} attribute of
9756 syntax ID {synID}. This can be used to obtain information
9757 about a syntax item.
9758 {mode} can be "gui", "cterm" or "term", to get the attributes
9759 for that mode. When {mode} is omitted, or an invalid value is
9760 used, the attributes for the currently active highlighting are
9761 used (GUI, cterm or term).
9762 Use synIDtrans() to follow linked highlight groups.
9763 {what} result
9764 "name" the name of the syntax item
9765 "fg" foreground color (GUI: color name used to set
9766 the color, cterm: color number as a string,
9767 term: empty string)
9768 "bg" background color (as with "fg")
9769 "font" font name (only available in the GUI)
9770 |highlight-font|
9771 "sp" special color for the GUI (as with "fg")
9772 |highlight-guisp|
9773 "ul" underline color for cterm: number as a string
9774 "fg#" like "fg", but for the GUI and the GUI is
9775 running the name in "#RRGGBB" form
9776 "bg#" like "fg#" for "bg"
9777 "sp#" like "fg#" for "sp"
9778 "bold" "1" if bold
9779 "italic" "1" if italic
9780 "reverse" "1" if reverse
9781 "inverse" "1" if inverse (= reverse)
9782 "standout" "1" if standout
9783 "underline" "1" if underlined
9784 "undercurl" "1" if undercurled
9785 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +01009786 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009787
Bram Moolenaard592deb2022-06-17 15:42:40 +01009788 Returns an empty string on error.
9789
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009790 Example (echoes the color of the syntax item under the
9791 cursor): >
9792 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
9793<
9794 Can also be used as a |method|: >
9795 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9796
9797
9798synIDtrans({synID}) *synIDtrans()*
9799 The result is a Number, which is the translated syntax ID of
9800 {synID}. This is the syntax group ID of what is being used to
9801 highlight the character. Highlight links given with
9802 ":highlight link" are followed.
9803
Bram Moolenaard592deb2022-06-17 15:42:40 +01009804 Returns zero on error.
9805
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009806 Can also be used as a |method|: >
9807 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9808
9809synconcealed({lnum}, {col}) *synconcealed()*
9810 The result is a |List| with currently three items:
9811 1. The first item in the list is 0 if the character at the
9812 position {lnum} and {col} is not part of a concealable
9813 region, 1 if it is. {lnum} is used like with |getline()|.
9814 2. The second item in the list is a string. If the first item
9815 is 1, the second item contains the text which will be
9816 displayed in place of the concealed text, depending on the
9817 current setting of 'conceallevel' and 'listchars'.
9818 3. The third and final item in the list is a number
9819 representing the specific syntax region matched in the
9820 line. When the character is not concealed the value is
9821 zero. This allows detection of the beginning of a new
9822 concealable region if there are two consecutive regions
9823 with the same replacement character. For an example, if
9824 the text is "123456" and both "23" and "45" are concealed
9825 and replaced by the character "X", then:
9826 call returns ~
9827 synconcealed(lnum, 1) [0, '', 0]
9828 synconcealed(lnum, 2) [1, 'X', 1]
9829 synconcealed(lnum, 3) [1, 'X', 1]
9830 synconcealed(lnum, 4) [1, 'X', 2]
9831 synconcealed(lnum, 5) [1, 'X', 2]
9832 synconcealed(lnum, 6) [0, '', 0]
9833
9834
9835synstack({lnum}, {col}) *synstack()*
9836 Return a |List|, which is the stack of syntax items at the
9837 position {lnum} and {col} in the current window. {lnum} is
9838 used like with |getline()|. Each item in the List is an ID
9839 like what |synID()| returns.
9840 The first item in the List is the outer region, following are
9841 items contained in that one. The last one is what |synID()|
9842 returns, unless not the whole item is highlighted or it is a
9843 transparent item.
9844 This function is useful for debugging a syntax file.
9845 Example that shows the syntax stack under the cursor: >
9846 for id in synstack(line("."), col("."))
9847 echo synIDattr(id, "name")
9848 endfor
9849< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +01009850 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009851 character in a line and the first column in an empty line are
9852 valid positions.
9853
9854system({expr} [, {input}]) *system()* *E677*
9855 Get the output of the shell command {expr} as a |String|. See
9856 |systemlist()| to get the output as a |List|.
9857
9858 When {input} is given and is a |String| this string is written
9859 to a file and passed as stdin to the command. The string is
9860 written as-is, you need to take care of using the correct line
9861 separators yourself.
9862 If {input} is given and is a |List| it is written to the file
9863 in a way |writefile()| does with {binary} set to "b" (i.e.
9864 with a newline between each list item with newlines inside
9865 list items converted to NULs).
9866 When {input} is given and is a number that is a valid id for
9867 an existing buffer then the content of the buffer is written
9868 to the file line by line, each line terminated by a NL and
9869 NULs characters where the text has a NL.
9870
9871 Pipes are not used, the 'shelltemp' option is not used.
9872
9873 When prepended by |:silent| the terminal will not be set to
9874 cooked mode. This is meant to be used for commands that do
9875 not need the user to type. It avoids stray characters showing
9876 up on the screen which require |CTRL-L| to remove. >
9877 :silent let f = system('ls *.vim')
9878<
9879 Note: Use |shellescape()| or |::S| with |expand()| or
9880 |fnamemodify()| to escape special characters in a command
9881 argument. Newlines in {expr} may cause the command to fail.
9882 The characters in 'shellquote' and 'shellxquote' may also
9883 cause trouble.
9884 This is not to be used for interactive commands.
9885
9886 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009887 :let files = system('ls ' .. shellescape(expand('%:h')))
9888 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009889
9890< To make the result more system-independent, the shell output
9891 is filtered to replace <CR> with <NL> for Macintosh, and
9892 <CR><NL> with <NL> for DOS-like systems.
9893 To avoid the string being truncated at a NUL, all NUL
9894 characters are replaced with SOH (0x01).
9895
9896 The command executed is constructed using several options:
9897 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
9898 ({tmp} is an automatically generated file name).
9899 For Unix, braces are put around {expr} to allow for
9900 concatenated commands.
9901
9902 The command will be executed in "cooked" mode, so that a
9903 CTRL-C will interrupt the command (on Unix at least).
9904
9905 The resulting error code can be found in |v:shell_error|.
9906 This function will fail in |restricted-mode|.
9907
9908 Note that any wrong value in the options mentioned above may
9909 make the function fail. It has also been reported to fail
9910 when using a security agent application.
9911 Unlike ":!cmd" there is no automatic check for changed files.
9912 Use |:checktime| to force a check.
9913
9914 Can also be used as a |method|: >
9915 :echo GetCmd()->system()
9916
9917
9918systemlist({expr} [, {input}]) *systemlist()*
9919 Same as |system()|, but returns a |List| with lines (parts of
9920 output separated by NL) with NULs transformed into NLs. Output
9921 is the same as |readfile()| will output with {binary} argument
9922 set to "b", except that there is no extra empty item when the
9923 result ends in a NL.
9924 Note that on MS-Windows you may get trailing CR characters.
9925
9926 To see the difference between "echo hello" and "echo -n hello"
9927 use |system()| and |split()|: >
9928 echo system('echo hello')->split('\n', 1)
9929<
9930 Returns an empty string on error.
9931
9932 Can also be used as a |method|: >
9933 :echo GetCmd()->systemlist()
9934
9935
9936tabpagebuflist([{arg}]) *tabpagebuflist()*
9937 The result is a |List|, where each item is the number of the
9938 buffer associated with each window in the current tab page.
9939 {arg} specifies the number of the tab page to be used. When
9940 omitted the current tab page is used.
9941 When {arg} is invalid the number zero is returned.
9942 To get a list of all buffers in all tabs use this: >
9943 let buflist = []
9944 for i in range(tabpagenr('$'))
9945 call extend(buflist, tabpagebuflist(i + 1))
9946 endfor
9947< Note that a buffer may appear in more than one window.
9948
9949 Can also be used as a |method|: >
9950 GetTabpage()->tabpagebuflist()
9951
9952tabpagenr([{arg}]) *tabpagenr()*
9953 The result is a Number, which is the number of the current
9954 tab page. The first tab page has number 1.
9955
9956 The optional argument {arg} supports the following values:
9957 $ the number of the last tab page (the tab page
9958 count).
9959 # the number of the last accessed tab page
9960 (where |g<Tab>| goes to). if there is no
9961 previous tab page 0 is returned.
9962 The number can be used with the |:tab| command.
9963
Bram Moolenaard592deb2022-06-17 15:42:40 +01009964 Returns zero on error.
9965
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009966
9967tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
9968 Like |winnr()| but for tab page {tabarg}.
9969 {tabarg} specifies the number of tab page to be used.
9970 {arg} is used like with |winnr()|:
9971 - When omitted the current window number is returned. This is
9972 the window which will be used when going to this tab page.
9973 - When "$" the number of windows is returned.
9974 - When "#" the previous window nr is returned.
9975 Useful examples: >
9976 tabpagewinnr(1) " current window of tab page 1
9977 tabpagewinnr(4, '$') " number of windows in tab page 4
9978< When {tabarg} is invalid zero is returned.
9979
9980 Can also be used as a |method|: >
9981 GetTabpage()->tabpagewinnr()
9982<
9983 *tagfiles()*
9984tagfiles() Returns a |List| with the file names used to search for tags
9985 for the current buffer. This is the 'tags' option expanded.
9986
9987
9988taglist({expr} [, {filename}]) *taglist()*
9989 Returns a |List| of tags matching the regular expression {expr}.
9990
9991 If {filename} is passed it is used to prioritize the results
9992 in the same way that |:tselect| does. See |tag-priority|.
9993 {filename} should be the full path of the file.
9994
9995 Each list item is a dictionary with at least the following
9996 entries:
9997 name Name of the tag.
9998 filename Name of the file where the tag is
9999 defined. It is either relative to the
10000 current directory or a full path.
10001 cmd Ex command used to locate the tag in
10002 the file.
10003 kind Type of the tag. The value for this
10004 entry depends on the language specific
10005 kind values. Only available when
10006 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +000010007 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010008 static A file specific tag. Refer to
10009 |static-tag| for more information.
10010 More entries may be present, depending on the content of the
10011 tags file: access, implementation, inherits and signature.
10012 Refer to the ctags documentation for information about these
10013 fields. For C code the fields "struct", "class" and "enum"
10014 may appear, they give the name of the entity the tag is
10015 contained in.
10016
10017 The ex-command "cmd" can be either an ex search pattern, a
10018 line number or a line number followed by a byte number.
10019
10020 If there are no matching tags, then an empty list is returned.
10021
10022 To get an exact tag match, the anchors '^' and '$' should be
10023 used in {expr}. This also make the function work faster.
10024 Refer to |tag-regexp| for more information about the tag
10025 search regular expression pattern.
10026
10027 Refer to |'tags'| for information about how the tags file is
10028 located by Vim. Refer to |tags-file-format| for the format of
10029 the tags file generated by the different ctags tools.
10030
10031 Can also be used as a |method|: >
10032 GetTagpattern()->taglist()
10033
10034tan({expr}) *tan()*
10035 Return the tangent of {expr}, measured in radians, as a |Float|
10036 in the range [-inf, inf].
10037 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010038 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010039 Examples: >
10040 :echo tan(10)
10041< 0.648361 >
10042 :echo tan(-4.01)
10043< -1.181502
10044
10045 Can also be used as a |method|: >
10046 Compute()->tan()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010047
10048
10049tanh({expr}) *tanh()*
10050 Return the hyperbolic tangent of {expr} as a |Float| in the
10051 range [-1, 1].
10052 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010053 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010054 Examples: >
10055 :echo tanh(0.5)
10056< 0.462117 >
10057 :echo tanh(-1)
10058< -0.761594
10059
10060 Can also be used as a |method|: >
10061 Compute()->tanh()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010062
10063
10064tempname() *tempname()* *temp-file-name*
10065 The result is a String, which is the name of a file that
10066 doesn't exist. It can be used for a temporary file. The name
10067 is different for at least 26 consecutive calls. Example: >
10068 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010069 :exe "redir > " .. tmpfile
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010070< For Unix, the file will be in a private directory |tempfile|.
10071 For MS-Windows forward slashes are used when the 'shellslash'
10072 option is set, or when 'shellcmdflag' starts with '-' and
10073 'shell' does not contain powershell or pwsh.
10074
10075
10076term_ functions are documented here: |terminal-function-details|
10077
10078
10079terminalprops() *terminalprops()*
10080 Returns a |Dictionary| with properties of the terminal that Vim
10081 detected from the response to |t_RV| request. See
10082 |v:termresponse| for the response itself. If |v:termresponse|
10083 is empty most values here will be 'u' for unknown.
10084 cursor_style whether sending |t_RS| works **
10085 cursor_blink_mode whether sending |t_RC| works **
10086 underline_rgb whether |t_8u| works **
10087 mouse mouse type supported
Bram Moolenaar4bc85f22022-10-21 14:17:24 +010010088 kitty whether Kitty terminal was detected
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010089
10090 ** value 'u' for unknown, 'y' for yes, 'n' for no
10091
10092 If the |+termresponse| feature is missing then the result is
10093 an empty dictionary.
10094
10095 If "cursor_style" is 'y' then |t_RS| will be sent to request the
10096 current cursor style.
10097 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
10098 request the cursor blink status.
10099 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
10100 is not empty, Vim will detect the working of sending |t_RS|
10101 and |t_RC| on startup.
10102
10103 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
10104 This avoids sending it to xterm, which would clear the colors.
10105
10106 For "mouse" the value 'u' is unknown
10107
10108 Also see:
10109 - 'ambiwidth' - detected by using |t_u7|.
10110 - |v:termstyleresp| and |v:termblinkresp| for the response to
10111 |t_RS| and |t_RC|.
10112
10113
10114test_ functions are documented here: |test-functions-details|
10115
10116
10117 *timer_info()*
10118timer_info([{id}])
10119 Return a list with information about timers.
10120 When {id} is given only information about this timer is
10121 returned. When timer {id} does not exist an empty list is
10122 returned.
10123 When {id} is omitted information about all timers is returned.
10124
10125 For each timer the information is stored in a |Dictionary| with
10126 these items:
10127 "id" the timer ID
10128 "time" time the timer was started with
10129 "remaining" time until the timer fires
10130 "repeat" number of times the timer will still fire;
10131 -1 means forever
10132 "callback" the callback
10133 "paused" 1 if the timer is paused, 0 otherwise
10134
10135 Can also be used as a |method|: >
10136 GetTimer()->timer_info()
10137
10138< {only available when compiled with the |+timers| feature}
10139
10140timer_pause({timer}, {paused}) *timer_pause()*
10141 Pause or unpause a timer. A paused timer does not invoke its
10142 callback when its time expires. Unpausing a timer may cause
10143 the callback to be invoked almost immediately if enough time
10144 has passed.
10145
10146 Pausing a timer is useful to avoid the callback to be called
10147 for a short time.
10148
10149 If {paused} evaluates to a non-zero Number or a non-empty
10150 String, then the timer is paused, otherwise it is unpaused.
10151 See |non-zero-arg|.
10152
10153 Can also be used as a |method|: >
10154 GetTimer()->timer_pause(1)
10155
10156< {only available when compiled with the |+timers| feature}
10157
10158 *timer_start()* *timer* *timers*
10159timer_start({time}, {callback} [, {options}])
10160 Create a timer and return the timer ID.
10161
10162 {time} is the waiting time in milliseconds. This is the
10163 minimum time before invoking the callback. When the system is
10164 busy or Vim is not waiting for input the time will be longer.
Bram Moolenaardd60c362023-02-27 15:49:53 +000010165 Zero can be used to execute the callback when Vim is back in
10166 the main loop.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010167
10168 {callback} is the function to call. It can be the name of a
10169 function or a |Funcref|. It is called with one argument, which
10170 is the timer ID. The callback is only invoked when Vim is
10171 waiting for input.
10172 If you want to show a message look at |popup_notification()|
10173 to avoid interfering with what the user is doing.
10174
10175 {options} is a dictionary. Supported entries:
10176 "repeat" Number of times to repeat calling the
10177 callback. -1 means forever. When not present
10178 the callback will be called once.
10179 If the timer causes an error three times in a
10180 row the repeat is cancelled. This avoids that
10181 Vim becomes unusable because of all the error
10182 messages.
10183
Bram Moolenaard592deb2022-06-17 15:42:40 +010010184 Returns -1 on error.
10185
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010186 Example: >
10187 func MyHandler(timer)
10188 echo 'Handler called'
10189 endfunc
10190 let timer = timer_start(500, 'MyHandler',
10191 \ {'repeat': 3})
10192< This will invoke MyHandler() three times at 500 msec
10193 intervals.
10194
10195 Can also be used as a |method|: >
10196 GetMsec()->timer_start(callback)
10197
10198< Not available in the |sandbox|.
10199 {only available when compiled with the |+timers| feature}
10200
10201timer_stop({timer}) *timer_stop()*
10202 Stop a timer. The timer callback will no longer be invoked.
10203 {timer} is an ID returned by timer_start(), thus it must be a
10204 Number. If {timer} does not exist there is no error.
10205
10206 Can also be used as a |method|: >
10207 GetTimer()->timer_stop()
10208
10209< {only available when compiled with the |+timers| feature}
10210
10211timer_stopall() *timer_stopall()*
10212 Stop all timers. The timer callbacks will no longer be
10213 invoked. Useful if a timer is misbehaving. If there are no
10214 timers there is no error.
10215
10216 {only available when compiled with the |+timers| feature}
10217
10218tolower({expr}) *tolower()*
10219 The result is a copy of the String given, with all uppercase
10220 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010010221 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010222
10223 Can also be used as a |method|: >
10224 GetText()->tolower()
10225
10226toupper({expr}) *toupper()*
10227 The result is a copy of the String given, with all lowercase
10228 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010010229 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010230
10231 Can also be used as a |method|: >
10232 GetText()->toupper()
10233
10234tr({src}, {fromstr}, {tostr}) *tr()*
10235 The result is a copy of the {src} string with all characters
10236 which appear in {fromstr} replaced by the character in that
10237 position in the {tostr} string. Thus the first character in
10238 {fromstr} is translated into the first character in {tostr}
10239 and so on. Exactly like the unix "tr" command.
10240 This code also deals with multibyte characters properly.
10241
Bram Moolenaard592deb2022-06-17 15:42:40 +010010242 Returns an empty string on error.
10243
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010244 Examples: >
10245 echo tr("hello there", "ht", "HT")
10246< returns "Hello THere" >
10247 echo tr("<blob>", "<>", "{}")
10248< returns "{blob}"
10249
10250 Can also be used as a |method|: >
10251 GetText()->tr(from, to)
10252
10253trim({text} [, {mask} [, {dir}]]) *trim()*
10254 Return {text} as a String where any character in {mask} is
10255 removed from the beginning and/or end of {text}.
10256
Illia Bobyr80799172023-10-17 18:00:50 +020010257 If {mask} is not given, or is an empty string, {mask} is all
10258 characters up to 0x20, which includes Tab, space, NL and CR,
10259 plus the non-breaking space character 0xa0.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010260
10261 The optional {dir} argument specifies where to remove the
10262 characters:
10263 0 remove from the beginning and end of {text}
10264 1 remove only at the beginning of {text}
10265 2 remove only at the end of {text}
10266 When omitted both ends are trimmed.
10267
10268 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010269 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010270
10271 Examples: >
10272 echo trim(" some text ")
10273< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010274 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010275< returns "RESERVE_TAIL" >
10276 echo trim("rm<Xrm<>X>rrm", "rm<>")
10277< returns "Xrm<>X" (characters in the middle are not removed) >
10278 echo trim(" vim ", " ", 2)
10279< returns " vim"
10280
10281 Can also be used as a |method|: >
10282 GetText()->trim()
10283
10284trunc({expr}) *trunc()*
10285 Return the largest integral value with magnitude less than or
10286 equal to {expr} as a |Float| (truncate towards zero).
10287 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010288 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010289 Examples: >
10290 echo trunc(1.456)
10291< 1.0 >
10292 echo trunc(-5.456)
10293< -5.0 >
10294 echo trunc(4.0)
10295< 4.0
10296
10297 Can also be used as a |method|: >
10298 Compute()->trunc()
10299<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010300 *type()*
10301type({expr}) The result is a Number representing the type of {expr}.
10302 Instead of using the number directly, it is better to use the
10303 v:t_ variable that has the value:
10304 Number: 0 |v:t_number|
10305 String: 1 |v:t_string|
10306 Funcref: 2 |v:t_func|
10307 List: 3 |v:t_list|
10308 Dictionary: 4 |v:t_dict|
10309 Float: 5 |v:t_float|
10310 Boolean: 6 |v:t_bool| (v:false and v:true)
10311 None: 7 |v:t_none| (v:null and v:none)
10312 Job: 8 |v:t_job|
10313 Channel: 9 |v:t_channel|
10314 Blob: 10 |v:t_blob|
h_east596a9f22023-11-21 21:24:23 +090010315 Class: 12 |v:t_class|
10316 Object: 13 |v:t_object|
Yegappan Lakshmanan2a71b542023-12-14 20:03:03 +010010317 Typealias: 14 |v:t_typealias|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010318 For backward compatibility, this method can be used: >
10319 :if type(myvar) == type(0)
10320 :if type(myvar) == type("")
10321 :if type(myvar) == type(function("tr"))
10322 :if type(myvar) == type([])
10323 :if type(myvar) == type({})
10324 :if type(myvar) == type(0.0)
10325 :if type(myvar) == type(v:false)
10326 :if type(myvar) == type(v:none)
10327< To check if the v:t_ variables exist use this: >
10328 :if exists('v:t_number')
10329
10330< Can also be used as a |method|: >
10331 mylist->type()
10332
10333
10334typename({expr}) *typename()*
10335 Return a string representation of the type of {expr}.
10336 Example: >
10337 echo typename([1, 2, 3])
Kota Kato66bb9ae2023-01-17 18:31:56 +000010338< list<number> ~
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010339
10340
10341undofile({name}) *undofile()*
10342 Return the name of the undo file that would be used for a file
10343 with name {name} when writing. This uses the 'undodir'
10344 option, finding directories that exist. It does not check if
10345 the undo file exists.
10346 {name} is always expanded to the full path, since that is what
10347 is used internally.
10348 If {name} is empty undofile() returns an empty string, since a
10349 buffer without a file name will not write an undo file.
10350 Useful in combination with |:wundo| and |:rundo|.
10351 When compiled without the |+persistent_undo| option this always
10352 returns an empty string.
10353
10354 Can also be used as a |method|: >
10355 GetFilename()->undofile()
10356
Devin J. Pohly5fee1112023-04-23 20:26:59 -050010357undotree([{buf}]) *undotree()*
10358 Return the current state of the undo tree for the current
10359 buffer, or for a specific buffer if {buf} is given. The
10360 result is a dictionary with the following items:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010361 "seq_last" The highest undo sequence number used.
10362 "seq_cur" The sequence number of the current position in
10363 the undo tree. This differs from "seq_last"
10364 when some changes were undone.
10365 "time_cur" Time last used for |:earlier| and related
10366 commands. Use |strftime()| to convert to
10367 something readable.
10368 "save_last" Number of the last file write. Zero when no
10369 write yet.
10370 "save_cur" Number of the current position in the undo
10371 tree.
10372 "synced" Non-zero when the last undo block was synced.
10373 This happens when waiting from input from the
10374 user. See |undo-blocks|.
10375 "entries" A list of dictionaries with information about
10376 undo blocks.
10377
10378 The first item in the "entries" list is the oldest undo item.
10379 Each List item is a |Dictionary| with these items:
10380 "seq" Undo sequence number. Same as what appears in
10381 |:undolist|.
10382 "time" Timestamp when the change happened. Use
10383 |strftime()| to convert to something readable.
10384 "newhead" Only appears in the item that is the last one
10385 that was added. This marks the last change
10386 and where further changes will be added.
10387 "curhead" Only appears in the item that is the last one
10388 that was undone. This marks the current
10389 position in the undo tree, the block that will
10390 be used by a redo command. When nothing was
10391 undone after the last change this item will
10392 not appear anywhere.
10393 "save" Only appears on the last block before a file
10394 write. The number is the write count. The
10395 first write has number 1, the last one the
10396 "save_last" mentioned above.
10397 "alt" Alternate entry. This is again a List of undo
10398 blocks. Each item may again have an "alt"
10399 item.
10400
10401uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
10402 Remove second and succeeding copies of repeated adjacent
10403 {list} items in-place. Returns {list}. If you want a list
10404 to remain unmodified make a copy first: >
10405 :let newlist = uniq(copy(mylist))
10406< The default compare function uses the string representation of
10407 each item. For the use of {func} and {dict} see |sort()|.
10408
Bram Moolenaard592deb2022-06-17 15:42:40 +010010409 Returns zero if {list} is not a |List|.
10410
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010411 Can also be used as a |method|: >
10412 mylist->uniq()
Christian Brabandt67672ef2023-04-24 21:09:54 +010010413<
10414 *utf16idx()*
10415utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010010416 Same as |charidx()| but returns the UTF-16 code unit index of
10417 the byte at {idx} in {string} (after converting it to UTF-16).
Christian Brabandt67672ef2023-04-24 21:09:54 +010010418
10419 When {charidx} is present and TRUE, {idx} is used as the
10420 character index in the String {string} instead of as the byte
10421 index.
Yegappan Lakshmanan95707032023-06-14 13:10:15 +010010422 An {idx} in the middle of a UTF-8 sequence is rounded
10423 downwards to the beginning of that sequence.
Christian Brabandt67672ef2023-04-24 21:09:54 +010010424
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010010425 Returns -1 if the arguments are invalid or if there are less
10426 than {idx} bytes in {string}. If there are exactly {idx} bytes
10427 the length of the string in UTF-16 code units is returned.
10428
Christian Brabandt67672ef2023-04-24 21:09:54 +010010429 See |byteidx()| and |byteidxcomp()| for getting the byte index
10430 from the UTF-16 index and |charidx()| for getting the
10431 character index from the UTF-16 index.
10432 Refer to |string-offset-encoding| for more information.
10433 Examples: >
10434 echo utf16idx('a😊😊', 3) returns 2
10435 echo utf16idx('a😊😊', 7) returns 4
10436 echo utf16idx('a😊😊', 1, 0, 1) returns 2
10437 echo utf16idx('a😊😊', 2, 0, 1) returns 4
10438 echo utf16idx('aą́c', 6) returns 2
10439 echo utf16idx('aą́c', 6, 1) returns 4
10440 echo utf16idx('a😊😊', 9) returns -1
10441<
10442 Can also be used as a |method|: >
10443 GetName()->utf16idx(idx)
10444
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010445
10446values({dict}) *values()*
10447 Return a |List| with all the values of {dict}. The |List| is
10448 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010449 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010450
10451 Can also be used as a |method|: >
10452 mydict->values()
10453
zeertzjq825cf812023-08-17 22:55:25 +020010454virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010455 The result is a Number, which is the screen column of the file
10456 position given with {expr}. That is, the last screen position
10457 occupied by the character at that position, when the screen
10458 would be of unlimited width. When there is a <Tab> at the
10459 position, the returned Number will be the column at the end of
10460 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
10461 set to 8, it returns 8. |conceal| is ignored.
10462 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010463
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010464 For the use of {expr} see |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010465
10466 When 'virtualedit' is used {expr} can be [lnum, col, off],
10467 where "off" is the offset in screen columns from the start of
10468 the character. E.g., a position within a <Tab> or after the
10469 last character. When "off" is omitted zero is used. When
10470 Virtual editing is active in the current mode, a position
10471 beyond the end of the line can be returned. Also see
10472 |'virtualedit'|
10473
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010474 The accepted positions are:
10475 . the cursor position
10476 $ the end of the cursor line (the result is the
10477 number of displayed characters in the cursor line
10478 plus one)
10479 'x position of mark x (if the mark is not set, 0 is
10480 returned)
10481 v In Visual mode: the start of the Visual area (the
10482 cursor is the end). When not in Visual mode
10483 returns the cursor position. Differs from |'<| in
10484 that it's updated right away.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010485
zeertzjq825cf812023-08-17 22:55:25 +020010486 If {list} is present and non-zero then virtcol() returns a
10487 List with the first and last screen position occupied by the
LemonBoy0f7a3e12022-05-26 12:10:37 +010010488 character.
10489
zeertzjq825cf812023-08-17 22:55:25 +020010490 With the optional {winid} argument the values are obtained for
10491 that window instead of the current window.
10492
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010493 Note that only marks in the current file can be used.
10494 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +010010495 " With text "foo^Lbar" and cursor on the "^L":
10496
10497 virtcol(".") " returns 5
10498 virtcol(".", 1) " returns [4, 5]
10499 virtcol("$") " returns 9
10500
10501 " With text " there", with 't at 'h':
10502
10503 virtcol("'t") " returns 6
zeertzjq825cf812023-08-17 22:55:25 +020010504< The first column is 1. 0 or [0, 0] is returned for an error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010505 A more advanced example that echoes the maximum length of
10506 all lines: >
10507 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
10508
10509< Can also be used as a |method|: >
10510 GetPos()->virtcol()
10511
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010512virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
10513 The result is a Number, which is the byte index of the
10514 character in window {winid} at buffer line {lnum} and virtual
10515 column {col}.
10516
zeertzjqb583eda2023-10-14 11:32:28 +020010517 If buffer line {lnum} is an empty line, 0 is returned.
10518
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010519 If {col} is greater than the last virtual column in line
10520 {lnum}, then the byte index of the character at the last
10521 virtual column is returned.
10522
Yegappan Lakshmananb209b862023-08-15 23:01:44 +020010523 For a multi-byte character, the column number of the first
10524 byte in the character is returned.
10525
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010526 The {winid} argument can be the window number or the
10527 |window-ID|. If this is zero, then the current window is used.
10528
10529 Returns -1 if the window {winid} doesn't exist or the buffer
10530 line {lnum} or virtual column {col} is invalid.
10531
10532 See also |screenpos()|, |virtcol()| and |col()|.
10533
10534 Can also be used as a |method|: >
10535 GetWinid()->virtcol2col(lnum, col)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010536
10537visualmode([{expr}]) *visualmode()*
10538 The result is a String, which describes the last Visual mode
10539 used in the current buffer. Initially it returns an empty
10540 string, but once Visual mode has been used, it returns "v",
10541 "V", or "<CTRL-V>" (a single CTRL-V character) for
10542 character-wise, line-wise, or block-wise Visual mode
10543 respectively.
10544 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010545 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010546< This enters the same Visual mode as before. It is also useful
10547 in scripts if you wish to act differently depending on the
10548 Visual mode that was used.
10549 If Visual mode is active, use |mode()| to get the Visual mode
10550 (e.g., in a |:vmap|).
10551 If {expr} is supplied and it evaluates to a non-zero Number or
10552 a non-empty String, then the Visual mode will be cleared and
10553 the old value is returned. See |non-zero-arg|.
10554
10555wildmenumode() *wildmenumode()*
10556 Returns |TRUE| when the wildmenu is active and |FALSE|
10557 otherwise. See 'wildmenu' and 'wildmode'.
10558 This can be used in mappings to handle the 'wildcharm' option
10559 gracefully. (Makes only sense with |mapmode-c| mappings).
10560
10561 For example to make <c-j> work like <down> in wildmode, use: >
10562 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
10563<
10564 (Note, this needs the 'wildcharm' option set appropriately).
10565
10566win_execute({id}, {command} [, {silent}]) *win_execute()*
10567 Like `execute()` but in the context of window {id}.
10568 The window will temporarily be made the current window,
10569 without triggering autocommands or changing directory. When
10570 executing {command} autocommands will be triggered, this may
Bram Moolenaarb7398fe2023-05-14 18:50:25 +010010571 have unexpected side effects. Use `:noautocmd` if needed.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010572 Example: >
10573 call win_execute(winid, 'set syntax=python')
10574< Doing the same with `setwinvar()` would not trigger
10575 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010576 *E994*
10577 Not all commands are allowed in popup windows.
10578 When window {id} does not exist then no error is given and
10579 an empty string is returned.
10580
10581 Can also be used as a |method|, the base is passed as the
10582 second argument: >
10583 GetCommand()->win_execute(winid)
10584
10585win_findbuf({bufnr}) *win_findbuf()*
10586 Returns a |List| with |window-ID|s for windows that contain
10587 buffer {bufnr}. When there is none the list is empty.
10588
10589 Can also be used as a |method|: >
10590 GetBufnr()->win_findbuf()
10591
10592win_getid([{win} [, {tab}]]) *win_getid()*
10593 Get the |window-ID| for the specified window.
10594 When {win} is missing use the current window.
10595 With {win} this is the window number. The top window has
10596 number 1.
10597 Without {tab} use the current tab, otherwise the tab with
10598 number {tab}. The first tab has number one.
10599 Return zero if the window cannot be found.
10600
10601 Can also be used as a |method|: >
10602 GetWinnr()->win_getid()
10603
10604
10605win_gettype([{nr}]) *win_gettype()*
10606 Return the type of the window:
10607 "autocmd" autocommand window. Temporary window
10608 used to execute autocommands.
10609 "command" command-line window |cmdwin|
10610 (empty) normal window
10611 "loclist" |location-list-window|
10612 "popup" popup window |popup|
10613 "preview" preview window |preview-window|
10614 "quickfix" |quickfix-window|
10615 "unknown" window {nr} not found
10616
10617 When {nr} is omitted return the type of the current window.
10618 When {nr} is given return the type of this window by number or
10619 |window-ID|.
10620
10621 Also see the 'buftype' option. When running a terminal in a
10622 popup window then 'buftype' is "terminal" and win_gettype()
10623 returns "popup".
10624
10625 Can also be used as a |method|: >
10626 GetWinid()->win_gettype()
10627<
10628win_gotoid({expr}) *win_gotoid()*
10629 Go to window with ID {expr}. This may also change the current
10630 tabpage.
10631 Return TRUE if successful, FALSE if the window cannot be found.
10632
10633 Can also be used as a |method|: >
10634 GetWinid()->win_gotoid()
10635
10636win_id2tabwin({expr}) *win_id2tabwin()*
10637 Return a list with the tab number and window number of window
10638 with ID {expr}: [tabnr, winnr].
10639 Return [0, 0] if the window cannot be found.
10640
10641 Can also be used as a |method|: >
10642 GetWinid()->win_id2tabwin()
10643
10644win_id2win({expr}) *win_id2win()*
10645 Return the window number of window with ID {expr}.
10646 Return 0 if the window cannot be found in the current tabpage.
10647
10648 Can also be used as a |method|: >
10649 GetWinid()->win_id2win()
10650
Daniel Steinbergee630312022-01-10 13:36:34 +000010651win_move_separator({nr}, {offset}) *win_move_separator()*
10652 Move window {nr}'s vertical separator (i.e., the right border)
10653 by {offset} columns, as if being dragged by the mouse. {nr}
10654 can be a window number or |window-ID|. A positive {offset}
10655 moves right and a negative {offset} moves left. Moving a
10656 window's vertical separator will change the width of the
10657 window and the width of other windows adjacent to the vertical
10658 separator. The magnitude of movement may be smaller than
10659 specified (e.g., as a consequence of maintaining
10660 'winminwidth'). Returns TRUE if the window can be found and
10661 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010662 This will fail for the rightmost window and a full-width
10663 window, since it has no separator on the right.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000010664 Only works for the current tab page. *E1308*
Daniel Steinbergee630312022-01-10 13:36:34 +000010665
10666 Can also be used as a |method|: >
10667 GetWinnr()->win_move_separator(offset)
10668
10669win_move_statusline({nr}, {offset}) *win_move_statusline()*
10670 Move window {nr}'s status line (i.e., the bottom border) by
10671 {offset} rows, as if being dragged by the mouse. {nr} can be a
10672 window number or |window-ID|. A positive {offset} moves down
10673 and a negative {offset} moves up. Moving a window's status
10674 line will change the height of the window and the height of
10675 other windows adjacent to the status line. The magnitude of
10676 movement may be smaller than specified (e.g., as a consequence
10677 of maintaining 'winminheight'). Returns TRUE if the window can
10678 be found and FALSE otherwise.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000010679 Only works for the current tab page.
Daniel Steinbergee630312022-01-10 13:36:34 +000010680
10681 Can also be used as a |method|: >
10682 GetWinnr()->win_move_statusline(offset)
10683
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010684win_screenpos({nr}) *win_screenpos()*
10685 Return the screen position of window {nr} as a list with two
10686 numbers: [row, col]. The first window always has position
10687 [1, 1], unless there is a tabline, then it is [2, 1].
10688 {nr} can be the window number or the |window-ID|. Use zero
10689 for the current window.
10690 Returns [0, 0] if the window cannot be found in the current
10691 tabpage.
10692
10693 Can also be used as a |method|: >
10694 GetWinid()->win_screenpos()
10695<
10696win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
10697 Move the window {nr} to a new split of the window {target}.
10698 This is similar to moving to {target}, creating a new window
10699 using |:split| but having the same contents as window {nr}, and
10700 then closing {nr}.
10701
10702 Both {nr} and {target} can be window numbers or |window-ID|s.
10703 Both must be in the current tab page.
10704
10705 Returns zero for success, non-zero for failure.
10706
10707 {options} is a |Dictionary| with the following optional entries:
10708 "vertical" When TRUE, the split is created vertically,
10709 like with |:vsplit|.
10710 "rightbelow" When TRUE, the split is made below or to the
10711 right (if vertical). When FALSE, it is done
10712 above or to the left (if vertical). When not
10713 present, the values of 'splitbelow' and
10714 'splitright' are used.
10715
10716 Can also be used as a |method|: >
10717 GetWinid()->win_splitmove(target)
10718<
10719
10720 *winbufnr()*
10721winbufnr({nr}) The result is a Number, which is the number of the buffer
10722 associated with window {nr}. {nr} can be the window number or
10723 the |window-ID|.
10724 When {nr} is zero, the number of the buffer in the current
10725 window is returned.
10726 When window {nr} doesn't exist, -1 is returned.
10727 Example: >
10728 :echo "The file in the current window is " . bufname(winbufnr(0))
10729<
10730 Can also be used as a |method|: >
10731 FindWindow()->winbufnr()->bufname()
10732<
10733 *wincol()*
10734wincol() The result is a Number, which is the virtual column of the
10735 cursor in the window. This is counting screen cells from the
10736 left side of the window. The leftmost column is one.
10737
10738 *windowsversion()*
10739windowsversion()
10740 The result is a String. For MS-Windows it indicates the OS
10741 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
10742 Windows XP is "5.1". For non-MS-Windows systems the result is
10743 an empty string.
10744
10745winheight({nr}) *winheight()*
10746 The result is a Number, which is the height of window {nr}.
10747 {nr} can be the window number or the |window-ID|.
10748 When {nr} is zero, the height of the current window is
10749 returned. When window {nr} doesn't exist, -1 is returned.
10750 An existing window always has a height of zero or more.
10751 This excludes any window toolbar line.
10752 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010753 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010754
10755< Can also be used as a |method|: >
10756 GetWinid()->winheight()
10757<
10758winlayout([{tabnr}]) *winlayout()*
10759 The result is a nested List containing the layout of windows
10760 in a tabpage.
10761
10762 Without {tabnr} use the current tabpage, otherwise the tabpage
10763 with number {tabnr}. If the tabpage {tabnr} is not found,
10764 returns an empty list.
10765
10766 For a leaf window, it returns:
10767 ['leaf', {winid}]
10768 For horizontally split windows, which form a column, it
10769 returns:
10770 ['col', [{nested list of windows}]]
10771 For vertically split windows, which form a row, it returns:
10772 ['row', [{nested list of windows}]]
10773
10774 Example: >
10775 " Only one window in the tab page
10776 :echo winlayout()
10777 ['leaf', 1000]
10778 " Two horizontally split windows
10779 :echo winlayout()
10780 ['col', [['leaf', 1000], ['leaf', 1001]]]
10781 " The second tab page, with three horizontally split
10782 " windows, with two vertically split windows in the
10783 " middle window
10784 :echo winlayout(2)
10785 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
10786 ['leaf', 1001]]], ['leaf', 1000]]]
10787<
10788 Can also be used as a |method|: >
10789 GetTabnr()->winlayout()
10790<
10791 *winline()*
10792winline() The result is a Number, which is the screen line of the cursor
10793 in the window. This is counting screen lines from the top of
10794 the window. The first line is one.
10795 If the cursor was moved the view on the file will be updated
10796 first, this may cause a scroll.
10797
10798 *winnr()*
10799winnr([{arg}]) The result is a Number, which is the number of the current
10800 window. The top window has number 1.
10801 Returns zero for a popup window.
10802
10803 The optional argument {arg} supports the following values:
10804 $ the number of the last window (the window
10805 count).
10806 # the number of the last accessed window (where
10807 |CTRL-W_p| goes to). If there is no previous
10808 window or it is in another tab page 0 is
10809 returned.
10810 {N}j the number of the Nth window below the
10811 current window (where |CTRL-W_j| goes to).
10812 {N}k the number of the Nth window above the current
10813 window (where |CTRL-W_k| goes to).
10814 {N}h the number of the Nth window left of the
10815 current window (where |CTRL-W_h| goes to).
10816 {N}l the number of the Nth window right of the
10817 current window (where |CTRL-W_l| goes to).
10818 The number can be used with |CTRL-W_w| and ":wincmd w"
10819 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010010820 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010821 Also see |tabpagewinnr()| and |win_getid()|.
10822 Examples: >
10823 let window_count = winnr('$')
10824 let prev_window = winnr('#')
10825 let wnum = winnr('3k')
10826
10827< Can also be used as a |method|: >
10828 GetWinval()->winnr()
10829<
10830 *winrestcmd()*
10831winrestcmd() Returns a sequence of |:resize| commands that should restore
10832 the current window sizes. Only works properly when no windows
10833 are opened or closed and the current window and tab page is
10834 unchanged.
10835 Example: >
10836 :let cmd = winrestcmd()
10837 :call MessWithWindowSizes()
10838 :exe cmd
10839<
10840 *winrestview()*
10841winrestview({dict})
10842 Uses the |Dictionary| returned by |winsaveview()| to restore
10843 the view of the current window.
10844 Note: The {dict} does not have to contain all values, that are
10845 returned by |winsaveview()|. If values are missing, those
10846 settings won't be restored. So you can use: >
10847 :call winrestview({'curswant': 4})
10848<
10849 This will only set the curswant value (the column the cursor
10850 wants to move on vertical movements) of the cursor to column 5
10851 (yes, that is 5), while all other settings will remain the
10852 same. This is useful, if you set the cursor position manually.
10853
10854 If you have changed the values the result is unpredictable.
10855 If the window size changed the result won't be the same.
10856
10857 Can also be used as a |method|: >
10858 GetView()->winrestview()
10859<
10860 *winsaveview()*
10861winsaveview() Returns a |Dictionary| that contains information to restore
10862 the view of the current window. Use |winrestview()| to
10863 restore the view.
10864 This is useful if you have a mapping that jumps around in the
10865 buffer and you want to go back to the original view.
10866 This does not save fold information. Use the 'foldenable'
10867 option to temporarily switch off folding, so that folds are
10868 not opened when moving around. This may have side effects.
10869 The return value includes:
10870 lnum cursor line number
10871 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000010872 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010873 returns)
10874 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000010875 curswant column for vertical movement (Note:
10876 the first column is zero, as opposed
10877 to what |getcurpos()| returns). After
10878 |$| command it will be a very large
10879 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010880 topline first line in the window
10881 topfill filler lines, only in diff mode
10882 leftcol first column displayed; only used when
10883 'wrap' is off
10884 skipcol columns skipped
10885 Note that no option values are saved.
10886
10887
10888winwidth({nr}) *winwidth()*
10889 The result is a Number, which is the width of window {nr}.
10890 {nr} can be the window number or the |window-ID|.
10891 When {nr} is zero, the width of the current window is
10892 returned. When window {nr} doesn't exist, -1 is returned.
10893 An existing window always has a width of zero or more.
10894 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010895 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010896 :if winwidth(0) <= 50
10897 : 50 wincmd |
10898 :endif
10899< For getting the terminal or screen size, see the 'columns'
10900 option.
10901
10902 Can also be used as a |method|: >
10903 GetWinid()->winwidth()
10904
10905
10906wordcount() *wordcount()*
10907 The result is a dictionary of byte/chars/word statistics for
10908 the current buffer. This is the same info as provided by
10909 |g_CTRL-G|
10910 The return value includes:
10911 bytes Number of bytes in the buffer
10912 chars Number of chars in the buffer
10913 words Number of words in the buffer
10914 cursor_bytes Number of bytes before cursor position
10915 (not in Visual mode)
10916 cursor_chars Number of chars before cursor position
10917 (not in Visual mode)
10918 cursor_words Number of words before cursor position
10919 (not in Visual mode)
10920 visual_bytes Number of bytes visually selected
10921 (only in Visual mode)
10922 visual_chars Number of chars visually selected
10923 (only in Visual mode)
10924 visual_words Number of words visually selected
10925 (only in Visual mode)
10926
10927
10928 *writefile()*
10929writefile({object}, {fname} [, {flags}])
10930 When {object} is a |List| write it to file {fname}. Each list
10931 item is separated with a NL. Each list item must be a String
10932 or Number.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010933 All NL characters are replaced with a NUL character.
10934 Inserting CR characters needs to be done before passing {list}
10935 to writefile().
Bram Moolenaar806a2732022-09-04 15:40:36 +010010936
10937 When {object} is a |Blob| write the bytes to file {fname}
10938 unmodified, also when binary mode is not specified.
10939
10940 {flags} must be a String. These characters are recognized:
10941
10942 'b' Binary mode is used: There will not be a NL after the
10943 last list item. An empty item at the end does cause the
10944 last line in the file to end in a NL.
10945
10946 'a' Append mode is used, lines are appended to the file: >
10947 :call writefile(["foo"], "event.log", "a")
10948 :call writefile(["bar"], "event.log", "a")
10949<
10950 'D' Delete the file when the current function ends. This
10951 works like: >
Bram Moolenaar938ae282023-02-20 20:44:55 +000010952 :defer delete({fname})
Bram Moolenaar806a2732022-09-04 15:40:36 +010010953< Fails when not in a function. Also see |:defer|.
10954
10955 's' fsync() is called after writing the file. This flushes
10956 the file to disk, if possible. This takes more time but
10957 avoids losing the file if the system crashes.
10958
10959 'S' fsync() is not called, even when 'fsync' is set.
10960
10961 When {flags} does not contain "S" or "s" then fsync() is
10962 called if the 'fsync' option is set.
10963
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010964 An existing file is overwritten, if possible.
Bram Moolenaar806a2732022-09-04 15:40:36 +010010965
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010966 When the write fails -1 is returned, otherwise 0. There is an
10967 error message if the file can't be created or when writing
10968 fails.
Bram Moolenaar806a2732022-09-04 15:40:36 +010010969
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010970 Also see |readfile()|.
10971 To copy a file byte for byte: >
10972 :let fl = readfile("foo", "b")
10973 :call writefile(fl, "foocopy", "b")
10974
10975< Can also be used as a |method|: >
10976 GetText()->writefile("thefile")
10977
10978
10979xor({expr}, {expr}) *xor()*
10980 Bitwise XOR on the two arguments. The arguments are converted
10981 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010982 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010983 Example: >
10984 :let bits = xor(bits, 0x80)
10985<
10986 Can also be used as a |method|: >
10987 :let bits = bits->xor(0x80)
10988<
10989
10990==============================================================================
109913. Feature list *feature-list*
10992
10993There are three types of features:
109941. Features that are only supported when they have been enabled when Vim
10995 was compiled |+feature-list|. Example: >
10996 :if has("cindent")
10997< *gui_running*
109982. Features that are only supported when certain conditions have been met.
10999 Example: >
11000 :if has("gui_running")
11001< *has-patch*
110023. Beyond a certain version or at a certain version and including a specific
11003 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
11004 later, or it is version 7.4 and patch 248 was included. Example: >
11005 :if has("patch-7.4.248")
11006< Note that it's possible for patch 248 to be omitted even though 249 is
11007 included. Only happens when cherry-picking patches.
11008 Note that this form only works for patch 7.4.237 and later, before that
11009 you need to check for the patch and the v:version. Example (checking
11010 version 6.2.148 or later): >
11011 :if v:version > 602 || (v:version == 602 && has("patch148"))
11012
11013Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
11014use: `if exists('+shellslash')`
11015
11016
11017acl Compiled with |ACL| support.
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010011018all_builtin_terms Compiled with all builtin terminals enabled. (always
11019 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011020amiga Amiga version of Vim.
11021arabic Compiled with Arabic support |Arabic|.
11022arp Compiled with ARP support (Amiga).
11023autocmd Compiled with autocommand support. (always true)
11024autochdir Compiled with support for 'autochdir'
11025autoservername Automatically enable |clientserver|
11026balloon_eval Compiled with |balloon-eval| support.
11027balloon_multiline GUI supports multiline balloons.
11028beos BeOS version of Vim.
11029browse Compiled with |:browse| support, and browse() will
11030 work.
11031browsefilter Compiled with support for |browsefilter|.
11032bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010011033builtin_terms Compiled with some builtin terminals. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011034byte_offset Compiled with support for 'o' in 'statusline'
11035channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011036cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011037clientserver Compiled with remote invocation support |clientserver|.
11038clipboard Compiled with 'clipboard' support.
11039clipboard_working Compiled with 'clipboard' support and it can be used.
11040cmdline_compl Compiled with |cmdline-completion| support.
11041cmdline_hist Compiled with |cmdline-history| support.
11042cmdline_info Compiled with 'showcmd' and 'ruler' support.
11043comments Compiled with |'comments'| support.
11044compatible Compiled to be very Vi compatible.
11045conpty Platform where |ConPTY| can be used.
11046cryptv Compiled with encryption support |encryption|.
11047cscope Compiled with |cscope| support.
11048cursorbind Compiled with |'cursorbind'| (always true)
11049debug Compiled with "DEBUG" defined.
11050dialog_con Compiled with console dialog support.
11051dialog_gui Compiled with GUI dialog support.
11052diff Compiled with |vimdiff| and 'diff' support.
11053digraphs Compiled with support for digraphs.
11054directx Compiled with support for DirectX and 'renderoptions'.
11055dnd Compiled with support for the "~ register |quote_~|.
11056drop_file Compiled with |drop_file| support.
11057ebcdic Compiled on a machine with ebcdic character set.
11058emacs_tags Compiled with support for Emacs tags.
11059eval Compiled with expression evaluation support. Always
11060 true, of course!
11061ex_extra |+ex_extra| (always true)
11062extra_search Compiled with support for |'incsearch'| and
11063 |'hlsearch'|
11064farsi Support for Farsi was removed |farsi|.
Bram Moolenaarf80f40a2022-08-25 16:02:23 +010011065file_in_path Compiled with support for |gf| and |<cfile>| (always
11066 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011067filterpipe When 'shelltemp' is off pipes are used for shell
11068 read/write/filter commands
11069find_in_path Compiled with support for include file searches
11070 |+find_in_path|.
11071float Compiled with support for |Float|.
11072fname_case Case in file names matters (for Amiga and MS-Windows
11073 this is not present).
11074folding Compiled with |folding| support.
11075footer Compiled with GUI footer support. |gui-footer|
11076fork Compiled to use fork()/exec() instead of system().
11077gettext Compiled with message translation |multi-lang|
11078gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010011079gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011080gui_gnome Compiled with Gnome support (gui_gtk is also defined).
11081gui_gtk Compiled with GTK+ GUI (any version).
11082gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
11083gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
11084gui_haiku Compiled with Haiku GUI.
11085gui_mac Compiled with Macintosh GUI.
11086gui_motif Compiled with Motif GUI.
11087gui_photon Compiled with Photon GUI.
11088gui_running Vim is running in the GUI, or it will start soon.
11089gui_win32 Compiled with MS-Windows Win32 GUI.
11090gui_win32s idem, and Win32s system being used (Windows 3.1)
11091haiku Haiku version of Vim.
11092hangul_input Compiled with Hangul input support. |hangul|
11093hpux HP-UX version of Vim.
11094iconv Can use iconv() for conversion.
11095insert_expand Compiled with support for CTRL-X expansion commands in
11096 Insert mode. (always true)
11097job Compiled with support for |channel| and |job|
11098ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011099jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011100keymap Compiled with 'keymap' support.
11101lambda Compiled with |lambda| support.
11102langmap Compiled with 'langmap' support.
11103libcall Compiled with |libcall()| support.
11104linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
11105 'breakindent' support.
11106linux Linux version of Vim.
11107lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011108 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011109listcmds Compiled with commands for the buffer list |:files|
11110 and the argument list |arglist|.
11111localmap Compiled with local mappings and abbr. |:map-local|
11112lua Compiled with Lua interface |Lua|.
11113mac Any Macintosh version of Vim cf. osx
11114macunix Synonym for osxdarwin
11115menu Compiled with support for |:menu|.
11116mksession Compiled with support for |:mksession|.
11117modify_fname Compiled with file name modifiers. |filename-modifiers|
11118 (always true)
11119mouse Compiled with support for mouse.
11120mouse_dec Compiled with support for Dec terminal mouse.
11121mouse_gpm Compiled with support for gpm (Linux console mouse)
11122mouse_gpm_enabled GPM mouse is working
11123mouse_netterm Compiled with support for netterm mouse.
11124mouse_pterm Compiled with support for qnx pterm mouse.
11125mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
11126mouse_sgr Compiled with support for sgr mouse.
11127mouse_urxvt Compiled with support for urxvt mouse.
11128mouse_xterm Compiled with support for xterm mouse.
11129mouseshape Compiled with support for 'mouseshape'.
11130multi_byte Compiled with support for 'encoding' (always true)
11131multi_byte_encoding 'encoding' is set to a multibyte encoding.
11132multi_byte_ime Compiled with support for IME input method.
11133multi_lang Compiled with support for multiple languages.
11134mzscheme Compiled with MzScheme interface |mzscheme|.
11135nanotime Compiled with sub-second time stamp checks.
11136netbeans_enabled Compiled with support for |netbeans| and connected.
11137netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011138num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011139ole Compiled with OLE automation support for Win32.
11140osx Compiled for macOS cf. mac
11141osxdarwin Compiled for macOS, with |mac-darwin-feature|
11142packages Compiled with |packages| support.
11143path_extra Compiled with up/downwards search in 'path' and 'tags'
11144perl Compiled with Perl interface.
11145persistent_undo Compiled with support for persistent undo history.
11146postscript Compiled with PostScript file printing.
11147printer Compiled with |:hardcopy| support.
11148profile Compiled with |:profile| support.
Bram Moolenaar71badf92023-04-22 22:40:14 +010011149prof_nsec Profile results are in nanoseconds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011150python Python 2.x interface available. |has-python|
11151python_compiled Compiled with Python 2.x interface. |has-python|
11152python_dynamic Python 2.x interface is dynamically loaded. |has-python|
11153python3 Python 3.x interface available. |has-python|
11154python3_compiled Compiled with Python 3.x interface. |has-python|
11155python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Yee Cheng Chinc13b3d12023-08-20 21:18:38 +020011156python3_stable Python 3.x interface is using Python Stable ABI. |has-python|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011157pythonx Python 2.x and/or 3.x interface available. |python_x|
11158qnx QNX version of Vim.
11159quickfix Compiled with |quickfix| support.
11160reltime Compiled with |reltime()| support.
11161rightleft Compiled with 'rightleft' support.
11162ruby Compiled with Ruby interface |ruby|.
11163scrollbind Compiled with 'scrollbind' support. (always true)
11164showcmd Compiled with 'showcmd' support.
11165signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011166smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011167sodium Compiled with libsodium for better crypt support
11168sound Compiled with sound support, e.g. `sound_playevent()`
11169spell Compiled with spell checking support |spell|.
11170startuptime Compiled with |--startuptime| support.
11171statusline Compiled with support for 'statusline', 'rulerformat'
11172 and special formats of 'titlestring' and 'iconstring'.
11173sun SunOS version of Vim.
11174sun_workshop Support for Sun |workshop| has been removed.
11175syntax Compiled with syntax highlighting support |syntax|.
11176syntax_items There are active syntax highlighting items for the
11177 current buffer.
11178system Compiled to use system() instead of fork()/exec().
11179tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011180 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011181tag_old_static Support for old static tags was removed, see
11182 |tag-old-static|.
11183tcl Compiled with Tcl interface.
11184termguicolors Compiled with true color in terminal support.
11185terminal Compiled with |terminal| support.
11186terminfo Compiled with terminfo instead of termcap.
11187termresponse Compiled with support for |t_RV| and |v:termresponse|.
11188textobjects Compiled with support for |text-objects|.
11189textprop Compiled with support for |text-properties|.
11190tgetent Compiled with tgetent support, able to use a termcap
11191 or terminfo file.
11192timers Compiled with |timer_start()| support.
11193title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011194 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011195toolbar Compiled with support for |gui-toolbar|.
11196ttyin input is a terminal (tty)
11197ttyout output is a terminal (tty)
11198unix Unix version of Vim. *+unix*
11199unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
11200user_commands User-defined commands. (always true)
11201vartabs Compiled with variable tabstop support |'vartabstop'|.
11202vcon Win32: Virtual console support is working, can use
11203 'termguicolors'. Also see |+vtp|.
11204vertsplit Compiled with vertically split windows |:vsplit|.
11205 (always true)
11206vim_starting True while initial source'ing takes place. |startup|
11207 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000011208vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011209viminfo Compiled with viminfo support.
11210vimscript-1 Compiled Vim script version 1 support
11211vimscript-2 Compiled Vim script version 2 support
11212vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010011213vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011214virtualedit Compiled with 'virtualedit' option. (always true)
11215visual Compiled with Visual mode. (always true)
11216visualextra Compiled with extra Visual mode commands. (always
11217 true) |blockwise-operators|.
11218vms VMS version of Vim.
11219vreplace Compiled with |gR| and |gr| commands. (always true)
11220vtp Compiled for vcon support |+vtp| (check vcon to find
11221 out if it works in the current console).
11222wildignore Compiled with 'wildignore' option.
11223wildmenu Compiled with 'wildmenu' option.
11224win16 old version for MS-Windows 3.1 (always false)
11225win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
11226 64 bits)
11227win32unix Win32 version of Vim, using Unix files (Cygwin)
11228win64 Win64 version of Vim (MS-Windows 64 bit).
11229win95 Win32 version for MS-Windows 95/98/ME (always false)
11230winaltkeys Compiled with 'winaltkeys' option.
11231windows Compiled with support for more than one window.
11232 (always true)
11233writebackup Compiled with 'writebackup' default on.
Christian Brabandte085dfd2023-09-30 12:49:18 +020011234xattr Compiled with extended attributes support |xattr|
11235 (currently only supported on Linux).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011236xfontset Compiled with X fontset support |xfontset|.
11237xim Compiled with X input method support |xim|.
11238xpm Compiled with pixmap support.
11239xpm_w32 Compiled with pixmap support for Win32. (Only for
11240 backward compatibility. Use "xpm" instead.)
11241xsmp Compiled with X session management support.
11242xsmp_interact Compiled with interactive X session management support.
11243xterm_clipboard Compiled with support for xterm clipboard.
11244xterm_save Compiled with support for saving and restoring the
11245 xterm screen.
11246x11 Compiled with X11 support.
11247
11248
11249==============================================================================
112504. Matching a pattern in a String *string-match*
11251
11252This is common between several functions. A regexp pattern as explained at
11253|pattern| is normally used to find a match in the buffer lines. When a
11254pattern is used to find a match in a String, almost everything works in the
11255same way. The difference is that a String is handled like it is one line.
11256When it contains a "\n" character, this is not seen as a line break for the
11257pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
11258>
11259 :let a = "aaaa\nxxxx"
11260 :echo matchstr(a, "..\n..")
11261 aa
11262 xx
11263 :echo matchstr(a, "a.x")
11264 a
11265 x
11266
11267Don't forget that "^" will only match at the first character of the String and
11268"$" at the last character of the string. They don't match after or before a
11269"\n".
11270
11271 vim:tw=78:ts=8:noet:ft=help:norl: