blob: dc47f410b25d7fd3f282d6f34e171c625c18b16e [file] [log] [blame]
zeertzjqc4815c12025-03-18 20:28:00 +01001*builtin.txt* For Vim version 9.1. Last change: 2025 Mar 18
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
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +0000132col({expr} [, {winid}]) Number column byte index of cursor or mark
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000133complete({startcol}, {matches}) none set Insert mode completion
134complete_add({expr}) Number add completion match
135complete_check() Number check for key typed during completion
136complete_info([{what}]) Dict get current completion information
137confirm({msg} [, {choices} [, {default} [, {type}]]])
138 Number number of choice picked by user
139copy({expr}) any make a shallow copy of {expr}
140cos({expr}) Float cosine of {expr}
141cosh({expr}) Float hyperbolic cosine of {expr}
142count({comp}, {expr} [, {ic} [, {start}]])
143 Number count how many {expr} are in {comp}
144cscope_connection([{num}, {dbpath} [, {prepend}]])
145 Number checks existence of cscope connection
146cursor({lnum}, {col} [, {off}])
147 Number move cursor to {lnum}, {col}, {off}
148cursor({list}) Number move cursor to position in {list}
149debugbreak({pid}) Number interrupt process being debugged
150deepcopy({expr} [, {noref}]) any make a full copy of {expr}
151delete({fname} [, {flags}]) Number delete the file or directory {fname}
152deletebufline({buf}, {first} [, {last}])
153 Number delete lines from buffer {buf}
154did_filetype() Number |TRUE| if FileType autocmd event used
Yegappan Lakshmananfa378352024-02-01 22:05:27 +0100155diff({fromlist}, {tolist} [, {options}])
156 List diff two Lists of strings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000157diff_filler({lnum}) Number diff filler lines about {lnum}
158diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
159digraph_get({chars}) String get the |digraph| of {chars}
160digraph_getlist([{listall}]) List get all |digraph|s
Christian Brabandtfbc37f12024-06-18 20:50:58 +0200161digraph_set({chars}, {digraph}) Bool register |digraph|
162digraph_setlist({digraphlist}) Bool register multiple |digraph|s
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000163echoraw({expr}) none output {expr} as-is
164empty({expr}) Number |TRUE| if {expr} is empty
165environ() Dict return environment variables
Sean Dewarb0efa492023-07-08 10:35:19 +0100166err_teapot([{expr}]) none give E418, or E503 if {expr} is |TRUE|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000167escape({string}, {chars}) String escape {chars} in {string} with '\'
168eval({string}) any evaluate {string} into its value
169eventhandler() Number |TRUE| if inside an event handler
170executable({expr}) Number 1 if executable {expr} exists
171execute({command}) String execute {command} and get the output
172exepath({expr}) String full path of the command {expr}
173exists({expr}) Number |TRUE| if {expr} exists
174exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
175exp({expr}) Float exponential of {expr}
176expand({expr} [, {nosuf} [, {list}]])
177 any expand special keywords in {expr}
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +0100178expandcmd({string} [, {options}])
179 String expand {string} like with `:edit`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000180extend({expr1}, {expr2} [, {expr3}])
181 List/Dict insert items of {expr2} into {expr1}
182extendnew({expr1}, {expr2} [, {expr3}])
183 List/Dict like |extend()| but creates a new
184 List or Dictionary
185feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Shougo Matsushita60c87432024-06-03 22:59:27 +0200186filecopy({from}, {to}) Number |TRUE| if copying file {from} to {to}
187 worked
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000188filereadable({file}) Number |TRUE| if {file} is a readable file
189filewritable({file}) Number |TRUE| if {file} is a writable file
190filter({expr1}, {expr2}) List/Dict/Blob/String
191 remove items from {expr1} where
192 {expr2} is 0
193finddir({name} [, {path} [, {count}]])
194 String find directory {name} in {path}
195findfile({name} [, {path} [, {count}]])
196 String find file {name} in {path}
197flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
198flattennew({list} [, {maxdepth}])
199 List flatten a copy of {list}
200float2nr({expr}) Number convert Float {expr} to a Number
201floor({expr}) Float round {expr} down
202fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
203fnameescape({fname}) String escape special characters in {fname}
204fnamemodify({fname}, {mods}) String modify file name
205foldclosed({lnum}) Number first line of fold at {lnum} if closed
206foldclosedend({lnum}) Number last line of fold at {lnum} if closed
207foldlevel({lnum}) Number fold level at {lnum}
208foldtext() String line displayed for closed fold
209foldtextresult({lnum}) String text for closed fold at {lnum}
Ernie Raele79e2072024-01-13 11:47:33 +0100210foreach({expr1}, {expr2}) List/Dict/Blob/String
211 for each item in {expr1} call {expr2}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000212foreground() Number bring the Vim window to the foreground
Bram Moolenaaraa534142022-09-15 21:46:02 +0100213fullcommand({name} [, {vim9}]) String get full command from {name}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000214funcref({name} [, {arglist}] [, {dict}])
215 Funcref reference to function {name}
216function({name} [, {arglist}] [, {dict}])
217 Funcref named reference to function {name}
218garbagecollect([{atexit}]) none free memory, breaking cyclic references
219get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
220get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
221get({func}, {what}) any get property of funcref/partial {func}
222getbufinfo([{buf}]) List information about buffers
223getbufline({buf}, {lnum} [, {end}])
224 List lines {lnum} to {end} of buffer {buf}
Bram Moolenaarce30ccc2022-11-21 19:57:04 +0000225getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000226getbufvar({buf}, {varname} [, {def}])
227 any variable {varname} in buffer {buf}
mikoto20001083cae2024-11-11 21:24:14 +0100228getcellpixels() List get character cell pixel size
Kota Kato66bb9ae2023-01-17 18:31:56 +0000229getcellwidths() List get character cell width overrides
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000230getchangelist([{buf}]) List list of change list items
zeertzjqe0a2ab32025-02-02 09:14:35 +0100231getchar([{expr} [, {opts}]]) Number or String
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000232 get one character from the user
233getcharmod() Number modifiers for the last typed character
234getcharpos({expr}) List position of cursor, mark, etc.
235getcharsearch() Dict last character search
zeertzjqe0a2ab32025-02-02 09:14:35 +0100236getcharstr([{expr} [, {opts}]]) String get one character from the user
Ruslan Russkikh0407d622024-10-08 22:21:05 +0200237getcmdcomplpat() String return the completion pattern of the
238 current command-line completion
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100239getcmdcompltype() String return the type of the current
240 command-line completion
Shougo Matsushita69084282024-09-23 20:34:47 +0200241getcmdline() String return the current command-line input
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000242getcmdpos() Number return cursor position in command-line
Shougo Matsushita69084282024-09-23 20:34:47 +0200243getcmdprompt() String return the current command-line prompt
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100244getcmdscreenpos() Number return cursor screen position in
245 command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000246getcmdtype() String return current command-line type
247getcmdwintype() String return current command-line window type
248getcompletion({pat}, {type} [, {filtered}])
249 List list of cmdline completion matches
250getcurpos([{winnr}]) List position of the cursor
251getcursorcharpos([{winnr}]) List character position of the cursor
252getcwd([{winnr} [, {tabnr}]]) String get the current working directory
253getenv({name}) String return environment variable
254getfontname([{name}]) String name of font being used
255getfperm({fname}) String file permissions of file {fname}
256getfsize({fname}) Number size in bytes of file {fname}
257getftime({fname}) Number last modification time of file
258getftype({fname}) String description of type of file {fname}
259getimstatus() Number |TRUE| if the IME status is active
260getjumplist([{winnr} [, {tabnr}]])
261 List list of jump list items
262getline({lnum}) String line {lnum} of current buffer
263getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
264getloclist({nr}) List list of location list items
265getloclist({nr}, {what}) Dict get specific location list properties
266getmarklist([{buf}]) List list of global/local marks
267getmatches([{win}]) List list of current matches
268getmousepos() Dict last known mouse position
Bram Moolenaar24dc19c2022-11-14 19:49:15 +0000269getmouseshape() String current mouse shape name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000270getpid() Number process ID of Vim
271getpos({expr}) List position of cursor, mark, etc.
272getqflist() List list of quickfix items
273getqflist({what}) Dict get specific quickfix list properties
274getreg([{regname} [, 1 [, {list}]]])
275 String or List contents of a register
276getreginfo([{regname}]) Dict information about a register
Shougo Matsushita19b71882024-02-28 22:48:12 +0100277getregion({pos1}, {pos2} [, {opts}])
Shougo Matsushita3f905ab2024-02-21 00:02:45 +0100278 List get the text from {pos1} to {pos2}
Shougo Matsushitab4757e62024-05-07 20:49:24 +0200279getregionpos({pos1}, {pos2} [, {opts}])
280 List get a list of positions for a region
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000281getregtype([{regname}]) String type of a register
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +0100282getscriptinfo([{opts}]) List list of sourced scripts
ichizok663d18d2025-01-02 18:06:00 +0100283getstacktrace() List get current stack trace of Vim scripts
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000284gettabinfo([{expr}]) List list of tab pages
285gettabvar({nr}, {varname} [, {def}])
286 any variable {varname} in tab {nr} or {def}
287gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
288 any {name} in {winnr} in tab page {tabnr}
289gettagstack([{nr}]) Dict get the tag stack of window {nr}
h-east52e7cc22024-07-28 17:03:29 +0200290gettext({text} [, {package}]) String lookup translation of {text}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000291getwininfo([{winid}]) List list of info about each window
Bram Moolenaar938ae282023-02-20 20:44:55 +0000292getwinpos([{timeout}]) List X and Y coord in pixels of Vim window
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000293getwinposx() Number X coord in pixels of the Vim window
294getwinposy() Number Y coord in pixels of the Vim window
295getwinvar({nr}, {varname} [, {def}])
296 any variable {varname} in window {nr}
297glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
298 any expand file wildcards in {expr}
299glob2regpat({expr}) String convert a glob pat into a search pat
300globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
301 String do glob({expr}) for all dirs in {path}
302has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
303has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
304haslocaldir([{winnr} [, {tabnr}]])
305 Number |TRUE| if the window executed |:lcd|
306 or |:tcd|
307hasmapto({what} [, {mode} [, {abbr}]])
308 Number |TRUE| if mapping to {what} exists
309histadd({history}, {item}) Number add an item to a history
310histdel({history} [, {item}]) Number remove an item from a history
311histget({history} [, {index}]) String get the item {index} from a history
312histnr({history}) Number highest index of a history
313hlID({name}) Number syntax ID of highlight group {name}
314hlexists({name}) Number |TRUE| if highlight group {name} exists
315hlget([{name} [, {resolve}]]) List get highlight group attributes
316hlset({list}) Number set highlight group attributes
317hostname() String name of the machine Vim is running on
318iconv({expr}, {from}, {to}) String convert encoding of {expr}
Ernie Rael05124252024-07-11 22:10:45 +0200319id({item}) String get unique identity string of item
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000320indent({lnum}) Number indent of line {lnum}
321index({object}, {expr} [, {start} [, {ic}]])
322 Number index in {object} where {expr} appears
Yegappan Lakshmananb2186552022-08-13 13:09:20 +0100323indexof({object}, {expr} [, {opts}]])
324 Number index in {object} where {expr} is true
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000325input({prompt} [, {text} [, {completion}]])
326 String get input from the user
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100327inputdialog({prompt} [, {text} [, {cancelreturn}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000328 String like input() but in a GUI dialog
329inputlist({textlist}) Number let the user pick from a choice list
330inputrestore() Number restore typeahead
331inputsave() Number save and clear typeahead
332inputsecret({prompt} [, {text}]) String like input() but hiding the text
333insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
LemonBoyafe04662023-08-23 21:08:11 +0200334instanceof({object}, {class}) Number |TRUE| if {object} is an instance of {class}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000335interrupt() none interrupt script execution
336invert({expr}) Number bitwise invert
LemonBoydca1d402022-04-28 15:26:33 +0100337isabsolutepath({path}) Number |TRUE| if {path} is an absolute path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000338isdirectory({directory}) Number |TRUE| if {directory} is a directory
339isinf({expr}) Number determine if {expr} is infinity value
340 (positive or negative)
341islocked({expr}) Number |TRUE| if {expr} is locked
342isnan({expr}) Number |TRUE| if {expr} is NaN
343items({dict}) List key-value pairs in {dict}
344job_getchannel({job}) Channel get the channel handle for {job}
345job_info([{job}]) Dict get information about {job}
346job_setoptions({job}, {options}) none set options for {job}
347job_start({command} [, {options}])
348 Job start a job
349job_status({job}) String get the status of {job}
350job_stop({job} [, {how}]) Number stop {job}
351join({list} [, {sep}]) String join {list} items into one String
352js_decode({string}) any decode JS style JSON
353js_encode({expr}) String encode JS style JSON
354json_decode({string}) any decode JSON
355json_encode({expr}) String encode JSON
356keys({dict}) List keys in {dict}
zeertzjqcdc83932022-09-12 13:38:41 +0100357keytrans({string}) String translate internal keycodes to a form
358 that can be used by |:map|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000359len({expr}) Number the length of {expr}
360libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
361libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
362line({expr} [, {winid}]) Number line nr of cursor, last line or mark
363line2byte({lnum}) Number byte count of line {lnum}
364lispindent({lnum}) Number Lisp indent for line {lnum}
365list2blob({list}) Blob turn {list} of numbers into a Blob
366list2str({list} [, {utf8}]) String turn {list} of numbers into a String
367listener_add({callback} [, {buf}])
368 Number add a callback to listen to changes
369listener_flush([{buf}]) none invoke listener callbacks
370listener_remove({id}) none remove a listener callback
371localtime() Number current time
372log({expr}) Float natural logarithm (base e) of {expr}
373log10({expr}) Float logarithm of Float {expr} to base 10
374luaeval({expr} [, {expr}]) any evaluate |Lua| expression
375map({expr1}, {expr2}) List/Dict/Blob/String
376 change each item in {expr1} to {expr2}
377maparg({name} [, {mode} [, {abbr} [, {dict}]]])
378 String or Dict
379 rhs of mapping {name} in mode {mode}
380mapcheck({name} [, {mode} [, {abbr}]])
381 String check for mappings matching {name}
Ernie Rael09661202022-04-25 14:40:44 +0100382maplist([{abbr}]) List list of all mappings, a dict for each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000383mapnew({expr1}, {expr2}) List/Dict/Blob/String
384 like |map()| but creates a new List or
385 Dictionary
386mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
387match({expr}, {pat} [, {start} [, {count}]])
388 Number position where {pat} matches in {expr}
389matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
390 Number highlight {pattern} with {group}
391matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
392 Number highlight positions with {group}
393matcharg({nr}) List arguments of |:match|
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100394matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict})
395 List all the {pat} matches in buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000396matchdelete({id} [, {win}]) Number delete match identified by {id}
397matchend({expr}, {pat} [, {start} [, {count}]])
398 Number position where {pat} ends in {expr}
399matchfuzzy({list}, {str} [, {dict}])
400 List fuzzy match {str} in {list}
401matchfuzzypos({list}, {str} [, {dict}])
402 List fuzzy match {str} in {list}
403matchlist({expr}, {pat} [, {start} [, {count}]])
404 List match and submatches of {pat} in {expr}
405matchstr({expr}, {pat} [, {start} [, {count}]])
406 String {count}'th match of {pat} in {expr}
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +0100407matchstrlist({list}, {pat} [, {dict})
408 List all the {pat} matches in {list}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000409matchstrpos({expr}, {pat} [, {start} [, {count}]])
410 List {count}'th match of {pat} in {expr}
411max({expr}) Number maximum value of items in {expr}
412menu_info({name} [, {mode}]) Dict get menu item information
413min({expr}) Number minimum value of items in {expr}
Bram Moolenaar938ae282023-02-20 20:44:55 +0000414mkdir({name} [, {flags} [, {prot}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000415 Number create directory {name}
Doug Kearns9cd9e752024-04-07 17:42:17 +0200416mode([{expr}]) String current editing mode
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000417mzeval({expr}) any evaluate |MzScheme| expression
418nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
Christ van Willegenc0786752025-02-01 15:42:16 +0100419ngettext({single}, {plural}, {number}[, {domain}])
420 String translate text based on {number}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000421nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
422or({expr}, {expr}) Number bitwise OR
423pathshorten({expr} [, {len}]) String shorten directory names in a path
424perleval({expr}) any evaluate |Perl| expression
425popup_atcursor({what}, {options}) Number create popup window near the cursor
426popup_beval({what}, {options}) Number create popup window for 'ballooneval'
427popup_clear() none close all popup windows
428popup_close({id} [, {result}]) none close popup window {id}
429popup_create({what}, {options}) Number create a popup window
430popup_dialog({what}, {options}) Number create a popup window used as a dialog
431popup_filter_menu({id}, {key}) Number filter for a menu popup window
432popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
Bram Moolenaarbdc09a12022-10-07 14:31:45 +0100433popup_findecho() Number get window ID of popup for `:echowin`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000434popup_findinfo() Number get window ID of info popup window
435popup_findpreview() Number get window ID of preview popup window
436popup_getoptions({id}) Dict get options of popup window {id}
437popup_getpos({id}) Dict get position of popup window {id}
438popup_hide({id}) none hide popup menu {id}
439popup_list() List get a list of window IDs of all popups
440popup_locate({row}, {col}) Number get window ID of popup at position
441popup_menu({what}, {options}) Number create a popup window used as a menu
442popup_move({id}, {options}) none set position of popup window {id}
443popup_notification({what}, {options})
444 Number create a notification popup window
Christian Brabandtfbc37f12024-06-18 20:50:58 +0200445popup_setbuf({id}, {buf}) Bool set the buffer for the popup window {id}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000446popup_setoptions({id}, {options})
447 none set options for popup window {id}
448popup_settext({id}, {text}) none set the text of popup window {id}
449popup_show({id}) none unhide popup window {id}
450pow({x}, {y}) Float {x} to the power of {y}
451prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
452printf({fmt}, {expr1}...) String format text
453prompt_getprompt({buf}) String get prompt text
454prompt_setcallback({buf}, {expr}) none set prompt callback function
455prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
456prompt_setprompt({buf}, {text}) none set prompt text
457prop_add({lnum}, {col}, {props}) none add one text property
458prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
459 none add multiple text properties
460prop_clear({lnum} [, {lnum-end} [, {props}]])
461 none remove all text properties
462prop_find({props} [, {direction}])
463 Dict search for a text property
464prop_list({lnum} [, {props}]) List text properties in {lnum}
465prop_remove({props} [, {lnum} [, {lnum-end}]])
466 Number remove a text property
467prop_type_add({name}, {props}) none define a new property type
468prop_type_change({name}, {props})
469 none change an existing property type
470prop_type_delete({name} [, {props}])
471 none delete a property type
472prop_type_get({name} [, {props}])
473 Dict get property type values
474prop_type_list([{props}]) List get list of property types
475pum_getpos() Dict position and size of pum if visible
476pumvisible() Number whether popup menu is visible
zeertzjq7c515282024-11-10 20:26:12 +0100477py3eval({expr} [, {locals}]) any evaluate |python3| expression
478pyeval({expr} [, {locals}]) any evaluate |Python| expression
479pyxeval({expr} [, {locals}]) any evaluate |python_x| expression
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000480rand([{expr}]) Number get pseudo-random number
481range({expr} [, {max} [, {stride}]])
482 List items from {expr} to {max}
K.Takata11df3ae2022-10-19 14:02:40 +0100483readblob({fname} [, {offset} [, {size}]])
484 Blob read a |Blob| from {fname}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000485readdir({dir} [, {expr} [, {dict}]])
486 List file names in {dir} selected by {expr}
487readdirex({dir} [, {expr} [, {dict}]])
488 List file info in {dir} selected by {expr}
489readfile({fname} [, {type} [, {max}]])
490 List get list of lines from file {fname}
491reduce({object}, {func} [, {initial}])
492 any reduce {object} using {func}
493reg_executing() String get the executing register name
494reg_recording() String get the recording register name
495reltime([{start} [, {end}]]) List get time value
496reltimefloat({time}) Float turn the time value into a Float
497reltimestr({time}) String turn time value into a String
498remote_expr({server}, {string} [, {idvar} [, {timeout}]])
499 String send expression
500remote_foreground({server}) Number bring Vim server to the foreground
501remote_peek({serverid} [, {retvar}])
502 Number check for reply string
503remote_read({serverid} [, {timeout}])
504 String read reply string
505remote_send({server}, {string} [, {idvar}])
506 String send key sequence
507remote_startserver({name}) none become server {name}
508remove({list}, {idx} [, {end}]) any/List
509 remove items {idx}-{end} from {list}
510remove({blob}, {idx} [, {end}]) Number/Blob
511 remove bytes {idx}-{end} from {blob}
512remove({dict}, {key}) any remove entry {key} from {dict}
513rename({from}, {to}) Number rename (move) file from {from} to {to}
Bakudankun375141e2022-09-09 18:46:47 +0100514repeat({expr}, {count}) List/Blob/String
515 repeat {expr} {count} times
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000516resolve({filename}) String get filename a shortcut points to
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +0100517reverse({obj}) List/Blob/String
518 reverse {obj}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000519round({expr}) Float round off {expr}
520rubyeval({expr}) any evaluate |Ruby| expression
521screenattr({row}, {col}) Number attribute at screen position
522screenchar({row}, {col}) Number character at screen position
523screenchars({row}, {col}) List List of characters at screen position
524screencol() Number current cursor column
525screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
526screenrow() Number current cursor row
527screenstring({row}, {col}) String characters at screen position
528search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
529 Number search for {pattern}
530searchcount([{options}]) Dict get or update search stats
531searchdecl({name} [, {global} [, {thisblock}]])
532 Number search for variable declaration
533searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
534 Number search for other end of start/end pair
535searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
536 List search for other end of start/end pair
537searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
538 List search for {pattern}
539server2client({clientid}, {string})
540 Number send reply string
541serverlist() String get a list of available servers
erraelf0837ba2024-06-24 12:27:01 -0700542setbufline({buf}, {lnum}, {text})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000543 Number set line {lnum} to {text} in buffer
erraelf0837ba2024-06-24 12:27:01 -0700544 {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000545setbufvar({buf}, {varname}, {val})
546 none set {varname} in buffer {buf} to {val}
547setcellwidths({list}) none set character cell width overrides
548setcharpos({expr}, {list}) Number set the {expr} position to {list}
549setcharsearch({dict}) Dict set character search from {dict}
Shougo Matsushita07ea5f12022-08-27 12:22:25 +0100550setcmdline({str} [, {pos}]) Number set command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000551setcmdpos({pos}) Number set cursor position in command-line
552setcursorcharpos({list}) Number move cursor to position in {list}
553setenv({name}, {val}) none set environment variable
554setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
555setline({lnum}, {line}) Number set line {lnum} to {line}
556setloclist({nr}, {list} [, {action}])
557 Number modify location list using {list}
558setloclist({nr}, {list}, {action}, {what})
559 Number modify specific location list props
560setmatches({list} [, {win}]) Number restore a list of matches
561setpos({expr}, {list}) Number set the {expr} position to {list}
562setqflist({list} [, {action}]) Number modify quickfix list using {list}
563setqflist({list}, {action}, {what})
564 Number modify specific quickfix list props
565setreg({n}, {v} [, {opt}]) Number set register to value and type
566settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
567settabwinvar({tabnr}, {winnr}, {varname}, {val})
568 none set {varname} in window {winnr} in tab
569 page {tabnr} to {val}
570settagstack({nr}, {dict} [, {action}])
571 Number modify tag stack using {dict}
572setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
573sha256({string}) String SHA256 checksum of {string}
574shellescape({string} [, {special}])
575 String escape {string} for use as shell
576 command argument
577shiftwidth([{col}]) Number effective value of 'shiftwidth'
578sign_define({name} [, {dict}]) Number define or update a sign
579sign_define({list}) List define or update a list of signs
580sign_getdefined([{name}]) List get a list of defined signs
581sign_getplaced([{buf} [, {dict}]])
582 List get a list of placed signs
583sign_jump({id}, {group}, {buf})
584 Number jump to a sign
585sign_place({id}, {group}, {name}, {buf} [, {dict}])
586 Number place a sign
587sign_placelist({list}) List place a list of signs
588sign_undefine([{name}]) Number undefine a sign
589sign_undefine({list}) List undefine a list of signs
590sign_unplace({group} [, {dict}])
591 Number unplace a sign
592sign_unplacelist({list}) List unplace a list of signs
593simplify({filename}) String simplify filename as much as possible
594sin({expr}) Float sine of {expr}
595sinh({expr}) Float hyperbolic sine of {expr}
596slice({expr}, {start} [, {end}]) String, List or Blob
597 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000598sort({list} [, {how} [, {dict}]])
599 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000600sound_clear() none stop playing all sounds
601sound_playevent({name} [, {callback}])
602 Number play an event sound
603sound_playfile({path} [, {callback}])
604 Number play sound file {path}
605sound_stop({id}) none stop playing sound {id}
606soundfold({word}) String sound-fold {word}
607spellbadword() String badly spelled word at cursor
608spellsuggest({word} [, {max} [, {capital}]])
609 List spelling suggestions
610split({expr} [, {pat} [, {keepempty}]])
611 List make |List| from {pat} separated {expr}
612sqrt({expr}) Float square root of {expr}
613srand([{expr}]) List get seed for |rand()|
614state([{what}]) String current state of Vim
Hirohito Higashi195fcc92025-02-01 10:26:58 +0100615str2blob({list} [, {options}]) Blob convert list of strings into a Blob
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000616str2float({expr} [, {quoted}]) Float convert String to Float
617str2list({expr} [, {utf8}]) List convert each character of {expr} to
618 ASCII/UTF-8 value
619str2nr({expr} [, {base} [, {quoted}]])
620 Number convert String to Number
621strcharlen({expr}) Number character length of the String {expr}
622strcharpart({str}, {start} [, {len} [, {skipcc}]])
623 String {len} characters of {str} at
624 character {start}
625strchars({expr} [, {skipcc}]) Number character count of the String {expr}
626strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
627strftime({format} [, {time}]) String format time with a specified format
628strgetchar({str}, {index}) Number get char {index} from {str}
629stridx({haystack}, {needle} [, {start}])
630 Number index of {needle} in {haystack}
631string({expr}) String String representation of {expr} value
632strlen({expr}) Number length of the String {expr}
633strpart({str}, {start} [, {len} [, {chars}]])
634 String {len} bytes/chars of {str} at
635 byte {start}
636strptime({format}, {timestring})
637 Number Convert {timestring} to unix timestamp
638strridx({haystack}, {needle} [, {start}])
639 Number last index of {needle} in {haystack}
640strtrans({expr}) String translate string to make it printable
Christian Brabandt67672ef2023-04-24 21:09:54 +0100641strutf16len({string} [, {countcc}])
642 Number number of UTF-16 code units in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000643strwidth({expr}) Number display cell length of the String {expr}
644submatch({nr} [, {list}]) String or List
645 specific match in ":s" or substitute()
646substitute({expr}, {pat}, {sub}, {flags})
647 String all {pat} in {expr} replaced with {sub}
Bram Moolenaarc216a7a2022-12-05 13:50:55 +0000648swapfilelist() List swap files found in 'directory'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000649swapinfo({fname}) Dict information about swap file {fname}
650swapname({buf}) String swap file of buffer {buf}
651synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
652synIDattr({synID}, {what} [, {mode}])
653 String attribute {what} of syntax ID {synID}
654synIDtrans({synID}) Number translated syntax ID of {synID}
655synconcealed({lnum}, {col}) List info about concealing
656synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
657system({expr} [, {input}]) String output of shell command/filter {expr}
658systemlist({expr} [, {input}]) List output of shell command/filter {expr}
659tabpagebuflist([{arg}]) List list of buffer numbers in tab page
660tabpagenr([{arg}]) Number number of current or last tab page
661tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
662tagfiles() List tags files used
663taglist({expr} [, {filename}]) List list of tags matching {expr}
664tan({expr}) Float tangent of {expr}
665tanh({expr}) Float hyperbolic tangent of {expr}
666tempname() String name for a temporary file
667term_dumpdiff({filename}, {filename} [, {options}])
668 Number display difference between two dumps
669term_dumpload({filename} [, {options}])
670 Number displaying a screen dump
671term_dumpwrite({buf}, {filename} [, {options}])
672 none dump terminal window contents
673term_getaltscreen({buf}) Number get the alternate screen flag
674term_getansicolors({buf}) List get ANSI palette in GUI color mode
675term_getattr({attr}, {what}) Number get the value of attribute {what}
676term_getcursor({buf}) List get the cursor position of a terminal
677term_getjob({buf}) Job get the job associated with a terminal
678term_getline({buf}, {row}) String get a line of text from a terminal
679term_getscrolled({buf}) Number get the scroll count of a terminal
680term_getsize({buf}) List get the size of a terminal
681term_getstatus({buf}) String get the status of a terminal
682term_gettitle({buf}) String get the title of a terminal
683term_gettty({buf}, [{input}]) String get the tty name of a terminal
684term_list() List get the list of terminal buffers
685term_scrape({buf}, {row}) List get row of a terminal screen
686term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
687term_setansicolors({buf}, {colors})
688 none set ANSI palette in GUI color mode
689term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
690term_setkill({buf}, {how}) none set signal to stop job in terminal
691term_setrestore({buf}, {command}) none set command to restore terminal
692term_setsize({buf}, {rows}, {cols})
693 none set the size of a terminal
694term_start({cmd} [, {options}]) Number open a terminal window and run a job
695term_wait({buf} [, {time}]) Number wait for screen to be updated
696terminalprops() Dict properties of the terminal
697test_alloc_fail({id}, {countdown}, {repeat})
698 none make memory allocation fail
699test_autochdir() none enable 'autochdir' during startup
700test_feedinput({string}) none add key sequence to input buffer
701test_garbagecollect_now() none free memory right now for testing
702test_garbagecollect_soon() none free memory soon for testing
703test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000704test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000705test_ignore_error({expr}) none ignore a specific error
Christopher Plewright20b795e2022-12-20 20:01:58 +0000706test_mswin_event({event}, {args})
707 bool generate MS-Windows event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000708test_null_blob() Blob null value for testing
709test_null_channel() Channel null value for testing
710test_null_dict() Dict null value for testing
711test_null_function() Funcref null value for testing
712test_null_job() Job null value for testing
713test_null_list() List null value for testing
714test_null_partial() Funcref null value for testing
715test_null_string() String null value for testing
716test_option_not_set({name}) none reset flag indicating option was set
717test_override({expr}, {val}) none test with Vim internal overrides
718test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000719test_setmouse({row}, {col}) none set the mouse position for testing
720test_settime({expr}) none set current time for testing
Doug Kearns9cd9e752024-04-07 17:42:17 +0200721test_srand_seed([{seed}]) none set seed for testing srand()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000722test_unknown() any unknown value for testing
723test_void() any void value for testing
724timer_info([{id}]) List information about timers
725timer_pause({id}, {pause}) none pause or unpause a timer
726timer_start({time}, {callback} [, {options}])
727 Number create a timer
728timer_stop({timer}) none stop a timer
729timer_stopall() none stop all timers
730tolower({expr}) String the String {expr} switched to lowercase
731toupper({expr}) String the String {expr} switched to uppercase
732tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
733 to chars in {tostr}
734trim({text} [, {mask} [, {dir}]])
735 String trim characters in {mask} from {text}
736trunc({expr}) Float truncate Float {expr}
737type({expr}) Number type of value {expr}
738typename({expr}) String representation of the type of {expr}
739undofile({name}) String undo file name for {name}
Devin J. Pohly5fee1112023-04-23 20:26:59 -0500740undotree([{buf}]) List undo file tree for buffer {buf}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000741uniq({list} [, {func} [, {dict}]])
742 List remove adjacent duplicates from a list
Christian Brabandt67672ef2023-04-24 21:09:54 +0100743utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
744 Number UTF-16 index of byte {idx} in {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000745values({dict}) List values in {dict}
zeertzjq825cf812023-08-17 22:55:25 +0200746virtcol({expr} [, {list} [, {winid}])
747 Number or List
LemonBoy0f7a3e12022-05-26 12:10:37 +0100748 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100749virtcol2col({winid}, {lnum}, {col})
750 Number byte index of a character on screen
Doug Kearns9cd9e752024-04-07 17:42:17 +0200751visualmode([{expr}]) String last visual mode used
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000752wildmenumode() Number whether 'wildmenu' mode is active
753win_execute({id}, {command} [, {silent}])
754 String execute {command} in window {id}
755win_findbuf({bufnr}) List find windows containing {bufnr}
756win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
757win_gettype([{nr}]) String type of window {nr}
758win_gotoid({expr}) Number go to window with ID {expr}
759win_id2tabwin({expr}) List get tab and window nr from window ID
760win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000761win_move_separator({nr}) Number move window vertical separator
762win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000763win_screenpos({nr}) List get screen position of window {nr}
764win_splitmove({nr}, {target} [, {options}])
765 Number move window {nr} to split of {target}
766winbufnr({nr}) Number buffer number of window {nr}
767wincol() Number window column of the cursor
768windowsversion() String MS-Windows OS version
769winheight({nr}) Number height of window {nr}
770winlayout([{tabnr}]) List layout of windows in tab {tabnr}
771winline() Number window line of the cursor
772winnr([{expr}]) Number number of current window
773winrestcmd() String returns command to restore window sizes
774winrestview({dict}) none restore view of current window
775winsaveview() Dict save view of current window
776winwidth({nr}) Number width of window {nr}
777wordcount() Dict get byte/char/word statistics
778writefile({object}, {fname} [, {flags}])
779 Number write |Blob| or |List| of lines to file
780xor({expr}, {expr}) Number bitwise XOR
781
782==============================================================================
7832. Details *builtin-function-details*
784
785Not all functions are here, some have been moved to a help file covering the
786specific functionality.
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200787Return type specifies the type for |Vim9-script|, see |vim9-types|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000788
789abs({expr}) *abs()*
790 Return the absolute value of {expr}. When {expr} evaluates to
791 a |Float| abs() returns a |Float|. When {expr} can be
792 converted to a |Number| abs() returns a |Number|. Otherwise
793 abs() gives an error message and returns -1.
794 Examples: >
795 echo abs(1.456)
796< 1.456 >
797 echo abs(-5.456)
798< 5.456 >
799 echo abs(-4)
800< 4
801
802 Can also be used as a |method|: >
803 Compute()->abs()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200804<
805 Return type: |Number| or |Float| depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000806
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000807
808acos({expr}) *acos()*
809 Return the arc cosine of {expr} measured in radians, as a
810 |Float| in the range of [0, pi].
811 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100812 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000813 Examples: >
814 :echo acos(0)
815< 1.570796 >
816 :echo acos(-0.5)
817< 2.094395
818
819 Can also be used as a |method|: >
820 Compute()->acos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200821<
822 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000823
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000824
825add({object}, {expr}) *add()*
826 Append the item {expr} to |List| or |Blob| {object}. Returns
827 the resulting |List| or |Blob|. Examples: >
828 :let alist = add([1, 2, 3], item)
829 :call add(mylist, "woodstock")
830< Note that when {expr} is a |List| it is appended as a single
831 item. Use |extend()| to concatenate |Lists|.
832 When {object} is a |Blob| then {expr} must be a number.
833 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100834 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000835
836 Can also be used as a |method|: >
837 mylist->add(val1)->add(val2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200838<
839 Return type: list<{type}> (depending on the given |List|) or
840 |Blob|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000841
842
843and({expr}, {expr}) *and()*
844 Bitwise AND on the two arguments. The arguments are converted
845 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100846 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000847 Example: >
848 :let flag = and(bits, 0x80)
849< Can also be used as a |method|: >
850 :let flag = bits->and(0x80)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200851<
852 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000853
854
855append({lnum}, {text}) *append()*
856 When {text} is a |List|: Append each item of the |List| as a
857 text line below line {lnum} in the current buffer.
858 Otherwise append {text} as one text line below line {lnum} in
859 the current buffer.
860 Any type of item is accepted and converted to a String.
861 {lnum} can be zero to insert a line before the first one.
862 {lnum} is used like with |getline()|.
863 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000864 0 for success. When {text} is an empty list zero is returned,
865 no matter the value of {lnum}.
866 In |Vim9| script an invalid argument or negative number
867 results in an error. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000868 :let failed = append(line('$'), "# THE END")
869 :let failed = append(0, ["Chapter 1", "the beginning"])
870
871< Can also be used as a |method| after a List, the base is
872 passed as the second argument: >
873 mylist->append(lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200874<
875 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000876
877
878appendbufline({buf}, {lnum}, {text}) *appendbufline()*
879 Like |append()| but append the text in buffer {buf}.
880
881 This function works only for loaded buffers. First call
882 |bufload()| if needed.
883
884 For the use of {buf}, see |bufname()|.
885
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000886 {lnum} is the line number to append below. Note that using
887 |line()| would use the current buffer, not the one appending
888 to. Use "$" to append at the end of the buffer. Other string
889 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000890
891 On success 0 is returned, on failure 1 is returned.
892 In |Vim9| script an error is given for an invalid {lnum}.
893
894 If {buf} is not a valid buffer or {lnum} is not valid, an
895 error message is given. Example: >
896 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +0000897< However, when {text} is an empty list then no error is given
898 for an invalid {lnum}, since {lnum} isn't actually used.
899
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000900 Can also be used as a |method| after a List, the base is
901 passed as the second argument: >
902 mylist->appendbufline(buf, lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200903<
904 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000905
906
907argc([{winid}]) *argc()*
908 The result is the number of files in the argument list. See
909 |arglist|.
910 If {winid} is not supplied, the argument list of the current
911 window is used.
912 If {winid} is -1, the global argument list is used.
913 Otherwise {winid} specifies the window of which the argument
914 list is used: either the window number or the window ID.
915 Returns -1 if the {winid} argument is invalid.
916
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200917 Return type: |Number|
918
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000919 *argidx()*
920argidx() The result is the current index in the argument list. 0 is
921 the first file. argc() - 1 is the last one. See |arglist|.
922
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200923 Return type: |Number|
924
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000925 *arglistid()*
926arglistid([{winnr} [, {tabnr}]])
927 Return the argument list ID. This is a number which
928 identifies the argument list being used. Zero is used for the
929 global argument list. See |arglist|.
930 Returns -1 if the arguments are invalid.
931
932 Without arguments use the current window.
933 With {winnr} only use this window in the current tab page.
934 With {winnr} and {tabnr} use the window in the specified tab
935 page.
936 {winnr} can be the window number or the |window-ID|.
937
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200938 Return type: |Number|
939
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000940 *argv()*
941argv([{nr} [, {winid}]])
942 The result is the {nr}th file in the argument list. See
943 |arglist|. "argv(0)" is the first one. Example: >
944 :let i = 0
945 :while i < argc()
946 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000947 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000948 : let i = i + 1
949 :endwhile
950< Without the {nr} argument, or when {nr} is -1, a |List| with
951 the whole |arglist| is returned.
952
953 The {winid} argument specifies the window ID, see |argc()|.
954 For the Vim command line arguments see |v:argv|.
955
Bram Moolenaar016188f2022-06-06 20:52:59 +0100956 Returns an empty string if {nr}th argument is not present in
957 the argument list. Returns an empty List if the {winid}
958 argument is invalid.
959
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200960 Return type: |String|
961
962
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000963asin({expr}) *asin()*
964 Return the arc sine of {expr} measured in radians, as a |Float|
965 in the range of [-pi/2, pi/2].
966 {expr} must evaluate to a |Float| or a |Number| in the range
967 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100968 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
969 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000970 Examples: >
971 :echo asin(0.8)
972< 0.927295 >
973 :echo asin(-0.5)
974< -0.523599
975
976 Can also be used as a |method|: >
977 Compute()->asin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200978<
979 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000980
981assert_ functions are documented here: |assert-functions-details|
982
983
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000984atan({expr}) *atan()*
985 Return the principal value of the arc tangent of {expr}, in
986 the range [-pi/2, +pi/2] radians, as a |Float|.
987 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100988 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000989 Examples: >
990 :echo atan(100)
991< 1.560797 >
992 :echo atan(-4.01)
993< -1.326405
994
995 Can also be used as a |method|: >
996 Compute()->atan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +0200997<
998 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000999
1000
1001atan2({expr1}, {expr2}) *atan2()*
1002 Return the arc tangent of {expr1} / {expr2}, measured in
1003 radians, as a |Float| in the range [-pi, pi].
1004 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001005 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
1006 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001007 Examples: >
1008 :echo atan2(-1, 1)
1009< -0.785398 >
1010 :echo atan2(1, -1)
1011< 2.356194
1012
1013 Can also be used as a |method|: >
1014 Compute()->atan2(1)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001015<
1016 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001017
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001018
1019autocmd_add({acmds}) *autocmd_add()*
1020 Adds a List of autocmds and autocmd groups.
1021
1022 The {acmds} argument is a List where each item is a Dict with
1023 the following optional items:
1024 bufnr buffer number to add a buffer-local autocmd.
1025 If this item is specified, then the "pattern"
1026 item is ignored.
1027 cmd Ex command to execute for this autocmd event
1028 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +01001029 This can be either a String with a single
1030 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001031 group autocmd group name. Refer to |autocmd-groups|.
1032 If this group doesn't exist then it is
1033 created. If not specified or empty, then the
1034 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001035 nested boolean flag, set to v:true to add a nested
1036 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +01001037 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001038 which executes only once. Refer to
1039 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001040 pattern autocmd pattern string. Refer to
1041 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +01001042 present, then this item is ignored. This can
1043 be a String with a single pattern or a List of
1044 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001045 replace boolean flag, set to v:true to remove all the
1046 commands associated with the specified autocmd
1047 event and group and add the {cmd}. This is
1048 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +01001049 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001050
1051 Returns v:true on success and v:false on failure.
1052 Examples: >
1053 " Create a buffer-local autocmd for buffer 5
1054 let acmd = {}
1055 let acmd.group = 'MyGroup'
1056 let acmd.event = 'BufEnter'
1057 let acmd.bufnr = 5
1058 let acmd.cmd = 'call BufEnterFunc()'
1059 call autocmd_add([acmd])
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00001060<
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001061 Can also be used as a |method|: >
1062 GetAutocmdList()->autocmd_add()
1063<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001064 Return type: |vim9-boolean|
1065
1066
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001067autocmd_delete({acmds}) *autocmd_delete()*
1068 Deletes a List of autocmds and autocmd groups.
1069
1070 The {acmds} argument is a List where each item is a Dict with
1071 the following optional items:
1072 bufnr buffer number to delete a buffer-local autocmd.
1073 If this item is specified, then the "pattern"
1074 item is ignored.
1075 cmd Ex command for this autocmd event
1076 event autocmd event name. Refer to |autocmd-events|.
1077 If '*' then all the autocmd events in this
1078 group are deleted.
1079 group autocmd group name. Refer to |autocmd-groups|.
1080 If not specified or empty, then the default
1081 group is used.
1082 nested set to v:true for a nested autocmd.
1083 Refer to |autocmd-nested|.
1084 once set to v:true for an autocmd which executes
1085 only once. Refer to |autocmd-once|.
1086 pattern autocmd pattern string. Refer to
1087 |autocmd-patterns|. If "bufnr" item is
1088 present, then this item is ignored.
1089
1090 If only {group} is specified in a {acmds} entry and {event},
1091 {pattern} and {cmd} are not specified, then that autocmd group
1092 is deleted.
1093
Bram Moolenaar016188f2022-06-06 20:52:59 +01001094 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001095 Examples: >
1096 " :autocmd! BufLeave *.vim
1097 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1098 call autocmd_delete([acmd]})
1099 " :autocmd! MyGroup1 BufLeave
1100 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1101 call autocmd_delete([acmd])
1102 " :autocmd! MyGroup2 BufEnter *.c
1103 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1104 \ pattern: '*.c'}
1105 " :autocmd! MyGroup2 * *.c
1106 let acmd = #{group: 'MyGroup2', event: '*',
1107 \ pattern: '*.c'}
1108 call autocmd_delete([acmd])
1109 " :autocmd! MyGroup3
1110 let acmd = #{group: 'MyGroup3'}
1111 call autocmd_delete([acmd])
1112<
1113 Can also be used as a |method|: >
1114 GetAutocmdList()->autocmd_delete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001115<
1116 Return type: |vim9-boolean|
1117
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001118
1119autocmd_get([{opts}]) *autocmd_get()*
1120 Returns a |List| of autocmds. If {opts} is not supplied, then
1121 returns the autocmds for all the events in all the groups.
1122
1123 The optional {opts} Dict argument supports the following
1124 items:
1125 group Autocmd group name. If specified, returns only
1126 the autocmds defined in this group. If the
1127 specified group doesn't exist, results in an
1128 error message. If set to an empty string,
1129 then the default autocmd group is used.
1130 event Autocmd event name. If specified, returns only
1131 the autocmds defined for this event. If set
1132 to "*", then returns autocmds for all the
1133 events. If the specified event doesn't exist,
1134 results in an error message.
1135 pattern Autocmd pattern. If specified, returns only
1136 the autocmds defined for this pattern.
1137 A combination of the above three times can be supplied in
1138 {opts}.
1139
1140 Each Dict in the returned List contains the following items:
1141 bufnr For buffer-local autocmds, buffer number where
1142 the autocmd is defined.
1143 cmd Command executed for this autocmd.
1144 event Autocmd event name.
1145 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001146 nested Boolean flag, set to v:true for a nested
1147 autocmd. See |autocmd-nested|.
1148 once Boolean flag, set to v:true, if the autocmd
1149 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001150 pattern Autocmd pattern. For a buffer-local
1151 autocmd, this will be of the form "<buffer=n>".
1152 If there are multiple commands for an autocmd event in a
1153 group, then separate items are returned for each command.
1154
Bram Moolenaar016188f2022-06-06 20:52:59 +01001155 Returns an empty List if an autocmd with the specified group
1156 or event or pattern is not found.
1157
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001158 Examples: >
1159 " :autocmd MyGroup
1160 echo autocmd_get(#{group: 'Mygroup'})
1161 " :autocmd G BufUnload
1162 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1163 " :autocmd G * *.ts
1164 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1165 echo autocmd_get(acmd)
1166 " :autocmd Syntax
1167 echo autocmd_get(#{event: 'Syntax'})
1168 " :autocmd G BufEnter *.ts
1169 let acmd = #{group: 'G', event: 'BufEnter',
1170 \ pattern: '*.ts'}
1171 echo autocmd_get(acmd)
1172<
1173 Can also be used as a |method|: >
1174 Getopts()->autocmd_get()
1175<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001176 Return type: list<dict<any>>
1177
1178
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001179balloon_gettext() *balloon_gettext()*
1180 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001181 not used for the List. Returns an empty string if balloon
1182 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001183
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001184 Return type: |String|
1185
1186
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001187balloon_show({expr}) *balloon_show()*
1188 Show {expr} inside the balloon. For the GUI {expr} is used as
1189 a string. For a terminal {expr} can be a list, which contains
1190 the lines of the balloon. If {expr} is not a list it will be
1191 split with |balloon_split()|.
1192 If {expr} is an empty string any existing balloon is removed.
1193
1194 Example: >
1195 func GetBalloonContent()
1196 " ... initiate getting the content
1197 return ''
1198 endfunc
1199 set balloonexpr=GetBalloonContent()
1200
1201 func BalloonCallback(result)
1202 call balloon_show(a:result)
1203 endfunc
1204< Can also be used as a |method|: >
1205 GetText()->balloon_show()
1206<
1207 The intended use is that fetching the content of the balloon
1208 is initiated from 'balloonexpr'. It will invoke an
1209 asynchronous method, in which a callback invokes
1210 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001211 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001212
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001213 When showing a balloon is not possible then nothing happens,
1214 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001215 {only available when compiled with the |+balloon_eval| or
1216 |+balloon_eval_term| feature}
1217
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001218 Return type: |Number|
1219
1220
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001221balloon_split({msg}) *balloon_split()*
1222 Split String {msg} into lines to be displayed in a balloon.
1223 The splits are made for the current window size and optimize
1224 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001225 Returns a |List| with the split lines. Returns an empty List
1226 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001227 Can also be used as a |method|: >
1228 GetText()->balloon_split()->balloon_show()
1229
1230< {only available when compiled with the |+balloon_eval_term|
1231 feature}
1232
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001233 Return type: list<any> or list<string>
1234
h-easte80f3452025-01-02 10:40:29 +01001235base64_decode({string}) *base64_decode()*
1236 Return a Blob containing the bytes decoded from the base64
1237 encoded characters in {string}.
1238
1239 The {string} argument should contain only base64-encoded
1240 characters and should have a length that is a multiple of 4.
1241
1242 Returns an empty blob on error.
1243
1244 Examples: >
1245 " Write the decoded contents to a binary file
1246 call writefile(base64_decode(s), 'tools.bmp')
1247 " Decode a base64-encoded string
Maxim Kim6472e582025-01-15 18:31:05 +01001248 echo blob2str(base64_decode(encodedstr))
h-easte80f3452025-01-02 10:40:29 +01001249<
1250 Can also be used as a |method|: >
1251 GetEncodedString()->base64_decode()
1252<
1253 Return type: |Blob|
1254
1255
1256base64_encode({blob}) *base64_encode()*
1257 Return a base64-encoded String representing the bytes in
1258 {blob}. The base64 alphabet defined in RFC 4648 is used.
1259
1260 Examples: >
1261 " Encode the contents of a binary file
1262 echo base64_encode(readblob('somefile.bin'))
1263 " Encode a string
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001264 echo base64_encode(str2blob([somestr]))
h-easte80f3452025-01-02 10:40:29 +01001265<
1266 Can also be used as a |method|: >
1267 GetBinaryData()->base64_encode()
1268<
1269 Return type: |String|
1270
1271
Christ van Willegence0ef912024-06-20 23:41:59 +02001272bindtextdomain({package}, {path}) *bindtextdomain()*
1273 Bind a specific {package} to a {path} so that the
1274 |gettext()| function can be used to get language-specific
1275 translations for a package. {path} is the directory name
h-east52e7cc22024-07-28 17:03:29 +02001276 for the translations. See |package-translation|.
Christ van Willegence0ef912024-06-20 23:41:59 +02001277
Christ van Willegen8252ef12024-07-11 21:36:21 +02001278 Returns v:true on success and v:false on failure (out of
1279 memory).
1280
1281 Return type: |vim9-boolean|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001282
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001283blob2list({blob}) *blob2list()*
1284 Return a List containing the number value of each byte in Blob
1285 {blob}. Examples: >
1286 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1287 blob2list(0z) returns []
1288< Returns an empty List on error. |list2blob()| does the
1289 opposite.
1290
1291 Can also be used as a |method|: >
1292 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001293<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001294 Return type: list<any> or list<number>
1295
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001296
1297blob2str({blob} [, {options}]) *blob2str()*
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001298 Return a List of Strings in the current 'encoding' by
1299 converting the bytes in {blob} into characters.
1300
1301 Each <NL> byte in the blob is interpreted as the end of a
1302 string and a new list item is added. Each <NUL> byte in the
1303 blob is converted into a <NL> character.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001304
1305 If {options} is not supplied, the current 'encoding' value is
1306 used to decode the bytes in {blob}.
1307
1308 The argument {options} is a |Dict| and supports the following
1309 items:
1310 encoding Decode the bytes in {blob} using this
1311 encoding. The value is a |String|. See
Bakudankunb3854bf2025-02-23 20:29:21 +01001312 |encoding-names| for the supported values
1313 (plus the special value "none").
Christian Brabandtd5afc742025-03-18 20:55:42 +01001314 *E1515* *E1516*
Bakudankunb3854bf2025-02-23 20:29:21 +01001315 When current 'encoding' is "utf-8", an error is given and an
1316 empty List is returned if an invalid byte sequence is
1317 encountered in {blob}. To suppress this validation and get
1318 potentially invalid string, set "encoding" in {options} to
1319 "none".
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001320
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001321 Returns an empty List if blob is empty.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001322
1323 See also |str2blob()|
1324
1325 Examples: >
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001326 blob2str(0z6162) returns ["ab"]
1327 blob2str(0zC2ABC2BB) returns ["«»"]
1328 blob2str(0zABBB, {'encoding': 'latin1'}) returns ["«»"]
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001329<
1330 Can also be used as a |method|: >
1331 GetBlob()->blob2str()
1332<
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +01001333 Return type: list<string>
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +01001334
1335
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001336 *browse()*
1337browse({save}, {title}, {initdir}, {default})
1338 Put up a file requester. This only works when "has("browse")"
1339 returns |TRUE| (only in some GUI versions).
1340 The input fields are:
1341 {save} when |TRUE|, select file to write
1342 {title} title for the requester
1343 {initdir} directory to start browsing in
1344 {default} default file name
1345 An empty string is returned when the "Cancel" button is hit,
1346 something went wrong, or browsing is not possible.
1347
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001348 Return type: |String|
1349
1350
1351browsedir({title}, {initdir}) *browsedir()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001352 Put up a directory requester. This only works when
1353 "has("browse")" returns |TRUE| (only in some GUI versions).
1354 On systems where a directory browser is not supported a file
1355 browser is used. In that case: select a file in the directory
1356 to be used.
1357 The input fields are:
1358 {title} title for the requester
1359 {initdir} directory to start browsing in
1360 When the "Cancel" button is hit, something went wrong, or
1361 browsing is not possible, an empty string is returned.
1362
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001363 Return type: |String|
1364
1365
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001366bufadd({name}) *bufadd()*
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001367 Add a buffer to the buffer list with name {name} (must be a
1368 String).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001369 If a buffer for file {name} already exists, return that buffer
1370 number. Otherwise return the buffer number of the newly
1371 created buffer. When {name} is an empty string then a new
1372 buffer is always created.
1373 The buffer will not have 'buflisted' set and not be loaded
1374 yet. To add some text to the buffer use this: >
1375 let bufnr = bufadd('someName')
1376 call bufload(bufnr)
1377 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001378< Returns 0 on error.
1379 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001380 let bufnr = 'somename'->bufadd()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001381<
1382 Return type: |Number|
1383
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001384
1385bufexists({buf}) *bufexists()*
1386 The result is a Number, which is |TRUE| if a buffer called
1387 {buf} exists.
1388 If the {buf} argument is a number, buffer numbers are used.
1389 Number zero is the alternate buffer for the current window.
1390
1391 If the {buf} argument is a string it must match a buffer name
1392 exactly. The name can be:
1393 - Relative to the current directory.
1394 - A full path.
1395 - The name of a buffer with 'buftype' set to "nofile".
1396 - A URL name.
1397 Unlisted buffers will be found.
1398 Note that help files are listed by their short name in the
1399 output of |:buffers|, but bufexists() requires using their
1400 long name to be able to find them.
1401 bufexists() may report a buffer exists, but to use the name
1402 with a |:buffer| command you may need to use |expand()|. Esp
1403 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1404 Use "bufexists(0)" to test for the existence of an alternate
1405 file name.
1406
1407 Can also be used as a |method|: >
1408 let exists = 'somename'->bufexists()
1409<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001410 Return type: |Number|
1411
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001412 Obsolete name: buffer_exists(). *buffer_exists()*
1413
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001414
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001415buflisted({buf}) *buflisted()*
1416 The result is a Number, which is |TRUE| if a buffer called
1417 {buf} exists and is listed (has the 'buflisted' option set).
1418 The {buf} argument is used like with |bufexists()|.
1419
1420 Can also be used as a |method|: >
1421 let listed = 'somename'->buflisted()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001422<
1423 Return type: |Number|
1424
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001425
1426bufload({buf}) *bufload()*
1427 Ensure the buffer {buf} is loaded. When the buffer name
1428 refers to an existing file then the file is read. Otherwise
1429 the buffer will be empty. If the buffer was already loaded
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001430 then there is no change. If the buffer is not related to a
Daniel Steinbergc2bd2052023-08-09 12:10:59 -04001431 file then no file is read (e.g., when 'buftype' is "nofile").
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001432 If there is an existing swap file for the file of the buffer,
1433 there will be no dialog, the buffer will be loaded anyway.
1434 The {buf} argument is used like with |bufexists()|.
1435
1436 Can also be used as a |method|: >
1437 eval 'somename'->bufload()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001438<
1439 Return type: |Number|
1440
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001441
1442bufloaded({buf}) *bufloaded()*
1443 The result is a Number, which is |TRUE| if a buffer called
1444 {buf} exists and is loaded (shown in a window or hidden).
1445 The {buf} argument is used like with |bufexists()|.
1446
1447 Can also be used as a |method|: >
1448 let loaded = 'somename'->bufloaded()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001449<
1450 Return type: |Number|
1451
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001452
1453bufname([{buf}]) *bufname()*
1454 The result is the name of a buffer. Mostly as it is displayed
1455 by the `:ls` command, but not using special names such as
1456 "[No Name]".
1457 If {buf} is omitted the current buffer is used.
1458 If {buf} is a Number, that buffer number's name is given.
1459 Number zero is the alternate buffer for the current window.
1460 If {buf} is a String, it is used as a |file-pattern| to match
1461 with the buffer names. This is always done like 'magic' is
1462 set and 'cpoptions' is empty. When there is more than one
1463 match an empty string is returned.
1464 "" or "%" can be used for the current buffer, "#" for the
1465 alternate buffer.
1466 A full match is preferred, otherwise a match at the start, end
1467 or middle of the buffer name is accepted. If you only want a
1468 full match then put "^" at the start and "$" at the end of the
1469 pattern.
1470 Listed buffers are found first. If there is a single match
1471 with a listed buffer, that one is returned. Next unlisted
1472 buffers are searched for.
1473 If the {buf} is a String, but you want to use it as a buffer
1474 number, force it to be a Number by adding zero to it: >
1475 :echo bufname("3" + 0)
1476< Can also be used as a |method|: >
1477 echo bufnr->bufname()
1478
1479< If the buffer doesn't exist, or doesn't have a name, an empty
1480 string is returned. >
1481 bufname("#") alternate buffer name
1482 bufname(3) name of buffer 3
1483 bufname("%") name of current buffer
1484 bufname("file2") name of buffer where "file2" matches.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001485<
1486 Return type: |String|
1487 *buffer_name()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001488 Obsolete name: buffer_name().
1489
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001490
1491bufnr([{buf} [, {create}]]) *bufnr()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001492 The result is the number of a buffer, as it is displayed by
1493 the `:ls` command. For the use of {buf}, see |bufname()|
1494 above.
1495
1496 If the buffer doesn't exist, -1 is returned. Or, if the
1497 {create} argument is present and TRUE, a new, unlisted,
1498 buffer is created and its number is returned. Example: >
1499 let newbuf = bufnr('Scratch001', 1)
1500< Using an empty name uses the current buffer. To create a new
1501 buffer with an empty name use |bufadd()|.
1502
1503 bufnr("$") is the last buffer: >
1504 :let last_buffer = bufnr("$")
1505< The result is a Number, which is the highest buffer number
1506 of existing buffers. Note that not all buffers with a smaller
1507 number necessarily exist, because ":bwipeout" may have removed
1508 them. Use bufexists() to test for the existence of a buffer.
1509
1510 Can also be used as a |method|: >
1511 echo bufref->bufnr()
1512<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001513 Return type: |Number|
1514
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001515 Obsolete name: buffer_number(). *buffer_number()*
1516 *last_buffer_nr()*
1517 Obsolete name for bufnr("$"): last_buffer_nr().
1518
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001519
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001520bufwinid({buf}) *bufwinid()*
1521 The result is a Number, which is the |window-ID| of the first
1522 window associated with buffer {buf}. For the use of {buf},
1523 see |bufname()| above. If buffer {buf} doesn't exist or
1524 there is no such window, -1 is returned. Example: >
1525
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001526 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001527<
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001528 Only deals with the current tab page. See |win_findbuf()| for
1529 finding more.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001530
1531 Can also be used as a |method|: >
1532 FindBuffer()->bufwinid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001533<
1534 Return type: |Number|
1535
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001536
1537bufwinnr({buf}) *bufwinnr()*
1538 Like |bufwinid()| but return the window number instead of the
1539 |window-ID|.
1540 If buffer {buf} doesn't exist or there is no such window, -1
1541 is returned. Example: >
1542
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001543 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001544
1545< The number can be used with |CTRL-W_w| and ":wincmd w"
1546 |:wincmd|.
1547
1548 Can also be used as a |method|: >
1549 FindBuffer()->bufwinnr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001550<
1551 Return type: |Number|
1552
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001553
1554byte2line({byte}) *byte2line()*
1555 Return the line number that contains the character at byte
1556 count {byte} in the current buffer. This includes the
1557 end-of-line character, depending on the 'fileformat' option
1558 for the current buffer. The first character has byte count
1559 one.
1560 Also see |line2byte()|, |go| and |:goto|.
1561
Bram Moolenaar016188f2022-06-06 20:52:59 +01001562 Returns -1 if the {byte} value is invalid.
1563
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001564 Can also be used as a |method|: >
1565 GetOffset()->byte2line()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001566<
1567 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001568
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001569 {not available when compiled without the |+byte_offset|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001570 feature}
1571
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001572
Christian Brabandt67672ef2023-04-24 21:09:54 +01001573byteidx({expr}, {nr} [, {utf16}]) *byteidx()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001574 Return byte index of the {nr}'th character in the String
1575 {expr}. Use zero for the first character, it then returns
1576 zero.
1577 If there are no multibyte characters the returned value is
1578 equal to {nr}.
1579 Composing characters are not counted separately, their byte
1580 length is added to the preceding base character. See
1581 |byteidxcomp()| below for counting composing characters
1582 separately.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001583 When {utf16} is present and TRUE, {nr} is used as the UTF-16
1584 index in the String {expr} instead of as the character index.
1585 The UTF-16 index is the index in the string when it is encoded
1586 with 16-bit words. If the specified UTF-16 index is in the
1587 middle of a character (e.g. in a 4-byte character), then the
1588 byte index of the first byte in the character is returned.
1589 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001590 Example : >
1591 echo matchstr(str, ".", byteidx(str, 3))
1592< will display the fourth character. Another way to do the
1593 same: >
1594 let s = strpart(str, byteidx(str, 3))
1595 echo strpart(s, 0, byteidx(s, 1))
1596< Also see |strgetchar()| and |strcharpart()|.
1597
1598 If there are less than {nr} characters -1 is returned.
1599 If there are exactly {nr} characters the length of the string
1600 in bytes is returned.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001601 See |charidx()| and |utf16idx()| for getting the character and
1602 UTF-16 index respectively from the byte index.
1603 Examples: >
1604 echo byteidx('a😊😊', 2) returns 5
1605 echo byteidx('a😊😊', 2, 1) returns 1
1606 echo byteidx('a😊😊', 3, 1) returns 5
1607<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001608 Can also be used as a |method|: >
1609 GetName()->byteidx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001610<
1611 Return type: |Number|
1612
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001613
Christian Brabandt67672ef2023-04-24 21:09:54 +01001614byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001615 Like byteidx(), except that a composing character is counted
1616 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001617 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001618 echo byteidx(s, 1)
1619 echo byteidxcomp(s, 1)
1620 echo byteidxcomp(s, 2)
1621< The first and third echo result in 3 ('e' plus composing
1622 character is 3 bytes), the second echo results in 1 ('e' is
1623 one byte).
1624 Only works differently from byteidx() when 'encoding' is set
1625 to a Unicode encoding.
1626
1627 Can also be used as a |method|: >
1628 GetName()->byteidxcomp(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001629<
1630 Return type: |Number|
1631
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001632
1633call({func}, {arglist} [, {dict}]) *call()* *E699*
1634 Call function {func} with the items in |List| {arglist} as
1635 arguments.
1636 {func} can either be a |Funcref| or the name of a function.
1637 a:firstline and a:lastline are set to the cursor line.
1638 Returns the return value of the called function.
1639 {dict} is for functions with the "dict" attribute. It will be
1640 used to set the local variable "self". |Dictionary-function|
1641
1642 Can also be used as a |method|: >
1643 GetFunc()->call([arg, arg], dict)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001644<
1645 Return type: any, depending on {func}
1646
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001647
1648ceil({expr}) *ceil()*
1649 Return the smallest integral value greater than or equal to
1650 {expr} as a |Float| (round up).
1651 {expr} must evaluate to a |Float| or a |Number|.
1652 Examples: >
1653 echo ceil(1.456)
1654< 2.0 >
1655 echo ceil(-5.456)
1656< -5.0 >
1657 echo ceil(4.0)
1658< 4.0
1659
Bram Moolenaar016188f2022-06-06 20:52:59 +01001660 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1661
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001662 Can also be used as a |method|: >
1663 Compute()->ceil()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001664<
1665 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001666
1667
1668ch_ functions are documented here: |channel-functions-details|
1669
1670
1671changenr() *changenr()*
1672 Return the number of the most recent change. This is the same
1673 number as what is displayed with |:undolist| and can be used
1674 with the |:undo| command.
1675 When a change was made it is the number of that change. After
1676 redo it is the number of the redone change. After undo it is
1677 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001678 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001679
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001680 Return type: |Number|
1681
1682
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001683char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001684 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001685 Examples: >
1686 char2nr(" ") returns 32
1687 char2nr("ABC") returns 65
1688< When {utf8} is omitted or zero, the current 'encoding' is used.
1689 Example for "utf-8": >
1690 char2nr("á") returns 225
1691 char2nr("á"[0]) returns 195
1692< When {utf8} is TRUE, always treat as UTF-8 characters.
1693 A combining character is a separate character.
1694 |nr2char()| does the opposite.
1695 To turn a string into a list of character numbers: >
1696 let str = "ABC"
1697 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1698< Result: [65, 66, 67]
1699
Bram Moolenaar016188f2022-06-06 20:52:59 +01001700 Returns 0 if {string} is not a |String|.
1701
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001702 Can also be used as a |method|: >
1703 GetChar()->char2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001704<
1705 Return type: |Number|
1706
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001707
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001708charclass({string}) *charclass()*
1709 Return the character class of the first character in {string}.
1710 The character class is one of:
1711 0 blank
1712 1 punctuation
Christian Brabandtb5e7da12024-11-01 09:33:00 +01001713 2 word character (depends on 'iskeyword')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001714 3 emoji
1715 other specific Unicode class
1716 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001717 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001718
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001719 Return type: |Number|
1720
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001721
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001722charcol({expr} [, {winid}]) *charcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001723 Same as |col()| but returns the character index of the column
1724 position given with {expr} instead of the byte position.
1725
1726 Example:
1727 With the cursor on '세' in line 5 with text "여보세요": >
1728 charcol('.') returns 3
1729 col('.') returns 7
1730
1731< Can also be used as a |method|: >
1732 GetPos()->col()
1733<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001734 Return type: |Number|
1735
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001736 *charidx()*
Christian Brabandt67672ef2023-04-24 21:09:54 +01001737charidx({string}, {idx} [, {countcc} [, {utf16}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001738 Return the character index of the byte at {idx} in {string}.
1739 The index of the first character is zero.
1740 If there are no multibyte characters the returned value is
1741 equal to {idx}.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001742
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001743 When {countcc} is omitted or |FALSE|, then composing characters
Christian Brabandt67672ef2023-04-24 21:09:54 +01001744 are not counted separately, their byte length is added to the
1745 preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001746 When {countcc} is |TRUE|, then composing characters are
1747 counted as separate characters.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001748
1749 When {utf16} is present and TRUE, {idx} is used as the UTF-16
1750 index in the String {expr} instead of as the byte index.
1751
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +01001752 Returns -1 if the arguments are invalid or if there are less
1753 than {idx} bytes. If there are exactly {idx} bytes the length
1754 of the string in characters is returned.
1755
1756 An error is given and -1 is returned if the first argument is
1757 not a string, the second argument is not a number or when the
1758 third argument is present and is not zero or one.
Christian Brabandt67672ef2023-04-24 21:09:54 +01001759
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001760 See |byteidx()| and |byteidxcomp()| for getting the byte index
Christian Brabandt67672ef2023-04-24 21:09:54 +01001761 from the character index and |utf16idx()| for getting the
1762 UTF-16 index from the character index.
1763 Refer to |string-offset-encoding| for more information.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001764 Examples: >
1765 echo charidx('áb́ć', 3) returns 1
1766 echo charidx('áb́ć', 6, 1) returns 4
1767 echo charidx('áb́ć', 16) returns -1
Christian Brabandt67672ef2023-04-24 21:09:54 +01001768 echo charidx('a😊😊', 4, 0, 1) returns 2
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001769<
1770 Can also be used as a |method|: >
1771 GetName()->charidx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001772<
1773 Return type: |Number|
1774
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001775
1776chdir({dir}) *chdir()*
1777 Change the current working directory to {dir}. The scope of
1778 the directory change depends on the directory of the current
1779 window:
1780 - If the current window has a window-local directory
1781 (|:lcd|), then changes the window local directory.
1782 - Otherwise, if the current tabpage has a local
1783 directory (|:tcd|) then changes the tabpage local
1784 directory.
1785 - Otherwise, changes the global directory.
1786 {dir} must be a String.
1787 If successful, returns the previous working directory. Pass
1788 this to another chdir() to restore the directory.
1789 On failure, returns an empty string.
1790
1791 Example: >
1792 let save_dir = chdir(newdir)
1793 if save_dir != ""
1794 " ... do some work
1795 call chdir(save_dir)
1796 endif
1797
1798< Can also be used as a |method|: >
1799 GetDir()->chdir()
1800<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001801 Return type: |String|
1802
1803
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001804cindent({lnum}) *cindent()*
1805 Get the amount of indent for line {lnum} according the C
1806 indenting rules, as with 'cindent'.
1807 The indent is counted in spaces, the value of 'tabstop' is
1808 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001809 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001810 See |C-indenting|.
1811
1812 Can also be used as a |method|: >
1813 GetLnum()->cindent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001814<
1815 Return type: |Number|
1816
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001817
1818clearmatches([{win}]) *clearmatches()*
1819 Clears all matches previously defined for the current window
1820 by |matchadd()| and the |:match| commands.
1821 If {win} is specified, use the window with this number or
1822 window ID instead of the current window.
1823
1824 Can also be used as a |method|: >
1825 GetWin()->clearmatches()
1826<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001827 Return type: |Number|
1828
1829
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001830col({expr} [, {winid}]) *col()*
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001831 The result is a Number, which is the byte index of the column
zeertzjq02f3eba2024-06-12 20:45:24 +02001832 position given with {expr}.
1833 For accepted positions see |getpos()|.
zeertzjqd353d272024-06-13 23:00:25 +08001834 When {expr} is "$", it means the end of the cursor line, so
1835 the result is the number of bytes in the cursor line plus one.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001836 Additionally {expr} can be [lnum, col]: a |List| with the line
1837 and column number. Most useful when the column is "$", to get
1838 the last column of a specific line. When "lnum" or "col" is
1839 out of range then col() returns zero.
zeertzjq02f3eba2024-06-12 20:45:24 +02001840
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001841 With the optional {winid} argument the values are obtained for
1842 that window instead of the current window.
zeertzjq02f3eba2024-06-12 20:45:24 +02001843
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001844 To get the line number use |line()|. To get both use
1845 |getpos()|.
1846 For the screen column position use |virtcol()|. For the
1847 character position use |charcol()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02001848
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001849 Note that only marks in the current file can be used.
zeertzjq02f3eba2024-06-12 20:45:24 +02001850
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001851 Examples: >
1852 col(".") column of cursor
1853 col("$") length of cursor line plus one
1854 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001855 col("'" .. markname) column of mark markname
zeertzjq02f3eba2024-06-12 20:45:24 +02001856<
1857 The first column is 1. Returns 0 if {expr} is invalid or when
Yegappan Lakshmanan4c8d2f02022-11-12 16:07:47 +00001858 the window with ID {winid} is not found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001859 For an uppercase mark the column may actually be in another
1860 buffer.
1861 For the cursor position, when 'virtualedit' is active, the
1862 column is one higher if the cursor is after the end of the
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01001863 line. Also, when using a <Cmd> mapping the cursor isn't
1864 moved, this can be used to obtain the column in Insert mode: >
Bram Moolenaar76db9e02022-11-09 21:21:04 +00001865 :imap <F2> <Cmd>echowin col(".")<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001866
1867< Can also be used as a |method|: >
1868 GetPos()->col()
1869<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001870 Return type: |Number|
1871
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001872
1873complete({startcol}, {matches}) *complete()* *E785*
1874 Set the matches for Insert mode completion.
1875 Can only be used in Insert mode. You need to use a mapping
1876 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1877 or with an expression mapping.
1878 {startcol} is the byte offset in the line where the completed
1879 text start. The text up to the cursor is the original text
1880 that will be replaced by the matches. Use col('.') for an
1881 empty string. "col('.') - 1" will replace one character by a
1882 match.
1883 {matches} must be a |List|. Each |List| item is one match.
1884 See |complete-items| for the kind of items that are possible.
1885 "longest" in 'completeopt' is ignored.
1886 Note that the after calling this function you need to avoid
1887 inserting anything that would cause completion to stop.
1888 The match can be selected with CTRL-N and CTRL-P as usual with
1889 Insert mode completion. The popup menu will appear if
1890 specified, see |ins-completion-menu|.
1891 Example: >
1892 inoremap <F5> <C-R>=ListMonths()<CR>
1893
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001894 func ListMonths()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001895 call complete(col('.'), ['January', 'February', 'March',
1896 \ 'April', 'May', 'June', 'July', 'August', 'September',
1897 \ 'October', 'November', 'December'])
1898 return ''
1899 endfunc
1900< This isn't very useful, but it shows how it works. Note that
1901 an empty string is returned to avoid a zero being inserted.
1902
1903 Can also be used as a |method|, the base is passed as the
1904 second argument: >
1905 GetMatches()->complete(col('.'))
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001906<
1907 Return type: |Number|
1908
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001909
1910complete_add({expr}) *complete_add()*
1911 Add {expr} to the list of matches. Only to be used by the
1912 function specified with the 'completefunc' option.
1913 Returns 0 for failure (empty string or out of memory),
1914 1 when the match was added, 2 when the match was already in
1915 the list.
1916 See |complete-functions| for an explanation of {expr}. It is
1917 the same as one item in the list that 'omnifunc' would return.
1918
1919 Can also be used as a |method|: >
1920 GetMoreMatches()->complete_add()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001921<
1922 Return type: |Number|
1923
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001924
1925complete_check() *complete_check()*
1926 Check for a key typed while looking for completion matches.
1927 This is to be used when looking for matches takes some time.
1928 Returns |TRUE| when searching for matches is to be aborted,
1929 zero otherwise.
1930 Only to be used by the function specified with the
1931 'completefunc' option.
1932
Christian Brabandt5674c9a2024-06-09 00:13:43 +02001933 Return type: |Number|
1934
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001935
1936complete_info([{what}]) *complete_info()*
1937 Returns a |Dictionary| with information about Insert mode
1938 completion. See |ins-completion|.
1939 The items are:
1940 mode Current completion mode name string.
1941 See |complete_info_mode| for the values.
1942 pum_visible |TRUE| if popup menu is visible.
1943 See |pumvisible()|.
glepnird4088ed2024-12-31 10:55:22 +01001944 items List of all completion candidates. Each item
1945 is a dictionary containing the entries "word",
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001946 "abbr", "menu", "kind", "info" and "user_data".
1947 See |complete-items|.
glepnird4088ed2024-12-31 10:55:22 +01001948 matches Same as "items", but only returns items that
1949 are matching current query. If both "matches"
1950 and "items" are in "what", the returned list
1951 will still be named "items", but each item
1952 will have an additional "match" field.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001953 selected Selected item index. First index is zero.
1954 Index is -1 if no item is selected (showing
1955 typed text only, or the last completion after
1956 no item is selected when using the <Up> or
1957 <Down> keys)
glepnir037b0282025-01-16 14:37:44 +01001958 completed Return a dictionary containing the entries of
1959 the currently selected index item.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001960
1961 *complete_info_mode*
1962 mode values are:
1963 "" Not in completion mode
1964 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1965 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1966 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1967 |i_CTRL-X_CTRL-Y|
1968 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1969 "files" File names |i_CTRL-X_CTRL-F|
1970 "tags" Tags |i_CTRL-X_CTRL-]|
1971 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1972 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1973 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1974 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1975 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1976 "function" User defined completion |i_CTRL-X_CTRL-U|
1977 "omni" Omni completion |i_CTRL-X_CTRL-O|
1978 "spell" Spelling suggestions |i_CTRL-X_s|
1979 "eval" |complete()| completion
1980 "unknown" Other internal modes
1981
1982 If the optional {what} list argument is supplied, then only
1983 the items listed in {what} are returned. Unsupported items in
1984 {what} are silently ignored.
1985
1986 To get the position and size of the popup menu, see
1987 |pum_getpos()|. It's also available in |v:event| during the
1988 |CompleteChanged| event.
1989
Bram Moolenaar016188f2022-06-06 20:52:59 +01001990 Returns an empty |Dictionary| on error.
1991
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001992 Examples: >
1993 " Get all items
1994 call complete_info()
1995 " Get only 'mode'
1996 call complete_info(['mode'])
1997 " Get only 'mode' and 'pum_visible'
1998 call complete_info(['mode', 'pum_visible'])
1999
2000< Can also be used as a |method|: >
2001 GetItems()->complete_info()
2002<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002003 Return type: dict<any>
2004
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002005 *confirm()*
2006confirm({msg} [, {choices} [, {default} [, {type}]]])
2007 confirm() offers the user a dialog, from which a choice can be
2008 made. It returns the number of the choice. For the first
2009 choice this is 1.
2010 Note: confirm() is only supported when compiled with dialog
glepnirdf461152024-04-04 22:23:29 +02002011 support, see |+dialog_con| |+dialog_con_gui| and |+dialog_gui|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002012
2013 {msg} is displayed in a |dialog| with {choices} as the
2014 alternatives. When {choices} is missing or empty, "&OK" is
2015 used (and translated).
2016 {msg} is a String, use '\n' to include a newline. Only on
2017 some systems the string is wrapped when it doesn't fit.
2018
2019 {choices} is a String, with the individual choices separated
2020 by '\n', e.g. >
2021 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2022< The letter after the '&' is the shortcut key for that choice.
2023 Thus you can type 'c' to select "Cancel". The shortcut does
2024 not need to be the first letter: >
2025 confirm("file has been modified", "&Save\nSave &All")
2026< For the console, the first letter of each choice is used as
2027 the default shortcut key. Case is ignored.
2028
2029 The optional {default} argument is the number of the choice
2030 that is made if the user hits <CR>. Use 1 to make the first
2031 choice the default one. Use 0 to not set a default. If
2032 {default} is omitted, 1 is used.
2033
2034 The optional {type} String argument gives the type of dialog.
2035 This is only used for the icon of the GTK, Mac, Motif and
2036 Win32 GUI. It can be one of these values: "Error",
2037 "Question", "Info", "Warning" or "Generic". Only the first
2038 character is relevant. When {type} is omitted, "Generic" is
2039 used.
2040
2041 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2042 or another valid interrupt key, confirm() returns 0.
2043
2044 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01002045 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002046 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01002047 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002048 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01002049 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002050 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01002051 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002052 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01002053 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002054< In a GUI dialog, buttons are used. The layout of the buttons
2055 depends on the 'v' flag in 'guioptions'. If it is included,
2056 the buttons are always put vertically. Otherwise, confirm()
2057 tries to put the buttons in one horizontal line. If they
2058 don't fit, a vertical layout is used anyway. For some systems
2059 the horizontal layout is always used.
2060
2061 Can also be used as a |method|in: >
2062 BuildMessage()->confirm("&Yes\n&No")
2063<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002064 Return type: |Number|
2065
2066
2067copy({expr}) *copy()*
2068 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002069 different from using {expr} directly.
2070 When {expr} is a |List| a shallow copy is created. This means
2071 that the original |List| can be changed without changing the
2072 copy, and vice versa. But the items are identical, thus
2073 changing an item changes the contents of both |Lists|.
2074 A |Dictionary| is copied in a similar way as a |List|.
2075 Also see |deepcopy()|.
2076 Can also be used as a |method|: >
2077 mylist->copy()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002078<
2079 Return type: any, depending on {expr}
2080
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002081
2082cos({expr}) *cos()*
2083 Return the cosine of {expr}, measured in radians, as a |Float|.
2084 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002085 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002086 Examples: >
2087 :echo cos(100)
2088< 0.862319 >
2089 :echo cos(-4.01)
2090< -0.646043
2091
2092 Can also be used as a |method|: >
2093 Compute()->cos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002094<
2095 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002096
2097
2098cosh({expr}) *cosh()*
2099 Return the hyperbolic cosine of {expr} as a |Float| in the range
2100 [1, inf].
2101 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002102 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002103 Examples: >
2104 :echo cosh(0.5)
2105< 1.127626 >
2106 :echo cosh(-0.5)
2107< -1.127626
2108
2109 Can also be used as a |method|: >
2110 Compute()->cosh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002111<
2112 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002113
2114
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07002115count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002116 Return the number of times an item with value {expr} appears
2117 in |String|, |List| or |Dictionary| {comp}.
2118
2119 If {start} is given then start with the item with this index.
2120 {start} can only be used with a |List|.
2121
2122 When {ic} is given and it's |TRUE| then case is ignored.
2123
2124 When {comp} is a string then the number of not overlapping
2125 occurrences of {expr} is returned. Zero is returned when
2126 {expr} is an empty string.
2127
2128 Can also be used as a |method|: >
2129 mylist->count(val)
2130<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002131 Return type: |Number|
2132
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002133 *cscope_connection()*
2134cscope_connection([{num} , {dbpath} [, {prepend}]])
2135 Checks for the existence of a |cscope| connection. If no
2136 parameters are specified, then the function returns:
2137 0, if cscope was not available (not compiled in), or
2138 if there are no cscope connections;
2139 1, if there is at least one cscope connection.
2140
2141 If parameters are specified, then the value of {num}
2142 determines how existence of a cscope connection is checked:
2143
2144 {num} Description of existence check
2145 ----- ------------------------------
2146 0 Same as no parameters (e.g., "cscope_connection()").
2147 1 Ignore {prepend}, and use partial string matches for
2148 {dbpath}.
2149 2 Ignore {prepend}, and use exact string matches for
2150 {dbpath}.
2151 3 Use {prepend}, use partial string matches for both
2152 {dbpath} and {prepend}.
2153 4 Use {prepend}, use exact string matches for both
2154 {dbpath} and {prepend}.
2155
2156 Note: All string comparisons are case sensitive!
2157
2158 Examples. Suppose we had the following (from ":cs show"): >
2159
2160 # pid database name prepend path
2161 0 27664 cscope.out /usr/local
2162<
2163 Invocation Return Val ~
2164 ---------- ---------- >
2165 cscope_connection() 1
2166 cscope_connection(1, "out") 1
2167 cscope_connection(2, "out") 0
2168 cscope_connection(3, "out") 0
2169 cscope_connection(3, "out", "local") 1
2170 cscope_connection(4, "out") 0
2171 cscope_connection(4, "out", "local") 0
2172 cscope_connection(4, "cscope.out", "/usr/local") 1
2173<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002174 Return type: |Number|
2175
2176
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002177cursor({lnum}, {col} [, {off}]) *cursor()*
2178cursor({list})
2179 Positions the cursor at the column (byte count) {col} in the
2180 line {lnum}. The first column is one.
2181
2182 When there is one argument {list} this is used as a |List|
2183 with two, three or four item:
2184 [{lnum}, {col}]
2185 [{lnum}, {col}, {off}]
2186 [{lnum}, {col}, {off}, {curswant}]
2187 This is like the return value of |getpos()| or |getcurpos()|,
2188 but without the first item.
2189
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01002190 To position the cursor using {col} as the character count, use
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002191 |setcursorcharpos()|.
2192
2193 Does not change the jumplist.
Bram Moolenaar7c6cd442022-10-11 21:54:04 +01002194 {lnum} is used like with |getline()|, except that if {lnum} is
2195 zero, the cursor will stay in the current line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002196 If {lnum} is greater than the number of lines in the buffer,
2197 the cursor will be positioned at the last line in the buffer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002198 If {col} is greater than the number of bytes in the line,
2199 the cursor will be positioned at the last character in the
2200 line.
2201 If {col} is zero, the cursor will stay in the current column.
2202 If {curswant} is given it is used to set the preferred column
2203 for vertical movement. Otherwise {col} is used.
2204
2205 When 'virtualedit' is used {off} specifies the offset in
2206 screen columns from the start of the character. E.g., a
2207 position within a <Tab> or after the last character.
2208 Returns 0 when the position could be set, -1 otherwise.
2209
2210 Can also be used as a |method|: >
2211 GetCursorPos()->cursor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002212<
2213 Return type: |Number|
2214
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002215
2216debugbreak({pid}) *debugbreak()*
2217 Specifically used to interrupt a program being debugged. It
2218 will cause process {pid} to get a SIGTRAP. Behavior for other
2219 processes is undefined. See |terminal-debugger|.
2220 {only available on MS-Windows}
2221
Bram Moolenaar016188f2022-06-06 20:52:59 +01002222 Returns |TRUE| if successfully interrupted the program.
2223 Otherwise returns |FALSE|.
2224
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002225 Can also be used as a |method|: >
2226 GetPid()->debugbreak()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002227<
2228 Return type: |Number|
2229
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002230
2231deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
2232 Make a copy of {expr}. For Numbers and Strings this isn't
2233 different from using {expr} directly.
2234 When {expr} is a |List| a full copy is created. This means
2235 that the original |List| can be changed without changing the
2236 copy, and vice versa. When an item is a |List| or
2237 |Dictionary|, a copy for it is made, recursively. Thus
2238 changing an item in the copy does not change the contents of
2239 the original |List|.
2240 A |Dictionary| is copied in a similar way as a |List|.
2241
2242 When {noref} is omitted or zero a contained |List| or
2243 |Dictionary| is only copied once. All references point to
2244 this single copy. With {noref} set to 1 every occurrence of a
2245 |List| or |Dictionary| results in a new copy. This also means
2246 that a cyclic reference causes deepcopy() to fail.
2247 *E724*
2248 Nesting is possible up to 100 levels. When there is an item
2249 that refers back to a higher level making a deep copy with
2250 {noref} set to 1 will fail.
2251 Also see |copy()|.
2252
2253 Can also be used as a |method|: >
2254 GetObject()->deepcopy()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002255<
2256 Return type: any, depending on {expr}
2257
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002258
2259delete({fname} [, {flags}]) *delete()*
2260 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002261 name {fname}.
2262
2263 This also works when {fname} is a symbolic link. The symbolic
2264 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002265
2266 When {flags} is "d": Deletes the directory by the name
2267 {fname}. This fails when directory {fname} is not empty.
2268
2269 When {flags} is "rf": Deletes the directory by the name
2270 {fname} and everything in it, recursively. BE CAREFUL!
2271 Note: on MS-Windows it is not possible to delete a directory
2272 that is being used.
2273
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002274 The result is a Number, which is 0/false if the delete
2275 operation was successful and -1/true when the deletion failed
2276 or partly failed.
2277
2278 Use |remove()| to delete an item from a |List|.
2279 To delete a line from the buffer use |:delete| or
2280 |deletebufline()|.
2281
2282 Can also be used as a |method|: >
2283 GetName()->delete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002284<
2285 Return type: |Number|
2286
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002287
2288deletebufline({buf}, {first} [, {last}]) *deletebufline()*
2289 Delete lines {first} to {last} (inclusive) from buffer {buf}.
2290 If {last} is omitted then delete line {first} only.
2291 On success 0 is returned, on failure 1 is returned.
2292
2293 This function works only for loaded buffers. First call
2294 |bufload()| if needed.
2295
2296 For the use of {buf}, see |bufname()| above.
2297
2298 {first} and {last} are used like with |getline()|. Note that
2299 when using |line()| this refers to the current buffer. Use "$"
2300 to refer to the last line in buffer {buf}.
2301
2302 Can also be used as a |method|: >
2303 GetBuffer()->deletebufline(1)
2304<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002305 Return type: |Number|
2306
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002307 *did_filetype()*
2308did_filetype() Returns |TRUE| when autocommands are being executed and the
2309 FileType event has been triggered at least once. Can be used
2310 to avoid triggering the FileType event again in the scripts
2311 that detect the file type. |FileType|
2312 Returns |FALSE| when `:setf FALLBACK` was used.
2313 When editing another file, the counter is reset, thus this
2314 really checks if the FileType event has been triggered for the
2315 current buffer. This allows an autocommand that starts
2316 editing another buffer to set 'filetype' and load a syntax
2317 file.
2318
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002319 Return type: |Number|
2320
2321
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002322diff({fromlist}, {tolist} [, {options}]) *diff()*
2323 Returns a String or a List containing the diff between the
2324 strings in {fromlist} and {tolist}. Uses the Vim internal
2325 diff library to compute the diff.
2326
2327 *E106*
2328 The optional "output" item in {options} specifies the returned
2329 diff format. The following values are supported:
2330 indices Return a List of the starting and ending
2331 indices and a count of the strings in each
2332 diff hunk.
2333 unified Return the unified diff output as a String.
2334 This is the default.
2335
2336 If the "output" item in {options} is "indices", then a List is
2337 returned. Each List item contains a Dict with the following
2338 items for each diff hunk:
2339 from_idx start index in {fromlist} for this diff hunk.
2340 from_count number of strings in {fromlist} that are
2341 added/removed/modified in this diff hunk.
2342 to_idx start index in {tolist} for this diff hunk.
2343 to_count number of strings in {tolist} that are
2344 added/removed/modified in this diff hunk.
2345
2346 The {options} Dict argument also specifies diff options
2347 (similar to 'diffopt') and supports the following items:
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002348 algorithm Dict specifying the diff algorithm to
2349 use. Supported boolean items are
2350 "myers", "minimal", "patience" and
2351 "histogram".
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002352 context diff context length. Default is 0.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002353 iblank ignore changes where lines are all
2354 blank.
2355 icase ignore changes in case of text.
Yegappan Lakshmananbe156a32024-02-11 17:08:29 +01002356 indent-heuristic use the indent heuristic for the
2357 internal diff library.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002358 iwhite ignore changes in amount of white
2359 space.
2360 iwhiteall ignore all white space changes.
2361 iwhiteeol ignore white space changes at end of
2362 line.
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002363 For more information about these options, refer to 'diffopt'.
2364
Yegappan Lakshmanana0010a12024-02-12 20:21:26 +01002365 To compute the unified diff, all the items in {fromlist} are
2366 concatenated into a string using a newline separator and the
2367 same for {tolist}. The unified diff output uses line numbers.
2368
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002369 Returns an empty List or String if {fromlist} and {tolist} are
2370 identical.
2371
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002372 Examples: >
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002373 :echo diff(['abc'], ['xxx'])
2374 @@ -1 +1 @@
2375 -abc
2376 +xxx
2377
2378 :echo diff(['abc'], ['xxx'], {'output': 'indices'})
2379 [{'from_idx': 0, 'from_count': 1, 'to_idx': 0, 'to_count': 1}]
2380 :echo diff(readfile('oldfile'), readfile('newfile'))
2381 :echo diff(getbufline(5, 1, '$'), getbufline(6, 1, '$'))
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +01002382<
Yegappan Lakshmananfa378352024-02-01 22:05:27 +01002383 For more examples, refer to |diff-func-examples|
2384
2385 Can also be used as a |method|: >
2386 GetFromList->diff(to_list)
2387<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002388 Return type: |String| or list<dict<number>> or list<any>
2389 depending on {options}
2390
2391
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002392diff_filler({lnum}) *diff_filler()*
2393 Returns the number of filler lines above line {lnum}.
2394 These are the lines that were inserted at this point in
2395 another diff'ed window. These filler lines are shown in the
2396 display but don't exist in the buffer.
2397 {lnum} is used like with |getline()|. Thus "." is the current
2398 line, "'m" mark m, etc.
2399 Returns 0 if the current window is not in diff mode.
2400
2401 Can also be used as a |method|: >
2402 GetLnum()->diff_filler()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002403<
2404 Return type: |Number|
2405
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002406
2407diff_hlID({lnum}, {col}) *diff_hlID()*
2408 Returns the highlight ID for diff mode at line {lnum} column
2409 {col} (byte index). When the current line does not have a
2410 diff change zero is returned.
2411 {lnum} is used like with |getline()|. Thus "." is the current
2412 line, "'m" mark m, etc.
2413 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2414 line.
2415 The highlight ID can be used with |synIDattr()| to obtain
2416 syntax information about the highlighting.
2417
2418 Can also be used as a |method|: >
2419 GetLnum()->diff_hlID(col)
2420<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002421 Return type: |Number|
2422
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002423
2424digraph_get({chars}) *digraph_get()* *E1214*
2425 Return the digraph of {chars}. This should be a string with
2426 exactly two characters. If {chars} are not just two
2427 characters, or the digraph of {chars} does not exist, an error
2428 is given and an empty string is returned.
2429
2430 The character will be converted from Unicode to 'encoding'
2431 when needed. This does require the conversion to be
2432 available, it might fail.
2433
2434 Also see |digraph_getlist()|.
2435
2436 Examples: >
2437 " Get a built-in digraph
2438 :echo digraph_get('00') " Returns '∞'
2439
2440 " Get a user-defined digraph
2441 :call digraph_set('aa', 'あ')
2442 :echo digraph_get('aa') " Returns 'あ'
2443<
2444 Can also be used as a |method|: >
2445 GetChars()->digraph_get()
2446<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002447 Return type: |String|
2448
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002449 This function works only when compiled with the |+digraphs|
2450 feature. If this feature is disabled, this function will
2451 display an error message.
2452
2453
2454digraph_getlist([{listall}]) *digraph_getlist()*
2455 Return a list of digraphs. If the {listall} argument is given
2456 and it is TRUE, return all digraphs, including the default
2457 digraphs. Otherwise, return only user-defined digraphs.
2458
2459 The characters will be converted from Unicode to 'encoding'
2460 when needed. This does require the conservation to be
2461 available, it might fail.
2462
2463 Also see |digraph_get()|.
2464
2465 Examples: >
2466 " Get user-defined digraphs
2467 :echo digraph_getlist()
2468
2469 " Get all the digraphs, including default digraphs
2470 :echo digraph_getlist(1)
2471<
2472 Can also be used as a |method|: >
2473 GetNumber()->digraph_getlist()
2474<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002475 Return type: list<list<string>>
2476
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002477 This function works only when compiled with the |+digraphs|
2478 feature. If this feature is disabled, this function will
2479 display an error message.
2480
2481
Bram Moolenaara2baa732022-02-04 16:09:54 +00002482digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002483 Add digraph {chars} to the list. {chars} must be a string
2484 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002485 encoded character. *E1215*
2486 Be careful, composing characters are NOT ignored. This
2487 function is similar to |:digraphs| command, but useful to add
2488 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002489
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002490 The function returns v:true if |digraph| is registered. If
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002491 this fails an error message is given and v:false is returned.
2492
2493 If you want to define multiple digraphs at once, you can use
2494 |digraph_setlist()|.
2495
2496 Example: >
2497 call digraph_set(' ', 'あ')
2498<
2499 Can be used as a |method|: >
2500 GetString()->digraph_set('あ')
2501<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002502 Return type: |vim9-boolean|
2503
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002504 This function works only when compiled with the |+digraphs|
2505 feature. If this feature is disabled, this function will
2506 display an error message.
2507
2508
2509digraph_setlist({digraphlist}) *digraph_setlist()*
2510 Similar to |digraph_set()| but this function can add multiple
2511 digraphs at once. {digraphlist} is a list composed of lists,
2512 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002513 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002514 Example: >
2515 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2516<
2517 It is similar to the following: >
2518 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2519 call digraph_set(chars, digraph)
2520 endfor
2521< Except that the function returns after the first error,
2522 following digraphs will not be added.
2523
2524 Can be used as a |method|: >
2525 GetList()->digraph_setlist()
2526<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002527 Return type: |vim9-boolean|
2528
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002529 This function works only when compiled with the |+digraphs|
2530 feature. If this feature is disabled, this function will
2531 display an error message.
2532
2533
2534echoraw({string}) *echoraw()*
2535 Output {string} as-is, including unprintable characters.
2536 This can be used to output a terminal code. For example, to
2537 disable modifyOtherKeys: >
2538 call echoraw(&t_TE)
2539< and to enable it again: >
2540 call echoraw(&t_TI)
2541< Use with care, you can mess up the terminal this way.
2542
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002543 Return type: |Number|
2544
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002545
2546empty({expr}) *empty()*
2547 Return the Number 1 if {expr} is empty, zero otherwise.
2548 - A |List| or |Dictionary| is empty when it does not have any
2549 items.
2550 - A |String| is empty when its length is zero.
2551 - A |Number| and |Float| are empty when their value is zero.
2552 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2553 - A |Job| is empty when it failed to start.
2554 - A |Channel| is empty when it is closed.
2555 - A |Blob| is empty when its length is zero.
mityu7f0bba22024-03-29 10:14:41 +01002556 - An |Object| is empty, when the empty() method in the object
2557 (if present) returns true. |object-empty()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002558
2559 For a long |List| this is much faster than comparing the
2560 length with zero.
2561
2562 Can also be used as a |method|: >
2563 mylist->empty()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002564<
2565 Return type: |Number|
2566
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002567
2568environ() *environ()*
2569 Return all of environment variables as dictionary. You can
2570 check if an environment variable exists like this: >
2571 :echo has_key(environ(), 'HOME')
2572< Note that the variable name may be CamelCase; to ignore case
2573 use this: >
2574 :echo index(keys(environ()), 'HOME', 0, 1) != -1
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002575<
2576 Return type: dict<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002577
Bram Moolenaar416bd912023-07-07 23:19:18 +01002578
2579err_teapot([{expr}]) *err_teapot()*
2580 Produce an error with number 418, needed for implementation of
Christian Brabandtee17b6f2023-09-09 11:23:50 +02002581 RFC 2324.
Bram Moolenaar416bd912023-07-07 23:19:18 +01002582 If {expr} is present and it is TRUE error 503 is given,
2583 indicating that coffee is temporarily not available.
2584 If {expr} is present it must be a String.
2585
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002586 Return type: |Number|
2587
Bram Moolenaar416bd912023-07-07 23:19:18 +01002588
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002589escape({string}, {chars}) *escape()*
2590 Escape the characters in {chars} that occur in {string} with a
2591 backslash. Example: >
2592 :echo escape('c:\program files\vim', ' \')
2593< results in: >
2594 c:\\program\ files\\vim
2595< Also see |shellescape()| and |fnameescape()|.
2596
2597 Can also be used as a |method|: >
2598 GetText()->escape(' \')
2599<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002600 Return type: |String|
2601
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002602 *eval()*
2603eval({string}) Evaluate {string} and return the result. Especially useful to
2604 turn the result of |string()| back into the original value.
2605 This works for Numbers, Floats, Strings, Blobs and composites
2606 of them. Also works for |Funcref|s that refer to existing
Aliaksei Budavei95740222024-04-04 23:05:33 +03002607 functions. In |Vim9| script, it can be used to obtain |enum|
2608 values from their fully qualified names.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002609
2610 Can also be used as a |method|: >
2611 argv->join()->eval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002612<
2613 Return type: any, depending on {string}
2614
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002615
2616eventhandler() *eventhandler()*
2617 Returns 1 when inside an event handler. That is that Vim got
2618 interrupted while waiting for the user to type a character,
2619 e.g., when dropping a file on Vim. This means interactive
2620 commands cannot be used. Otherwise zero is returned.
2621
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002622 Return type: |Number|
2623
2624
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002625executable({expr}) *executable()*
2626 This function checks if an executable with the name {expr}
2627 exists. {expr} must be the name of the program without any
2628 arguments.
zeertzjq0cc5dce2024-08-08 21:12:15 +02002629
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002630 executable() uses the value of $PATH and/or the normal
zeertzjq0cc5dce2024-08-08 21:12:15 +02002631 searchpath for programs.
2632 *PATHEXT*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002633 On MS-Windows the ".exe", ".bat", etc. can optionally be
2634 included. Then the extensions in $PATHEXT are tried. Thus if
2635 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2636 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2637 by itself can be used in $PATHEXT to try using the name
2638 without an extension. When 'shell' looks like a Unix shell,
2639 then the name is also tried without adding an extension.
2640 On MS-Windows it only checks if the file exists and is not a
2641 directory, not if it's really executable.
zeertzjq0cc5dce2024-08-08 21:12:15 +02002642 On MS-Windows an executable in the same directory as the Vim
2643 executable is always found. Since this directory is added to
2644 $PATH it should also work to execute it |win32-PATH|.
2645 *NoDefaultCurrentDirectoryInExePath*
2646 On MS-Windows an executable in Vim's current working directory
2647 is also normally found, but this can be disabled by setting
2648 the $NoDefaultCurrentDirectoryInExePath environment variable.
2649
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002650 The result is a Number:
2651 1 exists
2652 0 does not exist
2653 -1 not implemented on this system
2654 |exepath()| can be used to get the full path of an executable.
2655
2656 Can also be used as a |method|: >
2657 GetCommand()->executable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002658<
2659 Return type: |Number|
2660
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002661
2662execute({command} [, {silent}]) *execute()*
2663 Execute an Ex command or commands and return the output as a
2664 string.
2665 {command} can be a string or a List. In case of a List the
2666 lines are executed one by one.
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002667 This is more or less equivalent to: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002668 redir => var
2669 {command}
2670 redir END
Bram Moolenaar71badf92023-04-22 22:40:14 +01002671< Except that line continuation in {command} is not recognized.
2672
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002673 The optional {silent} argument can have these values:
2674 "" no `:silent` used
2675 "silent" `:silent` used
2676 "silent!" `:silent!` used
2677 The default is "silent". Note that with "silent!", unlike
2678 `:redir`, error messages are dropped. When using an external
2679 command the screen may be messed up, use `system()` instead.
2680 *E930*
2681 It is not possible to use `:redir` anywhere in {command}.
2682
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01002683 To get a list of lines use `split()` on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002684 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002685
2686< To execute a command in another window than the current one
2687 use `win_execute()`.
2688
2689 When used recursively the output of the recursive call is not
2690 included in the output of the higher level call.
2691
2692 Can also be used as a |method|: >
2693 GetCommand()->execute()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002694<
Marius Gedminasc98bfb92024-06-19 19:59:23 +02002695 Return type: |String|
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002696
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002697
2698exepath({expr}) *exepath()*
2699 If {expr} is an executable and is either an absolute path, a
2700 relative path or found in $PATH, return the full path.
2701 Note that the current directory is used when {expr} starts
2702 with "./", which may be a problem for Vim: >
2703 echo exepath(v:progpath)
2704< If {expr} cannot be found in $PATH or is not executable then
2705 an empty string is returned.
2706
2707 Can also be used as a |method|: >
2708 GetCommand()->exepath()
2709<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002710 Return type: |String|
2711
2712
2713exists({expr}) *exists()*
2714 The result is a Number, which is |TRUE| if {expr} is defined,
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002715 zero otherwise.
2716
2717 Note: In a compiled |:def| function the evaluation is done at
2718 runtime. Use `exists_compiled()` to evaluate the expression
2719 at compile time.
2720
2721 For checking for a supported feature use |has()|.
2722 For checking if a file exists use |filereadable()|.
2723
2724 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002725 varname internal variable (see
2726 dict.key |internal-variables|). Also works
2727 list[i] for |curly-braces-names|, |Dictionary|
Yegappan Lakshmanana2ebb6e2024-02-25 08:40:10 +01002728 import.Func entries, |List| items, class and
2729 class.Func object methods, imported items, etc.
2730 object.Func Does not work for local variables in a
2731 class.varname compiled `:def` function.
2732 object.varname Also works for a function in |Vim9|
Bram Moolenaar944697a2022-02-20 19:48:20 +00002733 script, since it can be used as a
2734 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002735 Beware that evaluating an index may
2736 cause an error message for an invalid
2737 expression. E.g.: >
2738 :let l = [1, 2, 3]
2739 :echo exists("l[5]")
2740< 0 >
2741 :echo exists("l[xx]")
2742< E121: Undefined variable: xx
2743 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002744 &option-name Vim option (only checks if it exists,
2745 not if it really works)
2746 +option-name Vim option that works.
2747 $ENVNAME environment variable (could also be
2748 done by comparing with an empty
2749 string)
2750 *funcname built-in function (see |functions|)
2751 or user defined function (see
2752 |user-functions|) that is implemented.
2753 Also works for a variable that is a
2754 Funcref.
2755 ?funcname built-in function that could be
2756 implemented; to be used to check if
2757 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002758 :cmdname Ex command: built-in command, user
2759 command or command modifier |:command|.
2760 Returns:
2761 1 for match with start of a command
2762 2 full match with a command
2763 3 matches several user commands
2764 To check for a supported command
2765 always check the return value to be 2.
2766 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002767 :3match The |:3match| command (but you
2768 probably should not use it, it is
2769 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002770 #event autocommand defined for this event
2771 #event#pattern autocommand defined for this event and
2772 pattern (the pattern is taken
2773 literally and compared to the
2774 autocommand patterns character by
2775 character)
2776 #group autocommand group exists
2777 #group#event autocommand defined for this group and
2778 event.
2779 #group#event#pattern
2780 autocommand defined for this group,
2781 event and pattern.
2782 ##event autocommand for this event is
2783 supported.
2784
2785 Examples: >
2786 exists("&shortname")
2787 exists("$HOSTNAME")
2788 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002789 exists("*s:MyFunc") " only for legacy script
2790 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002791 exists("bufcount")
2792 exists(":Make")
2793 exists("#CursorHold")
2794 exists("#BufReadPre#*.gz")
2795 exists("#filetypeindent")
2796 exists("#filetypeindent#FileType")
2797 exists("#filetypeindent#FileType#*")
2798 exists("##ColorScheme")
2799< There must be no space between the symbol (&/$/*/#) and the
2800 name.
2801 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002802 a few cases this is ignored. That may become stricter in the
2803 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002804 Working example: >
2805 exists(":make")
2806< NOT working example: >
2807 exists(":make install")
2808
2809< Note that the argument must be a string, not the name of the
2810 variable itself. For example: >
2811 exists(bufcount)
2812< This doesn't check for existence of the "bufcount" variable,
2813 but gets the value of "bufcount", and checks if that exists.
2814
2815 Can also be used as a |method|: >
2816 Varname()->exists()
2817<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002818 Return type: |String|
2819
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002820
2821exists_compiled({expr}) *exists_compiled()*
2822 Like `exists()` but evaluated at compile time. This is useful
2823 to skip a block where a function is used that would otherwise
2824 give an error: >
2825 if exists_compiled('*ThatFunction')
2826 ThatFunction('works')
2827 endif
2828< If `exists()` were used then a compilation error would be
2829 given if ThatFunction() is not defined.
2830
2831 {expr} must be a literal string. *E1232*
2832 Can only be used in a |:def| function. *E1233*
2833 This does not work to check for arguments or local variables.
2834
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002835 Return type: |String|
2836
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002837
2838exp({expr}) *exp()*
2839 Return the exponential of {expr} as a |Float| in the range
2840 [0, inf].
2841 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002842 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002843 Examples: >
2844 :echo exp(2)
2845< 7.389056 >
2846 :echo exp(-1)
2847< 0.367879
2848
2849 Can also be used as a |method|: >
2850 Compute()->exp()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002851<
2852 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002853
2854
2855expand({string} [, {nosuf} [, {list}]]) *expand()*
2856 Expand wildcards and the following special keywords in
2857 {string}. 'wildignorecase' applies.
2858
2859 If {list} is given and it is |TRUE|, a List will be returned.
2860 Otherwise the result is a String and when there are several
2861 matches, they are separated by <NL> characters. [Note: in
2862 version 5.0 a space was used, which caused problems when a
2863 file name contains a space]
2864
2865 If the expansion fails, the result is an empty string. A name
2866 for a non-existing file is not included, unless {string} does
2867 not start with '%', '#' or '<', see below.
2868
Christian Brabandtec9c3262024-02-21 20:40:05 +01002869 For a |:terminal| window '%' expands to a '!' followed by
h-east53753f62024-05-05 18:42:31 +02002870 the command or shell that is run. |terminal-bufname|
Christian Brabandtec9c3262024-02-21 20:40:05 +01002871
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002872 When {string} starts with '%', '#' or '<', the expansion is
2873 done like for the |cmdline-special| variables with their
2874 associated modifiers. Here is a short overview:
2875
2876 % current file name
2877 # alternate file name
2878 #n alternate file name n
2879 <cfile> file name under the cursor
2880 <afile> autocmd file name
2881 <abuf> autocmd buffer number (as a String!)
2882 <amatch> autocmd matched name
2883 <cexpr> C expression under the cursor
2884 <sfile> sourced script file or function name
2885 <slnum> sourced script line number or function
2886 line number
2887 <sflnum> script file line number, also when in
2888 a function
2889 <SID> "<SNR>123_" where "123" is the
2890 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002891 <script> sourced script file, or script file
2892 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002893 <stack> call stack
2894 <cword> word under the cursor
2895 <cWORD> WORD under the cursor
2896 <client> the {clientid} of the last received
2897 message |server2client()|
2898 Modifiers:
2899 :p expand to full path
2900 :h head (last path component removed)
2901 :t tail (last path component only)
2902 :r root (one extension removed)
2903 :e extension only
2904
2905 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002906 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002907< Note that when expanding a string that starts with '%', '#' or
2908 '<', any following text is ignored. This does NOT work: >
2909 :let doesntwork = expand("%:h.bak")
2910< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002911 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002912< Also note that expanding "<cfile>" and others only returns the
2913 referenced file name without further expansion. If "<cfile>"
2914 is "~/.cshrc", you need to do another expand() to have the
2915 "~/" expanded into the path of the home directory: >
2916 :echo expand(expand("<cfile>"))
2917<
2918 There cannot be white space between the variables and the
2919 following modifier. The |fnamemodify()| function can be used
2920 to modify normal file names.
2921
2922 When using '%' or '#', and the current or alternate file name
2923 is not defined, an empty string is used. Using "%:p" in a
2924 buffer with no name, results in the current directory, with a
2925 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01002926 When 'verbose' is set then expanding '%', '#' and <> items
2927 will result in an error message if the argument cannot be
2928 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002929
2930 When {string} does not start with '%', '#' or '<', it is
2931 expanded like a file name is expanded on the command line.
2932 'suffixes' and 'wildignore' are used, unless the optional
2933 {nosuf} argument is given and it is |TRUE|.
2934 Names for non-existing files are included. The "**" item can
2935 be used to search in a directory tree. For example, to find
2936 all "README" files in the current directory and below: >
2937 :echo expand("**/README")
2938<
2939 expand() can also be used to expand variables and environment
2940 variables that are only known in a shell. But this can be
2941 slow, because a shell may be used to do the expansion. See
2942 |expr-env-expand|.
2943 The expanded variable is still handled like a list of file
2944 names. When an environment variable cannot be expanded, it is
2945 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2946 "$FOOBAR".
2947
2948 See |glob()| for finding existing files. See |system()| for
2949 getting the raw output of an external command.
2950
2951 Can also be used as a |method|: >
2952 Getpattern()->expand()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002953<
2954 Return type: |String| or list<string> depending on {list}
2955
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002956
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002957expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002958 Expand special items in String {string} like what is done for
2959 an Ex command such as `:edit`. This expands special keywords,
2960 like with |expand()|, and environment variables, anywhere in
2961 {string}. "~user" and "~/path" are only expanded at the
2962 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002963
2964 The following items are supported in the {options} Dict
2965 argument:
2966 errmsg If set to TRUE, error messages are displayed
2967 if an error is encountered during expansion.
2968 By default, error messages are not displayed.
2969
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002970 Returns the expanded string. If an error is encountered
2971 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002972
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002973 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002974 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002975 make /path/runtime/doc/builtin.o
2976 :echo expandcmd('make %<.o', {'errmsg': v:true})
2977<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002978 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002979 GetCommand()->expandcmd()
2980<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02002981 Return type: |String| or list<string> depending on {list}
2982
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002983extend({expr1}, {expr2} [, {expr3}]) *extend()*
2984 {expr1} and {expr2} must be both |Lists| or both
2985 |Dictionaries|.
2986
2987 If they are |Lists|: Append {expr2} to {expr1}.
2988 If {expr3} is given insert the items of {expr2} before the
2989 item with index {expr3} in {expr1}. When {expr3} is zero
2990 insert before the first item. When {expr3} is equal to
2991 len({expr1}) then {expr2} is appended.
2992 Examples: >
2993 :echo sort(extend(mylist, [7, 5]))
2994 :call extend(mylist, [2, 3], 1)
2995< When {expr1} is the same List as {expr2} then the number of
2996 items copied is equal to the original length of the List.
2997 E.g., when {expr3} is 1 you get N new copies of the first item
2998 (where N is the original length of the List).
2999 Use |add()| to concatenate one item to a list. To concatenate
3000 two lists into a new list use the + operator: >
3001 :let newlist = [1, 2, 3] + [4, 5]
3002<
3003 If they are |Dictionaries|:
3004 Add all entries from {expr2} to {expr1}.
3005 If a key exists in both {expr1} and {expr2} then {expr3} is
3006 used to decide what to do:
3007 {expr3} = "keep": keep the value of {expr1}
3008 {expr3} = "force": use the value of {expr2}
3009 {expr3} = "error": give an error message *E737*
3010 When {expr3} is omitted then "force" is assumed.
3011
3012 {expr1} is changed when {expr2} is not empty. If necessary
Christian Brabandt5647c912025-02-17 21:33:30 +01003013 make a copy of {expr1} first or use |extendnew()| to return a
3014 new List/Dictionary.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003015 {expr2} remains unchanged.
3016 When {expr1} is locked and {expr2} is not empty the operation
3017 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003018 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003019
3020 Can also be used as a |method|: >
3021 mylist->extend(otherlist)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003022<
3023 Return type: list<{type}> or dict<{type}> depending on {expr1}
3024 and {expr2}, in case of error: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003025
3026
3027extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
3028 Like |extend()| but instead of adding items to {expr1} a new
3029 List or Dictionary is created and returned. {expr1} remains
Bram Moolenaardd60c362023-02-27 15:49:53 +00003030 unchanged.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003031
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003032 Return type: list<{type}> or dict<{type}> depending on {expr1}
3033 and {expr2}, in case of error: |Number|
3034
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003035
3036feedkeys({string} [, {mode}]) *feedkeys()*
3037 Characters in {string} are queued for processing as if they
3038 come from a mapping or were typed by the user.
3039
3040 By default the string is added to the end of the typeahead
3041 buffer, thus if a mapping is still being executed the
3042 characters come after them. Use the 'i' flag to insert before
3043 other characters, they will be executed next, before any
3044 characters from a mapping.
3045
3046 The function does not wait for processing of keys contained in
3047 {string}.
3048
3049 To include special keys into {string}, use double-quotes
3050 and "\..." notation |expr-quote|. For example,
3051 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
3052 feedkeys('\<CR>') pushes 5 characters.
3053 A special code that might be useful is <Ignore>, it exits the
3054 wait for a character without doing anything. *<Ignore>*
3055
3056 {mode} is a String, which can contain these character flags:
3057 'm' Remap keys. This is default. If {mode} is absent,
3058 keys are remapped.
3059 'n' Do not remap keys.
3060 't' Handle keys as if typed; otherwise they are handled as
3061 if coming from a mapping. This matters for undo,
3062 opening folds, etc.
3063 'L' Lowlevel input. Only works for Unix or when using the
3064 GUI. Keys are used as if they were coming from the
3065 terminal. Other flags are not used. *E980*
3066 When a CTRL-C interrupts and 't' is included it sets
3067 the internal "got_int" flag.
3068 'i' Insert the string instead of appending (see above).
3069 'x' Execute commands until typeahead is empty. This is
3070 similar to using ":normal!". You can call feedkeys()
3071 several times without 'x' and then one time with 'x'
3072 (possibly with an empty {string}) to execute all the
3073 typeahead. Note that when Vim ends in Insert mode it
3074 will behave as if <Esc> is typed, to avoid getting
3075 stuck, waiting for a character to be typed before the
3076 script continues.
3077 Note that if you manage to call feedkeys() while
3078 executing commands, thus calling it recursively, then
3079 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00003080 'c' Remove any script context when executing, so that
3081 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01003082 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01003083 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003084 '!' When used with 'x' will not end Insert mode. Can be
3085 used in a test when a timer is set to exit Insert mode
3086 a little later. Useful for testing CursorHoldI.
3087
3088 Return value is always 0.
3089
3090 Can also be used as a |method|: >
3091 GetInput()->feedkeys()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003092<
3093 Return type: |String| or list<string> depending on {list}
3094
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003095
Shougo Matsushita60c87432024-06-03 22:59:27 +02003096filecopy({from}, {to}) *filecopy()*
3097 Copy the file pointed to by the name {from} to {to}. The
3098 result is a Number, which is |TRUE| if the file was copied
3099 successfully, and |FALSE| when it failed.
3100 If a file with name {to} already exists, it will fail.
3101 Note that it does not handle directories (yet).
3102
3103 This function is not available in the |sandbox|.
3104
3105 Can also be used as a |method|: >
3106 GetOldName()->filecopy(newname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003107<
3108 Return type: |Number|
3109
Shougo Matsushita60c87432024-06-03 22:59:27 +02003110
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003111filereadable({file}) *filereadable()*
3112 The result is a Number, which is |TRUE| when a file with the
3113 name {file} exists, and can be read. If {file} doesn't exist,
3114 or is a directory, the result is |FALSE|. {file} is any
3115 expression, which is used as a String.
3116 If you don't care about the file being readable you can use
3117 |glob()|.
3118 {file} is used as-is, you may want to expand wildcards first: >
3119 echo filereadable('~/.vimrc')
3120 0
3121 echo filereadable(expand('~/.vimrc'))
3122 1
3123
3124< Can also be used as a |method|: >
3125 GetName()->filereadable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003126<
3127 Return type: |Number|
3128
3129 *file_readable()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003130 Obsolete name: file_readable().
3131
3132
3133filewritable({file}) *filewritable()*
3134 The result is a Number, which is 1 when a file with the
3135 name {file} exists, and can be written. If {file} doesn't
3136 exist, or is not writable, the result is 0. If {file} is a
3137 directory, and we can write to it, the result is 2.
3138
3139 Can also be used as a |method|: >
3140 GetName()->filewritable()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003141<
3142 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003143
3144
3145filter({expr1}, {expr2}) *filter()*
3146 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
3147 For each item in {expr1} evaluate {expr2} and when the result
3148 is zero or false remove the item from the |List| or
3149 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003150 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003151
3152 {expr2} must be a |string| or |Funcref|.
3153
3154 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3155 of the current item. For a |Dictionary| |v:key| has the key
3156 of the current item and for a |List| |v:key| has the index of
3157 the current item. For a |Blob| |v:key| has the index of the
3158 current byte. For a |String| |v:key| has the index of the
3159 current character.
3160 Examples: >
3161 call filter(mylist, 'v:val !~ "OLD"')
3162< Removes the items where "OLD" appears. >
3163 call filter(mydict, 'v:key >= 8')
3164< Removes the items with a key below 8. >
3165 call filter(var, 0)
3166< Removes all the items, thus clears the |List| or |Dictionary|.
3167
3168 Note that {expr2} is the result of expression and is then
3169 used as an expression again. Often it is good to use a
3170 |literal-string| to avoid having to double backslashes.
3171
3172 If {expr2} is a |Funcref| it must take two arguments:
3173 1. the key or the index of the current item.
3174 2. the value of the current item.
3175 The function must return |TRUE| if the item should be kept.
3176 Example that keeps the odd items of a list: >
3177 func Odd(idx, val)
3178 return a:idx % 2 == 1
3179 endfunc
3180 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003181< It is shorter when using a |lambda|. In |Vim9| syntax: >
3182 call filter(myList, (idx, val) => idx * val <= 42)
3183< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003184 call filter(myList, {idx, val -> idx * val <= 42})
3185< If you do not use "val" you can leave it out: >
3186 call filter(myList, {idx -> idx % 2 == 1})
3187<
3188 In |Vim9| script the result must be true, false, zero or one.
3189 Other values will result in a type error.
3190
3191 For a |List| and a |Dictionary| the operation is done
3192 in-place. If you want it to remain unmodified make a copy
3193 first: >
3194 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
3195
3196< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00003197 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003198 When an error is encountered while evaluating {expr2} no
3199 further items in {expr1} are processed.
3200 When {expr2} is a Funcref errors inside a function are ignored,
3201 unless it was defined with the "abort" flag.
3202
3203 Can also be used as a |method|: >
3204 mylist->filter(expr2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003205<
3206 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
3207 depending on {expr1}
3208
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003209
3210finddir({name} [, {path} [, {count}]]) *finddir()*
3211 Find directory {name} in {path}. Supports both downwards and
3212 upwards recursive directory searches. See |file-searching|
3213 for the syntax of {path}.
3214
3215 Returns the path of the first found match. When the found
3216 directory is below the current directory a relative path is
3217 returned. Otherwise a full path is returned.
3218 If {path} is omitted or empty then 'path' is used.
3219
3220 If the optional {count} is given, find {count}'s occurrence of
3221 {name} in {path} instead of the first one.
3222 When {count} is negative return all the matches in a |List|.
3223
Bram Moolenaar016188f2022-06-06 20:52:59 +01003224 Returns an empty string if the directory is not found.
3225
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003226 This is quite similar to the ex-command `:find`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003227
3228 Can also be used as a |method|: >
3229 GetName()->finddir()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003230<
3231 Return type: |String|
3232
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003233
3234findfile({name} [, {path} [, {count}]]) *findfile()*
3235 Just like |finddir()|, but find a file instead of a directory.
3236 Uses 'suffixesadd'.
3237 Example: >
3238 :echo findfile("tags.vim", ".;")
3239< Searches from the directory of the current file upwards until
3240 it finds the file "tags.vim".
3241
3242 Can also be used as a |method|: >
3243 GetName()->findfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003244<
3245 Return type: |String|
3246
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003247
3248flatten({list} [, {maxdepth}]) *flatten()*
3249 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
3250 the result is a |List| without nesting, as if {maxdepth} is
3251 a very large number.
3252 The {list} is changed in place, use |flattennew()| if you do
3253 not want that.
3254 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00003255 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003256 *E900*
3257 {maxdepth} means how deep in nested lists changes are made.
3258 {list} is not modified when {maxdepth} is 0.
3259 {maxdepth} must be positive number.
3260
3261 If there is an error the number zero is returned.
3262
3263 Example: >
3264 :echo flatten([1, [2, [3, 4]], 5])
3265< [1, 2, 3, 4, 5] >
3266 :echo flatten([1, [2, [3, 4]], 5], 1)
3267< [1, 2, [3, 4], 5]
3268
3269 Can also be used as a |method|: >
3270 mylist->flatten()
3271<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003272 Return type: list<{type}>
3273
3274
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003275flattennew({list} [, {maxdepth}]) *flattennew()*
3276 Like |flatten()| but first make a copy of {list}.
3277
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003278 Return type: list<{type}>
3279
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003280
3281float2nr({expr}) *float2nr()*
3282 Convert {expr} to a Number by omitting the part after the
3283 decimal point.
Bram Moolenaar76db9e02022-11-09 21:21:04 +00003284 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003285 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003286 When the value of {expr} is out of range for a |Number| the
3287 result is truncated to 0x7fffffff or -0x7fffffff (or when
3288 64-bit Number support is enabled, 0x7fffffffffffffff or
3289 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
3290 64-bit Number support is enabled, -0x8000000000000000).
3291 Examples: >
3292 echo float2nr(3.95)
3293< 3 >
3294 echo float2nr(-23.45)
3295< -23 >
3296 echo float2nr(1.0e100)
3297< 2147483647 (or 9223372036854775807) >
3298 echo float2nr(-1.0e150)
3299< -2147483647 (or -9223372036854775807) >
3300 echo float2nr(1.0e-100)
3301< 0
3302
3303 Can also be used as a |method|: >
3304 Compute()->float2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003305<
3306 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003307
3308
3309floor({expr}) *floor()*
3310 Return the largest integral value less than or equal to
3311 {expr} as a |Float| (round down).
3312 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003313 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003314 Examples: >
3315 echo floor(1.856)
3316< 1.0 >
3317 echo floor(-5.456)
3318< -6.0 >
3319 echo floor(4.0)
3320< 4.0
3321
3322 Can also be used as a |method|: >
3323 Compute()->floor()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003324<
3325 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003326
3327
3328fmod({expr1}, {expr2}) *fmod()*
3329 Return the remainder of {expr1} / {expr2}, even if the
3330 division is not representable. Returns {expr1} - i * {expr2}
3331 for some integer i such that if {expr2} is non-zero, the
3332 result has the same sign as {expr1} and magnitude less than
3333 the magnitude of {expr2}. If {expr2} is zero, the value
3334 returned is zero. The value returned is a |Float|.
3335 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003336 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
3337 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003338 Examples: >
3339 :echo fmod(12.33, 1.22)
3340< 0.13 >
3341 :echo fmod(-12.33, 1.22)
3342< -0.13
3343
3344 Can also be used as a |method|: >
3345 Compute()->fmod(1.22)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003346<
3347 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003348
3349
3350fnameescape({string}) *fnameescape()*
3351 Escape {string} for use as file name command argument. All
3352 characters that have a special meaning, such as '%' and '|'
3353 are escaped with a backslash.
3354 For most systems the characters escaped are
3355 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3356 appears in a filename, it depends on the value of 'isfname'.
3357 A leading '+' and '>' is also escaped (special after |:edit|
3358 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01003359 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003360 Example: >
3361 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003362 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003363< results in executing: >
3364 edit \+some\ str\%nge\|name
3365<
3366 Can also be used as a |method|: >
3367 GetName()->fnameescape()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003368<
3369 Return type: |String|
3370
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003371
3372fnamemodify({fname}, {mods}) *fnamemodify()*
3373 Modify file name {fname} according to {mods}. {mods} is a
3374 string of characters like it is used for file names on the
3375 command line. See |filename-modifiers|.
3376 Example: >
3377 :echo fnamemodify("main.c", ":p:h")
3378< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01003379 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01003380< If {mods} is empty or an unsupported modifier is used then
3381 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01003382 When {fname} is empty then with {mods} ":h" returns ".", so
3383 that `:cd` can be used with it. This is different from
3384 expand('%:h') without a buffer name, which returns an empty
3385 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003386 Note: Environment variables don't work in {fname}, use
3387 |expand()| first then.
3388
3389 Can also be used as a |method|: >
3390 GetName()->fnamemodify(':p:h')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003391<
3392 Return type: |String|
3393
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003394
3395foldclosed({lnum}) *foldclosed()*
3396 The result is a Number. If the line {lnum} is in a closed
3397 fold, the result is the number of the first line in that fold.
3398 If the line {lnum} is not in a closed fold, -1 is returned.
3399 {lnum} is used like with |getline()|. Thus "." is the current
3400 line, "'m" mark m, etc.
3401
3402 Can also be used as a |method|: >
3403 GetLnum()->foldclosed()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003404<
3405 Return type: |Number|
3406
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003407
3408foldclosedend({lnum}) *foldclosedend()*
3409 The result is a Number. If the line {lnum} is in a closed
3410 fold, the result is the number of the last line in that fold.
3411 If the line {lnum} is not in a closed fold, -1 is returned.
3412 {lnum} is used like with |getline()|. Thus "." is the current
3413 line, "'m" mark m, etc.
3414
3415 Can also be used as a |method|: >
3416 GetLnum()->foldclosedend()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003417<
3418 Return type: |Number|
3419
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003420
3421foldlevel({lnum}) *foldlevel()*
3422 The result is a Number, which is the foldlevel of line {lnum}
3423 in the current buffer. For nested folds the deepest level is
3424 returned. If there is no fold at line {lnum}, zero is
3425 returned. It doesn't matter if the folds are open or closed.
3426 When used while updating folds (from 'foldexpr') -1 is
3427 returned for lines where folds are still to be updated and the
3428 foldlevel is unknown. As a special case the level of the
3429 previous line is usually available.
3430 {lnum} is used like with |getline()|. Thus "." is the current
3431 line, "'m" mark m, etc.
3432
3433 Can also be used as a |method|: >
3434 GetLnum()->foldlevel()
3435<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003436 Return type: |Number|
3437
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003438 *foldtext()*
3439foldtext() Returns a String, to be displayed for a closed fold. This is
3440 the default function used for the 'foldtext' option and should
3441 only be called from evaluating 'foldtext'. It uses the
3442 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3443 The returned string looks like this: >
3444 +-- 45 lines: abcdef
3445< The number of leading dashes depends on the foldlevel. The
3446 "45" is the number of lines in the fold. "abcdef" is the text
3447 in the first non-blank line of the fold. Leading white space,
3448 "//" or "/*" and the text from the 'foldmarker' and
3449 'commentstring' options is removed.
3450 When used to draw the actual foldtext, the rest of the line
3451 will be filled with the fold char from the 'fillchars'
3452 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003453 Returns an empty string when there is no fold.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003454
3455 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003456 {not available when compiled without the |+folding| feature}
3457
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003458
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003459foldtextresult({lnum}) *foldtextresult()*
3460 Returns the text that is displayed for the closed fold at line
3461 {lnum}. Evaluates 'foldtext' in the appropriate context.
3462 When there is no closed fold at {lnum} an empty string is
3463 returned.
3464 {lnum} is used like with |getline()|. Thus "." is the current
3465 line, "'m" mark m, etc.
3466 Useful when exporting folded text, e.g., to HTML.
3467 {not available when compiled without the |+folding| feature}
3468
3469
3470 Can also be used as a |method|: >
3471 GetLnum()->foldtextresult()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003472<
3473 Return type: |String|
3474
Ernie Raele79e2072024-01-13 11:47:33 +01003475
3476foreach({expr1}, {expr2}) *foreach()*
3477 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
3478 For each item in {expr1} execute {expr2}. {expr1} is not
erraelc92b8be2024-01-14 10:11:07 -08003479 modified; its values may be, as with |:lockvar| 1. |E741|
Ernie Raele79e2072024-01-13 11:47:33 +01003480 See |map()| and |filter()| to modify {expr1}.
3481
3482 {expr2} must be a |string| or |Funcref|.
3483
3484 If {expr2} is a |string|, inside {expr2} |v:val| has the value
3485 of the current item. For a |Dictionary| |v:key| has the key
3486 of the current item and for a |List| |v:key| has the index of
3487 the current item. For a |Blob| |v:key| has the index of the
3488 current byte. For a |String| |v:key| has the index of the
3489 current character.
3490 Examples: >
3491 call foreach(mylist, 'used[v:val] = true')
3492< This records the items that are in the {expr1} list.
3493
3494 Note that {expr2} is the result of expression and is then used
3495 as a command. Often it is good to use a |literal-string| to
3496 avoid having to double backslashes.
3497
3498 If {expr2} is a |Funcref| it must take two arguments:
3499 1. the key or the index of the current item.
3500 2. the value of the current item.
3501 With a legacy script lambda you don't get an error if it only
3502 accepts one argument, but with a Vim9 lambda you get "E1106:
3503 One argument too many", the number of arguments must match.
3504 If the function returns a value, it is ignored.
3505
3506 Returns {expr1} in all cases.
3507 When an error is encountered while executing {expr2} no
3508 further items in {expr1} are processed.
3509 When {expr2} is a Funcref errors inside a function are ignored,
3510 unless it was defined with the "abort" flag.
3511
3512 Can also be used as a |method|: >
3513 mylist->foreach(expr2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003514<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003515 Return type: |String|, |Blob| list<{type}> or dict<{type}>
3516 depending on {expr1}
3517
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003518 *foreground()*
3519foreground() Move the Vim window to the foreground. Useful when sent from
3520 a client to a Vim server. |remote_send()|
3521 On Win32 systems this might not work, the OS does not always
3522 allow a window to bring itself to the foreground. Use
3523 |remote_foreground()| instead.
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003524
3525 Return type: |Number|
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003526 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003527 Win32 console version}
3528
Bram Moolenaaraa534142022-09-15 21:46:02 +01003529fullcommand({name} [, {vim9}]) *fullcommand()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003530 Get the full command name from a short abbreviated command
3531 name; see |20.2| for details on command abbreviations.
3532
3533 The string argument {name} may start with a `:` and can
3534 include a [range], these are skipped and not returned.
Bram Moolenaaraa534142022-09-15 21:46:02 +01003535 Returns an empty string if a command doesn't exist, if it's
3536 ambiguous (for user-defined commands) or cannot be shortened
3537 this way. |vim9-no-shorten|
3538
3539 Without the {vim9} argument uses the current script version.
3540 If {vim9} is present and FALSE then legacy script rules are
3541 used. When {vim9} is present and TRUE then Vim9 rules are
3542 used, e.g. "en" is not a short form of "endif".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003543
3544 For example `fullcommand('s')`, `fullcommand('sub')`,
3545 `fullcommand(':%substitute')` all return "substitute".
3546
3547 Can also be used as a |method|: >
3548 GetName()->fullcommand()
3549<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003550 Return type: |String|
3551
3552
3553funcref({name} [, {arglist}] [, {dict}]) *funcref()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003554 Just like |function()|, but the returned Funcref will lookup
3555 the function by reference, not by name. This matters when the
3556 function {name} is redefined later.
3557
3558 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00003559 It only works for an autoloaded function if it has already
3560 been loaded (to avoid mistakenly loading the autoload script
3561 when only intending to use the function name, use |function()|
3562 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01003563 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003564
3565 Can also be used as a |method|: >
3566 GetFuncname()->funcref([arg])
3567<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003568 Return type: func(...): any or |Number| on error
3569
Dominique Pellee764d1b2023-03-12 21:20:59 +00003570 *function()* *partial* *E700* *E923*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003571function({name} [, {arglist}] [, {dict}])
3572 Return a |Funcref| variable that refers to function {name}.
3573 {name} can be the name of a user defined function or an
3574 internal function.
3575
3576 {name} can also be a Funcref or a partial. When it is a
3577 partial the dict stored in it will be used and the {dict}
3578 argument is not allowed. E.g.: >
3579 let FuncWithArg = function(dict.Func, [arg])
3580 let Broken = function(dict.Func, [arg], dict)
3581<
3582 When using the Funcref the function will be found by {name},
3583 also when it was redefined later. Use |funcref()| to keep the
3584 same function.
3585
3586 When {arglist} or {dict} is present this creates a partial.
3587 That means the argument list and/or the dictionary is stored in
3588 the Funcref and will be used when the Funcref is called.
3589
3590 The arguments are passed to the function in front of other
3591 arguments, but after any argument from |method|. Example: >
3592 func Callback(arg1, arg2, name)
3593 ...
3594 let Partial = function('Callback', ['one', 'two'])
3595 ...
3596 call Partial('name')
3597< Invokes the function as with: >
3598 call Callback('one', 'two', 'name')
3599
3600< With a |method|: >
3601 func Callback(one, two, three)
3602 ...
3603 let Partial = function('Callback', ['two'])
3604 ...
3605 eval 'one'->Partial('three')
3606< Invokes the function as with: >
3607 call Callback('one', 'two', 'three')
3608
3609< The function() call can be nested to add more arguments to the
3610 Funcref. The extra arguments are appended to the list of
3611 arguments. Example: >
3612 func Callback(arg1, arg2, name)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003613 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003614 let Func = function('Callback', ['one'])
3615 let Func2 = function(Func, ['two'])
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003616 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003617 call Func2('name')
3618< Invokes the function as with: >
3619 call Callback('one', 'two', 'name')
3620
3621< The Dictionary is only useful when calling a "dict" function.
3622 In that case the {dict} is passed in as "self". Example: >
3623 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003624 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003625 endfunction
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003626 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003627 let context = {"name": "example"}
3628 let Func = function('Callback', context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003629 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003630 call Func() " will echo: called for example
3631< The use of function() is not needed when there are no extra
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003632 arguments, these two are equivalent, if Callback() is defined
3633 as context.Callback(): >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003634 let Func = function('Callback', context)
3635 let Func = context.Callback
3636
3637< The argument list and the Dictionary can be combined: >
3638 function Callback(arg1, count) dict
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003639 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003640 let context = {"name": "example"}
3641 let Func = function('Callback', ['one'], context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003642 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003643 call Func(500)
3644< Invokes the function as with: >
3645 call context.Callback('one', 500)
3646<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003647 Returns 0 on error.
3648
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003649 Can also be used as a |method|: >
3650 GetFuncname()->function([arg])
3651
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003652<
3653 Return type: func(...): any or |Number| on error
3654
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003655
3656garbagecollect([{atexit}]) *garbagecollect()*
3657 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3658 that have circular references.
3659
3660 There is hardly ever a need to invoke this function, as it is
3661 automatically done when Vim runs out of memory or is waiting
3662 for the user to press a key after 'updatetime'. Items without
3663 circular references are always freed when they become unused.
3664 This is useful if you have deleted a very big |List| and/or
3665 |Dictionary| with circular references in a script that runs
3666 for a long time.
3667
3668 When the optional {atexit} argument is one, garbage
3669 collection will also be done when exiting Vim, if it wasn't
3670 done before. This is useful when checking for memory leaks.
3671
3672 The garbage collection is not done immediately but only when
3673 it's safe to perform. This is when waiting for the user to
3674 type a character. To force garbage collection immediately use
3675 |test_garbagecollect_now()|.
3676
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003677 Return type: |String|
3678
3679
LemonBoy48b7d052024-07-09 18:24:59 +02003680get({list}, {idx} [, {default}]) *get()* *get()-list*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003681 Get item {idx} from |List| {list}. When this item is not
3682 available return {default}. Return zero when {default} is
3683 omitted.
3684 Preferably used as a |method|: >
3685 mylist->get(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003686<
3687 Return type: any, depending on {list}
3688
LemonBoy48b7d052024-07-09 18:24:59 +02003689get({blob}, {idx} [, {default}]) *get()-blob*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003690 Get byte {idx} from |Blob| {blob}. When this byte is not
3691 available return {default}. Return -1 when {default} is
3692 omitted.
3693 Preferably used as a |method|: >
3694 myblob->get(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003695<
3696 Return type: |Number|
3697
LemonBoy48b7d052024-07-09 18:24:59 +02003698get({dict}, {key} [, {default}]) *get()-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003699 Get item with key {key} from |Dictionary| {dict}. When this
3700 item is not available return {default}. Return zero when
3701 {default} is omitted. Useful example: >
3702 let val = get(g:, 'var_name', 'default')
3703< This gets the value of g:var_name if it exists, and uses
3704 'default' when it does not exist.
3705 Preferably used as a |method|: >
3706 mydict->get(key)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003707<
h-east84ac2122024-06-17 18:12:30 +02003708 Return type: any, depending on {dict}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003709
LemonBoy48b7d052024-07-09 18:24:59 +02003710get({func}, {what}) *get()-func*
3711 Get item {what} from |Funcref| {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003712 {what} are:
LemonBoy48b7d052024-07-09 18:24:59 +02003713 "name" The function name
3714 "func" The function
3715 "dict" The dictionary
3716 "args" The list with arguments
3717 "arity" A dictionary with information about the number of
3718 arguments accepted by the function (minus the
3719 {arglist}) with the following fields:
3720 required the number of positional arguments
3721 optional the number of optional arguments,
3722 in addition to the required ones
3723 varargs |TRUE| if the function accepts a
3724 variable number of arguments |...|
3725
3726 Note: There is no error, if the {arglist} of
3727 the Funcref contains more arguments than the
3728 Funcref expects, it's not validated.
3729
Bram Moolenaar016188f2022-06-06 20:52:59 +01003730 Returns zero on error.
LemonBoy48b7d052024-07-09 18:24:59 +02003731
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003732 Preferably used as a |method|: >
3733 myfunc->get(what)
3734<
LemonBoy48b7d052024-07-09 18:24:59 +02003735 Return type: any, depending on {func} and {what}
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003736
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003737 *getbufinfo()*
3738getbufinfo([{buf}])
3739getbufinfo([{dict}])
3740 Get information about buffers as a List of Dictionaries.
3741
3742 Without an argument information about all the buffers is
3743 returned.
3744
3745 When the argument is a |Dictionary| only the buffers matching
3746 the specified criteria are returned. The following keys can
3747 be specified in {dict}:
3748 buflisted include only listed buffers.
3749 bufloaded include only loaded buffers.
3750 bufmodified include only modified buffers.
3751
3752 Otherwise, {buf} specifies a particular buffer to return
3753 information for. For the use of {buf}, see |bufname()|
3754 above. If the buffer is found the returned List has one item.
3755 Otherwise the result is an empty list.
3756
3757 Each returned List item is a dictionary with the following
3758 entries:
3759 bufnr Buffer number.
3760 changed TRUE if the buffer is modified.
3761 changedtick Number of changes made to the buffer.
Sean Dewar1fb41032023-08-16 17:15:05 +01003762 command TRUE if the buffer belongs to the
3763 command-line window |cmdwin|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003764 hidden TRUE if the buffer is hidden.
3765 lastused Timestamp in seconds, like
3766 |localtime()|, when the buffer was
3767 last used.
3768 {only with the |+viminfo| feature}
3769 listed TRUE if the buffer is listed.
3770 lnum Line number used for the buffer when
3771 opened in the current window.
3772 Only valid if the buffer has been
3773 displayed in the window in the past.
3774 If you want the line number of the
3775 last known cursor position in a given
3776 window, use |line()|: >
3777 :echo line('.', {winid})
3778<
3779 linecount Number of lines in the buffer (only
3780 valid when loaded)
3781 loaded TRUE if the buffer is loaded.
3782 name Full path to the file in the buffer.
3783 signs List of signs placed in the buffer.
3784 Each list item is a dictionary with
3785 the following fields:
3786 id sign identifier
3787 lnum line number
3788 name sign name
3789 variables A reference to the dictionary with
3790 buffer-local variables.
3791 windows List of |window-ID|s that display this
3792 buffer
3793 popups List of popup |window-ID|s that
3794 display this buffer
3795
3796 Examples: >
3797 for buf in getbufinfo()
3798 echo buf.name
3799 endfor
3800 for buf in getbufinfo({'buflisted':1})
3801 if buf.changed
3802 ....
3803 endif
3804 endfor
3805<
3806 To get buffer-local options use: >
3807 getbufvar({bufnr}, '&option_name')
3808<
3809 Can also be used as a |method|: >
3810 GetBufnr()->getbufinfo()
3811<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003812 Return type: list<dict<any>>
3813
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003814
3815 *getbufline()*
3816getbufline({buf}, {lnum} [, {end}])
3817 Return a |List| with the lines starting from {lnum} to {end}
3818 (inclusive) in the buffer {buf}. If {end} is omitted, a
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003819 |List| with only the line {lnum} is returned. See
3820 `getbufoneline()` for only getting the line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003821
3822 For the use of {buf}, see |bufname()| above.
3823
3824 For {lnum} and {end} "$" can be used for the last line of the
3825 buffer. Otherwise a number must be used.
3826
3827 When {lnum} is smaller than 1 or bigger than the number of
3828 lines in the buffer, an empty |List| is returned.
3829
3830 When {end} is greater than the number of lines in the buffer,
3831 it is treated as {end} is set to the number of lines in the
3832 buffer. When {end} is before {lnum} an empty |List| is
3833 returned.
3834
3835 This function works only for loaded buffers. For unloaded and
3836 non-existing buffers, an empty |List| is returned.
3837
3838 Example: >
3839 :let lines = getbufline(bufnr("myfile"), 1, "$")
3840
3841< Can also be used as a |method|: >
3842 GetBufnr()->getbufline(lnum)
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003843<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003844 Return type: list<string>
3845
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00003846 *getbufoneline()*
3847getbufoneline({buf}, {lnum})
3848 Just like `getbufline()` but only get one line and return it
3849 as a string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003850
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003851 Return type: |String|
3852
3853
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003854getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3855 The result is the value of option or local buffer variable
3856 {varname} in buffer {buf}. Note that the name without "b:"
3857 must be used.
3858 The {varname} argument is a string.
3859 When {varname} is empty returns a |Dictionary| with all the
3860 buffer-local variables.
3861 When {varname} is equal to "&" returns a |Dictionary| with all
3862 the buffer-local options.
3863 Otherwise, when {varname} starts with "&" returns the value of
3864 a buffer-local option.
3865 This also works for a global or buffer-local option, but it
3866 doesn't work for a global variable, window-local variable or
3867 window-local option.
3868 For the use of {buf}, see |bufname()| above.
3869 When the buffer or variable doesn't exist {def} or an empty
3870 string is returned, there is no error message.
3871 Examples: >
3872 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003873 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003874
3875< Can also be used as a |method|: >
3876 GetBufnr()->getbufvar(varname)
3877<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003878 Return type: any, depending on {varname}
3879
3880
mikoto20001083cae2024-11-11 21:24:14 +01003881getcellpixels() *getcellpixels()*
3882 Returns a |List| of terminal cell pixel size.
h-eastb534e802024-12-03 20:37:52 +01003883 List format is [xpixel, ypixel].
mikoto2000a73dfc22024-11-18 21:12:21 +01003884
3885 Only works on Unix (terminal and gVim) and Windows (gVim only).
3886 Returns [] on other systems or on failure.
3887 Note that there could be variations across different terminals.
3888 On macOS, system Terminal.app returns sizes in points (before
3889 Retina scaling), whereas third-party terminals return raw pixel
3890 sizes (post Retina scaling).
mikoto20001083cae2024-11-11 21:24:14 +01003891
mikoto2000de094dc2024-11-14 22:13:48 +01003892 Return type: list<any>
mikoto20001083cae2024-11-11 21:24:14 +01003893
3894
Kota Kato66bb9ae2023-01-17 18:31:56 +00003895getcellwidths() *getcellwidths()*
3896 Returns a |List| of cell widths of character ranges overridden
3897 by |setcellwidths()|. The format is equal to the argument of
3898 |setcellwidths()|. If no character ranges have their cell
3899 widths overridden, an empty List is returned.
h-east84ac2122024-06-17 18:12:30 +02003900
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003901 Return type: list<any>
Kota Kato66bb9ae2023-01-17 18:31:56 +00003902
3903
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003904getchangelist([{buf}]) *getchangelist()*
3905 Returns the |changelist| for the buffer {buf}. For the use
3906 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3907 exist, an empty list is returned.
3908
3909 The returned list contains two entries: a list with the change
3910 locations and the current position in the list. Each
3911 entry in the change list is a dictionary with the following
3912 entries:
3913 col column number
3914 coladd column offset for 'virtualedit'
3915 lnum line number
3916 If buffer {buf} is the current buffer, then the current
3917 position refers to the position in the list. For other
3918 buffers, it is set to the length of the list.
3919
3920 Can also be used as a |method|: >
3921 GetBufnr()->getchangelist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02003922<
3923 Return type: list<any>
3924
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003925
zeertzjqe0a2ab32025-02-02 09:14:35 +01003926getchar([{expr} [, {opts}]]) *getchar()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003927 Get a single character from the user or input stream.
zeertzjqe0a2ab32025-02-02 09:14:35 +01003928 If {expr} is omitted or is -1, wait until a character is
3929 available.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003930 If {expr} is 0, only get a character when one is available.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003931 Return zero otherwise.
Doug Kearns9cd9e752024-04-07 17:42:17 +02003932 If {expr} is 1, only check if a character is available, it is
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003933 not consumed. Return zero if no character available.
zeertzjqe0a2ab32025-02-02 09:14:35 +01003934 If you prefer always getting a string use |getcharstr()|, or
3935 specify |FALSE| as "number" in {opts}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003936
Doug Kearns9cd9e752024-04-07 17:42:17 +02003937 Without {expr} and when {expr} is 0 a whole character or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003938 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01003939 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003940 Otherwise a String is returned with the encoded character.
3941 For a special key it's a String with a sequence of bytes
3942 starting with 0x80 (decimal: 128). This is the same value as
3943 the String "\<Key>", e.g., "\<Left>". The returned value is
3944 also a String when a modifier (shift, control, alt) was used
zeertzjqe0a2ab32025-02-02 09:14:35 +01003945 that is not included in the character. |keytrans()| can also
3946 be used to convert a returned String into a readable form.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003947
Doug Kearns9cd9e752024-04-07 17:42:17 +02003948 When {expr} is 0 and Esc is typed, there will be a short delay
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003949 while Vim waits to see if this is the start of an escape
3950 sequence.
3951
Doug Kearns9cd9e752024-04-07 17:42:17 +02003952 When {expr} is 1 only the first byte is returned. For a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003953 one-byte character it is the character itself as a number.
3954 Use nr2char() to convert it to a String.
3955
3956 Use getcharmod() to obtain any additional modifiers.
3957
zeertzjqe0a2ab32025-02-02 09:14:35 +01003958 The optional argument {opts} is a Dict and supports the
3959 following items:
3960
zeertzjqedf0f7d2025-02-02 19:01:01 +01003961 cursor A String specifying cursor behavior
3962 when waiting for a character.
3963 "hide": hide the cursor.
3964 "keep": keep current cursor unchanged.
3965 "msg": move cursor to message area.
3966 (default: "msg")
3967
zeertzjqe0a2ab32025-02-02 09:14:35 +01003968 number If |TRUE|, return a Number when getting
3969 a single character.
3970 If |FALSE|, the return value is always
3971 converted to a String, and an empty
3972 String (instead of 0) is returned when
3973 no character is available.
3974 (default: |TRUE|)
3975
3976 simplify If |TRUE|, include modifiers in the
3977 character if possible. E.g., return
3978 the same value for CTRL-I and <Tab>.
3979 If |FALSE|, don't include modifiers in
3980 the character.
3981 (default: |TRUE|)
3982
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003983 When the user clicks a mouse button, the mouse event will be
3984 returned. The position can then be found in |v:mouse_col|,
3985 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3986 |getmousepos()| can also be used. Mouse move events will be
3987 ignored.
3988 This example positions the mouse as it would normally happen: >
3989 let c = getchar()
3990 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003991 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003992 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003993 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003994 endif
3995<
3996 When using bracketed paste only the first character is
3997 returned, the rest of the pasted text is dropped.
3998 |xterm-bracketed-paste|.
3999
4000 There is no prompt, you will somehow have to make clear to the
4001 user that a character has to be typed. The screen is not
4002 redrawn, e.g. when resizing the window. When using a popup
4003 window it should work better with a |popup-filter|.
4004
4005 There is no mapping for the character.
4006 Key codes are replaced, thus when the user presses the <Del>
4007 key you get the code for the <Del> key, not the raw character
4008 sequence. Examples: >
4009 getchar() == "\<Del>"
4010 getchar() == "\<S-Left>"
4011< This example redefines "f" to ignore case: >
4012 :nmap f :call FindChar()<CR>
4013 :function FindChar()
4014 : let c = nr2char(getchar())
4015 : while col('.') < col('$') - 1
4016 : normal l
4017 : if getline('.')[col('.') - 1] ==? c
4018 : break
4019 : endif
4020 : endwhile
4021 :endfunction
4022<
4023 You may also receive synthetic characters, such as
4024 |<CursorHold>|. Often you will want to ignore this and get
4025 another character: >
4026 :function GetKey()
4027 : let c = getchar()
4028 : while c == "\<CursorHold>"
4029 : let c = getchar()
4030 : endwhile
4031 : return c
4032 :endfunction
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004033<
4034 Return type: |Number| or |String|
4035
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004036
4037getcharmod() *getcharmod()*
4038 The result is a Number which is the state of the modifiers for
4039 the last obtained character with getchar() or in another way.
4040 These values are added together:
4041 2 shift
4042 4 control
4043 8 alt (meta)
4044 16 meta (when it's different from ALT)
4045 32 mouse double click
4046 64 mouse triple click
4047 96 mouse quadruple click (== 32 + 64)
Casey Tucker92e90a12024-01-25 22:44:00 +01004048 128 command (Mac) or super (GTK)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004049 Only the modifiers that have not been included in the
4050 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01004051 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004052
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004053 Return type: |Number|
4054
4055
4056getcharpos({expr}) *getcharpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004057 Get the position for String {expr}. Same as |getpos()| but the
4058 column number in the returned List is a character index
4059 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00004060 If |getpos()| returns a very large column number, equal to
4061 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004062 of the last character.
4063
4064 Example:
4065 With the cursor on '세' in line 5 with text "여보세요": >
4066 getcharpos('.') returns [0, 5, 3, 0]
4067 getpos('.') returns [0, 5, 7, 0]
4068<
4069 Can also be used as a |method|: >
4070 GetMark()->getcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004071<
4072 Return type: list<number>
4073
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004074
4075getcharsearch() *getcharsearch()*
4076 Return the current character search information as a {dict}
4077 with the following entries:
4078
4079 char character previously used for a character
4080 search (|t|, |f|, |T|, or |F|); empty string
4081 if no character search has been performed
4082 forward direction of character search; 1 for forward,
4083 0 for backward
4084 until type of character search; 1 for a |t| or |T|
4085 character search, 0 for an |f| or |F|
4086 character search
4087
4088 This can be useful to always have |;| and |,| search
4089 forward/backward regardless of the direction of the previous
4090 character search: >
4091 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
4092 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
4093< Also see |setcharsearch()|.
4094
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004095 Return type: dict<any>
4096
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004097
zeertzjqe0a2ab32025-02-02 09:14:35 +01004098getcharstr([{expr} [, {opts}]]) *getcharstr()*
4099 The same as |getchar()|, except that this always returns a
4100 String, and "number" isn't allowed in {opts}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004101
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004102 Return type: |String|
4103
Ruslan Russkikh0407d622024-10-08 22:21:05 +02004104getcmdcomplpat() *getcmdcomplpat()*
4105 Return completion pattern of the current command-line.
4106 Only works when the command line is being edited, thus
4107 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
4108 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
4109 |getcmdprompt()|, |getcmdcompltype()| and |setcmdline()|.
4110 Returns an empty string when completion is not defined.
4111
4112 Return type: |String|
4113
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004114
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004115getcmdcompltype() *getcmdcompltype()*
4116 Return the type of the current command-line completion.
4117 Only works when the command line is being edited, thus
4118 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01004119 See |:command-completion| for the return string.
Shougo Matsushita69084282024-09-23 20:34:47 +02004120 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
Ruslan Russkikh0407d622024-10-08 22:21:05 +02004121 |getcmdprompt()|, |getcmdcomplpat()| and |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004122 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004123
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004124 Return type: |String|
4125
4126
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004127getcmdline() *getcmdline()*
Shougo Matsushita69084282024-09-23 20:34:47 +02004128 Return the current command-line input. Only works when the
4129 command line is being edited, thus requires use of
4130 |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004131 Example: >
4132 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Shougo Matsushita69084282024-09-23 20:34:47 +02004133< Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()|,
4134 |getcmdprompt()| and |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004135 Returns an empty string when entering a password or using
4136 |inputsecret()|.
4137
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004138 Return type: |String|
4139
4140
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004141getcmdpos() *getcmdpos()*
4142 Return the position of the cursor in the command line as a
4143 byte count. The first column is 1.
4144 Only works when editing the command line, thus requires use of
4145 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4146 Returns 0 otherwise.
Shougo Matsushita69084282024-09-23 20:34:47 +02004147 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
4148 |getcmdprompt()| and |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004149
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004150 Return type: |Number|
4151
4152
Shougo Matsushita69084282024-09-23 20:34:47 +02004153getcmdprompt() *getcmdprompt()*
4154 Return the current command-line prompt when using functions
4155 like |input()| or |confirm()|.
4156 Only works when the command line is being edited, thus
4157 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
4158 Also see |getcmdtype()|, |getcmdline()|, |getcmdpos()|,
4159 |setcmdpos()| and |setcmdline()|.
4160
4161 Return type: |String|
4162
4163
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004164getcmdscreenpos() *getcmdscreenpos()*
4165 Return the screen position of the cursor in the command line
4166 as a byte count. The first column is 1.
4167 Instead of |getcmdpos()|, it adds the prompt position.
4168 Only works when editing the command line, thus requires use of
4169 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4170 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01004171 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
4172 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01004173
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004174 Return type: |Number|
4175
4176
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004177getcmdtype() *getcmdtype()*
4178 Return the current command-line type. Possible return values
4179 are:
4180 : normal Ex command
4181 > debug mode command |debug-mode|
4182 / forward search command
4183 ? backward search command
4184 @ |input()| command
4185 - |:insert| or |:append| command
4186 = |i_CTRL-R_=|
4187 Only works when editing the command line, thus requires use of
4188 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4189 Returns an empty string otherwise.
4190 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
4191
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004192 Return type: |String|
4193
4194
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004195getcmdwintype() *getcmdwintype()*
4196 Return the current |command-line-window| type. Possible return
4197 values are the same as |getcmdtype()|. Returns an empty string
4198 when not in the command-line window.
4199
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004200 Return type: |String|
4201
4202
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004203getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
4204 Return a list of command-line completion matches. The String
4205 {type} argument specifies what for. The following completion
4206 types are supported:
4207
4208 arglist file names in argument list
4209 augroup autocmd groups
4210 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00004211 behave |:behave| suboptions
4212 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004213 color color schemes
4214 command Ex command
4215 cmdline |cmdline-completion| result
4216 compiler compilers
4217 cscope |:cscope| suboptions
Shougo Matsushita92997dd2023-08-20 20:55:55 +02004218 custom,{func} custom completion, defined via {func}
4219 customlist,{func} custom completion, defined via {func}
zeertzjq85f36d62024-10-10 19:14:13 +02004220 diff_buffer |:diffget| and |:diffput| completion
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004221 dir directory names
LemonBoya20bf692024-07-11 22:35:53 +02004222 dir_in_path directory names in |'cdpath'|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004223 environment environment variable names
4224 event autocommand events
4225 expression Vim expression
4226 file file and directory names
4227 file_in_path file and directory names in |'path'|
4228 filetype filetype names |'filetype'|
4229 function function name
4230 help help subjects
4231 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00004232 history |:history| suboptions
Doug Kearns81642d92024-01-04 22:37:44 +01004233 keymap keyboard mappings
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004234 locale locale names (as output of locale -a)
4235 mapclear buffer argument
4236 mapping mapping name
4237 menu menus
4238 messages |:messages| suboptions
4239 option options
4240 packadd optional package |pack-add| names
zeertzjq5c8771b2023-01-24 12:34:03 +00004241 runtime |:runtime| completion
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00004242 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004243 shellcmd Shell command
zeertzjq85f36d62024-10-10 19:14:13 +02004244 shellcmdline Shell command line with filename arguments
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004245 sign |:sign| suboptions
4246 syntax syntax file names |'syntax'|
4247 syntime |:syntime| suboptions
4248 tag tags
4249 tag_listfiles tags, file names
4250 user user names
4251 var user variables
4252
4253 If {pat} is an empty string, then all the matches are
4254 returned. Otherwise only items matching {pat} are returned.
4255 See |wildcards| for the use of special characters in {pat}.
4256
4257 If the optional {filtered} flag is set to 1, then 'wildignore'
4258 is applied to filter the results. Otherwise all the matches
4259 are returned. The 'wildignorecase' option always applies.
4260
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00004261 If the 'wildoptions' option contains 'fuzzy', then fuzzy
4262 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00004263 regular expression matching is used. Thus this function
4264 follows the user preference, what happens on the command line.
4265 If you do not want this you can make 'wildoptions' empty
4266 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00004267
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004268 If {type} is "cmdline", then the |cmdline-completion| result is
4269 returned. For example, to complete the possible values after
4270 a ":call" command: >
4271 echo getcompletion('call ', 'cmdline')
4272<
4273 If there are no matches, an empty list is returned. An
4274 invalid value for {type} produces an error.
4275
4276 Can also be used as a |method|: >
4277 GetPattern()->getcompletion('color')
4278<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004279 Return type: list<string>
4280
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004281 *getcurpos()*
4282getcurpos([{winid}])
4283 Get the position of the cursor. This is like getpos('.'), but
4284 includes an extra "curswant" item in the list:
4285 [0, lnum, col, off, curswant] ~
4286 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00004287 cursor vertically. After |$| command it will be a very large
4288 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004289 |getpos()|.
4290 The first "bufnum" item is always zero. The byte position of
4291 the cursor is returned in 'col'. To get the character
4292 position, use |getcursorcharpos()|.
4293
4294 The optional {winid} argument can specify the window. It can
4295 be the window number or the |window-ID|. The last known
4296 cursor position is returned, this may be invalid for the
4297 current value of the buffer if it is not the current window.
4298 If {winid} is invalid a list with zeroes is returned.
4299
4300 This can be used to save and restore the cursor position: >
4301 let save_cursor = getcurpos()
4302 MoveTheCursorAround
4303 call setpos('.', save_cursor)
4304< Note that this only works within the window. See
4305 |winrestview()| for restoring more state.
4306
4307 Can also be used as a |method|: >
4308 GetWinid()->getcurpos()
4309<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004310 Return type: list<number>
4311
4312
4313getcursorcharpos([{winid}]) *getcursorcharpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004314 Same as |getcurpos()| but the column number in the returned
4315 List is a character index instead of a byte index.
4316
4317 Example:
4318 With the cursor on '보' in line 3 with text "여보세요": >
4319 getcursorcharpos() returns [0, 3, 2, 0, 3]
4320 getcurpos() returns [0, 3, 4, 0, 3]
4321<
4322 Can also be used as a |method|: >
4323 GetWinid()->getcursorcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004324<
4325 Return type: list<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004326
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004327
4328getcwd([{winnr} [, {tabnr}]]) *getcwd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004329 The result is a String, which is the name of the current
4330 working directory. 'autochdir' is ignored.
4331
4332 With {winnr} return the local current directory of this window
4333 in the current tab page. {winnr} can be the window number or
4334 the |window-ID|.
4335 If {winnr} is -1 return the name of the global working
4336 directory. See also |haslocaldir()|.
4337
4338 With {winnr} and {tabnr} return the local current directory of
4339 the window in the specified tab page. If {winnr} is -1 return
4340 the working directory of the tabpage.
4341 If {winnr} is zero use the current window, if {tabnr} is zero
4342 use the current tabpage.
4343 Without any arguments, return the actual working directory of
4344 the current window.
4345 Return an empty string if the arguments are invalid.
4346
4347 Examples: >
4348 " Get the working directory of the current window
4349 :echo getcwd()
4350 :echo getcwd(0)
4351 :echo getcwd(0, 0)
4352 " Get the working directory of window 3 in tabpage 2
4353 :echo getcwd(3, 2)
4354 " Get the global working directory
4355 :echo getcwd(-1)
4356 " Get the working directory of tabpage 3
4357 :echo getcwd(-1, 3)
4358 " Get the working directory of current tabpage
4359 :echo getcwd(-1, 0)
4360
4361< Can also be used as a |method|: >
4362 GetWinnr()->getcwd()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004363<
4364 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004365
4366getenv({name}) *getenv()*
4367 Return the value of environment variable {name}. The {name}
4368 argument is a string, without a leading '$'. Example: >
4369 myHome = getenv('HOME')
4370
4371< When the variable does not exist |v:null| is returned. That
4372 is different from a variable set to an empty string, although
4373 some systems interpret the empty value as the variable being
4374 deleted. See also |expr-env|.
4375
4376 Can also be used as a |method|: >
4377 GetVarname()->getenv()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004378<
4379 Return type: |String| or |Number|
4380
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004381
4382getfontname([{name}]) *getfontname()*
4383 Without an argument returns the name of the normal font being
4384 used. Like what is used for the Normal highlight group
4385 |hl-Normal|.
4386 With an argument a check is done whether String {name} is a
4387 valid font name. If not then an empty string is returned.
4388 Otherwise the actual font name is returned, or {name} if the
4389 GUI does not support obtaining the real name.
4390 Only works when the GUI is running, thus not in your vimrc or
4391 gvimrc file. Use the |GUIEnter| autocommand to use this
4392 function just after the GUI has started.
4393 Note that the GTK GUI accepts any font name, thus checking for
4394 a valid name does not work.
4395
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004396 Return type: |String|
4397
4398
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004399getfperm({fname}) *getfperm()*
4400 The result is a String, which is the read, write, and execute
4401 permissions of the given file {fname}.
4402 If {fname} does not exist or its directory cannot be read, an
4403 empty string is returned.
4404 The result is of the form "rwxrwxrwx", where each group of
4405 "rwx" flags represent, in turn, the permissions of the owner
4406 of the file, the group the file belongs to, and other users.
4407 If a user does not have a given permission the flag for this
4408 is replaced with the string "-". Examples: >
4409 :echo getfperm("/etc/passwd")
4410 :echo getfperm(expand("~/.vimrc"))
4411< This will hopefully (from a security point of view) display
4412 the string "rw-r--r--" or even "rw-------".
4413
4414 Can also be used as a |method|: >
4415 GetFilename()->getfperm()
4416<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004417 Return type: |String|
4418
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004419 For setting permissions use |setfperm()|.
4420
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004421
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004422getfsize({fname}) *getfsize()*
4423 The result is a Number, which is the size in bytes of the
4424 given file {fname}.
4425 If {fname} is a directory, 0 is returned.
4426 If the file {fname} can't be found, -1 is returned.
4427 If the size of {fname} is too big to fit in a Number then -2
4428 is returned.
4429
4430 Can also be used as a |method|: >
4431 GetFilename()->getfsize()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004432<
4433 Return type: |Number|
4434
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004435
4436getftime({fname}) *getftime()*
4437 The result is a Number, which is the last modification time of
4438 the given file {fname}. The value is measured as seconds
4439 since 1st Jan 1970, and may be passed to strftime(). See also
4440 |localtime()| and |strftime()|.
4441 If the file {fname} can't be found -1 is returned.
4442
4443 Can also be used as a |method|: >
4444 GetFilename()->getftime()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004445<
4446 Return type: |Number|
4447
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004448
4449getftype({fname}) *getftype()*
4450 The result is a String, which is a description of the kind of
4451 file of the given file {fname}.
4452 If {fname} does not exist an empty string is returned.
4453 Here is a table over different kinds of files and their
4454 results:
4455 Normal file "file"
4456 Directory "dir"
4457 Symbolic link "link"
4458 Block device "bdev"
4459 Character device "cdev"
4460 Socket "socket"
4461 FIFO "fifo"
4462 All other "other"
4463 Example: >
4464 getftype("/home")
4465< Note that a type such as "link" will only be returned on
4466 systems that support it. On some systems only "dir" and
4467 "file" are returned. On MS-Windows a symbolic link to a
4468 directory returns "dir" instead of "link".
4469
4470 Can also be used as a |method|: >
4471 GetFilename()->getftype()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004472<
4473 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004474
4475getimstatus() *getimstatus()*
4476 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01004477 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004478 See 'imstatusfunc'.
4479
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004480 Return type: |Number|
4481
4482
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004483getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
4484 Returns the |jumplist| for the specified window.
4485
4486 Without arguments use the current window.
4487 With {winnr} only use this window in the current tab page.
4488 {winnr} can also be a |window-ID|.
4489 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01004490 page. If {winnr} or {tabnr} is invalid, an empty list is
4491 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004492
4493 The returned list contains two entries: a list with the jump
4494 locations and the last used jump position number in the list.
4495 Each entry in the jump location list is a dictionary with
4496 the following entries:
4497 bufnr buffer number
4498 col column number
4499 coladd column offset for 'virtualedit'
4500 filename filename if available
4501 lnum line number
4502
4503 Can also be used as a |method|: >
4504 GetWinnr()->getjumplist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004505<
4506 Return type: list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004507
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004508 *getline()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004509getline({lnum} [, {end}])
4510 Without {end} the result is a String, which is line {lnum}
4511 from the current buffer. Example: >
4512 getline(1)
4513< When {lnum} is a String that doesn't start with a
4514 digit, |line()| is called to translate the String into a Number.
4515 To get the line under the cursor: >
4516 getline(".")
4517< When {lnum} is a number smaller than 1 or bigger than the
4518 number of lines in the buffer, an empty string is returned.
4519
4520 When {end} is given the result is a |List| where each item is
4521 a line from the current buffer in the range {lnum} to {end},
4522 including line {end}.
4523 {end} is used in the same way as {lnum}.
4524 Non-existing lines are silently omitted.
4525 When {end} is before {lnum} an empty |List| is returned.
4526 Example: >
4527 :let start = line('.')
4528 :let end = search("^$") - 1
4529 :let lines = getline(start, end)
4530
4531< Can also be used as a |method|: >
4532 ComputeLnum()->getline()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004533<
4534 Return type: list<string> or |String| depending on {end}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004535
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004536 To get lines from another buffer see |getbufline()| and
Bram Moolenaarce30ccc2022-11-21 19:57:04 +00004537 |getbufoneline()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004538
4539getloclist({nr} [, {what}]) *getloclist()*
4540 Returns a |List| with all the entries in the location list for
4541 window {nr}. {nr} can be the window number or the |window-ID|.
4542 When {nr} is zero the current window is used.
4543
4544 For a location list window, the displayed location list is
4545 returned. For an invalid window number {nr}, an empty list is
4546 returned. Otherwise, same as |getqflist()|.
4547
4548 If the optional {what} dictionary argument is supplied, then
4549 returns the items listed in {what} as a dictionary. Refer to
4550 |getqflist()| for the supported items in {what}.
4551
4552 In addition to the items supported by |getqflist()| in {what},
4553 the following item is supported by |getloclist()|:
4554
4555 filewinid id of the window used to display files
4556 from the location list. This field is
4557 applicable only when called from a
4558 location list window. See
4559 |location-list-file-window| for more
4560 details.
4561
4562 Returns a |Dictionary| with default values if there is no
4563 location list for the window {nr}.
4564 Returns an empty Dictionary if window {nr} does not exist.
4565
4566 Examples (See also |getqflist-examples|): >
4567 :echo getloclist(3, {'all': 0})
4568 :echo getloclist(5, {'filewinid': 0})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004569<
4570 Return type: list<dict<any>> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004571
4572
4573getmarklist([{buf}]) *getmarklist()*
4574 Without the {buf} argument returns a |List| with information
4575 about all the global marks. |mark|
4576
4577 If the optional {buf} argument is specified, returns the
4578 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01004579 see |bufname()|. If {buf} is invalid, an empty list is
4580 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004581
4582 Each item in the returned List is a |Dict| with the following:
4583 mark name of the mark prefixed by "'"
4584 pos a |List| with the position of the mark:
4585 [bufnum, lnum, col, off]
4586 Refer to |getpos()| for more information.
4587 file file name
4588
4589 Refer to |getpos()| for getting information about a specific
4590 mark.
4591
4592 Can also be used as a |method|: >
4593 GetBufnr()->getmarklist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004594<
4595 Return type: list<dict<any>> or list<any>
4596
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004597
4598getmatches([{win}]) *getmatches()*
4599 Returns a |List| with all matches previously defined for the
4600 current window by |matchadd()| and the |:match| commands.
4601 |getmatches()| is useful in combination with |setmatches()|,
4602 as |setmatches()| can restore a list of matches saved by
4603 |getmatches()|.
4604 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01004605 window ID instead of the current window. If {win} is invalid,
4606 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004607 Example: >
4608 :echo getmatches()
4609< [{'group': 'MyGroup1', 'pattern': 'TODO',
4610 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4611 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4612 :let m = getmatches()
4613 :call clearmatches()
4614 :echo getmatches()
4615< [] >
4616 :call setmatches(m)
4617 :echo getmatches()
4618< [{'group': 'MyGroup1', 'pattern': 'TODO',
4619 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4620 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4621 :unlet m
4622<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004623 Return type: list<dict<any>> or list<any>
4624
4625
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004626getmousepos() *getmousepos()*
4627 Returns a |Dictionary| with the last known position of the
4628 mouse. This can be used in a mapping for a mouse click or in
4629 a filter of a popup window. The items are:
4630 screenrow screen row
4631 screencol screen column
4632 winid Window ID of the click
4633 winrow row inside "winid"
4634 wincol column inside "winid"
4635 line text line inside "winid"
4636 column text column inside "winid"
zeertzjqf5a94d52023-10-15 10:03:30 +02004637 coladd offset (in screen columns) from the
4638 start of the clicked char
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004639 All numbers are 1-based.
4640
4641 If not over a window, e.g. when in the command line, then only
4642 "screenrow" and "screencol" are valid, the others are zero.
4643
4644 When on the status line below a window or the vertical
4645 separator right of a window, the "line" and "column" values
4646 are zero.
4647
4648 When the position is after the text then "column" is the
4649 length of the text in bytes plus one.
4650
4651 If the mouse is over a popup window then that window is used.
4652
4653 When using |getchar()| the Vim variables |v:mouse_lnum|,
4654 |v:mouse_col| and |v:mouse_winid| also provide these values.
4655
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004656 Return type: dict<number>
4657
4658
Bram Moolenaar24dc19c2022-11-14 19:49:15 +00004659getmouseshape() *getmouseshape()*
4660 Returns the name of the currently showing mouse pointer.
4661 When the |+mouseshape| feature is not supported or the shape
4662 is unknown an empty string is returned.
4663 This function is mainly intended for testing.
4664
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004665 Return type: |String|
4666
4667
4668getpid() *getpid()*
4669 Return a Number which is the process ID of the Vim process.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004670 On Unix and MS-Windows this is a unique number, until Vim
4671 exits.
4672
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004673 Return type: |Number|
4674
4675
4676getpos({expr}) *getpos()*
zeertzjq02f3eba2024-06-12 20:45:24 +02004677 Get the position for String {expr}.
4678 The accepted values for {expr} are: *E1209*
4679 . The cursor position.
4680 $ The last line in the current buffer.
4681 'x Position of mark x (if the mark is not set, 0 is
zeertzjqd353d272024-06-13 23:00:25 +08004682 returned for all values).
zeertzjq02f3eba2024-06-12 20:45:24 +02004683 w0 First line visible in current window (one if the
4684 display isn't updated, e.g. in silent Ex mode).
4685 w$ Last line visible in current window (this is one
4686 less than "w0" if no lines are visible).
4687 v When not in Visual mode, returns the cursor
4688 position. In Visual mode, returns the other end
4689 of the Visual area. A good way to think about
4690 this is that in Visual mode "v" and "." complement
4691 each other. While "." refers to the cursor
4692 position, "v" refers to where |v_o| would move the
4693 cursor. As a result, you can use "v" and "."
4694 together to work on all of a selection in
4695 characterwise Visual mode. If the cursor is at
4696 the end of a characterwise Visual area, "v" refers
4697 to the start of the same Visual area. And if the
4698 cursor is at the start of a characterwise Visual
4699 area, "v" refers to the end of the same Visual
4700 area. "v" differs from |'<| and |'>| in that it's
4701 updated right away.
4702 Note that a mark in another file can be used. The line number
4703 then applies to another buffer.
4704
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004705 The result is a |List| with four numbers:
4706 [bufnum, lnum, col, off]
4707 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4708 is the buffer number of the mark.
4709 "lnum" and "col" are the position in the buffer. The first
4710 column is 1.
4711 The "off" number is zero, unless 'virtualedit' is used. Then
4712 it is the offset in screen columns from the start of the
4713 character. E.g., a position within a <Tab> or after the last
4714 character.
zeertzjq02f3eba2024-06-12 20:45:24 +02004715
4716 For getting the cursor position see |getcurpos()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004717 The column number in the returned List is the byte position
4718 within the line. To get the character position in the line,
4719 use |getcharpos()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02004720
4721 Note that for '< and '> Visual mode matters: when it is "V"
4722 (visual line mode) the column of '< is zero and the column of
4723 '> is a large number equal to |v:maxcol|.
naohiro ono56200ee2022-01-01 14:59:44 +00004724 A very large column number equal to |v:maxcol| can be returned,
4725 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01004726 If {expr} is invalid, returns a list with all zeros.
zeertzjq02f3eba2024-06-12 20:45:24 +02004727
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004728 This can be used to save and restore the position of a mark: >
4729 let save_a_mark = getpos("'a")
4730 ...
4731 call setpos("'a", save_a_mark)
zeertzjqd353d272024-06-13 23:00:25 +08004732<
4733 Also see |getcharpos()|, |getcurpos()| and |setpos()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004734
4735 Can also be used as a |method|: >
4736 GetMark()->getpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004737<
4738 Return type: list<number>
4739
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004740
4741getqflist([{what}]) *getqflist()*
4742 Returns a |List| with all the current quickfix errors. Each
4743 list item is a dictionary with these entries:
4744 bufnr number of buffer that has the file name, use
4745 bufname() to get the name
4746 module module name
4747 lnum line number in the buffer (first line is 1)
4748 end_lnum
4749 end of line number if the item is multiline
4750 col column number (first column is 1)
4751 end_col end of column number if the item has range
4752 vcol |TRUE|: "col" is visual column
4753 |FALSE|: "col" is byte index
4754 nr error number
h-east84ac2122024-06-17 18:12:30 +02004755 pattern search pattern used to locate the error
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004756 text description of the error
4757 type type of the error, 'E', '1', etc.
4758 valid |TRUE|: recognized error message
h_east596a9f22023-11-21 21:24:23 +09004759 user_data
4760 custom data associated with the item, can be
Tom Praschanca6ac992023-08-11 23:26:12 +02004761 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004762
4763 When there is no error list or it's empty, an empty list is
4764 returned. Quickfix list entries with a non-existing buffer
4765 number are returned with "bufnr" set to zero (Note: some
4766 functions accept buffer number zero for the alternate buffer,
4767 you may need to explicitly check for zero).
4768
4769 Useful application: Find pattern matches in multiple files and
4770 do something with them: >
4771 :vimgrep /theword/jg *.c
4772 :for d in getqflist()
4773 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4774 :endfor
4775<
4776 If the optional {what} dictionary argument is supplied, then
4777 returns only the items listed in {what} as a dictionary. The
4778 following string items are supported in {what}:
4779 changedtick get the total number of changes made
4780 to the list |quickfix-changedtick|
4781 context get the |quickfix-context|
4782 efm errorformat to use when parsing "lines". If
4783 not present, then the 'errorformat' option
4784 value is used.
4785 id get information for the quickfix list with
4786 |quickfix-ID|; zero means the id for the
4787 current list or the list specified by "nr"
4788 idx get information for the quickfix entry at this
4789 index in the list specified by 'id' or 'nr'.
4790 If set to zero, then uses the current entry.
4791 See |quickfix-index|
4792 items quickfix list entries
4793 lines parse a list of lines using 'efm' and return
4794 the resulting entries. Only a |List| type is
4795 accepted. The current quickfix list is not
4796 modified. See |quickfix-parse|.
4797 nr get information for this quickfix list; zero
4798 means the current quickfix list and "$" means
4799 the last quickfix list
4800 qfbufnr number of the buffer displayed in the quickfix
4801 window. Returns 0 if the quickfix buffer is
4802 not present. See |quickfix-buffer|.
4803 size number of entries in the quickfix list
4804 title get the list title |quickfix-title|
4805 winid get the quickfix |window-ID|
4806 all all of the above quickfix properties
4807 Non-string items in {what} are ignored. To get the value of a
4808 particular item, set it to zero.
4809 If "nr" is not present then the current quickfix list is used.
4810 If both "nr" and a non-zero "id" are specified, then the list
4811 specified by "id" is used.
4812 To get the number of lists in the quickfix stack, set "nr" to
4813 "$" in {what}. The "nr" value in the returned dictionary
4814 contains the quickfix stack size.
4815 When "lines" is specified, all the other items except "efm"
4816 are ignored. The returned dictionary contains the entry
4817 "items" with the list of entries.
4818
4819 The returned dictionary contains the following entries:
4820 changedtick total number of changes made to the
4821 list |quickfix-changedtick|
4822 context quickfix list context. See |quickfix-context|
4823 If not present, set to "".
4824 id quickfix list ID |quickfix-ID|. If not
4825 present, set to 0.
4826 idx index of the quickfix entry in the list. If not
4827 present, set to 0.
4828 items quickfix list entries. If not present, set to
4829 an empty list.
4830 nr quickfix list number. If not present, set to 0
4831 qfbufnr number of the buffer displayed in the quickfix
4832 window. If not present, set to 0.
4833 size number of entries in the quickfix list. If not
4834 present, set to 0.
4835 title quickfix list title text. If not present, set
4836 to "".
4837 winid quickfix |window-ID|. If not present, set to 0
4838
4839 Examples (See also |getqflist-examples|): >
4840 :echo getqflist({'all': 1})
4841 :echo getqflist({'nr': 2, 'title': 1})
4842 :echo getqflist({'lines' : ["F1:10:L10"]})
4843<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004844 Return type: list<dict<any>> or list<any>
4845
4846
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004847getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4848 The result is a String, which is the contents of register
4849 {regname}. Example: >
4850 :let cliptext = getreg('*')
4851< When register {regname} was not set the result is an empty
4852 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004853 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004854
4855 getreg('=') returns the last evaluated value of the expression
4856 register. (For use in maps.)
4857 getreg('=', 1) returns the expression itself, so that it can
4858 be restored with |setreg()|. For other registers the extra
4859 argument is ignored, thus you can always give it.
4860
4861 If {list} is present and |TRUE|, the result type is changed
4862 to |List|. Each list item is one text line. Use it if you care
4863 about zero bytes possibly present inside register: without
4864 third argument both NLs and zero bytes are represented as NLs
4865 (see |NL-used-for-Nul|).
4866 When the register was not set an empty list is returned.
4867
4868 If {regname} is "", the unnamed register '"' is used.
4869 If {regname} is not specified, |v:register| is used.
4870 In |Vim9-script| {regname} must be one character.
4871
4872 Can also be used as a |method|: >
4873 GetRegname()->getreg()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004874<
4875 Return type: |String|
4876
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004877
4878getreginfo([{regname}]) *getreginfo()*
4879 Returns detailed information about register {regname} as a
4880 Dictionary with the following entries:
4881 regcontents List of lines contained in register
4882 {regname}, like
4883 |getreg|({regname}, 1, 1).
4884 regtype the type of register {regname}, as in
4885 |getregtype()|.
4886 isunnamed Boolean flag, v:true if this register
4887 is currently pointed to by the unnamed
4888 register.
4889 points_to for the unnamed register, gives the
4890 single letter name of the register
4891 currently pointed to (see |quotequote|).
4892 For example, after deleting a line
4893 with `dd`, this field will be "1",
4894 which is the register that got the
4895 deleted text.
4896
4897 The {regname} argument is a string. If {regname} is invalid
4898 or not set, an empty Dictionary will be returned.
4899 If {regname} is "" or "@", the unnamed register '"' is used.
4900 If {regname} is not specified, |v:register| is used.
4901 The returned Dictionary can be passed to |setreg()|.
4902 In |Vim9-script| {regname} must be one character.
4903
4904 Can also be used as a |method|: >
4905 GetRegname()->getreginfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004906<
4907 Return type: dict<any>
4908
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004909
Shougo Matsushita19b71882024-02-28 22:48:12 +01004910getregion({pos1}, {pos2} [, {opts}]) *getregion()*
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004911 Returns the list of strings from {pos1} to {pos2} from a
Shougo Matsushita19b71882024-02-28 22:48:12 +01004912 buffer.
4913
4914 {pos1} and {pos2} must both be |List|s with four numbers.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004915 See |getpos()| for the format of the list. It's possible
4916 to specify positions from a different buffer, but please
zeertzjq0df8f932024-03-07 21:40:53 +01004917 note the limitations at |getregion-notes|.
Shougo Matsushita19b71882024-02-28 22:48:12 +01004918
4919 The optional argument {opts} is a Dict and supports the
4920 following items:
4921
zeertzjqafc22952024-05-24 19:07:12 +02004922 type Specify the region's selection type.
4923 See |getregtype()| for possible values,
zeertzjqdff55a32024-05-25 10:25:36 +02004924 except that the width can be omitted
4925 and an empty string cannot be used.
zeertzjqafc22952024-05-24 19:07:12 +02004926 (default: "v")
Shougo Matsushita19b71882024-02-28 22:48:12 +01004927
zeertzjq87410ab2024-03-02 06:00:23 +08004928 exclusive If |TRUE|, use exclusive selection
zeertzjqafc22952024-05-24 19:07:12 +02004929 for the end position.
zeertzjq87410ab2024-03-02 06:00:23 +08004930 (default: follow 'selection')
Shougo Matsushita19b71882024-02-28 22:48:12 +01004931
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004932 You can get the last selection type by |visualmode()|.
4933 If Visual mode is active, use |mode()| to get the Visual mode
4934 (e.g., in a |:vmap|).
zeertzjq87410ab2024-03-02 06:00:23 +08004935 This function is useful to get text starting and ending in
4936 different columns, such as a |characterwise-visual| selection.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004937
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004938 *getregion-notes*
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004939 Note that:
4940 - Order of {pos1} and {pos2} doesn't matter, it will always
4941 return content from the upper left position to the lower
4942 right position.
zeertzjq87410ab2024-03-02 06:00:23 +08004943 - If 'virtualedit' is enabled and the region is past the end
4944 of the lines, resulting lines are padded with spaces.
4945 - If the region is blockwise and it starts or ends in the
4946 middle of a multi-cell character, it is not included but
4947 its selected part is substituted with spaces.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004948 - If {pos1} and {pos2} are not in the same buffer, an empty
zeertzjq421b5972024-02-22 19:48:06 +01004949 list is returned.
Shougo Matsushita84bf6e62024-03-06 21:10:18 +01004950 - {pos1} and {pos2} must belong to a |bufloaded()| buffer.
zeertzjq0df8f932024-03-07 21:40:53 +01004951 - It is evaluated in current window context, which makes a
4952 difference if the buffer is displayed in a window with
4953 different 'virtualedit' or 'list' values.
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004954
4955 Examples: >
4956 :xnoremap <CR>
Shougo Matsushita19b71882024-02-28 22:48:12 +01004957 \ <Cmd>echow getregion(
4958 \ getpos('v'), getpos('.'), #{ type: mode() })<CR>
Shougo Matsushita3f905ab2024-02-21 00:02:45 +01004959<
4960 Can also be used as a |method|: >
Shougo Matsushita19b71882024-02-28 22:48:12 +01004961 getpos('.')->getregion(getpos("'a"))
zeertzjqd4d12072024-07-16 20:34:16 +02004962<
4963 Return type: list<string>
Christian Brabandt5674c9a2024-06-09 00:13:43 +02004964
Yee Cheng Chind52fb2f2024-10-31 09:25:09 +01004965
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004966getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()*
4967 Same as |getregion()|, but returns a list of positions
4968 describing the buffer text segments bound by {pos1} and
4969 {pos2}.
4970 The segments are a pair of positions for every line: >
4971 [[{start_pos}, {end_pos}], ...]
4972<
4973 The position is a |List| with four numbers:
4974 [bufnum, lnum, col, off]
4975 "bufnum" is the buffer number.
4976 "lnum" and "col" are the position in the buffer. The first
4977 column is 1.
zeertzjqc95e64f2024-05-20 14:00:31 +02004978 If the "off" number of a starting position is non-zero, it is
4979 the offset in screen columns from the start of the character.
4980 E.g., a position within a <Tab> or after the last character.
4981 If the "off" number of an ending position is non-zero, it is
zeertzjq52a6f342024-05-22 16:42:44 +02004982 the offset of the character's first cell not included in the
4983 selection, otherwise all its cells are included.
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004984
zeertzjq2b09de92024-05-24 07:48:51 +02004985 Apart from the options supported by |getregion()|, {opts} also
4986 supports the following:
4987
4988 eol If |TRUE|, indicate positions beyond
4989 the end of a line with "col" values
4990 one more than the length of the line.
4991 If |FALSE|, positions are limited
4992 within their lines, and if a line is
4993 empty or the selection is entirely
4994 beyond the end of a line, a "col"
4995 value of 0 is used for both positions.
4996 (default: |FALSE|)
4997
Shougo Matsushitab4757e62024-05-07 20:49:24 +02004998 Can also be used as a |method|: >
4999 getpos('.')->getregionpos(getpos("'a"))
5000<
Christian Brabandt83d74402025-03-19 21:55:59 +01005001 For an example, see the highlight-yank plugin |52.6|
5002
zeertzjqd4d12072024-07-16 20:34:16 +02005003 Return type: list<list<list<number>>>
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005004
5005
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005006getregtype([{regname}]) *getregtype()*
5007 The result is a String, which is type of register {regname}.
5008 The value will be one of:
5009 "v" for |characterwise| text
5010 "V" for |linewise| text
5011 "<CTRL-V>{width}" for |blockwise-visual| text
5012 "" for an empty or unknown register
5013 <CTRL-V> is one character with value 0x16.
5014 The {regname} argument is a string. If {regname} is "", the
5015 unnamed register '"' is used. If {regname} is not specified,
5016 |v:register| is used.
5017 In |Vim9-script| {regname} must be one character.
5018
5019 Can also be used as a |method|: >
5020 GetRegname()->getregtype()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005021<
5022 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005023
Yee Cheng Chind52fb2f2024-10-31 09:25:09 +01005024
Bram Moolenaar71badf92023-04-22 22:40:14 +01005025getscriptinfo([{opts}]) *getscriptinfo()*
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01005026 Returns a |List| with information about all the sourced Vim
Bram Moolenaar753885b2022-08-24 16:30:36 +01005027 scripts in the order they were sourced, like what
5028 `:scriptnames` shows.
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01005029
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005030 The optional Dict argument {opts} supports the following
5031 optional items:
5032 name Script name match pattern. If specified,
5033 and "sid" is not specified, information about
Bram Moolenaar71badf92023-04-22 22:40:14 +01005034 scripts with a name that match the pattern
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005035 "name" are returned.
5036 sid Script ID |<SID>|. If specified, only
5037 information about the script with ID "sid" is
5038 returned and "name" is ignored.
5039
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01005040 Each item in the returned List is a |Dict| with the following
5041 items:
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005042 autoload Set to TRUE for a script that was used with
Bram Moolenaar753885b2022-08-24 16:30:36 +01005043 `import autoload` but was not actually sourced
5044 yet (see |import-autoload|).
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005045 functions List of script-local function names defined in
5046 the script. Present only when a particular
5047 script is specified using the "sid" item in
5048 {opts}.
5049 name Vim script file name.
5050 sid Script ID |<SID>|.
5051 sourced Script ID of the actually sourced script that
Bram Moolenaarfd999452022-08-24 18:30:14 +01005052 this script name links to, if any, otherwise
5053 zero
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005054 variables A dictionary with the script-local variables.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00005055 Present only when a particular script is
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005056 specified using the "sid" item in {opts}.
5057 Note that this is a copy, the value of
5058 script-local variables cannot be changed using
5059 this dictionary.
h_east59858792023-10-25 22:47:05 +09005060 version Vim script version (|scriptversion|)
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01005061
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005062 Examples: >
5063 :echo getscriptinfo({'name': 'myscript'})
zeertzjqad4881c2024-05-04 15:35:30 +08005064 :echo getscriptinfo({'sid': 15})[0].variables
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01005065<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005066 Return type: list<dict<any>>
5067
5068
ichizok663d18d2025-01-02 18:06:00 +01005069getstacktrace() *getstacktrace()*
5070 Returns the current stack trace of Vim scripts.
5071 Stack trace is a |List|, of which each item is a |Dictionary|
5072 with the following items:
zeertzjq6655bef2025-01-06 18:32:13 +01005073 funcref The funcref if the stack is at a function,
5074 otherwise this item is omitted.
ichizok663d18d2025-01-02 18:06:00 +01005075 event The string of the event description if the
zeertzjq6655bef2025-01-06 18:32:13 +01005076 stack is at an autocmd event, otherwise this
5077 item is omitted.
5078 lnum The line number in the script on the stack.
ichizok663d18d2025-01-02 18:06:00 +01005079 filepath The file path of the script on the stack.
5080
5081 Return type: list<dict<any>>
5082
5083
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005084gettabinfo([{tabnr}]) *gettabinfo()*
5085 If {tabnr} is not specified, then information about all the
5086 tab pages is returned as a |List|. Each List item is a
5087 |Dictionary|. Otherwise, {tabnr} specifies the tab page
5088 number and information about that one is returned. If the tab
5089 page does not exist an empty List is returned.
5090
5091 Each List item is a |Dictionary| with the following entries:
5092 tabnr tab page number.
5093 variables a reference to the dictionary with
5094 tabpage-local variables
5095 windows List of |window-ID|s in the tab page.
5096
5097 Can also be used as a |method|: >
5098 GetTabnr()->gettabinfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005099<
5100 Return type: list<dict<any>>
5101
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005102
5103gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
5104 Get the value of a tab-local variable {varname} in tab page
5105 {tabnr}. |t:var|
5106 Tabs are numbered starting with one.
5107 The {varname} argument is a string. When {varname} is empty a
5108 dictionary with all tab-local variables is returned.
5109 Note that the name without "t:" must be used.
5110 When the tab or variable doesn't exist {def} or an empty
5111 string is returned, there is no error message.
5112
5113 Can also be used as a |method|: >
5114 GetTabnr()->gettabvar(varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005115<
5116 Return type: any, depending on {varname}
5117
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005118
5119gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
5120 Get the value of window-local variable {varname} in window
5121 {winnr} in tab page {tabnr}.
5122 The {varname} argument is a string. When {varname} is empty a
5123 dictionary with all window-local variables is returned.
5124 When {varname} is equal to "&" get the values of all
5125 window-local options in a |Dictionary|.
5126 Otherwise, when {varname} starts with "&" get the value of a
5127 window-local option.
5128 Note that {varname} must be the name without "w:".
5129 Tabs are numbered starting with one. For the current tabpage
5130 use |getwinvar()|.
5131 {winnr} can be the window number or the |window-ID|.
5132 When {winnr} is zero the current window is used.
5133 This also works for a global option, buffer-local option and
5134 window-local option, but it doesn't work for a global variable
5135 or buffer-local variable.
5136 When the tab, window or variable doesn't exist {def} or an
5137 empty string is returned, there is no error message.
5138 Examples: >
5139 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005140 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005141<
5142 To obtain all window-local variables use: >
5143 gettabwinvar({tabnr}, {winnr}, '&')
5144
5145< Can also be used as a |method|: >
5146 GetTabnr()->gettabwinvar(winnr, varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005147<
5148 Return type: any, depending on {varname}
5149
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005150
5151gettagstack([{winnr}]) *gettagstack()*
5152 The result is a Dict, which is the tag stack of window {winnr}.
5153 {winnr} can be the window number or the |window-ID|.
5154 When {winnr} is not specified, the current window is used.
5155 When window {winnr} doesn't exist, an empty Dict is returned.
5156
5157 The returned dictionary contains the following entries:
5158 curidx Current index in the stack. When at
5159 top of the stack, set to (length + 1).
5160 Index of bottom of the stack is 1.
5161 items List of items in the stack. Each item
5162 is a dictionary containing the
5163 entries described below.
5164 length Number of entries in the stack.
5165
5166 Each item in the stack is a dictionary with the following
5167 entries:
5168 bufnr buffer number of the current jump
5169 from cursor position before the tag jump.
5170 See |getpos()| for the format of the
5171 returned list.
5172 matchnr current matching tag number. Used when
5173 multiple matching tags are found for a
5174 name.
5175 tagname name of the tag
5176
5177 See |tagstack| for more information about the tag stack.
5178
5179 Can also be used as a |method|: >
5180 GetWinnr()->gettagstack()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005181<
5182 Return type: dict<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005183
5184
Christ van Willegence0ef912024-06-20 23:41:59 +02005185gettext({text} [, {package}]) *gettext()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005186 Translate String {text} if possible.
RestorerZ96509102024-07-11 21:14:15 +02005187 This is intended for use in Vim scripts. When generating
5188 message translations the {text} is extracted by `xgettext`,
5189 the translator can add translated messages into the .po file
5190 and Vim will lookup the translation when gettext() is called.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005191 For {text} double quoted strings are preferred, because
RestorerZ96509102024-07-11 21:14:15 +02005192 `xgettext` does not support single quoted escaped text.
5193
Christ van Willegence0ef912024-06-20 23:41:59 +02005194 When the {package} is specified, the translation is looked up
RestorerZ96509102024-07-11 21:14:15 +02005195 for that specific package. This is mainly required for
5196 third-party Vim scripts. You need to specify a path to the
5197 translations with the |bindtextdomain()| function before
5198 using the gettext() function.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005199
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005200 Return type: |String|
5201
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005202
5203getwininfo([{winid}]) *getwininfo()*
5204 Returns information about windows as a |List| with Dictionaries.
5205
5206 If {winid} is given Information about the window with that ID
5207 is returned, as a |List| with one item. If the window does not
5208 exist the result is an empty list.
5209
5210 Without {winid} information about all the windows in all the
5211 tab pages is returned.
5212
5213 Each List item is a |Dictionary| with the following entries:
5214 botline last complete displayed buffer line
5215 bufnr number of buffer in the window
5216 height window height (excluding winbar)
glepnir0a850672024-11-25 19:39:04 +01005217 leftcol first column displayed; only used when
5218 'wrap' is off
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005219 loclist 1 if showing a location list
5220 {only with the +quickfix feature}
5221 quickfix 1 if quickfix or location list window
5222 {only with the +quickfix feature}
5223 terminal 1 if a terminal window
5224 {only with the +terminal feature}
5225 tabnr tab page number
5226 topline first displayed buffer line
5227 variables a reference to the dictionary with
5228 window-local variables
5229 width window width
5230 winbar 1 if the window has a toolbar, 0
5231 otherwise
5232 wincol leftmost screen column of the window;
5233 "col" from |win_screenpos()|
5234 textoff number of columns occupied by any
5235 'foldcolumn', 'signcolumn' and line
5236 number in front of the text
5237 winid |window-ID|
5238 winnr window number
5239 winrow topmost screen line of the window;
5240 "row" from |win_screenpos()|
5241
5242 Can also be used as a |method|: >
5243 GetWinnr()->getwininfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005244<
5245 Return type: list<dict<any>>
5246
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005247
5248getwinpos([{timeout}]) *getwinpos()*
5249 The result is a |List| with two numbers, the result of
5250 |getwinposx()| and |getwinposy()| combined:
5251 [x-pos, y-pos]
5252 {timeout} can be used to specify how long to wait in msec for
5253 a response from the terminal. When omitted 100 msec is used.
5254 Use a longer time for a remote terminal.
5255 When using a value less than 10 and no response is received
5256 within that time, a previously reported position is returned,
5257 if available. This can be used to poll for the position and
5258 do some work in the meantime: >
5259 while 1
5260 let res = getwinpos(1)
5261 if res[0] >= 0
5262 break
5263 endif
5264 " Do some work here
5265 endwhile
5266<
5267
5268 Can also be used as a |method|: >
5269 GetTimeout()->getwinpos()
5270<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005271 Return type: list<number>
5272
5273
5274getwinposx() *getwinposx()*
5275 The result is a Number, which is the X coordinate in pixels of
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005276 the left hand side of the GUI Vim window. Also works for an
5277 xterm (uses a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01005278 The result will be -1 if the information is not available
5279 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005280 The value can be used with `:winpos`.
5281
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005282 Return type: |Number|
5283
5284
5285getwinposy() *getwinposy()*
5286 The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005287 the top of the GUI Vim window. Also works for an xterm (uses
5288 a timeout of 100 msec).
lilydjwg6e0a18f2024-01-29 20:54:28 +01005289 The result will be -1 if the information is not available
5290 (e.g. on the Wayland backend).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005291 The value can be used with `:winpos`.
5292
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005293 Return type: |Number|
5294
5295
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005296getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
5297 Like |gettabwinvar()| for the current tabpage.
5298 Examples: >
5299 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005300 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005301
5302< Can also be used as a |method|: >
5303 GetWinnr()->getwinvar(varname)
5304<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005305 Return type: any, depending on {varname}
5306
5307
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005308glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
5309 Expand the file wildcards in {expr}. See |wildcards| for the
5310 use of special characters.
5311
5312 Unless the optional {nosuf} argument is given and is |TRUE|,
5313 the 'suffixes' and 'wildignore' options apply: Names matching
5314 one of the patterns in 'wildignore' will be skipped and
5315 'suffixes' affect the ordering of matches.
5316 'wildignorecase' always applies.
5317
5318 When {list} is present and it is |TRUE| the result is a |List|
5319 with all matching files. The advantage of using a List is,
5320 you also get filenames containing newlines correctly.
5321 Otherwise the result is a String and when there are several
5322 matches, they are separated by <NL> characters.
5323
5324 If the expansion fails, the result is an empty String or List.
5325
5326 You can also use |readdir()| if you need to do complicated
5327 things, such as limiting the number of matches.
5328
5329 A name for a non-existing file is not included. A symbolic
5330 link is only included if it points to an existing file.
5331 However, when the {alllinks} argument is present and it is
5332 |TRUE| then all symbolic links are included.
5333
5334 For most systems backticks can be used to get files names from
5335 any external command. Example: >
5336 :let tagfiles = glob("`find . -name tags -print`")
5337 :let &tags = substitute(tagfiles, "\n", ",", "g")
5338< The result of the program inside the backticks should be one
5339 item per line. Spaces inside an item are allowed.
5340
5341 See |expand()| for expanding special Vim variables. See
5342 |system()| for getting the raw output of an external command.
5343
5344 Can also be used as a |method|: >
5345 GetExpr()->glob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005346<
5347 Return type: |String| or list<string> or list<any> depending
5348 on {list}
5349
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005350
h-east624bb832024-11-09 18:37:32 +01005351glob2regpat({string}) *glob2regpat()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005352 Convert a file pattern, as used by glob(), into a search
5353 pattern. The result can be used to match with a string that
5354 is a file name. E.g. >
5355 if filename =~ glob2regpat('Make*.mak')
5356< This is equivalent to: >
5357 if filename =~ '^Make.*\.mak$'
5358< When {string} is an empty string the result is "^$", match an
5359 empty string.
5360 Note that the result depends on the system. On MS-Windows
5361 a backslash usually means a path separator.
5362
5363 Can also be used as a |method|: >
5364 GetExpr()->glob2regpat()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005365<
5366 Return type: |String|
5367
5368 *globpath()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005369globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
5370 Perform glob() for String {expr} on all directories in {path}
5371 and concatenate the results. Example: >
5372 :echo globpath(&rtp, "syntax/c.vim")
5373<
5374 {path} is a comma-separated list of directory names. Each
5375 directory name is prepended to {expr} and expanded like with
5376 |glob()|. A path separator is inserted when needed.
5377 To add a comma inside a directory name escape it with a
5378 backslash. Note that on MS-Windows a directory may have a
5379 trailing backslash, remove it if you put a comma after it.
5380 If the expansion fails for one of the directories, there is no
5381 error message.
5382
5383 Unless the optional {nosuf} argument is given and is |TRUE|,
5384 the 'suffixes' and 'wildignore' options apply: Names matching
5385 one of the patterns in 'wildignore' will be skipped and
5386 'suffixes' affect the ordering of matches.
5387
5388 When {list} is present and it is |TRUE| the result is a |List|
5389 with all matching files. The advantage of using a List is, you
5390 also get filenames containing newlines correctly. Otherwise
5391 the result is a String and when there are several matches,
5392 they are separated by <NL> characters. Example: >
5393 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
5394<
5395 {alllinks} is used as with |glob()|.
5396
5397 The "**" item can be used to search in a directory tree.
5398 For example, to find all "README.txt" files in the directories
5399 in 'runtimepath' and below: >
5400 :echo globpath(&rtp, "**/README.txt")
5401< Upwards search and limiting the depth of "**" is not
5402 supported, thus using 'path' will not always work properly.
5403
5404 Can also be used as a |method|, the base is passed as the
5405 second argument: >
5406 GetExpr()->globpath(&rtp)
5407<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005408 Return type: |String| or list<string> or list<any> depending
5409 on {list}
5410
5411
5412has({feature} [, {check}]) *has()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005413 When {check} is omitted or is zero: The result is a Number,
5414 which is 1 if the feature {feature} is supported, zero
5415 otherwise. The {feature} argument is a string, case is
5416 ignored. See |feature-list| below.
5417
5418 When {check} is present and not zero: The result is a Number,
5419 which is 1 if the feature {feature} could ever be supported,
5420 zero otherwise. This is useful to check for a typo in
5421 {feature} and to detect dead code. Keep in mind that an older
5422 Vim version will not know about a feature added later and
5423 features that have been abandoned will not be known by the
5424 current Vim version.
5425
5426 Also see |exists()| and |exists_compiled()|.
5427
5428 Note that to skip code that has a syntax error when the
5429 feature is not available, Vim may skip the rest of the line
5430 and miss a following `endif`. Therefore put the `endif` on a
5431 separate line: >
5432 if has('feature')
5433 let x = this->breaks->without->the->feature
5434 endif
5435< If the `endif` would be moved to the second line as "| endif" it
5436 would not be found.
5437
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005438 Return type: |Number|
5439
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005440
5441has_key({dict}, {key}) *has_key()*
5442 The result is a Number, which is TRUE if |Dictionary| {dict}
Bram Moolenaare8008642022-08-19 17:15:35 +01005443 has an entry with key {key}. FALSE otherwise.
5444 The {key} argument is a string. In |Vim9| script a number is
5445 also accepted (and converted to a string) but no other types.
5446 In legacy script the usual automatic conversion to string is
5447 done.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005448
5449 Can also be used as a |method|: >
5450 mydict->has_key(key)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005451<
5452 Return type: |Number|
5453
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005454
5455haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
5456 The result is a Number:
5457 1 when the window has set a local directory via |:lcd|
5458 2 when the tab-page has set a local directory via |:tcd|
5459 0 otherwise.
5460
5461 Without arguments use the current window.
5462 With {winnr} use this window in the current tab page.
5463 With {winnr} and {tabnr} use the window in the specified tab
5464 page.
5465 {winnr} can be the window number or the |window-ID|.
5466 If {winnr} is -1 it is ignored and only the tabpage is used.
5467 Return 0 if the arguments are invalid.
5468 Examples: >
5469 if haslocaldir() == 1
5470 " window local directory case
5471 elseif haslocaldir() == 2
5472 " tab-local directory case
5473 else
5474 " global directory case
5475 endif
5476
5477 " current window
5478 :echo haslocaldir()
5479 :echo haslocaldir(0)
5480 :echo haslocaldir(0, 0)
5481 " window n in current tab page
5482 :echo haslocaldir(n)
5483 :echo haslocaldir(n, 0)
5484 " window n in tab page m
5485 :echo haslocaldir(n, m)
5486 " tab page m
5487 :echo haslocaldir(-1, m)
5488<
5489 Can also be used as a |method|: >
5490 GetWinnr()->haslocaldir()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005491<
5492 Return type: |Number|
5493
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005494
5495hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
5496 The result is a Number, which is TRUE if there is a mapping
5497 that contains {what} in somewhere in the rhs (what it is
5498 mapped to) and this mapping exists in one of the modes
5499 indicated by {mode}.
5500 The arguments {what} and {mode} are strings.
5501 When {abbr} is there and it is |TRUE| use abbreviations
5502 instead of mappings. Don't forget to specify Insert and/or
5503 Command-line mode.
5504 Both the global mappings and the mappings local to the current
5505 buffer are checked for a match.
5506 If no matching mapping is found FALSE is returned.
5507 The following characters are recognized in {mode}:
5508 n Normal mode
5509 v Visual and Select mode
5510 x Visual mode
5511 s Select mode
5512 o Operator-pending mode
5513 i Insert mode
5514 l Language-Argument ("r", "f", "t", etc.)
5515 c Command-line mode
5516 When {mode} is omitted, "nvo" is used.
5517
5518 This function is useful to check if a mapping already exists
5519 to a function in a Vim script. Example: >
5520 :if !hasmapto('\ABCdoit')
5521 : map <Leader>d \ABCdoit
5522 :endif
5523< This installs the mapping to "\ABCdoit" only if there isn't
5524 already a mapping to "\ABCdoit".
5525
5526 Can also be used as a |method|: >
5527 GetRHS()->hasmapto()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005528<
5529 Return type: |Number|
5530
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005531
5532histadd({history}, {item}) *histadd()*
5533 Add the String {item} to the history {history} which can be
5534 one of: *hist-names*
5535 "cmd" or ":" command line history
5536 "search" or "/" search pattern history
5537 "expr" or "=" typed expression history
5538 "input" or "@" input line history
5539 "debug" or ">" debug command history
5540 empty the current or last used history
5541 The {history} string does not need to be the whole name, one
5542 character is sufficient.
5543 If {item} does already exist in the history, it will be
5544 shifted to become the newest entry.
5545 The result is a Number: TRUE if the operation was successful,
5546 otherwise FALSE is returned.
5547
5548 Example: >
5549 :call histadd("input", strftime("%Y %b %d"))
5550 :let date=input("Enter date: ")
5551< This function is not available in the |sandbox|.
5552
5553 Can also be used as a |method|, the base is passed as the
5554 second argument: >
5555 GetHistory()->histadd('search')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005556<
5557 Return type: |Number|
5558
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005559
5560histdel({history} [, {item}]) *histdel()*
5561 Clear {history}, i.e. delete all its entries. See |hist-names|
5562 for the possible values of {history}.
5563
5564 If the parameter {item} evaluates to a String, it is used as a
5565 regular expression. All entries matching that expression will
5566 be removed from the history (if there are any).
5567 Upper/lowercase must match, unless "\c" is used |/\c|.
5568 If {item} evaluates to a Number, it will be interpreted as
5569 an index, see |:history-indexing|. The respective entry will
5570 be removed if it exists.
5571
5572 The result is TRUE for a successful operation, otherwise FALSE
5573 is returned.
5574
5575 Examples:
5576 Clear expression register history: >
5577 :call histdel("expr")
5578<
5579 Remove all entries starting with "*" from the search history: >
5580 :call histdel("/", '^\*')
5581<
5582 The following three are equivalent: >
5583 :call histdel("search", histnr("search"))
5584 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005585 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005586<
5587 To delete the last search pattern and use the last-but-one for
5588 the "n" command and 'hlsearch': >
5589 :call histdel("search", -1)
5590 :let @/ = histget("search", -1)
5591<
5592 Can also be used as a |method|: >
5593 GetHistory()->histdel()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005594<
5595 Return type: |Number|
5596
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005597
5598histget({history} [, {index}]) *histget()*
5599 The result is a String, the entry with Number {index} from
5600 {history}. See |hist-names| for the possible values of
5601 {history}, and |:history-indexing| for {index}. If there is
5602 no such entry, an empty String is returned. When {index} is
5603 omitted, the most recent item from the history is used.
5604
5605 Examples:
5606 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005607 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005608
5609< Define an Ex command ":H {num}" that supports re-execution of
5610 the {num}th entry from the output of |:history|. >
5611 :command -nargs=1 H execute histget("cmd", 0+<args>)
5612<
5613 Can also be used as a |method|: >
5614 GetHistory()->histget()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005615<
5616 Return type: |String|
5617
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005618
5619histnr({history}) *histnr()*
5620 The result is the Number of the current entry in {history}.
5621 See |hist-names| for the possible values of {history}.
5622 If an error occurred, -1 is returned.
5623
5624 Example: >
5625 :let inp_index = histnr("expr")
5626
5627< Can also be used as a |method|: >
5628 GetHistory()->histnr()
5629<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005630 Return type: |Number|
5631
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005632hlexists({name}) *hlexists()*
5633 The result is a Number, which is TRUE if a highlight group
5634 called {name} exists. This is when the group has been
5635 defined in some way. Not necessarily when highlighting has
5636 been defined for it, it may also have been used for a syntax
5637 item.
5638 *highlight_exists()*
5639 Obsolete name: highlight_exists().
5640
5641 Can also be used as a |method|: >
5642 GetName()->hlexists()
5643<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005644 Return type: |Number|
5645
5646
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005647hlget([{name} [, {resolve}]]) *hlget()*
5648 Returns a List of all the highlight group attributes. If the
5649 optional {name} is specified, then returns a List with only
5650 the attributes of the specified highlight group. Returns an
5651 empty List if the highlight group {name} is not present.
5652
5653 If the optional {resolve} argument is set to v:true and the
5654 highlight group {name} is linked to another group, then the
5655 link is resolved recursively and the attributes of the
5656 resolved highlight group are returned.
5657
5658 Each entry in the returned List is a Dictionary with the
5659 following items:
5660 cleared boolean flag, set to v:true if the highlight
5661 group attributes are cleared or not yet
5662 specified. See |highlight-clear|.
5663 cterm cterm attributes. See |highlight-cterm|.
5664 ctermbg cterm background color.
5665 See |highlight-ctermbg|.
5666 ctermfg cterm foreground color.
5667 See |highlight-ctermfg|.
5668 ctermul cterm underline color. See |highlight-ctermul|.
5669 default boolean flag, set to v:true if the highlight
5670 group link is a default link. See
5671 |highlight-default|.
5672 font highlight group font. See |highlight-font|.
5673 gui gui attributes. See |highlight-gui|.
5674 guibg gui background color. See |highlight-guibg|.
5675 guifg gui foreground color. See |highlight-guifg|.
5676 guisp gui special color. See |highlight-guisp|.
5677 id highlight group ID.
5678 linksto linked highlight group name.
5679 See |:highlight-link|.
5680 name highlight group name. See |group-name|.
5681 start start terminal keycode. See |highlight-start|.
5682 stop stop terminal keycode. See |highlight-stop|.
5683 term term attributes. See |highlight-term|.
5684
5685 The 'term', 'cterm' and 'gui' items in the above Dictionary
5686 have a dictionary value with the following optional boolean
5687 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
5688 'reverse', 'inverse' and 'strikethrough'.
5689
5690 Example(s): >
5691 :echo hlget()
5692 :echo hlget('ModeMsg')
5693 :echo hlget('Number', v:true)
5694<
5695 Can also be used as a |method|: >
5696 GetName()->hlget()
5697<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005698 Return type: list<dict<any>>
5699
5700
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005701hlset({list}) *hlset()*
5702 Creates or modifies the attributes of a List of highlight
5703 groups. Each item in {list} is a dictionary containing the
5704 attributes of a highlight group. See |hlget()| for the list of
5705 supported items in this dictionary.
5706
5707 In addition to the items described in |hlget()|, the following
5708 additional items are supported in the dictionary:
5709
5710 force boolean flag to force the creation of
5711 a link for an existing highlight group
5712 with attributes.
5713
5714 The highlight group is identified using the 'name' item and
5715 the 'id' item (if supplied) is ignored. If a highlight group
5716 with a specified name doesn't exist, then it is created.
5717 Otherwise the attributes of an existing highlight group are
5718 modified.
5719
5720 If an empty dictionary value is used for the 'term' or 'cterm'
5721 or 'gui' entries, then the corresponding attributes are
5722 cleared. If the 'cleared' item is set to v:true, then all the
5723 attributes of the highlight group are cleared.
5724
5725 The 'linksto' item can be used to link a highlight group to
5726 another highlight group. See |:highlight-link|.
5727
5728 Returns zero for success, -1 for failure.
5729
5730 Example(s): >
5731 " add bold attribute to the Visual highlight group
5732 :call hlset([#{name: 'Visual',
5733 \ term: #{reverse: 1 , bold: 1}}])
5734 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
5735 :let l = hlget()
5736 :call hlset(l)
5737 " clear the Search highlight group
5738 :call hlset([#{name: 'Search', cleared: v:true}])
5739 " clear the 'term' attributes for a highlight group
5740 :call hlset([#{name: 'Title', term: {}}])
5741 " create the MyHlg group linking it to DiffAdd
5742 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
5743 " remove the MyHlg group link
5744 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
5745 " clear the attributes and a link
5746 :call hlset([#{name: 'MyHlg', cleared: v:true,
5747 \ linksto: 'NONE'}])
5748<
5749 Can also be used as a |method|: >
5750 GetAttrList()->hlset()
5751<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005752 Return type: |Number|
5753
5754hlID({name}) *hlID()*
5755 The result is a Number, which is the ID of the highlight group
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005756 with name {name}. When the highlight group doesn't exist,
5757 zero is returned.
5758 This can be used to retrieve information about the highlight
5759 group. For example, to get the background color of the
5760 "Comment" group: >
5761 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5762< *highlightID()*
5763 Obsolete name: highlightID().
5764
5765 Can also be used as a |method|: >
5766 GetName()->hlID()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005767<
5768 Return type: |Number|
5769
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005770
5771hostname() *hostname()*
5772 The result is a String, which is the name of the machine on
5773 which Vim is currently running. Machine names greater than
5774 256 characters long are truncated.
5775
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005776 Return type: |String|
5777
5778
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005779iconv({string}, {from}, {to}) *iconv()*
5780 The result is a String, which is the text {string} converted
5781 from encoding {from} to encoding {to}.
5782 When the conversion completely fails an empty string is
5783 returned. When some characters could not be converted they
5784 are replaced with "?".
5785 The encoding names are whatever the iconv() library function
5786 can accept, see ":!man 3 iconv".
5787 Most conversions require Vim to be compiled with the |+iconv|
5788 feature. Otherwise only UTF-8 to latin1 conversion and back
5789 can be done.
5790 This can be used to display messages with special characters,
5791 no matter what 'encoding' is set to. Write the message in
5792 UTF-8 and use: >
5793 echo iconv(utf8_str, "utf-8", &enc)
5794< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5795 from/to UCS-2 is automatically changed to use UTF-8. You
5796 cannot use UCS-2 in a string anyway, because of the NUL bytes.
5797
5798 Can also be used as a |method|: >
5799 GetText()->iconv('latin1', 'utf-8')
5800<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005801 Return type: |String|
5802
5803
h-east624bb832024-11-09 18:37:32 +01005804id({item}) *id()*
Ernie Raelc8e158b2024-07-09 18:39:52 +02005805 The result is a unique String associated with the {item} and
5806 not with the {item}'s contents. It is only valid while the
5807 {item} exists and is referenced. It is valid only in the
5808 instance of vim that produces the result. The whole idea is
5809 that `id({item})` does not change if the contents of {item}
5810 changes. This is useful as a `key` for creating an identity
5811 dictionary, rather than one based on equals.
5812
5813 This operation does not reference {item} and there is no
5814 function to convert the `id` to the {item}. It may be useful to
5815 have a map of `id` to {item}. The following >
5816 var referenceMap: dict<any>
5817 var id = item->id()
5818 referenceMap[id] = item
5819< prevents {item} from being garbage collected and provides a
5820 way to get the {item} from the `id`.
5821
5822 {item} may be a List, Dictionary, Object, Job, Channel or
5823 Blob. If the item is not a permitted type, or it is a null
5824 value, then an empty String is returned.
5825
5826 Can also be used as a |method|: >
5827 GetItem()->id()
5828<
5829 Return type: |String|
5830
5831
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005832indent({lnum}) *indent()*
5833 The result is a Number, which is indent of line {lnum} in the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005834 current buffer. The indent is counted in spaces, the value
5835 of 'tabstop' is relevant. {lnum} is used just like in
5836 |getline()|.
5837 When {lnum} is invalid -1 is returned. In |Vim9| script an
5838 error is given.
5839
5840 Can also be used as a |method|: >
5841 GetLnum()->indent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005842<
5843 Return type: |Number|
5844
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005845
5846index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005847 Find {expr} in {object} and return its index. See
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005848 |indexof()| for using a lambda to select the item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005849
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005850 If {object} is a |List| return the lowest index where the item
5851 has a value equal to {expr}. There is no automatic
5852 conversion, so the String "4" is different from the Number 4.
5853 And the number 4 is different from the Float 4.0. The value
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005854 of 'ignorecase' is not used here, case matters as indicated by
5855 the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005856
5857 If {object} is |Blob| return the lowest index where the byte
5858 value is equal to {expr}.
5859
5860 If {start} is given then start looking at the item with index
5861 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005862
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005863 When {ic} is given and it is |TRUE|, ignore case. Otherwise
5864 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005865
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005866 -1 is returned when {expr} is not found in {object}.
5867 Example: >
5868 :let idx = index(words, "the")
5869 :if index(numbers, 123) >= 0
5870
5871< Can also be used as a |method|: >
5872 GetObject()->index(what)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005873<
5874 Return type: |Number|
5875
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005876
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005877indexof({object}, {expr} [, {opts}]) *indexof()*
5878 Returns the index of an item in {object} where {expr} is
5879 v:true. {object} must be a |List| or a |Blob|.
5880
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005881 If {object} is a |List|, evaluate {expr} for each item in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005882 List until the expression is v:true and return the index of
5883 this item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005884
5885 If {object} is a |Blob| evaluate {expr} for each byte in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005886 Blob until the expression is v:true and return the index of
5887 this byte.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005888
5889 {expr} must be a |string| or |Funcref|.
5890
5891 If {expr} is a |string|: If {object} is a |List|, inside
5892 {expr} |v:key| has the index of the current List item and
5893 |v:val| has the value of the item. If {object} is a |Blob|,
5894 inside {expr} |v:key| has the index of the current byte and
5895 |v:val| has the byte value.
5896
5897 If {expr} is a |Funcref| it must take two arguments:
5898 1. the key or the index of the current item.
5899 2. the value of the current item.
5900 The function must return |TRUE| if the item is found and the
5901 search should stop.
5902
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005903 The optional argument {opts} is a Dict and supports the
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005904 following items:
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005905 startidx start evaluating {expr} at the item with this
5906 index; may be negative for an item relative to
5907 the end
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005908 Returns -1 when {expr} evaluates to v:false for all the items.
5909 Example: >
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01005910 :let l = [#{n: 10}, #{n: 20}, #{n: 30}]
5911 :echo indexof(l, "v:val.n == 20")
5912 :echo indexof(l, {i, v -> v.n == 30})
5913 :echo indexof(l, "v:val.n == 20", #{startidx: 1})
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005914
5915< Can also be used as a |method|: >
5916 mylist->indexof(expr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005917<
5918 Return type: |Number|
5919
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01005920
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005921input({prompt} [, {text} [, {completion}]]) *input()*
5922 The result is a String, which is whatever the user typed on
5923 the command-line. The {prompt} argument is either a prompt
5924 string, or a blank string (for no prompt). A '\n' can be used
5925 in the prompt to start a new line.
5926 The highlighting set with |:echohl| is used for the prompt.
5927 The input is entered just like a command-line, with the same
5928 editing commands and mappings. There is a separate history
5929 for lines typed for input().
5930 Example: >
5931 :if input("Coffee or beer? ") == "beer"
5932 : echo "Cheers!"
5933 :endif
5934<
5935 If the optional {text} argument is present and not empty, this
5936 is used for the default reply, as if the user typed this.
5937 Example: >
5938 :let color = input("Color? ", "white")
5939
5940< The optional {completion} argument specifies the type of
5941 completion supported for the input. Without it completion is
5942 not performed. The supported completion types are the same as
5943 that can be supplied to a user-defined command using the
5944 "-complete=" argument. Refer to |:command-completion| for
5945 more information. Example: >
5946 let fname = input("File: ", "", "file")
5947<
5948 NOTE: This function must not be used in a startup file, for
5949 the versions that only run in GUI mode (e.g., the Win32 GUI).
5950 Note: When input() is called from within a mapping it will
5951 consume remaining characters from that mapping, because a
5952 mapping is handled like the characters were typed.
5953 Use |inputsave()| before input() and |inputrestore()|
5954 after input() to avoid that. Another solution is to avoid
5955 that further characters follow in the mapping, e.g., by using
5956 |:execute| or |:normal|.
5957
5958 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005959 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005960 :function GetFoo()
5961 : call inputsave()
5962 : let g:Foo = input("enter search pattern: ")
5963 : call inputrestore()
5964 :endfunction
5965
5966< Can also be used as a |method|: >
5967 GetPrompt()->input()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005968<
5969 Return type: |String|
5970
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005971
5972inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
5973 Like |input()|, but when the GUI is running and text dialogs
5974 are supported, a dialog window pops up to input the text.
5975 Example: >
5976 :let n = inputdialog("value for shiftwidth", shiftwidth())
5977 :if n != ""
5978 : let &sw = n
5979 :endif
5980< When the dialog is cancelled {cancelreturn} is returned. When
5981 omitted an empty string is returned.
5982 Hitting <Enter> works like pressing the OK button. Hitting
5983 <Esc> works like pressing the Cancel button.
5984 NOTE: Command-line completion is not supported.
5985
5986 Can also be used as a |method|: >
5987 GetPrompt()->inputdialog()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02005988<
5989 Return type: |String|
5990
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005991
5992inputlist({textlist}) *inputlist()*
5993 {textlist} must be a |List| of strings. This |List| is
5994 displayed, one string per line. The user will be prompted to
5995 enter a number, which is returned.
5996 The user can also select an item by clicking on it with the
5997 mouse, if the mouse is enabled in the command line ('mouse' is
5998 "a" or includes "c"). For the first string 0 is returned.
5999 When clicking above the first item a negative number is
6000 returned. When clicking on the prompt one more than the
6001 length of {textlist} is returned.
6002 Make sure {textlist} has less than 'lines' entries, otherwise
6003 it won't work. It's a good idea to put the entry number at
6004 the start of the string. And put a prompt in the first item.
6005 Example: >
6006 let color = inputlist(['Select color:', '1. red',
6007 \ '2. green', '3. blue'])
6008
6009< Can also be used as a |method|: >
6010 GetChoices()->inputlist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006011<
6012 Return type: |Number|
6013
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006014
6015inputrestore() *inputrestore()*
6016 Restore typeahead that was saved with a previous |inputsave()|.
6017 Should be called the same number of times inputsave() is
6018 called. Calling it more often is harmless though.
6019 Returns TRUE when there is nothing to restore, FALSE otherwise.
6020
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006021 Return type: |Number|
6022
6023
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006024inputsave() *inputsave()*
6025 Preserve typeahead (also from mappings) and clear it, so that
6026 a following prompt gets input from the user. Should be
6027 followed by a matching inputrestore() after the prompt. Can
6028 be used several times, in which case there must be just as
6029 many inputrestore() calls.
6030 Returns TRUE when out of memory, FALSE otherwise.
6031
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006032 Return type: |Number|
6033
6034
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006035inputsecret({prompt} [, {text}]) *inputsecret()*
6036 This function acts much like the |input()| function with but
6037 two exceptions:
6038 a) the user's response will be displayed as a sequence of
6039 asterisks ("*") thereby keeping the entry secret, and
6040 b) the user's response will not be recorded on the input
6041 |history| stack.
6042 The result is a String, which is whatever the user actually
6043 typed on the command-line in response to the issued prompt.
6044 NOTE: Command-line completion is not supported.
6045
6046 Can also be used as a |method|: >
6047 GetPrompt()->inputsecret()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006048<
6049 Return type: |String|
6050
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006051
6052insert({object}, {item} [, {idx}]) *insert()*
6053 When {object} is a |List| or a |Blob| insert {item} at the start
6054 of it.
6055
6056 If {idx} is specified insert {item} before the item with index
6057 {idx}. If {idx} is zero it goes before the first item, just
6058 like omitting {idx}. A negative {idx} is also possible, see
6059 |list-index|. -1 inserts just before the last item.
6060
6061 Returns the resulting |List| or |Blob|. Examples: >
6062 :let mylist = insert([2, 3, 5], 1)
6063 :call insert(mylist, 4, -1)
6064 :call insert(mylist, 6, len(mylist))
6065< The last example can be done simpler with |add()|.
6066 Note that when {item} is a |List| it is inserted as a single
6067 item. Use |extend()| to concatenate |Lists|.
6068
6069 Can also be used as a |method|: >
6070 mylist->insert(item)
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07006071<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006072 Return type: |Number|
6073
6074
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07006075 *instanceof()* *E614* *E616* *E693*
6076instanceof({object}, {class})
6077 The result is a Number, which is |TRUE| when the {object}
Ernie Rael2025af12023-12-12 16:58:00 +01006078 argument is a direct or indirect instance of a |Class|,
6079 |Interface|, or class |:type| alias specified by {class}.
6080 If {class} is varargs, the function returns |TRUE| when
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07006081 {object} is an instance of any of the specified classes.
LemonBoyafe04662023-08-23 21:08:11 +02006082 Example: >
Ernie Rael2025af12023-12-12 16:58:00 +01006083 instanceof(animal, Dog, Cat)
LemonBoyafe04662023-08-23 21:08:11 +02006084
6085< Can also be used as a |method|: >
6086 myobj->instanceof(mytype)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006087<
6088 Return type: |Number|
LemonBoyafe04662023-08-23 21:08:11 +02006089
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006090interrupt() *interrupt()*
6091 Interrupt script execution. It works more or less like the
6092 user typing CTRL-C, most commands won't execute and control
6093 returns to the user. This is useful to abort execution
6094 from lower down, e.g. in an autocommand. Example: >
6095 :function s:check_typoname(file)
6096 : if fnamemodify(a:file, ':t') == '['
6097 : echomsg 'Maybe typo'
6098 : call interrupt()
6099 : endif
6100 :endfunction
6101 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006102<
6103 Return type: void
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006104
6105invert({expr}) *invert()*
6106 Bitwise invert. The argument is converted to a number. A
6107 List, Dict or Float argument causes an error. Example: >
6108 :let bits = invert(bits)
6109< Can also be used as a |method|: >
6110 :let bits = bits->invert()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006111<
6112 Return type: |Number|
6113
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006114
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01006115isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01006116 The result is a Number, which is |TRUE| when {path} is an
6117 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01006118 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01006119 On MS-Windows, it is considered absolute when it starts with an
6120 optional drive prefix and is followed by a '\' or '/'. UNC paths
6121 are always absolute.
6122 Example: >
6123 echo isabsolutepath('/usr/share/') " 1
6124 echo isabsolutepath('./foobar') " 0
6125 echo isabsolutepath('C:\Windows') " 1
6126 echo isabsolutepath('foobar') " 0
6127 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01006128<
LemonBoydca1d402022-04-28 15:26:33 +01006129 Can also be used as a |method|: >
6130 GetName()->isabsolutepath()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006131<
6132 Return type: |Number|
LemonBoydca1d402022-04-28 15:26:33 +01006133
6134
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006135isdirectory({directory}) *isdirectory()*
6136 The result is a Number, which is |TRUE| when a directory
6137 with the name {directory} exists. If {directory} doesn't
6138 exist, or isn't a directory, the result is |FALSE|. {directory}
6139 is any expression, which is used as a String.
6140
6141 Can also be used as a |method|: >
6142 GetName()->isdirectory()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006143<
6144 Return type: |Number|
6145
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006146
6147isinf({expr}) *isinf()*
6148 Return 1 if {expr} is a positive infinity, or -1 a negative
6149 infinity, otherwise 0. >
6150 :echo isinf(1.0 / 0.0)
6151< 1 >
6152 :echo isinf(-1.0 / 0.0)
6153< -1
6154
6155 Can also be used as a |method|: >
6156 Compute()->isinf()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006157<
6158 Return type: |Number|
6159
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006160
6161islocked({expr}) *islocked()* *E786*
6162 The result is a Number, which is |TRUE| when {expr} is the
6163 name of a locked variable.
6164 The string argument {expr} must be the name of a variable,
6165 |List| item or |Dictionary| entry, not the variable itself!
6166 Example: >
6167 :let alist = [0, ['a', 'b'], 2, 3]
6168 :lockvar 1 alist
6169 :echo islocked('alist') " 1
6170 :echo islocked('alist[1]') " 0
6171
Bram Moolenaar9da17d72022-02-09 21:50:44 +00006172< When {expr} is a variable that does not exist -1 is returned.
6173 If {expr} uses a range, list or dict index that is out of
6174 range or does not exist you get an error message. Use
6175 |exists()| to check for existence.
6176 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006177
6178 Can also be used as a |method|: >
6179 GetName()->islocked()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006180<
6181 Return type: |Number|
6182
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006183
6184isnan({expr}) *isnan()*
6185 Return |TRUE| if {expr} is a float with value NaN. >
6186 echo isnan(0.0 / 0.0)
6187< 1
6188
6189 Can also be used as a |method|: >
6190 Compute()->isnan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006191<
6192 Return type: |Number|
6193
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006194
6195items({dict}) *items()*
6196 Return a |List| with all the key-value pairs of {dict}. Each
6197 |List| item is a list with two items: the key of a {dict}
6198 entry and the value of this entry. The |List| is in arbitrary
6199 order. Also see |keys()| and |values()|.
6200 Example: >
6201 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006202 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006203 endfor
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01006204<
6205 A List or a String argument is also supported. In these
6206 cases, items() returns a List with the index and the value at
6207 the index.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006208
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +01006209 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006210 mydict->items()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006211<
6212 Return type: list<list<any>> or list<any>
6213
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006214
6215job_ functions are documented here: |job-functions-details|
6216
6217
6218join({list} [, {sep}]) *join()*
6219 Join the items in {list} together into one String.
6220 When {sep} is specified it is put in between the items. If
6221 {sep} is omitted a single space is used.
6222 Note that {sep} is not added at the end. You might want to
6223 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006224 let lines = join(mylist, "\n") .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006225< String items are used as-is. |Lists| and |Dictionaries| are
6226 converted into a string like with |string()|.
6227 The opposite function is |split()|.
6228
6229 Can also be used as a |method|: >
6230 mylist->join()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006231<
6232 Return type: |String|
6233
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006234
6235js_decode({string}) *js_decode()*
6236 This is similar to |json_decode()| with these differences:
6237 - Object key names do not have to be in quotes.
6238 - Strings can be in single quotes.
6239 - Empty items in an array (between two commas) are allowed and
6240 result in v:none items.
6241
6242 Can also be used as a |method|: >
6243 ReadObject()->js_decode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006244<
6245 Return type: any, depending on {varname}
6246
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006247
6248js_encode({expr}) *js_encode()*
6249 This is similar to |json_encode()| with these differences:
6250 - Object key names are not in quotes.
6251 - v:none items in an array result in an empty item between
6252 commas.
6253 For example, the Vim object:
6254 [1,v:none,{"one":1},v:none] ~
6255 Will be encoded as:
6256 [1,,{one:1},,] ~
6257 While json_encode() would produce:
6258 [1,null,{"one":1},null] ~
6259 This encoding is valid for JavaScript. It is more efficient
6260 than JSON, especially when using an array with optional items.
6261
6262 Can also be used as a |method|: >
6263 GetObject()->js_encode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006264<
6265 Return type: |String|
6266
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006267
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00006268json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006269 This parses a JSON formatted string and returns the equivalent
6270 in Vim values. See |json_encode()| for the relation between
6271 JSON and Vim values.
6272 The decoding is permissive:
6273 - A trailing comma in an array and object is ignored, e.g.
6274 "[1, 2, ]" is the same as "[1, 2]".
6275 - Integer keys are accepted in objects, e.g. {1:2} is the
6276 same as {"1":2}.
6277 - More floating point numbers are recognized, e.g. "1." for
6278 "1.0", or "001.2" for "1.2". Special floating point values
6279 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
6280 are accepted.
6281 - Leading zeroes in integer numbers are ignored, e.g. "012"
6282 for "12" or "-012" for "-12".
6283 - Capitalization is ignored in literal names null, true or
6284 false, e.g. "NULL" for "null", "True" for "true".
6285 - Control characters U+0000 through U+001F which are not
6286 escaped in strings are accepted, e.g. " " (tab
6287 character in string) for "\t".
6288 - An empty JSON expression or made of only spaces is accepted
6289 and results in v:none.
6290 - Backslash in an invalid 2-character sequence escape is
6291 ignored, e.g. "\a" is decoded as "a".
6292 - A correct surrogate pair in JSON strings should normally be
6293 a 12 character sequence such as "\uD834\uDD1E", but
6294 json_decode() silently accepts truncated surrogate pairs
6295 such as "\uD834" or "\uD834\u"
6296 *E938*
6297 A duplicate key in an object, valid in rfc7159, is not
6298 accepted by json_decode() as the result must be a valid Vim
6299 type, e.g. this fails: {"a":"b", "a":"c"}
6300
6301 Can also be used as a |method|: >
6302 ReadObject()->json_decode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006303<
6304 Return type: any, depending on {varname}
6305
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006306
6307json_encode({expr}) *json_encode()*
6308 Encode {expr} as JSON and return this as a string.
6309 The encoding is specified in:
6310 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00006311 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006312 |Number| decimal number
6313 |Float| floating point number
6314 Float nan "NaN"
6315 Float inf "Infinity"
6316 Float -inf "-Infinity"
6317 |String| in double quotes (possibly null)
6318 |Funcref| not possible, error
6319 |List| as an array (possibly null); when
6320 used recursively: []
6321 |Dict| as an object (possibly null); when
6322 used recursively: {}
6323 |Blob| as an array of the individual bytes
6324 v:false "false"
6325 v:true "true"
6326 v:none "null"
6327 v:null "null"
6328 Note that NaN and Infinity are passed on as values. This is
6329 missing in the JSON standard, but several implementations do
6330 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006331 If a string contains an illegal character then the replacement
6332 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006333
6334 Can also be used as a |method|: >
6335 GetObject()->json_encode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006336<
6337 Return type: |String|
6338
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006339
6340keys({dict}) *keys()*
6341 Return a |List| with all the keys of {dict}. The |List| is in
6342 arbitrary order. Also see |items()| and |values()|.
6343
6344 Can also be used as a |method|: >
6345 mydict->keys()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006346<
6347 Return type: list<string>
6348
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006349
zeertzjqcdc83932022-09-12 13:38:41 +01006350keytrans({string}) *keytrans()*
6351 Turn the internal byte representation of keys into a form that
6352 can be used for |:map|. E.g. >
6353 :let xx = "\<C-Home>"
6354 :echo keytrans(xx)
6355< <C-Home>
6356
6357 Can also be used as a |method|: >
6358 "\<C-Home>"->keytrans()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006359<
6360 Return type: |String|
zeertzjqcdc83932022-09-12 13:38:41 +01006361
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006362
6363len({expr}) *len()* *E701*
6364 The result is a Number, which is the length of the argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006365 When {expr} is a String or a Number the length in bytes is
6366 used, as with |strlen()|.
6367 When {expr} is a |List| the number of items in the |List| is
6368 returned.
6369 When {expr} is a |Blob| the number of bytes is returned.
6370 When {expr} is a |Dictionary| the number of entries in the
6371 |Dictionary| is returned.
mityu7f0bba22024-03-29 10:14:41 +01006372 When {expr} is an |Object|, invokes the len() method in the
6373 object (if present) to get the length (|object-len()|).
6374 Otherwise returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006375
6376 Can also be used as a |method|: >
6377 mylist->len()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006378<
6379 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006380
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006381
6382 *libcall()* *E364* *E368*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006383libcall({libname}, {funcname}, {argument})
6384 Call function {funcname} in the run-time library {libname}
6385 with single argument {argument}.
6386 This is useful to call functions in a library that you
6387 especially made to be used with Vim. Since only one argument
6388 is possible, calling standard library functions is rather
6389 limited.
6390 The result is the String returned by the function. If the
6391 function returns NULL, this will appear as an empty string ""
6392 to Vim.
6393 If the function returns a number, use libcallnr()!
6394 If {argument} is a number, it is passed to the function as an
6395 int; if {argument} is a string, it is passed as a
6396 null-terminated string.
6397 This function will fail in |restricted-mode|.
6398
6399 libcall() allows you to write your own 'plug-in' extensions to
6400 Vim without having to recompile the program. It is NOT a
6401 means to call system functions! If you try to do so Vim will
6402 very probably crash.
6403
6404 For Win32, the functions you write must be placed in a DLL
6405 and use the normal C calling convention (NOT Pascal which is
6406 used in Windows System DLLs). The function must take exactly
6407 one parameter, either a character pointer or a long integer,
6408 and must return a character pointer or NULL. The character
6409 pointer returned must point to memory that will remain valid
6410 after the function has returned (e.g. in static data in the
6411 DLL). If it points to allocated memory, that memory will
6412 leak away. Using a static buffer in the function should work,
6413 it's then freed when the DLL is unloaded.
6414
6415 WARNING: If the function returns a non-valid pointer, Vim may
6416 crash! This also happens if the function returns a number,
6417 because Vim thinks it's a pointer.
6418 For Win32 systems, {libname} should be the filename of the DLL
6419 without the ".DLL" suffix. A full path is only required if
6420 the DLL is not in the usual places.
6421 For Unix: When compiling your own plugins, remember that the
6422 object code must be compiled as position-independent ('PIC').
6423 {only in Win32 and some Unix versions, when the |+libcall|
6424 feature is present}
6425 Examples: >
6426 :echo libcall("libc.so", "getenv", "HOME")
6427
6428< Can also be used as a |method|, the base is passed as the
6429 third argument: >
6430 GetValue()->libcall("libc.so", "getenv")
6431<
6432 *libcallnr()*
6433libcallnr({libname}, {funcname}, {argument})
6434 Just like |libcall()|, but used for a function that returns an
6435 int instead of a string.
6436 {only in Win32 on some Unix versions, when the |+libcall|
6437 feature is present}
6438 Examples: >
6439 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
6440 :call libcallnr("libc.so", "printf", "Hello World!\n")
6441 :call libcallnr("libc.so", "sleep", 10)
6442<
6443 Can also be used as a |method|, the base is passed as the
6444 third argument: >
6445 GetValue()->libcallnr("libc.so", "printf")
6446<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006447 Return type: |String|
6448
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006449
6450line({expr} [, {winid}]) *line()*
6451 The result is a Number, which is the line number of the file
6452 position given with {expr}. The {expr} argument is a string.
zeertzjq02f3eba2024-06-12 20:45:24 +02006453 See |getpos()| for accepted positions.
6454
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006455 To get the column number use |col()|. To get both use
6456 |getpos()|.
zeertzjq02f3eba2024-06-12 20:45:24 +02006457
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006458 With the optional {winid} argument the values are obtained for
6459 that window instead of the current window.
zeertzjq02f3eba2024-06-12 20:45:24 +02006460
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006461 Returns 0 for invalid values of {expr} and {winid}.
zeertzjq02f3eba2024-06-12 20:45:24 +02006462
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006463 Examples: >
6464 line(".") line number of the cursor
6465 line(".", winid) idem, in window "winid"
6466 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006467 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006468<
6469 To jump to the last known position when opening a file see
6470 |last-position-jump|.
6471
6472 Can also be used as a |method|: >
6473 GetValue()->line()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006474<
6475 Return type: |Number|
6476
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006477
6478line2byte({lnum}) *line2byte()*
6479 Return the byte count from the start of the buffer for line
6480 {lnum}. This includes the end-of-line character, depending on
6481 the 'fileformat' option for the current buffer. The first
6482 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
6483 This can also be used to get the byte count for the line just
6484 below the last line: >
6485 line2byte(line("$") + 1)
6486< This is the buffer size plus one. If 'fileencoding' is empty
6487 it is the file size plus one. {lnum} is used like with
6488 |getline()|. When {lnum} is invalid, or the |+byte_offset|
6489 feature has been disabled at compile time, -1 is returned.
6490 Also see |byte2line()|, |go| and |:goto|.
6491
6492 Can also be used as a |method|: >
6493 GetLnum()->line2byte()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006494<
6495 Return type: |Number|
6496
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006497
6498lispindent({lnum}) *lispindent()*
6499 Get the amount of indent for line {lnum} according the lisp
6500 indenting rules, as with 'lisp'.
6501 The indent is counted in spaces, the value of 'tabstop' is
6502 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01006503 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006504 error is given.
6505
6506 Can also be used as a |method|: >
6507 GetLnum()->lispindent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006508<
6509 Return type: |Number|
6510
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006511
6512list2blob({list}) *list2blob()*
6513 Return a Blob concatenating all the number values in {list}.
6514 Examples: >
6515 list2blob([1, 2, 3, 4]) returns 0z01020304
6516 list2blob([]) returns 0z
6517< Returns an empty Blob on error. If one of the numbers is
6518 negative or more than 255 error *E1239* is given.
6519
6520 |blob2list()| does the opposite.
6521
6522 Can also be used as a |method|: >
6523 GetList()->list2blob()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006524<
6525 Return type: |Blob|
6526
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006527
6528list2str({list} [, {utf8}]) *list2str()*
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006529 Convert each number in {list} to a character string and
6530 concatenates them all. Examples: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006531 list2str([32]) returns " "
6532 list2str([65, 66, 67]) returns "ABC"
6533< The same can be done (slowly) with: >
6534 join(map(list, {nr, val -> nr2char(val)}), '')
6535< |str2list()| does the opposite.
6536
6537 When {utf8} is omitted or zero, the current 'encoding' is used.
6538 When {utf8} is TRUE, always return UTF-8 characters.
6539 With UTF-8 composing characters work as expected: >
6540 list2str([97, 769]) returns "á"
6541<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006542 Returns an empty string on error.
6543
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006544 Can also be used as a |method|: >
6545 GetList()->list2str()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006546<
6547 Return type: |String|
6548
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006549
6550listener_add({callback} [, {buf}]) *listener_add()*
6551 Add a callback function that will be invoked when changes have
6552 been made to buffer {buf}.
6553 {buf} refers to a buffer name or number. For the accepted
6554 values, see |bufname()|. When {buf} is omitted the current
6555 buffer is used.
6556 Returns a unique ID that can be passed to |listener_remove()|.
6557
6558 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00006559 bufnr the buffer that was changed
6560 start first changed line number
6561 end first line number below the change
6562 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006563 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00006564 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006565
6566 Example: >
6567 func Listener(bufnr, start, end, added, changes)
6568 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
6569 endfunc
6570 call listener_add('Listener', bufnr)
6571
Bram Moolenaar944697a2022-02-20 19:48:20 +00006572< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006573 dictionary with these entries:
6574 lnum the first line number of the change
6575 end the first line below the change
6576 added number of lines added; negative if lines were
6577 deleted
6578 col first column in "lnum" that was affected by
6579 the change; one if unknown or the whole line
6580 was affected; this is a byte index, first
6581 character has a value of one.
Bram Moolenaar3c053a12022-10-16 13:11:12 +01006582 When lines are inserted (not when a line is split, e.g. by
6583 typing CR in Insert mode) the values are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006584 lnum line above which the new line is added
6585 end equal to "lnum"
6586 added number of lines inserted
6587 col 1
6588 When lines are deleted the values are:
6589 lnum the first deleted line
6590 end the line below the first deleted line, before
6591 the deletion was done
6592 added negative, number of lines deleted
6593 col 1
6594 When lines are changed:
6595 lnum the first changed line
6596 end the line below the last changed line
6597 added 0
6598 col first column with a change or 1
6599
6600 The entries are in the order the changes were made, thus the
6601 most recent change is at the end. The line numbers are valid
6602 when the callback is invoked, but later changes may make them
6603 invalid, thus keeping a copy for later might not work.
6604
6605 The {callback} is invoked just before the screen is updated,
6606 when |listener_flush()| is called or when a change is being
6607 made that changes the line count in a way it causes a line
6608 number in the list of changes to become invalid.
6609
6610 The {callback} is invoked with the text locked, see
6611 |textlock|. If you do need to make changes to the buffer, use
6612 a timer to do this later |timer_start()|.
6613
6614 The {callback} is not invoked when the buffer is first loaded.
6615 Use the |BufReadPost| autocmd event to handle the initial text
6616 of a buffer.
6617 The {callback} is also not invoked when the buffer is
6618 unloaded, use the |BufUnload| autocmd event for that.
6619
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006620 Returns zero if {callback} or {buf} is invalid.
6621
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006622 Can also be used as a |method|, the base is passed as the
6623 second argument: >
6624 GetBuffer()->listener_add(callback)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006625<
6626 Return type: |Number|
6627
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006628
6629listener_flush([{buf}]) *listener_flush()*
6630 Invoke listener callbacks for buffer {buf}. If there are no
6631 pending changes then no callbacks are invoked.
6632
6633 {buf} refers to a buffer name or number. For the accepted
6634 values, see |bufname()|. When {buf} is omitted the current
6635 buffer is used.
6636
6637 Can also be used as a |method|: >
6638 GetBuffer()->listener_flush()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006639<
6640 Return type: |Number|
6641
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006642
6643listener_remove({id}) *listener_remove()*
6644 Remove a listener previously added with listener_add().
6645 Returns FALSE when {id} could not be found, TRUE when {id} was
6646 removed.
6647
6648 Can also be used as a |method|: >
6649 GetListenerId()->listener_remove()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006650<
6651 Return type: |Number|
6652
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006653
6654localtime() *localtime()*
6655 Return the current time, measured as seconds since 1st Jan
6656 1970. See also |strftime()|, |strptime()| and |getftime()|.
6657
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006658 Return type: |Number|
6659
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006660
6661log({expr}) *log()*
6662 Return the natural logarithm (base e) of {expr} as a |Float|.
6663 {expr} must evaluate to a |Float| or a |Number| in the range
6664 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006665 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006666 Examples: >
6667 :echo log(10)
6668< 2.302585 >
6669 :echo log(exp(5))
6670< 5.0
6671
6672 Can also be used as a |method|: >
6673 Compute()->log()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006674<
6675 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006676
6677
6678log10({expr}) *log10()*
6679 Return the logarithm of Float {expr} to base 10 as a |Float|.
6680 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006681 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006682 Examples: >
6683 :echo log10(1000)
6684< 3.0 >
6685 :echo log10(0.01)
6686< -2.0
6687
6688 Can also be used as a |method|: >
6689 Compute()->log10()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006690<
6691 Return type: |Float|
6692
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006693
6694luaeval({expr} [, {expr}]) *luaeval()*
6695 Evaluate Lua expression {expr} and return its result converted
6696 to Vim data structures. Second {expr} may hold additional
6697 argument accessible as _A inside first {expr}.
6698 Strings are returned as they are.
6699 Boolean objects are converted to numbers.
Bram Moolenaar73e28dc2022-09-17 21:08:33 +01006700 Numbers are converted to |Float| values.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006701 Dictionaries and lists obtained by vim.eval() are returned
6702 as-is.
6703 Other objects are returned as zero without any errors.
6704 See |lua-luaeval| for more details.
6705 Note that in a `:def` function local variables are not visible
6706 to {expr}.
6707
6708 Can also be used as a |method|: >
6709 GetExpr()->luaeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006710<
6711 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006712
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006713 {only available when compiled with the |+lua| feature}
6714
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006715
6716map({expr1}, {expr2}) *map()*
6717 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00006718 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006719 item in {expr1} with the result of evaluating {expr2}.
6720 For a |Blob| each byte is replaced.
6721 For a |String|, each character, including composing
6722 characters, is replaced.
6723 If the item type changes you may want to use |mapnew()| to
6724 create a new List or Dictionary. This is required when using
6725 Vim9 script.
6726
6727 {expr2} must be a |String| or |Funcref|.
6728
6729 If {expr2} is a |String|, inside {expr2} |v:val| has the value
6730 of the current item. For a |Dictionary| |v:key| has the key
6731 of the current item and for a |List| |v:key| has the index of
6732 the current item. For a |Blob| |v:key| has the index of the
6733 current byte. For a |String| |v:key| has the index of the
6734 current character.
6735 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006736 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006737< This puts "> " before and " <" after each item in "mylist".
6738
6739 Note that {expr2} is the result of an expression and is then
6740 used as an expression again. Often it is good to use a
6741 |literal-string| to avoid having to double backslashes. You
6742 still have to double ' quotes
6743
6744 If {expr2} is a |Funcref| it is called with two arguments:
6745 1. The key or the index of the current item.
6746 2. the value of the current item.
Bram Moolenaarb59ae592022-11-23 23:46:31 +00006747 With a legacy script lambda you don't get an error if it only
6748 accepts one argument, but with a Vim9 lambda you get "E1106:
6749 One argument too many", the number of arguments must match.
6750
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006751 The function must return the new value of the item. Example
6752 that changes each value by "key-value": >
6753 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006754 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006755 endfunc
6756 call map(myDict, function('KeyValue'))
6757< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006758 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006759< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006760 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006761< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006762 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006763<
6764 The operation is done in-place for a |List| and |Dictionary|.
6765 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006766 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006767
6768< Returns {expr1}, the |List| or |Dictionary| that was filtered,
6769 or a new |Blob| or |String|.
6770 When an error is encountered while evaluating {expr2} no
6771 further items in {expr1} are processed.
6772 When {expr2} is a Funcref errors inside a function are ignored,
6773 unless it was defined with the "abort" flag.
6774
6775 Can also be used as a |method|: >
6776 mylist->map(expr2)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006777<
6778 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
6779 depending on {expr1}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006780
6781
6782maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
6783 When {dict} is omitted or zero: Return the rhs of mapping
6784 {name} in mode {mode}. The returned String has special
6785 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01006786 listing. When {dict} is TRUE a dictionary is returned, see
6787 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006788
6789 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006790 returned if {dict} is FALSE, otherwise returns an empty Dict.
6791 When the mapping for {name} is empty, then "<Nop>" is
6792 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006793
6794 The {name} can have special key names, like in the ":map"
6795 command.
6796
6797 {mode} can be one of these strings:
6798 "n" Normal
6799 "v" Visual (including Select)
6800 "o" Operator-pending
6801 "i" Insert
6802 "c" Cmd-line
6803 "s" Select
6804 "x" Visual
6805 "l" langmap |language-mapping|
6806 "t" Terminal-Job
6807 "" Normal, Visual and Operator-pending
6808 When {mode} is omitted, the modes for "" are used.
6809
6810 When {abbr} is there and it is |TRUE| use abbreviations
6811 instead of mappings.
6812
6813 When {dict} is there and it is |TRUE| return a dictionary
6814 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01006815 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006816 "lhs" The {lhs} of the mapping as it would be typed
6817 "lhsraw" The {lhs} of the mapping as raw bytes
6818 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
6819 form, only present when it differs from "lhsraw"
6820 "rhs" The {rhs} of the mapping as typed.
6821 "silent" 1 for a |:map-silent| mapping, else 0.
6822 "noremap" 1 if the {rhs} of the mapping is not remappable.
6823 "script" 1 if mapping was defined with <script>.
6824 "expr" 1 for an expression mapping (|:map-<expr>|).
6825 "buffer" 1 for a buffer local mapping (|:map-local|).
6826 "mode" Modes for which the mapping is defined. In
6827 addition to the modes mentioned above, these
6828 characters will be used:
6829 " " Normal, Visual and Operator-pending
6830 "!" Insert and Commandline mode
6831 (|mapmode-ic|)
6832 "sid" The script local ID, used for <sid> mappings
Bram Moolenaar71badf92023-04-22 22:40:14 +01006833 (|<SID>|). Negative for special contexts.
Bram Moolenaara9528b32022-01-18 20:51:35 +00006834 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01006835 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006836 "lnum" The line number in "sid", zero if unknown.
6837 "nowait" Do not wait for other, longer mappings.
6838 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01006839 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01006840 "mode_bits" Vim's internal binary representation of "mode".
6841 |mapset()| ignores this; only "mode" is used.
6842 See |maplist()| for usage examples. The values
6843 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006844
6845 The dictionary can be used to restore a mapping with
6846 |mapset()|.
6847
6848 The mappings local to the current buffer are checked first,
6849 then the global mappings.
6850 This function can be used to map a key even when it's already
6851 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006852 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006853
6854< Can also be used as a |method|: >
6855 GetKey()->maparg('n')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006856<
6857 Return type: |String| or dict<any> depending on {dict}
6858
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006859
6860mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
6861 Check if there is a mapping that matches with {name} in mode
6862 {mode}. See |maparg()| for {mode} and special names in
6863 {name}.
6864 When {abbr} is there and it is |TRUE| use abbreviations
6865 instead of mappings.
6866 A match happens with a mapping that starts with {name} and
6867 with a mapping which is equal to the start of {name}.
6868
6869 matches mapping "a" "ab" "abc" ~
6870 mapcheck("a") yes yes yes
6871 mapcheck("abc") yes yes yes
6872 mapcheck("ax") yes no no
6873 mapcheck("b") no no no
6874
6875 The difference with maparg() is that mapcheck() finds a
6876 mapping that matches with {name}, while maparg() only finds a
6877 mapping for {name} exactly.
6878 When there is no mapping that starts with {name}, an empty
6879 String is returned. If there is one, the RHS of that mapping
6880 is returned. If there are several mappings that start with
6881 {name}, the RHS of one of them is returned. This will be
6882 "<Nop>" if the RHS is empty.
6883 The mappings local to the current buffer are checked first,
6884 then the global mappings.
6885 This function can be used to check if a mapping can be added
6886 without being ambiguous. Example: >
6887 :if mapcheck("_vv") == ""
6888 : map _vv :set guifont=7x13<CR>
6889 :endif
6890< This avoids adding the "_vv" mapping when there already is a
6891 mapping for "_v" or for "_vvv".
6892
6893 Can also be used as a |method|: >
6894 GetKey()->mapcheck('n')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006895<
6896 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006897
6898
Ernie Rael09661202022-04-25 14:40:44 +01006899maplist([{abbr}]) *maplist()*
6900 Returns a |List| of all mappings. Each List item is a |Dict|,
6901 the same as what is returned by |maparg()|, see
6902 |mapping-dict|. When {abbr} is there and it is |TRUE| use
6903 abbreviations instead of mappings.
6904
6905 Example to show all mappings with 'MultiMatch' in rhs: >
6906 vim9script
6907 echo maplist()->filter(
6908 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01006909< It can be tricky to find mappings for particular |:map-modes|.
6910 |mapping-dict|'s "mode_bits" can simplify this. For example,
6911 the mode_bits for Normal, Insert or Command-line modes are
6912 0x19. To find all the mappings available in those modes you
6913 can do: >
6914 vim9script
6915 var saved_maps = []
6916 for m in maplist()
6917 if and(m.mode_bits, 0x19) != 0
6918 saved_maps->add(m)
6919 endif
6920 endfor
6921 echo saved_maps->mapnew((_, m) => m.lhs)
6922< The values of the mode_bits are defined in Vim's src/vim.h
6923 file and they can be discovered at runtime using
6924 |:map-commands| and "maplist()". Example: >
6925 vim9script
6926 omap xyzzy <Nop>
6927 var op_bit = maplist()->filter(
6928 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
6929 ounmap xyzzy
6930 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006931<
6932 Return type: list<dict<any>>
Ernie Rael09661202022-04-25 14:40:44 +01006933
6934
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006935mapnew({expr1}, {expr2}) *mapnew()*
6936 Like |map()| but instead of replacing items in {expr1} a new
6937 List or Dictionary is created and returned. {expr1} remains
6938 unchanged. Items can still be changed by {expr2}, if you
6939 don't want that use |deepcopy()| first.
6940
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006941 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
6942 depending on {expr1}
6943
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006944
6945mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01006946mapset({dict})
6947 Restore a mapping from a dictionary, possibly returned by
6948 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
6949 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01006950 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01006951 feature allows copying mappings from one buffer to another.
6952 The dict.mode value may restore a single mapping that covers
6953 more than one mode, like with mode values of '!', ' ', 'nox',
6954 or 'v'. *E1276*
6955
6956 In the first form, {mode} and {abbr} should be the same as
6957 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006958 {mode} is used to define the mode in which the mapping is set,
6959 not the "mode" entry in {dict}.
6960 Example for saving and restoring a mapping: >
6961 let save_map = maparg('K', 'n', 0, 1)
6962 nnoremap K somethingelse
6963 ...
6964 call mapset('n', 0, save_map)
6965< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01006966 e.g. with `:map!`, you need to save/restore the mapping for
6967 all of them, when they might differ.
6968
6969 In the second form, with {dict} as the only argument, mode
6970 and abbr are taken from the dict.
6971 Example: >
6972 vim9script
6973 var save_maps = maplist()->filter(
6974 (_, m) => m.lhs == 'K')
6975 nnoremap K somethingelse
6976 cnoremap K somethingelse2
6977 # ...
6978 unmap K
6979 for d in save_maps
6980 mapset(d)
6981 endfor
Christian Brabandt5674c9a2024-06-09 00:13:43 +02006982<
6983 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006984
6985
6986match({expr}, {pat} [, {start} [, {count}]]) *match()*
6987 When {expr} is a |List| then this returns the index of the
6988 first item where {pat} matches. Each item is used as a
6989 String, |Lists| and |Dictionaries| are used as echoed.
6990
6991 Otherwise, {expr} is used as a String. The result is a
6992 Number, which gives the index (byte offset) in {expr} where
6993 {pat} matches.
6994
6995 A match at the first character or |List| item returns zero.
6996 If there is no match -1 is returned.
6997
6998 For getting submatches see |matchlist()|.
6999 Example: >
7000 :echo match("testing", "ing") " results in 4
7001 :echo match([1, 'x'], '\a') " results in 1
7002< See |string-match| for how {pat} is used.
7003 *strpbrk()*
7004 Vim doesn't have a strpbrk() function. But you can do: >
7005 :let sepidx = match(line, '[.,;: \t]')
7006< *strcasestr()*
7007 Vim doesn't have a strcasestr() function. But you can add
7008 "\c" to the pattern to ignore case: >
7009 :let idx = match(haystack, '\cneedle')
7010<
7011 If {start} is given, the search starts from byte index
7012 {start} in a String or item {start} in a |List|.
7013 The result, however, is still the index counted from the
7014 first character/item. Example: >
7015 :echo match("testing", "ing", 2)
7016< result is again "4". >
7017 :echo match("testing", "ing", 4)
7018< result is again "4". >
7019 :echo match("testing", "t", 2)
7020< result is "3".
7021 For a String, if {start} > 0 then it is like the string starts
7022 {start} bytes later, thus "^" will match at {start}. Except
7023 when {count} is given, then it's like matches before the
7024 {start} byte are ignored (this is a bit complicated to keep it
7025 backwards compatible).
7026 For a String, if {start} < 0, it will be set to 0. For a list
7027 the index is counted from the end.
7028 If {start} is out of range ({start} > strlen({expr}) for a
7029 String or {start} > len({expr}) for a |List|) -1 is returned.
7030
7031 When {count} is given use the {count}'th match. When a match
7032 is found in a String the search for the next one starts one
7033 character further. Thus this example results in 1: >
7034 echo match("testing", "..", 0, 2)
7035< In a |List| the search continues in the next item.
7036 Note that when {count} is added the way {start} works changes,
7037 see above.
7038
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007039 *match-pattern*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007040 See |pattern| for the patterns that are accepted.
7041 The 'ignorecase' option is used to set the ignore-caseness of
7042 the pattern. 'smartcase' is NOT used. The matching is always
7043 done like 'magic' is set and 'cpoptions' is empty.
7044 Note that a match at the start is preferred, thus when the
7045 pattern is using "*" (any number of matches) it tends to find
7046 zero matches at the start instead of a number of matches
7047 further down in the text.
7048
7049 Can also be used as a |method|: >
7050 GetText()->match('word')
7051 GetList()->match('word')
7052<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007053 Return type: |Number|
7054
7055
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00007056 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007057matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
7058 Defines a pattern to be highlighted in the current window (a
7059 "match"). It will be highlighted with {group}. Returns an
7060 identification number (ID), which can be used to delete the
7061 match using |matchdelete()|. The ID is bound to the window.
7062 Matching is case sensitive and magic, unless case sensitivity
7063 or magicness are explicitly overridden in {pattern}. The
7064 'magic', 'smartcase' and 'ignorecase' options are not used.
7065 The "Conceal" value is special, it causes the match to be
7066 concealed.
7067
7068 The optional {priority} argument assigns a priority to the
7069 match. A match with a high priority will have its
7070 highlighting overrule that of a match with a lower priority.
7071 A priority is specified as an integer (negative numbers are no
7072 exception). If the {priority} argument is not specified, the
7073 default priority is 10. The priority of 'hlsearch' is zero,
7074 hence all matches with a priority greater than zero will
7075 overrule it. Syntax highlighting (see 'syntax') is a separate
7076 mechanism, and regardless of the chosen priority a match will
7077 always overrule syntax highlighting.
7078
7079 The optional {id} argument allows the request for a specific
7080 match ID. If a specified ID is already taken, an error
7081 message will appear and the match will not be added. An ID
7082 is specified as a positive integer (zero excluded). IDs 1, 2
7083 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01007084 respectively. 3 is reserved for use by the |matchparen|
7085 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01007086 If the {id} argument is not specified or -1, |matchadd()|
Bram Moolenaar9f573a82022-09-29 13:50:08 +01007087 automatically chooses a free ID, which is at least 1000.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007088
7089 The optional {dict} argument allows for further custom
7090 values. Currently this is used to specify a match specific
7091 conceal character that will be shown for |hl-Conceal|
7092 highlighted matches. The dict can have the following members:
7093
7094 conceal Special character to show instead of the
7095 match (only for |hl-Conceal| highlighted
7096 matches, see |:syn-cchar|)
7097 window Instead of the current window use the
7098 window with this number or window ID.
7099
7100 The number of matches is not limited, as it is the case with
7101 the |:match| commands.
7102
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007103 Returns -1 on error.
7104
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007105 Example: >
7106 :highlight MyGroup ctermbg=green guibg=green
7107 :let m = matchadd("MyGroup", "TODO")
7108< Deletion of the pattern: >
7109 :call matchdelete(m)
7110
7111< A list of matches defined by |matchadd()| and |:match| are
7112 available from |getmatches()|. All matches can be deleted in
7113 one operation by |clearmatches()|.
7114
7115 Can also be used as a |method|: >
7116 GetGroup()->matchadd('TODO')
7117<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007118 Return type: |Number|
7119
7120
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007121 *matchaddpos()*
7122matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
7123 Same as |matchadd()|, but requires a list of positions {pos}
7124 instead of a pattern. This command is faster than |matchadd()|
Shane Harperc1b39842024-07-17 19:40:40 +02007125 because it does not handle regular expressions and it sets
7126 buffer line boundaries to redraw screen. It is supposed to be
7127 used when fast match additions and deletions are required, for
7128 example to highlight matching parentheses.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007129
7130 {pos} is a list of positions. Each position can be one of
7131 these:
7132 - A number. This whole line will be highlighted. The first
7133 line has number 1.
7134 - A list with one number, e.g., [23]. The whole line with this
7135 number will be highlighted.
7136 - A list with two numbers, e.g., [23, 11]. The first number is
7137 the line number, the second one is the column number (first
7138 column is 1, the value must correspond to the byte index as
7139 |col()| would return). The character at this position will
7140 be highlighted.
7141 - A list with three numbers, e.g., [23, 11, 3]. As above, but
7142 the third number gives the length of the highlight in bytes.
7143
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007144 Returns -1 on error.
7145
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007146 Example: >
7147 :highlight MyGroup ctermbg=green guibg=green
7148 :let m = matchaddpos("MyGroup", [[23, 24], 34])
7149< Deletion of the pattern: >
7150 :call matchdelete(m)
7151
7152< Matches added by |matchaddpos()| are returned by
7153 |getmatches()|.
7154
7155 Can also be used as a |method|: >
7156 GetGroup()->matchaddpos([23, 11])
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007157<
7158 Return type: |Number|
7159
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007160
7161matcharg({nr}) *matcharg()*
7162 Selects the {nr} match item, as set with a |:match|,
7163 |:2match| or |:3match| command.
7164 Return a |List| with two elements:
7165 The name of the highlight group used
7166 The pattern used.
7167 When {nr} is not 1, 2 or 3 returns an empty |List|.
7168 When there is no match item set returns ['', ''].
7169 This is useful to save and restore a |:match|.
7170 Highlighting matches using the |:match| commands are limited
7171 to three matches. |matchadd()| does not have this limitation.
7172
7173 Can also be used as a |method|: >
7174 GetMatch()->matcharg()
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007175<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007176 Return type: list<string>
7177
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007178 *matchbufline()*
7179matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])
7180 Returns the |List| of matches in lines from {lnum} to {end} in
7181 buffer {buf} where {pat} matches.
7182
7183 {lnum} and {end} can either be a line number or the string "$"
7184 to refer to the last line in {buf}.
7185
7186 The {dict} argument supports following items:
7187 submatches include submatch information (|/\(|)
7188
7189 For each match, a |Dict| with the following items is returned:
7190 byteidx starting byte index of the match
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007191 lnum line number where there is a match
7192 text matched string
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007193 Note that there can be multiple matches in a single line.
7194
7195 This function works only for loaded buffers. First call
7196 |bufload()| if needed.
7197
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007198 See |match-pattern| for information about the effect of some
7199 option settings on the pattern.
7200
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007201 When {buf} is not a valid buffer, the buffer is not loaded or
7202 {lnum} or {end} is not valid then an error is given and an
7203 empty |List| is returned.
7204
7205 Examples: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007206 " Assuming line 3 in buffer 5 contains "a"
7207 :echo matchbufline(5, '\<\k\+\>', 3, 3)
7208 [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
7209 " Assuming line 4 in buffer 10 contains "tik tok"
7210 :echo matchbufline(10, '\<\k\+\>', 1, 4)
7211 [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007212<
7213 If {submatch} is present and is v:true, then submatches like
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007214 "\1", "\2", etc. are also returned. Example: >
7215 " Assuming line 2 in buffer 2 contains "acd"
7216 :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007217 \ {'submatches': v:true})
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007218 [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007219< The "submatches" List always contains 9 items. If a submatch
7220 is not found, then an empty string is returned for that
7221 submatch.
7222
7223 Can also be used as a |method|: >
7224 GetBuffer()->matchbufline('mypat', 1, '$')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007225<
7226 Return type: list<dict<any>> or list<any>
7227
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007228
h-east624bb832024-11-09 18:37:32 +01007229matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007230 Deletes a match with ID {id} previously defined by |matchadd()|
7231 or one of the |:match| commands. Returns 0 if successful,
7232 otherwise -1. See example for |matchadd()|. All matches can
7233 be deleted in one operation by |clearmatches()|.
7234 If {win} is specified, use the window with this number or
7235 window ID instead of the current window.
7236
7237 Can also be used as a |method|: >
7238 GetMatch()->matchdelete()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007239<
7240 Return type: |Number|
7241
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007242
7243matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
7244 Same as |match()|, but return the index of first character
7245 after the match. Example: >
7246 :echo matchend("testing", "ing")
7247< results in "7".
7248 *strspn()* *strcspn()*
7249 Vim doesn't have a strspn() or strcspn() function, but you can
7250 do it with matchend(): >
7251 :let span = matchend(line, '[a-zA-Z]')
7252 :let span = matchend(line, '[^a-zA-Z]')
7253< Except that -1 is returned when there are no matches.
7254
7255 The {start}, if given, has the same meaning as for |match()|. >
7256 :echo matchend("testing", "ing", 2)
7257< results in "7". >
7258 :echo matchend("testing", "ing", 5)
7259< result is "-1".
7260 When {expr} is a |List| the result is equal to |match()|.
7261
7262 Can also be used as a |method|: >
7263 GetText()->matchend('word')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007264<
7265 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007266
7267
7268matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
7269 If {list} is a list of strings, then returns a |List| with all
7270 the strings in {list} that fuzzy match {str}. The strings in
7271 the returned list are sorted based on the matching score.
7272
7273 The optional {dict} argument always supports the following
7274 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01007275 matchseq When this item is present return only matches
7276 that contain the characters in {str} in the
7277 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01007278 limit Maximum number of matches in {list} to be
7279 returned. Zero means no limit.
glepnir28e40a72025-03-16 21:24:22 +01007280 camelcase Use enhanced camel case scoring making results
7281 better suited for completion related to
zeertzjqc4815c12025-03-18 20:28:00 +01007282 programming languages. Defaults to v:true.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007283
7284 If {list} is a list of dictionaries, then the optional {dict}
7285 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01007286 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007287 {str}. The value of this item should be a
7288 string.
7289 text_cb |Funcref| that will be called for every item
7290 in {list} to get the text for fuzzy matching.
7291 This should accept a dictionary item as the
7292 argument and return the text for that item to
7293 use for fuzzy matching.
7294
7295 {str} is treated as a literal string and regular expression
7296 matching is NOT supported. The maximum supported {str} length
7297 is 256.
7298
7299 When {str} has multiple words each separated by white space,
7300 then the list of strings that have all the words is returned.
7301
7302 If there are no matching strings or there is an error, then an
7303 empty list is returned. If length of {str} is greater than
7304 256, then returns an empty list.
7305
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01007306 When {limit} is given, matchfuzzy() will find up to this
7307 number of matches in {list} and return them in sorted order.
7308
Bram Moolenaar1588bc82022-03-08 21:35:07 +00007309 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007310 matching strings.
7311
7312 Example: >
7313 :echo matchfuzzy(["clay", "crow"], "cay")
7314< results in ["clay"]. >
7315 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
7316< results in a list of buffer names fuzzy matching "ndl". >
7317 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
7318< results in a list of buffer information dicts with buffer
7319 names fuzzy matching "ndl". >
7320 :echo getbufinfo()->matchfuzzy("spl",
7321 \ {'text_cb' : {v -> v.name}})
7322< results in a list of buffer information dicts with buffer
7323 names fuzzy matching "spl". >
7324 :echo v:oldfiles->matchfuzzy("test")
7325< results in a list of file names fuzzy matching "test". >
7326 :let l = readfile("buffer.c")->matchfuzzy("str")
7327< results in a list of lines in "buffer.c" fuzzy matching "str". >
7328 :echo ['one two', 'two one']->matchfuzzy('two one')
7329< results in ['two one', 'one two']. >
7330 :echo ['one two', 'two one']->matchfuzzy('two one',
7331 \ {'matchseq': 1})
7332< results in ['two one'].
7333
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007334 Return type: list<string> or list<any>
7335
7336
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007337matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
7338 Same as |matchfuzzy()|, but returns the list of matched
7339 strings, the list of character positions where characters
7340 in {str} matches and a list of matching scores. You can
7341 use |byteidx()| to convert a character position to a byte
7342 position.
7343
7344 If {str} matches multiple times in a string, then only the
7345 positions for the best match is returned.
7346
7347 If there are no matching strings or there is an error, then a
7348 list with three empty list items is returned.
7349
7350 Example: >
7351 :echo matchfuzzypos(['testing'], 'tsg')
7352< results in [['testing'], [[0, 2, 6]], [99]] >
7353 :echo matchfuzzypos(['clay', 'lacy'], 'la')
7354< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
7355 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
7356< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
7357
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007358 Return type: list<list<any>>
7359
7360
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007361matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
7362 Same as |match()|, but return a |List|. The first item in the
7363 list is the matched string, same as what matchstr() would
7364 return. Following items are submatches, like "\1", "\2", etc.
7365 in |:substitute|. When an optional submatch didn't match an
7366 empty string is used. Example: >
7367 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
7368< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
7369 When there is no match an empty list is returned.
7370
7371 You can pass in a List, but that is not very useful.
7372
7373 Can also be used as a |method|: >
7374 GetText()->matchlist('word')
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007375<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007376 Return type: list<string> or list<any>
7377
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007378 *matchstrlist()*
7379matchstrlist({list}, {pat} [, {dict}])
7380 Returns the |List| of matches in {list} where {pat} matches.
7381 {list} is a |List| of strings. {pat} is matched against each
7382 string in {list}.
7383
7384 The {dict} argument supports following items:
7385 submatches include submatch information (|/\(|)
7386
7387 For each match, a |Dict| with the following items is returned:
7388 byteidx starting byte index of the match.
7389 idx index in {list} of the match.
7390 text matched string
7391 submatches a List of submatches. Present only if
7392 "submatches" is set to v:true in {dict}.
7393
Yegappan Lakshmanana35235e2024-02-24 10:09:43 +01007394 See |match-pattern| for information about the effect of some
7395 option settings on the pattern.
7396
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007397 Example: >
Yegappan Lakshmananeb3475d2024-01-15 11:08:25 -08007398 :echo matchstrlist(['tik tok'], '\<\k\+\>')
7399 [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
7400 :echo matchstrlist(['a', 'b'], '\<\k\+\>')
7401 [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
Yegappan Lakshmananf93b1c82024-01-04 22:28:46 +01007402<
7403 If "submatches" is present and is v:true, then submatches like
7404 "\1", "\2", etc. are also returned. Example: >
7405 :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
7406 \ #{submatches: v:true})
7407 [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
7408< The "submatches" List always contains 9 items. If a submatch
7409 is not found, then an empty string is returned for that
7410 submatch.
7411
7412 Can also be used as a |method|: >
7413 GetListOfStrings()->matchstrlist('mypat')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007414<
7415 Return type: list<dict<any>> or list<any>
7416
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007417
7418matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
7419 Same as |match()|, but return the matched string. Example: >
7420 :echo matchstr("testing", "ing")
7421< results in "ing".
7422 When there is no match "" is returned.
7423 The {start}, if given, has the same meaning as for |match()|. >
7424 :echo matchstr("testing", "ing", 2)
7425< results in "ing". >
7426 :echo matchstr("testing", "ing", 5)
7427< result is "".
7428 When {expr} is a |List| then the matching item is returned.
7429 The type isn't changed, it's not necessarily a String.
7430
7431 Can also be used as a |method|: >
7432 GetText()->matchstr('word')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007433<
7434 Return type: |String|
7435
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007436
7437matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
7438 Same as |matchstr()|, but return the matched string, the start
7439 position and the end position of the match. Example: >
7440 :echo matchstrpos("testing", "ing")
7441< results in ["ing", 4, 7].
7442 When there is no match ["", -1, -1] is returned.
7443 The {start}, if given, has the same meaning as for |match()|. >
7444 :echo matchstrpos("testing", "ing", 2)
7445< results in ["ing", 4, 7]. >
7446 :echo matchstrpos("testing", "ing", 5)
7447< result is ["", -1, -1].
7448 When {expr} is a |List| then the matching item, the index
7449 of first item where {pat} matches, the start position and the
7450 end position of the match are returned. >
7451 :echo matchstrpos([1, '__x'], '\a')
7452< result is ["x", 1, 2, 3].
7453 The type isn't changed, it's not necessarily a String.
7454
7455 Can also be used as a |method|: >
7456 GetText()->matchstrpos('word')
7457<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007458 Return type: list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007459
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007460
7461max({expr}) *max()*
7462 Return the maximum value of all items in {expr}. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007463 echo max([apples, pears, oranges])
7464
7465< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
7466 it returns the maximum of all values in the Dictionary.
7467 If {expr} is neither a List nor a Dictionary, or one of the
7468 items in {expr} cannot be used as a Number this results in
7469 an error. An empty |List| or |Dictionary| results in zero.
7470
7471 Can also be used as a |method|: >
7472 mylist->max()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007473<
7474 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007475
7476
7477menu_info({name} [, {mode}]) *menu_info()*
7478 Return information about the specified menu {name} in
7479 mode {mode}. The menu name should be specified without the
7480 shortcut character ('&'). If {name} is "", then the top-level
7481 menu names are returned.
7482
7483 {mode} can be one of these strings:
7484 "n" Normal
7485 "v" Visual (including Select)
7486 "o" Operator-pending
7487 "i" Insert
7488 "c" Cmd-line
7489 "s" Select
7490 "x" Visual
7491 "t" Terminal-Job
7492 "" Normal, Visual and Operator-pending
7493 "!" Insert and Cmd-line
7494 When {mode} is omitted, the modes for "" are used.
7495
7496 Returns a |Dictionary| containing the following items:
7497 accel menu item accelerator text |menu-text|
7498 display display name (name without '&')
7499 enabled v:true if this menu item is enabled
7500 Refer to |:menu-enable|
7501 icon name of the icon file (for toolbar)
7502 |toolbar-icon|
7503 iconidx index of a built-in icon
7504 modes modes for which the menu is defined. In
7505 addition to the modes mentioned above, these
7506 characters will be used:
7507 " " Normal, Visual and Operator-pending
7508 name menu item name.
7509 noremenu v:true if the {rhs} of the menu item is not
7510 remappable else v:false.
7511 priority menu order priority |menu-priority|
7512 rhs right-hand-side of the menu item. The returned
7513 string has special characters translated like
7514 in the output of the ":menu" command listing.
7515 When the {rhs} of a menu item is empty, then
7516 "<Nop>" is returned.
7517 script v:true if script-local remapping of {rhs} is
7518 allowed else v:false. See |:menu-script|.
7519 shortcut shortcut key (character after '&' in
7520 the menu name) |menu-shortcut|
7521 silent v:true if the menu item is created
7522 with <silent> argument |:menu-silent|
7523 submenus |List| containing the names of
7524 all the submenus. Present only if the menu
7525 item has submenus.
7526
7527 Returns an empty dictionary if the menu item is not found.
7528
7529 Examples: >
7530 :echo menu_info('Edit.Cut')
7531 :echo menu_info('File.Save', 'n')
7532
7533 " Display the entire menu hierarchy in a buffer
7534 func ShowMenu(name, pfx)
7535 let m = menu_info(a:name)
7536 call append(line('$'), a:pfx .. m.display)
7537 for child in m->get('submenus', [])
7538 call ShowMenu(a:name .. '.' .. escape(child, '.'),
7539 \ a:pfx .. ' ')
7540 endfor
7541 endfunc
7542 new
7543 for topmenu in menu_info('').submenus
7544 call ShowMenu(topmenu, '')
7545 endfor
7546<
7547 Can also be used as a |method|: >
7548 GetMenuName()->menu_info('v')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007549<
7550 Return type: dict<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007551
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007552min({expr}) *min()*
7553 Return the minimum value of all items in {expr}. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007554 echo min([apples, pears, oranges])
7555
7556< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
7557 it returns the minimum of all values in the Dictionary.
7558 If {expr} is neither a List nor a Dictionary, or one of the
7559 items in {expr} cannot be used as a Number this results in
7560 an error. An empty |List| or |Dictionary| results in zero.
7561
7562 Can also be used as a |method|: >
7563 mylist->min()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007564<
7565 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007566
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007567
7568mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E739*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007569 Create directory {name}.
7570
Bram Moolenaar938ae282023-02-20 20:44:55 +00007571 When {flags} is present it must be a string. An empty string
7572 has no effect.
Bram Moolenaar6f14da12022-09-07 21:30:44 +01007573
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007574 {flags} can contain these character flags:
7575 "p" intermediate directories will be created as necessary
7576 "D" {name} will be deleted at the end of the current
Christian Brabandtc509c002024-06-14 20:22:05 +02007577 function, but not recursively |:defer|
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007578 "R" {name} will be deleted recursively at the end of the
Christian Brabandtc509c002024-06-14 20:22:05 +02007579 current function |:defer|
Bram Moolenaar938ae282023-02-20 20:44:55 +00007580
Christian Brabandtd6d4e132024-06-13 21:21:41 +02007581 Note that when {name} has more than one part and "p" is used
Bram Moolenaar6f14da12022-09-07 21:30:44 +01007582 some directories may already exist. Only the first one that
7583 is created and what it contains is scheduled to be deleted.
7584 E.g. when using: >
7585 call mkdir('subdir/tmp/autoload', 'pR')
7586< and "subdir" already exists then "subdir/tmp" will be
7587 scheduled for deletion, like with: >
7588 defer delete('subdir/tmp', 'rf')
7589< Note that if scheduling the defer fails the directory is not
7590 deleted. This should only happen when out of memory.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007591
7592 If {prot} is given it is used to set the protection bits of
7593 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
7594 the user, readable for others). Use 0o700 to make it
Christian Brabandt0a336cc2025-03-11 21:14:31 +01007595 unreadable for others. This is used for the newly created
zeertzjqc1c3b5d2025-03-12 21:16:13 +01007596 directories. Note: umask is applied to {prot} (on Unix).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007597 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007598 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007599
7600< This function is not available in the |sandbox|.
7601
7602 There is no error if the directory already exists and the "p"
7603 flag is passed (since patch 8.0.1708). However, without the
7604 "p" option the call will fail.
7605
7606 The function result is a Number, which is TRUE if the call was
7607 successful or FALSE if the directory creation failed or partly
7608 failed.
7609
7610 Not available on all systems. To check use: >
7611 :if exists("*mkdir")
7612
7613< Can also be used as a |method|: >
7614 GetName()->mkdir()
7615<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007616 Return type: |Number|
7617
7618
7619mode([{expr}]) *mode()*
7620 Return a string that indicates the current mode.
Doug Kearns9cd9e752024-04-07 17:42:17 +02007621 If {expr} is supplied and it evaluates to a non-zero Number or
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007622 a non-empty String (|non-zero-arg|), then the full mode is
7623 returned, otherwise only the first letter is returned.
7624 Also see |state()|.
7625
7626 n Normal
7627 no Operator-pending
7628 nov Operator-pending (forced characterwise |o_v|)
7629 noV Operator-pending (forced linewise |o_V|)
7630 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
7631 CTRL-V is one character
7632 niI Normal using |i_CTRL-O| in |Insert-mode|
7633 niR Normal using |i_CTRL-O| in |Replace-mode|
7634 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
7635 nt Terminal-Normal (insert goes to Terminal-Job mode)
7636 v Visual by character
7637 vs Visual by character using |v_CTRL-O| in Select mode
7638 V Visual by line
7639 Vs Visual by line using |v_CTRL-O| in Select mode
7640 CTRL-V Visual blockwise
7641 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
7642 s Select by character
7643 S Select by line
7644 CTRL-S Select blockwise
7645 i Insert
7646 ic Insert mode completion |compl-generic|
7647 ix Insert mode |i_CTRL-X| completion
7648 R Replace |R|
7649 Rc Replace mode completion |compl-generic|
7650 Rx Replace mode |i_CTRL-X| completion
7651 Rv Virtual Replace |gR|
7652 Rvc Virtual Replace mode completion |compl-generic|
7653 Rvx Virtual Replace mode |i_CTRL-X| completion
7654 c Command-line editing
h-east71ebf3b2023-09-03 17:12:55 +02007655 ct Command-line editing via Terminal-Job mode
zeertzjqfcaeb3d2023-11-28 20:46:29 +01007656 cr Command-line editing overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007657 cv Vim Ex mode |gQ|
zeertzjqfcaeb3d2023-11-28 20:46:29 +01007658 cvr Vim Ex mode while in overstrike mode |c_<Insert>|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007659 ce Normal Ex mode |Q|
7660 r Hit-enter prompt
7661 rm The -- more -- prompt
7662 r? A |:confirm| query of some sort
7663 ! Shell or external command is executing
7664 t Terminal-Job mode: keys go to the job
7665
7666 This is useful in the 'statusline' option or when used
7667 with |remote_expr()| In most other places it always returns
7668 "c" or "n".
7669 Note that in the future more modes and more specific modes may
7670 be added. It's better not to compare the whole string but only
7671 the leading character(s).
7672 Also see |visualmode()|.
7673
7674 Can also be used as a |method|: >
7675 DoFull()->mode()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007676<
7677 Return type: |String|
7678
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007679
7680mzeval({expr}) *mzeval()*
7681 Evaluate MzScheme expression {expr} and return its result
7682 converted to Vim data structures.
7683 Numbers and strings are returned as they are.
7684 Pairs (including lists and improper lists) and vectors are
7685 returned as Vim |Lists|.
7686 Hash tables are represented as Vim |Dictionary| type with keys
7687 converted to strings.
7688 All other types are converted to string with display function.
7689 Examples: >
7690 :mz (define l (list 1 2 3))
7691 :mz (define h (make-hash)) (hash-set! h "list" l)
7692 :echo mzeval("l")
7693 :echo mzeval("h")
7694<
7695 Note that in a `:def` function local variables are not visible
7696 to {expr}.
7697
7698 Can also be used as a |method|: >
7699 GetExpr()->mzeval()
7700<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007701 Return type: any, depending on {expr}
7702
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007703 {only available when compiled with the |+mzscheme| feature}
7704
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007705
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007706nextnonblank({lnum}) *nextnonblank()*
7707 Return the line number of the first line at or below {lnum}
7708 that is not blank. Example: >
7709 if getline(nextnonblank(1)) =~ "Java"
7710< When {lnum} is invalid or there is no non-blank line at or
7711 below it, zero is returned.
7712 {lnum} is used like with |getline()|.
7713 See also |prevnonblank()|.
7714
7715 Can also be used as a |method|: >
7716 GetLnum()->nextnonblank()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007717<
7718 Return type: |Number|
7719
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007720
Christ van Willegenc0786752025-02-01 15:42:16 +01007721ngettext({single}, {plural}, {number}[, {domain}) *ngettext()*
7722 Return a string that contains the correct value for a
7723 message based on the rules for plural form(s) in
7724 a language. Examples: >
7725 ngettext("File", "Files", 2) # returns "Files"
7726<
7727 Can be used as a |method|: >
7728 1->ngettext("File", "Files") # returns "File"
7729<
7730 See |gettext()| for information on the domain parameter.
7731
7732 Return type: |String|
7733
7734
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007735nr2char({expr} [, {utf8}]) *nr2char()*
7736 Return a string with a single character, which has the number
7737 value {expr}. Examples: >
7738 nr2char(64) returns "@"
7739 nr2char(32) returns " "
7740< When {utf8} is omitted or zero, the current 'encoding' is used.
7741 Example for "utf-8": >
7742 nr2char(300) returns I with bow character
7743< When {utf8} is TRUE, always return UTF-8 characters.
7744 Note that a NUL character in the file is specified with
7745 nr2char(10), because NULs are represented with newline
7746 characters. nr2char(0) is a real NUL and terminates the
7747 string, thus results in an empty string.
7748 To turn a list of character numbers into a string: >
7749 let list = [65, 66, 67]
7750 let str = join(map(list, {_, val -> nr2char(val)}), '')
7751< Result: "ABC"
7752
7753 Can also be used as a |method|: >
7754 GetNumber()->nr2char()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007755<
7756 Return type: |String|
7757
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007758
7759or({expr}, {expr}) *or()*
7760 Bitwise OR on the two arguments. The arguments are converted
7761 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01007762 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007763 Example: >
7764 :let bits = or(bits, 0x80)
7765< Can also be used as a |method|: >
7766 :let bits = bits->or(0x80)
7767
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01007768< Rationale: The reason this is a function and not using the "|"
7769 character like many languages, is that Vi has always used "|"
7770 to separate commands. In many places it would not be clear if
7771 "|" is an operator or a command separator.
7772
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007773 Return type: |Number|
7774
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007775
7776pathshorten({path} [, {len}]) *pathshorten()*
7777 Shorten directory names in the path {path} and return the
7778 result. The tail, the file name, is kept as-is. The other
7779 components in the path are reduced to {len} letters in length.
7780 If {len} is omitted or smaller than 1 then 1 is used (single
7781 letters). Leading '~' and '.' characters are kept. Examples: >
7782 :echo pathshorten('~/.vim/autoload/myfile.vim')
7783< ~/.v/a/myfile.vim ~
7784>
7785 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
7786< ~/.vi/au/myfile.vim ~
7787 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007788 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007789
7790 Can also be used as a |method|: >
7791 GetDirectories()->pathshorten()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007792<
7793 Return type: |String|
7794
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007795
7796perleval({expr}) *perleval()*
7797 Evaluate Perl expression {expr} in scalar context and return
7798 its result converted to Vim data structures. If value can't be
7799 converted, it is returned as a string Perl representation.
7800 Note: If you want an array or hash, {expr} must return a
7801 reference to it.
7802 Example: >
7803 :echo perleval('[1 .. 4]')
7804< [1, 2, 3, 4]
7805
7806 Note that in a `:def` function local variables are not visible
7807 to {expr}.
7808
7809 Can also be used as a |method|: >
7810 GetExpr()->perleval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007811<
7812 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007813
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007814 {only available when compiled with the |+perl| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007815
7816
7817popup_ functions are documented here: |popup-functions|
7818
7819
7820pow({x}, {y}) *pow()*
7821 Return the power of {x} to the exponent {y} as a |Float|.
7822 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007823 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007824 Examples: >
7825 :echo pow(3, 3)
7826< 27.0 >
7827 :echo pow(2, 16)
7828< 65536.0 >
7829 :echo pow(32, 0.20)
7830< 2.0
7831
7832 Can also be used as a |method|: >
7833 Compute()->pow(3)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007834<
7835 Return type: |Number|
7836
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007837
7838prevnonblank({lnum}) *prevnonblank()*
7839 Return the line number of the first line at or above {lnum}
7840 that is not blank. Example: >
7841 let ind = indent(prevnonblank(v:lnum - 1))
7842< When {lnum} is invalid or there is no non-blank line at or
7843 above it, zero is returned.
7844 {lnum} is used like with |getline()|.
7845 Also see |nextnonblank()|.
7846
7847 Can also be used as a |method|: >
7848 GetLnum()->prevnonblank()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02007849<
7850 Return type: |Number|
7851
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007852
7853printf({fmt}, {expr1} ...) *printf()*
7854 Return a String with {fmt}, where "%" items are replaced by
7855 the formatted form of their respective arguments. Example: >
7856 printf("%4d: E%d %.30s", lnum, errno, msg)
7857< May result in:
7858 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
7859
7860 When used as a |method| the base is passed as the second
7861 argument: >
7862 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007863<
7864 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007865
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007866 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007867 %s string
7868 %6S string right-aligned in 6 display cells
7869 %6s string right-aligned in 6 bytes
7870 %.9s string truncated to 9 bytes
7871 %c single byte
7872 %d decimal number
7873 %5d decimal number padded with spaces to 5 characters
7874 %x hex number
7875 %04x hex number padded with zeros to at least 4 characters
7876 %X hex number using upper case letters
7877 %o octal number
7878 %08b binary number padded with zeros to at least 8 chars
7879 %f floating point number as 12.23, inf, -inf or nan
7880 %F floating point number as 12.23, INF, -INF or NAN
7881 %e floating point number as 1.23e3, inf, -inf or nan
7882 %E floating point number as 1.23E3, INF, -INF or NAN
7883 %g floating point number, as %f or %e depending on value
7884 %G floating point number, as %F or %E depending on value
7885 %% the % character itself
7886
7887 Conversion specifications start with '%' and end with the
7888 conversion type. All other characters are copied unchanged to
7889 the result.
7890
7891 The "%" starts a conversion specification. The following
7892 arguments appear in sequence:
7893
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007894 % [pos-argument] [flags] [field-width] [.precision] type
7895
7896 pos-argument
7897 At most one positional argument specifier. These
7898 take the form {n$}, where n is >= 1.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007899
7900 flags
7901 Zero or more of the following flags:
7902
7903 # The value should be converted to an "alternate
7904 form". For c, d, and s conversions, this option
7905 has no effect. For o conversions, the precision
7906 of the number is increased to force the first
7907 character of the output string to a zero (except
7908 if a zero value is printed with an explicit
7909 precision of zero).
7910 For b and B conversions, a non-zero result has
7911 the string "0b" (or "0B" for B conversions)
7912 prepended to it.
7913 For x and X conversions, a non-zero result has
7914 the string "0x" (or "0X" for X conversions)
7915 prepended to it.
7916
7917 0 (zero) Zero padding. For all conversions the converted
7918 value is padded on the left with zeros rather
7919 than blanks. If a precision is given with a
7920 numeric conversion (d, b, B, o, x, and X), the 0
7921 flag is ignored.
7922
7923 - A negative field width flag; the converted value
7924 is to be left adjusted on the field boundary.
7925 The converted value is padded on the right with
7926 blanks, rather than on the left with blanks or
7927 zeros. A - overrides a 0 if both are given.
7928
7929 ' ' (space) A blank should be left before a positive
7930 number produced by a signed conversion (d).
7931
7932 + A sign must always be placed before a number
7933 produced by a signed conversion. A + overrides
7934 a space if both are used.
7935
7936 field-width
7937 An optional decimal digit string specifying a minimum
7938 field width. If the converted value has fewer bytes
7939 than the field width, it will be padded with spaces on
7940 the left (or right, if the left-adjustment flag has
7941 been given) to fill out the field width. For the S
7942 conversion the count is in cells.
7943
7944 .precision
7945 An optional precision, in the form of a period '.'
7946 followed by an optional digit string. If the digit
7947 string is omitted, the precision is taken as zero.
7948 This gives the minimum number of digits to appear for
7949 d, o, x, and X conversions, the maximum number of
7950 bytes to be printed from a string for s conversions,
7951 or the maximum number of cells to be printed from a
7952 string for S conversions.
7953 For floating point it is the number of digits after
7954 the decimal point.
7955
7956 type
7957 A character that specifies the type of conversion to
7958 be applied, see below.
7959
7960 A field width or precision, or both, may be indicated by an
7961 asterisk '*' instead of a digit string. In this case, a
7962 Number argument supplies the field width or precision. A
7963 negative field width is treated as a left adjustment flag
7964 followed by a positive field width; a negative precision is
7965 treated as though it were missing. Example: >
7966 :echo printf("%d: %.*s", nr, width, line)
7967< This limits the length of the text used from "line" to
7968 "width" bytes.
7969
Dominique Pellé17dca3c2023-12-14 20:36:32 +01007970 If the argument to be formatted is specified using a
7971 positional argument specifier, and a '*' is used to indicate
7972 that a number argument is to be used to specify the width or
Christ van Willegen0c6181f2023-08-13 18:03:14 +02007973 precision, the argument(s) to be used must also be specified
7974 using a {n$} positional argument specifier. See |printf-$|.
7975
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007976 The conversion specifiers and their meanings are:
7977
7978 *printf-d* *printf-b* *printf-B* *printf-o*
7979 *printf-x* *printf-X*
7980 dbBoxX The Number argument is converted to signed decimal
7981 (d), unsigned binary (b and B), unsigned octal (o), or
7982 unsigned hexadecimal (x and X) notation. The letters
7983 "abcdef" are used for x conversions; the letters
7984 "ABCDEF" are used for X conversions.
7985 The precision, if any, gives the minimum number of
7986 digits that must appear; if the converted value
7987 requires fewer digits, it is padded on the left with
7988 zeros.
7989 In no case does a non-existent or small field width
7990 cause truncation of a numeric field; if the result of
7991 a conversion is wider than the field width, the field
7992 is expanded to contain the conversion result.
7993 The 'h' modifier indicates the argument is 16 bits.
Christ van Willegenaa90d4f2023-09-03 17:22:37 +02007994 The 'l' modifier indicates the argument is a long
7995 integer. The size will be 32 bits or 64 bits
7996 depending on your platform.
7997 The "ll" modifier indicates the argument is 64 bits.
7998 The b and B conversion specifiers never take a width
7999 modifier and always assume their argument is a 64 bit
8000 integer.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008001 Generally, these modifiers are not useful. They are
8002 ignored when type is known from the argument.
8003
8004 i alias for d
8005 D alias for ld
8006 U alias for lu
8007 O alias for lo
8008
8009 *printf-c*
8010 c The Number argument is converted to a byte, and the
8011 resulting character is written.
8012
8013 *printf-s*
8014 s The text of the String argument is used. If a
8015 precision is specified, no more bytes than the number
8016 specified are used.
8017 If the argument is not a String type, it is
8018 automatically converted to text with the same format
8019 as ":echo".
8020 *printf-S*
8021 S The text of the String argument is used. If a
8022 precision is specified, no more display cells than the
8023 number specified are used.
8024
8025 *printf-f* *E807*
8026 f F The Float argument is converted into a string of the
8027 form 123.456. The precision specifies the number of
8028 digits after the decimal point. When the precision is
8029 zero the decimal point is omitted. When the precision
8030 is not specified 6 is used. A really big number
8031 (out of range or dividing by zero) results in "inf"
8032 or "-inf" with %f (INF or -INF with %F).
8033 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
8034 Example: >
8035 echo printf("%.2f", 12.115)
8036< 12.12
8037 Note that roundoff depends on the system libraries.
8038 Use |round()| when in doubt.
8039
8040 *printf-e* *printf-E*
8041 e E The Float argument is converted into a string of the
8042 form 1.234e+03 or 1.234E+03 when using 'E'. The
8043 precision specifies the number of digits after the
8044 decimal point, like with 'f'.
8045
8046 *printf-g* *printf-G*
8047 g G The Float argument is converted like with 'f' if the
8048 value is between 0.001 (inclusive) and 10000000.0
8049 (exclusive). Otherwise 'e' is used for 'g' and 'E'
8050 for 'G'. When no precision is specified superfluous
8051 zeroes and '+' signs are removed, except for the zero
8052 immediately after the decimal point. Thus 10000000.0
8053 results in 1.0e7.
8054
8055 *printf-%*
8056 % A '%' is written. No argument is converted. The
8057 complete conversion specification is "%%".
8058
8059 When a Number argument is expected a String argument is also
8060 accepted and automatically converted.
8061 When a Float or String argument is expected a Number argument
8062 is also accepted and automatically converted.
8063 Any other argument type results in an error message.
8064
8065 *E766* *E767*
8066 The number of {exprN} arguments must exactly match the number
8067 of "%" items. If there are not sufficient or too many
8068 arguments an error is given. Up to 18 arguments can be used.
8069
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008070 *printf-$*
8071 In certain languages, error and informative messages are
8072 more readable when the order of words is different from the
Christian Brabandtee17b6f2023-09-09 11:23:50 +02008073 corresponding message in English. To accommodate translations
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008074 having a different word order, positional arguments may be
8075 used to indicate this. For instance: >
8076
h_east596a9f22023-11-21 21:24:23 +09008077 #, c-format
8078 msgid "%s returning %s"
8079 msgstr "waarde %2$s komt terug van %1$s"
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008080<
h_east596a9f22023-11-21 21:24:23 +09008081 In this example, the sentence has its 2 string arguments
8082 reversed in the output. >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008083
h_east596a9f22023-11-21 21:24:23 +09008084 echo printf(
8085 "In The Netherlands, vim's creator's name is: %1$s %2$s",
8086 "Bram", "Moolenaar")
8087< In The Netherlands, vim's creator's name is: Bram Moolenaar >
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008088
h_east596a9f22023-11-21 21:24:23 +09008089 echo printf(
8090 "In Belgium, vim's creator's name is: %2$s %1$s",
8091 "Bram", "Moolenaar")
8092< In Belgium, vim's creator's name is: Moolenaar Bram
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008093
8094 Width (and precision) can be specified using the '*' specifier.
8095 In this case, you must specify the field width position in the
8096 argument list. >
8097
h_east596a9f22023-11-21 21:24:23 +09008098 echo printf("%1$*2$.*3$d", 1, 2, 3)
8099< 001 >
8100 echo printf("%2$*3$.*1$d", 1, 2, 3)
8101< 2 >
8102 echo printf("%3$*1$.*2$d", 1, 2, 3)
8103< 03 >
8104 echo printf("%1$*2$.*3$g", 1.4142, 2, 3)
8105< 1.414
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008106
8107 You can mix specifying the width and/or precision directly
8108 and via positional arguments: >
8109
h_east596a9f22023-11-21 21:24:23 +09008110 echo printf("%1$4.*2$f", 1.4142135, 6)
8111< 1.414214 >
8112 echo printf("%1$*2$.4f", 1.4142135, 6)
8113< 1.4142 >
8114 echo printf("%1$*2$.*3$f", 1.4142135, 6, 2)
8115< 1.41
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008116
Christ van Willegenc35fc032024-03-14 18:30:41 +01008117 You will get an overflow error |E1510|, when the field-width
8118 or precision will result in a string longer than 6400 chars.
8119
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008120 *E1500*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008121 You cannot mix positional and non-positional arguments: >
h_east596a9f22023-11-21 21:24:23 +09008122 echo printf("%s%1$s", "One", "Two")
8123< E1500: Cannot mix positional and non-positional arguments:
8124 %s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008125
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008126 *E1501*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008127 You cannot skip a positional argument in a format string: >
h_east596a9f22023-11-21 21:24:23 +09008128 echo printf("%3$s%1$s", "One", "Two", "Three")
8129< E1501: format argument 2 unused in $-style format:
8130 %3$s%1$s
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008131
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008132 *E1502*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008133 You can re-use a [field-width] (or [precision]) argument: >
h_east596a9f22023-11-21 21:24:23 +09008134 echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2)
8135< 1 at width 2 is: 01
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008136
8137 However, you can't use it as a different type: >
h_east596a9f22023-11-21 21:24:23 +09008138 echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2)
8139< E1502: Positional argument 2 used as field width reused as
8140 different type: long int/int
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008141
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008142 *E1503*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008143 When a positional argument is used, but not the correct number
8144 or arguments is given, an error is raised: >
h_east596a9f22023-11-21 21:24:23 +09008145 echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2)
8146< E1503: Positional argument 3 out of bounds: %1$d at width
8147 %2$d is: %01$*2$.*3$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008148
8149 Only the first error is reported: >
h_east596a9f22023-11-21 21:24:23 +09008150 echo printf("%01$*2$.*3$d %4$d", 1, 2)
8151< E1503: Positional argument 3 out of bounds: %01$*2$.*3$d
8152 %4$d
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008153
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008154 *E1504*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008155 A positional argument can be used more than once: >
h_east596a9f22023-11-21 21:24:23 +09008156 echo printf("%1$s %2$s %1$s", "One", "Two")
8157< One Two One
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008158
8159 However, you can't use a different type the second time: >
h_east596a9f22023-11-21 21:24:23 +09008160 echo printf("%1$s %2$s %1$d", "One", "Two")
8161< E1504: Positional argument 1 type used inconsistently:
8162 int/string
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008163
Yegappan Lakshmanan413f8392023-09-28 22:46:37 +02008164 *E1505*
Christ van Willegen0c6181f2023-08-13 18:03:14 +02008165 Various other errors that lead to a format string being
8166 wrongly formatted lead to: >
h_east596a9f22023-11-21 21:24:23 +09008167 echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2)
8168< E1505: Invalid format specifier: %1$d at width %2$d is:
8169 %01$*2$.3$d
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008170
Christ van Willegenea746f92023-10-05 20:48:36 +02008171 *E1507*
zeertzjq27e12c72023-10-07 01:34:04 +08008172 This internal error indicates that the logic to parse a
8173 positional format argument ran into a problem that couldn't be
8174 otherwise reported. Please file a bug against Vim if you run
8175 into this, copying the exact format string and parameters that
8176 were used.
Christ van Willegenea746f92023-10-05 20:48:36 +02008177
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008178 Return type: |String|
8179
Christ van Willegenea746f92023-10-05 20:48:36 +02008180
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008181prompt_getprompt({buf}) *prompt_getprompt()*
8182 Returns the effective prompt text for buffer {buf}. {buf} can
8183 be a buffer name or number. See |prompt-buffer|.
8184
8185 If the buffer doesn't exist or isn't a prompt buffer, an empty
8186 string is returned.
8187
8188 Can also be used as a |method|: >
8189 GetBuffer()->prompt_getprompt()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008190<
8191 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008192
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008193 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008194
8195
8196prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
8197 Set prompt callback for buffer {buf} to {expr}. When {expr}
8198 is an empty string the callback is removed. This has only
8199 effect if {buf} has 'buftype' set to "prompt".
8200
8201 The callback is invoked when pressing Enter. The current
8202 buffer will always be the prompt buffer. A new line for a
8203 prompt is added before invoking the callback, thus the prompt
8204 for which the callback was invoked will be in the last but one
8205 line.
8206 If the callback wants to add text to the buffer, it must
8207 insert it above the last line, since that is where the current
8208 prompt is. This can also be done asynchronously.
8209 The callback is invoked with one argument, which is the text
8210 that was entered at the prompt. This can be an empty string
8211 if the user only typed Enter.
8212 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008213 func s:TextEntered(text)
8214 if a:text == 'exit' || a:text == 'quit'
8215 stopinsert
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008216 " Reset 'modified' to allow the buffer to be closed.
8217 " We assume there is nothing useful to be saved.
8218 set nomodified
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008219 close
8220 else
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008221 " Do something useful with "a:text". In this example
8222 " we just repeat it.
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008223 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008224 endif
8225 endfunc
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01008226 call prompt_setcallback(bufnr(), function('s:TextEntered'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008227
8228< Can also be used as a |method|: >
8229 GetBuffer()->prompt_setcallback(callback)
8230
8231< {only available when compiled with the |+channel| feature}
8232
8233prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
8234 Set a callback for buffer {buf} to {expr}. When {expr} is an
8235 empty string the callback is removed. This has only effect if
8236 {buf} has 'buftype' set to "prompt".
8237
8238 This callback will be invoked when pressing CTRL-C in Insert
8239 mode. Without setting a callback Vim will exit Insert mode,
8240 as in any buffer.
8241
8242 Can also be used as a |method|: >
8243 GetBuffer()->prompt_setinterrupt(callback)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008244<
8245 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008246
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008247 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008248
8249prompt_setprompt({buf}, {text}) *prompt_setprompt()*
8250 Set prompt for buffer {buf} to {text}. You most likely want
8251 {text} to end in a space.
8252 The result is only visible if {buf} has 'buftype' set to
8253 "prompt". Example: >
8254 call prompt_setprompt(bufnr(), 'command: ')
8255<
8256 Can also be used as a |method|: >
8257 GetBuffer()->prompt_setprompt('command: ')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008258<
8259 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008260
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008261 {only available when compiled with the |+channel| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008262
8263prop_ functions are documented here: |text-prop-functions|
8264
8265pum_getpos() *pum_getpos()*
8266 If the popup menu (see |ins-completion-menu|) is not visible,
8267 returns an empty |Dictionary|, otherwise, returns a
8268 |Dictionary| with the following keys:
8269 height nr of items visible
8270 width screen cells
8271 row top screen row (0 first row)
8272 col leftmost screen column (0 first col)
8273 size total nr of items
8274 scrollbar |TRUE| if scrollbar is visible
8275
8276 The values are the same as in |v:event| during
8277 |CompleteChanged|.
8278
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008279 Return type: dict<any>
8280
8281
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008282pumvisible() *pumvisible()*
8283 Returns non-zero when the popup menu is visible, zero
8284 otherwise. See |ins-completion-menu|.
8285 This can be used to avoid some things that would remove the
8286 popup menu.
8287
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008288 Return type: |Number|
8289
8290
zeertzjq7c515282024-11-10 20:26:12 +01008291py3eval({expr} [, {locals}]) *py3eval()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008292 Evaluate Python expression {expr} and return its result
8293 converted to Vim data structures.
Ben Jacksonea19e782024-11-06 21:50:05 +01008294 If a {locals} |Dictionary| is given, it defines set of local
8295 variables available in the expression. The keys are variable
8296 names and the values are the variable values. |Dictionary| and
8297 |List| values are referenced, and may be updated by the
8298 expression (as if |python-bindeval| was used).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008299 Numbers and strings are returned as they are (strings are
8300 copied though, Unicode strings are additionally converted to
8301 'encoding').
8302 Lists are represented as Vim |List| type.
8303 Dictionaries are represented as Vim |Dictionary| type with
8304 keys converted to strings.
8305 Note that in a `:def` function local variables are not visible
8306 to {expr}.
8307
8308 Can also be used as a |method|: >
8309 GetExpr()->py3eval()
Ben Jacksonea19e782024-11-06 21:50:05 +01008310 'b",".join(l)'->py3eval({'l': ['a', 'b', 'c']})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008311<
8312 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008313
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008314 {only available when compiled with the |+python3| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008315
8316 *E858* *E859*
zeertzjq7c515282024-11-10 20:26:12 +01008317pyeval({expr} [, {locals}]) *pyeval()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008318 Evaluate Python expression {expr} and return its result
8319 converted to Vim data structures.
Ben Jacksonea19e782024-11-06 21:50:05 +01008320 For {locals} see |py3eval()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008321 Numbers and strings are returned as they are (strings are
8322 copied though).
8323 Lists are represented as Vim |List| type.
8324 Dictionaries are represented as Vim |Dictionary| type,
8325 non-string keys result in error.
8326 Note that in a `:def` function local variables are not visible
8327 to {expr}.
8328
8329 Can also be used as a |method|: >
8330 GetExpr()->pyeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008331<
8332 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008333
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008334 {only available when compiled with the |+python| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008335
zeertzjq7c515282024-11-10 20:26:12 +01008336pyxeval({expr} [, {locals}]) *pyxeval()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008337 Evaluate Python expression {expr} and return its result
8338 converted to Vim data structures.
Ben Jacksonea19e782024-11-06 21:50:05 +01008339 For {locals} see |py3eval()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008340 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
8341 See also: |pyeval()|, |py3eval()|
8342
8343 Can also be used as a |method|: >
h-east52e7cc22024-07-28 17:03:29 +02008344 GetExpr()->pyxeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008345<
8346 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008347
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008348 {only available when compiled with the |+python| or the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008349 |+python3| feature}
8350
8351rand([{expr}]) *rand()* *random*
8352 Return a pseudo-random Number generated with an xoshiro128**
8353 algorithm using seed {expr}. The returned number is 32 bits,
8354 also on 64 bits systems, for consistency.
8355 {expr} can be initialized by |srand()| and will be updated by
8356 rand(). If {expr} is omitted, an internal seed value is used
8357 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008358 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008359
8360 Examples: >
8361 :echo rand()
8362 :let seed = srand()
8363 :echo rand(seed)
8364 :echo rand(seed) % 16 " random number 0 - 15
8365<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008366 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008367
8368 *E726* *E727*
8369range({expr} [, {max} [, {stride}]]) *range()*
8370 Returns a |List| with Numbers:
8371 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
8372 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
8373 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
8374 {max}] (increasing {expr} with {stride} each time, not
8375 producing a value past {max}).
8376 When the maximum is one before the start the result is an
8377 empty list. When the maximum is more than one before the
8378 start this is an error.
8379 Examples: >
8380 range(4) " [0, 1, 2, 3]
8381 range(2, 4) " [2, 3, 4]
8382 range(2, 9, 3) " [2, 5, 8]
8383 range(2, -2, -1) " [2, 1, 0, -1, -2]
8384 range(0) " []
8385 range(2, 0) " error!
8386<
8387 Can also be used as a |method|: >
8388 GetExpr()->range()
8389<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008390 Return type: list<number>
8391
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008392
K.Takata11df3ae2022-10-19 14:02:40 +01008393readblob({fname} [, {offset} [, {size}]]) *readblob()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008394 Read file {fname} in binary mode and return a |Blob|.
K.Takata11df3ae2022-10-19 14:02:40 +01008395 If {offset} is specified, read the file from the specified
8396 offset. If it is a negative value, it is used as an offset
8397 from the end of the file. E.g., to read the last 12 bytes: >
8398 readblob('file.bin', -12)
8399< If {size} is specified, only the specified size will be read.
8400 E.g. to read the first 100 bytes of a file: >
8401 readblob('file.bin', 0, 100)
8402< If {size} is -1 or omitted, the whole data starting from
8403 {offset} will be read.
K.Takata43625762022-10-20 13:28:51 +01008404 This can be also used to read the data from a character device
8405 on Unix when {size} is explicitly set. Only if the device
8406 supports seeking {offset} can be used. Otherwise it should be
8407 zero. E.g. to read 10 bytes from a serial console: >
8408 readblob('/dev/ttyS0', 0, 10)
8409< When the file can't be opened an error message is given and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008410 the result is an empty |Blob|.
Bram Moolenaar5b2a3d72022-10-21 11:25:30 +01008411 When the offset is beyond the end of the file the result is an
8412 empty blob.
8413 When trying to read more bytes than are available the result
8414 is truncated.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008415 Also see |readfile()| and |writefile()|.
8416
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008417 Return type: |Blob|
8418
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008419
8420readdir({directory} [, {expr} [, {dict}]]) *readdir()*
8421 Return a list with file and directory names in {directory}.
8422 You can also use |glob()| if you don't need to do complicated
8423 things, such as limiting the number of matches.
8424 The list will be sorted (case sensitive), see the {dict}
8425 argument below for changing the sort order.
8426
8427 When {expr} is omitted all entries are included.
8428 When {expr} is given, it is evaluated to check what to do:
8429 If {expr} results in -1 then no further entries will
8430 be handled.
8431 If {expr} results in 0 then this entry will not be
8432 added to the list.
8433 If {expr} results in 1 then this entry will be added
8434 to the list.
8435 The entries "." and ".." are always excluded.
8436 Each time {expr} is evaluated |v:val| is set to the entry name.
8437 When {expr} is a function the name is passed as the argument.
8438 For example, to get a list of files ending in ".txt": >
8439 readdir(dirname, {n -> n =~ '.txt$'})
8440< To skip hidden and backup files: >
8441 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00008442< *E857*
8443 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008444 values. Currently this is used to specify if and how sorting
8445 should be performed. The dict can have the following members:
8446
8447 sort How to sort the result returned from the system.
8448 Valid values are:
8449 "none" do not sort (fastest method)
8450 "case" sort case sensitive (byte value of
8451 each character, technically, using
8452 strcmp()) (default)
8453 "icase" sort case insensitive (technically
8454 using strcasecmp())
8455 "collate" sort using the collation order
8456 of the "POSIX" or "C" |locale|
8457 (technically using strcoll())
8458 Other values are silently ignored.
8459
8460 For example, to get a list of all files in the current
8461 directory without sorting the individual entries: >
8462 readdir('.', '1', #{sort: 'none'})
8463< If you want to get a directory tree: >
8464 function! s:tree(dir)
8465 return {a:dir : map(readdir(a:dir),
8466 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008467 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008468 endfunction
8469 echo s:tree(".")
8470<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008471 Returns an empty List on error.
8472
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008473 Can also be used as a |method|: >
8474 GetDirName()->readdir()
8475<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008476 Return type: list<string> or list<any>
8477
8478
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008479readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
8480 Extended version of |readdir()|.
8481 Return a list of Dictionaries with file and directory
8482 information in {directory}.
8483 This is useful if you want to get the attributes of file and
8484 directory at the same time as getting a list of a directory.
8485 This is much faster than calling |readdir()| then calling
8486 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
8487 each file and directory especially on MS-Windows.
8488 The list will by default be sorted by name (case sensitive),
8489 the sorting can be changed by using the optional {dict}
8490 argument, see |readdir()|.
8491
8492 The Dictionary for file and directory information has the
8493 following items:
8494 group Group name of the entry. (Only on Unix)
8495 name Name of the entry.
8496 perm Permissions of the entry. See |getfperm()|.
8497 size Size of the entry. See |getfsize()|.
8498 time Timestamp of the entry. See |getftime()|.
8499 type Type of the entry.
8500 On Unix, almost same as |getftype()| except:
8501 Symlink to a dir "linkd"
8502 Other symlink "link"
8503 On MS-Windows:
8504 Normal file "file"
8505 Directory "dir"
8506 Junction "junction"
8507 Symlink to a dir "linkd"
8508 Other symlink "link"
8509 Other reparse point "reparse"
8510 user User name of the entry's owner. (Only on Unix)
8511 On Unix, if the entry is a symlink, the Dictionary includes
8512 the information of the target (except the "type" item).
8513 On MS-Windows, it includes the information of the symlink
8514 itself because of performance reasons.
8515
8516 When {expr} is omitted all entries are included.
8517 When {expr} is given, it is evaluated to check what to do:
8518 If {expr} results in -1 then no further entries will
8519 be handled.
8520 If {expr} results in 0 then this entry will not be
8521 added to the list.
8522 If {expr} results in 1 then this entry will be added
8523 to the list.
8524 The entries "." and ".." are always excluded.
8525 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
8526 of the entry.
8527 When {expr} is a function the entry is passed as the argument.
8528 For example, to get a list of files ending in ".txt": >
8529 readdirex(dirname, {e -> e.name =~ '.txt$'})
8530<
8531 For example, to get a list of all files in the current
8532 directory without sorting the individual entries: >
8533 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008534<
8535 Can also be used as a |method|: >
8536 GetDirName()->readdirex()
8537<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008538 Return type: list<dict<any>> or list<any>
8539
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008540
8541 *readfile()*
8542readfile({fname} [, {type} [, {max}]])
8543 Read file {fname} and return a |List|, each line of the file
8544 as an item. Lines are broken at NL characters. Macintosh
8545 files separated with CR will result in a single long line
8546 (unless a NL appears somewhere).
8547 All NUL characters are replaced with a NL character.
8548 When {type} contains "b" binary mode is used:
8549 - When the last line ends in a NL an extra empty list item is
8550 added.
8551 - No CR characters are removed.
8552 Otherwise:
8553 - CR characters that appear before a NL are removed.
8554 - Whether the last line ends in a NL or not does not matter.
8555 - When 'encoding' is Unicode any UTF-8 byte order mark is
8556 removed from the text.
8557 When {max} is given this specifies the maximum number of lines
8558 to be read. Useful if you only want to check the first ten
8559 lines of a file: >
8560 :for line in readfile(fname, '', 10)
8561 : if line =~ 'Date' | echo line | endif
8562 :endfor
8563< When {max} is negative -{max} lines from the end of the file
8564 are returned, or as many as there are.
8565 When {max} is zero the result is an empty list.
8566 Note that without {max} the whole file is read into memory.
8567 Also note that there is no recognition of encoding. Read a
8568 file into a buffer if you need to.
8569 Deprecated (use |readblob()| instead): When {type} contains
8570 "B" a |Blob| is returned with the binary data of the file
8571 unmodified.
8572 When the file can't be opened an error message is given and
8573 the result is an empty list.
8574 Also see |writefile()|.
8575
8576 Can also be used as a |method|: >
8577 GetFileName()->readfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008578<
8579 Return type: list<string> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008580
8581reduce({object}, {func} [, {initial}]) *reduce()* *E998*
8582 {func} is called for every item in {object}, which can be a
8583 |String|, |List| or a |Blob|. {func} is called with two
8584 arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00008585 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008586
8587 {initial} is the initial result. When omitted, the first item
8588 in {object} is used and {func} is first called for the second
8589 item. If {initial} is not given and {object} is empty no
8590 result can be computed, an E998 error is given.
8591
8592 Examples: >
8593 echo reduce([1, 3, 5], { acc, val -> acc + val })
8594 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
8595 echo reduce(0z1122, { acc, val -> 2 * acc + val })
8596 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
8597<
8598 Can also be used as a |method|: >
8599 echo mylist->reduce({ acc, val -> acc + val }, 0)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008600<
8601 Return type: |String|, |Blob|, list<{type}> or dict<{type}>
8602 depending on {object} and {func}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008603
8604
8605reg_executing() *reg_executing()*
8606 Returns the single letter name of the register being executed.
8607 Returns an empty string when no register is being executed.
8608 See |@|.
8609
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008610 Return type: |String|
8611
8612
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008613reg_recording() *reg_recording()*
8614 Returns the single letter name of the register being recorded.
8615 Returns an empty string when not recording. See |q|.
8616
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008617 Return type: |String|
8618
8619
8620reltime() *reltime()*
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008621reltime({start})
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008622reltime({start}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008623 Return an item that represents a time value. The item is a
8624 list with items that depend on the system. In Vim 9 script
Bram Moolenaar71badf92023-04-22 22:40:14 +01008625 the type list<any> can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008626 The item can be passed to |reltimestr()| to convert it to a
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008627 string or |reltimefloat()| to convert to a Float. For
8628 example, to see the time spent in function Work(): >
8629 var startTime = reltime()
8630 Work()
8631 echo startTime->reltime()->reltimestr()
8632<
Bram Moolenaar016188f2022-06-06 20:52:59 +01008633 Without an argument reltime() returns the current time (the
Lifepillar963fd7d2024-01-05 17:44:57 +01008634 representation is system-dependent, it cannot be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01008635 wall-clock time, see |localtime()| for that).
Lifepillar963fd7d2024-01-05 17:44:57 +01008636 With one argument it returns the time passed since the time
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008637 specified in the argument.
8638 With two arguments it returns the time passed between {start}
8639 and {end}.
8640
8641 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008642 reltime(). If there is an error an empty List is returned in
8643 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008644
8645 Can also be used as a |method|: >
8646 GetStart()->reltime()
8647<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008648 Return type: list<number>
8649
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008650 {only available when compiled with the |+reltime| feature}
8651
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008652
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008653reltimefloat({time}) *reltimefloat()*
8654 Return a Float that represents the time value of {time}.
8655 Example: >
8656 let start = reltime()
8657 call MyFunction()
8658 let seconds = reltimefloat(reltime(start))
8659< See the note of reltimestr() about overhead.
8660 Also see |profiling|.
8661 If there is an error 0.0 is returned in legacy script, in Vim9
8662 script an error is given.
8663
8664 Can also be used as a |method|: >
8665 reltime(start)->reltimefloat()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008666<
8667 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008668
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008669 {only available when compiled with the |+reltime| feature}
8670
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008671
8672reltimestr({time}) *reltimestr()*
8673 Return a String that represents the time value of {time}.
8674 This is the number of seconds, a dot and the number of
8675 microseconds. Example: >
8676 let start = reltime()
8677 call MyFunction()
8678 echo reltimestr(reltime(start))
8679< Note that overhead for the commands will be added to the time.
Ernie Rael076de792023-03-16 21:43:15 +00008680 The accuracy depends on the system. Use reltimefloat() for the
8681 greatest accuracy which is nanoseconds on some systems.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008682 Leading spaces are used to make the string align nicely. You
8683 can use split() to remove it. >
8684 echo split(reltimestr(reltime(start)))[0]
8685< Also see |profiling|.
8686 If there is an error an empty string is returned in legacy
8687 script, in Vim9 script an error is given.
8688
8689 Can also be used as a |method|: >
8690 reltime(start)->reltimestr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008691<
8692 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008693
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008694 {only available when compiled with the |+reltime| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008695
8696 *remote_expr()* *E449*
8697remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00008698 Send the {string} to {server}. The {server} argument is a
8699 string, also see |{server}|.
8700
8701 The string is sent as an expression and the result is returned
Christian Brabandt1961caf2024-10-12 11:57:12 +02008702 after evaluation. The result must be a String or a |List|
8703 other types will be converted to String. A |List| is turned
8704 into a String by joining the items with a line break in
8705 between (not at the end), like with join(expr, "\n").
Bram Moolenaar944697a2022-02-20 19:48:20 +00008706
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008707 If {idvar} is present and not empty, it is taken as the name
8708 of a variable and a {serverid} for later use with
8709 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008710
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008711 If {timeout} is given the read times out after this many
8712 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008713
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008714 See also |clientserver| |RemoteReply|.
8715 This function is not available in the |sandbox|.
8716 {only available when compiled with the |+clientserver| feature}
8717 Note: Any errors will cause a local error message to be issued
8718 and the result will be the empty string.
8719
8720 Variables will be evaluated in the global namespace,
8721 independent of a function currently being active. Except
8722 when in debug mode, then local function variables and
8723 arguments can be evaluated.
8724
8725 Examples: >
8726 :echo remote_expr("gvim", "2+2")
8727 :echo remote_expr("gvim1", "b:current_syntax")
8728<
8729 Can also be used as a |method|: >
8730 ServerName()->remote_expr(expr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008731<
8732 Return type: |String| or list<{type}>
8733
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008734
8735remote_foreground({server}) *remote_foreground()*
8736 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008737 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008738 This works like: >
8739 remote_expr({server}, "foreground()")
8740< Except that on Win32 systems the client does the work, to work
8741 around the problem that the OS doesn't always allow the server
8742 to bring itself to the foreground.
8743 Note: This does not restore the window if it was minimized,
8744 like foreground() does.
8745 This function is not available in the |sandbox|.
8746
8747 Can also be used as a |method|: >
8748 ServerName()->remote_foreground()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008749<
8750 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008751
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008752 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008753 Win32 console version}
8754
8755
8756remote_peek({serverid} [, {retvar}]) *remote_peek()*
8757 Returns a positive number if there are available strings
8758 from {serverid}. Copies any reply string into the variable
8759 {retvar} if specified. {retvar} must be a string with the
8760 name of a variable.
8761 Returns zero if none are available.
8762 Returns -1 if something is wrong.
8763 See also |clientserver|.
8764 This function is not available in the |sandbox|.
8765 {only available when compiled with the |+clientserver| feature}
8766 Examples: >
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008767 :let repl = ""
8768 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008769
8770< Can also be used as a |method|: >
8771 ServerId()->remote_peek()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008772<
8773 Return type: |Number|
8774
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008775
8776remote_read({serverid}, [{timeout}]) *remote_read()*
8777 Return the oldest available reply from {serverid} and consume
8778 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008779 reply is available. Returns an empty string, if a reply is
8780 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008781 See also |clientserver|.
8782 This function is not available in the |sandbox|.
8783 {only available when compiled with the |+clientserver| feature}
8784 Example: >
8785 :echo remote_read(id)
8786
8787< Can also be used as a |method|: >
8788 ServerId()->remote_read()
8789<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008790 Return type: |String|
8791
8792
8793remote_send({server}, {string} [, {idvar}]) *remote_send()* *E241*
Bram Moolenaar944697a2022-02-20 19:48:20 +00008794 Send the {string} to {server}. The {server} argument is a
8795 string, also see |{server}|.
8796
8797 The string is sent as input keys and the function returns
8798 immediately. At the Vim server the keys are not mapped
8799 |:map|.
8800
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008801 If {idvar} is present, it is taken as the name of a variable
8802 and a {serverid} for later use with remote_read() is stored
8803 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00008804
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008805 See also |clientserver| |RemoteReply|.
8806 This function is not available in the |sandbox|.
8807 {only available when compiled with the |+clientserver| feature}
8808
8809 Note: Any errors will be reported in the server and may mess
8810 up the display.
8811 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008812 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008813 \ remote_read(serverid)
8814
8815 :autocmd NONE RemoteReply *
8816 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008817 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008818 \ 'server2client(expand("<client>"), "HELLO")<CR>')
8819<
8820 Can also be used as a |method|: >
8821 ServerName()->remote_send(keys)
8822<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008823 Return type: |String|
8824
8825
8826remote_startserver({name}) *remote_startserver()* *E941* *E942*
h-east17b69512023-05-01 22:36:56 +01008827 Become the server {name}. {name} must be a non-empty string.
8828 This fails if already running as a server, when |v:servername|
8829 is not empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008830
8831 Can also be used as a |method|: >
8832 ServerName()->remote_startserver()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008833<
8834 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008835
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008836 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008837
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008838
8839remove({list}, {idx}) *remove()*
8840remove({list}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008841 Without {end}: Remove the item at {idx} from |List| {list} and
8842 return the item.
8843 With {end}: Remove items from {idx} to {end} (inclusive) and
8844 return a |List| with these items. When {idx} points to the same
8845 item as {end} a list with one item is returned. When {end}
8846 points to an item before {idx} this is an error.
8847 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008848 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008849 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008850 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008851 :call remove(mylist, 0, 9)
8852<
8853 Use |delete()| to remove a file.
8854
8855 Can also be used as a |method|: >
8856 mylist->remove(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008857<
8858 Return type: any, depending on {list}
8859
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008860
Bram Moolenaarf269eab2022-10-03 18:04:35 +01008861remove({blob}, {idx})
8862remove({blob}, {idx}, {end})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008863 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
8864 return the byte.
8865 With {end}: Remove bytes from {idx} to {end} (inclusive) and
8866 return a |Blob| with these bytes. When {idx} points to the same
8867 byte as {end} a |Blob| with one byte is returned. When {end}
8868 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008869 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008870 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008871 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008872 :call remove(mylist, 0, 9)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008873<
8874 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008875
8876remove({dict}, {key})
8877 Remove the entry from {dict} with key {key} and return it.
8878 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008879 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008880< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008881 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008882
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008883 Return type: any, depending on {dict}
8884
8885
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008886rename({from}, {to}) *rename()*
8887 Rename the file by the name {from} to the name {to}. This
8888 should also work to move files across file systems. The
8889 result is a Number, which is 0 if the file was renamed
8890 successfully, and non-zero when the renaming failed.
8891 NOTE: If {to} exists it is overwritten without warning.
8892 This function is not available in the |sandbox|.
8893
8894 Can also be used as a |method|: >
8895 GetOldName()->rename(newname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008896<
8897 Return type: |Number|
8898
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008899
8900repeat({expr}, {count}) *repeat()*
8901 Repeat {expr} {count} times and return the concatenated
8902 result. Example: >
8903 :let separator = repeat('-', 80)
8904< When {count} is zero or negative the result is empty.
Bakudankun375141e2022-09-09 18:46:47 +01008905 When {expr} is a |List| or a |Blob| the result is {expr}
8906 concatenated {count} times. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008907 :let longlist = repeat(['a', 'b'], 3)
8908< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
8909
8910 Can also be used as a |method|: >
8911 mylist->repeat(count)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008912<
8913 Return type: |String|, |Blob| or list<{type}> depending on
8914 {expr}
8915
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008916
8917resolve({filename}) *resolve()* *E655*
8918 On MS-Windows, when {filename} is a shortcut (a .lnk file),
8919 returns the path the shortcut points to in a simplified form.
8920 When {filename} is a symbolic link or junction point, return
8921 the full path to the target. If the target of junction is
8922 removed, return {filename}.
8923 On Unix, repeat resolving symbolic links in all path
8924 components of {filename} and return the simplified result.
8925 To cope with link cycles, resolving of symbolic links is
8926 stopped after 100 iterations.
8927 On other systems, return the simplified {filename}.
8928 The simplification step is done as by |simplify()|.
8929 resolve() keeps a leading path component specifying the
8930 current directory (provided the result is still a relative
8931 path name) and also keeps a trailing path separator.
8932
8933 Can also be used as a |method|: >
8934 GetName()->resolve()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008935<
8936 Return type: |String|
8937
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008938
8939reverse({object}) *reverse()*
Yegappan Lakshmanan03ff1c22023-05-06 14:08:21 +01008940 Reverse the order of items in {object}. {object} can be a
8941 |List|, a |Blob| or a |String|. For a List and a Blob the
8942 items are reversed in-place and {object} is returned.
8943 For a String a new String is returned.
8944 Returns zero if {object} is not a List, Blob or a String.
8945 If you want a List or Blob to remain unmodified make a copy
8946 first: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008947 :let revlist = reverse(copy(mylist))
8948< Can also be used as a |method|: >
8949 mylist->reverse()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008950<
8951 Return type: |String|, |Blob| or list<{type}> depending on
8952 {object}
8953
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008954
8955round({expr}) *round()*
8956 Round off {expr} to the nearest integral value and return it
8957 as a |Float|. If {expr} lies halfway between two integral
8958 values, then use the larger one (away from zero).
8959 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008960 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008961 Examples: >
8962 echo round(0.456)
8963< 0.0 >
8964 echo round(4.5)
8965< 5.0 >
8966 echo round(-4.5)
8967< -5.0
8968
8969 Can also be used as a |method|: >
8970 Compute()->round()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008971<
8972 Return type: |Float|
8973
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008974
8975rubyeval({expr}) *rubyeval()*
8976 Evaluate Ruby expression {expr} and return its result
8977 converted to Vim data structures.
8978 Numbers, floats and strings are returned as they are (strings
8979 are copied though).
8980 Arrays are represented as Vim |List| type.
8981 Hashes are represented as Vim |Dictionary| type.
8982 Other objects are represented as strings resulted from their
8983 "Object#to_s" method.
8984 Note that in a `:def` function local variables are not visible
8985 to {expr}.
8986
8987 Can also be used as a |method|: >
8988 GetRubyExpr()->rubyeval()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008989<
8990 Return type: any, depending on {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008991
Christian Brabandt5674c9a2024-06-09 00:13:43 +02008992 {only available when compiled with the |+ruby| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008993
8994screenattr({row}, {col}) *screenattr()*
8995 Like |screenchar()|, but return the attribute. This is a rather
8996 arbitrary number that can only be used to compare to the
8997 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008998 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008999
9000 Can also be used as a |method|: >
9001 GetRow()->screenattr(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009002<
9003 Return type: |Number|
9004
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009005
9006screenchar({row}, {col}) *screenchar()*
9007 The result is a Number, which is the character at position
9008 [row, col] on the screen. This works for every possible
9009 screen position, also status lines, window separators and the
9010 command line. The top left position is row one, column one
9011 The character excludes composing characters. For double-byte
9012 encodings it may only be the first byte.
9013 This is mainly to be used for testing.
9014 Returns -1 when row or col is out of range.
9015
9016 Can also be used as a |method|: >
9017 GetRow()->screenchar(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009018<
9019 Return type: |Number|
9020
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009021
9022screenchars({row}, {col}) *screenchars()*
9023 The result is a |List| of Numbers. The first number is the same
9024 as what |screenchar()| returns. Further numbers are
9025 composing characters on top of the base character.
9026 This is mainly to be used for testing.
9027 Returns an empty List when row or col is out of range.
9028
9029 Can also be used as a |method|: >
9030 GetRow()->screenchars(col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009031<
9032 Return type: list<number> or list<any>
9033
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009034
9035screencol() *screencol()*
9036 The result is a Number, which is the current screen column of
9037 the cursor. The leftmost column has number 1.
9038 This function is mainly used for testing.
9039
9040 Note: Always returns the current screen column, thus if used
9041 in a command (e.g. ":echo screencol()") it will return the
9042 column inside the command line, which is 1 when the command is
9043 executed. To get the cursor position in the file use one of
9044 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009045 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009046 nnoremap <silent> GG :echom screencol()<CR>
9047 nnoremap GG <Cmd>echom screencol()<CR>
9048<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009049 Return type: |Number|
9050
9051
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009052screenpos({winid}, {lnum}, {col}) *screenpos()*
9053 The result is a Dict with the screen position of the text
9054 character in window {winid} at buffer line {lnum} and column
9055 {col}. {col} is a one-based byte index.
9056 The Dict has these members:
9057 row screen row
9058 col first screen column
9059 endcol last screen column
9060 curscol cursor screen column
9061 If the specified position is not visible, all values are zero.
9062 The "endcol" value differs from "col" when the character
9063 occupies more than one screen cell. E.g. for a Tab "col" can
9064 be 1 and "endcol" can be 8.
9065 The "curscol" value is where the cursor would be placed. For
9066 a Tab it would be the same as "endcol", while for a double
9067 width character it would be the same as "col".
9068 The |conceal| feature is ignored here, the column numbers are
9069 as if 'conceallevel' is zero. You can set the cursor to the
9070 right position and use |screencol()| to get the value with
9071 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00009072 If the position is in a closed fold the screen position of the
9073 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01009074 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009075
9076 Can also be used as a |method|: >
9077 GetWinid()->screenpos(lnum, col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009078<
9079 Return type: dict<number> or dict<any>
9080
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009081
9082screenrow() *screenrow()*
9083 The result is a Number, which is the current screen row of the
9084 cursor. The top line has number one.
9085 This function is mainly used for testing.
9086 Alternatively you can use |winline()|.
9087
9088 Note: Same restrictions as with |screencol()|.
9089
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009090 Return type: |Number|
9091
9092
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009093screenstring({row}, {col}) *screenstring()*
9094 The result is a String that contains the base character and
9095 any composing characters at position [row, col] on the screen.
9096 This is like |screenchars()| but returning a String with the
9097 characters.
9098 This is mainly to be used for testing.
9099 Returns an empty String when row or col is out of range.
9100
9101 Can also be used as a |method|: >
9102 GetRow()->screenstring(col)
9103<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009104 Return type: |String|
9105
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009106 *search()*
9107search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
9108 Search for regexp pattern {pattern}. The search starts at the
9109 cursor position (you can use |cursor()| to set it).
9110
9111 When a match has been found its line number is returned.
9112 If there is no match a 0 is returned and the cursor doesn't
9113 move. No error message is given.
Christian Brabandt9a660d22024-03-12 22:03:09 +01009114 To get the matched string, use |matchbufline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009115
9116 {flags} is a String, which can contain these character flags:
9117 'b' search Backward instead of forward
9118 'c' accept a match at the Cursor position
9119 'e' move to the End of the match
9120 'n' do Not move the cursor
9121 'p' return number of matching sub-Pattern (see below)
9122 's' Set the ' mark at the previous location of the cursor
9123 'w' Wrap around the end of the file
9124 'W' don't Wrap around the end of the file
Doug Kearns8a27d972025-01-05 15:56:57 +01009125 'z' start searching at the cursor column instead of Zero
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009126 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
9127
9128 If the 's' flag is supplied, the ' mark is set, only if the
9129 cursor is moved. The 's' flag cannot be combined with the 'n'
9130 flag.
9131
9132 'ignorecase', 'smartcase' and 'magic' are used.
9133
9134 When the 'z' flag is not given, forward searching always
9135 starts in column zero and then matches before the cursor are
9136 skipped. When the 'c' flag is present in 'cpo' the next
9137 search starts after the match. Without the 'c' flag the next
Bram Moolenaarfd999452022-08-24 18:30:14 +01009138 search starts one column after the start of the match. This
9139 matters for overlapping matches. See |cpo-c|. You can also
9140 insert "\ze" to change where the match ends, see |/\ze|.
9141
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009142 When searching backwards and the 'z' flag is given then the
9143 search starts in column zero, thus no match in the current
9144 line will be found (unless wrapping around the end of the
9145 file).
9146
9147 When the {stopline} argument is given then the search stops
9148 after searching this line. This is useful to restrict the
9149 search to a range of lines. Examples: >
9150 let match = search('(', 'b', line("w0"))
9151 let end = search('END', '', line("w$"))
9152< When {stopline} is used and it is not zero this also implies
9153 that the search does not wrap around the end of the file.
9154 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01009155 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009156 When the {timeout} argument is given the search stops when
9157 more than this many milliseconds have passed. Thus when
9158 {timeout} is 500 the search stops after half a second.
9159 The value must not be negative. A zero value is like not
9160 giving the argument.
Christian Brabandtd657d3d2024-09-10 21:55:49 +02009161
9162 Note: the timeout is only considered when searching, not
9163 while evaluating the {skip} expression.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009164 {only available when compiled with the |+reltime| feature}
9165
9166 If the {skip} expression is given it is evaluated with the
9167 cursor positioned on the start of a match. If it evaluates to
9168 non-zero this match is skipped. This can be used, for
9169 example, to skip a match in a comment or a string.
9170 {skip} can be a string, which is evaluated as an expression, a
9171 function reference or a lambda.
9172 When {skip} is omitted or empty, every match is accepted.
9173 When evaluating {skip} causes an error the search is aborted
9174 and -1 returned.
9175 *search()-sub-match*
9176 With the 'p' flag the returned value is one more than the
9177 first sub-match in \(\). One if none of them matched but the
9178 whole pattern did match.
9179 To get the column number too use |searchpos()|.
9180
9181 The cursor will be positioned at the match, unless the 'n'
9182 flag is used.
9183
9184 Example (goes over all files in the argument list): >
9185 :let n = 1
9186 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009187 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009188 : " start at the last char in the file and wrap for the
9189 : " first search to find match at start of file
9190 : normal G$
9191 : let flags = "w"
9192 : while search("foo", flags) > 0
9193 : s/foo/bar/g
9194 : let flags = "W"
9195 : endwhile
9196 : update " write the file if modified
9197 : let n = n + 1
9198 :endwhile
9199<
9200 Example for using some flags: >
9201 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
9202< This will search for the keywords "if", "else", and "endif"
9203 under or after the cursor. Because of the 'p' flag, it
9204 returns 1, 2, or 3 depending on which keyword is found, or 0
9205 if the search fails. With the cursor on the first word of the
9206 line:
9207 if (foo == 0) | let foo = foo + 1 | endif ~
9208 the function returns 1. Without the 'c' flag, the function
9209 finds the "endif" and returns 3. The same thing happens
9210 without the 'e' flag if the cursor is on the "f" of "if".
9211 The 'n' flag tells the function not to move the cursor.
9212
9213 Can also be used as a |method|: >
9214 GetPattern()->search()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009215<
9216 Return type: |Number|
9217
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009218
9219searchcount([{options}]) *searchcount()*
9220 Get or update the last search count, like what is displayed
9221 without the "S" flag in 'shortmess'. This works even if
9222 'shortmess' does contain the "S" flag.
9223
9224 This returns a |Dictionary|. The dictionary is empty if the
9225 previous pattern was not set and "pattern" was not specified.
9226
9227 key type meaning ~
9228 current |Number| current position of match;
9229 0 if the cursor position is
9230 before the first match
9231 exact_match |Boolean| 1 if "current" is matched on
9232 "pos", otherwise 0
9233 total |Number| total count of matches found
9234 incomplete |Number| 0: search was fully completed
9235 1: recomputing was timed out
9236 2: max count exceeded
9237
9238 For {options} see further down.
9239
9240 To get the last search count when |n| or |N| was pressed, call
9241 this function with `recompute: 0` . This sometimes returns
9242 wrong information because |n| and |N|'s maximum count is 99.
9243 If it exceeded 99 the result must be max count + 1 (100). If
9244 you want to get correct information, specify `recompute: 1`: >
9245
9246 " result == maxcount + 1 (100) when many matches
9247 let result = searchcount(#{recompute: 0})
9248
9249 " Below returns correct result (recompute defaults
9250 " to 1)
9251 let result = searchcount()
9252<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01009253 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009254 function! LastSearchCount() abort
9255 let result = searchcount(#{recompute: 0})
9256 if empty(result)
9257 return ''
9258 endif
9259 if result.incomplete ==# 1 " timed out
9260 return printf(' /%s [?/??]', @/)
9261 elseif result.incomplete ==# 2 " max count exceeded
9262 if result.total > result.maxcount &&
9263 \ result.current > result.maxcount
9264 return printf(' /%s [>%d/>%d]', @/,
9265 \ result.current, result.total)
9266 elseif result.total > result.maxcount
9267 return printf(' /%s [%d/>%d]', @/,
9268 \ result.current, result.total)
9269 endif
9270 endif
9271 return printf(' /%s [%d/%d]', @/,
9272 \ result.current, result.total)
9273 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009274 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009275
9276 " Or if you want to show the count only when
9277 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009278 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009279 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
9280<
9281 You can also update the search count, which can be useful in a
9282 |CursorMoved| or |CursorMovedI| autocommand: >
9283
9284 autocmd CursorMoved,CursorMovedI *
9285 \ let s:searchcount_timer = timer_start(
9286 \ 200, function('s:update_searchcount'))
9287 function! s:update_searchcount(timer) abort
9288 if a:timer ==# s:searchcount_timer
9289 call searchcount(#{
9290 \ recompute: 1, maxcount: 0, timeout: 100})
9291 redrawstatus
9292 endif
9293 endfunction
9294<
9295 This can also be used to count matched texts with specified
9296 pattern in the current buffer using "pattern": >
9297
9298 " Count '\<foo\>' in this buffer
9299 " (Note that it also updates search count)
9300 let result = searchcount(#{pattern: '\<foo\>'})
9301
9302 " To restore old search count by old pattern,
9303 " search again
9304 call searchcount()
9305<
9306 {options} must be a |Dictionary|. It can contain:
9307 key type meaning ~
9308 recompute |Boolean| if |TRUE|, recompute the count
9309 like |n| or |N| was executed.
9310 otherwise returns the last
9311 computed result (when |n| or
9312 |N| was used when "S" is not
9313 in 'shortmess', or this
9314 function was called).
9315 (default: |TRUE|)
9316 pattern |String| recompute if this was given
9317 and different with |@/|.
9318 this works as same as the
9319 below command is executed
9320 before calling this function >
9321 let @/ = pattern
9322< (default: |@/|)
9323 timeout |Number| 0 or negative number is no
9324 timeout. timeout milliseconds
9325 for recomputing the result
9326 (default: 0)
9327 maxcount |Number| 0 or negative number is no
9328 limit. max count of matched
9329 text while recomputing the
9330 result. if search exceeded
9331 total count, "total" value
9332 becomes `maxcount + 1`
9333 (default: 99)
9334 pos |List| `[lnum, col, off]` value
9335 when recomputing the result.
9336 this changes "current" result
9337 value. see |cursor()|,
9338 |getpos()|
9339 (default: cursor's position)
9340
9341 Can also be used as a |method|: >
9342 GetSearchOpts()->searchcount()
9343<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009344 Return type: dict<number>
9345
9346
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009347searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
9348 Search for the declaration of {name}.
9349
9350 With a non-zero {global} argument it works like |gD|, find
9351 first match in the file. Otherwise it works like |gd|, find
9352 first match in the function.
9353
9354 With a non-zero {thisblock} argument matches in a {} block
9355 that ends before the cursor position are ignored. Avoids
9356 finding variable declarations only valid in another scope.
9357
9358 Moves the cursor to the found match.
9359 Returns zero for success, non-zero for failure.
9360 Example: >
9361 if searchdecl('myvar') == 0
9362 echo getline('.')
9363 endif
9364<
9365 Can also be used as a |method|: >
9366 GetName()->searchdecl()
9367<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009368 Return type: |Number|
9369
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009370 *searchpair()*
9371searchpair({start}, {middle}, {end} [, {flags} [, {skip}
9372 [, {stopline} [, {timeout}]]]])
9373 Search for the match of a nested start-end pair. This can be
9374 used to find the "endif" that matches an "if", while other
9375 if/endif pairs in between are ignored.
9376 The search starts at the cursor. The default is to search
9377 forward, include 'b' in {flags} to search backward.
9378 If a match is found, the cursor is positioned at it and the
9379 line number is returned. If no match is found 0 or -1 is
9380 returned and the cursor doesn't move. No error message is
9381 given.
9382
9383 {start}, {middle} and {end} are patterns, see |pattern|. They
9384 must not contain \( \) pairs. Use of \%( \) is allowed. When
9385 {middle} is not empty, it is found when searching from either
9386 direction, but only when not in a nested start-end pair. A
9387 typical use is: >
9388 searchpair('\<if\>', '\<else\>', '\<endif\>')
9389< By leaving {middle} empty the "else" is skipped.
9390
9391 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
9392 |search()|. Additionally:
9393 'r' Repeat until no more matches found; will find the
9394 outer pair. Implies the 'W' flag.
9395 'm' Return number of matches instead of line number with
9396 the match; will be > 1 when 'r' is used.
9397 Note: it's nearly always a good idea to use the 'W' flag, to
9398 avoid wrapping around the end of the file.
9399
9400 When a match for {start}, {middle} or {end} is found, the
9401 {skip} expression is evaluated with the cursor positioned on
9402 the start of the match. It should return non-zero if this
9403 match is to be skipped. E.g., because it is inside a comment
9404 or a string.
9405 When {skip} is omitted or empty, every match is accepted.
9406 When evaluating {skip} causes an error the search is aborted
9407 and -1 returned.
9408 {skip} can be a string, a lambda, a funcref or a partial.
9409 Anything else makes the function fail.
9410 In a `:def` function when the {skip} argument is a string
9411 constant it is compiled into instructions.
9412
9413 For {stopline} and {timeout} see |search()|.
9414
9415 The value of 'ignorecase' is used. 'magic' is ignored, the
9416 patterns are used like it's on.
9417
9418 The search starts exactly at the cursor. A match with
9419 {start}, {middle} or {end} at the next character, in the
9420 direction of searching, is the first one found. Example: >
9421 if 1
9422 if 2
9423 endif 2
9424 endif 1
9425< When starting at the "if 2", with the cursor on the "i", and
9426 searching forwards, the "endif 2" is found. When starting on
9427 the character just before the "if 2", the "endif 1" will be
9428 found. That's because the "if 2" will be found first, and
9429 then this is considered to be a nested if/endif from "if 2" to
9430 "endif 2".
9431 When searching backwards and {end} is more than one character,
9432 it may be useful to put "\zs" at the end of the pattern, so
9433 that when the cursor is inside a match with the end it finds
9434 the matching start.
9435
9436 Example, to find the "endif" command in a Vim script: >
9437
9438 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
9439 \ 'getline(".") =~ "^\\s*\""')
9440
9441< The cursor must be at or after the "if" for which a match is
9442 to be found. Note that single-quote strings are used to avoid
9443 having to double the backslashes. The skip expression only
9444 catches comments at the start of a line, not after a command.
9445 Also, a word "en" or "if" halfway a line is considered a
9446 match.
9447 Another example, to search for the matching "{" of a "}": >
9448
9449 :echo searchpair('{', '', '}', 'bW')
9450
9451< This works when the cursor is at or before the "}" for which a
9452 match is to be found. To reject matches that syntax
9453 highlighting recognized as strings: >
9454
9455 :echo searchpair('{', '', '}', 'bW',
9456 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
9457<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009458 Return type: |Number|
9459
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009460 *searchpairpos()*
9461searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
9462 [, {stopline} [, {timeout}]]]])
9463 Same as |searchpair()|, but returns a |List| with the line and
9464 column position of the match. The first element of the |List|
9465 is the line number and the second element is the byte index of
9466 the column position of the match. If no match is found,
9467 returns [0, 0]. >
9468
9469 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
9470<
9471 See |match-parens| for a bigger and more useful example.
9472
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009473 Return type: list<number>
9474
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009475 *searchpos()*
9476searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
9477 Same as |search()|, but returns a |List| with the line and
9478 column position of the match. The first element of the |List|
9479 is the line number and the second element is the byte index of
9480 the column position of the match. If no match is found,
9481 returns [0, 0].
9482 Example: >
9483 :let [lnum, col] = searchpos('mypattern', 'n')
9484
9485< When the 'p' flag is given then there is an extra item with
9486 the sub-pattern match number |search()-sub-match|. Example: >
9487 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
9488< In this example "submatch" is 2 when a lowercase letter is
9489 found |/\l|, 3 when an uppercase letter is found |/\u|.
9490
9491 Can also be used as a |method|: >
9492 GetPattern()->searchpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009493<
9494 Return type: list<number>
9495
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009496
9497server2client({clientid}, {string}) *server2client()*
9498 Send a reply string to {clientid}. The most recent {clientid}
9499 that sent a string can be retrieved with expand("<client>").
9500 {only available when compiled with the |+clientserver| feature}
9501 Returns zero for success, -1 for failure.
9502 Note:
9503 This id has to be stored before the next command can be
9504 received. I.e. before returning from the received command and
9505 before calling any commands that waits for input.
9506 See also |clientserver|.
9507 Example: >
9508 :echo server2client(expand("<client>"), "HELLO")
9509
9510< Can also be used as a |method|: >
9511 GetClientId()->server2client(string)
9512<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009513 Return type: |Number|
9514
9515
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009516serverlist() *serverlist()*
9517 Return a list of available server names, one per line.
9518 When there are no servers or the information is not available
9519 an empty string is returned. See also |clientserver|.
9520 {only available when compiled with the |+clientserver| feature}
9521 Example: >
9522 :echo serverlist()
9523<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009524 Return type: |String|
9525
9526
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009527setbufline({buf}, {lnum}, {text}) *setbufline()*
9528 Set line {lnum} to {text} in buffer {buf}. This works like
9529 |setline()| for the specified buffer.
9530
9531 This function works only for loaded buffers. First call
9532 |bufload()| if needed.
9533
9534 To insert lines use |appendbufline()|.
9535 Any text properties in {lnum} are cleared.
9536
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00009537 {text} can be a string to set one line, or a List of strings
9538 to set multiple lines. If the List extends below the last
9539 line then those lines are added. If the List is empty then
9540 nothing is changed and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009541
9542 For the use of {buf}, see |bufname()| above.
9543
9544 {lnum} is used like with |setline()|.
9545 Use "$" to refer to the last line in buffer {buf}.
9546 When {lnum} is just below the last line the {text} will be
9547 added below the last line.
9548
9549 When {buf} is not a valid buffer, the buffer is not loaded or
9550 {lnum} is not valid then 1 is returned. In |Vim9| script an
9551 error is given.
9552 On success 0 is returned.
9553
9554 Can also be used as a |method|, the base is passed as the
9555 third argument: >
9556 GetText()->setbufline(buf, lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009557<
9558 Return type: |Number|
9559
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009560
9561setbufvar({buf}, {varname}, {val}) *setbufvar()*
9562 Set option or local variable {varname} in buffer {buf} to
9563 {val}.
9564 This also works for a global or local window option, but it
9565 doesn't work for a global or local window variable.
9566 For a local window option the global value is unchanged.
9567 For the use of {buf}, see |bufname()| above.
9568 The {varname} argument is a string.
9569 Note that the variable name without "b:" must be used.
9570 Examples: >
9571 :call setbufvar(1, "&mod", 1)
9572 :call setbufvar("todo", "myvar", "foobar")
9573< This function is not available in the |sandbox|.
9574
9575 Can also be used as a |method|, the base is passed as the
9576 third argument: >
9577 GetValue()->setbufvar(buf, varname)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009578<
9579 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009580
9581
9582setcellwidths({list}) *setcellwidths()*
9583 Specify overrides for cell widths of character ranges. This
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009584 tells Vim how wide characters are when displayed in the
9585 terminal, counted in screen cells. The values override
9586 'ambiwidth'. Example: >
9587 call setcellwidths([
Bram Moolenaar938ae282023-02-20 20:44:55 +00009588 \ [0x111, 0x111, 1],
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009589 \ [0x2194, 0x2199, 2],
9590 \ ])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009591
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009592< The {list} argument is a List of Lists with each three
9593 numbers: [{low}, {high}, {width}]. *E1109* *E1110*
9594 {low} and {high} can be the same, in which case this refers to
9595 one character. Otherwise it is the range of characters from
9596 {low} to {high} (inclusive). *E1111* *E1114*
K.Takata71933232023-01-20 16:00:55 +00009597 Only characters with value 0x80 and higher can be used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009598
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009599 {width} must be either 1 or 2, indicating the character width
9600 in screen cells. *E1112*
9601 An error is given if the argument is invalid, also when a
Bram Moolenaar938ae282023-02-20 20:44:55 +00009602 range overlaps with another. *E1113*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009603
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009604 If the new value causes 'fillchars' or 'listchars' to become
9605 invalid it is rejected and an error is given.
9606
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009607 To clear the overrides pass an empty {list}: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009608 setcellwidths([]);
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009609
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009610< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
Bram Moolenaarb59ae592022-11-23 23:46:31 +00009611 the effect for known emoji characters. Move the cursor
9612 through the text to check if the cell widths of your terminal
9613 match with what Vim knows about each emoji. If it doesn't
9614 look right you need to adjust the {list} argument.
9615
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009616 Return type: |Number|
9617
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009618
9619setcharpos({expr}, {list}) *setcharpos()*
9620 Same as |setpos()| but uses the specified column number as the
9621 character index instead of the byte index in the line.
9622
9623 Example:
9624 With the text "여보세요" in line 8: >
9625 call setcharpos('.', [0, 8, 4, 0])
9626< positions the cursor on the fourth character '요'. >
9627 call setpos('.', [0, 8, 4, 0])
9628< positions the cursor on the second character '보'.
9629
9630 Can also be used as a |method|: >
9631 GetPosition()->setcharpos('.')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009632<
9633 Return type: |Number|
9634
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009635
9636setcharsearch({dict}) *setcharsearch()*
9637 Set the current character search information to {dict},
9638 which contains one or more of the following entries:
9639
9640 char character which will be used for a subsequent
9641 |,| or |;| command; an empty string clears the
9642 character search
9643 forward direction of character search; 1 for forward,
9644 0 for backward
9645 until type of character search; 1 for a |t| or |T|
9646 character search, 0 for an |f| or |F|
9647 character search
9648
9649 This can be useful to save/restore a user's character search
9650 from a script: >
9651 :let prevsearch = getcharsearch()
9652 :" Perform a command which clobbers user's search
9653 :call setcharsearch(prevsearch)
9654< Also see |getcharsearch()|.
9655
9656 Can also be used as a |method|: >
9657 SavedSearch()->setcharsearch()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009658<
9659 Return type: dict<any>
9660
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009661
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009662setcmdline({str} [, {pos}]) *setcmdline()*
9663 Set the command line to {str} and set the cursor position to
9664 {pos}.
9665 If {pos} is omitted, the cursor is positioned after the text.
9666 Returns 0 when successful, 1 when not editing the command
9667 line.
9668
9669 Can also be used as a |method|: >
9670 GetText()->setcmdline()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009671<
9672 Return type: |Number|
9673
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009674
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009675setcmdpos({pos}) *setcmdpos()*
9676 Set the cursor position in the command line to byte position
9677 {pos}. The first position is 1.
9678 Use |getcmdpos()| to obtain the current position.
9679 Only works while editing the command line, thus you must use
9680 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
9681 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
9682 set after the command line is set to the expression. For
9683 |c_CTRL-R_=| it is set after evaluating the expression but
9684 before inserting the resulting text.
9685 When the number is too big the cursor is put at the end of the
9686 line. A number smaller than one has undefined results.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01009687 Returns 0 when successful, 1 when not editing the command
9688 line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009689
9690 Can also be used as a |method|: >
9691 GetPos()->setcmdpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009692<
9693 Return type: |Number|
9694
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009695
9696setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
9697setcursorcharpos({list})
9698 Same as |cursor()| but uses the specified column number as the
9699 character index instead of the byte index in the line.
9700
9701 Example:
9702 With the text "여보세요" in line 4: >
9703 call setcursorcharpos(4, 3)
9704< positions the cursor on the third character '세'. >
9705 call cursor(4, 3)
9706< positions the cursor on the first character '여'.
9707
9708 Can also be used as a |method|: >
9709 GetCursorPos()->setcursorcharpos()
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009710<
9711 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009712
9713
9714setenv({name}, {val}) *setenv()*
9715 Set environment variable {name} to {val}. Example: >
9716 call setenv('HOME', '/home/myhome')
9717
9718< When {val} is |v:null| the environment variable is deleted.
9719 See also |expr-env|.
9720
9721 Can also be used as a |method|, the base is passed as the
9722 second argument: >
9723 GetPath()->setenv('PATH')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009724<
9725 Return type: |Number|
9726
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009727
9728setfperm({fname}, {mode}) *setfperm()* *chmod*
9729 Set the file permissions for {fname} to {mode}.
9730 {mode} must be a string with 9 characters. It is of the form
9731 "rwxrwxrwx", where each group of "rwx" flags represent, in
9732 turn, the permissions of the owner of the file, the group the
9733 file belongs to, and other users. A '-' character means the
9734 permission is off, any other character means on. Multi-byte
9735 characters are not supported.
9736
9737 For example "rw-r-----" means read-write for the user,
9738 readable by the group, not accessible by others. "xx-x-----"
9739 would do the same thing.
9740
9741 Returns non-zero for success, zero for failure.
9742
9743 Can also be used as a |method|: >
9744 GetFilename()->setfperm(mode)
9745<
9746 To read permissions see |getfperm()|.
9747
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009748 Return type: |Number|
9749
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009750
9751setline({lnum}, {text}) *setline()*
9752 Set line {lnum} of the current buffer to {text}. To insert
9753 lines use |append()|. To set lines in another buffer use
Christian Brabandt946f61c2024-06-17 13:17:58 +02009754 |setbufline()|.
h-east52e7cc22024-07-28 17:03:29 +02009755 Any text properties in {lnum} are cleared. See
9756 |text-prop-cleared|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009757
9758 {lnum} is used like with |getline()|.
9759 When {lnum} is just below the last line the {text} will be
9760 added below the last line.
9761 {text} can be any type or a List of any type, each item is
Bram Moolenaarcd9c8d42022-11-05 23:46:43 +00009762 converted to a String. When {text} is an empty List then
9763 nothing is changed and FALSE is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009764
9765 If this succeeds, FALSE is returned. If this fails (most likely
9766 because {lnum} is invalid) TRUE is returned.
9767 In |Vim9| script an error is given if {lnum} is invalid.
9768
9769 Example: >
9770 :call setline(5, strftime("%c"))
9771
9772< When {text} is a |List| then line {lnum} and following lines
9773 will be set to the items in the list. Example: >
9774 :call setline(5, ['aaa', 'bbb', 'ccc'])
9775< This is equivalent to: >
9776 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
9777 : call setline(n, l)
9778 :endfor
9779
9780< Note: The '[ and '] marks are not set.
9781
9782 Can also be used as a |method|, the base is passed as the
9783 second argument: >
9784 GetText()->setline(lnum)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009785<
9786 Return type: |Number|
9787
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009788
9789setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
9790 Create or replace or add to the location list for window {nr}.
9791 {nr} can be the window number or the |window-ID|.
9792 When {nr} is zero the current window is used.
9793
9794 For a location list window, the displayed location list is
9795 modified. For an invalid window number {nr}, -1 is returned.
9796 Otherwise, same as |setqflist()|.
9797 Also see |location-list|.
9798
9799 For {action} see |setqflist-action|.
9800
9801 If the optional {what} dictionary argument is supplied, then
9802 only the items listed in {what} are set. Refer to |setqflist()|
9803 for the list of supported keys in {what}.
9804
9805 Can also be used as a |method|, the base is passed as the
9806 second argument: >
9807 GetLoclist()->setloclist(winnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009808<
9809 Return type: |Number|
9810
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009811
9812setmatches({list} [, {win}]) *setmatches()*
9813 Restores a list of matches saved by |getmatches()| for the
9814 current window. Returns 0 if successful, otherwise -1. All
9815 current matches are cleared before the list is restored. See
9816 example for |getmatches()|.
9817 If {win} is specified, use the window with this number or
9818 window ID instead of the current window.
9819
9820 Can also be used as a |method|: >
9821 GetMatches()->setmatches()
9822<
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009823 Return type: |Number|
9824
9825
9826setpos({expr}, {list}) *setpos()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009827 Set the position for String {expr}. Possible values:
9828 . the cursor
9829 'x mark x
9830
9831 {list} must be a |List| with four or five numbers:
9832 [bufnum, lnum, col, off]
9833 [bufnum, lnum, col, off, curswant]
9834
9835 "bufnum" is the buffer number. Zero can be used for the
9836 current buffer. When setting an uppercase mark "bufnum" is
9837 used for the mark position. For other marks it specifies the
9838 buffer to set the mark in. You can use the |bufnr()| function
9839 to turn a file name into a buffer number.
9840 For setting the cursor and the ' mark "bufnum" is ignored,
9841 since these are associated with a window, not a buffer.
9842 Does not change the jumplist.
9843
9844 "lnum" and "col" are the position in the buffer. The first
9845 column is 1. Use a zero "lnum" to delete a mark. If "col" is
9846 smaller than 1 then 1 is used. To use the character count
9847 instead of the byte count, use |setcharpos()|.
9848
9849 The "off" number is only used when 'virtualedit' is set. Then
9850 it is the offset in screen columns from the start of the
9851 character. E.g., a position within a <Tab> or after the last
9852 character.
9853
9854 The "curswant" number is only used when setting the cursor
9855 position. It sets the preferred column for when moving the
9856 cursor vertically. When the "curswant" number is missing the
9857 preferred column is not set. When it is present and setting a
9858 mark position it is not used.
9859
9860 Note that for '< and '> changing the line number may result in
9861 the marks to be effectively be swapped, so that '< is always
9862 before '>.
9863
9864 Returns 0 when the position could be set, -1 otherwise.
9865 An error message is given if {expr} is invalid.
9866
9867 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
9868
9869 This does not restore the preferred column for moving
9870 vertically; if you set the cursor position with this, |j| and
9871 |k| motions will jump to previous columns! Use |cursor()| to
9872 also set the preferred column. Also see the "curswant" key in
9873 |winrestview()|.
9874
9875 Can also be used as a |method|: >
9876 GetPosition()->setpos('.')
Christian Brabandt5674c9a2024-06-09 00:13:43 +02009877<
9878 Return type: |Number|
9879
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009880
9881setqflist({list} [, {action} [, {what}]]) *setqflist()*
9882 Create or replace or add to the quickfix list.
9883
9884 If the optional {what} dictionary argument is supplied, then
9885 only the items listed in {what} are set. The first {list}
9886 argument is ignored. See below for the supported items in
9887 {what}.
9888 *setqflist-what*
9889 When {what} is not present, the items in {list} are used. Each
9890 item must be a dictionary. Non-dictionary items in {list} are
9891 ignored. Each dictionary item can contain the following
9892 entries:
9893
9894 bufnr buffer number; must be the number of a valid
9895 buffer
9896 filename name of a file; only used when "bufnr" is not
9897 present or it is invalid.
9898 module name of a module; if given it will be used in
9899 quickfix error window instead of the filename.
9900 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +00009901 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009902 pattern search pattern used to locate the error
9903 col column number
9904 vcol when non-zero: "col" is visual column
9905 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +00009906 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009907 nr error number
9908 text description of the error
9909 type single-character error type, 'E', 'W', etc.
9910 valid recognized error message
Tom Praschanca6ac992023-08-11 23:26:12 +02009911 user_data custom data associated with the item, can be
9912 any type.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009913
9914 The "col", "vcol", "nr", "type" and "text" entries are
9915 optional. Either "lnum" or "pattern" entry can be used to
9916 locate a matching error line.
9917 If the "filename" and "bufnr" entries are not present or
9918 neither the "lnum" or "pattern" entries are present, then the
9919 item will not be handled as an error line.
9920 If both "pattern" and "lnum" are present then "pattern" will
9921 be used.
9922 If the "valid" entry is not supplied, then the valid flag is
9923 set when "bufnr" is a valid buffer or "filename" exists.
9924 If you supply an empty {list}, the quickfix list will be
9925 cleared.
9926 Note that the list is not exactly the same as what
9927 |getqflist()| returns.
9928
9929 {action} values: *setqflist-action* *E927*
9930 'a' The items from {list} are added to the existing
9931 quickfix list. If there is no existing list, then a
9932 new list is created.
9933
9934 'r' The items from the current quickfix list are replaced
9935 with the items from {list}. This can also be used to
9936 clear the list: >
9937 :call setqflist([], 'r')
9938<
Jeremy Fleischman27fbf6e2024-10-14 20:46:27 +02009939 'u' Like 'r', but tries to preserve the current selection
9940 in the quickfix list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009941 'f' All the quickfix lists in the quickfix stack are
9942 freed.
9943
9944 If {action} is not present or is set to ' ', then a new list
9945 is created. The new quickfix list is added after the current
9946 quickfix list in the stack and all the following lists are
9947 freed. To add a new quickfix list at the end of the stack,
9948 set "nr" in {what} to "$".
9949
9950 The following items can be specified in dictionary {what}:
9951 context quickfix list context. See |quickfix-context|
9952 efm errorformat to use when parsing text from
9953 "lines". If this is not present, then the
9954 'errorformat' option value is used.
9955 See |quickfix-parse|
9956 id quickfix list identifier |quickfix-ID|
9957 idx index of the current entry in the quickfix
9958 list specified by 'id' or 'nr'. If set to '$',
9959 then the last entry in the list is set as the
9960 current entry. See |quickfix-index|
9961 items list of quickfix entries. Same as the {list}
9962 argument.
9963 lines use 'errorformat' to parse a list of lines and
9964 add the resulting entries to the quickfix list
9965 {nr} or {id}. Only a |List| value is supported.
9966 See |quickfix-parse|
9967 nr list number in the quickfix stack; zero
9968 means the current quickfix list and "$" means
9969 the last quickfix list.
9970 quickfixtextfunc
9971 function to get the text to display in the
9972 quickfix window. The value can be the name of
9973 a function or a funcref or a lambda. Refer to
9974 |quickfix-window-function| for an explanation
9975 of how to write the function and an example.
9976 title quickfix list title text. See |quickfix-title|
9977 Unsupported keys in {what} are ignored.
9978 If the "nr" item is not present, then the current quickfix list
9979 is modified. When creating a new quickfix list, "nr" can be
9980 set to a value one greater than the quickfix stack size.
9981 When modifying a quickfix list, to guarantee that the correct
9982 list is modified, "id" should be used instead of "nr" to
9983 specify the list.
9984
9985 Examples (See also |setqflist-examples|): >
9986 :call setqflist([], 'r', {'title': 'My search'})
9987 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
9988 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
9989<
9990 Returns zero for success, -1 for failure.
9991
9992 This function can be used to create a quickfix list
9993 independent of the 'errorformat' setting. Use a command like
9994 `:cc 1` to jump to the first position.
9995
9996 Can also be used as a |method|, the base is passed as the
9997 second argument: >
9998 GetErrorlist()->setqflist()
9999<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010000 Return type: |Number|
10001
10002
10003setreg({regname}, {value} [, {options}]) *setreg()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010004 Set the register {regname} to {value}.
10005 If {regname} is "" or "@", the unnamed register '"' is used.
10006 The {regname} argument is a string. In |Vim9-script|
10007 {regname} must be one character.
10008
10009 {value} may be any value returned by |getreg()| or
10010 |getreginfo()|, including a |List| or |Dict|.
10011 If {options} contains "a" or {regname} is upper case,
10012 then the value is appended.
10013
10014 {options} can also contain a register type specification:
10015 "c" or "v" |characterwise| mode
10016 "l" or "V" |linewise| mode
10017 "b" or "<CTRL-V>" |blockwise-visual| mode
10018 If a number immediately follows "b" or "<CTRL-V>" then this is
10019 used as the width of the selection - if it is not specified
10020 then the width of the block is set to the number of characters
10021 in the longest line (counting a <Tab> as 1 character).
10022
10023 If {options} contains no register settings, then the default
10024 is to use character mode unless {value} ends in a <NL> for
10025 string {value} and linewise mode for list {value}. Blockwise
10026 mode is never selected automatically.
10027 Returns zero for success, non-zero for failure.
10028
10029 *E883*
10030 Note: you may not use |List| containing more than one item to
10031 set search and expression registers. Lists containing no
10032 items act like empty strings.
10033
10034 Examples: >
10035 :call setreg(v:register, @*)
10036 :call setreg('*', @%, 'ac')
10037 :call setreg('a', "1\n2\n3", 'b5')
10038 :call setreg('"', { 'points_to': 'a'})
10039
10040< This example shows using the functions to save and restore a
10041 register: >
10042 :let var_a = getreginfo()
10043 :call setreg('a', var_a)
10044< or: >
10045 :let var_a = getreg('a', 1, 1)
10046 :let var_amode = getregtype('a')
10047 ....
10048 :call setreg('a', var_a, var_amode)
10049< Note: you may not reliably restore register value
10050 without using the third argument to |getreg()| as without it
10051 newlines are represented as newlines AND Nul bytes are
10052 represented as newlines as well, see |NL-used-for-Nul|.
10053
10054 You can also change the type of a register by appending
10055 nothing: >
10056 :call setreg('a', '', 'al')
10057
10058< Can also be used as a |method|, the base is passed as the
10059 second argument: >
10060 GetText()->setreg('a')
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010061<
10062 Return type: |Number|
10063
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010064
10065settabvar({tabnr}, {varname}, {val}) *settabvar()*
10066 Set tab-local variable {varname} to {val} in tab page {tabnr}.
10067 |t:var|
10068 The {varname} argument is a string.
10069 Note that autocommands are blocked, side effects may not be
10070 triggered, e.g. when setting 'filetype'.
10071 Note that the variable name without "t:" must be used.
10072 Tabs are numbered starting with one.
10073 This function is not available in the |sandbox|.
10074
10075 Can also be used as a |method|, the base is passed as the
10076 third argument: >
10077 GetValue()->settabvar(tab, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010078<
10079 Return type: |Number|
10080
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010081
10082settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
10083 Set option or local variable {varname} in window {winnr} to
10084 {val}.
10085 Tabs are numbered starting with one. For the current tabpage
10086 use |setwinvar()|.
10087 {winnr} can be the window number or the |window-ID|.
10088 When {winnr} is zero the current window is used.
10089 Note that autocommands are blocked, side effects may not be
10090 triggered, e.g. when setting 'filetype' or 'syntax'.
10091 This also works for a global or local buffer option, but it
10092 doesn't work for a global or local buffer variable.
10093 For a local buffer option the global value is unchanged.
10094 Note that the variable name without "w:" must be used.
10095 Examples: >
10096 :call settabwinvar(1, 1, "&list", 0)
10097 :call settabwinvar(3, 2, "myvar", "foobar")
10098< This function is not available in the |sandbox|.
10099
10100 Can also be used as a |method|, the base is passed as the
10101 fourth argument: >
10102 GetValue()->settabwinvar(tab, winnr, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010103<
10104 Return type: |Number|
10105
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010106
10107settagstack({nr}, {dict} [, {action}]) *settagstack()*
10108 Modify the tag stack of the window {nr} using {dict}.
10109 {nr} can be the window number or the |window-ID|.
10110
10111 For a list of supported items in {dict}, refer to
10112 |gettagstack()|. "curidx" takes effect before changing the tag
10113 stack.
10114 *E962*
10115 How the tag stack is modified depends on the {action}
10116 argument:
10117 - If {action} is not present or is set to 'r', then the tag
10118 stack is replaced.
10119 - If {action} is set to 'a', then new entries from {dict} are
10120 pushed (added) onto the tag stack.
10121 - If {action} is set to 't', then all the entries from the
10122 current entry in the tag stack or "curidx" in {dict} are
10123 removed and then new entries are pushed to the stack.
10124
10125 The current index is set to one after the length of the tag
10126 stack after the modification.
10127
10128 Returns zero for success, -1 for failure.
10129
10130 Examples (for more examples see |tagstack-examples|):
10131 Empty the tag stack of window 3: >
10132 call settagstack(3, {'items' : []})
10133
10134< Save and restore the tag stack: >
10135 let stack = gettagstack(1003)
10136 " do something else
10137 call settagstack(1003, stack)
10138 unlet stack
10139<
10140 Can also be used as a |method|, the base is passed as the
10141 second argument: >
10142 GetStack()->settagstack(winnr)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010143<
10144 Return type: |Number|
10145
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010146
10147setwinvar({winnr}, {varname}, {val}) *setwinvar()*
10148 Like |settabwinvar()| for the current tab page.
10149 Examples: >
10150 :call setwinvar(1, "&list", 0)
10151 :call setwinvar(2, "myvar", "foobar")
10152
10153< Can also be used as a |method|, the base is passed as the
10154 third argument: >
10155 GetValue()->setwinvar(winnr, name)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010156<
10157 Return type: |Number|
10158
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010159
10160sha256({string}) *sha256()*
10161 Returns a String with 64 hex characters, which is the SHA256
10162 checksum of {string}.
10163
10164 Can also be used as a |method|: >
10165 GetText()->sha256()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010166<
10167 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010168
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010169 {only available when compiled with the |+cryptv| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010170
10171shellescape({string} [, {special}]) *shellescape()*
10172 Escape {string} for use as a shell command argument.
10173 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +000010174 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010175 in single quotes and will double up all internal single
10176 quotes.
10177 On MS-Windows, when 'shellslash' is not set, it will enclose
10178 {string} in double quotes and double all double quotes within
10179 {string}.
10180 Otherwise it will enclose {string} in single quotes and
10181 replace all "'" with "'\''".
10182
Enno5faeb602024-05-15 21:54:19 +020010183 The {special} argument adds additional escaping of keywords
10184 used in Vim commands. When it is not omitted and a non-zero
K.Takatac0e038b2024-05-16 12:39:01 +090010185 number or a non-empty String (|non-zero-arg|), then special
10186 items such as "!", "%", "#" and "<cword>" (as listed in
10187 |expand()|) will be preceded by a backslash.
Enno5faeb602024-05-15 21:54:19 +020010188 This backslash will be removed again by the |:!| command.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010189
10190 The "!" character will be escaped (again with a |non-zero-arg|
10191 {special}) when 'shell' contains "csh" in the tail. That is
10192 because for csh and tcsh "!" is used for history replacement
10193 even when inside single quotes.
10194
10195 With a |non-zero-arg| {special} the <NL> character is also
10196 escaped. When 'shell' containing "csh" in the tail it's
10197 escaped a second time.
10198
10199 The "\" character will be escaped when 'shell' contains "fish"
10200 in the tail. That is because for fish "\" is used as an escape
10201 character inside single quotes.
10202
10203 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010204 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010205< This results in a directory listing for the file under the
10206 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010207 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010208< See also |::S|.
10209
10210 Can also be used as a |method|: >
10211 GetCommand()->shellescape()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010212<
10213 Return type: |String|
10214
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010215
10216shiftwidth([{col}]) *shiftwidth()*
10217 Returns the effective value of 'shiftwidth'. This is the
10218 'shiftwidth' value unless it is zero, in which case it is the
10219 'tabstop' value. This function was introduced with patch
10220 7.3.694 in 2012, everybody should have it by now (however it
10221 did not allow for the optional {col} argument until 8.1.542).
10222
10223 When there is one argument {col} this is used as column number
10224 for which to return the 'shiftwidth' value. This matters for the
10225 'vartabstop' feature. If the 'vartabstop' setting is enabled and
10226 no {col} argument is given, column 1 will be assumed.
10227
10228 Can also be used as a |method|: >
10229 GetColumn()->shiftwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010230<
10231 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010232
10233sign_ functions are documented here: |sign-functions-details|
10234
10235
10236simplify({filename}) *simplify()*
10237 Simplify the file name as much as possible without changing
10238 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
10239 Unix) are not resolved. If the first path component in
10240 {filename} designates the current directory, this will be
10241 valid for the result as well. A trailing path separator is
10242 not removed either. On Unix "//path" is unchanged, but
10243 "///path" is simplified to "/path" (this follows the Posix
10244 standard).
10245 Example: >
10246 simplify("./dir/.././/file/") == "./file/"
10247< Note: The combination "dir/.." is only removed if "dir" is
10248 a searchable directory or does not exist. On Unix, it is also
10249 removed when "dir" is a symbolic link within the same
10250 directory. In order to resolve all the involved symbolic
10251 links before simplifying the path name, use |resolve()|.
10252
10253 Can also be used as a |method|: >
10254 GetName()->simplify()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010255<
10256 Return type: |String|
10257
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010258
10259sin({expr}) *sin()*
10260 Return the sine of {expr}, measured in radians, as a |Float|.
10261 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010262 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010263 Examples: >
10264 :echo sin(100)
10265< -0.506366 >
10266 :echo sin(-4.01)
10267< 0.763301
10268
10269 Can also be used as a |method|: >
10270 Compute()->sin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010271<
10272 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010273
10274
10275sinh({expr}) *sinh()*
10276 Return the hyperbolic sine of {expr} as a |Float| in the range
10277 [-inf, inf].
10278 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010279 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010280 Examples: >
10281 :echo sinh(0.5)
10282< 0.521095 >
10283 :echo sinh(-0.9)
10284< -1.026517
10285
10286 Can also be used as a |method|: >
10287 Compute()->sinh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010288<
10289 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010290
10291
10292slice({expr}, {start} [, {end}]) *slice()*
10293 Similar to using a |slice| "expr[start : end]", but "end" is
10294 used exclusive. And for a string the indexes are used as
10295 character indexes instead of byte indexes, like in
zeertzjqad387692024-03-23 08:23:48 +010010296 |vim9script|. Also, composing characters are treated as a
10297 part of the preceding base character.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010298 When {end} is omitted the slice continues to the last item.
10299 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010300 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010301
10302 Can also be used as a |method|: >
10303 GetList()->slice(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010304<
10305 Return type: list<{type}>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010306
10307
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010308sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010309 Sort the items in {list} in-place. Returns {list}.
10310
10311 If you want a list to remain unmodified make a copy first: >
10312 :let sortedlist = sort(copy(mylist))
10313
Bram Moolenaar2d8ed022022-05-21 13:08:16 +010010314< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010315 string representation of each item to sort on. Numbers sort
10316 after Strings, |Lists| after Numbers. For sorting text in the
10317 current buffer use |:sort|.
10318
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010319 When {how} is given and it is 'i' then case is ignored.
10320 In legacy script, for backwards compatibility, the value one
10321 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010322
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010323 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010324 locale is used for ordering. Implementation details: strcoll()
10325 is used to compare strings. See |:language| check or set the
10326 collation locale. |v:collate| can also be used to check the
10327 current locale. Sorting using the locale typically ignores
10328 case. Example: >
10329 " ö is sorted similarly to o with English locale.
10330 :language collate en_US.UTF8
10331 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10332< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
10333>
10334 " ö is sorted after z with Swedish locale.
10335 :language collate sv_SE.UTF8
10336 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10337< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
10338 This does not work properly on Mac.
10339
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010340 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010341 sorted numerical (Implementation detail: this uses the
Bram Moolenaarbe19d782023-03-09 22:06:49 +000010342 strtod() function to parse numbers. Strings, Lists, Dicts and
10343 Funcrefs will be considered as being 0). Note that this won't
10344 sort a list of strings with numbers!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010345
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010346 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010347 sorted numerical. This is like 'n' but a string containing
10348 digits will be used as the number they represent.
10349
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010350 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010351 sorted numerical. All values must be a Number or a Float.
10352
Bram Moolenaar2007dd42022-02-23 13:17:47 +000010353 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010354 is called to compare items. The function is invoked with two
10355 items as argument and must return zero if they are equal, 1 or
10356 bigger if the first one sorts after the second one, -1 or
10357 smaller if the first one sorts before the second one.
10358
10359 {dict} is for functions with the "dict" attribute. It will be
10360 used to set the local variable "self". |Dictionary-function|
10361
10362 The sort is stable, items which compare equal (as number or as
10363 string) will keep their relative position. E.g., when sorting
10364 on numbers, text strings will sort next to each other, in the
10365 same order as they were originally.
10366
10367 Can also be used as a |method|: >
10368 mylist->sort()
10369
10370< Also see |uniq()|.
10371
10372 Example: >
10373 func MyCompare(i1, i2)
10374 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
10375 endfunc
10376 eval mylist->sort("MyCompare")
10377< A shorter compare version for this specific simple case, which
10378 ignores overflow: >
10379 func MyCompare(i1, i2)
10380 return a:i1 - a:i2
10381 endfunc
10382< For a simple expression you can use a lambda: >
10383 eval mylist->sort({i1, i2 -> i1 - i2})
10384<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010385 Return type: list<{type}>
10386
10387
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010388sound_clear() *sound_clear()*
10389 Stop playing all sounds.
10390
10391 On some Linux systems you may need the libcanberra-pulse
10392 package, otherwise sound may not stop.
10393
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010394 Return type: |Number|
10395
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010396 {only available when compiled with the |+sound| feature}
10397
10398 *sound_playevent()*
10399sound_playevent({name} [, {callback}])
10400 Play a sound identified by {name}. Which event names are
10401 supported depends on the system. Often the XDG sound names
10402 are used. On Ubuntu they may be found in
10403 /usr/share/sounds/freedesktop/stereo. Example: >
10404 call sound_playevent('bell')
10405< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
10406 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
10407 SystemStart, SystemWelcome, etc.
Yee Cheng Chin4314e4f2022-10-08 13:50:05 +010010408 On macOS, {name} refers to files located in
10409 /System/Library/Sounds (e.g. "Tink"). It will also work for
10410 custom installed sounds in folders like ~/Library/Sounds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010411
10412 When {callback} is specified it is invoked when the sound is
10413 finished. The first argument is the sound ID, the second
10414 argument is the status:
10415 0 sound was played to the end
10416 1 sound was interrupted
10417 2 error occurred after sound started
10418 Example: >
10419 func Callback(id, status)
10420 echomsg "sound " .. a:id .. " finished with " .. a:status
10421 endfunc
10422 call sound_playevent('bell', 'Callback')
10423
10424< MS-Windows: {callback} doesn't work for this function.
10425
10426 Returns the sound ID, which can be passed to `sound_stop()`.
10427 Returns zero if the sound could not be played.
10428
10429 Can also be used as a |method|: >
10430 GetSoundName()->sound_playevent()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010431<
10432 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010433
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010434 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010435
10436 *sound_playfile()*
10437sound_playfile({path} [, {callback}])
10438 Like `sound_playevent()` but play sound file {path}. {path}
10439 must be a full path. On Ubuntu you may find files to play
10440 with this command: >
10441 :!find /usr/share/sounds -type f | grep -v index.theme
10442
10443< Can also be used as a |method|: >
10444 GetSoundPath()->sound_playfile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010445<
10446 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010447
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010448 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010449
10450
10451sound_stop({id}) *sound_stop()*
10452 Stop playing sound {id}. {id} must be previously returned by
10453 `sound_playevent()` or `sound_playfile()`.
10454
10455 On some Linux systems you may need the libcanberra-pulse
10456 package, otherwise sound may not stop.
10457
10458 On MS-Windows, this does not work for event sound started by
10459 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
10460
10461 Can also be used as a |method|: >
10462 soundid->sound_stop()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010463<
10464 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010465
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010466 {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010467
10468 *soundfold()*
10469soundfold({word})
10470 Return the sound-folded equivalent of {word}. Uses the first
10471 language in 'spelllang' for the current window that supports
10472 soundfolding. 'spell' must be set. When no sound folding is
10473 possible the {word} is returned unmodified.
10474 This can be used for making spelling suggestions. Note that
10475 the method can be quite slow.
10476
10477 Can also be used as a |method|: >
10478 GetWord()->soundfold()
10479<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010480 Return type: |String|
10481
10482
10483spellbadword([{sentence}]) *spellbadword()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010484 Without argument: The result is the badly spelled word under
10485 or after the cursor. The cursor is moved to the start of the
10486 bad word. When no bad word is found in the cursor line the
10487 result is an empty string and the cursor doesn't move.
10488
10489 With argument: The result is the first word in {sentence} that
10490 is badly spelled. If there are no spelling mistakes the
10491 result is an empty string.
10492
10493 The return value is a list with two items:
10494 - The badly spelled word or an empty string.
10495 - The type of the spelling error:
10496 "bad" spelling mistake
10497 "rare" rare word
10498 "local" word only valid in another region
10499 "caps" word should start with Capital
10500 Example: >
10501 echo spellbadword("the quik brown fox")
10502< ['quik', 'bad'] ~
10503
10504 The spelling information for the current window and the value
10505 of 'spelllang' are used.
10506
10507 Can also be used as a |method|: >
10508 GetText()->spellbadword()
10509<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010510 Return type: list<string>
10511
10512
10513spellsuggest({word} [, {max} [, {capital}]]) *spellsuggest()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010514 Return a |List| with spelling suggestions to replace {word}.
10515 When {max} is given up to this number of suggestions are
10516 returned. Otherwise up to 25 suggestions are returned.
10517
10518 When the {capital} argument is given and it's non-zero only
10519 suggestions with a leading capital will be given. Use this
10520 after a match with 'spellcapcheck'.
10521
10522 {word} can be a badly spelled word followed by other text.
10523 This allows for joining two words that were split. The
10524 suggestions also include the following text, thus you can
10525 replace a line.
10526
10527 {word} may also be a good word. Similar words will then be
10528 returned. {word} itself is not included in the suggestions,
10529 although it may appear capitalized.
10530
10531 The spelling information for the current window is used. The
10532 values of 'spelllang' and 'spellsuggest' are used.
10533
10534 Can also be used as a |method|: >
10535 GetWord()->spellsuggest()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010536<
10537 Return type: list<string> or list<any>
10538
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010539
10540split({string} [, {pattern} [, {keepempty}]]) *split()*
10541 Make a |List| out of {string}. When {pattern} is omitted or
Shane Harperc1b39842024-07-17 19:40:40 +020010542 empty each white space separated sequence of characters
10543 becomes an item.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010544 Otherwise the string is split where {pattern} matches,
10545 removing the matched characters. 'ignorecase' is not used
10546 here, add \c to ignore case. |/\c|
10547 When the first or last item is empty it is omitted, unless the
10548 {keepempty} argument is given and it's non-zero.
10549 Other empty items are kept when {pattern} matches at least one
10550 character or when {keepempty} is non-zero.
10551 Example: >
10552 :let words = split(getline('.'), '\W\+')
10553< To split a string in individual characters: >
10554 :for c in split(mystring, '\zs')
10555< If you want to keep the separator you can also use '\zs' at
10556 the end of the pattern: >
10557 :echo split('abc:def:ghi', ':\zs')
10558< ['abc:', 'def:', 'ghi'] ~
10559 Splitting a table where the first element can be empty: >
10560 :let items = split(line, ':', 1)
10561< The opposite function is |join()|.
10562
10563 Can also be used as a |method|: >
10564 GetString()->split()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010565<
10566 Return type: list<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010567
10568sqrt({expr}) *sqrt()*
10569 Return the non-negative square root of Float {expr} as a
10570 |Float|.
10571 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010572 is negative the result is NaN (Not a Number). Returns 0.0 if
10573 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010574 Examples: >
10575 :echo sqrt(100)
10576< 10.0 >
10577 :echo sqrt(-4.01)
10578< nan
10579 "nan" may be different, it depends on system libraries.
10580
10581 Can also be used as a |method|: >
10582 Compute()->sqrt()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010583<
10584 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010585
10586
10587srand([{expr}]) *srand()*
10588 Initialize seed used by |rand()|:
10589 - If {expr} is not given, seed values are initialized by
10590 reading from /dev/urandom, if possible, or using time(NULL)
10591 a.k.a. epoch time otherwise; this only has second accuracy.
10592 - If {expr} is given it must be a Number. It is used to
10593 initialize the seed values. This is useful for testing or
10594 when a predictable sequence is intended.
10595
10596 Examples: >
10597 :let seed = srand()
10598 :let seed = srand(userinput)
10599 :echo rand(seed)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010600<
10601 Return type: list<number>
10602
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010603
10604state([{what}]) *state()*
10605 Return a string which contains characters indicating the
10606 current state. Mostly useful in callbacks that want to do
10607 work that may not always be safe. Roughly this works like:
10608 - callback uses state() to check if work is safe to do.
10609 Yes: then do it right away.
10610 No: add to work queue and add a |SafeState| and/or
10611 |SafeStateAgain| autocommand (|SafeState| triggers at
10612 toplevel, |SafeStateAgain| triggers after handling
10613 messages and callbacks).
10614 - When SafeState or SafeStateAgain is triggered and executes
10615 your autocommand, check with `state()` if the work can be
10616 done now, and if yes remove it from the queue and execute.
10617 Remove the autocommand if the queue is now empty.
10618 Also see |mode()|.
10619
10620 When {what} is given only characters in this string will be
10621 added. E.g, this checks if the screen has scrolled: >
10622 if state('s') == ''
10623 " screen has not scrolled
10624<
10625 These characters indicate the state, generally indicating that
10626 something is busy:
10627 m halfway a mapping, :normal command, feedkeys() or
10628 stuffed command
10629 o operator pending, e.g. after |d|
10630 a Insert mode autocomplete active
10631 x executing an autocommand
10632 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
10633 ch_readraw() when reading json
10634 S not triggering SafeState or SafeStateAgain, e.g. after
10635 |f| or a count
10636 c callback invoked, including timer (repeats for
10637 recursiveness up to "ccc")
10638 s screen has scrolled for messages
10639
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010640 Return type: |String|
10641
10642
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010643str2blob({list} [, {options}]) *str2blob()*
10644 Return a Blob by converting the characters in the List of
10645 strings in {list} into bytes.
10646
10647 A <NL> byte is added to the blob after each list item. A
10648 newline character in the string is translated into a <NUL>
10649 byte in the blob.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010650
10651 If {options} is not supplied, the current 'encoding' value is
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010652 used to convert the characters into bytes.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010653
10654 The argument {options} is a |Dict| and supports the following
10655 items:
Bakudankunb3854bf2025-02-23 20:29:21 +010010656 encoding Convert the characters using this encoding
10657 before making the Blob.
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010658 The value is a |String|. See |encoding-names|
10659 for the supported values.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010660
10661 An error is given and an empty blob is returned if the
10662 character encoding fails.
10663
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010664 Returns an empty Blob if {list} is empty.
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010665
10666 See also |blob2str()|
10667
10668 Examples: >
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010669 str2blob(["ab"]) returns 0z6162
10670 str2blob(["«»"]) returns 0zC2ABC2BB
10671 str2blob(["a\nb"]) returns 0z610A62
10672 str2blob(readfile('myfile.txt'))
10673 str2blob(["«»"], {'encoding': 'latin1'}) returns 0zABBB
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010674<
10675 Can also be used as a |method|: >
Yegappan Lakshmanana11b23c2025-01-16 19:16:42 +010010676 GetListOfStrings()->str2blob()
Yegappan Lakshmanan1aefe1d2025-01-14 17:29:42 +010010677<
10678 Return type: |Blob|
10679
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010680str2float({string} [, {quoted}]) *str2float()*
10681 Convert String {string} to a Float. This mostly works the
10682 same as when using a floating point number in an expression,
10683 see |floating-point-format|. But it's a bit more permissive.
10684 E.g., "1e40" is accepted, while in an expression you need to
10685 write "1.0e40". The hexadecimal form "0x123" is also
10686 accepted, but not others, like binary or octal.
10687 When {quoted} is present and non-zero then embedded single
10688 quotes before the dot are ignored, thus "1'000.0" is a
10689 thousand.
10690 Text after the number is silently ignored.
10691 The decimal point is always '.', no matter what the locale is
10692 set to. A comma ends the number: "12,345.67" is converted to
10693 12.0. You can strip out thousands separators with
10694 |substitute()|: >
10695 let f = str2float(substitute(text, ',', '', 'g'))
10696<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010697 Returns 0.0 if the conversion fails.
10698
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010699 Can also be used as a |method|: >
10700 let f = text->substitute(',', '', 'g')->str2float()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010701<
10702 Return type: |Float|
10703
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010704
10705str2list({string} [, {utf8}]) *str2list()*
10706 Return a list containing the number values which represent
10707 each character in String {string}. Examples: >
10708 str2list(" ") returns [32]
10709 str2list("ABC") returns [65, 66, 67]
10710< |list2str()| does the opposite.
10711
10712 When {utf8} is omitted or zero, the current 'encoding' is used.
10713 When {utf8} is TRUE, always treat the String as UTF-8
10714 characters. With UTF-8 composing characters are handled
10715 properly: >
10716 str2list("á") returns [97, 769]
10717
10718< Can also be used as a |method|: >
10719 GetString()->str2list()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010720<
10721 Return type: list<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010722
10723
10724str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
10725 Convert string {string} to a number.
10726 {base} is the conversion base, it can be 2, 8, 10 or 16.
10727 When {quoted} is present and non-zero then embedded single
10728 quotes are ignored, thus "1'000'000" is a million.
10729
10730 When {base} is omitted base 10 is used. This also means that
10731 a leading zero doesn't cause octal conversion to be used, as
10732 with the default String to Number conversion. Example: >
10733 let nr = str2nr('0123')
10734<
10735 When {base} is 16 a leading "0x" or "0X" is ignored. With a
10736 different base the result will be zero. Similarly, when
10737 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
10738 {base} is 2 a leading "0b" or "0B" is ignored.
10739 Text after the number is silently ignored.
10740
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010741 Returns 0 if {string} is empty or on error.
10742
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010743 Can also be used as a |method|: >
10744 GetText()->str2nr()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010745<
10746 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010747
10748
10749strcharlen({string}) *strcharlen()*
10750 The result is a Number, which is the number of characters
10751 in String {string}. Composing characters are ignored.
10752 |strchars()| can count the number of characters, counting
10753 composing characters separately.
10754
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +010010755 Returns 0 if {string} is empty or on error.
10756
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010757 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10758
10759 Can also be used as a |method|: >
10760 GetText()->strcharlen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010761<
10762 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010763
10764
10765strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
10766 Like |strpart()| but using character index and length instead
10767 of byte index and length.
10768 When {skipcc} is omitted or zero, composing characters are
10769 counted separately.
zeertzjqad387692024-03-23 08:23:48 +010010770 When {skipcc} set to 1, composing characters are treated as a
10771 part of the preceding base character, similar to |slice()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010772 When a character index is used where a character does not
10773 exist it is omitted and counted as one character. For
10774 example: >
10775 strcharpart('abc', -1, 2)
10776< results in 'a'.
10777
Bram Moolenaard592deb2022-06-17 15:42:40 +010010778 Returns an empty string on error.
10779
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010780 Can also be used as a |method|: >
10781 GetText()->strcharpart(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010782<
10783 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010784
10785
10786strchars({string} [, {skipcc}]) *strchars()*
10787 The result is a Number, which is the number of characters
10788 in String {string}.
10789 When {skipcc} is omitted or zero, composing characters are
10790 counted separately.
zeertzjqad387692024-03-23 08:23:48 +010010791 When {skipcc} set to 1, composing characters are ignored.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010792 |strcharlen()| always does this.
10793
Bram Moolenaard592deb2022-06-17 15:42:40 +010010794 Returns zero on error.
10795
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010796 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10797
10798 {skipcc} is only available after 7.4.755. For backward
10799 compatibility, you can define a wrapper function: >
10800 if has("patch-7.4.755")
10801 function s:strchars(str, skipcc)
10802 return strchars(a:str, a:skipcc)
10803 endfunction
10804 else
10805 function s:strchars(str, skipcc)
10806 if a:skipcc
10807 return strlen(substitute(a:str, ".", "x", "g"))
10808 else
10809 return strchars(a:str)
10810 endif
10811 endfunction
10812 endif
10813<
10814 Can also be used as a |method|: >
10815 GetText()->strchars()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010816<
10817 Return type: |Number|
10818
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010819
10820strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
10821 The result is a Number, which is the number of display cells
10822 String {string} occupies on the screen when it starts at {col}
10823 (first column is zero). When {col} is omitted zero is used.
10824 Otherwise it is the screen column where to start. This
10825 matters for Tab characters.
10826 The option settings of the current window are used. This
10827 matters for anything that's displayed differently, such as
10828 'tabstop' and 'display'.
10829 When {string} contains characters with East Asian Width Class
10830 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010831 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010832 Also see |strlen()|, |strwidth()| and |strchars()|.
10833
10834 Can also be used as a |method|: >
10835 GetText()->strdisplaywidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010836<
10837 Return type: |Number|
10838
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010839
10840strftime({format} [, {time}]) *strftime()*
10841 The result is a String, which is a formatted date and time, as
10842 specified by the {format} string. The given {time} is used,
10843 or the current time if no time is given. The accepted
10844 {format} depends on your system, thus this is not portable!
10845 See the manual page of the C function strftime() for the
10846 format. The maximum length of the result is 80 characters.
10847 See also |localtime()|, |getftime()| and |strptime()|.
10848 The language can be changed with the |:language| command.
10849 Examples: >
10850 :echo strftime("%c") Sun Apr 27 11:49:23 1997
10851 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
10852 :echo strftime("%y%m%d %T") 970427 11:53:55
10853 :echo strftime("%H:%M") 11:55
10854 :echo strftime("%c", getftime("file.c"))
10855 Show mod time of file.c.
10856< Not available on all systems. To check use: >
10857 :if exists("*strftime")
10858
10859< Can also be used as a |method|: >
10860 GetFormat()->strftime()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010861<
10862 Return type: |String|
10863
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010864
10865strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +010010866 Get a Number corresponding to the character at {index} in
10867 {str}. This uses a zero-based character index, not a byte
10868 index. Composing characters are considered separate
10869 characters here. Use |nr2char()| to convert the Number to a
10870 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010871 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010872 Also see |strcharpart()| and |strchars()|.
10873
10874 Can also be used as a |method|: >
10875 GetText()->strgetchar(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010876<
10877 Return type: |Number|
10878
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010879
10880stridx({haystack}, {needle} [, {start}]) *stridx()*
10881 The result is a Number, which gives the byte index in
10882 {haystack} of the first occurrence of the String {needle}.
10883 If {start} is specified, the search starts at index {start}.
10884 This can be used to find a second match: >
10885 :let colon1 = stridx(line, ":")
10886 :let colon2 = stridx(line, ":", colon1 + 1)
10887< The search is done case-sensitive.
10888 For pattern searches use |match()|.
10889 -1 is returned if the {needle} does not occur in {haystack}.
10890 See also |strridx()|.
10891 Examples: >
10892 :echo stridx("An Example", "Example") 3
10893 :echo stridx("Starting point", "Start") 0
10894 :echo stridx("Starting point", "start") -1
10895< *strstr()* *strchr()*
10896 stridx() works similar to the C function strstr(). When used
10897 with a single character it works similar to strchr().
10898
10899 Can also be used as a |method|: >
10900 GetHaystack()->stridx(needle)
10901<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010902 Return type: |Number|
10903
10904
10905string({expr}) *string()*
10906 Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010907 Float, String, Blob or a composition of them, then the result
10908 can be parsed back with |eval()|.
10909 {expr} type result ~
10910 String 'string' (single quotes are doubled)
10911 Number 123
10912 Float 123.123456 or 1.123456e8
10913 Funcref function('name')
10914 Blob 0z00112233.44556677.8899
10915 List [item, item]
10916 Dictionary {key: value, key: value}
Bram Moolenaarf1dcd142022-12-31 15:30:45 +000010917 Class class SomeName
10918 Object object of SomeName {lnum: 1, col: 3}
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010010919 Enum enum EnumName
Yegappan Lakshmanan3cf121e2024-03-31 18:45:35 +020010920 EnumValue enum name.value {name: str, ordinal: nr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010921
10922 When a |List| or |Dictionary| has a recursive reference it is
10923 replaced by "[...]" or "{...}". Using eval() on the result
10924 will then fail.
10925
mityu7f0bba22024-03-29 10:14:41 +010010926 For an object, invokes the string() method to get a textual
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +010010927 representation of the object. If the method is not present,
mityu7f0bba22024-03-29 10:14:41 +010010928 then the default representation is used. |object-string()|
Yegappan Lakshmanand3eae7b2024-03-03 16:26:58 +010010929
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010930 Can also be used as a |method|: >
10931 mylist->string()
10932
10933< Also see |strtrans()|.
10934
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010935 Return type: |String|
10936
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010937
10938strlen({string}) *strlen()*
10939 The result is a Number, which is the length of the String
10940 {string} in bytes.
10941 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010942 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010943 If you want to count the number of multibyte characters use
10944 |strchars()|.
10945 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
10946
10947 Can also be used as a |method|: >
10948 GetString()->strlen()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010949<
10950 Return type: |Number|
10951
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010952
10953strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
10954 The result is a String, which is part of {src}, starting from
10955 byte {start}, with the byte length {len}.
10956 When {chars} is present and TRUE then {len} is the number of
10957 characters positions (composing characters are not counted
10958 separately, thus "1" means one base character and any
10959 following composing characters).
10960 To count {start} as characters instead of bytes use
10961 |strcharpart()|.
10962
10963 When bytes are selected which do not exist, this doesn't
10964 result in an error, the bytes are simply omitted.
10965 If {len} is missing, the copy continues from {start} till the
10966 end of the {src}. >
10967 strpart("abcdefg", 3, 2) == "de"
10968 strpart("abcdefg", -2, 4) == "ab"
10969 strpart("abcdefg", 5, 4) == "fg"
10970 strpart("abcdefg", 3) == "defg"
10971
10972< Note: To get the first character, {start} must be 0. For
10973 example, to get the character under the cursor: >
10974 strpart(getline("."), col(".") - 1, 1, v:true)
10975<
Bram Moolenaard592deb2022-06-17 15:42:40 +010010976 Returns an empty string on error.
10977
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010978 Can also be used as a |method|: >
10979 GetText()->strpart(5)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020010980<
10981 Return type: |String|
10982
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010983
10984strptime({format}, {timestring}) *strptime()*
10985 The result is a Number, which is a unix timestamp representing
10986 the date and time in {timestring}, which is expected to match
10987 the format specified in {format}.
10988
10989 The accepted {format} depends on your system, thus this is not
10990 portable! See the manual page of the C function strptime()
10991 for the format. Especially avoid "%c". The value of $TZ also
10992 matters.
10993
10994 If the {timestring} cannot be parsed with {format} zero is
10995 returned. If you do not know the format of {timestring} you
10996 can try different {format} values until you get a non-zero
10997 result.
10998
10999 See also |strftime()|.
11000 Examples: >
11001 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
11002< 862156163 >
11003 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
11004< Sun Apr 27 11:53:55 1997 >
11005 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
11006< Sun Apr 27 12:53:55 1997
11007
11008 Can also be used as a |method|: >
11009 GetFormat()->strptime(timestring)
11010<
11011 Not available on all systems. To check use: >
11012 :if exists("*strptime")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011013<
11014 Return type: |Number|
11015
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011016
11017strridx({haystack}, {needle} [, {start}]) *strridx()*
11018 The result is a Number, which gives the byte index in
11019 {haystack} of the last occurrence of the String {needle}.
11020 When {start} is specified, matches beyond this index are
11021 ignored. This can be used to find a match before a previous
11022 match: >
11023 :let lastcomma = strridx(line, ",")
11024 :let comma2 = strridx(line, ",", lastcomma - 1)
11025< The search is done case-sensitive.
11026 For pattern searches use |match()|.
11027 -1 is returned if the {needle} does not occur in {haystack}.
11028 If the {needle} is empty the length of {haystack} is returned.
11029 See also |stridx()|. Examples: >
11030 :echo strridx("an angry armadillo", "an") 3
11031< *strrchr()*
11032 When used with a single character it works similar to the C
11033 function strrchr().
11034
11035 Can also be used as a |method|: >
11036 GetHaystack()->strridx(needle)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011037<
11038 Return type: |Number|
11039
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011040
11041strtrans({string}) *strtrans()*
11042 The result is a String, which is {string} with all unprintable
11043 characters translated into printable characters |'isprint'|.
11044 Like they are shown in a window. Example: >
11045 echo strtrans(@a)
11046< This displays a newline in register a as "^@" instead of
11047 starting a new line.
11048
Bram Moolenaard592deb2022-06-17 15:42:40 +010011049 Returns an empty string on error.
11050
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011051 Can also be used as a |method|: >
11052 GetString()->strtrans()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011053<
11054 Return type: |String|
11055
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011056
Christian Brabandt67672ef2023-04-24 21:09:54 +010011057strutf16len({string} [, {countcc}]) *strutf16len()*
11058 The result is a Number, which is the number of UTF-16 code
11059 units in String {string} (after converting it to UTF-16).
11060
11061 When {countcc} is TRUE, composing characters are counted
11062 separately.
11063 When {countcc} is omitted or FALSE, composing characters are
11064 ignored.
11065
11066 Returns zero on error.
11067
11068 Also see |strlen()| and |strcharlen()|.
11069 Examples: >
11070 echo strutf16len('a') returns 1
11071 echo strutf16len('©') returns 1
11072 echo strutf16len('😊') returns 2
11073 echo strutf16len('ą́') returns 1
11074 echo strutf16len('ą́', v:true) returns 3
a5ob7r790f9a82023-09-25 06:05:47 +090011075<
Christian Brabandt67672ef2023-04-24 21:09:54 +010011076 Can also be used as a |method|: >
11077 GetText()->strutf16len()
11078<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011079 Return type: |Number|
11080
11081
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011082strwidth({string}) *strwidth()*
11083 The result is a Number, which is the number of display cells
11084 String {string} occupies. A Tab character is counted as one
11085 cell, alternatively use |strdisplaywidth()|.
11086 When {string} contains characters with East Asian Width Class
11087 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011088 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011089 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
11090
11091 Can also be used as a |method|: >
11092 GetString()->strwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011093<
11094 Return type: |Number|
11095
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011096
11097submatch({nr} [, {list}]) *submatch()* *E935*
11098 Only for an expression in a |:substitute| command or
11099 substitute() function.
11100 Returns the {nr}'th submatch of the matched text. When {nr}
11101 is 0 the whole matched text is returned.
11102 Note that a NL in the string can stand for a line break of a
11103 multi-line match or a NUL character in the text.
11104 Also see |sub-replace-expression|.
11105
11106 If {list} is present and non-zero then submatch() returns
11107 a list of strings, similar to |getline()| with two arguments.
11108 NL characters in the text represent NUL characters in the
11109 text.
11110 Only returns more than one item for |:substitute|, inside
11111 |substitute()| this list will always contain one or zero
11112 items, since there are no real line breaks.
11113
11114 When substitute() is used recursively only the submatches in
11115 the current (deepest) call can be obtained.
11116
Bram Moolenaard592deb2022-06-17 15:42:40 +010011117 Returns an empty string or list on error.
11118
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011119 Examples: >
11120 :s/\d\+/\=submatch(0) + 1/
11121 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
11122< This finds the first number in the line and adds one to it.
11123 A line break is included as a newline character.
11124
11125 Can also be used as a |method|: >
11126 GetNr()->submatch()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011127<
11128 Return type: |String| or list<string> depending on {list}
11129
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011130
11131substitute({string}, {pat}, {sub}, {flags}) *substitute()*
11132 The result is a String, which is a copy of {string}, in which
11133 the first match of {pat} is replaced with {sub}.
11134 When {flags} is "g", all matches of {pat} in {string} are
11135 replaced. Otherwise {flags} should be "".
11136
11137 This works like the ":substitute" command (without any flags).
11138 But the matching with {pat} is always done like the 'magic'
11139 option is set and 'cpoptions' is empty (to make scripts
11140 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
11141 if you want to ignore or match case and ignore 'ignorecase'.
11142 'smartcase' is not used. See |string-match| for how {pat} is
11143 used.
11144
11145 A "~" in {sub} is not replaced with the previous {sub}.
11146 Note that some codes in {sub} have a special meaning
11147 |sub-replace-special|. For example, to replace something with
11148 "\n" (two characters), use "\\\\n" or '\\n'.
11149
11150 When {pat} does not match in {string}, {string} is returned
11151 unmodified.
11152
11153 Example: >
11154 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
11155< This removes the last component of the 'path' option. >
11156 :echo substitute("testing", ".*", "\\U\\0", "")
11157< results in "TESTING".
11158
11159 When {sub} starts with "\=", the remainder is interpreted as
11160 an expression. See |sub-replace-expression|. Example: >
11161 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011162 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011163
11164< When {sub} is a Funcref that function is called, with one
11165 optional argument. Example: >
11166 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
11167< The optional argument is a list which contains the whole
11168 matched string and up to nine submatches, like what
11169 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011170 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011171
Bram Moolenaard592deb2022-06-17 15:42:40 +010011172< Returns an empty string on error.
11173
11174 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011175 GetString()->substitute(pat, sub, flags)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011176<
11177 Return type: |String|
11178
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011179
Bram Moolenaarc216a7a2022-12-05 13:50:55 +000011180swapfilelist() *swapfilelist()*
11181 Returns a list of swap file names, like what "vim -r" shows.
11182 See the |-r| command argument. The 'directory' option is used
11183 for the directories to inspect. If you only want to get a
11184 list of swap files in the current directory then temporarily
11185 set 'directory' to a dot: >
11186 let save_dir = &directory
11187 let &directory = '.'
11188 let swapfiles = swapfilelist()
11189 let &directory = save_dir
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011190<
11191 Return type: list<string>
11192
Bram Moolenaarc216a7a2022-12-05 13:50:55 +000011193
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011194swapinfo({fname}) *swapinfo()*
11195 The result is a dictionary, which holds information about the
11196 swapfile {fname}. The available fields are:
11197 version Vim version
11198 user user name
11199 host host name
11200 fname original file name
11201 pid PID of the Vim process that created the swap
11202 file
11203 mtime last modification time in seconds
11204 inode Optional: INODE number of the file
11205 dirty 1 if file was modified, 0 if not
11206 Note that "user" and "host" are truncated to at most 39 bytes.
11207 In case of failure an "error" item is added with the reason:
11208 Cannot open file: file not found or in accessible
11209 Cannot read file: cannot read first block
11210 Not a swap file: does not contain correct block ID
11211 Magic number mismatch: Info in first block is invalid
11212
11213 Can also be used as a |method|: >
11214 GetFilename()->swapinfo()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011215<
11216 Return type: dict<any> or dict<string>
11217
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011218
11219swapname({buf}) *swapname()*
11220 The result is the swap file path of the buffer {expr}.
11221 For the use of {buf}, see |bufname()| above.
11222 If buffer {buf} is the current buffer, the result is equal to
11223 |:swapname| (unless there is no swap file).
11224 If buffer {buf} has no swap file, returns an empty string.
11225
11226 Can also be used as a |method|: >
11227 GetBufname()->swapname()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011228<
11229 Return type: |String|
11230
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011231
11232synID({lnum}, {col}, {trans}) *synID()*
11233 The result is a Number, which is the syntax ID at the position
11234 {lnum} and {col} in the current window.
11235 The syntax ID can be used with |synIDattr()| and
11236 |synIDtrans()| to obtain syntax information about text.
11237
11238 {col} is 1 for the leftmost column, {lnum} is 1 for the first
11239 line. 'synmaxcol' applies, in a longer line zero is returned.
11240 Note that when the position is after the last character,
11241 that's where the cursor can be in Insert mode, synID() returns
11242 zero. {lnum} is used like with |getline()|.
11243
11244 When {trans} is |TRUE|, transparent items are reduced to the
11245 item that they reveal. This is useful when wanting to know
11246 the effective color. When {trans} is |FALSE|, the transparent
11247 item is returned. This is useful when wanting to know which
11248 syntax item is effective (e.g. inside parens).
11249 Warning: This function can be very slow. Best speed is
11250 obtained by going through the file in forward direction.
11251
Bram Moolenaard592deb2022-06-17 15:42:40 +010011252 Returns zero on error.
11253
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011254 Example (echoes the name of the syntax item under the cursor): >
11255 :echo synIDattr(synID(line("."), col("."), 1), "name")
11256<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011257 Return type: |Number|
11258
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011259
11260synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
11261 The result is a String, which is the {what} attribute of
11262 syntax ID {synID}. This can be used to obtain information
11263 about a syntax item.
11264 {mode} can be "gui", "cterm" or "term", to get the attributes
11265 for that mode. When {mode} is omitted, or an invalid value is
11266 used, the attributes for the currently active highlighting are
11267 used (GUI, cterm or term).
11268 Use synIDtrans() to follow linked highlight groups.
11269 {what} result
11270 "name" the name of the syntax item
11271 "fg" foreground color (GUI: color name used to set
11272 the color, cterm: color number as a string,
11273 term: empty string)
11274 "bg" background color (as with "fg")
11275 "font" font name (only available in the GUI)
11276 |highlight-font|
11277 "sp" special color for the GUI (as with "fg")
11278 |highlight-guisp|
11279 "ul" underline color for cterm: number as a string
11280 "fg#" like "fg", but for the GUI and the GUI is
11281 running the name in "#RRGGBB" form
11282 "bg#" like "fg#" for "bg"
11283 "sp#" like "fg#" for "sp"
11284 "bold" "1" if bold
11285 "italic" "1" if italic
11286 "reverse" "1" if reverse
11287 "inverse" "1" if inverse (= reverse)
11288 "standout" "1" if standout
11289 "underline" "1" if underlined
11290 "undercurl" "1" if undercurled
11291 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +010011292 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011293
Bram Moolenaard592deb2022-06-17 15:42:40 +010011294 Returns an empty string on error.
11295
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011296 Example (echoes the color of the syntax item under the
11297 cursor): >
11298 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
11299<
11300 Can also be used as a |method|: >
11301 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011302<
11303 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011304
11305
11306synIDtrans({synID}) *synIDtrans()*
11307 The result is a Number, which is the translated syntax ID of
11308 {synID}. This is the syntax group ID of what is being used to
11309 highlight the character. Highlight links given with
11310 ":highlight link" are followed.
11311
Bram Moolenaard592deb2022-06-17 15:42:40 +010011312 Returns zero on error.
11313
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011314 Can also be used as a |method|: >
11315 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011316<
11317 Return type: |Number|
11318
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011319
11320synconcealed({lnum}, {col}) *synconcealed()*
11321 The result is a |List| with currently three items:
11322 1. The first item in the list is 0 if the character at the
11323 position {lnum} and {col} is not part of a concealable
11324 region, 1 if it is. {lnum} is used like with |getline()|.
11325 2. The second item in the list is a string. If the first item
11326 is 1, the second item contains the text which will be
11327 displayed in place of the concealed text, depending on the
11328 current setting of 'conceallevel' and 'listchars'.
11329 3. The third and final item in the list is a number
11330 representing the specific syntax region matched in the
11331 line. When the character is not concealed the value is
11332 zero. This allows detection of the beginning of a new
11333 concealable region if there are two consecutive regions
11334 with the same replacement character. For an example, if
11335 the text is "123456" and both "23" and "45" are concealed
11336 and replaced by the character "X", then:
11337 call returns ~
11338 synconcealed(lnum, 1) [0, '', 0]
11339 synconcealed(lnum, 2) [1, 'X', 1]
11340 synconcealed(lnum, 3) [1, 'X', 1]
11341 synconcealed(lnum, 4) [1, 'X', 2]
11342 synconcealed(lnum, 5) [1, 'X', 2]
11343 synconcealed(lnum, 6) [0, '', 0]
11344
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020011345 Note: Doesn't consider |matchadd()| highlighting items,
11346 since syntax and matching highlighting are two different
11347 mechanisms |syntax-vs-match|.
h-east52e7cc22024-07-28 17:03:29 +020011348
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011349 Return type: list<any>
Christian Brabandtfe1e2b52024-04-26 18:42:59 +020011350
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011351
11352synstack({lnum}, {col}) *synstack()*
11353 Return a |List|, which is the stack of syntax items at the
11354 position {lnum} and {col} in the current window. {lnum} is
11355 used like with |getline()|. Each item in the List is an ID
11356 like what |synID()| returns.
11357 The first item in the List is the outer region, following are
11358 items contained in that one. The last one is what |synID()|
11359 returns, unless not the whole item is highlighted or it is a
11360 transparent item.
11361 This function is useful for debugging a syntax file.
11362 Example that shows the syntax stack under the cursor: >
11363 for id in synstack(line("."), col("."))
11364 echo synIDattr(id, "name")
11365 endfor
11366< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +010011367 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011368 character in a line and the first column in an empty line are
11369 valid positions.
11370
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011371 Return type: list<number> or list<any>
11372
11373
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011374system({expr} [, {input}]) *system()* *E677*
11375 Get the output of the shell command {expr} as a |String|. See
11376 |systemlist()| to get the output as a |List|.
11377
11378 When {input} is given and is a |String| this string is written
11379 to a file and passed as stdin to the command. The string is
11380 written as-is, you need to take care of using the correct line
11381 separators yourself.
11382 If {input} is given and is a |List| it is written to the file
11383 in a way |writefile()| does with {binary} set to "b" (i.e.
11384 with a newline between each list item with newlines inside
11385 list items converted to NULs).
11386 When {input} is given and is a number that is a valid id for
11387 an existing buffer then the content of the buffer is written
11388 to the file line by line, each line terminated by a NL and
11389 NULs characters where the text has a NL.
11390
11391 Pipes are not used, the 'shelltemp' option is not used.
11392
11393 When prepended by |:silent| the terminal will not be set to
11394 cooked mode. This is meant to be used for commands that do
11395 not need the user to type. It avoids stray characters showing
11396 up on the screen which require |CTRL-L| to remove. >
11397 :silent let f = system('ls *.vim')
11398<
11399 Note: Use |shellescape()| or |::S| with |expand()| or
11400 |fnamemodify()| to escape special characters in a command
11401 argument. Newlines in {expr} may cause the command to fail.
11402 The characters in 'shellquote' and 'shellxquote' may also
11403 cause trouble.
11404 This is not to be used for interactive commands.
11405
11406 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011407 :let files = system('ls ' .. shellescape(expand('%:h')))
11408 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011409
11410< To make the result more system-independent, the shell output
11411 is filtered to replace <CR> with <NL> for Macintosh, and
11412 <CR><NL> with <NL> for DOS-like systems.
11413 To avoid the string being truncated at a NUL, all NUL
11414 characters are replaced with SOH (0x01).
11415
11416 The command executed is constructed using several options:
11417 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
11418 ({tmp} is an automatically generated file name).
11419 For Unix, braces are put around {expr} to allow for
11420 concatenated commands.
11421
11422 The command will be executed in "cooked" mode, so that a
11423 CTRL-C will interrupt the command (on Unix at least).
11424
11425 The resulting error code can be found in |v:shell_error|.
11426 This function will fail in |restricted-mode|.
11427
11428 Note that any wrong value in the options mentioned above may
11429 make the function fail. It has also been reported to fail
11430 when using a security agent application.
11431 Unlike ":!cmd" there is no automatic check for changed files.
11432 Use |:checktime| to force a check.
11433
11434 Can also be used as a |method|: >
11435 :echo GetCmd()->system()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011436<
11437 Return type: |String|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011438
11439
11440systemlist({expr} [, {input}]) *systemlist()*
11441 Same as |system()|, but returns a |List| with lines (parts of
11442 output separated by NL) with NULs transformed into NLs. Output
11443 is the same as |readfile()| will output with {binary} argument
11444 set to "b", except that there is no extra empty item when the
11445 result ends in a NL.
11446 Note that on MS-Windows you may get trailing CR characters.
11447
11448 To see the difference between "echo hello" and "echo -n hello"
11449 use |system()| and |split()|: >
11450 echo system('echo hello')->split('\n', 1)
11451<
11452 Returns an empty string on error.
11453
11454 Can also be used as a |method|: >
11455 :echo GetCmd()->systemlist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011456<
11457 Return type: list<string>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011458
11459
11460tabpagebuflist([{arg}]) *tabpagebuflist()*
11461 The result is a |List|, where each item is the number of the
11462 buffer associated with each window in the current tab page.
11463 {arg} specifies the number of the tab page to be used. When
11464 omitted the current tab page is used.
11465 When {arg} is invalid the number zero is returned.
11466 To get a list of all buffers in all tabs use this: >
11467 let buflist = []
11468 for i in range(tabpagenr('$'))
11469 call extend(buflist, tabpagebuflist(i + 1))
11470 endfor
11471< Note that a buffer may appear in more than one window.
11472
11473 Can also be used as a |method|: >
11474 GetTabpage()->tabpagebuflist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011475<
11476 Return type: list<number>
11477
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011478
11479tabpagenr([{arg}]) *tabpagenr()*
11480 The result is a Number, which is the number of the current
11481 tab page. The first tab page has number 1.
11482
11483 The optional argument {arg} supports the following values:
11484 $ the number of the last tab page (the tab page
11485 count).
11486 # the number of the last accessed tab page
11487 (where |g<Tab>| goes to). if there is no
11488 previous tab page 0 is returned.
11489 The number can be used with the |:tab| command.
11490
Bram Moolenaard592deb2022-06-17 15:42:40 +010011491 Returns zero on error.
11492
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011493 Return type: |Number|
11494
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011495
11496tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
11497 Like |winnr()| but for tab page {tabarg}.
11498 {tabarg} specifies the number of tab page to be used.
11499 {arg} is used like with |winnr()|:
11500 - When omitted the current window number is returned. This is
11501 the window which will be used when going to this tab page.
11502 - When "$" the number of windows is returned.
11503 - When "#" the previous window nr is returned.
11504 Useful examples: >
11505 tabpagewinnr(1) " current window of tab page 1
11506 tabpagewinnr(4, '$') " number of windows in tab page 4
11507< When {tabarg} is invalid zero is returned.
11508
11509 Can also be used as a |method|: >
11510 GetTabpage()->tabpagewinnr()
11511<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011512 Return type: |Number|
11513
11514
11515tagfiles() *tagfiles()*
11516 Returns a |List| with the file names used to search for tags
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011517 for the current buffer. This is the 'tags' option expanded.
11518
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011519 Return type: list<string> or list<any>
11520
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011521
11522taglist({expr} [, {filename}]) *taglist()*
11523 Returns a |List| of tags matching the regular expression {expr}.
11524
11525 If {filename} is passed it is used to prioritize the results
11526 in the same way that |:tselect| does. See |tag-priority|.
11527 {filename} should be the full path of the file.
11528
11529 Each list item is a dictionary with at least the following
11530 entries:
11531 name Name of the tag.
11532 filename Name of the file where the tag is
11533 defined. It is either relative to the
11534 current directory or a full path.
11535 cmd Ex command used to locate the tag in
11536 the file.
11537 kind Type of the tag. The value for this
11538 entry depends on the language specific
11539 kind values. Only available when
11540 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +000011541 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011542 static A file specific tag. Refer to
11543 |static-tag| for more information.
11544 More entries may be present, depending on the content of the
11545 tags file: access, implementation, inherits and signature.
11546 Refer to the ctags documentation for information about these
11547 fields. For C code the fields "struct", "class" and "enum"
11548 may appear, they give the name of the entity the tag is
11549 contained in.
11550
11551 The ex-command "cmd" can be either an ex search pattern, a
11552 line number or a line number followed by a byte number.
11553
11554 If there are no matching tags, then an empty list is returned.
11555
11556 To get an exact tag match, the anchors '^' and '$' should be
11557 used in {expr}. This also make the function work faster.
11558 Refer to |tag-regexp| for more information about the tag
11559 search regular expression pattern.
11560
11561 Refer to |'tags'| for information about how the tags file is
11562 located by Vim. Refer to |tags-file-format| for the format of
11563 the tags file generated by the different ctags tools.
11564
11565 Can also be used as a |method|: >
11566 GetTagpattern()->taglist()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011567<
11568 Return type: list<dict<any>> or list<any>
11569
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011570
11571tan({expr}) *tan()*
11572 Return the tangent of {expr}, measured in radians, as a |Float|
11573 in the range [-inf, inf].
11574 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011575 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011576 Examples: >
11577 :echo tan(10)
11578< 0.648361 >
11579 :echo tan(-4.01)
11580< -1.181502
11581
11582 Can also be used as a |method|: >
11583 Compute()->tan()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011584<
11585 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011586
11587
11588tanh({expr}) *tanh()*
11589 Return the hyperbolic tangent of {expr} as a |Float| in the
11590 range [-1, 1].
11591 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011592 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011593 Examples: >
11594 :echo tanh(0.5)
11595< 0.462117 >
11596 :echo tanh(-1)
11597< -0.761594
11598
11599 Can also be used as a |method|: >
11600 Compute()->tanh()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011601<
11602 Return type: |Float|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011603
11604
11605tempname() *tempname()* *temp-file-name*
11606 The result is a String, which is the name of a file that
11607 doesn't exist. It can be used for a temporary file. The name
11608 is different for at least 26 consecutive calls. Example: >
11609 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011610 :exe "redir > " .. tmpfile
Christian Brabandt5cf53012024-05-18 10:13:11 +020011611< For Unix, the file will be in a private directory |tempfile|
11612 that is recursively deleted when Vim exits, on other systems
11613 temporary files are not cleaned up automatically on exit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011614 For MS-Windows forward slashes are used when the 'shellslash'
11615 option is set, or when 'shellcmdflag' starts with '-' and
11616 'shell' does not contain powershell or pwsh.
11617
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011618 Return type: |String|
11619
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011620
11621term_ functions are documented here: |terminal-function-details|
11622
11623
11624terminalprops() *terminalprops()*
11625 Returns a |Dictionary| with properties of the terminal that Vim
11626 detected from the response to |t_RV| request. See
11627 |v:termresponse| for the response itself. If |v:termresponse|
11628 is empty most values here will be 'u' for unknown.
11629 cursor_style whether sending |t_RS| works **
11630 cursor_blink_mode whether sending |t_RC| works **
11631 underline_rgb whether |t_8u| works **
11632 mouse mouse type supported
Bram Moolenaar4bc85f22022-10-21 14:17:24 +010011633 kitty whether Kitty terminal was detected
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011634
11635 ** value 'u' for unknown, 'y' for yes, 'n' for no
11636
11637 If the |+termresponse| feature is missing then the result is
11638 an empty dictionary.
11639
11640 If "cursor_style" is 'y' then |t_RS| will be sent to request the
11641 current cursor style.
11642 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
11643 request the cursor blink status.
11644 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
11645 is not empty, Vim will detect the working of sending |t_RS|
11646 and |t_RC| on startup.
11647
11648 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
11649 This avoids sending it to xterm, which would clear the colors.
11650
11651 For "mouse" the value 'u' is unknown
11652
11653 Also see:
11654 - 'ambiwidth' - detected by using |t_u7|.
11655 - |v:termstyleresp| and |v:termblinkresp| for the response to
11656 |t_RS| and |t_RC|.
11657
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011658 Return type: dict<string>
11659
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011660
11661test_ functions are documented here: |test-functions-details|
11662
11663
11664 *timer_info()*
11665timer_info([{id}])
11666 Return a list with information about timers.
11667 When {id} is given only information about this timer is
11668 returned. When timer {id} does not exist an empty list is
11669 returned.
11670 When {id} is omitted information about all timers is returned.
11671
11672 For each timer the information is stored in a |Dictionary| with
11673 these items:
11674 "id" the timer ID
11675 "time" time the timer was started with
11676 "remaining" time until the timer fires
11677 "repeat" number of times the timer will still fire;
11678 -1 means forever
11679 "callback" the callback
11680 "paused" 1 if the timer is paused, 0 otherwise
11681
11682 Can also be used as a |method|: >
11683 GetTimer()->timer_info()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011684<
11685 Return type: list<dict<any>> or list<any>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011686
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011687 {only available when compiled with the |+timers| feature}
11688
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011689
11690timer_pause({timer}, {paused}) *timer_pause()*
11691 Pause or unpause a timer. A paused timer does not invoke its
11692 callback when its time expires. Unpausing a timer may cause
11693 the callback to be invoked almost immediately if enough time
11694 has passed.
11695
11696 Pausing a timer is useful to avoid the callback to be called
11697 for a short time.
11698
11699 If {paused} evaluates to a non-zero Number or a non-empty
11700 String, then the timer is paused, otherwise it is unpaused.
11701 See |non-zero-arg|.
11702
11703 Can also be used as a |method|: >
11704 GetTimer()->timer_pause(1)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011705<
11706 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011707
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011708 {only available when compiled with the |+timers| feature}
11709
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011710
11711 *timer_start()* *timer* *timers*
11712timer_start({time}, {callback} [, {options}])
11713 Create a timer and return the timer ID.
11714
11715 {time} is the waiting time in milliseconds. This is the
11716 minimum time before invoking the callback. When the system is
11717 busy or Vim is not waiting for input the time will be longer.
Bram Moolenaardd60c362023-02-27 15:49:53 +000011718 Zero can be used to execute the callback when Vim is back in
11719 the main loop.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011720
11721 {callback} is the function to call. It can be the name of a
11722 function or a |Funcref|. It is called with one argument, which
11723 is the timer ID. The callback is only invoked when Vim is
11724 waiting for input.
11725 If you want to show a message look at |popup_notification()|
11726 to avoid interfering with what the user is doing.
11727
11728 {options} is a dictionary. Supported entries:
11729 "repeat" Number of times to repeat calling the
11730 callback. -1 means forever. When not present
11731 the callback will be called once.
11732 If the timer causes an error three times in a
11733 row the repeat is cancelled. This avoids that
11734 Vim becomes unusable because of all the error
11735 messages.
11736
Bram Moolenaard592deb2022-06-17 15:42:40 +010011737 Returns -1 on error.
11738
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011739 Example: >
11740 func MyHandler(timer)
11741 echo 'Handler called'
11742 endfunc
11743 let timer = timer_start(500, 'MyHandler',
11744 \ {'repeat': 3})
11745< This will invoke MyHandler() three times at 500 msec
11746 intervals.
11747
11748 Can also be used as a |method|: >
11749 GetMsec()->timer_start(callback)
11750
11751< Not available in the |sandbox|.
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011752
11753 Return type: |Number|
11754
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011755 {only available when compiled with the |+timers| feature}
11756
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011757
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011758timer_stop({timer}) *timer_stop()*
11759 Stop a timer. The timer callback will no longer be invoked.
11760 {timer} is an ID returned by timer_start(), thus it must be a
11761 Number. If {timer} does not exist there is no error.
11762
11763 Can also be used as a |method|: >
11764 GetTimer()->timer_stop()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011765<
11766 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011767
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011768 {only available when compiled with the |+timers| feature}
11769
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011770
11771timer_stopall() *timer_stopall()*
11772 Stop all timers. The timer callbacks will no longer be
11773 invoked. Useful if a timer is misbehaving. If there are no
11774 timers there is no error.
11775
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011776 Return type: |Number|
11777
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011778 {only available when compiled with the |+timers| feature}
11779
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011780
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011781tolower({expr}) *tolower()*
11782 The result is a copy of the String given, with all uppercase
11783 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010011784 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011785
11786 Can also be used as a |method|: >
11787 GetText()->tolower()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011788<
11789 Return type: |String|
11790
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011791
11792toupper({expr}) *toupper()*
11793 The result is a copy of the String given, with all lowercase
11794 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +010011795 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011796
11797 Can also be used as a |method|: >
11798 GetText()->toupper()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011799<
11800 Return type: |String|
11801
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011802
11803tr({src}, {fromstr}, {tostr}) *tr()*
11804 The result is a copy of the {src} string with all characters
11805 which appear in {fromstr} replaced by the character in that
11806 position in the {tostr} string. Thus the first character in
11807 {fromstr} is translated into the first character in {tostr}
11808 and so on. Exactly like the unix "tr" command.
11809 This code also deals with multibyte characters properly.
11810
Bram Moolenaard592deb2022-06-17 15:42:40 +010011811 Returns an empty string on error.
11812
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011813 Examples: >
11814 echo tr("hello there", "ht", "HT")
11815< returns "Hello THere" >
11816 echo tr("<blob>", "<>", "{}")
11817< returns "{blob}"
11818
11819 Can also be used as a |method|: >
11820 GetText()->tr(from, to)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011821<
11822 Return type: |String|
11823
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011824
11825trim({text} [, {mask} [, {dir}]]) *trim()*
11826 Return {text} as a String where any character in {mask} is
11827 removed from the beginning and/or end of {text}.
11828
Illia Bobyr80799172023-10-17 18:00:50 +020011829 If {mask} is not given, or is an empty string, {mask} is all
11830 characters up to 0x20, which includes Tab, space, NL and CR,
11831 plus the non-breaking space character 0xa0.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011832
11833 The optional {dir} argument specifies where to remove the
11834 characters:
11835 0 remove from the beginning and end of {text}
11836 1 remove only at the beginning of {text}
11837 2 remove only at the end of {text}
11838 When omitted both ends are trimmed.
11839
11840 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011841 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011842
11843 Examples: >
11844 echo trim(" some text ")
11845< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000011846 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011847< returns "RESERVE_TAIL" >
11848 echo trim("rm<Xrm<>X>rrm", "rm<>")
11849< returns "Xrm<>X" (characters in the middle are not removed) >
11850 echo trim(" vim ", " ", 2)
11851< returns " vim"
11852
11853 Can also be used as a |method|: >
11854 GetText()->trim()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011855<
11856 Return type: |String|
11857
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011858
11859trunc({expr}) *trunc()*
11860 Return the largest integral value with magnitude less than or
11861 equal to {expr} as a |Float| (truncate towards zero).
11862 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010011863 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011864 Examples: >
11865 echo trunc(1.456)
11866< 1.0 >
11867 echo trunc(-5.456)
11868< -5.0 >
11869 echo trunc(4.0)
11870< 4.0
11871
11872 Can also be used as a |method|: >
11873 Compute()->trunc()
11874<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011875 Return type: |Float|
11876
11877
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011878 *type()*
11879type({expr}) The result is a Number representing the type of {expr}.
11880 Instead of using the number directly, it is better to use the
11881 v:t_ variable that has the value:
11882 Number: 0 |v:t_number|
11883 String: 1 |v:t_string|
11884 Funcref: 2 |v:t_func|
11885 List: 3 |v:t_list|
11886 Dictionary: 4 |v:t_dict|
11887 Float: 5 |v:t_float|
11888 Boolean: 6 |v:t_bool| (v:false and v:true)
11889 None: 7 |v:t_none| (v:null and v:none)
11890 Job: 8 |v:t_job|
11891 Channel: 9 |v:t_channel|
11892 Blob: 10 |v:t_blob|
h_east596a9f22023-11-21 21:24:23 +090011893 Class: 12 |v:t_class|
11894 Object: 13 |v:t_object|
Yegappan Lakshmanan2a71b542023-12-14 20:03:03 +010011895 Typealias: 14 |v:t_typealias|
Yegappan Lakshmanan3164cf82024-03-28 10:36:42 +010011896 Enum: 15 |v:t_enum|
11897 EnumValue: 16 |v:t_enumvalue|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011898 For backward compatibility, this method can be used: >
11899 :if type(myvar) == type(0)
11900 :if type(myvar) == type("")
11901 :if type(myvar) == type(function("tr"))
11902 :if type(myvar) == type([])
11903 :if type(myvar) == type({})
11904 :if type(myvar) == type(0.0)
11905 :if type(myvar) == type(v:false)
11906 :if type(myvar) == type(v:none)
11907< To check if the v:t_ variables exist use this: >
11908 :if exists('v:t_number')
11909
11910< Can also be used as a |method|: >
11911 mylist->type()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011912<
11913 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011914
11915
11916typename({expr}) *typename()*
11917 Return a string representation of the type of {expr}.
11918 Example: >
11919 echo typename([1, 2, 3])
Kota Kato66bb9ae2023-01-17 18:31:56 +000011920< list<number> ~
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011921
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011922 Return type: |String|
11923
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011924
11925undofile({name}) *undofile()*
11926 Return the name of the undo file that would be used for a file
11927 with name {name} when writing. This uses the 'undodir'
11928 option, finding directories that exist. It does not check if
11929 the undo file exists.
11930 {name} is always expanded to the full path, since that is what
11931 is used internally.
11932 If {name} is empty undofile() returns an empty string, since a
11933 buffer without a file name will not write an undo file.
11934 Useful in combination with |:wundo| and |:rundo|.
11935 When compiled without the |+persistent_undo| option this always
11936 returns an empty string.
11937
11938 Can also be used as a |method|: >
11939 GetFilename()->undofile()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011940<
11941 Return type: |String|
11942
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011943
Devin J. Pohly5fee1112023-04-23 20:26:59 -050011944undotree([{buf}]) *undotree()*
11945 Return the current state of the undo tree for the current
11946 buffer, or for a specific buffer if {buf} is given. The
11947 result is a dictionary with the following items:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011948 "seq_last" The highest undo sequence number used.
11949 "seq_cur" The sequence number of the current position in
11950 the undo tree. This differs from "seq_last"
11951 when some changes were undone.
11952 "time_cur" Time last used for |:earlier| and related
11953 commands. Use |strftime()| to convert to
11954 something readable.
11955 "save_last" Number of the last file write. Zero when no
11956 write yet.
11957 "save_cur" Number of the current position in the undo
11958 tree.
11959 "synced" Non-zero when the last undo block was synced.
11960 This happens when waiting from input from the
11961 user. See |undo-blocks|.
11962 "entries" A list of dictionaries with information about
11963 undo blocks.
11964
11965 The first item in the "entries" list is the oldest undo item.
11966 Each List item is a |Dictionary| with these items:
11967 "seq" Undo sequence number. Same as what appears in
11968 |:undolist|.
11969 "time" Timestamp when the change happened. Use
11970 |strftime()| to convert to something readable.
11971 "newhead" Only appears in the item that is the last one
11972 that was added. This marks the last change
11973 and where further changes will be added.
11974 "curhead" Only appears in the item that is the last one
11975 that was undone. This marks the current
11976 position in the undo tree, the block that will
11977 be used by a redo command. When nothing was
11978 undone after the last change this item will
11979 not appear anywhere.
11980 "save" Only appears on the last block before a file
11981 write. The number is the write count. The
11982 first write has number 1, the last one the
11983 "save_last" mentioned above.
11984 "alt" Alternate entry. This is again a List of undo
11985 blocks. Each item may again have an "alt"
11986 item.
11987
Christian Brabandt5674c9a2024-06-09 00:13:43 +020011988 Return type: dict<any>
11989
11990
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000011991uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
11992 Remove second and succeeding copies of repeated adjacent
11993 {list} items in-place. Returns {list}. If you want a list
11994 to remain unmodified make a copy first: >
11995 :let newlist = uniq(copy(mylist))
11996< The default compare function uses the string representation of
11997 each item. For the use of {func} and {dict} see |sort()|.
11998
Bram Moolenaard592deb2022-06-17 15:42:40 +010011999 Returns zero if {list} is not a |List|.
12000
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012001 Can also be used as a |method|: >
12002 mylist->uniq()
Christian Brabandt67672ef2023-04-24 21:09:54 +010012003<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012004 Return type: list<{type}>
12005
12006
Christian Brabandt67672ef2023-04-24 21:09:54 +010012007 *utf16idx()*
12008utf16idx({string}, {idx} [, {countcc} [, {charidx}]])
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010012009 Same as |charidx()| but returns the UTF-16 code unit index of
12010 the byte at {idx} in {string} (after converting it to UTF-16).
Christian Brabandt67672ef2023-04-24 21:09:54 +010012011
12012 When {charidx} is present and TRUE, {idx} is used as the
12013 character index in the String {string} instead of as the byte
12014 index.
Yegappan Lakshmanan95707032023-06-14 13:10:15 +010012015 An {idx} in the middle of a UTF-8 sequence is rounded
12016 downwards to the beginning of that sequence.
Christian Brabandt67672ef2023-04-24 21:09:54 +010012017
Yegappan Lakshmanan577922b2023-06-08 17:09:45 +010012018 Returns -1 if the arguments are invalid or if there are less
12019 than {idx} bytes in {string}. If there are exactly {idx} bytes
12020 the length of the string in UTF-16 code units is returned.
12021
Christian Brabandt67672ef2023-04-24 21:09:54 +010012022 See |byteidx()| and |byteidxcomp()| for getting the byte index
12023 from the UTF-16 index and |charidx()| for getting the
12024 character index from the UTF-16 index.
12025 Refer to |string-offset-encoding| for more information.
12026 Examples: >
12027 echo utf16idx('a😊😊', 3) returns 2
12028 echo utf16idx('a😊😊', 7) returns 4
12029 echo utf16idx('a😊😊', 1, 0, 1) returns 2
12030 echo utf16idx('a😊😊', 2, 0, 1) returns 4
12031 echo utf16idx('aą́c', 6) returns 2
12032 echo utf16idx('aą́c', 6, 1) returns 4
12033 echo utf16idx('a😊😊', 9) returns -1
12034<
12035 Can also be used as a |method|: >
12036 GetName()->utf16idx(idx)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012037<
12038 Return type: |Number|
Christian Brabandt67672ef2023-04-24 21:09:54 +010012039
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012040
12041values({dict}) *values()*
12042 Return a |List| with all the values of {dict}. The |List| is
12043 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +010012044 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012045
12046 Can also be used as a |method|: >
12047 mydict->values()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012048<
12049 Return type: list<any>
12050
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012051
zeertzjq825cf812023-08-17 22:55:25 +020012052virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012053 The result is a Number, which is the screen column of the file
12054 position given with {expr}. That is, the last screen position
12055 occupied by the character at that position, when the screen
12056 would be of unlimited width. When there is a <Tab> at the
12057 position, the returned Number will be the column at the end of
12058 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
12059 set to 8, it returns 8. |conceal| is ignored.
12060 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010012061
zeertzjq02f3eba2024-06-12 20:45:24 +020012062 For the use of {expr} see |getpos()| and |col()|.
zeertzjqd353d272024-06-13 23:00:25 +080012063 When {expr} is "$", it means the end of the cursor line, so
12064 the result is the number of cells in the cursor line plus one.
LemonBoy0f7a3e12022-05-26 12:10:37 +010012065
12066 When 'virtualedit' is used {expr} can be [lnum, col, off],
12067 where "off" is the offset in screen columns from the start of
12068 the character. E.g., a position within a <Tab> or after the
12069 last character. When "off" is omitted zero is used. When
12070 Virtual editing is active in the current mode, a position
12071 beyond the end of the line can be returned. Also see
12072 |'virtualedit'|
12073
zeertzjq825cf812023-08-17 22:55:25 +020012074 If {list} is present and non-zero then virtcol() returns a
12075 List with the first and last screen position occupied by the
LemonBoy0f7a3e12022-05-26 12:10:37 +010012076 character.
12077
zeertzjq825cf812023-08-17 22:55:25 +020012078 With the optional {winid} argument the values are obtained for
12079 that window instead of the current window.
12080
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012081 Note that only marks in the current file can be used.
zeertzjq02f3eba2024-06-12 20:45:24 +020012082
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012083 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +010012084 " With text "foo^Lbar" and cursor on the "^L":
12085
12086 virtcol(".") " returns 5
12087 virtcol(".", 1) " returns [4, 5]
12088 virtcol("$") " returns 9
12089
12090 " With text " there", with 't at 'h':
12091
12092 virtcol("'t") " returns 6
zeertzjq02f3eba2024-06-12 20:45:24 +020012093<
12094 The first column is 1. 0 or [0, 0] is returned for an error.
12095
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012096 A more advanced example that echoes the maximum length of
12097 all lines: >
12098 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
12099
12100< Can also be used as a |method|: >
12101 GetPos()->virtcol()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012102<
12103 Return type: |Number|
12104
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012105
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012106virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
12107 The result is a Number, which is the byte index of the
12108 character in window {winid} at buffer line {lnum} and virtual
12109 column {col}.
12110
zeertzjqb583eda2023-10-14 11:32:28 +020012111 If buffer line {lnum} is an empty line, 0 is returned.
12112
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012113 If {col} is greater than the last virtual column in line
12114 {lnum}, then the byte index of the character at the last
12115 virtual column is returned.
12116
Yegappan Lakshmananb209b862023-08-15 23:01:44 +020012117 For a multi-byte character, the column number of the first
12118 byte in the character is returned.
12119
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012120 The {winid} argument can be the window number or the
12121 |window-ID|. If this is zero, then the current window is used.
12122
12123 Returns -1 if the window {winid} doesn't exist or the buffer
12124 line {lnum} or virtual column {col} is invalid.
12125
12126 See also |screenpos()|, |virtcol()| and |col()|.
12127
12128 Can also be used as a |method|: >
12129 GetWinid()->virtcol2col(lnum, col)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012130<
12131 Return type: |Number|
12132
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012133
12134visualmode([{expr}]) *visualmode()*
12135 The result is a String, which describes the last Visual mode
12136 used in the current buffer. Initially it returns an empty
12137 string, but once Visual mode has been used, it returns "v",
12138 "V", or "<CTRL-V>" (a single CTRL-V character) for
12139 character-wise, line-wise, or block-wise Visual mode
12140 respectively.
12141 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012142 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012143< This enters the same Visual mode as before. It is also useful
12144 in scripts if you wish to act differently depending on the
12145 Visual mode that was used.
12146 If Visual mode is active, use |mode()| to get the Visual mode
12147 (e.g., in a |:vmap|).
12148 If {expr} is supplied and it evaluates to a non-zero Number or
12149 a non-empty String, then the Visual mode will be cleared and
12150 the old value is returned. See |non-zero-arg|.
12151
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012152 Return type: |String|
12153
12154
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012155wildmenumode() *wildmenumode()*
12156 Returns |TRUE| when the wildmenu is active and |FALSE|
12157 otherwise. See 'wildmenu' and 'wildmode'.
12158 This can be used in mappings to handle the 'wildcharm' option
12159 gracefully. (Makes only sense with |mapmode-c| mappings).
12160
12161 For example to make <c-j> work like <down> in wildmode, use: >
12162 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
12163<
Milly6c2fc372024-10-16 22:11:17 +020012164 (Note: this needs the 'wildcharm' option set appropriately).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012165
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012166 Return type: |Number|
12167
12168
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012169win_execute({id}, {command} [, {silent}]) *win_execute()*
12170 Like `execute()` but in the context of window {id}.
12171 The window will temporarily be made the current window,
12172 without triggering autocommands or changing directory. When
12173 executing {command} autocommands will be triggered, this may
Bram Moolenaarb7398fe2023-05-14 18:50:25 +010012174 have unexpected side effects. Use `:noautocmd` if needed.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012175 Example: >
12176 call win_execute(winid, 'set syntax=python')
12177< Doing the same with `setwinvar()` would not trigger
12178 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012179 *E994*
12180 Not all commands are allowed in popup windows.
12181 When window {id} does not exist then no error is given and
12182 an empty string is returned.
12183
12184 Can also be used as a |method|, the base is passed as the
12185 second argument: >
12186 GetCommand()->win_execute(winid)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012187<
12188 Return type: |String|
12189
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012190
12191win_findbuf({bufnr}) *win_findbuf()*
12192 Returns a |List| with |window-ID|s for windows that contain
12193 buffer {bufnr}. When there is none the list is empty.
12194
12195 Can also be used as a |method|: >
12196 GetBufnr()->win_findbuf()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012197<
12198 Return type: list<number> or list<any>
12199
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012200
12201win_getid([{win} [, {tab}]]) *win_getid()*
12202 Get the |window-ID| for the specified window.
12203 When {win} is missing use the current window.
12204 With {win} this is the window number. The top window has
12205 number 1.
12206 Without {tab} use the current tab, otherwise the tab with
12207 number {tab}. The first tab has number one.
12208 Return zero if the window cannot be found.
12209
12210 Can also be used as a |method|: >
12211 GetWinnr()->win_getid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012212<
12213 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012214
12215
12216win_gettype([{nr}]) *win_gettype()*
12217 Return the type of the window:
12218 "autocmd" autocommand window. Temporary window
12219 used to execute autocommands.
12220 "command" command-line window |cmdwin|
12221 (empty) normal window
12222 "loclist" |location-list-window|
12223 "popup" popup window |popup|
12224 "preview" preview window |preview-window|
12225 "quickfix" |quickfix-window|
12226 "unknown" window {nr} not found
12227
12228 When {nr} is omitted return the type of the current window.
12229 When {nr} is given return the type of this window by number or
12230 |window-ID|.
12231
12232 Also see the 'buftype' option. When running a terminal in a
12233 popup window then 'buftype' is "terminal" and win_gettype()
12234 returns "popup".
12235
12236 Can also be used as a |method|: >
12237 GetWinid()->win_gettype()
12238<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012239 Return type: |String|
12240
12241
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012242win_gotoid({expr}) *win_gotoid()*
12243 Go to window with ID {expr}. This may also change the current
12244 tabpage.
12245 Return TRUE if successful, FALSE if the window cannot be found.
12246
12247 Can also be used as a |method|: >
12248 GetWinid()->win_gotoid()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012249<
12250 Return type: |Number|
12251
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012252
12253win_id2tabwin({expr}) *win_id2tabwin()*
12254 Return a list with the tab number and window number of window
12255 with ID {expr}: [tabnr, winnr].
12256 Return [0, 0] if the window cannot be found.
12257
12258 Can also be used as a |method|: >
12259 GetWinid()->win_id2tabwin()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012260<
12261 Return type: list<number>
12262
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012263
12264win_id2win({expr}) *win_id2win()*
12265 Return the window number of window with ID {expr}.
12266 Return 0 if the window cannot be found in the current tabpage.
12267
12268 Can also be used as a |method|: >
12269 GetWinid()->win_id2win()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012270<
12271 Return type: |Number|
12272
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012273
Daniel Steinbergee630312022-01-10 13:36:34 +000012274win_move_separator({nr}, {offset}) *win_move_separator()*
12275 Move window {nr}'s vertical separator (i.e., the right border)
12276 by {offset} columns, as if being dragged by the mouse. {nr}
12277 can be a window number or |window-ID|. A positive {offset}
12278 moves right and a negative {offset} moves left. Moving a
12279 window's vertical separator will change the width of the
12280 window and the width of other windows adjacent to the vertical
12281 separator. The magnitude of movement may be smaller than
12282 specified (e.g., as a consequence of maintaining
12283 'winminwidth'). Returns TRUE if the window can be found and
12284 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010012285 This will fail for the rightmost window and a full-width
12286 window, since it has no separator on the right.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000012287 Only works for the current tab page. *E1308*
Daniel Steinbergee630312022-01-10 13:36:34 +000012288
12289 Can also be used as a |method|: >
12290 GetWinnr()->win_move_separator(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012291<
12292 Return type: |Number|
12293
Daniel Steinbergee630312022-01-10 13:36:34 +000012294
12295win_move_statusline({nr}, {offset}) *win_move_statusline()*
12296 Move window {nr}'s status line (i.e., the bottom border) by
12297 {offset} rows, as if being dragged by the mouse. {nr} can be a
12298 window number or |window-ID|. A positive {offset} moves down
12299 and a negative {offset} moves up. Moving a window's status
12300 line will change the height of the window and the height of
12301 other windows adjacent to the status line. The magnitude of
12302 movement may be smaller than specified (e.g., as a consequence
12303 of maintaining 'winminheight'). Returns TRUE if the window can
12304 be found and FALSE otherwise.
Bram Moolenaar76db9e02022-11-09 21:21:04 +000012305 Only works for the current tab page.
Daniel Steinbergee630312022-01-10 13:36:34 +000012306
12307 Can also be used as a |method|: >
12308 GetWinnr()->win_move_statusline(offset)
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012309<
12310 Return type: |Number|
12311
Daniel Steinbergee630312022-01-10 13:36:34 +000012312
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012313win_screenpos({nr}) *win_screenpos()*
12314 Return the screen position of window {nr} as a list with two
12315 numbers: [row, col]. The first window always has position
12316 [1, 1], unless there is a tabline, then it is [2, 1].
12317 {nr} can be the window number or the |window-ID|. Use zero
12318 for the current window.
Sean Dewar5866bc32024-03-13 20:17:24 +010012319 Returns [0, 0] if the window cannot be found.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012320
12321 Can also be used as a |method|: >
12322 GetWinid()->win_screenpos()
12323<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012324 Return type: list<number>
12325
12326
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012327win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
Sean Dewar96cc4ae2024-02-20 21:52:31 +010012328 Temporarily switch to window {target}, then move window {nr}
12329 to a new split adjacent to {target}.
12330 Unlike commands such as |:split|, no new windows are created
12331 (the |window-ID| of window {nr} is unchanged after the move).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012332
12333 Both {nr} and {target} can be window numbers or |window-ID|s.
12334 Both must be in the current tab page.
12335
12336 Returns zero for success, non-zero for failure.
12337
12338 {options} is a |Dictionary| with the following optional entries:
12339 "vertical" When TRUE, the split is created vertically,
12340 like with |:vsplit|.
12341 "rightbelow" When TRUE, the split is made below or to the
12342 right (if vertical). When FALSE, it is done
12343 above or to the left (if vertical). When not
12344 present, the values of 'splitbelow' and
12345 'splitright' are used.
12346
12347 Can also be used as a |method|: >
12348 GetWinid()->win_splitmove(target)
12349<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012350 Return type: |Number|
12351
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012352
12353 *winbufnr()*
12354winbufnr({nr}) The result is a Number, which is the number of the buffer
12355 associated with window {nr}. {nr} can be the window number or
12356 the |window-ID|.
12357 When {nr} is zero, the number of the buffer in the current
12358 window is returned.
12359 When window {nr} doesn't exist, -1 is returned.
12360 Example: >
12361 :echo "The file in the current window is " . bufname(winbufnr(0))
12362<
12363 Can also be used as a |method|: >
12364 FindWindow()->winbufnr()->bufname()
12365<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012366 Return type: |Number|
12367
12368
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012369 *wincol()*
12370wincol() The result is a Number, which is the virtual column of the
12371 cursor in the window. This is counting screen cells from the
12372 left side of the window. The leftmost column is one.
12373
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012374 Return type: |Number|
12375
12376
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012377 *windowsversion()*
12378windowsversion()
12379 The result is a String. For MS-Windows it indicates the OS
12380 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
12381 Windows XP is "5.1". For non-MS-Windows systems the result is
12382 an empty string.
12383
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012384 Return type: |String|
12385
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012386winheight({nr}) *winheight()*
12387 The result is a Number, which is the height of window {nr}.
12388 {nr} can be the window number or the |window-ID|.
12389 When {nr} is zero, the height of the current window is
12390 returned. When window {nr} doesn't exist, -1 is returned.
12391 An existing window always has a height of zero or more.
12392 This excludes any window toolbar line.
12393 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012394 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012395
12396< Can also be used as a |method|: >
12397 GetWinid()->winheight()
12398<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012399 Return type: |Number|
12400
12401
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012402winlayout([{tabnr}]) *winlayout()*
12403 The result is a nested List containing the layout of windows
12404 in a tabpage.
12405
12406 Without {tabnr} use the current tabpage, otherwise the tabpage
12407 with number {tabnr}. If the tabpage {tabnr} is not found,
12408 returns an empty list.
12409
12410 For a leaf window, it returns:
12411 ['leaf', {winid}]
12412 For horizontally split windows, which form a column, it
12413 returns:
12414 ['col', [{nested list of windows}]]
12415 For vertically split windows, which form a row, it returns:
12416 ['row', [{nested list of windows}]]
12417
12418 Example: >
12419 " Only one window in the tab page
12420 :echo winlayout()
12421 ['leaf', 1000]
12422 " Two horizontally split windows
12423 :echo winlayout()
12424 ['col', [['leaf', 1000], ['leaf', 1001]]]
12425 " The second tab page, with three horizontally split
12426 " windows, with two vertically split windows in the
12427 " middle window
12428 :echo winlayout(2)
12429 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
12430 ['leaf', 1001]]], ['leaf', 1000]]]
12431<
12432 Can also be used as a |method|: >
12433 GetTabnr()->winlayout()
12434<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012435 Return type: list<any>
12436
12437
12438winline() *winline()*
12439 The result is a Number, which is the screen line of the cursor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012440 in the window. This is counting screen lines from the top of
12441 the window. The first line is one.
12442 If the cursor was moved the view on the file will be updated
12443 first, this may cause a scroll.
12444
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012445 Return type: |Number|
12446
12447
12448winnr([{arg}]) *winnr()*
12449 The result is a Number, which is the number of the current
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012450 window. The top window has number 1.
12451 Returns zero for a popup window.
12452
12453 The optional argument {arg} supports the following values:
12454 $ the number of the last window (the window
12455 count).
12456 # the number of the last accessed window (where
12457 |CTRL-W_p| goes to). If there is no previous
12458 window or it is in another tab page 0 is
Sean Deward64801e2024-03-12 20:46:12 +010012459 returned. May refer to the current window in
12460 some cases (e.g. when evaluating 'statusline'
12461 expressions).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012462 {N}j the number of the Nth window below the
12463 current window (where |CTRL-W_j| goes to).
12464 {N}k the number of the Nth window above the current
12465 window (where |CTRL-W_k| goes to).
12466 {N}h the number of the Nth window left of the
12467 current window (where |CTRL-W_h| goes to).
12468 {N}l the number of the Nth window right of the
12469 current window (where |CTRL-W_l| goes to).
12470 The number can be used with |CTRL-W_w| and ":wincmd w"
12471 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010012472 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012473 Also see |tabpagewinnr()| and |win_getid()|.
12474 Examples: >
12475 let window_count = winnr('$')
12476 let prev_window = winnr('#')
12477 let wnum = winnr('3k')
12478
12479< Can also be used as a |method|: >
12480 GetWinval()->winnr()
12481<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012482 Return type: |Number|
12483
12484
12485winrestcmd() *winrestcmd()*
12486 Returns a sequence of |:resize| commands that should restore
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012487 the current window sizes. Only works properly when no windows
12488 are opened or closed and the current window and tab page is
12489 unchanged.
12490 Example: >
12491 :let cmd = winrestcmd()
12492 :call MessWithWindowSizes()
12493 :exe cmd
12494<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012495 Return type: |String|
12496
12497
12498winrestview({dict}) *winrestview()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012499 Uses the |Dictionary| returned by |winsaveview()| to restore
12500 the view of the current window.
12501 Note: The {dict} does not have to contain all values, that are
12502 returned by |winsaveview()|. If values are missing, those
12503 settings won't be restored. So you can use: >
12504 :call winrestview({'curswant': 4})
12505<
12506 This will only set the curswant value (the column the cursor
12507 wants to move on vertical movements) of the cursor to column 5
12508 (yes, that is 5), while all other settings will remain the
12509 same. This is useful, if you set the cursor position manually.
12510
12511 If you have changed the values the result is unpredictable.
12512 If the window size changed the result won't be the same.
12513
12514 Can also be used as a |method|: >
12515 GetView()->winrestview()
12516<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012517 Return type: |Number|
12518
12519
12520winsaveview() *winsaveview()*
12521 Returns a |Dictionary| that contains information to restore
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012522 the view of the current window. Use |winrestview()| to
12523 restore the view.
12524 This is useful if you have a mapping that jumps around in the
12525 buffer and you want to go back to the original view.
12526 This does not save fold information. Use the 'foldenable'
12527 option to temporarily switch off folding, so that folds are
12528 not opened when moving around. This may have side effects.
12529 The return value includes:
12530 lnum cursor line number
12531 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000012532 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012533 returns)
12534 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000012535 curswant column for vertical movement (Note:
12536 the first column is zero, as opposed
12537 to what |getcurpos()| returns). After
12538 |$| command it will be a very large
12539 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012540 topline first line in the window
12541 topfill filler lines, only in diff mode
12542 leftcol first column displayed; only used when
12543 'wrap' is off
12544 skipcol columns skipped
12545 Note that no option values are saved.
12546
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012547 Return type: dict<number>
12548
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012549
12550winwidth({nr}) *winwidth()*
12551 The result is a Number, which is the width of window {nr}.
12552 {nr} can be the window number or the |window-ID|.
12553 When {nr} is zero, the width of the current window is
12554 returned. When window {nr} doesn't exist, -1 is returned.
12555 An existing window always has a width of zero or more.
12556 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000012557 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012558 :if winwidth(0) <= 50
12559 : 50 wincmd |
12560 :endif
12561< For getting the terminal or screen size, see the 'columns'
12562 option.
12563
12564 Can also be used as a |method|: >
12565 GetWinid()->winwidth()
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012566<
12567 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012568
12569
12570wordcount() *wordcount()*
12571 The result is a dictionary of byte/chars/word statistics for
12572 the current buffer. This is the same info as provided by
12573 |g_CTRL-G|
12574 The return value includes:
12575 bytes Number of bytes in the buffer
12576 chars Number of chars in the buffer
12577 words Number of words in the buffer
12578 cursor_bytes Number of bytes before cursor position
12579 (not in Visual mode)
12580 cursor_chars Number of chars before cursor position
12581 (not in Visual mode)
12582 cursor_words Number of words before cursor position
12583 (not in Visual mode)
12584 visual_bytes Number of bytes visually selected
12585 (only in Visual mode)
12586 visual_chars Number of chars visually selected
12587 (only in Visual mode)
12588 visual_words Number of words visually selected
12589 (only in Visual mode)
12590
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012591 Return type: dict<number>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012592
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012593
12594writefile({object}, {fname} [, {flags}]) *writefile()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012595 When {object} is a |List| write it to file {fname}. Each list
12596 item is separated with a NL. Each list item must be a String
12597 or Number.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012598 All NL characters are replaced with a NUL character.
12599 Inserting CR characters needs to be done before passing {list}
12600 to writefile().
Bram Moolenaar806a2732022-09-04 15:40:36 +010012601
12602 When {object} is a |Blob| write the bytes to file {fname}
12603 unmodified, also when binary mode is not specified.
12604
12605 {flags} must be a String. These characters are recognized:
12606
12607 'b' Binary mode is used: There will not be a NL after the
12608 last list item. An empty item at the end does cause the
12609 last line in the file to end in a NL.
12610
12611 'a' Append mode is used, lines are appended to the file: >
12612 :call writefile(["foo"], "event.log", "a")
12613 :call writefile(["bar"], "event.log", "a")
12614<
12615 'D' Delete the file when the current function ends. This
12616 works like: >
Bram Moolenaar938ae282023-02-20 20:44:55 +000012617 :defer delete({fname})
Bram Moolenaar806a2732022-09-04 15:40:36 +010012618< Fails when not in a function. Also see |:defer|.
12619
12620 's' fsync() is called after writing the file. This flushes
12621 the file to disk, if possible. This takes more time but
12622 avoids losing the file if the system crashes.
12623
12624 'S' fsync() is not called, even when 'fsync' is set.
12625
12626 When {flags} does not contain "S" or "s" then fsync() is
12627 called if the 'fsync' option is set.
12628
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012629 An existing file is overwritten, if possible.
Bram Moolenaar806a2732022-09-04 15:40:36 +010012630
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012631 When the write fails -1 is returned, otherwise 0. There is an
12632 error message if the file can't be created or when writing
12633 fails.
Bram Moolenaar806a2732022-09-04 15:40:36 +010012634
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012635 Also see |readfile()|.
12636 To copy a file byte for byte: >
12637 :let fl = readfile("foo", "b")
12638 :call writefile(fl, "foocopy", "b")
12639
12640< Can also be used as a |method|: >
12641 GetText()->writefile("thefile")
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012642<
12643 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012644
12645
12646xor({expr}, {expr}) *xor()*
12647 Bitwise XOR on the two arguments. The arguments are converted
12648 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010012649 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012650 Example: >
12651 :let bits = xor(bits, 0x80)
12652<
12653 Can also be used as a |method|: >
12654 :let bits = bits->xor(0x80)
12655<
Christian Brabandt5674c9a2024-06-09 00:13:43 +020012656 Return type: |Number|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012657
12658==============================================================================
126593. Feature list *feature-list*
12660
12661There are three types of features:
126621. Features that are only supported when they have been enabled when Vim
12663 was compiled |+feature-list|. Example: >
12664 :if has("cindent")
12665< *gui_running*
126662. Features that are only supported when certain conditions have been met.
12667 Example: >
12668 :if has("gui_running")
12669< *has-patch*
126703. Beyond a certain version or at a certain version and including a specific
12671 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
12672 later, or it is version 7.4 and patch 248 was included. Example: >
12673 :if has("patch-7.4.248")
12674< Note that it's possible for patch 248 to be omitted even though 249 is
12675 included. Only happens when cherry-picking patches.
12676 Note that this form only works for patch 7.4.237 and later, before that
12677 you need to check for the patch and the v:version. Example (checking
12678 version 6.2.148 or later): >
12679 :if v:version > 602 || (v:version == 602 && has("patch148"))
12680
12681Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
12682use: `if exists('+shellslash')`
12683
12684
12685acl Compiled with |ACL| support.
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010012686all_builtin_terms Compiled with all builtin terminals enabled. (always
12687 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012688amiga Amiga version of Vim.
12689arabic Compiled with Arabic support |Arabic|.
12690arp Compiled with ARP support (Amiga).
12691autocmd Compiled with autocommand support. (always true)
12692autochdir Compiled with support for 'autochdir'
12693autoservername Automatically enable |clientserver|
12694balloon_eval Compiled with |balloon-eval| support.
12695balloon_multiline GUI supports multiline balloons.
12696beos BeOS version of Vim.
12697browse Compiled with |:browse| support, and browse() will
12698 work.
12699browsefilter Compiled with support for |browsefilter|.
12700bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010012701builtin_terms Compiled with some builtin terminals. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012702byte_offset Compiled with support for 'o' in 'statusline'
12703channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012704cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012705clientserver Compiled with remote invocation support |clientserver|.
12706clipboard Compiled with 'clipboard' support.
12707clipboard_working Compiled with 'clipboard' support and it can be used.
12708cmdline_compl Compiled with |cmdline-completion| support.
12709cmdline_hist Compiled with |cmdline-history| support.
12710cmdline_info Compiled with 'showcmd' and 'ruler' support.
12711comments Compiled with |'comments'| support.
12712compatible Compiled to be very Vi compatible.
12713conpty Platform where |ConPTY| can be used.
12714cryptv Compiled with encryption support |encryption|.
12715cscope Compiled with |cscope| support.
12716cursorbind Compiled with |'cursorbind'| (always true)
12717debug Compiled with "DEBUG" defined.
12718dialog_con Compiled with console dialog support.
glepnirdf461152024-04-04 22:23:29 +020012719dialog_con_gui Compiled with console and GUI dialog support.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012720dialog_gui Compiled with GUI dialog support.
12721diff Compiled with |vimdiff| and 'diff' support.
12722digraphs Compiled with support for digraphs.
12723directx Compiled with support for DirectX and 'renderoptions'.
12724dnd Compiled with support for the "~ register |quote_~|.
12725drop_file Compiled with |drop_file| support.
12726ebcdic Compiled on a machine with ebcdic character set.
12727emacs_tags Compiled with support for Emacs tags.
12728eval Compiled with expression evaluation support. Always
12729 true, of course!
12730ex_extra |+ex_extra| (always true)
12731extra_search Compiled with support for |'incsearch'| and
12732 |'hlsearch'|
12733farsi Support for Farsi was removed |farsi|.
Bram Moolenaarf80f40a2022-08-25 16:02:23 +010012734file_in_path Compiled with support for |gf| and |<cfile>| (always
12735 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012736filterpipe When 'shelltemp' is off pipes are used for shell
12737 read/write/filter commands
12738find_in_path Compiled with support for include file searches
12739 |+find_in_path|.
12740float Compiled with support for |Float|.
12741fname_case Case in file names matters (for Amiga and MS-Windows
12742 this is not present).
12743folding Compiled with |folding| support.
12744footer Compiled with GUI footer support. |gui-footer|
12745fork Compiled to use fork()/exec() instead of system().
12746gettext Compiled with message translation |multi-lang|
12747gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010012748gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012749gui_gnome Compiled with Gnome support (gui_gtk is also defined).
12750gui_gtk Compiled with GTK+ GUI (any version).
12751gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
12752gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
12753gui_haiku Compiled with Haiku GUI.
12754gui_mac Compiled with Macintosh GUI.
12755gui_motif Compiled with Motif GUI.
12756gui_photon Compiled with Photon GUI.
12757gui_running Vim is running in the GUI, or it will start soon.
12758gui_win32 Compiled with MS-Windows Win32 GUI.
12759gui_win32s idem, and Win32s system being used (Windows 3.1)
12760haiku Haiku version of Vim.
12761hangul_input Compiled with Hangul input support. |hangul|
12762hpux HP-UX version of Vim.
Zhaoming Luoa41dfcd2025-02-06 21:39:35 +010012763hurd GNU/Hurd version of Vim
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012764iconv Can use iconv() for conversion.
12765insert_expand Compiled with support for CTRL-X expansion commands in
12766 Insert mode. (always true)
12767job Compiled with support for |channel| and |job|
12768ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012769jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012770keymap Compiled with 'keymap' support.
12771lambda Compiled with |lambda| support.
12772langmap Compiled with 'langmap' support.
12773libcall Compiled with |libcall()| support.
12774linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
12775 'breakindent' support.
12776linux Linux version of Vim.
12777lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012778 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012779listcmds Compiled with commands for the buffer list |:files|
12780 and the argument list |arglist|.
12781localmap Compiled with local mappings and abbr. |:map-local|
12782lua Compiled with Lua interface |Lua|.
12783mac Any Macintosh version of Vim cf. osx
12784macunix Synonym for osxdarwin
12785menu Compiled with support for |:menu|.
12786mksession Compiled with support for |:mksession|.
12787modify_fname Compiled with file name modifiers. |filename-modifiers|
12788 (always true)
12789mouse Compiled with support for mouse.
12790mouse_dec Compiled with support for Dec terminal mouse.
12791mouse_gpm Compiled with support for gpm (Linux console mouse)
12792mouse_gpm_enabled GPM mouse is working
12793mouse_netterm Compiled with support for netterm mouse.
12794mouse_pterm Compiled with support for qnx pterm mouse.
12795mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
12796mouse_sgr Compiled with support for sgr mouse.
12797mouse_urxvt Compiled with support for urxvt mouse.
12798mouse_xterm Compiled with support for xterm mouse.
12799mouseshape Compiled with support for 'mouseshape'.
12800multi_byte Compiled with support for 'encoding' (always true)
12801multi_byte_encoding 'encoding' is set to a multibyte encoding.
12802multi_byte_ime Compiled with support for IME input method.
12803multi_lang Compiled with support for multiple languages.
12804mzscheme Compiled with MzScheme interface |mzscheme|.
12805nanotime Compiled with sub-second time stamp checks.
12806netbeans_enabled Compiled with support for |netbeans| and connected.
12807netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012808num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012809ole Compiled with OLE automation support for Win32.
12810osx Compiled for macOS cf. mac
12811osxdarwin Compiled for macOS, with |mac-darwin-feature|
12812packages Compiled with |packages| support.
12813path_extra Compiled with up/downwards search in 'path' and 'tags'
12814perl Compiled with Perl interface.
12815persistent_undo Compiled with support for persistent undo history.
12816postscript Compiled with PostScript file printing.
12817printer Compiled with |:hardcopy| support.
12818profile Compiled with |:profile| support.
Bram Moolenaar71badf92023-04-22 22:40:14 +010012819prof_nsec Profile results are in nanoseconds.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012820python Python 2.x interface available. |has-python|
12821python_compiled Compiled with Python 2.x interface. |has-python|
12822python_dynamic Python 2.x interface is dynamically loaded. |has-python|
12823python3 Python 3.x interface available. |has-python|
12824python3_compiled Compiled with Python 3.x interface. |has-python|
12825python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Yee Cheng Chinc13b3d12023-08-20 21:18:38 +020012826python3_stable Python 3.x interface is using Python Stable ABI. |has-python|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012827pythonx Python 2.x and/or 3.x interface available. |python_x|
12828qnx QNX version of Vim.
12829quickfix Compiled with |quickfix| support.
12830reltime Compiled with |reltime()| support.
12831rightleft Compiled with 'rightleft' support.
12832ruby Compiled with Ruby interface |ruby|.
12833scrollbind Compiled with 'scrollbind' support. (always true)
12834showcmd Compiled with 'showcmd' support.
12835signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012836smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012837sodium Compiled with libsodium for better crypt support
12838sound Compiled with sound support, e.g. `sound_playevent()`
12839spell Compiled with spell checking support |spell|.
12840startuptime Compiled with |--startuptime| support.
12841statusline Compiled with support for 'statusline', 'rulerformat'
12842 and special formats of 'titlestring' and 'iconstring'.
12843sun SunOS version of Vim.
12844sun_workshop Support for Sun |workshop| has been removed.
12845syntax Compiled with syntax highlighting support |syntax|.
12846syntax_items There are active syntax highlighting items for the
12847 current buffer.
12848system Compiled to use system() instead of fork()/exec().
12849tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012850 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012851tag_old_static Support for old static tags was removed, see
12852 |tag-old-static|.
12853tcl Compiled with Tcl interface.
12854termguicolors Compiled with true color in terminal support.
12855terminal Compiled with |terminal| support.
12856terminfo Compiled with terminfo instead of termcap.
12857termresponse Compiled with support for |t_RV| and |v:termresponse|.
12858textobjects Compiled with support for |text-objects|.
12859textprop Compiled with support for |text-properties|.
12860tgetent Compiled with tgetent support, able to use a termcap
12861 or terminfo file.
12862timers Compiled with |timer_start()| support.
12863title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010012864 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012865toolbar Compiled with support for |gui-toolbar|.
12866ttyin input is a terminal (tty)
12867ttyout output is a terminal (tty)
12868unix Unix version of Vim. *+unix*
12869unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
12870user_commands User-defined commands. (always true)
12871vartabs Compiled with variable tabstop support |'vartabstop'|.
12872vcon Win32: Virtual console support is working, can use
12873 'termguicolors'. Also see |+vtp|.
12874vertsplit Compiled with vertically split windows |:vsplit|.
12875 (always true)
12876vim_starting True while initial source'ing takes place. |startup|
12877 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000012878vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012879viminfo Compiled with viminfo support.
12880vimscript-1 Compiled Vim script version 1 support
12881vimscript-2 Compiled Vim script version 2 support
12882vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010012883vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012884virtualedit Compiled with 'virtualedit' option. (always true)
12885visual Compiled with Visual mode. (always true)
12886visualextra Compiled with extra Visual mode commands. (always
12887 true) |blockwise-operators|.
12888vms VMS version of Vim.
12889vreplace Compiled with |gR| and |gr| commands. (always true)
12890vtp Compiled for vcon support |+vtp| (check vcon to find
12891 out if it works in the current console).
12892wildignore Compiled with 'wildignore' option.
12893wildmenu Compiled with 'wildmenu' option.
12894win16 old version for MS-Windows 3.1 (always false)
12895win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
12896 64 bits)
12897win32unix Win32 version of Vim, using Unix files (Cygwin)
12898win64 Win64 version of Vim (MS-Windows 64 bit).
12899win95 Win32 version for MS-Windows 95/98/ME (always false)
12900winaltkeys Compiled with 'winaltkeys' option.
12901windows Compiled with support for more than one window.
12902 (always true)
12903writebackup Compiled with 'writebackup' default on.
Christian Brabandte085dfd2023-09-30 12:49:18 +020012904xattr Compiled with extended attributes support |xattr|
12905 (currently only supported on Linux).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000012906xfontset Compiled with X fontset support |xfontset|.
12907xim Compiled with X input method support |xim|.
12908xpm Compiled with pixmap support.
12909xpm_w32 Compiled with pixmap support for Win32. (Only for
12910 backward compatibility. Use "xpm" instead.)
12911xsmp Compiled with X session management support.
12912xsmp_interact Compiled with interactive X session management support.
12913xterm_clipboard Compiled with support for xterm clipboard.
12914xterm_save Compiled with support for saving and restoring the
12915 xterm screen.
12916x11 Compiled with X11 support.
12917
12918
12919==============================================================================
129204. Matching a pattern in a String *string-match*
12921
12922This is common between several functions. A regexp pattern as explained at
12923|pattern| is normally used to find a match in the buffer lines. When a
12924pattern is used to find a match in a String, almost everything works in the
12925same way. The difference is that a String is handled like it is one line.
12926When it contains a "\n" character, this is not seen as a line break for the
12927pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
12928>
12929 :let a = "aaaa\nxxxx"
12930 :echo matchstr(a, "..\n..")
12931 aa
12932 xx
12933 :echo matchstr(a, "a.x")
12934 a
12935 x
12936
12937Don't forget that "^" will only match at the first character of the String and
12938"$" at the last character of the string. They don't match after or before a
12939"\n".
12940
12941 vim:tw=78:ts=8:noet:ft=help:norl: