blob: 9f91f47d4212eeddbf328dccfd678f27311c7599 [file] [log] [blame]
glepnirbcd59952025-04-24 21:48:35 +02001*builtin.txt* For Vim version 9.1. Last change: 2025 Apr 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}
erraelf0837ba2024-06-24 12:27:01 -070031appendbufline({buf}, {lnum}, {text})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000032 Number append {text} below line {lnum}
erraelf0837ba2024-06-24 12:27:01 -070033 in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000034argc([{winid}]) Number number of files in the argument list
35argidx() Number current index in the argument list
36arglistid([{winnr} [, {tabnr}]]) Number argument list id
37argv({nr} [, {winid}]) String {nr} entry of the argument list
38argv([-1, {winid}]) List the argument list
39asin({expr}) Float arc sine of {expr}
40assert_beeps({cmd}) Number assert {cmd} causes a beep
41assert_equal({exp}, {act} [, {msg}])
42 Number assert {exp} is equal to {act}
43assert_equalfile({fname-one}, {fname-two} [, {msg}])
44 Number assert file contents are equal
45assert_exception({error} [, {msg}])
46 Number assert {error} is in v:exception
47assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])
48 Number assert {cmd} fails
49assert_false({actual} [, {msg}])
50 Number assert {actual} is false
51assert_inrange({lower}, {upper}, {actual} [, {msg}])
52 Number assert {actual} is inside the range
53assert_match({pat}, {text} [, {msg}])
54 Number assert {pat} matches {text}
55assert_nobeep({cmd}) Number assert {cmd} does not cause a beep
56assert_notequal({exp}, {act} [, {msg}])
57 Number assert {exp} is not equal {act}
58assert_notmatch({pat}, {text} [, {msg}])
59 Number assert {pat} not matches {text}
60assert_report({msg}) Number report a test failure
61assert_true({actual} [, {msg}]) Number assert {actual} is true
62atan({expr}) Float arc tangent of {expr}
63atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +010064autocmd_add({acmds}) Bool add a list of autocmds and groups
65autocmd_delete({acmds}) Bool delete a list of autocmds and groups
66autocmd_get([{opts}]) List return a list of autocmds
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000067balloon_gettext() String current text in the balloon
68balloon_show({expr}) none show {expr} inside the balloon
69balloon_split({msg}) List split {msg} as used for a balloon
h-easte80f3452025-01-02 10:40:29 +010070base64_decode({string}) Blob base64 decode {string} characters
71base64_encode({blob}) String base64 encode the bytes in {blob}
Christ van Willegence0ef912024-06-20 23:41:59 +020072bindtextdomain({package}, {path})
Christ van Willegen8252ef12024-07-11 21:36:21 +020073 Bool bind text domain to specified path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000074blob2list({blob}) List convert {blob} into a list of numbers
Yegappan Lakshmanan166b1752025-01-17 11:48:12 +010075blob2str({blob} [, {options}]) List convert {blob} into a list of strings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000076browse({save}, {title}, {initdir}, {default})
77 String put up a file requester
78browsedir({title}, {initdir}) String put up a directory requester
79bufadd({name}) Number add a buffer to the buffer list
80bufexists({buf}) Number |TRUE| if buffer {buf} exists
81buflisted({buf}) Number |TRUE| if buffer {buf} is listed
82bufload({buf}) Number load buffer {buf} if not loaded yet
83bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
84bufname([{buf}]) String Name of the buffer {buf}
85bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
86bufwinid({buf}) Number window ID of buffer {buf}
87bufwinnr({buf}) Number window number of buffer {buf}
88byte2line({byte}) Number line number at byte count {byte}
Christian Brabandt67672ef2023-04-24 21:09:54 +010089byteidx({expr}, {nr} [, {utf16}])
90 Number byte index of {nr}'th char in {expr}
91byteidxcomp({expr}, {nr} [, {utf16}])
92 Number byte index of {nr}'th char in {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000093call({func}, {arglist} [, {dict}])
94 any call {func} with arguments {arglist}
95ceil({expr}) Float round {expr} up
96ch_canread({handle}) Number check if there is something to read
97ch_close({handle}) none close {handle}
98ch_close_in({handle}) none close in part of {handle}
99ch_evalexpr({handle}, {expr} [, {options}])
100 any evaluate {expr} on JSON {handle}
101ch_evalraw({handle}, {string} [, {options}])
102 any evaluate {string} on raw {handle}
103ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
104ch_getjob({channel}) Job get the Job of {channel}
105ch_info({handle}) String info about channel {handle}
106ch_log({msg} [, {handle}]) none write {msg} in the channel log file
107ch_logfile({fname} [, {mode}]) none start logging channel activity
108ch_open({address} [, {options}])
109 Channel open a channel to {address}
110ch_read({handle} [, {options}]) String read from {handle}
111ch_readblob({handle} [, {options}])
112 Blob read Blob from {handle}
113ch_readraw({handle} [, {options}])
114 String read raw from {handle}
115ch_sendexpr({handle}, {expr} [, {options}])
116 any send {expr} over JSON {handle}
117ch_sendraw({handle}, {expr} [, {options}])
118 any send {expr} over raw {handle}
119ch_setoptions({handle}, {options})
120 none set options for {handle}
121ch_status({handle} [, {options}])
122 String status of channel {handle}
123changenr() Number current change number
124char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
125charclass({string}) Number character class of {string}
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000126charcol({expr} [, {winid}]) Number column number of cursor or mark
Christian Brabandt67672ef2023-04-24 21:09:54 +0100127charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000128 Number char index of byte {idx} in {string}
129chdir({dir}) String change current working directory
130cindent({lnum}) Number C indent for line {lnum}
131clearmatches([{win}]) none clear all matches
Girish Palya92f68e22025-04-21 11:12:41 +0200132cmdcomplete_info() Dict get current cmdline completion
133 information
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000134col({expr} [, {winid}]) Number column byte index of cursor or mark
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000135complete({startcol}, {matches}) none set Insert mode completion
136complete_add({expr}) Number add completion match
137complete_check() Number check for key typed during completion
138complete_info([{what}]) Dict get current completion information
glepnirbcd59952025-04-24 21:48:35 +0200139complete_match([{lnum}, {col}]) List get completion column and trigger text
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000140confirm({msg} [, {choices} [, {default} [, {type}]]])
141 Number number of choice picked by user
142copy({expr}) any make a shallow copy of {expr}
143cos({expr}) Float cosine of {expr}
144cosh({expr}) Float hyperbolic cosine of {expr}
145count({comp}, {expr} [, {ic} [, {start}]])
146 Number count how many {expr} are in {comp}
147cscope_connection([{num}, {dbpath} [, {prepend}]])
148 Number checks existence of cscope connection
149cursor({lnum}, {col} [, {off}])
150 Number move cursor to {lnum}, {col}, {off}
151cursor({list}) Number move cursor to position in {list}
152debugbreak({pid}) Number interrupt process being debugged
153deepcopy({expr} [, {noref}]) any make a full copy of {expr}
154delete({fname} [, {flags}]) Number delete the file or directory {fname}
155deletebufline({buf}, {first} [, {last}])
156 Number delete lines from buffer {buf}
157did_filetype() Number |TRUE| if FileType autocmd event used
Yegappan Lakshmananfa378352024-02-01 22:05:27 +0100158diff({fromlist}, {tolist} [, {options}])
159 List diff two Lists of strings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000160diff_filler({lnum}) Number diff filler lines about {lnum}
161diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
162digraph_get({chars}) String get the |digraph| of {chars}
163digraph_getlist([{listall}]) List get all |digraph|s
Christian Brabandtfbc37f12024-06-18 20:50:58 +0200164digraph_set({chars}, {digraph}) Bool register |digraph|
165digraph_setlist({digraphlist}) Bool register multiple |digraph|s
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000166echoraw({expr}) none output {expr} as-is
167empty({expr}) Number |TRUE| if {expr} is empty
168environ() Dict return environment variables
Sean Dewarb0efa492023-07-08 10:35:19 +0100169err_teapot([{expr}]) none give E418, or E503 if {expr} is |TRUE|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000170escape({string}, {chars}) String escape {chars} in {string} with '\'
171eval({string}) any evaluate {string} into its value
172eventhandler() Number |TRUE| if inside an event handler
173executable({expr}) Number 1 if executable {expr} exists
174execute({command}) String execute {command} and get the output
175exepath({expr}) String full path of the command {expr}
176exists({expr}) Number |TRUE| if {expr} exists
177exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
178exp({expr}) Float exponential of {expr}
179expand({expr} [, {nosuf} [, {list}]])
180 any expand special keywords in {expr}
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +0100181expandcmd({string} [, {options}])
182 String expand {string} like with `:edit`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000183extend({expr1}, {expr2} [, {expr3}])
184 List/Dict insert items of {expr2} into {expr1}
185extendnew({expr1}, {expr2} [, {expr3}])
186 List/Dict like |extend()| but creates a new
187 List or Dictionary
188feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Shougo Matsushita60c87432024-06-03 22:59:27 +0200189filecopy({from}, {to}) Number |TRUE| if copying file {from} to {to}
190 worked
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000191filereadable({file}) Number |TRUE| if {file} is a readable file
192filewritable({file}) Number |TRUE| if {file} is a writable file
193filter({expr1}, {expr2}) List/Dict/Blob/String
194 remove items from {expr1} where
195 {expr2} is 0
196finddir({name} [, {path} [, {count}]])
197 String find directory {name} in {path}
198findfile({name} [, {path} [, {count}]])
199 String find file {name} in {path}
200flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
201flattennew({list} [, {maxdepth}])
202 List flatten a copy of {list}
203float2nr({expr}) Number convert Float {expr} to a Number
204floor({expr}) Float round {expr} down
205fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
206fnameescape({fname}) String escape special characters in {fname}
207fnamemodify({fname}, {mods}) String modify file name
208foldclosed({lnum}) Number first line of fold at {lnum} if closed
209foldclosedend({lnum}) Number last line of fold at {lnum} if closed
210foldlevel({lnum}) Number fold level at {lnum}
211foldtext() String line displayed for closed fold
212foldtextresult({lnum}) String text for closed fold at {lnum}
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100213foreach({expr1}, {expr2}) List/Tuple/Dict/Blob/String
Ernie Raele79e2072024-01-13 11:47:33 +0100214 for each item in {expr1} call {expr2}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000215foreground() Number bring the Vim window to the foreground
Bram Moolenaaraa534142022-09-15 21:46:02 +0100216fullcommand({name} [, {vim9}]) String get full command from {name}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000217funcref({name} [, {arglist}] [, {dict}])
218 Funcref reference to function {name}
219function({name} [, {arglist}] [, {dict}])
220 Funcref named reference to function {name}
221garbagecollect([{atexit}]) none free memory, breaking cyclic references
222get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
223get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
224get({func}, {what}) any get property of funcref/partial {func}
225getbufinfo([{buf}]) List information about buffers
226getbufline({buf}, {lnum} [, {end}])
227 List lines {lnum} to {end} of buffer {buf}
Bram Moolenaarce30ccc2022-11-21 19:57:04 +0000228getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000229getbufvar({buf}, {varname} [, {def}])
230 any variable {varname} in buffer {buf}
mikoto20001083cae2024-11-11 21:24:14 +0100231getcellpixels() List get character cell pixel size
Kota Kato66bb9ae2023-01-17 18:31:56 +0000232getcellwidths() List get character cell width overrides
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000233getchangelist([{buf}]) List list of change list items
zeertzjqe0a2ab32025-02-02 09:14:35 +0100234getchar([{expr} [, {opts}]]) Number or String
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000235 get one character from the user
236getcharmod() Number modifiers for the last typed character
237getcharpos({expr}) List position of cursor, mark, etc.
238getcharsearch() Dict last character search
zeertzjqe0a2ab32025-02-02 09:14:35 +0100239getcharstr([{expr} [, {opts}]]) String get one character from the user
Ruslan Russkikh0407d622024-10-08 22:21:05 +0200240getcmdcomplpat() String return the completion pattern of the
241 current command-line completion
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100242getcmdcompltype() String return the type of the current
243 command-line completion
Shougo Matsushita69084282024-09-23 20:34:47 +0200244getcmdline() String return the current command-line input
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000245getcmdpos() Number return cursor position in command-line
Shougo Matsushita69084282024-09-23 20:34:47 +0200246getcmdprompt() String return the current command-line prompt
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100247getcmdscreenpos() Number return cursor screen position in
248 command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000249getcmdtype() String return current command-line type
250getcmdwintype() String return current command-line window type
251getcompletion({pat}, {type} [, {filtered}])
252 List list of cmdline completion matches
253getcurpos([{winnr}]) List position of the cursor
254getcursorcharpos([{winnr}]) List character position of the cursor
255getcwd([{winnr} [, {tabnr}]]) String get the current working directory
256getenv({name}) String return environment variable
257getfontname([{name}]) String name of font being used
258getfperm({fname}) String file permissions of file {fname}
259getfsize({fname}) Number size in bytes of file {fname}
260getftime({fname}) Number last modification time of file
261getftype({fname}) String description of type of file {fname}
262getimstatus() Number |TRUE| if the IME status is active
263getjumplist([{winnr} [, {tabnr}]])
264 List list of jump list items
265getline({lnum}) String line {lnum} of current buffer
266getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
267getloclist({nr}) List list of location list items
268getloclist({nr}, {what}) Dict get specific location list properties
269getmarklist([{buf}]) List list of global/local marks
270getmatches([{win}]) List list of current matches
271getmousepos() Dict last known mouse position
Bram Moolenaar24dc19c2022-11-14 19:49:15 +0000272getmouseshape() String current mouse shape name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000273getpid() Number process ID of Vim
274getpos({expr}) List position of cursor, mark, etc.
275getqflist() List list of quickfix items
276getqflist({what}) Dict get specific quickfix list properties
277getreg([{regname} [, 1 [, {list}]]])
278 String or List contents of a register
279getreginfo([{regname}]) Dict information about a register
Shougo Matsushita19b71882024-02-28 22:48:12 +0100280getregion({pos1}, {pos2} [, {opts}])
Shougo Matsushita3f905ab2024-02-21 00:02:45 +0100281 List get the text from {pos1} to {pos2}
Shougo Matsushitab4757e62024-05-07 20:49:24 +0200282getregionpos({pos1}, {pos2} [, {opts}])
283 List get a list of positions for a region
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000284getregtype([{regname}]) String type of a register
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +0100285getscriptinfo([{opts}]) List list of sourced scripts
ichizok663d18d2025-01-02 18:06:00 +0100286getstacktrace() List get current stack trace of Vim scripts
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000287gettabinfo([{expr}]) List list of tab pages
288gettabvar({nr}, {varname} [, {def}])
289 any variable {varname} in tab {nr} or {def}
290gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
291 any {name} in {winnr} in tab page {tabnr}
292gettagstack([{nr}]) Dict get the tag stack of window {nr}
h-east52e7cc22024-07-28 17:03:29 +0200293gettext({text} [, {package}]) String lookup translation of {text}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000294getwininfo([{winid}]) List list of info about each window
Bram Moolenaar938ae282023-02-20 20:44:55 +0000295getwinpos([{timeout}]) List X and Y coord in pixels of Vim window
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000296getwinposx() Number X coord in pixels of the Vim window
297getwinposy() Number Y coord in pixels of the Vim window
298getwinvar({nr}, {varname} [, {def}])
299 any variable {varname} in window {nr}
300glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
301 any expand file wildcards in {expr}
302glob2regpat({expr}) String convert a glob pat into a search pat
303globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
304 String do glob({expr}) for all dirs in {path}
305has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
306has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
307haslocaldir([{winnr} [, {tabnr}]])
308 Number |TRUE| if the window executed |:lcd|
309 or |:tcd|
310hasmapto({what} [, {mode} [, {abbr}]])
311 Number |TRUE| if mapping to {what} exists
312histadd({history}, {item}) Number add an item to a history
313histdel({history} [, {item}]) Number remove an item from a history
314histget({history} [, {index}]) String get the item {index} from a history
315histnr({history}) Number highest index of a history
316hlID({name}) Number syntax ID of highlight group {name}
317hlexists({name}) Number |TRUE| if highlight group {name} exists
318hlget([{name} [, {resolve}]]) List get highlight group attributes
319hlset({list}) Number set highlight group attributes
320hostname() String name of the machine Vim is running on
321iconv({expr}, {from}, {to}) String convert encoding of {expr}
Ernie Rael05124252024-07-11 22:10:45 +0200322id({item}) String get unique identity string of item
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000323indent({lnum}) Number indent of line {lnum}
324index({object}, {expr} [, {start} [, {ic}]])
325 Number index in {object} where {expr} appears
Yegappan Lakshmananb2186552022-08-13 13:09:20 +0100326indexof({object}, {expr} [, {opts}]])
327 Number index in {object} where {expr} is true
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000328input({prompt} [, {text} [, {completion}]])
329 String get input from the user
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100330inputdialog({prompt} [, {text} [, {cancelreturn}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000331 String like input() but in a GUI dialog
332inputlist({textlist}) Number let the user pick from a choice list
333inputrestore() Number restore typeahead
334inputsave() Number save and clear typeahead
335inputsecret({prompt} [, {text}]) String like input() but hiding the text
336insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
LemonBoyafe04662023-08-23 21:08:11 +0200337instanceof({object}, {class}) Number |TRUE| if {object} is an instance of {class}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000338interrupt() none interrupt script execution
339invert({expr}) Number bitwise invert
LemonBoydca1d402022-04-28 15:26:33 +0100340isabsolutepath({path}) Number |TRUE| if {path} is an absolute path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000341isdirectory({directory}) Number |TRUE| if {directory} is a directory
342isinf({expr}) Number determine if {expr} is infinity value
343 (positive or negative)
344islocked({expr}) Number |TRUE| if {expr} is locked
345isnan({expr}) Number |TRUE| if {expr} is NaN
346items({dict}) List key-value pairs in {dict}
347job_getchannel({job}) Channel get the channel handle for {job}
348job_info([{job}]) Dict get information about {job}
349job_setoptions({job}, {options}) none set options for {job}
350job_start({command} [, {options}])
351 Job start a job
352job_status({job}) String get the status of {job}
353job_stop({job} [, {how}]) Number stop {job}
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100354join({expr} [, {sep}]) String join items in {expr} into one String
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000355js_decode({string}) any decode JS style JSON
356js_encode({expr}) String encode JS style JSON
357json_decode({string}) any decode JSON
358json_encode({expr}) String encode JSON
359keys({dict}) List keys in {dict}
zeertzjqcdc83932022-09-12 13:38:41 +0100360keytrans({string}) String translate internal keycodes to a form
361 that can be used by |:map|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000362len({expr}) Number the length of {expr}
363libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
364libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
365line({expr} [, {winid}]) Number line nr of cursor, last line or mark
366line2byte({lnum}) Number byte count of line {lnum}
367lispindent({lnum}) Number Lisp indent for line {lnum}
368list2blob({list}) Blob turn {list} of numbers into a Blob
369list2str({list} [, {utf8}]) String turn {list} of numbers into a String
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100370list2tuple({list}) Tuple turn {list} of items into a tuple
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000371listener_add({callback} [, {buf}])
372 Number add a callback to listen to changes
373listener_flush([{buf}]) none invoke listener callbacks
374listener_remove({id}) none remove a listener callback
375localtime() Number current time
376log({expr}) Float natural logarithm (base e) of {expr}
377log10({expr}) Float logarithm of Float {expr} to base 10
378luaeval({expr} [, {expr}]) any evaluate |Lua| expression
379map({expr1}, {expr2}) List/Dict/Blob/String
380 change each item in {expr1} to {expr2}
381maparg({name} [, {mode} [, {abbr} [, {dict}]]])
382 String or Dict
383 rhs of mapping {name} in mode {mode}
384mapcheck({name} [, {mode} [, {abbr}]])
385 String check for mappings matching {name}
Ernie Rael09661202022-04-25 14:40:44 +0100386maplist([{abbr}]) List list of all mappings, a dict for each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000387mapnew({expr1}, {expr2}) List/Dict/Blob/String
388 like |map()| but creates a new List or
389 Dictionary
390mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
391match({expr}, {pat} [, {start} [, {count}]])
392 Number position where {pat} matches in {expr}
393matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
394 Number highlight {pattern} with {group}
395matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
396 Number highlight positions with {group}
397matcharg({nr}) List arguments of |:match|
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100398matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict})
399 List all the {pat} matches in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000400matchdelete({id} [, {win}]) Number delete match identified by {id}
401matchend({expr}, {pat} [, {start} [, {count}]])
402 Number position where {pat} ends in {expr}
403matchfuzzy({list}, {str} [, {dict}])
404 List fuzzy match {str} in {list}
405matchfuzzypos({list}, {str} [, {dict}])
406 List fuzzy match {str} in {list}
407matchlist({expr}, {pat} [, {start} [, {count}]])
408 List match and submatches of {pat} in {expr}
409matchstr({expr}, {pat} [, {start} [, {count}]])
410 String {count}'th match of {pat} in {expr}
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100411matchstrlist({list}, {pat} [, {dict})
412 List all the {pat} matches in {list}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000413matchstrpos({expr}, {pat} [, {start} [, {count}]])
414 List {count}'th match of {pat} in {expr}
415max({expr}) Number maximum value of items in {expr}
416menu_info({name} [, {mode}]) Dict get menu item information
417min({expr}) Number minimum value of items in {expr}
Bram Moolenaar938ae282023-02-20 20:44:55 +0000418mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000419 Number create directory {name}
Doug Kearns9cd9e752024-04-07 17:42:17 +0200420mode([{expr}]) String current editing mode
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000421mzeval({expr}) any evaluate |MzScheme| expression
422nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
Christ van Willegenc0786752025-02-01 15:42:16 +0100423ngettext({single}, {plural}, {number}[, {domain}])
424 String translate text based on {number}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000425nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
426or({expr}, {expr}) Number bitwise OR
427pathshorten({expr} [, {len}]) String shorten directory names in a path
428perleval({expr}) any evaluate |Perl| expression
429popup_atcursor({what}, {options}) Number create popup window near the cursor
430popup_beval({what}, {options}) Number create popup window for 'ballooneval'
431popup_clear() none close all popup windows
432popup_close({id} [, {result}]) none close popup window {id}
433popup_create({what}, {options}) Number create a popup window
434popup_dialog({what}, {options}) Number create a popup window used as a dialog
435popup_filter_menu({id}, {key}) Number filter for a menu popup window
436popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
Bram Moolenaarbdc09a12022-10-07 14:31:45 +0100437popup_findecho() Number get window ID of popup for `:echowin`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000438popup_findinfo() Number get window ID of info popup window
439popup_findpreview() Number get window ID of preview popup window
440popup_getoptions({id}) Dict get options of popup window {id}
441popup_getpos({id}) Dict get position of popup window {id}
442popup_hide({id}) none hide popup menu {id}
443popup_list() List get a list of window IDs of all popups
444popup_locate({row}, {col}) Number get window ID of popup at position
445popup_menu({what}, {options}) Number create a popup window used as a menu
446popup_move({id}, {options}) none set position of popup window {id}
447popup_notification({what}, {options})
448 Number create a notification popup window
Christian Brabandtfbc37f12024-06-18 20:50:58 +0200449popup_setbuf({id}, {buf}) Bool set the buffer for the popup window {id}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000450popup_setoptions({id}, {options})
451 none set options for popup window {id}
452popup_settext({id}, {text}) none set the text of popup window {id}
453popup_show({id}) none unhide popup window {id}
454pow({x}, {y}) Float {x} to the power of {y}
455prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
456printf({fmt}, {expr1}...) String format text
457prompt_getprompt({buf}) String get prompt text
458prompt_setcallback({buf}, {expr}) none set prompt callback function
459prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
460prompt_setprompt({buf}, {text}) none set prompt text
461prop_add({lnum}, {col}, {props}) none add one text property
462prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
463 none add multiple text properties
464prop_clear({lnum} [, {lnum-end} [, {props}]])
465 none remove all text properties
466prop_find({props} [, {direction}])
467 Dict search for a text property
468prop_list({lnum} [, {props}]) List text properties in {lnum}
469prop_remove({props} [, {lnum} [, {lnum-end}]])
470 Number remove a text property
471prop_type_add({name}, {props}) none define a new property type
472prop_type_change({name}, {props})
473 none change an existing property type
474prop_type_delete({name} [, {props}])
475 none delete a property type
476prop_type_get({name} [, {props}])
477 Dict get property type values
478prop_type_list([{props}]) List get list of property types
479pum_getpos() Dict position and size of pum if visible
480pumvisible() Number whether popup menu is visible
zeertzjq7c515282024-11-10 20:26:12 +0100481py3eval({expr} [, {locals}]) any evaluate |python3| expression
482pyeval({expr} [, {locals}]) any evaluate |Python| expression
483pyxeval({expr} [, {locals}]) any evaluate |python_x| expression
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000484rand([{expr}]) Number get pseudo-random number
485range({expr} [, {max} [, {stride}]])
486 List items from {expr} to {max}
K.Takata11df3ae2022-10-19 14:02:40 +0100487readblob({fname} [, {offset} [, {size}]])
488 Blob read a |Blob| from {fname}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000489readdir({dir} [, {expr} [, {dict}]])
490 List file names in {dir} selected by {expr}
491readdirex({dir} [, {expr} [, {dict}]])
492 List file info in {dir} selected by {expr}
493readfile({fname} [, {type} [, {max}]])
494 List get list of lines from file {fname}
495reduce({object}, {func} [, {initial}])
496 any reduce {object} using {func}
497reg_executing() String get the executing register name
498reg_recording() String get the recording register name
499reltime([{start} [, {end}]]) List get time value
500reltimefloat({time}) Float turn the time value into a Float
501reltimestr({time}) String turn time value into a String
502remote_expr({server}, {string} [, {idvar} [, {timeout}]])
503 String send expression
504remote_foreground({server}) Number bring Vim server to the foreground
505remote_peek({serverid} [, {retvar}])
506 Number check for reply string
507remote_read({serverid} [, {timeout}])
508 String read reply string
509remote_send({server}, {string} [, {idvar}])
510 String send key sequence
511remote_startserver({name}) none become server {name}
512remove({list}, {idx} [, {end}]) any/List
513 remove items {idx}-{end} from {list}
514remove({blob}, {idx} [, {end}]) Number/Blob
515 remove bytes {idx}-{end} from {blob}
516remove({dict}, {key}) any remove entry {key} from {dict}
517rename({from}, {to}) Number rename (move) file from {from} to {to}
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100518repeat({expr}, {count}) List/Tuple/Blob/String
Bakudankun375141e2022-09-09 18:46:47 +0100519 repeat {expr} {count} times
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000520resolve({filename}) String get filename a shortcut points to
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100521reverse({obj}) List/Tuple/Blob/String
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +0100522 reverse {obj}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000523round({expr}) Float round off {expr}
524rubyeval({expr}) any evaluate |Ruby| expression
525screenattr({row}, {col}) Number attribute at screen position
526screenchar({row}, {col}) Number character at screen position
527screenchars({row}, {col}) List List of characters at screen position
528screencol() Number current cursor column
529screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
530screenrow() Number current cursor row
531screenstring({row}, {col}) String characters at screen position
532search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
533 Number search for {pattern}
534searchcount([{options}]) Dict get or update search stats
535searchdecl({name} [, {global} [, {thisblock}]])
536 Number search for variable declaration
537searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
538 Number search for other end of start/end pair
539searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
540 List search for other end of start/end pair
541searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
542 List search for {pattern}
543server2client({clientid}, {string})
544 Number send reply string
545serverlist() String get a list of available servers
erraelf0837ba2024-06-24 12:27:01 -0700546setbufline({buf}, {lnum}, {text})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000547 Number set line {lnum} to {text} in buffer
erraelf0837ba2024-06-24 12:27:01 -0700548 {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000549setbufvar({buf}, {varname}, {val})
550 none set {varname} in buffer {buf} to {val}
551setcellwidths({list}) none set character cell width overrides
552setcharpos({expr}, {list}) Number set the {expr} position to {list}
553setcharsearch({dict}) Dict set character search from {dict}
Shougo Matsushita07ea5f12022-08-27 12:22:25 +0100554setcmdline({str} [, {pos}]) Number set command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000555setcmdpos({pos}) Number set cursor position in command-line
556setcursorcharpos({list}) Number move cursor to position in {list}
557setenv({name}, {val}) none set environment variable
558setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
559setline({lnum}, {line}) Number set line {lnum} to {line}
560setloclist({nr}, {list} [, {action}])
561 Number modify location list using {list}
562setloclist({nr}, {list}, {action}, {what})
563 Number modify specific location list props
564setmatches({list} [, {win}]) Number restore a list of matches
565setpos({expr}, {list}) Number set the {expr} position to {list}
566setqflist({list} [, {action}]) Number modify quickfix list using {list}
567setqflist({list}, {action}, {what})
568 Number modify specific quickfix list props
569setreg({n}, {v} [, {opt}]) Number set register to value and type
570settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
571settabwinvar({tabnr}, {winnr}, {varname}, {val})
572 none set {varname} in window {winnr} in tab
573 page {tabnr} to {val}
574settagstack({nr}, {dict} [, {action}])
575 Number modify tag stack using {dict}
576setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
577sha256({string}) String SHA256 checksum of {string}
578shellescape({string} [, {special}])
579 String escape {string} for use as shell
580 command argument
581shiftwidth([{col}]) Number effective value of 'shiftwidth'
582sign_define({name} [, {dict}]) Number define or update a sign
583sign_define({list}) List define or update a list of signs
584sign_getdefined([{name}]) List get a list of defined signs
585sign_getplaced([{buf} [, {dict}]])
586 List get a list of placed signs
587sign_jump({id}, {group}, {buf})
588 Number jump to a sign
589sign_place({id}, {group}, {name}, {buf} [, {dict}])
590 Number place a sign
591sign_placelist({list}) List place a list of signs
592sign_undefine([{name}]) Number undefine a sign
593sign_undefine({list}) List undefine a list of signs
594sign_unplace({group} [, {dict}])
595 Number unplace a sign
596sign_unplacelist({list}) List unplace a list of signs
597simplify({filename}) String simplify filename as much as possible
598sin({expr}) Float sine of {expr}
599sinh({expr}) Float hyperbolic sine of {expr}
600slice({expr}, {start} [, {end}]) String, List or Blob
601 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000602sort({list} [, {how} [, {dict}]])
603 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000604sound_clear() none stop playing all sounds
605sound_playevent({name} [, {callback}])
606 Number play an event sound
607sound_playfile({path} [, {callback}])
608 Number play sound file {path}
609sound_stop({id}) none stop playing sound {id}
610soundfold({word}) String sound-fold {word}
611spellbadword() String badly spelled word at cursor
612spellsuggest({word} [, {max} [, {capital}]])
613 List spelling suggestions
614split({expr} [, {pat} [, {keepempty}]])
615 List make |List| from {pat} separated {expr}
616sqrt({expr}) Float square root of {expr}
617srand([{expr}]) List get seed for |rand()|
618state([{what}]) String current state of Vim
Hirohito Higashi195fcc92025-02-01 10:26:58 +0100619str2blob({list} [, {options}]) Blob convert list of strings into a Blob
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000620str2float({expr} [, {quoted}]) Float convert String to Float
621str2list({expr} [, {utf8}]) List convert each character of {expr} to
622 ASCII/UTF-8 value
623str2nr({expr} [, {base} [, {quoted}]])
624 Number convert String to Number
625strcharlen({expr}) Number character length of the String {expr}
626strcharpart({str}, {start} [, {len} [, {skipcc}]])
627 String {len} characters of {str} at
628 character {start}
629strchars({expr} [, {skipcc}]) Number character count of the String {expr}
630strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
631strftime({format} [, {time}]) String format time with a specified format
632strgetchar({str}, {index}) Number get char {index} from {str}
633stridx({haystack}, {needle} [, {start}])
634 Number index of {needle} in {haystack}
635string({expr}) String String representation of {expr} value
636strlen({expr}) Number length of the String {expr}
637strpart({str}, {start} [, {len} [, {chars}]])
638 String {len} bytes/chars of {str} at
639 byte {start}
640strptime({format}, {timestring})
641 Number Convert {timestring} to unix timestamp
642strridx({haystack}, {needle} [, {start}])
643 Number last index of {needle} in {haystack}
644strtrans({expr}) String translate string to make it printable
Christian Brabandt67672ef2023-04-24 21:09:54 +0100645strutf16len({string} [, {countcc}])
646 Number number of UTF-16 code units in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000647strwidth({expr}) Number display cell length of the String {expr}
648submatch({nr} [, {list}]) String or List
649 specific match in ":s" or substitute()
650substitute({expr}, {pat}, {sub}, {flags})
651 String all {pat} in {expr} replaced with {sub}
Bram Moolenaarc216a7a2022-12-05 13:50:55 +0000652swapfilelist() List swap files found in 'directory'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000653swapinfo({fname}) Dict information about swap file {fname}
654swapname({buf}) String swap file of buffer {buf}
655synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
656synIDattr({synID}, {what} [, {mode}])
657 String attribute {what} of syntax ID {synID}
658synIDtrans({synID}) Number translated syntax ID of {synID}
659synconcealed({lnum}, {col}) List info about concealing
660synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
661system({expr} [, {input}]) String output of shell command/filter {expr}
662systemlist({expr} [, {input}]) List output of shell command/filter {expr}
663tabpagebuflist([{arg}]) List list of buffer numbers in tab page
664tabpagenr([{arg}]) Number number of current or last tab page
665tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
666tagfiles() List tags files used
667taglist({expr} [, {filename}]) List list of tags matching {expr}
668tan({expr}) Float tangent of {expr}
669tanh({expr}) Float hyperbolic tangent of {expr}
670tempname() String name for a temporary file
671term_dumpdiff({filename}, {filename} [, {options}])
672 Number display difference between two dumps
673term_dumpload({filename} [, {options}])
674 Number displaying a screen dump
675term_dumpwrite({buf}, {filename} [, {options}])
676 none dump terminal window contents
677term_getaltscreen({buf}) Number get the alternate screen flag
678term_getansicolors({buf}) List get ANSI palette in GUI color mode
679term_getattr({attr}, {what}) Number get the value of attribute {what}
680term_getcursor({buf}) List get the cursor position of a terminal
681term_getjob({buf}) Job get the job associated with a terminal
682term_getline({buf}, {row}) String get a line of text from a terminal
683term_getscrolled({buf}) Number get the scroll count of a terminal
684term_getsize({buf}) List get the size of a terminal
685term_getstatus({buf}) String get the status of a terminal
686term_gettitle({buf}) String get the title of a terminal
687term_gettty({buf}, [{input}]) String get the tty name of a terminal
688term_list() List get the list of terminal buffers
689term_scrape({buf}, {row}) List get row of a terminal screen
690term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
691term_setansicolors({buf}, {colors})
692 none set ANSI palette in GUI color mode
693term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
694term_setkill({buf}, {how}) none set signal to stop job in terminal
695term_setrestore({buf}, {command}) none set command to restore terminal
696term_setsize({buf}, {rows}, {cols})
697 none set the size of a terminal
698term_start({cmd} [, {options}]) Number open a terminal window and run a job
699term_wait({buf} [, {time}]) Number wait for screen to be updated
700terminalprops() Dict properties of the terminal
701test_alloc_fail({id}, {countdown}, {repeat})
702 none make memory allocation fail
703test_autochdir() none enable 'autochdir' during startup
704test_feedinput({string}) none add key sequence to input buffer
705test_garbagecollect_now() none free memory right now for testing
706test_garbagecollect_soon() none free memory soon for testing
707test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000708test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000709test_ignore_error({expr}) none ignore a specific error
Christopher Plewright20b795e2022-12-20 20:01:58 +0000710test_mswin_event({event}, {args})
711 bool generate MS-Windows event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000712test_null_blob() Blob null value for testing
713test_null_channel() Channel null value for testing
714test_null_dict() Dict null value for testing
715test_null_function() Funcref null value for testing
716test_null_job() Job null value for testing
717test_null_list() List null value for testing
718test_null_partial() Funcref null value for testing
719test_null_string() String null value for testing
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100720test_null_tuple() Tuple null value for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000721test_option_not_set({name}) none reset flag indicating option was set
722test_override({expr}, {val}) none test with Vim internal overrides
723test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000724test_setmouse({row}, {col}) none set the mouse position for testing
725test_settime({expr}) none set current time for testing
Doug Kearns9cd9e752024-04-07 17:42:17 +0200726test_srand_seed([{seed}]) none set seed for testing srand()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000727test_unknown() any unknown value for testing
728test_void() any void value for testing
729timer_info([{id}]) List information about timers
730timer_pause({id}, {pause}) none pause or unpause a timer
731timer_start({time}, {callback} [, {options}])
732 Number create a timer
733timer_stop({timer}) none stop a timer
734timer_stopall() none stop all timers
735tolower({expr}) String the String {expr} switched to lowercase
736toupper({expr}) String the String {expr} switched to uppercase
737tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
738 to chars in {tostr}
739trim({text} [, {mask} [, {dir}]])
740 String trim characters in {mask} from {text}
741trunc({expr}) Float truncate Float {expr}
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +0100742tuple2list({tuple}) List turn {tuple} of items into a list
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000743type({expr}) Number type of value {expr}
744typename({expr}) String representation of the type of {expr}
745undofile({name}) String undo file name for {name}
Devin J. Pohly5fee1112023-04-23 20:26:59 -0500746undotree([{buf}]) List undo file tree for buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000747uniq({list} [, {func} [, {dict}]])
748 List remove adjacent duplicates from a list
Christian Brabandt67672ef2023-04-24 21:09:54 +0100749utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
750 Number UTF-16 index of byte {idx} in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000751values({dict}) List values in {dict}
zeertzjq825cf812023-08-17 22:55:25 +0200752virtcol({expr} [, {list} [, {winid}])
753 Number or List
LemonBoy0f7a3e12022-05-26 12:10:37 +0100754 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100755virtcol2col({winid}, {lnum}, {col})
756 Number byte index of a character on screen
Doug Kearns9cd9e752024-04-07 17:42:17 +0200757visualmode([{expr}]) String last visual mode used
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000758wildmenumode() Number whether 'wildmenu' mode is active
759win_execute({id}, {command} [, {silent}])
760 String execute {command} in window {id}
761win_findbuf({bufnr}) List find windows containing {bufnr}
762win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
763win_gettype([{nr}]) String type of window {nr}
764win_gotoid({expr}) Number go to window with ID {expr}
765win_id2tabwin({expr}) List get tab and window nr from window ID
766win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000767win_move_separator({nr}) Number move window vertical separator
768win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000769win_screenpos({nr}) List get screen position of window {nr}
770win_splitmove({nr}, {target} [, {options}])
771 Number move window {nr} to split of {target}
772winbufnr({nr}) Number buffer number of window {nr}
773wincol() Number window column of the cursor
774windowsversion() String MS-Windows OS version
775winheight({nr}) Number height of window {nr}
776winlayout([{tabnr}]) List layout of windows in tab {tabnr}
777winline() Number window line of the cursor
778winnr([{expr}]) Number number of current window
779winrestcmd() String returns command to restore window sizes
780winrestview({dict}) none restore view of current window
781winsaveview() Dict save view of current window
782winwidth({nr}) Number width of window {nr}
783wordcount() Dict get byte/char/word statistics
784writefile({object}, {fname} [, {flags}])
785 Number write |Blob| or |List| of lines to file
786xor({expr}, {expr}) Number bitwise XOR
787
788==============================================================================
7892. Details *builtin-function-details*
790
791Not all functions are here, some have been moved to a help file covering the
792specific functionality.
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200793Return type specifies the type for |Vim9-script|, see |vim9-types|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000794
795abs({expr}) *abs()*
796 Return the absolute value of {expr}. When {expr} evaluates to
797 a |Float| abs() returns a |Float|. When {expr} can be
798 converted to a |Number| abs() returns a |Number|. Otherwise
799 abs() gives an error message and returns -1.
800 Examples: >
801 echo abs(1.456)
802< 1.456 >
803 echo abs(-5.456)
804< 5.456 >
805 echo abs(-4)
806< 4
807
808 Can also be used as a |method|: >
809 Compute()->abs()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200810<
811 Return type: |Number| or |Float| depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000812
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000813
814acos({expr}) *acos()*
815 Return the arc cosine of {expr} measured in radians, as a
816 |Float| in the range of [0, pi].
817 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100818 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000819 Examples: >
820 :echo acos(0)
821< 1.570796 >
822 :echo acos(-0.5)
823< 2.094395
824
825 Can also be used as a |method|: >
826 Compute()->acos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200827<
828 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000829
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000830
831add({object}, {expr}) *add()*
832 Append the item {expr} to |List| or |Blob| {object}. Returns
833 the resulting |List| or |Blob|. Examples: >
834 :let alist = add([1, 2, 3], item)
835 :call add(mylist, "woodstock")
836< Note that when {expr} is a |List| it is appended as a single
837 item. Use |extend()| to concatenate |Lists|.
838 When {object} is a |Blob| then {expr} must be a number.
839 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100840 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000841
842 Can also be used as a |method|: >
843 mylist->add(val1)->add(val2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200844<
845 Return type: list<{type}> (depending on the given |List|) or
846 |Blob|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000847
848
849and({expr}, {expr}) *and()*
850 Bitwise AND on the two arguments. The arguments are converted
851 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100852 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000853 Example: >
854 :let flag = and(bits, 0x80)
855< Can also be used as a |method|: >
856 :let flag = bits->and(0x80)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200857<
858 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000859
860
861append({lnum}, {text}) *append()*
862 When {text} is a |List|: Append each item of the |List| as a
863 text line below line {lnum} in the current buffer.
864 Otherwise append {text} as one text line below line {lnum} in
865 the current buffer.
866 Any type of item is accepted and converted to a String.
867 {lnum} can be zero to insert a line before the first one.
868 {lnum} is used like with |getline()|.
869 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000870 0 for success. When {text} is an empty list zero is returned,
871 no matter the value of {lnum}.
872 In |Vim9| script an invalid argument or negative number
873 results in an error. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000874 :let failed = append(line('$'), "# THE END")
875 :let failed = append(0, ["Chapter 1", "the beginning"])
876
877< Can also be used as a |method| after a List, the base is
878 passed as the second argument: >
879 mylist->append(lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200880<
881 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000882
883
884appendbufline({buf}, {lnum}, {text}) *appendbufline()*
885 Like |append()| but append the text in buffer {buf}.
886
887 This function works only for loaded buffers. First call
888 |bufload()| if needed.
889
890 For the use of {buf}, see |bufname()|.
891
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000892 {lnum} is the line number to append below. Note that using
893 |line()| would use the current buffer, not the one appending
894 to. Use "$" to append at the end of the buffer. Other string
895 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000896
897 On success 0 is returned, on failure 1 is returned.
898 In |Vim9| script an error is given for an invalid {lnum}.
899
900 If {buf} is not a valid buffer or {lnum} is not valid, an
901 error message is given. Example: >
902 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000903< However, when {text} is an empty list then no error is given
904 for an invalid {lnum}, since {lnum} isn't actually used.
905
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000906 Can also be used as a |method| after a List, the base is
907 passed as the second argument: >
908 mylist->appendbufline(buf, lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200909<
910 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000911
912
913argc([{winid}]) *argc()*
914 The result is the number of files in the argument list. See
915 |arglist|.
916 If {winid} is not supplied, the argument list of the current
917 window is used.
918 If {winid} is -1, the global argument list is used.
919 Otherwise {winid} specifies the window of which the argument
920 list is used: either the window number or the window ID.
921 Returns -1 if the {winid} argument is invalid.
922
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200923 Return type: |Number|
924
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000925 *argidx()*
926argidx() The result is the current index in the argument list. 0 is
927 the first file. argc() - 1 is the last one. See |arglist|.
928
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200929 Return type: |Number|
930
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000931 *arglistid()*
932arglistid([{winnr} [, {tabnr}]])
933 Return the argument list ID. This is a number which
934 identifies the argument list being used. Zero is used for the
935 global argument list. See |arglist|.
936 Returns -1 if the arguments are invalid.
937
938 Without arguments use the current window.
939 With {winnr} only use this window in the current tab page.
940 With {winnr} and {tabnr} use the window in the specified tab
941 page.
942 {winnr} can be the window number or the |window-ID|.
943
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200944 Return type: |Number|
945
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000946 *argv()*
947argv([{nr} [, {winid}]])
948 The result is the {nr}th file in the argument list. See
949 |arglist|. "argv(0)" is the first one. Example: >
950 :let i = 0
951 :while i < argc()
952 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000953 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000954 : let i = i + 1
955 :endwhile
956< Without the {nr} argument, or when {nr} is -1, a |List| with
957 the whole |arglist| is returned.
958
959 The {winid} argument specifies the window ID, see |argc()|.
960 For the Vim command line arguments see |v:argv|.
961
Bram Moolenaar016188f2022-06-06 20:52:59 +0100962 Returns an empty string if {nr}th argument is not present in
963 the argument list. Returns an empty List if the {winid}
964 argument is invalid.
965
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200966 Return type: |String|
967
968
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000969asin({expr}) *asin()*
970 Return the arc sine of {expr} measured in radians, as a |Float|
971 in the range of [-pi/2, pi/2].
972 {expr} must evaluate to a |Float| or a |Number| in the range
973 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100974 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
975 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000976 Examples: >
977 :echo asin(0.8)
978< 0.927295 >
979 :echo asin(-0.5)
980< -0.523599
981
982 Can also be used as a |method|: >
983 Compute()->asin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200984<
985 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000986
987assert_ functions are documented here: |assert-functions-details|
988
989
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000990atan({expr}) *atan()*
991 Return the principal value of the arc tangent of {expr}, in
992 the range [-pi/2, +pi/2] radians, as a |Float|.
993 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100994 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000995 Examples: >
996 :echo atan(100)
997< 1.560797 >
998 :echo atan(-4.01)
999< -1.326405
1000
1001 Can also be used as a |method|: >
1002 Compute()->atan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001003<
1004 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001005
1006
1007atan2({expr1}, {expr2}) *atan2()*
1008 Return the arc tangent of {expr1} / {expr2}, measured in
1009 radians, as a |Float| in the range [-pi, pi].
1010 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001011 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
1012 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001013 Examples: >
1014 :echo atan2(-1, 1)
1015< -0.785398 >
1016 :echo atan2(1, -1)
1017< 2.356194
1018
1019 Can also be used as a |method|: >
1020 Compute()->atan2(1)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001021<
1022 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001023
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001024
1025autocmd_add({acmds}) *autocmd_add()*
1026 Adds a List of autocmds and autocmd groups.
1027
1028 The {acmds} argument is a List where each item is a Dict with
1029 the following optional items:
1030 bufnr buffer number to add a buffer-local autocmd.
1031 If this item is specified, then the "pattern"
1032 item is ignored.
1033 cmd Ex command to execute for this autocmd event
1034 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +01001035 This can be either a String with a single
1036 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001037 group autocmd group name. Refer to |autocmd-groups|.
1038 If this group doesn't exist then it is
1039 created. If not specified or empty, then the
1040 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001041 nested boolean flag, set to v:true to add a nested
1042 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +01001043 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001044 which executes only once. Refer to
1045 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001046 pattern autocmd pattern string. Refer to
1047 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +01001048 present, then this item is ignored. This can
1049 be a String with a single pattern or a List of
1050 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001051 replace boolean flag, set to v:true to remove all the
1052 commands associated with the specified autocmd
1053 event and group and add the {cmd}. This is
1054 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +01001055 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001056
1057 Returns v:true on success and v:false on failure.
1058 Examples: >
1059 " Create a buffer-local autocmd for buffer 5
1060 let acmd = {}
1061 let acmd.group = 'MyGroup'
1062 let acmd.event = 'BufEnter'
1063 let acmd.bufnr = 5
1064 let acmd.cmd = 'call BufEnterFunc()'
1065 call autocmd_add([acmd])
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00001066<
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001067 Can also be used as a |method|: >
1068 GetAutocmdList()->autocmd_add()
1069<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001070 Return type: |vim9-boolean|
1071
1072
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001073autocmd_delete({acmds}) *autocmd_delete()*
1074 Deletes a List of autocmds and autocmd groups.
1075
1076 The {acmds} argument is a List where each item is a Dict with
1077 the following optional items:
1078 bufnr buffer number to delete a buffer-local autocmd.
1079 If this item is specified, then the "pattern"
1080 item is ignored.
1081 cmd Ex command for this autocmd event
1082 event autocmd event name. Refer to |autocmd-events|.
1083 If '*' then all the autocmd events in this
1084 group are deleted.
1085 group autocmd group name. Refer to |autocmd-groups|.
1086 If not specified or empty, then the default
1087 group is used.
1088 nested set to v:true for a nested autocmd.
1089 Refer to |autocmd-nested|.
1090 once set to v:true for an autocmd which executes
1091 only once. Refer to |autocmd-once|.
1092 pattern autocmd pattern string. Refer to
1093 |autocmd-patterns|. If "bufnr" item is
1094 present, then this item is ignored.
1095
1096 If only {group} is specified in a {acmds} entry and {event},
1097 {pattern} and {cmd} are not specified, then that autocmd group
1098 is deleted.
1099
Bram Moolenaar016188f2022-06-06 20:52:59 +01001100 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001101 Examples: >
1102 " :autocmd! BufLeave *.vim
1103 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1104 call autocmd_delete([acmd]})
1105 " :autocmd! MyGroup1 BufLeave
1106 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1107 call autocmd_delete([acmd])
1108 " :autocmd! MyGroup2 BufEnter *.c
1109 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1110 \ pattern: '*.c'}
1111 " :autocmd! MyGroup2 * *.c
1112 let acmd = #{group: 'MyGroup2', event: '*',
1113 \ pattern: '*.c'}
1114 call autocmd_delete([acmd])
1115 " :autocmd! MyGroup3
1116 let acmd = #{group: 'MyGroup3'}
1117 call autocmd_delete([acmd])
1118<
1119 Can also be used as a |method|: >
1120 GetAutocmdList()->autocmd_delete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001121<
1122 Return type: |vim9-boolean|
1123
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001124
1125autocmd_get([{opts}]) *autocmd_get()*
1126 Returns a |List| of autocmds. If {opts} is not supplied, then
1127 returns the autocmds for all the events in all the groups.
1128
1129 The optional {opts} Dict argument supports the following
1130 items:
1131 group Autocmd group name. If specified, returns only
1132 the autocmds defined in this group. If the
1133 specified group doesn't exist, results in an
1134 error message. If set to an empty string,
1135 then the default autocmd group is used.
1136 event Autocmd event name. If specified, returns only
1137 the autocmds defined for this event. If set
1138 to "*", then returns autocmds for all the
1139 events. If the specified event doesn't exist,
1140 results in an error message.
1141 pattern Autocmd pattern. If specified, returns only
1142 the autocmds defined for this pattern.
1143 A combination of the above three times can be supplied in
1144 {opts}.
1145
1146 Each Dict in the returned List contains the following items:
1147 bufnr For buffer-local autocmds, buffer number where
1148 the autocmd is defined.
1149 cmd Command executed for this autocmd.
1150 event Autocmd event name.
1151 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001152 nested Boolean flag, set to v:true for a nested
1153 autocmd. See |autocmd-nested|.
1154 once Boolean flag, set to v:true, if the autocmd
1155 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001156 pattern Autocmd pattern. For a buffer-local
1157 autocmd, this will be of the form "<buffer=n>".
1158 If there are multiple commands for an autocmd event in a
1159 group, then separate items are returned for each command.
1160
Bram Moolenaar016188f2022-06-06 20:52:59 +01001161 Returns an empty List if an autocmd with the specified group
1162 or event or pattern is not found.
1163
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001164 Examples: >
1165 " :autocmd MyGroup
1166 echo autocmd_get(#{group: 'Mygroup'})
1167 " :autocmd G BufUnload
1168 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1169 " :autocmd G * *.ts
1170 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1171 echo autocmd_get(acmd)
1172 " :autocmd Syntax
1173 echo autocmd_get(#{event: 'Syntax'})
1174 " :autocmd G BufEnter *.ts
1175 let acmd = #{group: 'G', event: 'BufEnter',
1176 \ pattern: '*.ts'}
1177 echo autocmd_get(acmd)
1178<
1179 Can also be used as a |method|: >
1180 Getopts()->autocmd_get()
1181<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001182 Return type: list<dict<any>>
1183
1184
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001185balloon_gettext() *balloon_gettext()*
1186 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001187 not used for the List. Returns an empty string if balloon
1188 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001189
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001190 Return type: |String|
1191
1192
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001193balloon_show({expr}) *balloon_show()*
1194 Show {expr} inside the balloon. For the GUI {expr} is used as
1195 a string. For a terminal {expr} can be a list, which contains
1196 the lines of the balloon. If {expr} is not a list it will be
1197 split with |balloon_split()|.
1198 If {expr} is an empty string any existing balloon is removed.
1199
1200 Example: >
1201 func GetBalloonContent()
1202 " ... initiate getting the content
1203 return ''
1204 endfunc
1205 set balloonexpr=GetBalloonContent()
1206
1207 func BalloonCallback(result)
1208 call balloon_show(a:result)
1209 endfunc
1210< Can also be used as a |method|: >
1211 GetText()->balloon_show()
1212<
1213 The intended use is that fetching the content of the balloon
1214 is initiated from 'balloonexpr'. It will invoke an
1215 asynchronous method, in which a callback invokes
1216 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001217 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001218
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001219 When showing a balloon is not possible then nothing happens,
1220 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001221 {only available when compiled with the |+balloon_eval| or
1222 |+balloon_eval_term| feature}
1223
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001224 Return type: |Number|
1225
1226
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001227balloon_split({msg}) *balloon_split()*
1228 Split String {msg} into lines to be displayed in a balloon.
1229 The splits are made for the current window size and optimize
1230 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001231 Returns a |List| with the split lines. Returns an empty List
1232 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001233 Can also be used as a |method|: >
1234 GetText()->balloon_split()->balloon_show()
1235
1236< {only available when compiled with the |+balloon_eval_term|
1237 feature}
1238
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001239 Return type: list<any> or list<string>
1240
h-easte80f3452025-01-02 10:40:29 +01001241base64_decode({string}) *base64_decode()*
1242 Return a Blob containing the bytes decoded from the base64
1243 encoded characters in {string}.
1244
1245 The {string} argument should contain only base64-encoded
1246 characters and should have a length that is a multiple of 4.
1247
1248 Returns an empty blob on error.
1249
1250 Examples: >
1251 " Write the decoded contents to a binary file
1252 call writefile(base64_decode(s), 'tools.bmp')
1253 " Decode a base64-encoded string
Maxim Kim6472e582025-01-15 18:31:05 +01001254 echo blob2str(base64_decode(encodedstr))
h-easte80f3452025-01-02 10:40:29 +01001255<
1256 Can also be used as a |method|: >
1257 GetEncodedString()->base64_decode()
1258<
1259 Return type: |Blob|
1260
1261
1262base64_encode({blob}) *base64_encode()*
1263 Return a base64-encoded String representing the bytes in
1264 {blob}. The base64 alphabet defined in RFC 4648 is used.
1265
1266 Examples: >
1267 " Encode the contents of a binary file
1268 echo base64_encode(readblob('somefile.bin'))
1269 " Encode a string
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001270 echo base64_encode(str2blob([somestr]))
h-easte80f3452025-01-02 10:40:29 +01001271<
1272 Can also be used as a |method|: >
1273 GetBinaryData()->base64_encode()
1274<
1275 Return type: |String|
1276
1277
Christ van Willegence0ef912024-06-20 23:41:59 +02001278bindtextdomain({package}, {path}) *bindtextdomain()*
1279 Bind a specific {package} to a {path} so that the
1280 |gettext()| function can be used to get language-specific
1281 translations for a package. {path} is the directory name
h-east52e7cc22024-07-28 17:03:29 +02001282 for the translations. See |package-translation|.
Christ van Willegence0ef912024-06-20 23:41:59 +02001283
Christ van Willegen8252ef12024-07-11 21:36:21 +02001284 Returns v:true on success and v:false on failure (out of
1285 memory).
1286
1287 Return type: |vim9-boolean|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001288
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001289blob2list({blob}) *blob2list()*
1290 Return a List containing the number value of each byte in Blob
1291 {blob}. Examples: >
1292 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1293 blob2list(0z) returns []
1294< Returns an empty List on error. |list2blob()| does the
1295 opposite.
1296
1297 Can also be used as a |method|: >
1298 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001299<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001300 Return type: list<any> or list<number>
1301
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001302
1303blob2str({blob} [, {options}]) *blob2str()*
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001304 Return a List of Strings in the current 'encoding' by
1305 converting the bytes in {blob} into characters.
1306
1307 Each <NL> byte in the blob is interpreted as the end of a
1308 string and a new list item is added. Each <NUL> byte in the
1309 blob is converted into a <NL> character.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001310
1311 If {options} is not supplied, the current 'encoding' value is
1312 used to decode the bytes in {blob}.
1313
1314 The argument {options} is a |Dict| and supports the following
1315 items:
1316 encoding Decode the bytes in {blob} using this
1317 encoding. The value is a |String|. See
Bakudankunb3854bf2025-02-23 20:29:21 +01001318 |encoding-names| for the supported values
1319 (plus the special value "none").
Christian Brabandtd5afc742025-03-18 20:55:42 +01001320 *E1515* *E1516*
Bakudankunb3854bf2025-02-23 20:29:21 +01001321 When current 'encoding' is "utf-8", an error is given and an
1322 empty List is returned if an invalid byte sequence is
1323 encountered in {blob}. To suppress this validation and get
1324 potentially invalid string, set "encoding" in {options} to
1325 "none".
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001326
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001327 Returns an empty List if blob is empty.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001328
1329 See also |str2blob()|
1330
1331 Examples: >
Hirohito Higashi932a5352025-03-23 10:20:20 +01001332 blob2str(0z6162) returns ['ab']
1333 blob2str(0zC2ABC2BB) returns ['«»']
1334 blob2str(0z610A62) returns ['a', 'b']
1335 blob2str(0z610062) returns ['a\nb']
1336 blob2str(0zABBB, {'encoding': 'latin1'}) returns ['«»']
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001337<
1338 Can also be used as a |method|: >
1339 GetBlob()->blob2str()
1340<
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001341 Return type: list<string>
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001342
1343
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001344 *browse()*
1345browse({save}, {title}, {initdir}, {default})
1346 Put up a file requester. This only works when "has("browse")"
1347 returns |TRUE| (only in some GUI versions).
1348 The input fields are:
1349 {save} when |TRUE|, select file to write
1350 {title} title for the requester
1351 {initdir} directory to start browsing in
1352 {default} default file name
1353 An empty string is returned when the "Cancel" button is hit,
1354 something went wrong, or browsing is not possible.
1355
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001356 Return type: |String|
1357
1358
1359browsedir({title}, {initdir}) *browsedir()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001360 Put up a directory requester. This only works when
1361 "has("browse")" returns |TRUE| (only in some GUI versions).
1362 On systems where a directory browser is not supported a file
1363 browser is used. In that case: select a file in the directory
1364 to be used.
1365 The input fields are:
1366 {title} title for the requester
1367 {initdir} directory to start browsing in
1368 When the "Cancel" button is hit, something went wrong, or
1369 browsing is not possible, an empty string is returned.
1370
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001371 Return type: |String|
1372
1373
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001374bufadd({name}) *bufadd()*
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001375 Add a buffer to the buffer list with name {name} (must be a
1376 String).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001377 If a buffer for file {name} already exists, return that buffer
1378 number. Otherwise return the buffer number of the newly
1379 created buffer. When {name} is an empty string then a new
1380 buffer is always created.
1381 The buffer will not have 'buflisted' set and not be loaded
1382 yet. To add some text to the buffer use this: >
1383 let bufnr = bufadd('someName')
1384 call bufload(bufnr)
1385 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001386< Returns 0 on error.
1387 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001388 let bufnr = 'somename'->bufadd()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001389<
1390 Return type: |Number|
1391
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001392
1393bufexists({buf}) *bufexists()*
1394 The result is a Number, which is |TRUE| if a buffer called
1395 {buf} exists.
1396 If the {buf} argument is a number, buffer numbers are used.
1397 Number zero is the alternate buffer for the current window.
1398
1399 If the {buf} argument is a string it must match a buffer name
1400 exactly. The name can be:
1401 - Relative to the current directory.
1402 - A full path.
1403 - The name of a buffer with 'buftype' set to "nofile".
1404 - A URL name.
1405 Unlisted buffers will be found.
1406 Note that help files are listed by their short name in the
1407 output of |:buffers|, but bufexists() requires using their
1408 long name to be able to find them.
1409 bufexists() may report a buffer exists, but to use the name
1410 with a |:buffer| command you may need to use |expand()|. Esp
1411 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1412 Use "bufexists(0)" to test for the existence of an alternate
1413 file name.
1414
1415 Can also be used as a |method|: >
1416 let exists = 'somename'->bufexists()
1417<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001418 Return type: |Number|
1419
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001420 Obsolete name: buffer_exists(). *buffer_exists()*
1421
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001422
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001423buflisted({buf}) *buflisted()*
1424 The result is a Number, which is |TRUE| if a buffer called
1425 {buf} exists and is listed (has the 'buflisted' option set).
1426 The {buf} argument is used like with |bufexists()|.
1427
1428 Can also be used as a |method|: >
1429 let listed = 'somename'->buflisted()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001430<
1431 Return type: |Number|
1432
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001433
1434bufload({buf}) *bufload()*
1435 Ensure the buffer {buf} is loaded. When the buffer name
1436 refers to an existing file then the file is read. Otherwise
1437 the buffer will be empty. If the buffer was already loaded
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001438 then there is no change. If the buffer is not related to a
Daniel Steinbergc2bd2052023-08-09 12:10:59 -04001439 file then no file is read (e.g., when 'buftype' is "nofile").
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001440 If there is an existing swap file for the file of the buffer,
1441 there will be no dialog, the buffer will be loaded anyway.
1442 The {buf} argument is used like with |bufexists()|.
1443
1444 Can also be used as a |method|: >
1445 eval 'somename'->bufload()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001446<
1447 Return type: |Number|
1448
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001449
1450bufloaded({buf}) *bufloaded()*
1451 The result is a Number, which is |TRUE| if a buffer called
1452 {buf} exists and is loaded (shown in a window or hidden).
1453 The {buf} argument is used like with |bufexists()|.
1454
1455 Can also be used as a |method|: >
1456 let loaded = 'somename'->bufloaded()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001457<
1458 Return type: |Number|
1459
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001460
1461bufname([{buf}]) *bufname()*
1462 The result is the name of a buffer. Mostly as it is displayed
1463 by the `:ls` command, but not using special names such as
1464 "[No Name]".
1465 If {buf} is omitted the current buffer is used.
1466 If {buf} is a Number, that buffer number's name is given.
1467 Number zero is the alternate buffer for the current window.
1468 If {buf} is a String, it is used as a |file-pattern| to match
1469 with the buffer names. This is always done like 'magic' is
1470 set and 'cpoptions' is empty. When there is more than one
1471 match an empty string is returned.
1472 "" or "%" can be used for the current buffer, "#" for the
1473 alternate buffer.
1474 A full match is preferred, otherwise a match at the start, end
1475 or middle of the buffer name is accepted. If you only want a
1476 full match then put "^" at the start and "$" at the end of the
1477 pattern.
1478 Listed buffers are found first. If there is a single match
1479 with a listed buffer, that one is returned. Next unlisted
1480 buffers are searched for.
1481 If the {buf} is a String, but you want to use it as a buffer
1482 number, force it to be a Number by adding zero to it: >
1483 :echo bufname("3" + 0)
1484< Can also be used as a |method|: >
1485 echo bufnr->bufname()
1486
1487< If the buffer doesn't exist, or doesn't have a name, an empty
1488 string is returned. >
1489 bufname("#") alternate buffer name
1490 bufname(3) name of buffer 3
1491 bufname("%") name of current buffer
1492 bufname("file2") name of buffer where "file2" matches.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001493<
1494 Return type: |String|
1495 *buffer_name()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001496 Obsolete name: buffer_name().
1497
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001498
1499bufnr([{buf} [, {create}]]) *bufnr()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001500 The result is the number of a buffer, as it is displayed by
1501 the `:ls` command. For the use of {buf}, see |bufname()|
1502 above.
1503
1504 If the buffer doesn't exist, -1 is returned. Or, if the
1505 {create} argument is present and TRUE, a new, unlisted,
1506 buffer is created and its number is returned. Example: >
1507 let newbuf = bufnr('Scratch001', 1)
1508< Using an empty name uses the current buffer. To create a new
1509 buffer with an empty name use |bufadd()|.
1510
1511 bufnr("$") is the last buffer: >
1512 :let last_buffer = bufnr("$")
1513< The result is a Number, which is the highest buffer number
1514 of existing buffers. Note that not all buffers with a smaller
1515 number necessarily exist, because ":bwipeout" may have removed
1516 them. Use bufexists() to test for the existence of a buffer.
1517
1518 Can also be used as a |method|: >
1519 echo bufref->bufnr()
1520<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001521 Return type: |Number|
1522
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001523 Obsolete name: buffer_number(). *buffer_number()*
1524 *last_buffer_nr()*
1525 Obsolete name for bufnr("$"): last_buffer_nr().
1526
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001527
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001528bufwinid({buf}) *bufwinid()*
1529 The result is a Number, which is the |window-ID| of the first
1530 window associated with buffer {buf}. For the use of {buf},
1531 see |bufname()| above. If buffer {buf} doesn't exist or
1532 there is no such window, -1 is returned. Example: >
1533
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001534 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001535<
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001536 Only deals with the current tab page. See |win_findbuf()| for
1537 finding more.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001538
1539 Can also be used as a |method|: >
1540 FindBuffer()->bufwinid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001541<
1542 Return type: |Number|
1543
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001544
1545bufwinnr({buf}) *bufwinnr()*
1546 Like |bufwinid()| but return the window number instead of the
1547 |window-ID|.
1548 If buffer {buf} doesn't exist or there is no such window, -1
1549 is returned. Example: >
1550
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001551 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001552
1553< The number can be used with |CTRL-W_w| and ":wincmd w"
1554 |:wincmd|.
1555
1556 Can also be used as a |method|: >
1557 FindBuffer()->bufwinnr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001558<
1559 Return type: |Number|
1560
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001561
1562byte2line({byte}) *byte2line()*
1563 Return the line number that contains the character at byte
1564 count {byte} in the current buffer. This includes the
1565 end-of-line character, depending on the 'fileformat' option
1566 for the current buffer. The first character has byte count
1567 one.
1568 Also see |line2byte()|, |go| and |:goto|.
1569
Bram Moolenaar016188f2022-06-06 20:52:59 +01001570 Returns -1 if the {byte} value is invalid.
1571
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001572 Can also be used as a |method|: >
1573 GetOffset()->byte2line()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001574<
1575 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001576
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001577 {not available when compiled without the |+byte_offset|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001578 feature}
1579
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001580
Christian Brabandt67672ef2023-04-24 21:09:54 +01001581byteidx({expr}, {nr} [, {utf16}]) *byteidx()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001582 Return byte index of the {nr}'th character in the String
1583 {expr}. Use zero for the first character, it then returns
1584 zero.
1585 If there are no multibyte characters the returned value is
1586 equal to {nr}.
1587 Composing characters are not counted separately, their byte
1588 length is added to the preceding base character. See
1589 |byteidxcomp()| below for counting composing characters
1590 separately.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001591 When {utf16} is present and TRUE, {nr} is used as the UTF-16
1592 index in the String {expr} instead of as the character index.
1593 The UTF-16 index is the index in the string when it is encoded
1594 with 16-bit words. If the specified UTF-16 index is in the
1595 middle of a character (e.g. in a 4-byte character), then the
1596 byte index of the first byte in the character is returned.
1597 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001598 Example : >
1599 echo matchstr(str, ".", byteidx(str, 3))
1600< will display the fourth character. Another way to do the
1601 same: >
1602 let s = strpart(str, byteidx(str, 3))
1603 echo strpart(s, 0, byteidx(s, 1))
1604< Also see |strgetchar()| and |strcharpart()|.
1605
1606 If there are less than {nr} characters -1 is returned.
1607 If there are exactly {nr} characters the length of the string
1608 in bytes is returned.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001609 See |charidx()| and |utf16idx()| for getting the character and
1610 UTF-16 index respectively from the byte index.
1611 Examples: >
1612 echo byteidx('a😊😊', 2) returns 5
1613 echo byteidx('a😊😊', 2, 1) returns 1
1614 echo byteidx('a😊😊', 3, 1) returns 5
1615<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001616 Can also be used as a |method|: >
1617 GetName()->byteidx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001618<
1619 Return type: |Number|
1620
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001621
Christian Brabandt67672ef2023-04-24 21:09:54 +01001622byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001623 Like byteidx(), except that a composing character is counted
1624 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001625 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001626 echo byteidx(s, 1)
1627 echo byteidxcomp(s, 1)
1628 echo byteidxcomp(s, 2)
1629< The first and third echo result in 3 ('e' plus composing
1630 character is 3 bytes), the second echo results in 1 ('e' is
1631 one byte).
1632 Only works differently from byteidx() when 'encoding' is set
1633 to a Unicode encoding.
1634
1635 Can also be used as a |method|: >
1636 GetName()->byteidxcomp(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001637<
1638 Return type: |Number|
1639
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001640
1641call({func}, {arglist} [, {dict}]) *call()* *E699*
1642 Call function {func} with the items in |List| {arglist} as
1643 arguments.
1644 {func} can either be a |Funcref| or the name of a function.
1645 a:firstline and a:lastline are set to the cursor line.
1646 Returns the return value of the called function.
1647 {dict} is for functions with the "dict" attribute. It will be
1648 used to set the local variable "self". |Dictionary-function|
1649
1650 Can also be used as a |method|: >
1651 GetFunc()->call([arg, arg], dict)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001652<
1653 Return type: any, depending on {func}
1654
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001655
1656ceil({expr}) *ceil()*
1657 Return the smallest integral value greater than or equal to
1658 {expr} as a |Float| (round up).
1659 {expr} must evaluate to a |Float| or a |Number|.
1660 Examples: >
1661 echo ceil(1.456)
1662< 2.0 >
1663 echo ceil(-5.456)
1664< -5.0 >
1665 echo ceil(4.0)
1666< 4.0
1667
Bram Moolenaar016188f2022-06-06 20:52:59 +01001668 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1669
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001670 Can also be used as a |method|: >
1671 Compute()->ceil()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001672<
1673 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001674
1675
1676ch_ functions are documented here: |channel-functions-details|
1677
1678
1679changenr() *changenr()*
1680 Return the number of the most recent change. This is the same
1681 number as what is displayed with |:undolist| and can be used
1682 with the |:undo| command.
1683 When a change was made it is the number of that change. After
1684 redo it is the number of the redone change. After undo it is
1685 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001686 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001687
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001688 Return type: |Number|
1689
1690
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001691char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001692 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001693 Examples: >
1694 char2nr(" ") returns 32
1695 char2nr("ABC") returns 65
1696< When {utf8} is omitted or zero, the current 'encoding' is used.
1697 Example for "utf-8": >
1698 char2nr("á") returns 225
1699 char2nr("á"[0]) returns 195
1700< When {utf8} is TRUE, always treat as UTF-8 characters.
1701 A combining character is a separate character.
1702 |nr2char()| does the opposite.
1703 To turn a string into a list of character numbers: >
1704 let str = "ABC"
1705 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1706< Result: [65, 66, 67]
1707
Bram Moolenaar016188f2022-06-06 20:52:59 +01001708 Returns 0 if {string} is not a |String|.
1709
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001710 Can also be used as a |method|: >
1711 GetChar()->char2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001712<
1713 Return type: |Number|
1714
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001715
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001716charclass({string}) *charclass()*
1717 Return the character class of the first character in {string}.
1718 The character class is one of:
1719 0 blank
1720 1 punctuation
Christian Brabandtb5e7da12024-11-01 09:33:00 +01001721 2 word character (depends on 'iskeyword')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001722 3 emoji
1723 other specific Unicode class
1724 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001725 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001726
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001727 Return type: |Number|
1728
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001729
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001730charcol({expr} [, {winid}]) *charcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001731 Same as |col()| but returns the character index of the column
1732 position given with {expr} instead of the byte position.
1733
1734 Example:
1735 With the cursor on '세' in line 5 with text "여보세요": >
1736 charcol('.') returns 3
1737 col('.') returns 7
1738
1739< Can also be used as a |method|: >
1740 GetPos()->col()
1741<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001742 Return type: |Number|
1743
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001744 *charidx()*
Christian Brabandt67672ef2023-04-24 21:09:54 +01001745charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001746 Return the character index of the byte at {idx} in {string}.
1747 The index of the first character is zero.
1748 If there are no multibyte characters the returned value is
1749 equal to {idx}.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001750
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001751 When {countcc} is omitted or |FALSE|, then composing characters
Christian Brabandt67672ef2023-04-24 21:09:54 +01001752 are not counted separately, their byte length is added to the
1753 preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001754 When {countcc} is |TRUE|, then composing characters are
1755 counted as separate characters.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001756
1757 When {utf16} is present and TRUE, {idx} is used as the UTF-16
1758 index in the String {expr} instead of as the byte index.
1759
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +01001760 Returns -1 if the arguments are invalid or if there are less
1761 than {idx} bytes. If there are exactly {idx} bytes the length
1762 of the string in characters is returned.
1763
1764 An error is given and -1 is returned if the first argument is
1765 not a string, the second argument is not a number or when the
1766 third argument is present and is not zero or one.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001767
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001768 See |byteidx()| and |byteidxcomp()| for getting the byte index
Christian Brabandt67672ef2023-04-24 21:09:54 +01001769 from the character index and |utf16idx()| for getting the
1770 UTF-16 index from the character index.
1771 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001772 Examples: >
1773 echo charidx('áb́ć', 3) returns 1
1774 echo charidx('áb́ć', 6, 1) returns 4
1775 echo charidx('áb́ć', 16) returns -1
Christian Brabandt67672ef2023-04-24 21:09:54 +01001776 echo charidx('a😊😊', 4, 0, 1) returns 2
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001777<
1778 Can also be used as a |method|: >
1779 GetName()->charidx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001780<
1781 Return type: |Number|
1782
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001783
1784chdir({dir}) *chdir()*
1785 Change the current working directory to {dir}. The scope of
1786 the directory change depends on the directory of the current
1787 window:
1788 - If the current window has a window-local directory
1789 (|:lcd|), then changes the window local directory.
1790 - Otherwise, if the current tabpage has a local
1791 directory (|:tcd|) then changes the tabpage local
1792 directory.
1793 - Otherwise, changes the global directory.
1794 {dir} must be a String.
1795 If successful, returns the previous working directory. Pass
1796 this to another chdir() to restore the directory.
1797 On failure, returns an empty string.
1798
1799 Example: >
1800 let save_dir = chdir(newdir)
1801 if save_dir != ""
1802 " ... do some work
1803 call chdir(save_dir)
1804 endif
1805
1806< Can also be used as a |method|: >
1807 GetDir()->chdir()
1808<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001809 Return type: |String|
1810
1811
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001812cindent({lnum}) *cindent()*
1813 Get the amount of indent for line {lnum} according the C
1814 indenting rules, as with 'cindent'.
1815 The indent is counted in spaces, the value of 'tabstop' is
1816 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001817 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001818 See |C-indenting|.
1819
1820 Can also be used as a |method|: >
1821 GetLnum()->cindent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001822<
1823 Return type: |Number|
1824
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001825
1826clearmatches([{win}]) *clearmatches()*
1827 Clears all matches previously defined for the current window
1828 by |matchadd()| and the |:match| commands.
1829 If {win} is specified, use the window with this number or
1830 window ID instead of the current window.
1831
1832 Can also be used as a |method|: >
1833 GetWin()->clearmatches()
1834<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001835 Return type: |Number|
1836
1837
Girish Palya5c3d1e32025-04-22 19:52:16 +02001838cmdcomplete_info() *cmdcomplete_info()*
Girish Palya92f68e22025-04-21 11:12:41 +02001839 Returns a |Dictionary| with information about cmdline
1840 completion. See |cmdline-completion|.
1841 The items are:
1842 cmdline_orig The original command-line string before
1843 completion began.
1844 pum_visible |TRUE| if popup menu is visible.
1845 See |pumvisible()|.
1846 matches List of all completion candidates. Each item
1847 is a string.
1848 selected Selected item index. First index is zero.
1849 Index is -1 if no item is selected (showing
1850 typed text only, or the last completion after
1851 no item is selected when using the <Up> or
1852 <Down> keys)
1853
1854 Returns an empty |Dictionary| if no completion was attempted,
1855 if there was only one candidate and it was fully completed, or
1856 if an error occurred.
1857
1858 Return type: dict<any>
1859
1860
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001861col({expr} [, {winid}]) *col()*
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001862 The result is a Number, which is the byte index of the column
zeertzjq02f3eba2024-06-12 20:45:24 +02001863 position given with {expr}.
1864 For accepted positions see |getpos()|.
zeertzjqd353d272024-06-13 23:00:25 +08001865 When {expr} is "$", it means the end of the cursor line, so
1866 the result is the number of bytes in the cursor line plus one.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001867 Additionally {expr} can be [lnum, col]: a |List| with the line
1868 and column number. Most useful when the column is "$", to get
1869 the last column of a specific line. When "lnum" or "col" is
1870 out of range then col() returns zero.
zeertzjq02f3eba2024-06-12 20:45:24 +02001871
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001872 With the optional {winid} argument the values are obtained for
1873 that window instead of the current window.
zeertzjq02f3eba2024-06-12 20:45:24 +02001874
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001875 To get the line number use |line()|. To get both use
1876 |getpos()|.
1877 For the screen column position use |virtcol()|. For the
1878 character position use |charcol()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02001879
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001880 Note that only marks in the current file can be used.
zeertzjq02f3eba2024-06-12 20:45:24 +02001881
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001882 Examples: >
1883 col(".") column of cursor
1884 col("$") length of cursor line plus one
1885 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001886 col("'" .. markname) column of mark markname
zeertzjq02f3eba2024-06-12 20:45:24 +02001887<
1888 The first column is 1. Returns 0 if {expr} is invalid or when
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001889 the window with ID {winid} is not found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001890 For an uppercase mark the column may actually be in another
1891 buffer.
1892 For the cursor position, when 'virtualedit' is active, the
1893 column is one higher if the cursor is after the end of the
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01001894 line. Also, when using a <Cmd> mapping the cursor isn't
1895 moved, this can be used to obtain the column in Insert mode: >
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001896 :imap <F2> <Cmd>echowin col(".")<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001897
1898< Can also be used as a |method|: >
1899 GetPos()->col()
1900<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001901 Return type: |Number|
1902
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001903
1904complete({startcol}, {matches}) *complete()* *E785*
1905 Set the matches for Insert mode completion.
1906 Can only be used in Insert mode. You need to use a mapping
1907 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1908 or with an expression mapping.
1909 {startcol} is the byte offset in the line where the completed
1910 text start. The text up to the cursor is the original text
1911 that will be replaced by the matches. Use col('.') for an
1912 empty string. "col('.') - 1" will replace one character by a
1913 match.
1914 {matches} must be a |List|. Each |List| item is one match.
1915 See |complete-items| for the kind of items that are possible.
1916 "longest" in 'completeopt' is ignored.
1917 Note that the after calling this function you need to avoid
1918 inserting anything that would cause completion to stop.
1919 The match can be selected with CTRL-N and CTRL-P as usual with
1920 Insert mode completion. The popup menu will appear if
1921 specified, see |ins-completion-menu|.
1922 Example: >
1923 inoremap <F5> <C-R>=ListMonths()<CR>
1924
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001925 func ListMonths()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001926 call complete(col('.'), ['January', 'February', 'March',
1927 \ 'April', 'May', 'June', 'July', 'August', 'September',
1928 \ 'October', 'November', 'December'])
1929 return ''
1930 endfunc
1931< This isn't very useful, but it shows how it works. Note that
1932 an empty string is returned to avoid a zero being inserted.
1933
1934 Can also be used as a |method|, the base is passed as the
1935 second argument: >
1936 GetMatches()->complete(col('.'))
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001937<
1938 Return type: |Number|
1939
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001940
1941complete_add({expr}) *complete_add()*
1942 Add {expr} to the list of matches. Only to be used by the
1943 function specified with the 'completefunc' option.
1944 Returns 0 for failure (empty string or out of memory),
1945 1 when the match was added, 2 when the match was already in
1946 the list.
1947 See |complete-functions| for an explanation of {expr}. It is
1948 the same as one item in the list that 'omnifunc' would return.
1949
1950 Can also be used as a |method|: >
1951 GetMoreMatches()->complete_add()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001952<
1953 Return type: |Number|
1954
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001955
1956complete_check() *complete_check()*
1957 Check for a key typed while looking for completion matches.
1958 This is to be used when looking for matches takes some time.
1959 Returns |TRUE| when searching for matches is to be aborted,
1960 zero otherwise.
1961 Only to be used by the function specified with the
1962 'completefunc' option.
1963
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001964 Return type: |Number|
1965
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001966
1967complete_info([{what}]) *complete_info()*
1968 Returns a |Dictionary| with information about Insert mode
1969 completion. See |ins-completion|.
1970 The items are:
1971 mode Current completion mode name string.
1972 See |complete_info_mode| for the values.
1973 pum_visible |TRUE| if popup menu is visible.
1974 See |pumvisible()|.
glepnird4088ed2024-12-31 10:55:22 +01001975 items List of all completion candidates. Each item
1976 is a dictionary containing the entries "word",
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001977 "abbr", "menu", "kind", "info" and "user_data".
1978 See |complete-items|.
glepnird4088ed2024-12-31 10:55:22 +01001979 matches Same as "items", but only returns items that
1980 are matching current query. If both "matches"
1981 and "items" are in "what", the returned list
1982 will still be named "items", but each item
1983 will have an additional "match" field.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001984 selected Selected item index. First index is zero.
1985 Index is -1 if no item is selected (showing
1986 typed text only, or the last completion after
1987 no item is selected when using the <Up> or
1988 <Down> keys)
glepnir037b0282025-01-16 14:37:44 +01001989 completed Return a dictionary containing the entries of
1990 the currently selected index item.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001991
1992 *complete_info_mode*
1993 mode values are:
1994 "" Not in completion mode
1995 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1996 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1997 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1998 |i_CTRL-X_CTRL-Y|
1999 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
2000 "files" File names |i_CTRL-X_CTRL-F|
2001 "tags" Tags |i_CTRL-X_CTRL-]|
2002 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
2003 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
2004 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
2005 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
2006 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
2007 "function" User defined completion |i_CTRL-X_CTRL-U|
2008 "omni" Omni completion |i_CTRL-X_CTRL-O|
2009 "spell" Spelling suggestions |i_CTRL-X_s|
2010 "eval" |complete()| completion
2011 "unknown" Other internal modes
2012
2013 If the optional {what} list argument is supplied, then only
2014 the items listed in {what} are returned. Unsupported items in
2015 {what} are silently ignored.
2016
2017 To get the position and size of the popup menu, see
2018 |pum_getpos()|. It's also available in |v:event| during the
2019 |CompleteChanged| event.
2020
Bram Moolenaar016188f2022-06-06 20:52:59 +01002021 Returns an empty |Dictionary| on error.
2022
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002023 Examples: >
2024 " Get all items
2025 call complete_info()
2026 " Get only 'mode'
2027 call complete_info(['mode'])
2028 " Get only 'mode' and 'pum_visible'
2029 call complete_info(['mode', 'pum_visible'])
2030
2031< Can also be used as a |method|: >
2032 GetItems()->complete_info()
2033<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002034 Return type: dict<any>
2035
glepnirbcd59952025-04-24 21:48:35 +02002036complete_match([{lnum}, {col}]) *complete_match()*
2037 Returns a List of matches found according to the 'isexpand'
2038 option. Each match is represented as a List containing
2039 [startcol, trigger_text] where:
2040 - startcol: column position where completion should start,
2041 or -1 if no trigger position is found. For multi-character
2042 triggers, returns the column of the first character.
2043 - trigger_text: the matching trigger string from 'isexpand',
2044 or empty string if no match was found or when using the
2045 default 'iskeyword' pattern.
2046
2047 When 'isexpand' is empty, uses the 'iskeyword' pattern
2048 "\k\+$" to find the start of the current keyword.
2049
2050 When no arguments are provided, uses the current cursor
2051 position.
2052
2053 Examples: >
2054 set isexpand=.,->,/,/*,abc
2055 func CustomComplete()
2056 let res = complete_match()
2057 if res->len() == 0 | return | endif
2058 let [col, trigger] = res[0]
2059 let items = []
2060 if trigger == '/*'
2061 let items = ['/** */']
2062 elseif trigger == '/'
2063 let items = ['/*! */', '// TODO:', '// fixme:']
2064 elseif trigger == '.'
2065 let items = ['length()']
2066 elseif trigger =~ '^\->'
2067 let items = ['map()', 'reduce()']
2068 elseif trigger =~ '^\abc'
2069 let items = ['def', 'ghk']
2070 endif
2071 if items->len() > 0
2072 let startcol = trigger =~ '^/' ? col : col + len(trigger)
2073 call complete(startcol, items)
2074 endif
2075 endfunc
2076 inoremap <Tab> <Cmd>call CustomComplete()<CR>
2077<
2078 Return type: list<list<any>>
2079
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002080 *confirm()*
2081confirm({msg} [, {choices} [, {default} [, {type}]]])
2082 confirm() offers the user a dialog, from which a choice can be
2083 made. It returns the number of the choice. For the first
2084 choice this is 1.
2085 Note: confirm() is only supported when compiled with dialog
glepnirdf461152024-04-04 22:23:29 +02002086 support, see |+dialog_con| |+dialog_con_gui| and |+dialog_gui|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002087
2088 {msg} is displayed in a |dialog| with {choices} as the
2089 alternatives. When {choices} is missing or empty, "&OK" is
2090 used (and translated).
2091 {msg} is a String, use '\n' to include a newline. Only on
2092 some systems the string is wrapped when it doesn't fit.
2093
2094 {choices} is a String, with the individual choices separated
2095 by '\n', e.g. >
2096 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2097< The letter after the '&' is the shortcut key for that choice.
2098 Thus you can type 'c' to select "Cancel". The shortcut does
2099 not need to be the first letter: >
2100 confirm("file has been modified", "&Save\nSave &All")
2101< For the console, the first letter of each choice is used as
2102 the default shortcut key. Case is ignored.
2103
2104 The optional {default} argument is the number of the choice
2105 that is made if the user hits <CR>. Use 1 to make the first
2106 choice the default one. Use 0 to not set a default. If
2107 {default} is omitted, 1 is used.
2108
2109 The optional {type} String argument gives the type of dialog.
2110 This is only used for the icon of the GTK, Mac, Motif and
2111 Win32 GUI. It can be one of these values: "Error",
2112 "Question", "Info", "Warning" or "Generic". Only the first
2113 character is relevant. When {type} is omitted, "Generic" is
2114 used.
2115
2116 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2117 or another valid interrupt key, confirm() returns 0.
2118
2119 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01002120 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002121 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01002122 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002123 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01002124 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002125 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01002126 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002127 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01002128 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002129< In a GUI dialog, buttons are used. The layout of the buttons
2130 depends on the 'v' flag in 'guioptions'. If it is included,
2131 the buttons are always put vertically. Otherwise, confirm()
2132 tries to put the buttons in one horizontal line. If they
2133 don't fit, a vertical layout is used anyway. For some systems
2134 the horizontal layout is always used.
2135
2136 Can also be used as a |method|in: >
2137 BuildMessage()->confirm("&Yes\n&No")
2138<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002139 Return type: |Number|
2140
2141
2142copy({expr}) *copy()*
2143 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002144 different from using {expr} directly.
2145 When {expr} is a |List| a shallow copy is created. This means
2146 that the original |List| can be changed without changing the
2147 copy, and vice versa. But the items are identical, thus
2148 changing an item changes the contents of both |Lists|.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01002149 A |Tuple| or |Dictionary| is copied in a similar way as a
2150 |List|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002151 Also see |deepcopy()|.
2152 Can also be used as a |method|: >
2153 mylist->copy()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002154<
2155 Return type: any, depending on {expr}
2156
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002157
2158cos({expr}) *cos()*
2159 Return the cosine of {expr}, measured in radians, as a |Float|.
2160 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002161 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002162 Examples: >
2163 :echo cos(100)
2164< 0.862319 >
2165 :echo cos(-4.01)
2166< -0.646043
2167
2168 Can also be used as a |method|: >
2169 Compute()->cos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002170<
2171 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002172
2173
2174cosh({expr}) *cosh()*
2175 Return the hyperbolic cosine of {expr} as a |Float| in the range
2176 [1, inf].
2177 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002178 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002179 Examples: >
2180 :echo cosh(0.5)
2181< 1.127626 >
2182 :echo cosh(-0.5)
2183< -1.127626
2184
2185 Can also be used as a |method|: >
2186 Compute()->cosh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002187<
2188 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002189
2190
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07002191count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002192 Return the number of times an item with value {expr} appears
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01002193 in |String|, |List|, |Tuple| or |Dictionary| {comp}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002194
2195 If {start} is given then start with the item with this index.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01002196 {start} can only be used with a |List| or a |Tuple|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002197
2198 When {ic} is given and it's |TRUE| then case is ignored.
2199
2200 When {comp} is a string then the number of not overlapping
2201 occurrences of {expr} is returned. Zero is returned when
2202 {expr} is an empty string.
2203
2204 Can also be used as a |method|: >
2205 mylist->count(val)
2206<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002207 Return type: |Number|
2208
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002209 *cscope_connection()*
2210cscope_connection([{num} , {dbpath} [, {prepend}]])
2211 Checks for the existence of a |cscope| connection. If no
2212 parameters are specified, then the function returns:
2213 0, if cscope was not available (not compiled in), or
2214 if there are no cscope connections;
2215 1, if there is at least one cscope connection.
2216
2217 If parameters are specified, then the value of {num}
2218 determines how existence of a cscope connection is checked:
2219
2220 {num} Description of existence check
2221 ----- ------------------------------
2222 0 Same as no parameters (e.g., "cscope_connection()").
2223 1 Ignore {prepend}, and use partial string matches for
2224 {dbpath}.
2225 2 Ignore {prepend}, and use exact string matches for
2226 {dbpath}.
2227 3 Use {prepend}, use partial string matches for both
2228 {dbpath} and {prepend}.
2229 4 Use {prepend}, use exact string matches for both
2230 {dbpath} and {prepend}.
2231
2232 Note: All string comparisons are case sensitive!
2233
2234 Examples. Suppose we had the following (from ":cs show"): >
2235
2236 # pid database name prepend path
2237 0 27664 cscope.out /usr/local
2238<
2239 Invocation Return Val ~
2240 ---------- ---------- >
2241 cscope_connection() 1
2242 cscope_connection(1, "out") 1
2243 cscope_connection(2, "out") 0
2244 cscope_connection(3, "out") 0
2245 cscope_connection(3, "out", "local") 1
2246 cscope_connection(4, "out") 0
2247 cscope_connection(4, "out", "local") 0
2248 cscope_connection(4, "cscope.out", "/usr/local") 1
2249<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002250 Return type: |Number|
2251
2252
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002253cursor({lnum}, {col} [, {off}]) *cursor()*
2254cursor({list})
2255 Positions the cursor at the column (byte count) {col} in the
2256 line {lnum}. The first column is one.
2257
2258 When there is one argument {list} this is used as a |List|
2259 with two, three or four item:
2260 [{lnum}, {col}]
2261 [{lnum}, {col}, {off}]
2262 [{lnum}, {col}, {off}, {curswant}]
2263 This is like the return value of |getpos()| or |getcurpos()|,
2264 but without the first item.
2265
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01002266 To position the cursor using {col} as the character count, use
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002267 |setcursorcharpos()|.
2268
2269 Does not change the jumplist.
Bram Moolenaar7c6cd442022-10-11 21:54:04 +01002270 {lnum} is used like with |getline()|, except that if {lnum} is
2271 zero, the cursor will stay in the current line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002272 If {lnum} is greater than the number of lines in the buffer,
2273 the cursor will be positioned at the last line in the buffer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002274 If {col} is greater than the number of bytes in the line,
2275 the cursor will be positioned at the last character in the
2276 line.
2277 If {col} is zero, the cursor will stay in the current column.
2278 If {curswant} is given it is used to set the preferred column
2279 for vertical movement. Otherwise {col} is used.
2280
2281 When 'virtualedit' is used {off} specifies the offset in
2282 screen columns from the start of the character. E.g., a
2283 position within a <Tab> or after the last character.
2284 Returns 0 when the position could be set, -1 otherwise.
2285
2286 Can also be used as a |method|: >
2287 GetCursorPos()->cursor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002288<
2289 Return type: |Number|
2290
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002291
2292debugbreak({pid}) *debugbreak()*
2293 Specifically used to interrupt a program being debugged. It
2294 will cause process {pid} to get a SIGTRAP. Behavior for other
2295 processes is undefined. See |terminal-debugger|.
2296 {only available on MS-Windows}
2297
Bram Moolenaar016188f2022-06-06 20:52:59 +01002298 Returns |TRUE| if successfully interrupted the program.
2299 Otherwise returns |FALSE|.
2300
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002301 Can also be used as a |method|: >
2302 GetPid()->debugbreak()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002303<
2304 Return type: |Number|
2305
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002306
2307deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
2308 Make a copy of {expr}. For Numbers and Strings this isn't
2309 different from using {expr} directly.
2310 When {expr} is a |List| a full copy is created. This means
2311 that the original |List| can be changed without changing the
2312 copy, and vice versa. When an item is a |List| or
2313 |Dictionary|, a copy for it is made, recursively. Thus
2314 changing an item in the copy does not change the contents of
2315 the original |List|.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01002316 A |Tuple| or |Dictionary| is copied in a similar way as a
2317 |List|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002318
2319 When {noref} is omitted or zero a contained |List| or
2320 |Dictionary| is only copied once. All references point to
2321 this single copy. With {noref} set to 1 every occurrence of a
2322 |List| or |Dictionary| results in a new copy. This also means
2323 that a cyclic reference causes deepcopy() to fail.
2324 *E724*
2325 Nesting is possible up to 100 levels. When there is an item
2326 that refers back to a higher level making a deep copy with
2327 {noref} set to 1 will fail.
2328 Also see |copy()|.
2329
2330 Can also be used as a |method|: >
2331 GetObject()->deepcopy()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002332<
2333 Return type: any, depending on {expr}
2334
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002335
2336delete({fname} [, {flags}]) *delete()*
2337 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002338 name {fname}.
2339
2340 This also works when {fname} is a symbolic link. The symbolic
2341 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002342
2343 When {flags} is "d": Deletes the directory by the name
2344 {fname}. This fails when directory {fname} is not empty.
2345
2346 When {flags} is "rf": Deletes the directory by the name
2347 {fname} and everything in it, recursively. BE CAREFUL!
2348 Note: on MS-Windows it is not possible to delete a directory
2349 that is being used.
2350
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002351 The result is a Number, which is 0/false if the delete
2352 operation was successful and -1/true when the deletion failed
2353 or partly failed.
2354
2355 Use |remove()| to delete an item from a |List|.
2356 To delete a line from the buffer use |:delete| or
2357 |deletebufline()|.
2358
2359 Can also be used as a |method|: >
2360 GetName()->delete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002361<
2362 Return type: |Number|
2363
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002364
2365deletebufline({buf}, {first} [, {last}]) *deletebufline()*
2366 Delete lines {first} to {last} (inclusive) from buffer {buf}.
2367 If {last} is omitted then delete line {first} only.
2368 On success 0 is returned, on failure 1 is returned.
2369
2370 This function works only for loaded buffers. First call
2371 |bufload()| if needed.
2372
2373 For the use of {buf}, see |bufname()| above.
2374
2375 {first} and {last} are used like with |getline()|. Note that
2376 when using |line()| this refers to the current buffer. Use "$"
2377 to refer to the last line in buffer {buf}.
2378
2379 Can also be used as a |method|: >
2380 GetBuffer()->deletebufline(1)
2381<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002382 Return type: |Number|
2383
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002384 *did_filetype()*
2385did_filetype() Returns |TRUE| when autocommands are being executed and the
2386 FileType event has been triggered at least once. Can be used
2387 to avoid triggering the FileType event again in the scripts
2388 that detect the file type. |FileType|
2389 Returns |FALSE| when `:setf FALLBACK` was used.
2390 When editing another file, the counter is reset, thus this
2391 really checks if the FileType event has been triggered for the
2392 current buffer. This allows an autocommand that starts
2393 editing another buffer to set 'filetype' and load a syntax
2394 file.
2395
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002396 Return type: |Number|
2397
2398
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002399diff({fromlist}, {tolist} [, {options}]) *diff()*
2400 Returns a String or a List containing the diff between the
2401 strings in {fromlist} and {tolist}. Uses the Vim internal
2402 diff library to compute the diff.
2403
2404 *E106*
2405 The optional "output" item in {options} specifies the returned
2406 diff format. The following values are supported:
2407 indices Return a List of the starting and ending
2408 indices and a count of the strings in each
2409 diff hunk.
2410 unified Return the unified diff output as a String.
2411 This is the default.
2412
2413 If the "output" item in {options} is "indices", then a List is
2414 returned. Each List item contains a Dict with the following
2415 items for each diff hunk:
2416 from_idx start index in {fromlist} for this diff hunk.
2417 from_count number of strings in {fromlist} that are
2418 added/removed/modified in this diff hunk.
2419 to_idx start index in {tolist} for this diff hunk.
2420 to_count number of strings in {tolist} that are
2421 added/removed/modified in this diff hunk.
2422
2423 The {options} Dict argument also specifies diff options
2424 (similar to 'diffopt') and supports the following items:
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002425 algorithm Dict specifying the diff algorithm to
2426 use. Supported boolean items are
2427 "myers", "minimal", "patience" and
2428 "histogram".
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002429 context diff context length. Default is 0.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002430 iblank ignore changes where lines are all
2431 blank.
2432 icase ignore changes in case of text.
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002433 indent-heuristic use the indent heuristic for the
2434 internal diff library.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002435 iwhite ignore changes in amount of white
2436 space.
2437 iwhiteall ignore all white space changes.
2438 iwhiteeol ignore white space changes at end of
2439 line.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002440 For more information about these options, refer to 'diffopt'.
2441
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002442 To compute the unified diff, all the items in {fromlist} are
2443 concatenated into a string using a newline separator and the
2444 same for {tolist}. The unified diff output uses line numbers.
2445
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002446 Returns an empty List or String if {fromlist} and {tolist} are
2447 identical.
2448
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002449 Examples: >
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002450 :echo diff(['abc'], ['xxx'])
2451 @@ -1 +1 @@
2452 -abc
2453 +xxx
2454
2455 :echo diff(['abc'], ['xxx'], {'output': 'indices'})
2456 [{'from_idx': 0, 'from_count': 1, 'to_idx': 0, 'to_count': 1}]
2457 :echo diff(readfile('oldfile'), readfile('newfile'))
2458 :echo diff(getbufline(5, 1, '$'), getbufline(6, 1, '$'))
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002459<
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002460 For more examples, refer to |diff-func-examples|
2461
2462 Can also be used as a |method|: >
2463 GetFromList->diff(to_list)
2464<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002465 Return type: |String| or list<dict<number>> or list<any>
2466 depending on {options}
2467
2468
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002469diff_filler({lnum}) *diff_filler()*
2470 Returns the number of filler lines above line {lnum}.
2471 These are the lines that were inserted at this point in
2472 another diff'ed window. These filler lines are shown in the
2473 display but don't exist in the buffer.
2474 {lnum} is used like with |getline()|. Thus "." is the current
2475 line, "'m" mark m, etc.
2476 Returns 0 if the current window is not in diff mode.
2477
2478 Can also be used as a |method|: >
2479 GetLnum()->diff_filler()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002480<
2481 Return type: |Number|
2482
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002483
2484diff_hlID({lnum}, {col}) *diff_hlID()*
2485 Returns the highlight ID for diff mode at line {lnum} column
2486 {col} (byte index). When the current line does not have a
2487 diff change zero is returned.
2488 {lnum} is used like with |getline()|. Thus "." is the current
2489 line, "'m" mark m, etc.
2490 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2491 line.
2492 The highlight ID can be used with |synIDattr()| to obtain
2493 syntax information about the highlighting.
2494
2495 Can also be used as a |method|: >
2496 GetLnum()->diff_hlID(col)
2497<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002498 Return type: |Number|
2499
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002500
2501digraph_get({chars}) *digraph_get()* *E1214*
2502 Return the digraph of {chars}. This should be a string with
2503 exactly two characters. If {chars} are not just two
2504 characters, or the digraph of {chars} does not exist, an error
2505 is given and an empty string is returned.
2506
2507 The character will be converted from Unicode to 'encoding'
2508 when needed. This does require the conversion to be
2509 available, it might fail.
2510
2511 Also see |digraph_getlist()|.
2512
2513 Examples: >
2514 " Get a built-in digraph
2515 :echo digraph_get('00') " Returns '∞'
2516
2517 " Get a user-defined digraph
2518 :call digraph_set('aa', 'あ')
2519 :echo digraph_get('aa') " Returns 'あ'
2520<
2521 Can also be used as a |method|: >
2522 GetChars()->digraph_get()
2523<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002524 Return type: |String|
2525
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002526 This function works only when compiled with the |+digraphs|
2527 feature. If this feature is disabled, this function will
2528 display an error message.
2529
2530
2531digraph_getlist([{listall}]) *digraph_getlist()*
2532 Return a list of digraphs. If the {listall} argument is given
2533 and it is TRUE, return all digraphs, including the default
2534 digraphs. Otherwise, return only user-defined digraphs.
2535
2536 The characters will be converted from Unicode to 'encoding'
2537 when needed. This does require the conservation to be
2538 available, it might fail.
2539
2540 Also see |digraph_get()|.
2541
2542 Examples: >
2543 " Get user-defined digraphs
2544 :echo digraph_getlist()
2545
2546 " Get all the digraphs, including default digraphs
2547 :echo digraph_getlist(1)
2548<
2549 Can also be used as a |method|: >
2550 GetNumber()->digraph_getlist()
2551<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002552 Return type: list<list<string>>
2553
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002554 This function works only when compiled with the |+digraphs|
2555 feature. If this feature is disabled, this function will
2556 display an error message.
2557
2558
Bram Moolenaara2baa732022-02-04 16:09:54 +00002559digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002560 Add digraph {chars} to the list. {chars} must be a string
2561 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002562 encoded character. *E1215*
2563 Be careful, composing characters are NOT ignored. This
2564 function is similar to |:digraphs| command, but useful to add
2565 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002566
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002567 The function returns v:true if |digraph| is registered. If
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002568 this fails an error message is given and v:false is returned.
2569
2570 If you want to define multiple digraphs at once, you can use
2571 |digraph_setlist()|.
2572
2573 Example: >
2574 call digraph_set(' ', 'あ')
2575<
2576 Can be used as a |method|: >
2577 GetString()->digraph_set('あ')
2578<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002579 Return type: |vim9-boolean|
2580
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002581 This function works only when compiled with the |+digraphs|
2582 feature. If this feature is disabled, this function will
2583 display an error message.
2584
2585
2586digraph_setlist({digraphlist}) *digraph_setlist()*
2587 Similar to |digraph_set()| but this function can add multiple
2588 digraphs at once. {digraphlist} is a list composed of lists,
2589 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002590 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002591 Example: >
2592 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2593<
2594 It is similar to the following: >
2595 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2596 call digraph_set(chars, digraph)
2597 endfor
2598< Except that the function returns after the first error,
2599 following digraphs will not be added.
2600
2601 Can be used as a |method|: >
2602 GetList()->digraph_setlist()
2603<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002604 Return type: |vim9-boolean|
2605
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002606 This function works only when compiled with the |+digraphs|
2607 feature. If this feature is disabled, this function will
2608 display an error message.
2609
2610
2611echoraw({string}) *echoraw()*
2612 Output {string} as-is, including unprintable characters.
2613 This can be used to output a terminal code. For example, to
2614 disable modifyOtherKeys: >
2615 call echoraw(&t_TE)
2616< and to enable it again: >
2617 call echoraw(&t_TI)
2618< Use with care, you can mess up the terminal this way.
2619
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002620 Return type: |Number|
2621
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002622
2623empty({expr}) *empty()*
2624 Return the Number 1 if {expr} is empty, zero otherwise.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01002625 - A |List|, |Tuple| or |Dictionary| is empty when it does
2626 not have any items.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002627 - A |String| is empty when its length is zero.
2628 - A |Number| and |Float| are empty when their value is zero.
2629 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2630 - A |Job| is empty when it failed to start.
2631 - A |Channel| is empty when it is closed.
2632 - A |Blob| is empty when its length is zero.
mityu7f0bba22024-03-29 10:14:41 +01002633 - An |Object| is empty, when the empty() method in the object
2634 (if present) returns true. |object-empty()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002635
2636 For a long |List| this is much faster than comparing the
2637 length with zero.
2638
2639 Can also be used as a |method|: >
2640 mylist->empty()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002641<
2642 Return type: |Number|
2643
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002644
2645environ() *environ()*
2646 Return all of environment variables as dictionary. You can
2647 check if an environment variable exists like this: >
2648 :echo has_key(environ(), 'HOME')
2649< Note that the variable name may be CamelCase; to ignore case
2650 use this: >
2651 :echo index(keys(environ()), 'HOME', 0, 1) != -1
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002652<
2653 Return type: dict<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002654
Bram Moolenaar416bd912023-07-07 23:19:18 +01002655
2656err_teapot([{expr}]) *err_teapot()*
2657 Produce an error with number 418, needed for implementation of
Christian Brabandtee17b6f2023-09-09 11:23:50 +02002658 RFC 2324.
Bram Moolenaar416bd912023-07-07 23:19:18 +01002659 If {expr} is present and it is TRUE error 503 is given,
2660 indicating that coffee is temporarily not available.
2661 If {expr} is present it must be a String.
2662
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002663 Return type: |Number|
2664
Bram Moolenaar416bd912023-07-07 23:19:18 +01002665
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002666escape({string}, {chars}) *escape()*
2667 Escape the characters in {chars} that occur in {string} with a
2668 backslash. Example: >
2669 :echo escape('c:\program files\vim', ' \')
2670< results in: >
2671 c:\\program\ files\\vim
2672< Also see |shellescape()| and |fnameescape()|.
2673
2674 Can also be used as a |method|: >
2675 GetText()->escape(' \')
2676<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002677 Return type: |String|
2678
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002679 *eval()*
2680eval({string}) Evaluate {string} and return the result. Especially useful to
2681 turn the result of |string()| back into the original value.
2682 This works for Numbers, Floats, Strings, Blobs and composites
2683 of them. Also works for |Funcref|s that refer to existing
Aliaksei Budavei95740222024-04-04 23:05:33 +03002684 functions. In |Vim9| script, it can be used to obtain |enum|
2685 values from their fully qualified names.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002686
2687 Can also be used as a |method|: >
2688 argv->join()->eval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002689<
2690 Return type: any, depending on {string}
2691
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002692
2693eventhandler() *eventhandler()*
2694 Returns 1 when inside an event handler. That is that Vim got
2695 interrupted while waiting for the user to type a character,
2696 e.g., when dropping a file on Vim. This means interactive
2697 commands cannot be used. Otherwise zero is returned.
2698
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002699 Return type: |Number|
2700
2701
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002702executable({expr}) *executable()*
2703 This function checks if an executable with the name {expr}
2704 exists. {expr} must be the name of the program without any
2705 arguments.
zeertzjq0cc5dce2024-08-08 21:12:15 +02002706
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002707 executable() uses the value of $PATH and/or the normal
zeertzjq0cc5dce2024-08-08 21:12:15 +02002708 searchpath for programs.
2709 *PATHEXT*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002710 On MS-Windows the ".exe", ".bat", etc. can optionally be
2711 included. Then the extensions in $PATHEXT are tried. Thus if
2712 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2713 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2714 by itself can be used in $PATHEXT to try using the name
2715 without an extension. When 'shell' looks like a Unix shell,
2716 then the name is also tried without adding an extension.
2717 On MS-Windows it only checks if the file exists and is not a
2718 directory, not if it's really executable.
zeertzjq0cc5dce2024-08-08 21:12:15 +02002719 On MS-Windows an executable in the same directory as the Vim
2720 executable is always found. Since this directory is added to
2721 $PATH it should also work to execute it |win32-PATH|.
2722 *NoDefaultCurrentDirectoryInExePath*
2723 On MS-Windows an executable in Vim's current working directory
2724 is also normally found, but this can be disabled by setting
2725 the $NoDefaultCurrentDirectoryInExePath environment variable.
2726
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002727 The result is a Number:
2728 1 exists
2729 0 does not exist
2730 -1 not implemented on this system
2731 |exepath()| can be used to get the full path of an executable.
2732
2733 Can also be used as a |method|: >
2734 GetCommand()->executable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002735<
2736 Return type: |Number|
2737
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002738
2739execute({command} [, {silent}]) *execute()*
2740 Execute an Ex command or commands and return the output as a
2741 string.
2742 {command} can be a string or a List. In case of a List the
2743 lines are executed one by one.
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002744 This is more or less equivalent to: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002745 redir => var
2746 {command}
2747 redir END
Bram Moolenaar71badf92023-04-22 22:40:14 +01002748< Except that line continuation in {command} is not recognized.
2749
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002750 The optional {silent} argument can have these values:
2751 "" no `:silent` used
2752 "silent" `:silent` used
2753 "silent!" `:silent!` used
2754 The default is "silent". Note that with "silent!", unlike
2755 `:redir`, error messages are dropped. When using an external
2756 command the screen may be messed up, use `system()` instead.
2757 *E930*
2758 It is not possible to use `:redir` anywhere in {command}.
2759
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002760 To get a list of lines use `split()` on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002761 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002762
2763< To execute a command in another window than the current one
2764 use `win_execute()`.
2765
2766 When used recursively the output of the recursive call is not
2767 included in the output of the higher level call.
2768
2769 Can also be used as a |method|: >
2770 GetCommand()->execute()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002771<
Marius Gedminasc98bfb92024-06-19 19:59:23 +02002772 Return type: |String|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002773
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002774
2775exepath({expr}) *exepath()*
2776 If {expr} is an executable and is either an absolute path, a
2777 relative path or found in $PATH, return the full path.
2778 Note that the current directory is used when {expr} starts
2779 with "./", which may be a problem for Vim: >
2780 echo exepath(v:progpath)
2781< If {expr} cannot be found in $PATH or is not executable then
2782 an empty string is returned.
2783
2784 Can also be used as a |method|: >
2785 GetCommand()->exepath()
2786<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002787 Return type: |String|
2788
2789
2790exists({expr}) *exists()*
2791 The result is a Number, which is |TRUE| if {expr} is defined,
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002792 zero otherwise.
2793
2794 Note: In a compiled |:def| function the evaluation is done at
2795 runtime. Use `exists_compiled()` to evaluate the expression
2796 at compile time.
2797
2798 For checking for a supported feature use |has()|.
2799 For checking if a file exists use |filereadable()|.
2800
2801 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002802 varname internal variable (see
2803 dict.key |internal-variables|). Also works
2804 list[i] for |curly-braces-names|, |Dictionary|
Yegappan Lakshmanana2ebb6e2024-02-25 08:40:10 +01002805 import.Func entries, |List| items, class and
2806 class.Func object methods, imported items, etc.
2807 object.Func Does not work for local variables in a
2808 class.varname compiled `:def` function.
2809 object.varname Also works for a function in |Vim9|
Bram Moolenaar944697a2022-02-20 19:48:20 +00002810 script, since it can be used as a
2811 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002812 Beware that evaluating an index may
2813 cause an error message for an invalid
2814 expression. E.g.: >
2815 :let l = [1, 2, 3]
2816 :echo exists("l[5]")
2817< 0 >
2818 :echo exists("l[xx]")
2819< E121: Undefined variable: xx
2820 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002821 &option-name Vim option (only checks if it exists,
2822 not if it really works)
2823 +option-name Vim option that works.
2824 $ENVNAME environment variable (could also be
2825 done by comparing with an empty
2826 string)
2827 *funcname built-in function (see |functions|)
2828 or user defined function (see
2829 |user-functions|) that is implemented.
2830 Also works for a variable that is a
2831 Funcref.
2832 ?funcname built-in function that could be
2833 implemented; to be used to check if
2834 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002835 :cmdname Ex command: built-in command, user
2836 command or command modifier |:command|.
2837 Returns:
2838 1 for match with start of a command
2839 2 full match with a command
2840 3 matches several user commands
2841 To check for a supported command
2842 always check the return value to be 2.
2843 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002844 :3match The |:3match| command (but you
2845 probably should not use it, it is
2846 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002847 #event autocommand defined for this event
2848 #event#pattern autocommand defined for this event and
2849 pattern (the pattern is taken
2850 literally and compared to the
2851 autocommand patterns character by
2852 character)
2853 #group autocommand group exists
2854 #group#event autocommand defined for this group and
2855 event.
2856 #group#event#pattern
2857 autocommand defined for this group,
2858 event and pattern.
2859 ##event autocommand for this event is
2860 supported.
2861
2862 Examples: >
2863 exists("&shortname")
2864 exists("$HOSTNAME")
2865 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002866 exists("*s:MyFunc") " only for legacy script
2867 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002868 exists("bufcount")
2869 exists(":Make")
2870 exists("#CursorHold")
2871 exists("#BufReadPre#*.gz")
2872 exists("#filetypeindent")
2873 exists("#filetypeindent#FileType")
2874 exists("#filetypeindent#FileType#*")
2875 exists("##ColorScheme")
2876< There must be no space between the symbol (&/$/*/#) and the
2877 name.
2878 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002879 a few cases this is ignored. That may become stricter in the
2880 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002881 Working example: >
2882 exists(":make")
2883< NOT working example: >
2884 exists(":make install")
2885
2886< Note that the argument must be a string, not the name of the
2887 variable itself. For example: >
2888 exists(bufcount)
2889< This doesn't check for existence of the "bufcount" variable,
2890 but gets the value of "bufcount", and checks if that exists.
2891
2892 Can also be used as a |method|: >
2893 Varname()->exists()
2894<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002895 Return type: |String|
2896
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002897
2898exists_compiled({expr}) *exists_compiled()*
2899 Like `exists()` but evaluated at compile time. This is useful
2900 to skip a block where a function is used that would otherwise
2901 give an error: >
2902 if exists_compiled('*ThatFunction')
2903 ThatFunction('works')
2904 endif
2905< If `exists()` were used then a compilation error would be
2906 given if ThatFunction() is not defined.
2907
2908 {expr} must be a literal string. *E1232*
2909 Can only be used in a |:def| function. *E1233*
2910 This does not work to check for arguments or local variables.
2911
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002912 Return type: |String|
2913
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002914
2915exp({expr}) *exp()*
2916 Return the exponential of {expr} as a |Float| in the range
2917 [0, inf].
2918 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002919 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002920 Examples: >
2921 :echo exp(2)
2922< 7.389056 >
2923 :echo exp(-1)
2924< 0.367879
2925
2926 Can also be used as a |method|: >
2927 Compute()->exp()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002928<
2929 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002930
2931
2932expand({string} [, {nosuf} [, {list}]]) *expand()*
2933 Expand wildcards and the following special keywords in
2934 {string}. 'wildignorecase' applies.
2935
2936 If {list} is given and it is |TRUE|, a List will be returned.
2937 Otherwise the result is a String and when there are several
2938 matches, they are separated by <NL> characters. [Note: in
2939 version 5.0 a space was used, which caused problems when a
2940 file name contains a space]
2941
2942 If the expansion fails, the result is an empty string. A name
2943 for a non-existing file is not included, unless {string} does
2944 not start with '%', '#' or '<', see below.
2945
Christian Brabandtec9c3262024-02-21 20:40:05 +01002946 For a |:terminal| window '%' expands to a '!' followed by
h-east53753f62024-05-05 18:42:31 +02002947 the command or shell that is run. |terminal-bufname|
Christian Brabandtec9c3262024-02-21 20:40:05 +01002948
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002949 When {string} starts with '%', '#' or '<', the expansion is
2950 done like for the |cmdline-special| variables with their
2951 associated modifiers. Here is a short overview:
2952
2953 % current file name
2954 # alternate file name
2955 #n alternate file name n
2956 <cfile> file name under the cursor
2957 <afile> autocmd file name
2958 <abuf> autocmd buffer number (as a String!)
2959 <amatch> autocmd matched name
2960 <cexpr> C expression under the cursor
2961 <sfile> sourced script file or function name
2962 <slnum> sourced script line number or function
2963 line number
2964 <sflnum> script file line number, also when in
2965 a function
2966 <SID> "<SNR>123_" where "123" is the
2967 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002968 <script> sourced script file, or script file
2969 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002970 <stack> call stack
2971 <cword> word under the cursor
2972 <cWORD> WORD under the cursor
2973 <client> the {clientid} of the last received
2974 message |server2client()|
2975 Modifiers:
2976 :p expand to full path
2977 :h head (last path component removed)
2978 :t tail (last path component only)
2979 :r root (one extension removed)
2980 :e extension only
2981
2982 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002983 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002984< Note that when expanding a string that starts with '%', '#' or
2985 '<', any following text is ignored. This does NOT work: >
2986 :let doesntwork = expand("%:h.bak")
2987< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002988 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002989< Also note that expanding "<cfile>" and others only returns the
2990 referenced file name without further expansion. If "<cfile>"
2991 is "~/.cshrc", you need to do another expand() to have the
2992 "~/" expanded into the path of the home directory: >
2993 :echo expand(expand("<cfile>"))
2994<
2995 There cannot be white space between the variables and the
2996 following modifier. The |fnamemodify()| function can be used
2997 to modify normal file names.
2998
2999 When using '%' or '#', and the current or alternate file name
3000 is not defined, an empty string is used. Using "%:p" in a
3001 buffer with no name, results in the current directory, with a
3002 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01003003 When 'verbose' is set then expanding '%', '#' and <> items
3004 will result in an error message if the argument cannot be
3005 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003006
3007 When {string} does not start with '%', '#' or '<', it is
3008 expanded like a file name is expanded on the command line.
3009 'suffixes' and 'wildignore' are used, unless the optional
3010 {nosuf} argument is given and it is |TRUE|.
3011 Names for non-existing files are included. The "**" item can
3012 be used to search in a directory tree. For example, to find
3013 all "README" files in the current directory and below: >
3014 :echo expand("**/README")
3015<
3016 expand() can also be used to expand variables and environment
3017 variables that are only known in a shell. But this can be
3018 slow, because a shell may be used to do the expansion. See
3019 |expr-env-expand|.
3020 The expanded variable is still handled like a list of file
3021 names. When an environment variable cannot be expanded, it is
3022 left unchanged. Thus ":echo expand('$FOOBAR')" results in
3023 "$FOOBAR".
3024
3025 See |glob()| for finding existing files. See |system()| for
3026 getting the raw output of an external command.
3027
3028 Can also be used as a |method|: >
3029 Getpattern()->expand()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003030<
3031 Return type: |String| or list<string> depending on {list}
3032
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003033
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01003034expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003035 Expand special items in String {string} like what is done for
3036 an Ex command such as `:edit`. This expands special keywords,
3037 like with |expand()|, and environment variables, anywhere in
3038 {string}. "~user" and "~/path" are only expanded at the
3039 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01003040
3041 The following items are supported in the {options} Dict
3042 argument:
3043 errmsg If set to TRUE, error messages are displayed
3044 if an error is encountered during expansion.
3045 By default, error messages are not displayed.
3046
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01003047 Returns the expanded string. If an error is encountered
3048 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01003049
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01003050 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003051 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01003052 make /path/runtime/doc/builtin.o
3053 :echo expandcmd('make %<.o', {'errmsg': v:true})
3054<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01003055 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003056 GetCommand()->expandcmd()
3057<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003058 Return type: |String| or list<string> depending on {list}
3059
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003060extend({expr1}, {expr2} [, {expr3}]) *extend()*
3061 {expr1} and {expr2} must be both |Lists| or both
3062 |Dictionaries|.
3063
3064 If they are |Lists|: Append {expr2} to {expr1}.
3065 If {expr3} is given insert the items of {expr2} before the
3066 item with index {expr3} in {expr1}. When {expr3} is zero
3067 insert before the first item. When {expr3} is equal to
3068 len({expr1}) then {expr2} is appended.
3069 Examples: >
3070 :echo sort(extend(mylist, [7, 5]))
3071 :call extend(mylist, [2, 3], 1)
3072< When {expr1} is the same List as {expr2} then the number of
3073 items copied is equal to the original length of the List.
3074 E.g., when {expr3} is 1 you get N new copies of the first item
3075 (where N is the original length of the List).
3076 Use |add()| to concatenate one item to a list. To concatenate
3077 two lists into a new list use the + operator: >
3078 :let newlist = [1, 2, 3] + [4, 5]
3079<
3080 If they are |Dictionaries|:
3081 Add all entries from {expr2} to {expr1}.
3082 If a key exists in both {expr1} and {expr2} then {expr3} is
3083 used to decide what to do:
3084 {expr3} = "keep": keep the value of {expr1}
3085 {expr3} = "force": use the value of {expr2}
3086 {expr3} = "error": give an error message *E737*
3087 When {expr3} is omitted then "force" is assumed.
3088
3089 {expr1} is changed when {expr2} is not empty. If necessary
Christian Brabandt5647c912025-02-17 21:33:30 +01003090 make a copy of {expr1} first or use |extendnew()| to return a
3091 new List/Dictionary.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003092 {expr2} remains unchanged.
3093 When {expr1} is locked and {expr2} is not empty the operation
3094 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003095 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003096
3097 Can also be used as a |method|: >
3098 mylist->extend(otherlist)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003099<
3100 Return type: list<{type}> or dict<{type}> depending on {expr1}
3101 and {expr2}, in case of error: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003102
3103
3104extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
3105 Like |extend()| but instead of adding items to {expr1} a new
3106 List or Dictionary is created and returned. {expr1} remains
Bram Moolenaardd60c362023-02-27 15:49:53 +00003107 unchanged.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003108
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003109 Return type: list<{type}> or dict<{type}> depending on {expr1}
3110 and {expr2}, in case of error: |Number|
3111
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003112
3113feedkeys({string} [, {mode}]) *feedkeys()*
3114 Characters in {string} are queued for processing as if they
3115 come from a mapping or were typed by the user.
3116
3117 By default the string is added to the end of the typeahead
3118 buffer, thus if a mapping is still being executed the
3119 characters come after them. Use the 'i' flag to insert before
3120 other characters, they will be executed next, before any
3121 characters from a mapping.
3122
3123 The function does not wait for processing of keys contained in
3124 {string}.
3125
3126 To include special keys into {string}, use double-quotes
3127 and "\..." notation |expr-quote|. For example,
3128 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
3129 feedkeys('\<CR>') pushes 5 characters.
3130 A special code that might be useful is <Ignore>, it exits the
3131 wait for a character without doing anything. *<Ignore>*
3132
3133 {mode} is a String, which can contain these character flags:
3134 'm' Remap keys. This is default. If {mode} is absent,
3135 keys are remapped.
3136 'n' Do not remap keys.
3137 't' Handle keys as if typed; otherwise they are handled as
3138 if coming from a mapping. This matters for undo,
3139 opening folds, etc.
3140 'L' Lowlevel input. Only works for Unix or when using the
3141 GUI. Keys are used as if they were coming from the
3142 terminal. Other flags are not used. *E980*
3143 When a CTRL-C interrupts and 't' is included it sets
3144 the internal "got_int" flag.
3145 'i' Insert the string instead of appending (see above).
3146 'x' Execute commands until typeahead is empty. This is
3147 similar to using ":normal!". You can call feedkeys()
3148 several times without 'x' and then one time with 'x'
3149 (possibly with an empty {string}) to execute all the
3150 typeahead. Note that when Vim ends in Insert mode it
3151 will behave as if <Esc> is typed, to avoid getting
3152 stuck, waiting for a character to be typed before the
3153 script continues.
3154 Note that if you manage to call feedkeys() while
3155 executing commands, thus calling it recursively, then
3156 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00003157 'c' Remove any script context when executing, so that
3158 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01003159 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01003160 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003161 '!' When used with 'x' will not end Insert mode. Can be
3162 used in a test when a timer is set to exit Insert mode
3163 a little later. Useful for testing CursorHoldI.
3164
3165 Return value is always 0.
3166
3167 Can also be used as a |method|: >
3168 GetInput()->feedkeys()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003169<
3170 Return type: |String| or list<string> depending on {list}
3171
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003172
Shougo Matsushita60c87432024-06-03 22:59:27 +02003173filecopy({from}, {to}) *filecopy()*
3174 Copy the file pointed to by the name {from} to {to}. The
3175 result is a Number, which is |TRUE| if the file was copied
3176 successfully, and |FALSE| when it failed.
3177 If a file with name {to} already exists, it will fail.
3178 Note that it does not handle directories (yet).
3179
3180 This function is not available in the |sandbox|.
3181
3182 Can also be used as a |method|: >
3183 GetOldName()->filecopy(newname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003184<
3185 Return type: |Number|
3186
Shougo Matsushita60c87432024-06-03 22:59:27 +02003187
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003188filereadable({file}) *filereadable()*
3189 The result is a Number, which is |TRUE| when a file with the
3190 name {file} exists, and can be read. If {file} doesn't exist,
3191 or is a directory, the result is |FALSE|. {file} is any
3192 expression, which is used as a String.
3193 If you don't care about the file being readable you can use
3194 |glob()|.
3195 {file} is used as-is, you may want to expand wildcards first: >
3196 echo filereadable('~/.vimrc')
3197 0
3198 echo filereadable(expand('~/.vimrc'))
3199 1
3200
3201< Can also be used as a |method|: >
3202 GetName()->filereadable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003203<
3204 Return type: |Number|
3205
3206 *file_readable()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003207 Obsolete name: file_readable().
3208
3209
3210filewritable({file}) *filewritable()*
3211 The result is a Number, which is 1 when a file with the
3212 name {file} exists, and can be written. If {file} doesn't
3213 exist, or is not writable, the result is 0. If {file} is a
3214 directory, and we can write to it, the result is 2.
3215
3216 Can also be used as a |method|: >
3217 GetName()->filewritable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003218<
3219 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003220
3221
3222filter({expr1}, {expr2}) *filter()*
3223 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
3224 For each item in {expr1} evaluate {expr2} and when the result
3225 is zero or false remove the item from the |List| or
3226 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003227 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003228
3229 {expr2} must be a |string| or |Funcref|.
3230
3231 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3232 of the current item. For a |Dictionary| |v:key| has the key
3233 of the current item and for a |List| |v:key| has the index of
3234 the current item. For a |Blob| |v:key| has the index of the
3235 current byte. For a |String| |v:key| has the index of the
3236 current character.
3237 Examples: >
3238 call filter(mylist, 'v:val !~ "OLD"')
3239< Removes the items where "OLD" appears. >
3240 call filter(mydict, 'v:key >= 8')
3241< Removes the items with a key below 8. >
3242 call filter(var, 0)
3243< Removes all the items, thus clears the |List| or |Dictionary|.
3244
3245 Note that {expr2} is the result of expression and is then
3246 used as an expression again. Often it is good to use a
3247 |literal-string| to avoid having to double backslashes.
3248
3249 If {expr2} is a |Funcref| it must take two arguments:
3250 1. the key or the index of the current item.
3251 2. the value of the current item.
3252 The function must return |TRUE| if the item should be kept.
3253 Example that keeps the odd items of a list: >
3254 func Odd(idx, val)
3255 return a:idx % 2 == 1
3256 endfunc
3257 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003258< It is shorter when using a |lambda|. In |Vim9| syntax: >
3259 call filter(myList, (idx, val) => idx * val <= 42)
3260< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003261 call filter(myList, {idx, val -> idx * val <= 42})
3262< If you do not use "val" you can leave it out: >
3263 call filter(myList, {idx -> idx % 2 == 1})
3264<
3265 In |Vim9| script the result must be true, false, zero or one.
3266 Other values will result in a type error.
3267
3268 For a |List| and a |Dictionary| the operation is done
3269 in-place. If you want it to remain unmodified make a copy
3270 first: >
3271 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
3272
3273< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00003274 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003275 When an error is encountered while evaluating {expr2} no
3276 further items in {expr1} are processed.
3277 When {expr2} is a Funcref errors inside a function are ignored,
3278 unless it was defined with the "abort" flag.
3279
3280 Can also be used as a |method|: >
3281 mylist->filter(expr2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003282<
3283 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
3284 depending on {expr1}
3285
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003286
3287finddir({name} [, {path} [, {count}]]) *finddir()*
3288 Find directory {name} in {path}. Supports both downwards and
3289 upwards recursive directory searches. See |file-searching|
3290 for the syntax of {path}.
3291
3292 Returns the path of the first found match. When the found
3293 directory is below the current directory a relative path is
3294 returned. Otherwise a full path is returned.
3295 If {path} is omitted or empty then 'path' is used.
3296
3297 If the optional {count} is given, find {count}'s occurrence of
3298 {name} in {path} instead of the first one.
3299 When {count} is negative return all the matches in a |List|.
3300
Bram Moolenaar016188f2022-06-06 20:52:59 +01003301 Returns an empty string if the directory is not found.
3302
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003303 This is quite similar to the ex-command `:find`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003304
3305 Can also be used as a |method|: >
3306 GetName()->finddir()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003307<
Christian Brabandtb753d802025-04-21 11:31:58 +02003308 Return type: list<string> if {count} is negative, |String|
3309 otherwise
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003310
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003311
3312findfile({name} [, {path} [, {count}]]) *findfile()*
3313 Just like |finddir()|, but find a file instead of a directory.
3314 Uses 'suffixesadd'.
3315 Example: >
3316 :echo findfile("tags.vim", ".;")
3317< Searches from the directory of the current file upwards until
3318 it finds the file "tags.vim".
3319
3320 Can also be used as a |method|: >
3321 GetName()->findfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003322<
Christian Brabandtb753d802025-04-21 11:31:58 +02003323 Return type: list<string> if {count} is negative, |String|
3324 otherwise
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003325
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003326
3327flatten({list} [, {maxdepth}]) *flatten()*
3328 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
3329 the result is a |List| without nesting, as if {maxdepth} is
3330 a very large number.
3331 The {list} is changed in place, use |flattennew()| if you do
3332 not want that.
3333 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00003334 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003335 *E900*
3336 {maxdepth} means how deep in nested lists changes are made.
3337 {list} is not modified when {maxdepth} is 0.
3338 {maxdepth} must be positive number.
3339
3340 If there is an error the number zero is returned.
3341
3342 Example: >
3343 :echo flatten([1, [2, [3, 4]], 5])
3344< [1, 2, 3, 4, 5] >
3345 :echo flatten([1, [2, [3, 4]], 5], 1)
3346< [1, 2, [3, 4], 5]
3347
3348 Can also be used as a |method|: >
3349 mylist->flatten()
3350<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003351 Return type: list<{type}>
3352
3353
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003354flattennew({list} [, {maxdepth}]) *flattennew()*
3355 Like |flatten()| but first make a copy of {list}.
3356
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003357 Return type: list<{type}>
3358
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003359
3360float2nr({expr}) *float2nr()*
3361 Convert {expr} to a Number by omitting the part after the
3362 decimal point.
Bram Moolenaar76db9e02022-11-09 21:21:04 +00003363 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003364 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003365 When the value of {expr} is out of range for a |Number| the
3366 result is truncated to 0x7fffffff or -0x7fffffff (or when
3367 64-bit Number support is enabled, 0x7fffffffffffffff or
3368 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
3369 64-bit Number support is enabled, -0x8000000000000000).
3370 Examples: >
3371 echo float2nr(3.95)
3372< 3 >
3373 echo float2nr(-23.45)
3374< -23 >
3375 echo float2nr(1.0e100)
3376< 2147483647 (or 9223372036854775807) >
3377 echo float2nr(-1.0e150)
3378< -2147483647 (or -9223372036854775807) >
3379 echo float2nr(1.0e-100)
3380< 0
3381
3382 Can also be used as a |method|: >
3383 Compute()->float2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003384<
3385 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003386
3387
3388floor({expr}) *floor()*
3389 Return the largest integral value less than or equal to
3390 {expr} as a |Float| (round down).
3391 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003392 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003393 Examples: >
3394 echo floor(1.856)
3395< 1.0 >
3396 echo floor(-5.456)
3397< -6.0 >
3398 echo floor(4.0)
3399< 4.0
3400
3401 Can also be used as a |method|: >
3402 Compute()->floor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003403<
3404 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003405
3406
3407fmod({expr1}, {expr2}) *fmod()*
3408 Return the remainder of {expr1} / {expr2}, even if the
3409 division is not representable. Returns {expr1} - i * {expr2}
3410 for some integer i such that if {expr2} is non-zero, the
3411 result has the same sign as {expr1} and magnitude less than
3412 the magnitude of {expr2}. If {expr2} is zero, the value
3413 returned is zero. The value returned is a |Float|.
3414 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003415 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
3416 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003417 Examples: >
3418 :echo fmod(12.33, 1.22)
3419< 0.13 >
3420 :echo fmod(-12.33, 1.22)
3421< -0.13
3422
3423 Can also be used as a |method|: >
3424 Compute()->fmod(1.22)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003425<
3426 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003427
3428
3429fnameescape({string}) *fnameescape()*
3430 Escape {string} for use as file name command argument. All
3431 characters that have a special meaning, such as '%' and '|'
3432 are escaped with a backslash.
3433 For most systems the characters escaped are
3434 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3435 appears in a filename, it depends on the value of 'isfname'.
3436 A leading '+' and '>' is also escaped (special after |:edit|
3437 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01003438 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003439 Example: >
3440 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003441 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003442< results in executing: >
3443 edit \+some\ str\%nge\|name
3444<
3445 Can also be used as a |method|: >
3446 GetName()->fnameescape()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003447<
3448 Return type: |String|
3449
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003450
3451fnamemodify({fname}, {mods}) *fnamemodify()*
3452 Modify file name {fname} according to {mods}. {mods} is a
3453 string of characters like it is used for file names on the
3454 command line. See |filename-modifiers|.
3455 Example: >
3456 :echo fnamemodify("main.c", ":p:h")
3457< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01003458 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01003459< If {mods} is empty or an unsupported modifier is used then
3460 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01003461 When {fname} is empty then with {mods} ":h" returns ".", so
3462 that `:cd` can be used with it. This is different from
3463 expand('%:h') without a buffer name, which returns an empty
3464 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003465 Note: Environment variables don't work in {fname}, use
3466 |expand()| first then.
3467
3468 Can also be used as a |method|: >
3469 GetName()->fnamemodify(':p:h')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003470<
3471 Return type: |String|
3472
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003473
3474foldclosed({lnum}) *foldclosed()*
3475 The result is a Number. If the line {lnum} is in a closed
3476 fold, the result is the number of the first line in that fold.
3477 If the line {lnum} is not in a closed fold, -1 is returned.
3478 {lnum} is used like with |getline()|. Thus "." is the current
3479 line, "'m" mark m, etc.
3480
3481 Can also be used as a |method|: >
3482 GetLnum()->foldclosed()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003483<
3484 Return type: |Number|
3485
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003486
3487foldclosedend({lnum}) *foldclosedend()*
3488 The result is a Number. If the line {lnum} is in a closed
3489 fold, the result is the number of the last line in that fold.
3490 If the line {lnum} is not in a closed fold, -1 is returned.
3491 {lnum} is used like with |getline()|. Thus "." is the current
3492 line, "'m" mark m, etc.
3493
3494 Can also be used as a |method|: >
3495 GetLnum()->foldclosedend()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003496<
3497 Return type: |Number|
3498
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003499
3500foldlevel({lnum}) *foldlevel()*
3501 The result is a Number, which is the foldlevel of line {lnum}
3502 in the current buffer. For nested folds the deepest level is
3503 returned. If there is no fold at line {lnum}, zero is
3504 returned. It doesn't matter if the folds are open or closed.
3505 When used while updating folds (from 'foldexpr') -1 is
3506 returned for lines where folds are still to be updated and the
3507 foldlevel is unknown. As a special case the level of the
3508 previous line is usually available.
3509 {lnum} is used like with |getline()|. Thus "." is the current
3510 line, "'m" mark m, etc.
3511
3512 Can also be used as a |method|: >
3513 GetLnum()->foldlevel()
3514<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003515 Return type: |Number|
3516
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003517 *foldtext()*
3518foldtext() Returns a String, to be displayed for a closed fold. This is
3519 the default function used for the 'foldtext' option and should
3520 only be called from evaluating 'foldtext'. It uses the
3521 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3522 The returned string looks like this: >
3523 +-- 45 lines: abcdef
3524< The number of leading dashes depends on the foldlevel. The
3525 "45" is the number of lines in the fold. "abcdef" is the text
3526 in the first non-blank line of the fold. Leading white space,
3527 "//" or "/*" and the text from the 'foldmarker' and
3528 'commentstring' options is removed.
3529 When used to draw the actual foldtext, the rest of the line
3530 will be filled with the fold char from the 'fillchars'
3531 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003532 Returns an empty string when there is no fold.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003533
3534 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003535 {not available when compiled without the |+folding| feature}
3536
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003537
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003538foldtextresult({lnum}) *foldtextresult()*
3539 Returns the text that is displayed for the closed fold at line
3540 {lnum}. Evaluates 'foldtext' in the appropriate context.
3541 When there is no closed fold at {lnum} an empty string is
3542 returned.
3543 {lnum} is used like with |getline()|. Thus "." is the current
3544 line, "'m" mark m, etc.
3545 Useful when exporting folded text, e.g., to HTML.
3546 {not available when compiled without the |+folding| feature}
3547
3548
3549 Can also be used as a |method|: >
3550 GetLnum()->foldtextresult()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003551<
3552 Return type: |String|
3553
Ernie Raele79e2072024-01-13 11:47:33 +01003554
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01003555foreach({expr1}, {expr2}) *foreach()* *E1525*
3556 {expr1} must be a |List|, |Tuple|, |String|, |Blob| or
3557 |Dictionary|.
Ernie Raele79e2072024-01-13 11:47:33 +01003558 For each item in {expr1} execute {expr2}. {expr1} is not
erraelc92b8be2024-01-14 10:11:07 -08003559 modified; its values may be, as with |:lockvar| 1. |E741|
Ernie Raele79e2072024-01-13 11:47:33 +01003560 See |map()| and |filter()| to modify {expr1}.
3561
3562 {expr2} must be a |string| or |Funcref|.
3563
3564 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3565 of the current item. For a |Dictionary| |v:key| has the key
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01003566 of the current item and for a |List| or a |Tuple| |v:key| has
3567 the index of the current item. For a |Blob| |v:key| has the
3568 index of the current byte. For a |String| |v:key| has the
3569 index of the current character.
Ernie Raele79e2072024-01-13 11:47:33 +01003570 Examples: >
3571 call foreach(mylist, 'used[v:val] = true')
3572< This records the items that are in the {expr1} list.
3573
3574 Note that {expr2} is the result of expression and is then used
3575 as a command. Often it is good to use a |literal-string| to
3576 avoid having to double backslashes.
3577
3578 If {expr2} is a |Funcref| it must take two arguments:
3579 1. the key or the index of the current item.
3580 2. the value of the current item.
3581 With a legacy script lambda you don't get an error if it only
3582 accepts one argument, but with a Vim9 lambda you get "E1106:
3583 One argument too many", the number of arguments must match.
3584 If the function returns a value, it is ignored.
3585
3586 Returns {expr1} in all cases.
3587 When an error is encountered while executing {expr2} no
3588 further items in {expr1} are processed.
3589 When {expr2} is a Funcref errors inside a function are ignored,
3590 unless it was defined with the "abort" flag.
3591
3592 Can also be used as a |method|: >
3593 mylist->foreach(expr2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003594<
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01003595 Return type: |String|, |Blob|, list<{type}>, tuple<{type}> or
3596 dict<{type}> depending on {expr1}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003597
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003598 *foreground()*
3599foreground() Move the Vim window to the foreground. Useful when sent from
3600 a client to a Vim server. |remote_send()|
3601 On Win32 systems this might not work, the OS does not always
3602 allow a window to bring itself to the foreground. Use
3603 |remote_foreground()| instead.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003604
3605 Return type: |Number|
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003606 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003607 Win32 console version}
3608
Bram Moolenaaraa534142022-09-15 21:46:02 +01003609fullcommand({name} [, {vim9}]) *fullcommand()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003610 Get the full command name from a short abbreviated command
3611 name; see |20.2| for details on command abbreviations.
3612
3613 The string argument {name} may start with a `:` and can
3614 include a [range], these are skipped and not returned.
Bram Moolenaaraa534142022-09-15 21:46:02 +01003615 Returns an empty string if a command doesn't exist, if it's
3616 ambiguous (for user-defined commands) or cannot be shortened
3617 this way. |vim9-no-shorten|
3618
3619 Without the {vim9} argument uses the current script version.
3620 If {vim9} is present and FALSE then legacy script rules are
3621 used. When {vim9} is present and TRUE then Vim9 rules are
3622 used, e.g. "en" is not a short form of "endif".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003623
3624 For example `fullcommand('s')`, `fullcommand('sub')`,
3625 `fullcommand(':%substitute')` all return "substitute".
3626
3627 Can also be used as a |method|: >
3628 GetName()->fullcommand()
3629<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003630 Return type: |String|
3631
3632
3633funcref({name} [, {arglist}] [, {dict}]) *funcref()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003634 Just like |function()|, but the returned Funcref will lookup
3635 the function by reference, not by name. This matters when the
3636 function {name} is redefined later.
3637
3638 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003639 It only works for an autoloaded function if it has already
3640 been loaded (to avoid mistakenly loading the autoload script
3641 when only intending to use the function name, use |function()|
3642 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003643 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003644
3645 Can also be used as a |method|: >
3646 GetFuncname()->funcref([arg])
3647<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003648 Return type: func(...): any or |Number| on error
3649
Dominique Pellee764d1b2023-03-12 21:20:59 +00003650 *function()* *partial* *E700* *E923*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003651function({name} [, {arglist}] [, {dict}])
3652 Return a |Funcref| variable that refers to function {name}.
3653 {name} can be the name of a user defined function or an
3654 internal function.
3655
3656 {name} can also be a Funcref or a partial. When it is a
3657 partial the dict stored in it will be used and the {dict}
3658 argument is not allowed. E.g.: >
3659 let FuncWithArg = function(dict.Func, [arg])
3660 let Broken = function(dict.Func, [arg], dict)
3661<
3662 When using the Funcref the function will be found by {name},
3663 also when it was redefined later. Use |funcref()| to keep the
3664 same function.
3665
3666 When {arglist} or {dict} is present this creates a partial.
3667 That means the argument list and/or the dictionary is stored in
3668 the Funcref and will be used when the Funcref is called.
3669
3670 The arguments are passed to the function in front of other
3671 arguments, but after any argument from |method|. Example: >
3672 func Callback(arg1, arg2, name)
3673 ...
3674 let Partial = function('Callback', ['one', 'two'])
3675 ...
3676 call Partial('name')
3677< Invokes the function as with: >
3678 call Callback('one', 'two', 'name')
3679
3680< With a |method|: >
3681 func Callback(one, two, three)
3682 ...
3683 let Partial = function('Callback', ['two'])
3684 ...
3685 eval 'one'->Partial('three')
3686< Invokes the function as with: >
3687 call Callback('one', 'two', 'three')
3688
3689< The function() call can be nested to add more arguments to the
3690 Funcref. The extra arguments are appended to the list of
3691 arguments. Example: >
3692 func Callback(arg1, arg2, name)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003693 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003694 let Func = function('Callback', ['one'])
3695 let Func2 = function(Func, ['two'])
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003696 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003697 call Func2('name')
3698< Invokes the function as with: >
3699 call Callback('one', 'two', 'name')
3700
3701< The Dictionary is only useful when calling a "dict" function.
3702 In that case the {dict} is passed in as "self". Example: >
3703 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003704 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003705 endfunction
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003706 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003707 let context = {"name": "example"}
3708 let Func = function('Callback', context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003709 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003710 call Func() " will echo: called for example
3711< The use of function() is not needed when there are no extra
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003712 arguments, these two are equivalent, if Callback() is defined
3713 as context.Callback(): >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003714 let Func = function('Callback', context)
3715 let Func = context.Callback
3716
3717< The argument list and the Dictionary can be combined: >
3718 function Callback(arg1, count) dict
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003719 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003720 let context = {"name": "example"}
3721 let Func = function('Callback', ['one'], context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003722 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003723 call Func(500)
3724< Invokes the function as with: >
3725 call context.Callback('one', 500)
3726<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003727 Returns 0 on error.
3728
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003729 Can also be used as a |method|: >
3730 GetFuncname()->function([arg])
3731
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003732<
3733 Return type: func(...): any or |Number| on error
3734
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003735
3736garbagecollect([{atexit}]) *garbagecollect()*
3737 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3738 that have circular references.
3739
3740 There is hardly ever a need to invoke this function, as it is
3741 automatically done when Vim runs out of memory or is waiting
3742 for the user to press a key after 'updatetime'. Items without
3743 circular references are always freed when they become unused.
3744 This is useful if you have deleted a very big |List| and/or
3745 |Dictionary| with circular references in a script that runs
3746 for a long time.
3747
3748 When the optional {atexit} argument is one, garbage
3749 collection will also be done when exiting Vim, if it wasn't
3750 done before. This is useful when checking for memory leaks.
3751
3752 The garbage collection is not done immediately but only when
3753 it's safe to perform. This is when waiting for the user to
3754 type a character. To force garbage collection immediately use
3755 |test_garbagecollect_now()|.
3756
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003757 Return type: |String|
3758
3759
LemonBoy48b7d052024-07-09 18:24:59 +02003760get({list}, {idx} [, {default}]) *get()* *get()-list*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003761 Get item {idx} from |List| {list}. When this item is not
3762 available return {default}. Return zero when {default} is
3763 omitted.
3764 Preferably used as a |method|: >
3765 mylist->get(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003766<
3767 Return type: any, depending on {list}
3768
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01003769get({tuple}, {idx} [, {default}]) *get()-tuple*
3770 Get item {idx} from |Tuple| {tuple}. When this item is not
3771 available return {default}. Return zero when {default} is
3772 omitted.
3773 Preferably used as a |method|: >
3774 mytuple->get(idx)
3775<
3776 Return type: any, depending on {tuple}
3777
LemonBoy48b7d052024-07-09 18:24:59 +02003778get({blob}, {idx} [, {default}]) *get()-blob*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003779 Get byte {idx} from |Blob| {blob}. When this byte is not
3780 available return {default}. Return -1 when {default} is
3781 omitted.
3782 Preferably used as a |method|: >
3783 myblob->get(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003784<
3785 Return type: |Number|
3786
LemonBoy48b7d052024-07-09 18:24:59 +02003787get({dict}, {key} [, {default}]) *get()-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003788 Get item with key {key} from |Dictionary| {dict}. When this
3789 item is not available return {default}. Return zero when
3790 {default} is omitted. Useful example: >
3791 let val = get(g:, 'var_name', 'default')
3792< This gets the value of g:var_name if it exists, and uses
3793 'default' when it does not exist.
3794 Preferably used as a |method|: >
3795 mydict->get(key)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003796<
h-east84ac2122024-06-17 18:12:30 +02003797 Return type: any, depending on {dict}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003798
LemonBoy48b7d052024-07-09 18:24:59 +02003799get({func}, {what}) *get()-func*
3800 Get item {what} from |Funcref| {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003801 {what} are:
LemonBoy48b7d052024-07-09 18:24:59 +02003802 "name" The function name
3803 "func" The function
3804 "dict" The dictionary
3805 "args" The list with arguments
3806 "arity" A dictionary with information about the number of
3807 arguments accepted by the function (minus the
3808 {arglist}) with the following fields:
3809 required the number of positional arguments
3810 optional the number of optional arguments,
3811 in addition to the required ones
3812 varargs |TRUE| if the function accepts a
3813 variable number of arguments |...|
3814
3815 Note: There is no error, if the {arglist} of
3816 the Funcref contains more arguments than the
3817 Funcref expects, it's not validated.
3818
Bram Moolenaar016188f2022-06-06 20:52:59 +01003819 Returns zero on error.
LemonBoy48b7d052024-07-09 18:24:59 +02003820
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003821 Preferably used as a |method|: >
3822 myfunc->get(what)
3823<
LemonBoy48b7d052024-07-09 18:24:59 +02003824 Return type: any, depending on {func} and {what}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003825
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003826 *getbufinfo()*
3827getbufinfo([{buf}])
3828getbufinfo([{dict}])
3829 Get information about buffers as a List of Dictionaries.
3830
3831 Without an argument information about all the buffers is
3832 returned.
3833
3834 When the argument is a |Dictionary| only the buffers matching
3835 the specified criteria are returned. The following keys can
3836 be specified in {dict}:
3837 buflisted include only listed buffers.
3838 bufloaded include only loaded buffers.
3839 bufmodified include only modified buffers.
3840
3841 Otherwise, {buf} specifies a particular buffer to return
3842 information for. For the use of {buf}, see |bufname()|
3843 above. If the buffer is found the returned List has one item.
3844 Otherwise the result is an empty list.
3845
3846 Each returned List item is a dictionary with the following
3847 entries:
3848 bufnr Buffer number.
3849 changed TRUE if the buffer is modified.
3850 changedtick Number of changes made to the buffer.
Sean Dewar1fb41032023-08-16 17:15:05 +01003851 command TRUE if the buffer belongs to the
3852 command-line window |cmdwin|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003853 hidden TRUE if the buffer is hidden.
3854 lastused Timestamp in seconds, like
3855 |localtime()|, when the buffer was
3856 last used.
3857 {only with the |+viminfo| feature}
3858 listed TRUE if the buffer is listed.
3859 lnum Line number used for the buffer when
3860 opened in the current window.
3861 Only valid if the buffer has been
3862 displayed in the window in the past.
3863 If you want the line number of the
3864 last known cursor position in a given
3865 window, use |line()|: >
3866 :echo line('.', {winid})
3867<
3868 linecount Number of lines in the buffer (only
3869 valid when loaded)
3870 loaded TRUE if the buffer is loaded.
3871 name Full path to the file in the buffer.
3872 signs List of signs placed in the buffer.
3873 Each list item is a dictionary with
3874 the following fields:
3875 id sign identifier
3876 lnum line number
3877 name sign name
3878 variables A reference to the dictionary with
3879 buffer-local variables.
3880 windows List of |window-ID|s that display this
3881 buffer
3882 popups List of popup |window-ID|s that
3883 display this buffer
3884
3885 Examples: >
3886 for buf in getbufinfo()
3887 echo buf.name
3888 endfor
3889 for buf in getbufinfo({'buflisted':1})
3890 if buf.changed
3891 ....
3892 endif
3893 endfor
3894<
3895 To get buffer-local options use: >
3896 getbufvar({bufnr}, '&option_name')
3897<
3898 Can also be used as a |method|: >
3899 GetBufnr()->getbufinfo()
3900<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003901 Return type: list<dict<any>>
3902
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003903
3904 *getbufline()*
3905getbufline({buf}, {lnum} [, {end}])
3906 Return a |List| with the lines starting from {lnum} to {end}
3907 (inclusive) in the buffer {buf}. If {end} is omitted, a
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003908 |List| with only the line {lnum} is returned. See
3909 `getbufoneline()` for only getting the line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003910
3911 For the use of {buf}, see |bufname()| above.
3912
3913 For {lnum} and {end} "$" can be used for the last line of the
3914 buffer. Otherwise a number must be used.
3915
3916 When {lnum} is smaller than 1 or bigger than the number of
3917 lines in the buffer, an empty |List| is returned.
3918
3919 When {end} is greater than the number of lines in the buffer,
3920 it is treated as {end} is set to the number of lines in the
3921 buffer. When {end} is before {lnum} an empty |List| is
3922 returned.
3923
3924 This function works only for loaded buffers. For unloaded and
3925 non-existing buffers, an empty |List| is returned.
3926
3927 Example: >
3928 :let lines = getbufline(bufnr("myfile"), 1, "$")
3929
3930< Can also be used as a |method|: >
3931 GetBufnr()->getbufline(lnum)
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003932<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003933 Return type: list<string>
3934
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003935 *getbufoneline()*
3936getbufoneline({buf}, {lnum})
3937 Just like `getbufline()` but only get one line and return it
3938 as a string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003939
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003940 Return type: |String|
3941
3942
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003943getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3944 The result is the value of option or local buffer variable
3945 {varname} in buffer {buf}. Note that the name without "b:"
3946 must be used.
3947 The {varname} argument is a string.
3948 When {varname} is empty returns a |Dictionary| with all the
3949 buffer-local variables.
3950 When {varname} is equal to "&" returns a |Dictionary| with all
3951 the buffer-local options.
3952 Otherwise, when {varname} starts with "&" returns the value of
3953 a buffer-local option.
3954 This also works for a global or buffer-local option, but it
3955 doesn't work for a global variable, window-local variable or
3956 window-local option.
3957 For the use of {buf}, see |bufname()| above.
3958 When the buffer or variable doesn't exist {def} or an empty
3959 string is returned, there is no error message.
3960 Examples: >
3961 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003962 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003963
3964< Can also be used as a |method|: >
3965 GetBufnr()->getbufvar(varname)
3966<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003967 Return type: any, depending on {varname}
3968
3969
mikoto20001083cae2024-11-11 21:24:14 +01003970getcellpixels() *getcellpixels()*
3971 Returns a |List| of terminal cell pixel size.
h-eastb534e802024-12-03 20:37:52 +01003972 List format is [xpixel, ypixel].
mikoto2000a73dfc22024-11-18 21:12:21 +01003973
3974 Only works on Unix (terminal and gVim) and Windows (gVim only).
3975 Returns [] on other systems or on failure.
3976 Note that there could be variations across different terminals.
3977 On macOS, system Terminal.app returns sizes in points (before
3978 Retina scaling), whereas third-party terminals return raw pixel
3979 sizes (post Retina scaling).
mikoto20001083cae2024-11-11 21:24:14 +01003980
mikoto2000de094dc2024-11-14 22:13:48 +01003981 Return type: list<any>
mikoto20001083cae2024-11-11 21:24:14 +01003982
3983
Kota Kato66bb9ae2023-01-17 18:31:56 +00003984getcellwidths() *getcellwidths()*
3985 Returns a |List| of cell widths of character ranges overridden
3986 by |setcellwidths()|. The format is equal to the argument of
3987 |setcellwidths()|. If no character ranges have their cell
3988 widths overridden, an empty List is returned.
h-east84ac2122024-06-17 18:12:30 +02003989
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003990 Return type: list<any>
Kota Kato66bb9ae2023-01-17 18:31:56 +00003991
3992
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003993getchangelist([{buf}]) *getchangelist()*
3994 Returns the |changelist| for the buffer {buf}. For the use
3995 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3996 exist, an empty list is returned.
3997
3998 The returned list contains two entries: a list with the change
3999 locations and the current position in the list. Each
4000 entry in the change list is a dictionary with the following
4001 entries:
4002 col column number
4003 coladd column offset for 'virtualedit'
4004 lnum line number
4005 If buffer {buf} is the current buffer, then the current
4006 position refers to the position in the list. For other
4007 buffers, it is set to the length of the list.
4008
4009 Can also be used as a |method|: >
4010 GetBufnr()->getchangelist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004011<
4012 Return type: list<any>
4013
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004014
zeertzjqe0a2ab32025-02-02 09:14:35 +01004015getchar([{expr} [, {opts}]]) *getchar()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004016 Get a single character from the user or input stream.
zeertzjqe0a2ab32025-02-02 09:14:35 +01004017 If {expr} is omitted or is -1, wait until a character is
4018 available.
Doug Kearns9cd9e752024-04-07 17:42:17 +02004019 If {expr} is 0, only get a character when one is available.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004020 Return zero otherwise.
Doug Kearns9cd9e752024-04-07 17:42:17 +02004021 If {expr} is 1, only check if a character is available, it is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004022 not consumed. Return zero if no character available.
zeertzjqe0a2ab32025-02-02 09:14:35 +01004023 If you prefer always getting a string use |getcharstr()|, or
4024 specify |FALSE| as "number" in {opts}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004025
Doug Kearns9cd9e752024-04-07 17:42:17 +02004026 Without {expr} and when {expr} is 0 a whole character or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004027 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01004028 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004029 Otherwise a String is returned with the encoded character.
4030 For a special key it's a String with a sequence of bytes
4031 starting with 0x80 (decimal: 128). This is the same value as
4032 the String "\<Key>", e.g., "\<Left>". The returned value is
4033 also a String when a modifier (shift, control, alt) was used
zeertzjqe0a2ab32025-02-02 09:14:35 +01004034 that is not included in the character. |keytrans()| can also
4035 be used to convert a returned String into a readable form.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004036
Doug Kearns9cd9e752024-04-07 17:42:17 +02004037 When {expr} is 0 and Esc is typed, there will be a short delay
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004038 while Vim waits to see if this is the start of an escape
4039 sequence.
4040
Doug Kearns9cd9e752024-04-07 17:42:17 +02004041 When {expr} is 1 only the first byte is returned. For a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004042 one-byte character it is the character itself as a number.
4043 Use nr2char() to convert it to a String.
4044
4045 Use getcharmod() to obtain any additional modifiers.
4046
zeertzjqe0a2ab32025-02-02 09:14:35 +01004047 The optional argument {opts} is a Dict and supports the
4048 following items:
4049
zeertzjqedf0f7d2025-02-02 19:01:01 +01004050 cursor A String specifying cursor behavior
4051 when waiting for a character.
4052 "hide": hide the cursor.
4053 "keep": keep current cursor unchanged.
4054 "msg": move cursor to message area.
4055 (default: "msg")
4056
zeertzjqe0a2ab32025-02-02 09:14:35 +01004057 number If |TRUE|, return a Number when getting
4058 a single character.
4059 If |FALSE|, the return value is always
4060 converted to a String, and an empty
4061 String (instead of 0) is returned when
4062 no character is available.
4063 (default: |TRUE|)
4064
4065 simplify If |TRUE|, include modifiers in the
4066 character if possible. E.g., return
4067 the same value for CTRL-I and <Tab>.
4068 If |FALSE|, don't include modifiers in
4069 the character.
4070 (default: |TRUE|)
4071
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004072 When the user clicks a mouse button, the mouse event will be
4073 returned. The position can then be found in |v:mouse_col|,
4074 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
4075 |getmousepos()| can also be used. Mouse move events will be
4076 ignored.
4077 This example positions the mouse as it would normally happen: >
4078 let c = getchar()
4079 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004080 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004081 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004082 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004083 endif
4084<
4085 When using bracketed paste only the first character is
4086 returned, the rest of the pasted text is dropped.
4087 |xterm-bracketed-paste|.
4088
4089 There is no prompt, you will somehow have to make clear to the
4090 user that a character has to be typed. The screen is not
4091 redrawn, e.g. when resizing the window. When using a popup
4092 window it should work better with a |popup-filter|.
4093
4094 There is no mapping for the character.
4095 Key codes are replaced, thus when the user presses the <Del>
4096 key you get the code for the <Del> key, not the raw character
4097 sequence. Examples: >
4098 getchar() == "\<Del>"
4099 getchar() == "\<S-Left>"
4100< This example redefines "f" to ignore case: >
4101 :nmap f :call FindChar()<CR>
4102 :function FindChar()
4103 : let c = nr2char(getchar())
4104 : while col('.') < col('$') - 1
4105 : normal l
4106 : if getline('.')[col('.') - 1] ==? c
4107 : break
4108 : endif
4109 : endwhile
4110 :endfunction
4111<
4112 You may also receive synthetic characters, such as
4113 |<CursorHold>|. Often you will want to ignore this and get
4114 another character: >
4115 :function GetKey()
4116 : let c = getchar()
4117 : while c == "\<CursorHold>"
4118 : let c = getchar()
4119 : endwhile
4120 : return c
4121 :endfunction
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004122<
4123 Return type: |Number| or |String|
4124
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004125
4126getcharmod() *getcharmod()*
4127 The result is a Number which is the state of the modifiers for
4128 the last obtained character with getchar() or in another way.
4129 These values are added together:
4130 2 shift
4131 4 control
4132 8 alt (meta)
4133 16 meta (when it's different from ALT)
4134 32 mouse double click
4135 64 mouse triple click
4136 96 mouse quadruple click (== 32 + 64)
Casey Tucker92e90a12024-01-25 22:44:00 +01004137 128 command (Mac) or super (GTK)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004138 Only the modifiers that have not been included in the
4139 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01004140 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004141
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004142 Return type: |Number|
4143
4144
4145getcharpos({expr}) *getcharpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004146 Get the position for String {expr}. Same as |getpos()| but the
4147 column number in the returned List is a character index
4148 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00004149 If |getpos()| returns a very large column number, equal to
4150 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004151 of the last character.
4152
4153 Example:
4154 With the cursor on '세' in line 5 with text "여보세요": >
4155 getcharpos('.') returns [0, 5, 3, 0]
4156 getpos('.') returns [0, 5, 7, 0]
4157<
4158 Can also be used as a |method|: >
4159 GetMark()->getcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004160<
4161 Return type: list<number>
4162
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004163
4164getcharsearch() *getcharsearch()*
4165 Return the current character search information as a {dict}
4166 with the following entries:
4167
4168 char character previously used for a character
4169 search (|t|, |f|, |T|, or |F|); empty string
4170 if no character search has been performed
4171 forward direction of character search; 1 for forward,
4172 0 for backward
4173 until type of character search; 1 for a |t| or |T|
4174 character search, 0 for an |f| or |F|
4175 character search
4176
4177 This can be useful to always have |;| and |,| search
4178 forward/backward regardless of the direction of the previous
4179 character search: >
4180 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
4181 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
4182< Also see |setcharsearch()|.
4183
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004184 Return type: dict<any>
4185
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004186
zeertzjqe0a2ab32025-02-02 09:14:35 +01004187getcharstr([{expr} [, {opts}]]) *getcharstr()*
4188 The same as |getchar()|, except that this always returns a
4189 String, and "number" isn't allowed in {opts}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004190
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004191 Return type: |String|
4192
Ruslan Russkikh0407d622024-10-08 22:21:05 +02004193getcmdcomplpat() *getcmdcomplpat()*
4194 Return completion pattern of the current command-line.
4195 Only works when the command line is being edited, thus
4196 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
4197 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
4198 |getcmdprompt()|, |getcmdcompltype()| and |setcmdline()|.
4199 Returns an empty string when completion is not defined.
4200
4201 Return type: |String|
4202
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004203
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004204getcmdcompltype() *getcmdcompltype()*
4205 Return the type of the current command-line completion.
4206 Only works when the command line is being edited, thus
4207 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01004208 See |:command-completion| for the return string.
Shougo Matsushita69084282024-09-23 20:34:47 +02004209 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
Ruslan Russkikh0407d622024-10-08 22:21:05 +02004210 |getcmdprompt()|, |getcmdcomplpat()| and |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004211 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004212
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004213 Return type: |String|
4214
4215
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004216getcmdline() *getcmdline()*
Shougo Matsushita69084282024-09-23 20:34:47 +02004217 Return the current command-line input. Only works when the
4218 command line is being edited, thus requires use of
4219 |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004220 Example: >
4221 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Shougo Matsushita69084282024-09-23 20:34:47 +02004222< Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()|,
4223 |getcmdprompt()| and |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004224 Returns an empty string when entering a password or using
4225 |inputsecret()|.
4226
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004227 Return type: |String|
4228
4229
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004230getcmdpos() *getcmdpos()*
4231 Return the position of the cursor in the command line as a
4232 byte count. The first column is 1.
4233 Only works when editing the command line, thus requires use of
4234 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4235 Returns 0 otherwise.
Shougo Matsushita69084282024-09-23 20:34:47 +02004236 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
4237 |getcmdprompt()| and |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004238
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004239 Return type: |Number|
4240
4241
Shougo Matsushita69084282024-09-23 20:34:47 +02004242getcmdprompt() *getcmdprompt()*
4243 Return the current command-line prompt when using functions
4244 like |input()| or |confirm()|.
4245 Only works when the command line is being edited, thus
4246 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
4247 Also see |getcmdtype()|, |getcmdline()|, |getcmdpos()|,
4248 |setcmdpos()| and |setcmdline()|.
4249
4250 Return type: |String|
4251
4252
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004253getcmdscreenpos() *getcmdscreenpos()*
4254 Return the screen position of the cursor in the command line
4255 as a byte count. The first column is 1.
4256 Instead of |getcmdpos()|, it adds the prompt position.
4257 Only works when editing the command line, thus requires use of
4258 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4259 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01004260 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
4261 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004262
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004263 Return type: |Number|
4264
4265
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004266getcmdtype() *getcmdtype()*
4267 Return the current command-line type. Possible return values
4268 are:
4269 : normal Ex command
4270 > debug mode command |debug-mode|
4271 / forward search command
4272 ? backward search command
4273 @ |input()| command
4274 - |:insert| or |:append| command
4275 = |i_CTRL-R_=|
4276 Only works when editing the command line, thus requires use of
4277 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4278 Returns an empty string otherwise.
4279 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
4280
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004281 Return type: |String|
4282
4283
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004284getcmdwintype() *getcmdwintype()*
4285 Return the current |command-line-window| type. Possible return
4286 values are the same as |getcmdtype()|. Returns an empty string
4287 when not in the command-line window.
4288
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004289 Return type: |String|
4290
4291
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004292getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
4293 Return a list of command-line completion matches. The String
4294 {type} argument specifies what for. The following completion
4295 types are supported:
4296
4297 arglist file names in argument list
4298 augroup autocmd groups
4299 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00004300 behave |:behave| suboptions
4301 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004302 color color schemes
4303 command Ex command
4304 cmdline |cmdline-completion| result
4305 compiler compilers
4306 cscope |:cscope| suboptions
Shougo Matsushita92997dd2023-08-20 20:55:55 +02004307 custom,{func} custom completion, defined via {func}
4308 customlist,{func} custom completion, defined via {func}
zeertzjq85f36d62024-10-10 19:14:13 +02004309 diff_buffer |:diffget| and |:diffput| completion
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004310 dir directory names
LemonBoya20bf692024-07-11 22:35:53 +02004311 dir_in_path directory names in |'cdpath'|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004312 environment environment variable names
4313 event autocommand events
4314 expression Vim expression
4315 file file and directory names
4316 file_in_path file and directory names in |'path'|
4317 filetype filetype names |'filetype'|
Christian Brabandta3422aa2025-04-23 21:04:24 +02004318 filetypecmd |:filetype| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004319 function function name
4320 help help subjects
4321 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00004322 history |:history| suboptions
Doug Kearns81642d92024-01-04 22:37:44 +01004323 keymap keyboard mappings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004324 locale locale names (as output of locale -a)
4325 mapclear buffer argument
4326 mapping mapping name
4327 menu menus
4328 messages |:messages| suboptions
4329 option options
4330 packadd optional package |pack-add| names
zeertzjq5c8771b2023-01-24 12:34:03 +00004331 runtime |:runtime| completion
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00004332 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004333 shellcmd Shell command
zeertzjq85f36d62024-10-10 19:14:13 +02004334 shellcmdline Shell command line with filename arguments
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004335 sign |:sign| suboptions
4336 syntax syntax file names |'syntax'|
4337 syntime |:syntime| suboptions
4338 tag tags
4339 tag_listfiles tags, file names
4340 user user names
4341 var user variables
4342
4343 If {pat} is an empty string, then all the matches are
4344 returned. Otherwise only items matching {pat} are returned.
4345 See |wildcards| for the use of special characters in {pat}.
4346
4347 If the optional {filtered} flag is set to 1, then 'wildignore'
4348 is applied to filter the results. Otherwise all the matches
4349 are returned. The 'wildignorecase' option always applies.
4350
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00004351 If the 'wildoptions' option contains 'fuzzy', then fuzzy
4352 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00004353 regular expression matching is used. Thus this function
4354 follows the user preference, what happens on the command line.
4355 If you do not want this you can make 'wildoptions' empty
4356 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00004357
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004358 If {type} is "cmdline", then the |cmdline-completion| result is
4359 returned. For example, to complete the possible values after
4360 a ":call" command: >
4361 echo getcompletion('call ', 'cmdline')
4362<
4363 If there are no matches, an empty list is returned. An
4364 invalid value for {type} produces an error.
4365
4366 Can also be used as a |method|: >
4367 GetPattern()->getcompletion('color')
4368<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004369 Return type: list<string>
4370
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004371 *getcurpos()*
4372getcurpos([{winid}])
4373 Get the position of the cursor. This is like getpos('.'), but
4374 includes an extra "curswant" item in the list:
4375 [0, lnum, col, off, curswant] ~
4376 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00004377 cursor vertically. After |$| command it will be a very large
4378 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004379 |getpos()|.
4380 The first "bufnum" item is always zero. The byte position of
4381 the cursor is returned in 'col'. To get the character
4382 position, use |getcursorcharpos()|.
4383
4384 The optional {winid} argument can specify the window. It can
4385 be the window number or the |window-ID|. The last known
4386 cursor position is returned, this may be invalid for the
4387 current value of the buffer if it is not the current window.
4388 If {winid} is invalid a list with zeroes is returned.
4389
4390 This can be used to save and restore the cursor position: >
4391 let save_cursor = getcurpos()
4392 MoveTheCursorAround
4393 call setpos('.', save_cursor)
4394< Note that this only works within the window. See
4395 |winrestview()| for restoring more state.
4396
4397 Can also be used as a |method|: >
4398 GetWinid()->getcurpos()
4399<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004400 Return type: list<number>
4401
4402
4403getcursorcharpos([{winid}]) *getcursorcharpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004404 Same as |getcurpos()| but the column number in the returned
4405 List is a character index instead of a byte index.
4406
4407 Example:
4408 With the cursor on '보' in line 3 with text "여보세요": >
4409 getcursorcharpos() returns [0, 3, 2, 0, 3]
4410 getcurpos() returns [0, 3, 4, 0, 3]
4411<
4412 Can also be used as a |method|: >
4413 GetWinid()->getcursorcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004414<
4415 Return type: list<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004416
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004417
4418getcwd([{winnr} [, {tabnr}]]) *getcwd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004419 The result is a String, which is the name of the current
4420 working directory. 'autochdir' is ignored.
4421
4422 With {winnr} return the local current directory of this window
4423 in the current tab page. {winnr} can be the window number or
4424 the |window-ID|.
4425 If {winnr} is -1 return the name of the global working
4426 directory. See also |haslocaldir()|.
4427
4428 With {winnr} and {tabnr} return the local current directory of
4429 the window in the specified tab page. If {winnr} is -1 return
4430 the working directory of the tabpage.
4431 If {winnr} is zero use the current window, if {tabnr} is zero
4432 use the current tabpage.
4433 Without any arguments, return the actual working directory of
4434 the current window.
4435 Return an empty string if the arguments are invalid.
4436
4437 Examples: >
4438 " Get the working directory of the current window
4439 :echo getcwd()
4440 :echo getcwd(0)
4441 :echo getcwd(0, 0)
4442 " Get the working directory of window 3 in tabpage 2
4443 :echo getcwd(3, 2)
4444 " Get the global working directory
4445 :echo getcwd(-1)
4446 " Get the working directory of tabpage 3
4447 :echo getcwd(-1, 3)
4448 " Get the working directory of current tabpage
4449 :echo getcwd(-1, 0)
4450
4451< Can also be used as a |method|: >
4452 GetWinnr()->getcwd()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004453<
4454 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004455
4456getenv({name}) *getenv()*
4457 Return the value of environment variable {name}. The {name}
4458 argument is a string, without a leading '$'. Example: >
4459 myHome = getenv('HOME')
4460
4461< When the variable does not exist |v:null| is returned. That
4462 is different from a variable set to an empty string, although
4463 some systems interpret the empty value as the variable being
4464 deleted. See also |expr-env|.
4465
4466 Can also be used as a |method|: >
4467 GetVarname()->getenv()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004468<
4469 Return type: |String| or |Number|
4470
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004471
4472getfontname([{name}]) *getfontname()*
4473 Without an argument returns the name of the normal font being
4474 used. Like what is used for the Normal highlight group
4475 |hl-Normal|.
4476 With an argument a check is done whether String {name} is a
4477 valid font name. If not then an empty string is returned.
4478 Otherwise the actual font name is returned, or {name} if the
4479 GUI does not support obtaining the real name.
4480 Only works when the GUI is running, thus not in your vimrc or
4481 gvimrc file. Use the |GUIEnter| autocommand to use this
4482 function just after the GUI has started.
4483 Note that the GTK GUI accepts any font name, thus checking for
4484 a valid name does not work.
4485
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004486 Return type: |String|
4487
4488
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004489getfperm({fname}) *getfperm()*
4490 The result is a String, which is the read, write, and execute
4491 permissions of the given file {fname}.
4492 If {fname} does not exist or its directory cannot be read, an
4493 empty string is returned.
4494 The result is of the form "rwxrwxrwx", where each group of
4495 "rwx" flags represent, in turn, the permissions of the owner
4496 of the file, the group the file belongs to, and other users.
4497 If a user does not have a given permission the flag for this
4498 is replaced with the string "-". Examples: >
4499 :echo getfperm("/etc/passwd")
4500 :echo getfperm(expand("~/.vimrc"))
4501< This will hopefully (from a security point of view) display
4502 the string "rw-r--r--" or even "rw-------".
4503
4504 Can also be used as a |method|: >
4505 GetFilename()->getfperm()
4506<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004507 Return type: |String|
4508
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004509 For setting permissions use |setfperm()|.
4510
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004511
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004512getfsize({fname}) *getfsize()*
4513 The result is a Number, which is the size in bytes of the
4514 given file {fname}.
4515 If {fname} is a directory, 0 is returned.
4516 If the file {fname} can't be found, -1 is returned.
4517 If the size of {fname} is too big to fit in a Number then -2
4518 is returned.
4519
4520 Can also be used as a |method|: >
4521 GetFilename()->getfsize()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004522<
4523 Return type: |Number|
4524
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004525
4526getftime({fname}) *getftime()*
4527 The result is a Number, which is the last modification time of
4528 the given file {fname}. The value is measured as seconds
4529 since 1st Jan 1970, and may be passed to strftime(). See also
4530 |localtime()| and |strftime()|.
4531 If the file {fname} can't be found -1 is returned.
4532
4533 Can also be used as a |method|: >
4534 GetFilename()->getftime()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004535<
4536 Return type: |Number|
4537
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004538
4539getftype({fname}) *getftype()*
4540 The result is a String, which is a description of the kind of
4541 file of the given file {fname}.
4542 If {fname} does not exist an empty string is returned.
4543 Here is a table over different kinds of files and their
4544 results:
4545 Normal file "file"
4546 Directory "dir"
4547 Symbolic link "link"
4548 Block device "bdev"
4549 Character device "cdev"
4550 Socket "socket"
4551 FIFO "fifo"
4552 All other "other"
4553 Example: >
4554 getftype("/home")
4555< Note that a type such as "link" will only be returned on
4556 systems that support it. On some systems only "dir" and
4557 "file" are returned. On MS-Windows a symbolic link to a
4558 directory returns "dir" instead of "link".
4559
4560 Can also be used as a |method|: >
4561 GetFilename()->getftype()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004562<
4563 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004564
4565getimstatus() *getimstatus()*
4566 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01004567 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004568 See 'imstatusfunc'.
4569
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004570 Return type: |Number|
4571
4572
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004573getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
4574 Returns the |jumplist| for the specified window.
4575
4576 Without arguments use the current window.
4577 With {winnr} only use this window in the current tab page.
4578 {winnr} can also be a |window-ID|.
4579 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01004580 page. If {winnr} or {tabnr} is invalid, an empty list is
4581 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004582
4583 The returned list contains two entries: a list with the jump
4584 locations and the last used jump position number in the list.
4585 Each entry in the jump location list is a dictionary with
4586 the following entries:
4587 bufnr buffer number
4588 col column number
4589 coladd column offset for 'virtualedit'
4590 filename filename if available
4591 lnum line number
4592
4593 Can also be used as a |method|: >
4594 GetWinnr()->getjumplist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004595<
4596 Return type: list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004597
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004598 *getline()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004599getline({lnum} [, {end}])
4600 Without {end} the result is a String, which is line {lnum}
4601 from the current buffer. Example: >
4602 getline(1)
4603< When {lnum} is a String that doesn't start with a
4604 digit, |line()| is called to translate the String into a Number.
4605 To get the line under the cursor: >
4606 getline(".")
4607< When {lnum} is a number smaller than 1 or bigger than the
4608 number of lines in the buffer, an empty string is returned.
4609
4610 When {end} is given the result is a |List| where each item is
4611 a line from the current buffer in the range {lnum} to {end},
4612 including line {end}.
4613 {end} is used in the same way as {lnum}.
4614 Non-existing lines are silently omitted.
4615 When {end} is before {lnum} an empty |List| is returned.
4616 Example: >
4617 :let start = line('.')
4618 :let end = search("^$") - 1
4619 :let lines = getline(start, end)
4620
4621< Can also be used as a |method|: >
4622 ComputeLnum()->getline()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004623<
4624 Return type: list<string> or |String| depending on {end}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004625
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004626 To get lines from another buffer see |getbufline()| and
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00004627 |getbufoneline()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004628
4629getloclist({nr} [, {what}]) *getloclist()*
4630 Returns a |List| with all the entries in the location list for
4631 window {nr}. {nr} can be the window number or the |window-ID|.
4632 When {nr} is zero the current window is used.
4633
4634 For a location list window, the displayed location list is
4635 returned. For an invalid window number {nr}, an empty list is
4636 returned. Otherwise, same as |getqflist()|.
4637
4638 If the optional {what} dictionary argument is supplied, then
4639 returns the items listed in {what} as a dictionary. Refer to
4640 |getqflist()| for the supported items in {what}.
4641
4642 In addition to the items supported by |getqflist()| in {what},
4643 the following item is supported by |getloclist()|:
4644
4645 filewinid id of the window used to display files
4646 from the location list. This field is
4647 applicable only when called from a
4648 location list window. See
4649 |location-list-file-window| for more
4650 details.
4651
4652 Returns a |Dictionary| with default values if there is no
4653 location list for the window {nr}.
4654 Returns an empty Dictionary if window {nr} does not exist.
4655
4656 Examples (See also |getqflist-examples|): >
4657 :echo getloclist(3, {'all': 0})
4658 :echo getloclist(5, {'filewinid': 0})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004659<
4660 Return type: list<dict<any>> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004661
4662
4663getmarklist([{buf}]) *getmarklist()*
4664 Without the {buf} argument returns a |List| with information
4665 about all the global marks. |mark|
4666
4667 If the optional {buf} argument is specified, returns the
4668 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01004669 see |bufname()|. If {buf} is invalid, an empty list is
4670 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004671
4672 Each item in the returned List is a |Dict| with the following:
4673 mark name of the mark prefixed by "'"
4674 pos a |List| with the position of the mark:
4675 [bufnum, lnum, col, off]
4676 Refer to |getpos()| for more information.
4677 file file name
4678
4679 Refer to |getpos()| for getting information about a specific
4680 mark.
4681
4682 Can also be used as a |method|: >
4683 GetBufnr()->getmarklist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004684<
4685 Return type: list<dict<any>> or list<any>
4686
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004687
4688getmatches([{win}]) *getmatches()*
4689 Returns a |List| with all matches previously defined for the
4690 current window by |matchadd()| and the |:match| commands.
4691 |getmatches()| is useful in combination with |setmatches()|,
4692 as |setmatches()| can restore a list of matches saved by
4693 |getmatches()|.
4694 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01004695 window ID instead of the current window. If {win} is invalid,
4696 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004697 Example: >
4698 :echo getmatches()
4699< [{'group': 'MyGroup1', 'pattern': 'TODO',
4700 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4701 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4702 :let m = getmatches()
4703 :call clearmatches()
4704 :echo getmatches()
4705< [] >
4706 :call setmatches(m)
4707 :echo getmatches()
4708< [{'group': 'MyGroup1', 'pattern': 'TODO',
4709 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4710 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4711 :unlet m
4712<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004713 Return type: list<dict<any>> or list<any>
4714
4715
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004716getmousepos() *getmousepos()*
4717 Returns a |Dictionary| with the last known position of the
4718 mouse. This can be used in a mapping for a mouse click or in
4719 a filter of a popup window. The items are:
4720 screenrow screen row
4721 screencol screen column
4722 winid Window ID of the click
4723 winrow row inside "winid"
4724 wincol column inside "winid"
4725 line text line inside "winid"
4726 column text column inside "winid"
zeertzjqf5a94d52023-10-15 10:03:30 +02004727 coladd offset (in screen columns) from the
4728 start of the clicked char
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004729 All numbers are 1-based.
4730
4731 If not over a window, e.g. when in the command line, then only
4732 "screenrow" and "screencol" are valid, the others are zero.
4733
4734 When on the status line below a window or the vertical
4735 separator right of a window, the "line" and "column" values
4736 are zero.
4737
4738 When the position is after the text then "column" is the
4739 length of the text in bytes plus one.
4740
4741 If the mouse is over a popup window then that window is used.
4742
4743 When using |getchar()| the Vim variables |v:mouse_lnum|,
4744 |v:mouse_col| and |v:mouse_winid| also provide these values.
4745
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004746 Return type: dict<number>
4747
4748
Bram Moolenaar24dc19c2022-11-14 19:49:15 +00004749getmouseshape() *getmouseshape()*
4750 Returns the name of the currently showing mouse pointer.
4751 When the |+mouseshape| feature is not supported or the shape
4752 is unknown an empty string is returned.
4753 This function is mainly intended for testing.
4754
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004755 Return type: |String|
4756
4757
4758getpid() *getpid()*
4759 Return a Number which is the process ID of the Vim process.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004760 On Unix and MS-Windows this is a unique number, until Vim
4761 exits.
4762
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004763 Return type: |Number|
4764
4765
4766getpos({expr}) *getpos()*
zeertzjq02f3eba2024-06-12 20:45:24 +02004767 Get the position for String {expr}.
4768 The accepted values for {expr} are: *E1209*
4769 . The cursor position.
4770 $ The last line in the current buffer.
4771 'x Position of mark x (if the mark is not set, 0 is
zeertzjqd353d272024-06-13 23:00:25 +08004772 returned for all values).
zeertzjq02f3eba2024-06-12 20:45:24 +02004773 w0 First line visible in current window (one if the
4774 display isn't updated, e.g. in silent Ex mode).
4775 w$ Last line visible in current window (this is one
4776 less than "w0" if no lines are visible).
4777 v When not in Visual mode, returns the cursor
4778 position. In Visual mode, returns the other end
4779 of the Visual area. A good way to think about
4780 this is that in Visual mode "v" and "." complement
4781 each other. While "." refers to the cursor
4782 position, "v" refers to where |v_o| would move the
4783 cursor. As a result, you can use "v" and "."
4784 together to work on all of a selection in
4785 characterwise Visual mode. If the cursor is at
4786 the end of a characterwise Visual area, "v" refers
4787 to the start of the same Visual area. And if the
4788 cursor is at the start of a characterwise Visual
4789 area, "v" refers to the end of the same Visual
4790 area. "v" differs from |'<| and |'>| in that it's
4791 updated right away.
4792 Note that a mark in another file can be used. The line number
4793 then applies to another buffer.
4794
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004795 The result is a |List| with four numbers:
4796 [bufnum, lnum, col, off]
4797 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4798 is the buffer number of the mark.
4799 "lnum" and "col" are the position in the buffer. The first
4800 column is 1.
4801 The "off" number is zero, unless 'virtualedit' is used. Then
4802 it is the offset in screen columns from the start of the
4803 character. E.g., a position within a <Tab> or after the last
4804 character.
zeertzjq02f3eba2024-06-12 20:45:24 +02004805
4806 For getting the cursor position see |getcurpos()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004807 The column number in the returned List is the byte position
4808 within the line. To get the character position in the line,
4809 use |getcharpos()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02004810
4811 Note that for '< and '> Visual mode matters: when it is "V"
4812 (visual line mode) the column of '< is zero and the column of
4813 '> is a large number equal to |v:maxcol|.
naohiro ono56200ee2022-01-01 14:59:44 +00004814 A very large column number equal to |v:maxcol| can be returned,
4815 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01004816 If {expr} is invalid, returns a list with all zeros.
zeertzjq02f3eba2024-06-12 20:45:24 +02004817
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004818 This can be used to save and restore the position of a mark: >
4819 let save_a_mark = getpos("'a")
4820 ...
4821 call setpos("'a", save_a_mark)
zeertzjqd353d272024-06-13 23:00:25 +08004822<
4823 Also see |getcharpos()|, |getcurpos()| and |setpos()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004824
4825 Can also be used as a |method|: >
4826 GetMark()->getpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004827<
4828 Return type: list<number>
4829
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004830
4831getqflist([{what}]) *getqflist()*
4832 Returns a |List| with all the current quickfix errors. Each
4833 list item is a dictionary with these entries:
4834 bufnr number of buffer that has the file name, use
4835 bufname() to get the name
4836 module module name
4837 lnum line number in the buffer (first line is 1)
4838 end_lnum
4839 end of line number if the item is multiline
4840 col column number (first column is 1)
4841 end_col end of column number if the item has range
4842 vcol |TRUE|: "col" is visual column
4843 |FALSE|: "col" is byte index
4844 nr error number
h-east84ac2122024-06-17 18:12:30 +02004845 pattern search pattern used to locate the error
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004846 text description of the error
4847 type type of the error, 'E', '1', etc.
4848 valid |TRUE|: recognized error message
h_east596a9f22023-11-21 21:24:23 +09004849 user_data
4850 custom data associated with the item, can be
Tom Praschanca6ac992023-08-11 23:26:12 +02004851 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004852
4853 When there is no error list or it's empty, an empty list is
4854 returned. Quickfix list entries with a non-existing buffer
4855 number are returned with "bufnr" set to zero (Note: some
4856 functions accept buffer number zero for the alternate buffer,
4857 you may need to explicitly check for zero).
4858
4859 Useful application: Find pattern matches in multiple files and
4860 do something with them: >
4861 :vimgrep /theword/jg *.c
4862 :for d in getqflist()
4863 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4864 :endfor
4865<
4866 If the optional {what} dictionary argument is supplied, then
4867 returns only the items listed in {what} as a dictionary. The
4868 following string items are supported in {what}:
4869 changedtick get the total number of changes made
4870 to the list |quickfix-changedtick|
4871 context get the |quickfix-context|
4872 efm errorformat to use when parsing "lines". If
4873 not present, then the 'errorformat' option
4874 value is used.
4875 id get information for the quickfix list with
4876 |quickfix-ID|; zero means the id for the
4877 current list or the list specified by "nr"
4878 idx get information for the quickfix entry at this
4879 index in the list specified by 'id' or 'nr'.
4880 If set to zero, then uses the current entry.
4881 See |quickfix-index|
4882 items quickfix list entries
4883 lines parse a list of lines using 'efm' and return
4884 the resulting entries. Only a |List| type is
4885 accepted. The current quickfix list is not
4886 modified. See |quickfix-parse|.
4887 nr get information for this quickfix list; zero
4888 means the current quickfix list and "$" means
4889 the last quickfix list
4890 qfbufnr number of the buffer displayed in the quickfix
4891 window. Returns 0 if the quickfix buffer is
4892 not present. See |quickfix-buffer|.
4893 size number of entries in the quickfix list
4894 title get the list title |quickfix-title|
4895 winid get the quickfix |window-ID|
4896 all all of the above quickfix properties
4897 Non-string items in {what} are ignored. To get the value of a
4898 particular item, set it to zero.
4899 If "nr" is not present then the current quickfix list is used.
4900 If both "nr" and a non-zero "id" are specified, then the list
4901 specified by "id" is used.
4902 To get the number of lists in the quickfix stack, set "nr" to
4903 "$" in {what}. The "nr" value in the returned dictionary
4904 contains the quickfix stack size.
4905 When "lines" is specified, all the other items except "efm"
4906 are ignored. The returned dictionary contains the entry
4907 "items" with the list of entries.
4908
4909 The returned dictionary contains the following entries:
4910 changedtick total number of changes made to the
4911 list |quickfix-changedtick|
4912 context quickfix list context. See |quickfix-context|
4913 If not present, set to "".
4914 id quickfix list ID |quickfix-ID|. If not
4915 present, set to 0.
4916 idx index of the quickfix entry in the list. If not
4917 present, set to 0.
4918 items quickfix list entries. If not present, set to
4919 an empty list.
4920 nr quickfix list number. If not present, set to 0
4921 qfbufnr number of the buffer displayed in the quickfix
4922 window. If not present, set to 0.
4923 size number of entries in the quickfix list. If not
4924 present, set to 0.
4925 title quickfix list title text. If not present, set
4926 to "".
4927 winid quickfix |window-ID|. If not present, set to 0
4928
4929 Examples (See also |getqflist-examples|): >
4930 :echo getqflist({'all': 1})
4931 :echo getqflist({'nr': 2, 'title': 1})
4932 :echo getqflist({'lines' : ["F1:10:L10"]})
4933<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004934 Return type: list<dict<any>> or list<any>
4935
4936
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004937getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4938 The result is a String, which is the contents of register
4939 {regname}. Example: >
4940 :let cliptext = getreg('*')
4941< When register {regname} was not set the result is an empty
4942 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004943 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004944
4945 getreg('=') returns the last evaluated value of the expression
4946 register. (For use in maps.)
4947 getreg('=', 1) returns the expression itself, so that it can
4948 be restored with |setreg()|. For other registers the extra
4949 argument is ignored, thus you can always give it.
4950
4951 If {list} is present and |TRUE|, the result type is changed
4952 to |List|. Each list item is one text line. Use it if you care
4953 about zero bytes possibly present inside register: without
4954 third argument both NLs and zero bytes are represented as NLs
4955 (see |NL-used-for-Nul|).
4956 When the register was not set an empty list is returned.
4957
4958 If {regname} is "", the unnamed register '"' is used.
4959 If {regname} is not specified, |v:register| is used.
4960 In |Vim9-script| {regname} must be one character.
4961
4962 Can also be used as a |method|: >
4963 GetRegname()->getreg()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004964<
4965 Return type: |String|
4966
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004967
4968getreginfo([{regname}]) *getreginfo()*
4969 Returns detailed information about register {regname} as a
4970 Dictionary with the following entries:
4971 regcontents List of lines contained in register
4972 {regname}, like
4973 |getreg|({regname}, 1, 1).
4974 regtype the type of register {regname}, as in
4975 |getregtype()|.
4976 isunnamed Boolean flag, v:true if this register
4977 is currently pointed to by the unnamed
4978 register.
4979 points_to for the unnamed register, gives the
4980 single letter name of the register
4981 currently pointed to (see |quotequote|).
4982 For example, after deleting a line
4983 with `dd`, this field will be "1",
4984 which is the register that got the
4985 deleted text.
4986
4987 The {regname} argument is a string. If {regname} is invalid
4988 or not set, an empty Dictionary will be returned.
4989 If {regname} is "" or "@", the unnamed register '"' is used.
4990 If {regname} is not specified, |v:register| is used.
4991 The returned Dictionary can be passed to |setreg()|.
4992 In |Vim9-script| {regname} must be one character.
4993
4994 Can also be used as a |method|: >
4995 GetRegname()->getreginfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004996<
4997 Return type: dict<any>
4998
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004999
Shougo Matsushita19b71882024-02-28 22:48:12 +01005000getregion({pos1}, {pos2} [, {opts}]) *getregion()*
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01005001 Returns the list of strings from {pos1} to {pos2} from a
Shougo Matsushita19b71882024-02-28 22:48:12 +01005002 buffer.
5003
5004 {pos1} and {pos2} must both be |List|s with four numbers.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01005005 See |getpos()| for the format of the list. It's possible
5006 to specify positions from a different buffer, but please
zeertzjq0df8f932024-03-07 21:40:53 +01005007 note the limitations at |getregion-notes|.
Shougo Matsushita19b71882024-02-28 22:48:12 +01005008
5009 The optional argument {opts} is a Dict and supports the
5010 following items:
5011
zeertzjqafc22952024-05-24 19:07:12 +02005012 type Specify the region's selection type.
5013 See |getregtype()| for possible values,
zeertzjqdff55a32024-05-25 10:25:36 +02005014 except that the width can be omitted
5015 and an empty string cannot be used.
zeertzjqafc22952024-05-24 19:07:12 +02005016 (default: "v")
Shougo Matsushita19b71882024-02-28 22:48:12 +01005017
zeertzjq87410ab2024-03-02 06:00:23 +08005018 exclusive If |TRUE|, use exclusive selection
zeertzjqafc22952024-05-24 19:07:12 +02005019 for the end position.
zeertzjq87410ab2024-03-02 06:00:23 +08005020 (default: follow 'selection')
Shougo Matsushita19b71882024-02-28 22:48:12 +01005021
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01005022 You can get the last selection type by |visualmode()|.
5023 If Visual mode is active, use |mode()| to get the Visual mode
5024 (e.g., in a |:vmap|).
zeertzjq87410ab2024-03-02 06:00:23 +08005025 This function is useful to get text starting and ending in
5026 different columns, such as a |characterwise-visual| selection.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01005027
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01005028 *getregion-notes*
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01005029 Note that:
5030 - Order of {pos1} and {pos2} doesn't matter, it will always
5031 return content from the upper left position to the lower
5032 right position.
zeertzjq87410ab2024-03-02 06:00:23 +08005033 - If 'virtualedit' is enabled and the region is past the end
5034 of the lines, resulting lines are padded with spaces.
5035 - If the region is blockwise and it starts or ends in the
5036 middle of a multi-cell character, it is not included but
5037 its selected part is substituted with spaces.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01005038 - If {pos1} and {pos2} are not in the same buffer, an empty
zeertzjq421b5972024-02-22 19:48:06 +01005039 list is returned.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01005040 - {pos1} and {pos2} must belong to a |bufloaded()| buffer.
zeertzjq0df8f932024-03-07 21:40:53 +01005041 - It is evaluated in current window context, which makes a
5042 difference if the buffer is displayed in a window with
5043 different 'virtualedit' or 'list' values.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01005044
5045 Examples: >
5046 :xnoremap <CR>
Shougo Matsushita19b71882024-02-28 22:48:12 +01005047 \ <Cmd>echow getregion(
5048 \ getpos('v'), getpos('.'), #{ type: mode() })<CR>
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01005049<
5050 Can also be used as a |method|: >
Shougo Matsushita19b71882024-02-28 22:48:12 +01005051 getpos('.')->getregion(getpos("'a"))
zeertzjqd4d12072024-07-16 20:34:16 +02005052<
5053 Return type: list<string>
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005054
Yee Cheng Chind52fb2f2024-10-31 09:25:09 +01005055
Shougo Matsushitab4757e62024-05-07 20:49:24 +02005056getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()*
5057 Same as |getregion()|, but returns a list of positions
5058 describing the buffer text segments bound by {pos1} and
5059 {pos2}.
5060 The segments are a pair of positions for every line: >
5061 [[{start_pos}, {end_pos}], ...]
5062<
5063 The position is a |List| with four numbers:
5064 [bufnum, lnum, col, off]
5065 "bufnum" is the buffer number.
5066 "lnum" and "col" are the position in the buffer. The first
5067 column is 1.
zeertzjqc95e64f2024-05-20 14:00:31 +02005068 If the "off" number of a starting position is non-zero, it is
5069 the offset in screen columns from the start of the character.
5070 E.g., a position within a <Tab> or after the last character.
5071 If the "off" number of an ending position is non-zero, it is
zeertzjq52a6f342024-05-22 16:42:44 +02005072 the offset of the character's first cell not included in the
5073 selection, otherwise all its cells are included.
Shougo Matsushitab4757e62024-05-07 20:49:24 +02005074
zeertzjq2b09de92024-05-24 07:48:51 +02005075 Apart from the options supported by |getregion()|, {opts} also
5076 supports the following:
5077
5078 eol If |TRUE|, indicate positions beyond
5079 the end of a line with "col" values
5080 one more than the length of the line.
5081 If |FALSE|, positions are limited
5082 within their lines, and if a line is
5083 empty or the selection is entirely
5084 beyond the end of a line, a "col"
5085 value of 0 is used for both positions.
5086 (default: |FALSE|)
5087
Shougo Matsushitab4757e62024-05-07 20:49:24 +02005088 Can also be used as a |method|: >
5089 getpos('.')->getregionpos(getpos("'a"))
5090<
Christian Brabandt83d74402025-03-19 21:55:59 +01005091 For an example, see the highlight-yank plugin |52.6|
5092
zeertzjqd4d12072024-07-16 20:34:16 +02005093 Return type: list<list<list<number>>>
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005094
5095
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005096getregtype([{regname}]) *getregtype()*
5097 The result is a String, which is type of register {regname}.
5098 The value will be one of:
5099 "v" for |characterwise| text
5100 "V" for |linewise| text
5101 "<CTRL-V>{width}" for |blockwise-visual| text
5102 "" for an empty or unknown register
5103 <CTRL-V> is one character with value 0x16.
5104 The {regname} argument is a string. If {regname} is "", the
5105 unnamed register '"' is used. If {regname} is not specified,
5106 |v:register| is used.
5107 In |Vim9-script| {regname} must be one character.
5108
5109 Can also be used as a |method|: >
5110 GetRegname()->getregtype()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005111<
5112 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005113
Yee Cheng Chind52fb2f2024-10-31 09:25:09 +01005114
Bram Moolenaar71badf92023-04-22 22:40:14 +01005115getscriptinfo([{opts}]) *getscriptinfo()*
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01005116 Returns a |List| with information about all the sourced Vim
Bram Moolenaar753885b2022-08-24 16:30:36 +01005117 scripts in the order they were sourced, like what
5118 `:scriptnames` shows.
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01005119
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005120 The optional Dict argument {opts} supports the following
5121 optional items:
5122 name Script name match pattern. If specified,
5123 and "sid" is not specified, information about
Bram Moolenaar71badf92023-04-22 22:40:14 +01005124 scripts with a name that match the pattern
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005125 "name" are returned.
5126 sid Script ID |<SID>|. If specified, only
5127 information about the script with ID "sid" is
5128 returned and "name" is ignored.
5129
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01005130 Each item in the returned List is a |Dict| with the following
5131 items:
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005132 autoload Set to TRUE for a script that was used with
Bram Moolenaar753885b2022-08-24 16:30:36 +01005133 `import autoload` but was not actually sourced
5134 yet (see |import-autoload|).
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005135 functions List of script-local function names defined in
5136 the script. Present only when a particular
5137 script is specified using the "sid" item in
5138 {opts}.
5139 name Vim script file name.
5140 sid Script ID |<SID>|.
5141 sourced Script ID of the actually sourced script that
Bram Moolenaarfd999452022-08-24 18:30:14 +01005142 this script name links to, if any, otherwise
5143 zero
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005144 variables A dictionary with the script-local variables.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00005145 Present only when a particular script is
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005146 specified using the "sid" item in {opts}.
5147 Note that this is a copy, the value of
5148 script-local variables cannot be changed using
5149 this dictionary.
h_east59858792023-10-25 22:47:05 +09005150 version Vim script version (|scriptversion|)
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01005151
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005152 Examples: >
5153 :echo getscriptinfo({'name': 'myscript'})
zeertzjqad4881c2024-05-04 15:35:30 +08005154 :echo getscriptinfo({'sid': 15})[0].variables
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005155<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005156 Return type: list<dict<any>>
5157
5158
ichizok663d18d2025-01-02 18:06:00 +01005159getstacktrace() *getstacktrace()*
5160 Returns the current stack trace of Vim scripts.
5161 Stack trace is a |List|, of which each item is a |Dictionary|
5162 with the following items:
zeertzjq6655bef2025-01-06 18:32:13 +01005163 funcref The funcref if the stack is at a function,
5164 otherwise this item is omitted.
ichizok663d18d2025-01-02 18:06:00 +01005165 event The string of the event description if the
zeertzjq6655bef2025-01-06 18:32:13 +01005166 stack is at an autocmd event, otherwise this
5167 item is omitted.
5168 lnum The line number in the script on the stack.
ichizok663d18d2025-01-02 18:06:00 +01005169 filepath The file path of the script on the stack.
5170
5171 Return type: list<dict<any>>
5172
5173
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005174gettabinfo([{tabnr}]) *gettabinfo()*
5175 If {tabnr} is not specified, then information about all the
5176 tab pages is returned as a |List|. Each List item is a
5177 |Dictionary|. Otherwise, {tabnr} specifies the tab page
5178 number and information about that one is returned. If the tab
5179 page does not exist an empty List is returned.
5180
5181 Each List item is a |Dictionary| with the following entries:
5182 tabnr tab page number.
5183 variables a reference to the dictionary with
5184 tabpage-local variables
5185 windows List of |window-ID|s in the tab page.
5186
5187 Can also be used as a |method|: >
5188 GetTabnr()->gettabinfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005189<
5190 Return type: list<dict<any>>
5191
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005192
5193gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
5194 Get the value of a tab-local variable {varname} in tab page
5195 {tabnr}. |t:var|
5196 Tabs are numbered starting with one.
5197 The {varname} argument is a string. When {varname} is empty a
5198 dictionary with all tab-local variables is returned.
5199 Note that the name without "t:" must be used.
5200 When the tab or variable doesn't exist {def} or an empty
5201 string is returned, there is no error message.
5202
5203 Can also be used as a |method|: >
5204 GetTabnr()->gettabvar(varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005205<
5206 Return type: any, depending on {varname}
5207
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005208
5209gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
5210 Get the value of window-local variable {varname} in window
5211 {winnr} in tab page {tabnr}.
5212 The {varname} argument is a string. When {varname} is empty a
5213 dictionary with all window-local variables is returned.
5214 When {varname} is equal to "&" get the values of all
5215 window-local options in a |Dictionary|.
5216 Otherwise, when {varname} starts with "&" get the value of a
5217 window-local option.
5218 Note that {varname} must be the name without "w:".
5219 Tabs are numbered starting with one. For the current tabpage
5220 use |getwinvar()|.
5221 {winnr} can be the window number or the |window-ID|.
5222 When {winnr} is zero the current window is used.
5223 This also works for a global option, buffer-local option and
5224 window-local option, but it doesn't work for a global variable
5225 or buffer-local variable.
5226 When the tab, window or variable doesn't exist {def} or an
5227 empty string is returned, there is no error message.
5228 Examples: >
5229 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005230 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005231<
5232 To obtain all window-local variables use: >
5233 gettabwinvar({tabnr}, {winnr}, '&')
5234
5235< Can also be used as a |method|: >
5236 GetTabnr()->gettabwinvar(winnr, varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005237<
5238 Return type: any, depending on {varname}
5239
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005240
5241gettagstack([{winnr}]) *gettagstack()*
5242 The result is a Dict, which is the tag stack of window {winnr}.
5243 {winnr} can be the window number or the |window-ID|.
5244 When {winnr} is not specified, the current window is used.
5245 When window {winnr} doesn't exist, an empty Dict is returned.
5246
5247 The returned dictionary contains the following entries:
5248 curidx Current index in the stack. When at
5249 top of the stack, set to (length + 1).
5250 Index of bottom of the stack is 1.
5251 items List of items in the stack. Each item
5252 is a dictionary containing the
5253 entries described below.
5254 length Number of entries in the stack.
5255
5256 Each item in the stack is a dictionary with the following
5257 entries:
5258 bufnr buffer number of the current jump
5259 from cursor position before the tag jump.
5260 See |getpos()| for the format of the
5261 returned list.
5262 matchnr current matching tag number. Used when
5263 multiple matching tags are found for a
5264 name.
5265 tagname name of the tag
5266
5267 See |tagstack| for more information about the tag stack.
5268
5269 Can also be used as a |method|: >
5270 GetWinnr()->gettagstack()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005271<
5272 Return type: dict<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005273
5274
Christ van Willegence0ef912024-06-20 23:41:59 +02005275gettext({text} [, {package}]) *gettext()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005276 Translate String {text} if possible.
RestorerZ96509102024-07-11 21:14:15 +02005277 This is intended for use in Vim scripts. When generating
5278 message translations the {text} is extracted by `xgettext`,
5279 the translator can add translated messages into the .po file
5280 and Vim will lookup the translation when gettext() is called.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005281 For {text} double quoted strings are preferred, because
RestorerZ96509102024-07-11 21:14:15 +02005282 `xgettext` does not support single quoted escaped text.
5283
Christ van Willegence0ef912024-06-20 23:41:59 +02005284 When the {package} is specified, the translation is looked up
RestorerZ96509102024-07-11 21:14:15 +02005285 for that specific package. This is mainly required for
5286 third-party Vim scripts. You need to specify a path to the
5287 translations with the |bindtextdomain()| function before
5288 using the gettext() function.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005289
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005290 Return type: |String|
5291
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005292
5293getwininfo([{winid}]) *getwininfo()*
5294 Returns information about windows as a |List| with Dictionaries.
5295
5296 If {winid} is given Information about the window with that ID
5297 is returned, as a |List| with one item. If the window does not
5298 exist the result is an empty list.
5299
5300 Without {winid} information about all the windows in all the
5301 tab pages is returned.
5302
5303 Each List item is a |Dictionary| with the following entries:
5304 botline last complete displayed buffer line
5305 bufnr number of buffer in the window
5306 height window height (excluding winbar)
glepnir0a850672024-11-25 19:39:04 +01005307 leftcol first column displayed; only used when
5308 'wrap' is off
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005309 loclist 1 if showing a location list
5310 {only with the +quickfix feature}
5311 quickfix 1 if quickfix or location list window
5312 {only with the +quickfix feature}
5313 terminal 1 if a terminal window
5314 {only with the +terminal feature}
5315 tabnr tab page number
5316 topline first displayed buffer line
5317 variables a reference to the dictionary with
5318 window-local variables
5319 width window width
5320 winbar 1 if the window has a toolbar, 0
5321 otherwise
5322 wincol leftmost screen column of the window;
5323 "col" from |win_screenpos()|
5324 textoff number of columns occupied by any
5325 'foldcolumn', 'signcolumn' and line
5326 number in front of the text
5327 winid |window-ID|
5328 winnr window number
5329 winrow topmost screen line of the window;
5330 "row" from |win_screenpos()|
5331
5332 Can also be used as a |method|: >
5333 GetWinnr()->getwininfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005334<
5335 Return type: list<dict<any>>
5336
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005337
5338getwinpos([{timeout}]) *getwinpos()*
5339 The result is a |List| with two numbers, the result of
5340 |getwinposx()| and |getwinposy()| combined:
5341 [x-pos, y-pos]
5342 {timeout} can be used to specify how long to wait in msec for
5343 a response from the terminal. When omitted 100 msec is used.
5344 Use a longer time for a remote terminal.
5345 When using a value less than 10 and no response is received
5346 within that time, a previously reported position is returned,
5347 if available. This can be used to poll for the position and
5348 do some work in the meantime: >
5349 while 1
5350 let res = getwinpos(1)
5351 if res[0] >= 0
5352 break
5353 endif
5354 " Do some work here
5355 endwhile
5356<
5357
5358 Can also be used as a |method|: >
5359 GetTimeout()->getwinpos()
5360<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005361 Return type: list<number>
5362
5363
5364getwinposx() *getwinposx()*
5365 The result is a Number, which is the X coordinate in pixels of
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005366 the left hand side of the GUI Vim window. Also works for an
5367 xterm (uses a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01005368 The result will be -1 if the information is not available
5369 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005370 The value can be used with `:winpos`.
5371
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005372 Return type: |Number|
5373
5374
5375getwinposy() *getwinposy()*
5376 The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005377 the top of the GUI Vim window. Also works for an xterm (uses
5378 a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01005379 The result will be -1 if the information is not available
5380 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005381 The value can be used with `:winpos`.
5382
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005383 Return type: |Number|
5384
5385
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005386getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
5387 Like |gettabwinvar()| for the current tabpage.
5388 Examples: >
5389 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005390 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005391
5392< Can also be used as a |method|: >
5393 GetWinnr()->getwinvar(varname)
5394<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005395 Return type: any, depending on {varname}
5396
5397
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005398glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
5399 Expand the file wildcards in {expr}. See |wildcards| for the
5400 use of special characters.
5401
5402 Unless the optional {nosuf} argument is given and is |TRUE|,
5403 the 'suffixes' and 'wildignore' options apply: Names matching
5404 one of the patterns in 'wildignore' will be skipped and
5405 'suffixes' affect the ordering of matches.
5406 'wildignorecase' always applies.
5407
5408 When {list} is present and it is |TRUE| the result is a |List|
5409 with all matching files. The advantage of using a List is,
5410 you also get filenames containing newlines correctly.
5411 Otherwise the result is a String and when there are several
5412 matches, they are separated by <NL> characters.
5413
5414 If the expansion fails, the result is an empty String or List.
5415
5416 You can also use |readdir()| if you need to do complicated
5417 things, such as limiting the number of matches.
5418
5419 A name for a non-existing file is not included. A symbolic
5420 link is only included if it points to an existing file.
5421 However, when the {alllinks} argument is present and it is
5422 |TRUE| then all symbolic links are included.
5423
5424 For most systems backticks can be used to get files names from
5425 any external command. Example: >
5426 :let tagfiles = glob("`find . -name tags -print`")
5427 :let &tags = substitute(tagfiles, "\n", ",", "g")
5428< The result of the program inside the backticks should be one
5429 item per line. Spaces inside an item are allowed.
5430
5431 See |expand()| for expanding special Vim variables. See
5432 |system()| for getting the raw output of an external command.
5433
5434 Can also be used as a |method|: >
5435 GetExpr()->glob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005436<
5437 Return type: |String| or list<string> or list<any> depending
5438 on {list}
5439
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005440
h-east624bb832024-11-09 18:37:32 +01005441glob2regpat({string}) *glob2regpat()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005442 Convert a file pattern, as used by glob(), into a search
5443 pattern. The result can be used to match with a string that
5444 is a file name. E.g. >
5445 if filename =~ glob2regpat('Make*.mak')
5446< This is equivalent to: >
5447 if filename =~ '^Make.*\.mak$'
5448< When {string} is an empty string the result is "^$", match an
5449 empty string.
5450 Note that the result depends on the system. On MS-Windows
5451 a backslash usually means a path separator.
5452
5453 Can also be used as a |method|: >
5454 GetExpr()->glob2regpat()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005455<
5456 Return type: |String|
5457
5458 *globpath()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005459globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
5460 Perform glob() for String {expr} on all directories in {path}
5461 and concatenate the results. Example: >
5462 :echo globpath(&rtp, "syntax/c.vim")
5463<
5464 {path} is a comma-separated list of directory names. Each
5465 directory name is prepended to {expr} and expanded like with
5466 |glob()|. A path separator is inserted when needed.
5467 To add a comma inside a directory name escape it with a
5468 backslash. Note that on MS-Windows a directory may have a
5469 trailing backslash, remove it if you put a comma after it.
5470 If the expansion fails for one of the directories, there is no
5471 error message.
5472
5473 Unless the optional {nosuf} argument is given and is |TRUE|,
5474 the 'suffixes' and 'wildignore' options apply: Names matching
5475 one of the patterns in 'wildignore' will be skipped and
5476 'suffixes' affect the ordering of matches.
5477
5478 When {list} is present and it is |TRUE| the result is a |List|
5479 with all matching files. The advantage of using a List is, you
5480 also get filenames containing newlines correctly. Otherwise
5481 the result is a String and when there are several matches,
5482 they are separated by <NL> characters. Example: >
5483 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
5484<
5485 {alllinks} is used as with |glob()|.
5486
5487 The "**" item can be used to search in a directory tree.
5488 For example, to find all "README.txt" files in the directories
5489 in 'runtimepath' and below: >
5490 :echo globpath(&rtp, "**/README.txt")
5491< Upwards search and limiting the depth of "**" is not
5492 supported, thus using 'path' will not always work properly.
5493
5494 Can also be used as a |method|, the base is passed as the
5495 second argument: >
5496 GetExpr()->globpath(&rtp)
5497<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005498 Return type: |String| or list<string> or list<any> depending
5499 on {list}
5500
5501
5502has({feature} [, {check}]) *has()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005503 When {check} is omitted or is zero: The result is a Number,
5504 which is 1 if the feature {feature} is supported, zero
5505 otherwise. The {feature} argument is a string, case is
5506 ignored. See |feature-list| below.
5507
5508 When {check} is present and not zero: The result is a Number,
5509 which is 1 if the feature {feature} could ever be supported,
5510 zero otherwise. This is useful to check for a typo in
5511 {feature} and to detect dead code. Keep in mind that an older
5512 Vim version will not know about a feature added later and
5513 features that have been abandoned will not be known by the
5514 current Vim version.
5515
5516 Also see |exists()| and |exists_compiled()|.
5517
5518 Note that to skip code that has a syntax error when the
5519 feature is not available, Vim may skip the rest of the line
5520 and miss a following `endif`. Therefore put the `endif` on a
5521 separate line: >
5522 if has('feature')
5523 let x = this->breaks->without->the->feature
5524 endif
5525< If the `endif` would be moved to the second line as "| endif" it
5526 would not be found.
5527
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005528 Return type: |Number|
5529
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005530
5531has_key({dict}, {key}) *has_key()*
5532 The result is a Number, which is TRUE if |Dictionary| {dict}
Bram Moolenaare8008642022-08-19 17:15:35 +01005533 has an entry with key {key}. FALSE otherwise.
5534 The {key} argument is a string. In |Vim9| script a number is
5535 also accepted (and converted to a string) but no other types.
5536 In legacy script the usual automatic conversion to string is
5537 done.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005538
5539 Can also be used as a |method|: >
5540 mydict->has_key(key)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005541<
5542 Return type: |Number|
5543
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005544
5545haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
5546 The result is a Number:
5547 1 when the window has set a local directory via |:lcd|
5548 2 when the tab-page has set a local directory via |:tcd|
5549 0 otherwise.
5550
5551 Without arguments use the current window.
5552 With {winnr} use this window in the current tab page.
5553 With {winnr} and {tabnr} use the window in the specified tab
5554 page.
5555 {winnr} can be the window number or the |window-ID|.
5556 If {winnr} is -1 it is ignored and only the tabpage is used.
5557 Return 0 if the arguments are invalid.
5558 Examples: >
5559 if haslocaldir() == 1
5560 " window local directory case
5561 elseif haslocaldir() == 2
5562 " tab-local directory case
5563 else
5564 " global directory case
5565 endif
5566
5567 " current window
5568 :echo haslocaldir()
5569 :echo haslocaldir(0)
5570 :echo haslocaldir(0, 0)
5571 " window n in current tab page
5572 :echo haslocaldir(n)
5573 :echo haslocaldir(n, 0)
5574 " window n in tab page m
5575 :echo haslocaldir(n, m)
5576 " tab page m
5577 :echo haslocaldir(-1, m)
5578<
5579 Can also be used as a |method|: >
5580 GetWinnr()->haslocaldir()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005581<
5582 Return type: |Number|
5583
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005584
5585hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
5586 The result is a Number, which is TRUE if there is a mapping
5587 that contains {what} in somewhere in the rhs (what it is
5588 mapped to) and this mapping exists in one of the modes
5589 indicated by {mode}.
5590 The arguments {what} and {mode} are strings.
5591 When {abbr} is there and it is |TRUE| use abbreviations
5592 instead of mappings. Don't forget to specify Insert and/or
5593 Command-line mode.
5594 Both the global mappings and the mappings local to the current
5595 buffer are checked for a match.
5596 If no matching mapping is found FALSE is returned.
5597 The following characters are recognized in {mode}:
5598 n Normal mode
5599 v Visual and Select mode
5600 x Visual mode
5601 s Select mode
5602 o Operator-pending mode
5603 i Insert mode
5604 l Language-Argument ("r", "f", "t", etc.)
5605 c Command-line mode
5606 When {mode} is omitted, "nvo" is used.
5607
5608 This function is useful to check if a mapping already exists
5609 to a function in a Vim script. Example: >
5610 :if !hasmapto('\ABCdoit')
5611 : map <Leader>d \ABCdoit
5612 :endif
5613< This installs the mapping to "\ABCdoit" only if there isn't
5614 already a mapping to "\ABCdoit".
5615
5616 Can also be used as a |method|: >
5617 GetRHS()->hasmapto()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005618<
5619 Return type: |Number|
5620
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005621
5622histadd({history}, {item}) *histadd()*
5623 Add the String {item} to the history {history} which can be
5624 one of: *hist-names*
5625 "cmd" or ":" command line history
5626 "search" or "/" search pattern history
5627 "expr" or "=" typed expression history
5628 "input" or "@" input line history
5629 "debug" or ">" debug command history
5630 empty the current or last used history
5631 The {history} string does not need to be the whole name, one
5632 character is sufficient.
5633 If {item} does already exist in the history, it will be
5634 shifted to become the newest entry.
5635 The result is a Number: TRUE if the operation was successful,
5636 otherwise FALSE is returned.
5637
5638 Example: >
5639 :call histadd("input", strftime("%Y %b %d"))
5640 :let date=input("Enter date: ")
5641< This function is not available in the |sandbox|.
5642
5643 Can also be used as a |method|, the base is passed as the
5644 second argument: >
5645 GetHistory()->histadd('search')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005646<
5647 Return type: |Number|
5648
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005649
5650histdel({history} [, {item}]) *histdel()*
5651 Clear {history}, i.e. delete all its entries. See |hist-names|
5652 for the possible values of {history}.
5653
5654 If the parameter {item} evaluates to a String, it is used as a
5655 regular expression. All entries matching that expression will
5656 be removed from the history (if there are any).
5657 Upper/lowercase must match, unless "\c" is used |/\c|.
5658 If {item} evaluates to a Number, it will be interpreted as
5659 an index, see |:history-indexing|. The respective entry will
5660 be removed if it exists.
5661
5662 The result is TRUE for a successful operation, otherwise FALSE
5663 is returned.
5664
5665 Examples:
5666 Clear expression register history: >
5667 :call histdel("expr")
5668<
5669 Remove all entries starting with "*" from the search history: >
5670 :call histdel("/", '^\*')
5671<
5672 The following three are equivalent: >
5673 :call histdel("search", histnr("search"))
5674 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005675 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005676<
5677 To delete the last search pattern and use the last-but-one for
5678 the "n" command and 'hlsearch': >
5679 :call histdel("search", -1)
5680 :let @/ = histget("search", -1)
5681<
5682 Can also be used as a |method|: >
5683 GetHistory()->histdel()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005684<
5685 Return type: |Number|
5686
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005687
5688histget({history} [, {index}]) *histget()*
5689 The result is a String, the entry with Number {index} from
5690 {history}. See |hist-names| for the possible values of
5691 {history}, and |:history-indexing| for {index}. If there is
5692 no such entry, an empty String is returned. When {index} is
5693 omitted, the most recent item from the history is used.
5694
5695 Examples:
5696 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005697 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005698
5699< Define an Ex command ":H {num}" that supports re-execution of
5700 the {num}th entry from the output of |:history|. >
5701 :command -nargs=1 H execute histget("cmd", 0+<args>)
5702<
5703 Can also be used as a |method|: >
5704 GetHistory()->histget()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005705<
5706 Return type: |String|
5707
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005708
5709histnr({history}) *histnr()*
5710 The result is the Number of the current entry in {history}.
5711 See |hist-names| for the possible values of {history}.
5712 If an error occurred, -1 is returned.
5713
5714 Example: >
5715 :let inp_index = histnr("expr")
5716
5717< Can also be used as a |method|: >
5718 GetHistory()->histnr()
5719<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005720 Return type: |Number|
5721
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005722hlexists({name}) *hlexists()*
5723 The result is a Number, which is TRUE if a highlight group
5724 called {name} exists. This is when the group has been
5725 defined in some way. Not necessarily when highlighting has
5726 been defined for it, it may also have been used for a syntax
5727 item.
5728 *highlight_exists()*
5729 Obsolete name: highlight_exists().
5730
5731 Can also be used as a |method|: >
5732 GetName()->hlexists()
5733<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005734 Return type: |Number|
5735
5736
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005737hlget([{name} [, {resolve}]]) *hlget()*
5738 Returns a List of all the highlight group attributes. If the
5739 optional {name} is specified, then returns a List with only
5740 the attributes of the specified highlight group. Returns an
5741 empty List if the highlight group {name} is not present.
5742
5743 If the optional {resolve} argument is set to v:true and the
5744 highlight group {name} is linked to another group, then the
5745 link is resolved recursively and the attributes of the
5746 resolved highlight group are returned.
5747
5748 Each entry in the returned List is a Dictionary with the
5749 following items:
5750 cleared boolean flag, set to v:true if the highlight
5751 group attributes are cleared or not yet
5752 specified. See |highlight-clear|.
5753 cterm cterm attributes. See |highlight-cterm|.
5754 ctermbg cterm background color.
5755 See |highlight-ctermbg|.
5756 ctermfg cterm foreground color.
5757 See |highlight-ctermfg|.
5758 ctermul cterm underline color. See |highlight-ctermul|.
5759 default boolean flag, set to v:true if the highlight
5760 group link is a default link. See
5761 |highlight-default|.
5762 font highlight group font. See |highlight-font|.
5763 gui gui attributes. See |highlight-gui|.
5764 guibg gui background color. See |highlight-guibg|.
5765 guifg gui foreground color. See |highlight-guifg|.
5766 guisp gui special color. See |highlight-guisp|.
5767 id highlight group ID.
5768 linksto linked highlight group name.
5769 See |:highlight-link|.
5770 name highlight group name. See |group-name|.
5771 start start terminal keycode. See |highlight-start|.
5772 stop stop terminal keycode. See |highlight-stop|.
5773 term term attributes. See |highlight-term|.
5774
5775 The 'term', 'cterm' and 'gui' items in the above Dictionary
5776 have a dictionary value with the following optional boolean
5777 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
5778 'reverse', 'inverse' and 'strikethrough'.
5779
5780 Example(s): >
5781 :echo hlget()
5782 :echo hlget('ModeMsg')
5783 :echo hlget('Number', v:true)
5784<
5785 Can also be used as a |method|: >
5786 GetName()->hlget()
5787<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005788 Return type: list<dict<any>>
5789
5790
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005791hlset({list}) *hlset()*
5792 Creates or modifies the attributes of a List of highlight
5793 groups. Each item in {list} is a dictionary containing the
5794 attributes of a highlight group. See |hlget()| for the list of
5795 supported items in this dictionary.
5796
5797 In addition to the items described in |hlget()|, the following
5798 additional items are supported in the dictionary:
5799
5800 force boolean flag to force the creation of
5801 a link for an existing highlight group
5802 with attributes.
5803
5804 The highlight group is identified using the 'name' item and
5805 the 'id' item (if supplied) is ignored. If a highlight group
5806 with a specified name doesn't exist, then it is created.
5807 Otherwise the attributes of an existing highlight group are
5808 modified.
5809
5810 If an empty dictionary value is used for the 'term' or 'cterm'
5811 or 'gui' entries, then the corresponding attributes are
5812 cleared. If the 'cleared' item is set to v:true, then all the
5813 attributes of the highlight group are cleared.
5814
5815 The 'linksto' item can be used to link a highlight group to
5816 another highlight group. See |:highlight-link|.
5817
5818 Returns zero for success, -1 for failure.
5819
5820 Example(s): >
5821 " add bold attribute to the Visual highlight group
5822 :call hlset([#{name: 'Visual',
5823 \ term: #{reverse: 1 , bold: 1}}])
5824 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
5825 :let l = hlget()
5826 :call hlset(l)
5827 " clear the Search highlight group
5828 :call hlset([#{name: 'Search', cleared: v:true}])
5829 " clear the 'term' attributes for a highlight group
5830 :call hlset([#{name: 'Title', term: {}}])
5831 " create the MyHlg group linking it to DiffAdd
5832 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
5833 " remove the MyHlg group link
5834 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
5835 " clear the attributes and a link
5836 :call hlset([#{name: 'MyHlg', cleared: v:true,
5837 \ linksto: 'NONE'}])
5838<
5839 Can also be used as a |method|: >
5840 GetAttrList()->hlset()
5841<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005842 Return type: |Number|
5843
5844hlID({name}) *hlID()*
5845 The result is a Number, which is the ID of the highlight group
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005846 with name {name}. When the highlight group doesn't exist,
5847 zero is returned.
5848 This can be used to retrieve information about the highlight
5849 group. For example, to get the background color of the
5850 "Comment" group: >
5851 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5852< *highlightID()*
5853 Obsolete name: highlightID().
5854
5855 Can also be used as a |method|: >
5856 GetName()->hlID()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005857<
5858 Return type: |Number|
5859
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005860
5861hostname() *hostname()*
5862 The result is a String, which is the name of the machine on
5863 which Vim is currently running. Machine names greater than
5864 256 characters long are truncated.
5865
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005866 Return type: |String|
5867
5868
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005869iconv({string}, {from}, {to}) *iconv()*
5870 The result is a String, which is the text {string} converted
5871 from encoding {from} to encoding {to}.
5872 When the conversion completely fails an empty string is
5873 returned. When some characters could not be converted they
5874 are replaced with "?".
5875 The encoding names are whatever the iconv() library function
5876 can accept, see ":!man 3 iconv".
5877 Most conversions require Vim to be compiled with the |+iconv|
5878 feature. Otherwise only UTF-8 to latin1 conversion and back
5879 can be done.
5880 This can be used to display messages with special characters,
5881 no matter what 'encoding' is set to. Write the message in
5882 UTF-8 and use: >
5883 echo iconv(utf8_str, "utf-8", &enc)
5884< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5885 from/to UCS-2 is automatically changed to use UTF-8. You
5886 cannot use UCS-2 in a string anyway, because of the NUL bytes.
5887
5888 Can also be used as a |method|: >
5889 GetText()->iconv('latin1', 'utf-8')
5890<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005891 Return type: |String|
5892
5893
h-east624bb832024-11-09 18:37:32 +01005894id({item}) *id()*
Ernie Raelc8e158b2024-07-09 18:39:52 +02005895 The result is a unique String associated with the {item} and
5896 not with the {item}'s contents. It is only valid while the
5897 {item} exists and is referenced. It is valid only in the
5898 instance of vim that produces the result. The whole idea is
5899 that `id({item})` does not change if the contents of {item}
5900 changes. This is useful as a `key` for creating an identity
5901 dictionary, rather than one based on equals.
5902
5903 This operation does not reference {item} and there is no
5904 function to convert the `id` to the {item}. It may be useful to
5905 have a map of `id` to {item}. The following >
5906 var referenceMap: dict<any>
5907 var id = item->id()
5908 referenceMap[id] = item
5909< prevents {item} from being garbage collected and provides a
5910 way to get the {item} from the `id`.
5911
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01005912 {item} may be a List, Tuple, Dictionary, Object, Job, Channel
5913 or Blob. If the item is not a permitted type, or it is a null
Ernie Raelc8e158b2024-07-09 18:39:52 +02005914 value, then an empty String is returned.
5915
5916 Can also be used as a |method|: >
5917 GetItem()->id()
5918<
5919 Return type: |String|
5920
5921
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005922indent({lnum}) *indent()*
5923 The result is a Number, which is indent of line {lnum} in the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005924 current buffer. The indent is counted in spaces, the value
5925 of 'tabstop' is relevant. {lnum} is used just like in
5926 |getline()|.
5927 When {lnum} is invalid -1 is returned. In |Vim9| script an
5928 error is given.
5929
5930 Can also be used as a |method|: >
5931 GetLnum()->indent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005932<
5933 Return type: |Number|
5934
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005935
5936index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005937 Find {expr} in {object} and return its index. See
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005938 |indexof()| for using a lambda to select the item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005939
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01005940 If {object} is a |List| or a |Tuple| return the lowest index
5941 where the item has a value equal to {expr}. There is no
5942 automatic conversion, so the String "4" is different from the
5943 Number 4. And the number 4 is different from the Float 4.0.
5944 The value of 'ignorecase' is not used here, case matters as
5945 indicated by the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005946
5947 If {object} is |Blob| return the lowest index where the byte
5948 value is equal to {expr}.
5949
5950 If {start} is given then start looking at the item with index
5951 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005952
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005953 When {ic} is given and it is |TRUE|, ignore case. Otherwise
5954 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005955
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005956 -1 is returned when {expr} is not found in {object}.
5957 Example: >
5958 :let idx = index(words, "the")
5959 :if index(numbers, 123) >= 0
5960
5961< Can also be used as a |method|: >
5962 GetObject()->index(what)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005963<
5964 Return type: |Number|
5965
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005966
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005967indexof({object}, {expr} [, {opts}]) *indexof()*
5968 Returns the index of an item in {object} where {expr} is
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01005969 v:true. {object} must be a |List|, a |Tuple| or a |Blob|.
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005970
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01005971 If {object} is a |List| or a |Tuple|, evaluate {expr} for each
Christ van Willegen92e109f2025-03-24 20:12:37 +01005972 item in the List or Tuple until the expression is v:true
5973 and return the index of this item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005974
5975 If {object} is a |Blob| evaluate {expr} for each byte in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005976 Blob until the expression is v:true and return the index of
5977 this byte.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005978
5979 {expr} must be a |string| or |Funcref|.
5980
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01005981 If {expr} is a |string|: If {object} is a |List| or a |Tuple|,
5982 inside {expr} |v:key| has the index of the current List or
5983 Tuple item and |v:val| has the value of the item. If {object}
5984 is a |Blob|, inside {expr} |v:key| has the index of the
5985 current byte and |v:val| has the byte value.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005986
5987 If {expr} is a |Funcref| it must take two arguments:
5988 1. the key or the index of the current item.
5989 2. the value of the current item.
5990 The function must return |TRUE| if the item is found and the
5991 search should stop.
5992
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005993 The optional argument {opts} is a Dict and supports the
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005994 following items:
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005995 startidx start evaluating {expr} at the item with this
5996 index; may be negative for an item relative to
5997 the end
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005998 Returns -1 when {expr} evaluates to v:false for all the items.
5999 Example: >
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01006000 :let l = [#{n: 10}, #{n: 20}, #{n: 30}]
6001 :echo indexof(l, "v:val.n == 20")
6002 :echo indexof(l, {i, v -> v.n == 30})
6003 :echo indexof(l, "v:val.n == 20", #{startidx: 1})
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01006004
6005< Can also be used as a |method|: >
6006 mylist->indexof(expr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006007<
6008 Return type: |Number|
6009
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01006010
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006011input({prompt} [, {text} [, {completion}]]) *input()*
6012 The result is a String, which is whatever the user typed on
6013 the command-line. The {prompt} argument is either a prompt
6014 string, or a blank string (for no prompt). A '\n' can be used
6015 in the prompt to start a new line.
6016 The highlighting set with |:echohl| is used for the prompt.
6017 The input is entered just like a command-line, with the same
6018 editing commands and mappings. There is a separate history
6019 for lines typed for input().
6020 Example: >
6021 :if input("Coffee or beer? ") == "beer"
6022 : echo "Cheers!"
6023 :endif
6024<
6025 If the optional {text} argument is present and not empty, this
6026 is used for the default reply, as if the user typed this.
6027 Example: >
6028 :let color = input("Color? ", "white")
6029
6030< The optional {completion} argument specifies the type of
6031 completion supported for the input. Without it completion is
6032 not performed. The supported completion types are the same as
6033 that can be supplied to a user-defined command using the
6034 "-complete=" argument. Refer to |:command-completion| for
6035 more information. Example: >
6036 let fname = input("File: ", "", "file")
6037<
6038 NOTE: This function must not be used in a startup file, for
6039 the versions that only run in GUI mode (e.g., the Win32 GUI).
6040 Note: When input() is called from within a mapping it will
6041 consume remaining characters from that mapping, because a
6042 mapping is handled like the characters were typed.
6043 Use |inputsave()| before input() and |inputrestore()|
6044 after input() to avoid that. Another solution is to avoid
6045 that further characters follow in the mapping, e.g., by using
6046 |:execute| or |:normal|.
6047
6048 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006049 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006050 :function GetFoo()
6051 : call inputsave()
6052 : let g:Foo = input("enter search pattern: ")
6053 : call inputrestore()
6054 :endfunction
6055
6056< Can also be used as a |method|: >
6057 GetPrompt()->input()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006058<
6059 Return type: |String|
6060
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006061
6062inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
6063 Like |input()|, but when the GUI is running and text dialogs
6064 are supported, a dialog window pops up to input the text.
6065 Example: >
6066 :let n = inputdialog("value for shiftwidth", shiftwidth())
6067 :if n != ""
6068 : let &sw = n
6069 :endif
6070< When the dialog is cancelled {cancelreturn} is returned. When
6071 omitted an empty string is returned.
6072 Hitting <Enter> works like pressing the OK button. Hitting
6073 <Esc> works like pressing the Cancel button.
6074 NOTE: Command-line completion is not supported.
6075
6076 Can also be used as a |method|: >
6077 GetPrompt()->inputdialog()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006078<
6079 Return type: |String|
6080
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006081
6082inputlist({textlist}) *inputlist()*
6083 {textlist} must be a |List| of strings. This |List| is
6084 displayed, one string per line. The user will be prompted to
6085 enter a number, which is returned.
6086 The user can also select an item by clicking on it with the
6087 mouse, if the mouse is enabled in the command line ('mouse' is
6088 "a" or includes "c"). For the first string 0 is returned.
6089 When clicking above the first item a negative number is
6090 returned. When clicking on the prompt one more than the
6091 length of {textlist} is returned.
6092 Make sure {textlist} has less than 'lines' entries, otherwise
6093 it won't work. It's a good idea to put the entry number at
6094 the start of the string. And put a prompt in the first item.
6095 Example: >
6096 let color = inputlist(['Select color:', '1. red',
6097 \ '2. green', '3. blue'])
6098
6099< Can also be used as a |method|: >
6100 GetChoices()->inputlist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006101<
6102 Return type: |Number|
6103
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006104
6105inputrestore() *inputrestore()*
6106 Restore typeahead that was saved with a previous |inputsave()|.
6107 Should be called the same number of times inputsave() is
6108 called. Calling it more often is harmless though.
6109 Returns TRUE when there is nothing to restore, FALSE otherwise.
6110
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006111 Return type: |Number|
6112
6113
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006114inputsave() *inputsave()*
6115 Preserve typeahead (also from mappings) and clear it, so that
6116 a following prompt gets input from the user. Should be
6117 followed by a matching inputrestore() after the prompt. Can
6118 be used several times, in which case there must be just as
6119 many inputrestore() calls.
6120 Returns TRUE when out of memory, FALSE otherwise.
6121
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006122 Return type: |Number|
6123
6124
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006125inputsecret({prompt} [, {text}]) *inputsecret()*
6126 This function acts much like the |input()| function with but
6127 two exceptions:
6128 a) the user's response will be displayed as a sequence of
6129 asterisks ("*") thereby keeping the entry secret, and
6130 b) the user's response will not be recorded on the input
6131 |history| stack.
6132 The result is a String, which is whatever the user actually
6133 typed on the command-line in response to the issued prompt.
6134 NOTE: Command-line completion is not supported.
6135
6136 Can also be used as a |method|: >
6137 GetPrompt()->inputsecret()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006138<
6139 Return type: |String|
6140
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006141
6142insert({object}, {item} [, {idx}]) *insert()*
6143 When {object} is a |List| or a |Blob| insert {item} at the start
6144 of it.
6145
6146 If {idx} is specified insert {item} before the item with index
6147 {idx}. If {idx} is zero it goes before the first item, just
6148 like omitting {idx}. A negative {idx} is also possible, see
6149 |list-index|. -1 inserts just before the last item.
6150
6151 Returns the resulting |List| or |Blob|. Examples: >
6152 :let mylist = insert([2, 3, 5], 1)
6153 :call insert(mylist, 4, -1)
6154 :call insert(mylist, 6, len(mylist))
6155< The last example can be done simpler with |add()|.
6156 Note that when {item} is a |List| it is inserted as a single
6157 item. Use |extend()| to concatenate |Lists|.
6158
6159 Can also be used as a |method|: >
6160 mylist->insert(item)
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07006161<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006162 Return type: |Number|
6163
6164
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07006165 *instanceof()* *E614* *E616* *E693*
6166instanceof({object}, {class})
6167 The result is a Number, which is |TRUE| when the {object}
Ernie Rael2025af12023-12-12 16:58:00 +01006168 argument is a direct or indirect instance of a |Class|,
6169 |Interface|, or class |:type| alias specified by {class}.
6170 If {class} is varargs, the function returns |TRUE| when
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07006171 {object} is an instance of any of the specified classes.
LemonBoyafe04662023-08-23 21:08:11 +02006172 Example: >
Ernie Rael2025af12023-12-12 16:58:00 +01006173 instanceof(animal, Dog, Cat)
LemonBoyafe04662023-08-23 21:08:11 +02006174
6175< Can also be used as a |method|: >
6176 myobj->instanceof(mytype)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006177<
6178 Return type: |Number|
LemonBoyafe04662023-08-23 21:08:11 +02006179
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006180interrupt() *interrupt()*
6181 Interrupt script execution. It works more or less like the
6182 user typing CTRL-C, most commands won't execute and control
6183 returns to the user. This is useful to abort execution
6184 from lower down, e.g. in an autocommand. Example: >
6185 :function s:check_typoname(file)
6186 : if fnamemodify(a:file, ':t') == '['
6187 : echomsg 'Maybe typo'
6188 : call interrupt()
6189 : endif
6190 :endfunction
6191 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006192<
6193 Return type: void
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006194
6195invert({expr}) *invert()*
6196 Bitwise invert. The argument is converted to a number. A
6197 List, Dict or Float argument causes an error. Example: >
6198 :let bits = invert(bits)
6199< Can also be used as a |method|: >
6200 :let bits = bits->invert()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006201<
6202 Return type: |Number|
6203
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006204
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01006205isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01006206 The result is a Number, which is |TRUE| when {path} is an
6207 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01006208 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01006209 On MS-Windows, it is considered absolute when it starts with an
6210 optional drive prefix and is followed by a '\' or '/'. UNC paths
6211 are always absolute.
6212 Example: >
6213 echo isabsolutepath('/usr/share/') " 1
6214 echo isabsolutepath('./foobar') " 0
6215 echo isabsolutepath('C:\Windows') " 1
6216 echo isabsolutepath('foobar') " 0
6217 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01006218<
LemonBoydca1d402022-04-28 15:26:33 +01006219 Can also be used as a |method|: >
6220 GetName()->isabsolutepath()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006221<
6222 Return type: |Number|
LemonBoydca1d402022-04-28 15:26:33 +01006223
6224
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006225isdirectory({directory}) *isdirectory()*
6226 The result is a Number, which is |TRUE| when a directory
6227 with the name {directory} exists. If {directory} doesn't
6228 exist, or isn't a directory, the result is |FALSE|. {directory}
6229 is any expression, which is used as a String.
6230
6231 Can also be used as a |method|: >
6232 GetName()->isdirectory()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006233<
6234 Return type: |Number|
6235
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006236
6237isinf({expr}) *isinf()*
6238 Return 1 if {expr} is a positive infinity, or -1 a negative
6239 infinity, otherwise 0. >
6240 :echo isinf(1.0 / 0.0)
6241< 1 >
6242 :echo isinf(-1.0 / 0.0)
6243< -1
6244
6245 Can also be used as a |method|: >
6246 Compute()->isinf()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006247<
6248 Return type: |Number|
6249
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006250
6251islocked({expr}) *islocked()* *E786*
6252 The result is a Number, which is |TRUE| when {expr} is the
6253 name of a locked variable.
6254 The string argument {expr} must be the name of a variable,
6255 |List| item or |Dictionary| entry, not the variable itself!
6256 Example: >
6257 :let alist = [0, ['a', 'b'], 2, 3]
6258 :lockvar 1 alist
6259 :echo islocked('alist') " 1
6260 :echo islocked('alist[1]') " 0
6261
Bram Moolenaar9da17d72022-02-09 21:50:44 +00006262< When {expr} is a variable that does not exist -1 is returned.
6263 If {expr} uses a range, list or dict index that is out of
6264 range or does not exist you get an error message. Use
6265 |exists()| to check for existence.
6266 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006267
6268 Can also be used as a |method|: >
6269 GetName()->islocked()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006270<
6271 Return type: |Number|
6272
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006273
6274isnan({expr}) *isnan()*
6275 Return |TRUE| if {expr} is a float with value NaN. >
6276 echo isnan(0.0 / 0.0)
6277< 1
6278
6279 Can also be used as a |method|: >
6280 Compute()->isnan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006281<
6282 Return type: |Number|
6283
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006284
6285items({dict}) *items()*
6286 Return a |List| with all the key-value pairs of {dict}. Each
6287 |List| item is a list with two items: the key of a {dict}
6288 entry and the value of this entry. The |List| is in arbitrary
6289 order. Also see |keys()| and |values()|.
6290 Example: >
6291 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006292 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006293 endfor
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01006294<
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006295 A |List|, a |Tuple| or a |String| argument is also supported.
6296 In these cases, items() returns a List with the index and the
6297 value at the index.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006298
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01006299 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006300 mydict->items()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006301<
6302 Return type: list<list<any>> or list<any>
6303
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006304
6305job_ functions are documented here: |job-functions-details|
6306
6307
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006308join({expr} [, {sep}]) *join()*
6309 Join the items in {expr} together into one String. {expr} can
6310 be a |List| or a |Tuple|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006311 When {sep} is specified it is put in between the items. If
6312 {sep} is omitted a single space is used.
6313 Note that {sep} is not added at the end. You might want to
6314 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006315 let lines = join(mylist, "\n") .. "\n"
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006316< String items are used as-is. |Lists|, |Tuples| and
6317 |Dictionaries| are converted into a string like with
6318 |string()|. The opposite function is |split()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006319
6320 Can also be used as a |method|: >
6321 mylist->join()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006322<
6323 Return type: |String|
6324
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006325
6326js_decode({string}) *js_decode()*
6327 This is similar to |json_decode()| with these differences:
6328 - Object key names do not have to be in quotes.
6329 - Strings can be in single quotes.
6330 - Empty items in an array (between two commas) are allowed and
6331 result in v:none items.
6332
6333 Can also be used as a |method|: >
6334 ReadObject()->js_decode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006335<
6336 Return type: any, depending on {varname}
6337
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006338
6339js_encode({expr}) *js_encode()*
6340 This is similar to |json_encode()| with these differences:
6341 - Object key names are not in quotes.
6342 - v:none items in an array result in an empty item between
6343 commas.
6344 For example, the Vim object:
6345 [1,v:none,{"one":1},v:none] ~
6346 Will be encoded as:
6347 [1,,{one:1},,] ~
6348 While json_encode() would produce:
6349 [1,null,{"one":1},null] ~
6350 This encoding is valid for JavaScript. It is more efficient
6351 than JSON, especially when using an array with optional items.
6352
6353 Can also be used as a |method|: >
6354 GetObject()->js_encode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006355<
6356 Return type: |String|
6357
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006358
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00006359json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006360 This parses a JSON formatted string and returns the equivalent
6361 in Vim values. See |json_encode()| for the relation between
6362 JSON and Vim values.
6363 The decoding is permissive:
6364 - A trailing comma in an array and object is ignored, e.g.
6365 "[1, 2, ]" is the same as "[1, 2]".
6366 - Integer keys are accepted in objects, e.g. {1:2} is the
6367 same as {"1":2}.
6368 - More floating point numbers are recognized, e.g. "1." for
6369 "1.0", or "001.2" for "1.2". Special floating point values
6370 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
6371 are accepted.
6372 - Leading zeroes in integer numbers are ignored, e.g. "012"
6373 for "12" or "-012" for "-12".
6374 - Capitalization is ignored in literal names null, true or
6375 false, e.g. "NULL" for "null", "True" for "true".
6376 - Control characters U+0000 through U+001F which are not
6377 escaped in strings are accepted, e.g. " " (tab
6378 character in string) for "\t".
6379 - An empty JSON expression or made of only spaces is accepted
6380 and results in v:none.
6381 - Backslash in an invalid 2-character sequence escape is
6382 ignored, e.g. "\a" is decoded as "a".
6383 - A correct surrogate pair in JSON strings should normally be
6384 a 12 character sequence such as "\uD834\uDD1E", but
6385 json_decode() silently accepts truncated surrogate pairs
6386 such as "\uD834" or "\uD834\u"
6387 *E938*
6388 A duplicate key in an object, valid in rfc7159, is not
6389 accepted by json_decode() as the result must be a valid Vim
6390 type, e.g. this fails: {"a":"b", "a":"c"}
6391
6392 Can also be used as a |method|: >
6393 ReadObject()->json_decode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006394<
6395 Return type: any, depending on {varname}
6396
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006397
6398json_encode({expr}) *json_encode()*
6399 Encode {expr} as JSON and return this as a string.
6400 The encoding is specified in:
6401 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00006402 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006403 |Number| decimal number
6404 |Float| floating point number
6405 Float nan "NaN"
6406 Float inf "Infinity"
6407 Float -inf "-Infinity"
6408 |String| in double quotes (possibly null)
6409 |Funcref| not possible, error
6410 |List| as an array (possibly null); when
6411 used recursively: []
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006412 |Tuple| as an array (possibly null); when
6413 used recursively: []
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006414 |Dict| as an object (possibly null); when
6415 used recursively: {}
6416 |Blob| as an array of the individual bytes
6417 v:false "false"
6418 v:true "true"
6419 v:none "null"
6420 v:null "null"
6421 Note that NaN and Infinity are passed on as values. This is
6422 missing in the JSON standard, but several implementations do
6423 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006424 If a string contains an illegal character then the replacement
6425 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006426
6427 Can also be used as a |method|: >
6428 GetObject()->json_encode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006429<
6430 Return type: |String|
6431
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006432
6433keys({dict}) *keys()*
6434 Return a |List| with all the keys of {dict}. The |List| is in
6435 arbitrary order. Also see |items()| and |values()|.
6436
6437 Can also be used as a |method|: >
6438 mydict->keys()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006439<
6440 Return type: list<string>
6441
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006442
zeertzjqcdc83932022-09-12 13:38:41 +01006443keytrans({string}) *keytrans()*
6444 Turn the internal byte representation of keys into a form that
6445 can be used for |:map|. E.g. >
6446 :let xx = "\<C-Home>"
6447 :echo keytrans(xx)
6448< <C-Home>
6449
6450 Can also be used as a |method|: >
6451 "\<C-Home>"->keytrans()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006452<
6453 Return type: |String|
zeertzjqcdc83932022-09-12 13:38:41 +01006454
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006455
6456len({expr}) *len()* *E701*
6457 The result is a Number, which is the length of the argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006458 When {expr} is a String or a Number the length in bytes is
6459 used, as with |strlen()|.
6460 When {expr} is a |List| the number of items in the |List| is
6461 returned.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006462 When {expr} is a |Tuple| the number of items in the |Tuple| is
6463 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006464 When {expr} is a |Blob| the number of bytes is returned.
6465 When {expr} is a |Dictionary| the number of entries in the
6466 |Dictionary| is returned.
mityu7f0bba22024-03-29 10:14:41 +01006467 When {expr} is an |Object|, invokes the len() method in the
6468 object (if present) to get the length (|object-len()|).
6469 Otherwise returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006470
6471 Can also be used as a |method|: >
6472 mylist->len()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006473<
6474 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006475
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006476
6477 *libcall()* *E364* *E368*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006478libcall({libname}, {funcname}, {argument})
6479 Call function {funcname} in the run-time library {libname}
6480 with single argument {argument}.
6481 This is useful to call functions in a library that you
6482 especially made to be used with Vim. Since only one argument
6483 is possible, calling standard library functions is rather
6484 limited.
6485 The result is the String returned by the function. If the
6486 function returns NULL, this will appear as an empty string ""
6487 to Vim.
6488 If the function returns a number, use libcallnr()!
6489 If {argument} is a number, it is passed to the function as an
6490 int; if {argument} is a string, it is passed as a
6491 null-terminated string.
6492 This function will fail in |restricted-mode|.
6493
6494 libcall() allows you to write your own 'plug-in' extensions to
6495 Vim without having to recompile the program. It is NOT a
6496 means to call system functions! If you try to do so Vim will
6497 very probably crash.
6498
6499 For Win32, the functions you write must be placed in a DLL
6500 and use the normal C calling convention (NOT Pascal which is
6501 used in Windows System DLLs). The function must take exactly
6502 one parameter, either a character pointer or a long integer,
6503 and must return a character pointer or NULL. The character
6504 pointer returned must point to memory that will remain valid
6505 after the function has returned (e.g. in static data in the
6506 DLL). If it points to allocated memory, that memory will
6507 leak away. Using a static buffer in the function should work,
6508 it's then freed when the DLL is unloaded.
6509
6510 WARNING: If the function returns a non-valid pointer, Vim may
6511 crash! This also happens if the function returns a number,
6512 because Vim thinks it's a pointer.
6513 For Win32 systems, {libname} should be the filename of the DLL
6514 without the ".DLL" suffix. A full path is only required if
6515 the DLL is not in the usual places.
6516 For Unix: When compiling your own plugins, remember that the
6517 object code must be compiled as position-independent ('PIC').
6518 {only in Win32 and some Unix versions, when the |+libcall|
6519 feature is present}
6520 Examples: >
6521 :echo libcall("libc.so", "getenv", "HOME")
6522
6523< Can also be used as a |method|, the base is passed as the
6524 third argument: >
6525 GetValue()->libcall("libc.so", "getenv")
6526<
6527 *libcallnr()*
6528libcallnr({libname}, {funcname}, {argument})
6529 Just like |libcall()|, but used for a function that returns an
6530 int instead of a string.
6531 {only in Win32 on some Unix versions, when the |+libcall|
6532 feature is present}
6533 Examples: >
6534 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
6535 :call libcallnr("libc.so", "printf", "Hello World!\n")
6536 :call libcallnr("libc.so", "sleep", 10)
6537<
6538 Can also be used as a |method|, the base is passed as the
6539 third argument: >
6540 GetValue()->libcallnr("libc.so", "printf")
6541<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006542 Return type: |String|
6543
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006544
6545line({expr} [, {winid}]) *line()*
6546 The result is a Number, which is the line number of the file
6547 position given with {expr}. The {expr} argument is a string.
zeertzjq02f3eba2024-06-12 20:45:24 +02006548 See |getpos()| for accepted positions.
6549
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006550 To get the column number use |col()|. To get both use
6551 |getpos()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02006552
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006553 With the optional {winid} argument the values are obtained for
6554 that window instead of the current window.
zeertzjq02f3eba2024-06-12 20:45:24 +02006555
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006556 Returns 0 for invalid values of {expr} and {winid}.
zeertzjq02f3eba2024-06-12 20:45:24 +02006557
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006558 Examples: >
6559 line(".") line number of the cursor
6560 line(".", winid) idem, in window "winid"
6561 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006562 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006563<
6564 To jump to the last known position when opening a file see
6565 |last-position-jump|.
6566
6567 Can also be used as a |method|: >
6568 GetValue()->line()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006569<
6570 Return type: |Number|
6571
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006572
6573line2byte({lnum}) *line2byte()*
6574 Return the byte count from the start of the buffer for line
6575 {lnum}. This includes the end-of-line character, depending on
6576 the 'fileformat' option for the current buffer. The first
6577 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
6578 This can also be used to get the byte count for the line just
6579 below the last line: >
6580 line2byte(line("$") + 1)
6581< This is the buffer size plus one. If 'fileencoding' is empty
6582 it is the file size plus one. {lnum} is used like with
6583 |getline()|. When {lnum} is invalid, or the |+byte_offset|
6584 feature has been disabled at compile time, -1 is returned.
6585 Also see |byte2line()|, |go| and |:goto|.
6586
6587 Can also be used as a |method|: >
6588 GetLnum()->line2byte()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006589<
6590 Return type: |Number|
6591
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006592
6593lispindent({lnum}) *lispindent()*
6594 Get the amount of indent for line {lnum} according the lisp
6595 indenting rules, as with 'lisp'.
6596 The indent is counted in spaces, the value of 'tabstop' is
6597 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01006598 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006599 error is given.
6600
6601 Can also be used as a |method|: >
6602 GetLnum()->lispindent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006603<
6604 Return type: |Number|
6605
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006606
6607list2blob({list}) *list2blob()*
6608 Return a Blob concatenating all the number values in {list}.
6609 Examples: >
6610 list2blob([1, 2, 3, 4]) returns 0z01020304
6611 list2blob([]) returns 0z
6612< Returns an empty Blob on error. If one of the numbers is
6613 negative or more than 255 error *E1239* is given.
6614
6615 |blob2list()| does the opposite.
6616
6617 Can also be used as a |method|: >
6618 GetList()->list2blob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006619<
6620 Return type: |Blob|
6621
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006622
6623list2str({list} [, {utf8}]) *list2str()*
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006624 Convert each number in {list} to a character string and
6625 concatenates them all. Examples: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006626 list2str([32]) returns " "
6627 list2str([65, 66, 67]) returns "ABC"
6628< The same can be done (slowly) with: >
6629 join(map(list, {nr, val -> nr2char(val)}), '')
6630< |str2list()| does the opposite.
6631
6632 When {utf8} is omitted or zero, the current 'encoding' is used.
6633 When {utf8} is TRUE, always return UTF-8 characters.
6634 With UTF-8 composing characters work as expected: >
6635 list2str([97, 769]) returns "á"
6636<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006637 Returns an empty string on error.
6638
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006639 Can also be used as a |method|: >
6640 GetList()->list2str()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006641<
6642 Return type: |String|
6643
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006644
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01006645list2tuple({list}) *list2tuple()*
6646 Create a Tuple from a shallow copy of the list items.
6647 Examples: >
6648 list2tuple([1, 2, 3]) returns (1, 2, 3)
6649< |tuple2list()| does the opposite.
6650
6651 This function doesn't recursively convert all the List items
6652 in {list} to a Tuple. Note that the items are identical
6653 between the list and the tuple, changing an item changes the
6654 contents of both the tuple and the list.
6655
6656 Returns an empty tuple on error.
6657
6658 Can also be used as a |method|: >
6659 GetList()->list2tuple()
6660<
6661 Return type: tuple<{type}> (depending on the given |List|)
6662
6663
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006664listener_add({callback} [, {buf}]) *listener_add()*
6665 Add a callback function that will be invoked when changes have
6666 been made to buffer {buf}.
6667 {buf} refers to a buffer name or number. For the accepted
6668 values, see |bufname()|. When {buf} is omitted the current
6669 buffer is used.
6670 Returns a unique ID that can be passed to |listener_remove()|.
6671
6672 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00006673 bufnr the buffer that was changed
6674 start first changed line number
6675 end first line number below the change
6676 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006677 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00006678 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006679
6680 Example: >
6681 func Listener(bufnr, start, end, added, changes)
6682 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
6683 endfunc
6684 call listener_add('Listener', bufnr)
6685
Bram Moolenaar944697a2022-02-20 19:48:20 +00006686< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006687 dictionary with these entries:
6688 lnum the first line number of the change
6689 end the first line below the change
6690 added number of lines added; negative if lines were
6691 deleted
6692 col first column in "lnum" that was affected by
6693 the change; one if unknown or the whole line
6694 was affected; this is a byte index, first
6695 character has a value of one.
Bram Moolenaar3c053a12022-10-16 13:11:12 +01006696 When lines are inserted (not when a line is split, e.g. by
6697 typing CR in Insert mode) the values are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006698 lnum line above which the new line is added
6699 end equal to "lnum"
6700 added number of lines inserted
6701 col 1
6702 When lines are deleted the values are:
6703 lnum the first deleted line
6704 end the line below the first deleted line, before
6705 the deletion was done
6706 added negative, number of lines deleted
6707 col 1
6708 When lines are changed:
6709 lnum the first changed line
6710 end the line below the last changed line
6711 added 0
6712 col first column with a change or 1
6713
6714 The entries are in the order the changes were made, thus the
6715 most recent change is at the end. The line numbers are valid
6716 when the callback is invoked, but later changes may make them
6717 invalid, thus keeping a copy for later might not work.
6718
6719 The {callback} is invoked just before the screen is updated,
6720 when |listener_flush()| is called or when a change is being
6721 made that changes the line count in a way it causes a line
6722 number in the list of changes to become invalid.
6723
6724 The {callback} is invoked with the text locked, see
6725 |textlock|. If you do need to make changes to the buffer, use
6726 a timer to do this later |timer_start()|.
6727
6728 The {callback} is not invoked when the buffer is first loaded.
6729 Use the |BufReadPost| autocmd event to handle the initial text
6730 of a buffer.
6731 The {callback} is also not invoked when the buffer is
6732 unloaded, use the |BufUnload| autocmd event for that.
6733
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006734 Returns zero if {callback} or {buf} is invalid.
6735
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006736 Can also be used as a |method|, the base is passed as the
6737 second argument: >
6738 GetBuffer()->listener_add(callback)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006739<
6740 Return type: |Number|
6741
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006742
6743listener_flush([{buf}]) *listener_flush()*
6744 Invoke listener callbacks for buffer {buf}. If there are no
6745 pending changes then no callbacks are invoked.
6746
6747 {buf} refers to a buffer name or number. For the accepted
6748 values, see |bufname()|. When {buf} is omitted the current
6749 buffer is used.
6750
6751 Can also be used as a |method|: >
6752 GetBuffer()->listener_flush()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006753<
6754 Return type: |Number|
6755
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006756
6757listener_remove({id}) *listener_remove()*
6758 Remove a listener previously added with listener_add().
6759 Returns FALSE when {id} could not be found, TRUE when {id} was
6760 removed.
6761
6762 Can also be used as a |method|: >
6763 GetListenerId()->listener_remove()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006764<
6765 Return type: |Number|
6766
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006767
6768localtime() *localtime()*
6769 Return the current time, measured as seconds since 1st Jan
6770 1970. See also |strftime()|, |strptime()| and |getftime()|.
6771
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006772 Return type: |Number|
6773
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006774
6775log({expr}) *log()*
6776 Return the natural logarithm (base e) of {expr} as a |Float|.
6777 {expr} must evaluate to a |Float| or a |Number| in the range
6778 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006779 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006780 Examples: >
6781 :echo log(10)
6782< 2.302585 >
6783 :echo log(exp(5))
6784< 5.0
6785
6786 Can also be used as a |method|: >
6787 Compute()->log()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006788<
6789 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006790
6791
6792log10({expr}) *log10()*
6793 Return the logarithm of Float {expr} to base 10 as a |Float|.
6794 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006795 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006796 Examples: >
6797 :echo log10(1000)
6798< 3.0 >
6799 :echo log10(0.01)
6800< -2.0
6801
6802 Can also be used as a |method|: >
6803 Compute()->log10()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006804<
6805 Return type: |Float|
6806
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006807
6808luaeval({expr} [, {expr}]) *luaeval()*
6809 Evaluate Lua expression {expr} and return its result converted
6810 to Vim data structures. Second {expr} may hold additional
6811 argument accessible as _A inside first {expr}.
6812 Strings are returned as they are.
6813 Boolean objects are converted to numbers.
Bram Moolenaar73e28dc2022-09-17 21:08:33 +01006814 Numbers are converted to |Float| values.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006815 Dictionaries and lists obtained by vim.eval() are returned
6816 as-is.
6817 Other objects are returned as zero without any errors.
6818 See |lua-luaeval| for more details.
6819 Note that in a `:def` function local variables are not visible
6820 to {expr}.
6821
6822 Can also be used as a |method|: >
6823 GetExpr()->luaeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006824<
6825 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006826
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006827 {only available when compiled with the |+lua| feature}
6828
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006829
6830map({expr1}, {expr2}) *map()*
6831 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00006832 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006833 item in {expr1} with the result of evaluating {expr2}.
6834 For a |Blob| each byte is replaced.
6835 For a |String|, each character, including composing
6836 characters, is replaced.
6837 If the item type changes you may want to use |mapnew()| to
6838 create a new List or Dictionary. This is required when using
6839 Vim9 script.
6840
6841 {expr2} must be a |String| or |Funcref|.
6842
6843 If {expr2} is a |String|, inside {expr2} |v:val| has the value
6844 of the current item. For a |Dictionary| |v:key| has the key
6845 of the current item and for a |List| |v:key| has the index of
6846 the current item. For a |Blob| |v:key| has the index of the
6847 current byte. For a |String| |v:key| has the index of the
6848 current character.
6849 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006850 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006851< This puts "> " before and " <" after each item in "mylist".
6852
6853 Note that {expr2} is the result of an expression and is then
6854 used as an expression again. Often it is good to use a
6855 |literal-string| to avoid having to double backslashes. You
6856 still have to double ' quotes
6857
6858 If {expr2} is a |Funcref| it is called with two arguments:
6859 1. The key or the index of the current item.
6860 2. the value of the current item.
Bram Moolenaarb59ae592022-11-23 23:46:31 +00006861 With a legacy script lambda you don't get an error if it only
6862 accepts one argument, but with a Vim9 lambda you get "E1106:
6863 One argument too many", the number of arguments must match.
6864
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006865 The function must return the new value of the item. Example
6866 that changes each value by "key-value": >
6867 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006868 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006869 endfunc
6870 call map(myDict, function('KeyValue'))
6871< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006872 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006873< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006874 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006875< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006876 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006877<
6878 The operation is done in-place for a |List| and |Dictionary|.
6879 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006880 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006881
6882< Returns {expr1}, the |List| or |Dictionary| that was filtered,
6883 or a new |Blob| or |String|.
6884 When an error is encountered while evaluating {expr2} no
6885 further items in {expr1} are processed.
6886 When {expr2} is a Funcref errors inside a function are ignored,
6887 unless it was defined with the "abort" flag.
6888
6889 Can also be used as a |method|: >
6890 mylist->map(expr2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006891<
6892 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
6893 depending on {expr1}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006894
6895
6896maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
6897 When {dict} is omitted or zero: Return the rhs of mapping
6898 {name} in mode {mode}. The returned String has special
6899 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01006900 listing. When {dict} is TRUE a dictionary is returned, see
6901 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006902
6903 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006904 returned if {dict} is FALSE, otherwise returns an empty Dict.
6905 When the mapping for {name} is empty, then "<Nop>" is
6906 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006907
6908 The {name} can have special key names, like in the ":map"
6909 command.
6910
6911 {mode} can be one of these strings:
6912 "n" Normal
6913 "v" Visual (including Select)
6914 "o" Operator-pending
6915 "i" Insert
6916 "c" Cmd-line
6917 "s" Select
6918 "x" Visual
6919 "l" langmap |language-mapping|
6920 "t" Terminal-Job
6921 "" Normal, Visual and Operator-pending
6922 When {mode} is omitted, the modes for "" are used.
6923
6924 When {abbr} is there and it is |TRUE| use abbreviations
6925 instead of mappings.
6926
6927 When {dict} is there and it is |TRUE| return a dictionary
6928 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01006929 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006930 "lhs" The {lhs} of the mapping as it would be typed
6931 "lhsraw" The {lhs} of the mapping as raw bytes
6932 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
6933 form, only present when it differs from "lhsraw"
6934 "rhs" The {rhs} of the mapping as typed.
6935 "silent" 1 for a |:map-silent| mapping, else 0.
6936 "noremap" 1 if the {rhs} of the mapping is not remappable.
6937 "script" 1 if mapping was defined with <script>.
6938 "expr" 1 for an expression mapping (|:map-<expr>|).
6939 "buffer" 1 for a buffer local mapping (|:map-local|).
6940 "mode" Modes for which the mapping is defined. In
6941 addition to the modes mentioned above, these
6942 characters will be used:
6943 " " Normal, Visual and Operator-pending
6944 "!" Insert and Commandline mode
6945 (|mapmode-ic|)
6946 "sid" The script local ID, used for <sid> mappings
Bram Moolenaar71badf92023-04-22 22:40:14 +01006947 (|<SID>|). Negative for special contexts.
Bram Moolenaara9528b32022-01-18 20:51:35 +00006948 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01006949 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006950 "lnum" The line number in "sid", zero if unknown.
6951 "nowait" Do not wait for other, longer mappings.
6952 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01006953 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01006954 "mode_bits" Vim's internal binary representation of "mode".
6955 |mapset()| ignores this; only "mode" is used.
6956 See |maplist()| for usage examples. The values
6957 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006958
6959 The dictionary can be used to restore a mapping with
6960 |mapset()|.
6961
6962 The mappings local to the current buffer are checked first,
6963 then the global mappings.
6964 This function can be used to map a key even when it's already
6965 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006966 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006967
6968< Can also be used as a |method|: >
6969 GetKey()->maparg('n')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006970<
6971 Return type: |String| or dict<any> depending on {dict}
6972
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006973
6974mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
6975 Check if there is a mapping that matches with {name} in mode
6976 {mode}. See |maparg()| for {mode} and special names in
6977 {name}.
6978 When {abbr} is there and it is |TRUE| use abbreviations
6979 instead of mappings.
6980 A match happens with a mapping that starts with {name} and
6981 with a mapping which is equal to the start of {name}.
6982
6983 matches mapping "a" "ab" "abc" ~
6984 mapcheck("a") yes yes yes
6985 mapcheck("abc") yes yes yes
6986 mapcheck("ax") yes no no
6987 mapcheck("b") no no no
6988
6989 The difference with maparg() is that mapcheck() finds a
6990 mapping that matches with {name}, while maparg() only finds a
6991 mapping for {name} exactly.
6992 When there is no mapping that starts with {name}, an empty
6993 String is returned. If there is one, the RHS of that mapping
6994 is returned. If there are several mappings that start with
6995 {name}, the RHS of one of them is returned. This will be
6996 "<Nop>" if the RHS is empty.
6997 The mappings local to the current buffer are checked first,
6998 then the global mappings.
6999 This function can be used to check if a mapping can be added
7000 without being ambiguous. Example: >
7001 :if mapcheck("_vv") == ""
7002 : map _vv :set guifont=7x13<CR>
7003 :endif
7004< This avoids adding the "_vv" mapping when there already is a
7005 mapping for "_v" or for "_vvv".
7006
7007 Can also be used as a |method|: >
7008 GetKey()->mapcheck('n')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007009<
7010 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007011
7012
Ernie Rael09661202022-04-25 14:40:44 +01007013maplist([{abbr}]) *maplist()*
7014 Returns a |List| of all mappings. Each List item is a |Dict|,
7015 the same as what is returned by |maparg()|, see
7016 |mapping-dict|. When {abbr} is there and it is |TRUE| use
7017 abbreviations instead of mappings.
7018
7019 Example to show all mappings with 'MultiMatch' in rhs: >
7020 vim9script
7021 echo maplist()->filter(
7022 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01007023< It can be tricky to find mappings for particular |:map-modes|.
7024 |mapping-dict|'s "mode_bits" can simplify this. For example,
7025 the mode_bits for Normal, Insert or Command-line modes are
7026 0x19. To find all the mappings available in those modes you
7027 can do: >
7028 vim9script
7029 var saved_maps = []
7030 for m in maplist()
7031 if and(m.mode_bits, 0x19) != 0
7032 saved_maps->add(m)
7033 endif
7034 endfor
7035 echo saved_maps->mapnew((_, m) => m.lhs)
7036< The values of the mode_bits are defined in Vim's src/vim.h
7037 file and they can be discovered at runtime using
7038 |:map-commands| and "maplist()". Example: >
7039 vim9script
7040 omap xyzzy <Nop>
7041 var op_bit = maplist()->filter(
7042 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
7043 ounmap xyzzy
7044 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007045<
7046 Return type: list<dict<any>>
Ernie Rael09661202022-04-25 14:40:44 +01007047
7048
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007049mapnew({expr1}, {expr2}) *mapnew()*
7050 Like |map()| but instead of replacing items in {expr1} a new
7051 List or Dictionary is created and returned. {expr1} remains
7052 unchanged. Items can still be changed by {expr2}, if you
7053 don't want that use |deepcopy()| first.
7054
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007055 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
7056 depending on {expr1}
7057
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007058
7059mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01007060mapset({dict})
7061 Restore a mapping from a dictionary, possibly returned by
7062 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
7063 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01007064 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01007065 feature allows copying mappings from one buffer to another.
7066 The dict.mode value may restore a single mapping that covers
7067 more than one mode, like with mode values of '!', ' ', 'nox',
7068 or 'v'. *E1276*
7069
7070 In the first form, {mode} and {abbr} should be the same as
7071 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007072 {mode} is used to define the mode in which the mapping is set,
7073 not the "mode" entry in {dict}.
7074 Example for saving and restoring a mapping: >
7075 let save_map = maparg('K', 'n', 0, 1)
7076 nnoremap K somethingelse
7077 ...
7078 call mapset('n', 0, save_map)
7079< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01007080 e.g. with `:map!`, you need to save/restore the mapping for
7081 all of them, when they might differ.
7082
7083 In the second form, with {dict} as the only argument, mode
7084 and abbr are taken from the dict.
7085 Example: >
7086 vim9script
7087 var save_maps = maplist()->filter(
7088 (_, m) => m.lhs == 'K')
7089 nnoremap K somethingelse
7090 cnoremap K somethingelse2
7091 # ...
7092 unmap K
7093 for d in save_maps
7094 mapset(d)
7095 endfor
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007096<
7097 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007098
7099
7100match({expr}, {pat} [, {start} [, {count}]]) *match()*
7101 When {expr} is a |List| then this returns the index of the
7102 first item where {pat} matches. Each item is used as a
7103 String, |Lists| and |Dictionaries| are used as echoed.
7104
7105 Otherwise, {expr} is used as a String. The result is a
7106 Number, which gives the index (byte offset) in {expr} where
7107 {pat} matches.
7108
7109 A match at the first character or |List| item returns zero.
7110 If there is no match -1 is returned.
7111
7112 For getting submatches see |matchlist()|.
7113 Example: >
7114 :echo match("testing", "ing") " results in 4
7115 :echo match([1, 'x'], '\a') " results in 1
7116< See |string-match| for how {pat} is used.
7117 *strpbrk()*
7118 Vim doesn't have a strpbrk() function. But you can do: >
7119 :let sepidx = match(line, '[.,;: \t]')
7120< *strcasestr()*
7121 Vim doesn't have a strcasestr() function. But you can add
7122 "\c" to the pattern to ignore case: >
7123 :let idx = match(haystack, '\cneedle')
7124<
7125 If {start} is given, the search starts from byte index
7126 {start} in a String or item {start} in a |List|.
7127 The result, however, is still the index counted from the
7128 first character/item. Example: >
7129 :echo match("testing", "ing", 2)
7130< result is again "4". >
7131 :echo match("testing", "ing", 4)
7132< result is again "4". >
7133 :echo match("testing", "t", 2)
7134< result is "3".
7135 For a String, if {start} > 0 then it is like the string starts
7136 {start} bytes later, thus "^" will match at {start}. Except
7137 when {count} is given, then it's like matches before the
7138 {start} byte are ignored (this is a bit complicated to keep it
7139 backwards compatible).
7140 For a String, if {start} < 0, it will be set to 0. For a list
7141 the index is counted from the end.
7142 If {start} is out of range ({start} > strlen({expr}) for a
7143 String or {start} > len({expr}) for a |List|) -1 is returned.
7144
7145 When {count} is given use the {count}'th match. When a match
7146 is found in a String the search for the next one starts one
7147 character further. Thus this example results in 1: >
7148 echo match("testing", "..", 0, 2)
7149< In a |List| the search continues in the next item.
7150 Note that when {count} is added the way {start} works changes,
7151 see above.
7152
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007153 *match-pattern*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007154 See |pattern| for the patterns that are accepted.
7155 The 'ignorecase' option is used to set the ignore-caseness of
7156 the pattern. 'smartcase' is NOT used. The matching is always
7157 done like 'magic' is set and 'cpoptions' is empty.
7158 Note that a match at the start is preferred, thus when the
7159 pattern is using "*" (any number of matches) it tends to find
7160 zero matches at the start instead of a number of matches
7161 further down in the text.
7162
7163 Can also be used as a |method|: >
7164 GetText()->match('word')
7165 GetList()->match('word')
7166<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007167 Return type: |Number|
7168
7169
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00007170 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007171matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
7172 Defines a pattern to be highlighted in the current window (a
7173 "match"). It will be highlighted with {group}. Returns an
7174 identification number (ID), which can be used to delete the
7175 match using |matchdelete()|. The ID is bound to the window.
7176 Matching is case sensitive and magic, unless case sensitivity
7177 or magicness are explicitly overridden in {pattern}. The
7178 'magic', 'smartcase' and 'ignorecase' options are not used.
7179 The "Conceal" value is special, it causes the match to be
7180 concealed.
7181
7182 The optional {priority} argument assigns a priority to the
7183 match. A match with a high priority will have its
7184 highlighting overrule that of a match with a lower priority.
7185 A priority is specified as an integer (negative numbers are no
7186 exception). If the {priority} argument is not specified, the
7187 default priority is 10. The priority of 'hlsearch' is zero,
7188 hence all matches with a priority greater than zero will
7189 overrule it. Syntax highlighting (see 'syntax') is a separate
7190 mechanism, and regardless of the chosen priority a match will
7191 always overrule syntax highlighting.
7192
7193 The optional {id} argument allows the request for a specific
7194 match ID. If a specified ID is already taken, an error
7195 message will appear and the match will not be added. An ID
7196 is specified as a positive integer (zero excluded). IDs 1, 2
7197 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01007198 respectively. 3 is reserved for use by the |matchparen|
7199 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01007200 If the {id} argument is not specified or -1, |matchadd()|
Bram Moolenaar9f573a82022-09-29 13:50:08 +01007201 automatically chooses a free ID, which is at least 1000.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007202
7203 The optional {dict} argument allows for further custom
7204 values. Currently this is used to specify a match specific
7205 conceal character that will be shown for |hl-Conceal|
7206 highlighted matches. The dict can have the following members:
7207
7208 conceal Special character to show instead of the
7209 match (only for |hl-Conceal| highlighted
7210 matches, see |:syn-cchar|)
7211 window Instead of the current window use the
7212 window with this number or window ID.
7213
7214 The number of matches is not limited, as it is the case with
7215 the |:match| commands.
7216
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007217 Returns -1 on error.
7218
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007219 Example: >
7220 :highlight MyGroup ctermbg=green guibg=green
7221 :let m = matchadd("MyGroup", "TODO")
7222< Deletion of the pattern: >
7223 :call matchdelete(m)
7224
7225< A list of matches defined by |matchadd()| and |:match| are
7226 available from |getmatches()|. All matches can be deleted in
7227 one operation by |clearmatches()|.
7228
7229 Can also be used as a |method|: >
7230 GetGroup()->matchadd('TODO')
7231<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007232 Return type: |Number|
7233
7234
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007235 *matchaddpos()*
7236matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
7237 Same as |matchadd()|, but requires a list of positions {pos}
7238 instead of a pattern. This command is faster than |matchadd()|
Shane Harperc1b39842024-07-17 19:40:40 +02007239 because it does not handle regular expressions and it sets
7240 buffer line boundaries to redraw screen. It is supposed to be
7241 used when fast match additions and deletions are required, for
7242 example to highlight matching parentheses.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007243
7244 {pos} is a list of positions. Each position can be one of
7245 these:
7246 - A number. This whole line will be highlighted. The first
7247 line has number 1.
7248 - A list with one number, e.g., [23]. The whole line with this
7249 number will be highlighted.
7250 - A list with two numbers, e.g., [23, 11]. The first number is
7251 the line number, the second one is the column number (first
7252 column is 1, the value must correspond to the byte index as
7253 |col()| would return). The character at this position will
7254 be highlighted.
7255 - A list with three numbers, e.g., [23, 11, 3]. As above, but
7256 the third number gives the length of the highlight in bytes.
7257
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007258 Returns -1 on error.
7259
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007260 Example: >
7261 :highlight MyGroup ctermbg=green guibg=green
7262 :let m = matchaddpos("MyGroup", [[23, 24], 34])
7263< Deletion of the pattern: >
7264 :call matchdelete(m)
7265
7266< Matches added by |matchaddpos()| are returned by
7267 |getmatches()|.
7268
7269 Can also be used as a |method|: >
7270 GetGroup()->matchaddpos([23, 11])
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007271<
7272 Return type: |Number|
7273
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007274
7275matcharg({nr}) *matcharg()*
7276 Selects the {nr} match item, as set with a |:match|,
7277 |:2match| or |:3match| command.
7278 Return a |List| with two elements:
7279 The name of the highlight group used
7280 The pattern used.
7281 When {nr} is not 1, 2 or 3 returns an empty |List|.
7282 When there is no match item set returns ['', ''].
7283 This is useful to save and restore a |:match|.
7284 Highlighting matches using the |:match| commands are limited
7285 to three matches. |matchadd()| does not have this limitation.
7286
7287 Can also be used as a |method|: >
7288 GetMatch()->matcharg()
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007289<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007290 Return type: list<string>
7291
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007292 *matchbufline()*
7293matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])
7294 Returns the |List| of matches in lines from {lnum} to {end} in
7295 buffer {buf} where {pat} matches.
7296
7297 {lnum} and {end} can either be a line number or the string "$"
7298 to refer to the last line in {buf}.
7299
7300 The {dict} argument supports following items:
7301 submatches include submatch information (|/\(|)
7302
7303 For each match, a |Dict| with the following items is returned:
7304 byteidx starting byte index of the match
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007305 lnum line number where there is a match
7306 text matched string
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007307 Note that there can be multiple matches in a single line.
7308
7309 This function works only for loaded buffers. First call
7310 |bufload()| if needed.
7311
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007312 See |match-pattern| for information about the effect of some
7313 option settings on the pattern.
7314
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007315 When {buf} is not a valid buffer, the buffer is not loaded or
7316 {lnum} or {end} is not valid then an error is given and an
7317 empty |List| is returned.
7318
7319 Examples: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007320 " Assuming line 3 in buffer 5 contains "a"
7321 :echo matchbufline(5, '\<\k\+\>', 3, 3)
7322 [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
7323 " Assuming line 4 in buffer 10 contains "tik tok"
7324 :echo matchbufline(10, '\<\k\+\>', 1, 4)
7325 [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007326<
7327 If {submatch} is present and is v:true, then submatches like
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007328 "\1", "\2", etc. are also returned. Example: >
7329 " Assuming line 2 in buffer 2 contains "acd"
7330 :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007331 \ {'submatches': v:true})
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007332 [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007333< The "submatches" List always contains 9 items. If a submatch
7334 is not found, then an empty string is returned for that
7335 submatch.
7336
7337 Can also be used as a |method|: >
7338 GetBuffer()->matchbufline('mypat', 1, '$')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007339<
7340 Return type: list<dict<any>> or list<any>
7341
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007342
h-east624bb832024-11-09 18:37:32 +01007343matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007344 Deletes a match with ID {id} previously defined by |matchadd()|
7345 or one of the |:match| commands. Returns 0 if successful,
7346 otherwise -1. See example for |matchadd()|. All matches can
7347 be deleted in one operation by |clearmatches()|.
7348 If {win} is specified, use the window with this number or
7349 window ID instead of the current window.
7350
7351 Can also be used as a |method|: >
7352 GetMatch()->matchdelete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007353<
7354 Return type: |Number|
7355
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007356
7357matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
7358 Same as |match()|, but return the index of first character
7359 after the match. Example: >
7360 :echo matchend("testing", "ing")
7361< results in "7".
7362 *strspn()* *strcspn()*
7363 Vim doesn't have a strspn() or strcspn() function, but you can
7364 do it with matchend(): >
7365 :let span = matchend(line, '[a-zA-Z]')
7366 :let span = matchend(line, '[^a-zA-Z]')
7367< Except that -1 is returned when there are no matches.
7368
7369 The {start}, if given, has the same meaning as for |match()|. >
7370 :echo matchend("testing", "ing", 2)
7371< results in "7". >
7372 :echo matchend("testing", "ing", 5)
7373< result is "-1".
7374 When {expr} is a |List| the result is equal to |match()|.
7375
7376 Can also be used as a |method|: >
7377 GetText()->matchend('word')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007378<
7379 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007380
7381
7382matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
7383 If {list} is a list of strings, then returns a |List| with all
7384 the strings in {list} that fuzzy match {str}. The strings in
7385 the returned list are sorted based on the matching score.
7386
7387 The optional {dict} argument always supports the following
7388 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01007389 matchseq When this item is present return only matches
7390 that contain the characters in {str} in the
7391 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01007392 limit Maximum number of matches in {list} to be
7393 returned. Zero means no limit.
glepnir28e40a72025-03-16 21:24:22 +01007394 camelcase Use enhanced camel case scoring making results
7395 better suited for completion related to
zeertzjqc4815c12025-03-18 20:28:00 +01007396 programming languages. Defaults to v:true.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007397
7398 If {list} is a list of dictionaries, then the optional {dict}
7399 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01007400 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007401 {str}. The value of this item should be a
7402 string.
7403 text_cb |Funcref| that will be called for every item
7404 in {list} to get the text for fuzzy matching.
7405 This should accept a dictionary item as the
7406 argument and return the text for that item to
7407 use for fuzzy matching.
7408
7409 {str} is treated as a literal string and regular expression
7410 matching is NOT supported. The maximum supported {str} length
7411 is 256.
7412
7413 When {str} has multiple words each separated by white space,
7414 then the list of strings that have all the words is returned.
7415
7416 If there are no matching strings or there is an error, then an
7417 empty list is returned. If length of {str} is greater than
7418 256, then returns an empty list.
7419
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01007420 When {limit} is given, matchfuzzy() will find up to this
7421 number of matches in {list} and return them in sorted order.
7422
Bram Moolenaar1588bc82022-03-08 21:35:07 +00007423 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007424 matching strings.
7425
7426 Example: >
7427 :echo matchfuzzy(["clay", "crow"], "cay")
7428< results in ["clay"]. >
7429 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
7430< results in a list of buffer names fuzzy matching "ndl". >
7431 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
7432< results in a list of buffer information dicts with buffer
7433 names fuzzy matching "ndl". >
7434 :echo getbufinfo()->matchfuzzy("spl",
7435 \ {'text_cb' : {v -> v.name}})
7436< results in a list of buffer information dicts with buffer
7437 names fuzzy matching "spl". >
7438 :echo v:oldfiles->matchfuzzy("test")
7439< results in a list of file names fuzzy matching "test". >
7440 :let l = readfile("buffer.c")->matchfuzzy("str")
7441< results in a list of lines in "buffer.c" fuzzy matching "str". >
7442 :echo ['one two', 'two one']->matchfuzzy('two one')
7443< results in ['two one', 'one two']. >
7444 :echo ['one two', 'two one']->matchfuzzy('two one',
7445 \ {'matchseq': 1})
7446< results in ['two one'].
7447
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007448 Return type: list<string> or list<any>
7449
7450
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007451matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
7452 Same as |matchfuzzy()|, but returns the list of matched
7453 strings, the list of character positions where characters
7454 in {str} matches and a list of matching scores. You can
7455 use |byteidx()| to convert a character position to a byte
7456 position.
7457
7458 If {str} matches multiple times in a string, then only the
7459 positions for the best match is returned.
7460
7461 If there are no matching strings or there is an error, then a
7462 list with three empty list items is returned.
7463
7464 Example: >
7465 :echo matchfuzzypos(['testing'], 'tsg')
7466< results in [['testing'], [[0, 2, 6]], [99]] >
7467 :echo matchfuzzypos(['clay', 'lacy'], 'la')
7468< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
7469 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
7470< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
7471
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007472 Return type: list<list<any>>
7473
7474
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007475matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
7476 Same as |match()|, but return a |List|. The first item in the
7477 list is the matched string, same as what matchstr() would
7478 return. Following items are submatches, like "\1", "\2", etc.
7479 in |:substitute|. When an optional submatch didn't match an
7480 empty string is used. Example: >
7481 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
7482< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
7483 When there is no match an empty list is returned.
7484
7485 You can pass in a List, but that is not very useful.
7486
7487 Can also be used as a |method|: >
7488 GetText()->matchlist('word')
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007489<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007490 Return type: list<string> or list<any>
7491
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007492 *matchstrlist()*
7493matchstrlist({list}, {pat} [, {dict}])
7494 Returns the |List| of matches in {list} where {pat} matches.
7495 {list} is a |List| of strings. {pat} is matched against each
7496 string in {list}.
7497
7498 The {dict} argument supports following items:
7499 submatches include submatch information (|/\(|)
7500
7501 For each match, a |Dict| with the following items is returned:
7502 byteidx starting byte index of the match.
7503 idx index in {list} of the match.
7504 text matched string
7505 submatches a List of submatches. Present only if
7506 "submatches" is set to v:true in {dict}.
7507
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007508 See |match-pattern| for information about the effect of some
7509 option settings on the pattern.
7510
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007511 Example: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007512 :echo matchstrlist(['tik tok'], '\<\k\+\>')
7513 [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
7514 :echo matchstrlist(['a', 'b'], '\<\k\+\>')
7515 [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007516<
7517 If "submatches" is present and is v:true, then submatches like
7518 "\1", "\2", etc. are also returned. Example: >
7519 :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
7520 \ #{submatches: v:true})
7521 [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
7522< The "submatches" List always contains 9 items. If a submatch
7523 is not found, then an empty string is returned for that
7524 submatch.
7525
7526 Can also be used as a |method|: >
7527 GetListOfStrings()->matchstrlist('mypat')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007528<
7529 Return type: list<dict<any>> or list<any>
7530
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007531
7532matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
7533 Same as |match()|, but return the matched string. Example: >
7534 :echo matchstr("testing", "ing")
7535< results in "ing".
7536 When there is no match "" is returned.
7537 The {start}, if given, has the same meaning as for |match()|. >
7538 :echo matchstr("testing", "ing", 2)
7539< results in "ing". >
7540 :echo matchstr("testing", "ing", 5)
7541< result is "".
7542 When {expr} is a |List| then the matching item is returned.
7543 The type isn't changed, it's not necessarily a String.
7544
7545 Can also be used as a |method|: >
7546 GetText()->matchstr('word')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007547<
7548 Return type: |String|
7549
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007550
7551matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
7552 Same as |matchstr()|, but return the matched string, the start
7553 position and the end position of the match. Example: >
7554 :echo matchstrpos("testing", "ing")
7555< results in ["ing", 4, 7].
7556 When there is no match ["", -1, -1] is returned.
7557 The {start}, if given, has the same meaning as for |match()|. >
7558 :echo matchstrpos("testing", "ing", 2)
7559< results in ["ing", 4, 7]. >
7560 :echo matchstrpos("testing", "ing", 5)
7561< result is ["", -1, -1].
7562 When {expr} is a |List| then the matching item, the index
7563 of first item where {pat} matches, the start position and the
7564 end position of the match are returned. >
7565 :echo matchstrpos([1, '__x'], '\a')
7566< result is ["x", 1, 2, 3].
7567 The type isn't changed, it's not necessarily a String.
7568
7569 Can also be used as a |method|: >
7570 GetText()->matchstrpos('word')
7571<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007572 Return type: list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007573
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007574
7575max({expr}) *max()*
7576 Return the maximum value of all items in {expr}. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007577 echo max([apples, pears, oranges])
7578
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01007579< {expr} can be a |List|, a |Tuple| or a |Dictionary|. For a
7580 Dictionary, it returns the maximum of all values in the
7581 Dictionary. If {expr} is neither a List nor a Tuple nor a
7582 Dictionary, or one of the items in {expr} cannot be used as a
7583 Number this results in an error. An empty |List|, |Tuple|
7584 or |Dictionary| results in zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007585
7586 Can also be used as a |method|: >
7587 mylist->max()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007588<
7589 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007590
7591
7592menu_info({name} [, {mode}]) *menu_info()*
7593 Return information about the specified menu {name} in
7594 mode {mode}. The menu name should be specified without the
7595 shortcut character ('&'). If {name} is "", then the top-level
7596 menu names are returned.
7597
7598 {mode} can be one of these strings:
7599 "n" Normal
7600 "v" Visual (including Select)
7601 "o" Operator-pending
7602 "i" Insert
7603 "c" Cmd-line
7604 "s" Select
7605 "x" Visual
7606 "t" Terminal-Job
7607 "" Normal, Visual and Operator-pending
7608 "!" Insert and Cmd-line
7609 When {mode} is omitted, the modes for "" are used.
7610
7611 Returns a |Dictionary| containing the following items:
7612 accel menu item accelerator text |menu-text|
7613 display display name (name without '&')
7614 enabled v:true if this menu item is enabled
7615 Refer to |:menu-enable|
7616 icon name of the icon file (for toolbar)
7617 |toolbar-icon|
7618 iconidx index of a built-in icon
7619 modes modes for which the menu is defined. In
7620 addition to the modes mentioned above, these
7621 characters will be used:
7622 " " Normal, Visual and Operator-pending
7623 name menu item name.
7624 noremenu v:true if the {rhs} of the menu item is not
7625 remappable else v:false.
7626 priority menu order priority |menu-priority|
7627 rhs right-hand-side of the menu item. The returned
7628 string has special characters translated like
7629 in the output of the ":menu" command listing.
7630 When the {rhs} of a menu item is empty, then
7631 "<Nop>" is returned.
7632 script v:true if script-local remapping of {rhs} is
7633 allowed else v:false. See |:menu-script|.
7634 shortcut shortcut key (character after '&' in
7635 the menu name) |menu-shortcut|
7636 silent v:true if the menu item is created
7637 with <silent> argument |:menu-silent|
7638 submenus |List| containing the names of
7639 all the submenus. Present only if the menu
7640 item has submenus.
7641
7642 Returns an empty dictionary if the menu item is not found.
7643
7644 Examples: >
7645 :echo menu_info('Edit.Cut')
7646 :echo menu_info('File.Save', 'n')
7647
7648 " Display the entire menu hierarchy in a buffer
7649 func ShowMenu(name, pfx)
7650 let m = menu_info(a:name)
7651 call append(line('$'), a:pfx .. m.display)
7652 for child in m->get('submenus', [])
7653 call ShowMenu(a:name .. '.' .. escape(child, '.'),
7654 \ a:pfx .. ' ')
7655 endfor
7656 endfunc
7657 new
7658 for topmenu in menu_info('').submenus
7659 call ShowMenu(topmenu, '')
7660 endfor
7661<
7662 Can also be used as a |method|: >
7663 GetMenuName()->menu_info('v')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007664<
7665 Return type: dict<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007666
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007667min({expr}) *min()*
7668 Return the minimum value of all items in {expr}. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007669 echo min([apples, pears, oranges])
7670
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01007671< {expr} can be a |List|, a |Tuple| or a |Dictionary|. For a
7672 Dictionary, it returns the minimum of all values in the
7673 Dictionary. If {expr} is neither a List nor a Tuple nor a
7674 Dictionary, or one of the items in {expr} cannot be used as a
7675 Number this results in an error. An empty |List|, |Tuple| or
7676 |Dictionary| results in zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007677
7678 Can also be used as a |method|: >
7679 mylist->min()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007680<
7681 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007682
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007683
7684mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E739*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007685 Create directory {name}.
7686
Bram Moolenaar938ae282023-02-20 20:44:55 +00007687 When {flags} is present it must be a string. An empty string
7688 has no effect.
Bram Moolenaar6f14da12022-09-07 21:30:44 +01007689
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007690 {flags} can contain these character flags:
7691 "p" intermediate directories will be created as necessary
7692 "D" {name} will be deleted at the end of the current
Christian Brabandtc509c002024-06-14 20:22:05 +02007693 function, but not recursively |:defer|
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007694 "R" {name} will be deleted recursively at the end of the
Christian Brabandtc509c002024-06-14 20:22:05 +02007695 current function |:defer|
Bram Moolenaar938ae282023-02-20 20:44:55 +00007696
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007697 Note that when {name} has more than one part and "p" is used
Bram Moolenaar6f14da12022-09-07 21:30:44 +01007698 some directories may already exist. Only the first one that
7699 is created and what it contains is scheduled to be deleted.
7700 E.g. when using: >
7701 call mkdir('subdir/tmp/autoload', 'pR')
7702< and "subdir" already exists then "subdir/tmp" will be
7703 scheduled for deletion, like with: >
7704 defer delete('subdir/tmp', 'rf')
7705< Note that if scheduling the defer fails the directory is not
7706 deleted. This should only happen when out of memory.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007707
7708 If {prot} is given it is used to set the protection bits of
7709 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
7710 the user, readable for others). Use 0o700 to make it
Christian Brabandt0a336cc2025-03-11 21:14:31 +01007711 unreadable for others. This is used for the newly created
zeertzjqc1c3b5d2025-03-12 21:16:13 +01007712 directories. Note: umask is applied to {prot} (on Unix).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007713 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007714 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007715
7716< This function is not available in the |sandbox|.
7717
7718 There is no error if the directory already exists and the "p"
7719 flag is passed (since patch 8.0.1708). However, without the
7720 "p" option the call will fail.
7721
7722 The function result is a Number, which is TRUE if the call was
7723 successful or FALSE if the directory creation failed or partly
7724 failed.
7725
7726 Not available on all systems. To check use: >
7727 :if exists("*mkdir")
7728
7729< Can also be used as a |method|: >
7730 GetName()->mkdir()
7731<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007732 Return type: |Number|
7733
7734
7735mode([{expr}]) *mode()*
7736 Return a string that indicates the current mode.
Doug Kearns9cd9e752024-04-07 17:42:17 +02007737 If {expr} is supplied and it evaluates to a non-zero Number or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007738 a non-empty String (|non-zero-arg|), then the full mode is
7739 returned, otherwise only the first letter is returned.
7740 Also see |state()|.
7741
7742 n Normal
7743 no Operator-pending
7744 nov Operator-pending (forced characterwise |o_v|)
7745 noV Operator-pending (forced linewise |o_V|)
7746 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
7747 CTRL-V is one character
7748 niI Normal using |i_CTRL-O| in |Insert-mode|
7749 niR Normal using |i_CTRL-O| in |Replace-mode|
7750 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
7751 nt Terminal-Normal (insert goes to Terminal-Job mode)
7752 v Visual by character
7753 vs Visual by character using |v_CTRL-O| in Select mode
7754 V Visual by line
7755 Vs Visual by line using |v_CTRL-O| in Select mode
7756 CTRL-V Visual blockwise
7757 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
7758 s Select by character
7759 S Select by line
7760 CTRL-S Select blockwise
7761 i Insert
7762 ic Insert mode completion |compl-generic|
7763 ix Insert mode |i_CTRL-X| completion
7764 R Replace |R|
7765 Rc Replace mode completion |compl-generic|
7766 Rx Replace mode |i_CTRL-X| completion
7767 Rv Virtual Replace |gR|
7768 Rvc Virtual Replace mode completion |compl-generic|
7769 Rvx Virtual Replace mode |i_CTRL-X| completion
7770 c Command-line editing
h-east71ebf3b2023-09-03 17:12:55 +02007771 ct Command-line editing via Terminal-Job mode
zeertzjqfcaeb3d2023-11-28 20:46:29 +01007772 cr Command-line editing overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007773 cv Vim Ex mode |gQ|
zeertzjqfcaeb3d2023-11-28 20:46:29 +01007774 cvr Vim Ex mode while in overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007775 ce Normal Ex mode |Q|
7776 r Hit-enter prompt
7777 rm The -- more -- prompt
7778 r? A |:confirm| query of some sort
7779 ! Shell or external command is executing
7780 t Terminal-Job mode: keys go to the job
7781
7782 This is useful in the 'statusline' option or when used
7783 with |remote_expr()| In most other places it always returns
7784 "c" or "n".
7785 Note that in the future more modes and more specific modes may
7786 be added. It's better not to compare the whole string but only
7787 the leading character(s).
7788 Also see |visualmode()|.
7789
7790 Can also be used as a |method|: >
7791 DoFull()->mode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007792<
7793 Return type: |String|
7794
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007795
7796mzeval({expr}) *mzeval()*
7797 Evaluate MzScheme expression {expr} and return its result
7798 converted to Vim data structures.
7799 Numbers and strings are returned as they are.
7800 Pairs (including lists and improper lists) and vectors are
7801 returned as Vim |Lists|.
7802 Hash tables are represented as Vim |Dictionary| type with keys
7803 converted to strings.
7804 All other types are converted to string with display function.
7805 Examples: >
7806 :mz (define l (list 1 2 3))
7807 :mz (define h (make-hash)) (hash-set! h "list" l)
7808 :echo mzeval("l")
7809 :echo mzeval("h")
7810<
7811 Note that in a `:def` function local variables are not visible
7812 to {expr}.
7813
7814 Can also be used as a |method|: >
7815 GetExpr()->mzeval()
7816<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007817 Return type: any, depending on {expr}
7818
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007819 {only available when compiled with the |+mzscheme| feature}
7820
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007821
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007822nextnonblank({lnum}) *nextnonblank()*
7823 Return the line number of the first line at or below {lnum}
7824 that is not blank. Example: >
7825 if getline(nextnonblank(1)) =~ "Java"
7826< When {lnum} is invalid or there is no non-blank line at or
7827 below it, zero is returned.
7828 {lnum} is used like with |getline()|.
7829 See also |prevnonblank()|.
7830
7831 Can also be used as a |method|: >
7832 GetLnum()->nextnonblank()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007833<
7834 Return type: |Number|
7835
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007836
Christ van Willegenc0786752025-02-01 15:42:16 +01007837ngettext({single}, {plural}, {number}[, {domain}) *ngettext()*
7838 Return a string that contains the correct value for a
7839 message based on the rules for plural form(s) in
7840 a language. Examples: >
7841 ngettext("File", "Files", 2) # returns "Files"
7842<
7843 Can be used as a |method|: >
7844 1->ngettext("File", "Files") # returns "File"
7845<
7846 See |gettext()| for information on the domain parameter.
7847
7848 Return type: |String|
7849
7850
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007851nr2char({expr} [, {utf8}]) *nr2char()*
7852 Return a string with a single character, which has the number
7853 value {expr}. Examples: >
7854 nr2char(64) returns "@"
7855 nr2char(32) returns " "
7856< When {utf8} is omitted or zero, the current 'encoding' is used.
7857 Example for "utf-8": >
7858 nr2char(300) returns I with bow character
7859< When {utf8} is TRUE, always return UTF-8 characters.
7860 Note that a NUL character in the file is specified with
7861 nr2char(10), because NULs are represented with newline
7862 characters. nr2char(0) is a real NUL and terminates the
7863 string, thus results in an empty string.
7864 To turn a list of character numbers into a string: >
7865 let list = [65, 66, 67]
7866 let str = join(map(list, {_, val -> nr2char(val)}), '')
7867< Result: "ABC"
7868
7869 Can also be used as a |method|: >
7870 GetNumber()->nr2char()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007871<
7872 Return type: |String|
7873
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007874
7875or({expr}, {expr}) *or()*
7876 Bitwise OR on the two arguments. The arguments are converted
7877 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01007878 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007879 Example: >
7880 :let bits = or(bits, 0x80)
7881< Can also be used as a |method|: >
7882 :let bits = bits->or(0x80)
7883
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01007884< Rationale: The reason this is a function and not using the "|"
7885 character like many languages, is that Vi has always used "|"
7886 to separate commands. In many places it would not be clear if
7887 "|" is an operator or a command separator.
7888
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007889 Return type: |Number|
7890
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007891
7892pathshorten({path} [, {len}]) *pathshorten()*
7893 Shorten directory names in the path {path} and return the
7894 result. The tail, the file name, is kept as-is. The other
7895 components in the path are reduced to {len} letters in length.
7896 If {len} is omitted or smaller than 1 then 1 is used (single
7897 letters). Leading '~' and '.' characters are kept. Examples: >
7898 :echo pathshorten('~/.vim/autoload/myfile.vim')
7899< ~/.v/a/myfile.vim ~
7900>
7901 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
7902< ~/.vi/au/myfile.vim ~
7903 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007904 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007905
7906 Can also be used as a |method|: >
7907 GetDirectories()->pathshorten()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007908<
7909 Return type: |String|
7910
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007911
7912perleval({expr}) *perleval()*
7913 Evaluate Perl expression {expr} in scalar context and return
7914 its result converted to Vim data structures. If value can't be
7915 converted, it is returned as a string Perl representation.
7916 Note: If you want an array or hash, {expr} must return a
7917 reference to it.
7918 Example: >
7919 :echo perleval('[1 .. 4]')
7920< [1, 2, 3, 4]
7921
7922 Note that in a `:def` function local variables are not visible
7923 to {expr}.
7924
7925 Can also be used as a |method|: >
7926 GetExpr()->perleval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007927<
7928 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007929
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007930 {only available when compiled with the |+perl| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007931
7932
7933popup_ functions are documented here: |popup-functions|
7934
7935
7936pow({x}, {y}) *pow()*
7937 Return the power of {x} to the exponent {y} as a |Float|.
7938 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007939 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007940 Examples: >
7941 :echo pow(3, 3)
7942< 27.0 >
7943 :echo pow(2, 16)
7944< 65536.0 >
7945 :echo pow(32, 0.20)
7946< 2.0
7947
7948 Can also be used as a |method|: >
7949 Compute()->pow(3)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007950<
7951 Return type: |Number|
7952
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007953
7954prevnonblank({lnum}) *prevnonblank()*
7955 Return the line number of the first line at or above {lnum}
7956 that is not blank. Example: >
7957 let ind = indent(prevnonblank(v:lnum - 1))
7958< When {lnum} is invalid or there is no non-blank line at or
7959 above it, zero is returned.
7960 {lnum} is used like with |getline()|.
7961 Also see |nextnonblank()|.
7962
7963 Can also be used as a |method|: >
7964 GetLnum()->prevnonblank()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007965<
7966 Return type: |Number|
7967
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007968
7969printf({fmt}, {expr1} ...) *printf()*
7970 Return a String with {fmt}, where "%" items are replaced by
7971 the formatted form of their respective arguments. Example: >
7972 printf("%4d: E%d %.30s", lnum, errno, msg)
7973< May result in:
7974 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
7975
7976 When used as a |method| the base is passed as the second
7977 argument: >
7978 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007979<
7980 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007981
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007982 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007983 %s string
7984 %6S string right-aligned in 6 display cells
7985 %6s string right-aligned in 6 bytes
7986 %.9s string truncated to 9 bytes
7987 %c single byte
7988 %d decimal number
7989 %5d decimal number padded with spaces to 5 characters
7990 %x hex number
7991 %04x hex number padded with zeros to at least 4 characters
7992 %X hex number using upper case letters
7993 %o octal number
7994 %08b binary number padded with zeros to at least 8 chars
7995 %f floating point number as 12.23, inf, -inf or nan
7996 %F floating point number as 12.23, INF, -INF or NAN
7997 %e floating point number as 1.23e3, inf, -inf or nan
7998 %E floating point number as 1.23E3, INF, -INF or NAN
7999 %g floating point number, as %f or %e depending on value
8000 %G floating point number, as %F or %E depending on value
8001 %% the % character itself
8002
8003 Conversion specifications start with '%' and end with the
8004 conversion type. All other characters are copied unchanged to
8005 the result.
8006
8007 The "%" starts a conversion specification. The following
8008 arguments appear in sequence:
8009
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008010 % [pos-argument] [flags] [field-width] [.precision] type
8011
8012 pos-argument
8013 At most one positional argument specifier. These
8014 take the form {n$}, where n is >= 1.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008015
8016 flags
8017 Zero or more of the following flags:
8018
8019 # The value should be converted to an "alternate
8020 form". For c, d, and s conversions, this option
8021 has no effect. For o conversions, the precision
8022 of the number is increased to force the first
8023 character of the output string to a zero (except
8024 if a zero value is printed with an explicit
8025 precision of zero).
8026 For b and B conversions, a non-zero result has
8027 the string "0b" (or "0B" for B conversions)
8028 prepended to it.
8029 For x and X conversions, a non-zero result has
8030 the string "0x" (or "0X" for X conversions)
8031 prepended to it.
8032
8033 0 (zero) Zero padding. For all conversions the converted
8034 value is padded on the left with zeros rather
8035 than blanks. If a precision is given with a
8036 numeric conversion (d, b, B, o, x, and X), the 0
8037 flag is ignored.
8038
8039 - A negative field width flag; the converted value
8040 is to be left adjusted on the field boundary.
8041 The converted value is padded on the right with
8042 blanks, rather than on the left with blanks or
8043 zeros. A - overrides a 0 if both are given.
8044
8045 ' ' (space) A blank should be left before a positive
8046 number produced by a signed conversion (d).
8047
8048 + A sign must always be placed before a number
8049 produced by a signed conversion. A + overrides
8050 a space if both are used.
8051
8052 field-width
8053 An optional decimal digit string specifying a minimum
8054 field width. If the converted value has fewer bytes
8055 than the field width, it will be padded with spaces on
8056 the left (or right, if the left-adjustment flag has
8057 been given) to fill out the field width. For the S
8058 conversion the count is in cells.
8059
8060 .precision
8061 An optional precision, in the form of a period '.'
8062 followed by an optional digit string. If the digit
8063 string is omitted, the precision is taken as zero.
8064 This gives the minimum number of digits to appear for
8065 d, o, x, and X conversions, the maximum number of
8066 bytes to be printed from a string for s conversions,
8067 or the maximum number of cells to be printed from a
8068 string for S conversions.
8069 For floating point it is the number of digits after
8070 the decimal point.
8071
8072 type
8073 A character that specifies the type of conversion to
8074 be applied, see below.
8075
8076 A field width or precision, or both, may be indicated by an
8077 asterisk '*' instead of a digit string. In this case, a
8078 Number argument supplies the field width or precision. A
8079 negative field width is treated as a left adjustment flag
8080 followed by a positive field width; a negative precision is
8081 treated as though it were missing. Example: >
8082 :echo printf("%d: %.*s", nr, width, line)
8083< This limits the length of the text used from "line" to
8084 "width" bytes.
8085
Dominique Pellé17dca3c2023-12-14 20:36:32 +01008086 If the argument to be formatted is specified using a
8087 positional argument specifier, and a '*' is used to indicate
8088 that a number argument is to be used to specify the width or
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008089 precision, the argument(s) to be used must also be specified
8090 using a {n$} positional argument specifier. See |printf-$|.
8091
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008092 The conversion specifiers and their meanings are:
8093
8094 *printf-d* *printf-b* *printf-B* *printf-o*
8095 *printf-x* *printf-X*
8096 dbBoxX The Number argument is converted to signed decimal
8097 (d), unsigned binary (b and B), unsigned octal (o), or
8098 unsigned hexadecimal (x and X) notation. The letters
8099 "abcdef" are used for x conversions; the letters
8100 "ABCDEF" are used for X conversions.
8101 The precision, if any, gives the minimum number of
8102 digits that must appear; if the converted value
8103 requires fewer digits, it is padded on the left with
8104 zeros.
8105 In no case does a non-existent or small field width
8106 cause truncation of a numeric field; if the result of
8107 a conversion is wider than the field width, the field
8108 is expanded to contain the conversion result.
8109 The 'h' modifier indicates the argument is 16 bits.
Christ van Willegenaa90d4f2023-09-03 17:22:37 +02008110 The 'l' modifier indicates the argument is a long
8111 integer. The size will be 32 bits or 64 bits
8112 depending on your platform.
8113 The "ll" modifier indicates the argument is 64 bits.
8114 The b and B conversion specifiers never take a width
8115 modifier and always assume their argument is a 64 bit
8116 integer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008117 Generally, these modifiers are not useful. They are
8118 ignored when type is known from the argument.
8119
8120 i alias for d
8121 D alias for ld
8122 U alias for lu
8123 O alias for lo
8124
8125 *printf-c*
8126 c The Number argument is converted to a byte, and the
8127 resulting character is written.
8128
8129 *printf-s*
8130 s The text of the String argument is used. If a
8131 precision is specified, no more bytes than the number
8132 specified are used.
8133 If the argument is not a String type, it is
8134 automatically converted to text with the same format
8135 as ":echo".
8136 *printf-S*
8137 S The text of the String argument is used. If a
8138 precision is specified, no more display cells than the
8139 number specified are used.
8140
8141 *printf-f* *E807*
8142 f F The Float argument is converted into a string of the
8143 form 123.456. The precision specifies the number of
8144 digits after the decimal point. When the precision is
8145 zero the decimal point is omitted. When the precision
8146 is not specified 6 is used. A really big number
8147 (out of range or dividing by zero) results in "inf"
8148 or "-inf" with %f (INF or -INF with %F).
8149 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
8150 Example: >
8151 echo printf("%.2f", 12.115)
8152< 12.12
8153 Note that roundoff depends on the system libraries.
8154 Use |round()| when in doubt.
8155
8156 *printf-e* *printf-E*
8157 e E The Float argument is converted into a string of the
8158 form 1.234e+03 or 1.234E+03 when using 'E'. The
8159 precision specifies the number of digits after the
8160 decimal point, like with 'f'.
8161
8162 *printf-g* *printf-G*
8163 g G The Float argument is converted like with 'f' if the
8164 value is between 0.001 (inclusive) and 10000000.0
8165 (exclusive). Otherwise 'e' is used for 'g' and 'E'
8166 for 'G'. When no precision is specified superfluous
8167 zeroes and '+' signs are removed, except for the zero
8168 immediately after the decimal point. Thus 10000000.0
8169 results in 1.0e7.
8170
8171 *printf-%*
8172 % A '%' is written. No argument is converted. The
8173 complete conversion specification is "%%".
8174
8175 When a Number argument is expected a String argument is also
8176 accepted and automatically converted.
8177 When a Float or String argument is expected a Number argument
8178 is also accepted and automatically converted.
8179 Any other argument type results in an error message.
8180
8181 *E766* *E767*
8182 The number of {exprN} arguments must exactly match the number
8183 of "%" items. If there are not sufficient or too many
8184 arguments an error is given. Up to 18 arguments can be used.
8185
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008186 *printf-$*
8187 In certain languages, error and informative messages are
8188 more readable when the order of words is different from the
Christian Brabandtee17b6f2023-09-09 11:23:50 +02008189 corresponding message in English. To accommodate translations
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008190 having a different word order, positional arguments may be
8191 used to indicate this. For instance: >
8192
h_east596a9f22023-11-21 21:24:23 +09008193 #, c-format
8194 msgid "%s returning %s"
8195 msgstr "waarde %2$s komt terug van %1$s"
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008196<
h_east596a9f22023-11-21 21:24:23 +09008197 In this example, the sentence has its 2 string arguments
8198 reversed in the output. >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008199
h_east596a9f22023-11-21 21:24:23 +09008200 echo printf(
8201 "In The Netherlands, vim's creator's name is: %1$s %2$s",
8202 "Bram", "Moolenaar")
8203< In The Netherlands, vim's creator's name is: Bram Moolenaar >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008204
h_east596a9f22023-11-21 21:24:23 +09008205 echo printf(
8206 "In Belgium, vim's creator's name is: %2$s %1$s",
8207 "Bram", "Moolenaar")
8208< In Belgium, vim's creator's name is: Moolenaar Bram
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008209
8210 Width (and precision) can be specified using the '*' specifier.
8211 In this case, you must specify the field width position in the
8212 argument list. >
8213
h_east596a9f22023-11-21 21:24:23 +09008214 echo printf("%1$*2$.*3$d", 1, 2, 3)
8215< 001 >
8216 echo printf("%2$*3$.*1$d", 1, 2, 3)
8217< 2 >
8218 echo printf("%3$*1$.*2$d", 1, 2, 3)
8219< 03 >
8220 echo printf("%1$*2$.*3$g", 1.4142, 2, 3)
8221< 1.414
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008222
8223 You can mix specifying the width and/or precision directly
8224 and via positional arguments: >
8225
h_east596a9f22023-11-21 21:24:23 +09008226 echo printf("%1$4.*2$f", 1.4142135, 6)
8227< 1.414214 >
8228 echo printf("%1$*2$.4f", 1.4142135, 6)
8229< 1.4142 >
8230 echo printf("%1$*2$.*3$f", 1.4142135, 6, 2)
8231< 1.41
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008232
Christ van Willegenc35fc032024-03-14 18:30:41 +01008233 You will get an overflow error |E1510|, when the field-width
Hirohito Higashi0ed11ba2025-04-18 18:45:31 +02008234 or precision will result in a string longer than 1 MiB
zeertzjqe9a27ef2025-04-18 10:45:45 +02008235 (1024*1024 = 1048576) chars.
Christ van Willegenc35fc032024-03-14 18:30:41 +01008236
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008237 *E1500*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008238 You cannot mix positional and non-positional arguments: >
h_east596a9f22023-11-21 21:24:23 +09008239 echo printf("%s%1$s", "One", "Two")
8240< E1500: Cannot mix positional and non-positional arguments:
8241 %s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008242
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008243 *E1501*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008244 You cannot skip a positional argument in a format string: >
h_east596a9f22023-11-21 21:24:23 +09008245 echo printf("%3$s%1$s", "One", "Two", "Three")
8246< E1501: format argument 2 unused in $-style format:
8247 %3$s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008248
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008249 *E1502*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008250 You can re-use a [field-width] (or [precision]) argument: >
h_east596a9f22023-11-21 21:24:23 +09008251 echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2)
8252< 1 at width 2 is: 01
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008253
8254 However, you can't use it as a different type: >
h_east596a9f22023-11-21 21:24:23 +09008255 echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2)
8256< E1502: Positional argument 2 used as field width reused as
8257 different type: long int/int
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008258
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008259 *E1503*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008260 When a positional argument is used, but not the correct number
8261 or arguments is given, an error is raised: >
h_east596a9f22023-11-21 21:24:23 +09008262 echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2)
8263< E1503: Positional argument 3 out of bounds: %1$d at width
8264 %2$d is: %01$*2$.*3$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008265
8266 Only the first error is reported: >
h_east596a9f22023-11-21 21:24:23 +09008267 echo printf("%01$*2$.*3$d %4$d", 1, 2)
8268< E1503: Positional argument 3 out of bounds: %01$*2$.*3$d
8269 %4$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008270
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008271 *E1504*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008272 A positional argument can be used more than once: >
h_east596a9f22023-11-21 21:24:23 +09008273 echo printf("%1$s %2$s %1$s", "One", "Two")
8274< One Two One
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008275
8276 However, you can't use a different type the second time: >
h_east596a9f22023-11-21 21:24:23 +09008277 echo printf("%1$s %2$s %1$d", "One", "Two")
8278< E1504: Positional argument 1 type used inconsistently:
8279 int/string
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008280
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008281 *E1505*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008282 Various other errors that lead to a format string being
8283 wrongly formatted lead to: >
h_east596a9f22023-11-21 21:24:23 +09008284 echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2)
8285< E1505: Invalid format specifier: %1$d at width %2$d is:
8286 %01$*2$.3$d
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008287
Christ van Willegenea746f92023-10-05 20:48:36 +02008288 *E1507*
zeertzjq27e12c72023-10-07 01:34:04 +08008289 This internal error indicates that the logic to parse a
8290 positional format argument ran into a problem that couldn't be
8291 otherwise reported. Please file a bug against Vim if you run
8292 into this, copying the exact format string and parameters that
8293 were used.
Christ van Willegenea746f92023-10-05 20:48:36 +02008294
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008295 Return type: |String|
8296
Christ van Willegenea746f92023-10-05 20:48:36 +02008297
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008298prompt_getprompt({buf}) *prompt_getprompt()*
8299 Returns the effective prompt text for buffer {buf}. {buf} can
8300 be a buffer name or number. See |prompt-buffer|.
8301
8302 If the buffer doesn't exist or isn't a prompt buffer, an empty
8303 string is returned.
8304
8305 Can also be used as a |method|: >
8306 GetBuffer()->prompt_getprompt()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008307<
8308 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008309
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008310 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008311
8312
8313prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
8314 Set prompt callback for buffer {buf} to {expr}. When {expr}
8315 is an empty string the callback is removed. This has only
8316 effect if {buf} has 'buftype' set to "prompt".
8317
8318 The callback is invoked when pressing Enter. The current
8319 buffer will always be the prompt buffer. A new line for a
8320 prompt is added before invoking the callback, thus the prompt
8321 for which the callback was invoked will be in the last but one
8322 line.
8323 If the callback wants to add text to the buffer, it must
8324 insert it above the last line, since that is where the current
8325 prompt is. This can also be done asynchronously.
8326 The callback is invoked with one argument, which is the text
8327 that was entered at the prompt. This can be an empty string
8328 if the user only typed Enter.
8329 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008330 func s:TextEntered(text)
8331 if a:text == 'exit' || a:text == 'quit'
8332 stopinsert
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008333 " Reset 'modified' to allow the buffer to be closed.
8334 " We assume there is nothing useful to be saved.
8335 set nomodified
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008336 close
8337 else
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008338 " Do something useful with "a:text". In this example
8339 " we just repeat it.
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008340 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008341 endif
8342 endfunc
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008343 call prompt_setcallback(bufnr(), function('s:TextEntered'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008344
8345< Can also be used as a |method|: >
8346 GetBuffer()->prompt_setcallback(callback)
8347
8348< {only available when compiled with the |+channel| feature}
8349
8350prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
8351 Set a callback for buffer {buf} to {expr}. When {expr} is an
8352 empty string the callback is removed. This has only effect if
8353 {buf} has 'buftype' set to "prompt".
8354
8355 This callback will be invoked when pressing CTRL-C in Insert
8356 mode. Without setting a callback Vim will exit Insert mode,
8357 as in any buffer.
8358
8359 Can also be used as a |method|: >
8360 GetBuffer()->prompt_setinterrupt(callback)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008361<
8362 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008363
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008364 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008365
8366prompt_setprompt({buf}, {text}) *prompt_setprompt()*
8367 Set prompt for buffer {buf} to {text}. You most likely want
8368 {text} to end in a space.
8369 The result is only visible if {buf} has 'buftype' set to
8370 "prompt". Example: >
8371 call prompt_setprompt(bufnr(), 'command: ')
8372<
8373 Can also be used as a |method|: >
8374 GetBuffer()->prompt_setprompt('command: ')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008375<
8376 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008377
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008378 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008379
8380prop_ functions are documented here: |text-prop-functions|
8381
8382pum_getpos() *pum_getpos()*
8383 If the popup menu (see |ins-completion-menu|) is not visible,
8384 returns an empty |Dictionary|, otherwise, returns a
8385 |Dictionary| with the following keys:
8386 height nr of items visible
8387 width screen cells
8388 row top screen row (0 first row)
8389 col leftmost screen column (0 first col)
8390 size total nr of items
8391 scrollbar |TRUE| if scrollbar is visible
8392
8393 The values are the same as in |v:event| during
8394 |CompleteChanged|.
8395
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008396 Return type: dict<any>
8397
8398
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008399pumvisible() *pumvisible()*
8400 Returns non-zero when the popup menu is visible, zero
8401 otherwise. See |ins-completion-menu|.
8402 This can be used to avoid some things that would remove the
8403 popup menu.
8404
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008405 Return type: |Number|
8406
8407
zeertzjq7c515282024-11-10 20:26:12 +01008408py3eval({expr} [, {locals}]) *py3eval()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008409 Evaluate Python expression {expr} and return its result
8410 converted to Vim data structures.
Ben Jacksonea19e782024-11-06 21:50:05 +01008411 If a {locals} |Dictionary| is given, it defines set of local
8412 variables available in the expression. The keys are variable
Yegappan Lakshmanan038be272025-03-26 18:46:21 +01008413 names and the values are the variable values. |Dictionary|,
8414 |List| and |Tuple| values are referenced, and may be updated
8415 by the expression (as if |python-bindeval| was used).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008416 Numbers and strings are returned as they are (strings are
8417 copied though, Unicode strings are additionally converted to
8418 'encoding').
8419 Lists are represented as Vim |List| type.
Yegappan Lakshmanan038be272025-03-26 18:46:21 +01008420 Tuples are represented as Vim |Tuple| type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008421 Dictionaries are represented as Vim |Dictionary| type with
8422 keys converted to strings.
8423 Note that in a `:def` function local variables are not visible
8424 to {expr}.
8425
8426 Can also be used as a |method|: >
8427 GetExpr()->py3eval()
Ben Jacksonea19e782024-11-06 21:50:05 +01008428 'b",".join(l)'->py3eval({'l': ['a', 'b', 'c']})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008429<
8430 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008431
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008432 {only available when compiled with the |+python3| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008433
8434 *E858* *E859*
zeertzjq7c515282024-11-10 20:26:12 +01008435pyeval({expr} [, {locals}]) *pyeval()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008436 Evaluate Python expression {expr} and return its result
8437 converted to Vim data structures.
Ben Jacksonea19e782024-11-06 21:50:05 +01008438 For {locals} see |py3eval()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008439 Numbers and strings are returned as they are (strings are
8440 copied though).
8441 Lists are represented as Vim |List| type.
Yegappan Lakshmanan038be272025-03-26 18:46:21 +01008442 Tuples are represented as Vim |Tuple| type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008443 Dictionaries are represented as Vim |Dictionary| type,
8444 non-string keys result in error.
8445 Note that in a `:def` function local variables are not visible
8446 to {expr}.
8447
8448 Can also be used as a |method|: >
8449 GetExpr()->pyeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008450<
8451 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008452
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008453 {only available when compiled with the |+python| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008454
zeertzjq7c515282024-11-10 20:26:12 +01008455pyxeval({expr} [, {locals}]) *pyxeval()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008456 Evaluate Python expression {expr} and return its result
8457 converted to Vim data structures.
Ben Jacksonea19e782024-11-06 21:50:05 +01008458 For {locals} see |py3eval()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008459 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
8460 See also: |pyeval()|, |py3eval()|
8461
8462 Can also be used as a |method|: >
h-east52e7cc22024-07-28 17:03:29 +02008463 GetExpr()->pyxeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008464<
8465 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008466
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008467 {only available when compiled with the |+python| or the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008468 |+python3| feature}
8469
8470rand([{expr}]) *rand()* *random*
8471 Return a pseudo-random Number generated with an xoshiro128**
8472 algorithm using seed {expr}. The returned number is 32 bits,
8473 also on 64 bits systems, for consistency.
8474 {expr} can be initialized by |srand()| and will be updated by
8475 rand(). If {expr} is omitted, an internal seed value is used
8476 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008477 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008478
8479 Examples: >
8480 :echo rand()
8481 :let seed = srand()
8482 :echo rand(seed)
8483 :echo rand(seed) % 16 " random number 0 - 15
8484<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008485 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008486
8487 *E726* *E727*
8488range({expr} [, {max} [, {stride}]]) *range()*
8489 Returns a |List| with Numbers:
8490 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
8491 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
8492 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
8493 {max}] (increasing {expr} with {stride} each time, not
8494 producing a value past {max}).
8495 When the maximum is one before the start the result is an
8496 empty list. When the maximum is more than one before the
8497 start this is an error.
8498 Examples: >
8499 range(4) " [0, 1, 2, 3]
8500 range(2, 4) " [2, 3, 4]
8501 range(2, 9, 3) " [2, 5, 8]
8502 range(2, -2, -1) " [2, 1, 0, -1, -2]
8503 range(0) " []
8504 range(2, 0) " error!
8505<
8506 Can also be used as a |method|: >
8507 GetExpr()->range()
8508<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008509 Return type: list<number>
8510
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008511
K.Takata11df3ae2022-10-19 14:02:40 +01008512readblob({fname} [, {offset} [, {size}]]) *readblob()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008513 Read file {fname} in binary mode and return a |Blob|.
K.Takata11df3ae2022-10-19 14:02:40 +01008514 If {offset} is specified, read the file from the specified
8515 offset. If it is a negative value, it is used as an offset
8516 from the end of the file. E.g., to read the last 12 bytes: >
8517 readblob('file.bin', -12)
8518< If {size} is specified, only the specified size will be read.
8519 E.g. to read the first 100 bytes of a file: >
8520 readblob('file.bin', 0, 100)
8521< If {size} is -1 or omitted, the whole data starting from
8522 {offset} will be read.
K.Takata43625762022-10-20 13:28:51 +01008523 This can be also used to read the data from a character device
8524 on Unix when {size} is explicitly set. Only if the device
8525 supports seeking {offset} can be used. Otherwise it should be
8526 zero. E.g. to read 10 bytes from a serial console: >
8527 readblob('/dev/ttyS0', 0, 10)
8528< When the file can't be opened an error message is given and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008529 the result is an empty |Blob|.
Bram Moolenaar5b2a3d72022-10-21 11:25:30 +01008530 When the offset is beyond the end of the file the result is an
8531 empty blob.
8532 When trying to read more bytes than are available the result
8533 is truncated.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008534 Also see |readfile()| and |writefile()|.
8535
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008536 Return type: |Blob|
8537
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008538
8539readdir({directory} [, {expr} [, {dict}]]) *readdir()*
8540 Return a list with file and directory names in {directory}.
8541 You can also use |glob()| if you don't need to do complicated
8542 things, such as limiting the number of matches.
8543 The list will be sorted (case sensitive), see the {dict}
8544 argument below for changing the sort order.
8545
8546 When {expr} is omitted all entries are included.
8547 When {expr} is given, it is evaluated to check what to do:
8548 If {expr} results in -1 then no further entries will
8549 be handled.
8550 If {expr} results in 0 then this entry will not be
8551 added to the list.
8552 If {expr} results in 1 then this entry will be added
8553 to the list.
8554 The entries "." and ".." are always excluded.
8555 Each time {expr} is evaluated |v:val| is set to the entry name.
8556 When {expr} is a function the name is passed as the argument.
8557 For example, to get a list of files ending in ".txt": >
8558 readdir(dirname, {n -> n =~ '.txt$'})
8559< To skip hidden and backup files: >
8560 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00008561< *E857*
8562 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008563 values. Currently this is used to specify if and how sorting
8564 should be performed. The dict can have the following members:
8565
8566 sort How to sort the result returned from the system.
8567 Valid values are:
8568 "none" do not sort (fastest method)
8569 "case" sort case sensitive (byte value of
8570 each character, technically, using
8571 strcmp()) (default)
8572 "icase" sort case insensitive (technically
8573 using strcasecmp())
8574 "collate" sort using the collation order
8575 of the "POSIX" or "C" |locale|
8576 (technically using strcoll())
8577 Other values are silently ignored.
8578
8579 For example, to get a list of all files in the current
8580 directory without sorting the individual entries: >
8581 readdir('.', '1', #{sort: 'none'})
8582< If you want to get a directory tree: >
8583 function! s:tree(dir)
8584 return {a:dir : map(readdir(a:dir),
8585 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008586 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008587 endfunction
8588 echo s:tree(".")
8589<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008590 Returns an empty List on error.
8591
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008592 Can also be used as a |method|: >
8593 GetDirName()->readdir()
8594<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008595 Return type: list<string> or list<any>
8596
8597
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008598readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
8599 Extended version of |readdir()|.
8600 Return a list of Dictionaries with file and directory
8601 information in {directory}.
8602 This is useful if you want to get the attributes of file and
8603 directory at the same time as getting a list of a directory.
8604 This is much faster than calling |readdir()| then calling
8605 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
8606 each file and directory especially on MS-Windows.
8607 The list will by default be sorted by name (case sensitive),
8608 the sorting can be changed by using the optional {dict}
8609 argument, see |readdir()|.
8610
8611 The Dictionary for file and directory information has the
8612 following items:
8613 group Group name of the entry. (Only on Unix)
8614 name Name of the entry.
8615 perm Permissions of the entry. See |getfperm()|.
8616 size Size of the entry. See |getfsize()|.
8617 time Timestamp of the entry. See |getftime()|.
8618 type Type of the entry.
8619 On Unix, almost same as |getftype()| except:
8620 Symlink to a dir "linkd"
8621 Other symlink "link"
8622 On MS-Windows:
8623 Normal file "file"
8624 Directory "dir"
8625 Junction "junction"
8626 Symlink to a dir "linkd"
8627 Other symlink "link"
8628 Other reparse point "reparse"
8629 user User name of the entry's owner. (Only on Unix)
8630 On Unix, if the entry is a symlink, the Dictionary includes
8631 the information of the target (except the "type" item).
8632 On MS-Windows, it includes the information of the symlink
8633 itself because of performance reasons.
8634
8635 When {expr} is omitted all entries are included.
8636 When {expr} is given, it is evaluated to check what to do:
8637 If {expr} results in -1 then no further entries will
8638 be handled.
8639 If {expr} results in 0 then this entry will not be
8640 added to the list.
8641 If {expr} results in 1 then this entry will be added
8642 to the list.
8643 The entries "." and ".." are always excluded.
8644 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
8645 of the entry.
8646 When {expr} is a function the entry is passed as the argument.
8647 For example, to get a list of files ending in ".txt": >
8648 readdirex(dirname, {e -> e.name =~ '.txt$'})
8649<
8650 For example, to get a list of all files in the current
8651 directory without sorting the individual entries: >
8652 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008653<
8654 Can also be used as a |method|: >
8655 GetDirName()->readdirex()
8656<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008657 Return type: list<dict<any>> or list<any>
8658
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008659
8660 *readfile()*
8661readfile({fname} [, {type} [, {max}]])
8662 Read file {fname} and return a |List|, each line of the file
8663 as an item. Lines are broken at NL characters. Macintosh
8664 files separated with CR will result in a single long line
8665 (unless a NL appears somewhere).
8666 All NUL characters are replaced with a NL character.
8667 When {type} contains "b" binary mode is used:
8668 - When the last line ends in a NL an extra empty list item is
8669 added.
8670 - No CR characters are removed.
8671 Otherwise:
8672 - CR characters that appear before a NL are removed.
8673 - Whether the last line ends in a NL or not does not matter.
8674 - When 'encoding' is Unicode any UTF-8 byte order mark is
8675 removed from the text.
8676 When {max} is given this specifies the maximum number of lines
8677 to be read. Useful if you only want to check the first ten
8678 lines of a file: >
8679 :for line in readfile(fname, '', 10)
8680 : if line =~ 'Date' | echo line | endif
8681 :endfor
8682< When {max} is negative -{max} lines from the end of the file
8683 are returned, or as many as there are.
8684 When {max} is zero the result is an empty list.
8685 Note that without {max} the whole file is read into memory.
8686 Also note that there is no recognition of encoding. Read a
8687 file into a buffer if you need to.
8688 Deprecated (use |readblob()| instead): When {type} contains
8689 "B" a |Blob| is returned with the binary data of the file
8690 unmodified.
8691 When the file can't be opened an error message is given and
8692 the result is an empty list.
8693 Also see |writefile()|.
8694
8695 Can also be used as a |method|: >
8696 GetFileName()->readfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008697<
8698 Return type: list<string> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008699
8700reduce({object}, {func} [, {initial}]) *reduce()* *E998*
8701 {func} is called for every item in {object}, which can be a
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01008702 |String|, |List|, |Tuple| or a |Blob|. {func} is called with
8703 two arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00008704 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008705
8706 {initial} is the initial result. When omitted, the first item
8707 in {object} is used and {func} is first called for the second
8708 item. If {initial} is not given and {object} is empty no
8709 result can be computed, an E998 error is given.
8710
8711 Examples: >
8712 echo reduce([1, 3, 5], { acc, val -> acc + val })
8713 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
8714 echo reduce(0z1122, { acc, val -> 2 * acc + val })
8715 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
8716<
8717 Can also be used as a |method|: >
8718 echo mylist->reduce({ acc, val -> acc + val }, 0)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008719<
8720 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
8721 depending on {object} and {func}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008722
8723
8724reg_executing() *reg_executing()*
8725 Returns the single letter name of the register being executed.
8726 Returns an empty string when no register is being executed.
8727 See |@|.
8728
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008729 Return type: |String|
8730
8731
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008732reg_recording() *reg_recording()*
8733 Returns the single letter name of the register being recorded.
8734 Returns an empty string when not recording. See |q|.
8735
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008736 Return type: |String|
8737
8738
8739reltime() *reltime()*
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008740reltime({start})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008741reltime({start}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008742 Return an item that represents a time value. The item is a
8743 list with items that depend on the system. In Vim 9 script
Bram Moolenaar71badf92023-04-22 22:40:14 +01008744 the type list<any> can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008745 The item can be passed to |reltimestr()| to convert it to a
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008746 string or |reltimefloat()| to convert to a Float. For
8747 example, to see the time spent in function Work(): >
8748 var startTime = reltime()
8749 Work()
8750 echo startTime->reltime()->reltimestr()
8751<
Bram Moolenaar016188f2022-06-06 20:52:59 +01008752 Without an argument reltime() returns the current time (the
Lifepillar963fd7d2024-01-05 17:44:57 +01008753 representation is system-dependent, it cannot be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01008754 wall-clock time, see |localtime()| for that).
Lifepillar963fd7d2024-01-05 17:44:57 +01008755 With one argument it returns the time passed since the time
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008756 specified in the argument.
8757 With two arguments it returns the time passed between {start}
8758 and {end}.
8759
8760 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008761 reltime(). If there is an error an empty List is returned in
8762 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008763
8764 Can also be used as a |method|: >
8765 GetStart()->reltime()
8766<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008767 Return type: list<number>
8768
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008769 {only available when compiled with the |+reltime| feature}
8770
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008771
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008772reltimefloat({time}) *reltimefloat()*
8773 Return a Float that represents the time value of {time}.
8774 Example: >
8775 let start = reltime()
8776 call MyFunction()
8777 let seconds = reltimefloat(reltime(start))
8778< See the note of reltimestr() about overhead.
8779 Also see |profiling|.
8780 If there is an error 0.0 is returned in legacy script, in Vim9
8781 script an error is given.
8782
8783 Can also be used as a |method|: >
8784 reltime(start)->reltimefloat()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008785<
8786 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008787
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008788 {only available when compiled with the |+reltime| feature}
8789
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008790
8791reltimestr({time}) *reltimestr()*
8792 Return a String that represents the time value of {time}.
8793 This is the number of seconds, a dot and the number of
8794 microseconds. Example: >
8795 let start = reltime()
8796 call MyFunction()
8797 echo reltimestr(reltime(start))
8798< Note that overhead for the commands will be added to the time.
Ernie Rael076de792023-03-16 21:43:15 +00008799 The accuracy depends on the system. Use reltimefloat() for the
8800 greatest accuracy which is nanoseconds on some systems.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008801 Leading spaces are used to make the string align nicely. You
8802 can use split() to remove it. >
8803 echo split(reltimestr(reltime(start)))[0]
8804< Also see |profiling|.
8805 If there is an error an empty string is returned in legacy
8806 script, in Vim9 script an error is given.
8807
8808 Can also be used as a |method|: >
8809 reltime(start)->reltimestr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008810<
8811 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008812
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008813 {only available when compiled with the |+reltime| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008814
8815 *remote_expr()* *E449*
8816remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00008817 Send the {string} to {server}. The {server} argument is a
8818 string, also see |{server}|.
8819
8820 The string is sent as an expression and the result is returned
Christian Brabandt1961caf2024-10-12 11:57:12 +02008821 after evaluation. The result must be a String or a |List|
8822 other types will be converted to String. A |List| is turned
8823 into a String by joining the items with a line break in
8824 between (not at the end), like with join(expr, "\n").
Bram Moolenaar944697a2022-02-20 19:48:20 +00008825
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008826 If {idvar} is present and not empty, it is taken as the name
8827 of a variable and a {serverid} for later use with
8828 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008829
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008830 If {timeout} is given the read times out after this many
8831 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008832
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008833 See also |clientserver| |RemoteReply|.
8834 This function is not available in the |sandbox|.
8835 {only available when compiled with the |+clientserver| feature}
8836 Note: Any errors will cause a local error message to be issued
8837 and the result will be the empty string.
8838
8839 Variables will be evaluated in the global namespace,
8840 independent of a function currently being active. Except
8841 when in debug mode, then local function variables and
8842 arguments can be evaluated.
8843
8844 Examples: >
8845 :echo remote_expr("gvim", "2+2")
8846 :echo remote_expr("gvim1", "b:current_syntax")
8847<
8848 Can also be used as a |method|: >
8849 ServerName()->remote_expr(expr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008850<
8851 Return type: |String| or list<{type}>
8852
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008853
8854remote_foreground({server}) *remote_foreground()*
8855 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008856 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008857 This works like: >
8858 remote_expr({server}, "foreground()")
8859< Except that on Win32 systems the client does the work, to work
8860 around the problem that the OS doesn't always allow the server
8861 to bring itself to the foreground.
8862 Note: This does not restore the window if it was minimized,
8863 like foreground() does.
8864 This function is not available in the |sandbox|.
8865
8866 Can also be used as a |method|: >
8867 ServerName()->remote_foreground()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008868<
8869 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008870
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008871 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008872 Win32 console version}
8873
8874
8875remote_peek({serverid} [, {retvar}]) *remote_peek()*
8876 Returns a positive number if there are available strings
8877 from {serverid}. Copies any reply string into the variable
8878 {retvar} if specified. {retvar} must be a string with the
8879 name of a variable.
8880 Returns zero if none are available.
8881 Returns -1 if something is wrong.
8882 See also |clientserver|.
8883 This function is not available in the |sandbox|.
8884 {only available when compiled with the |+clientserver| feature}
8885 Examples: >
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008886 :let repl = ""
8887 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008888
8889< Can also be used as a |method|: >
8890 ServerId()->remote_peek()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008891<
8892 Return type: |Number|
8893
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008894
8895remote_read({serverid}, [{timeout}]) *remote_read()*
8896 Return the oldest available reply from {serverid} and consume
8897 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008898 reply is available. Returns an empty string, if a reply is
8899 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008900 See also |clientserver|.
8901 This function is not available in the |sandbox|.
8902 {only available when compiled with the |+clientserver| feature}
8903 Example: >
8904 :echo remote_read(id)
8905
8906< Can also be used as a |method|: >
8907 ServerId()->remote_read()
8908<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008909 Return type: |String|
8910
8911
8912remote_send({server}, {string} [, {idvar}]) *remote_send()* *E241*
Bram Moolenaar944697a2022-02-20 19:48:20 +00008913 Send the {string} to {server}. The {server} argument is a
8914 string, also see |{server}|.
8915
8916 The string is sent as input keys and the function returns
8917 immediately. At the Vim server the keys are not mapped
8918 |:map|.
8919
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008920 If {idvar} is present, it is taken as the name of a variable
8921 and a {serverid} for later use with remote_read() is stored
8922 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008923
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008924 See also |clientserver| |RemoteReply|.
8925 This function is not available in the |sandbox|.
8926 {only available when compiled with the |+clientserver| feature}
8927
8928 Note: Any errors will be reported in the server and may mess
8929 up the display.
8930 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008931 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008932 \ remote_read(serverid)
8933
8934 :autocmd NONE RemoteReply *
8935 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008936 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008937 \ 'server2client(expand("<client>"), "HELLO")<CR>')
8938<
8939 Can also be used as a |method|: >
8940 ServerName()->remote_send(keys)
8941<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008942 Return type: |String|
8943
8944
8945remote_startserver({name}) *remote_startserver()* *E941* *E942*
h-east17b69512023-05-01 22:36:56 +01008946 Become the server {name}. {name} must be a non-empty string.
8947 This fails if already running as a server, when |v:servername|
8948 is not empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008949
8950 Can also be used as a |method|: >
8951 ServerName()->remote_startserver()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008952<
8953 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008954
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008955 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008956
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008957
8958remove({list}, {idx}) *remove()*
8959remove({list}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008960 Without {end}: Remove the item at {idx} from |List| {list} and
8961 return the item.
8962 With {end}: Remove items from {idx} to {end} (inclusive) and
8963 return a |List| with these items. When {idx} points to the same
8964 item as {end} a list with one item is returned. When {end}
8965 points to an item before {idx} this is an error.
8966 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008967 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008968 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008969 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008970 :call remove(mylist, 0, 9)
8971<
8972 Use |delete()| to remove a file.
8973
8974 Can also be used as a |method|: >
8975 mylist->remove(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008976<
8977 Return type: any, depending on {list}
8978
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008979
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008980remove({blob}, {idx})
8981remove({blob}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008982 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
8983 return the byte.
8984 With {end}: Remove bytes from {idx} to {end} (inclusive) and
8985 return a |Blob| with these bytes. When {idx} points to the same
8986 byte as {end} a |Blob| with one byte is returned. When {end}
8987 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008988 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008989 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008990 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008991 :call remove(mylist, 0, 9)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008992<
8993 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008994
8995remove({dict}, {key})
8996 Remove the entry from {dict} with key {key} and return it.
8997 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008998 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008999< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009000 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009001
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009002 Return type: any, depending on {dict}
9003
9004
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009005rename({from}, {to}) *rename()*
9006 Rename the file by the name {from} to the name {to}. This
9007 should also work to move files across file systems. The
9008 result is a Number, which is 0 if the file was renamed
9009 successfully, and non-zero when the renaming failed.
9010 NOTE: If {to} exists it is overwritten without warning.
9011 This function is not available in the |sandbox|.
9012
9013 Can also be used as a |method|: >
9014 GetOldName()->rename(newname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009015<
9016 Return type: |Number|
9017
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009018
9019repeat({expr}, {count}) *repeat()*
9020 Repeat {expr} {count} times and return the concatenated
9021 result. Example: >
9022 :let separator = repeat('-', 80)
9023< When {count} is zero or negative the result is empty.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01009024 When {expr} is a |List|, a |Tuple| or a |Blob| the result is
9025 {expr} concatenated {count} times. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009026 :let longlist = repeat(['a', 'b'], 3)
9027< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
9028
9029 Can also be used as a |method|: >
9030 mylist->repeat(count)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009031<
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01009032 Return type: |String|, |Blob|, list<{type}> or tuple<{type}>
9033 depending on {expr}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009034
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009035
9036resolve({filename}) *resolve()* *E655*
9037 On MS-Windows, when {filename} is a shortcut (a .lnk file),
9038 returns the path the shortcut points to in a simplified form.
9039 When {filename} is a symbolic link or junction point, return
9040 the full path to the target. If the target of junction is
9041 removed, return {filename}.
9042 On Unix, repeat resolving symbolic links in all path
9043 components of {filename} and return the simplified result.
9044 To cope with link cycles, resolving of symbolic links is
9045 stopped after 100 iterations.
9046 On other systems, return the simplified {filename}.
9047 The simplification step is done as by |simplify()|.
9048 resolve() keeps a leading path component specifying the
9049 current directory (provided the result is still a relative
9050 path name) and also keeps a trailing path separator.
9051
9052 Can also be used as a |method|: >
9053 GetName()->resolve()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009054<
9055 Return type: |String|
9056
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009057
9058reverse({object}) *reverse()*
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +01009059 Reverse the order of items in {object}. {object} can be a
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01009060 |List|, a |Tuple|, a |Blob| or a |String|. For a List and a
9061 Blob the items are reversed in-place and {object} is returned.
9062 For a Tuple, a new Tuple is returned.
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +01009063 For a String a new String is returned.
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01009064 Returns zero if {object} is not a List, Tuple, Blob or a
9065 String. If you want a List or Blob to remain unmodified make
9066 a copy first: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009067 :let revlist = reverse(copy(mylist))
9068< Can also be used as a |method|: >
9069 mylist->reverse()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009070<
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +01009071 Return type: |String|, |Blob|, list<{type}> or tuple<{type}>
9072 depending on {object}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009073
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009074
9075round({expr}) *round()*
9076 Round off {expr} to the nearest integral value and return it
9077 as a |Float|. If {expr} lies halfway between two integral
9078 values, then use the larger one (away from zero).
9079 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009080 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009081 Examples: >
9082 echo round(0.456)
9083< 0.0 >
9084 echo round(4.5)
9085< 5.0 >
9086 echo round(-4.5)
9087< -5.0
9088
9089 Can also be used as a |method|: >
9090 Compute()->round()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009091<
9092 Return type: |Float|
9093
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009094
9095rubyeval({expr}) *rubyeval()*
9096 Evaluate Ruby expression {expr} and return its result
9097 converted to Vim data structures.
9098 Numbers, floats and strings are returned as they are (strings
9099 are copied though).
9100 Arrays are represented as Vim |List| type.
9101 Hashes are represented as Vim |Dictionary| type.
9102 Other objects are represented as strings resulted from their
9103 "Object#to_s" method.
9104 Note that in a `:def` function local variables are not visible
9105 to {expr}.
9106
9107 Can also be used as a |method|: >
9108 GetRubyExpr()->rubyeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009109<
9110 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009111
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009112 {only available when compiled with the |+ruby| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009113
9114screenattr({row}, {col}) *screenattr()*
9115 Like |screenchar()|, but return the attribute. This is a rather
9116 arbitrary number that can only be used to compare to the
9117 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009118 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009119
9120 Can also be used as a |method|: >
9121 GetRow()->screenattr(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009122<
9123 Return type: |Number|
9124
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009125
9126screenchar({row}, {col}) *screenchar()*
9127 The result is a Number, which is the character at position
9128 [row, col] on the screen. This works for every possible
9129 screen position, also status lines, window separators and the
9130 command line. The top left position is row one, column one
9131 The character excludes composing characters. For double-byte
9132 encodings it may only be the first byte.
9133 This is mainly to be used for testing.
9134 Returns -1 when row or col is out of range.
9135
9136 Can also be used as a |method|: >
9137 GetRow()->screenchar(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009138<
9139 Return type: |Number|
9140
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009141
9142screenchars({row}, {col}) *screenchars()*
9143 The result is a |List| of Numbers. The first number is the same
9144 as what |screenchar()| returns. Further numbers are
9145 composing characters on top of the base character.
9146 This is mainly to be used for testing.
9147 Returns an empty List when row or col is out of range.
9148
9149 Can also be used as a |method|: >
9150 GetRow()->screenchars(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009151<
9152 Return type: list<number> or list<any>
9153
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009154
9155screencol() *screencol()*
9156 The result is a Number, which is the current screen column of
9157 the cursor. The leftmost column has number 1.
9158 This function is mainly used for testing.
9159
9160 Note: Always returns the current screen column, thus if used
9161 in a command (e.g. ":echo screencol()") it will return the
9162 column inside the command line, which is 1 when the command is
9163 executed. To get the cursor position in the file use one of
9164 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009165 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009166 nnoremap <silent> GG :echom screencol()<CR>
9167 nnoremap GG <Cmd>echom screencol()<CR>
9168<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009169 Return type: |Number|
9170
9171
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009172screenpos({winid}, {lnum}, {col}) *screenpos()*
9173 The result is a Dict with the screen position of the text
9174 character in window {winid} at buffer line {lnum} and column
9175 {col}. {col} is a one-based byte index.
9176 The Dict has these members:
9177 row screen row
9178 col first screen column
9179 endcol last screen column
9180 curscol cursor screen column
9181 If the specified position is not visible, all values are zero.
9182 The "endcol" value differs from "col" when the character
9183 occupies more than one screen cell. E.g. for a Tab "col" can
9184 be 1 and "endcol" can be 8.
9185 The "curscol" value is where the cursor would be placed. For
9186 a Tab it would be the same as "endcol", while for a double
9187 width character it would be the same as "col".
9188 The |conceal| feature is ignored here, the column numbers are
9189 as if 'conceallevel' is zero. You can set the cursor to the
9190 right position and use |screencol()| to get the value with
9191 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00009192 If the position is in a closed fold the screen position of the
9193 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009194 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009195
9196 Can also be used as a |method|: >
9197 GetWinid()->screenpos(lnum, col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009198<
9199 Return type: dict<number> or dict<any>
9200
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009201
9202screenrow() *screenrow()*
9203 The result is a Number, which is the current screen row of the
9204 cursor. The top line has number one.
9205 This function is mainly used for testing.
9206 Alternatively you can use |winline()|.
9207
9208 Note: Same restrictions as with |screencol()|.
9209
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009210 Return type: |Number|
9211
9212
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009213screenstring({row}, {col}) *screenstring()*
9214 The result is a String that contains the base character and
9215 any composing characters at position [row, col] on the screen.
9216 This is like |screenchars()| but returning a String with the
9217 characters.
9218 This is mainly to be used for testing.
9219 Returns an empty String when row or col is out of range.
9220
9221 Can also be used as a |method|: >
9222 GetRow()->screenstring(col)
9223<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009224 Return type: |String|
9225
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009226 *search()*
9227search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
9228 Search for regexp pattern {pattern}. The search starts at the
9229 cursor position (you can use |cursor()| to set it).
9230
9231 When a match has been found its line number is returned.
9232 If there is no match a 0 is returned and the cursor doesn't
9233 move. No error message is given.
Christian Brabandt9a660d22024-03-12 22:03:09 +01009234 To get the matched string, use |matchbufline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009235
9236 {flags} is a String, which can contain these character flags:
9237 'b' search Backward instead of forward
9238 'c' accept a match at the Cursor position
9239 'e' move to the End of the match
9240 'n' do Not move the cursor
9241 'p' return number of matching sub-Pattern (see below)
9242 's' Set the ' mark at the previous location of the cursor
9243 'w' Wrap around the end of the file
9244 'W' don't Wrap around the end of the file
Doug Kearns8a27d972025-01-05 15:56:57 +01009245 'z' start searching at the cursor column instead of Zero
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009246 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
9247
9248 If the 's' flag is supplied, the ' mark is set, only if the
9249 cursor is moved. The 's' flag cannot be combined with the 'n'
9250 flag.
9251
9252 'ignorecase', 'smartcase' and 'magic' are used.
9253
9254 When the 'z' flag is not given, forward searching always
9255 starts in column zero and then matches before the cursor are
9256 skipped. When the 'c' flag is present in 'cpo' the next
9257 search starts after the match. Without the 'c' flag the next
Bram Moolenaarfd999452022-08-24 18:30:14 +01009258 search starts one column after the start of the match. This
9259 matters for overlapping matches. See |cpo-c|. You can also
9260 insert "\ze" to change where the match ends, see |/\ze|.
9261
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009262 When searching backwards and the 'z' flag is given then the
9263 search starts in column zero, thus no match in the current
9264 line will be found (unless wrapping around the end of the
9265 file).
9266
9267 When the {stopline} argument is given then the search stops
9268 after searching this line. This is useful to restrict the
9269 search to a range of lines. Examples: >
9270 let match = search('(', 'b', line("w0"))
9271 let end = search('END', '', line("w$"))
9272< When {stopline} is used and it is not zero this also implies
9273 that the search does not wrap around the end of the file.
9274 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01009275 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009276 When the {timeout} argument is given the search stops when
9277 more than this many milliseconds have passed. Thus when
9278 {timeout} is 500 the search stops after half a second.
9279 The value must not be negative. A zero value is like not
9280 giving the argument.
Christian Brabandtd657d3d2024-09-10 21:55:49 +02009281
9282 Note: the timeout is only considered when searching, not
9283 while evaluating the {skip} expression.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009284 {only available when compiled with the |+reltime| feature}
9285
9286 If the {skip} expression is given it is evaluated with the
9287 cursor positioned on the start of a match. If it evaluates to
9288 non-zero this match is skipped. This can be used, for
9289 example, to skip a match in a comment or a string.
9290 {skip} can be a string, which is evaluated as an expression, a
9291 function reference or a lambda.
9292 When {skip} is omitted or empty, every match is accepted.
9293 When evaluating {skip} causes an error the search is aborted
9294 and -1 returned.
9295 *search()-sub-match*
9296 With the 'p' flag the returned value is one more than the
9297 first sub-match in \(\). One if none of them matched but the
9298 whole pattern did match.
9299 To get the column number too use |searchpos()|.
9300
9301 The cursor will be positioned at the match, unless the 'n'
9302 flag is used.
9303
9304 Example (goes over all files in the argument list): >
9305 :let n = 1
9306 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009307 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009308 : " start at the last char in the file and wrap for the
9309 : " first search to find match at start of file
9310 : normal G$
9311 : let flags = "w"
9312 : while search("foo", flags) > 0
9313 : s/foo/bar/g
9314 : let flags = "W"
9315 : endwhile
9316 : update " write the file if modified
9317 : let n = n + 1
9318 :endwhile
9319<
9320 Example for using some flags: >
9321 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
9322< This will search for the keywords "if", "else", and "endif"
9323 under or after the cursor. Because of the 'p' flag, it
9324 returns 1, 2, or 3 depending on which keyword is found, or 0
9325 if the search fails. With the cursor on the first word of the
9326 line:
9327 if (foo == 0) | let foo = foo + 1 | endif ~
9328 the function returns 1. Without the 'c' flag, the function
9329 finds the "endif" and returns 3. The same thing happens
9330 without the 'e' flag if the cursor is on the "f" of "if".
9331 The 'n' flag tells the function not to move the cursor.
9332
9333 Can also be used as a |method|: >
9334 GetPattern()->search()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009335<
9336 Return type: |Number|
9337
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009338
9339searchcount([{options}]) *searchcount()*
9340 Get or update the last search count, like what is displayed
9341 without the "S" flag in 'shortmess'. This works even if
9342 'shortmess' does contain the "S" flag.
9343
9344 This returns a |Dictionary|. The dictionary is empty if the
9345 previous pattern was not set and "pattern" was not specified.
9346
9347 key type meaning ~
9348 current |Number| current position of match;
9349 0 if the cursor position is
9350 before the first match
9351 exact_match |Boolean| 1 if "current" is matched on
9352 "pos", otherwise 0
9353 total |Number| total count of matches found
9354 incomplete |Number| 0: search was fully completed
9355 1: recomputing was timed out
9356 2: max count exceeded
9357
9358 For {options} see further down.
9359
9360 To get the last search count when |n| or |N| was pressed, call
9361 this function with `recompute: 0` . This sometimes returns
9362 wrong information because |n| and |N|'s maximum count is 99.
9363 If it exceeded 99 the result must be max count + 1 (100). If
9364 you want to get correct information, specify `recompute: 1`: >
9365
9366 " result == maxcount + 1 (100) when many matches
9367 let result = searchcount(#{recompute: 0})
9368
9369 " Below returns correct result (recompute defaults
9370 " to 1)
9371 let result = searchcount()
9372<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01009373 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009374 function! LastSearchCount() abort
9375 let result = searchcount(#{recompute: 0})
9376 if empty(result)
9377 return ''
9378 endif
9379 if result.incomplete ==# 1 " timed out
9380 return printf(' /%s [?/??]', @/)
9381 elseif result.incomplete ==# 2 " max count exceeded
9382 if result.total > result.maxcount &&
9383 \ result.current > result.maxcount
9384 return printf(' /%s [>%d/>%d]', @/,
9385 \ result.current, result.total)
9386 elseif result.total > result.maxcount
9387 return printf(' /%s [%d/>%d]', @/,
9388 \ result.current, result.total)
9389 endif
9390 endif
9391 return printf(' /%s [%d/%d]', @/,
9392 \ result.current, result.total)
9393 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009394 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009395
9396 " Or if you want to show the count only when
9397 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009398 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009399 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
9400<
9401 You can also update the search count, which can be useful in a
9402 |CursorMoved| or |CursorMovedI| autocommand: >
9403
9404 autocmd CursorMoved,CursorMovedI *
9405 \ let s:searchcount_timer = timer_start(
9406 \ 200, function('s:update_searchcount'))
9407 function! s:update_searchcount(timer) abort
9408 if a:timer ==# s:searchcount_timer
9409 call searchcount(#{
9410 \ recompute: 1, maxcount: 0, timeout: 100})
9411 redrawstatus
9412 endif
9413 endfunction
9414<
9415 This can also be used to count matched texts with specified
9416 pattern in the current buffer using "pattern": >
9417
9418 " Count '\<foo\>' in this buffer
9419 " (Note that it also updates search count)
9420 let result = searchcount(#{pattern: '\<foo\>'})
9421
9422 " To restore old search count by old pattern,
9423 " search again
9424 call searchcount()
9425<
9426 {options} must be a |Dictionary|. It can contain:
9427 key type meaning ~
9428 recompute |Boolean| if |TRUE|, recompute the count
9429 like |n| or |N| was executed.
9430 otherwise returns the last
9431 computed result (when |n| or
9432 |N| was used when "S" is not
9433 in 'shortmess', or this
9434 function was called).
9435 (default: |TRUE|)
9436 pattern |String| recompute if this was given
9437 and different with |@/|.
9438 this works as same as the
9439 below command is executed
9440 before calling this function >
9441 let @/ = pattern
9442< (default: |@/|)
9443 timeout |Number| 0 or negative number is no
9444 timeout. timeout milliseconds
9445 for recomputing the result
9446 (default: 0)
9447 maxcount |Number| 0 or negative number is no
9448 limit. max count of matched
9449 text while recomputing the
9450 result. if search exceeded
9451 total count, "total" value
9452 becomes `maxcount + 1`
9453 (default: 99)
9454 pos |List| `[lnum, col, off]` value
9455 when recomputing the result.
9456 this changes "current" result
9457 value. see |cursor()|,
9458 |getpos()|
9459 (default: cursor's position)
9460
9461 Can also be used as a |method|: >
9462 GetSearchOpts()->searchcount()
9463<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009464 Return type: dict<number>
9465
9466
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009467searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
9468 Search for the declaration of {name}.
9469
9470 With a non-zero {global} argument it works like |gD|, find
9471 first match in the file. Otherwise it works like |gd|, find
9472 first match in the function.
9473
9474 With a non-zero {thisblock} argument matches in a {} block
9475 that ends before the cursor position are ignored. Avoids
9476 finding variable declarations only valid in another scope.
9477
9478 Moves the cursor to the found match.
9479 Returns zero for success, non-zero for failure.
9480 Example: >
9481 if searchdecl('myvar') == 0
9482 echo getline('.')
9483 endif
9484<
9485 Can also be used as a |method|: >
9486 GetName()->searchdecl()
9487<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009488 Return type: |Number|
9489
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009490 *searchpair()*
9491searchpair({start}, {middle}, {end} [, {flags} [, {skip}
9492 [, {stopline} [, {timeout}]]]])
9493 Search for the match of a nested start-end pair. This can be
9494 used to find the "endif" that matches an "if", while other
9495 if/endif pairs in between are ignored.
9496 The search starts at the cursor. The default is to search
9497 forward, include 'b' in {flags} to search backward.
9498 If a match is found, the cursor is positioned at it and the
9499 line number is returned. If no match is found 0 or -1 is
9500 returned and the cursor doesn't move. No error message is
9501 given.
9502
9503 {start}, {middle} and {end} are patterns, see |pattern|. They
9504 must not contain \( \) pairs. Use of \%( \) is allowed. When
9505 {middle} is not empty, it is found when searching from either
9506 direction, but only when not in a nested start-end pair. A
9507 typical use is: >
9508 searchpair('\<if\>', '\<else\>', '\<endif\>')
9509< By leaving {middle} empty the "else" is skipped.
9510
9511 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
9512 |search()|. Additionally:
9513 'r' Repeat until no more matches found; will find the
9514 outer pair. Implies the 'W' flag.
9515 'm' Return number of matches instead of line number with
9516 the match; will be > 1 when 'r' is used.
9517 Note: it's nearly always a good idea to use the 'W' flag, to
9518 avoid wrapping around the end of the file.
9519
9520 When a match for {start}, {middle} or {end} is found, the
9521 {skip} expression is evaluated with the cursor positioned on
9522 the start of the match. It should return non-zero if this
9523 match is to be skipped. E.g., because it is inside a comment
9524 or a string.
9525 When {skip} is omitted or empty, every match is accepted.
9526 When evaluating {skip} causes an error the search is aborted
9527 and -1 returned.
9528 {skip} can be a string, a lambda, a funcref or a partial.
9529 Anything else makes the function fail.
9530 In a `:def` function when the {skip} argument is a string
9531 constant it is compiled into instructions.
9532
9533 For {stopline} and {timeout} see |search()|.
9534
9535 The value of 'ignorecase' is used. 'magic' is ignored, the
9536 patterns are used like it's on.
9537
9538 The search starts exactly at the cursor. A match with
9539 {start}, {middle} or {end} at the next character, in the
9540 direction of searching, is the first one found. Example: >
9541 if 1
9542 if 2
9543 endif 2
9544 endif 1
9545< When starting at the "if 2", with the cursor on the "i", and
9546 searching forwards, the "endif 2" is found. When starting on
9547 the character just before the "if 2", the "endif 1" will be
9548 found. That's because the "if 2" will be found first, and
9549 then this is considered to be a nested if/endif from "if 2" to
9550 "endif 2".
9551 When searching backwards and {end} is more than one character,
9552 it may be useful to put "\zs" at the end of the pattern, so
9553 that when the cursor is inside a match with the end it finds
9554 the matching start.
9555
9556 Example, to find the "endif" command in a Vim script: >
9557
9558 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
9559 \ 'getline(".") =~ "^\\s*\""')
9560
9561< The cursor must be at or after the "if" for which a match is
9562 to be found. Note that single-quote strings are used to avoid
9563 having to double the backslashes. The skip expression only
9564 catches comments at the start of a line, not after a command.
9565 Also, a word "en" or "if" halfway a line is considered a
9566 match.
9567 Another example, to search for the matching "{" of a "}": >
9568
9569 :echo searchpair('{', '', '}', 'bW')
9570
9571< This works when the cursor is at or before the "}" for which a
9572 match is to be found. To reject matches that syntax
9573 highlighting recognized as strings: >
9574
9575 :echo searchpair('{', '', '}', 'bW',
9576 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
9577<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009578 Return type: |Number|
9579
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009580 *searchpairpos()*
9581searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
9582 [, {stopline} [, {timeout}]]]])
9583 Same as |searchpair()|, but returns a |List| with the line and
9584 column position of the match. The first element of the |List|
9585 is the line number and the second element is the byte index of
9586 the column position of the match. If no match is found,
9587 returns [0, 0]. >
9588
9589 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
9590<
9591 See |match-parens| for a bigger and more useful example.
9592
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009593 Return type: list<number>
9594
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009595 *searchpos()*
9596searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
9597 Same as |search()|, but returns a |List| with the line and
9598 column position of the match. The first element of the |List|
9599 is the line number and the second element is the byte index of
9600 the column position of the match. If no match is found,
9601 returns [0, 0].
9602 Example: >
9603 :let [lnum, col] = searchpos('mypattern', 'n')
9604
9605< When the 'p' flag is given then there is an extra item with
9606 the sub-pattern match number |search()-sub-match|. Example: >
9607 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
9608< In this example "submatch" is 2 when a lowercase letter is
9609 found |/\l|, 3 when an uppercase letter is found |/\u|.
9610
9611 Can also be used as a |method|: >
9612 GetPattern()->searchpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009613<
9614 Return type: list<number>
9615
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009616
9617server2client({clientid}, {string}) *server2client()*
9618 Send a reply string to {clientid}. The most recent {clientid}
9619 that sent a string can be retrieved with expand("<client>").
9620 {only available when compiled with the |+clientserver| feature}
9621 Returns zero for success, -1 for failure.
9622 Note:
9623 This id has to be stored before the next command can be
9624 received. I.e. before returning from the received command and
9625 before calling any commands that waits for input.
9626 See also |clientserver|.
9627 Example: >
9628 :echo server2client(expand("<client>"), "HELLO")
9629
9630< Can also be used as a |method|: >
9631 GetClientId()->server2client(string)
9632<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009633 Return type: |Number|
9634
9635
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009636serverlist() *serverlist()*
9637 Return a list of available server names, one per line.
9638 When there are no servers or the information is not available
9639 an empty string is returned. See also |clientserver|.
9640 {only available when compiled with the |+clientserver| feature}
9641 Example: >
9642 :echo serverlist()
9643<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009644 Return type: |String|
9645
9646
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009647setbufline({buf}, {lnum}, {text}) *setbufline()*
9648 Set line {lnum} to {text} in buffer {buf}. This works like
9649 |setline()| for the specified buffer.
9650
9651 This function works only for loaded buffers. First call
9652 |bufload()| if needed.
9653
9654 To insert lines use |appendbufline()|.
9655 Any text properties in {lnum} are cleared.
9656
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00009657 {text} can be a string to set one line, or a List of strings
9658 to set multiple lines. If the List extends below the last
9659 line then those lines are added. If the List is empty then
9660 nothing is changed and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009661
9662 For the use of {buf}, see |bufname()| above.
9663
9664 {lnum} is used like with |setline()|.
9665 Use "$" to refer to the last line in buffer {buf}.
9666 When {lnum} is just below the last line the {text} will be
9667 added below the last line.
9668
9669 When {buf} is not a valid buffer, the buffer is not loaded or
9670 {lnum} is not valid then 1 is returned. In |Vim9| script an
9671 error is given.
9672 On success 0 is returned.
9673
9674 Can also be used as a |method|, the base is passed as the
9675 third argument: >
9676 GetText()->setbufline(buf, lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009677<
9678 Return type: |Number|
9679
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009680
9681setbufvar({buf}, {varname}, {val}) *setbufvar()*
9682 Set option or local variable {varname} in buffer {buf} to
9683 {val}.
9684 This also works for a global or local window option, but it
9685 doesn't work for a global or local window variable.
9686 For a local window option the global value is unchanged.
9687 For the use of {buf}, see |bufname()| above.
9688 The {varname} argument is a string.
9689 Note that the variable name without "b:" must be used.
9690 Examples: >
9691 :call setbufvar(1, "&mod", 1)
9692 :call setbufvar("todo", "myvar", "foobar")
9693< This function is not available in the |sandbox|.
9694
9695 Can also be used as a |method|, the base is passed as the
9696 third argument: >
9697 GetValue()->setbufvar(buf, varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009698<
9699 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009700
9701
9702setcellwidths({list}) *setcellwidths()*
9703 Specify overrides for cell widths of character ranges. This
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009704 tells Vim how wide characters are when displayed in the
9705 terminal, counted in screen cells. The values override
9706 'ambiwidth'. Example: >
9707 call setcellwidths([
Bram Moolenaar938ae282023-02-20 20:44:55 +00009708 \ [0x111, 0x111, 1],
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009709 \ [0x2194, 0x2199, 2],
9710 \ ])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009711
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009712< The {list} argument is a List of Lists with each three
9713 numbers: [{low}, {high}, {width}]. *E1109* *E1110*
9714 {low} and {high} can be the same, in which case this refers to
9715 one character. Otherwise it is the range of characters from
9716 {low} to {high} (inclusive). *E1111* *E1114*
K.Takata71933232023-01-20 16:00:55 +00009717 Only characters with value 0x80 and higher can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009718
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009719 {width} must be either 1 or 2, indicating the character width
9720 in screen cells. *E1112*
9721 An error is given if the argument is invalid, also when a
Bram Moolenaar938ae282023-02-20 20:44:55 +00009722 range overlaps with another. *E1113*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009723
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009724 If the new value causes 'fillchars' or 'listchars' to become
9725 invalid it is rejected and an error is given.
9726
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009727 To clear the overrides pass an empty {list}: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009728 setcellwidths([]);
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009729
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009730< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009731 the effect for known emoji characters. Move the cursor
9732 through the text to check if the cell widths of your terminal
9733 match with what Vim knows about each emoji. If it doesn't
9734 look right you need to adjust the {list} argument.
9735
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009736 Return type: |Number|
9737
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009738
9739setcharpos({expr}, {list}) *setcharpos()*
9740 Same as |setpos()| but uses the specified column number as the
9741 character index instead of the byte index in the line.
9742
9743 Example:
9744 With the text "여보세요" in line 8: >
9745 call setcharpos('.', [0, 8, 4, 0])
9746< positions the cursor on the fourth character '요'. >
9747 call setpos('.', [0, 8, 4, 0])
9748< positions the cursor on the second character '보'.
9749
9750 Can also be used as a |method|: >
9751 GetPosition()->setcharpos('.')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009752<
9753 Return type: |Number|
9754
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009755
9756setcharsearch({dict}) *setcharsearch()*
9757 Set the current character search information to {dict},
9758 which contains one or more of the following entries:
9759
9760 char character which will be used for a subsequent
9761 |,| or |;| command; an empty string clears the
9762 character search
9763 forward direction of character search; 1 for forward,
9764 0 for backward
9765 until type of character search; 1 for a |t| or |T|
9766 character search, 0 for an |f| or |F|
9767 character search
9768
9769 This can be useful to save/restore a user's character search
9770 from a script: >
9771 :let prevsearch = getcharsearch()
9772 :" Perform a command which clobbers user's search
9773 :call setcharsearch(prevsearch)
9774< Also see |getcharsearch()|.
9775
9776 Can also be used as a |method|: >
9777 SavedSearch()->setcharsearch()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009778<
9779 Return type: dict<any>
9780
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009781
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009782setcmdline({str} [, {pos}]) *setcmdline()*
9783 Set the command line to {str} and set the cursor position to
9784 {pos}.
9785 If {pos} is omitted, the cursor is positioned after the text.
9786 Returns 0 when successful, 1 when not editing the command
9787 line.
9788
9789 Can also be used as a |method|: >
9790 GetText()->setcmdline()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009791<
9792 Return type: |Number|
9793
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009794
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009795setcmdpos({pos}) *setcmdpos()*
9796 Set the cursor position in the command line to byte position
9797 {pos}. The first position is 1.
9798 Use |getcmdpos()| to obtain the current position.
9799 Only works while editing the command line, thus you must use
9800 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
9801 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
9802 set after the command line is set to the expression. For
9803 |c_CTRL-R_=| it is set after evaluating the expression but
9804 before inserting the resulting text.
9805 When the number is too big the cursor is put at the end of the
9806 line. A number smaller than one has undefined results.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009807 Returns 0 when successful, 1 when not editing the command
9808 line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009809
9810 Can also be used as a |method|: >
9811 GetPos()->setcmdpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009812<
9813 Return type: |Number|
9814
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009815
9816setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
9817setcursorcharpos({list})
9818 Same as |cursor()| but uses the specified column number as the
9819 character index instead of the byte index in the line.
9820
9821 Example:
9822 With the text "여보세요" in line 4: >
9823 call setcursorcharpos(4, 3)
9824< positions the cursor on the third character '세'. >
9825 call cursor(4, 3)
9826< positions the cursor on the first character '여'.
9827
9828 Can also be used as a |method|: >
9829 GetCursorPos()->setcursorcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009830<
9831 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009832
9833
9834setenv({name}, {val}) *setenv()*
9835 Set environment variable {name} to {val}. Example: >
9836 call setenv('HOME', '/home/myhome')
9837
9838< When {val} is |v:null| the environment variable is deleted.
9839 See also |expr-env|.
9840
9841 Can also be used as a |method|, the base is passed as the
9842 second argument: >
9843 GetPath()->setenv('PATH')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009844<
9845 Return type: |Number|
9846
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009847
9848setfperm({fname}, {mode}) *setfperm()* *chmod*
9849 Set the file permissions for {fname} to {mode}.
9850 {mode} must be a string with 9 characters. It is of the form
9851 "rwxrwxrwx", where each group of "rwx" flags represent, in
9852 turn, the permissions of the owner of the file, the group the
9853 file belongs to, and other users. A '-' character means the
9854 permission is off, any other character means on. Multi-byte
9855 characters are not supported.
9856
9857 For example "rw-r-----" means read-write for the user,
9858 readable by the group, not accessible by others. "xx-x-----"
9859 would do the same thing.
9860
9861 Returns non-zero for success, zero for failure.
9862
9863 Can also be used as a |method|: >
9864 GetFilename()->setfperm(mode)
9865<
9866 To read permissions see |getfperm()|.
9867
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009868 Return type: |Number|
9869
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009870
9871setline({lnum}, {text}) *setline()*
9872 Set line {lnum} of the current buffer to {text}. To insert
9873 lines use |append()|. To set lines in another buffer use
Christian Brabandt946f61c2024-06-17 13:17:58 +02009874 |setbufline()|.
h-east52e7cc22024-07-28 17:03:29 +02009875 Any text properties in {lnum} are cleared. See
9876 |text-prop-cleared|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009877
9878 {lnum} is used like with |getline()|.
9879 When {lnum} is just below the last line the {text} will be
9880 added below the last line.
9881 {text} can be any type or a List of any type, each item is
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00009882 converted to a String. When {text} is an empty List then
9883 nothing is changed and FALSE is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009884
9885 If this succeeds, FALSE is returned. If this fails (most likely
9886 because {lnum} is invalid) TRUE is returned.
9887 In |Vim9| script an error is given if {lnum} is invalid.
9888
9889 Example: >
9890 :call setline(5, strftime("%c"))
9891
9892< When {text} is a |List| then line {lnum} and following lines
9893 will be set to the items in the list. Example: >
9894 :call setline(5, ['aaa', 'bbb', 'ccc'])
9895< This is equivalent to: >
9896 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
9897 : call setline(n, l)
9898 :endfor
9899
9900< Note: The '[ and '] marks are not set.
9901
9902 Can also be used as a |method|, the base is passed as the
9903 second argument: >
9904 GetText()->setline(lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009905<
9906 Return type: |Number|
9907
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009908
9909setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
9910 Create or replace or add to the location list for window {nr}.
9911 {nr} can be the window number or the |window-ID|.
9912 When {nr} is zero the current window is used.
9913
9914 For a location list window, the displayed location list is
9915 modified. For an invalid window number {nr}, -1 is returned.
9916 Otherwise, same as |setqflist()|.
9917 Also see |location-list|.
9918
9919 For {action} see |setqflist-action|.
9920
9921 If the optional {what} dictionary argument is supplied, then
9922 only the items listed in {what} are set. Refer to |setqflist()|
9923 for the list of supported keys in {what}.
9924
9925 Can also be used as a |method|, the base is passed as the
9926 second argument: >
9927 GetLoclist()->setloclist(winnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009928<
9929 Return type: |Number|
9930
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009931
9932setmatches({list} [, {win}]) *setmatches()*
9933 Restores a list of matches saved by |getmatches()| for the
9934 current window. Returns 0 if successful, otherwise -1. All
9935 current matches are cleared before the list is restored. See
9936 example for |getmatches()|.
9937 If {win} is specified, use the window with this number or
9938 window ID instead of the current window.
9939
9940 Can also be used as a |method|: >
9941 GetMatches()->setmatches()
9942<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009943 Return type: |Number|
9944
9945
9946setpos({expr}, {list}) *setpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009947 Set the position for String {expr}. Possible values:
9948 . the cursor
9949 'x mark x
9950
9951 {list} must be a |List| with four or five numbers:
9952 [bufnum, lnum, col, off]
9953 [bufnum, lnum, col, off, curswant]
9954
9955 "bufnum" is the buffer number. Zero can be used for the
9956 current buffer. When setting an uppercase mark "bufnum" is
9957 used for the mark position. For other marks it specifies the
9958 buffer to set the mark in. You can use the |bufnr()| function
9959 to turn a file name into a buffer number.
9960 For setting the cursor and the ' mark "bufnum" is ignored,
9961 since these are associated with a window, not a buffer.
9962 Does not change the jumplist.
9963
9964 "lnum" and "col" are the position in the buffer. The first
9965 column is 1. Use a zero "lnum" to delete a mark. If "col" is
9966 smaller than 1 then 1 is used. To use the character count
9967 instead of the byte count, use |setcharpos()|.
9968
9969 The "off" number is only used when 'virtualedit' is set. Then
9970 it is the offset in screen columns from the start of the
9971 character. E.g., a position within a <Tab> or after the last
9972 character.
9973
9974 The "curswant" number is only used when setting the cursor
9975 position. It sets the preferred column for when moving the
9976 cursor vertically. When the "curswant" number is missing the
9977 preferred column is not set. When it is present and setting a
9978 mark position it is not used.
9979
9980 Note that for '< and '> changing the line number may result in
9981 the marks to be effectively be swapped, so that '< is always
9982 before '>.
9983
9984 Returns 0 when the position could be set, -1 otherwise.
9985 An error message is given if {expr} is invalid.
9986
9987 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
9988
9989 This does not restore the preferred column for moving
9990 vertically; if you set the cursor position with this, |j| and
9991 |k| motions will jump to previous columns! Use |cursor()| to
9992 also set the preferred column. Also see the "curswant" key in
9993 |winrestview()|.
9994
9995 Can also be used as a |method|: >
9996 GetPosition()->setpos('.')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009997<
9998 Return type: |Number|
9999
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010000
10001setqflist({list} [, {action} [, {what}]]) *setqflist()*
10002 Create or replace or add to the quickfix list.
10003
10004 If the optional {what} dictionary argument is supplied, then
10005 only the items listed in {what} are set. The first {list}
10006 argument is ignored. See below for the supported items in
10007 {what}.
10008 *setqflist-what*
10009 When {what} is not present, the items in {list} are used. Each
10010 item must be a dictionary. Non-dictionary items in {list} are
10011 ignored. Each dictionary item can contain the following
10012 entries:
10013
10014 bufnr buffer number; must be the number of a valid
10015 buffer
10016 filename name of a file; only used when "bufnr" is not
10017 present or it is invalid.
10018 module name of a module; if given it will be used in
10019 quickfix error window instead of the filename.
10020 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +000010021 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010022 pattern search pattern used to locate the error
10023 col column number
10024 vcol when non-zero: "col" is visual column
10025 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +000010026 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010027 nr error number
10028 text description of the error
10029 type single-character error type, 'E', 'W', etc.
10030 valid recognized error message
Tom Praschanca6ac992023-08-11 23:26:12 +020010031 user_data custom data associated with the item, can be
10032 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010033
10034 The "col", "vcol", "nr", "type" and "text" entries are
10035 optional. Either "lnum" or "pattern" entry can be used to
10036 locate a matching error line.
10037 If the "filename" and "bufnr" entries are not present or
10038 neither the "lnum" or "pattern" entries are present, then the
10039 item will not be handled as an error line.
10040 If both "pattern" and "lnum" are present then "pattern" will
10041 be used.
10042 If the "valid" entry is not supplied, then the valid flag is
10043 set when "bufnr" is a valid buffer or "filename" exists.
10044 If you supply an empty {list}, the quickfix list will be
10045 cleared.
10046 Note that the list is not exactly the same as what
10047 |getqflist()| returns.
10048
10049 {action} values: *setqflist-action* *E927*
10050 'a' The items from {list} are added to the existing
10051 quickfix list. If there is no existing list, then a
10052 new list is created.
10053
10054 'r' The items from the current quickfix list are replaced
10055 with the items from {list}. This can also be used to
10056 clear the list: >
10057 :call setqflist([], 'r')
10058<
Jeremy Fleischman27fbf6e2024-10-14 20:46:27 +020010059 'u' Like 'r', but tries to preserve the current selection
10060 in the quickfix list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010061 'f' All the quickfix lists in the quickfix stack are
10062 freed.
10063
10064 If {action} is not present or is set to ' ', then a new list
10065 is created. The new quickfix list is added after the current
10066 quickfix list in the stack and all the following lists are
10067 freed. To add a new quickfix list at the end of the stack,
10068 set "nr" in {what} to "$".
10069
10070 The following items can be specified in dictionary {what}:
10071 context quickfix list context. See |quickfix-context|
10072 efm errorformat to use when parsing text from
10073 "lines". If this is not present, then the
10074 'errorformat' option value is used.
10075 See |quickfix-parse|
10076 id quickfix list identifier |quickfix-ID|
10077 idx index of the current entry in the quickfix
10078 list specified by 'id' or 'nr'. If set to '$',
10079 then the last entry in the list is set as the
10080 current entry. See |quickfix-index|
10081 items list of quickfix entries. Same as the {list}
10082 argument.
10083 lines use 'errorformat' to parse a list of lines and
10084 add the resulting entries to the quickfix list
10085 {nr} or {id}. Only a |List| value is supported.
10086 See |quickfix-parse|
10087 nr list number in the quickfix stack; zero
10088 means the current quickfix list and "$" means
10089 the last quickfix list.
10090 quickfixtextfunc
10091 function to get the text to display in the
10092 quickfix window. The value can be the name of
10093 a function or a funcref or a lambda. Refer to
10094 |quickfix-window-function| for an explanation
10095 of how to write the function and an example.
10096 title quickfix list title text. See |quickfix-title|
10097 Unsupported keys in {what} are ignored.
10098 If the "nr" item is not present, then the current quickfix list
10099 is modified. When creating a new quickfix list, "nr" can be
10100 set to a value one greater than the quickfix stack size.
10101 When modifying a quickfix list, to guarantee that the correct
10102 list is modified, "id" should be used instead of "nr" to
10103 specify the list.
10104
10105 Examples (See also |setqflist-examples|): >
10106 :call setqflist([], 'r', {'title': 'My search'})
10107 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
10108 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
10109<
10110 Returns zero for success, -1 for failure.
10111
10112 This function can be used to create a quickfix list
10113 independent of the 'errorformat' setting. Use a command like
10114 `:cc 1` to jump to the first position.
10115
10116 Can also be used as a |method|, the base is passed as the
10117 second argument: >
10118 GetErrorlist()->setqflist()
10119<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010120 Return type: |Number|
10121
10122
10123setreg({regname}, {value} [, {options}]) *setreg()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010124 Set the register {regname} to {value}.
10125 If {regname} is "" or "@", the unnamed register '"' is used.
10126 The {regname} argument is a string. In |Vim9-script|
10127 {regname} must be one character.
10128
10129 {value} may be any value returned by |getreg()| or
10130 |getreginfo()|, including a |List| or |Dict|.
10131 If {options} contains "a" or {regname} is upper case,
10132 then the value is appended.
10133
10134 {options} can also contain a register type specification:
10135 "c" or "v" |characterwise| mode
10136 "l" or "V" |linewise| mode
10137 "b" or "<CTRL-V>" |blockwise-visual| mode
10138 If a number immediately follows "b" or "<CTRL-V>" then this is
10139 used as the width of the selection - if it is not specified
10140 then the width of the block is set to the number of characters
10141 in the longest line (counting a <Tab> as 1 character).
10142
10143 If {options} contains no register settings, then the default
10144 is to use character mode unless {value} ends in a <NL> for
10145 string {value} and linewise mode for list {value}. Blockwise
10146 mode is never selected automatically.
10147 Returns zero for success, non-zero for failure.
10148
10149 *E883*
10150 Note: you may not use |List| containing more than one item to
10151 set search and expression registers. Lists containing no
10152 items act like empty strings.
10153
10154 Examples: >
10155 :call setreg(v:register, @*)
10156 :call setreg('*', @%, 'ac')
10157 :call setreg('a', "1\n2\n3", 'b5')
10158 :call setreg('"', { 'points_to': 'a'})
10159
10160< This example shows using the functions to save and restore a
10161 register: >
10162 :let var_a = getreginfo()
10163 :call setreg('a', var_a)
10164< or: >
10165 :let var_a = getreg('a', 1, 1)
10166 :let var_amode = getregtype('a')
10167 ....
10168 :call setreg('a', var_a, var_amode)
10169< Note: you may not reliably restore register value
10170 without using the third argument to |getreg()| as without it
10171 newlines are represented as newlines AND Nul bytes are
10172 represented as newlines as well, see |NL-used-for-Nul|.
10173
10174 You can also change the type of a register by appending
10175 nothing: >
10176 :call setreg('a', '', 'al')
10177
10178< Can also be used as a |method|, the base is passed as the
10179 second argument: >
10180 GetText()->setreg('a')
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010181<
10182 Return type: |Number|
10183
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010184
10185settabvar({tabnr}, {varname}, {val}) *settabvar()*
10186 Set tab-local variable {varname} to {val} in tab page {tabnr}.
10187 |t:var|
10188 The {varname} argument is a string.
10189 Note that autocommands are blocked, side effects may not be
10190 triggered, e.g. when setting 'filetype'.
10191 Note that the variable name without "t:" must be used.
10192 Tabs are numbered starting with one.
10193 This function is not available in the |sandbox|.
10194
10195 Can also be used as a |method|, the base is passed as the
10196 third argument: >
10197 GetValue()->settabvar(tab, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010198<
10199 Return type: |Number|
10200
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010201
10202settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
10203 Set option or local variable {varname} in window {winnr} to
10204 {val}.
10205 Tabs are numbered starting with one. For the current tabpage
10206 use |setwinvar()|.
10207 {winnr} can be the window number or the |window-ID|.
10208 When {winnr} is zero the current window is used.
10209 Note that autocommands are blocked, side effects may not be
10210 triggered, e.g. when setting 'filetype' or 'syntax'.
10211 This also works for a global or local buffer option, but it
10212 doesn't work for a global or local buffer variable.
10213 For a local buffer option the global value is unchanged.
10214 Note that the variable name without "w:" must be used.
10215 Examples: >
10216 :call settabwinvar(1, 1, "&list", 0)
10217 :call settabwinvar(3, 2, "myvar", "foobar")
10218< This function is not available in the |sandbox|.
10219
10220 Can also be used as a |method|, the base is passed as the
10221 fourth argument: >
10222 GetValue()->settabwinvar(tab, winnr, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010223<
10224 Return type: |Number|
10225
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010226
10227settagstack({nr}, {dict} [, {action}]) *settagstack()*
10228 Modify the tag stack of the window {nr} using {dict}.
10229 {nr} can be the window number or the |window-ID|.
10230
10231 For a list of supported items in {dict}, refer to
10232 |gettagstack()|. "curidx" takes effect before changing the tag
10233 stack.
10234 *E962*
10235 How the tag stack is modified depends on the {action}
10236 argument:
10237 - If {action} is not present or is set to 'r', then the tag
10238 stack is replaced.
10239 - If {action} is set to 'a', then new entries from {dict} are
10240 pushed (added) onto the tag stack.
10241 - If {action} is set to 't', then all the entries from the
10242 current entry in the tag stack or "curidx" in {dict} are
10243 removed and then new entries are pushed to the stack.
10244
10245 The current index is set to one after the length of the tag
10246 stack after the modification.
10247
10248 Returns zero for success, -1 for failure.
10249
10250 Examples (for more examples see |tagstack-examples|):
10251 Empty the tag stack of window 3: >
10252 call settagstack(3, {'items' : []})
10253
10254< Save and restore the tag stack: >
10255 let stack = gettagstack(1003)
10256 " do something else
10257 call settagstack(1003, stack)
10258 unlet stack
10259<
10260 Can also be used as a |method|, the base is passed as the
10261 second argument: >
10262 GetStack()->settagstack(winnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010263<
10264 Return type: |Number|
10265
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010266
10267setwinvar({winnr}, {varname}, {val}) *setwinvar()*
10268 Like |settabwinvar()| for the current tab page.
10269 Examples: >
10270 :call setwinvar(1, "&list", 0)
10271 :call setwinvar(2, "myvar", "foobar")
10272
10273< Can also be used as a |method|, the base is passed as the
10274 third argument: >
10275 GetValue()->setwinvar(winnr, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010276<
10277 Return type: |Number|
10278
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010279
10280sha256({string}) *sha256()*
10281 Returns a String with 64 hex characters, which is the SHA256
10282 checksum of {string}.
10283
10284 Can also be used as a |method|: >
10285 GetText()->sha256()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010286<
10287 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010288
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010289 {only available when compiled with the |+cryptv| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010290
10291shellescape({string} [, {special}]) *shellescape()*
10292 Escape {string} for use as a shell command argument.
10293 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +000010294 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010295 in single quotes and will double up all internal single
10296 quotes.
10297 On MS-Windows, when 'shellslash' is not set, it will enclose
10298 {string} in double quotes and double all double quotes within
10299 {string}.
10300 Otherwise it will enclose {string} in single quotes and
10301 replace all "'" with "'\''".
10302
Enno5faeb602024-05-15 21:54:19 +020010303 The {special} argument adds additional escaping of keywords
10304 used in Vim commands. When it is not omitted and a non-zero
K.Takatac0e038b2024-05-16 12:39:01 +090010305 number or a non-empty String (|non-zero-arg|), then special
10306 items such as "!", "%", "#" and "<cword>" (as listed in
10307 |expand()|) will be preceded by a backslash.
Enno5faeb602024-05-15 21:54:19 +020010308 This backslash will be removed again by the |:!| command.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010309
10310 The "!" character will be escaped (again with a |non-zero-arg|
10311 {special}) when 'shell' contains "csh" in the tail. That is
10312 because for csh and tcsh "!" is used for history replacement
10313 even when inside single quotes.
10314
10315 With a |non-zero-arg| {special} the <NL> character is also
10316 escaped. When 'shell' containing "csh" in the tail it's
10317 escaped a second time.
10318
10319 The "\" character will be escaped when 'shell' contains "fish"
10320 in the tail. That is because for fish "\" is used as an escape
10321 character inside single quotes.
10322
10323 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010324 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010325< This results in a directory listing for the file under the
10326 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010327 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010328< See also |::S|.
10329
10330 Can also be used as a |method|: >
10331 GetCommand()->shellescape()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010332<
10333 Return type: |String|
10334
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010335
10336shiftwidth([{col}]) *shiftwidth()*
10337 Returns the effective value of 'shiftwidth'. This is the
10338 'shiftwidth' value unless it is zero, in which case it is the
10339 'tabstop' value. This function was introduced with patch
10340 7.3.694 in 2012, everybody should have it by now (however it
10341 did not allow for the optional {col} argument until 8.1.542).
10342
10343 When there is one argument {col} this is used as column number
10344 for which to return the 'shiftwidth' value. This matters for the
10345 'vartabstop' feature. If the 'vartabstop' setting is enabled and
10346 no {col} argument is given, column 1 will be assumed.
10347
10348 Can also be used as a |method|: >
10349 GetColumn()->shiftwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010350<
10351 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010352
10353sign_ functions are documented here: |sign-functions-details|
10354
10355
10356simplify({filename}) *simplify()*
10357 Simplify the file name as much as possible without changing
10358 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
10359 Unix) are not resolved. If the first path component in
10360 {filename} designates the current directory, this will be
10361 valid for the result as well. A trailing path separator is
10362 not removed either. On Unix "//path" is unchanged, but
10363 "///path" is simplified to "/path" (this follows the Posix
10364 standard).
10365 Example: >
10366 simplify("./dir/.././/file/") == "./file/"
10367< Note: The combination "dir/.." is only removed if "dir" is
10368 a searchable directory or does not exist. On Unix, it is also
10369 removed when "dir" is a symbolic link within the same
10370 directory. In order to resolve all the involved symbolic
10371 links before simplifying the path name, use |resolve()|.
10372
10373 Can also be used as a |method|: >
10374 GetName()->simplify()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010375<
10376 Return type: |String|
10377
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010378
10379sin({expr}) *sin()*
10380 Return the sine of {expr}, measured in radians, as a |Float|.
10381 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010382 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010383 Examples: >
10384 :echo sin(100)
10385< -0.506366 >
10386 :echo sin(-4.01)
10387< 0.763301
10388
10389 Can also be used as a |method|: >
10390 Compute()->sin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010391<
10392 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010393
10394
10395sinh({expr}) *sinh()*
10396 Return the hyperbolic sine of {expr} as a |Float| in the range
10397 [-inf, inf].
10398 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010399 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010400 Examples: >
10401 :echo sinh(0.5)
10402< 0.521095 >
10403 :echo sinh(-0.9)
10404< -1.026517
10405
10406 Can also be used as a |method|: >
10407 Compute()->sinh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010408<
10409 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010410
10411
10412slice({expr}, {start} [, {end}]) *slice()*
10413 Similar to using a |slice| "expr[start : end]", but "end" is
10414 used exclusive. And for a string the indexes are used as
10415 character indexes instead of byte indexes, like in
zeertzjqad387692024-03-23 08:23:48 +010010416 |vim9script|. Also, composing characters are treated as a
10417 part of the preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010418 When {end} is omitted the slice continues to the last item.
10419 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010420 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010421
10422 Can also be used as a |method|: >
10423 GetList()->slice(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010424<
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +010010425 Return type: list<{type}> or tuple<{type}>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010426
10427
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010428sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010429 Sort the items in {list} in-place. Returns {list}.
10430
10431 If you want a list to remain unmodified make a copy first: >
10432 :let sortedlist = sort(copy(mylist))
10433
Bram Moolenaar2d8ed022022-05-21 13:08:16 +010010434< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010435 string representation of each item to sort on. Numbers sort
10436 after Strings, |Lists| after Numbers. For sorting text in the
10437 current buffer use |:sort|.
10438
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010439 When {how} is given and it is 'i' then case is ignored.
10440 In legacy script, for backwards compatibility, the value one
10441 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010442
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010443 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010444 locale is used for ordering. Implementation details: strcoll()
10445 is used to compare strings. See |:language| check or set the
10446 collation locale. |v:collate| can also be used to check the
10447 current locale. Sorting using the locale typically ignores
10448 case. Example: >
10449 " ö is sorted similarly to o with English locale.
10450 :language collate en_US.UTF8
10451 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10452< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
10453>
10454 " ö is sorted after z with Swedish locale.
10455 :language collate sv_SE.UTF8
10456 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10457< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
10458 This does not work properly on Mac.
10459
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010460 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010461 sorted numerical (Implementation detail: this uses the
Bram Moolenaarbe19d782023-03-09 22:06:49 +000010462 strtod() function to parse numbers. Strings, Lists, Dicts and
10463 Funcrefs will be considered as being 0). Note that this won't
10464 sort a list of strings with numbers!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010465
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010466 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010467 sorted numerical. This is like 'n' but a string containing
10468 digits will be used as the number they represent.
10469
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010470 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010471 sorted numerical. All values must be a Number or a Float.
10472
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010473 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010474 is called to compare items. The function is invoked with two
10475 items as argument and must return zero if they are equal, 1 or
10476 bigger if the first one sorts after the second one, -1 or
10477 smaller if the first one sorts before the second one.
10478
10479 {dict} is for functions with the "dict" attribute. It will be
10480 used to set the local variable "self". |Dictionary-function|
10481
10482 The sort is stable, items which compare equal (as number or as
10483 string) will keep their relative position. E.g., when sorting
10484 on numbers, text strings will sort next to each other, in the
10485 same order as they were originally.
10486
10487 Can also be used as a |method|: >
10488 mylist->sort()
10489
10490< Also see |uniq()|.
10491
10492 Example: >
10493 func MyCompare(i1, i2)
10494 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
10495 endfunc
10496 eval mylist->sort("MyCompare")
10497< A shorter compare version for this specific simple case, which
10498 ignores overflow: >
10499 func MyCompare(i1, i2)
10500 return a:i1 - a:i2
10501 endfunc
10502< For a simple expression you can use a lambda: >
10503 eval mylist->sort({i1, i2 -> i1 - i2})
10504<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010505 Return type: list<{type}>
10506
10507
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010508sound_clear() *sound_clear()*
10509 Stop playing all sounds.
10510
10511 On some Linux systems you may need the libcanberra-pulse
10512 package, otherwise sound may not stop.
10513
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010514 Return type: |Number|
10515
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010516 {only available when compiled with the |+sound| feature}
10517
10518 *sound_playevent()*
10519sound_playevent({name} [, {callback}])
10520 Play a sound identified by {name}. Which event names are
10521 supported depends on the system. Often the XDG sound names
10522 are used. On Ubuntu they may be found in
10523 /usr/share/sounds/freedesktop/stereo. Example: >
10524 call sound_playevent('bell')
10525< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
10526 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
10527 SystemStart, SystemWelcome, etc.
Yee Cheng Chin4314e4f2022-10-08 13:50:05 +010010528 On macOS, {name} refers to files located in
10529 /System/Library/Sounds (e.g. "Tink"). It will also work for
10530 custom installed sounds in folders like ~/Library/Sounds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010531
10532 When {callback} is specified it is invoked when the sound is
10533 finished. The first argument is the sound ID, the second
10534 argument is the status:
10535 0 sound was played to the end
10536 1 sound was interrupted
10537 2 error occurred after sound started
10538 Example: >
10539 func Callback(id, status)
10540 echomsg "sound " .. a:id .. " finished with " .. a:status
10541 endfunc
10542 call sound_playevent('bell', 'Callback')
10543
10544< MS-Windows: {callback} doesn't work for this function.
10545
10546 Returns the sound ID, which can be passed to `sound_stop()`.
10547 Returns zero if the sound could not be played.
10548
10549 Can also be used as a |method|: >
10550 GetSoundName()->sound_playevent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010551<
10552 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010553
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010554 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010555
10556 *sound_playfile()*
10557sound_playfile({path} [, {callback}])
10558 Like `sound_playevent()` but play sound file {path}. {path}
10559 must be a full path. On Ubuntu you may find files to play
10560 with this command: >
10561 :!find /usr/share/sounds -type f | grep -v index.theme
10562
10563< Can also be used as a |method|: >
10564 GetSoundPath()->sound_playfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010565<
10566 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010567
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010568 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010569
10570
10571sound_stop({id}) *sound_stop()*
10572 Stop playing sound {id}. {id} must be previously returned by
10573 `sound_playevent()` or `sound_playfile()`.
10574
10575 On some Linux systems you may need the libcanberra-pulse
10576 package, otherwise sound may not stop.
10577
10578 On MS-Windows, this does not work for event sound started by
10579 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
10580
10581 Can also be used as a |method|: >
10582 soundid->sound_stop()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010583<
10584 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010585
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010586 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010587
10588 *soundfold()*
10589soundfold({word})
10590 Return the sound-folded equivalent of {word}. Uses the first
10591 language in 'spelllang' for the current window that supports
10592 soundfolding. 'spell' must be set. When no sound folding is
10593 possible the {word} is returned unmodified.
10594 This can be used for making spelling suggestions. Note that
10595 the method can be quite slow.
10596
10597 Can also be used as a |method|: >
10598 GetWord()->soundfold()
10599<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010600 Return type: |String|
10601
10602
10603spellbadword([{sentence}]) *spellbadword()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010604 Without argument: The result is the badly spelled word under
10605 or after the cursor. The cursor is moved to the start of the
10606 bad word. When no bad word is found in the cursor line the
10607 result is an empty string and the cursor doesn't move.
10608
10609 With argument: The result is the first word in {sentence} that
10610 is badly spelled. If there are no spelling mistakes the
10611 result is an empty string.
10612
10613 The return value is a list with two items:
10614 - The badly spelled word or an empty string.
10615 - The type of the spelling error:
10616 "bad" spelling mistake
10617 "rare" rare word
10618 "local" word only valid in another region
10619 "caps" word should start with Capital
10620 Example: >
10621 echo spellbadword("the quik brown fox")
10622< ['quik', 'bad'] ~
10623
10624 The spelling information for the current window and the value
10625 of 'spelllang' are used.
10626
10627 Can also be used as a |method|: >
10628 GetText()->spellbadword()
10629<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010630 Return type: list<string>
10631
10632
10633spellsuggest({word} [, {max} [, {capital}]]) *spellsuggest()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010634 Return a |List| with spelling suggestions to replace {word}.
10635 When {max} is given up to this number of suggestions are
10636 returned. Otherwise up to 25 suggestions are returned.
10637
10638 When the {capital} argument is given and it's non-zero only
10639 suggestions with a leading capital will be given. Use this
10640 after a match with 'spellcapcheck'.
10641
10642 {word} can be a badly spelled word followed by other text.
10643 This allows for joining two words that were split. The
10644 suggestions also include the following text, thus you can
10645 replace a line.
10646
10647 {word} may also be a good word. Similar words will then be
10648 returned. {word} itself is not included in the suggestions,
10649 although it may appear capitalized.
10650
10651 The spelling information for the current window is used. The
10652 values of 'spelllang' and 'spellsuggest' are used.
10653
10654 Can also be used as a |method|: >
10655 GetWord()->spellsuggest()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010656<
10657 Return type: list<string> or list<any>
10658
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010659
10660split({string} [, {pattern} [, {keepempty}]]) *split()*
10661 Make a |List| out of {string}. When {pattern} is omitted or
Shane Harperc1b39842024-07-17 19:40:40 +020010662 empty each white space separated sequence of characters
10663 becomes an item.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010664 Otherwise the string is split where {pattern} matches,
10665 removing the matched characters. 'ignorecase' is not used
10666 here, add \c to ignore case. |/\c|
10667 When the first or last item is empty it is omitted, unless the
10668 {keepempty} argument is given and it's non-zero.
10669 Other empty items are kept when {pattern} matches at least one
10670 character or when {keepempty} is non-zero.
10671 Example: >
10672 :let words = split(getline('.'), '\W\+')
10673< To split a string in individual characters: >
10674 :for c in split(mystring, '\zs')
10675< If you want to keep the separator you can also use '\zs' at
10676 the end of the pattern: >
10677 :echo split('abc:def:ghi', ':\zs')
10678< ['abc:', 'def:', 'ghi'] ~
10679 Splitting a table where the first element can be empty: >
10680 :let items = split(line, ':', 1)
10681< The opposite function is |join()|.
10682
10683 Can also be used as a |method|: >
10684 GetString()->split()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010685<
10686 Return type: list<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010687
10688sqrt({expr}) *sqrt()*
10689 Return the non-negative square root of Float {expr} as a
10690 |Float|.
10691 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010692 is negative the result is NaN (Not a Number). Returns 0.0 if
10693 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010694 Examples: >
10695 :echo sqrt(100)
10696< 10.0 >
10697 :echo sqrt(-4.01)
10698< nan
10699 "nan" may be different, it depends on system libraries.
10700
10701 Can also be used as a |method|: >
10702 Compute()->sqrt()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010703<
10704 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010705
10706
10707srand([{expr}]) *srand()*
10708 Initialize seed used by |rand()|:
10709 - If {expr} is not given, seed values are initialized by
10710 reading from /dev/urandom, if possible, or using time(NULL)
10711 a.k.a. epoch time otherwise; this only has second accuracy.
10712 - If {expr} is given it must be a Number. It is used to
10713 initialize the seed values. This is useful for testing or
10714 when a predictable sequence is intended.
10715
10716 Examples: >
10717 :let seed = srand()
10718 :let seed = srand(userinput)
10719 :echo rand(seed)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010720<
10721 Return type: list<number>
10722
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010723
10724state([{what}]) *state()*
10725 Return a string which contains characters indicating the
10726 current state. Mostly useful in callbacks that want to do
10727 work that may not always be safe. Roughly this works like:
10728 - callback uses state() to check if work is safe to do.
10729 Yes: then do it right away.
10730 No: add to work queue and add a |SafeState| and/or
10731 |SafeStateAgain| autocommand (|SafeState| triggers at
10732 toplevel, |SafeStateAgain| triggers after handling
10733 messages and callbacks).
10734 - When SafeState or SafeStateAgain is triggered and executes
10735 your autocommand, check with `state()` if the work can be
10736 done now, and if yes remove it from the queue and execute.
10737 Remove the autocommand if the queue is now empty.
10738 Also see |mode()|.
10739
10740 When {what} is given only characters in this string will be
10741 added. E.g, this checks if the screen has scrolled: >
10742 if state('s') == ''
10743 " screen has not scrolled
10744<
10745 These characters indicate the state, generally indicating that
10746 something is busy:
10747 m halfway a mapping, :normal command, feedkeys() or
10748 stuffed command
10749 o operator pending, e.g. after |d|
10750 a Insert mode autocomplete active
10751 x executing an autocommand
10752 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
10753 ch_readraw() when reading json
10754 S not triggering SafeState or SafeStateAgain, e.g. after
10755 |f| or a count
10756 c callback invoked, including timer (repeats for
10757 recursiveness up to "ccc")
10758 s screen has scrolled for messages
10759
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010760 Return type: |String|
10761
10762
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010763str2blob({list} [, {options}]) *str2blob()*
10764 Return a Blob by converting the characters in the List of
10765 strings in {list} into bytes.
10766
10767 A <NL> byte is added to the blob after each list item. A
10768 newline character in the string is translated into a <NUL>
10769 byte in the blob.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010770
10771 If {options} is not supplied, the current 'encoding' value is
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010772 used to convert the characters into bytes.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010773
10774 The argument {options} is a |Dict| and supports the following
10775 items:
Bakudankunb3854bf2025-02-23 20:29:21 +010010776 encoding Convert the characters using this encoding
10777 before making the Blob.
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010778 The value is a |String|. See |encoding-names|
10779 for the supported values.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010780
10781 An error is given and an empty blob is returned if the
10782 character encoding fails.
10783
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010784 Returns an empty Blob if {list} is empty.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010785
10786 See also |blob2str()|
10787
10788 Examples: >
Hirohito Higashi932a5352025-03-23 10:20:20 +010010789 str2blob(["ab"]) returns 0z6162
10790 str2blob(["«»"]) returns 0zC2ABC2BB
10791 str2blob(["a\nb"]) returns 0z610062
10792 str2blob(["a","b"]) returns 0z610A62
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010793 str2blob(["«»"], {'encoding': 'latin1'}) returns 0zABBB
Hirohito Higashi932a5352025-03-23 10:20:20 +010010794 str2blob(readfile('myfile.txt'))
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010795<
10796 Can also be used as a |method|: >
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010797 GetListOfStrings()->str2blob()
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010798<
10799 Return type: |Blob|
10800
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010801str2float({string} [, {quoted}]) *str2float()*
10802 Convert String {string} to a Float. This mostly works the
10803 same as when using a floating point number in an expression,
10804 see |floating-point-format|. But it's a bit more permissive.
10805 E.g., "1e40" is accepted, while in an expression you need to
10806 write "1.0e40". The hexadecimal form "0x123" is also
10807 accepted, but not others, like binary or octal.
10808 When {quoted} is present and non-zero then embedded single
10809 quotes before the dot are ignored, thus "1'000.0" is a
10810 thousand.
10811 Text after the number is silently ignored.
10812 The decimal point is always '.', no matter what the locale is
10813 set to. A comma ends the number: "12,345.67" is converted to
10814 12.0. You can strip out thousands separators with
10815 |substitute()|: >
10816 let f = str2float(substitute(text, ',', '', 'g'))
10817<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010818 Returns 0.0 if the conversion fails.
10819
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010820 Can also be used as a |method|: >
10821 let f = text->substitute(',', '', 'g')->str2float()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010822<
10823 Return type: |Float|
10824
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010825
10826str2list({string} [, {utf8}]) *str2list()*
10827 Return a list containing the number values which represent
10828 each character in String {string}. Examples: >
10829 str2list(" ") returns [32]
10830 str2list("ABC") returns [65, 66, 67]
10831< |list2str()| does the opposite.
10832
10833 When {utf8} is omitted or zero, the current 'encoding' is used.
10834 When {utf8} is TRUE, always treat the String as UTF-8
10835 characters. With UTF-8 composing characters are handled
10836 properly: >
10837 str2list("á") returns [97, 769]
10838
10839< Can also be used as a |method|: >
10840 GetString()->str2list()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010841<
10842 Return type: list<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010843
10844
10845str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
10846 Convert string {string} to a number.
10847 {base} is the conversion base, it can be 2, 8, 10 or 16.
10848 When {quoted} is present and non-zero then embedded single
10849 quotes are ignored, thus "1'000'000" is a million.
10850
10851 When {base} is omitted base 10 is used. This also means that
10852 a leading zero doesn't cause octal conversion to be used, as
10853 with the default String to Number conversion. Example: >
10854 let nr = str2nr('0123')
10855<
10856 When {base} is 16 a leading "0x" or "0X" is ignored. With a
10857 different base the result will be zero. Similarly, when
10858 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
10859 {base} is 2 a leading "0b" or "0B" is ignored.
10860 Text after the number is silently ignored.
10861
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010862 Returns 0 if {string} is empty or on error.
10863
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010864 Can also be used as a |method|: >
10865 GetText()->str2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010866<
10867 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010868
10869
10870strcharlen({string}) *strcharlen()*
10871 The result is a Number, which is the number of characters
10872 in String {string}. Composing characters are ignored.
10873 |strchars()| can count the number of characters, counting
10874 composing characters separately.
10875
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010876 Returns 0 if {string} is empty or on error.
10877
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010878 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10879
10880 Can also be used as a |method|: >
10881 GetText()->strcharlen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010882<
10883 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010884
10885
10886strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
10887 Like |strpart()| but using character index and length instead
10888 of byte index and length.
10889 When {skipcc} is omitted or zero, composing characters are
10890 counted separately.
zeertzjqad387692024-03-23 08:23:48 +010010891 When {skipcc} set to 1, composing characters are treated as a
10892 part of the preceding base character, similar to |slice()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010893 When a character index is used where a character does not
10894 exist it is omitted and counted as one character. For
10895 example: >
10896 strcharpart('abc', -1, 2)
10897< results in 'a'.
10898
Bram Moolenaard592deb2022-06-17 15:42:40 +010010899 Returns an empty string on error.
10900
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010901 Can also be used as a |method|: >
10902 GetText()->strcharpart(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010903<
10904 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010905
10906
10907strchars({string} [, {skipcc}]) *strchars()*
10908 The result is a Number, which is the number of characters
10909 in String {string}.
10910 When {skipcc} is omitted or zero, composing characters are
10911 counted separately.
zeertzjqad387692024-03-23 08:23:48 +010010912 When {skipcc} set to 1, composing characters are ignored.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010913 |strcharlen()| always does this.
10914
Bram Moolenaard592deb2022-06-17 15:42:40 +010010915 Returns zero on error.
10916
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010917 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10918
10919 {skipcc} is only available after 7.4.755. For backward
10920 compatibility, you can define a wrapper function: >
10921 if has("patch-7.4.755")
10922 function s:strchars(str, skipcc)
10923 return strchars(a:str, a:skipcc)
10924 endfunction
10925 else
10926 function s:strchars(str, skipcc)
10927 if a:skipcc
10928 return strlen(substitute(a:str, ".", "x", "g"))
10929 else
10930 return strchars(a:str)
10931 endif
10932 endfunction
10933 endif
10934<
10935 Can also be used as a |method|: >
10936 GetText()->strchars()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010937<
10938 Return type: |Number|
10939
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010940
10941strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
10942 The result is a Number, which is the number of display cells
10943 String {string} occupies on the screen when it starts at {col}
10944 (first column is zero). When {col} is omitted zero is used.
10945 Otherwise it is the screen column where to start. This
10946 matters for Tab characters.
10947 The option settings of the current window are used. This
10948 matters for anything that's displayed differently, such as
10949 'tabstop' and 'display'.
10950 When {string} contains characters with East Asian Width Class
10951 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010952 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010953 Also see |strlen()|, |strwidth()| and |strchars()|.
10954
10955 Can also be used as a |method|: >
10956 GetText()->strdisplaywidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010957<
10958 Return type: |Number|
10959
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010960
10961strftime({format} [, {time}]) *strftime()*
10962 The result is a String, which is a formatted date and time, as
10963 specified by the {format} string. The given {time} is used,
10964 or the current time if no time is given. The accepted
10965 {format} depends on your system, thus this is not portable!
10966 See the manual page of the C function strftime() for the
10967 format. The maximum length of the result is 80 characters.
10968 See also |localtime()|, |getftime()| and |strptime()|.
10969 The language can be changed with the |:language| command.
10970 Examples: >
10971 :echo strftime("%c") Sun Apr 27 11:49:23 1997
10972 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
10973 :echo strftime("%y%m%d %T") 970427 11:53:55
10974 :echo strftime("%H:%M") 11:55
10975 :echo strftime("%c", getftime("file.c"))
10976 Show mod time of file.c.
10977< Not available on all systems. To check use: >
10978 :if exists("*strftime")
10979
10980< Can also be used as a |method|: >
10981 GetFormat()->strftime()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010982<
10983 Return type: |String|
10984
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010985
10986strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +010010987 Get a Number corresponding to the character at {index} in
10988 {str}. This uses a zero-based character index, not a byte
10989 index. Composing characters are considered separate
10990 characters here. Use |nr2char()| to convert the Number to a
10991 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010992 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010993 Also see |strcharpart()| and |strchars()|.
10994
10995 Can also be used as a |method|: >
10996 GetText()->strgetchar(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010997<
10998 Return type: |Number|
10999
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011000
11001stridx({haystack}, {needle} [, {start}]) *stridx()*
11002 The result is a Number, which gives the byte index in
11003 {haystack} of the first occurrence of the String {needle}.
11004 If {start} is specified, the search starts at index {start}.
11005 This can be used to find a second match: >
11006 :let colon1 = stridx(line, ":")
11007 :let colon2 = stridx(line, ":", colon1 + 1)
11008< The search is done case-sensitive.
11009 For pattern searches use |match()|.
11010 -1 is returned if the {needle} does not occur in {haystack}.
11011 See also |strridx()|.
11012 Examples: >
11013 :echo stridx("An Example", "Example") 3
11014 :echo stridx("Starting point", "Start") 0
11015 :echo stridx("Starting point", "start") -1
11016< *strstr()* *strchr()*
11017 stridx() works similar to the C function strstr(). When used
11018 with a single character it works similar to strchr().
11019
11020 Can also be used as a |method|: >
11021 GetHaystack()->stridx(needle)
11022<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011023 Return type: |Number|
11024
11025
11026string({expr}) *string()*
11027 Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011028 Float, String, Blob or a composition of them, then the result
11029 can be parsed back with |eval()|.
11030 {expr} type result ~
11031 String 'string' (single quotes are doubled)
11032 Number 123
11033 Float 123.123456 or 1.123456e8
11034 Funcref function('name')
11035 Blob 0z00112233.44556677.8899
11036 List [item, item]
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +010011037 Tuple (item, item)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011038 Dictionary {key: value, key: value}
Bram Moolenaarf1dcd142022-12-31 15:30:45 +000011039 Class class SomeName
11040 Object object of SomeName {lnum: 1, col: 3}
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010011041 Enum enum EnumName
Yegappan Lakshmanan3cf121e2024-03-31 18:45:35 +020011042 EnumValue enum name.value {name: str, ordinal: nr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011043
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +010011044 When a |List|, |Tuple| or |Dictionary| has a recursive
11045 reference it is replaced by "[...]" or "(...)" or "{...}".
11046 Using eval() on the result will then fail.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011047
mityu7f0bba22024-03-29 10:14:41 +010011048 For an object, invokes the string() method to get a textual
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +010011049 representation of the object. If the method is not present,
mityu7f0bba22024-03-29 10:14:41 +010011050 then the default representation is used. |object-string()|
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +010011051
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011052 Can also be used as a |method|: >
11053 mylist->string()
11054
11055< Also see |strtrans()|.
11056
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011057 Return type: |String|
11058
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011059
11060strlen({string}) *strlen()*
11061 The result is a Number, which is the length of the String
11062 {string} in bytes.
11063 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011064 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011065 If you want to count the number of multibyte characters use
11066 |strchars()|.
11067 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
11068
11069 Can also be used as a |method|: >
11070 GetString()->strlen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011071<
11072 Return type: |Number|
11073
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011074
11075strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
11076 The result is a String, which is part of {src}, starting from
11077 byte {start}, with the byte length {len}.
11078 When {chars} is present and TRUE then {len} is the number of
11079 characters positions (composing characters are not counted
11080 separately, thus "1" means one base character and any
11081 following composing characters).
11082 To count {start} as characters instead of bytes use
11083 |strcharpart()|.
11084
11085 When bytes are selected which do not exist, this doesn't
11086 result in an error, the bytes are simply omitted.
11087 If {len} is missing, the copy continues from {start} till the
11088 end of the {src}. >
11089 strpart("abcdefg", 3, 2) == "de"
11090 strpart("abcdefg", -2, 4) == "ab"
11091 strpart("abcdefg", 5, 4) == "fg"
11092 strpart("abcdefg", 3) == "defg"
11093
11094< Note: To get the first character, {start} must be 0. For
11095 example, to get the character under the cursor: >
11096 strpart(getline("."), col(".") - 1, 1, v:true)
11097<
Bram Moolenaard592deb2022-06-17 15:42:40 +010011098 Returns an empty string on error.
11099
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011100 Can also be used as a |method|: >
11101 GetText()->strpart(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011102<
11103 Return type: |String|
11104
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011105
11106strptime({format}, {timestring}) *strptime()*
11107 The result is a Number, which is a unix timestamp representing
11108 the date and time in {timestring}, which is expected to match
11109 the format specified in {format}.
11110
11111 The accepted {format} depends on your system, thus this is not
11112 portable! See the manual page of the C function strptime()
11113 for the format. Especially avoid "%c". The value of $TZ also
11114 matters.
11115
11116 If the {timestring} cannot be parsed with {format} zero is
11117 returned. If you do not know the format of {timestring} you
11118 can try different {format} values until you get a non-zero
11119 result.
11120
11121 See also |strftime()|.
11122 Examples: >
11123 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
11124< 862156163 >
11125 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
11126< Sun Apr 27 11:53:55 1997 >
11127 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
11128< Sun Apr 27 12:53:55 1997
11129
11130 Can also be used as a |method|: >
11131 GetFormat()->strptime(timestring)
11132<
11133 Not available on all systems. To check use: >
11134 :if exists("*strptime")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011135<
11136 Return type: |Number|
11137
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011138
11139strridx({haystack}, {needle} [, {start}]) *strridx()*
11140 The result is a Number, which gives the byte index in
11141 {haystack} of the last occurrence of the String {needle}.
11142 When {start} is specified, matches beyond this index are
11143 ignored. This can be used to find a match before a previous
11144 match: >
11145 :let lastcomma = strridx(line, ",")
11146 :let comma2 = strridx(line, ",", lastcomma - 1)
11147< The search is done case-sensitive.
11148 For pattern searches use |match()|.
11149 -1 is returned if the {needle} does not occur in {haystack}.
11150 If the {needle} is empty the length of {haystack} is returned.
11151 See also |stridx()|. Examples: >
11152 :echo strridx("an angry armadillo", "an") 3
11153< *strrchr()*
11154 When used with a single character it works similar to the C
11155 function strrchr().
11156
11157 Can also be used as a |method|: >
11158 GetHaystack()->strridx(needle)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011159<
11160 Return type: |Number|
11161
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011162
11163strtrans({string}) *strtrans()*
11164 The result is a String, which is {string} with all unprintable
11165 characters translated into printable characters |'isprint'|.
11166 Like they are shown in a window. Example: >
11167 echo strtrans(@a)
11168< This displays a newline in register a as "^@" instead of
11169 starting a new line.
11170
Bram Moolenaard592deb2022-06-17 15:42:40 +010011171 Returns an empty string on error.
11172
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011173 Can also be used as a |method|: >
11174 GetString()->strtrans()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011175<
11176 Return type: |String|
11177
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011178
Christian Brabandt67672ef2023-04-24 21:09:54 +010011179strutf16len({string} [, {countcc}]) *strutf16len()*
11180 The result is a Number, which is the number of UTF-16 code
11181 units in String {string} (after converting it to UTF-16).
11182
11183 When {countcc} is TRUE, composing characters are counted
11184 separately.
11185 When {countcc} is omitted or FALSE, composing characters are
11186 ignored.
11187
11188 Returns zero on error.
11189
11190 Also see |strlen()| and |strcharlen()|.
11191 Examples: >
11192 echo strutf16len('a') returns 1
11193 echo strutf16len('©') returns 1
11194 echo strutf16len('😊') returns 2
11195 echo strutf16len('ą́') returns 1
11196 echo strutf16len('ą́', v:true) returns 3
a5ob7r790f9a82023-09-25 06:05:47 +090011197<
Christian Brabandt67672ef2023-04-24 21:09:54 +010011198 Can also be used as a |method|: >
11199 GetText()->strutf16len()
11200<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011201 Return type: |Number|
11202
11203
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011204strwidth({string}) *strwidth()*
11205 The result is a Number, which is the number of display cells
11206 String {string} occupies. A Tab character is counted as one
11207 cell, alternatively use |strdisplaywidth()|.
11208 When {string} contains characters with East Asian Width Class
11209 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011210 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011211 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
11212
11213 Can also be used as a |method|: >
11214 GetString()->strwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011215<
11216 Return type: |Number|
11217
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011218
11219submatch({nr} [, {list}]) *submatch()* *E935*
11220 Only for an expression in a |:substitute| command or
11221 substitute() function.
11222 Returns the {nr}'th submatch of the matched text. When {nr}
11223 is 0 the whole matched text is returned.
11224 Note that a NL in the string can stand for a line break of a
11225 multi-line match or a NUL character in the text.
11226 Also see |sub-replace-expression|.
11227
11228 If {list} is present and non-zero then submatch() returns
11229 a list of strings, similar to |getline()| with two arguments.
11230 NL characters in the text represent NUL characters in the
11231 text.
11232 Only returns more than one item for |:substitute|, inside
11233 |substitute()| this list will always contain one or zero
11234 items, since there are no real line breaks.
11235
11236 When substitute() is used recursively only the submatches in
11237 the current (deepest) call can be obtained.
11238
Bram Moolenaard592deb2022-06-17 15:42:40 +010011239 Returns an empty string or list on error.
11240
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011241 Examples: >
11242 :s/\d\+/\=submatch(0) + 1/
11243 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
11244< This finds the first number in the line and adds one to it.
11245 A line break is included as a newline character.
11246
11247 Can also be used as a |method|: >
11248 GetNr()->submatch()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011249<
11250 Return type: |String| or list<string> depending on {list}
11251
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011252
11253substitute({string}, {pat}, {sub}, {flags}) *substitute()*
11254 The result is a String, which is a copy of {string}, in which
11255 the first match of {pat} is replaced with {sub}.
11256 When {flags} is "g", all matches of {pat} in {string} are
11257 replaced. Otherwise {flags} should be "".
11258
11259 This works like the ":substitute" command (without any flags).
11260 But the matching with {pat} is always done like the 'magic'
11261 option is set and 'cpoptions' is empty (to make scripts
11262 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
11263 if you want to ignore or match case and ignore 'ignorecase'.
11264 'smartcase' is not used. See |string-match| for how {pat} is
11265 used.
11266
11267 A "~" in {sub} is not replaced with the previous {sub}.
11268 Note that some codes in {sub} have a special meaning
11269 |sub-replace-special|. For example, to replace something with
11270 "\n" (two characters), use "\\\\n" or '\\n'.
11271
11272 When {pat} does not match in {string}, {string} is returned
11273 unmodified.
11274
11275 Example: >
11276 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
11277< This removes the last component of the 'path' option. >
11278 :echo substitute("testing", ".*", "\\U\\0", "")
11279< results in "TESTING".
11280
11281 When {sub} starts with "\=", the remainder is interpreted as
11282 an expression. See |sub-replace-expression|. Example: >
11283 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011284 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011285
11286< When {sub} is a Funcref that function is called, with one
11287 optional argument. Example: >
11288 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
11289< The optional argument is a list which contains the whole
11290 matched string and up to nine submatches, like what
11291 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011292 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011293
Bram Moolenaard592deb2022-06-17 15:42:40 +010011294< Returns an empty string on error.
11295
11296 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011297 GetString()->substitute(pat, sub, flags)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011298<
11299 Return type: |String|
11300
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011301
Bram Moolenaarc216a7a2022-12-05 13:50:55 +000011302swapfilelist() *swapfilelist()*
11303 Returns a list of swap file names, like what "vim -r" shows.
11304 See the |-r| command argument. The 'directory' option is used
11305 for the directories to inspect. If you only want to get a
11306 list of swap files in the current directory then temporarily
11307 set 'directory' to a dot: >
11308 let save_dir = &directory
11309 let &directory = '.'
11310 let swapfiles = swapfilelist()
11311 let &directory = save_dir
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011312<
11313 Return type: list<string>
11314
Bram Moolenaarc216a7a2022-12-05 13:50:55 +000011315
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011316swapinfo({fname}) *swapinfo()*
11317 The result is a dictionary, which holds information about the
11318 swapfile {fname}. The available fields are:
11319 version Vim version
11320 user user name
11321 host host name
11322 fname original file name
11323 pid PID of the Vim process that created the swap
11324 file
11325 mtime last modification time in seconds
11326 inode Optional: INODE number of the file
11327 dirty 1 if file was modified, 0 if not
11328 Note that "user" and "host" are truncated to at most 39 bytes.
11329 In case of failure an "error" item is added with the reason:
11330 Cannot open file: file not found or in accessible
11331 Cannot read file: cannot read first block
11332 Not a swap file: does not contain correct block ID
11333 Magic number mismatch: Info in first block is invalid
11334
11335 Can also be used as a |method|: >
11336 GetFilename()->swapinfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011337<
11338 Return type: dict<any> or dict<string>
11339
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011340
11341swapname({buf}) *swapname()*
11342 The result is the swap file path of the buffer {expr}.
11343 For the use of {buf}, see |bufname()| above.
11344 If buffer {buf} is the current buffer, the result is equal to
11345 |:swapname| (unless there is no swap file).
11346 If buffer {buf} has no swap file, returns an empty string.
11347
11348 Can also be used as a |method|: >
11349 GetBufname()->swapname()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011350<
11351 Return type: |String|
11352
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011353
11354synID({lnum}, {col}, {trans}) *synID()*
11355 The result is a Number, which is the syntax ID at the position
11356 {lnum} and {col} in the current window.
11357 The syntax ID can be used with |synIDattr()| and
11358 |synIDtrans()| to obtain syntax information about text.
11359
11360 {col} is 1 for the leftmost column, {lnum} is 1 for the first
11361 line. 'synmaxcol' applies, in a longer line zero is returned.
11362 Note that when the position is after the last character,
11363 that's where the cursor can be in Insert mode, synID() returns
11364 zero. {lnum} is used like with |getline()|.
11365
11366 When {trans} is |TRUE|, transparent items are reduced to the
11367 item that they reveal. This is useful when wanting to know
11368 the effective color. When {trans} is |FALSE|, the transparent
11369 item is returned. This is useful when wanting to know which
11370 syntax item is effective (e.g. inside parens).
11371 Warning: This function can be very slow. Best speed is
11372 obtained by going through the file in forward direction.
11373
Bram Moolenaard592deb2022-06-17 15:42:40 +010011374 Returns zero on error.
11375
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011376 Example (echoes the name of the syntax item under the cursor): >
11377 :echo synIDattr(synID(line("."), col("."), 1), "name")
11378<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011379 Return type: |Number|
11380
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011381
11382synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
11383 The result is a String, which is the {what} attribute of
11384 syntax ID {synID}. This can be used to obtain information
11385 about a syntax item.
11386 {mode} can be "gui", "cterm" or "term", to get the attributes
11387 for that mode. When {mode} is omitted, or an invalid value is
11388 used, the attributes for the currently active highlighting are
11389 used (GUI, cterm or term).
11390 Use synIDtrans() to follow linked highlight groups.
11391 {what} result
11392 "name" the name of the syntax item
11393 "fg" foreground color (GUI: color name used to set
11394 the color, cterm: color number as a string,
11395 term: empty string)
11396 "bg" background color (as with "fg")
11397 "font" font name (only available in the GUI)
11398 |highlight-font|
11399 "sp" special color for the GUI (as with "fg")
11400 |highlight-guisp|
11401 "ul" underline color for cterm: number as a string
11402 "fg#" like "fg", but for the GUI and the GUI is
11403 running the name in "#RRGGBB" form
11404 "bg#" like "fg#" for "bg"
11405 "sp#" like "fg#" for "sp"
11406 "bold" "1" if bold
11407 "italic" "1" if italic
11408 "reverse" "1" if reverse
11409 "inverse" "1" if inverse (= reverse)
11410 "standout" "1" if standout
11411 "underline" "1" if underlined
11412 "undercurl" "1" if undercurled
11413 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +010011414 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011415
Bram Moolenaard592deb2022-06-17 15:42:40 +010011416 Returns an empty string on error.
11417
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011418 Example (echoes the color of the syntax item under the
11419 cursor): >
11420 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
11421<
11422 Can also be used as a |method|: >
11423 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011424<
11425 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011426
11427
11428synIDtrans({synID}) *synIDtrans()*
11429 The result is a Number, which is the translated syntax ID of
11430 {synID}. This is the syntax group ID of what is being used to
11431 highlight the character. Highlight links given with
11432 ":highlight link" are followed.
11433
Bram Moolenaard592deb2022-06-17 15:42:40 +010011434 Returns zero on error.
11435
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011436 Can also be used as a |method|: >
11437 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011438<
11439 Return type: |Number|
11440
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011441
11442synconcealed({lnum}, {col}) *synconcealed()*
11443 The result is a |List| with currently three items:
11444 1. The first item in the list is 0 if the character at the
11445 position {lnum} and {col} is not part of a concealable
11446 region, 1 if it is. {lnum} is used like with |getline()|.
11447 2. The second item in the list is a string. If the first item
11448 is 1, the second item contains the text which will be
11449 displayed in place of the concealed text, depending on the
11450 current setting of 'conceallevel' and 'listchars'.
11451 3. The third and final item in the list is a number
11452 representing the specific syntax region matched in the
11453 line. When the character is not concealed the value is
11454 zero. This allows detection of the beginning of a new
11455 concealable region if there are two consecutive regions
11456 with the same replacement character. For an example, if
11457 the text is "123456" and both "23" and "45" are concealed
11458 and replaced by the character "X", then:
11459 call returns ~
11460 synconcealed(lnum, 1) [0, '', 0]
11461 synconcealed(lnum, 2) [1, 'X', 1]
11462 synconcealed(lnum, 3) [1, 'X', 1]
11463 synconcealed(lnum, 4) [1, 'X', 2]
11464 synconcealed(lnum, 5) [1, 'X', 2]
11465 synconcealed(lnum, 6) [0, '', 0]
11466
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020011467 Note: Doesn't consider |matchadd()| highlighting items,
11468 since syntax and matching highlighting are two different
11469 mechanisms |syntax-vs-match|.
h-east52e7cc22024-07-28 17:03:29 +020011470
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011471 Return type: list<any>
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020011472
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011473
11474synstack({lnum}, {col}) *synstack()*
11475 Return a |List|, which is the stack of syntax items at the
11476 position {lnum} and {col} in the current window. {lnum} is
11477 used like with |getline()|. Each item in the List is an ID
11478 like what |synID()| returns.
11479 The first item in the List is the outer region, following are
11480 items contained in that one. The last one is what |synID()|
11481 returns, unless not the whole item is highlighted or it is a
11482 transparent item.
11483 This function is useful for debugging a syntax file.
11484 Example that shows the syntax stack under the cursor: >
11485 for id in synstack(line("."), col("."))
11486 echo synIDattr(id, "name")
11487 endfor
11488< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +010011489 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011490 character in a line and the first column in an empty line are
11491 valid positions.
11492
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011493 Return type: list<number> or list<any>
11494
11495
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011496system({expr} [, {input}]) *system()* *E677*
11497 Get the output of the shell command {expr} as a |String|. See
11498 |systemlist()| to get the output as a |List|.
11499
11500 When {input} is given and is a |String| this string is written
11501 to a file and passed as stdin to the command. The string is
11502 written as-is, you need to take care of using the correct line
11503 separators yourself.
11504 If {input} is given and is a |List| it is written to the file
11505 in a way |writefile()| does with {binary} set to "b" (i.e.
11506 with a newline between each list item with newlines inside
11507 list items converted to NULs).
11508 When {input} is given and is a number that is a valid id for
11509 an existing buffer then the content of the buffer is written
11510 to the file line by line, each line terminated by a NL and
11511 NULs characters where the text has a NL.
11512
11513 Pipes are not used, the 'shelltemp' option is not used.
11514
11515 When prepended by |:silent| the terminal will not be set to
11516 cooked mode. This is meant to be used for commands that do
11517 not need the user to type. It avoids stray characters showing
11518 up on the screen which require |CTRL-L| to remove. >
11519 :silent let f = system('ls *.vim')
11520<
11521 Note: Use |shellescape()| or |::S| with |expand()| or
11522 |fnamemodify()| to escape special characters in a command
11523 argument. Newlines in {expr} may cause the command to fail.
11524 The characters in 'shellquote' and 'shellxquote' may also
11525 cause trouble.
11526 This is not to be used for interactive commands.
11527
11528 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011529 :let files = system('ls ' .. shellescape(expand('%:h')))
11530 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011531
11532< To make the result more system-independent, the shell output
11533 is filtered to replace <CR> with <NL> for Macintosh, and
11534 <CR><NL> with <NL> for DOS-like systems.
11535 To avoid the string being truncated at a NUL, all NUL
11536 characters are replaced with SOH (0x01).
11537
11538 The command executed is constructed using several options:
11539 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
11540 ({tmp} is an automatically generated file name).
11541 For Unix, braces are put around {expr} to allow for
11542 concatenated commands.
11543
11544 The command will be executed in "cooked" mode, so that a
11545 CTRL-C will interrupt the command (on Unix at least).
11546
11547 The resulting error code can be found in |v:shell_error|.
11548 This function will fail in |restricted-mode|.
11549
11550 Note that any wrong value in the options mentioned above may
11551 make the function fail. It has also been reported to fail
11552 when using a security agent application.
11553 Unlike ":!cmd" there is no automatic check for changed files.
11554 Use |:checktime| to force a check.
11555
11556 Can also be used as a |method|: >
11557 :echo GetCmd()->system()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011558<
11559 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011560
11561
11562systemlist({expr} [, {input}]) *systemlist()*
11563 Same as |system()|, but returns a |List| with lines (parts of
11564 output separated by NL) with NULs transformed into NLs. Output
11565 is the same as |readfile()| will output with {binary} argument
11566 set to "b", except that there is no extra empty item when the
11567 result ends in a NL.
11568 Note that on MS-Windows you may get trailing CR characters.
11569
11570 To see the difference between "echo hello" and "echo -n hello"
11571 use |system()| and |split()|: >
11572 echo system('echo hello')->split('\n', 1)
11573<
11574 Returns an empty string on error.
11575
11576 Can also be used as a |method|: >
11577 :echo GetCmd()->systemlist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011578<
11579 Return type: list<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011580
11581
11582tabpagebuflist([{arg}]) *tabpagebuflist()*
11583 The result is a |List|, where each item is the number of the
11584 buffer associated with each window in the current tab page.
11585 {arg} specifies the number of the tab page to be used. When
11586 omitted the current tab page is used.
11587 When {arg} is invalid the number zero is returned.
11588 To get a list of all buffers in all tabs use this: >
11589 let buflist = []
11590 for i in range(tabpagenr('$'))
11591 call extend(buflist, tabpagebuflist(i + 1))
11592 endfor
11593< Note that a buffer may appear in more than one window.
11594
11595 Can also be used as a |method|: >
11596 GetTabpage()->tabpagebuflist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011597<
11598 Return type: list<number>
11599
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011600
11601tabpagenr([{arg}]) *tabpagenr()*
11602 The result is a Number, which is the number of the current
11603 tab page. The first tab page has number 1.
11604
11605 The optional argument {arg} supports the following values:
11606 $ the number of the last tab page (the tab page
11607 count).
11608 # the number of the last accessed tab page
11609 (where |g<Tab>| goes to). if there is no
11610 previous tab page 0 is returned.
11611 The number can be used with the |:tab| command.
11612
Bram Moolenaard592deb2022-06-17 15:42:40 +010011613 Returns zero on error.
11614
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011615 Return type: |Number|
11616
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011617
11618tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
11619 Like |winnr()| but for tab page {tabarg}.
11620 {tabarg} specifies the number of tab page to be used.
11621 {arg} is used like with |winnr()|:
11622 - When omitted the current window number is returned. This is
11623 the window which will be used when going to this tab page.
11624 - When "$" the number of windows is returned.
11625 - When "#" the previous window nr is returned.
11626 Useful examples: >
11627 tabpagewinnr(1) " current window of tab page 1
11628 tabpagewinnr(4, '$') " number of windows in tab page 4
11629< When {tabarg} is invalid zero is returned.
11630
11631 Can also be used as a |method|: >
11632 GetTabpage()->tabpagewinnr()
11633<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011634 Return type: |Number|
11635
11636
11637tagfiles() *tagfiles()*
11638 Returns a |List| with the file names used to search for tags
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011639 for the current buffer. This is the 'tags' option expanded.
11640
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011641 Return type: list<string> or list<any>
11642
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011643
11644taglist({expr} [, {filename}]) *taglist()*
11645 Returns a |List| of tags matching the regular expression {expr}.
11646
11647 If {filename} is passed it is used to prioritize the results
11648 in the same way that |:tselect| does. See |tag-priority|.
11649 {filename} should be the full path of the file.
11650
11651 Each list item is a dictionary with at least the following
11652 entries:
11653 name Name of the tag.
11654 filename Name of the file where the tag is
11655 defined. It is either relative to the
11656 current directory or a full path.
11657 cmd Ex command used to locate the tag in
11658 the file.
11659 kind Type of the tag. The value for this
11660 entry depends on the language specific
11661 kind values. Only available when
11662 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +000011663 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011664 static A file specific tag. Refer to
11665 |static-tag| for more information.
11666 More entries may be present, depending on the content of the
11667 tags file: access, implementation, inherits and signature.
11668 Refer to the ctags documentation for information about these
11669 fields. For C code the fields "struct", "class" and "enum"
11670 may appear, they give the name of the entity the tag is
11671 contained in.
11672
11673 The ex-command "cmd" can be either an ex search pattern, a
11674 line number or a line number followed by a byte number.
11675
11676 If there are no matching tags, then an empty list is returned.
11677
11678 To get an exact tag match, the anchors '^' and '$' should be
11679 used in {expr}. This also make the function work faster.
11680 Refer to |tag-regexp| for more information about the tag
11681 search regular expression pattern.
11682
11683 Refer to |'tags'| for information about how the tags file is
11684 located by Vim. Refer to |tags-file-format| for the format of
11685 the tags file generated by the different ctags tools.
11686
11687 Can also be used as a |method|: >
11688 GetTagpattern()->taglist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011689<
11690 Return type: list<dict<any>> or list<any>
11691
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011692
11693tan({expr}) *tan()*
11694 Return the tangent of {expr}, measured in radians, as a |Float|
11695 in the range [-inf, inf].
11696 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011697 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011698 Examples: >
11699 :echo tan(10)
11700< 0.648361 >
11701 :echo tan(-4.01)
11702< -1.181502
11703
11704 Can also be used as a |method|: >
11705 Compute()->tan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011706<
11707 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011708
11709
11710tanh({expr}) *tanh()*
11711 Return the hyperbolic tangent of {expr} as a |Float| in the
11712 range [-1, 1].
11713 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011714 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011715 Examples: >
11716 :echo tanh(0.5)
11717< 0.462117 >
11718 :echo tanh(-1)
11719< -0.761594
11720
11721 Can also be used as a |method|: >
11722 Compute()->tanh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011723<
11724 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011725
11726
11727tempname() *tempname()* *temp-file-name*
11728 The result is a String, which is the name of a file that
11729 doesn't exist. It can be used for a temporary file. The name
11730 is different for at least 26 consecutive calls. Example: >
11731 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011732 :exe "redir > " .. tmpfile
Christian Brabandt5cf53012024-05-18 10:13:11 +020011733< For Unix, the file will be in a private directory |tempfile|
11734 that is recursively deleted when Vim exits, on other systems
11735 temporary files are not cleaned up automatically on exit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011736 For MS-Windows forward slashes are used when the 'shellslash'
11737 option is set, or when 'shellcmdflag' starts with '-' and
11738 'shell' does not contain powershell or pwsh.
11739
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011740 Return type: |String|
11741
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011742
11743term_ functions are documented here: |terminal-function-details|
11744
11745
11746terminalprops() *terminalprops()*
11747 Returns a |Dictionary| with properties of the terminal that Vim
11748 detected from the response to |t_RV| request. See
11749 |v:termresponse| for the response itself. If |v:termresponse|
11750 is empty most values here will be 'u' for unknown.
11751 cursor_style whether sending |t_RS| works **
11752 cursor_blink_mode whether sending |t_RC| works **
11753 underline_rgb whether |t_8u| works **
11754 mouse mouse type supported
Bram Moolenaar4bc85f22022-10-21 14:17:24 +010011755 kitty whether Kitty terminal was detected
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011756
11757 ** value 'u' for unknown, 'y' for yes, 'n' for no
11758
11759 If the |+termresponse| feature is missing then the result is
11760 an empty dictionary.
11761
11762 If "cursor_style" is 'y' then |t_RS| will be sent to request the
11763 current cursor style.
11764 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
11765 request the cursor blink status.
11766 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
11767 is not empty, Vim will detect the working of sending |t_RS|
11768 and |t_RC| on startup.
11769
11770 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
11771 This avoids sending it to xterm, which would clear the colors.
11772
11773 For "mouse" the value 'u' is unknown
11774
11775 Also see:
11776 - 'ambiwidth' - detected by using |t_u7|.
11777 - |v:termstyleresp| and |v:termblinkresp| for the response to
11778 |t_RS| and |t_RC|.
11779
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011780 Return type: dict<string>
11781
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011782
11783test_ functions are documented here: |test-functions-details|
11784
11785
11786 *timer_info()*
11787timer_info([{id}])
11788 Return a list with information about timers.
11789 When {id} is given only information about this timer is
11790 returned. When timer {id} does not exist an empty list is
11791 returned.
11792 When {id} is omitted information about all timers is returned.
11793
11794 For each timer the information is stored in a |Dictionary| with
11795 these items:
11796 "id" the timer ID
11797 "time" time the timer was started with
11798 "remaining" time until the timer fires
11799 "repeat" number of times the timer will still fire;
11800 -1 means forever
11801 "callback" the callback
11802 "paused" 1 if the timer is paused, 0 otherwise
11803
11804 Can also be used as a |method|: >
11805 GetTimer()->timer_info()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011806<
11807 Return type: list<dict<any>> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011808
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011809 {only available when compiled with the |+timers| feature}
11810
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011811
11812timer_pause({timer}, {paused}) *timer_pause()*
11813 Pause or unpause a timer. A paused timer does not invoke its
11814 callback when its time expires. Unpausing a timer may cause
11815 the callback to be invoked almost immediately if enough time
11816 has passed.
11817
11818 Pausing a timer is useful to avoid the callback to be called
11819 for a short time.
11820
11821 If {paused} evaluates to a non-zero Number or a non-empty
11822 String, then the timer is paused, otherwise it is unpaused.
11823 See |non-zero-arg|.
11824
11825 Can also be used as a |method|: >
11826 GetTimer()->timer_pause(1)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011827<
11828 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011829
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011830 {only available when compiled with the |+timers| feature}
11831
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011832
11833 *timer_start()* *timer* *timers*
11834timer_start({time}, {callback} [, {options}])
11835 Create a timer and return the timer ID.
11836
11837 {time} is the waiting time in milliseconds. This is the
11838 minimum time before invoking the callback. When the system is
11839 busy or Vim is not waiting for input the time will be longer.
Bram Moolenaardd60c362023-02-27 15:49:53 +000011840 Zero can be used to execute the callback when Vim is back in
11841 the main loop.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011842
11843 {callback} is the function to call. It can be the name of a
11844 function or a |Funcref|. It is called with one argument, which
11845 is the timer ID. The callback is only invoked when Vim is
11846 waiting for input.
11847 If you want to show a message look at |popup_notification()|
11848 to avoid interfering with what the user is doing.
11849
11850 {options} is a dictionary. Supported entries:
11851 "repeat" Number of times to repeat calling the
11852 callback. -1 means forever. When not present
11853 the callback will be called once.
11854 If the timer causes an error three times in a
11855 row the repeat is cancelled. This avoids that
11856 Vim becomes unusable because of all the error
11857 messages.
11858
Bram Moolenaard592deb2022-06-17 15:42:40 +010011859 Returns -1 on error.
11860
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011861 Example: >
11862 func MyHandler(timer)
11863 echo 'Handler called'
11864 endfunc
11865 let timer = timer_start(500, 'MyHandler',
11866 \ {'repeat': 3})
11867< This will invoke MyHandler() three times at 500 msec
11868 intervals.
11869
11870 Can also be used as a |method|: >
11871 GetMsec()->timer_start(callback)
11872
11873< Not available in the |sandbox|.
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011874
11875 Return type: |Number|
11876
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011877 {only available when compiled with the |+timers| feature}
11878
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011879
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011880timer_stop({timer}) *timer_stop()*
11881 Stop a timer. The timer callback will no longer be invoked.
11882 {timer} is an ID returned by timer_start(), thus it must be a
11883 Number. If {timer} does not exist there is no error.
11884
11885 Can also be used as a |method|: >
11886 GetTimer()->timer_stop()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011887<
11888 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011889
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011890 {only available when compiled with the |+timers| feature}
11891
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011892
11893timer_stopall() *timer_stopall()*
11894 Stop all timers. The timer callbacks will no longer be
11895 invoked. Useful if a timer is misbehaving. If there are no
11896 timers there is no error.
11897
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011898 Return type: |Number|
11899
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011900 {only available when compiled with the |+timers| feature}
11901
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011902
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011903tolower({expr}) *tolower()*
11904 The result is a copy of the String given, with all uppercase
11905 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010011906 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011907
11908 Can also be used as a |method|: >
11909 GetText()->tolower()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011910<
11911 Return type: |String|
11912
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011913
11914toupper({expr}) *toupper()*
11915 The result is a copy of the String given, with all lowercase
11916 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010011917 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011918
11919 Can also be used as a |method|: >
11920 GetText()->toupper()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011921<
11922 Return type: |String|
11923
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011924
11925tr({src}, {fromstr}, {tostr}) *tr()*
11926 The result is a copy of the {src} string with all characters
11927 which appear in {fromstr} replaced by the character in that
11928 position in the {tostr} string. Thus the first character in
11929 {fromstr} is translated into the first character in {tostr}
11930 and so on. Exactly like the unix "tr" command.
11931 This code also deals with multibyte characters properly.
11932
Bram Moolenaard592deb2022-06-17 15:42:40 +010011933 Returns an empty string on error.
11934
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011935 Examples: >
11936 echo tr("hello there", "ht", "HT")
11937< returns "Hello THere" >
11938 echo tr("<blob>", "<>", "{}")
11939< returns "{blob}"
11940
11941 Can also be used as a |method|: >
11942 GetText()->tr(from, to)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011943<
11944 Return type: |String|
11945
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011946
11947trim({text} [, {mask} [, {dir}]]) *trim()*
11948 Return {text} as a String where any character in {mask} is
11949 removed from the beginning and/or end of {text}.
11950
Illia Bobyr80799172023-10-17 18:00:50 +020011951 If {mask} is not given, or is an empty string, {mask} is all
11952 characters up to 0x20, which includes Tab, space, NL and CR,
11953 plus the non-breaking space character 0xa0.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011954
11955 The optional {dir} argument specifies where to remove the
11956 characters:
11957 0 remove from the beginning and end of {text}
11958 1 remove only at the beginning of {text}
11959 2 remove only at the end of {text}
11960 When omitted both ends are trimmed.
11961
11962 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011963 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011964
11965 Examples: >
11966 echo trim(" some text ")
11967< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011968 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011969< returns "RESERVE_TAIL" >
11970 echo trim("rm<Xrm<>X>rrm", "rm<>")
11971< returns "Xrm<>X" (characters in the middle are not removed) >
11972 echo trim(" vim ", " ", 2)
11973< returns " vim"
11974
11975 Can also be used as a |method|: >
11976 GetText()->trim()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011977<
11978 Return type: |String|
11979
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011980
11981trunc({expr}) *trunc()*
11982 Return the largest integral value with magnitude less than or
11983 equal to {expr} as a |Float| (truncate towards zero).
11984 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011985 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011986 Examples: >
11987 echo trunc(1.456)
11988< 1.0 >
11989 echo trunc(-5.456)
11990< -5.0 >
11991 echo trunc(4.0)
11992< 4.0
11993
11994 Can also be used as a |method|: >
11995 Compute()->trunc()
11996<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011997 Return type: |Float|
11998
11999
Yegappan Lakshmanan1c2f4752025-03-30 15:37:24 +020012000tuple2list({tuple}) *tuple2list()*
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +010012001 Create a List from a shallow copy of the tuple items.
12002 Examples: >
12003 tuple2list((1, 2, 3)) returns [1, 2, 3]
12004< |list2tuple()| does the opposite.
12005
12006 This function doesn't recursively convert all the Tuple items
12007 in {tuple} to a List. Note that the items are identical
12008 between the list and the tuple, changing an item changes the
12009 contents of both the tuple and the list.
12010
12011 Returns an empty list on error.
12012
12013 Can also be used as a |method|: >
12014 GetTuple()->tuple2list()
12015<
12016 Return type: list<{type}> (depending on the given |Tuple|)
12017
12018
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012019 *type()*
12020type({expr}) The result is a Number representing the type of {expr}.
12021 Instead of using the number directly, it is better to use the
12022 v:t_ variable that has the value:
12023 Number: 0 |v:t_number|
12024 String: 1 |v:t_string|
12025 Funcref: 2 |v:t_func|
12026 List: 3 |v:t_list|
12027 Dictionary: 4 |v:t_dict|
12028 Float: 5 |v:t_float|
12029 Boolean: 6 |v:t_bool| (v:false and v:true)
12030 None: 7 |v:t_none| (v:null and v:none)
12031 Job: 8 |v:t_job|
12032 Channel: 9 |v:t_channel|
12033 Blob: 10 |v:t_blob|
h_east596a9f22023-11-21 21:24:23 +090012034 Class: 12 |v:t_class|
12035 Object: 13 |v:t_object|
Yegappan Lakshmanan2a71b542023-12-14 20:03:03 +010012036 Typealias: 14 |v:t_typealias|
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010012037 Enum: 15 |v:t_enum|
12038 EnumValue: 16 |v:t_enumvalue|
Yegappan Lakshmanan9cb865e2025-03-23 16:42:16 +010012039 Tuple: 17 |v:t_tuple|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012040 For backward compatibility, this method can be used: >
12041 :if type(myvar) == type(0)
12042 :if type(myvar) == type("")
12043 :if type(myvar) == type(function("tr"))
12044 :if type(myvar) == type([])
12045 :if type(myvar) == type({})
12046 :if type(myvar) == type(0.0)
12047 :if type(myvar) == type(v:false)
12048 :if type(myvar) == type(v:none)
12049< To check if the v:t_ variables exist use this: >
12050 :if exists('v:t_number')
12051
12052< Can also be used as a |method|: >
12053 mylist->type()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012054<
12055 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012056
12057
12058typename({expr}) *typename()*
12059 Return a string representation of the type of {expr}.
12060 Example: >
12061 echo typename([1, 2, 3])
Kota Kato66bb9ae2023-01-17 18:31:56 +000012062< list<number> ~
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012063
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012064 Return type: |String|
12065
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012066
12067undofile({name}) *undofile()*
12068 Return the name of the undo file that would be used for a file
12069 with name {name} when writing. This uses the 'undodir'
12070 option, finding directories that exist. It does not check if
12071 the undo file exists.
12072 {name} is always expanded to the full path, since that is what
12073 is used internally.
12074 If {name} is empty undofile() returns an empty string, since a
12075 buffer without a file name will not write an undo file.
12076 Useful in combination with |:wundo| and |:rundo|.
12077 When compiled without the |+persistent_undo| option this always
12078 returns an empty string.
12079
12080 Can also be used as a |method|: >
12081 GetFilename()->undofile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012082<
12083 Return type: |String|
12084
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012085
Devin J. Pohly5fee1112023-04-23 20:26:59 -050012086undotree([{buf}]) *undotree()*
12087 Return the current state of the undo tree for the current
12088 buffer, or for a specific buffer if {buf} is given. The
12089 result is a dictionary with the following items:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012090 "seq_last" The highest undo sequence number used.
12091 "seq_cur" The sequence number of the current position in
12092 the undo tree. This differs from "seq_last"
12093 when some changes were undone.
12094 "time_cur" Time last used for |:earlier| and related
12095 commands. Use |strftime()| to convert to
12096 something readable.
12097 "save_last" Number of the last file write. Zero when no
12098 write yet.
12099 "save_cur" Number of the current position in the undo
12100 tree.
12101 "synced" Non-zero when the last undo block was synced.
12102 This happens when waiting from input from the
12103 user. See |undo-blocks|.
12104 "entries" A list of dictionaries with information about
12105 undo blocks.
12106
12107 The first item in the "entries" list is the oldest undo item.
12108 Each List item is a |Dictionary| with these items:
12109 "seq" Undo sequence number. Same as what appears in
12110 |:undolist|.
12111 "time" Timestamp when the change happened. Use
12112 |strftime()| to convert to something readable.
12113 "newhead" Only appears in the item that is the last one
12114 that was added. This marks the last change
12115 and where further changes will be added.
12116 "curhead" Only appears in the item that is the last one
12117 that was undone. This marks the current
12118 position in the undo tree, the block that will
12119 be used by a redo command. When nothing was
12120 undone after the last change this item will
12121 not appear anywhere.
12122 "save" Only appears on the last block before a file
12123 write. The number is the write count. The
12124 first write has number 1, the last one the
12125 "save_last" mentioned above.
12126 "alt" Alternate entry. This is again a List of undo
12127 blocks. Each item may again have an "alt"
12128 item.
12129
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012130 Return type: dict<any>
12131
12132
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012133uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
12134 Remove second and succeeding copies of repeated adjacent
12135 {list} items in-place. Returns {list}. If you want a list
12136 to remain unmodified make a copy first: >
12137 :let newlist = uniq(copy(mylist))
12138< The default compare function uses the string representation of
12139 each item. For the use of {func} and {dict} see |sort()|.
12140
Bram Moolenaard592deb2022-06-17 15:42:40 +010012141 Returns zero if {list} is not a |List|.
12142
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012143 Can also be used as a |method|: >
12144 mylist->uniq()
Christian Brabandt67672ef2023-04-24 21:09:54 +010012145<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012146 Return type: list<{type}>
12147
12148
Christian Brabandt67672ef2023-04-24 21:09:54 +010012149 *utf16idx()*
12150utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010012151 Same as |charidx()| but returns the UTF-16 code unit index of
12152 the byte at {idx} in {string} (after converting it to UTF-16).
Christian Brabandt67672ef2023-04-24 21:09:54 +010012153
12154 When {charidx} is present and TRUE, {idx} is used as the
12155 character index in the String {string} instead of as the byte
12156 index.
Yegappan Lakshmanan95707032023-06-14 13:10:15 +010012157 An {idx} in the middle of a UTF-8 sequence is rounded
12158 downwards to the beginning of that sequence.
Christian Brabandt67672ef2023-04-24 21:09:54 +010012159
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010012160 Returns -1 if the arguments are invalid or if there are less
12161 than {idx} bytes in {string}. If there are exactly {idx} bytes
12162 the length of the string in UTF-16 code units is returned.
12163
Christian Brabandt67672ef2023-04-24 21:09:54 +010012164 See |byteidx()| and |byteidxcomp()| for getting the byte index
12165 from the UTF-16 index and |charidx()| for getting the
12166 character index from the UTF-16 index.
12167 Refer to |string-offset-encoding| for more information.
12168 Examples: >
12169 echo utf16idx('a😊😊', 3) returns 2
12170 echo utf16idx('a😊😊', 7) returns 4
12171 echo utf16idx('a😊😊', 1, 0, 1) returns 2
12172 echo utf16idx('a😊😊', 2, 0, 1) returns 4
12173 echo utf16idx('aą́c', 6) returns 2
12174 echo utf16idx('aą́c', 6, 1) returns 4
12175 echo utf16idx('a😊😊', 9) returns -1
12176<
12177 Can also be used as a |method|: >
12178 GetName()->utf16idx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012179<
12180 Return type: |Number|
Christian Brabandt67672ef2023-04-24 21:09:54 +010012181
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012182
12183values({dict}) *values()*
12184 Return a |List| with all the values of {dict}. The |List| is
12185 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010012186 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012187
12188 Can also be used as a |method|: >
12189 mydict->values()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012190<
12191 Return type: list<any>
12192
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012193
zeertzjq825cf812023-08-17 22:55:25 +020012194virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012195 The result is a Number, which is the screen column of the file
12196 position given with {expr}. That is, the last screen position
12197 occupied by the character at that position, when the screen
12198 would be of unlimited width. When there is a <Tab> at the
12199 position, the returned Number will be the column at the end of
12200 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
12201 set to 8, it returns 8. |conceal| is ignored.
12202 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010012203
zeertzjq02f3eba2024-06-12 20:45:24 +020012204 For the use of {expr} see |getpos()| and |col()|.
zeertzjqd353d272024-06-13 23:00:25 +080012205 When {expr} is "$", it means the end of the cursor line, so
12206 the result is the number of cells in the cursor line plus one.
LemonBoy0f7a3e12022-05-26 12:10:37 +010012207
12208 When 'virtualedit' is used {expr} can be [lnum, col, off],
12209 where "off" is the offset in screen columns from the start of
12210 the character. E.g., a position within a <Tab> or after the
12211 last character. When "off" is omitted zero is used. When
12212 Virtual editing is active in the current mode, a position
12213 beyond the end of the line can be returned. Also see
12214 |'virtualedit'|
12215
zeertzjq825cf812023-08-17 22:55:25 +020012216 If {list} is present and non-zero then virtcol() returns a
12217 List with the first and last screen position occupied by the
LemonBoy0f7a3e12022-05-26 12:10:37 +010012218 character.
12219
zeertzjq825cf812023-08-17 22:55:25 +020012220 With the optional {winid} argument the values are obtained for
12221 that window instead of the current window.
12222
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012223 Note that only marks in the current file can be used.
zeertzjq02f3eba2024-06-12 20:45:24 +020012224
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012225 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +010012226 " With text "foo^Lbar" and cursor on the "^L":
12227
12228 virtcol(".") " returns 5
12229 virtcol(".", 1) " returns [4, 5]
12230 virtcol("$") " returns 9
12231
12232 " With text " there", with 't at 'h':
12233
12234 virtcol("'t") " returns 6
zeertzjq02f3eba2024-06-12 20:45:24 +020012235<
12236 The first column is 1. 0 or [0, 0] is returned for an error.
12237
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012238 A more advanced example that echoes the maximum length of
12239 all lines: >
12240 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
12241
12242< Can also be used as a |method|: >
12243 GetPos()->virtcol()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012244<
12245 Return type: |Number|
12246
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012247
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012248virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
12249 The result is a Number, which is the byte index of the
12250 character in window {winid} at buffer line {lnum} and virtual
12251 column {col}.
12252
zeertzjqb583eda2023-10-14 11:32:28 +020012253 If buffer line {lnum} is an empty line, 0 is returned.
12254
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012255 If {col} is greater than the last virtual column in line
12256 {lnum}, then the byte index of the character at the last
12257 virtual column is returned.
12258
Yegappan Lakshmananb209b862023-08-15 23:01:44 +020012259 For a multi-byte character, the column number of the first
12260 byte in the character is returned.
12261
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012262 The {winid} argument can be the window number or the
12263 |window-ID|. If this is zero, then the current window is used.
12264
12265 Returns -1 if the window {winid} doesn't exist or the buffer
12266 line {lnum} or virtual column {col} is invalid.
12267
12268 See also |screenpos()|, |virtcol()| and |col()|.
12269
12270 Can also be used as a |method|: >
12271 GetWinid()->virtcol2col(lnum, col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012272<
12273 Return type: |Number|
12274
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012275
12276visualmode([{expr}]) *visualmode()*
12277 The result is a String, which describes the last Visual mode
12278 used in the current buffer. Initially it returns an empty
12279 string, but once Visual mode has been used, it returns "v",
12280 "V", or "<CTRL-V>" (a single CTRL-V character) for
12281 character-wise, line-wise, or block-wise Visual mode
12282 respectively.
12283 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012284 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012285< This enters the same Visual mode as before. It is also useful
12286 in scripts if you wish to act differently depending on the
12287 Visual mode that was used.
12288 If Visual mode is active, use |mode()| to get the Visual mode
12289 (e.g., in a |:vmap|).
12290 If {expr} is supplied and it evaluates to a non-zero Number or
12291 a non-empty String, then the Visual mode will be cleared and
12292 the old value is returned. See |non-zero-arg|.
12293
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012294 Return type: |String|
12295
12296
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012297wildmenumode() *wildmenumode()*
12298 Returns |TRUE| when the wildmenu is active and |FALSE|
12299 otherwise. See 'wildmenu' and 'wildmode'.
12300 This can be used in mappings to handle the 'wildcharm' option
12301 gracefully. (Makes only sense with |mapmode-c| mappings).
12302
12303 For example to make <c-j> work like <down> in wildmode, use: >
12304 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
12305<
Milly6c2fc372024-10-16 22:11:17 +020012306 (Note: this needs the 'wildcharm' option set appropriately).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012307
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012308 Return type: |Number|
12309
12310
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012311win_execute({id}, {command} [, {silent}]) *win_execute()*
12312 Like `execute()` but in the context of window {id}.
12313 The window will temporarily be made the current window,
12314 without triggering autocommands or changing directory. When
12315 executing {command} autocommands will be triggered, this may
Bram Moolenaarb7398fe2023-05-14 18:50:25 +010012316 have unexpected side effects. Use `:noautocmd` if needed.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012317 Example: >
12318 call win_execute(winid, 'set syntax=python')
12319< Doing the same with `setwinvar()` would not trigger
12320 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012321 *E994*
12322 Not all commands are allowed in popup windows.
12323 When window {id} does not exist then no error is given and
12324 an empty string is returned.
12325
12326 Can also be used as a |method|, the base is passed as the
12327 second argument: >
12328 GetCommand()->win_execute(winid)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012329<
12330 Return type: |String|
12331
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012332
12333win_findbuf({bufnr}) *win_findbuf()*
12334 Returns a |List| with |window-ID|s for windows that contain
12335 buffer {bufnr}. When there is none the list is empty.
12336
12337 Can also be used as a |method|: >
12338 GetBufnr()->win_findbuf()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012339<
12340 Return type: list<number> or list<any>
12341
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012342
12343win_getid([{win} [, {tab}]]) *win_getid()*
12344 Get the |window-ID| for the specified window.
12345 When {win} is missing use the current window.
12346 With {win} this is the window number. The top window has
12347 number 1.
12348 Without {tab} use the current tab, otherwise the tab with
12349 number {tab}. The first tab has number one.
12350 Return zero if the window cannot be found.
12351
12352 Can also be used as a |method|: >
12353 GetWinnr()->win_getid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012354<
12355 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012356
12357
12358win_gettype([{nr}]) *win_gettype()*
12359 Return the type of the window:
12360 "autocmd" autocommand window. Temporary window
12361 used to execute autocommands.
12362 "command" command-line window |cmdwin|
12363 (empty) normal window
12364 "loclist" |location-list-window|
12365 "popup" popup window |popup|
12366 "preview" preview window |preview-window|
12367 "quickfix" |quickfix-window|
12368 "unknown" window {nr} not found
12369
12370 When {nr} is omitted return the type of the current window.
12371 When {nr} is given return the type of this window by number or
12372 |window-ID|.
12373
12374 Also see the 'buftype' option. When running a terminal in a
12375 popup window then 'buftype' is "terminal" and win_gettype()
12376 returns "popup".
12377
12378 Can also be used as a |method|: >
12379 GetWinid()->win_gettype()
12380<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012381 Return type: |String|
12382
12383
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012384win_gotoid({expr}) *win_gotoid()*
12385 Go to window with ID {expr}. This may also change the current
12386 tabpage.
12387 Return TRUE if successful, FALSE if the window cannot be found.
12388
12389 Can also be used as a |method|: >
12390 GetWinid()->win_gotoid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012391<
12392 Return type: |Number|
12393
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012394
12395win_id2tabwin({expr}) *win_id2tabwin()*
12396 Return a list with the tab number and window number of window
12397 with ID {expr}: [tabnr, winnr].
12398 Return [0, 0] if the window cannot be found.
12399
12400 Can also be used as a |method|: >
12401 GetWinid()->win_id2tabwin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012402<
12403 Return type: list<number>
12404
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012405
12406win_id2win({expr}) *win_id2win()*
12407 Return the window number of window with ID {expr}.
12408 Return 0 if the window cannot be found in the current tabpage.
12409
12410 Can also be used as a |method|: >
12411 GetWinid()->win_id2win()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012412<
12413 Return type: |Number|
12414
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012415
Daniel Steinbergee630312022-01-10 13:36:34 +000012416win_move_separator({nr}, {offset}) *win_move_separator()*
12417 Move window {nr}'s vertical separator (i.e., the right border)
12418 by {offset} columns, as if being dragged by the mouse. {nr}
12419 can be a window number or |window-ID|. A positive {offset}
12420 moves right and a negative {offset} moves left. Moving a
12421 window's vertical separator will change the width of the
12422 window and the width of other windows adjacent to the vertical
12423 separator. The magnitude of movement may be smaller than
12424 specified (e.g., as a consequence of maintaining
12425 'winminwidth'). Returns TRUE if the window can be found and
12426 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010012427 This will fail for the rightmost window and a full-width
12428 window, since it has no separator on the right.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000012429 Only works for the current tab page. *E1308*
Daniel Steinbergee630312022-01-10 13:36:34 +000012430
12431 Can also be used as a |method|: >
12432 GetWinnr()->win_move_separator(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012433<
12434 Return type: |Number|
12435
Daniel Steinbergee630312022-01-10 13:36:34 +000012436
12437win_move_statusline({nr}, {offset}) *win_move_statusline()*
12438 Move window {nr}'s status line (i.e., the bottom border) by
12439 {offset} rows, as if being dragged by the mouse. {nr} can be a
12440 window number or |window-ID|. A positive {offset} moves down
12441 and a negative {offset} moves up. Moving a window's status
12442 line will change the height of the window and the height of
12443 other windows adjacent to the status line. The magnitude of
12444 movement may be smaller than specified (e.g., as a consequence
12445 of maintaining 'winminheight'). Returns TRUE if the window can
12446 be found and FALSE otherwise.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000012447 Only works for the current tab page.
Daniel Steinbergee630312022-01-10 13:36:34 +000012448
12449 Can also be used as a |method|: >
12450 GetWinnr()->win_move_statusline(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012451<
12452 Return type: |Number|
12453
Daniel Steinbergee630312022-01-10 13:36:34 +000012454
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012455win_screenpos({nr}) *win_screenpos()*
12456 Return the screen position of window {nr} as a list with two
12457 numbers: [row, col]. The first window always has position
12458 [1, 1], unless there is a tabline, then it is [2, 1].
12459 {nr} can be the window number or the |window-ID|. Use zero
12460 for the current window.
Sean Dewar5866bc32024-03-13 20:17:24 +010012461 Returns [0, 0] if the window cannot be found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012462
12463 Can also be used as a |method|: >
12464 GetWinid()->win_screenpos()
12465<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012466 Return type: list<number>
12467
12468
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012469win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
Sean Dewar96cc4ae2024-02-20 21:52:31 +010012470 Temporarily switch to window {target}, then move window {nr}
12471 to a new split adjacent to {target}.
12472 Unlike commands such as |:split|, no new windows are created
12473 (the |window-ID| of window {nr} is unchanged after the move).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012474
12475 Both {nr} and {target} can be window numbers or |window-ID|s.
12476 Both must be in the current tab page.
12477
12478 Returns zero for success, non-zero for failure.
12479
12480 {options} is a |Dictionary| with the following optional entries:
12481 "vertical" When TRUE, the split is created vertically,
12482 like with |:vsplit|.
12483 "rightbelow" When TRUE, the split is made below or to the
12484 right (if vertical). When FALSE, it is done
12485 above or to the left (if vertical). When not
12486 present, the values of 'splitbelow' and
12487 'splitright' are used.
12488
12489 Can also be used as a |method|: >
12490 GetWinid()->win_splitmove(target)
12491<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012492 Return type: |Number|
12493
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012494
12495 *winbufnr()*
12496winbufnr({nr}) The result is a Number, which is the number of the buffer
12497 associated with window {nr}. {nr} can be the window number or
12498 the |window-ID|.
12499 When {nr} is zero, the number of the buffer in the current
12500 window is returned.
12501 When window {nr} doesn't exist, -1 is returned.
12502 Example: >
12503 :echo "The file in the current window is " . bufname(winbufnr(0))
12504<
12505 Can also be used as a |method|: >
12506 FindWindow()->winbufnr()->bufname()
12507<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012508 Return type: |Number|
12509
12510
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012511 *wincol()*
12512wincol() The result is a Number, which is the virtual column of the
12513 cursor in the window. This is counting screen cells from the
12514 left side of the window. The leftmost column is one.
12515
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012516 Return type: |Number|
12517
12518
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012519 *windowsversion()*
12520windowsversion()
12521 The result is a String. For MS-Windows it indicates the OS
12522 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
12523 Windows XP is "5.1". For non-MS-Windows systems the result is
12524 an empty string.
12525
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012526 Return type: |String|
12527
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012528winheight({nr}) *winheight()*
12529 The result is a Number, which is the height of window {nr}.
12530 {nr} can be the window number or the |window-ID|.
12531 When {nr} is zero, the height of the current window is
12532 returned. When window {nr} doesn't exist, -1 is returned.
12533 An existing window always has a height of zero or more.
12534 This excludes any window toolbar line.
12535 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012536 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012537
12538< Can also be used as a |method|: >
12539 GetWinid()->winheight()
12540<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012541 Return type: |Number|
12542
12543
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012544winlayout([{tabnr}]) *winlayout()*
12545 The result is a nested List containing the layout of windows
12546 in a tabpage.
12547
12548 Without {tabnr} use the current tabpage, otherwise the tabpage
12549 with number {tabnr}. If the tabpage {tabnr} is not found,
12550 returns an empty list.
12551
12552 For a leaf window, it returns:
12553 ['leaf', {winid}]
12554 For horizontally split windows, which form a column, it
12555 returns:
12556 ['col', [{nested list of windows}]]
12557 For vertically split windows, which form a row, it returns:
12558 ['row', [{nested list of windows}]]
12559
12560 Example: >
12561 " Only one window in the tab page
12562 :echo winlayout()
12563 ['leaf', 1000]
12564 " Two horizontally split windows
12565 :echo winlayout()
12566 ['col', [['leaf', 1000], ['leaf', 1001]]]
12567 " The second tab page, with three horizontally split
12568 " windows, with two vertically split windows in the
12569 " middle window
12570 :echo winlayout(2)
12571 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
12572 ['leaf', 1001]]], ['leaf', 1000]]]
12573<
12574 Can also be used as a |method|: >
12575 GetTabnr()->winlayout()
12576<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012577 Return type: list<any>
12578
12579
12580winline() *winline()*
12581 The result is a Number, which is the screen line of the cursor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012582 in the window. This is counting screen lines from the top of
12583 the window. The first line is one.
12584 If the cursor was moved the view on the file will be updated
12585 first, this may cause a scroll.
12586
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012587 Return type: |Number|
12588
12589
12590winnr([{arg}]) *winnr()*
12591 The result is a Number, which is the number of the current
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012592 window. The top window has number 1.
12593 Returns zero for a popup window.
12594
12595 The optional argument {arg} supports the following values:
12596 $ the number of the last window (the window
12597 count).
12598 # the number of the last accessed window (where
12599 |CTRL-W_p| goes to). If there is no previous
12600 window or it is in another tab page 0 is
Sean Deward64801e2024-03-12 20:46:12 +010012601 returned. May refer to the current window in
12602 some cases (e.g. when evaluating 'statusline'
12603 expressions).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012604 {N}j the number of the Nth window below the
12605 current window (where |CTRL-W_j| goes to).
12606 {N}k the number of the Nth window above the current
12607 window (where |CTRL-W_k| goes to).
12608 {N}h the number of the Nth window left of the
12609 current window (where |CTRL-W_h| goes to).
12610 {N}l the number of the Nth window right of the
12611 current window (where |CTRL-W_l| goes to).
12612 The number can be used with |CTRL-W_w| and ":wincmd w"
12613 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010012614 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012615 Also see |tabpagewinnr()| and |win_getid()|.
12616 Examples: >
12617 let window_count = winnr('$')
12618 let prev_window = winnr('#')
12619 let wnum = winnr('3k')
12620
12621< Can also be used as a |method|: >
12622 GetWinval()->winnr()
12623<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012624 Return type: |Number|
12625
12626
12627winrestcmd() *winrestcmd()*
12628 Returns a sequence of |:resize| commands that should restore
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012629 the current window sizes. Only works properly when no windows
12630 are opened or closed and the current window and tab page is
12631 unchanged.
12632 Example: >
12633 :let cmd = winrestcmd()
12634 :call MessWithWindowSizes()
12635 :exe cmd
12636<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012637 Return type: |String|
12638
12639
12640winrestview({dict}) *winrestview()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012641 Uses the |Dictionary| returned by |winsaveview()| to restore
12642 the view of the current window.
12643 Note: The {dict} does not have to contain all values, that are
12644 returned by |winsaveview()|. If values are missing, those
12645 settings won't be restored. So you can use: >
12646 :call winrestview({'curswant': 4})
12647<
12648 This will only set the curswant value (the column the cursor
12649 wants to move on vertical movements) of the cursor to column 5
12650 (yes, that is 5), while all other settings will remain the
12651 same. This is useful, if you set the cursor position manually.
12652
12653 If you have changed the values the result is unpredictable.
12654 If the window size changed the result won't be the same.
12655
12656 Can also be used as a |method|: >
12657 GetView()->winrestview()
12658<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012659 Return type: |Number|
12660
12661
12662winsaveview() *winsaveview()*
12663 Returns a |Dictionary| that contains information to restore
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012664 the view of the current window. Use |winrestview()| to
12665 restore the view.
12666 This is useful if you have a mapping that jumps around in the
12667 buffer and you want to go back to the original view.
12668 This does not save fold information. Use the 'foldenable'
12669 option to temporarily switch off folding, so that folds are
12670 not opened when moving around. This may have side effects.
12671 The return value includes:
12672 lnum cursor line number
12673 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000012674 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012675 returns)
12676 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000012677 curswant column for vertical movement (Note:
12678 the first column is zero, as opposed
12679 to what |getcurpos()| returns). After
12680 |$| command it will be a very large
12681 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012682 topline first line in the window
12683 topfill filler lines, only in diff mode
12684 leftcol first column displayed; only used when
12685 'wrap' is off
12686 skipcol columns skipped
12687 Note that no option values are saved.
12688
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012689 Return type: dict<number>
12690
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012691
12692winwidth({nr}) *winwidth()*
12693 The result is a Number, which is the width of window {nr}.
12694 {nr} can be the window number or the |window-ID|.
12695 When {nr} is zero, the width of the current window is
12696 returned. When window {nr} doesn't exist, -1 is returned.
12697 An existing window always has a width of zero or more.
12698 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012699 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012700 :if winwidth(0) <= 50
12701 : 50 wincmd |
12702 :endif
12703< For getting the terminal or screen size, see the 'columns'
12704 option.
12705
12706 Can also be used as a |method|: >
12707 GetWinid()->winwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012708<
12709 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012710
12711
12712wordcount() *wordcount()*
12713 The result is a dictionary of byte/chars/word statistics for
12714 the current buffer. This is the same info as provided by
12715 |g_CTRL-G|
12716 The return value includes:
12717 bytes Number of bytes in the buffer
12718 chars Number of chars in the buffer
12719 words Number of words in the buffer
12720 cursor_bytes Number of bytes before cursor position
12721 (not in Visual mode)
12722 cursor_chars Number of chars before cursor position
12723 (not in Visual mode)
12724 cursor_words Number of words before cursor position
12725 (not in Visual mode)
12726 visual_bytes Number of bytes visually selected
12727 (only in Visual mode)
12728 visual_chars Number of chars visually selected
12729 (only in Visual mode)
12730 visual_words Number of words visually selected
12731 (only in Visual mode)
12732
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012733 Return type: dict<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012734
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012735
12736writefile({object}, {fname} [, {flags}]) *writefile()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012737 When {object} is a |List| write it to file {fname}. Each list
12738 item is separated with a NL. Each list item must be a String
12739 or Number.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012740 All NL characters are replaced with a NUL character.
12741 Inserting CR characters needs to be done before passing {list}
12742 to writefile().
Bram Moolenaar806a2732022-09-04 15:40:36 +010012743
12744 When {object} is a |Blob| write the bytes to file {fname}
12745 unmodified, also when binary mode is not specified.
12746
12747 {flags} must be a String. These characters are recognized:
12748
12749 'b' Binary mode is used: There will not be a NL after the
12750 last list item. An empty item at the end does cause the
12751 last line in the file to end in a NL.
12752
12753 'a' Append mode is used, lines are appended to the file: >
12754 :call writefile(["foo"], "event.log", "a")
12755 :call writefile(["bar"], "event.log", "a")
12756<
12757 'D' Delete the file when the current function ends. This
12758 works like: >
Bram Moolenaar938ae282023-02-20 20:44:55 +000012759 :defer delete({fname})
Bram Moolenaar806a2732022-09-04 15:40:36 +010012760< Fails when not in a function. Also see |:defer|.
12761
12762 's' fsync() is called after writing the file. This flushes
12763 the file to disk, if possible. This takes more time but
12764 avoids losing the file if the system crashes.
12765
12766 'S' fsync() is not called, even when 'fsync' is set.
12767
12768 When {flags} does not contain "S" or "s" then fsync() is
12769 called if the 'fsync' option is set.
12770
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012771 An existing file is overwritten, if possible.
Bram Moolenaar806a2732022-09-04 15:40:36 +010012772
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012773 When the write fails -1 is returned, otherwise 0. There is an
12774 error message if the file can't be created or when writing
12775 fails.
Bram Moolenaar806a2732022-09-04 15:40:36 +010012776
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012777 Also see |readfile()|.
12778 To copy a file byte for byte: >
12779 :let fl = readfile("foo", "b")
12780 :call writefile(fl, "foocopy", "b")
12781
12782< Can also be used as a |method|: >
12783 GetText()->writefile("thefile")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012784<
12785 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012786
12787
12788xor({expr}, {expr}) *xor()*
12789 Bitwise XOR on the two arguments. The arguments are converted
12790 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012791 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012792 Example: >
12793 :let bits = xor(bits, 0x80)
12794<
12795 Can also be used as a |method|: >
12796 :let bits = bits->xor(0x80)
12797<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012798 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012799
12800==============================================================================
128013. Feature list *feature-list*
12802
12803There are three types of features:
128041. Features that are only supported when they have been enabled when Vim
12805 was compiled |+feature-list|. Example: >
12806 :if has("cindent")
12807< *gui_running*
128082. Features that are only supported when certain conditions have been met.
12809 Example: >
12810 :if has("gui_running")
12811< *has-patch*
128123. Beyond a certain version or at a certain version and including a specific
12813 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
12814 later, or it is version 7.4 and patch 248 was included. Example: >
12815 :if has("patch-7.4.248")
12816< Note that it's possible for patch 248 to be omitted even though 249 is
12817 included. Only happens when cherry-picking patches.
12818 Note that this form only works for patch 7.4.237 and later, before that
12819 you need to check for the patch and the v:version. Example (checking
12820 version 6.2.148 or later): >
12821 :if v:version > 602 || (v:version == 602 && has("patch148"))
12822
12823Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
12824use: `if exists('+shellslash')`
12825
12826
12827acl Compiled with |ACL| support.
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010012828all_builtin_terms Compiled with all builtin terminals enabled. (always
12829 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012830amiga Amiga version of Vim.
12831arabic Compiled with Arabic support |Arabic|.
12832arp Compiled with ARP support (Amiga).
12833autocmd Compiled with autocommand support. (always true)
12834autochdir Compiled with support for 'autochdir'
12835autoservername Automatically enable |clientserver|
12836balloon_eval Compiled with |balloon-eval| support.
12837balloon_multiline GUI supports multiline balloons.
12838beos BeOS version of Vim.
12839browse Compiled with |:browse| support, and browse() will
12840 work.
12841browsefilter Compiled with support for |browsefilter|.
12842bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010012843builtin_terms Compiled with some builtin terminals. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012844byte_offset Compiled with support for 'o' in 'statusline'
12845channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012846cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012847clientserver Compiled with remote invocation support |clientserver|.
12848clipboard Compiled with 'clipboard' support.
12849clipboard_working Compiled with 'clipboard' support and it can be used.
12850cmdline_compl Compiled with |cmdline-completion| support.
12851cmdline_hist Compiled with |cmdline-history| support.
12852cmdline_info Compiled with 'showcmd' and 'ruler' support.
12853comments Compiled with |'comments'| support.
12854compatible Compiled to be very Vi compatible.
12855conpty Platform where |ConPTY| can be used.
12856cryptv Compiled with encryption support |encryption|.
12857cscope Compiled with |cscope| support.
12858cursorbind Compiled with |'cursorbind'| (always true)
12859debug Compiled with "DEBUG" defined.
12860dialog_con Compiled with console dialog support.
glepnirdf461152024-04-04 22:23:29 +020012861dialog_con_gui Compiled with console and GUI dialog support.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012862dialog_gui Compiled with GUI dialog support.
12863diff Compiled with |vimdiff| and 'diff' support.
12864digraphs Compiled with support for digraphs.
12865directx Compiled with support for DirectX and 'renderoptions'.
12866dnd Compiled with support for the "~ register |quote_~|.
12867drop_file Compiled with |drop_file| support.
12868ebcdic Compiled on a machine with ebcdic character set.
12869emacs_tags Compiled with support for Emacs tags.
12870eval Compiled with expression evaluation support. Always
12871 true, of course!
12872ex_extra |+ex_extra| (always true)
12873extra_search Compiled with support for |'incsearch'| and
12874 |'hlsearch'|
12875farsi Support for Farsi was removed |farsi|.
Bram Moolenaarf80f40a2022-08-25 16:02:23 +010012876file_in_path Compiled with support for |gf| and |<cfile>| (always
12877 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012878filterpipe When 'shelltemp' is off pipes are used for shell
12879 read/write/filter commands
12880find_in_path Compiled with support for include file searches
12881 |+find_in_path|.
12882float Compiled with support for |Float|.
12883fname_case Case in file names matters (for Amiga and MS-Windows
12884 this is not present).
12885folding Compiled with |folding| support.
12886footer Compiled with GUI footer support. |gui-footer|
12887fork Compiled to use fork()/exec() instead of system().
12888gettext Compiled with message translation |multi-lang|
12889gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010012890gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012891gui_gnome Compiled with Gnome support (gui_gtk is also defined).
12892gui_gtk Compiled with GTK+ GUI (any version).
12893gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
12894gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
12895gui_haiku Compiled with Haiku GUI.
12896gui_mac Compiled with Macintosh GUI.
12897gui_motif Compiled with Motif GUI.
12898gui_photon Compiled with Photon GUI.
12899gui_running Vim is running in the GUI, or it will start soon.
12900gui_win32 Compiled with MS-Windows Win32 GUI.
12901gui_win32s idem, and Win32s system being used (Windows 3.1)
12902haiku Haiku version of Vim.
12903hangul_input Compiled with Hangul input support. |hangul|
12904hpux HP-UX version of Vim.
Zhaoming Luoa41dfcd2025-02-06 21:39:35 +010012905hurd GNU/Hurd version of Vim
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012906iconv Can use iconv() for conversion.
12907insert_expand Compiled with support for CTRL-X expansion commands in
12908 Insert mode. (always true)
12909job Compiled with support for |channel| and |job|
12910ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012911jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012912keymap Compiled with 'keymap' support.
12913lambda Compiled with |lambda| support.
12914langmap Compiled with 'langmap' support.
12915libcall Compiled with |libcall()| support.
12916linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
12917 'breakindent' support.
12918linux Linux version of Vim.
12919lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012920 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012921listcmds Compiled with commands for the buffer list |:files|
12922 and the argument list |arglist|.
12923localmap Compiled with local mappings and abbr. |:map-local|
12924lua Compiled with Lua interface |Lua|.
12925mac Any Macintosh version of Vim cf. osx
12926macunix Synonym for osxdarwin
12927menu Compiled with support for |:menu|.
12928mksession Compiled with support for |:mksession|.
12929modify_fname Compiled with file name modifiers. |filename-modifiers|
12930 (always true)
12931mouse Compiled with support for mouse.
12932mouse_dec Compiled with support for Dec terminal mouse.
12933mouse_gpm Compiled with support for gpm (Linux console mouse)
12934mouse_gpm_enabled GPM mouse is working
12935mouse_netterm Compiled with support for netterm mouse.
12936mouse_pterm Compiled with support for qnx pterm mouse.
12937mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
12938mouse_sgr Compiled with support for sgr mouse.
12939mouse_urxvt Compiled with support for urxvt mouse.
12940mouse_xterm Compiled with support for xterm mouse.
12941mouseshape Compiled with support for 'mouseshape'.
12942multi_byte Compiled with support for 'encoding' (always true)
12943multi_byte_encoding 'encoding' is set to a multibyte encoding.
12944multi_byte_ime Compiled with support for IME input method.
12945multi_lang Compiled with support for multiple languages.
12946mzscheme Compiled with MzScheme interface |mzscheme|.
12947nanotime Compiled with sub-second time stamp checks.
12948netbeans_enabled Compiled with support for |netbeans| and connected.
12949netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012950num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012951ole Compiled with OLE automation support for Win32.
12952osx Compiled for macOS cf. mac
12953osxdarwin Compiled for macOS, with |mac-darwin-feature|
12954packages Compiled with |packages| support.
12955path_extra Compiled with up/downwards search in 'path' and 'tags'
12956perl Compiled with Perl interface.
12957persistent_undo Compiled with support for persistent undo history.
12958postscript Compiled with PostScript file printing.
12959printer Compiled with |:hardcopy| support.
12960profile Compiled with |:profile| support.
Bram Moolenaar71badf92023-04-22 22:40:14 +010012961prof_nsec Profile results are in nanoseconds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012962python Python 2.x interface available. |has-python|
12963python_compiled Compiled with Python 2.x interface. |has-python|
12964python_dynamic Python 2.x interface is dynamically loaded. |has-python|
12965python3 Python 3.x interface available. |has-python|
12966python3_compiled Compiled with Python 3.x interface. |has-python|
12967python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Yee Cheng Chinc13b3d12023-08-20 21:18:38 +020012968python3_stable Python 3.x interface is using Python Stable ABI. |has-python|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012969pythonx Python 2.x and/or 3.x interface available. |python_x|
12970qnx QNX version of Vim.
12971quickfix Compiled with |quickfix| support.
12972reltime Compiled with |reltime()| support.
12973rightleft Compiled with 'rightleft' support.
12974ruby Compiled with Ruby interface |ruby|.
12975scrollbind Compiled with 'scrollbind' support. (always true)
12976showcmd Compiled with 'showcmd' support.
12977signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012978smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012979sodium Compiled with libsodium for better crypt support
12980sound Compiled with sound support, e.g. `sound_playevent()`
12981spell Compiled with spell checking support |spell|.
12982startuptime Compiled with |--startuptime| support.
12983statusline Compiled with support for 'statusline', 'rulerformat'
12984 and special formats of 'titlestring' and 'iconstring'.
12985sun SunOS version of Vim.
12986sun_workshop Support for Sun |workshop| has been removed.
12987syntax Compiled with syntax highlighting support |syntax|.
12988syntax_items There are active syntax highlighting items for the
12989 current buffer.
12990system Compiled to use system() instead of fork()/exec().
12991tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012992 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012993tag_old_static Support for old static tags was removed, see
12994 |tag-old-static|.
12995tcl Compiled with Tcl interface.
12996termguicolors Compiled with true color in terminal support.
12997terminal Compiled with |terminal| support.
12998terminfo Compiled with terminfo instead of termcap.
12999termresponse Compiled with support for |t_RV| and |v:termresponse|.
13000textobjects Compiled with support for |text-objects|.
13001textprop Compiled with support for |text-properties|.
13002tgetent Compiled with tgetent support, able to use a termcap
13003 or terminfo file.
13004timers Compiled with |timer_start()| support.
13005title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010013006 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013007toolbar Compiled with support for |gui-toolbar|.
13008ttyin input is a terminal (tty)
13009ttyout output is a terminal (tty)
13010unix Unix version of Vim. *+unix*
13011unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
13012user_commands User-defined commands. (always true)
13013vartabs Compiled with variable tabstop support |'vartabstop'|.
13014vcon Win32: Virtual console support is working, can use
13015 'termguicolors'. Also see |+vtp|.
13016vertsplit Compiled with vertically split windows |:vsplit|.
13017 (always true)
13018vim_starting True while initial source'ing takes place. |startup|
13019 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000013020vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013021viminfo Compiled with viminfo support.
13022vimscript-1 Compiled Vim script version 1 support
13023vimscript-2 Compiled Vim script version 2 support
13024vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010013025vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013026virtualedit Compiled with 'virtualedit' option. (always true)
13027visual Compiled with Visual mode. (always true)
13028visualextra Compiled with extra Visual mode commands. (always
13029 true) |blockwise-operators|.
13030vms VMS version of Vim.
13031vreplace Compiled with |gR| and |gr| commands. (always true)
13032vtp Compiled for vcon support |+vtp| (check vcon to find
13033 out if it works in the current console).
13034wildignore Compiled with 'wildignore' option.
13035wildmenu Compiled with 'wildmenu' option.
13036win16 old version for MS-Windows 3.1 (always false)
13037win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
13038 64 bits)
13039win32unix Win32 version of Vim, using Unix files (Cygwin)
13040win64 Win64 version of Vim (MS-Windows 64 bit).
13041win95 Win32 version for MS-Windows 95/98/ME (always false)
13042winaltkeys Compiled with 'winaltkeys' option.
13043windows Compiled with support for more than one window.
13044 (always true)
13045writebackup Compiled with 'writebackup' default on.
Christian Brabandte085dfd2023-09-30 12:49:18 +020013046xattr Compiled with extended attributes support |xattr|
13047 (currently only supported on Linux).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000013048xfontset Compiled with X fontset support |xfontset|.
13049xim Compiled with X input method support |xim|.
13050xpm Compiled with pixmap support.
13051xpm_w32 Compiled with pixmap support for Win32. (Only for
13052 backward compatibility. Use "xpm" instead.)
13053xsmp Compiled with X session management support.
13054xsmp_interact Compiled with interactive X session management support.
13055xterm_clipboard Compiled with support for xterm clipboard.
13056xterm_save Compiled with support for saving and restoring the
13057 xterm screen.
13058x11 Compiled with X11 support.
13059
13060
13061==============================================================================
130624. Matching a pattern in a String *string-match*
13063
13064This is common between several functions. A regexp pattern as explained at
13065|pattern| is normally used to find a match in the buffer lines. When a
13066pattern is used to find a match in a String, almost everything works in the
13067same way. The difference is that a String is handled like it is one line.
13068When it contains a "\n" character, this is not seen as a line break for the
13069pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
13070>
13071 :let a = "aaaa\nxxxx"
13072 :echo matchstr(a, "..\n..")
13073 aa
13074 xx
13075 :echo matchstr(a, "a.x")
13076 a
13077 x
13078
13079Don't forget that "^" will only match at the first character of the String and
13080"$" at the last character of the string. They don't match after or before a
13081"\n".
13082
13083 vim:tw=78:ts=8:noet:ft=help:norl: