blob: 8f79d2001dfbc872f72c764cc346f5ce3cff97fe [file] [log] [blame]
Christian Brabandtb4ddc6c2024-01-02 16:51:11 +01001*builtin.txt* For Vim version 9.1. Last change: 2023 Dec 24
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}
201foreground() Number bring the Vim window to the foreground
Bram Moolenaaraa534142022-09-15 21:46:02 +0100202fullcommand({name} [, {vim9}]) String get full command from {name}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000203funcref({name} [, {arglist}] [, {dict}])
204 Funcref reference to function {name}
205function({name} [, {arglist}] [, {dict}])
206 Funcref named reference to function {name}
207garbagecollect([{atexit}]) none free memory, breaking cyclic references
208get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
209get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
210get({func}, {what}) any get property of funcref/partial {func}
211getbufinfo([{buf}]) List information about buffers
212getbufline({buf}, {lnum} [, {end}])
213 List lines {lnum} to {end} of buffer {buf}
Bram Moolenaarce30ccc2022-11-21 19:57:04 +0000214getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000215getbufvar({buf}, {varname} [, {def}])
216 any variable {varname} in buffer {buf}
Kota Kato66bb9ae2023-01-17 18:31:56 +0000217getcellwidths() List get character cell width overrides
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000218getchangelist([{buf}]) List list of change list items
219getchar([expr]) Number or String
220 get one character from the user
221getcharmod() Number modifiers for the last typed character
222getcharpos({expr}) List position of cursor, mark, etc.
223getcharsearch() Dict last character search
224getcharstr([expr]) String get one character from the user
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100225getcmdcompltype() String return the type of the current
226 command-line completion
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000227getcmdline() String return the current command-line
228getcmdpos() Number return cursor position in command-line
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100229getcmdscreenpos() Number return cursor screen position in
230 command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000231getcmdtype() String return current command-line type
232getcmdwintype() String return current command-line window type
233getcompletion({pat}, {type} [, {filtered}])
234 List list of cmdline completion matches
235getcurpos([{winnr}]) List position of the cursor
236getcursorcharpos([{winnr}]) List character position of the cursor
237getcwd([{winnr} [, {tabnr}]]) String get the current working directory
238getenv({name}) String return environment variable
239getfontname([{name}]) String name of font being used
240getfperm({fname}) String file permissions of file {fname}
241getfsize({fname}) Number size in bytes of file {fname}
242getftime({fname}) Number last modification time of file
243getftype({fname}) String description of type of file {fname}
244getimstatus() Number |TRUE| if the IME status is active
245getjumplist([{winnr} [, {tabnr}]])
246 List list of jump list items
247getline({lnum}) String line {lnum} of current buffer
248getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
249getloclist({nr}) List list of location list items
250getloclist({nr}, {what}) Dict get specific location list properties
251getmarklist([{buf}]) List list of global/local marks
252getmatches([{win}]) List list of current matches
253getmousepos() Dict last known mouse position
Bram Moolenaar24dc19c2022-11-14 19:49:15 +0000254getmouseshape() String current mouse shape name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000255getpid() Number process ID of Vim
256getpos({expr}) List position of cursor, mark, etc.
257getqflist() List list of quickfix items
258getqflist({what}) Dict get specific quickfix list properties
259getreg([{regname} [, 1 [, {list}]]])
260 String or List contents of a register
261getreginfo([{regname}]) Dict information about a register
262getregtype([{regname}]) String type of a register
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +0100263getscriptinfo([{opts}]) List list of sourced scripts
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000264gettabinfo([{expr}]) List list of tab pages
265gettabvar({nr}, {varname} [, {def}])
266 any variable {varname} in tab {nr} or {def}
267gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
268 any {name} in {winnr} in tab page {tabnr}
269gettagstack([{nr}]) Dict get the tag stack of window {nr}
270gettext({text}) String lookup translation of {text}
271getwininfo([{winid}]) List list of info about each window
Bram Moolenaar938ae282023-02-20 20:44:55 +0000272getwinpos([{timeout}]) List X and Y coord in pixels of Vim window
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000273getwinposx() Number X coord in pixels of the Vim window
274getwinposy() Number Y coord in pixels of the Vim window
275getwinvar({nr}, {varname} [, {def}])
276 any variable {varname} in window {nr}
277glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
278 any expand file wildcards in {expr}
279glob2regpat({expr}) String convert a glob pat into a search pat
280globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
281 String do glob({expr}) for all dirs in {path}
282has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
283has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
284haslocaldir([{winnr} [, {tabnr}]])
285 Number |TRUE| if the window executed |:lcd|
286 or |:tcd|
287hasmapto({what} [, {mode} [, {abbr}]])
288 Number |TRUE| if mapping to {what} exists
289histadd({history}, {item}) Number add an item to a history
290histdel({history} [, {item}]) Number remove an item from a history
291histget({history} [, {index}]) String get the item {index} from a history
292histnr({history}) Number highest index of a history
293hlID({name}) Number syntax ID of highlight group {name}
294hlexists({name}) Number |TRUE| if highlight group {name} exists
295hlget([{name} [, {resolve}]]) List get highlight group attributes
296hlset({list}) Number set highlight group attributes
297hostname() String name of the machine Vim is running on
298iconv({expr}, {from}, {to}) String convert encoding of {expr}
299indent({lnum}) Number indent of line {lnum}
300index({object}, {expr} [, {start} [, {ic}]])
301 Number index in {object} where {expr} appears
Yegappan Lakshmananb2186552022-08-13 13:09:20 +0100302indexof({object}, {expr} [, {opts}]])
303 Number index in {object} where {expr} is true
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000304input({prompt} [, {text} [, {completion}]])
305 String get input from the user
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100306inputdialog({prompt} [, {text} [, {cancelreturn}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000307 String like input() but in a GUI dialog
308inputlist({textlist}) Number let the user pick from a choice list
309inputrestore() Number restore typeahead
310inputsave() Number save and clear typeahead
311inputsecret({prompt} [, {text}]) String like input() but hiding the text
312insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
LemonBoyafe04662023-08-23 21:08:11 +0200313instanceof({object}, {class}) Number |TRUE| if {object} is an instance of {class}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000314interrupt() none interrupt script execution
315invert({expr}) Number bitwise invert
LemonBoydca1d402022-04-28 15:26:33 +0100316isabsolutepath({path}) Number |TRUE| if {path} is an absolute path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000317isdirectory({directory}) Number |TRUE| if {directory} is a directory
318isinf({expr}) Number determine if {expr} is infinity value
319 (positive or negative)
320islocked({expr}) Number |TRUE| if {expr} is locked
321isnan({expr}) Number |TRUE| if {expr} is NaN
322items({dict}) List key-value pairs in {dict}
323job_getchannel({job}) Channel get the channel handle for {job}
324job_info([{job}]) Dict get information about {job}
325job_setoptions({job}, {options}) none set options for {job}
326job_start({command} [, {options}])
327 Job start a job
328job_status({job}) String get the status of {job}
329job_stop({job} [, {how}]) Number stop {job}
330join({list} [, {sep}]) String join {list} items into one String
331js_decode({string}) any decode JS style JSON
332js_encode({expr}) String encode JS style JSON
333json_decode({string}) any decode JSON
334json_encode({expr}) String encode JSON
335keys({dict}) List keys in {dict}
zeertzjqcdc83932022-09-12 13:38:41 +0100336keytrans({string}) String translate internal keycodes to a form
337 that can be used by |:map|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000338len({expr}) Number the length of {expr}
339libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
340libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
341line({expr} [, {winid}]) Number line nr of cursor, last line or mark
342line2byte({lnum}) Number byte count of line {lnum}
343lispindent({lnum}) Number Lisp indent for line {lnum}
344list2blob({list}) Blob turn {list} of numbers into a Blob
345list2str({list} [, {utf8}]) String turn {list} of numbers into a String
346listener_add({callback} [, {buf}])
347 Number add a callback to listen to changes
348listener_flush([{buf}]) none invoke listener callbacks
349listener_remove({id}) none remove a listener callback
350localtime() Number current time
351log({expr}) Float natural logarithm (base e) of {expr}
352log10({expr}) Float logarithm of Float {expr} to base 10
353luaeval({expr} [, {expr}]) any evaluate |Lua| expression
354map({expr1}, {expr2}) List/Dict/Blob/String
355 change each item in {expr1} to {expr2}
356maparg({name} [, {mode} [, {abbr} [, {dict}]]])
357 String or Dict
358 rhs of mapping {name} in mode {mode}
359mapcheck({name} [, {mode} [, {abbr}]])
360 String check for mappings matching {name}
Ernie Rael09661202022-04-25 14:40:44 +0100361maplist([{abbr}]) List list of all mappings, a dict for each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000362mapnew({expr1}, {expr2}) List/Dict/Blob/String
363 like |map()| but creates a new List or
364 Dictionary
365mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
366match({expr}, {pat} [, {start} [, {count}]])
367 Number position where {pat} matches in {expr}
368matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
369 Number highlight {pattern} with {group}
370matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
371 Number highlight positions with {group}
372matcharg({nr}) List arguments of |:match|
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100373matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict})
374 List all the {pat} matches in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000375matchdelete({id} [, {win}]) Number delete match identified by {id}
376matchend({expr}, {pat} [, {start} [, {count}]])
377 Number position where {pat} ends in {expr}
378matchfuzzy({list}, {str} [, {dict}])
379 List fuzzy match {str} in {list}
380matchfuzzypos({list}, {str} [, {dict}])
381 List fuzzy match {str} in {list}
382matchlist({expr}, {pat} [, {start} [, {count}]])
383 List match and submatches of {pat} in {expr}
384matchstr({expr}, {pat} [, {start} [, {count}]])
385 String {count}'th match of {pat} in {expr}
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100386matchstrlist({list}, {pat} [, {dict})
387 List all the {pat} matches in {list}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000388matchstrpos({expr}, {pat} [, {start} [, {count}]])
389 List {count}'th match of {pat} in {expr}
390max({expr}) Number maximum value of items in {expr}
391menu_info({name} [, {mode}]) Dict get menu item information
392min({expr}) Number minimum value of items in {expr}
Bram Moolenaar938ae282023-02-20 20:44:55 +0000393mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000394 Number create directory {name}
395mode([expr]) String current editing mode
396mzeval({expr}) any evaluate |MzScheme| expression
397nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
398nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
399or({expr}, {expr}) Number bitwise OR
400pathshorten({expr} [, {len}]) String shorten directory names in a path
401perleval({expr}) any evaluate |Perl| expression
402popup_atcursor({what}, {options}) Number create popup window near the cursor
403popup_beval({what}, {options}) Number create popup window for 'ballooneval'
404popup_clear() none close all popup windows
405popup_close({id} [, {result}]) none close popup window {id}
406popup_create({what}, {options}) Number create a popup window
407popup_dialog({what}, {options}) Number create a popup window used as a dialog
408popup_filter_menu({id}, {key}) Number filter for a menu popup window
409popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
Bram Moolenaarbdc09a12022-10-07 14:31:45 +0100410popup_findecho() Number get window ID of popup for `:echowin`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000411popup_findinfo() Number get window ID of info popup window
412popup_findpreview() Number get window ID of preview popup window
413popup_getoptions({id}) Dict get options of popup window {id}
414popup_getpos({id}) Dict get position of popup window {id}
415popup_hide({id}) none hide popup menu {id}
416popup_list() List get a list of window IDs of all popups
417popup_locate({row}, {col}) Number get window ID of popup at position
418popup_menu({what}, {options}) Number create a popup window used as a menu
419popup_move({id}, {options}) none set position of popup window {id}
420popup_notification({what}, {options})
421 Number create a notification popup window
422popup_setoptions({id}, {options})
423 none set options for popup window {id}
424popup_settext({id}, {text}) none set the text of popup window {id}
425popup_show({id}) none unhide popup window {id}
426pow({x}, {y}) Float {x} to the power of {y}
427prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
428printf({fmt}, {expr1}...) String format text
429prompt_getprompt({buf}) String get prompt text
430prompt_setcallback({buf}, {expr}) none set prompt callback function
431prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
432prompt_setprompt({buf}, {text}) none set prompt text
433prop_add({lnum}, {col}, {props}) none add one text property
434prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
435 none add multiple text properties
436prop_clear({lnum} [, {lnum-end} [, {props}]])
437 none remove all text properties
438prop_find({props} [, {direction}])
439 Dict search for a text property
440prop_list({lnum} [, {props}]) List text properties in {lnum}
441prop_remove({props} [, {lnum} [, {lnum-end}]])
442 Number remove a text property
443prop_type_add({name}, {props}) none define a new property type
444prop_type_change({name}, {props})
445 none change an existing property type
446prop_type_delete({name} [, {props}])
447 none delete a property type
448prop_type_get({name} [, {props}])
449 Dict get property type values
450prop_type_list([{props}]) List get list of property types
451pum_getpos() Dict position and size of pum if visible
452pumvisible() Number whether popup menu is visible
453py3eval({expr}) any evaluate |python3| expression
454pyeval({expr}) any evaluate |Python| expression
455pyxeval({expr}) any evaluate |python_x| expression
456rand([{expr}]) Number get pseudo-random number
457range({expr} [, {max} [, {stride}]])
458 List items from {expr} to {max}
K.Takata11df3ae2022-10-19 14:02:40 +0100459readblob({fname} [, {offset} [, {size}]])
460 Blob read a |Blob| from {fname}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000461readdir({dir} [, {expr} [, {dict}]])
462 List file names in {dir} selected by {expr}
463readdirex({dir} [, {expr} [, {dict}]])
464 List file info in {dir} selected by {expr}
465readfile({fname} [, {type} [, {max}]])
466 List get list of lines from file {fname}
467reduce({object}, {func} [, {initial}])
468 any reduce {object} using {func}
469reg_executing() String get the executing register name
470reg_recording() String get the recording register name
471reltime([{start} [, {end}]]) List get time value
472reltimefloat({time}) Float turn the time value into a Float
473reltimestr({time}) String turn time value into a String
474remote_expr({server}, {string} [, {idvar} [, {timeout}]])
475 String send expression
476remote_foreground({server}) Number bring Vim server to the foreground
477remote_peek({serverid} [, {retvar}])
478 Number check for reply string
479remote_read({serverid} [, {timeout}])
480 String read reply string
481remote_send({server}, {string} [, {idvar}])
482 String send key sequence
483remote_startserver({name}) none become server {name}
484remove({list}, {idx} [, {end}]) any/List
485 remove items {idx}-{end} from {list}
486remove({blob}, {idx} [, {end}]) Number/Blob
487 remove bytes {idx}-{end} from {blob}
488remove({dict}, {key}) any remove entry {key} from {dict}
489rename({from}, {to}) Number rename (move) file from {from} to {to}
Bakudankun375141e2022-09-09 18:46:47 +0100490repeat({expr}, {count}) List/Blob/String
491 repeat {expr} {count} times
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000492resolve({filename}) String get filename a shortcut points to
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +0100493reverse({obj}) List/Blob/String
494 reverse {obj}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000495round({expr}) Float round off {expr}
496rubyeval({expr}) any evaluate |Ruby| expression
497screenattr({row}, {col}) Number attribute at screen position
498screenchar({row}, {col}) Number character at screen position
499screenchars({row}, {col}) List List of characters at screen position
500screencol() Number current cursor column
501screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
502screenrow() Number current cursor row
503screenstring({row}, {col}) String characters at screen position
504search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
505 Number search for {pattern}
506searchcount([{options}]) Dict get or update search stats
507searchdecl({name} [, {global} [, {thisblock}]])
508 Number search for variable declaration
509searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
510 Number search for other end of start/end pair
511searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
512 List search for other end of start/end pair
513searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
514 List search for {pattern}
515server2client({clientid}, {string})
516 Number send reply string
517serverlist() String get a list of available servers
518setbufline({expr}, {lnum}, {text})
519 Number set line {lnum} to {text} in buffer
520 {expr}
521setbufvar({buf}, {varname}, {val})
522 none set {varname} in buffer {buf} to {val}
523setcellwidths({list}) none set character cell width overrides
524setcharpos({expr}, {list}) Number set the {expr} position to {list}
525setcharsearch({dict}) Dict set character search from {dict}
Shougo Matsushita07ea5f12022-08-27 12:22:25 +0100526setcmdline({str} [, {pos}]) Number set command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000527setcmdpos({pos}) Number set cursor position in command-line
528setcursorcharpos({list}) Number move cursor to position in {list}
529setenv({name}, {val}) none set environment variable
530setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
531setline({lnum}, {line}) Number set line {lnum} to {line}
532setloclist({nr}, {list} [, {action}])
533 Number modify location list using {list}
534setloclist({nr}, {list}, {action}, {what})
535 Number modify specific location list props
536setmatches({list} [, {win}]) Number restore a list of matches
537setpos({expr}, {list}) Number set the {expr} position to {list}
538setqflist({list} [, {action}]) Number modify quickfix list using {list}
539setqflist({list}, {action}, {what})
540 Number modify specific quickfix list props
541setreg({n}, {v} [, {opt}]) Number set register to value and type
542settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
543settabwinvar({tabnr}, {winnr}, {varname}, {val})
544 none set {varname} in window {winnr} in tab
545 page {tabnr} to {val}
546settagstack({nr}, {dict} [, {action}])
547 Number modify tag stack using {dict}
548setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
549sha256({string}) String SHA256 checksum of {string}
550shellescape({string} [, {special}])
551 String escape {string} for use as shell
552 command argument
553shiftwidth([{col}]) Number effective value of 'shiftwidth'
554sign_define({name} [, {dict}]) Number define or update a sign
555sign_define({list}) List define or update a list of signs
556sign_getdefined([{name}]) List get a list of defined signs
557sign_getplaced([{buf} [, {dict}]])
558 List get a list of placed signs
559sign_jump({id}, {group}, {buf})
560 Number jump to a sign
561sign_place({id}, {group}, {name}, {buf} [, {dict}])
562 Number place a sign
563sign_placelist({list}) List place a list of signs
564sign_undefine([{name}]) Number undefine a sign
565sign_undefine({list}) List undefine a list of signs
566sign_unplace({group} [, {dict}])
567 Number unplace a sign
568sign_unplacelist({list}) List unplace a list of signs
569simplify({filename}) String simplify filename as much as possible
570sin({expr}) Float sine of {expr}
571sinh({expr}) Float hyperbolic sine of {expr}
572slice({expr}, {start} [, {end}]) String, List or Blob
573 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000574sort({list} [, {how} [, {dict}]])
575 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000576sound_clear() none stop playing all sounds
577sound_playevent({name} [, {callback}])
578 Number play an event sound
579sound_playfile({path} [, {callback}])
580 Number play sound file {path}
581sound_stop({id}) none stop playing sound {id}
582soundfold({word}) String sound-fold {word}
583spellbadword() String badly spelled word at cursor
584spellsuggest({word} [, {max} [, {capital}]])
585 List spelling suggestions
586split({expr} [, {pat} [, {keepempty}]])
587 List make |List| from {pat} separated {expr}
588sqrt({expr}) Float square root of {expr}
589srand([{expr}]) List get seed for |rand()|
590state([{what}]) String current state of Vim
591str2float({expr} [, {quoted}]) Float convert String to Float
592str2list({expr} [, {utf8}]) List convert each character of {expr} to
593 ASCII/UTF-8 value
594str2nr({expr} [, {base} [, {quoted}]])
595 Number convert String to Number
596strcharlen({expr}) Number character length of the String {expr}
597strcharpart({str}, {start} [, {len} [, {skipcc}]])
598 String {len} characters of {str} at
599 character {start}
600strchars({expr} [, {skipcc}]) Number character count of the String {expr}
601strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
602strftime({format} [, {time}]) String format time with a specified format
603strgetchar({str}, {index}) Number get char {index} from {str}
604stridx({haystack}, {needle} [, {start}])
605 Number index of {needle} in {haystack}
606string({expr}) String String representation of {expr} value
607strlen({expr}) Number length of the String {expr}
608strpart({str}, {start} [, {len} [, {chars}]])
609 String {len} bytes/chars of {str} at
610 byte {start}
611strptime({format}, {timestring})
612 Number Convert {timestring} to unix timestamp
613strridx({haystack}, {needle} [, {start}])
614 Number last index of {needle} in {haystack}
615strtrans({expr}) String translate string to make it printable
Christian Brabandt67672ef2023-04-24 21:09:54 +0100616strutf16len({string} [, {countcc}])
617 Number number of UTF-16 code units in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000618strwidth({expr}) Number display cell length of the String {expr}
619submatch({nr} [, {list}]) String or List
620 specific match in ":s" or substitute()
621substitute({expr}, {pat}, {sub}, {flags})
622 String all {pat} in {expr} replaced with {sub}
Bram Moolenaarc216a7a2022-12-05 13:50:55 +0000623swapfilelist() List swap files found in 'directory'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000624swapinfo({fname}) Dict information about swap file {fname}
625swapname({buf}) String swap file of buffer {buf}
626synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
627synIDattr({synID}, {what} [, {mode}])
628 String attribute {what} of syntax ID {synID}
629synIDtrans({synID}) Number translated syntax ID of {synID}
630synconcealed({lnum}, {col}) List info about concealing
631synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
632system({expr} [, {input}]) String output of shell command/filter {expr}
633systemlist({expr} [, {input}]) List output of shell command/filter {expr}
634tabpagebuflist([{arg}]) List list of buffer numbers in tab page
635tabpagenr([{arg}]) Number number of current or last tab page
636tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
637tagfiles() List tags files used
638taglist({expr} [, {filename}]) List list of tags matching {expr}
639tan({expr}) Float tangent of {expr}
640tanh({expr}) Float hyperbolic tangent of {expr}
641tempname() String name for a temporary file
642term_dumpdiff({filename}, {filename} [, {options}])
643 Number display difference between two dumps
644term_dumpload({filename} [, {options}])
645 Number displaying a screen dump
646term_dumpwrite({buf}, {filename} [, {options}])
647 none dump terminal window contents
648term_getaltscreen({buf}) Number get the alternate screen flag
649term_getansicolors({buf}) List get ANSI palette in GUI color mode
650term_getattr({attr}, {what}) Number get the value of attribute {what}
651term_getcursor({buf}) List get the cursor position of a terminal
652term_getjob({buf}) Job get the job associated with a terminal
653term_getline({buf}, {row}) String get a line of text from a terminal
654term_getscrolled({buf}) Number get the scroll count of a terminal
655term_getsize({buf}) List get the size of a terminal
656term_getstatus({buf}) String get the status of a terminal
657term_gettitle({buf}) String get the title of a terminal
658term_gettty({buf}, [{input}]) String get the tty name of a terminal
659term_list() List get the list of terminal buffers
660term_scrape({buf}, {row}) List get row of a terminal screen
661term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
662term_setansicolors({buf}, {colors})
663 none set ANSI palette in GUI color mode
664term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
665term_setkill({buf}, {how}) none set signal to stop job in terminal
666term_setrestore({buf}, {command}) none set command to restore terminal
667term_setsize({buf}, {rows}, {cols})
668 none set the size of a terminal
669term_start({cmd} [, {options}]) Number open a terminal window and run a job
670term_wait({buf} [, {time}]) Number wait for screen to be updated
671terminalprops() Dict properties of the terminal
672test_alloc_fail({id}, {countdown}, {repeat})
673 none make memory allocation fail
674test_autochdir() none enable 'autochdir' during startup
675test_feedinput({string}) none add key sequence to input buffer
676test_garbagecollect_now() none free memory right now for testing
677test_garbagecollect_soon() none free memory soon for testing
678test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000679test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000680test_ignore_error({expr}) none ignore a specific error
Christopher Plewright20b795e2022-12-20 20:01:58 +0000681test_mswin_event({event}, {args})
682 bool generate MS-Windows event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000683test_null_blob() Blob null value for testing
684test_null_channel() Channel null value for testing
685test_null_dict() Dict null value for testing
686test_null_function() Funcref null value for testing
687test_null_job() Job null value for testing
688test_null_list() List null value for testing
689test_null_partial() Funcref null value for testing
690test_null_string() String null value for testing
691test_option_not_set({name}) none reset flag indicating option was set
692test_override({expr}, {val}) none test with Vim internal overrides
693test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000694test_setmouse({row}, {col}) none set the mouse position for testing
695test_settime({expr}) none set current time for testing
696test_srand_seed([seed]) none set seed for testing srand()
697test_unknown() any unknown value for testing
698test_void() any void value for testing
699timer_info([{id}]) List information about timers
700timer_pause({id}, {pause}) none pause or unpause a timer
701timer_start({time}, {callback} [, {options}])
702 Number create a timer
703timer_stop({timer}) none stop a timer
704timer_stopall() none stop all timers
705tolower({expr}) String the String {expr} switched to lowercase
706toupper({expr}) String the String {expr} switched to uppercase
707tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
708 to chars in {tostr}
709trim({text} [, {mask} [, {dir}]])
710 String trim characters in {mask} from {text}
711trunc({expr}) Float truncate Float {expr}
712type({expr}) Number type of value {expr}
713typename({expr}) String representation of the type of {expr}
714undofile({name}) String undo file name for {name}
Devin J. Pohly5fee1112023-04-23 20:26:59 -0500715undotree([{buf}]) List undo file tree for buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000716uniq({list} [, {func} [, {dict}]])
717 List remove adjacent duplicates from a list
Christian Brabandt67672ef2023-04-24 21:09:54 +0100718utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
719 Number UTF-16 index of byte {idx} in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000720values({dict}) List values in {dict}
zeertzjq825cf812023-08-17 22:55:25 +0200721virtcol({expr} [, {list} [, {winid}])
722 Number or List
LemonBoy0f7a3e12022-05-26 12:10:37 +0100723 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100724virtcol2col({winid}, {lnum}, {col})
725 Number byte index of a character on screen
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000726visualmode([expr]) String last visual mode used
727wildmenumode() Number whether 'wildmenu' mode is active
728win_execute({id}, {command} [, {silent}])
729 String execute {command} in window {id}
730win_findbuf({bufnr}) List find windows containing {bufnr}
731win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
732win_gettype([{nr}]) String type of window {nr}
733win_gotoid({expr}) Number go to window with ID {expr}
734win_id2tabwin({expr}) List get tab and window nr from window ID
735win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000736win_move_separator({nr}) Number move window vertical separator
737win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000738win_screenpos({nr}) List get screen position of window {nr}
739win_splitmove({nr}, {target} [, {options}])
740 Number move window {nr} to split of {target}
741winbufnr({nr}) Number buffer number of window {nr}
742wincol() Number window column of the cursor
743windowsversion() String MS-Windows OS version
744winheight({nr}) Number height of window {nr}
745winlayout([{tabnr}]) List layout of windows in tab {tabnr}
746winline() Number window line of the cursor
747winnr([{expr}]) Number number of current window
748winrestcmd() String returns command to restore window sizes
749winrestview({dict}) none restore view of current window
750winsaveview() Dict save view of current window
751winwidth({nr}) Number width of window {nr}
752wordcount() Dict get byte/char/word statistics
753writefile({object}, {fname} [, {flags}])
754 Number write |Blob| or |List| of lines to file
755xor({expr}, {expr}) Number bitwise XOR
756
757==============================================================================
7582. Details *builtin-function-details*
759
760Not all functions are here, some have been moved to a help file covering the
761specific functionality.
762
763abs({expr}) *abs()*
764 Return the absolute value of {expr}. When {expr} evaluates to
765 a |Float| abs() returns a |Float|. When {expr} can be
766 converted to a |Number| abs() returns a |Number|. Otherwise
767 abs() gives an error message and returns -1.
768 Examples: >
769 echo abs(1.456)
770< 1.456 >
771 echo abs(-5.456)
772< 5.456 >
773 echo abs(-4)
774< 4
775
776 Can also be used as a |method|: >
777 Compute()->abs()
778
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000779
780acos({expr}) *acos()*
781 Return the arc cosine of {expr} measured in radians, as a
782 |Float| in the range of [0, pi].
783 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100784 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000785 Examples: >
786 :echo acos(0)
787< 1.570796 >
788 :echo acos(-0.5)
789< 2.094395
790
791 Can also be used as a |method|: >
792 Compute()->acos()
793
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000794
795add({object}, {expr}) *add()*
796 Append the item {expr} to |List| or |Blob| {object}. Returns
797 the resulting |List| or |Blob|. Examples: >
798 :let alist = add([1, 2, 3], item)
799 :call add(mylist, "woodstock")
800< Note that when {expr} is a |List| it is appended as a single
801 item. Use |extend()| to concatenate |Lists|.
802 When {object} is a |Blob| then {expr} must be a number.
803 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100804 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000805
806 Can also be used as a |method|: >
807 mylist->add(val1)->add(val2)
808
809
810and({expr}, {expr}) *and()*
811 Bitwise AND on the two arguments. The arguments are converted
812 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100813 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000814 Example: >
815 :let flag = and(bits, 0x80)
816< Can also be used as a |method|: >
817 :let flag = bits->and(0x80)
818
819
820append({lnum}, {text}) *append()*
821 When {text} is a |List|: Append each item of the |List| as a
822 text line below line {lnum} in the current buffer.
823 Otherwise append {text} as one text line below line {lnum} in
824 the current buffer.
825 Any type of item is accepted and converted to a String.
826 {lnum} can be zero to insert a line before the first one.
827 {lnum} is used like with |getline()|.
828 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000829 0 for success. When {text} is an empty list zero is returned,
830 no matter the value of {lnum}.
831 In |Vim9| script an invalid argument or negative number
832 results in an error. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000833 :let failed = append(line('$'), "# THE END")
834 :let failed = append(0, ["Chapter 1", "the beginning"])
835
836< Can also be used as a |method| after a List, the base is
837 passed as the second argument: >
838 mylist->append(lnum)
839
840
841appendbufline({buf}, {lnum}, {text}) *appendbufline()*
842 Like |append()| but append the text in buffer {buf}.
843
844 This function works only for loaded buffers. First call
845 |bufload()| if needed.
846
847 For the use of {buf}, see |bufname()|.
848
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000849 {lnum} is the line number to append below. Note that using
850 |line()| would use the current buffer, not the one appending
851 to. Use "$" to append at the end of the buffer. Other string
852 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000853
854 On success 0 is returned, on failure 1 is returned.
855 In |Vim9| script an error is given for an invalid {lnum}.
856
857 If {buf} is not a valid buffer or {lnum} is not valid, an
858 error message is given. Example: >
859 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000860< However, when {text} is an empty list then no error is given
861 for an invalid {lnum}, since {lnum} isn't actually used.
862
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000863 Can also be used as a |method| after a List, the base is
864 passed as the second argument: >
865 mylist->appendbufline(buf, lnum)
866
867
868argc([{winid}]) *argc()*
869 The result is the number of files in the argument list. See
870 |arglist|.
871 If {winid} is not supplied, the argument list of the current
872 window is used.
873 If {winid} is -1, the global argument list is used.
874 Otherwise {winid} specifies the window of which the argument
875 list is used: either the window number or the window ID.
876 Returns -1 if the {winid} argument is invalid.
877
878 *argidx()*
879argidx() The result is the current index in the argument list. 0 is
880 the first file. argc() - 1 is the last one. See |arglist|.
881
882 *arglistid()*
883arglistid([{winnr} [, {tabnr}]])
884 Return the argument list ID. This is a number which
885 identifies the argument list being used. Zero is used for the
886 global argument list. See |arglist|.
887 Returns -1 if the arguments are invalid.
888
889 Without arguments use the current window.
890 With {winnr} only use this window in the current tab page.
891 With {winnr} and {tabnr} use the window in the specified tab
892 page.
893 {winnr} can be the window number or the |window-ID|.
894
895 *argv()*
896argv([{nr} [, {winid}]])
897 The result is the {nr}th file in the argument list. See
898 |arglist|. "argv(0)" is the first one. Example: >
899 :let i = 0
900 :while i < argc()
901 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000902 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000903 : let i = i + 1
904 :endwhile
905< Without the {nr} argument, or when {nr} is -1, a |List| with
906 the whole |arglist| is returned.
907
908 The {winid} argument specifies the window ID, see |argc()|.
909 For the Vim command line arguments see |v:argv|.
910
Bram Moolenaar016188f2022-06-06 20:52:59 +0100911 Returns an empty string if {nr}th argument is not present in
912 the argument list. Returns an empty List if the {winid}
913 argument is invalid.
914
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000915asin({expr}) *asin()*
916 Return the arc sine of {expr} measured in radians, as a |Float|
917 in the range of [-pi/2, pi/2].
918 {expr} must evaluate to a |Float| or a |Number| in the range
919 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100920 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
921 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000922 Examples: >
923 :echo asin(0.8)
924< 0.927295 >
925 :echo asin(-0.5)
926< -0.523599
927
928 Can also be used as a |method|: >
929 Compute()->asin()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000930
931
932assert_ functions are documented here: |assert-functions-details|
933
934
935
936atan({expr}) *atan()*
937 Return the principal value of the arc tangent of {expr}, in
938 the range [-pi/2, +pi/2] radians, as a |Float|.
939 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100940 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000941 Examples: >
942 :echo atan(100)
943< 1.560797 >
944 :echo atan(-4.01)
945< -1.326405
946
947 Can also be used as a |method|: >
948 Compute()->atan()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000949
950
951atan2({expr1}, {expr2}) *atan2()*
952 Return the arc tangent of {expr1} / {expr2}, measured in
953 radians, as a |Float| in the range [-pi, pi].
954 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100955 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
956 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000957 Examples: >
958 :echo atan2(-1, 1)
959< -0.785398 >
960 :echo atan2(1, -1)
961< 2.356194
962
963 Can also be used as a |method|: >
964 Compute()->atan2(1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000965
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100966
967autocmd_add({acmds}) *autocmd_add()*
968 Adds a List of autocmds and autocmd groups.
969
970 The {acmds} argument is a List where each item is a Dict with
971 the following optional items:
972 bufnr buffer number to add a buffer-local autocmd.
973 If this item is specified, then the "pattern"
974 item is ignored.
975 cmd Ex command to execute for this autocmd event
976 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100977 This can be either a String with a single
978 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100979 group autocmd group name. Refer to |autocmd-groups|.
980 If this group doesn't exist then it is
981 created. If not specified or empty, then the
982 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100983 nested boolean flag, set to v:true to add a nested
984 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100985 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100986 which executes only once. Refer to
987 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100988 pattern autocmd pattern string. Refer to
989 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100990 present, then this item is ignored. This can
991 be a String with a single pattern or a List of
992 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100993 replace boolean flag, set to v:true to remove all the
994 commands associated with the specified autocmd
995 event and group and add the {cmd}. This is
996 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +0100997 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100998
999 Returns v:true on success and v:false on failure.
1000 Examples: >
1001 " Create a buffer-local autocmd for buffer 5
1002 let acmd = {}
1003 let acmd.group = 'MyGroup'
1004 let acmd.event = 'BufEnter'
1005 let acmd.bufnr = 5
1006 let acmd.cmd = 'call BufEnterFunc()'
1007 call autocmd_add([acmd])
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00001008<
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001009 Can also be used as a |method|: >
1010 GetAutocmdList()->autocmd_add()
1011<
1012autocmd_delete({acmds}) *autocmd_delete()*
1013 Deletes a List of autocmds and autocmd groups.
1014
1015 The {acmds} argument is a List where each item is a Dict with
1016 the following optional items:
1017 bufnr buffer number to delete a buffer-local autocmd.
1018 If this item is specified, then the "pattern"
1019 item is ignored.
1020 cmd Ex command for this autocmd event
1021 event autocmd event name. Refer to |autocmd-events|.
1022 If '*' then all the autocmd events in this
1023 group are deleted.
1024 group autocmd group name. Refer to |autocmd-groups|.
1025 If not specified or empty, then the default
1026 group is used.
1027 nested set to v:true for a nested autocmd.
1028 Refer to |autocmd-nested|.
1029 once set to v:true for an autocmd which executes
1030 only once. Refer to |autocmd-once|.
1031 pattern autocmd pattern string. Refer to
1032 |autocmd-patterns|. If "bufnr" item is
1033 present, then this item is ignored.
1034
1035 If only {group} is specified in a {acmds} entry and {event},
1036 {pattern} and {cmd} are not specified, then that autocmd group
1037 is deleted.
1038
Bram Moolenaar016188f2022-06-06 20:52:59 +01001039 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001040 Examples: >
1041 " :autocmd! BufLeave *.vim
1042 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1043 call autocmd_delete([acmd]})
1044 " :autocmd! MyGroup1 BufLeave
1045 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1046 call autocmd_delete([acmd])
1047 " :autocmd! MyGroup2 BufEnter *.c
1048 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1049 \ pattern: '*.c'}
1050 " :autocmd! MyGroup2 * *.c
1051 let acmd = #{group: 'MyGroup2', event: '*',
1052 \ pattern: '*.c'}
1053 call autocmd_delete([acmd])
1054 " :autocmd! MyGroup3
1055 let acmd = #{group: 'MyGroup3'}
1056 call autocmd_delete([acmd])
1057<
1058 Can also be used as a |method|: >
1059 GetAutocmdList()->autocmd_delete()
1060
1061autocmd_get([{opts}]) *autocmd_get()*
1062 Returns a |List| of autocmds. If {opts} is not supplied, then
1063 returns the autocmds for all the events in all the groups.
1064
1065 The optional {opts} Dict argument supports the following
1066 items:
1067 group Autocmd group name. If specified, returns only
1068 the autocmds defined in this group. If the
1069 specified group doesn't exist, results in an
1070 error message. If set to an empty string,
1071 then the default autocmd group is used.
1072 event Autocmd event name. If specified, returns only
1073 the autocmds defined for this event. If set
1074 to "*", then returns autocmds for all the
1075 events. If the specified event doesn't exist,
1076 results in an error message.
1077 pattern Autocmd pattern. If specified, returns only
1078 the autocmds defined for this pattern.
1079 A combination of the above three times can be supplied in
1080 {opts}.
1081
1082 Each Dict in the returned List contains the following items:
1083 bufnr For buffer-local autocmds, buffer number where
1084 the autocmd is defined.
1085 cmd Command executed for this autocmd.
1086 event Autocmd event name.
1087 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001088 nested Boolean flag, set to v:true for a nested
1089 autocmd. See |autocmd-nested|.
1090 once Boolean flag, set to v:true, if the autocmd
1091 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001092 pattern Autocmd pattern. For a buffer-local
1093 autocmd, this will be of the form "<buffer=n>".
1094 If there are multiple commands for an autocmd event in a
1095 group, then separate items are returned for each command.
1096
Bram Moolenaar016188f2022-06-06 20:52:59 +01001097 Returns an empty List if an autocmd with the specified group
1098 or event or pattern is not found.
1099
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001100 Examples: >
1101 " :autocmd MyGroup
1102 echo autocmd_get(#{group: 'Mygroup'})
1103 " :autocmd G BufUnload
1104 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1105 " :autocmd G * *.ts
1106 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1107 echo autocmd_get(acmd)
1108 " :autocmd Syntax
1109 echo autocmd_get(#{event: 'Syntax'})
1110 " :autocmd G BufEnter *.ts
1111 let acmd = #{group: 'G', event: 'BufEnter',
1112 \ pattern: '*.ts'}
1113 echo autocmd_get(acmd)
1114<
1115 Can also be used as a |method|: >
1116 Getopts()->autocmd_get()
1117<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001118balloon_gettext() *balloon_gettext()*
1119 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001120 not used for the List. Returns an empty string if balloon
1121 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001122
1123balloon_show({expr}) *balloon_show()*
1124 Show {expr} inside the balloon. For the GUI {expr} is used as
1125 a string. For a terminal {expr} can be a list, which contains
1126 the lines of the balloon. If {expr} is not a list it will be
1127 split with |balloon_split()|.
1128 If {expr} is an empty string any existing balloon is removed.
1129
1130 Example: >
1131 func GetBalloonContent()
1132 " ... initiate getting the content
1133 return ''
1134 endfunc
1135 set balloonexpr=GetBalloonContent()
1136
1137 func BalloonCallback(result)
1138 call balloon_show(a:result)
1139 endfunc
1140< Can also be used as a |method|: >
1141 GetText()->balloon_show()
1142<
1143 The intended use is that fetching the content of the balloon
1144 is initiated from 'balloonexpr'. It will invoke an
1145 asynchronous method, in which a callback invokes
1146 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001147 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001148
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001149 When showing a balloon is not possible then nothing happens,
1150 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001151 {only available when compiled with the |+balloon_eval| or
1152 |+balloon_eval_term| feature}
1153
1154balloon_split({msg}) *balloon_split()*
1155 Split String {msg} into lines to be displayed in a balloon.
1156 The splits are made for the current window size and optimize
1157 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001158 Returns a |List| with the split lines. Returns an empty List
1159 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001160 Can also be used as a |method|: >
1161 GetText()->balloon_split()->balloon_show()
1162
1163< {only available when compiled with the |+balloon_eval_term|
1164 feature}
1165
1166blob2list({blob}) *blob2list()*
1167 Return a List containing the number value of each byte in Blob
1168 {blob}. Examples: >
1169 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1170 blob2list(0z) returns []
1171< Returns an empty List on error. |list2blob()| does the
1172 opposite.
1173
1174 Can also be used as a |method|: >
1175 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001176<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001177 *browse()*
1178browse({save}, {title}, {initdir}, {default})
1179 Put up a file requester. This only works when "has("browse")"
1180 returns |TRUE| (only in some GUI versions).
1181 The input fields are:
1182 {save} when |TRUE|, select file to write
1183 {title} title for the requester
1184 {initdir} directory to start browsing in
1185 {default} default file name
1186 An empty string is returned when the "Cancel" button is hit,
1187 something went wrong, or browsing is not possible.
1188
1189 *browsedir()*
1190browsedir({title}, {initdir})
1191 Put up a directory requester. This only works when
1192 "has("browse")" returns |TRUE| (only in some GUI versions).
1193 On systems where a directory browser is not supported a file
1194 browser is used. In that case: select a file in the directory
1195 to be used.
1196 The input fields are:
1197 {title} title for the requester
1198 {initdir} directory to start browsing in
1199 When the "Cancel" button is hit, something went wrong, or
1200 browsing is not possible, an empty string is returned.
1201
1202bufadd({name}) *bufadd()*
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001203 Add a buffer to the buffer list with name {name} (must be a
1204 String).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001205 If a buffer for file {name} already exists, return that buffer
1206 number. Otherwise return the buffer number of the newly
1207 created buffer. When {name} is an empty string then a new
1208 buffer is always created.
1209 The buffer will not have 'buflisted' set and not be loaded
1210 yet. To add some text to the buffer use this: >
1211 let bufnr = bufadd('someName')
1212 call bufload(bufnr)
1213 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001214< Returns 0 on error.
1215 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001216 let bufnr = 'somename'->bufadd()
1217
1218bufexists({buf}) *bufexists()*
1219 The result is a Number, which is |TRUE| if a buffer called
1220 {buf} exists.
1221 If the {buf} argument is a number, buffer numbers are used.
1222 Number zero is the alternate buffer for the current window.
1223
1224 If the {buf} argument is a string it must match a buffer name
1225 exactly. The name can be:
1226 - Relative to the current directory.
1227 - A full path.
1228 - The name of a buffer with 'buftype' set to "nofile".
1229 - A URL name.
1230 Unlisted buffers will be found.
1231 Note that help files are listed by their short name in the
1232 output of |:buffers|, but bufexists() requires using their
1233 long name to be able to find them.
1234 bufexists() may report a buffer exists, but to use the name
1235 with a |:buffer| command you may need to use |expand()|. Esp
1236 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1237 Use "bufexists(0)" to test for the existence of an alternate
1238 file name.
1239
1240 Can also be used as a |method|: >
1241 let exists = 'somename'->bufexists()
1242<
1243 Obsolete name: buffer_exists(). *buffer_exists()*
1244
1245buflisted({buf}) *buflisted()*
1246 The result is a Number, which is |TRUE| if a buffer called
1247 {buf} exists and is listed (has the 'buflisted' option set).
1248 The {buf} argument is used like with |bufexists()|.
1249
1250 Can also be used as a |method|: >
1251 let listed = 'somename'->buflisted()
1252
1253bufload({buf}) *bufload()*
1254 Ensure the buffer {buf} is loaded. When the buffer name
1255 refers to an existing file then the file is read. Otherwise
1256 the buffer will be empty. If the buffer was already loaded
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001257 then there is no change. If the buffer is not related to a
Daniel Steinbergc2bd2052023-08-09 12:10:59 -04001258 file then no file is read (e.g., when 'buftype' is "nofile").
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001259 If there is an existing swap file for the file of the buffer,
1260 there will be no dialog, the buffer will be loaded anyway.
1261 The {buf} argument is used like with |bufexists()|.
1262
1263 Can also be used as a |method|: >
1264 eval 'somename'->bufload()
1265
1266bufloaded({buf}) *bufloaded()*
1267 The result is a Number, which is |TRUE| if a buffer called
1268 {buf} exists and is loaded (shown in a window or hidden).
1269 The {buf} argument is used like with |bufexists()|.
1270
1271 Can also be used as a |method|: >
1272 let loaded = 'somename'->bufloaded()
1273
1274bufname([{buf}]) *bufname()*
1275 The result is the name of a buffer. Mostly as it is displayed
1276 by the `:ls` command, but not using special names such as
1277 "[No Name]".
1278 If {buf} is omitted the current buffer is used.
1279 If {buf} is a Number, that buffer number's name is given.
1280 Number zero is the alternate buffer for the current window.
1281 If {buf} is a String, it is used as a |file-pattern| to match
1282 with the buffer names. This is always done like 'magic' is
1283 set and 'cpoptions' is empty. When there is more than one
1284 match an empty string is returned.
1285 "" or "%" can be used for the current buffer, "#" for the
1286 alternate buffer.
1287 A full match is preferred, otherwise a match at the start, end
1288 or middle of the buffer name is accepted. If you only want a
1289 full match then put "^" at the start and "$" at the end of the
1290 pattern.
1291 Listed buffers are found first. If there is a single match
1292 with a listed buffer, that one is returned. Next unlisted
1293 buffers are searched for.
1294 If the {buf} is a String, but you want to use it as a buffer
1295 number, force it to be a Number by adding zero to it: >
1296 :echo bufname("3" + 0)
1297< Can also be used as a |method|: >
1298 echo bufnr->bufname()
1299
1300< If the buffer doesn't exist, or doesn't have a name, an empty
1301 string is returned. >
1302 bufname("#") alternate buffer name
1303 bufname(3) name of buffer 3
1304 bufname("%") name of current buffer
1305 bufname("file2") name of buffer where "file2" matches.
1306< *buffer_name()*
1307 Obsolete name: buffer_name().
1308
1309 *bufnr()*
1310bufnr([{buf} [, {create}]])
1311 The result is the number of a buffer, as it is displayed by
1312 the `:ls` command. For the use of {buf}, see |bufname()|
1313 above.
1314
1315 If the buffer doesn't exist, -1 is returned. Or, if the
1316 {create} argument is present and TRUE, a new, unlisted,
1317 buffer is created and its number is returned. Example: >
1318 let newbuf = bufnr('Scratch001', 1)
1319< Using an empty name uses the current buffer. To create a new
1320 buffer with an empty name use |bufadd()|.
1321
1322 bufnr("$") is the last buffer: >
1323 :let last_buffer = bufnr("$")
1324< The result is a Number, which is the highest buffer number
1325 of existing buffers. Note that not all buffers with a smaller
1326 number necessarily exist, because ":bwipeout" may have removed
1327 them. Use bufexists() to test for the existence of a buffer.
1328
1329 Can also be used as a |method|: >
1330 echo bufref->bufnr()
1331<
1332 Obsolete name: buffer_number(). *buffer_number()*
1333 *last_buffer_nr()*
1334 Obsolete name for bufnr("$"): last_buffer_nr().
1335
1336bufwinid({buf}) *bufwinid()*
1337 The result is a Number, which is the |window-ID| of the first
1338 window associated with buffer {buf}. For the use of {buf},
1339 see |bufname()| above. If buffer {buf} doesn't exist or
1340 there is no such window, -1 is returned. Example: >
1341
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001342 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001343<
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001344 Only deals with the current tab page. See |win_findbuf()| for
1345 finding more.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001346
1347 Can also be used as a |method|: >
1348 FindBuffer()->bufwinid()
1349
1350bufwinnr({buf}) *bufwinnr()*
1351 Like |bufwinid()| but return the window number instead of the
1352 |window-ID|.
1353 If buffer {buf} doesn't exist or there is no such window, -1
1354 is returned. Example: >
1355
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001356 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001357
1358< The number can be used with |CTRL-W_w| and ":wincmd w"
1359 |:wincmd|.
1360
1361 Can also be used as a |method|: >
1362 FindBuffer()->bufwinnr()
1363
1364byte2line({byte}) *byte2line()*
1365 Return the line number that contains the character at byte
1366 count {byte} in the current buffer. This includes the
1367 end-of-line character, depending on the 'fileformat' option
1368 for the current buffer. The first character has byte count
1369 one.
1370 Also see |line2byte()|, |go| and |:goto|.
1371
Bram Moolenaar016188f2022-06-06 20:52:59 +01001372 Returns -1 if the {byte} value is invalid.
1373
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001374 Can also be used as a |method|: >
1375 GetOffset()->byte2line()
1376
1377< {not available when compiled without the |+byte_offset|
1378 feature}
1379
Christian Brabandt67672ef2023-04-24 21:09:54 +01001380byteidx({expr}, {nr} [, {utf16}]) *byteidx()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001381 Return byte index of the {nr}'th character in the String
1382 {expr}. Use zero for the first character, it then returns
1383 zero.
1384 If there are no multibyte characters the returned value is
1385 equal to {nr}.
1386 Composing characters are not counted separately, their byte
1387 length is added to the preceding base character. See
1388 |byteidxcomp()| below for counting composing characters
1389 separately.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001390 When {utf16} is present and TRUE, {nr} is used as the UTF-16
1391 index in the String {expr} instead of as the character index.
1392 The UTF-16 index is the index in the string when it is encoded
1393 with 16-bit words. If the specified UTF-16 index is in the
1394 middle of a character (e.g. in a 4-byte character), then the
1395 byte index of the first byte in the character is returned.
1396 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001397 Example : >
1398 echo matchstr(str, ".", byteidx(str, 3))
1399< will display the fourth character. Another way to do the
1400 same: >
1401 let s = strpart(str, byteidx(str, 3))
1402 echo strpart(s, 0, byteidx(s, 1))
1403< Also see |strgetchar()| and |strcharpart()|.
1404
1405 If there are less than {nr} characters -1 is returned.
1406 If there are exactly {nr} characters the length of the string
1407 in bytes is returned.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001408 See |charidx()| and |utf16idx()| for getting the character and
1409 UTF-16 index respectively from the byte index.
1410 Examples: >
1411 echo byteidx('a😊😊', 2) returns 5
1412 echo byteidx('a😊😊', 2, 1) returns 1
1413 echo byteidx('a😊😊', 3, 1) returns 5
1414<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001415 Can also be used as a |method|: >
1416 GetName()->byteidx(idx)
1417
Christian Brabandt67672ef2023-04-24 21:09:54 +01001418byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001419 Like byteidx(), except that a composing character is counted
1420 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001421 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001422 echo byteidx(s, 1)
1423 echo byteidxcomp(s, 1)
1424 echo byteidxcomp(s, 2)
1425< The first and third echo result in 3 ('e' plus composing
1426 character is 3 bytes), the second echo results in 1 ('e' is
1427 one byte).
1428 Only works differently from byteidx() when 'encoding' is set
1429 to a Unicode encoding.
1430
1431 Can also be used as a |method|: >
1432 GetName()->byteidxcomp(idx)
1433
1434call({func}, {arglist} [, {dict}]) *call()* *E699*
1435 Call function {func} with the items in |List| {arglist} as
1436 arguments.
1437 {func} can either be a |Funcref| or the name of a function.
1438 a:firstline and a:lastline are set to the cursor line.
1439 Returns the return value of the called function.
1440 {dict} is for functions with the "dict" attribute. It will be
1441 used to set the local variable "self". |Dictionary-function|
1442
1443 Can also be used as a |method|: >
1444 GetFunc()->call([arg, arg], dict)
1445
1446ceil({expr}) *ceil()*
1447 Return the smallest integral value greater than or equal to
1448 {expr} as a |Float| (round up).
1449 {expr} must evaluate to a |Float| or a |Number|.
1450 Examples: >
1451 echo ceil(1.456)
1452< 2.0 >
1453 echo ceil(-5.456)
1454< -5.0 >
1455 echo ceil(4.0)
1456< 4.0
1457
Bram Moolenaar016188f2022-06-06 20:52:59 +01001458 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1459
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001460 Can also be used as a |method|: >
1461 Compute()->ceil()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001462
1463
1464ch_ functions are documented here: |channel-functions-details|
1465
1466
1467changenr() *changenr()*
1468 Return the number of the most recent change. This is the same
1469 number as what is displayed with |:undolist| and can be used
1470 with the |:undo| command.
1471 When a change was made it is the number of that change. After
1472 redo it is the number of the redone change. After undo it is
1473 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001474 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001475
1476char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001477 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001478 Examples: >
1479 char2nr(" ") returns 32
1480 char2nr("ABC") returns 65
1481< When {utf8} is omitted or zero, the current 'encoding' is used.
1482 Example for "utf-8": >
1483 char2nr("á") returns 225
1484 char2nr("á"[0]) returns 195
1485< When {utf8} is TRUE, always treat as UTF-8 characters.
1486 A combining character is a separate character.
1487 |nr2char()| does the opposite.
1488 To turn a string into a list of character numbers: >
1489 let str = "ABC"
1490 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1491< Result: [65, 66, 67]
1492
Bram Moolenaar016188f2022-06-06 20:52:59 +01001493 Returns 0 if {string} is not a |String|.
1494
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001495 Can also be used as a |method|: >
1496 GetChar()->char2nr()
1497
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001498charclass({string}) *charclass()*
1499 Return the character class of the first character in {string}.
1500 The character class is one of:
1501 0 blank
1502 1 punctuation
1503 2 word character
1504 3 emoji
1505 other specific Unicode class
1506 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001507 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001508
1509
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001510charcol({expr} [, {winid}]) *charcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001511 Same as |col()| but returns the character index of the column
1512 position given with {expr} instead of the byte position.
1513
1514 Example:
1515 With the cursor on '세' in line 5 with text "여보세요": >
1516 charcol('.') returns 3
1517 col('.') returns 7
1518
1519< Can also be used as a |method|: >
1520 GetPos()->col()
1521<
1522 *charidx()*
Christian Brabandt67672ef2023-04-24 21:09:54 +01001523charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001524 Return the character index of the byte at {idx} in {string}.
1525 The index of the first character is zero.
1526 If there are no multibyte characters the returned value is
1527 equal to {idx}.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001528
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001529 When {countcc} is omitted or |FALSE|, then composing characters
Christian Brabandt67672ef2023-04-24 21:09:54 +01001530 are not counted separately, their byte length is added to the
1531 preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001532 When {countcc} is |TRUE|, then composing characters are
1533 counted as separate characters.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001534
1535 When {utf16} is present and TRUE, {idx} is used as the UTF-16
1536 index in the String {expr} instead of as the byte index.
1537
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +01001538 Returns -1 if the arguments are invalid or if there are less
1539 than {idx} bytes. If there are exactly {idx} bytes the length
1540 of the string in characters is returned.
1541
1542 An error is given and -1 is returned if the first argument is
1543 not a string, the second argument is not a number or when the
1544 third argument is present and is not zero or one.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001545
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001546 See |byteidx()| and |byteidxcomp()| for getting the byte index
Christian Brabandt67672ef2023-04-24 21:09:54 +01001547 from the character index and |utf16idx()| for getting the
1548 UTF-16 index from the character index.
1549 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001550 Examples: >
1551 echo charidx('áb́ć', 3) returns 1
1552 echo charidx('áb́ć', 6, 1) returns 4
1553 echo charidx('áb́ć', 16) returns -1
Christian Brabandt67672ef2023-04-24 21:09:54 +01001554 echo charidx('a😊😊', 4, 0, 1) returns 2
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001555<
1556 Can also be used as a |method|: >
1557 GetName()->charidx(idx)
1558
1559chdir({dir}) *chdir()*
1560 Change the current working directory to {dir}. The scope of
1561 the directory change depends on the directory of the current
1562 window:
1563 - If the current window has a window-local directory
1564 (|:lcd|), then changes the window local directory.
1565 - Otherwise, if the current tabpage has a local
1566 directory (|:tcd|) then changes the tabpage local
1567 directory.
1568 - Otherwise, changes the global directory.
1569 {dir} must be a String.
1570 If successful, returns the previous working directory. Pass
1571 this to another chdir() to restore the directory.
1572 On failure, returns an empty string.
1573
1574 Example: >
1575 let save_dir = chdir(newdir)
1576 if save_dir != ""
1577 " ... do some work
1578 call chdir(save_dir)
1579 endif
1580
1581< Can also be used as a |method|: >
1582 GetDir()->chdir()
1583<
1584cindent({lnum}) *cindent()*
1585 Get the amount of indent for line {lnum} according the C
1586 indenting rules, as with 'cindent'.
1587 The indent is counted in spaces, the value of 'tabstop' is
1588 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001589 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001590 See |C-indenting|.
1591
1592 Can also be used as a |method|: >
1593 GetLnum()->cindent()
1594
1595clearmatches([{win}]) *clearmatches()*
1596 Clears all matches previously defined for the current window
1597 by |matchadd()| and the |:match| commands.
1598 If {win} is specified, use the window with this number or
1599 window ID instead of the current window.
1600
1601 Can also be used as a |method|: >
1602 GetWin()->clearmatches()
1603<
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001604col({expr} [, {winid}]) *col()*
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001605 The result is a Number, which is the byte index of the column
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001606 position given with {expr}. The accepted positions are:
1607 . the cursor position
1608 $ the end of the cursor line (the result is the
1609 number of bytes in the cursor line plus one)
1610 'x position of mark x (if the mark is not set, 0 is
1611 returned)
1612 v In Visual mode: the start of the Visual area (the
1613 cursor is the end). When not in Visual mode
1614 returns the cursor position. Differs from |'<| in
1615 that it's updated right away.
1616 Additionally {expr} can be [lnum, col]: a |List| with the line
1617 and column number. Most useful when the column is "$", to get
1618 the last column of a specific line. When "lnum" or "col" is
1619 out of range then col() returns zero.
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001620 With the optional {winid} argument the values are obtained for
1621 that window instead of the current window.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001622 To get the line number use |line()|. To get both use
1623 |getpos()|.
1624 For the screen column position use |virtcol()|. For the
1625 character position use |charcol()|.
1626 Note that only marks in the current file can be used.
1627 Examples: >
1628 col(".") column of cursor
1629 col("$") length of cursor line plus one
1630 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001631 col("'" .. markname) column of mark markname
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001632< The first column is 1. Returns 0 if {expr} is invalid or when
1633 the window with ID {winid} is not found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001634 For an uppercase mark the column may actually be in another
1635 buffer.
1636 For the cursor position, when 'virtualedit' is active, the
1637 column is one higher if the cursor is after the end of the
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01001638 line. Also, when using a <Cmd> mapping the cursor isn't
1639 moved, this can be used to obtain the column in Insert mode: >
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001640 :imap <F2> <Cmd>echowin col(".")<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001641
1642< Can also be used as a |method|: >
1643 GetPos()->col()
1644<
1645
1646complete({startcol}, {matches}) *complete()* *E785*
1647 Set the matches for Insert mode completion.
1648 Can only be used in Insert mode. You need to use a mapping
1649 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1650 or with an expression mapping.
1651 {startcol} is the byte offset in the line where the completed
1652 text start. The text up to the cursor is the original text
1653 that will be replaced by the matches. Use col('.') for an
1654 empty string. "col('.') - 1" will replace one character by a
1655 match.
1656 {matches} must be a |List|. Each |List| item is one match.
1657 See |complete-items| for the kind of items that are possible.
1658 "longest" in 'completeopt' is ignored.
1659 Note that the after calling this function you need to avoid
1660 inserting anything that would cause completion to stop.
1661 The match can be selected with CTRL-N and CTRL-P as usual with
1662 Insert mode completion. The popup menu will appear if
1663 specified, see |ins-completion-menu|.
1664 Example: >
1665 inoremap <F5> <C-R>=ListMonths()<CR>
1666
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001667 func ListMonths()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001668 call complete(col('.'), ['January', 'February', 'March',
1669 \ 'April', 'May', 'June', 'July', 'August', 'September',
1670 \ 'October', 'November', 'December'])
1671 return ''
1672 endfunc
1673< This isn't very useful, but it shows how it works. Note that
1674 an empty string is returned to avoid a zero being inserted.
1675
1676 Can also be used as a |method|, the base is passed as the
1677 second argument: >
1678 GetMatches()->complete(col('.'))
1679
1680complete_add({expr}) *complete_add()*
1681 Add {expr} to the list of matches. Only to be used by the
1682 function specified with the 'completefunc' option.
1683 Returns 0 for failure (empty string or out of memory),
1684 1 when the match was added, 2 when the match was already in
1685 the list.
1686 See |complete-functions| for an explanation of {expr}. It is
1687 the same as one item in the list that 'omnifunc' would return.
1688
1689 Can also be used as a |method|: >
1690 GetMoreMatches()->complete_add()
1691
1692complete_check() *complete_check()*
1693 Check for a key typed while looking for completion matches.
1694 This is to be used when looking for matches takes some time.
1695 Returns |TRUE| when searching for matches is to be aborted,
1696 zero otherwise.
1697 Only to be used by the function specified with the
1698 'completefunc' option.
1699
1700
1701complete_info([{what}]) *complete_info()*
1702 Returns a |Dictionary| with information about Insert mode
1703 completion. See |ins-completion|.
1704 The items are:
1705 mode Current completion mode name string.
1706 See |complete_info_mode| for the values.
1707 pum_visible |TRUE| if popup menu is visible.
1708 See |pumvisible()|.
1709 items List of completion matches. Each item is a
1710 dictionary containing the entries "word",
1711 "abbr", "menu", "kind", "info" and "user_data".
1712 See |complete-items|.
1713 selected Selected item index. First index is zero.
1714 Index is -1 if no item is selected (showing
1715 typed text only, or the last completion after
1716 no item is selected when using the <Up> or
1717 <Down> keys)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01001718 inserted Inserted string. [NOT IMPLEMENTED YET]
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001719
1720 *complete_info_mode*
1721 mode values are:
1722 "" Not in completion mode
1723 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1724 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1725 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1726 |i_CTRL-X_CTRL-Y|
1727 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1728 "files" File names |i_CTRL-X_CTRL-F|
1729 "tags" Tags |i_CTRL-X_CTRL-]|
1730 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1731 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1732 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1733 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1734 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1735 "function" User defined completion |i_CTRL-X_CTRL-U|
1736 "omni" Omni completion |i_CTRL-X_CTRL-O|
1737 "spell" Spelling suggestions |i_CTRL-X_s|
1738 "eval" |complete()| completion
1739 "unknown" Other internal modes
1740
1741 If the optional {what} list argument is supplied, then only
1742 the items listed in {what} are returned. Unsupported items in
1743 {what} are silently ignored.
1744
1745 To get the position and size of the popup menu, see
1746 |pum_getpos()|. It's also available in |v:event| during the
1747 |CompleteChanged| event.
1748
Bram Moolenaar016188f2022-06-06 20:52:59 +01001749 Returns an empty |Dictionary| on error.
1750
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001751 Examples: >
1752 " Get all items
1753 call complete_info()
1754 " Get only 'mode'
1755 call complete_info(['mode'])
1756 " Get only 'mode' and 'pum_visible'
1757 call complete_info(['mode', 'pum_visible'])
1758
1759< Can also be used as a |method|: >
1760 GetItems()->complete_info()
1761<
1762 *confirm()*
1763confirm({msg} [, {choices} [, {default} [, {type}]]])
1764 confirm() offers the user a dialog, from which a choice can be
1765 made. It returns the number of the choice. For the first
1766 choice this is 1.
1767 Note: confirm() is only supported when compiled with dialog
1768 support, see |+dialog_con| and |+dialog_gui|.
1769
1770 {msg} is displayed in a |dialog| with {choices} as the
1771 alternatives. When {choices} is missing or empty, "&OK" is
1772 used (and translated).
1773 {msg} is a String, use '\n' to include a newline. Only on
1774 some systems the string is wrapped when it doesn't fit.
1775
1776 {choices} is a String, with the individual choices separated
1777 by '\n', e.g. >
1778 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1779< The letter after the '&' is the shortcut key for that choice.
1780 Thus you can type 'c' to select "Cancel". The shortcut does
1781 not need to be the first letter: >
1782 confirm("file has been modified", "&Save\nSave &All")
1783< For the console, the first letter of each choice is used as
1784 the default shortcut key. Case is ignored.
1785
1786 The optional {default} argument is the number of the choice
1787 that is made if the user hits <CR>. Use 1 to make the first
1788 choice the default one. Use 0 to not set a default. If
1789 {default} is omitted, 1 is used.
1790
1791 The optional {type} String argument gives the type of dialog.
1792 This is only used for the icon of the GTK, Mac, Motif and
1793 Win32 GUI. It can be one of these values: "Error",
1794 "Question", "Info", "Warning" or "Generic". Only the first
1795 character is relevant. When {type} is omitted, "Generic" is
1796 used.
1797
1798 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1799 or another valid interrupt key, confirm() returns 0.
1800
1801 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01001802 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001803 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01001804 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001805 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001806 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001807 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001808 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001809 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01001810 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001811< In a GUI dialog, buttons are used. The layout of the buttons
1812 depends on the 'v' flag in 'guioptions'. If it is included,
1813 the buttons are always put vertically. Otherwise, confirm()
1814 tries to put the buttons in one horizontal line. If they
1815 don't fit, a vertical layout is used anyway. For some systems
1816 the horizontal layout is always used.
1817
1818 Can also be used as a |method|in: >
1819 BuildMessage()->confirm("&Yes\n&No")
1820<
1821 *copy()*
1822copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1823 different from using {expr} directly.
1824 When {expr} is a |List| a shallow copy is created. This means
1825 that the original |List| can be changed without changing the
1826 copy, and vice versa. But the items are identical, thus
1827 changing an item changes the contents of both |Lists|.
1828 A |Dictionary| is copied in a similar way as a |List|.
1829 Also see |deepcopy()|.
1830 Can also be used as a |method|: >
1831 mylist->copy()
1832
1833cos({expr}) *cos()*
1834 Return the cosine of {expr}, measured in radians, as a |Float|.
1835 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001836 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001837 Examples: >
1838 :echo cos(100)
1839< 0.862319 >
1840 :echo cos(-4.01)
1841< -0.646043
1842
1843 Can also be used as a |method|: >
1844 Compute()->cos()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001845
1846
1847cosh({expr}) *cosh()*
1848 Return the hyperbolic cosine of {expr} as a |Float| in the range
1849 [1, inf].
1850 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001851 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001852 Examples: >
1853 :echo cosh(0.5)
1854< 1.127626 >
1855 :echo cosh(-0.5)
1856< -1.127626
1857
1858 Can also be used as a |method|: >
1859 Compute()->cosh()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001860
1861
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07001862count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001863 Return the number of times an item with value {expr} appears
1864 in |String|, |List| or |Dictionary| {comp}.
1865
1866 If {start} is given then start with the item with this index.
1867 {start} can only be used with a |List|.
1868
1869 When {ic} is given and it's |TRUE| then case is ignored.
1870
1871 When {comp} is a string then the number of not overlapping
1872 occurrences of {expr} is returned. Zero is returned when
1873 {expr} is an empty string.
1874
1875 Can also be used as a |method|: >
1876 mylist->count(val)
1877<
1878 *cscope_connection()*
1879cscope_connection([{num} , {dbpath} [, {prepend}]])
1880 Checks for the existence of a |cscope| connection. If no
1881 parameters are specified, then the function returns:
1882 0, if cscope was not available (not compiled in), or
1883 if there are no cscope connections;
1884 1, if there is at least one cscope connection.
1885
1886 If parameters are specified, then the value of {num}
1887 determines how existence of a cscope connection is checked:
1888
1889 {num} Description of existence check
1890 ----- ------------------------------
1891 0 Same as no parameters (e.g., "cscope_connection()").
1892 1 Ignore {prepend}, and use partial string matches for
1893 {dbpath}.
1894 2 Ignore {prepend}, and use exact string matches for
1895 {dbpath}.
1896 3 Use {prepend}, use partial string matches for both
1897 {dbpath} and {prepend}.
1898 4 Use {prepend}, use exact string matches for both
1899 {dbpath} and {prepend}.
1900
1901 Note: All string comparisons are case sensitive!
1902
1903 Examples. Suppose we had the following (from ":cs show"): >
1904
1905 # pid database name prepend path
1906 0 27664 cscope.out /usr/local
1907<
1908 Invocation Return Val ~
1909 ---------- ---------- >
1910 cscope_connection() 1
1911 cscope_connection(1, "out") 1
1912 cscope_connection(2, "out") 0
1913 cscope_connection(3, "out") 0
1914 cscope_connection(3, "out", "local") 1
1915 cscope_connection(4, "out") 0
1916 cscope_connection(4, "out", "local") 0
1917 cscope_connection(4, "cscope.out", "/usr/local") 1
1918<
1919cursor({lnum}, {col} [, {off}]) *cursor()*
1920cursor({list})
1921 Positions the cursor at the column (byte count) {col} in the
1922 line {lnum}. The first column is one.
1923
1924 When there is one argument {list} this is used as a |List|
1925 with two, three or four item:
1926 [{lnum}, {col}]
1927 [{lnum}, {col}, {off}]
1928 [{lnum}, {col}, {off}, {curswant}]
1929 This is like the return value of |getpos()| or |getcurpos()|,
1930 but without the first item.
1931
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001932 To position the cursor using {col} as the character count, use
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001933 |setcursorcharpos()|.
1934
1935 Does not change the jumplist.
Bram Moolenaar7c6cd442022-10-11 21:54:04 +01001936 {lnum} is used like with |getline()|, except that if {lnum} is
1937 zero, the cursor will stay in the current line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001938 If {lnum} is greater than the number of lines in the buffer,
1939 the cursor will be positioned at the last line in the buffer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001940 If {col} is greater than the number of bytes in the line,
1941 the cursor will be positioned at the last character in the
1942 line.
1943 If {col} is zero, the cursor will stay in the current column.
1944 If {curswant} is given it is used to set the preferred column
1945 for vertical movement. Otherwise {col} is used.
1946
1947 When 'virtualedit' is used {off} specifies the offset in
1948 screen columns from the start of the character. E.g., a
1949 position within a <Tab> or after the last character.
1950 Returns 0 when the position could be set, -1 otherwise.
1951
1952 Can also be used as a |method|: >
1953 GetCursorPos()->cursor()
1954
1955debugbreak({pid}) *debugbreak()*
1956 Specifically used to interrupt a program being debugged. It
1957 will cause process {pid} to get a SIGTRAP. Behavior for other
1958 processes is undefined. See |terminal-debugger|.
1959 {only available on MS-Windows}
1960
Bram Moolenaar016188f2022-06-06 20:52:59 +01001961 Returns |TRUE| if successfully interrupted the program.
1962 Otherwise returns |FALSE|.
1963
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001964 Can also be used as a |method|: >
1965 GetPid()->debugbreak()
1966
1967deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
1968 Make a copy of {expr}. For Numbers and Strings this isn't
1969 different from using {expr} directly.
1970 When {expr} is a |List| a full copy is created. This means
1971 that the original |List| can be changed without changing the
1972 copy, and vice versa. When an item is a |List| or
1973 |Dictionary|, a copy for it is made, recursively. Thus
1974 changing an item in the copy does not change the contents of
1975 the original |List|.
1976 A |Dictionary| is copied in a similar way as a |List|.
1977
1978 When {noref} is omitted or zero a contained |List| or
1979 |Dictionary| is only copied once. All references point to
1980 this single copy. With {noref} set to 1 every occurrence of a
1981 |List| or |Dictionary| results in a new copy. This also means
1982 that a cyclic reference causes deepcopy() to fail.
1983 *E724*
1984 Nesting is possible up to 100 levels. When there is an item
1985 that refers back to a higher level making a deep copy with
1986 {noref} set to 1 will fail.
1987 Also see |copy()|.
1988
1989 Can also be used as a |method|: >
1990 GetObject()->deepcopy()
1991
1992delete({fname} [, {flags}]) *delete()*
1993 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001994 name {fname}.
1995
1996 This also works when {fname} is a symbolic link. The symbolic
1997 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001998
1999 When {flags} is "d": Deletes the directory by the name
2000 {fname}. This fails when directory {fname} is not empty.
2001
2002 When {flags} is "rf": Deletes the directory by the name
2003 {fname} and everything in it, recursively. BE CAREFUL!
2004 Note: on MS-Windows it is not possible to delete a directory
2005 that is being used.
2006
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002007 The result is a Number, which is 0/false if the delete
2008 operation was successful and -1/true when the deletion failed
2009 or partly failed.
2010
2011 Use |remove()| to delete an item from a |List|.
2012 To delete a line from the buffer use |:delete| or
2013 |deletebufline()|.
2014
2015 Can also be used as a |method|: >
2016 GetName()->delete()
2017
2018deletebufline({buf}, {first} [, {last}]) *deletebufline()*
2019 Delete lines {first} to {last} (inclusive) from buffer {buf}.
2020 If {last} is omitted then delete line {first} only.
2021 On success 0 is returned, on failure 1 is returned.
2022
2023 This function works only for loaded buffers. First call
2024 |bufload()| if needed.
2025
2026 For the use of {buf}, see |bufname()| above.
2027
2028 {first} and {last} are used like with |getline()|. Note that
2029 when using |line()| this refers to the current buffer. Use "$"
2030 to refer to the last line in buffer {buf}.
2031
2032 Can also be used as a |method|: >
2033 GetBuffer()->deletebufline(1)
2034<
2035 *did_filetype()*
2036did_filetype() Returns |TRUE| when autocommands are being executed and the
2037 FileType event has been triggered at least once. Can be used
2038 to avoid triggering the FileType event again in the scripts
2039 that detect the file type. |FileType|
2040 Returns |FALSE| when `:setf FALLBACK` was used.
2041 When editing another file, the counter is reset, thus this
2042 really checks if the FileType event has been triggered for the
2043 current buffer. This allows an autocommand that starts
2044 editing another buffer to set 'filetype' and load a syntax
2045 file.
2046
2047diff_filler({lnum}) *diff_filler()*
2048 Returns the number of filler lines above line {lnum}.
2049 These are the lines that were inserted at this point in
2050 another diff'ed window. These filler lines are shown in the
2051 display but don't exist in the buffer.
2052 {lnum} is used like with |getline()|. Thus "." is the current
2053 line, "'m" mark m, etc.
2054 Returns 0 if the current window is not in diff mode.
2055
2056 Can also be used as a |method|: >
2057 GetLnum()->diff_filler()
2058
2059diff_hlID({lnum}, {col}) *diff_hlID()*
2060 Returns the highlight ID for diff mode at line {lnum} column
2061 {col} (byte index). When the current line does not have a
2062 diff change zero is returned.
2063 {lnum} is used like with |getline()|. Thus "." is the current
2064 line, "'m" mark m, etc.
2065 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2066 line.
2067 The highlight ID can be used with |synIDattr()| to obtain
2068 syntax information about the highlighting.
2069
2070 Can also be used as a |method|: >
2071 GetLnum()->diff_hlID(col)
2072<
2073
2074digraph_get({chars}) *digraph_get()* *E1214*
2075 Return the digraph of {chars}. This should be a string with
2076 exactly two characters. If {chars} are not just two
2077 characters, or the digraph of {chars} does not exist, an error
2078 is given and an empty string is returned.
2079
2080 The character will be converted from Unicode to 'encoding'
2081 when needed. This does require the conversion to be
2082 available, it might fail.
2083
2084 Also see |digraph_getlist()|.
2085
2086 Examples: >
2087 " Get a built-in digraph
2088 :echo digraph_get('00') " Returns '∞'
2089
2090 " Get a user-defined digraph
2091 :call digraph_set('aa', 'あ')
2092 :echo digraph_get('aa') " Returns 'あ'
2093<
2094 Can also be used as a |method|: >
2095 GetChars()->digraph_get()
2096<
2097 This function works only when compiled with the |+digraphs|
2098 feature. If this feature is disabled, this function will
2099 display an error message.
2100
2101
2102digraph_getlist([{listall}]) *digraph_getlist()*
2103 Return a list of digraphs. If the {listall} argument is given
2104 and it is TRUE, return all digraphs, including the default
2105 digraphs. Otherwise, return only user-defined digraphs.
2106
2107 The characters will be converted from Unicode to 'encoding'
2108 when needed. This does require the conservation to be
2109 available, it might fail.
2110
2111 Also see |digraph_get()|.
2112
2113 Examples: >
2114 " Get user-defined digraphs
2115 :echo digraph_getlist()
2116
2117 " Get all the digraphs, including default digraphs
2118 :echo digraph_getlist(1)
2119<
2120 Can also be used as a |method|: >
2121 GetNumber()->digraph_getlist()
2122<
2123 This function works only when compiled with the |+digraphs|
2124 feature. If this feature is disabled, this function will
2125 display an error message.
2126
2127
Bram Moolenaara2baa732022-02-04 16:09:54 +00002128digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002129 Add digraph {chars} to the list. {chars} must be a string
2130 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002131 encoded character. *E1215*
2132 Be careful, composing characters are NOT ignored. This
2133 function is similar to |:digraphs| command, but useful to add
2134 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002135
2136 The function result is v:true if |digraph| is registered. If
2137 this fails an error message is given and v:false is returned.
2138
2139 If you want to define multiple digraphs at once, you can use
2140 |digraph_setlist()|.
2141
2142 Example: >
2143 call digraph_set(' ', 'あ')
2144<
2145 Can be used as a |method|: >
2146 GetString()->digraph_set('あ')
2147<
2148 This function works only when compiled with the |+digraphs|
2149 feature. If this feature is disabled, this function will
2150 display an error message.
2151
2152
2153digraph_setlist({digraphlist}) *digraph_setlist()*
2154 Similar to |digraph_set()| but this function can add multiple
2155 digraphs at once. {digraphlist} is a list composed of lists,
2156 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002157 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002158 Example: >
2159 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2160<
2161 It is similar to the following: >
2162 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2163 call digraph_set(chars, digraph)
2164 endfor
2165< Except that the function returns after the first error,
2166 following digraphs will not be added.
2167
2168 Can be used as a |method|: >
2169 GetList()->digraph_setlist()
2170<
2171 This function works only when compiled with the |+digraphs|
2172 feature. If this feature is disabled, this function will
2173 display an error message.
2174
2175
2176echoraw({string}) *echoraw()*
2177 Output {string} as-is, including unprintable characters.
2178 This can be used to output a terminal code. For example, to
2179 disable modifyOtherKeys: >
2180 call echoraw(&t_TE)
2181< and to enable it again: >
2182 call echoraw(&t_TI)
2183< Use with care, you can mess up the terminal this way.
2184
2185
2186empty({expr}) *empty()*
2187 Return the Number 1 if {expr} is empty, zero otherwise.
2188 - A |List| or |Dictionary| is empty when it does not have any
2189 items.
2190 - A |String| is empty when its length is zero.
2191 - A |Number| and |Float| are empty when their value is zero.
2192 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2193 - A |Job| is empty when it failed to start.
2194 - A |Channel| is empty when it is closed.
2195 - A |Blob| is empty when its length is zero.
2196
2197 For a long |List| this is much faster than comparing the
2198 length with zero.
2199
2200 Can also be used as a |method|: >
2201 mylist->empty()
2202
2203environ() *environ()*
2204 Return all of environment variables as dictionary. You can
2205 check if an environment variable exists like this: >
2206 :echo has_key(environ(), 'HOME')
2207< Note that the variable name may be CamelCase; to ignore case
2208 use this: >
2209 :echo index(keys(environ()), 'HOME', 0, 1) != -1
2210
Bram Moolenaar416bd912023-07-07 23:19:18 +01002211
2212err_teapot([{expr}]) *err_teapot()*
2213 Produce an error with number 418, needed for implementation of
Christian Brabandtee17b6f2023-09-09 11:23:50 +02002214 RFC 2324.
Bram Moolenaar416bd912023-07-07 23:19:18 +01002215 If {expr} is present and it is TRUE error 503 is given,
2216 indicating that coffee is temporarily not available.
2217 If {expr} is present it must be a String.
2218
2219
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002220escape({string}, {chars}) *escape()*
2221 Escape the characters in {chars} that occur in {string} with a
2222 backslash. Example: >
2223 :echo escape('c:\program files\vim', ' \')
2224< results in: >
2225 c:\\program\ files\\vim
2226< Also see |shellescape()| and |fnameescape()|.
2227
2228 Can also be used as a |method|: >
2229 GetText()->escape(' \')
2230<
2231 *eval()*
2232eval({string}) Evaluate {string} and return the result. Especially useful to
2233 turn the result of |string()| back into the original value.
2234 This works for Numbers, Floats, Strings, Blobs and composites
2235 of them. Also works for |Funcref|s that refer to existing
2236 functions.
2237
2238 Can also be used as a |method|: >
2239 argv->join()->eval()
2240
2241eventhandler() *eventhandler()*
2242 Returns 1 when inside an event handler. That is that Vim got
2243 interrupted while waiting for the user to type a character,
2244 e.g., when dropping a file on Vim. This means interactive
2245 commands cannot be used. Otherwise zero is returned.
2246
2247executable({expr}) *executable()*
2248 This function checks if an executable with the name {expr}
2249 exists. {expr} must be the name of the program without any
2250 arguments.
2251 executable() uses the value of $PATH and/or the normal
2252 searchpath for programs. *PATHEXT*
2253 On MS-Windows the ".exe", ".bat", etc. can optionally be
2254 included. Then the extensions in $PATHEXT are tried. Thus if
2255 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2256 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2257 by itself can be used in $PATHEXT to try using the name
2258 without an extension. When 'shell' looks like a Unix shell,
2259 then the name is also tried without adding an extension.
2260 On MS-Windows it only checks if the file exists and is not a
2261 directory, not if it's really executable.
2262 On MS-Windows an executable in the same directory as Vim is
Yasuhiro Matsumoto05cf63e2022-05-03 11:02:28 +01002263 normally found. Since this directory is added to $PATH it
2264 should also work to execute it |win32-PATH|. This can be
2265 disabled by setting the $NoDefaultCurrentDirectoryInExePath
2266 environment variable. *NoDefaultCurrentDirectoryInExePath*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002267 The result is a Number:
2268 1 exists
2269 0 does not exist
2270 -1 not implemented on this system
2271 |exepath()| can be used to get the full path of an executable.
2272
2273 Can also be used as a |method|: >
2274 GetCommand()->executable()
2275
2276execute({command} [, {silent}]) *execute()*
2277 Execute an Ex command or commands and return the output as a
2278 string.
2279 {command} can be a string or a List. In case of a List the
2280 lines are executed one by one.
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002281 This is more or less equivalent to: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002282 redir => var
2283 {command}
2284 redir END
Bram Moolenaar71badf92023-04-22 22:40:14 +01002285< Except that line continuation in {command} is not recognized.
2286
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002287 The optional {silent} argument can have these values:
2288 "" no `:silent` used
2289 "silent" `:silent` used
2290 "silent!" `:silent!` used
2291 The default is "silent". Note that with "silent!", unlike
2292 `:redir`, error messages are dropped. When using an external
2293 command the screen may be messed up, use `system()` instead.
2294 *E930*
2295 It is not possible to use `:redir` anywhere in {command}.
2296
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002297 To get a list of lines use `split()` on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002298 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002299
2300< To execute a command in another window than the current one
2301 use `win_execute()`.
2302
2303 When used recursively the output of the recursive call is not
2304 included in the output of the higher level call.
2305
2306 Can also be used as a |method|: >
2307 GetCommand()->execute()
2308
2309exepath({expr}) *exepath()*
2310 If {expr} is an executable and is either an absolute path, a
2311 relative path or found in $PATH, return the full path.
2312 Note that the current directory is used when {expr} starts
2313 with "./", which may be a problem for Vim: >
2314 echo exepath(v:progpath)
2315< If {expr} cannot be found in $PATH or is not executable then
2316 an empty string is returned.
2317
2318 Can also be used as a |method|: >
2319 GetCommand()->exepath()
2320<
2321 *exists()*
2322exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
2323 zero otherwise.
2324
2325 Note: In a compiled |:def| function the evaluation is done at
2326 runtime. Use `exists_compiled()` to evaluate the expression
2327 at compile time.
2328
2329 For checking for a supported feature use |has()|.
2330 For checking if a file exists use |filereadable()|.
2331
2332 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002333 varname internal variable (see
2334 dict.key |internal-variables|). Also works
2335 list[i] for |curly-braces-names|, |Dictionary|
2336 import.Func entries, |List| items, imported
Bram Moolenaar944697a2022-02-20 19:48:20 +00002337 items, etc.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002338 Does not work for local variables in a
2339 compiled `:def` function.
Bram Moolenaar944697a2022-02-20 19:48:20 +00002340 Also works for a function in |Vim9|
2341 script, since it can be used as a
2342 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002343 Beware that evaluating an index may
2344 cause an error message for an invalid
2345 expression. E.g.: >
2346 :let l = [1, 2, 3]
2347 :echo exists("l[5]")
2348< 0 >
2349 :echo exists("l[xx]")
2350< E121: Undefined variable: xx
2351 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002352 &option-name Vim option (only checks if it exists,
2353 not if it really works)
2354 +option-name Vim option that works.
2355 $ENVNAME environment variable (could also be
2356 done by comparing with an empty
2357 string)
2358 *funcname built-in function (see |functions|)
2359 or user defined function (see
2360 |user-functions|) that is implemented.
2361 Also works for a variable that is a
2362 Funcref.
2363 ?funcname built-in function that could be
2364 implemented; to be used to check if
2365 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002366 :cmdname Ex command: built-in command, user
2367 command or command modifier |:command|.
2368 Returns:
2369 1 for match with start of a command
2370 2 full match with a command
2371 3 matches several user commands
2372 To check for a supported command
2373 always check the return value to be 2.
2374 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002375 :3match The |:3match| command (but you
2376 probably should not use it, it is
2377 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002378 #event autocommand defined for this event
2379 #event#pattern autocommand defined for this event and
2380 pattern (the pattern is taken
2381 literally and compared to the
2382 autocommand patterns character by
2383 character)
2384 #group autocommand group exists
2385 #group#event autocommand defined for this group and
2386 event.
2387 #group#event#pattern
2388 autocommand defined for this group,
2389 event and pattern.
2390 ##event autocommand for this event is
2391 supported.
2392
2393 Examples: >
2394 exists("&shortname")
2395 exists("$HOSTNAME")
2396 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002397 exists("*s:MyFunc") " only for legacy script
2398 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002399 exists("bufcount")
2400 exists(":Make")
2401 exists("#CursorHold")
2402 exists("#BufReadPre#*.gz")
2403 exists("#filetypeindent")
2404 exists("#filetypeindent#FileType")
2405 exists("#filetypeindent#FileType#*")
2406 exists("##ColorScheme")
2407< There must be no space between the symbol (&/$/*/#) and the
2408 name.
2409 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002410 a few cases this is ignored. That may become stricter in the
2411 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002412 Working example: >
2413 exists(":make")
2414< NOT working example: >
2415 exists(":make install")
2416
2417< Note that the argument must be a string, not the name of the
2418 variable itself. For example: >
2419 exists(bufcount)
2420< This doesn't check for existence of the "bufcount" variable,
2421 but gets the value of "bufcount", and checks if that exists.
2422
2423 Can also be used as a |method|: >
2424 Varname()->exists()
2425<
2426
2427exists_compiled({expr}) *exists_compiled()*
2428 Like `exists()` but evaluated at compile time. This is useful
2429 to skip a block where a function is used that would otherwise
2430 give an error: >
2431 if exists_compiled('*ThatFunction')
2432 ThatFunction('works')
2433 endif
2434< If `exists()` were used then a compilation error would be
2435 given if ThatFunction() is not defined.
2436
2437 {expr} must be a literal string. *E1232*
2438 Can only be used in a |:def| function. *E1233*
2439 This does not work to check for arguments or local variables.
2440
2441
2442exp({expr}) *exp()*
2443 Return the exponential of {expr} as a |Float| in the range
2444 [0, inf].
2445 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002446 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002447 Examples: >
2448 :echo exp(2)
2449< 7.389056 >
2450 :echo exp(-1)
2451< 0.367879
2452
2453 Can also be used as a |method|: >
2454 Compute()->exp()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002455
2456
2457expand({string} [, {nosuf} [, {list}]]) *expand()*
2458 Expand wildcards and the following special keywords in
2459 {string}. 'wildignorecase' applies.
2460
2461 If {list} is given and it is |TRUE|, a List will be returned.
2462 Otherwise the result is a String and when there are several
2463 matches, they are separated by <NL> characters. [Note: in
2464 version 5.0 a space was used, which caused problems when a
2465 file name contains a space]
2466
2467 If the expansion fails, the result is an empty string. A name
2468 for a non-existing file is not included, unless {string} does
2469 not start with '%', '#' or '<', see below.
2470
2471 When {string} starts with '%', '#' or '<', the expansion is
2472 done like for the |cmdline-special| variables with their
2473 associated modifiers. Here is a short overview:
2474
2475 % current file name
2476 # alternate file name
2477 #n alternate file name n
2478 <cfile> file name under the cursor
2479 <afile> autocmd file name
2480 <abuf> autocmd buffer number (as a String!)
2481 <amatch> autocmd matched name
2482 <cexpr> C expression under the cursor
2483 <sfile> sourced script file or function name
2484 <slnum> sourced script line number or function
2485 line number
2486 <sflnum> script file line number, also when in
2487 a function
2488 <SID> "<SNR>123_" where "123" is the
2489 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002490 <script> sourced script file, or script file
2491 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002492 <stack> call stack
2493 <cword> word under the cursor
2494 <cWORD> WORD under the cursor
2495 <client> the {clientid} of the last received
2496 message |server2client()|
2497 Modifiers:
2498 :p expand to full path
2499 :h head (last path component removed)
2500 :t tail (last path component only)
2501 :r root (one extension removed)
2502 :e extension only
2503
2504 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002505 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002506< Note that when expanding a string that starts with '%', '#' or
2507 '<', any following text is ignored. This does NOT work: >
2508 :let doesntwork = expand("%:h.bak")
2509< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002510 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002511< Also note that expanding "<cfile>" and others only returns the
2512 referenced file name without further expansion. If "<cfile>"
2513 is "~/.cshrc", you need to do another expand() to have the
2514 "~/" expanded into the path of the home directory: >
2515 :echo expand(expand("<cfile>"))
2516<
2517 There cannot be white space between the variables and the
2518 following modifier. The |fnamemodify()| function can be used
2519 to modify normal file names.
2520
2521 When using '%' or '#', and the current or alternate file name
2522 is not defined, an empty string is used. Using "%:p" in a
2523 buffer with no name, results in the current directory, with a
2524 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01002525 When 'verbose' is set then expanding '%', '#' and <> items
2526 will result in an error message if the argument cannot be
2527 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002528
2529 When {string} does not start with '%', '#' or '<', it is
2530 expanded like a file name is expanded on the command line.
2531 'suffixes' and 'wildignore' are used, unless the optional
2532 {nosuf} argument is given and it is |TRUE|.
2533 Names for non-existing files are included. The "**" item can
2534 be used to search in a directory tree. For example, to find
2535 all "README" files in the current directory and below: >
2536 :echo expand("**/README")
2537<
2538 expand() can also be used to expand variables and environment
2539 variables that are only known in a shell. But this can be
2540 slow, because a shell may be used to do the expansion. See
2541 |expr-env-expand|.
2542 The expanded variable is still handled like a list of file
2543 names. When an environment variable cannot be expanded, it is
2544 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2545 "$FOOBAR".
2546
2547 See |glob()| for finding existing files. See |system()| for
2548 getting the raw output of an external command.
2549
2550 Can also be used as a |method|: >
2551 Getpattern()->expand()
2552
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002553expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002554 Expand special items in String {string} like what is done for
2555 an Ex command such as `:edit`. This expands special keywords,
2556 like with |expand()|, and environment variables, anywhere in
2557 {string}. "~user" and "~/path" are only expanded at the
2558 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002559
2560 The following items are supported in the {options} Dict
2561 argument:
2562 errmsg If set to TRUE, error messages are displayed
2563 if an error is encountered during expansion.
2564 By default, error messages are not displayed.
2565
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002566 Returns the expanded string. If an error is encountered
2567 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002568
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002569 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002570 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002571 make /path/runtime/doc/builtin.o
2572 :echo expandcmd('make %<.o', {'errmsg': v:true})
2573<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002574 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002575 GetCommand()->expandcmd()
2576<
2577extend({expr1}, {expr2} [, {expr3}]) *extend()*
2578 {expr1} and {expr2} must be both |Lists| or both
2579 |Dictionaries|.
2580
2581 If they are |Lists|: Append {expr2} to {expr1}.
2582 If {expr3} is given insert the items of {expr2} before the
2583 item with index {expr3} in {expr1}. When {expr3} is zero
2584 insert before the first item. When {expr3} is equal to
2585 len({expr1}) then {expr2} is appended.
2586 Examples: >
2587 :echo sort(extend(mylist, [7, 5]))
2588 :call extend(mylist, [2, 3], 1)
2589< When {expr1} is the same List as {expr2} then the number of
2590 items copied is equal to the original length of the List.
2591 E.g., when {expr3} is 1 you get N new copies of the first item
2592 (where N is the original length of the List).
2593 Use |add()| to concatenate one item to a list. To concatenate
2594 two lists into a new list use the + operator: >
2595 :let newlist = [1, 2, 3] + [4, 5]
2596<
2597 If they are |Dictionaries|:
2598 Add all entries from {expr2} to {expr1}.
2599 If a key exists in both {expr1} and {expr2} then {expr3} is
2600 used to decide what to do:
2601 {expr3} = "keep": keep the value of {expr1}
2602 {expr3} = "force": use the value of {expr2}
2603 {expr3} = "error": give an error message *E737*
2604 When {expr3} is omitted then "force" is assumed.
2605
2606 {expr1} is changed when {expr2} is not empty. If necessary
2607 make a copy of {expr1} first.
2608 {expr2} remains unchanged.
2609 When {expr1} is locked and {expr2} is not empty the operation
2610 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002611 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002612
2613 Can also be used as a |method|: >
2614 mylist->extend(otherlist)
2615
2616
2617extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2618 Like |extend()| but instead of adding items to {expr1} a new
2619 List or Dictionary is created and returned. {expr1} remains
Bram Moolenaardd60c362023-02-27 15:49:53 +00002620 unchanged.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002621
2622
2623feedkeys({string} [, {mode}]) *feedkeys()*
2624 Characters in {string} are queued for processing as if they
2625 come from a mapping or were typed by the user.
2626
2627 By default the string is added to the end of the typeahead
2628 buffer, thus if a mapping is still being executed the
2629 characters come after them. Use the 'i' flag to insert before
2630 other characters, they will be executed next, before any
2631 characters from a mapping.
2632
2633 The function does not wait for processing of keys contained in
2634 {string}.
2635
2636 To include special keys into {string}, use double-quotes
2637 and "\..." notation |expr-quote|. For example,
2638 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2639 feedkeys('\<CR>') pushes 5 characters.
2640 A special code that might be useful is <Ignore>, it exits the
2641 wait for a character without doing anything. *<Ignore>*
2642
2643 {mode} is a String, which can contain these character flags:
2644 'm' Remap keys. This is default. If {mode} is absent,
2645 keys are remapped.
2646 'n' Do not remap keys.
2647 't' Handle keys as if typed; otherwise they are handled as
2648 if coming from a mapping. This matters for undo,
2649 opening folds, etc.
2650 'L' Lowlevel input. Only works for Unix or when using the
2651 GUI. Keys are used as if they were coming from the
2652 terminal. Other flags are not used. *E980*
2653 When a CTRL-C interrupts and 't' is included it sets
2654 the internal "got_int" flag.
2655 'i' Insert the string instead of appending (see above).
2656 'x' Execute commands until typeahead is empty. This is
2657 similar to using ":normal!". You can call feedkeys()
2658 several times without 'x' and then one time with 'x'
2659 (possibly with an empty {string}) to execute all the
2660 typeahead. Note that when Vim ends in Insert mode it
2661 will behave as if <Esc> is typed, to avoid getting
2662 stuck, waiting for a character to be typed before the
2663 script continues.
2664 Note that if you manage to call feedkeys() while
2665 executing commands, thus calling it recursively, then
2666 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00002667 'c' Remove any script context when executing, so that
2668 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01002669 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01002670 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002671 '!' When used with 'x' will not end Insert mode. Can be
2672 used in a test when a timer is set to exit Insert mode
2673 a little later. Useful for testing CursorHoldI.
2674
2675 Return value is always 0.
2676
2677 Can also be used as a |method|: >
2678 GetInput()->feedkeys()
2679
2680filereadable({file}) *filereadable()*
2681 The result is a Number, which is |TRUE| when a file with the
2682 name {file} exists, and can be read. If {file} doesn't exist,
2683 or is a directory, the result is |FALSE|. {file} is any
2684 expression, which is used as a String.
2685 If you don't care about the file being readable you can use
2686 |glob()|.
2687 {file} is used as-is, you may want to expand wildcards first: >
2688 echo filereadable('~/.vimrc')
2689 0
2690 echo filereadable(expand('~/.vimrc'))
2691 1
2692
2693< Can also be used as a |method|: >
2694 GetName()->filereadable()
2695< *file_readable()*
2696 Obsolete name: file_readable().
2697
2698
2699filewritable({file}) *filewritable()*
2700 The result is a Number, which is 1 when a file with the
2701 name {file} exists, and can be written. If {file} doesn't
2702 exist, or is not writable, the result is 0. If {file} is a
2703 directory, and we can write to it, the result is 2.
2704
2705 Can also be used as a |method|: >
2706 GetName()->filewritable()
2707
2708
2709filter({expr1}, {expr2}) *filter()*
2710 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
2711 For each item in {expr1} evaluate {expr2} and when the result
2712 is zero or false remove the item from the |List| or
2713 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002714 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002715
2716 {expr2} must be a |string| or |Funcref|.
2717
2718 If {expr2} is a |string|, inside {expr2} |v:val| has the value
2719 of the current item. For a |Dictionary| |v:key| has the key
2720 of the current item and for a |List| |v:key| has the index of
2721 the current item. For a |Blob| |v:key| has the index of the
2722 current byte. For a |String| |v:key| has the index of the
2723 current character.
2724 Examples: >
2725 call filter(mylist, 'v:val !~ "OLD"')
2726< Removes the items where "OLD" appears. >
2727 call filter(mydict, 'v:key >= 8')
2728< Removes the items with a key below 8. >
2729 call filter(var, 0)
2730< Removes all the items, thus clears the |List| or |Dictionary|.
2731
2732 Note that {expr2} is the result of expression and is then
2733 used as an expression again. Often it is good to use a
2734 |literal-string| to avoid having to double backslashes.
2735
2736 If {expr2} is a |Funcref| it must take two arguments:
2737 1. the key or the index of the current item.
2738 2. the value of the current item.
2739 The function must return |TRUE| if the item should be kept.
2740 Example that keeps the odd items of a list: >
2741 func Odd(idx, val)
2742 return a:idx % 2 == 1
2743 endfunc
2744 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002745< It is shorter when using a |lambda|. In |Vim9| syntax: >
2746 call filter(myList, (idx, val) => idx * val <= 42)
2747< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002748 call filter(myList, {idx, val -> idx * val <= 42})
2749< If you do not use "val" you can leave it out: >
2750 call filter(myList, {idx -> idx % 2 == 1})
2751<
2752 In |Vim9| script the result must be true, false, zero or one.
2753 Other values will result in a type error.
2754
2755 For a |List| and a |Dictionary| the operation is done
2756 in-place. If you want it to remain unmodified make a copy
2757 first: >
2758 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2759
2760< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00002761 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002762 When an error is encountered while evaluating {expr2} no
2763 further items in {expr1} are processed.
2764 When {expr2} is a Funcref errors inside a function are ignored,
2765 unless it was defined with the "abort" flag.
2766
2767 Can also be used as a |method|: >
2768 mylist->filter(expr2)
2769
2770finddir({name} [, {path} [, {count}]]) *finddir()*
2771 Find directory {name} in {path}. Supports both downwards and
2772 upwards recursive directory searches. See |file-searching|
2773 for the syntax of {path}.
2774
2775 Returns the path of the first found match. When the found
2776 directory is below the current directory a relative path is
2777 returned. Otherwise a full path is returned.
2778 If {path} is omitted or empty then 'path' is used.
2779
2780 If the optional {count} is given, find {count}'s occurrence of
2781 {name} in {path} instead of the first one.
2782 When {count} is negative return all the matches in a |List|.
2783
Bram Moolenaar016188f2022-06-06 20:52:59 +01002784 Returns an empty string if the directory is not found.
2785
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002786 This is quite similar to the ex-command `:find`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002787
2788 Can also be used as a |method|: >
2789 GetName()->finddir()
2790
2791findfile({name} [, {path} [, {count}]]) *findfile()*
2792 Just like |finddir()|, but find a file instead of a directory.
2793 Uses 'suffixesadd'.
2794 Example: >
2795 :echo findfile("tags.vim", ".;")
2796< Searches from the directory of the current file upwards until
2797 it finds the file "tags.vim".
2798
2799 Can also be used as a |method|: >
2800 GetName()->findfile()
2801
2802flatten({list} [, {maxdepth}]) *flatten()*
2803 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
2804 the result is a |List| without nesting, as if {maxdepth} is
2805 a very large number.
2806 The {list} is changed in place, use |flattennew()| if you do
2807 not want that.
2808 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00002809 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002810 *E900*
2811 {maxdepth} means how deep in nested lists changes are made.
2812 {list} is not modified when {maxdepth} is 0.
2813 {maxdepth} must be positive number.
2814
2815 If there is an error the number zero is returned.
2816
2817 Example: >
2818 :echo flatten([1, [2, [3, 4]], 5])
2819< [1, 2, 3, 4, 5] >
2820 :echo flatten([1, [2, [3, 4]], 5], 1)
2821< [1, 2, [3, 4], 5]
2822
2823 Can also be used as a |method|: >
2824 mylist->flatten()
2825<
2826flattennew({list} [, {maxdepth}]) *flattennew()*
2827 Like |flatten()| but first make a copy of {list}.
2828
2829
2830float2nr({expr}) *float2nr()*
2831 Convert {expr} to a Number by omitting the part after the
2832 decimal point.
Bram Moolenaar76db9e02022-11-09 21:21:04 +00002833 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002834 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002835 When the value of {expr} is out of range for a |Number| the
2836 result is truncated to 0x7fffffff or -0x7fffffff (or when
2837 64-bit Number support is enabled, 0x7fffffffffffffff or
2838 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
2839 64-bit Number support is enabled, -0x8000000000000000).
2840 Examples: >
2841 echo float2nr(3.95)
2842< 3 >
2843 echo float2nr(-23.45)
2844< -23 >
2845 echo float2nr(1.0e100)
2846< 2147483647 (or 9223372036854775807) >
2847 echo float2nr(-1.0e150)
2848< -2147483647 (or -9223372036854775807) >
2849 echo float2nr(1.0e-100)
2850< 0
2851
2852 Can also be used as a |method|: >
2853 Compute()->float2nr()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002854
2855
2856floor({expr}) *floor()*
2857 Return the largest integral value less than or equal to
2858 {expr} as a |Float| (round down).
2859 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002860 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002861 Examples: >
2862 echo floor(1.856)
2863< 1.0 >
2864 echo floor(-5.456)
2865< -6.0 >
2866 echo floor(4.0)
2867< 4.0
2868
2869 Can also be used as a |method|: >
2870 Compute()->floor()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002871
2872
2873fmod({expr1}, {expr2}) *fmod()*
2874 Return the remainder of {expr1} / {expr2}, even if the
2875 division is not representable. Returns {expr1} - i * {expr2}
2876 for some integer i such that if {expr2} is non-zero, the
2877 result has the same sign as {expr1} and magnitude less than
2878 the magnitude of {expr2}. If {expr2} is zero, the value
2879 returned is zero. The value returned is a |Float|.
2880 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002881 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
2882 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002883 Examples: >
2884 :echo fmod(12.33, 1.22)
2885< 0.13 >
2886 :echo fmod(-12.33, 1.22)
2887< -0.13
2888
2889 Can also be used as a |method|: >
2890 Compute()->fmod(1.22)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002891
2892
2893fnameescape({string}) *fnameescape()*
2894 Escape {string} for use as file name command argument. All
2895 characters that have a special meaning, such as '%' and '|'
2896 are escaped with a backslash.
2897 For most systems the characters escaped are
2898 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2899 appears in a filename, it depends on the value of 'isfname'.
2900 A leading '+' and '>' is also escaped (special after |:edit|
2901 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01002902 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002903 Example: >
2904 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002905 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002906< results in executing: >
2907 edit \+some\ str\%nge\|name
2908<
2909 Can also be used as a |method|: >
2910 GetName()->fnameescape()
2911
2912fnamemodify({fname}, {mods}) *fnamemodify()*
2913 Modify file name {fname} according to {mods}. {mods} is a
2914 string of characters like it is used for file names on the
2915 command line. See |filename-modifiers|.
2916 Example: >
2917 :echo fnamemodify("main.c", ":p:h")
2918< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01002919 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01002920< If {mods} is empty or an unsupported modifier is used then
2921 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01002922 When {fname} is empty then with {mods} ":h" returns ".", so
2923 that `:cd` can be used with it. This is different from
2924 expand('%:h') without a buffer name, which returns an empty
2925 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002926 Note: Environment variables don't work in {fname}, use
2927 |expand()| first then.
2928
2929 Can also be used as a |method|: >
2930 GetName()->fnamemodify(':p:h')
2931
2932foldclosed({lnum}) *foldclosed()*
2933 The result is a Number. If the line {lnum} is in a closed
2934 fold, the result is the number of the first line in that fold.
2935 If the line {lnum} is not in a closed fold, -1 is returned.
2936 {lnum} is used like with |getline()|. Thus "." is the current
2937 line, "'m" mark m, etc.
2938
2939 Can also be used as a |method|: >
2940 GetLnum()->foldclosed()
2941
2942foldclosedend({lnum}) *foldclosedend()*
2943 The result is a Number. If the line {lnum} is in a closed
2944 fold, the result is the number of the last line in that fold.
2945 If the line {lnum} is not in a closed fold, -1 is returned.
2946 {lnum} is used like with |getline()|. Thus "." is the current
2947 line, "'m" mark m, etc.
2948
2949 Can also be used as a |method|: >
2950 GetLnum()->foldclosedend()
2951
2952foldlevel({lnum}) *foldlevel()*
2953 The result is a Number, which is the foldlevel of line {lnum}
2954 in the current buffer. For nested folds the deepest level is
2955 returned. If there is no fold at line {lnum}, zero is
2956 returned. It doesn't matter if the folds are open or closed.
2957 When used while updating folds (from 'foldexpr') -1 is
2958 returned for lines where folds are still to be updated and the
2959 foldlevel is unknown. As a special case the level of the
2960 previous line is usually available.
2961 {lnum} is used like with |getline()|. Thus "." is the current
2962 line, "'m" mark m, etc.
2963
2964 Can also be used as a |method|: >
2965 GetLnum()->foldlevel()
2966<
2967 *foldtext()*
2968foldtext() Returns a String, to be displayed for a closed fold. This is
2969 the default function used for the 'foldtext' option and should
2970 only be called from evaluating 'foldtext'. It uses the
2971 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2972 The returned string looks like this: >
2973 +-- 45 lines: abcdef
2974< The number of leading dashes depends on the foldlevel. The
2975 "45" is the number of lines in the fold. "abcdef" is the text
2976 in the first non-blank line of the fold. Leading white space,
2977 "//" or "/*" and the text from the 'foldmarker' and
2978 'commentstring' options is removed.
2979 When used to draw the actual foldtext, the rest of the line
2980 will be filled with the fold char from the 'fillchars'
2981 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002982 Returns an empty string when there is no fold.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002983 {not available when compiled without the |+folding| feature}
2984
2985foldtextresult({lnum}) *foldtextresult()*
2986 Returns the text that is displayed for the closed fold at line
2987 {lnum}. Evaluates 'foldtext' in the appropriate context.
2988 When there is no closed fold at {lnum} an empty string is
2989 returned.
2990 {lnum} is used like with |getline()|. Thus "." is the current
2991 line, "'m" mark m, etc.
2992 Useful when exporting folded text, e.g., to HTML.
2993 {not available when compiled without the |+folding| feature}
2994
2995
2996 Can also be used as a |method|: >
2997 GetLnum()->foldtextresult()
2998<
2999 *foreground()*
3000foreground() Move the Vim window to the foreground. Useful when sent from
3001 a client to a Vim server. |remote_send()|
3002 On Win32 systems this might not work, the OS does not always
3003 allow a window to bring itself to the foreground. Use
3004 |remote_foreground()| instead.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003005 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003006 Win32 console version}
3007
Bram Moolenaaraa534142022-09-15 21:46:02 +01003008fullcommand({name} [, {vim9}]) *fullcommand()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003009 Get the full command name from a short abbreviated command
3010 name; see |20.2| for details on command abbreviations.
3011
3012 The string argument {name} may start with a `:` and can
3013 include a [range], these are skipped and not returned.
Bram Moolenaaraa534142022-09-15 21:46:02 +01003014 Returns an empty string if a command doesn't exist, if it's
3015 ambiguous (for user-defined commands) or cannot be shortened
3016 this way. |vim9-no-shorten|
3017
3018 Without the {vim9} argument uses the current script version.
3019 If {vim9} is present and FALSE then legacy script rules are
3020 used. When {vim9} is present and TRUE then Vim9 rules are
3021 used, e.g. "en" is not a short form of "endif".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003022
3023 For example `fullcommand('s')`, `fullcommand('sub')`,
3024 `fullcommand(':%substitute')` all return "substitute".
3025
3026 Can also be used as a |method|: >
3027 GetName()->fullcommand()
3028<
3029 *funcref()*
3030funcref({name} [, {arglist}] [, {dict}])
3031 Just like |function()|, but the returned Funcref will lookup
3032 the function by reference, not by name. This matters when the
3033 function {name} is redefined later.
3034
3035 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003036 It only works for an autoloaded function if it has already
3037 been loaded (to avoid mistakenly loading the autoload script
3038 when only intending to use the function name, use |function()|
3039 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003040 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003041
3042 Can also be used as a |method|: >
3043 GetFuncname()->funcref([arg])
3044<
Dominique Pellee764d1b2023-03-12 21:20:59 +00003045 *function()* *partial* *E700* *E923*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003046function({name} [, {arglist}] [, {dict}])
3047 Return a |Funcref| variable that refers to function {name}.
3048 {name} can be the name of a user defined function or an
3049 internal function.
3050
3051 {name} can also be a Funcref or a partial. When it is a
3052 partial the dict stored in it will be used and the {dict}
3053 argument is not allowed. E.g.: >
3054 let FuncWithArg = function(dict.Func, [arg])
3055 let Broken = function(dict.Func, [arg], dict)
3056<
3057 When using the Funcref the function will be found by {name},
3058 also when it was redefined later. Use |funcref()| to keep the
3059 same function.
3060
3061 When {arglist} or {dict} is present this creates a partial.
3062 That means the argument list and/or the dictionary is stored in
3063 the Funcref and will be used when the Funcref is called.
3064
3065 The arguments are passed to the function in front of other
3066 arguments, but after any argument from |method|. Example: >
3067 func Callback(arg1, arg2, name)
3068 ...
3069 let Partial = function('Callback', ['one', 'two'])
3070 ...
3071 call Partial('name')
3072< Invokes the function as with: >
3073 call Callback('one', 'two', 'name')
3074
3075< With a |method|: >
3076 func Callback(one, two, three)
3077 ...
3078 let Partial = function('Callback', ['two'])
3079 ...
3080 eval 'one'->Partial('three')
3081< Invokes the function as with: >
3082 call Callback('one', 'two', 'three')
3083
3084< The function() call can be nested to add more arguments to the
3085 Funcref. The extra arguments are appended to the list of
3086 arguments. Example: >
3087 func Callback(arg1, arg2, name)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003088 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003089 let Func = function('Callback', ['one'])
3090 let Func2 = function(Func, ['two'])
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003091 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003092 call Func2('name')
3093< Invokes the function as with: >
3094 call Callback('one', 'two', 'name')
3095
3096< The Dictionary is only useful when calling a "dict" function.
3097 In that case the {dict} is passed in as "self". Example: >
3098 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003099 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003100 endfunction
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003101 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003102 let context = {"name": "example"}
3103 let Func = function('Callback', context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003104 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003105 call Func() " will echo: called for example
3106< The use of function() is not needed when there are no extra
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003107 arguments, these two are equivalent, if Callback() is defined
3108 as context.Callback(): >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003109 let Func = function('Callback', context)
3110 let Func = context.Callback
3111
3112< The argument list and the Dictionary can be combined: >
3113 function Callback(arg1, count) dict
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003114 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003115 let context = {"name": "example"}
3116 let Func = function('Callback', ['one'], context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003117 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003118 call Func(500)
3119< Invokes the function as with: >
3120 call context.Callback('one', 500)
3121<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003122 Returns 0 on error.
3123
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003124 Can also be used as a |method|: >
3125 GetFuncname()->function([arg])
3126
3127
3128garbagecollect([{atexit}]) *garbagecollect()*
3129 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3130 that have circular references.
3131
3132 There is hardly ever a need to invoke this function, as it is
3133 automatically done when Vim runs out of memory or is waiting
3134 for the user to press a key after 'updatetime'. Items without
3135 circular references are always freed when they become unused.
3136 This is useful if you have deleted a very big |List| and/or
3137 |Dictionary| with circular references in a script that runs
3138 for a long time.
3139
3140 When the optional {atexit} argument is one, garbage
3141 collection will also be done when exiting Vim, if it wasn't
3142 done before. This is useful when checking for memory leaks.
3143
3144 The garbage collection is not done immediately but only when
3145 it's safe to perform. This is when waiting for the user to
3146 type a character. To force garbage collection immediately use
3147 |test_garbagecollect_now()|.
3148
3149get({list}, {idx} [, {default}]) *get()*
3150 Get item {idx} from |List| {list}. When this item is not
3151 available return {default}. Return zero when {default} is
3152 omitted.
3153 Preferably used as a |method|: >
3154 mylist->get(idx)
3155get({blob}, {idx} [, {default}])
3156 Get byte {idx} from |Blob| {blob}. When this byte is not
3157 available return {default}. Return -1 when {default} is
3158 omitted.
3159 Preferably used as a |method|: >
3160 myblob->get(idx)
3161get({dict}, {key} [, {default}])
3162 Get item with key {key} from |Dictionary| {dict}. When this
3163 item is not available return {default}. Return zero when
3164 {default} is omitted. Useful example: >
3165 let val = get(g:, 'var_name', 'default')
3166< This gets the value of g:var_name if it exists, and uses
3167 'default' when it does not exist.
3168 Preferably used as a |method|: >
3169 mydict->get(key)
3170get({func}, {what})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003171 Get item {what} from Funcref {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003172 {what} are:
3173 "name" The function name
3174 "func" The function
3175 "dict" The dictionary
3176 "args" The list with arguments
Bram Moolenaar016188f2022-06-06 20:52:59 +01003177 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003178 Preferably used as a |method|: >
3179 myfunc->get(what)
3180<
3181 *getbufinfo()*
3182getbufinfo([{buf}])
3183getbufinfo([{dict}])
3184 Get information about buffers as a List of Dictionaries.
3185
3186 Without an argument information about all the buffers is
3187 returned.
3188
3189 When the argument is a |Dictionary| only the buffers matching
3190 the specified criteria are returned. The following keys can
3191 be specified in {dict}:
3192 buflisted include only listed buffers.
3193 bufloaded include only loaded buffers.
3194 bufmodified include only modified buffers.
3195
3196 Otherwise, {buf} specifies a particular buffer to return
3197 information for. For the use of {buf}, see |bufname()|
3198 above. If the buffer is found the returned List has one item.
3199 Otherwise the result is an empty list.
3200
3201 Each returned List item is a dictionary with the following
3202 entries:
3203 bufnr Buffer number.
3204 changed TRUE if the buffer is modified.
3205 changedtick Number of changes made to the buffer.
3206 hidden TRUE if the buffer is hidden.
3207 lastused Timestamp in seconds, like
3208 |localtime()|, when the buffer was
3209 last used.
3210 {only with the |+viminfo| feature}
3211 listed TRUE if the buffer is listed.
3212 lnum Line number used for the buffer when
3213 opened in the current window.
3214 Only valid if the buffer has been
3215 displayed in the window in the past.
3216 If you want the line number of the
3217 last known cursor position in a given
3218 window, use |line()|: >
3219 :echo line('.', {winid})
3220<
3221 linecount Number of lines in the buffer (only
3222 valid when loaded)
3223 loaded TRUE if the buffer is loaded.
3224 name Full path to the file in the buffer.
3225 signs List of signs placed in the buffer.
3226 Each list item is a dictionary with
3227 the following fields:
3228 id sign identifier
3229 lnum line number
3230 name sign name
3231 variables A reference to the dictionary with
3232 buffer-local variables.
3233 windows List of |window-ID|s that display this
3234 buffer
3235 popups List of popup |window-ID|s that
3236 display this buffer
3237
3238 Examples: >
3239 for buf in getbufinfo()
3240 echo buf.name
3241 endfor
3242 for buf in getbufinfo({'buflisted':1})
3243 if buf.changed
3244 ....
3245 endif
3246 endfor
3247<
3248 To get buffer-local options use: >
3249 getbufvar({bufnr}, '&option_name')
3250<
3251 Can also be used as a |method|: >
3252 GetBufnr()->getbufinfo()
3253<
3254
3255 *getbufline()*
3256getbufline({buf}, {lnum} [, {end}])
3257 Return a |List| with the lines starting from {lnum} to {end}
3258 (inclusive) in the buffer {buf}. If {end} is omitted, a
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003259 |List| with only the line {lnum} is returned. See
3260 `getbufoneline()` for only getting the line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003261
3262 For the use of {buf}, see |bufname()| above.
3263
3264 For {lnum} and {end} "$" can be used for the last line of the
3265 buffer. Otherwise a number must be used.
3266
3267 When {lnum} is smaller than 1 or bigger than the number of
3268 lines in the buffer, an empty |List| is returned.
3269
3270 When {end} is greater than the number of lines in the buffer,
3271 it is treated as {end} is set to the number of lines in the
3272 buffer. When {end} is before {lnum} an empty |List| is
3273 returned.
3274
3275 This function works only for loaded buffers. For unloaded and
3276 non-existing buffers, an empty |List| is returned.
3277
3278 Example: >
3279 :let lines = getbufline(bufnr("myfile"), 1, "$")
3280
3281< Can also be used as a |method|: >
3282 GetBufnr()->getbufline(lnum)
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003283<
3284 *getbufoneline()*
3285getbufoneline({buf}, {lnum})
3286 Just like `getbufline()` but only get one line and return it
3287 as a string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003288
3289getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3290 The result is the value of option or local buffer variable
3291 {varname} in buffer {buf}. Note that the name without "b:"
3292 must be used.
3293 The {varname} argument is a string.
3294 When {varname} is empty returns a |Dictionary| with all the
3295 buffer-local variables.
3296 When {varname} is equal to "&" returns a |Dictionary| with all
3297 the buffer-local options.
3298 Otherwise, when {varname} starts with "&" returns the value of
3299 a buffer-local option.
3300 This also works for a global or buffer-local option, but it
3301 doesn't work for a global variable, window-local variable or
3302 window-local option.
3303 For the use of {buf}, see |bufname()| above.
3304 When the buffer or variable doesn't exist {def} or an empty
3305 string is returned, there is no error message.
3306 Examples: >
3307 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003308 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003309
3310< Can also be used as a |method|: >
3311 GetBufnr()->getbufvar(varname)
3312<
Kota Kato66bb9ae2023-01-17 18:31:56 +00003313getcellwidths() *getcellwidths()*
3314 Returns a |List| of cell widths of character ranges overridden
3315 by |setcellwidths()|. The format is equal to the argument of
3316 |setcellwidths()|. If no character ranges have their cell
3317 widths overridden, an empty List is returned.
3318
3319
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003320getchangelist([{buf}]) *getchangelist()*
3321 Returns the |changelist| for the buffer {buf}. For the use
3322 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3323 exist, an empty list is returned.
3324
3325 The returned list contains two entries: a list with the change
3326 locations and the current position in the list. Each
3327 entry in the change list is a dictionary with the following
3328 entries:
3329 col column number
3330 coladd column offset for 'virtualedit'
3331 lnum line number
3332 If buffer {buf} is the current buffer, then the current
3333 position refers to the position in the list. For other
3334 buffers, it is set to the length of the list.
3335
3336 Can also be used as a |method|: >
3337 GetBufnr()->getchangelist()
3338
3339getchar([expr]) *getchar()*
3340 Get a single character from the user or input stream.
3341 If [expr] is omitted, wait until a character is available.
3342 If [expr] is 0, only get a character when one is available.
3343 Return zero otherwise.
3344 If [expr] is 1, only check if a character is available, it is
3345 not consumed. Return zero if no character available.
3346 If you prefer always getting a string use |getcharstr()|.
3347
3348 Without [expr] and when [expr] is 0 a whole character or
3349 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01003350 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003351 Otherwise a String is returned with the encoded character.
3352 For a special key it's a String with a sequence of bytes
3353 starting with 0x80 (decimal: 128). This is the same value as
3354 the String "\<Key>", e.g., "\<Left>". The returned value is
3355 also a String when a modifier (shift, control, alt) was used
3356 that is not included in the character.
3357
3358 When [expr] is 0 and Esc is typed, there will be a short delay
3359 while Vim waits to see if this is the start of an escape
3360 sequence.
3361
3362 When [expr] is 1 only the first byte is returned. For a
3363 one-byte character it is the character itself as a number.
3364 Use nr2char() to convert it to a String.
3365
3366 Use getcharmod() to obtain any additional modifiers.
3367
3368 When the user clicks a mouse button, the mouse event will be
3369 returned. The position can then be found in |v:mouse_col|,
3370 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3371 |getmousepos()| can also be used. Mouse move events will be
3372 ignored.
3373 This example positions the mouse as it would normally happen: >
3374 let c = getchar()
3375 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003376 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003377 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003378 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003379 endif
3380<
3381 When using bracketed paste only the first character is
3382 returned, the rest of the pasted text is dropped.
3383 |xterm-bracketed-paste|.
3384
3385 There is no prompt, you will somehow have to make clear to the
3386 user that a character has to be typed. The screen is not
3387 redrawn, e.g. when resizing the window. When using a popup
3388 window it should work better with a |popup-filter|.
3389
3390 There is no mapping for the character.
3391 Key codes are replaced, thus when the user presses the <Del>
3392 key you get the code for the <Del> key, not the raw character
3393 sequence. Examples: >
3394 getchar() == "\<Del>"
3395 getchar() == "\<S-Left>"
3396< This example redefines "f" to ignore case: >
3397 :nmap f :call FindChar()<CR>
3398 :function FindChar()
3399 : let c = nr2char(getchar())
3400 : while col('.') < col('$') - 1
3401 : normal l
3402 : if getline('.')[col('.') - 1] ==? c
3403 : break
3404 : endif
3405 : endwhile
3406 :endfunction
3407<
3408 You may also receive synthetic characters, such as
3409 |<CursorHold>|. Often you will want to ignore this and get
3410 another character: >
3411 :function GetKey()
3412 : let c = getchar()
3413 : while c == "\<CursorHold>"
3414 : let c = getchar()
3415 : endwhile
3416 : return c
3417 :endfunction
3418
3419getcharmod() *getcharmod()*
3420 The result is a Number which is the state of the modifiers for
3421 the last obtained character with getchar() or in another way.
3422 These values are added together:
3423 2 shift
3424 4 control
3425 8 alt (meta)
3426 16 meta (when it's different from ALT)
3427 32 mouse double click
3428 64 mouse triple click
3429 96 mouse quadruple click (== 32 + 64)
3430 128 command (Macintosh only)
3431 Only the modifiers that have not been included in the
3432 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01003433 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003434
3435 *getcharpos()*
3436getcharpos({expr})
3437 Get the position for String {expr}. Same as |getpos()| but the
3438 column number in the returned List is a character index
3439 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00003440 If |getpos()| returns a very large column number, equal to
3441 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003442 of the last character.
3443
3444 Example:
3445 With the cursor on '세' in line 5 with text "여보세요": >
3446 getcharpos('.') returns [0, 5, 3, 0]
3447 getpos('.') returns [0, 5, 7, 0]
3448<
3449 Can also be used as a |method|: >
3450 GetMark()->getcharpos()
3451
3452getcharsearch() *getcharsearch()*
3453 Return the current character search information as a {dict}
3454 with the following entries:
3455
3456 char character previously used for a character
3457 search (|t|, |f|, |T|, or |F|); empty string
3458 if no character search has been performed
3459 forward direction of character search; 1 for forward,
3460 0 for backward
3461 until type of character search; 1 for a |t| or |T|
3462 character search, 0 for an |f| or |F|
3463 character search
3464
3465 This can be useful to always have |;| and |,| search
3466 forward/backward regardless of the direction of the previous
3467 character search: >
3468 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3469 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3470< Also see |setcharsearch()|.
3471
3472
3473getcharstr([expr]) *getcharstr()*
3474 Get a single character from the user or input stream as a
3475 string.
3476 If [expr] is omitted, wait until a character is available.
3477 If [expr] is 0 or false, only get a character when one is
3478 available. Return an empty string otherwise.
3479 If [expr] is 1 or true, only check if a character is
3480 available, it is not consumed. Return an empty string
3481 if no character is available.
3482 Otherwise this works like |getchar()|, except that a number
3483 result is converted to a string.
3484
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003485getcmdcompltype() *getcmdcompltype()*
3486 Return the type of the current command-line completion.
3487 Only works when the command line is being edited, thus
3488 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01003489 See |:command-completion| for the return string.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003490 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3491 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003492 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003493
3494getcmdline() *getcmdline()*
3495 Return the current command-line. Only works when the command
3496 line is being edited, thus requires use of |c_CTRL-\_e| or
3497 |c_CTRL-R_=|.
3498 Example: >
3499 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003500< Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and
3501 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003502 Returns an empty string when entering a password or using
3503 |inputsecret()|.
3504
3505getcmdpos() *getcmdpos()*
3506 Return the position of the cursor in the command line as a
3507 byte count. The first column is 1.
3508 Only works when editing the command line, thus requires use of
3509 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3510 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003511 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3512 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003513
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003514getcmdscreenpos() *getcmdscreenpos()*
3515 Return the screen position of the cursor in the command line
3516 as a byte count. The first column is 1.
3517 Instead of |getcmdpos()|, it adds the prompt position.
3518 Only works when editing the command line, thus requires use of
3519 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3520 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003521 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
3522 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003523
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003524getcmdtype() *getcmdtype()*
3525 Return the current command-line type. Possible return values
3526 are:
3527 : normal Ex command
3528 > debug mode command |debug-mode|
3529 / forward search command
3530 ? backward search command
3531 @ |input()| command
3532 - |:insert| or |:append| command
3533 = |i_CTRL-R_=|
3534 Only works when editing the command line, thus requires use of
3535 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3536 Returns an empty string otherwise.
3537 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3538
3539getcmdwintype() *getcmdwintype()*
3540 Return the current |command-line-window| type. Possible return
3541 values are the same as |getcmdtype()|. Returns an empty string
3542 when not in the command-line window.
3543
3544getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
3545 Return a list of command-line completion matches. The String
3546 {type} argument specifies what for. The following completion
3547 types are supported:
3548
3549 arglist file names in argument list
3550 augroup autocmd groups
3551 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003552 behave |:behave| suboptions
3553 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003554 color color schemes
3555 command Ex command
3556 cmdline |cmdline-completion| result
3557 compiler compilers
3558 cscope |:cscope| suboptions
Shougo Matsushita92997dd2023-08-20 20:55:55 +02003559 custom,{func} custom completion, defined via {func}
3560 customlist,{func} custom completion, defined via {func}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003561 diff_buffer |:diffget| and |:diffput| completion
3562 dir directory names
3563 environment environment variable names
3564 event autocommand events
3565 expression Vim expression
3566 file file and directory names
3567 file_in_path file and directory names in |'path'|
3568 filetype filetype names |'filetype'|
3569 function function name
3570 help help subjects
3571 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003572 history |:history| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003573 locale locale names (as output of locale -a)
3574 mapclear buffer argument
3575 mapping mapping name
3576 menu menus
3577 messages |:messages| suboptions
3578 option options
3579 packadd optional package |pack-add| names
zeertzjq5c8771b2023-01-24 12:34:03 +00003580 runtime |:runtime| completion
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003581 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003582 shellcmd Shell command
3583 sign |:sign| suboptions
3584 syntax syntax file names |'syntax'|
3585 syntime |:syntime| suboptions
3586 tag tags
3587 tag_listfiles tags, file names
3588 user user names
3589 var user variables
3590
3591 If {pat} is an empty string, then all the matches are
3592 returned. Otherwise only items matching {pat} are returned.
3593 See |wildcards| for the use of special characters in {pat}.
3594
3595 If the optional {filtered} flag is set to 1, then 'wildignore'
3596 is applied to filter the results. Otherwise all the matches
3597 are returned. The 'wildignorecase' option always applies.
3598
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003599 If the 'wildoptions' option contains 'fuzzy', then fuzzy
3600 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003601 regular expression matching is used. Thus this function
3602 follows the user preference, what happens on the command line.
3603 If you do not want this you can make 'wildoptions' empty
3604 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003605
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003606 If {type} is "cmdline", then the |cmdline-completion| result is
3607 returned. For example, to complete the possible values after
3608 a ":call" command: >
3609 echo getcompletion('call ', 'cmdline')
3610<
3611 If there are no matches, an empty list is returned. An
3612 invalid value for {type} produces an error.
3613
3614 Can also be used as a |method|: >
3615 GetPattern()->getcompletion('color')
3616<
3617 *getcurpos()*
3618getcurpos([{winid}])
3619 Get the position of the cursor. This is like getpos('.'), but
3620 includes an extra "curswant" item in the list:
3621 [0, lnum, col, off, curswant] ~
3622 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00003623 cursor vertically. After |$| command it will be a very large
3624 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003625 |getpos()|.
3626 The first "bufnum" item is always zero. The byte position of
3627 the cursor is returned in 'col'. To get the character
3628 position, use |getcursorcharpos()|.
3629
3630 The optional {winid} argument can specify the window. It can
3631 be the window number or the |window-ID|. The last known
3632 cursor position is returned, this may be invalid for the
3633 current value of the buffer if it is not the current window.
3634 If {winid} is invalid a list with zeroes is returned.
3635
3636 This can be used to save and restore the cursor position: >
3637 let save_cursor = getcurpos()
3638 MoveTheCursorAround
3639 call setpos('.', save_cursor)
3640< Note that this only works within the window. See
3641 |winrestview()| for restoring more state.
3642
3643 Can also be used as a |method|: >
3644 GetWinid()->getcurpos()
3645<
3646 *getcursorcharpos()*
3647getcursorcharpos([{winid}])
3648 Same as |getcurpos()| but the column number in the returned
3649 List is a character index instead of a byte index.
3650
3651 Example:
3652 With the cursor on '보' in line 3 with text "여보세요": >
3653 getcursorcharpos() returns [0, 3, 2, 0, 3]
3654 getcurpos() returns [0, 3, 4, 0, 3]
3655<
3656 Can also be used as a |method|: >
3657 GetWinid()->getcursorcharpos()
3658
3659< *getcwd()*
3660getcwd([{winnr} [, {tabnr}]])
3661 The result is a String, which is the name of the current
3662 working directory. 'autochdir' is ignored.
3663
3664 With {winnr} return the local current directory of this window
3665 in the current tab page. {winnr} can be the window number or
3666 the |window-ID|.
3667 If {winnr} is -1 return the name of the global working
3668 directory. See also |haslocaldir()|.
3669
3670 With {winnr} and {tabnr} return the local current directory of
3671 the window in the specified tab page. If {winnr} is -1 return
3672 the working directory of the tabpage.
3673 If {winnr} is zero use the current window, if {tabnr} is zero
3674 use the current tabpage.
3675 Without any arguments, return the actual working directory of
3676 the current window.
3677 Return an empty string if the arguments are invalid.
3678
3679 Examples: >
3680 " Get the working directory of the current window
3681 :echo getcwd()
3682 :echo getcwd(0)
3683 :echo getcwd(0, 0)
3684 " Get the working directory of window 3 in tabpage 2
3685 :echo getcwd(3, 2)
3686 " Get the global working directory
3687 :echo getcwd(-1)
3688 " Get the working directory of tabpage 3
3689 :echo getcwd(-1, 3)
3690 " Get the working directory of current tabpage
3691 :echo getcwd(-1, 0)
3692
3693< Can also be used as a |method|: >
3694 GetWinnr()->getcwd()
3695
3696getenv({name}) *getenv()*
3697 Return the value of environment variable {name}. The {name}
3698 argument is a string, without a leading '$'. Example: >
3699 myHome = getenv('HOME')
3700
3701< When the variable does not exist |v:null| is returned. That
3702 is different from a variable set to an empty string, although
3703 some systems interpret the empty value as the variable being
3704 deleted. See also |expr-env|.
3705
3706 Can also be used as a |method|: >
3707 GetVarname()->getenv()
3708
3709getfontname([{name}]) *getfontname()*
3710 Without an argument returns the name of the normal font being
3711 used. Like what is used for the Normal highlight group
3712 |hl-Normal|.
3713 With an argument a check is done whether String {name} is a
3714 valid font name. If not then an empty string is returned.
3715 Otherwise the actual font name is returned, or {name} if the
3716 GUI does not support obtaining the real name.
3717 Only works when the GUI is running, thus not in your vimrc or
3718 gvimrc file. Use the |GUIEnter| autocommand to use this
3719 function just after the GUI has started.
3720 Note that the GTK GUI accepts any font name, thus checking for
3721 a valid name does not work.
3722
3723getfperm({fname}) *getfperm()*
3724 The result is a String, which is the read, write, and execute
3725 permissions of the given file {fname}.
3726 If {fname} does not exist or its directory cannot be read, an
3727 empty string is returned.
3728 The result is of the form "rwxrwxrwx", where each group of
3729 "rwx" flags represent, in turn, the permissions of the owner
3730 of the file, the group the file belongs to, and other users.
3731 If a user does not have a given permission the flag for this
3732 is replaced with the string "-". Examples: >
3733 :echo getfperm("/etc/passwd")
3734 :echo getfperm(expand("~/.vimrc"))
3735< This will hopefully (from a security point of view) display
3736 the string "rw-r--r--" or even "rw-------".
3737
3738 Can also be used as a |method|: >
3739 GetFilename()->getfperm()
3740<
3741 For setting permissions use |setfperm()|.
3742
3743getfsize({fname}) *getfsize()*
3744 The result is a Number, which is the size in bytes of the
3745 given file {fname}.
3746 If {fname} is a directory, 0 is returned.
3747 If the file {fname} can't be found, -1 is returned.
3748 If the size of {fname} is too big to fit in a Number then -2
3749 is returned.
3750
3751 Can also be used as a |method|: >
3752 GetFilename()->getfsize()
3753
3754getftime({fname}) *getftime()*
3755 The result is a Number, which is the last modification time of
3756 the given file {fname}. The value is measured as seconds
3757 since 1st Jan 1970, and may be passed to strftime(). See also
3758 |localtime()| and |strftime()|.
3759 If the file {fname} can't be found -1 is returned.
3760
3761 Can also be used as a |method|: >
3762 GetFilename()->getftime()
3763
3764getftype({fname}) *getftype()*
3765 The result is a String, which is a description of the kind of
3766 file of the given file {fname}.
3767 If {fname} does not exist an empty string is returned.
3768 Here is a table over different kinds of files and their
3769 results:
3770 Normal file "file"
3771 Directory "dir"
3772 Symbolic link "link"
3773 Block device "bdev"
3774 Character device "cdev"
3775 Socket "socket"
3776 FIFO "fifo"
3777 All other "other"
3778 Example: >
3779 getftype("/home")
3780< Note that a type such as "link" will only be returned on
3781 systems that support it. On some systems only "dir" and
3782 "file" are returned. On MS-Windows a symbolic link to a
3783 directory returns "dir" instead of "link".
3784
3785 Can also be used as a |method|: >
3786 GetFilename()->getftype()
3787
3788getimstatus() *getimstatus()*
3789 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01003790 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003791 See 'imstatusfunc'.
3792
3793getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
3794 Returns the |jumplist| for the specified window.
3795
3796 Without arguments use the current window.
3797 With {winnr} only use this window in the current tab page.
3798 {winnr} can also be a |window-ID|.
3799 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01003800 page. If {winnr} or {tabnr} is invalid, an empty list is
3801 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003802
3803 The returned list contains two entries: a list with the jump
3804 locations and the last used jump position number in the list.
3805 Each entry in the jump location list is a dictionary with
3806 the following entries:
3807 bufnr buffer number
3808 col column number
3809 coladd column offset for 'virtualedit'
3810 filename filename if available
3811 lnum line number
3812
3813 Can also be used as a |method|: >
3814 GetWinnr()->getjumplist()
3815
3816< *getline()*
3817getline({lnum} [, {end}])
3818 Without {end} the result is a String, which is line {lnum}
3819 from the current buffer. Example: >
3820 getline(1)
3821< When {lnum} is a String that doesn't start with a
3822 digit, |line()| is called to translate the String into a Number.
3823 To get the line under the cursor: >
3824 getline(".")
3825< When {lnum} is a number smaller than 1 or bigger than the
3826 number of lines in the buffer, an empty string is returned.
3827
3828 When {end} is given the result is a |List| where each item is
3829 a line from the current buffer in the range {lnum} to {end},
3830 including line {end}.
3831 {end} is used in the same way as {lnum}.
3832 Non-existing lines are silently omitted.
3833 When {end} is before {lnum} an empty |List| is returned.
3834 Example: >
3835 :let start = line('.')
3836 :let end = search("^$") - 1
3837 :let lines = getline(start, end)
3838
3839< Can also be used as a |method|: >
3840 ComputeLnum()->getline()
3841
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003842< To get lines from another buffer see |getbufline()| and
3843 |getbufoneline()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003844
3845getloclist({nr} [, {what}]) *getloclist()*
3846 Returns a |List| with all the entries in the location list for
3847 window {nr}. {nr} can be the window number or the |window-ID|.
3848 When {nr} is zero the current window is used.
3849
3850 For a location list window, the displayed location list is
3851 returned. For an invalid window number {nr}, an empty list is
3852 returned. Otherwise, same as |getqflist()|.
3853
3854 If the optional {what} dictionary argument is supplied, then
3855 returns the items listed in {what} as a dictionary. Refer to
3856 |getqflist()| for the supported items in {what}.
3857
3858 In addition to the items supported by |getqflist()| in {what},
3859 the following item is supported by |getloclist()|:
3860
3861 filewinid id of the window used to display files
3862 from the location list. This field is
3863 applicable only when called from a
3864 location list window. See
3865 |location-list-file-window| for more
3866 details.
3867
3868 Returns a |Dictionary| with default values if there is no
3869 location list for the window {nr}.
3870 Returns an empty Dictionary if window {nr} does not exist.
3871
3872 Examples (See also |getqflist-examples|): >
3873 :echo getloclist(3, {'all': 0})
3874 :echo getloclist(5, {'filewinid': 0})
3875
3876
3877getmarklist([{buf}]) *getmarklist()*
3878 Without the {buf} argument returns a |List| with information
3879 about all the global marks. |mark|
3880
3881 If the optional {buf} argument is specified, returns the
3882 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01003883 see |bufname()|. If {buf} is invalid, an empty list is
3884 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003885
3886 Each item in the returned List is a |Dict| with the following:
3887 mark name of the mark prefixed by "'"
3888 pos a |List| with the position of the mark:
3889 [bufnum, lnum, col, off]
3890 Refer to |getpos()| for more information.
3891 file file name
3892
3893 Refer to |getpos()| for getting information about a specific
3894 mark.
3895
3896 Can also be used as a |method|: >
3897 GetBufnr()->getmarklist()
3898
3899getmatches([{win}]) *getmatches()*
3900 Returns a |List| with all matches previously defined for the
3901 current window by |matchadd()| and the |:match| commands.
3902 |getmatches()| is useful in combination with |setmatches()|,
3903 as |setmatches()| can restore a list of matches saved by
3904 |getmatches()|.
3905 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01003906 window ID instead of the current window. If {win} is invalid,
3907 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003908 Example: >
3909 :echo getmatches()
3910< [{'group': 'MyGroup1', 'pattern': 'TODO',
3911 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3912 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3913 :let m = getmatches()
3914 :call clearmatches()
3915 :echo getmatches()
3916< [] >
3917 :call setmatches(m)
3918 :echo getmatches()
3919< [{'group': 'MyGroup1', 'pattern': 'TODO',
3920 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3921 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3922 :unlet m
3923<
3924getmousepos() *getmousepos()*
3925 Returns a |Dictionary| with the last known position of the
3926 mouse. This can be used in a mapping for a mouse click or in
3927 a filter of a popup window. The items are:
3928 screenrow screen row
3929 screencol screen column
3930 winid Window ID of the click
3931 winrow row inside "winid"
3932 wincol column inside "winid"
3933 line text line inside "winid"
3934 column text column inside "winid"
zeertzjqf5a94d52023-10-15 10:03:30 +02003935 coladd offset (in screen columns) from the
3936 start of the clicked char
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003937 All numbers are 1-based.
3938
3939 If not over a window, e.g. when in the command line, then only
3940 "screenrow" and "screencol" are valid, the others are zero.
3941
3942 When on the status line below a window or the vertical
3943 separator right of a window, the "line" and "column" values
3944 are zero.
3945
3946 When the position is after the text then "column" is the
3947 length of the text in bytes plus one.
3948
3949 If the mouse is over a popup window then that window is used.
3950
3951 When using |getchar()| the Vim variables |v:mouse_lnum|,
3952 |v:mouse_col| and |v:mouse_winid| also provide these values.
3953
Bram Moolenaar24dc19c2022-11-14 19:49:15 +00003954getmouseshape() *getmouseshape()*
3955 Returns the name of the currently showing mouse pointer.
3956 When the |+mouseshape| feature is not supported or the shape
3957 is unknown an empty string is returned.
3958 This function is mainly intended for testing.
3959
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003960 *getpid()*
3961getpid() Return a Number which is the process ID of the Vim process.
3962 On Unix and MS-Windows this is a unique number, until Vim
3963 exits.
3964
3965 *getpos()*
3966getpos({expr}) Get the position for String {expr}. For possible values of
3967 {expr} see |line()|. For getting the cursor position see
3968 |getcurpos()|.
3969 The result is a |List| with four numbers:
3970 [bufnum, lnum, col, off]
3971 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3972 is the buffer number of the mark.
3973 "lnum" and "col" are the position in the buffer. The first
3974 column is 1.
3975 The "off" number is zero, unless 'virtualedit' is used. Then
3976 it is the offset in screen columns from the start of the
3977 character. E.g., a position within a <Tab> or after the last
3978 character.
3979 Note that for '< and '> Visual mode matters: when it is "V"
3980 (visual line mode) the column of '< is zero and the column of
naohiro ono56200ee2022-01-01 14:59:44 +00003981 '> is a large number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003982 The column number in the returned List is the byte position
3983 within the line. To get the character position in the line,
3984 use |getcharpos()|.
naohiro ono56200ee2022-01-01 14:59:44 +00003985 A very large column number equal to |v:maxcol| can be returned,
3986 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01003987 If {expr} is invalid, returns a list with all zeros.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003988 This can be used to save and restore the position of a mark: >
3989 let save_a_mark = getpos("'a")
3990 ...
3991 call setpos("'a", save_a_mark)
3992< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
3993
3994 Can also be used as a |method|: >
3995 GetMark()->getpos()
3996
3997getqflist([{what}]) *getqflist()*
3998 Returns a |List| with all the current quickfix errors. Each
3999 list item is a dictionary with these entries:
4000 bufnr number of buffer that has the file name, use
4001 bufname() to get the name
4002 module module name
4003 lnum line number in the buffer (first line is 1)
4004 end_lnum
4005 end of line number if the item is multiline
4006 col column number (first column is 1)
4007 end_col end of column number if the item has range
4008 vcol |TRUE|: "col" is visual column
4009 |FALSE|: "col" is byte index
4010 nr error number
4011 pattern search pattern used to locate the error
4012 text description of the error
4013 type type of the error, 'E', '1', etc.
4014 valid |TRUE|: recognized error message
h_east596a9f22023-11-21 21:24:23 +09004015 user_data
4016 custom data associated with the item, can be
Tom Praschanca6ac992023-08-11 23:26:12 +02004017 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004018
4019 When there is no error list or it's empty, an empty list is
4020 returned. Quickfix list entries with a non-existing buffer
4021 number are returned with "bufnr" set to zero (Note: some
4022 functions accept buffer number zero for the alternate buffer,
4023 you may need to explicitly check for zero).
4024
4025 Useful application: Find pattern matches in multiple files and
4026 do something with them: >
4027 :vimgrep /theword/jg *.c
4028 :for d in getqflist()
4029 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4030 :endfor
4031<
4032 If the optional {what} dictionary argument is supplied, then
4033 returns only the items listed in {what} as a dictionary. The
4034 following string items are supported in {what}:
4035 changedtick get the total number of changes made
4036 to the list |quickfix-changedtick|
4037 context get the |quickfix-context|
4038 efm errorformat to use when parsing "lines". If
4039 not present, then the 'errorformat' option
4040 value is used.
4041 id get information for the quickfix list with
4042 |quickfix-ID|; zero means the id for the
4043 current list or the list specified by "nr"
4044 idx get information for the quickfix entry at this
4045 index in the list specified by 'id' or 'nr'.
4046 If set to zero, then uses the current entry.
4047 See |quickfix-index|
4048 items quickfix list entries
4049 lines parse a list of lines using 'efm' and return
4050 the resulting entries. Only a |List| type is
4051 accepted. The current quickfix list is not
4052 modified. See |quickfix-parse|.
4053 nr get information for this quickfix list; zero
4054 means the current quickfix list and "$" means
4055 the last quickfix list
4056 qfbufnr number of the buffer displayed in the quickfix
4057 window. Returns 0 if the quickfix buffer is
4058 not present. See |quickfix-buffer|.
4059 size number of entries in the quickfix list
4060 title get the list title |quickfix-title|
4061 winid get the quickfix |window-ID|
4062 all all of the above quickfix properties
4063 Non-string items in {what} are ignored. To get the value of a
4064 particular item, set it to zero.
4065 If "nr" is not present then the current quickfix list is used.
4066 If both "nr" and a non-zero "id" are specified, then the list
4067 specified by "id" is used.
4068 To get the number of lists in the quickfix stack, set "nr" to
4069 "$" in {what}. The "nr" value in the returned dictionary
4070 contains the quickfix stack size.
4071 When "lines" is specified, all the other items except "efm"
4072 are ignored. The returned dictionary contains the entry
4073 "items" with the list of entries.
4074
4075 The returned dictionary contains the following entries:
4076 changedtick total number of changes made to the
4077 list |quickfix-changedtick|
4078 context quickfix list context. See |quickfix-context|
4079 If not present, set to "".
4080 id quickfix list ID |quickfix-ID|. If not
4081 present, set to 0.
4082 idx index of the quickfix entry in the list. If not
4083 present, set to 0.
4084 items quickfix list entries. If not present, set to
4085 an empty list.
4086 nr quickfix list number. If not present, set to 0
4087 qfbufnr number of the buffer displayed in the quickfix
4088 window. If not present, set to 0.
4089 size number of entries in the quickfix list. If not
4090 present, set to 0.
4091 title quickfix list title text. If not present, set
4092 to "".
4093 winid quickfix |window-ID|. If not present, set to 0
4094
4095 Examples (See also |getqflist-examples|): >
4096 :echo getqflist({'all': 1})
4097 :echo getqflist({'nr': 2, 'title': 1})
4098 :echo getqflist({'lines' : ["F1:10:L10"]})
4099<
4100getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4101 The result is a String, which is the contents of register
4102 {regname}. Example: >
4103 :let cliptext = getreg('*')
4104< When register {regname} was not set the result is an empty
4105 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004106 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004107
4108 getreg('=') returns the last evaluated value of the expression
4109 register. (For use in maps.)
4110 getreg('=', 1) returns the expression itself, so that it can
4111 be restored with |setreg()|. For other registers the extra
4112 argument is ignored, thus you can always give it.
4113
4114 If {list} is present and |TRUE|, the result type is changed
4115 to |List|. Each list item is one text line. Use it if you care
4116 about zero bytes possibly present inside register: without
4117 third argument both NLs and zero bytes are represented as NLs
4118 (see |NL-used-for-Nul|).
4119 When the register was not set an empty list is returned.
4120
4121 If {regname} is "", the unnamed register '"' is used.
4122 If {regname} is not specified, |v:register| is used.
4123 In |Vim9-script| {regname} must be one character.
4124
4125 Can also be used as a |method|: >
4126 GetRegname()->getreg()
4127
4128getreginfo([{regname}]) *getreginfo()*
4129 Returns detailed information about register {regname} as a
4130 Dictionary with the following entries:
4131 regcontents List of lines contained in register
4132 {regname}, like
4133 |getreg|({regname}, 1, 1).
4134 regtype the type of register {regname}, as in
4135 |getregtype()|.
4136 isunnamed Boolean flag, v:true if this register
4137 is currently pointed to by the unnamed
4138 register.
4139 points_to for the unnamed register, gives the
4140 single letter name of the register
4141 currently pointed to (see |quotequote|).
4142 For example, after deleting a line
4143 with `dd`, this field will be "1",
4144 which is the register that got the
4145 deleted text.
4146
4147 The {regname} argument is a string. If {regname} is invalid
4148 or not set, an empty Dictionary will be returned.
4149 If {regname} is "" or "@", the unnamed register '"' is used.
4150 If {regname} is not specified, |v:register| is used.
4151 The returned Dictionary can be passed to |setreg()|.
4152 In |Vim9-script| {regname} must be one character.
4153
4154 Can also be used as a |method|: >
4155 GetRegname()->getreginfo()
4156
4157getregtype([{regname}]) *getregtype()*
4158 The result is a String, which is type of register {regname}.
4159 The value will be one of:
4160 "v" for |characterwise| text
4161 "V" for |linewise| text
4162 "<CTRL-V>{width}" for |blockwise-visual| text
4163 "" for an empty or unknown register
4164 <CTRL-V> is one character with value 0x16.
4165 The {regname} argument is a string. If {regname} is "", the
4166 unnamed register '"' is used. If {regname} is not specified,
4167 |v:register| is used.
4168 In |Vim9-script| {regname} must be one character.
4169
4170 Can also be used as a |method|: >
4171 GetRegname()->getregtype()
4172
Bram Moolenaar71badf92023-04-22 22:40:14 +01004173getscriptinfo([{opts}]) *getscriptinfo()*
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004174 Returns a |List| with information about all the sourced Vim
Bram Moolenaar753885b2022-08-24 16:30:36 +01004175 scripts in the order they were sourced, like what
4176 `:scriptnames` shows.
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004177
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004178 The optional Dict argument {opts} supports the following
4179 optional items:
4180 name Script name match pattern. If specified,
4181 and "sid" is not specified, information about
Bram Moolenaar71badf92023-04-22 22:40:14 +01004182 scripts with a name that match the pattern
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004183 "name" are returned.
4184 sid Script ID |<SID>|. If specified, only
4185 information about the script with ID "sid" is
4186 returned and "name" is ignored.
4187
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004188 Each item in the returned List is a |Dict| with the following
4189 items:
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004190 autoload Set to TRUE for a script that was used with
Bram Moolenaar753885b2022-08-24 16:30:36 +01004191 `import autoload` but was not actually sourced
4192 yet (see |import-autoload|).
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004193 functions List of script-local function names defined in
4194 the script. Present only when a particular
4195 script is specified using the "sid" item in
4196 {opts}.
4197 name Vim script file name.
4198 sid Script ID |<SID>|.
4199 sourced Script ID of the actually sourced script that
Bram Moolenaarfd999452022-08-24 18:30:14 +01004200 this script name links to, if any, otherwise
4201 zero
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004202 variables A dictionary with the script-local variables.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00004203 Present only when a particular script is
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004204 specified using the "sid" item in {opts}.
4205 Note that this is a copy, the value of
4206 script-local variables cannot be changed using
4207 this dictionary.
h_east59858792023-10-25 22:47:05 +09004208 version Vim script version (|scriptversion|)
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01004209
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004210 Examples: >
4211 :echo getscriptinfo({'name': 'myscript'})
4212 :echo getscriptinfo({'sid': 15}).variables
4213<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004214gettabinfo([{tabnr}]) *gettabinfo()*
4215 If {tabnr} is not specified, then information about all the
4216 tab pages is returned as a |List|. Each List item is a
4217 |Dictionary|. Otherwise, {tabnr} specifies the tab page
4218 number and information about that one is returned. If the tab
4219 page does not exist an empty List is returned.
4220
4221 Each List item is a |Dictionary| with the following entries:
4222 tabnr tab page number.
4223 variables a reference to the dictionary with
4224 tabpage-local variables
4225 windows List of |window-ID|s in the tab page.
4226
4227 Can also be used as a |method|: >
4228 GetTabnr()->gettabinfo()
4229
4230gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
4231 Get the value of a tab-local variable {varname} in tab page
4232 {tabnr}. |t:var|
4233 Tabs are numbered starting with one.
4234 The {varname} argument is a string. When {varname} is empty a
4235 dictionary with all tab-local variables is returned.
4236 Note that the name without "t:" must be used.
4237 When the tab or variable doesn't exist {def} or an empty
4238 string is returned, there is no error message.
4239
4240 Can also be used as a |method|: >
4241 GetTabnr()->gettabvar(varname)
4242
4243gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
4244 Get the value of window-local variable {varname} in window
4245 {winnr} in tab page {tabnr}.
4246 The {varname} argument is a string. When {varname} is empty a
4247 dictionary with all window-local variables is returned.
4248 When {varname} is equal to "&" get the values of all
4249 window-local options in a |Dictionary|.
4250 Otherwise, when {varname} starts with "&" get the value of a
4251 window-local option.
4252 Note that {varname} must be the name without "w:".
4253 Tabs are numbered starting with one. For the current tabpage
4254 use |getwinvar()|.
4255 {winnr} can be the window number or the |window-ID|.
4256 When {winnr} is zero the current window is used.
4257 This also works for a global option, buffer-local option and
4258 window-local option, but it doesn't work for a global variable
4259 or buffer-local variable.
4260 When the tab, window or variable doesn't exist {def} or an
4261 empty string is returned, there is no error message.
4262 Examples: >
4263 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004264 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004265<
4266 To obtain all window-local variables use: >
4267 gettabwinvar({tabnr}, {winnr}, '&')
4268
4269< Can also be used as a |method|: >
4270 GetTabnr()->gettabwinvar(winnr, varname)
4271
4272gettagstack([{winnr}]) *gettagstack()*
4273 The result is a Dict, which is the tag stack of window {winnr}.
4274 {winnr} can be the window number or the |window-ID|.
4275 When {winnr} is not specified, the current window is used.
4276 When window {winnr} doesn't exist, an empty Dict is returned.
4277
4278 The returned dictionary contains the following entries:
4279 curidx Current index in the stack. When at
4280 top of the stack, set to (length + 1).
4281 Index of bottom of the stack is 1.
4282 items List of items in the stack. Each item
4283 is a dictionary containing the
4284 entries described below.
4285 length Number of entries in the stack.
4286
4287 Each item in the stack is a dictionary with the following
4288 entries:
4289 bufnr buffer number of the current jump
4290 from cursor position before the tag jump.
4291 See |getpos()| for the format of the
4292 returned list.
4293 matchnr current matching tag number. Used when
4294 multiple matching tags are found for a
4295 name.
4296 tagname name of the tag
4297
4298 See |tagstack| for more information about the tag stack.
4299
4300 Can also be used as a |method|: >
4301 GetWinnr()->gettagstack()
4302
4303
4304gettext({text}) *gettext()*
4305 Translate String {text} if possible.
4306 This is mainly for use in the distributed Vim scripts. When
4307 generating message translations the {text} is extracted by
4308 xgettext, the translator can add the translated message in the
4309 .po file and Vim will lookup the translation when gettext() is
4310 called.
4311 For {text} double quoted strings are preferred, because
4312 xgettext does not understand escaping in single quoted
4313 strings.
4314
4315
4316getwininfo([{winid}]) *getwininfo()*
4317 Returns information about windows as a |List| with Dictionaries.
4318
4319 If {winid} is given Information about the window with that ID
4320 is returned, as a |List| with one item. If the window does not
4321 exist the result is an empty list.
4322
4323 Without {winid} information about all the windows in all the
4324 tab pages is returned.
4325
4326 Each List item is a |Dictionary| with the following entries:
4327 botline last complete displayed buffer line
4328 bufnr number of buffer in the window
4329 height window height (excluding winbar)
4330 loclist 1 if showing a location list
4331 {only with the +quickfix feature}
4332 quickfix 1 if quickfix or location list window
4333 {only with the +quickfix feature}
4334 terminal 1 if a terminal window
4335 {only with the +terminal feature}
4336 tabnr tab page number
4337 topline first displayed buffer line
4338 variables a reference to the dictionary with
4339 window-local variables
4340 width window width
4341 winbar 1 if the window has a toolbar, 0
4342 otherwise
4343 wincol leftmost screen column of the window;
4344 "col" from |win_screenpos()|
4345 textoff number of columns occupied by any
4346 'foldcolumn', 'signcolumn' and line
4347 number in front of the text
4348 winid |window-ID|
4349 winnr window number
4350 winrow topmost screen line of the window;
4351 "row" from |win_screenpos()|
4352
4353 Can also be used as a |method|: >
4354 GetWinnr()->getwininfo()
4355
4356getwinpos([{timeout}]) *getwinpos()*
4357 The result is a |List| with two numbers, the result of
4358 |getwinposx()| and |getwinposy()| combined:
4359 [x-pos, y-pos]
4360 {timeout} can be used to specify how long to wait in msec for
4361 a response from the terminal. When omitted 100 msec is used.
4362 Use a longer time for a remote terminal.
4363 When using a value less than 10 and no response is received
4364 within that time, a previously reported position is returned,
4365 if available. This can be used to poll for the position and
4366 do some work in the meantime: >
4367 while 1
4368 let res = getwinpos(1)
4369 if res[0] >= 0
4370 break
4371 endif
4372 " Do some work here
4373 endwhile
4374<
4375
4376 Can also be used as a |method|: >
4377 GetTimeout()->getwinpos()
4378<
4379 *getwinposx()*
4380getwinposx() The result is a Number, which is the X coordinate in pixels of
4381 the left hand side of the GUI Vim window. Also works for an
4382 xterm (uses a timeout of 100 msec).
4383 The result will be -1 if the information is not available.
4384 The value can be used with `:winpos`.
4385
4386 *getwinposy()*
4387getwinposy() The result is a Number, which is the Y coordinate in pixels of
4388 the top of the GUI Vim window. Also works for an xterm (uses
4389 a timeout of 100 msec).
4390 The result will be -1 if the information is not available.
4391 The value can be used with `:winpos`.
4392
4393getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
4394 Like |gettabwinvar()| for the current tabpage.
4395 Examples: >
4396 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004397 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004398
4399< Can also be used as a |method|: >
4400 GetWinnr()->getwinvar(varname)
4401<
4402glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
4403 Expand the file wildcards in {expr}. See |wildcards| for the
4404 use of special characters.
4405
4406 Unless the optional {nosuf} argument is given and is |TRUE|,
4407 the 'suffixes' and 'wildignore' options apply: Names matching
4408 one of the patterns in 'wildignore' will be skipped and
4409 'suffixes' affect the ordering of matches.
4410 'wildignorecase' always applies.
4411
4412 When {list} is present and it is |TRUE| the result is a |List|
4413 with all matching files. The advantage of using a List is,
4414 you also get filenames containing newlines correctly.
4415 Otherwise the result is a String and when there are several
4416 matches, they are separated by <NL> characters.
4417
4418 If the expansion fails, the result is an empty String or List.
4419
4420 You can also use |readdir()| if you need to do complicated
4421 things, such as limiting the number of matches.
4422
4423 A name for a non-existing file is not included. A symbolic
4424 link is only included if it points to an existing file.
4425 However, when the {alllinks} argument is present and it is
4426 |TRUE| then all symbolic links are included.
4427
4428 For most systems backticks can be used to get files names from
4429 any external command. Example: >
4430 :let tagfiles = glob("`find . -name tags -print`")
4431 :let &tags = substitute(tagfiles, "\n", ",", "g")
4432< The result of the program inside the backticks should be one
4433 item per line. Spaces inside an item are allowed.
4434
4435 See |expand()| for expanding special Vim variables. See
4436 |system()| for getting the raw output of an external command.
4437
4438 Can also be used as a |method|: >
4439 GetExpr()->glob()
4440
4441glob2regpat({string}) *glob2regpat()*
4442 Convert a file pattern, as used by glob(), into a search
4443 pattern. The result can be used to match with a string that
4444 is a file name. E.g. >
4445 if filename =~ glob2regpat('Make*.mak')
4446< This is equivalent to: >
4447 if filename =~ '^Make.*\.mak$'
4448< When {string} is an empty string the result is "^$", match an
4449 empty string.
4450 Note that the result depends on the system. On MS-Windows
4451 a backslash usually means a path separator.
4452
4453 Can also be used as a |method|: >
4454 GetExpr()->glob2regpat()
4455< *globpath()*
4456globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
4457 Perform glob() for String {expr} on all directories in {path}
4458 and concatenate the results. Example: >
4459 :echo globpath(&rtp, "syntax/c.vim")
4460<
4461 {path} is a comma-separated list of directory names. Each
4462 directory name is prepended to {expr} and expanded like with
4463 |glob()|. A path separator is inserted when needed.
4464 To add a comma inside a directory name escape it with a
4465 backslash. Note that on MS-Windows a directory may have a
4466 trailing backslash, remove it if you put a comma after it.
4467 If the expansion fails for one of the directories, there is no
4468 error message.
4469
4470 Unless the optional {nosuf} argument is given and is |TRUE|,
4471 the 'suffixes' and 'wildignore' options apply: Names matching
4472 one of the patterns in 'wildignore' will be skipped and
4473 'suffixes' affect the ordering of matches.
4474
4475 When {list} is present and it is |TRUE| the result is a |List|
4476 with all matching files. The advantage of using a List is, you
4477 also get filenames containing newlines correctly. Otherwise
4478 the result is a String and when there are several matches,
4479 they are separated by <NL> characters. Example: >
4480 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4481<
4482 {alllinks} is used as with |glob()|.
4483
4484 The "**" item can be used to search in a directory tree.
4485 For example, to find all "README.txt" files in the directories
4486 in 'runtimepath' and below: >
4487 :echo globpath(&rtp, "**/README.txt")
4488< Upwards search and limiting the depth of "**" is not
4489 supported, thus using 'path' will not always work properly.
4490
4491 Can also be used as a |method|, the base is passed as the
4492 second argument: >
4493 GetExpr()->globpath(&rtp)
4494<
4495 *has()*
4496has({feature} [, {check}])
4497 When {check} is omitted or is zero: The result is a Number,
4498 which is 1 if the feature {feature} is supported, zero
4499 otherwise. The {feature} argument is a string, case is
4500 ignored. See |feature-list| below.
4501
4502 When {check} is present and not zero: The result is a Number,
4503 which is 1 if the feature {feature} could ever be supported,
4504 zero otherwise. This is useful to check for a typo in
4505 {feature} and to detect dead code. Keep in mind that an older
4506 Vim version will not know about a feature added later and
4507 features that have been abandoned will not be known by the
4508 current Vim version.
4509
4510 Also see |exists()| and |exists_compiled()|.
4511
4512 Note that to skip code that has a syntax error when the
4513 feature is not available, Vim may skip the rest of the line
4514 and miss a following `endif`. Therefore put the `endif` on a
4515 separate line: >
4516 if has('feature')
4517 let x = this->breaks->without->the->feature
4518 endif
4519< If the `endif` would be moved to the second line as "| endif" it
4520 would not be found.
4521
4522
4523has_key({dict}, {key}) *has_key()*
4524 The result is a Number, which is TRUE if |Dictionary| {dict}
Bram Moolenaare8008642022-08-19 17:15:35 +01004525 has an entry with key {key}. FALSE otherwise.
4526 The {key} argument is a string. In |Vim9| script a number is
4527 also accepted (and converted to a string) but no other types.
4528 In legacy script the usual automatic conversion to string is
4529 done.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004530
4531 Can also be used as a |method|: >
4532 mydict->has_key(key)
4533
4534haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4535 The result is a Number:
4536 1 when the window has set a local directory via |:lcd|
4537 2 when the tab-page has set a local directory via |:tcd|
4538 0 otherwise.
4539
4540 Without arguments use the current window.
4541 With {winnr} use this window in the current tab page.
4542 With {winnr} and {tabnr} use the window in the specified tab
4543 page.
4544 {winnr} can be the window number or the |window-ID|.
4545 If {winnr} is -1 it is ignored and only the tabpage is used.
4546 Return 0 if the arguments are invalid.
4547 Examples: >
4548 if haslocaldir() == 1
4549 " window local directory case
4550 elseif haslocaldir() == 2
4551 " tab-local directory case
4552 else
4553 " global directory case
4554 endif
4555
4556 " current window
4557 :echo haslocaldir()
4558 :echo haslocaldir(0)
4559 :echo haslocaldir(0, 0)
4560 " window n in current tab page
4561 :echo haslocaldir(n)
4562 :echo haslocaldir(n, 0)
4563 " window n in tab page m
4564 :echo haslocaldir(n, m)
4565 " tab page m
4566 :echo haslocaldir(-1, m)
4567<
4568 Can also be used as a |method|: >
4569 GetWinnr()->haslocaldir()
4570
4571hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
4572 The result is a Number, which is TRUE if there is a mapping
4573 that contains {what} in somewhere in the rhs (what it is
4574 mapped to) and this mapping exists in one of the modes
4575 indicated by {mode}.
4576 The arguments {what} and {mode} are strings.
4577 When {abbr} is there and it is |TRUE| use abbreviations
4578 instead of mappings. Don't forget to specify Insert and/or
4579 Command-line mode.
4580 Both the global mappings and the mappings local to the current
4581 buffer are checked for a match.
4582 If no matching mapping is found FALSE is returned.
4583 The following characters are recognized in {mode}:
4584 n Normal mode
4585 v Visual and Select mode
4586 x Visual mode
4587 s Select mode
4588 o Operator-pending mode
4589 i Insert mode
4590 l Language-Argument ("r", "f", "t", etc.)
4591 c Command-line mode
4592 When {mode} is omitted, "nvo" is used.
4593
4594 This function is useful to check if a mapping already exists
4595 to a function in a Vim script. Example: >
4596 :if !hasmapto('\ABCdoit')
4597 : map <Leader>d \ABCdoit
4598 :endif
4599< This installs the mapping to "\ABCdoit" only if there isn't
4600 already a mapping to "\ABCdoit".
4601
4602 Can also be used as a |method|: >
4603 GetRHS()->hasmapto()
4604
4605histadd({history}, {item}) *histadd()*
4606 Add the String {item} to the history {history} which can be
4607 one of: *hist-names*
4608 "cmd" or ":" command line history
4609 "search" or "/" search pattern history
4610 "expr" or "=" typed expression history
4611 "input" or "@" input line history
4612 "debug" or ">" debug command history
4613 empty the current or last used history
4614 The {history} string does not need to be the whole name, one
4615 character is sufficient.
4616 If {item} does already exist in the history, it will be
4617 shifted to become the newest entry.
4618 The result is a Number: TRUE if the operation was successful,
4619 otherwise FALSE is returned.
4620
4621 Example: >
4622 :call histadd("input", strftime("%Y %b %d"))
4623 :let date=input("Enter date: ")
4624< This function is not available in the |sandbox|.
4625
4626 Can also be used as a |method|, the base is passed as the
4627 second argument: >
4628 GetHistory()->histadd('search')
4629
4630histdel({history} [, {item}]) *histdel()*
4631 Clear {history}, i.e. delete all its entries. See |hist-names|
4632 for the possible values of {history}.
4633
4634 If the parameter {item} evaluates to a String, it is used as a
4635 regular expression. All entries matching that expression will
4636 be removed from the history (if there are any).
4637 Upper/lowercase must match, unless "\c" is used |/\c|.
4638 If {item} evaluates to a Number, it will be interpreted as
4639 an index, see |:history-indexing|. The respective entry will
4640 be removed if it exists.
4641
4642 The result is TRUE for a successful operation, otherwise FALSE
4643 is returned.
4644
4645 Examples:
4646 Clear expression register history: >
4647 :call histdel("expr")
4648<
4649 Remove all entries starting with "*" from the search history: >
4650 :call histdel("/", '^\*')
4651<
4652 The following three are equivalent: >
4653 :call histdel("search", histnr("search"))
4654 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004655 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004656<
4657 To delete the last search pattern and use the last-but-one for
4658 the "n" command and 'hlsearch': >
4659 :call histdel("search", -1)
4660 :let @/ = histget("search", -1)
4661<
4662 Can also be used as a |method|: >
4663 GetHistory()->histdel()
4664
4665histget({history} [, {index}]) *histget()*
4666 The result is a String, the entry with Number {index} from
4667 {history}. See |hist-names| for the possible values of
4668 {history}, and |:history-indexing| for {index}. If there is
4669 no such entry, an empty String is returned. When {index} is
4670 omitted, the most recent item from the history is used.
4671
4672 Examples:
4673 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004674 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004675
4676< Define an Ex command ":H {num}" that supports re-execution of
4677 the {num}th entry from the output of |:history|. >
4678 :command -nargs=1 H execute histget("cmd", 0+<args>)
4679<
4680 Can also be used as a |method|: >
4681 GetHistory()->histget()
4682
4683histnr({history}) *histnr()*
4684 The result is the Number of the current entry in {history}.
4685 See |hist-names| for the possible values of {history}.
4686 If an error occurred, -1 is returned.
4687
4688 Example: >
4689 :let inp_index = histnr("expr")
4690
4691< Can also be used as a |method|: >
4692 GetHistory()->histnr()
4693<
4694hlexists({name}) *hlexists()*
4695 The result is a Number, which is TRUE if a highlight group
4696 called {name} exists. This is when the group has been
4697 defined in some way. Not necessarily when highlighting has
4698 been defined for it, it may also have been used for a syntax
4699 item.
4700 *highlight_exists()*
4701 Obsolete name: highlight_exists().
4702
4703 Can also be used as a |method|: >
4704 GetName()->hlexists()
4705<
4706hlget([{name} [, {resolve}]]) *hlget()*
4707 Returns a List of all the highlight group attributes. If the
4708 optional {name} is specified, then returns a List with only
4709 the attributes of the specified highlight group. Returns an
4710 empty List if the highlight group {name} is not present.
4711
4712 If the optional {resolve} argument is set to v:true and the
4713 highlight group {name} is linked to another group, then the
4714 link is resolved recursively and the attributes of the
4715 resolved highlight group are returned.
4716
4717 Each entry in the returned List is a Dictionary with the
4718 following items:
4719 cleared boolean flag, set to v:true if the highlight
4720 group attributes are cleared or not yet
4721 specified. See |highlight-clear|.
4722 cterm cterm attributes. See |highlight-cterm|.
4723 ctermbg cterm background color.
4724 See |highlight-ctermbg|.
4725 ctermfg cterm foreground color.
4726 See |highlight-ctermfg|.
4727 ctermul cterm underline color. See |highlight-ctermul|.
4728 default boolean flag, set to v:true if the highlight
4729 group link is a default link. See
4730 |highlight-default|.
4731 font highlight group font. See |highlight-font|.
4732 gui gui attributes. See |highlight-gui|.
4733 guibg gui background color. See |highlight-guibg|.
4734 guifg gui foreground color. See |highlight-guifg|.
4735 guisp gui special color. See |highlight-guisp|.
4736 id highlight group ID.
4737 linksto linked highlight group name.
4738 See |:highlight-link|.
4739 name highlight group name. See |group-name|.
4740 start start terminal keycode. See |highlight-start|.
4741 stop stop terminal keycode. See |highlight-stop|.
4742 term term attributes. See |highlight-term|.
4743
4744 The 'term', 'cterm' and 'gui' items in the above Dictionary
4745 have a dictionary value with the following optional boolean
4746 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
4747 'reverse', 'inverse' and 'strikethrough'.
4748
4749 Example(s): >
4750 :echo hlget()
4751 :echo hlget('ModeMsg')
4752 :echo hlget('Number', v:true)
4753<
4754 Can also be used as a |method|: >
4755 GetName()->hlget()
4756<
4757hlset({list}) *hlset()*
4758 Creates or modifies the attributes of a List of highlight
4759 groups. Each item in {list} is a dictionary containing the
4760 attributes of a highlight group. See |hlget()| for the list of
4761 supported items in this dictionary.
4762
4763 In addition to the items described in |hlget()|, the following
4764 additional items are supported in the dictionary:
4765
4766 force boolean flag to force the creation of
4767 a link for an existing highlight group
4768 with attributes.
4769
4770 The highlight group is identified using the 'name' item and
4771 the 'id' item (if supplied) is ignored. If a highlight group
4772 with a specified name doesn't exist, then it is created.
4773 Otherwise the attributes of an existing highlight group are
4774 modified.
4775
4776 If an empty dictionary value is used for the 'term' or 'cterm'
4777 or 'gui' entries, then the corresponding attributes are
4778 cleared. If the 'cleared' item is set to v:true, then all the
4779 attributes of the highlight group are cleared.
4780
4781 The 'linksto' item can be used to link a highlight group to
4782 another highlight group. See |:highlight-link|.
4783
4784 Returns zero for success, -1 for failure.
4785
4786 Example(s): >
4787 " add bold attribute to the Visual highlight group
4788 :call hlset([#{name: 'Visual',
4789 \ term: #{reverse: 1 , bold: 1}}])
4790 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
4791 :let l = hlget()
4792 :call hlset(l)
4793 " clear the Search highlight group
4794 :call hlset([#{name: 'Search', cleared: v:true}])
4795 " clear the 'term' attributes for a highlight group
4796 :call hlset([#{name: 'Title', term: {}}])
4797 " create the MyHlg group linking it to DiffAdd
4798 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
4799 " remove the MyHlg group link
4800 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
4801 " clear the attributes and a link
4802 :call hlset([#{name: 'MyHlg', cleared: v:true,
4803 \ linksto: 'NONE'}])
4804<
4805 Can also be used as a |method|: >
4806 GetAttrList()->hlset()
4807<
4808 *hlID()*
4809hlID({name}) The result is a Number, which is the ID of the highlight group
4810 with name {name}. When the highlight group doesn't exist,
4811 zero is returned.
4812 This can be used to retrieve information about the highlight
4813 group. For example, to get the background color of the
4814 "Comment" group: >
4815 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4816< *highlightID()*
4817 Obsolete name: highlightID().
4818
4819 Can also be used as a |method|: >
4820 GetName()->hlID()
4821
4822hostname() *hostname()*
4823 The result is a String, which is the name of the machine on
4824 which Vim is currently running. Machine names greater than
4825 256 characters long are truncated.
4826
4827iconv({string}, {from}, {to}) *iconv()*
4828 The result is a String, which is the text {string} converted
4829 from encoding {from} to encoding {to}.
4830 When the conversion completely fails an empty string is
4831 returned. When some characters could not be converted they
4832 are replaced with "?".
4833 The encoding names are whatever the iconv() library function
4834 can accept, see ":!man 3 iconv".
4835 Most conversions require Vim to be compiled with the |+iconv|
4836 feature. Otherwise only UTF-8 to latin1 conversion and back
4837 can be done.
4838 This can be used to display messages with special characters,
4839 no matter what 'encoding' is set to. Write the message in
4840 UTF-8 and use: >
4841 echo iconv(utf8_str, "utf-8", &enc)
4842< Note that Vim uses UTF-8 for all Unicode encodings, conversion
4843 from/to UCS-2 is automatically changed to use UTF-8. You
4844 cannot use UCS-2 in a string anyway, because of the NUL bytes.
4845
4846 Can also be used as a |method|: >
4847 GetText()->iconv('latin1', 'utf-8')
4848<
4849 *indent()*
4850indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4851 current buffer. The indent is counted in spaces, the value
4852 of 'tabstop' is relevant. {lnum} is used just like in
4853 |getline()|.
4854 When {lnum} is invalid -1 is returned. In |Vim9| script an
4855 error is given.
4856
4857 Can also be used as a |method|: >
4858 GetLnum()->indent()
4859
4860index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004861 Find {expr} in {object} and return its index. See
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004862 |indexof()| for using a lambda to select the item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004863
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004864 If {object} is a |List| return the lowest index where the item
4865 has a value equal to {expr}. There is no automatic
4866 conversion, so the String "4" is different from the Number 4.
4867 And the number 4 is different from the Float 4.0. The value
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004868 of 'ignorecase' is not used here, case matters as indicated by
4869 the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004870
4871 If {object} is |Blob| return the lowest index where the byte
4872 value is equal to {expr}.
4873
4874 If {start} is given then start looking at the item with index
4875 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004876
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004877 When {ic} is given and it is |TRUE|, ignore case. Otherwise
4878 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004879
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004880 -1 is returned when {expr} is not found in {object}.
4881 Example: >
4882 :let idx = index(words, "the")
4883 :if index(numbers, 123) >= 0
4884
4885< Can also be used as a |method|: >
4886 GetObject()->index(what)
4887
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004888indexof({object}, {expr} [, {opts}]) *indexof()*
4889 Returns the index of an item in {object} where {expr} is
4890 v:true. {object} must be a |List| or a |Blob|.
4891
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004892 If {object} is a |List|, evaluate {expr} for each item in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004893 List until the expression is v:true and return the index of
4894 this item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004895
4896 If {object} is a |Blob| evaluate {expr} for each byte in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004897 Blob until the expression is v:true and return the index of
4898 this byte.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004899
4900 {expr} must be a |string| or |Funcref|.
4901
4902 If {expr} is a |string|: If {object} is a |List|, inside
4903 {expr} |v:key| has the index of the current List item and
4904 |v:val| has the value of the item. If {object} is a |Blob|,
4905 inside {expr} |v:key| has the index of the current byte and
4906 |v:val| has the byte value.
4907
4908 If {expr} is a |Funcref| it must take two arguments:
4909 1. the key or the index of the current item.
4910 2. the value of the current item.
4911 The function must return |TRUE| if the item is found and the
4912 search should stop.
4913
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004914 The optional argument {opts} is a Dict and supports the
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004915 following items:
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004916 startidx start evaluating {expr} at the item with this
4917 index; may be negative for an item relative to
4918 the end
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004919 Returns -1 when {expr} evaluates to v:false for all the items.
4920 Example: >
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004921 :let l = [#{n: 10}, #{n: 20}, #{n: 30}]
4922 :echo indexof(l, "v:val.n == 20")
4923 :echo indexof(l, {i, v -> v.n == 30})
4924 :echo indexof(l, "v:val.n == 20", #{startidx: 1})
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004925
4926< Can also be used as a |method|: >
4927 mylist->indexof(expr)
4928
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004929input({prompt} [, {text} [, {completion}]]) *input()*
4930 The result is a String, which is whatever the user typed on
4931 the command-line. The {prompt} argument is either a prompt
4932 string, or a blank string (for no prompt). A '\n' can be used
4933 in the prompt to start a new line.
4934 The highlighting set with |:echohl| is used for the prompt.
4935 The input is entered just like a command-line, with the same
4936 editing commands and mappings. There is a separate history
4937 for lines typed for input().
4938 Example: >
4939 :if input("Coffee or beer? ") == "beer"
4940 : echo "Cheers!"
4941 :endif
4942<
4943 If the optional {text} argument is present and not empty, this
4944 is used for the default reply, as if the user typed this.
4945 Example: >
4946 :let color = input("Color? ", "white")
4947
4948< The optional {completion} argument specifies the type of
4949 completion supported for the input. Without it completion is
4950 not performed. The supported completion types are the same as
4951 that can be supplied to a user-defined command using the
4952 "-complete=" argument. Refer to |:command-completion| for
4953 more information. Example: >
4954 let fname = input("File: ", "", "file")
4955<
4956 NOTE: This function must not be used in a startup file, for
4957 the versions that only run in GUI mode (e.g., the Win32 GUI).
4958 Note: When input() is called from within a mapping it will
4959 consume remaining characters from that mapping, because a
4960 mapping is handled like the characters were typed.
4961 Use |inputsave()| before input() and |inputrestore()|
4962 after input() to avoid that. Another solution is to avoid
4963 that further characters follow in the mapping, e.g., by using
4964 |:execute| or |:normal|.
4965
4966 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004967 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004968 :function GetFoo()
4969 : call inputsave()
4970 : let g:Foo = input("enter search pattern: ")
4971 : call inputrestore()
4972 :endfunction
4973
4974< Can also be used as a |method|: >
4975 GetPrompt()->input()
4976
4977inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
4978 Like |input()|, but when the GUI is running and text dialogs
4979 are supported, a dialog window pops up to input the text.
4980 Example: >
4981 :let n = inputdialog("value for shiftwidth", shiftwidth())
4982 :if n != ""
4983 : let &sw = n
4984 :endif
4985< When the dialog is cancelled {cancelreturn} is returned. When
4986 omitted an empty string is returned.
4987 Hitting <Enter> works like pressing the OK button. Hitting
4988 <Esc> works like pressing the Cancel button.
4989 NOTE: Command-line completion is not supported.
4990
4991 Can also be used as a |method|: >
4992 GetPrompt()->inputdialog()
4993
4994inputlist({textlist}) *inputlist()*
4995 {textlist} must be a |List| of strings. This |List| is
4996 displayed, one string per line. The user will be prompted to
4997 enter a number, which is returned.
4998 The user can also select an item by clicking on it with the
4999 mouse, if the mouse is enabled in the command line ('mouse' is
5000 "a" or includes "c"). For the first string 0 is returned.
5001 When clicking above the first item a negative number is
5002 returned. When clicking on the prompt one more than the
5003 length of {textlist} is returned.
5004 Make sure {textlist} has less than 'lines' entries, otherwise
5005 it won't work. It's a good idea to put the entry number at
5006 the start of the string. And put a prompt in the first item.
5007 Example: >
5008 let color = inputlist(['Select color:', '1. red',
5009 \ '2. green', '3. blue'])
5010
5011< Can also be used as a |method|: >
5012 GetChoices()->inputlist()
5013
5014inputrestore() *inputrestore()*
5015 Restore typeahead that was saved with a previous |inputsave()|.
5016 Should be called the same number of times inputsave() is
5017 called. Calling it more often is harmless though.
5018 Returns TRUE when there is nothing to restore, FALSE otherwise.
5019
5020inputsave() *inputsave()*
5021 Preserve typeahead (also from mappings) and clear it, so that
5022 a following prompt gets input from the user. Should be
5023 followed by a matching inputrestore() after the prompt. Can
5024 be used several times, in which case there must be just as
5025 many inputrestore() calls.
5026 Returns TRUE when out of memory, FALSE otherwise.
5027
5028inputsecret({prompt} [, {text}]) *inputsecret()*
5029 This function acts much like the |input()| function with but
5030 two exceptions:
5031 a) the user's response will be displayed as a sequence of
5032 asterisks ("*") thereby keeping the entry secret, and
5033 b) the user's response will not be recorded on the input
5034 |history| stack.
5035 The result is a String, which is whatever the user actually
5036 typed on the command-line in response to the issued prompt.
5037 NOTE: Command-line completion is not supported.
5038
5039 Can also be used as a |method|: >
5040 GetPrompt()->inputsecret()
5041
5042insert({object}, {item} [, {idx}]) *insert()*
5043 When {object} is a |List| or a |Blob| insert {item} at the start
5044 of it.
5045
5046 If {idx} is specified insert {item} before the item with index
5047 {idx}. If {idx} is zero it goes before the first item, just
5048 like omitting {idx}. A negative {idx} is also possible, see
5049 |list-index|. -1 inserts just before the last item.
5050
5051 Returns the resulting |List| or |Blob|. Examples: >
5052 :let mylist = insert([2, 3, 5], 1)
5053 :call insert(mylist, 4, -1)
5054 :call insert(mylist, 6, len(mylist))
5055< The last example can be done simpler with |add()|.
5056 Note that when {item} is a |List| it is inserted as a single
5057 item. Use |extend()| to concatenate |Lists|.
5058
5059 Can also be used as a |method|: >
5060 mylist->insert(item)
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005061<
5062 *instanceof()* *E614* *E616* *E693*
5063instanceof({object}, {class})
5064 The result is a Number, which is |TRUE| when the {object}
Ernie Rael2025af12023-12-12 16:58:00 +01005065 argument is a direct or indirect instance of a |Class|,
5066 |Interface|, or class |:type| alias specified by {class}.
5067 If {class} is varargs, the function returns |TRUE| when
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07005068 {object} is an instance of any of the specified classes.
LemonBoyafe04662023-08-23 21:08:11 +02005069 Example: >
Ernie Rael2025af12023-12-12 16:58:00 +01005070 instanceof(animal, Dog, Cat)
LemonBoyafe04662023-08-23 21:08:11 +02005071
5072< Can also be used as a |method|: >
5073 myobj->instanceof(mytype)
5074
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005075interrupt() *interrupt()*
5076 Interrupt script execution. It works more or less like the
5077 user typing CTRL-C, most commands won't execute and control
5078 returns to the user. This is useful to abort execution
5079 from lower down, e.g. in an autocommand. Example: >
5080 :function s:check_typoname(file)
5081 : if fnamemodify(a:file, ':t') == '['
5082 : echomsg 'Maybe typo'
5083 : call interrupt()
5084 : endif
5085 :endfunction
5086 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
5087
5088invert({expr}) *invert()*
5089 Bitwise invert. The argument is converted to a number. A
5090 List, Dict or Float argument causes an error. Example: >
5091 :let bits = invert(bits)
5092< Can also be used as a |method|: >
5093 :let bits = bits->invert()
5094
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005095isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01005096 The result is a Number, which is |TRUE| when {path} is an
5097 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005098 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01005099 On MS-Windows, it is considered absolute when it starts with an
5100 optional drive prefix and is followed by a '\' or '/'. UNC paths
5101 are always absolute.
5102 Example: >
5103 echo isabsolutepath('/usr/share/') " 1
5104 echo isabsolutepath('./foobar') " 0
5105 echo isabsolutepath('C:\Windows') " 1
5106 echo isabsolutepath('foobar') " 0
5107 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005108<
LemonBoydca1d402022-04-28 15:26:33 +01005109 Can also be used as a |method|: >
5110 GetName()->isabsolutepath()
5111
5112
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005113isdirectory({directory}) *isdirectory()*
5114 The result is a Number, which is |TRUE| when a directory
5115 with the name {directory} exists. If {directory} doesn't
5116 exist, or isn't a directory, the result is |FALSE|. {directory}
5117 is any expression, which is used as a String.
5118
5119 Can also be used as a |method|: >
5120 GetName()->isdirectory()
5121
5122isinf({expr}) *isinf()*
5123 Return 1 if {expr} is a positive infinity, or -1 a negative
5124 infinity, otherwise 0. >
5125 :echo isinf(1.0 / 0.0)
5126< 1 >
5127 :echo isinf(-1.0 / 0.0)
5128< -1
5129
5130 Can also be used as a |method|: >
5131 Compute()->isinf()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005132
5133islocked({expr}) *islocked()* *E786*
5134 The result is a Number, which is |TRUE| when {expr} is the
5135 name of a locked variable.
5136 The string argument {expr} must be the name of a variable,
5137 |List| item or |Dictionary| entry, not the variable itself!
5138 Example: >
5139 :let alist = [0, ['a', 'b'], 2, 3]
5140 :lockvar 1 alist
5141 :echo islocked('alist') " 1
5142 :echo islocked('alist[1]') " 0
5143
Bram Moolenaar9da17d72022-02-09 21:50:44 +00005144< When {expr} is a variable that does not exist -1 is returned.
5145 If {expr} uses a range, list or dict index that is out of
5146 range or does not exist you get an error message. Use
5147 |exists()| to check for existence.
5148 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005149
5150 Can also be used as a |method|: >
5151 GetName()->islocked()
5152
5153isnan({expr}) *isnan()*
5154 Return |TRUE| if {expr} is a float with value NaN. >
5155 echo isnan(0.0 / 0.0)
5156< 1
5157
5158 Can also be used as a |method|: >
5159 Compute()->isnan()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005160
5161items({dict}) *items()*
5162 Return a |List| with all the key-value pairs of {dict}. Each
5163 |List| item is a list with two items: the key of a {dict}
5164 entry and the value of this entry. The |List| is in arbitrary
5165 order. Also see |keys()| and |values()|.
5166 Example: >
5167 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005168 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005169 endfor
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01005170<
5171 A List or a String argument is also supported. In these
5172 cases, items() returns a List with the index and the value at
5173 the index.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005174
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01005175 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005176 mydict->items()
5177
5178job_ functions are documented here: |job-functions-details|
5179
5180
5181join({list} [, {sep}]) *join()*
5182 Join the items in {list} together into one String.
5183 When {sep} is specified it is put in between the items. If
5184 {sep} is omitted a single space is used.
5185 Note that {sep} is not added at the end. You might want to
5186 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005187 let lines = join(mylist, "\n") .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005188< String items are used as-is. |Lists| and |Dictionaries| are
5189 converted into a string like with |string()|.
5190 The opposite function is |split()|.
5191
5192 Can also be used as a |method|: >
5193 mylist->join()
5194
5195js_decode({string}) *js_decode()*
5196 This is similar to |json_decode()| with these differences:
5197 - Object key names do not have to be in quotes.
5198 - Strings can be in single quotes.
5199 - Empty items in an array (between two commas) are allowed and
5200 result in v:none items.
5201
5202 Can also be used as a |method|: >
5203 ReadObject()->js_decode()
5204
5205js_encode({expr}) *js_encode()*
5206 This is similar to |json_encode()| with these differences:
5207 - Object key names are not in quotes.
5208 - v:none items in an array result in an empty item between
5209 commas.
5210 For example, the Vim object:
5211 [1,v:none,{"one":1},v:none] ~
5212 Will be encoded as:
5213 [1,,{one:1},,] ~
5214 While json_encode() would produce:
5215 [1,null,{"one":1},null] ~
5216 This encoding is valid for JavaScript. It is more efficient
5217 than JSON, especially when using an array with optional items.
5218
5219 Can also be used as a |method|: >
5220 GetObject()->js_encode()
5221
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005222json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005223 This parses a JSON formatted string and returns the equivalent
5224 in Vim values. See |json_encode()| for the relation between
5225 JSON and Vim values.
5226 The decoding is permissive:
5227 - A trailing comma in an array and object is ignored, e.g.
5228 "[1, 2, ]" is the same as "[1, 2]".
5229 - Integer keys are accepted in objects, e.g. {1:2} is the
5230 same as {"1":2}.
5231 - More floating point numbers are recognized, e.g. "1." for
5232 "1.0", or "001.2" for "1.2". Special floating point values
5233 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
5234 are accepted.
5235 - Leading zeroes in integer numbers are ignored, e.g. "012"
5236 for "12" or "-012" for "-12".
5237 - Capitalization is ignored in literal names null, true or
5238 false, e.g. "NULL" for "null", "True" for "true".
5239 - Control characters U+0000 through U+001F which are not
5240 escaped in strings are accepted, e.g. " " (tab
5241 character in string) for "\t".
5242 - An empty JSON expression or made of only spaces is accepted
5243 and results in v:none.
5244 - Backslash in an invalid 2-character sequence escape is
5245 ignored, e.g. "\a" is decoded as "a".
5246 - A correct surrogate pair in JSON strings should normally be
5247 a 12 character sequence such as "\uD834\uDD1E", but
5248 json_decode() silently accepts truncated surrogate pairs
5249 such as "\uD834" or "\uD834\u"
5250 *E938*
5251 A duplicate key in an object, valid in rfc7159, is not
5252 accepted by json_decode() as the result must be a valid Vim
5253 type, e.g. this fails: {"a":"b", "a":"c"}
5254
5255 Can also be used as a |method|: >
5256 ReadObject()->json_decode()
5257
5258json_encode({expr}) *json_encode()*
5259 Encode {expr} as JSON and return this as a string.
5260 The encoding is specified in:
5261 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00005262 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005263 |Number| decimal number
5264 |Float| floating point number
5265 Float nan "NaN"
5266 Float inf "Infinity"
5267 Float -inf "-Infinity"
5268 |String| in double quotes (possibly null)
5269 |Funcref| not possible, error
5270 |List| as an array (possibly null); when
5271 used recursively: []
5272 |Dict| as an object (possibly null); when
5273 used recursively: {}
5274 |Blob| as an array of the individual bytes
5275 v:false "false"
5276 v:true "true"
5277 v:none "null"
5278 v:null "null"
5279 Note that NaN and Infinity are passed on as values. This is
5280 missing in the JSON standard, but several implementations do
5281 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01005282 If a string contains an illegal character then the replacement
5283 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005284
5285 Can also be used as a |method|: >
5286 GetObject()->json_encode()
5287
5288keys({dict}) *keys()*
5289 Return a |List| with all the keys of {dict}. The |List| is in
5290 arbitrary order. Also see |items()| and |values()|.
5291
5292 Can also be used as a |method|: >
5293 mydict->keys()
5294
zeertzjqcdc83932022-09-12 13:38:41 +01005295keytrans({string}) *keytrans()*
5296 Turn the internal byte representation of keys into a form that
5297 can be used for |:map|. E.g. >
5298 :let xx = "\<C-Home>"
5299 :echo keytrans(xx)
5300< <C-Home>
5301
5302 Can also be used as a |method|: >
5303 "\<C-Home>"->keytrans()
5304
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005305< *len()* *E701*
5306len({expr}) The result is a Number, which is the length of the argument.
5307 When {expr} is a String or a Number the length in bytes is
5308 used, as with |strlen()|.
5309 When {expr} is a |List| the number of items in the |List| is
5310 returned.
5311 When {expr} is a |Blob| the number of bytes is returned.
5312 When {expr} is a |Dictionary| the number of entries in the
5313 |Dictionary| is returned.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005314 Otherwise an error is given and returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005315
5316 Can also be used as a |method|: >
5317 mylist->len()
5318
5319< *libcall()* *E364* *E368*
5320libcall({libname}, {funcname}, {argument})
5321 Call function {funcname} in the run-time library {libname}
5322 with single argument {argument}.
5323 This is useful to call functions in a library that you
5324 especially made to be used with Vim. Since only one argument
5325 is possible, calling standard library functions is rather
5326 limited.
5327 The result is the String returned by the function. If the
5328 function returns NULL, this will appear as an empty string ""
5329 to Vim.
5330 If the function returns a number, use libcallnr()!
5331 If {argument} is a number, it is passed to the function as an
5332 int; if {argument} is a string, it is passed as a
5333 null-terminated string.
5334 This function will fail in |restricted-mode|.
5335
5336 libcall() allows you to write your own 'plug-in' extensions to
5337 Vim without having to recompile the program. It is NOT a
5338 means to call system functions! If you try to do so Vim will
5339 very probably crash.
5340
5341 For Win32, the functions you write must be placed in a DLL
5342 and use the normal C calling convention (NOT Pascal which is
5343 used in Windows System DLLs). The function must take exactly
5344 one parameter, either a character pointer or a long integer,
5345 and must return a character pointer or NULL. The character
5346 pointer returned must point to memory that will remain valid
5347 after the function has returned (e.g. in static data in the
5348 DLL). If it points to allocated memory, that memory will
5349 leak away. Using a static buffer in the function should work,
5350 it's then freed when the DLL is unloaded.
5351
5352 WARNING: If the function returns a non-valid pointer, Vim may
5353 crash! This also happens if the function returns a number,
5354 because Vim thinks it's a pointer.
5355 For Win32 systems, {libname} should be the filename of the DLL
5356 without the ".DLL" suffix. A full path is only required if
5357 the DLL is not in the usual places.
5358 For Unix: When compiling your own plugins, remember that the
5359 object code must be compiled as position-independent ('PIC').
5360 {only in Win32 and some Unix versions, when the |+libcall|
5361 feature is present}
5362 Examples: >
5363 :echo libcall("libc.so", "getenv", "HOME")
5364
5365< Can also be used as a |method|, the base is passed as the
5366 third argument: >
5367 GetValue()->libcall("libc.so", "getenv")
5368<
5369 *libcallnr()*
5370libcallnr({libname}, {funcname}, {argument})
5371 Just like |libcall()|, but used for a function that returns an
5372 int instead of a string.
5373 {only in Win32 on some Unix versions, when the |+libcall|
5374 feature is present}
5375 Examples: >
5376 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
5377 :call libcallnr("libc.so", "printf", "Hello World!\n")
5378 :call libcallnr("libc.so", "sleep", 10)
5379<
5380 Can also be used as a |method|, the base is passed as the
5381 third argument: >
5382 GetValue()->libcallnr("libc.so", "printf")
5383<
5384
5385line({expr} [, {winid}]) *line()*
5386 The result is a Number, which is the line number of the file
5387 position given with {expr}. The {expr} argument is a string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00005388 The accepted positions are: *E1209*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005389 . the cursor position
5390 $ the last line in the current buffer
5391 'x position of mark x (if the mark is not set, 0 is
5392 returned)
5393 w0 first line visible in current window (one if the
5394 display isn't updated, e.g. in silent Ex mode)
5395 w$ last line visible in current window (this is one
5396 less than "w0" if no lines are visible)
5397 v In Visual mode: the start of the Visual area (the
5398 cursor is the end). When not in Visual mode
5399 returns the cursor position. Differs from |'<| in
5400 that it's updated right away.
5401 Note that a mark in another file can be used. The line number
5402 then applies to another buffer.
5403 To get the column number use |col()|. To get both use
5404 |getpos()|.
5405 With the optional {winid} argument the values are obtained for
5406 that window instead of the current window.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005407 Returns 0 for invalid values of {expr} and {winid}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005408 Examples: >
5409 line(".") line number of the cursor
5410 line(".", winid) idem, in window "winid"
5411 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005412 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005413<
5414 To jump to the last known position when opening a file see
5415 |last-position-jump|.
5416
5417 Can also be used as a |method|: >
5418 GetValue()->line()
5419
5420line2byte({lnum}) *line2byte()*
5421 Return the byte count from the start of the buffer for line
5422 {lnum}. This includes the end-of-line character, depending on
5423 the 'fileformat' option for the current buffer. The first
5424 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
5425 This can also be used to get the byte count for the line just
5426 below the last line: >
5427 line2byte(line("$") + 1)
5428< This is the buffer size plus one. If 'fileencoding' is empty
5429 it is the file size plus one. {lnum} is used like with
5430 |getline()|. When {lnum} is invalid, or the |+byte_offset|
5431 feature has been disabled at compile time, -1 is returned.
5432 Also see |byte2line()|, |go| and |:goto|.
5433
5434 Can also be used as a |method|: >
5435 GetLnum()->line2byte()
5436
5437lispindent({lnum}) *lispindent()*
5438 Get the amount of indent for line {lnum} according the lisp
5439 indenting rules, as with 'lisp'.
5440 The indent is counted in spaces, the value of 'tabstop' is
5441 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01005442 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005443 error is given.
5444
5445 Can also be used as a |method|: >
5446 GetLnum()->lispindent()
5447
5448list2blob({list}) *list2blob()*
5449 Return a Blob concatenating all the number values in {list}.
5450 Examples: >
5451 list2blob([1, 2, 3, 4]) returns 0z01020304
5452 list2blob([]) returns 0z
5453< Returns an empty Blob on error. If one of the numbers is
5454 negative or more than 255 error *E1239* is given.
5455
5456 |blob2list()| does the opposite.
5457
5458 Can also be used as a |method|: >
5459 GetList()->list2blob()
5460
5461list2str({list} [, {utf8}]) *list2str()*
5462 Convert each number in {list} to a character string can
5463 concatenate them all. Examples: >
5464 list2str([32]) returns " "
5465 list2str([65, 66, 67]) returns "ABC"
5466< The same can be done (slowly) with: >
5467 join(map(list, {nr, val -> nr2char(val)}), '')
5468< |str2list()| does the opposite.
5469
5470 When {utf8} is omitted or zero, the current 'encoding' is used.
5471 When {utf8} is TRUE, always return UTF-8 characters.
5472 With UTF-8 composing characters work as expected: >
5473 list2str([97, 769]) returns "á"
5474<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005475 Returns an empty string on error.
5476
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005477 Can also be used as a |method|: >
5478 GetList()->list2str()
5479
5480listener_add({callback} [, {buf}]) *listener_add()*
5481 Add a callback function that will be invoked when changes have
5482 been made to buffer {buf}.
5483 {buf} refers to a buffer name or number. For the accepted
5484 values, see |bufname()|. When {buf} is omitted the current
5485 buffer is used.
5486 Returns a unique ID that can be passed to |listener_remove()|.
5487
5488 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00005489 bufnr the buffer that was changed
5490 start first changed line number
5491 end first line number below the change
5492 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005493 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00005494 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005495
5496 Example: >
5497 func Listener(bufnr, start, end, added, changes)
5498 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
5499 endfunc
5500 call listener_add('Listener', bufnr)
5501
Bram Moolenaar944697a2022-02-20 19:48:20 +00005502< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005503 dictionary with these entries:
5504 lnum the first line number of the change
5505 end the first line below the change
5506 added number of lines added; negative if lines were
5507 deleted
5508 col first column in "lnum" that was affected by
5509 the change; one if unknown or the whole line
5510 was affected; this is a byte index, first
5511 character has a value of one.
Bram Moolenaar3c053a12022-10-16 13:11:12 +01005512 When lines are inserted (not when a line is split, e.g. by
5513 typing CR in Insert mode) the values are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005514 lnum line above which the new line is added
5515 end equal to "lnum"
5516 added number of lines inserted
5517 col 1
5518 When lines are deleted the values are:
5519 lnum the first deleted line
5520 end the line below the first deleted line, before
5521 the deletion was done
5522 added negative, number of lines deleted
5523 col 1
5524 When lines are changed:
5525 lnum the first changed line
5526 end the line below the last changed line
5527 added 0
5528 col first column with a change or 1
5529
5530 The entries are in the order the changes were made, thus the
5531 most recent change is at the end. The line numbers are valid
5532 when the callback is invoked, but later changes may make them
5533 invalid, thus keeping a copy for later might not work.
5534
5535 The {callback} is invoked just before the screen is updated,
5536 when |listener_flush()| is called or when a change is being
5537 made that changes the line count in a way it causes a line
5538 number in the list of changes to become invalid.
5539
5540 The {callback} is invoked with the text locked, see
5541 |textlock|. If you do need to make changes to the buffer, use
5542 a timer to do this later |timer_start()|.
5543
5544 The {callback} is not invoked when the buffer is first loaded.
5545 Use the |BufReadPost| autocmd event to handle the initial text
5546 of a buffer.
5547 The {callback} is also not invoked when the buffer is
5548 unloaded, use the |BufUnload| autocmd event for that.
5549
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005550 Returns zero if {callback} or {buf} is invalid.
5551
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005552 Can also be used as a |method|, the base is passed as the
5553 second argument: >
5554 GetBuffer()->listener_add(callback)
5555
5556listener_flush([{buf}]) *listener_flush()*
5557 Invoke listener callbacks for buffer {buf}. If there are no
5558 pending changes then no callbacks are invoked.
5559
5560 {buf} refers to a buffer name or number. For the accepted
5561 values, see |bufname()|. When {buf} is omitted the current
5562 buffer is used.
5563
5564 Can also be used as a |method|: >
5565 GetBuffer()->listener_flush()
5566
5567listener_remove({id}) *listener_remove()*
5568 Remove a listener previously added with listener_add().
5569 Returns FALSE when {id} could not be found, TRUE when {id} was
5570 removed.
5571
5572 Can also be used as a |method|: >
5573 GetListenerId()->listener_remove()
5574
5575localtime() *localtime()*
5576 Return the current time, measured as seconds since 1st Jan
5577 1970. See also |strftime()|, |strptime()| and |getftime()|.
5578
5579
5580log({expr}) *log()*
5581 Return the natural logarithm (base e) of {expr} as a |Float|.
5582 {expr} must evaluate to a |Float| or a |Number| in the range
5583 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005584 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005585 Examples: >
5586 :echo log(10)
5587< 2.302585 >
5588 :echo log(exp(5))
5589< 5.0
5590
5591 Can also be used as a |method|: >
5592 Compute()->log()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005593
5594
5595log10({expr}) *log10()*
5596 Return the logarithm of Float {expr} to base 10 as a |Float|.
5597 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005598 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005599 Examples: >
5600 :echo log10(1000)
5601< 3.0 >
5602 :echo log10(0.01)
5603< -2.0
5604
5605 Can also be used as a |method|: >
5606 Compute()->log10()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005607
5608luaeval({expr} [, {expr}]) *luaeval()*
5609 Evaluate Lua expression {expr} and return its result converted
5610 to Vim data structures. Second {expr} may hold additional
5611 argument accessible as _A inside first {expr}.
5612 Strings are returned as they are.
5613 Boolean objects are converted to numbers.
Bram Moolenaar73e28dc2022-09-17 21:08:33 +01005614 Numbers are converted to |Float| values.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005615 Dictionaries and lists obtained by vim.eval() are returned
5616 as-is.
5617 Other objects are returned as zero without any errors.
5618 See |lua-luaeval| for more details.
5619 Note that in a `:def` function local variables are not visible
5620 to {expr}.
5621
5622 Can also be used as a |method|: >
5623 GetExpr()->luaeval()
5624
5625< {only available when compiled with the |+lua| feature}
5626
5627map({expr1}, {expr2}) *map()*
5628 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00005629 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005630 item in {expr1} with the result of evaluating {expr2}.
5631 For a |Blob| each byte is replaced.
5632 For a |String|, each character, including composing
5633 characters, is replaced.
5634 If the item type changes you may want to use |mapnew()| to
5635 create a new List or Dictionary. This is required when using
5636 Vim9 script.
5637
5638 {expr2} must be a |String| or |Funcref|.
5639
5640 If {expr2} is a |String|, inside {expr2} |v:val| has the value
5641 of the current item. For a |Dictionary| |v:key| has the key
5642 of the current item and for a |List| |v:key| has the index of
5643 the current item. For a |Blob| |v:key| has the index of the
5644 current byte. For a |String| |v:key| has the index of the
5645 current character.
5646 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005647 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005648< This puts "> " before and " <" after each item in "mylist".
5649
5650 Note that {expr2} is the result of an expression and is then
5651 used as an expression again. Often it is good to use a
5652 |literal-string| to avoid having to double backslashes. You
5653 still have to double ' quotes
5654
5655 If {expr2} is a |Funcref| it is called with two arguments:
5656 1. The key or the index of the current item.
5657 2. the value of the current item.
Bram Moolenaarb59ae592022-11-23 23:46:31 +00005658 With a legacy script lambda you don't get an error if it only
5659 accepts one argument, but with a Vim9 lambda you get "E1106:
5660 One argument too many", the number of arguments must match.
5661
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005662 The function must return the new value of the item. Example
5663 that changes each value by "key-value": >
5664 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005665 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005666 endfunc
5667 call map(myDict, function('KeyValue'))
5668< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005669 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005670< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005671 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005672< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005673 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005674<
5675 The operation is done in-place for a |List| and |Dictionary|.
5676 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005677 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005678
5679< Returns {expr1}, the |List| or |Dictionary| that was filtered,
5680 or a new |Blob| or |String|.
5681 When an error is encountered while evaluating {expr2} no
5682 further items in {expr1} are processed.
5683 When {expr2} is a Funcref errors inside a function are ignored,
5684 unless it was defined with the "abort" flag.
5685
5686 Can also be used as a |method|: >
5687 mylist->map(expr2)
5688
5689
5690maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
5691 When {dict} is omitted or zero: Return the rhs of mapping
5692 {name} in mode {mode}. The returned String has special
5693 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01005694 listing. When {dict} is TRUE a dictionary is returned, see
5695 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005696
5697 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005698 returned if {dict} is FALSE, otherwise returns an empty Dict.
5699 When the mapping for {name} is empty, then "<Nop>" is
5700 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005701
5702 The {name} can have special key names, like in the ":map"
5703 command.
5704
5705 {mode} can be one of these strings:
5706 "n" Normal
5707 "v" Visual (including Select)
5708 "o" Operator-pending
5709 "i" Insert
5710 "c" Cmd-line
5711 "s" Select
5712 "x" Visual
5713 "l" langmap |language-mapping|
5714 "t" Terminal-Job
5715 "" Normal, Visual and Operator-pending
5716 When {mode} is omitted, the modes for "" are used.
5717
5718 When {abbr} is there and it is |TRUE| use abbreviations
5719 instead of mappings.
5720
5721 When {dict} is there and it is |TRUE| return a dictionary
5722 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01005723 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005724 "lhs" The {lhs} of the mapping as it would be typed
5725 "lhsraw" The {lhs} of the mapping as raw bytes
5726 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
5727 form, only present when it differs from "lhsraw"
5728 "rhs" The {rhs} of the mapping as typed.
5729 "silent" 1 for a |:map-silent| mapping, else 0.
5730 "noremap" 1 if the {rhs} of the mapping is not remappable.
5731 "script" 1 if mapping was defined with <script>.
5732 "expr" 1 for an expression mapping (|:map-<expr>|).
5733 "buffer" 1 for a buffer local mapping (|:map-local|).
5734 "mode" Modes for which the mapping is defined. In
5735 addition to the modes mentioned above, these
5736 characters will be used:
5737 " " Normal, Visual and Operator-pending
5738 "!" Insert and Commandline mode
5739 (|mapmode-ic|)
5740 "sid" The script local ID, used for <sid> mappings
Bram Moolenaar71badf92023-04-22 22:40:14 +01005741 (|<SID>|). Negative for special contexts.
Bram Moolenaara9528b32022-01-18 20:51:35 +00005742 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005743 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005744 "lnum" The line number in "sid", zero if unknown.
5745 "nowait" Do not wait for other, longer mappings.
5746 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01005747 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01005748 "mode_bits" Vim's internal binary representation of "mode".
5749 |mapset()| ignores this; only "mode" is used.
5750 See |maplist()| for usage examples. The values
5751 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005752
5753 The dictionary can be used to restore a mapping with
5754 |mapset()|.
5755
5756 The mappings local to the current buffer are checked first,
5757 then the global mappings.
5758 This function can be used to map a key even when it's already
5759 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005760 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005761
5762< Can also be used as a |method|: >
5763 GetKey()->maparg('n')
5764
5765mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
5766 Check if there is a mapping that matches with {name} in mode
5767 {mode}. See |maparg()| for {mode} and special names in
5768 {name}.
5769 When {abbr} is there and it is |TRUE| use abbreviations
5770 instead of mappings.
5771 A match happens with a mapping that starts with {name} and
5772 with a mapping which is equal to the start of {name}.
5773
5774 matches mapping "a" "ab" "abc" ~
5775 mapcheck("a") yes yes yes
5776 mapcheck("abc") yes yes yes
5777 mapcheck("ax") yes no no
5778 mapcheck("b") no no no
5779
5780 The difference with maparg() is that mapcheck() finds a
5781 mapping that matches with {name}, while maparg() only finds a
5782 mapping for {name} exactly.
5783 When there is no mapping that starts with {name}, an empty
5784 String is returned. If there is one, the RHS of that mapping
5785 is returned. If there are several mappings that start with
5786 {name}, the RHS of one of them is returned. This will be
5787 "<Nop>" if the RHS is empty.
5788 The mappings local to the current buffer are checked first,
5789 then the global mappings.
5790 This function can be used to check if a mapping can be added
5791 without being ambiguous. Example: >
5792 :if mapcheck("_vv") == ""
5793 : map _vv :set guifont=7x13<CR>
5794 :endif
5795< This avoids adding the "_vv" mapping when there already is a
5796 mapping for "_v" or for "_vvv".
5797
5798 Can also be used as a |method|: >
5799 GetKey()->mapcheck('n')
5800
5801
Ernie Rael09661202022-04-25 14:40:44 +01005802maplist([{abbr}]) *maplist()*
5803 Returns a |List| of all mappings. Each List item is a |Dict|,
5804 the same as what is returned by |maparg()|, see
5805 |mapping-dict|. When {abbr} is there and it is |TRUE| use
5806 abbreviations instead of mappings.
5807
5808 Example to show all mappings with 'MultiMatch' in rhs: >
5809 vim9script
5810 echo maplist()->filter(
5811 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01005812< It can be tricky to find mappings for particular |:map-modes|.
5813 |mapping-dict|'s "mode_bits" can simplify this. For example,
5814 the mode_bits for Normal, Insert or Command-line modes are
5815 0x19. To find all the mappings available in those modes you
5816 can do: >
5817 vim9script
5818 var saved_maps = []
5819 for m in maplist()
5820 if and(m.mode_bits, 0x19) != 0
5821 saved_maps->add(m)
5822 endif
5823 endfor
5824 echo saved_maps->mapnew((_, m) => m.lhs)
5825< The values of the mode_bits are defined in Vim's src/vim.h
5826 file and they can be discovered at runtime using
5827 |:map-commands| and "maplist()". Example: >
5828 vim9script
5829 omap xyzzy <Nop>
5830 var op_bit = maplist()->filter(
5831 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
5832 ounmap xyzzy
5833 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Ernie Rael09661202022-04-25 14:40:44 +01005834
5835
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005836mapnew({expr1}, {expr2}) *mapnew()*
5837 Like |map()| but instead of replacing items in {expr1} a new
5838 List or Dictionary is created and returned. {expr1} remains
5839 unchanged. Items can still be changed by {expr2}, if you
5840 don't want that use |deepcopy()| first.
5841
5842
5843mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01005844mapset({dict})
5845 Restore a mapping from a dictionary, possibly returned by
5846 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
5847 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005848 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01005849 feature allows copying mappings from one buffer to another.
5850 The dict.mode value may restore a single mapping that covers
5851 more than one mode, like with mode values of '!', ' ', 'nox',
5852 or 'v'. *E1276*
5853
5854 In the first form, {mode} and {abbr} should be the same as
5855 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005856 {mode} is used to define the mode in which the mapping is set,
5857 not the "mode" entry in {dict}.
5858 Example for saving and restoring a mapping: >
5859 let save_map = maparg('K', 'n', 0, 1)
5860 nnoremap K somethingelse
5861 ...
5862 call mapset('n', 0, save_map)
5863< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01005864 e.g. with `:map!`, you need to save/restore the mapping for
5865 all of them, when they might differ.
5866
5867 In the second form, with {dict} as the only argument, mode
5868 and abbr are taken from the dict.
5869 Example: >
5870 vim9script
5871 var save_maps = maplist()->filter(
5872 (_, m) => m.lhs == 'K')
5873 nnoremap K somethingelse
5874 cnoremap K somethingelse2
5875 # ...
5876 unmap K
5877 for d in save_maps
5878 mapset(d)
5879 endfor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005880
5881
5882match({expr}, {pat} [, {start} [, {count}]]) *match()*
5883 When {expr} is a |List| then this returns the index of the
5884 first item where {pat} matches. Each item is used as a
5885 String, |Lists| and |Dictionaries| are used as echoed.
5886
5887 Otherwise, {expr} is used as a String. The result is a
5888 Number, which gives the index (byte offset) in {expr} where
5889 {pat} matches.
5890
5891 A match at the first character or |List| item returns zero.
5892 If there is no match -1 is returned.
5893
5894 For getting submatches see |matchlist()|.
5895 Example: >
5896 :echo match("testing", "ing") " results in 4
5897 :echo match([1, 'x'], '\a') " results in 1
5898< See |string-match| for how {pat} is used.
5899 *strpbrk()*
5900 Vim doesn't have a strpbrk() function. But you can do: >
5901 :let sepidx = match(line, '[.,;: \t]')
5902< *strcasestr()*
5903 Vim doesn't have a strcasestr() function. But you can add
5904 "\c" to the pattern to ignore case: >
5905 :let idx = match(haystack, '\cneedle')
5906<
5907 If {start} is given, the search starts from byte index
5908 {start} in a String or item {start} in a |List|.
5909 The result, however, is still the index counted from the
5910 first character/item. Example: >
5911 :echo match("testing", "ing", 2)
5912< result is again "4". >
5913 :echo match("testing", "ing", 4)
5914< result is again "4". >
5915 :echo match("testing", "t", 2)
5916< result is "3".
5917 For a String, if {start} > 0 then it is like the string starts
5918 {start} bytes later, thus "^" will match at {start}. Except
5919 when {count} is given, then it's like matches before the
5920 {start} byte are ignored (this is a bit complicated to keep it
5921 backwards compatible).
5922 For a String, if {start} < 0, it will be set to 0. For a list
5923 the index is counted from the end.
5924 If {start} is out of range ({start} > strlen({expr}) for a
5925 String or {start} > len({expr}) for a |List|) -1 is returned.
5926
5927 When {count} is given use the {count}'th match. When a match
5928 is found in a String the search for the next one starts one
5929 character further. Thus this example results in 1: >
5930 echo match("testing", "..", 0, 2)
5931< In a |List| the search continues in the next item.
5932 Note that when {count} is added the way {start} works changes,
5933 see above.
5934
5935 See |pattern| for the patterns that are accepted.
5936 The 'ignorecase' option is used to set the ignore-caseness of
5937 the pattern. 'smartcase' is NOT used. The matching is always
5938 done like 'magic' is set and 'cpoptions' is empty.
5939 Note that a match at the start is preferred, thus when the
5940 pattern is using "*" (any number of matches) it tends to find
5941 zero matches at the start instead of a number of matches
5942 further down in the text.
5943
5944 Can also be used as a |method|: >
5945 GetText()->match('word')
5946 GetList()->match('word')
5947<
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005948 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005949matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
5950 Defines a pattern to be highlighted in the current window (a
5951 "match"). It will be highlighted with {group}. Returns an
5952 identification number (ID), which can be used to delete the
5953 match using |matchdelete()|. The ID is bound to the window.
5954 Matching is case sensitive and magic, unless case sensitivity
5955 or magicness are explicitly overridden in {pattern}. The
5956 'magic', 'smartcase' and 'ignorecase' options are not used.
5957 The "Conceal" value is special, it causes the match to be
5958 concealed.
5959
5960 The optional {priority} argument assigns a priority to the
5961 match. A match with a high priority will have its
5962 highlighting overrule that of a match with a lower priority.
5963 A priority is specified as an integer (negative numbers are no
5964 exception). If the {priority} argument is not specified, the
5965 default priority is 10. The priority of 'hlsearch' is zero,
5966 hence all matches with a priority greater than zero will
5967 overrule it. Syntax highlighting (see 'syntax') is a separate
5968 mechanism, and regardless of the chosen priority a match will
5969 always overrule syntax highlighting.
5970
5971 The optional {id} argument allows the request for a specific
5972 match ID. If a specified ID is already taken, an error
5973 message will appear and the match will not be added. An ID
5974 is specified as a positive integer (zero excluded). IDs 1, 2
5975 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01005976 respectively. 3 is reserved for use by the |matchparen|
5977 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01005978 If the {id} argument is not specified or -1, |matchadd()|
Bram Moolenaar9f573a82022-09-29 13:50:08 +01005979 automatically chooses a free ID, which is at least 1000.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005980
5981 The optional {dict} argument allows for further custom
5982 values. Currently this is used to specify a match specific
5983 conceal character that will be shown for |hl-Conceal|
5984 highlighted matches. The dict can have the following members:
5985
5986 conceal Special character to show instead of the
5987 match (only for |hl-Conceal| highlighted
5988 matches, see |:syn-cchar|)
5989 window Instead of the current window use the
5990 window with this number or window ID.
5991
5992 The number of matches is not limited, as it is the case with
5993 the |:match| commands.
5994
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005995 Returns -1 on error.
5996
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005997 Example: >
5998 :highlight MyGroup ctermbg=green guibg=green
5999 :let m = matchadd("MyGroup", "TODO")
6000< Deletion of the pattern: >
6001 :call matchdelete(m)
6002
6003< A list of matches defined by |matchadd()| and |:match| are
6004 available from |getmatches()|. All matches can be deleted in
6005 one operation by |clearmatches()|.
6006
6007 Can also be used as a |method|: >
6008 GetGroup()->matchadd('TODO')
6009<
6010 *matchaddpos()*
6011matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
6012 Same as |matchadd()|, but requires a list of positions {pos}
6013 instead of a pattern. This command is faster than |matchadd()|
6014 because it does not require to handle regular expressions and
6015 sets buffer line boundaries to redraw screen. It is supposed
6016 to be used when fast match additions and deletions are
6017 required, for example to highlight matching parentheses.
6018
6019 {pos} is a list of positions. Each position can be one of
6020 these:
6021 - A number. This whole line will be highlighted. The first
6022 line has number 1.
6023 - A list with one number, e.g., [23]. The whole line with this
6024 number will be highlighted.
6025 - A list with two numbers, e.g., [23, 11]. The first number is
6026 the line number, the second one is the column number (first
6027 column is 1, the value must correspond to the byte index as
6028 |col()| would return). The character at this position will
6029 be highlighted.
6030 - A list with three numbers, e.g., [23, 11, 3]. As above, but
6031 the third number gives the length of the highlight in bytes.
6032
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006033 Returns -1 on error.
6034
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006035 Example: >
6036 :highlight MyGroup ctermbg=green guibg=green
6037 :let m = matchaddpos("MyGroup", [[23, 24], 34])
6038< Deletion of the pattern: >
6039 :call matchdelete(m)
6040
6041< Matches added by |matchaddpos()| are returned by
6042 |getmatches()|.
6043
6044 Can also be used as a |method|: >
6045 GetGroup()->matchaddpos([23, 11])
6046
6047matcharg({nr}) *matcharg()*
6048 Selects the {nr} match item, as set with a |:match|,
6049 |:2match| or |:3match| command.
6050 Return a |List| with two elements:
6051 The name of the highlight group used
6052 The pattern used.
6053 When {nr} is not 1, 2 or 3 returns an empty |List|.
6054 When there is no match item set returns ['', ''].
6055 This is useful to save and restore a |:match|.
6056 Highlighting matches using the |:match| commands are limited
6057 to three matches. |matchadd()| does not have this limitation.
6058
6059 Can also be used as a |method|: >
6060 GetMatch()->matcharg()
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006061<
6062 *matchbufline()*
6063matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])
6064 Returns the |List| of matches in lines from {lnum} to {end} in
6065 buffer {buf} where {pat} matches.
6066
6067 {lnum} and {end} can either be a line number or the string "$"
6068 to refer to the last line in {buf}.
6069
6070 The {dict} argument supports following items:
6071 submatches include submatch information (|/\(|)
6072
6073 For each match, a |Dict| with the following items is returned:
6074 byteidx starting byte index of the match
6075    lnum line number where there is a match
6076    text matched string
6077 Note that there can be multiple matches in a single line.
6078
6079 This function works only for loaded buffers. First call
6080 |bufload()| if needed.
6081
6082 When {buf} is not a valid buffer, the buffer is not loaded or
6083 {lnum} or {end} is not valid then an error is given and an
6084 empty |List| is returned.
6085
6086 Examples: >
6087    " Assuming line 3 in buffer 5 contains "a"
6088    :echo matchbufline(5, '\<\k\+\>', 3, 3)
6089    [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
6090    " Assuming line 4 in buffer 10 contains "tik tok"
6091    :echo matchbufline(10, '\<\k\+\>', 1, 4)
6092    [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
6093<
6094 If {submatch} is present and is v:true, then submatches like
6095 "\1", "\2", etc. are also returned.  Example: >
6096    " Assuming line 2 in buffer 2 contains "acd"
6097    :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
6098 \ {'submatches': v:true})
6099    [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
6100< The "submatches" List always contains 9 items. If a submatch
6101 is not found, then an empty string is returned for that
6102 submatch.
6103
6104 Can also be used as a |method|: >
6105 GetBuffer()->matchbufline('mypat', 1, '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006106
6107matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
6108 Deletes a match with ID {id} previously defined by |matchadd()|
6109 or one of the |:match| commands. Returns 0 if successful,
6110 otherwise -1. See example for |matchadd()|. All matches can
6111 be deleted in one operation by |clearmatches()|.
6112 If {win} is specified, use the window with this number or
6113 window ID instead of the current window.
6114
6115 Can also be used as a |method|: >
6116 GetMatch()->matchdelete()
6117
6118matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
6119 Same as |match()|, but return the index of first character
6120 after the match. Example: >
6121 :echo matchend("testing", "ing")
6122< results in "7".
6123 *strspn()* *strcspn()*
6124 Vim doesn't have a strspn() or strcspn() function, but you can
6125 do it with matchend(): >
6126 :let span = matchend(line, '[a-zA-Z]')
6127 :let span = matchend(line, '[^a-zA-Z]')
6128< Except that -1 is returned when there are no matches.
6129
6130 The {start}, if given, has the same meaning as for |match()|. >
6131 :echo matchend("testing", "ing", 2)
6132< results in "7". >
6133 :echo matchend("testing", "ing", 5)
6134< result is "-1".
6135 When {expr} is a |List| the result is equal to |match()|.
6136
6137 Can also be used as a |method|: >
6138 GetText()->matchend('word')
6139
6140
6141matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
6142 If {list} is a list of strings, then returns a |List| with all
6143 the strings in {list} that fuzzy match {str}. The strings in
6144 the returned list are sorted based on the matching score.
6145
6146 The optional {dict} argument always supports the following
6147 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01006148 matchseq When this item is present return only matches
6149 that contain the characters in {str} in the
6150 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01006151 limit Maximum number of matches in {list} to be
6152 returned. Zero means no limit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006153
6154 If {list} is a list of dictionaries, then the optional {dict}
6155 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01006156 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006157 {str}. The value of this item should be a
6158 string.
6159 text_cb |Funcref| that will be called for every item
6160 in {list} to get the text for fuzzy matching.
6161 This should accept a dictionary item as the
6162 argument and return the text for that item to
6163 use for fuzzy matching.
6164
6165 {str} is treated as a literal string and regular expression
6166 matching is NOT supported. The maximum supported {str} length
6167 is 256.
6168
6169 When {str} has multiple words each separated by white space,
6170 then the list of strings that have all the words is returned.
6171
6172 If there are no matching strings or there is an error, then an
6173 empty list is returned. If length of {str} is greater than
6174 256, then returns an empty list.
6175
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01006176 When {limit} is given, matchfuzzy() will find up to this
6177 number of matches in {list} and return them in sorted order.
6178
Bram Moolenaar1588bc82022-03-08 21:35:07 +00006179 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006180 matching strings.
6181
6182 Example: >
6183 :echo matchfuzzy(["clay", "crow"], "cay")
6184< results in ["clay"]. >
6185 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
6186< results in a list of buffer names fuzzy matching "ndl". >
6187 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
6188< results in a list of buffer information dicts with buffer
6189 names fuzzy matching "ndl". >
6190 :echo getbufinfo()->matchfuzzy("spl",
6191 \ {'text_cb' : {v -> v.name}})
6192< results in a list of buffer information dicts with buffer
6193 names fuzzy matching "spl". >
6194 :echo v:oldfiles->matchfuzzy("test")
6195< results in a list of file names fuzzy matching "test". >
6196 :let l = readfile("buffer.c")->matchfuzzy("str")
6197< results in a list of lines in "buffer.c" fuzzy matching "str". >
6198 :echo ['one two', 'two one']->matchfuzzy('two one')
6199< results in ['two one', 'one two']. >
6200 :echo ['one two', 'two one']->matchfuzzy('two one',
6201 \ {'matchseq': 1})
6202< results in ['two one'].
6203
6204matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
6205 Same as |matchfuzzy()|, but returns the list of matched
6206 strings, the list of character positions where characters
6207 in {str} matches and a list of matching scores. You can
6208 use |byteidx()| to convert a character position to a byte
6209 position.
6210
6211 If {str} matches multiple times in a string, then only the
6212 positions for the best match is returned.
6213
6214 If there are no matching strings or there is an error, then a
6215 list with three empty list items is returned.
6216
6217 Example: >
6218 :echo matchfuzzypos(['testing'], 'tsg')
6219< results in [['testing'], [[0, 2, 6]], [99]] >
6220 :echo matchfuzzypos(['clay', 'lacy'], 'la')
6221< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
6222 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
6223< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
6224
6225matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
6226 Same as |match()|, but return a |List|. The first item in the
6227 list is the matched string, same as what matchstr() would
6228 return. Following items are submatches, like "\1", "\2", etc.
6229 in |:substitute|. When an optional submatch didn't match an
6230 empty string is used. Example: >
6231 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
6232< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
6233 When there is no match an empty list is returned.
6234
6235 You can pass in a List, but that is not very useful.
6236
6237 Can also be used as a |method|: >
6238 GetText()->matchlist('word')
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01006239<
6240 *matchstrlist()*
6241matchstrlist({list}, {pat} [, {dict}])
6242 Returns the |List| of matches in {list} where {pat} matches.
6243 {list} is a |List| of strings. {pat} is matched against each
6244 string in {list}.
6245
6246 The {dict} argument supports following items:
6247 submatches include submatch information (|/\(|)
6248
6249 For each match, a |Dict| with the following items is returned:
6250 byteidx starting byte index of the match.
6251 idx index in {list} of the match.
6252 text matched string
6253 submatches a List of submatches. Present only if
6254 "submatches" is set to v:true in {dict}.
6255
6256 Example: >
6257    :echo matchstrlist(['tik tok'], '\<\k\+\>')
6258    [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
6259    :echo matchstrlist(['a', 'b'], '\<\k\+\>')
6260    [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
6261<
6262 If "submatches" is present and is v:true, then submatches like
6263 "\1", "\2", etc. are also returned. Example: >
6264 :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
6265 \ #{submatches: v:true})
6266 [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
6267< The "submatches" List always contains 9 items. If a submatch
6268 is not found, then an empty string is returned for that
6269 submatch.
6270
6271 Can also be used as a |method|: >
6272 GetListOfStrings()->matchstrlist('mypat')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006273
6274matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
6275 Same as |match()|, but return the matched string. Example: >
6276 :echo matchstr("testing", "ing")
6277< results in "ing".
6278 When there is no match "" is returned.
6279 The {start}, if given, has the same meaning as for |match()|. >
6280 :echo matchstr("testing", "ing", 2)
6281< results in "ing". >
6282 :echo matchstr("testing", "ing", 5)
6283< result is "".
6284 When {expr} is a |List| then the matching item is returned.
6285 The type isn't changed, it's not necessarily a String.
6286
6287 Can also be used as a |method|: >
6288 GetText()->matchstr('word')
6289
6290matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
6291 Same as |matchstr()|, but return the matched string, the start
6292 position and the end position of the match. Example: >
6293 :echo matchstrpos("testing", "ing")
6294< results in ["ing", 4, 7].
6295 When there is no match ["", -1, -1] is returned.
6296 The {start}, if given, has the same meaning as for |match()|. >
6297 :echo matchstrpos("testing", "ing", 2)
6298< results in ["ing", 4, 7]. >
6299 :echo matchstrpos("testing", "ing", 5)
6300< result is ["", -1, -1].
6301 When {expr} is a |List| then the matching item, the index
6302 of first item where {pat} matches, the start position and the
6303 end position of the match are returned. >
6304 :echo matchstrpos([1, '__x'], '\a')
6305< result is ["x", 1, 2, 3].
6306 The type isn't changed, it's not necessarily a String.
6307
6308 Can also be used as a |method|: >
6309 GetText()->matchstrpos('word')
6310<
6311
6312 *max()*
6313max({expr}) Return the maximum value of all items in {expr}. Example: >
6314 echo max([apples, pears, oranges])
6315
6316< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6317 it returns the maximum of all values in the Dictionary.
6318 If {expr} is neither a List nor a Dictionary, or one of the
6319 items in {expr} cannot be used as a Number this results in
6320 an error. An empty |List| or |Dictionary| results in zero.
6321
6322 Can also be used as a |method|: >
6323 mylist->max()
6324
6325
6326menu_info({name} [, {mode}]) *menu_info()*
6327 Return information about the specified menu {name} in
6328 mode {mode}. The menu name should be specified without the
6329 shortcut character ('&'). If {name} is "", then the top-level
6330 menu names are returned.
6331
6332 {mode} can be one of these strings:
6333 "n" Normal
6334 "v" Visual (including Select)
6335 "o" Operator-pending
6336 "i" Insert
6337 "c" Cmd-line
6338 "s" Select
6339 "x" Visual
6340 "t" Terminal-Job
6341 "" Normal, Visual and Operator-pending
6342 "!" Insert and Cmd-line
6343 When {mode} is omitted, the modes for "" are used.
6344
6345 Returns a |Dictionary| containing the following items:
6346 accel menu item accelerator text |menu-text|
6347 display display name (name without '&')
6348 enabled v:true if this menu item is enabled
6349 Refer to |:menu-enable|
6350 icon name of the icon file (for toolbar)
6351 |toolbar-icon|
6352 iconidx index of a built-in icon
6353 modes modes for which the menu is defined. In
6354 addition to the modes mentioned above, these
6355 characters will be used:
6356 " " Normal, Visual and Operator-pending
6357 name menu item name.
6358 noremenu v:true if the {rhs} of the menu item is not
6359 remappable else v:false.
6360 priority menu order priority |menu-priority|
6361 rhs right-hand-side of the menu item. The returned
6362 string has special characters translated like
6363 in the output of the ":menu" command listing.
6364 When the {rhs} of a menu item is empty, then
6365 "<Nop>" is returned.
6366 script v:true if script-local remapping of {rhs} is
6367 allowed else v:false. See |:menu-script|.
6368 shortcut shortcut key (character after '&' in
6369 the menu name) |menu-shortcut|
6370 silent v:true if the menu item is created
6371 with <silent> argument |:menu-silent|
6372 submenus |List| containing the names of
6373 all the submenus. Present only if the menu
6374 item has submenus.
6375
6376 Returns an empty dictionary if the menu item is not found.
6377
6378 Examples: >
6379 :echo menu_info('Edit.Cut')
6380 :echo menu_info('File.Save', 'n')
6381
6382 " Display the entire menu hierarchy in a buffer
6383 func ShowMenu(name, pfx)
6384 let m = menu_info(a:name)
6385 call append(line('$'), a:pfx .. m.display)
6386 for child in m->get('submenus', [])
6387 call ShowMenu(a:name .. '.' .. escape(child, '.'),
6388 \ a:pfx .. ' ')
6389 endfor
6390 endfunc
6391 new
6392 for topmenu in menu_info('').submenus
6393 call ShowMenu(topmenu, '')
6394 endfor
6395<
6396 Can also be used as a |method|: >
6397 GetMenuName()->menu_info('v')
6398
6399
6400< *min()*
6401min({expr}) Return the minimum value of all items in {expr}. Example: >
6402 echo min([apples, pears, oranges])
6403
6404< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6405 it returns the minimum of all values in the Dictionary.
6406 If {expr} is neither a List nor a Dictionary, or one of the
6407 items in {expr} cannot be used as a Number this results in
6408 an error. An empty |List| or |Dictionary| results in zero.
6409
6410 Can also be used as a |method|: >
6411 mylist->min()
6412
6413< *mkdir()* *E739*
Bram Moolenaar938ae282023-02-20 20:44:55 +00006414mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006415 Create directory {name}.
6416
Bram Moolenaar938ae282023-02-20 20:44:55 +00006417 When {flags} is present it must be a string. An empty string
6418 has no effect.
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006419
Bram Moolenaar938ae282023-02-20 20:44:55 +00006420 If {flags} contains "p" then intermediate directories are
6421 created as necessary.
6422
6423 If {flags} contains "D" then {name} is deleted at the end of
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006424 the current function, as with: >
6425 defer delete({name}, 'd')
6426<
Bram Moolenaar938ae282023-02-20 20:44:55 +00006427 If {flags} contains "R" then {name} is deleted recursively at
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006428 the end of the current function, as with: >
6429 defer delete({name}, 'rf')
6430< Note that when {name} has more than one part and "p" is used
6431 some directories may already exist. Only the first one that
6432 is created and what it contains is scheduled to be deleted.
6433 E.g. when using: >
6434 call mkdir('subdir/tmp/autoload', 'pR')
6435< and "subdir" already exists then "subdir/tmp" will be
6436 scheduled for deletion, like with: >
6437 defer delete('subdir/tmp', 'rf')
6438< Note that if scheduling the defer fails the directory is not
6439 deleted. This should only happen when out of memory.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006440
6441 If {prot} is given it is used to set the protection bits of
6442 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
6443 the user, readable for others). Use 0o700 to make it
6444 unreadable for others. This is only used for the last part of
6445 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
6446 created with 0o755.
6447 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006448 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006449
6450< This function is not available in the |sandbox|.
6451
6452 There is no error if the directory already exists and the "p"
6453 flag is passed (since patch 8.0.1708). However, without the
6454 "p" option the call will fail.
6455
6456 The function result is a Number, which is TRUE if the call was
6457 successful or FALSE if the directory creation failed or partly
6458 failed.
6459
6460 Not available on all systems. To check use: >
6461 :if exists("*mkdir")
6462
6463< Can also be used as a |method|: >
6464 GetName()->mkdir()
6465<
6466 *mode()*
6467mode([expr]) Return a string that indicates the current mode.
6468 If [expr] is supplied and it evaluates to a non-zero Number or
6469 a non-empty String (|non-zero-arg|), then the full mode is
6470 returned, otherwise only the first letter is returned.
6471 Also see |state()|.
6472
6473 n Normal
6474 no Operator-pending
6475 nov Operator-pending (forced characterwise |o_v|)
6476 noV Operator-pending (forced linewise |o_V|)
6477 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
6478 CTRL-V is one character
6479 niI Normal using |i_CTRL-O| in |Insert-mode|
6480 niR Normal using |i_CTRL-O| in |Replace-mode|
6481 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
6482 nt Terminal-Normal (insert goes to Terminal-Job mode)
6483 v Visual by character
6484 vs Visual by character using |v_CTRL-O| in Select mode
6485 V Visual by line
6486 Vs Visual by line using |v_CTRL-O| in Select mode
6487 CTRL-V Visual blockwise
6488 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
6489 s Select by character
6490 S Select by line
6491 CTRL-S Select blockwise
6492 i Insert
6493 ic Insert mode completion |compl-generic|
6494 ix Insert mode |i_CTRL-X| completion
6495 R Replace |R|
6496 Rc Replace mode completion |compl-generic|
6497 Rx Replace mode |i_CTRL-X| completion
6498 Rv Virtual Replace |gR|
6499 Rvc Virtual Replace mode completion |compl-generic|
6500 Rvx Virtual Replace mode |i_CTRL-X| completion
6501 c Command-line editing
h-east71ebf3b2023-09-03 17:12:55 +02006502 ct Command-line editing via Terminal-Job mode
zeertzjqfcaeb3d2023-11-28 20:46:29 +01006503 cr Command-line editing overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006504 cv Vim Ex mode |gQ|
zeertzjqfcaeb3d2023-11-28 20:46:29 +01006505 cvr Vim Ex mode while in overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006506 ce Normal Ex mode |Q|
6507 r Hit-enter prompt
6508 rm The -- more -- prompt
6509 r? A |:confirm| query of some sort
6510 ! Shell or external command is executing
6511 t Terminal-Job mode: keys go to the job
6512
6513 This is useful in the 'statusline' option or when used
6514 with |remote_expr()| In most other places it always returns
6515 "c" or "n".
6516 Note that in the future more modes and more specific modes may
6517 be added. It's better not to compare the whole string but only
6518 the leading character(s).
6519 Also see |visualmode()|.
6520
6521 Can also be used as a |method|: >
6522 DoFull()->mode()
6523
6524mzeval({expr}) *mzeval()*
6525 Evaluate MzScheme expression {expr} and return its result
6526 converted to Vim data structures.
6527 Numbers and strings are returned as they are.
6528 Pairs (including lists and improper lists) and vectors are
6529 returned as Vim |Lists|.
6530 Hash tables are represented as Vim |Dictionary| type with keys
6531 converted to strings.
6532 All other types are converted to string with display function.
6533 Examples: >
6534 :mz (define l (list 1 2 3))
6535 :mz (define h (make-hash)) (hash-set! h "list" l)
6536 :echo mzeval("l")
6537 :echo mzeval("h")
6538<
6539 Note that in a `:def` function local variables are not visible
6540 to {expr}.
6541
6542 Can also be used as a |method|: >
6543 GetExpr()->mzeval()
6544<
6545 {only available when compiled with the |+mzscheme| feature}
6546
6547nextnonblank({lnum}) *nextnonblank()*
6548 Return the line number of the first line at or below {lnum}
6549 that is not blank. Example: >
6550 if getline(nextnonblank(1)) =~ "Java"
6551< When {lnum} is invalid or there is no non-blank line at or
6552 below it, zero is returned.
6553 {lnum} is used like with |getline()|.
6554 See also |prevnonblank()|.
6555
6556 Can also be used as a |method|: >
6557 GetLnum()->nextnonblank()
6558
6559nr2char({expr} [, {utf8}]) *nr2char()*
6560 Return a string with a single character, which has the number
6561 value {expr}. Examples: >
6562 nr2char(64) returns "@"
6563 nr2char(32) returns " "
6564< When {utf8} is omitted or zero, the current 'encoding' is used.
6565 Example for "utf-8": >
6566 nr2char(300) returns I with bow character
6567< When {utf8} is TRUE, always return UTF-8 characters.
6568 Note that a NUL character in the file is specified with
6569 nr2char(10), because NULs are represented with newline
6570 characters. nr2char(0) is a real NUL and terminates the
6571 string, thus results in an empty string.
6572 To turn a list of character numbers into a string: >
6573 let list = [65, 66, 67]
6574 let str = join(map(list, {_, val -> nr2char(val)}), '')
6575< Result: "ABC"
6576
6577 Can also be used as a |method|: >
6578 GetNumber()->nr2char()
6579
6580or({expr}, {expr}) *or()*
6581 Bitwise OR on the two arguments. The arguments are converted
6582 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006583 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006584 Example: >
6585 :let bits = or(bits, 0x80)
6586< Can also be used as a |method|: >
6587 :let bits = bits->or(0x80)
6588
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006589< Rationale: The reason this is a function and not using the "|"
6590 character like many languages, is that Vi has always used "|"
6591 to separate commands. In many places it would not be clear if
6592 "|" is an operator or a command separator.
6593
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006594
6595pathshorten({path} [, {len}]) *pathshorten()*
6596 Shorten directory names in the path {path} and return the
6597 result. The tail, the file name, is kept as-is. The other
6598 components in the path are reduced to {len} letters in length.
6599 If {len} is omitted or smaller than 1 then 1 is used (single
6600 letters). Leading '~' and '.' characters are kept. Examples: >
6601 :echo pathshorten('~/.vim/autoload/myfile.vim')
6602< ~/.v/a/myfile.vim ~
6603>
6604 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
6605< ~/.vi/au/myfile.vim ~
6606 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006607 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006608
6609 Can also be used as a |method|: >
6610 GetDirectories()->pathshorten()
6611
6612perleval({expr}) *perleval()*
6613 Evaluate Perl expression {expr} in scalar context and return
6614 its result converted to Vim data structures. If value can't be
6615 converted, it is returned as a string Perl representation.
6616 Note: If you want an array or hash, {expr} must return a
6617 reference to it.
6618 Example: >
6619 :echo perleval('[1 .. 4]')
6620< [1, 2, 3, 4]
6621
6622 Note that in a `:def` function local variables are not visible
6623 to {expr}.
6624
6625 Can also be used as a |method|: >
6626 GetExpr()->perleval()
6627
6628< {only available when compiled with the |+perl| feature}
6629
6630
6631popup_ functions are documented here: |popup-functions|
6632
6633
6634pow({x}, {y}) *pow()*
6635 Return the power of {x} to the exponent {y} as a |Float|.
6636 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006637 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006638 Examples: >
6639 :echo pow(3, 3)
6640< 27.0 >
6641 :echo pow(2, 16)
6642< 65536.0 >
6643 :echo pow(32, 0.20)
6644< 2.0
6645
6646 Can also be used as a |method|: >
6647 Compute()->pow(3)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006648
6649prevnonblank({lnum}) *prevnonblank()*
6650 Return the line number of the first line at or above {lnum}
6651 that is not blank. Example: >
6652 let ind = indent(prevnonblank(v:lnum - 1))
6653< When {lnum} is invalid or there is no non-blank line at or
6654 above it, zero is returned.
6655 {lnum} is used like with |getline()|.
6656 Also see |nextnonblank()|.
6657
6658 Can also be used as a |method|: >
6659 GetLnum()->prevnonblank()
6660
6661printf({fmt}, {expr1} ...) *printf()*
6662 Return a String with {fmt}, where "%" items are replaced by
6663 the formatted form of their respective arguments. Example: >
6664 printf("%4d: E%d %.30s", lnum, errno, msg)
6665< May result in:
6666 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
6667
6668 When used as a |method| the base is passed as the second
6669 argument: >
6670 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006671<
6672 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006673
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006674 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006675 %s string
6676 %6S string right-aligned in 6 display cells
6677 %6s string right-aligned in 6 bytes
6678 %.9s string truncated to 9 bytes
6679 %c single byte
6680 %d decimal number
6681 %5d decimal number padded with spaces to 5 characters
6682 %x hex number
6683 %04x hex number padded with zeros to at least 4 characters
6684 %X hex number using upper case letters
6685 %o octal number
6686 %08b binary number padded with zeros to at least 8 chars
6687 %f floating point number as 12.23, inf, -inf or nan
6688 %F floating point number as 12.23, INF, -INF or NAN
6689 %e floating point number as 1.23e3, inf, -inf or nan
6690 %E floating point number as 1.23E3, INF, -INF or NAN
6691 %g floating point number, as %f or %e depending on value
6692 %G floating point number, as %F or %E depending on value
6693 %% the % character itself
6694
6695 Conversion specifications start with '%' and end with the
6696 conversion type. All other characters are copied unchanged to
6697 the result.
6698
6699 The "%" starts a conversion specification. The following
6700 arguments appear in sequence:
6701
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006702 % [pos-argument] [flags] [field-width] [.precision] type
6703
6704 pos-argument
6705 At most one positional argument specifier. These
6706 take the form {n$}, where n is >= 1.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006707
6708 flags
6709 Zero or more of the following flags:
6710
6711 # The value should be converted to an "alternate
6712 form". For c, d, and s conversions, this option
6713 has no effect. For o conversions, the precision
6714 of the number is increased to force the first
6715 character of the output string to a zero (except
6716 if a zero value is printed with an explicit
6717 precision of zero).
6718 For b and B conversions, a non-zero result has
6719 the string "0b" (or "0B" for B conversions)
6720 prepended to it.
6721 For x and X conversions, a non-zero result has
6722 the string "0x" (or "0X" for X conversions)
6723 prepended to it.
6724
6725 0 (zero) Zero padding. For all conversions the converted
6726 value is padded on the left with zeros rather
6727 than blanks. If a precision is given with a
6728 numeric conversion (d, b, B, o, x, and X), the 0
6729 flag is ignored.
6730
6731 - A negative field width flag; the converted value
6732 is to be left adjusted on the field boundary.
6733 The converted value is padded on the right with
6734 blanks, rather than on the left with blanks or
6735 zeros. A - overrides a 0 if both are given.
6736
6737 ' ' (space) A blank should be left before a positive
6738 number produced by a signed conversion (d).
6739
6740 + A sign must always be placed before a number
6741 produced by a signed conversion. A + overrides
6742 a space if both are used.
6743
6744 field-width
6745 An optional decimal digit string specifying a minimum
6746 field width. If the converted value has fewer bytes
6747 than the field width, it will be padded with spaces on
6748 the left (or right, if the left-adjustment flag has
6749 been given) to fill out the field width. For the S
6750 conversion the count is in cells.
6751
6752 .precision
6753 An optional precision, in the form of a period '.'
6754 followed by an optional digit string. If the digit
6755 string is omitted, the precision is taken as zero.
6756 This gives the minimum number of digits to appear for
6757 d, o, x, and X conversions, the maximum number of
6758 bytes to be printed from a string for s conversions,
6759 or the maximum number of cells to be printed from a
6760 string for S conversions.
6761 For floating point it is the number of digits after
6762 the decimal point.
6763
6764 type
6765 A character that specifies the type of conversion to
6766 be applied, see below.
6767
6768 A field width or precision, or both, may be indicated by an
6769 asterisk '*' instead of a digit string. In this case, a
6770 Number argument supplies the field width or precision. A
6771 negative field width is treated as a left adjustment flag
6772 followed by a positive field width; a negative precision is
6773 treated as though it were missing. Example: >
6774 :echo printf("%d: %.*s", nr, width, line)
6775< This limits the length of the text used from "line" to
6776 "width" bytes.
6777
Dominique Pellé17dca3c2023-12-14 20:36:32 +01006778 If the argument to be formatted is specified using a
6779 positional argument specifier, and a '*' is used to indicate
6780 that a number argument is to be used to specify the width or
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006781 precision, the argument(s) to be used must also be specified
6782 using a {n$} positional argument specifier. See |printf-$|.
6783
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006784 The conversion specifiers and their meanings are:
6785
6786 *printf-d* *printf-b* *printf-B* *printf-o*
6787 *printf-x* *printf-X*
6788 dbBoxX The Number argument is converted to signed decimal
6789 (d), unsigned binary (b and B), unsigned octal (o), or
6790 unsigned hexadecimal (x and X) notation. The letters
6791 "abcdef" are used for x conversions; the letters
6792 "ABCDEF" are used for X conversions.
6793 The precision, if any, gives the minimum number of
6794 digits that must appear; if the converted value
6795 requires fewer digits, it is padded on the left with
6796 zeros.
6797 In no case does a non-existent or small field width
6798 cause truncation of a numeric field; if the result of
6799 a conversion is wider than the field width, the field
6800 is expanded to contain the conversion result.
6801 The 'h' modifier indicates the argument is 16 bits.
Christ van Willegenaa90d4f2023-09-03 17:22:37 +02006802 The 'l' modifier indicates the argument is a long
6803 integer. The size will be 32 bits or 64 bits
6804 depending on your platform.
6805 The "ll" modifier indicates the argument is 64 bits.
6806 The b and B conversion specifiers never take a width
6807 modifier and always assume their argument is a 64 bit
6808 integer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006809 Generally, these modifiers are not useful. They are
6810 ignored when type is known from the argument.
6811
6812 i alias for d
6813 D alias for ld
6814 U alias for lu
6815 O alias for lo
6816
6817 *printf-c*
6818 c The Number argument is converted to a byte, and the
6819 resulting character is written.
6820
6821 *printf-s*
6822 s The text of the String argument is used. If a
6823 precision is specified, no more bytes than the number
6824 specified are used.
6825 If the argument is not a String type, it is
6826 automatically converted to text with the same format
6827 as ":echo".
6828 *printf-S*
6829 S The text of the String argument is used. If a
6830 precision is specified, no more display cells than the
6831 number specified are used.
6832
6833 *printf-f* *E807*
6834 f F The Float argument is converted into a string of the
6835 form 123.456. The precision specifies the number of
6836 digits after the decimal point. When the precision is
6837 zero the decimal point is omitted. When the precision
6838 is not specified 6 is used. A really big number
6839 (out of range or dividing by zero) results in "inf"
6840 or "-inf" with %f (INF or -INF with %F).
6841 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
6842 Example: >
6843 echo printf("%.2f", 12.115)
6844< 12.12
6845 Note that roundoff depends on the system libraries.
6846 Use |round()| when in doubt.
6847
6848 *printf-e* *printf-E*
6849 e E The Float argument is converted into a string of the
6850 form 1.234e+03 or 1.234E+03 when using 'E'. The
6851 precision specifies the number of digits after the
6852 decimal point, like with 'f'.
6853
6854 *printf-g* *printf-G*
6855 g G The Float argument is converted like with 'f' if the
6856 value is between 0.001 (inclusive) and 10000000.0
6857 (exclusive). Otherwise 'e' is used for 'g' and 'E'
6858 for 'G'. When no precision is specified superfluous
6859 zeroes and '+' signs are removed, except for the zero
6860 immediately after the decimal point. Thus 10000000.0
6861 results in 1.0e7.
6862
6863 *printf-%*
6864 % A '%' is written. No argument is converted. The
6865 complete conversion specification is "%%".
6866
6867 When a Number argument is expected a String argument is also
6868 accepted and automatically converted.
6869 When a Float or String argument is expected a Number argument
6870 is also accepted and automatically converted.
6871 Any other argument type results in an error message.
6872
6873 *E766* *E767*
6874 The number of {exprN} arguments must exactly match the number
6875 of "%" items. If there are not sufficient or too many
6876 arguments an error is given. Up to 18 arguments can be used.
6877
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006878 *printf-$*
6879 In certain languages, error and informative messages are
6880 more readable when the order of words is different from the
Christian Brabandtee17b6f2023-09-09 11:23:50 +02006881 corresponding message in English. To accommodate translations
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006882 having a different word order, positional arguments may be
6883 used to indicate this. For instance: >
6884
h_east596a9f22023-11-21 21:24:23 +09006885 #, c-format
6886 msgid "%s returning %s"
6887 msgstr "waarde %2$s komt terug van %1$s"
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006888<
h_east596a9f22023-11-21 21:24:23 +09006889 In this example, the sentence has its 2 string arguments
6890 reversed in the output. >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006891
h_east596a9f22023-11-21 21:24:23 +09006892 echo printf(
6893 "In The Netherlands, vim's creator's name is: %1$s %2$s",
6894 "Bram", "Moolenaar")
6895< In The Netherlands, vim's creator's name is: Bram Moolenaar >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006896
h_east596a9f22023-11-21 21:24:23 +09006897 echo printf(
6898 "In Belgium, vim's creator's name is: %2$s %1$s",
6899 "Bram", "Moolenaar")
6900< In Belgium, vim's creator's name is: Moolenaar Bram
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006901
6902 Width (and precision) can be specified using the '*' specifier.
6903 In this case, you must specify the field width position in the
6904 argument list. >
6905
h_east596a9f22023-11-21 21:24:23 +09006906 echo printf("%1$*2$.*3$d", 1, 2, 3)
6907< 001 >
6908 echo printf("%2$*3$.*1$d", 1, 2, 3)
6909< 2 >
6910 echo printf("%3$*1$.*2$d", 1, 2, 3)
6911< 03 >
6912 echo printf("%1$*2$.*3$g", 1.4142, 2, 3)
6913< 1.414
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006914
6915 You can mix specifying the width and/or precision directly
6916 and via positional arguments: >
6917
h_east596a9f22023-11-21 21:24:23 +09006918 echo printf("%1$4.*2$f", 1.4142135, 6)
6919< 1.414214 >
6920 echo printf("%1$*2$.4f", 1.4142135, 6)
6921< 1.4142 >
6922 echo printf("%1$*2$.*3$f", 1.4142135, 6, 2)
6923< 1.41
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006924
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02006925 *E1500*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006926 You cannot mix positional and non-positional arguments: >
h_east596a9f22023-11-21 21:24:23 +09006927 echo printf("%s%1$s", "One", "Two")
6928< E1500: Cannot mix positional and non-positional arguments:
6929 %s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006930
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02006931 *E1501*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006932 You cannot skip a positional argument in a format string: >
h_east596a9f22023-11-21 21:24:23 +09006933 echo printf("%3$s%1$s", "One", "Two", "Three")
6934< E1501: format argument 2 unused in $-style format:
6935 %3$s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006936
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02006937 *E1502*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006938 You can re-use a [field-width] (or [precision]) argument: >
h_east596a9f22023-11-21 21:24:23 +09006939 echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2)
6940< 1 at width 2 is: 01
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006941
6942 However, you can't use it as a different type: >
h_east596a9f22023-11-21 21:24:23 +09006943 echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2)
6944< E1502: Positional argument 2 used as field width reused as
6945 different type: long int/int
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006946
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02006947 *E1503*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006948 When a positional argument is used, but not the correct number
6949 or arguments is given, an error is raised: >
h_east596a9f22023-11-21 21:24:23 +09006950 echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2)
6951< E1503: Positional argument 3 out of bounds: %1$d at width
6952 %2$d is: %01$*2$.*3$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006953
6954 Only the first error is reported: >
h_east596a9f22023-11-21 21:24:23 +09006955 echo printf("%01$*2$.*3$d %4$d", 1, 2)
6956< E1503: Positional argument 3 out of bounds: %01$*2$.*3$d
6957 %4$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006958
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02006959 *E1504*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006960 A positional argument can be used more than once: >
h_east596a9f22023-11-21 21:24:23 +09006961 echo printf("%1$s %2$s %1$s", "One", "Two")
6962< One Two One
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006963
6964 However, you can't use a different type the second time: >
h_east596a9f22023-11-21 21:24:23 +09006965 echo printf("%1$s %2$s %1$d", "One", "Two")
6966< E1504: Positional argument 1 type used inconsistently:
6967 int/string
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006968
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02006969 *E1505*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02006970 Various other errors that lead to a format string being
6971 wrongly formatted lead to: >
h_east596a9f22023-11-21 21:24:23 +09006972 echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2)
6973< E1505: Invalid format specifier: %1$d at width %2$d is:
6974 %01$*2$.3$d
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006975
Christ van Willegenea746f92023-10-05 20:48:36 +02006976 *E1507*
zeertzjq27e12c72023-10-07 01:34:04 +08006977 This internal error indicates that the logic to parse a
6978 positional format argument ran into a problem that couldn't be
6979 otherwise reported. Please file a bug against Vim if you run
6980 into this, copying the exact format string and parameters that
6981 were used.
Christ van Willegenea746f92023-10-05 20:48:36 +02006982
6983
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006984prompt_getprompt({buf}) *prompt_getprompt()*
6985 Returns the effective prompt text for buffer {buf}. {buf} can
6986 be a buffer name or number. See |prompt-buffer|.
6987
6988 If the buffer doesn't exist or isn't a prompt buffer, an empty
6989 string is returned.
6990
6991 Can also be used as a |method|: >
6992 GetBuffer()->prompt_getprompt()
6993
6994< {only available when compiled with the |+channel| feature}
6995
6996
6997prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
6998 Set prompt callback for buffer {buf} to {expr}. When {expr}
6999 is an empty string the callback is removed. This has only
7000 effect if {buf} has 'buftype' set to "prompt".
7001
7002 The callback is invoked when pressing Enter. The current
7003 buffer will always be the prompt buffer. A new line for a
7004 prompt is added before invoking the callback, thus the prompt
7005 for which the callback was invoked will be in the last but one
7006 line.
7007 If the callback wants to add text to the buffer, it must
7008 insert it above the last line, since that is where the current
7009 prompt is. This can also be done asynchronously.
7010 The callback is invoked with one argument, which is the text
7011 that was entered at the prompt. This can be an empty string
7012 if the user only typed Enter.
7013 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007014 func s:TextEntered(text)
7015 if a:text == 'exit' || a:text == 'quit'
7016 stopinsert
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01007017 " Reset 'modified' to allow the buffer to be closed.
7018 " We assume there is nothing useful to be saved.
7019 set nomodified
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007020 close
7021 else
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01007022 " Do something useful with "a:text". In this example
7023 " we just repeat it.
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007024 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007025 endif
7026 endfunc
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01007027 call prompt_setcallback(bufnr(), function('s:TextEntered'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007028
7029< Can also be used as a |method|: >
7030 GetBuffer()->prompt_setcallback(callback)
7031
7032< {only available when compiled with the |+channel| feature}
7033
7034prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
7035 Set a callback for buffer {buf} to {expr}. When {expr} is an
7036 empty string the callback is removed. This has only effect if
7037 {buf} has 'buftype' set to "prompt".
7038
7039 This callback will be invoked when pressing CTRL-C in Insert
7040 mode. Without setting a callback Vim will exit Insert mode,
7041 as in any buffer.
7042
7043 Can also be used as a |method|: >
7044 GetBuffer()->prompt_setinterrupt(callback)
7045
7046< {only available when compiled with the |+channel| feature}
7047
7048prompt_setprompt({buf}, {text}) *prompt_setprompt()*
7049 Set prompt for buffer {buf} to {text}. You most likely want
7050 {text} to end in a space.
7051 The result is only visible if {buf} has 'buftype' set to
7052 "prompt". Example: >
7053 call prompt_setprompt(bufnr(), 'command: ')
7054<
7055 Can also be used as a |method|: >
7056 GetBuffer()->prompt_setprompt('command: ')
7057
7058< {only available when compiled with the |+channel| feature}
7059
7060prop_ functions are documented here: |text-prop-functions|
7061
7062pum_getpos() *pum_getpos()*
7063 If the popup menu (see |ins-completion-menu|) is not visible,
7064 returns an empty |Dictionary|, otherwise, returns a
7065 |Dictionary| with the following keys:
7066 height nr of items visible
7067 width screen cells
7068 row top screen row (0 first row)
7069 col leftmost screen column (0 first col)
7070 size total nr of items
7071 scrollbar |TRUE| if scrollbar is visible
7072
7073 The values are the same as in |v:event| during
7074 |CompleteChanged|.
7075
7076pumvisible() *pumvisible()*
7077 Returns non-zero when the popup menu is visible, zero
7078 otherwise. See |ins-completion-menu|.
7079 This can be used to avoid some things that would remove the
7080 popup menu.
7081
7082py3eval({expr}) *py3eval()*
7083 Evaluate Python expression {expr} and return its result
7084 converted to Vim data structures.
7085 Numbers and strings are returned as they are (strings are
7086 copied though, Unicode strings are additionally converted to
7087 'encoding').
7088 Lists are represented as Vim |List| type.
7089 Dictionaries are represented as Vim |Dictionary| type with
7090 keys converted to strings.
7091 Note that in a `:def` function local variables are not visible
7092 to {expr}.
7093
7094 Can also be used as a |method|: >
7095 GetExpr()->py3eval()
7096
7097< {only available when compiled with the |+python3| feature}
7098
7099 *E858* *E859*
7100pyeval({expr}) *pyeval()*
7101 Evaluate Python expression {expr} and return its result
7102 converted to Vim data structures.
7103 Numbers and strings are returned as they are (strings are
7104 copied though).
7105 Lists are represented as Vim |List| type.
7106 Dictionaries are represented as Vim |Dictionary| type,
7107 non-string keys result in error.
7108 Note that in a `:def` function local variables are not visible
7109 to {expr}.
7110
7111 Can also be used as a |method|: >
7112 GetExpr()->pyeval()
7113
7114< {only available when compiled with the |+python| feature}
7115
7116pyxeval({expr}) *pyxeval()*
7117 Evaluate Python expression {expr} and return its result
7118 converted to Vim data structures.
7119 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
7120 See also: |pyeval()|, |py3eval()|
7121
7122 Can also be used as a |method|: >
7123 GetExpr()->pyxeval()
7124
7125< {only available when compiled with the |+python| or the
7126 |+python3| feature}
7127
7128rand([{expr}]) *rand()* *random*
7129 Return a pseudo-random Number generated with an xoshiro128**
7130 algorithm using seed {expr}. The returned number is 32 bits,
7131 also on 64 bits systems, for consistency.
7132 {expr} can be initialized by |srand()| and will be updated by
7133 rand(). If {expr} is omitted, an internal seed value is used
7134 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007135 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007136
7137 Examples: >
7138 :echo rand()
7139 :let seed = srand()
7140 :echo rand(seed)
7141 :echo rand(seed) % 16 " random number 0 - 15
7142<
7143
7144 *E726* *E727*
7145range({expr} [, {max} [, {stride}]]) *range()*
7146 Returns a |List| with Numbers:
7147 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
7148 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
7149 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
7150 {max}] (increasing {expr} with {stride} each time, not
7151 producing a value past {max}).
7152 When the maximum is one before the start the result is an
7153 empty list. When the maximum is more than one before the
7154 start this is an error.
7155 Examples: >
7156 range(4) " [0, 1, 2, 3]
7157 range(2, 4) " [2, 3, 4]
7158 range(2, 9, 3) " [2, 5, 8]
7159 range(2, -2, -1) " [2, 1, 0, -1, -2]
7160 range(0) " []
7161 range(2, 0) " error!
7162<
7163 Can also be used as a |method|: >
7164 GetExpr()->range()
7165<
7166
K.Takata11df3ae2022-10-19 14:02:40 +01007167readblob({fname} [, {offset} [, {size}]]) *readblob()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007168 Read file {fname} in binary mode and return a |Blob|.
K.Takata11df3ae2022-10-19 14:02:40 +01007169 If {offset} is specified, read the file from the specified
7170 offset. If it is a negative value, it is used as an offset
7171 from the end of the file. E.g., to read the last 12 bytes: >
7172 readblob('file.bin', -12)
7173< If {size} is specified, only the specified size will be read.
7174 E.g. to read the first 100 bytes of a file: >
7175 readblob('file.bin', 0, 100)
7176< If {size} is -1 or omitted, the whole data starting from
7177 {offset} will be read.
K.Takata43625762022-10-20 13:28:51 +01007178 This can be also used to read the data from a character device
7179 on Unix when {size} is explicitly set. Only if the device
7180 supports seeking {offset} can be used. Otherwise it should be
7181 zero. E.g. to read 10 bytes from a serial console: >
7182 readblob('/dev/ttyS0', 0, 10)
7183< When the file can't be opened an error message is given and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007184 the result is an empty |Blob|.
Bram Moolenaar5b2a3d72022-10-21 11:25:30 +01007185 When the offset is beyond the end of the file the result is an
7186 empty blob.
7187 When trying to read more bytes than are available the result
7188 is truncated.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007189 Also see |readfile()| and |writefile()|.
7190
7191
7192readdir({directory} [, {expr} [, {dict}]]) *readdir()*
7193 Return a list with file and directory names in {directory}.
7194 You can also use |glob()| if you don't need to do complicated
7195 things, such as limiting the number of matches.
7196 The list will be sorted (case sensitive), see the {dict}
7197 argument below for changing the sort order.
7198
7199 When {expr} is omitted all entries are included.
7200 When {expr} is given, it is evaluated to check what to do:
7201 If {expr} results in -1 then no further entries will
7202 be handled.
7203 If {expr} results in 0 then this entry will not be
7204 added to the list.
7205 If {expr} results in 1 then this entry will be added
7206 to the list.
7207 The entries "." and ".." are always excluded.
7208 Each time {expr} is evaluated |v:val| is set to the entry name.
7209 When {expr} is a function the name is passed as the argument.
7210 For example, to get a list of files ending in ".txt": >
7211 readdir(dirname, {n -> n =~ '.txt$'})
7212< To skip hidden and backup files: >
7213 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00007214< *E857*
7215 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007216 values. Currently this is used to specify if and how sorting
7217 should be performed. The dict can have the following members:
7218
7219 sort How to sort the result returned from the system.
7220 Valid values are:
7221 "none" do not sort (fastest method)
7222 "case" sort case sensitive (byte value of
7223 each character, technically, using
7224 strcmp()) (default)
7225 "icase" sort case insensitive (technically
7226 using strcasecmp())
7227 "collate" sort using the collation order
7228 of the "POSIX" or "C" |locale|
7229 (technically using strcoll())
7230 Other values are silently ignored.
7231
7232 For example, to get a list of all files in the current
7233 directory without sorting the individual entries: >
7234 readdir('.', '1', #{sort: 'none'})
7235< If you want to get a directory tree: >
7236 function! s:tree(dir)
7237 return {a:dir : map(readdir(a:dir),
7238 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007239 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007240 endfunction
7241 echo s:tree(".")
7242<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007243 Returns an empty List on error.
7244
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007245 Can also be used as a |method|: >
7246 GetDirName()->readdir()
7247<
7248readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
7249 Extended version of |readdir()|.
7250 Return a list of Dictionaries with file and directory
7251 information in {directory}.
7252 This is useful if you want to get the attributes of file and
7253 directory at the same time as getting a list of a directory.
7254 This is much faster than calling |readdir()| then calling
7255 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
7256 each file and directory especially on MS-Windows.
7257 The list will by default be sorted by name (case sensitive),
7258 the sorting can be changed by using the optional {dict}
7259 argument, see |readdir()|.
7260
7261 The Dictionary for file and directory information has the
7262 following items:
7263 group Group name of the entry. (Only on Unix)
7264 name Name of the entry.
7265 perm Permissions of the entry. See |getfperm()|.
7266 size Size of the entry. See |getfsize()|.
7267 time Timestamp of the entry. See |getftime()|.
7268 type Type of the entry.
7269 On Unix, almost same as |getftype()| except:
7270 Symlink to a dir "linkd"
7271 Other symlink "link"
7272 On MS-Windows:
7273 Normal file "file"
7274 Directory "dir"
7275 Junction "junction"
7276 Symlink to a dir "linkd"
7277 Other symlink "link"
7278 Other reparse point "reparse"
7279 user User name of the entry's owner. (Only on Unix)
7280 On Unix, if the entry is a symlink, the Dictionary includes
7281 the information of the target (except the "type" item).
7282 On MS-Windows, it includes the information of the symlink
7283 itself because of performance reasons.
7284
7285 When {expr} is omitted all entries are included.
7286 When {expr} is given, it is evaluated to check what to do:
7287 If {expr} results in -1 then no further entries will
7288 be handled.
7289 If {expr} results in 0 then this entry will not be
7290 added to the list.
7291 If {expr} results in 1 then this entry will be added
7292 to the list.
7293 The entries "." and ".." are always excluded.
7294 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
7295 of the entry.
7296 When {expr} is a function the entry is passed as the argument.
7297 For example, to get a list of files ending in ".txt": >
7298 readdirex(dirname, {e -> e.name =~ '.txt$'})
7299<
7300 For example, to get a list of all files in the current
7301 directory without sorting the individual entries: >
7302 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007303<
7304 Can also be used as a |method|: >
7305 GetDirName()->readdirex()
7306<
7307
7308 *readfile()*
7309readfile({fname} [, {type} [, {max}]])
7310 Read file {fname} and return a |List|, each line of the file
7311 as an item. Lines are broken at NL characters. Macintosh
7312 files separated with CR will result in a single long line
7313 (unless a NL appears somewhere).
7314 All NUL characters are replaced with a NL character.
7315 When {type} contains "b" binary mode is used:
7316 - When the last line ends in a NL an extra empty list item is
7317 added.
7318 - No CR characters are removed.
7319 Otherwise:
7320 - CR characters that appear before a NL are removed.
7321 - Whether the last line ends in a NL or not does not matter.
7322 - When 'encoding' is Unicode any UTF-8 byte order mark is
7323 removed from the text.
7324 When {max} is given this specifies the maximum number of lines
7325 to be read. Useful if you only want to check the first ten
7326 lines of a file: >
7327 :for line in readfile(fname, '', 10)
7328 : if line =~ 'Date' | echo line | endif
7329 :endfor
7330< When {max} is negative -{max} lines from the end of the file
7331 are returned, or as many as there are.
7332 When {max} is zero the result is an empty list.
7333 Note that without {max} the whole file is read into memory.
7334 Also note that there is no recognition of encoding. Read a
7335 file into a buffer if you need to.
7336 Deprecated (use |readblob()| instead): When {type} contains
7337 "B" a |Blob| is returned with the binary data of the file
7338 unmodified.
7339 When the file can't be opened an error message is given and
7340 the result is an empty list.
7341 Also see |writefile()|.
7342
7343 Can also be used as a |method|: >
7344 GetFileName()->readfile()
7345
7346reduce({object}, {func} [, {initial}]) *reduce()* *E998*
7347 {func} is called for every item in {object}, which can be a
7348 |String|, |List| or a |Blob|. {func} is called with two
7349 arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00007350 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007351
7352 {initial} is the initial result. When omitted, the first item
7353 in {object} is used and {func} is first called for the second
7354 item. If {initial} is not given and {object} is empty no
7355 result can be computed, an E998 error is given.
7356
7357 Examples: >
7358 echo reduce([1, 3, 5], { acc, val -> acc + val })
7359 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
7360 echo reduce(0z1122, { acc, val -> 2 * acc + val })
7361 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
7362<
7363 Can also be used as a |method|: >
7364 echo mylist->reduce({ acc, val -> acc + val }, 0)
7365
7366
7367reg_executing() *reg_executing()*
7368 Returns the single letter name of the register being executed.
7369 Returns an empty string when no register is being executed.
7370 See |@|.
7371
7372reg_recording() *reg_recording()*
7373 Returns the single letter name of the register being recorded.
7374 Returns an empty string when not recording. See |q|.
7375
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007376reltime()
7377reltime({start})
7378reltime({start}, {end}) *reltime()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007379 Return an item that represents a time value. The item is a
7380 list with items that depend on the system. In Vim 9 script
Bram Moolenaar71badf92023-04-22 22:40:14 +01007381 the type list<any> can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007382 The item can be passed to |reltimestr()| to convert it to a
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007383 string or |reltimefloat()| to convert to a Float. For
7384 example, to see the time spent in function Work(): >
7385 var startTime = reltime()
7386 Work()
7387 echo startTime->reltime()->reltimestr()
7388<
Bram Moolenaar016188f2022-06-06 20:52:59 +01007389 Without an argument reltime() returns the current time (the
Bram Moolenaareb490412022-06-28 13:44:46 +01007390 representation is system-dependent, it can not be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01007391 wall-clock time, see |localtime()| for that).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007392 With one argument is returns the time passed since the time
7393 specified in the argument.
7394 With two arguments it returns the time passed between {start}
7395 and {end}.
7396
7397 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007398 reltime(). If there is an error an empty List is returned in
7399 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007400
7401 Can also be used as a |method|: >
7402 GetStart()->reltime()
7403<
7404 {only available when compiled with the |+reltime| feature}
7405
7406reltimefloat({time}) *reltimefloat()*
7407 Return a Float that represents the time value of {time}.
7408 Example: >
7409 let start = reltime()
7410 call MyFunction()
7411 let seconds = reltimefloat(reltime(start))
7412< See the note of reltimestr() about overhead.
7413 Also see |profiling|.
7414 If there is an error 0.0 is returned in legacy script, in Vim9
7415 script an error is given.
7416
7417 Can also be used as a |method|: >
7418 reltime(start)->reltimefloat()
7419
7420< {only available when compiled with the |+reltime| feature}
7421
7422reltimestr({time}) *reltimestr()*
7423 Return a String that represents the time value of {time}.
7424 This is the number of seconds, a dot and the number of
7425 microseconds. Example: >
7426 let start = reltime()
7427 call MyFunction()
7428 echo reltimestr(reltime(start))
7429< Note that overhead for the commands will be added to the time.
Ernie Rael076de792023-03-16 21:43:15 +00007430 The accuracy depends on the system. Use reltimefloat() for the
7431 greatest accuracy which is nanoseconds on some systems.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007432 Leading spaces are used to make the string align nicely. You
7433 can use split() to remove it. >
7434 echo split(reltimestr(reltime(start)))[0]
7435< Also see |profiling|.
7436 If there is an error an empty string is returned in legacy
7437 script, in Vim9 script an error is given.
7438
7439 Can also be used as a |method|: >
7440 reltime(start)->reltimestr()
7441
7442< {only available when compiled with the |+reltime| feature}
7443
7444 *remote_expr()* *E449*
7445remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007446 Send the {string} to {server}. The {server} argument is a
7447 string, also see |{server}|.
7448
7449 The string is sent as an expression and the result is returned
7450 after evaluation. The result must be a String or a |List|. A
7451 |List| is turned into a String by joining the items with a
7452 line break in between (not at the end), like with join(expr,
7453 "\n").
7454
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007455 If {idvar} is present and not empty, it is taken as the name
7456 of a variable and a {serverid} for later use with
7457 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007458
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007459 If {timeout} is given the read times out after this many
7460 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007461
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007462 See also |clientserver| |RemoteReply|.
7463 This function is not available in the |sandbox|.
7464 {only available when compiled with the |+clientserver| feature}
7465 Note: Any errors will cause a local error message to be issued
7466 and the result will be the empty string.
7467
7468 Variables will be evaluated in the global namespace,
7469 independent of a function currently being active. Except
7470 when in debug mode, then local function variables and
7471 arguments can be evaluated.
7472
7473 Examples: >
7474 :echo remote_expr("gvim", "2+2")
7475 :echo remote_expr("gvim1", "b:current_syntax")
7476<
7477 Can also be used as a |method|: >
7478 ServerName()->remote_expr(expr)
7479
7480remote_foreground({server}) *remote_foreground()*
7481 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007482 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007483 This works like: >
7484 remote_expr({server}, "foreground()")
7485< Except that on Win32 systems the client does the work, to work
7486 around the problem that the OS doesn't always allow the server
7487 to bring itself to the foreground.
7488 Note: This does not restore the window if it was minimized,
7489 like foreground() does.
7490 This function is not available in the |sandbox|.
7491
7492 Can also be used as a |method|: >
7493 ServerName()->remote_foreground()
7494
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007495< {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007496 Win32 console version}
7497
7498
7499remote_peek({serverid} [, {retvar}]) *remote_peek()*
7500 Returns a positive number if there are available strings
7501 from {serverid}. Copies any reply string into the variable
7502 {retvar} if specified. {retvar} must be a string with the
7503 name of a variable.
7504 Returns zero if none are available.
7505 Returns -1 if something is wrong.
7506 See also |clientserver|.
7507 This function is not available in the |sandbox|.
7508 {only available when compiled with the |+clientserver| feature}
7509 Examples: >
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007510 :let repl = ""
7511 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007512
7513< Can also be used as a |method|: >
7514 ServerId()->remote_peek()
7515
7516remote_read({serverid}, [{timeout}]) *remote_read()*
7517 Return the oldest available reply from {serverid} and consume
7518 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007519 reply is available. Returns an empty string, if a reply is
7520 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007521 See also |clientserver|.
7522 This function is not available in the |sandbox|.
7523 {only available when compiled with the |+clientserver| feature}
7524 Example: >
7525 :echo remote_read(id)
7526
7527< Can also be used as a |method|: >
7528 ServerId()->remote_read()
7529<
7530 *remote_send()* *E241*
7531remote_send({server}, {string} [, {idvar}])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007532 Send the {string} to {server}. The {server} argument is a
7533 string, also see |{server}|.
7534
7535 The string is sent as input keys and the function returns
7536 immediately. At the Vim server the keys are not mapped
7537 |:map|.
7538
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007539 If {idvar} is present, it is taken as the name of a variable
7540 and a {serverid} for later use with remote_read() is stored
7541 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007542
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007543 See also |clientserver| |RemoteReply|.
7544 This function is not available in the |sandbox|.
7545 {only available when compiled with the |+clientserver| feature}
7546
7547 Note: Any errors will be reported in the server and may mess
7548 up the display.
7549 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007550 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007551 \ remote_read(serverid)
7552
7553 :autocmd NONE RemoteReply *
7554 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007555 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007556 \ 'server2client(expand("<client>"), "HELLO")<CR>')
7557<
7558 Can also be used as a |method|: >
7559 ServerName()->remote_send(keys)
7560<
7561 *remote_startserver()* *E941* *E942*
7562remote_startserver({name})
h-east17b69512023-05-01 22:36:56 +01007563 Become the server {name}. {name} must be a non-empty string.
7564 This fails if already running as a server, when |v:servername|
7565 is not empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007566
7567 Can also be used as a |method|: >
7568 ServerName()->remote_startserver()
7569
7570< {only available when compiled with the |+clientserver| feature}
7571
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007572remove({list}, {idx})
7573remove({list}, {idx}, {end}) *remove()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007574 Without {end}: Remove the item at {idx} from |List| {list} and
7575 return the item.
7576 With {end}: Remove items from {idx} to {end} (inclusive) and
7577 return a |List| with these items. When {idx} points to the same
7578 item as {end} a list with one item is returned. When {end}
7579 points to an item before {idx} this is an error.
7580 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007581 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007582 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007583 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007584 :call remove(mylist, 0, 9)
7585<
7586 Use |delete()| to remove a file.
7587
7588 Can also be used as a |method|: >
7589 mylist->remove(idx)
7590
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007591remove({blob}, {idx})
7592remove({blob}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007593 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
7594 return the byte.
7595 With {end}: Remove bytes from {idx} to {end} (inclusive) and
7596 return a |Blob| with these bytes. When {idx} points to the same
7597 byte as {end} a |Blob| with one byte is returned. When {end}
7598 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007599 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007600 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007601 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007602 :call remove(mylist, 0, 9)
7603
7604remove({dict}, {key})
7605 Remove the entry from {dict} with key {key} and return it.
7606 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007607 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007608< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007609 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007610
7611rename({from}, {to}) *rename()*
7612 Rename the file by the name {from} to the name {to}. This
7613 should also work to move files across file systems. The
7614 result is a Number, which is 0 if the file was renamed
7615 successfully, and non-zero when the renaming failed.
7616 NOTE: If {to} exists it is overwritten without warning.
7617 This function is not available in the |sandbox|.
7618
7619 Can also be used as a |method|: >
7620 GetOldName()->rename(newname)
7621
7622repeat({expr}, {count}) *repeat()*
7623 Repeat {expr} {count} times and return the concatenated
7624 result. Example: >
7625 :let separator = repeat('-', 80)
7626< When {count} is zero or negative the result is empty.
Bakudankun375141e2022-09-09 18:46:47 +01007627 When {expr} is a |List| or a |Blob| the result is {expr}
7628 concatenated {count} times. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007629 :let longlist = repeat(['a', 'b'], 3)
7630< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
7631
7632 Can also be used as a |method|: >
7633 mylist->repeat(count)
7634
7635resolve({filename}) *resolve()* *E655*
7636 On MS-Windows, when {filename} is a shortcut (a .lnk file),
7637 returns the path the shortcut points to in a simplified form.
7638 When {filename} is a symbolic link or junction point, return
7639 the full path to the target. If the target of junction is
7640 removed, return {filename}.
7641 On Unix, repeat resolving symbolic links in all path
7642 components of {filename} and return the simplified result.
7643 To cope with link cycles, resolving of symbolic links is
7644 stopped after 100 iterations.
7645 On other systems, return the simplified {filename}.
7646 The simplification step is done as by |simplify()|.
7647 resolve() keeps a leading path component specifying the
7648 current directory (provided the result is still a relative
7649 path name) and also keeps a trailing path separator.
7650
7651 Can also be used as a |method|: >
7652 GetName()->resolve()
7653
7654reverse({object}) *reverse()*
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +01007655 Reverse the order of items in {object}. {object} can be a
7656 |List|, a |Blob| or a |String|. For a List and a Blob the
7657 items are reversed in-place and {object} is returned.
7658 For a String a new String is returned.
7659 Returns zero if {object} is not a List, Blob or a String.
7660 If you want a List or Blob to remain unmodified make a copy
7661 first: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007662 :let revlist = reverse(copy(mylist))
7663< Can also be used as a |method|: >
7664 mylist->reverse()
7665
7666round({expr}) *round()*
7667 Round off {expr} to the nearest integral value and return it
7668 as a |Float|. If {expr} lies halfway between two integral
7669 values, then use the larger one (away from zero).
7670 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007671 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007672 Examples: >
7673 echo round(0.456)
7674< 0.0 >
7675 echo round(4.5)
7676< 5.0 >
7677 echo round(-4.5)
7678< -5.0
7679
7680 Can also be used as a |method|: >
7681 Compute()->round()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007682
7683rubyeval({expr}) *rubyeval()*
7684 Evaluate Ruby expression {expr} and return its result
7685 converted to Vim data structures.
7686 Numbers, floats and strings are returned as they are (strings
7687 are copied though).
7688 Arrays are represented as Vim |List| type.
7689 Hashes are represented as Vim |Dictionary| type.
7690 Other objects are represented as strings resulted from their
7691 "Object#to_s" method.
7692 Note that in a `:def` function local variables are not visible
7693 to {expr}.
7694
7695 Can also be used as a |method|: >
7696 GetRubyExpr()->rubyeval()
7697
7698< {only available when compiled with the |+ruby| feature}
7699
7700screenattr({row}, {col}) *screenattr()*
7701 Like |screenchar()|, but return the attribute. This is a rather
7702 arbitrary number that can only be used to compare to the
7703 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007704 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007705
7706 Can also be used as a |method|: >
7707 GetRow()->screenattr(col)
7708
7709screenchar({row}, {col}) *screenchar()*
7710 The result is a Number, which is the character at position
7711 [row, col] on the screen. This works for every possible
7712 screen position, also status lines, window separators and the
7713 command line. The top left position is row one, column one
7714 The character excludes composing characters. For double-byte
7715 encodings it may only be the first byte.
7716 This is mainly to be used for testing.
7717 Returns -1 when row or col is out of range.
7718
7719 Can also be used as a |method|: >
7720 GetRow()->screenchar(col)
7721
7722screenchars({row}, {col}) *screenchars()*
7723 The result is a |List| of Numbers. The first number is the same
7724 as what |screenchar()| returns. Further numbers are
7725 composing characters on top of the base character.
7726 This is mainly to be used for testing.
7727 Returns an empty List when row or col is out of range.
7728
7729 Can also be used as a |method|: >
7730 GetRow()->screenchars(col)
7731
7732screencol() *screencol()*
7733 The result is a Number, which is the current screen column of
7734 the cursor. The leftmost column has number 1.
7735 This function is mainly used for testing.
7736
7737 Note: Always returns the current screen column, thus if used
7738 in a command (e.g. ":echo screencol()") it will return the
7739 column inside the command line, which is 1 when the command is
7740 executed. To get the cursor position in the file use one of
7741 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007742 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007743 nnoremap <silent> GG :echom screencol()<CR>
7744 nnoremap GG <Cmd>echom screencol()<CR>
7745<
7746screenpos({winid}, {lnum}, {col}) *screenpos()*
7747 The result is a Dict with the screen position of the text
7748 character in window {winid} at buffer line {lnum} and column
7749 {col}. {col} is a one-based byte index.
7750 The Dict has these members:
7751 row screen row
7752 col first screen column
7753 endcol last screen column
7754 curscol cursor screen column
7755 If the specified position is not visible, all values are zero.
7756 The "endcol" value differs from "col" when the character
7757 occupies more than one screen cell. E.g. for a Tab "col" can
7758 be 1 and "endcol" can be 8.
7759 The "curscol" value is where the cursor would be placed. For
7760 a Tab it would be the same as "endcol", while for a double
7761 width character it would be the same as "col".
7762 The |conceal| feature is ignored here, the column numbers are
7763 as if 'conceallevel' is zero. You can set the cursor to the
7764 right position and use |screencol()| to get the value with
7765 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007766 If the position is in a closed fold the screen position of the
7767 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007768 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007769
7770 Can also be used as a |method|: >
7771 GetWinid()->screenpos(lnum, col)
7772
7773screenrow() *screenrow()*
7774 The result is a Number, which is the current screen row of the
7775 cursor. The top line has number one.
7776 This function is mainly used for testing.
7777 Alternatively you can use |winline()|.
7778
7779 Note: Same restrictions as with |screencol()|.
7780
7781screenstring({row}, {col}) *screenstring()*
7782 The result is a String that contains the base character and
7783 any composing characters at position [row, col] on the screen.
7784 This is like |screenchars()| but returning a String with the
7785 characters.
7786 This is mainly to be used for testing.
7787 Returns an empty String when row or col is out of range.
7788
7789 Can also be used as a |method|: >
7790 GetRow()->screenstring(col)
7791<
7792 *search()*
7793search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7794 Search for regexp pattern {pattern}. The search starts at the
7795 cursor position (you can use |cursor()| to set it).
7796
7797 When a match has been found its line number is returned.
7798 If there is no match a 0 is returned and the cursor doesn't
7799 move. No error message is given.
7800
7801 {flags} is a String, which can contain these character flags:
7802 'b' search Backward instead of forward
7803 'c' accept a match at the Cursor position
7804 'e' move to the End of the match
7805 'n' do Not move the cursor
7806 'p' return number of matching sub-Pattern (see below)
7807 's' Set the ' mark at the previous location of the cursor
7808 'w' Wrap around the end of the file
7809 'W' don't Wrap around the end of the file
7810 'z' start searching at the cursor column instead of zero
7811 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
7812
7813 If the 's' flag is supplied, the ' mark is set, only if the
7814 cursor is moved. The 's' flag cannot be combined with the 'n'
7815 flag.
7816
7817 'ignorecase', 'smartcase' and 'magic' are used.
7818
7819 When the 'z' flag is not given, forward searching always
7820 starts in column zero and then matches before the cursor are
7821 skipped. When the 'c' flag is present in 'cpo' the next
7822 search starts after the match. Without the 'c' flag the next
Bram Moolenaarfd999452022-08-24 18:30:14 +01007823 search starts one column after the start of the match. This
7824 matters for overlapping matches. See |cpo-c|. You can also
7825 insert "\ze" to change where the match ends, see |/\ze|.
7826
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007827 When searching backwards and the 'z' flag is given then the
7828 search starts in column zero, thus no match in the current
7829 line will be found (unless wrapping around the end of the
7830 file).
7831
7832 When the {stopline} argument is given then the search stops
7833 after searching this line. This is useful to restrict the
7834 search to a range of lines. Examples: >
7835 let match = search('(', 'b', line("w0"))
7836 let end = search('END', '', line("w$"))
7837< When {stopline} is used and it is not zero this also implies
7838 that the search does not wrap around the end of the file.
7839 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01007840 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007841 When the {timeout} argument is given the search stops when
7842 more than this many milliseconds have passed. Thus when
7843 {timeout} is 500 the search stops after half a second.
7844 The value must not be negative. A zero value is like not
7845 giving the argument.
7846 {only available when compiled with the |+reltime| feature}
7847
7848 If the {skip} expression is given it is evaluated with the
7849 cursor positioned on the start of a match. If it evaluates to
7850 non-zero this match is skipped. This can be used, for
7851 example, to skip a match in a comment or a string.
7852 {skip} can be a string, which is evaluated as an expression, a
7853 function reference or a lambda.
7854 When {skip} is omitted or empty, every match is accepted.
7855 When evaluating {skip} causes an error the search is aborted
7856 and -1 returned.
7857 *search()-sub-match*
7858 With the 'p' flag the returned value is one more than the
7859 first sub-match in \(\). One if none of them matched but the
7860 whole pattern did match.
7861 To get the column number too use |searchpos()|.
7862
7863 The cursor will be positioned at the match, unless the 'n'
7864 flag is used.
7865
7866 Example (goes over all files in the argument list): >
7867 :let n = 1
7868 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007869 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007870 : " start at the last char in the file and wrap for the
7871 : " first search to find match at start of file
7872 : normal G$
7873 : let flags = "w"
7874 : while search("foo", flags) > 0
7875 : s/foo/bar/g
7876 : let flags = "W"
7877 : endwhile
7878 : update " write the file if modified
7879 : let n = n + 1
7880 :endwhile
7881<
7882 Example for using some flags: >
7883 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7884< This will search for the keywords "if", "else", and "endif"
7885 under or after the cursor. Because of the 'p' flag, it
7886 returns 1, 2, or 3 depending on which keyword is found, or 0
7887 if the search fails. With the cursor on the first word of the
7888 line:
7889 if (foo == 0) | let foo = foo + 1 | endif ~
7890 the function returns 1. Without the 'c' flag, the function
7891 finds the "endif" and returns 3. The same thing happens
7892 without the 'e' flag if the cursor is on the "f" of "if".
7893 The 'n' flag tells the function not to move the cursor.
7894
7895 Can also be used as a |method|: >
7896 GetPattern()->search()
7897
7898searchcount([{options}]) *searchcount()*
7899 Get or update the last search count, like what is displayed
7900 without the "S" flag in 'shortmess'. This works even if
7901 'shortmess' does contain the "S" flag.
7902
7903 This returns a |Dictionary|. The dictionary is empty if the
7904 previous pattern was not set and "pattern" was not specified.
7905
7906 key type meaning ~
7907 current |Number| current position of match;
7908 0 if the cursor position is
7909 before the first match
7910 exact_match |Boolean| 1 if "current" is matched on
7911 "pos", otherwise 0
7912 total |Number| total count of matches found
7913 incomplete |Number| 0: search was fully completed
7914 1: recomputing was timed out
7915 2: max count exceeded
7916
7917 For {options} see further down.
7918
7919 To get the last search count when |n| or |N| was pressed, call
7920 this function with `recompute: 0` . This sometimes returns
7921 wrong information because |n| and |N|'s maximum count is 99.
7922 If it exceeded 99 the result must be max count + 1 (100). If
7923 you want to get correct information, specify `recompute: 1`: >
7924
7925 " result == maxcount + 1 (100) when many matches
7926 let result = searchcount(#{recompute: 0})
7927
7928 " Below returns correct result (recompute defaults
7929 " to 1)
7930 let result = searchcount()
7931<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01007932 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007933 function! LastSearchCount() abort
7934 let result = searchcount(#{recompute: 0})
7935 if empty(result)
7936 return ''
7937 endif
7938 if result.incomplete ==# 1 " timed out
7939 return printf(' /%s [?/??]', @/)
7940 elseif result.incomplete ==# 2 " max count exceeded
7941 if result.total > result.maxcount &&
7942 \ result.current > result.maxcount
7943 return printf(' /%s [>%d/>%d]', @/,
7944 \ result.current, result.total)
7945 elseif result.total > result.maxcount
7946 return printf(' /%s [%d/>%d]', @/,
7947 \ result.current, result.total)
7948 endif
7949 endif
7950 return printf(' /%s [%d/%d]', @/,
7951 \ result.current, result.total)
7952 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007953 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007954
7955 " Or if you want to show the count only when
7956 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007957 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007958 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
7959<
7960 You can also update the search count, which can be useful in a
7961 |CursorMoved| or |CursorMovedI| autocommand: >
7962
7963 autocmd CursorMoved,CursorMovedI *
7964 \ let s:searchcount_timer = timer_start(
7965 \ 200, function('s:update_searchcount'))
7966 function! s:update_searchcount(timer) abort
7967 if a:timer ==# s:searchcount_timer
7968 call searchcount(#{
7969 \ recompute: 1, maxcount: 0, timeout: 100})
7970 redrawstatus
7971 endif
7972 endfunction
7973<
7974 This can also be used to count matched texts with specified
7975 pattern in the current buffer using "pattern": >
7976
7977 " Count '\<foo\>' in this buffer
7978 " (Note that it also updates search count)
7979 let result = searchcount(#{pattern: '\<foo\>'})
7980
7981 " To restore old search count by old pattern,
7982 " search again
7983 call searchcount()
7984<
7985 {options} must be a |Dictionary|. It can contain:
7986 key type meaning ~
7987 recompute |Boolean| if |TRUE|, recompute the count
7988 like |n| or |N| was executed.
7989 otherwise returns the last
7990 computed result (when |n| or
7991 |N| was used when "S" is not
7992 in 'shortmess', or this
7993 function was called).
7994 (default: |TRUE|)
7995 pattern |String| recompute if this was given
7996 and different with |@/|.
7997 this works as same as the
7998 below command is executed
7999 before calling this function >
8000 let @/ = pattern
8001< (default: |@/|)
8002 timeout |Number| 0 or negative number is no
8003 timeout. timeout milliseconds
8004 for recomputing the result
8005 (default: 0)
8006 maxcount |Number| 0 or negative number is no
8007 limit. max count of matched
8008 text while recomputing the
8009 result. if search exceeded
8010 total count, "total" value
8011 becomes `maxcount + 1`
8012 (default: 99)
8013 pos |List| `[lnum, col, off]` value
8014 when recomputing the result.
8015 this changes "current" result
8016 value. see |cursor()|,
8017 |getpos()|
8018 (default: cursor's position)
8019
8020 Can also be used as a |method|: >
8021 GetSearchOpts()->searchcount()
8022<
8023searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
8024 Search for the declaration of {name}.
8025
8026 With a non-zero {global} argument it works like |gD|, find
8027 first match in the file. Otherwise it works like |gd|, find
8028 first match in the function.
8029
8030 With a non-zero {thisblock} argument matches in a {} block
8031 that ends before the cursor position are ignored. Avoids
8032 finding variable declarations only valid in another scope.
8033
8034 Moves the cursor to the found match.
8035 Returns zero for success, non-zero for failure.
8036 Example: >
8037 if searchdecl('myvar') == 0
8038 echo getline('.')
8039 endif
8040<
8041 Can also be used as a |method|: >
8042 GetName()->searchdecl()
8043<
8044 *searchpair()*
8045searchpair({start}, {middle}, {end} [, {flags} [, {skip}
8046 [, {stopline} [, {timeout}]]]])
8047 Search for the match of a nested start-end pair. This can be
8048 used to find the "endif" that matches an "if", while other
8049 if/endif pairs in between are ignored.
8050 The search starts at the cursor. The default is to search
8051 forward, include 'b' in {flags} to search backward.
8052 If a match is found, the cursor is positioned at it and the
8053 line number is returned. If no match is found 0 or -1 is
8054 returned and the cursor doesn't move. No error message is
8055 given.
8056
8057 {start}, {middle} and {end} are patterns, see |pattern|. They
8058 must not contain \( \) pairs. Use of \%( \) is allowed. When
8059 {middle} is not empty, it is found when searching from either
8060 direction, but only when not in a nested start-end pair. A
8061 typical use is: >
8062 searchpair('\<if\>', '\<else\>', '\<endif\>')
8063< By leaving {middle} empty the "else" is skipped.
8064
8065 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
8066 |search()|. Additionally:
8067 'r' Repeat until no more matches found; will find the
8068 outer pair. Implies the 'W' flag.
8069 'm' Return number of matches instead of line number with
8070 the match; will be > 1 when 'r' is used.
8071 Note: it's nearly always a good idea to use the 'W' flag, to
8072 avoid wrapping around the end of the file.
8073
8074 When a match for {start}, {middle} or {end} is found, the
8075 {skip} expression is evaluated with the cursor positioned on
8076 the start of the match. It should return non-zero if this
8077 match is to be skipped. E.g., because it is inside a comment
8078 or a string.
8079 When {skip} is omitted or empty, every match is accepted.
8080 When evaluating {skip} causes an error the search is aborted
8081 and -1 returned.
8082 {skip} can be a string, a lambda, a funcref or a partial.
8083 Anything else makes the function fail.
8084 In a `:def` function when the {skip} argument is a string
8085 constant it is compiled into instructions.
8086
8087 For {stopline} and {timeout} see |search()|.
8088
8089 The value of 'ignorecase' is used. 'magic' is ignored, the
8090 patterns are used like it's on.
8091
8092 The search starts exactly at the cursor. A match with
8093 {start}, {middle} or {end} at the next character, in the
8094 direction of searching, is the first one found. Example: >
8095 if 1
8096 if 2
8097 endif 2
8098 endif 1
8099< When starting at the "if 2", with the cursor on the "i", and
8100 searching forwards, the "endif 2" is found. When starting on
8101 the character just before the "if 2", the "endif 1" will be
8102 found. That's because the "if 2" will be found first, and
8103 then this is considered to be a nested if/endif from "if 2" to
8104 "endif 2".
8105 When searching backwards and {end} is more than one character,
8106 it may be useful to put "\zs" at the end of the pattern, so
8107 that when the cursor is inside a match with the end it finds
8108 the matching start.
8109
8110 Example, to find the "endif" command in a Vim script: >
8111
8112 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
8113 \ 'getline(".") =~ "^\\s*\""')
8114
8115< The cursor must be at or after the "if" for which a match is
8116 to be found. Note that single-quote strings are used to avoid
8117 having to double the backslashes. The skip expression only
8118 catches comments at the start of a line, not after a command.
8119 Also, a word "en" or "if" halfway a line is considered a
8120 match.
8121 Another example, to search for the matching "{" of a "}": >
8122
8123 :echo searchpair('{', '', '}', 'bW')
8124
8125< This works when the cursor is at or before the "}" for which a
8126 match is to be found. To reject matches that syntax
8127 highlighting recognized as strings: >
8128
8129 :echo searchpair('{', '', '}', 'bW',
8130 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
8131<
8132 *searchpairpos()*
8133searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
8134 [, {stopline} [, {timeout}]]]])
8135 Same as |searchpair()|, but returns a |List| with the line and
8136 column position of the match. The first element of the |List|
8137 is the line number and the second element is the byte index of
8138 the column position of the match. If no match is found,
8139 returns [0, 0]. >
8140
8141 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
8142<
8143 See |match-parens| for a bigger and more useful example.
8144
8145 *searchpos()*
8146searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
8147 Same as |search()|, but returns a |List| with the line and
8148 column position of the match. The first element of the |List|
8149 is the line number and the second element is the byte index of
8150 the column position of the match. If no match is found,
8151 returns [0, 0].
8152 Example: >
8153 :let [lnum, col] = searchpos('mypattern', 'n')
8154
8155< When the 'p' flag is given then there is an extra item with
8156 the sub-pattern match number |search()-sub-match|. Example: >
8157 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
8158< In this example "submatch" is 2 when a lowercase letter is
8159 found |/\l|, 3 when an uppercase letter is found |/\u|.
8160
8161 Can also be used as a |method|: >
8162 GetPattern()->searchpos()
8163
8164server2client({clientid}, {string}) *server2client()*
8165 Send a reply string to {clientid}. The most recent {clientid}
8166 that sent a string can be retrieved with expand("<client>").
8167 {only available when compiled with the |+clientserver| feature}
8168 Returns zero for success, -1 for failure.
8169 Note:
8170 This id has to be stored before the next command can be
8171 received. I.e. before returning from the received command and
8172 before calling any commands that waits for input.
8173 See also |clientserver|.
8174 Example: >
8175 :echo server2client(expand("<client>"), "HELLO")
8176
8177< Can also be used as a |method|: >
8178 GetClientId()->server2client(string)
8179<
8180serverlist() *serverlist()*
8181 Return a list of available server names, one per line.
8182 When there are no servers or the information is not available
8183 an empty string is returned. See also |clientserver|.
8184 {only available when compiled with the |+clientserver| feature}
8185 Example: >
8186 :echo serverlist()
8187<
8188setbufline({buf}, {lnum}, {text}) *setbufline()*
8189 Set line {lnum} to {text} in buffer {buf}. This works like
8190 |setline()| for the specified buffer.
8191
8192 This function works only for loaded buffers. First call
8193 |bufload()| if needed.
8194
8195 To insert lines use |appendbufline()|.
8196 Any text properties in {lnum} are cleared.
8197
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00008198 {text} can be a string to set one line, or a List of strings
8199 to set multiple lines. If the List extends below the last
8200 line then those lines are added. If the List is empty then
8201 nothing is changed and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008202
8203 For the use of {buf}, see |bufname()| above.
8204
8205 {lnum} is used like with |setline()|.
8206 Use "$" to refer to the last line in buffer {buf}.
8207 When {lnum} is just below the last line the {text} will be
8208 added below the last line.
8209
8210 When {buf} is not a valid buffer, the buffer is not loaded or
8211 {lnum} is not valid then 1 is returned. In |Vim9| script an
8212 error is given.
8213 On success 0 is returned.
8214
8215 Can also be used as a |method|, the base is passed as the
8216 third argument: >
8217 GetText()->setbufline(buf, lnum)
8218
8219setbufvar({buf}, {varname}, {val}) *setbufvar()*
8220 Set option or local variable {varname} in buffer {buf} to
8221 {val}.
8222 This also works for a global or local window option, but it
8223 doesn't work for a global or local window variable.
8224 For a local window option the global value is unchanged.
8225 For the use of {buf}, see |bufname()| above.
8226 The {varname} argument is a string.
8227 Note that the variable name without "b:" must be used.
8228 Examples: >
8229 :call setbufvar(1, "&mod", 1)
8230 :call setbufvar("todo", "myvar", "foobar")
8231< This function is not available in the |sandbox|.
8232
8233 Can also be used as a |method|, the base is passed as the
8234 third argument: >
8235 GetValue()->setbufvar(buf, varname)
8236
8237
8238setcellwidths({list}) *setcellwidths()*
8239 Specify overrides for cell widths of character ranges. This
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008240 tells Vim how wide characters are when displayed in the
8241 terminal, counted in screen cells. The values override
8242 'ambiwidth'. Example: >
8243 call setcellwidths([
Bram Moolenaar938ae282023-02-20 20:44:55 +00008244 \ [0x111, 0x111, 1],
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008245 \ [0x2194, 0x2199, 2],
8246 \ ])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008247
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008248< The {list} argument is a List of Lists with each three
8249 numbers: [{low}, {high}, {width}]. *E1109* *E1110*
8250 {low} and {high} can be the same, in which case this refers to
8251 one character. Otherwise it is the range of characters from
8252 {low} to {high} (inclusive). *E1111* *E1114*
K.Takata71933232023-01-20 16:00:55 +00008253 Only characters with value 0x80 and higher can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008254
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008255 {width} must be either 1 or 2, indicating the character width
8256 in screen cells. *E1112*
8257 An error is given if the argument is invalid, also when a
Bram Moolenaar938ae282023-02-20 20:44:55 +00008258 range overlaps with another. *E1113*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008259
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008260 If the new value causes 'fillchars' or 'listchars' to become
8261 invalid it is rejected and an error is given.
8262
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008263 To clear the overrides pass an empty {list}: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008264 setcellwidths([]);
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008265
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008266< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
Bram Moolenaarb59ae592022-11-23 23:46:31 +00008267 the effect for known emoji characters. Move the cursor
8268 through the text to check if the cell widths of your terminal
8269 match with what Vim knows about each emoji. If it doesn't
8270 look right you need to adjust the {list} argument.
8271
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008272
8273setcharpos({expr}, {list}) *setcharpos()*
8274 Same as |setpos()| but uses the specified column number as the
8275 character index instead of the byte index in the line.
8276
8277 Example:
8278 With the text "여보세요" in line 8: >
8279 call setcharpos('.', [0, 8, 4, 0])
8280< positions the cursor on the fourth character '요'. >
8281 call setpos('.', [0, 8, 4, 0])
8282< positions the cursor on the second character '보'.
8283
8284 Can also be used as a |method|: >
8285 GetPosition()->setcharpos('.')
8286
8287setcharsearch({dict}) *setcharsearch()*
8288 Set the current character search information to {dict},
8289 which contains one or more of the following entries:
8290
8291 char character which will be used for a subsequent
8292 |,| or |;| command; an empty string clears the
8293 character search
8294 forward direction of character search; 1 for forward,
8295 0 for backward
8296 until type of character search; 1 for a |t| or |T|
8297 character search, 0 for an |f| or |F|
8298 character search
8299
8300 This can be useful to save/restore a user's character search
8301 from a script: >
8302 :let prevsearch = getcharsearch()
8303 :" Perform a command which clobbers user's search
8304 :call setcharsearch(prevsearch)
8305< Also see |getcharsearch()|.
8306
8307 Can also be used as a |method|: >
8308 SavedSearch()->setcharsearch()
8309
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01008310setcmdline({str} [, {pos}]) *setcmdline()*
8311 Set the command line to {str} and set the cursor position to
8312 {pos}.
8313 If {pos} is omitted, the cursor is positioned after the text.
8314 Returns 0 when successful, 1 when not editing the command
8315 line.
8316
8317 Can also be used as a |method|: >
8318 GetText()->setcmdline()
8319
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008320setcmdpos({pos}) *setcmdpos()*
8321 Set the cursor position in the command line to byte position
8322 {pos}. The first position is 1.
8323 Use |getcmdpos()| to obtain the current position.
8324 Only works while editing the command line, thus you must use
8325 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
8326 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
8327 set after the command line is set to the expression. For
8328 |c_CTRL-R_=| it is set after evaluating the expression but
8329 before inserting the resulting text.
8330 When the number is too big the cursor is put at the end of the
8331 line. A number smaller than one has undefined results.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01008332 Returns 0 when successful, 1 when not editing the command
8333 line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008334
8335 Can also be used as a |method|: >
8336 GetPos()->setcmdpos()
8337
8338setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
8339setcursorcharpos({list})
8340 Same as |cursor()| but uses the specified column number as the
8341 character index instead of the byte index in the line.
8342
8343 Example:
8344 With the text "여보세요" in line 4: >
8345 call setcursorcharpos(4, 3)
8346< positions the cursor on the third character '세'. >
8347 call cursor(4, 3)
8348< positions the cursor on the first character '여'.
8349
8350 Can also be used as a |method|: >
8351 GetCursorPos()->setcursorcharpos()
8352
8353
8354setenv({name}, {val}) *setenv()*
8355 Set environment variable {name} to {val}. Example: >
8356 call setenv('HOME', '/home/myhome')
8357
8358< When {val} is |v:null| the environment variable is deleted.
8359 See also |expr-env|.
8360
8361 Can also be used as a |method|, the base is passed as the
8362 second argument: >
8363 GetPath()->setenv('PATH')
8364
8365setfperm({fname}, {mode}) *setfperm()* *chmod*
8366 Set the file permissions for {fname} to {mode}.
8367 {mode} must be a string with 9 characters. It is of the form
8368 "rwxrwxrwx", where each group of "rwx" flags represent, in
8369 turn, the permissions of the owner of the file, the group the
8370 file belongs to, and other users. A '-' character means the
8371 permission is off, any other character means on. Multi-byte
8372 characters are not supported.
8373
8374 For example "rw-r-----" means read-write for the user,
8375 readable by the group, not accessible by others. "xx-x-----"
8376 would do the same thing.
8377
8378 Returns non-zero for success, zero for failure.
8379
8380 Can also be used as a |method|: >
8381 GetFilename()->setfperm(mode)
8382<
8383 To read permissions see |getfperm()|.
8384
8385
8386setline({lnum}, {text}) *setline()*
8387 Set line {lnum} of the current buffer to {text}. To insert
8388 lines use |append()|. To set lines in another buffer use
8389 |setbufline()|. Any text properties in {lnum} are cleared.
8390
8391 {lnum} is used like with |getline()|.
8392 When {lnum} is just below the last line the {text} will be
8393 added below the last line.
8394 {text} can be any type or a List of any type, each item is
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00008395 converted to a String. When {text} is an empty List then
8396 nothing is changed and FALSE is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008397
8398 If this succeeds, FALSE is returned. If this fails (most likely
8399 because {lnum} is invalid) TRUE is returned.
8400 In |Vim9| script an error is given if {lnum} is invalid.
8401
8402 Example: >
8403 :call setline(5, strftime("%c"))
8404
8405< When {text} is a |List| then line {lnum} and following lines
8406 will be set to the items in the list. Example: >
8407 :call setline(5, ['aaa', 'bbb', 'ccc'])
8408< This is equivalent to: >
8409 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
8410 : call setline(n, l)
8411 :endfor
8412
8413< Note: The '[ and '] marks are not set.
8414
8415 Can also be used as a |method|, the base is passed as the
8416 second argument: >
8417 GetText()->setline(lnum)
8418
8419setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
8420 Create or replace or add to the location list for window {nr}.
8421 {nr} can be the window number or the |window-ID|.
8422 When {nr} is zero the current window is used.
8423
8424 For a location list window, the displayed location list is
8425 modified. For an invalid window number {nr}, -1 is returned.
8426 Otherwise, same as |setqflist()|.
8427 Also see |location-list|.
8428
8429 For {action} see |setqflist-action|.
8430
8431 If the optional {what} dictionary argument is supplied, then
8432 only the items listed in {what} are set. Refer to |setqflist()|
8433 for the list of supported keys in {what}.
8434
8435 Can also be used as a |method|, the base is passed as the
8436 second argument: >
8437 GetLoclist()->setloclist(winnr)
8438
8439setmatches({list} [, {win}]) *setmatches()*
8440 Restores a list of matches saved by |getmatches()| for the
8441 current window. Returns 0 if successful, otherwise -1. All
8442 current matches are cleared before the list is restored. See
8443 example for |getmatches()|.
8444 If {win} is specified, use the window with this number or
8445 window ID instead of the current window.
8446
8447 Can also be used as a |method|: >
8448 GetMatches()->setmatches()
8449<
8450 *setpos()*
8451setpos({expr}, {list})
8452 Set the position for String {expr}. Possible values:
8453 . the cursor
8454 'x mark x
8455
8456 {list} must be a |List| with four or five numbers:
8457 [bufnum, lnum, col, off]
8458 [bufnum, lnum, col, off, curswant]
8459
8460 "bufnum" is the buffer number. Zero can be used for the
8461 current buffer. When setting an uppercase mark "bufnum" is
8462 used for the mark position. For other marks it specifies the
8463 buffer to set the mark in. You can use the |bufnr()| function
8464 to turn a file name into a buffer number.
8465 For setting the cursor and the ' mark "bufnum" is ignored,
8466 since these are associated with a window, not a buffer.
8467 Does not change the jumplist.
8468
8469 "lnum" and "col" are the position in the buffer. The first
8470 column is 1. Use a zero "lnum" to delete a mark. If "col" is
8471 smaller than 1 then 1 is used. To use the character count
8472 instead of the byte count, use |setcharpos()|.
8473
8474 The "off" number is only used when 'virtualedit' is set. Then
8475 it is the offset in screen columns from the start of the
8476 character. E.g., a position within a <Tab> or after the last
8477 character.
8478
8479 The "curswant" number is only used when setting the cursor
8480 position. It sets the preferred column for when moving the
8481 cursor vertically. When the "curswant" number is missing the
8482 preferred column is not set. When it is present and setting a
8483 mark position it is not used.
8484
8485 Note that for '< and '> changing the line number may result in
8486 the marks to be effectively be swapped, so that '< is always
8487 before '>.
8488
8489 Returns 0 when the position could be set, -1 otherwise.
8490 An error message is given if {expr} is invalid.
8491
8492 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
8493
8494 This does not restore the preferred column for moving
8495 vertically; if you set the cursor position with this, |j| and
8496 |k| motions will jump to previous columns! Use |cursor()| to
8497 also set the preferred column. Also see the "curswant" key in
8498 |winrestview()|.
8499
8500 Can also be used as a |method|: >
8501 GetPosition()->setpos('.')
8502
8503setqflist({list} [, {action} [, {what}]]) *setqflist()*
8504 Create or replace or add to the quickfix list.
8505
8506 If the optional {what} dictionary argument is supplied, then
8507 only the items listed in {what} are set. The first {list}
8508 argument is ignored. See below for the supported items in
8509 {what}.
8510 *setqflist-what*
8511 When {what} is not present, the items in {list} are used. Each
8512 item must be a dictionary. Non-dictionary items in {list} are
8513 ignored. Each dictionary item can contain the following
8514 entries:
8515
8516 bufnr buffer number; must be the number of a valid
8517 buffer
8518 filename name of a file; only used when "bufnr" is not
8519 present or it is invalid.
8520 module name of a module; if given it will be used in
8521 quickfix error window instead of the filename.
8522 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +00008523 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008524 pattern search pattern used to locate the error
8525 col column number
8526 vcol when non-zero: "col" is visual column
8527 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +00008528 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008529 nr error number
8530 text description of the error
8531 type single-character error type, 'E', 'W', etc.
8532 valid recognized error message
Tom Praschanca6ac992023-08-11 23:26:12 +02008533 user_data custom data associated with the item, can be
8534 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008535
8536 The "col", "vcol", "nr", "type" and "text" entries are
8537 optional. Either "lnum" or "pattern" entry can be used to
8538 locate a matching error line.
8539 If the "filename" and "bufnr" entries are not present or
8540 neither the "lnum" or "pattern" entries are present, then the
8541 item will not be handled as an error line.
8542 If both "pattern" and "lnum" are present then "pattern" will
8543 be used.
8544 If the "valid" entry is not supplied, then the valid flag is
8545 set when "bufnr" is a valid buffer or "filename" exists.
8546 If you supply an empty {list}, the quickfix list will be
8547 cleared.
8548 Note that the list is not exactly the same as what
8549 |getqflist()| returns.
8550
8551 {action} values: *setqflist-action* *E927*
8552 'a' The items from {list} are added to the existing
8553 quickfix list. If there is no existing list, then a
8554 new list is created.
8555
8556 'r' The items from the current quickfix list are replaced
8557 with the items from {list}. This can also be used to
8558 clear the list: >
8559 :call setqflist([], 'r')
8560<
8561 'f' All the quickfix lists in the quickfix stack are
8562 freed.
8563
8564 If {action} is not present or is set to ' ', then a new list
8565 is created. The new quickfix list is added after the current
8566 quickfix list in the stack and all the following lists are
8567 freed. To add a new quickfix list at the end of the stack,
8568 set "nr" in {what} to "$".
8569
8570 The following items can be specified in dictionary {what}:
8571 context quickfix list context. See |quickfix-context|
8572 efm errorformat to use when parsing text from
8573 "lines". If this is not present, then the
8574 'errorformat' option value is used.
8575 See |quickfix-parse|
8576 id quickfix list identifier |quickfix-ID|
8577 idx index of the current entry in the quickfix
8578 list specified by 'id' or 'nr'. If set to '$',
8579 then the last entry in the list is set as the
8580 current entry. See |quickfix-index|
8581 items list of quickfix entries. Same as the {list}
8582 argument.
8583 lines use 'errorformat' to parse a list of lines and
8584 add the resulting entries to the quickfix list
8585 {nr} or {id}. Only a |List| value is supported.
8586 See |quickfix-parse|
8587 nr list number in the quickfix stack; zero
8588 means the current quickfix list and "$" means
8589 the last quickfix list.
8590 quickfixtextfunc
8591 function to get the text to display in the
8592 quickfix window. The value can be the name of
8593 a function or a funcref or a lambda. Refer to
8594 |quickfix-window-function| for an explanation
8595 of how to write the function and an example.
8596 title quickfix list title text. See |quickfix-title|
8597 Unsupported keys in {what} are ignored.
8598 If the "nr" item is not present, then the current quickfix list
8599 is modified. When creating a new quickfix list, "nr" can be
8600 set to a value one greater than the quickfix stack size.
8601 When modifying a quickfix list, to guarantee that the correct
8602 list is modified, "id" should be used instead of "nr" to
8603 specify the list.
8604
8605 Examples (See also |setqflist-examples|): >
8606 :call setqflist([], 'r', {'title': 'My search'})
8607 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
8608 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
8609<
8610 Returns zero for success, -1 for failure.
8611
8612 This function can be used to create a quickfix list
8613 independent of the 'errorformat' setting. Use a command like
8614 `:cc 1` to jump to the first position.
8615
8616 Can also be used as a |method|, the base is passed as the
8617 second argument: >
8618 GetErrorlist()->setqflist()
8619<
8620 *setreg()*
8621setreg({regname}, {value} [, {options}])
8622 Set the register {regname} to {value}.
8623 If {regname} is "" or "@", the unnamed register '"' is used.
8624 The {regname} argument is a string. In |Vim9-script|
8625 {regname} must be one character.
8626
8627 {value} may be any value returned by |getreg()| or
8628 |getreginfo()|, including a |List| or |Dict|.
8629 If {options} contains "a" or {regname} is upper case,
8630 then the value is appended.
8631
8632 {options} can also contain a register type specification:
8633 "c" or "v" |characterwise| mode
8634 "l" or "V" |linewise| mode
8635 "b" or "<CTRL-V>" |blockwise-visual| mode
8636 If a number immediately follows "b" or "<CTRL-V>" then this is
8637 used as the width of the selection - if it is not specified
8638 then the width of the block is set to the number of characters
8639 in the longest line (counting a <Tab> as 1 character).
8640
8641 If {options} contains no register settings, then the default
8642 is to use character mode unless {value} ends in a <NL> for
8643 string {value} and linewise mode for list {value}. Blockwise
8644 mode is never selected automatically.
8645 Returns zero for success, non-zero for failure.
8646
8647 *E883*
8648 Note: you may not use |List| containing more than one item to
8649 set search and expression registers. Lists containing no
8650 items act like empty strings.
8651
8652 Examples: >
8653 :call setreg(v:register, @*)
8654 :call setreg('*', @%, 'ac')
8655 :call setreg('a', "1\n2\n3", 'b5')
8656 :call setreg('"', { 'points_to': 'a'})
8657
8658< This example shows using the functions to save and restore a
8659 register: >
8660 :let var_a = getreginfo()
8661 :call setreg('a', var_a)
8662< or: >
8663 :let var_a = getreg('a', 1, 1)
8664 :let var_amode = getregtype('a')
8665 ....
8666 :call setreg('a', var_a, var_amode)
8667< Note: you may not reliably restore register value
8668 without using the third argument to |getreg()| as without it
8669 newlines are represented as newlines AND Nul bytes are
8670 represented as newlines as well, see |NL-used-for-Nul|.
8671
8672 You can also change the type of a register by appending
8673 nothing: >
8674 :call setreg('a', '', 'al')
8675
8676< Can also be used as a |method|, the base is passed as the
8677 second argument: >
8678 GetText()->setreg('a')
8679
8680settabvar({tabnr}, {varname}, {val}) *settabvar()*
8681 Set tab-local variable {varname} to {val} in tab page {tabnr}.
8682 |t:var|
8683 The {varname} argument is a string.
8684 Note that autocommands are blocked, side effects may not be
8685 triggered, e.g. when setting 'filetype'.
8686 Note that the variable name without "t:" must be used.
8687 Tabs are numbered starting with one.
8688 This function is not available in the |sandbox|.
8689
8690 Can also be used as a |method|, the base is passed as the
8691 third argument: >
8692 GetValue()->settabvar(tab, name)
8693
8694settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
8695 Set option or local variable {varname} in window {winnr} to
8696 {val}.
8697 Tabs are numbered starting with one. For the current tabpage
8698 use |setwinvar()|.
8699 {winnr} can be the window number or the |window-ID|.
8700 When {winnr} is zero the current window is used.
8701 Note that autocommands are blocked, side effects may not be
8702 triggered, e.g. when setting 'filetype' or 'syntax'.
8703 This also works for a global or local buffer option, but it
8704 doesn't work for a global or local buffer variable.
8705 For a local buffer option the global value is unchanged.
8706 Note that the variable name without "w:" must be used.
8707 Examples: >
8708 :call settabwinvar(1, 1, "&list", 0)
8709 :call settabwinvar(3, 2, "myvar", "foobar")
8710< This function is not available in the |sandbox|.
8711
8712 Can also be used as a |method|, the base is passed as the
8713 fourth argument: >
8714 GetValue()->settabwinvar(tab, winnr, name)
8715
8716settagstack({nr}, {dict} [, {action}]) *settagstack()*
8717 Modify the tag stack of the window {nr} using {dict}.
8718 {nr} can be the window number or the |window-ID|.
8719
8720 For a list of supported items in {dict}, refer to
8721 |gettagstack()|. "curidx" takes effect before changing the tag
8722 stack.
8723 *E962*
8724 How the tag stack is modified depends on the {action}
8725 argument:
8726 - If {action} is not present or is set to 'r', then the tag
8727 stack is replaced.
8728 - If {action} is set to 'a', then new entries from {dict} are
8729 pushed (added) onto the tag stack.
8730 - If {action} is set to 't', then all the entries from the
8731 current entry in the tag stack or "curidx" in {dict} are
8732 removed and then new entries are pushed to the stack.
8733
8734 The current index is set to one after the length of the tag
8735 stack after the modification.
8736
8737 Returns zero for success, -1 for failure.
8738
8739 Examples (for more examples see |tagstack-examples|):
8740 Empty the tag stack of window 3: >
8741 call settagstack(3, {'items' : []})
8742
8743< Save and restore the tag stack: >
8744 let stack = gettagstack(1003)
8745 " do something else
8746 call settagstack(1003, stack)
8747 unlet stack
8748<
8749 Can also be used as a |method|, the base is passed as the
8750 second argument: >
8751 GetStack()->settagstack(winnr)
8752
8753setwinvar({winnr}, {varname}, {val}) *setwinvar()*
8754 Like |settabwinvar()| for the current tab page.
8755 Examples: >
8756 :call setwinvar(1, "&list", 0)
8757 :call setwinvar(2, "myvar", "foobar")
8758
8759< Can also be used as a |method|, the base is passed as the
8760 third argument: >
8761 GetValue()->setwinvar(winnr, name)
8762
8763sha256({string}) *sha256()*
8764 Returns a String with 64 hex characters, which is the SHA256
8765 checksum of {string}.
8766
8767 Can also be used as a |method|: >
8768 GetText()->sha256()
8769
8770< {only available when compiled with the |+cryptv| feature}
8771
8772shellescape({string} [, {special}]) *shellescape()*
8773 Escape {string} for use as a shell command argument.
8774 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +00008775 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008776 in single quotes and will double up all internal single
8777 quotes.
8778 On MS-Windows, when 'shellslash' is not set, it will enclose
8779 {string} in double quotes and double all double quotes within
8780 {string}.
8781 Otherwise it will enclose {string} in single quotes and
8782 replace all "'" with "'\''".
8783
8784 When the {special} argument is present and it's a non-zero
8785 Number or a non-empty String (|non-zero-arg|), then special
8786 items such as "!", "%", "#" and "<cword>" will be preceded by
8787 a backslash. This backslash will be removed again by the |:!|
8788 command.
8789
8790 The "!" character will be escaped (again with a |non-zero-arg|
8791 {special}) when 'shell' contains "csh" in the tail. That is
8792 because for csh and tcsh "!" is used for history replacement
8793 even when inside single quotes.
8794
8795 With a |non-zero-arg| {special} the <NL> character is also
8796 escaped. When 'shell' containing "csh" in the tail it's
8797 escaped a second time.
8798
8799 The "\" character will be escaped when 'shell' contains "fish"
8800 in the tail. That is because for fish "\" is used as an escape
8801 character inside single quotes.
8802
8803 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008804 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008805< This results in a directory listing for the file under the
8806 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008807 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008808< See also |::S|.
8809
8810 Can also be used as a |method|: >
8811 GetCommand()->shellescape()
8812
8813shiftwidth([{col}]) *shiftwidth()*
8814 Returns the effective value of 'shiftwidth'. This is the
8815 'shiftwidth' value unless it is zero, in which case it is the
8816 'tabstop' value. This function was introduced with patch
8817 7.3.694 in 2012, everybody should have it by now (however it
8818 did not allow for the optional {col} argument until 8.1.542).
8819
8820 When there is one argument {col} this is used as column number
8821 for which to return the 'shiftwidth' value. This matters for the
8822 'vartabstop' feature. If the 'vartabstop' setting is enabled and
8823 no {col} argument is given, column 1 will be assumed.
8824
8825 Can also be used as a |method|: >
8826 GetColumn()->shiftwidth()
8827
8828sign_ functions are documented here: |sign-functions-details|
8829
8830
8831simplify({filename}) *simplify()*
8832 Simplify the file name as much as possible without changing
8833 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
8834 Unix) are not resolved. If the first path component in
8835 {filename} designates the current directory, this will be
8836 valid for the result as well. A trailing path separator is
8837 not removed either. On Unix "//path" is unchanged, but
8838 "///path" is simplified to "/path" (this follows the Posix
8839 standard).
8840 Example: >
8841 simplify("./dir/.././/file/") == "./file/"
8842< Note: The combination "dir/.." is only removed if "dir" is
8843 a searchable directory or does not exist. On Unix, it is also
8844 removed when "dir" is a symbolic link within the same
8845 directory. In order to resolve all the involved symbolic
8846 links before simplifying the path name, use |resolve()|.
8847
8848 Can also be used as a |method|: >
8849 GetName()->simplify()
8850
8851sin({expr}) *sin()*
8852 Return the sine of {expr}, measured in radians, as a |Float|.
8853 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008854 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008855 Examples: >
8856 :echo sin(100)
8857< -0.506366 >
8858 :echo sin(-4.01)
8859< 0.763301
8860
8861 Can also be used as a |method|: >
8862 Compute()->sin()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008863
8864
8865sinh({expr}) *sinh()*
8866 Return the hyperbolic sine of {expr} as a |Float| in the range
8867 [-inf, inf].
8868 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008869 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008870 Examples: >
8871 :echo sinh(0.5)
8872< 0.521095 >
8873 :echo sinh(-0.9)
8874< -1.026517
8875
8876 Can also be used as a |method|: >
8877 Compute()->sinh()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008878
8879
8880slice({expr}, {start} [, {end}]) *slice()*
8881 Similar to using a |slice| "expr[start : end]", but "end" is
8882 used exclusive. And for a string the indexes are used as
8883 character indexes instead of byte indexes, like in
8884 |vim9script|. Also, composing characters are not counted.
8885 When {end} is omitted the slice continues to the last item.
8886 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008887 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008888
8889 Can also be used as a |method|: >
8890 GetList()->slice(offset)
8891
8892
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008893sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008894 Sort the items in {list} in-place. Returns {list}.
8895
8896 If you want a list to remain unmodified make a copy first: >
8897 :let sortedlist = sort(copy(mylist))
8898
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01008899< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008900 string representation of each item to sort on. Numbers sort
8901 after Strings, |Lists| after Numbers. For sorting text in the
8902 current buffer use |:sort|.
8903
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008904 When {how} is given and it is 'i' then case is ignored.
8905 In legacy script, for backwards compatibility, the value one
8906 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008907
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008908 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008909 locale is used for ordering. Implementation details: strcoll()
8910 is used to compare strings. See |:language| check or set the
8911 collation locale. |v:collate| can also be used to check the
8912 current locale. Sorting using the locale typically ignores
8913 case. Example: >
8914 " ö is sorted similarly to o with English locale.
8915 :language collate en_US.UTF8
8916 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8917< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
8918>
8919 " ö is sorted after z with Swedish locale.
8920 :language collate sv_SE.UTF8
8921 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8922< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
8923 This does not work properly on Mac.
8924
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008925 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008926 sorted numerical (Implementation detail: this uses the
Bram Moolenaarbe19d782023-03-09 22:06:49 +00008927 strtod() function to parse numbers. Strings, Lists, Dicts and
8928 Funcrefs will be considered as being 0). Note that this won't
8929 sort a list of strings with numbers!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008930
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008931 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008932 sorted numerical. This is like 'n' but a string containing
8933 digits will be used as the number they represent.
8934
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008935 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008936 sorted numerical. All values must be a Number or a Float.
8937
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008938 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008939 is called to compare items. The function is invoked with two
8940 items as argument and must return zero if they are equal, 1 or
8941 bigger if the first one sorts after the second one, -1 or
8942 smaller if the first one sorts before the second one.
8943
8944 {dict} is for functions with the "dict" attribute. It will be
8945 used to set the local variable "self". |Dictionary-function|
8946
8947 The sort is stable, items which compare equal (as number or as
8948 string) will keep their relative position. E.g., when sorting
8949 on numbers, text strings will sort next to each other, in the
8950 same order as they were originally.
8951
8952 Can also be used as a |method|: >
8953 mylist->sort()
8954
8955< Also see |uniq()|.
8956
8957 Example: >
8958 func MyCompare(i1, i2)
8959 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8960 endfunc
8961 eval mylist->sort("MyCompare")
8962< A shorter compare version for this specific simple case, which
8963 ignores overflow: >
8964 func MyCompare(i1, i2)
8965 return a:i1 - a:i2
8966 endfunc
8967< For a simple expression you can use a lambda: >
8968 eval mylist->sort({i1, i2 -> i1 - i2})
8969<
8970sound_clear() *sound_clear()*
8971 Stop playing all sounds.
8972
8973 On some Linux systems you may need the libcanberra-pulse
8974 package, otherwise sound may not stop.
8975
8976 {only available when compiled with the |+sound| feature}
8977
8978 *sound_playevent()*
8979sound_playevent({name} [, {callback}])
8980 Play a sound identified by {name}. Which event names are
8981 supported depends on the system. Often the XDG sound names
8982 are used. On Ubuntu they may be found in
8983 /usr/share/sounds/freedesktop/stereo. Example: >
8984 call sound_playevent('bell')
8985< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
8986 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
8987 SystemStart, SystemWelcome, etc.
Yee Cheng Chin4314e4f2022-10-08 13:50:05 +01008988 On macOS, {name} refers to files located in
8989 /System/Library/Sounds (e.g. "Tink"). It will also work for
8990 custom installed sounds in folders like ~/Library/Sounds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008991
8992 When {callback} is specified it is invoked when the sound is
8993 finished. The first argument is the sound ID, the second
8994 argument is the status:
8995 0 sound was played to the end
8996 1 sound was interrupted
8997 2 error occurred after sound started
8998 Example: >
8999 func Callback(id, status)
9000 echomsg "sound " .. a:id .. " finished with " .. a:status
9001 endfunc
9002 call sound_playevent('bell', 'Callback')
9003
9004< MS-Windows: {callback} doesn't work for this function.
9005
9006 Returns the sound ID, which can be passed to `sound_stop()`.
9007 Returns zero if the sound could not be played.
9008
9009 Can also be used as a |method|: >
9010 GetSoundName()->sound_playevent()
9011
9012< {only available when compiled with the |+sound| feature}
9013
9014 *sound_playfile()*
9015sound_playfile({path} [, {callback}])
9016 Like `sound_playevent()` but play sound file {path}. {path}
9017 must be a full path. On Ubuntu you may find files to play
9018 with this command: >
9019 :!find /usr/share/sounds -type f | grep -v index.theme
9020
9021< Can also be used as a |method|: >
9022 GetSoundPath()->sound_playfile()
9023
Bram Moolenaar1588bc82022-03-08 21:35:07 +00009024< {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009025
9026
9027sound_stop({id}) *sound_stop()*
9028 Stop playing sound {id}. {id} must be previously returned by
9029 `sound_playevent()` or `sound_playfile()`.
9030
9031 On some Linux systems you may need the libcanberra-pulse
9032 package, otherwise sound may not stop.
9033
9034 On MS-Windows, this does not work for event sound started by
9035 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
9036
9037 Can also be used as a |method|: >
9038 soundid->sound_stop()
9039
9040< {only available when compiled with the |+sound| feature}
9041
9042 *soundfold()*
9043soundfold({word})
9044 Return the sound-folded equivalent of {word}. Uses the first
9045 language in 'spelllang' for the current window that supports
9046 soundfolding. 'spell' must be set. When no sound folding is
9047 possible the {word} is returned unmodified.
9048 This can be used for making spelling suggestions. Note that
9049 the method can be quite slow.
9050
9051 Can also be used as a |method|: >
9052 GetWord()->soundfold()
9053<
9054 *spellbadword()*
9055spellbadword([{sentence}])
9056 Without argument: The result is the badly spelled word under
9057 or after the cursor. The cursor is moved to the start of the
9058 bad word. When no bad word is found in the cursor line the
9059 result is an empty string and the cursor doesn't move.
9060
9061 With argument: The result is the first word in {sentence} that
9062 is badly spelled. If there are no spelling mistakes the
9063 result is an empty string.
9064
9065 The return value is a list with two items:
9066 - The badly spelled word or an empty string.
9067 - The type of the spelling error:
9068 "bad" spelling mistake
9069 "rare" rare word
9070 "local" word only valid in another region
9071 "caps" word should start with Capital
9072 Example: >
9073 echo spellbadword("the quik brown fox")
9074< ['quik', 'bad'] ~
9075
9076 The spelling information for the current window and the value
9077 of 'spelllang' are used.
9078
9079 Can also be used as a |method|: >
9080 GetText()->spellbadword()
9081<
9082 *spellsuggest()*
9083spellsuggest({word} [, {max} [, {capital}]])
9084 Return a |List| with spelling suggestions to replace {word}.
9085 When {max} is given up to this number of suggestions are
9086 returned. Otherwise up to 25 suggestions are returned.
9087
9088 When the {capital} argument is given and it's non-zero only
9089 suggestions with a leading capital will be given. Use this
9090 after a match with 'spellcapcheck'.
9091
9092 {word} can be a badly spelled word followed by other text.
9093 This allows for joining two words that were split. The
9094 suggestions also include the following text, thus you can
9095 replace a line.
9096
9097 {word} may also be a good word. Similar words will then be
9098 returned. {word} itself is not included in the suggestions,
9099 although it may appear capitalized.
9100
9101 The spelling information for the current window is used. The
9102 values of 'spelllang' and 'spellsuggest' are used.
9103
9104 Can also be used as a |method|: >
9105 GetWord()->spellsuggest()
9106
9107split({string} [, {pattern} [, {keepempty}]]) *split()*
9108 Make a |List| out of {string}. When {pattern} is omitted or
9109 empty each white-separated sequence of characters becomes an
9110 item.
9111 Otherwise the string is split where {pattern} matches,
9112 removing the matched characters. 'ignorecase' is not used
9113 here, add \c to ignore case. |/\c|
9114 When the first or last item is empty it is omitted, unless the
9115 {keepempty} argument is given and it's non-zero.
9116 Other empty items are kept when {pattern} matches at least one
9117 character or when {keepempty} is non-zero.
9118 Example: >
9119 :let words = split(getline('.'), '\W\+')
9120< To split a string in individual characters: >
9121 :for c in split(mystring, '\zs')
9122< If you want to keep the separator you can also use '\zs' at
9123 the end of the pattern: >
9124 :echo split('abc:def:ghi', ':\zs')
9125< ['abc:', 'def:', 'ghi'] ~
9126 Splitting a table where the first element can be empty: >
9127 :let items = split(line, ':', 1)
9128< The opposite function is |join()|.
9129
9130 Can also be used as a |method|: >
9131 GetString()->split()
9132
9133sqrt({expr}) *sqrt()*
9134 Return the non-negative square root of Float {expr} as a
9135 |Float|.
9136 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009137 is negative the result is NaN (Not a Number). Returns 0.0 if
9138 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009139 Examples: >
9140 :echo sqrt(100)
9141< 10.0 >
9142 :echo sqrt(-4.01)
9143< nan
9144 "nan" may be different, it depends on system libraries.
9145
9146 Can also be used as a |method|: >
9147 Compute()->sqrt()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009148
9149
9150srand([{expr}]) *srand()*
9151 Initialize seed used by |rand()|:
9152 - If {expr} is not given, seed values are initialized by
9153 reading from /dev/urandom, if possible, or using time(NULL)
9154 a.k.a. epoch time otherwise; this only has second accuracy.
9155 - If {expr} is given it must be a Number. It is used to
9156 initialize the seed values. This is useful for testing or
9157 when a predictable sequence is intended.
9158
9159 Examples: >
9160 :let seed = srand()
9161 :let seed = srand(userinput)
9162 :echo rand(seed)
9163
9164state([{what}]) *state()*
9165 Return a string which contains characters indicating the
9166 current state. Mostly useful in callbacks that want to do
9167 work that may not always be safe. Roughly this works like:
9168 - callback uses state() to check if work is safe to do.
9169 Yes: then do it right away.
9170 No: add to work queue and add a |SafeState| and/or
9171 |SafeStateAgain| autocommand (|SafeState| triggers at
9172 toplevel, |SafeStateAgain| triggers after handling
9173 messages and callbacks).
9174 - When SafeState or SafeStateAgain is triggered and executes
9175 your autocommand, check with `state()` if the work can be
9176 done now, and if yes remove it from the queue and execute.
9177 Remove the autocommand if the queue is now empty.
9178 Also see |mode()|.
9179
9180 When {what} is given only characters in this string will be
9181 added. E.g, this checks if the screen has scrolled: >
9182 if state('s') == ''
9183 " screen has not scrolled
9184<
9185 These characters indicate the state, generally indicating that
9186 something is busy:
9187 m halfway a mapping, :normal command, feedkeys() or
9188 stuffed command
9189 o operator pending, e.g. after |d|
9190 a Insert mode autocomplete active
9191 x executing an autocommand
9192 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
9193 ch_readraw() when reading json
9194 S not triggering SafeState or SafeStateAgain, e.g. after
9195 |f| or a count
9196 c callback invoked, including timer (repeats for
9197 recursiveness up to "ccc")
9198 s screen has scrolled for messages
9199
9200str2float({string} [, {quoted}]) *str2float()*
9201 Convert String {string} to a Float. This mostly works the
9202 same as when using a floating point number in an expression,
9203 see |floating-point-format|. But it's a bit more permissive.
9204 E.g., "1e40" is accepted, while in an expression you need to
9205 write "1.0e40". The hexadecimal form "0x123" is also
9206 accepted, but not others, like binary or octal.
9207 When {quoted} is present and non-zero then embedded single
9208 quotes before the dot are ignored, thus "1'000.0" is a
9209 thousand.
9210 Text after the number is silently ignored.
9211 The decimal point is always '.', no matter what the locale is
9212 set to. A comma ends the number: "12,345.67" is converted to
9213 12.0. You can strip out thousands separators with
9214 |substitute()|: >
9215 let f = str2float(substitute(text, ',', '', 'g'))
9216<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009217 Returns 0.0 if the conversion fails.
9218
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009219 Can also be used as a |method|: >
9220 let f = text->substitute(',', '', 'g')->str2float()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009221
9222str2list({string} [, {utf8}]) *str2list()*
9223 Return a list containing the number values which represent
9224 each character in String {string}. Examples: >
9225 str2list(" ") returns [32]
9226 str2list("ABC") returns [65, 66, 67]
9227< |list2str()| does the opposite.
9228
9229 When {utf8} is omitted or zero, the current 'encoding' is used.
9230 When {utf8} is TRUE, always treat the String as UTF-8
9231 characters. With UTF-8 composing characters are handled
9232 properly: >
9233 str2list("á") returns [97, 769]
9234
9235< Can also be used as a |method|: >
9236 GetString()->str2list()
9237
9238
9239str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
9240 Convert string {string} to a number.
9241 {base} is the conversion base, it can be 2, 8, 10 or 16.
9242 When {quoted} is present and non-zero then embedded single
9243 quotes are ignored, thus "1'000'000" is a million.
9244
9245 When {base} is omitted base 10 is used. This also means that
9246 a leading zero doesn't cause octal conversion to be used, as
9247 with the default String to Number conversion. Example: >
9248 let nr = str2nr('0123')
9249<
9250 When {base} is 16 a leading "0x" or "0X" is ignored. With a
9251 different base the result will be zero. Similarly, when
9252 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
9253 {base} is 2 a leading "0b" or "0B" is ignored.
9254 Text after the number is silently ignored.
9255
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009256 Returns 0 if {string} is empty or on error.
9257
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009258 Can also be used as a |method|: >
9259 GetText()->str2nr()
9260
9261
9262strcharlen({string}) *strcharlen()*
9263 The result is a Number, which is the number of characters
9264 in String {string}. Composing characters are ignored.
9265 |strchars()| can count the number of characters, counting
9266 composing characters separately.
9267
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009268 Returns 0 if {string} is empty or on error.
9269
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009270 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
9271
9272 Can also be used as a |method|: >
9273 GetText()->strcharlen()
9274
9275
9276strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
9277 Like |strpart()| but using character index and length instead
9278 of byte index and length.
9279 When {skipcc} is omitted or zero, composing characters are
9280 counted separately.
9281 When {skipcc} set to 1, Composing characters are ignored,
9282 similar to |slice()|.
9283 When a character index is used where a character does not
9284 exist it is omitted and counted as one character. For
9285 example: >
9286 strcharpart('abc', -1, 2)
9287< results in 'a'.
9288
Bram Moolenaard592deb2022-06-17 15:42:40 +01009289 Returns an empty string on error.
9290
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009291 Can also be used as a |method|: >
9292 GetText()->strcharpart(5)
9293
9294
9295strchars({string} [, {skipcc}]) *strchars()*
9296 The result is a Number, which is the number of characters
9297 in String {string}.
9298 When {skipcc} is omitted or zero, composing characters are
9299 counted separately.
9300 When {skipcc} set to 1, Composing characters are ignored.
9301 |strcharlen()| always does this.
9302
Bram Moolenaard592deb2022-06-17 15:42:40 +01009303 Returns zero on error.
9304
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009305 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
9306
9307 {skipcc} is only available after 7.4.755. For backward
9308 compatibility, you can define a wrapper function: >
9309 if has("patch-7.4.755")
9310 function s:strchars(str, skipcc)
9311 return strchars(a:str, a:skipcc)
9312 endfunction
9313 else
9314 function s:strchars(str, skipcc)
9315 if a:skipcc
9316 return strlen(substitute(a:str, ".", "x", "g"))
9317 else
9318 return strchars(a:str)
9319 endif
9320 endfunction
9321 endif
9322<
9323 Can also be used as a |method|: >
9324 GetText()->strchars()
9325
9326strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
9327 The result is a Number, which is the number of display cells
9328 String {string} occupies on the screen when it starts at {col}
9329 (first column is zero). When {col} is omitted zero is used.
9330 Otherwise it is the screen column where to start. This
9331 matters for Tab characters.
9332 The option settings of the current window are used. This
9333 matters for anything that's displayed differently, such as
9334 'tabstop' and 'display'.
9335 When {string} contains characters with East Asian Width Class
9336 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009337 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009338 Also see |strlen()|, |strwidth()| and |strchars()|.
9339
9340 Can also be used as a |method|: >
9341 GetText()->strdisplaywidth()
9342
9343strftime({format} [, {time}]) *strftime()*
9344 The result is a String, which is a formatted date and time, as
9345 specified by the {format} string. The given {time} is used,
9346 or the current time if no time is given. The accepted
9347 {format} depends on your system, thus this is not portable!
9348 See the manual page of the C function strftime() for the
9349 format. The maximum length of the result is 80 characters.
9350 See also |localtime()|, |getftime()| and |strptime()|.
9351 The language can be changed with the |:language| command.
9352 Examples: >
9353 :echo strftime("%c") Sun Apr 27 11:49:23 1997
9354 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
9355 :echo strftime("%y%m%d %T") 970427 11:53:55
9356 :echo strftime("%H:%M") 11:55
9357 :echo strftime("%c", getftime("file.c"))
9358 Show mod time of file.c.
9359< Not available on all systems. To check use: >
9360 :if exists("*strftime")
9361
9362< Can also be used as a |method|: >
9363 GetFormat()->strftime()
9364
9365strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01009366 Get a Number corresponding to the character at {index} in
9367 {str}. This uses a zero-based character index, not a byte
9368 index. Composing characters are considered separate
9369 characters here. Use |nr2char()| to convert the Number to a
9370 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009371 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009372 Also see |strcharpart()| and |strchars()|.
9373
9374 Can also be used as a |method|: >
9375 GetText()->strgetchar(5)
9376
9377stridx({haystack}, {needle} [, {start}]) *stridx()*
9378 The result is a Number, which gives the byte index in
9379 {haystack} of the first occurrence of the String {needle}.
9380 If {start} is specified, the search starts at index {start}.
9381 This can be used to find a second match: >
9382 :let colon1 = stridx(line, ":")
9383 :let colon2 = stridx(line, ":", colon1 + 1)
9384< The search is done case-sensitive.
9385 For pattern searches use |match()|.
9386 -1 is returned if the {needle} does not occur in {haystack}.
9387 See also |strridx()|.
9388 Examples: >
9389 :echo stridx("An Example", "Example") 3
9390 :echo stridx("Starting point", "Start") 0
9391 :echo stridx("Starting point", "start") -1
9392< *strstr()* *strchr()*
9393 stridx() works similar to the C function strstr(). When used
9394 with a single character it works similar to strchr().
9395
9396 Can also be used as a |method|: >
9397 GetHaystack()->stridx(needle)
9398<
9399 *string()*
9400string({expr}) Return {expr} converted to a String. If {expr} is a Number,
9401 Float, String, Blob or a composition of them, then the result
9402 can be parsed back with |eval()|.
9403 {expr} type result ~
9404 String 'string' (single quotes are doubled)
9405 Number 123
9406 Float 123.123456 or 1.123456e8
9407 Funcref function('name')
9408 Blob 0z00112233.44556677.8899
9409 List [item, item]
9410 Dictionary {key: value, key: value}
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00009411 Class class SomeName
9412 Object object of SomeName {lnum: 1, col: 3}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009413
9414 When a |List| or |Dictionary| has a recursive reference it is
9415 replaced by "[...]" or "{...}". Using eval() on the result
9416 will then fail.
9417
9418 Can also be used as a |method|: >
9419 mylist->string()
9420
9421< Also see |strtrans()|.
9422
9423
9424strlen({string}) *strlen()*
9425 The result is a Number, which is the length of the String
9426 {string} in bytes.
9427 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009428 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009429 If you want to count the number of multibyte characters use
9430 |strchars()|.
9431 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
9432
9433 Can also be used as a |method|: >
9434 GetString()->strlen()
9435
9436strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
9437 The result is a String, which is part of {src}, starting from
9438 byte {start}, with the byte length {len}.
9439 When {chars} is present and TRUE then {len} is the number of
9440 characters positions (composing characters are not counted
9441 separately, thus "1" means one base character and any
9442 following composing characters).
9443 To count {start} as characters instead of bytes use
9444 |strcharpart()|.
9445
9446 When bytes are selected which do not exist, this doesn't
9447 result in an error, the bytes are simply omitted.
9448 If {len} is missing, the copy continues from {start} till the
9449 end of the {src}. >
9450 strpart("abcdefg", 3, 2) == "de"
9451 strpart("abcdefg", -2, 4) == "ab"
9452 strpart("abcdefg", 5, 4) == "fg"
9453 strpart("abcdefg", 3) == "defg"
9454
9455< Note: To get the first character, {start} must be 0. For
9456 example, to get the character under the cursor: >
9457 strpart(getline("."), col(".") - 1, 1, v:true)
9458<
Bram Moolenaard592deb2022-06-17 15:42:40 +01009459 Returns an empty string on error.
9460
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009461 Can also be used as a |method|: >
9462 GetText()->strpart(5)
9463
9464strptime({format}, {timestring}) *strptime()*
9465 The result is a Number, which is a unix timestamp representing
9466 the date and time in {timestring}, which is expected to match
9467 the format specified in {format}.
9468
9469 The accepted {format} depends on your system, thus this is not
9470 portable! See the manual page of the C function strptime()
9471 for the format. Especially avoid "%c". The value of $TZ also
9472 matters.
9473
9474 If the {timestring} cannot be parsed with {format} zero is
9475 returned. If you do not know the format of {timestring} you
9476 can try different {format} values until you get a non-zero
9477 result.
9478
9479 See also |strftime()|.
9480 Examples: >
9481 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
9482< 862156163 >
9483 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
9484< Sun Apr 27 11:53:55 1997 >
9485 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
9486< Sun Apr 27 12:53:55 1997
9487
9488 Can also be used as a |method|: >
9489 GetFormat()->strptime(timestring)
9490<
9491 Not available on all systems. To check use: >
9492 :if exists("*strptime")
9493
9494strridx({haystack}, {needle} [, {start}]) *strridx()*
9495 The result is a Number, which gives the byte index in
9496 {haystack} of the last occurrence of the String {needle}.
9497 When {start} is specified, matches beyond this index are
9498 ignored. This can be used to find a match before a previous
9499 match: >
9500 :let lastcomma = strridx(line, ",")
9501 :let comma2 = strridx(line, ",", lastcomma - 1)
9502< The search is done case-sensitive.
9503 For pattern searches use |match()|.
9504 -1 is returned if the {needle} does not occur in {haystack}.
9505 If the {needle} is empty the length of {haystack} is returned.
9506 See also |stridx()|. Examples: >
9507 :echo strridx("an angry armadillo", "an") 3
9508< *strrchr()*
9509 When used with a single character it works similar to the C
9510 function strrchr().
9511
9512 Can also be used as a |method|: >
9513 GetHaystack()->strridx(needle)
9514
9515strtrans({string}) *strtrans()*
9516 The result is a String, which is {string} with all unprintable
9517 characters translated into printable characters |'isprint'|.
9518 Like they are shown in a window. Example: >
9519 echo strtrans(@a)
9520< This displays a newline in register a as "^@" instead of
9521 starting a new line.
9522
Bram Moolenaard592deb2022-06-17 15:42:40 +01009523 Returns an empty string on error.
9524
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009525 Can also be used as a |method|: >
9526 GetString()->strtrans()
9527
Christian Brabandt67672ef2023-04-24 21:09:54 +01009528strutf16len({string} [, {countcc}]) *strutf16len()*
9529 The result is a Number, which is the number of UTF-16 code
9530 units in String {string} (after converting it to UTF-16).
9531
9532 When {countcc} is TRUE, composing characters are counted
9533 separately.
9534 When {countcc} is omitted or FALSE, composing characters are
9535 ignored.
9536
9537 Returns zero on error.
9538
9539 Also see |strlen()| and |strcharlen()|.
9540 Examples: >
9541 echo strutf16len('a') returns 1
9542 echo strutf16len('©') returns 1
9543 echo strutf16len('😊') returns 2
9544 echo strutf16len('ą́') returns 1
9545 echo strutf16len('ą́', v:true) returns 3
a5ob7r790f9a82023-09-25 06:05:47 +09009546<
Christian Brabandt67672ef2023-04-24 21:09:54 +01009547 Can also be used as a |method|: >
9548 GetText()->strutf16len()
9549<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009550strwidth({string}) *strwidth()*
9551 The result is a Number, which is the number of display cells
9552 String {string} occupies. A Tab character is counted as one
9553 cell, alternatively use |strdisplaywidth()|.
9554 When {string} contains characters with East Asian Width Class
9555 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009556 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009557 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
9558
9559 Can also be used as a |method|: >
9560 GetString()->strwidth()
9561
9562submatch({nr} [, {list}]) *submatch()* *E935*
9563 Only for an expression in a |:substitute| command or
9564 substitute() function.
9565 Returns the {nr}'th submatch of the matched text. When {nr}
9566 is 0 the whole matched text is returned.
9567 Note that a NL in the string can stand for a line break of a
9568 multi-line match or a NUL character in the text.
9569 Also see |sub-replace-expression|.
9570
9571 If {list} is present and non-zero then submatch() returns
9572 a list of strings, similar to |getline()| with two arguments.
9573 NL characters in the text represent NUL characters in the
9574 text.
9575 Only returns more than one item for |:substitute|, inside
9576 |substitute()| this list will always contain one or zero
9577 items, since there are no real line breaks.
9578
9579 When substitute() is used recursively only the submatches in
9580 the current (deepest) call can be obtained.
9581
Bram Moolenaard592deb2022-06-17 15:42:40 +01009582 Returns an empty string or list on error.
9583
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009584 Examples: >
9585 :s/\d\+/\=submatch(0) + 1/
9586 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
9587< This finds the first number in the line and adds one to it.
9588 A line break is included as a newline character.
9589
9590 Can also be used as a |method|: >
9591 GetNr()->submatch()
9592
9593substitute({string}, {pat}, {sub}, {flags}) *substitute()*
9594 The result is a String, which is a copy of {string}, in which
9595 the first match of {pat} is replaced with {sub}.
9596 When {flags} is "g", all matches of {pat} in {string} are
9597 replaced. Otherwise {flags} should be "".
9598
9599 This works like the ":substitute" command (without any flags).
9600 But the matching with {pat} is always done like the 'magic'
9601 option is set and 'cpoptions' is empty (to make scripts
9602 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
9603 if you want to ignore or match case and ignore 'ignorecase'.
9604 'smartcase' is not used. See |string-match| for how {pat} is
9605 used.
9606
9607 A "~" in {sub} is not replaced with the previous {sub}.
9608 Note that some codes in {sub} have a special meaning
9609 |sub-replace-special|. For example, to replace something with
9610 "\n" (two characters), use "\\\\n" or '\\n'.
9611
9612 When {pat} does not match in {string}, {string} is returned
9613 unmodified.
9614
9615 Example: >
9616 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
9617< This removes the last component of the 'path' option. >
9618 :echo substitute("testing", ".*", "\\U\\0", "")
9619< results in "TESTING".
9620
9621 When {sub} starts with "\=", the remainder is interpreted as
9622 an expression. See |sub-replace-expression|. Example: >
9623 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009624 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009625
9626< When {sub} is a Funcref that function is called, with one
9627 optional argument. Example: >
9628 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
9629< The optional argument is a list which contains the whole
9630 matched string and up to nine submatches, like what
9631 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009632 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009633
Bram Moolenaard592deb2022-06-17 15:42:40 +01009634< Returns an empty string on error.
9635
9636 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009637 GetString()->substitute(pat, sub, flags)
9638
Bram Moolenaarc216a7a2022-12-05 13:50:55 +00009639swapfilelist() *swapfilelist()*
9640 Returns a list of swap file names, like what "vim -r" shows.
9641 See the |-r| command argument. The 'directory' option is used
9642 for the directories to inspect. If you only want to get a
9643 list of swap files in the current directory then temporarily
9644 set 'directory' to a dot: >
9645 let save_dir = &directory
9646 let &directory = '.'
9647 let swapfiles = swapfilelist()
9648 let &directory = save_dir
9649
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009650swapinfo({fname}) *swapinfo()*
9651 The result is a dictionary, which holds information about the
9652 swapfile {fname}. The available fields are:
9653 version Vim version
9654 user user name
9655 host host name
9656 fname original file name
9657 pid PID of the Vim process that created the swap
9658 file
9659 mtime last modification time in seconds
9660 inode Optional: INODE number of the file
9661 dirty 1 if file was modified, 0 if not
9662 Note that "user" and "host" are truncated to at most 39 bytes.
9663 In case of failure an "error" item is added with the reason:
9664 Cannot open file: file not found or in accessible
9665 Cannot read file: cannot read first block
9666 Not a swap file: does not contain correct block ID
9667 Magic number mismatch: Info in first block is invalid
9668
9669 Can also be used as a |method|: >
9670 GetFilename()->swapinfo()
9671
9672swapname({buf}) *swapname()*
9673 The result is the swap file path of the buffer {expr}.
9674 For the use of {buf}, see |bufname()| above.
9675 If buffer {buf} is the current buffer, the result is equal to
9676 |:swapname| (unless there is no swap file).
9677 If buffer {buf} has no swap file, returns an empty string.
9678
9679 Can also be used as a |method|: >
9680 GetBufname()->swapname()
9681
9682synID({lnum}, {col}, {trans}) *synID()*
9683 The result is a Number, which is the syntax ID at the position
9684 {lnum} and {col} in the current window.
9685 The syntax ID can be used with |synIDattr()| and
9686 |synIDtrans()| to obtain syntax information about text.
9687
9688 {col} is 1 for the leftmost column, {lnum} is 1 for the first
9689 line. 'synmaxcol' applies, in a longer line zero is returned.
9690 Note that when the position is after the last character,
9691 that's where the cursor can be in Insert mode, synID() returns
9692 zero. {lnum} is used like with |getline()|.
9693
9694 When {trans} is |TRUE|, transparent items are reduced to the
9695 item that they reveal. This is useful when wanting to know
9696 the effective color. When {trans} is |FALSE|, the transparent
9697 item is returned. This is useful when wanting to know which
9698 syntax item is effective (e.g. inside parens).
9699 Warning: This function can be very slow. Best speed is
9700 obtained by going through the file in forward direction.
9701
Bram Moolenaard592deb2022-06-17 15:42:40 +01009702 Returns zero on error.
9703
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009704 Example (echoes the name of the syntax item under the cursor): >
9705 :echo synIDattr(synID(line("."), col("."), 1), "name")
9706<
9707
9708synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
9709 The result is a String, which is the {what} attribute of
9710 syntax ID {synID}. This can be used to obtain information
9711 about a syntax item.
9712 {mode} can be "gui", "cterm" or "term", to get the attributes
9713 for that mode. When {mode} is omitted, or an invalid value is
9714 used, the attributes for the currently active highlighting are
9715 used (GUI, cterm or term).
9716 Use synIDtrans() to follow linked highlight groups.
9717 {what} result
9718 "name" the name of the syntax item
9719 "fg" foreground color (GUI: color name used to set
9720 the color, cterm: color number as a string,
9721 term: empty string)
9722 "bg" background color (as with "fg")
9723 "font" font name (only available in the GUI)
9724 |highlight-font|
9725 "sp" special color for the GUI (as with "fg")
9726 |highlight-guisp|
9727 "ul" underline color for cterm: number as a string
9728 "fg#" like "fg", but for the GUI and the GUI is
9729 running the name in "#RRGGBB" form
9730 "bg#" like "fg#" for "bg"
9731 "sp#" like "fg#" for "sp"
9732 "bold" "1" if bold
9733 "italic" "1" if italic
9734 "reverse" "1" if reverse
9735 "inverse" "1" if inverse (= reverse)
9736 "standout" "1" if standout
9737 "underline" "1" if underlined
9738 "undercurl" "1" if undercurled
9739 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +01009740 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009741
Bram Moolenaard592deb2022-06-17 15:42:40 +01009742 Returns an empty string on error.
9743
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009744 Example (echoes the color of the syntax item under the
9745 cursor): >
9746 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
9747<
9748 Can also be used as a |method|: >
9749 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9750
9751
9752synIDtrans({synID}) *synIDtrans()*
9753 The result is a Number, which is the translated syntax ID of
9754 {synID}. This is the syntax group ID of what is being used to
9755 highlight the character. Highlight links given with
9756 ":highlight link" are followed.
9757
Bram Moolenaard592deb2022-06-17 15:42:40 +01009758 Returns zero on error.
9759
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009760 Can also be used as a |method|: >
9761 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9762
9763synconcealed({lnum}, {col}) *synconcealed()*
9764 The result is a |List| with currently three items:
9765 1. The first item in the list is 0 if the character at the
9766 position {lnum} and {col} is not part of a concealable
9767 region, 1 if it is. {lnum} is used like with |getline()|.
9768 2. The second item in the list is a string. If the first item
9769 is 1, the second item contains the text which will be
9770 displayed in place of the concealed text, depending on the
9771 current setting of 'conceallevel' and 'listchars'.
9772 3. The third and final item in the list is a number
9773 representing the specific syntax region matched in the
9774 line. When the character is not concealed the value is
9775 zero. This allows detection of the beginning of a new
9776 concealable region if there are two consecutive regions
9777 with the same replacement character. For an example, if
9778 the text is "123456" and both "23" and "45" are concealed
9779 and replaced by the character "X", then:
9780 call returns ~
9781 synconcealed(lnum, 1) [0, '', 0]
9782 synconcealed(lnum, 2) [1, 'X', 1]
9783 synconcealed(lnum, 3) [1, 'X', 1]
9784 synconcealed(lnum, 4) [1, 'X', 2]
9785 synconcealed(lnum, 5) [1, 'X', 2]
9786 synconcealed(lnum, 6) [0, '', 0]
9787
9788
9789synstack({lnum}, {col}) *synstack()*
9790 Return a |List|, which is the stack of syntax items at the
9791 position {lnum} and {col} in the current window. {lnum} is
9792 used like with |getline()|. Each item in the List is an ID
9793 like what |synID()| returns.
9794 The first item in the List is the outer region, following are
9795 items contained in that one. The last one is what |synID()|
9796 returns, unless not the whole item is highlighted or it is a
9797 transparent item.
9798 This function is useful for debugging a syntax file.
9799 Example that shows the syntax stack under the cursor: >
9800 for id in synstack(line("."), col("."))
9801 echo synIDattr(id, "name")
9802 endfor
9803< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +01009804 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009805 character in a line and the first column in an empty line are
9806 valid positions.
9807
9808system({expr} [, {input}]) *system()* *E677*
9809 Get the output of the shell command {expr} as a |String|. See
9810 |systemlist()| to get the output as a |List|.
9811
9812 When {input} is given and is a |String| this string is written
9813 to a file and passed as stdin to the command. The string is
9814 written as-is, you need to take care of using the correct line
9815 separators yourself.
9816 If {input} is given and is a |List| it is written to the file
9817 in a way |writefile()| does with {binary} set to "b" (i.e.
9818 with a newline between each list item with newlines inside
9819 list items converted to NULs).
9820 When {input} is given and is a number that is a valid id for
9821 an existing buffer then the content of the buffer is written
9822 to the file line by line, each line terminated by a NL and
9823 NULs characters where the text has a NL.
9824
9825 Pipes are not used, the 'shelltemp' option is not used.
9826
9827 When prepended by |:silent| the terminal will not be set to
9828 cooked mode. This is meant to be used for commands that do
9829 not need the user to type. It avoids stray characters showing
9830 up on the screen which require |CTRL-L| to remove. >
9831 :silent let f = system('ls *.vim')
9832<
9833 Note: Use |shellescape()| or |::S| with |expand()| or
9834 |fnamemodify()| to escape special characters in a command
9835 argument. Newlines in {expr} may cause the command to fail.
9836 The characters in 'shellquote' and 'shellxquote' may also
9837 cause trouble.
9838 This is not to be used for interactive commands.
9839
9840 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009841 :let files = system('ls ' .. shellescape(expand('%:h')))
9842 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009843
9844< To make the result more system-independent, the shell output
9845 is filtered to replace <CR> with <NL> for Macintosh, and
9846 <CR><NL> with <NL> for DOS-like systems.
9847 To avoid the string being truncated at a NUL, all NUL
9848 characters are replaced with SOH (0x01).
9849
9850 The command executed is constructed using several options:
9851 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
9852 ({tmp} is an automatically generated file name).
9853 For Unix, braces are put around {expr} to allow for
9854 concatenated commands.
9855
9856 The command will be executed in "cooked" mode, so that a
9857 CTRL-C will interrupt the command (on Unix at least).
9858
9859 The resulting error code can be found in |v:shell_error|.
9860 This function will fail in |restricted-mode|.
9861
9862 Note that any wrong value in the options mentioned above may
9863 make the function fail. It has also been reported to fail
9864 when using a security agent application.
9865 Unlike ":!cmd" there is no automatic check for changed files.
9866 Use |:checktime| to force a check.
9867
9868 Can also be used as a |method|: >
9869 :echo GetCmd()->system()
9870
9871
9872systemlist({expr} [, {input}]) *systemlist()*
9873 Same as |system()|, but returns a |List| with lines (parts of
9874 output separated by NL) with NULs transformed into NLs. Output
9875 is the same as |readfile()| will output with {binary} argument
9876 set to "b", except that there is no extra empty item when the
9877 result ends in a NL.
9878 Note that on MS-Windows you may get trailing CR characters.
9879
9880 To see the difference between "echo hello" and "echo -n hello"
9881 use |system()| and |split()|: >
9882 echo system('echo hello')->split('\n', 1)
9883<
9884 Returns an empty string on error.
9885
9886 Can also be used as a |method|: >
9887 :echo GetCmd()->systemlist()
9888
9889
9890tabpagebuflist([{arg}]) *tabpagebuflist()*
9891 The result is a |List|, where each item is the number of the
9892 buffer associated with each window in the current tab page.
9893 {arg} specifies the number of the tab page to be used. When
9894 omitted the current tab page is used.
9895 When {arg} is invalid the number zero is returned.
9896 To get a list of all buffers in all tabs use this: >
9897 let buflist = []
9898 for i in range(tabpagenr('$'))
9899 call extend(buflist, tabpagebuflist(i + 1))
9900 endfor
9901< Note that a buffer may appear in more than one window.
9902
9903 Can also be used as a |method|: >
9904 GetTabpage()->tabpagebuflist()
9905
9906tabpagenr([{arg}]) *tabpagenr()*
9907 The result is a Number, which is the number of the current
9908 tab page. The first tab page has number 1.
9909
9910 The optional argument {arg} supports the following values:
9911 $ the number of the last tab page (the tab page
9912 count).
9913 # the number of the last accessed tab page
9914 (where |g<Tab>| goes to). if there is no
9915 previous tab page 0 is returned.
9916 The number can be used with the |:tab| command.
9917
Bram Moolenaard592deb2022-06-17 15:42:40 +01009918 Returns zero on error.
9919
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009920
9921tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
9922 Like |winnr()| but for tab page {tabarg}.
9923 {tabarg} specifies the number of tab page to be used.
9924 {arg} is used like with |winnr()|:
9925 - When omitted the current window number is returned. This is
9926 the window which will be used when going to this tab page.
9927 - When "$" the number of windows is returned.
9928 - When "#" the previous window nr is returned.
9929 Useful examples: >
9930 tabpagewinnr(1) " current window of tab page 1
9931 tabpagewinnr(4, '$') " number of windows in tab page 4
9932< When {tabarg} is invalid zero is returned.
9933
9934 Can also be used as a |method|: >
9935 GetTabpage()->tabpagewinnr()
9936<
9937 *tagfiles()*
9938tagfiles() Returns a |List| with the file names used to search for tags
9939 for the current buffer. This is the 'tags' option expanded.
9940
9941
9942taglist({expr} [, {filename}]) *taglist()*
9943 Returns a |List| of tags matching the regular expression {expr}.
9944
9945 If {filename} is passed it is used to prioritize the results
9946 in the same way that |:tselect| does. See |tag-priority|.
9947 {filename} should be the full path of the file.
9948
9949 Each list item is a dictionary with at least the following
9950 entries:
9951 name Name of the tag.
9952 filename Name of the file where the tag is
9953 defined. It is either relative to the
9954 current directory or a full path.
9955 cmd Ex command used to locate the tag in
9956 the file.
9957 kind Type of the tag. The value for this
9958 entry depends on the language specific
9959 kind values. Only available when
9960 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +00009961 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009962 static A file specific tag. Refer to
9963 |static-tag| for more information.
9964 More entries may be present, depending on the content of the
9965 tags file: access, implementation, inherits and signature.
9966 Refer to the ctags documentation for information about these
9967 fields. For C code the fields "struct", "class" and "enum"
9968 may appear, they give the name of the entity the tag is
9969 contained in.
9970
9971 The ex-command "cmd" can be either an ex search pattern, a
9972 line number or a line number followed by a byte number.
9973
9974 If there are no matching tags, then an empty list is returned.
9975
9976 To get an exact tag match, the anchors '^' and '$' should be
9977 used in {expr}. This also make the function work faster.
9978 Refer to |tag-regexp| for more information about the tag
9979 search regular expression pattern.
9980
9981 Refer to |'tags'| for information about how the tags file is
9982 located by Vim. Refer to |tags-file-format| for the format of
9983 the tags file generated by the different ctags tools.
9984
9985 Can also be used as a |method|: >
9986 GetTagpattern()->taglist()
9987
9988tan({expr}) *tan()*
9989 Return the tangent of {expr}, measured in radians, as a |Float|
9990 in the range [-inf, inf].
9991 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009992 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009993 Examples: >
9994 :echo tan(10)
9995< 0.648361 >
9996 :echo tan(-4.01)
9997< -1.181502
9998
9999 Can also be used as a |method|: >
10000 Compute()->tan()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010001
10002
10003tanh({expr}) *tanh()*
10004 Return the hyperbolic tangent of {expr} as a |Float| in the
10005 range [-1, 1].
10006 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010007 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010008 Examples: >
10009 :echo tanh(0.5)
10010< 0.462117 >
10011 :echo tanh(-1)
10012< -0.761594
10013
10014 Can also be used as a |method|: >
10015 Compute()->tanh()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010016
10017
10018tempname() *tempname()* *temp-file-name*
10019 The result is a String, which is the name of a file that
10020 doesn't exist. It can be used for a temporary file. The name
10021 is different for at least 26 consecutive calls. Example: >
10022 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010023 :exe "redir > " .. tmpfile
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010024< For Unix, the file will be in a private directory |tempfile|.
10025 For MS-Windows forward slashes are used when the 'shellslash'
10026 option is set, or when 'shellcmdflag' starts with '-' and
10027 'shell' does not contain powershell or pwsh.
10028
10029
10030term_ functions are documented here: |terminal-function-details|
10031
10032
10033terminalprops() *terminalprops()*
10034 Returns a |Dictionary| with properties of the terminal that Vim
10035 detected from the response to |t_RV| request. See
10036 |v:termresponse| for the response itself. If |v:termresponse|
10037 is empty most values here will be 'u' for unknown.
10038 cursor_style whether sending |t_RS| works **
10039 cursor_blink_mode whether sending |t_RC| works **
10040 underline_rgb whether |t_8u| works **
10041 mouse mouse type supported
Bram Moolenaar4bc85f22022-10-21 14:17:24 +010010042 kitty whether Kitty terminal was detected
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010043
10044 ** value 'u' for unknown, 'y' for yes, 'n' for no
10045
10046 If the |+termresponse| feature is missing then the result is
10047 an empty dictionary.
10048
10049 If "cursor_style" is 'y' then |t_RS| will be sent to request the
10050 current cursor style.
10051 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
10052 request the cursor blink status.
10053 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
10054 is not empty, Vim will detect the working of sending |t_RS|
10055 and |t_RC| on startup.
10056
10057 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
10058 This avoids sending it to xterm, which would clear the colors.
10059
10060 For "mouse" the value 'u' is unknown
10061
10062 Also see:
10063 - 'ambiwidth' - detected by using |t_u7|.
10064 - |v:termstyleresp| and |v:termblinkresp| for the response to
10065 |t_RS| and |t_RC|.
10066
10067
10068test_ functions are documented here: |test-functions-details|
10069
10070
10071 *timer_info()*
10072timer_info([{id}])
10073 Return a list with information about timers.
10074 When {id} is given only information about this timer is
10075 returned. When timer {id} does not exist an empty list is
10076 returned.
10077 When {id} is omitted information about all timers is returned.
10078
10079 For each timer the information is stored in a |Dictionary| with
10080 these items:
10081 "id" the timer ID
10082 "time" time the timer was started with
10083 "remaining" time until the timer fires
10084 "repeat" number of times the timer will still fire;
10085 -1 means forever
10086 "callback" the callback
10087 "paused" 1 if the timer is paused, 0 otherwise
10088
10089 Can also be used as a |method|: >
10090 GetTimer()->timer_info()
10091
10092< {only available when compiled with the |+timers| feature}
10093
10094timer_pause({timer}, {paused}) *timer_pause()*
10095 Pause or unpause a timer. A paused timer does not invoke its
10096 callback when its time expires. Unpausing a timer may cause
10097 the callback to be invoked almost immediately if enough time
10098 has passed.
10099
10100 Pausing a timer is useful to avoid the callback to be called
10101 for a short time.
10102
10103 If {paused} evaluates to a non-zero Number or a non-empty
10104 String, then the timer is paused, otherwise it is unpaused.
10105 See |non-zero-arg|.
10106
10107 Can also be used as a |method|: >
10108 GetTimer()->timer_pause(1)
10109
10110< {only available when compiled with the |+timers| feature}
10111
10112 *timer_start()* *timer* *timers*
10113timer_start({time}, {callback} [, {options}])
10114 Create a timer and return the timer ID.
10115
10116 {time} is the waiting time in milliseconds. This is the
10117 minimum time before invoking the callback. When the system is
10118 busy or Vim is not waiting for input the time will be longer.
Bram Moolenaardd60c362023-02-27 15:49:53 +000010119 Zero can be used to execute the callback when Vim is back in
10120 the main loop.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010121
10122 {callback} is the function to call. It can be the name of a
10123 function or a |Funcref|. It is called with one argument, which
10124 is the timer ID. The callback is only invoked when Vim is
10125 waiting for input.
10126 If you want to show a message look at |popup_notification()|
10127 to avoid interfering with what the user is doing.
10128
10129 {options} is a dictionary. Supported entries:
10130 "repeat" Number of times to repeat calling the
10131 callback. -1 means forever. When not present
10132 the callback will be called once.
10133 If the timer causes an error three times in a
10134 row the repeat is cancelled. This avoids that
10135 Vim becomes unusable because of all the error
10136 messages.
10137
Bram Moolenaard592deb2022-06-17 15:42:40 +010010138 Returns -1 on error.
10139
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010140 Example: >
10141 func MyHandler(timer)
10142 echo 'Handler called'
10143 endfunc
10144 let timer = timer_start(500, 'MyHandler',
10145 \ {'repeat': 3})
10146< This will invoke MyHandler() three times at 500 msec
10147 intervals.
10148
10149 Can also be used as a |method|: >
10150 GetMsec()->timer_start(callback)
10151
10152< Not available in the |sandbox|.
10153 {only available when compiled with the |+timers| feature}
10154
10155timer_stop({timer}) *timer_stop()*
10156 Stop a timer. The timer callback will no longer be invoked.
10157 {timer} is an ID returned by timer_start(), thus it must be a
10158 Number. If {timer} does not exist there is no error.
10159
10160 Can also be used as a |method|: >
10161 GetTimer()->timer_stop()
10162
10163< {only available when compiled with the |+timers| feature}
10164
10165timer_stopall() *timer_stopall()*
10166 Stop all timers. The timer callbacks will no longer be
10167 invoked. Useful if a timer is misbehaving. If there are no
10168 timers there is no error.
10169
10170 {only available when compiled with the |+timers| feature}
10171
10172tolower({expr}) *tolower()*
10173 The result is a copy of the String given, with all uppercase
10174 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010010175 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010176
10177 Can also be used as a |method|: >
10178 GetText()->tolower()
10179
10180toupper({expr}) *toupper()*
10181 The result is a copy of the String given, with all lowercase
10182 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010010183 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010184
10185 Can also be used as a |method|: >
10186 GetText()->toupper()
10187
10188tr({src}, {fromstr}, {tostr}) *tr()*
10189 The result is a copy of the {src} string with all characters
10190 which appear in {fromstr} replaced by the character in that
10191 position in the {tostr} string. Thus the first character in
10192 {fromstr} is translated into the first character in {tostr}
10193 and so on. Exactly like the unix "tr" command.
10194 This code also deals with multibyte characters properly.
10195
Bram Moolenaard592deb2022-06-17 15:42:40 +010010196 Returns an empty string on error.
10197
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010198 Examples: >
10199 echo tr("hello there", "ht", "HT")
10200< returns "Hello THere" >
10201 echo tr("<blob>", "<>", "{}")
10202< returns "{blob}"
10203
10204 Can also be used as a |method|: >
10205 GetText()->tr(from, to)
10206
10207trim({text} [, {mask} [, {dir}]]) *trim()*
10208 Return {text} as a String where any character in {mask} is
10209 removed from the beginning and/or end of {text}.
10210
Illia Bobyr80799172023-10-17 18:00:50 +020010211 If {mask} is not given, or is an empty string, {mask} is all
10212 characters up to 0x20, which includes Tab, space, NL and CR,
10213 plus the non-breaking space character 0xa0.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010214
10215 The optional {dir} argument specifies where to remove the
10216 characters:
10217 0 remove from the beginning and end of {text}
10218 1 remove only at the beginning of {text}
10219 2 remove only at the end of {text}
10220 When omitted both ends are trimmed.
10221
10222 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010223 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010224
10225 Examples: >
10226 echo trim(" some text ")
10227< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010228 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010229< returns "RESERVE_TAIL" >
10230 echo trim("rm<Xrm<>X>rrm", "rm<>")
10231< returns "Xrm<>X" (characters in the middle are not removed) >
10232 echo trim(" vim ", " ", 2)
10233< returns " vim"
10234
10235 Can also be used as a |method|: >
10236 GetText()->trim()
10237
10238trunc({expr}) *trunc()*
10239 Return the largest integral value with magnitude less than or
10240 equal to {expr} as a |Float| (truncate towards zero).
10241 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010242 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010243 Examples: >
10244 echo trunc(1.456)
10245< 1.0 >
10246 echo trunc(-5.456)
10247< -5.0 >
10248 echo trunc(4.0)
10249< 4.0
10250
10251 Can also be used as a |method|: >
10252 Compute()->trunc()
10253<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010254 *type()*
10255type({expr}) The result is a Number representing the type of {expr}.
10256 Instead of using the number directly, it is better to use the
10257 v:t_ variable that has the value:
10258 Number: 0 |v:t_number|
10259 String: 1 |v:t_string|
10260 Funcref: 2 |v:t_func|
10261 List: 3 |v:t_list|
10262 Dictionary: 4 |v:t_dict|
10263 Float: 5 |v:t_float|
10264 Boolean: 6 |v:t_bool| (v:false and v:true)
10265 None: 7 |v:t_none| (v:null and v:none)
10266 Job: 8 |v:t_job|
10267 Channel: 9 |v:t_channel|
10268 Blob: 10 |v:t_blob|
h_east596a9f22023-11-21 21:24:23 +090010269 Class: 12 |v:t_class|
10270 Object: 13 |v:t_object|
Yegappan Lakshmanan2a71b542023-12-14 20:03:03 +010010271 Typealias: 14 |v:t_typealias|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010272 For backward compatibility, this method can be used: >
10273 :if type(myvar) == type(0)
10274 :if type(myvar) == type("")
10275 :if type(myvar) == type(function("tr"))
10276 :if type(myvar) == type([])
10277 :if type(myvar) == type({})
10278 :if type(myvar) == type(0.0)
10279 :if type(myvar) == type(v:false)
10280 :if type(myvar) == type(v:none)
10281< To check if the v:t_ variables exist use this: >
10282 :if exists('v:t_number')
10283
10284< Can also be used as a |method|: >
10285 mylist->type()
10286
10287
10288typename({expr}) *typename()*
10289 Return a string representation of the type of {expr}.
10290 Example: >
10291 echo typename([1, 2, 3])
Kota Kato66bb9ae2023-01-17 18:31:56 +000010292< list<number> ~
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010293
10294
10295undofile({name}) *undofile()*
10296 Return the name of the undo file that would be used for a file
10297 with name {name} when writing. This uses the 'undodir'
10298 option, finding directories that exist. It does not check if
10299 the undo file exists.
10300 {name} is always expanded to the full path, since that is what
10301 is used internally.
10302 If {name} is empty undofile() returns an empty string, since a
10303 buffer without a file name will not write an undo file.
10304 Useful in combination with |:wundo| and |:rundo|.
10305 When compiled without the |+persistent_undo| option this always
10306 returns an empty string.
10307
10308 Can also be used as a |method|: >
10309 GetFilename()->undofile()
10310
Devin J. Pohly5fee1112023-04-23 20:26:59 -050010311undotree([{buf}]) *undotree()*
10312 Return the current state of the undo tree for the current
10313 buffer, or for a specific buffer if {buf} is given. The
10314 result is a dictionary with the following items:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010315 "seq_last" The highest undo sequence number used.
10316 "seq_cur" The sequence number of the current position in
10317 the undo tree. This differs from "seq_last"
10318 when some changes were undone.
10319 "time_cur" Time last used for |:earlier| and related
10320 commands. Use |strftime()| to convert to
10321 something readable.
10322 "save_last" Number of the last file write. Zero when no
10323 write yet.
10324 "save_cur" Number of the current position in the undo
10325 tree.
10326 "synced" Non-zero when the last undo block was synced.
10327 This happens when waiting from input from the
10328 user. See |undo-blocks|.
10329 "entries" A list of dictionaries with information about
10330 undo blocks.
10331
10332 The first item in the "entries" list is the oldest undo item.
10333 Each List item is a |Dictionary| with these items:
10334 "seq" Undo sequence number. Same as what appears in
10335 |:undolist|.
10336 "time" Timestamp when the change happened. Use
10337 |strftime()| to convert to something readable.
10338 "newhead" Only appears in the item that is the last one
10339 that was added. This marks the last change
10340 and where further changes will be added.
10341 "curhead" Only appears in the item that is the last one
10342 that was undone. This marks the current
10343 position in the undo tree, the block that will
10344 be used by a redo command. When nothing was
10345 undone after the last change this item will
10346 not appear anywhere.
10347 "save" Only appears on the last block before a file
10348 write. The number is the write count. The
10349 first write has number 1, the last one the
10350 "save_last" mentioned above.
10351 "alt" Alternate entry. This is again a List of undo
10352 blocks. Each item may again have an "alt"
10353 item.
10354
10355uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
10356 Remove second and succeeding copies of repeated adjacent
10357 {list} items in-place. Returns {list}. If you want a list
10358 to remain unmodified make a copy first: >
10359 :let newlist = uniq(copy(mylist))
10360< The default compare function uses the string representation of
10361 each item. For the use of {func} and {dict} see |sort()|.
10362
Bram Moolenaard592deb2022-06-17 15:42:40 +010010363 Returns zero if {list} is not a |List|.
10364
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010365 Can also be used as a |method|: >
10366 mylist->uniq()
Christian Brabandt67672ef2023-04-24 21:09:54 +010010367<
10368 *utf16idx()*
10369utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010010370 Same as |charidx()| but returns the UTF-16 code unit index of
10371 the byte at {idx} in {string} (after converting it to UTF-16).
Christian Brabandt67672ef2023-04-24 21:09:54 +010010372
10373 When {charidx} is present and TRUE, {idx} is used as the
10374 character index in the String {string} instead of as the byte
10375 index.
Yegappan Lakshmanan95707032023-06-14 13:10:15 +010010376 An {idx} in the middle of a UTF-8 sequence is rounded
10377 downwards to the beginning of that sequence.
Christian Brabandt67672ef2023-04-24 21:09:54 +010010378
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010010379 Returns -1 if the arguments are invalid or if there are less
10380 than {idx} bytes in {string}. If there are exactly {idx} bytes
10381 the length of the string in UTF-16 code units is returned.
10382
Christian Brabandt67672ef2023-04-24 21:09:54 +010010383 See |byteidx()| and |byteidxcomp()| for getting the byte index
10384 from the UTF-16 index and |charidx()| for getting the
10385 character index from the UTF-16 index.
10386 Refer to |string-offset-encoding| for more information.
10387 Examples: >
10388 echo utf16idx('a😊😊', 3) returns 2
10389 echo utf16idx('a😊😊', 7) returns 4
10390 echo utf16idx('a😊😊', 1, 0, 1) returns 2
10391 echo utf16idx('a😊😊', 2, 0, 1) returns 4
10392 echo utf16idx('aą́c', 6) returns 2
10393 echo utf16idx('aą́c', 6, 1) returns 4
10394 echo utf16idx('a😊😊', 9) returns -1
10395<
10396 Can also be used as a |method|: >
10397 GetName()->utf16idx(idx)
10398
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010399
10400values({dict}) *values()*
10401 Return a |List| with all the values of {dict}. The |List| is
10402 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010403 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010404
10405 Can also be used as a |method|: >
10406 mydict->values()
10407
zeertzjq825cf812023-08-17 22:55:25 +020010408virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010409 The result is a Number, which is the screen column of the file
10410 position given with {expr}. That is, the last screen position
10411 occupied by the character at that position, when the screen
10412 would be of unlimited width. When there is a <Tab> at the
10413 position, the returned Number will be the column at the end of
10414 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
10415 set to 8, it returns 8. |conceal| is ignored.
10416 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010417
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010418 For the use of {expr} see |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010419
10420 When 'virtualedit' is used {expr} can be [lnum, col, off],
10421 where "off" is the offset in screen columns from the start of
10422 the character. E.g., a position within a <Tab> or after the
10423 last character. When "off" is omitted zero is used. When
10424 Virtual editing is active in the current mode, a position
10425 beyond the end of the line can be returned. Also see
10426 |'virtualedit'|
10427
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010428 The accepted positions are:
10429 . the cursor position
10430 $ the end of the cursor line (the result is the
10431 number of displayed characters in the cursor line
10432 plus one)
10433 'x position of mark x (if the mark is not set, 0 is
10434 returned)
10435 v In Visual mode: the start of the Visual area (the
10436 cursor is the end). When not in Visual mode
10437 returns the cursor position. Differs from |'<| in
10438 that it's updated right away.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010439
zeertzjq825cf812023-08-17 22:55:25 +020010440 If {list} is present and non-zero then virtcol() returns a
10441 List with the first and last screen position occupied by the
LemonBoy0f7a3e12022-05-26 12:10:37 +010010442 character.
10443
zeertzjq825cf812023-08-17 22:55:25 +020010444 With the optional {winid} argument the values are obtained for
10445 that window instead of the current window.
10446
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010447 Note that only marks in the current file can be used.
10448 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +010010449 " With text "foo^Lbar" and cursor on the "^L":
10450
10451 virtcol(".") " returns 5
10452 virtcol(".", 1) " returns [4, 5]
10453 virtcol("$") " returns 9
10454
10455 " With text " there", with 't at 'h':
10456
10457 virtcol("'t") " returns 6
zeertzjq825cf812023-08-17 22:55:25 +020010458< The first column is 1. 0 or [0, 0] is returned for an error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010459 A more advanced example that echoes the maximum length of
10460 all lines: >
10461 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
10462
10463< Can also be used as a |method|: >
10464 GetPos()->virtcol()
10465
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010466virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
10467 The result is a Number, which is the byte index of the
10468 character in window {winid} at buffer line {lnum} and virtual
10469 column {col}.
10470
zeertzjqb583eda2023-10-14 11:32:28 +020010471 If buffer line {lnum} is an empty line, 0 is returned.
10472
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010473 If {col} is greater than the last virtual column in line
10474 {lnum}, then the byte index of the character at the last
10475 virtual column is returned.
10476
Yegappan Lakshmananb209b862023-08-15 23:01:44 +020010477 For a multi-byte character, the column number of the first
10478 byte in the character is returned.
10479
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010480 The {winid} argument can be the window number or the
10481 |window-ID|. If this is zero, then the current window is used.
10482
10483 Returns -1 if the window {winid} doesn't exist or the buffer
10484 line {lnum} or virtual column {col} is invalid.
10485
10486 See also |screenpos()|, |virtcol()| and |col()|.
10487
10488 Can also be used as a |method|: >
10489 GetWinid()->virtcol2col(lnum, col)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010490
10491visualmode([{expr}]) *visualmode()*
10492 The result is a String, which describes the last Visual mode
10493 used in the current buffer. Initially it returns an empty
10494 string, but once Visual mode has been used, it returns "v",
10495 "V", or "<CTRL-V>" (a single CTRL-V character) for
10496 character-wise, line-wise, or block-wise Visual mode
10497 respectively.
10498 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010499 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010500< This enters the same Visual mode as before. It is also useful
10501 in scripts if you wish to act differently depending on the
10502 Visual mode that was used.
10503 If Visual mode is active, use |mode()| to get the Visual mode
10504 (e.g., in a |:vmap|).
10505 If {expr} is supplied and it evaluates to a non-zero Number or
10506 a non-empty String, then the Visual mode will be cleared and
10507 the old value is returned. See |non-zero-arg|.
10508
10509wildmenumode() *wildmenumode()*
10510 Returns |TRUE| when the wildmenu is active and |FALSE|
10511 otherwise. See 'wildmenu' and 'wildmode'.
10512 This can be used in mappings to handle the 'wildcharm' option
10513 gracefully. (Makes only sense with |mapmode-c| mappings).
10514
10515 For example to make <c-j> work like <down> in wildmode, use: >
10516 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
10517<
10518 (Note, this needs the 'wildcharm' option set appropriately).
10519
10520win_execute({id}, {command} [, {silent}]) *win_execute()*
10521 Like `execute()` but in the context of window {id}.
10522 The window will temporarily be made the current window,
10523 without triggering autocommands or changing directory. When
10524 executing {command} autocommands will be triggered, this may
Bram Moolenaarb7398fe2023-05-14 18:50:25 +010010525 have unexpected side effects. Use `:noautocmd` if needed.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010526 Example: >
10527 call win_execute(winid, 'set syntax=python')
10528< Doing the same with `setwinvar()` would not trigger
10529 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010530 *E994*
10531 Not all commands are allowed in popup windows.
10532 When window {id} does not exist then no error is given and
10533 an empty string is returned.
10534
10535 Can also be used as a |method|, the base is passed as the
10536 second argument: >
10537 GetCommand()->win_execute(winid)
10538
10539win_findbuf({bufnr}) *win_findbuf()*
10540 Returns a |List| with |window-ID|s for windows that contain
10541 buffer {bufnr}. When there is none the list is empty.
10542
10543 Can also be used as a |method|: >
10544 GetBufnr()->win_findbuf()
10545
10546win_getid([{win} [, {tab}]]) *win_getid()*
10547 Get the |window-ID| for the specified window.
10548 When {win} is missing use the current window.
10549 With {win} this is the window number. The top window has
10550 number 1.
10551 Without {tab} use the current tab, otherwise the tab with
10552 number {tab}. The first tab has number one.
10553 Return zero if the window cannot be found.
10554
10555 Can also be used as a |method|: >
10556 GetWinnr()->win_getid()
10557
10558
10559win_gettype([{nr}]) *win_gettype()*
10560 Return the type of the window:
10561 "autocmd" autocommand window. Temporary window
10562 used to execute autocommands.
10563 "command" command-line window |cmdwin|
10564 (empty) normal window
10565 "loclist" |location-list-window|
10566 "popup" popup window |popup|
10567 "preview" preview window |preview-window|
10568 "quickfix" |quickfix-window|
10569 "unknown" window {nr} not found
10570
10571 When {nr} is omitted return the type of the current window.
10572 When {nr} is given return the type of this window by number or
10573 |window-ID|.
10574
10575 Also see the 'buftype' option. When running a terminal in a
10576 popup window then 'buftype' is "terminal" and win_gettype()
10577 returns "popup".
10578
10579 Can also be used as a |method|: >
10580 GetWinid()->win_gettype()
10581<
10582win_gotoid({expr}) *win_gotoid()*
10583 Go to window with ID {expr}. This may also change the current
10584 tabpage.
10585 Return TRUE if successful, FALSE if the window cannot be found.
10586
10587 Can also be used as a |method|: >
10588 GetWinid()->win_gotoid()
10589
10590win_id2tabwin({expr}) *win_id2tabwin()*
10591 Return a list with the tab number and window number of window
10592 with ID {expr}: [tabnr, winnr].
10593 Return [0, 0] if the window cannot be found.
10594
10595 Can also be used as a |method|: >
10596 GetWinid()->win_id2tabwin()
10597
10598win_id2win({expr}) *win_id2win()*
10599 Return the window number of window with ID {expr}.
10600 Return 0 if the window cannot be found in the current tabpage.
10601
10602 Can also be used as a |method|: >
10603 GetWinid()->win_id2win()
10604
Daniel Steinbergee630312022-01-10 13:36:34 +000010605win_move_separator({nr}, {offset}) *win_move_separator()*
10606 Move window {nr}'s vertical separator (i.e., the right border)
10607 by {offset} columns, as if being dragged by the mouse. {nr}
10608 can be a window number or |window-ID|. A positive {offset}
10609 moves right and a negative {offset} moves left. Moving a
10610 window's vertical separator will change the width of the
10611 window and the width of other windows adjacent to the vertical
10612 separator. The magnitude of movement may be smaller than
10613 specified (e.g., as a consequence of maintaining
10614 'winminwidth'). Returns TRUE if the window can be found and
10615 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010616 This will fail for the rightmost window and a full-width
10617 window, since it has no separator on the right.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000010618 Only works for the current tab page. *E1308*
Daniel Steinbergee630312022-01-10 13:36:34 +000010619
10620 Can also be used as a |method|: >
10621 GetWinnr()->win_move_separator(offset)
10622
10623win_move_statusline({nr}, {offset}) *win_move_statusline()*
10624 Move window {nr}'s status line (i.e., the bottom border) by
10625 {offset} rows, as if being dragged by the mouse. {nr} can be a
10626 window number or |window-ID|. A positive {offset} moves down
10627 and a negative {offset} moves up. Moving a window's status
10628 line will change the height of the window and the height of
10629 other windows adjacent to the status line. The magnitude of
10630 movement may be smaller than specified (e.g., as a consequence
10631 of maintaining 'winminheight'). Returns TRUE if the window can
10632 be found and FALSE otherwise.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000010633 Only works for the current tab page.
Daniel Steinbergee630312022-01-10 13:36:34 +000010634
10635 Can also be used as a |method|: >
10636 GetWinnr()->win_move_statusline(offset)
10637
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010638win_screenpos({nr}) *win_screenpos()*
10639 Return the screen position of window {nr} as a list with two
10640 numbers: [row, col]. The first window always has position
10641 [1, 1], unless there is a tabline, then it is [2, 1].
10642 {nr} can be the window number or the |window-ID|. Use zero
10643 for the current window.
10644 Returns [0, 0] if the window cannot be found in the current
10645 tabpage.
10646
10647 Can also be used as a |method|: >
10648 GetWinid()->win_screenpos()
10649<
10650win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
10651 Move the window {nr} to a new split of the window {target}.
10652 This is similar to moving to {target}, creating a new window
10653 using |:split| but having the same contents as window {nr}, and
10654 then closing {nr}.
10655
10656 Both {nr} and {target} can be window numbers or |window-ID|s.
10657 Both must be in the current tab page.
10658
10659 Returns zero for success, non-zero for failure.
10660
10661 {options} is a |Dictionary| with the following optional entries:
10662 "vertical" When TRUE, the split is created vertically,
10663 like with |:vsplit|.
10664 "rightbelow" When TRUE, the split is made below or to the
10665 right (if vertical). When FALSE, it is done
10666 above or to the left (if vertical). When not
10667 present, the values of 'splitbelow' and
10668 'splitright' are used.
10669
10670 Can also be used as a |method|: >
10671 GetWinid()->win_splitmove(target)
10672<
10673
10674 *winbufnr()*
10675winbufnr({nr}) The result is a Number, which is the number of the buffer
10676 associated with window {nr}. {nr} can be the window number or
10677 the |window-ID|.
10678 When {nr} is zero, the number of the buffer in the current
10679 window is returned.
10680 When window {nr} doesn't exist, -1 is returned.
10681 Example: >
10682 :echo "The file in the current window is " . bufname(winbufnr(0))
10683<
10684 Can also be used as a |method|: >
10685 FindWindow()->winbufnr()->bufname()
10686<
10687 *wincol()*
10688wincol() The result is a Number, which is the virtual column of the
10689 cursor in the window. This is counting screen cells from the
10690 left side of the window. The leftmost column is one.
10691
10692 *windowsversion()*
10693windowsversion()
10694 The result is a String. For MS-Windows it indicates the OS
10695 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
10696 Windows XP is "5.1". For non-MS-Windows systems the result is
10697 an empty string.
10698
10699winheight({nr}) *winheight()*
10700 The result is a Number, which is the height of window {nr}.
10701 {nr} can be the window number or the |window-ID|.
10702 When {nr} is zero, the height of the current window is
10703 returned. When window {nr} doesn't exist, -1 is returned.
10704 An existing window always has a height of zero or more.
10705 This excludes any window toolbar line.
10706 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010707 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010708
10709< Can also be used as a |method|: >
10710 GetWinid()->winheight()
10711<
10712winlayout([{tabnr}]) *winlayout()*
10713 The result is a nested List containing the layout of windows
10714 in a tabpage.
10715
10716 Without {tabnr} use the current tabpage, otherwise the tabpage
10717 with number {tabnr}. If the tabpage {tabnr} is not found,
10718 returns an empty list.
10719
10720 For a leaf window, it returns:
10721 ['leaf', {winid}]
10722 For horizontally split windows, which form a column, it
10723 returns:
10724 ['col', [{nested list of windows}]]
10725 For vertically split windows, which form a row, it returns:
10726 ['row', [{nested list of windows}]]
10727
10728 Example: >
10729 " Only one window in the tab page
10730 :echo winlayout()
10731 ['leaf', 1000]
10732 " Two horizontally split windows
10733 :echo winlayout()
10734 ['col', [['leaf', 1000], ['leaf', 1001]]]
10735 " The second tab page, with three horizontally split
10736 " windows, with two vertically split windows in the
10737 " middle window
10738 :echo winlayout(2)
10739 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
10740 ['leaf', 1001]]], ['leaf', 1000]]]
10741<
10742 Can also be used as a |method|: >
10743 GetTabnr()->winlayout()
10744<
10745 *winline()*
10746winline() The result is a Number, which is the screen line of the cursor
10747 in the window. This is counting screen lines from the top of
10748 the window. The first line is one.
10749 If the cursor was moved the view on the file will be updated
10750 first, this may cause a scroll.
10751
10752 *winnr()*
10753winnr([{arg}]) The result is a Number, which is the number of the current
10754 window. The top window has number 1.
10755 Returns zero for a popup window.
10756
10757 The optional argument {arg} supports the following values:
10758 $ the number of the last window (the window
10759 count).
10760 # the number of the last accessed window (where
10761 |CTRL-W_p| goes to). If there is no previous
10762 window or it is in another tab page 0 is
10763 returned.
10764 {N}j the number of the Nth window below the
10765 current window (where |CTRL-W_j| goes to).
10766 {N}k the number of the Nth window above the current
10767 window (where |CTRL-W_k| goes to).
10768 {N}h the number of the Nth window left of the
10769 current window (where |CTRL-W_h| goes to).
10770 {N}l the number of the Nth window right of the
10771 current window (where |CTRL-W_l| goes to).
10772 The number can be used with |CTRL-W_w| and ":wincmd w"
10773 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010010774 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010775 Also see |tabpagewinnr()| and |win_getid()|.
10776 Examples: >
10777 let window_count = winnr('$')
10778 let prev_window = winnr('#')
10779 let wnum = winnr('3k')
10780
10781< Can also be used as a |method|: >
10782 GetWinval()->winnr()
10783<
10784 *winrestcmd()*
10785winrestcmd() Returns a sequence of |:resize| commands that should restore
10786 the current window sizes. Only works properly when no windows
10787 are opened or closed and the current window and tab page is
10788 unchanged.
10789 Example: >
10790 :let cmd = winrestcmd()
10791 :call MessWithWindowSizes()
10792 :exe cmd
10793<
10794 *winrestview()*
10795winrestview({dict})
10796 Uses the |Dictionary| returned by |winsaveview()| to restore
10797 the view of the current window.
10798 Note: The {dict} does not have to contain all values, that are
10799 returned by |winsaveview()|. If values are missing, those
10800 settings won't be restored. So you can use: >
10801 :call winrestview({'curswant': 4})
10802<
10803 This will only set the curswant value (the column the cursor
10804 wants to move on vertical movements) of the cursor to column 5
10805 (yes, that is 5), while all other settings will remain the
10806 same. This is useful, if you set the cursor position manually.
10807
10808 If you have changed the values the result is unpredictable.
10809 If the window size changed the result won't be the same.
10810
10811 Can also be used as a |method|: >
10812 GetView()->winrestview()
10813<
10814 *winsaveview()*
10815winsaveview() Returns a |Dictionary| that contains information to restore
10816 the view of the current window. Use |winrestview()| to
10817 restore the view.
10818 This is useful if you have a mapping that jumps around in the
10819 buffer and you want to go back to the original view.
10820 This does not save fold information. Use the 'foldenable'
10821 option to temporarily switch off folding, so that folds are
10822 not opened when moving around. This may have side effects.
10823 The return value includes:
10824 lnum cursor line number
10825 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000010826 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010827 returns)
10828 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000010829 curswant column for vertical movement (Note:
10830 the first column is zero, as opposed
10831 to what |getcurpos()| returns). After
10832 |$| command it will be a very large
10833 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010834 topline first line in the window
10835 topfill filler lines, only in diff mode
10836 leftcol first column displayed; only used when
10837 'wrap' is off
10838 skipcol columns skipped
10839 Note that no option values are saved.
10840
10841
10842winwidth({nr}) *winwidth()*
10843 The result is a Number, which is the width of window {nr}.
10844 {nr} can be the window number or the |window-ID|.
10845 When {nr} is zero, the width of the current window is
10846 returned. When window {nr} doesn't exist, -1 is returned.
10847 An existing window always has a width of zero or more.
10848 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010849 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010850 :if winwidth(0) <= 50
10851 : 50 wincmd |
10852 :endif
10853< For getting the terminal or screen size, see the 'columns'
10854 option.
10855
10856 Can also be used as a |method|: >
10857 GetWinid()->winwidth()
10858
10859
10860wordcount() *wordcount()*
10861 The result is a dictionary of byte/chars/word statistics for
10862 the current buffer. This is the same info as provided by
10863 |g_CTRL-G|
10864 The return value includes:
10865 bytes Number of bytes in the buffer
10866 chars Number of chars in the buffer
10867 words Number of words in the buffer
10868 cursor_bytes Number of bytes before cursor position
10869 (not in Visual mode)
10870 cursor_chars Number of chars before cursor position
10871 (not in Visual mode)
10872 cursor_words Number of words before cursor position
10873 (not in Visual mode)
10874 visual_bytes Number of bytes visually selected
10875 (only in Visual mode)
10876 visual_chars Number of chars visually selected
10877 (only in Visual mode)
10878 visual_words Number of words visually selected
10879 (only in Visual mode)
10880
10881
10882 *writefile()*
10883writefile({object}, {fname} [, {flags}])
10884 When {object} is a |List| write it to file {fname}. Each list
10885 item is separated with a NL. Each list item must be a String
10886 or Number.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010887 All NL characters are replaced with a NUL character.
10888 Inserting CR characters needs to be done before passing {list}
10889 to writefile().
Bram Moolenaar806a2732022-09-04 15:40:36 +010010890
10891 When {object} is a |Blob| write the bytes to file {fname}
10892 unmodified, also when binary mode is not specified.
10893
10894 {flags} must be a String. These characters are recognized:
10895
10896 'b' Binary mode is used: There will not be a NL after the
10897 last list item. An empty item at the end does cause the
10898 last line in the file to end in a NL.
10899
10900 'a' Append mode is used, lines are appended to the file: >
10901 :call writefile(["foo"], "event.log", "a")
10902 :call writefile(["bar"], "event.log", "a")
10903<
10904 'D' Delete the file when the current function ends. This
10905 works like: >
Bram Moolenaar938ae282023-02-20 20:44:55 +000010906 :defer delete({fname})
Bram Moolenaar806a2732022-09-04 15:40:36 +010010907< Fails when not in a function. Also see |:defer|.
10908
10909 's' fsync() is called after writing the file. This flushes
10910 the file to disk, if possible. This takes more time but
10911 avoids losing the file if the system crashes.
10912
10913 'S' fsync() is not called, even when 'fsync' is set.
10914
10915 When {flags} does not contain "S" or "s" then fsync() is
10916 called if the 'fsync' option is set.
10917
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010918 An existing file is overwritten, if possible.
Bram Moolenaar806a2732022-09-04 15:40:36 +010010919
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010920 When the write fails -1 is returned, otherwise 0. There is an
10921 error message if the file can't be created or when writing
10922 fails.
Bram Moolenaar806a2732022-09-04 15:40:36 +010010923
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010924 Also see |readfile()|.
10925 To copy a file byte for byte: >
10926 :let fl = readfile("foo", "b")
10927 :call writefile(fl, "foocopy", "b")
10928
10929< Can also be used as a |method|: >
10930 GetText()->writefile("thefile")
10931
10932
10933xor({expr}, {expr}) *xor()*
10934 Bitwise XOR on the two arguments. The arguments are converted
10935 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010936 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010937 Example: >
10938 :let bits = xor(bits, 0x80)
10939<
10940 Can also be used as a |method|: >
10941 :let bits = bits->xor(0x80)
10942<
10943
10944==============================================================================
109453. Feature list *feature-list*
10946
10947There are three types of features:
109481. Features that are only supported when they have been enabled when Vim
10949 was compiled |+feature-list|. Example: >
10950 :if has("cindent")
10951< *gui_running*
109522. Features that are only supported when certain conditions have been met.
10953 Example: >
10954 :if has("gui_running")
10955< *has-patch*
109563. Beyond a certain version or at a certain version and including a specific
10957 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
10958 later, or it is version 7.4 and patch 248 was included. Example: >
10959 :if has("patch-7.4.248")
10960< Note that it's possible for patch 248 to be omitted even though 249 is
10961 included. Only happens when cherry-picking patches.
10962 Note that this form only works for patch 7.4.237 and later, before that
10963 you need to check for the patch and the v:version. Example (checking
10964 version 6.2.148 or later): >
10965 :if v:version > 602 || (v:version == 602 && has("patch148"))
10966
10967Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
10968use: `if exists('+shellslash')`
10969
10970
10971acl Compiled with |ACL| support.
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010010972all_builtin_terms Compiled with all builtin terminals enabled. (always
10973 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010974amiga Amiga version of Vim.
10975arabic Compiled with Arabic support |Arabic|.
10976arp Compiled with ARP support (Amiga).
10977autocmd Compiled with autocommand support. (always true)
10978autochdir Compiled with support for 'autochdir'
10979autoservername Automatically enable |clientserver|
10980balloon_eval Compiled with |balloon-eval| support.
10981balloon_multiline GUI supports multiline balloons.
10982beos BeOS version of Vim.
10983browse Compiled with |:browse| support, and browse() will
10984 work.
10985browsefilter Compiled with support for |browsefilter|.
10986bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010010987builtin_terms Compiled with some builtin terminals. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010988byte_offset Compiled with support for 'o' in 'statusline'
10989channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010990cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010991clientserver Compiled with remote invocation support |clientserver|.
10992clipboard Compiled with 'clipboard' support.
10993clipboard_working Compiled with 'clipboard' support and it can be used.
10994cmdline_compl Compiled with |cmdline-completion| support.
10995cmdline_hist Compiled with |cmdline-history| support.
10996cmdline_info Compiled with 'showcmd' and 'ruler' support.
10997comments Compiled with |'comments'| support.
10998compatible Compiled to be very Vi compatible.
10999conpty Platform where |ConPTY| can be used.
11000cryptv Compiled with encryption support |encryption|.
11001cscope Compiled with |cscope| support.
11002cursorbind Compiled with |'cursorbind'| (always true)
11003debug Compiled with "DEBUG" defined.
11004dialog_con Compiled with console dialog support.
11005dialog_gui Compiled with GUI dialog support.
11006diff Compiled with |vimdiff| and 'diff' support.
11007digraphs Compiled with support for digraphs.
11008directx Compiled with support for DirectX and 'renderoptions'.
11009dnd Compiled with support for the "~ register |quote_~|.
11010drop_file Compiled with |drop_file| support.
11011ebcdic Compiled on a machine with ebcdic character set.
11012emacs_tags Compiled with support for Emacs tags.
11013eval Compiled with expression evaluation support. Always
11014 true, of course!
11015ex_extra |+ex_extra| (always true)
11016extra_search Compiled with support for |'incsearch'| and
11017 |'hlsearch'|
11018farsi Support for Farsi was removed |farsi|.
Bram Moolenaarf80f40a2022-08-25 16:02:23 +010011019file_in_path Compiled with support for |gf| and |<cfile>| (always
11020 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011021filterpipe When 'shelltemp' is off pipes are used for shell
11022 read/write/filter commands
11023find_in_path Compiled with support for include file searches
11024 |+find_in_path|.
11025float Compiled with support for |Float|.
11026fname_case Case in file names matters (for Amiga and MS-Windows
11027 this is not present).
11028folding Compiled with |folding| support.
11029footer Compiled with GUI footer support. |gui-footer|
11030fork Compiled to use fork()/exec() instead of system().
11031gettext Compiled with message translation |multi-lang|
11032gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010011033gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011034gui_gnome Compiled with Gnome support (gui_gtk is also defined).
11035gui_gtk Compiled with GTK+ GUI (any version).
11036gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
11037gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
11038gui_haiku Compiled with Haiku GUI.
11039gui_mac Compiled with Macintosh GUI.
11040gui_motif Compiled with Motif GUI.
11041gui_photon Compiled with Photon GUI.
11042gui_running Vim is running in the GUI, or it will start soon.
11043gui_win32 Compiled with MS-Windows Win32 GUI.
11044gui_win32s idem, and Win32s system being used (Windows 3.1)
11045haiku Haiku version of Vim.
11046hangul_input Compiled with Hangul input support. |hangul|
11047hpux HP-UX version of Vim.
11048iconv Can use iconv() for conversion.
11049insert_expand Compiled with support for CTRL-X expansion commands in
11050 Insert mode. (always true)
11051job Compiled with support for |channel| and |job|
11052ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011053jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011054keymap Compiled with 'keymap' support.
11055lambda Compiled with |lambda| support.
11056langmap Compiled with 'langmap' support.
11057libcall Compiled with |libcall()| support.
11058linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
11059 'breakindent' support.
11060linux Linux version of Vim.
11061lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011062 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011063listcmds Compiled with commands for the buffer list |:files|
11064 and the argument list |arglist|.
11065localmap Compiled with local mappings and abbr. |:map-local|
11066lua Compiled with Lua interface |Lua|.
11067mac Any Macintosh version of Vim cf. osx
11068macunix Synonym for osxdarwin
11069menu Compiled with support for |:menu|.
11070mksession Compiled with support for |:mksession|.
11071modify_fname Compiled with file name modifiers. |filename-modifiers|
11072 (always true)
11073mouse Compiled with support for mouse.
11074mouse_dec Compiled with support for Dec terminal mouse.
11075mouse_gpm Compiled with support for gpm (Linux console mouse)
11076mouse_gpm_enabled GPM mouse is working
11077mouse_netterm Compiled with support for netterm mouse.
11078mouse_pterm Compiled with support for qnx pterm mouse.
11079mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
11080mouse_sgr Compiled with support for sgr mouse.
11081mouse_urxvt Compiled with support for urxvt mouse.
11082mouse_xterm Compiled with support for xterm mouse.
11083mouseshape Compiled with support for 'mouseshape'.
11084multi_byte Compiled with support for 'encoding' (always true)
11085multi_byte_encoding 'encoding' is set to a multibyte encoding.
11086multi_byte_ime Compiled with support for IME input method.
11087multi_lang Compiled with support for multiple languages.
11088mzscheme Compiled with MzScheme interface |mzscheme|.
11089nanotime Compiled with sub-second time stamp checks.
11090netbeans_enabled Compiled with support for |netbeans| and connected.
11091netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011092num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011093ole Compiled with OLE automation support for Win32.
11094osx Compiled for macOS cf. mac
11095osxdarwin Compiled for macOS, with |mac-darwin-feature|
11096packages Compiled with |packages| support.
11097path_extra Compiled with up/downwards search in 'path' and 'tags'
11098perl Compiled with Perl interface.
11099persistent_undo Compiled with support for persistent undo history.
11100postscript Compiled with PostScript file printing.
11101printer Compiled with |:hardcopy| support.
11102profile Compiled with |:profile| support.
Bram Moolenaar71badf92023-04-22 22:40:14 +010011103prof_nsec Profile results are in nanoseconds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011104python Python 2.x interface available. |has-python|
11105python_compiled Compiled with Python 2.x interface. |has-python|
11106python_dynamic Python 2.x interface is dynamically loaded. |has-python|
11107python3 Python 3.x interface available. |has-python|
11108python3_compiled Compiled with Python 3.x interface. |has-python|
11109python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Yee Cheng Chinc13b3d12023-08-20 21:18:38 +020011110python3_stable Python 3.x interface is using Python Stable ABI. |has-python|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011111pythonx Python 2.x and/or 3.x interface available. |python_x|
11112qnx QNX version of Vim.
11113quickfix Compiled with |quickfix| support.
11114reltime Compiled with |reltime()| support.
11115rightleft Compiled with 'rightleft' support.
11116ruby Compiled with Ruby interface |ruby|.
11117scrollbind Compiled with 'scrollbind' support. (always true)
11118showcmd Compiled with 'showcmd' support.
11119signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011120smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011121sodium Compiled with libsodium for better crypt support
11122sound Compiled with sound support, e.g. `sound_playevent()`
11123spell Compiled with spell checking support |spell|.
11124startuptime Compiled with |--startuptime| support.
11125statusline Compiled with support for 'statusline', 'rulerformat'
11126 and special formats of 'titlestring' and 'iconstring'.
11127sun SunOS version of Vim.
11128sun_workshop Support for Sun |workshop| has been removed.
11129syntax Compiled with syntax highlighting support |syntax|.
11130syntax_items There are active syntax highlighting items for the
11131 current buffer.
11132system Compiled to use system() instead of fork()/exec().
11133tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011134 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011135tag_old_static Support for old static tags was removed, see
11136 |tag-old-static|.
11137tcl Compiled with Tcl interface.
11138termguicolors Compiled with true color in terminal support.
11139terminal Compiled with |terminal| support.
11140terminfo Compiled with terminfo instead of termcap.
11141termresponse Compiled with support for |t_RV| and |v:termresponse|.
11142textobjects Compiled with support for |text-objects|.
11143textprop Compiled with support for |text-properties|.
11144tgetent Compiled with tgetent support, able to use a termcap
11145 or terminfo file.
11146timers Compiled with |timer_start()| support.
11147title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010011148 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011149toolbar Compiled with support for |gui-toolbar|.
11150ttyin input is a terminal (tty)
11151ttyout output is a terminal (tty)
11152unix Unix version of Vim. *+unix*
11153unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
11154user_commands User-defined commands. (always true)
11155vartabs Compiled with variable tabstop support |'vartabstop'|.
11156vcon Win32: Virtual console support is working, can use
11157 'termguicolors'. Also see |+vtp|.
11158vertsplit Compiled with vertically split windows |:vsplit|.
11159 (always true)
11160vim_starting True while initial source'ing takes place. |startup|
11161 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000011162vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011163viminfo Compiled with viminfo support.
11164vimscript-1 Compiled Vim script version 1 support
11165vimscript-2 Compiled Vim script version 2 support
11166vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010011167vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011168virtualedit Compiled with 'virtualedit' option. (always true)
11169visual Compiled with Visual mode. (always true)
11170visualextra Compiled with extra Visual mode commands. (always
11171 true) |blockwise-operators|.
11172vms VMS version of Vim.
11173vreplace Compiled with |gR| and |gr| commands. (always true)
11174vtp Compiled for vcon support |+vtp| (check vcon to find
11175 out if it works in the current console).
11176wildignore Compiled with 'wildignore' option.
11177wildmenu Compiled with 'wildmenu' option.
11178win16 old version for MS-Windows 3.1 (always false)
11179win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
11180 64 bits)
11181win32unix Win32 version of Vim, using Unix files (Cygwin)
11182win64 Win64 version of Vim (MS-Windows 64 bit).
11183win95 Win32 version for MS-Windows 95/98/ME (always false)
11184winaltkeys Compiled with 'winaltkeys' option.
11185windows Compiled with support for more than one window.
11186 (always true)
11187writebackup Compiled with 'writebackup' default on.
Christian Brabandte085dfd2023-09-30 12:49:18 +020011188xattr Compiled with extended attributes support |xattr|
11189 (currently only supported on Linux).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011190xfontset Compiled with X fontset support |xfontset|.
11191xim Compiled with X input method support |xim|.
11192xpm Compiled with pixmap support.
11193xpm_w32 Compiled with pixmap support for Win32. (Only for
11194 backward compatibility. Use "xpm" instead.)
11195xsmp Compiled with X session management support.
11196xsmp_interact Compiled with interactive X session management support.
11197xterm_clipboard Compiled with support for xterm clipboard.
11198xterm_save Compiled with support for saving and restoring the
11199 xterm screen.
11200x11 Compiled with X11 support.
11201
11202
11203==============================================================================
112044. Matching a pattern in a String *string-match*
11205
11206This is common between several functions. A regexp pattern as explained at
11207|pattern| is normally used to find a match in the buffer lines. When a
11208pattern is used to find a match in a String, almost everything works in the
11209same way. The difference is that a String is handled like it is one line.
11210When it contains a "\n" character, this is not seen as a line break for the
11211pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
11212>
11213 :let a = "aaaa\nxxxx"
11214 :echo matchstr(a, "..\n..")
11215 aa
11216 xx
11217 :echo matchstr(a, "a.x")
11218 a
11219 x
11220
11221Don't forget that "^" will only match at the first character of the String and
11222"$" at the last character of the string. They don't match after or before a
11223"\n".
11224
11225 vim:tw=78:ts=8:noet:ft=help:norl: