builtin.txt (501969B)
1 *builtin.txt* For Vim version 9.2. Last change: 2026 Sep 30 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 Builtin functions *builtin-functions* 8 9 Note: Expression evaluation can be disabled at compile time, the builtin 10 functions are not available then. See |+eval| and |no-eval-feature|. 11 12 For functions grouped by what they are used for see |function-list|. 13 14 1. Overview |builtin-function-list| 15 2. Details |builtin-function-details| 16 3. Feature list |feature-list| 17 4. Matching a pattern in a String |string-match| 18 19 ============================================================================== 20 1. Overview *builtin-function-list* 21 22 Use CTRL-] on the function name to jump to the full explanation. 23 24 USAGE RESULT DESCRIPTION ~ 25 26 abs({expr}) Float/Number 27 absolute value of {expr} 28 acos({expr}) Float arc cosine of {expr} 29 add({object}, {item}) List/Blob 30 append {item} to {object} 31 and({expr}, {expr}) Number bitwise AND 32 append({lnum}, {text}) Number append {text} below line {lnum} 33 appendbufline({buf}, {lnum}, {text}) 34 Number append {text} below line {lnum} 35 in buffer {buf} 36 argc([{winid}]) Number number of files in the argument list 37 argidx() Number current index in the argument list 38 arglistid([{winnr} [, {tabnr}]]) 39 Number argument list id 40 argv({nr} [, {winid}]) String {nr} entry of the argument list 41 argv([-1, {winid}]) List the argument list 42 asin({expr}) Float arc sine of {expr} 43 assert_beeps({cmd}) Number assert {cmd} causes a beep 44 assert_equal({exp}, {act} [, {msg}]) 45 Number assert {exp} is equal to {act} 46 assert_equalfile({fname-one}, {fname-two} [, {msg}]) 47 Number assert file contents are equal 48 assert_exception({error} [, {msg}]) 49 Number assert {error} is in |v:exception| 50 assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]]) 51 Number assert {cmd} fails 52 assert_false({actual} [, {msg}]) 53 Number assert {actual} is false 54 assert_inrange({lower}, {upper}, {actual} [, {msg}]) 55 Number assert {actual} is inside the range 56 assert_match({pat}, {text} [, {msg}]) 57 Number assert {pat} matches {text} 58 assert_nobeep({cmd}) Number assert {cmd} does not cause a beep 59 assert_notequal({exp}, {act} [, {msg}]) 60 Number assert {exp} is not equal {act} 61 assert_notmatch({pat}, {text} [, {msg}]) 62 Number assert {pat} not matches {text} 63 assert_report({msg}) Number report a test failure 64 assert_true({actual} [, {msg}]) Number assert {actual} is true 65 atan({expr}) Float arc tangent of {expr} 66 atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2} 67 autocmd_add({acmds}) Bool add a list of autocmds and groups 68 autocmd_delete({acmds}) Bool delete a list of autocmds and groups 69 autocmd_get([{opts}]) List return a list of autocmds 70 balloon_gettext() String current text in the balloon 71 balloon_show({expr}) none show {expr} inside the balloon 72 balloon_split({msg}) List split {msg} as used for a balloon 73 base64_decode({string}) Blob base64 decode {string} characters 74 base64_encode({blob}) String base64 encode the bytes in {blob} 75 bindtextdomain({package}, {path}) 76 Bool bind text domain to specified path 77 blob2list({blob}) List convert {blob} into a list of numbers 78 blob2str({blob} [, {options}]) List convert {blob} into a list of strings 79 browse({save}, {title}, {initdir}, {default}) 80 String put up a file requester 81 browsedir({title}, {initdir}) String put up a directory requester 82 bufadd({name}) Number add a buffer to the buffer list 83 bufexists({buf}) Number |TRUE| if buffer {buf} exists 84 buflisted({buf}) Number |TRUE| if buffer {buf} is listed 85 bufload({buf}) none load buffer {buf} if not loaded yet 86 bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded 87 bufname([{buf}]) String name of the buffer {buf} 88 bufnr([{buf} [, {create}]]) Number number of the buffer {buf} 89 bufwinid({buf}) Number window ID of buffer {buf} 90 bufwinnr({buf}) Number window number of buffer {buf} 91 byte2line({byte}) Number line number at byte count {byte} 92 byteidx({expr}, {nr} [, {utf16}]) 93 Number byte index of {nr}'th char in {expr} 94 byteidxcomp({expr}, {nr} [, {utf16}]) 95 Number byte index of {nr}'th char in {expr} 96 call({func}, {arglist} [, {dict}]) 97 any call {func} with arguments {arglist} 98 ceil({expr}) Float round {expr} up 99 ch_canread({handle}) Number check if there is something to read 100 ch_close({handle}) none close {handle} 101 ch_close_in({handle}) none close in part of {handle} 102 ch_evalexpr({handle}, {expr} [, {options}]) 103 any evaluate {expr} on JSON {handle} 104 ch_evalraw({handle}, {string} [, {options}]) 105 any evaluate {string} on raw {handle} 106 ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what} 107 ch_getjob({channel}) Job get the Job of {channel} 108 ch_info({handle}) Dict info about channel {handle} 109 ch_listen({address} [, {options}]) 110 Channel listen on {address} - port on loopback 111 or UNIX domain socket 112 ch_log({msg} [, {handle}]) none write {msg} in the channel log file 113 ch_logfile({fname} [, {mode}]) none start logging channel activity 114 ch_open({address} [, {options}]) 115 Channel open a channel to {address} 116 ch_read({handle} [, {options}]) String read from {handle} 117 ch_readblob({handle} [, {options}]) 118 Blob read Blob from {handle} 119 ch_readraw({handle} [, {options}]) 120 String read raw from {handle} 121 ch_sendexpr({handle}, {expr} [, {options}]) 122 any send {expr} over JSON {handle} 123 ch_sendraw({handle}, {expr} [, {options}]) 124 none send {expr} over raw {handle} 125 ch_setoptions({handle}, {options}) 126 none set options for {handle} 127 ch_status({handle} [, {options}]) 128 String status of channel {handle} 129 changenr() Number current change number 130 char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in 131 {expr} 132 charclass({string}) Number character class of {string} 133 charcol({expr} [, {winid}]) Number column number of cursor or mark 134 charidx({string}, {idx} [, {countcc} [, {utf16}]]) 135 Number char index of byte {idx} in {string} 136 chdir({dir} [, {scope}]) String change current working directory 137 cindent({lnum}) Number C indent for line {lnum} 138 clearmatches([{win}]) none clear all matches 139 cmdcomplete_info() Dict get current cmdline completion 140 information 141 col({expr} [, {winid}]) Number column byte index of cursor or mark 142 complete({startcol}, {matches}) none set Insert mode completion 143 complete_add({expr}) Number add completion match 144 complete_check() Number check for key typed during completion 145 complete_info([{what}]) Dict get current completion information 146 confirm({msg} [, {choices} [, {default} [, {type}]]]) 147 Number number of choice picked by user 148 copy({expr}) any make a shallow copy of {expr} 149 cos({expr}) Float cosine of {expr} 150 cosh({expr}) Float hyperbolic cosine of {expr} 151 count({comp}, {expr} [, {ic} [, {start}]]) 152 Number count how many {expr} are in {comp} 153 cscope_connection([{num}, {dbpath} [, {prepend}]]) 154 Number checks existence of cscope connection 155 cursor({lnum}, {col} [, {off}]) 156 Number move cursor to {lnum}, {col}, {off} 157 cursor({list}) Number move cursor to position in {list} 158 debugbreak({pid}) Number interrupt process being debugged 159 deepcopy({expr} [, {noref}]) any make a full copy of {expr} 160 delete({fname} [, {flags}]) Number delete the file or directory {fname} 161 deletebufline({buf}, {first} [, {last}]) 162 Number delete lines from buffer {buf} 163 did_filetype() Number |TRUE| if FileType autocmd event used 164 diff({fromlist}, {tolist} [, {options}]) 165 List diff two Lists of strings 166 diff_filler({lnum}) Number diff filler lines about {lnum} 167 diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col} 168 digraph_get({chars}) String get the |digraph| of {chars} 169 digraph_getlist([{listall}]) List get all |digraph|s 170 digraph_set({chars}, {digraph}) Bool register |digraph| 171 digraph_setlist({digraphlist}) Bool register multiple |digraph|s 172 echoraw({expr}) none output {expr} as-is 173 empty({expr}) Number |TRUE| if {expr} is empty 174 environ() Dict return environment variables 175 err_teapot([{expr}]) none give E418, or E503 if {expr} is |TRUE| 176 escape({string}, {chars}) String escape {chars} in {string} with '\' 177 eval({string}) any evaluate {string} into its value 178 eventhandler() Number |TRUE| if inside an event handler 179 executable({expr}) Number 1 if executable {expr} exists 180 execute({command} [, {silent}]) String execute {command} and get the output 181 exepath({expr}) String full path of the command {expr} 182 exists({expr}) Number |TRUE| if {expr} exists 183 exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time 184 exp({expr}) Float exponential of {expr} 185 expand({expr} [, {nosuf} [, {list}]]) 186 any expand special keywords in {expr} 187 expandcmd({string} [, {options}]) 188 String expand {string} like with `:edit` 189 extend({expr1}, {expr2} [, {expr3}]) 190 List/Dict/Blob 191 insert items of {expr2} into {expr1} 192 extendnew({expr1}, {expr2} [, {expr3}]) 193 List/Dict/Blob 194 like |extend()| but creates a new 195 List, Dictionary or Blob 196 feedkeys({string} [, {mode}]) none add key sequence to typeahead buffer 197 filecopy({from}, {to}) Number |TRUE| if copying file {from} to {to} 198 worked 199 filereadable({file}) Number |TRUE| if {file} is a readable file 200 filewritable({file}) Number |TRUE| if {file} is a writable file 201 filter({expr1}, {expr2}) List/Dict/Blob/String 202 remove items from {expr1} where 203 {expr2} is 0 204 finddir({name} [, {path} [, {count}]]) 205 findfile({name} [, {path} [, {count}]]) 206 String/List 207 find dir/file {name} in {path} 208 flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels 209 flattennew({list} [, {maxdepth}]) 210 List flatten a copy of {list} 211 float2nr({expr}) Number convert Float {expr} to a Number 212 floor({expr}) Float round {expr} down 213 fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2} 214 fnameescape({fname}) String escape special characters in {fname} 215 fnamemodify({fname}, {mods}) String modify file name 216 foldclosed({lnum} [, {winid}]) Number first line of fold at {lnum} if closed 217 foldclosedend({lnum} [, {winid}]) 218 Number last line of fold at {lnum} if closed 219 foldlevel({lnum} [, {winid}]) Number fold level at {lnum} 220 foldtext() String line displayed for closed fold 221 foldtextresult({lnum} [, {winid}]) 222 String text for closed fold at {lnum} 223 foreach({expr1}, {expr2}) List/Tuple/Dict/Blob/String 224 for each item in {expr1} call {expr2} 225 foreground() none bring the Vim window to the foreground 226 fullcommand({name} [, {vim9}]) String get full command from {name} 227 funcref({name} [, {arglist}] [, {dict}]) 228 Funcref reference to function {name} 229 function({name} [, {arglist}] [, {dict}]) 230 Funcref named reference to function {name} 231 garbagecollect([{atexit}]) none free memory, breaking cyclic 232 references 233 get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def} 234 get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def} 235 get({func}, {what}) any get property of funcref/partial {func} 236 getbgcolor() List get background colour as [r, g, b] 237 getbufinfo([{buf}]) List information about buffers 238 getbufline({buf}, {lnum} [, {end}]) 239 List lines {lnum} to {end} of buffer {buf} 240 getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf} 241 getbufvar({buf}, {varname} [, {def}]) 242 any variable {varname} in buffer {buf} 243 getcellpixels() List get character cell pixel size 244 getcellwidths() List get character cell width overrides 245 getchangelist([{buf}]) List list of change list items 246 getchar([{expr} [, {opts}]]) Number/String 247 get one character from the user 248 getcharmod() Number modifiers for the last typed character 249 getcharpos({expr}) List position of cursor, mark, etc. 250 getcharsearch() Dict last character search 251 getcharstr([{expr} [, {opts}]]) String get one character from the user 252 getcmdcomplpat() String return the completion pattern of the 253 current command-line completion 254 getcmdcompltype() String return the type of the current 255 command-line completion 256 getcmdline() String return the current command-line input 257 getcmdpos() Number return cursor position in command-line 258 getcmdprompt() String return the current command-line prompt 259 getcmdscreenpos() Number return cursor screen position in 260 command-line 261 getcmdtype() String return current command-line type 262 getcmdwintype() String return current command-line window 263 type 264 getcompletion({pat}, {type} [, {filtered}]) 265 List list of cmdline completion matches 266 getcompletiontype({pat}) String return the type of the command-line 267 completion using {pat} 268 getcurpos([{winnr}]) List position of the cursor 269 getcursorcharpos([{winnr}]) List character position of the cursor 270 getcwd([{winnr} [, {tabnr}]]) String get the current working directory 271 getenv({name}) String return environment variable 272 getfontname([{name}]) String name of font being used 273 getfperm({fname}) String file permissions of file {fname} 274 getfsize({fname}) Number size in bytes of file {fname} 275 getftime({fname}) Number last modification time of file 276 getftype({fname}) String description of type of file {fname} 277 getimstatus() Number |TRUE| if the IME status is active 278 getinfo({kind}, {name} [, {opts}]) 279 Dict the definition of {name} 280 getjumplist([{winnr} [, {tabnr}]]) 281 List list of jump list items 282 getline({lnum}) String line {lnum} of current buffer 283 getline({lnum}, {end}) List lines {lnum} to {end} of current 284 buffer 285 getloclist({nr}) List list of location list items 286 getloclist({nr}, {what}) Dict get specific location list properties 287 getmarklist([{buf}]) List list of global/local marks 288 getmatches([{win}]) List list of current matches 289 getmousepos() Dict last known mouse position 290 getmouseshape() String current mouse shape name 291 getpid() Number process ID of Vim 292 getpos({expr}) List position of cursor, mark, etc. 293 getqflist() List list of quickfix items 294 getqflist({what}) Dict get specific quickfix list properties 295 getreg([{regname} [, 1 [, {list}]]]) 296 String/List 297 contents of a register 298 getreginfo([{regname}]) Dict information about a register 299 getregion({pos1}, {pos2} [, {opts}]) 300 List get the text from {pos1} to {pos2} 301 getregionpos({pos1}, {pos2} [, {opts}]) 302 List get a list of positions for a region 303 getregtype([{regname}]) String type of a register 304 getscriptinfo([{opts}]) List list of sourced scripts 305 getstacktrace() List get current stack trace of Vim scripts 306 gettabinfo([{expr}]) List list of tab pages 307 gettabvar({nr}, {varname} [, {def}]) 308 any variable {varname} in tab {nr} or 309 {def} 310 gettabwinvar({tabnr}, {winnr}, {name} [, {def}]) 311 any {name} in {winnr} in tab page {tabnr} 312 gettagstack([{nr}]) Dict get the tag stack of window {nr} 313 gettext({text} [, {package}]) String lookup translation of {text} 314 getwininfo([{winid}]) List list of info about each window 315 getwinpos([{timeout}]) List X and Y coord in pixels of Vim window 316 getwinposx() Number X coord in pixels of the Vim window 317 getwinposy() Number Y coord in pixels of the Vim window 318 getwinvar({nr}, {varname} [, {def}]) 319 any variable {varname} in window {nr} 320 glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) 321 any expand file wildcards in {expr} 322 glob2regpat({expr}) String convert a glob pat into a search pat 323 globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) 324 String do glob({expr}) for all dirs in {path} 325 has({feature} [, {check}]) Number |TRUE| if feature {feature} supported 326 has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key} 327 haslocaldir([{winnr} [, {tabnr}]]) 328 Number |TRUE| if the window executed `:lcd` or 329 `:tcd` 330 hasmapto({what} [, {mode} [, {abbr}]]) 331 Number |TRUE| if mapping to {what} exists 332 histadd({history}, {item}) Number add an item to a history 333 histdel({history} [, {item}]) Number remove an item from a history 334 histget({history} [, {index}]) String get the item {index} from a history 335 histnr({history}) Number highest index of a history 336 hlID({name}) Number syntax ID of highlight group {name} 337 hlexists({name}) Number |TRUE| if highlight group {name} exists 338 hlget([{name} [, {resolve}]]) List get highlight group attributes 339 hlset({list}) Number set highlight group attributes 340 hostname() String name of the machine Vim is running on 341 iconv({expr}, {from}, {to}) String convert encoding of {expr} 342 id({item}) String get unique identity string of item 343 image_add({dict}) Number Add an image and return handle to it 344 image_discard({id}) none Discard an image handle 345 image_info([{id}]) List Get information about an image 346 indent({lnum}) Number indent of line {lnum} 347 index({object}, {expr} [, {start} [, {ic}]]) 348 Number index in {object} where {expr} appears 349 indexof({object}, {expr} [, {opts}]) 350 Number index in {object} where {expr} is true 351 input({prompt} [, {text} [, {completion}]]) 352 String get input from the user 353 inputdialog({prompt} [, {text} [, {cancelreturn}]]) 354 String like input() but in a GUI dialog 355 inputlist({textlist}) Number let the user pick from a choice list 356 inputrestore() Number restore typeahead 357 inputsave() Number save and clear typeahead 358 inputsecret({prompt} [, {text}]) 359 String like input() but hiding the text 360 insert({object}, {item} [, {idx}]) 361 List insert {item} in {object} 362 [before {idx}] 363 instanceof({object}, {class} ...) 364 Bool |TRUE| if {object} is an instance of 365 {class} 366 interrupt() none interrupt script execution 367 invert({expr}) Number bitwise invert 368 isabsolutepath({path}) Number |TRUE| if {path} is an absolute path 369 isdirectory({directory}) Number |TRUE| if {directory} is a directory 370 isinf({expr}) Number determine if {expr} is infinity value 371 (positive or negative) 372 islocked({expr}) Number |TRUE| if {expr} is locked 373 isnan({expr}) Number |TRUE| if {expr} is NaN 374 items({expr}) List key/index-value pairs in {expr} 375 job_getchannel({job}) Channel get the channel handle for {job} 376 job_info([{job}]) Dict get information about {job} 377 job_setoptions({job}, {options}) 378 none set options for {job} 379 job_start({command} [, {options}]) 380 Job start a job 381 job_status({job}) String get the status of {job} 382 job_stop({job} [, {how}]) Number stop {job} 383 join({expr} [, {sep}]) String join items in {expr} into one String 384 js_decode({string}) any decode JS style JSON 385 js_encode({expr}) String encode JS style JSON 386 json_decode({string}) any decode JSON 387 json_encode({expr}) String encode JSON 388 keys({dict}) List keys in {dict} 389 keytrans({string}) String translate internal keycodes to a form 390 that can be used by `:map` 391 len({expr}) Number the length of {expr} 392 libcall({lib}, {func}, {arg}) String call {func} in library {lib} with 393 {arg} 394 libcallnr({lib}, {func}, {arg}) Number idem, but return a Number 395 line({expr} [, {winid}]) Number line nr of cursor, last line or mark 396 line2byte({lnum}) Number byte count of line {lnum} 397 lispindent({lnum}) Number Lisp indent for line {lnum} 398 list2blob({list}) Blob turn {list} of numbers into a Blob 399 list2str({list} [, {utf8}]) String turn {list} of numbers into a String 400 list2tuple({list}) Tuple turn {list} of items into a tuple 401 listener_add({callback} [, {buf} [, {options}]]) 402 Number add a callback to listen to changes 403 listener_flush([{buf}]) none invoke listener callbacks 404 listener_remove({id}) Number remove a listener callback 405 localtime() Number current time 406 log({expr}) Float natural logarithm (base e) of {expr} 407 log10({expr}) Float logarithm of Float {expr} to base 10 408 luaeval({expr} [, {expr}]) any evaluate |Lua| expression 409 map({expr1}, {expr2}) List/Dict/Blob/String 410 change each item in {expr1} to {expr2} 411 maparg({name} [, {mode} [, {abbr} [, {dict}]]]) 412 String/Dict 413 rhs of mapping {name} in mode {mode} 414 mapcheck({name} [, {mode} [, {abbr}]]) 415 String check for mappings matching {name} 416 maplist([{abbr}]) List list of all mappings, a dict for each 417 mapnew({expr1}, {expr2}) List/Dict/Blob/String 418 like |map()| but creates a new List or 419 Dictionary 420 mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result 421 mapset({dict}) none restore mapping from |maparg()| result 422 match({expr}, {pat} [, {start} [, {count}]]) 423 Number position where {pat} matches in {expr} 424 matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) 425 Number highlight {pattern} with {group} 426 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) 427 Number highlight positions with {group} 428 matcharg({nr}) List arguments of `:match` 429 matchbufline({buf}, {pat}, {lnum}, {end} [, {dict}]) 430 List all the {pat} matches in buffer {buf} 431 matchdelete({id} [, {win}]) Number delete match identified by {id} 432 matchend({expr}, {pat} [, {start} [, {count}]]) 433 Number position where {pat} ends in {expr} 434 matchfuzzy({list}, {str} [, {dict}]) 435 List fuzzy match {str} in {list} 436 matchfuzzypos({list}, {str} [, {dict}]) 437 List fuzzy match {str} in {list} 438 matchlist({expr}, {pat} [, {start} [, {count}]]) 439 List match and submatches of {pat} in 440 {expr} 441 matchstr({expr}, {pat} [, {start} [, {count}]]) 442 String {count}'th match of {pat} in {expr} 443 matchstrlist({list}, {pat} [, {dict}]) 444 List all the {pat} matches in {list} 445 matchstrpos({expr}, {pat} [, {start} [, {count}]]) 446 List {count}'th match of {pat} in {expr} 447 max({expr}) Number maximum value of items in {expr} 448 menu_info({name} [, {mode}]) Dict get menu item information 449 min({expr}) Number minimum value of items in {expr} 450 mkdir({name} [, {flags} [, {prot}]]) 451 Number create directory {name} 452 mode([{expr}]) String current editing mode 453 mzeval({expr}) any evaluate |MzScheme| expression 454 nextnonblank({lnum}) Number line nr of non-blank line >= {lnum} 455 ngettext({single}, {plural}, {number} [, {domain}]) 456 String translate text based on {number} 457 nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value 458 {expr} 459 or({expr}, {expr}) Number bitwise OR 460 pathshorten({expr} [, {len}]) String shorten directory names in a path 461 perleval({expr}) any evaluate |Perl| expression 462 popup_atcursor({what}, {options}) 463 Number create popup window near the cursor 464 popup_beval({what}, {options}) Number create popup window for 'ballooneval' 465 popup_clear([{force}]) none close all popup windows 466 popup_close({id} [, {result}]) none close popup window {id} 467 popup_create({what}, {options}) Number create a popup window 468 popup_dialog({what}, {options}) Number create a popup window used as a dialog 469 popup_filter_menu({id}, {key}) Bool filter for a menu popup window 470 popup_filter_yesno({id}, {key}) Bool filter for a dialog popup window 471 popup_findecho() Number get window ID of popup for `:echowin` 472 popup_findinfo() Number get window ID of info popup window 473 popup_findpreview() Number get window ID of preview popup window 474 popup_getoptions({id}) Dict get options of popup window {id} 475 popup_getpos({id}) Dict get position of popup window {id} 476 popup_hide({id}) none hide popup menu {id} 477 popup_list() List get a list of window IDs of all popups 478 popup_locate({row}, {col}) Number get window ID of popup at position 479 popup_menu({what}, {options}) Number create a popup window used as a menu 480 popup_move({id}, {options}) none set position of popup window {id} 481 popup_notification({what}, {options}) 482 Number create a notification popup window 483 popup_setbuf({id}, {buf}) Bool set the buffer for the popup window 484 {id} 485 popup_setoptions({id}, {options}) 486 none set options for popup window {id} 487 popup_settext({id}, {text}) none set the text of popup window {id} 488 popup_show({id}) Number unhide popup window {id} 489 pow({x}, {y}) Float {x} to the power of {y} 490 preinserted() Number whether text is inserted after cursor 491 prevnonblank({lnum}) Number line nr of non-blank line <= {lnum} 492 printf({fmt} [, {expr1} ...]) String format text 493 prompt_getprompt({buf}) String get prompt text 494 prompt_setcallback({buf}, {expr}) 495 none set prompt callback function 496 prompt_setinterrupt({buf}, {text}) 497 none set prompt interrupt function 498 prompt_setprompt({buf}, {text}) none set prompt text 499 prop_add({lnum}, {col}, {props}) 500 Number add one text property 501 prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) 502 none add multiple text properties 503 prop_clear({lnum} [, {lnum-end} [, {props}]]) 504 none remove all text properties 505 prop_find({props} [, {direction}]) 506 Dict search for a text property 507 prop_list({lnum} [, {props}]) List text properties in {lnum} 508 prop_remove({props} [, {lnum} [, {lnum-end}]]) 509 Number remove a text property 510 prop_type_add({name}, {props}) none define a new property type 511 prop_type_change({name}, {props}) 512 none change an existing property type 513 prop_type_delete({name} [, {props}]) 514 none delete a property type 515 prop_type_get({name} [, {props}]) 516 Dict get property type values 517 prop_type_list([{props}]) List get list of property types 518 pum_getpos() Dict position and size of pum if visible 519 pumvisible() Number whether popup menu is visible 520 py3eval({expr} [, {locals}]) any evaluate |python3| expression 521 pyeval({expr} [, {locals}]) any evaluate |Python| expression 522 pyxeval({expr} [, {locals}]) any evaluate |python_x| expression 523 rand([{expr}]) Number get pseudo-random number 524 range({expr} [, {max} [, {stride}]]) 525 List items from {expr} to {max} 526 readblob({fname} [, {offset} [, {size}]]) 527 Blob read a |Blob| from {fname} 528 readdir({dir} [, {expr} [, {dict}]]) 529 List file names in {dir} selected by {expr} 530 readdirex({dir} [, {expr} [, {dict}]]) 531 List file info in {dir} selected by {expr} 532 readfile({fname} [, {type} [, {max}]]) 533 List get list of lines from file {fname} 534 redraw_listener_add({opts}) Number add callbacks to listen for redraws 535 redraw_listener_remove({id}) none remove a redraw listener 536 reduce({object}, {func} [, {initial}]) 537 any reduce {object} using {func} 538 reg_executing() String get the executing register name 539 reg_recording() String get the recording register name 540 reltime([{start} [, {end}]]) List get time value 541 reltimefloat({time}) Float turn the time value into a Float 542 reltimestr({time}) String turn time value into a String 543 remote_expr({server}, {string} [, {idvar} [, {timeout}]]) 544 String send expression 545 remote_foreground({server}) none bring Vim server to the foreground 546 remote_peek({serverid} [, {retvar}]) 547 Number check for reply string 548 remote_read({serverid} [, {timeout}]) 549 String read reply string 550 remote_send({server}, {string} [, {idvar}]) 551 String send key sequence 552 remote_startserver({name}) none become server {name} 553 remove({list}, {idx} [, {end}]) any/List 554 remove items {idx}-{end} from {list} 555 remove({blob}, {idx} [, {end}]) Number/Blob 556 remove bytes {idx}-{end} from {blob} 557 remove({dict}, {key}) any remove entry {key} from {dict} 558 rename({from}, {to}) Number rename (move) file from {from} to {to} 559 repeat({expr}, {count}) List/Tuple/Blob/String 560 repeat {expr} {count} times 561 resolve({filename}) String get filename a shortcut points to 562 reverse({obj}) List/Tuple/Blob/String 563 reverse {obj} 564 round({expr}) Float round off {expr} 565 rubyeval({expr}) any evaluate |Ruby| expression 566 screenattr({row}, {col}) Number attribute at screen position 567 screenchar({row}, {col}) Number character at screen position 568 screenchars({row}, {col}) List list of characters at screen position 569 screencol() Number current cursor column 570 screenpos({winid}, {lnum}, {col}) 571 Dict screen row and col of a text character 572 screenrow() Number current cursor row 573 screenstring({row}, {col}) String characters at screen position 574 search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) 575 Number search for {pattern} 576 searchcount([{options}]) Dict get or update search stats 577 searchdecl({name} [, {global} [, {thisblock}]]) 578 Number search for variable declaration 579 searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) 580 Number search for other end of start/end pair 581 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) 582 List search for other end of start/end pair 583 searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) 584 List search for {pattern} 585 server2client({clientid}, {string}) 586 Number send reply string 587 serverlist([{dict}]) String get a list of available servers 588 setbufline({buf}, {lnum}, {text}) 589 Number set line {lnum} to {text} in buffer 590 {buf} 591 setbufvar({buf}, {varname}, {val}) 592 none set {varname} in buffer {buf} to {val} 593 setcellwidths({list}) none set character cell width overrides 594 setcharpos({expr}, {list}) Number set the {expr} position to {list} 595 setcharsearch({dict}) none set character search from {dict} 596 setcmdline({str} [, {pos}]) Number set command-line 597 setcmdpos({pos}) Number set cursor position in command-line 598 setcursorcharpos({lnum}, {col} [, {off}]) 599 Number move cursor to {lnum}, {col}, {off} 600 setcursorcharpos({list}) Number move cursor to position in {list} 601 setenv({name}, {val}) none set environment variable 602 setfperm({fname}, {mode}) Number set {fname} file permissions to {mode} 603 setline({lnum}, {line}) Number set line {lnum} to {line} 604 setloclist({nr}, {list} [, {action}]) 605 Number modify location list using {list} 606 setloclist({nr}, {list}, {action}, {what}) 607 Number modify specific location list props 608 setmatches({list} [, {win}]) Number restore a list of matches 609 setpos({expr}, {list}) Number set the {expr} position to {list} 610 setqflist({list} [, {action}]) Number modify quickfix list using {list} 611 setqflist({list}, {action}, {what}) 612 Number modify specific quickfix list props 613 setreg({n}, {v} [, {opt}]) Number set register to value and type 614 settabvar({nr}, {varname}, {val}) 615 none set {varname} in tab page {nr} to 616 {val} 617 settabwinvar({tabnr}, {winnr}, {varname}, {val}) 618 none set {varname} in window {winnr} in tab 619 page {tabnr} to {val} 620 settagstack({nr}, {dict} [, {action}]) 621 Number modify tag stack using {dict} 622 setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val} 623 sha256({expr}) String SHA256 checksum of String or Blob 624 shellescape({string} [, {special}]) 625 String escape {string} for use as shell 626 command argument 627 shiftwidth([{col}]) Number effective value of 'shiftwidth' 628 sign_define({name} [, {dict}]) Number define or update a sign 629 sign_define({list}) List define or update a list of signs 630 sign_getdefined([{name}]) List get a list of defined signs 631 sign_getplaced([{buf} [, {dict}]]) 632 List get a list of placed signs 633 sign_jump({id}, {group}, {buf}) 634 Number jump to a sign 635 sign_place({id}, {group}, {name}, {buf} [, {dict}]) 636 Number place a sign 637 sign_placelist({list}) List place a list of signs 638 sign_undefine([{name}]) Number undefine a sign 639 sign_undefine({list}) List undefine a list of signs 640 sign_unplace({group} [, {dict}]) 641 Number unplace a sign 642 sign_unplacelist({list}) List unplace a list of signs 643 simplify({filename}) String simplify filename as much as possible 644 sin({expr}) Float sine of {expr} 645 sinh({expr}) Float hyperbolic sine of {expr} 646 slice({expr}, {start} [, {end}]) 647 String/List/Blob/Tuple 648 slice of a String, List, Blob or Tuple 649 sort({list} [, {how} [, {dict}]]) 650 List sort {list}, compare with {how} 651 sound_clear() none stop playing all sounds 652 sound_playevent({name} [, {callback}]) 653 Number play an event sound 654 sound_playfile({path} [, {callback}]) 655 Number play sound file {path} 656 sound_stop({id}) none stop playing sound {id} 657 soundfold({word}) String sound-fold {word} 658 spellbadword([{sentence}]) List badly spelled word at cursor 659 spellsuggest({word} [, {max} [, {capital}]]) 660 List spelling suggestions 661 split({expr} [, {pat} [, {keepempty}]]) 662 List make |List| from {pat} separated {expr} 663 sqrt({expr}) Float square root of {expr} 664 srand([{expr}]) List get seed for |rand()| 665 state([{what}]) String current state of Vim 666 str2blob({list} [, {options}]) Blob convert list of strings into a Blob 667 str2float({expr} [, {quoted}]) Float convert String to Float 668 str2list({expr} [, {utf8}]) List convert each character of {expr} to 669 ASCII/UTF-8 value 670 str2nr({expr} [, {base} [, {quoted}]]) 671 Number convert String to Number 672 strcharlen({expr}) Number character length of the String {expr} 673 strcharpart({str}, {start} [, {len} [, {skipcc}]]) 674 String {len} characters of {str} at 675 character {start} 676 strchars({expr} [, {skipcc}]) Number character count of the String {expr} 677 strdisplaywidth({expr} [, {col}]) 678 Number display length of the String {expr} 679 strftime({format} [, {time}]) String format time with a specified format 680 strgetchar({str}, {index}) Number get char {index} from {str} 681 stridx({haystack}, {needle} [, {start}]) 682 Number index of {needle} in {haystack} 683 string({expr}) String String representation of {expr} value 684 strlen({expr}) Number length of the String {expr} 685 strpart({str}, {start} [, {len} [, {chars}]]) 686 String {len} bytes/chars of {str} at byte 687 {start} 688 strptime({format}, {timestring}) 689 Number convert {timestring} to unix timestamp 690 strridx({haystack}, {needle} [, {start}]) 691 Number last index of {needle} in {haystack} 692 strtrans({expr}) String translate string to make it printable 693 strutf16len({string} [, {countcc}]) 694 Number number of UTF-16 code units in 695 {string} 696 strwidth({expr}) Number display cell length of the String 697 {expr} 698 submatch({nr} [, {list}]) String/List 699 specific match in `:substitute` or 700 substitute() 701 substitute({expr}, {pat}, {sub}, {flags}) 702 String all {pat} in {expr} replaced with 703 {sub} 704 swapfilelist() List swap files found in 'directory' 705 swapinfo({fname}) Dict information about swap file {fname} 706 swapname({buf}) String swap file of buffer {buf} 707 synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col} 708 synIDattr({synID}, {what} [, {mode}]) 709 String attribute {what} of syntax ID {synID} 710 synIDtrans({synID}) Number translated syntax ID of {synID} 711 synconcealed({lnum}, {col}) List info about concealing 712 synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and 713 {col} 714 system({expr} [, {input}]) String output of shell command/filter {expr} 715 systemlist({expr} [, {input}]) List output of shell command/filter {expr} 716 tabpagebuflist([{arg}]) List list of buffer numbers in tab page 717 tabpagenr([{arg}]) Number number of current or last tab page 718 tabpagewinnr({tabarg} [, {arg}]) 719 Number number of current window in tab page 720 tabpanel_getinfo() Dict get current state of the tabpanel 721 tabpanel_scroll({n} [, {opts}]) Bool scroll the tabpanel 722 tagfiles() List tags files used 723 taglist({expr} [, {filename}]) List list of tags matching {expr} 724 tan({expr}) Float tangent of {expr} 725 tanh({expr}) Float hyperbolic tangent of {expr} 726 tempname() String name for a temporary file 727 term_dumpdiff({filename}, {filename} [, {options}]) 728 Number display difference between two dumps 729 term_dumpload({filename} [, {options}]) 730 Number displaying a screen dump 731 term_dumpwrite({buf}, {filename} [, {options}]) 732 none dump terminal window contents 733 term_getaltscreen({buf}) Number get the alternate screen flag 734 term_getansicolors({buf}) List get ANSI palette in GUI color mode 735 term_getattr({attr}, {what}) Number get the value of attribute {what} 736 term_getcursor({buf}) List get the cursor position of a terminal 737 term_getjob({buf}) Job get the job associated with a terminal 738 term_getline({buf}, {row}) String get a line of text from a terminal 739 term_getscrolled({buf}) Number get the scroll count of a terminal 740 term_getsize({buf}) List get the size of a terminal 741 term_getstatus({buf}) String get the status of a terminal 742 term_gettitle({buf}) String get the title of a terminal 743 term_gettty({buf} [, {input}]) String get the tty name of a terminal 744 term_list() List get the list of terminal buffers 745 term_scrape({buf}, {row}) List get row of a terminal screen 746 term_sendkeys({buf}, {keys}) none send keystrokes to a terminal 747 term_setansicolors({buf}, {colors}) 748 none set ANSI palette in GUI color mode 749 term_setapi({buf}, {expr}) none set |terminal-api| function name prefix 750 term_setkill({buf}, {how}) none set signal to stop job in terminal 751 term_setrestore({buf}, {command}) 752 none set command to restore terminal 753 term_setsize({buf}, {rows}, {cols}) 754 none set the size of a terminal 755 term_start({cmd} [, {options}]) Number open a terminal window and run a job 756 term_wait({buf} [, {time}]) none wait for screen to be updated 757 terminalprops() Dict properties of the terminal 758 test_alloc_fail({id}, {countdown}, {repeat}) 759 none make memory allocation fail 760 test_autochdir() none enable 'autochdir' during startup 761 test_feedinput({string}) none add key sequence to input buffer 762 test_garbagecollect_now() none free memory right now for testing 763 test_garbagecollect_soon() none free memory soon for testing 764 test_getvalue({string}) Number get value of an internal variable 765 test_gui_event({event}, {args}) bool generate a GUI event for testing 766 test_ignore_error({expr}) none ignore a specific error 767 test_mswin_event({event}, {args}) 768 Bool generate MS-Windows event for testing 769 test_null_blob() Blob null value for testing 770 test_null_channel() Channel null value for testing 771 test_null_dict() Dict null value for testing 772 test_null_function() Funcref null value for testing 773 test_null_job() Job null value for testing 774 test_null_list() List null value for testing 775 test_null_partial() Funcref null value for testing 776 test_null_string() String null value for testing 777 test_null_tuple() Tuple null value for testing 778 test_option_not_set({name}) none reset flag indicating option was set 779 test_override({expr}, {val}) none test with Vim internal overrides 780 test_refcount({expr}) Number get the reference count of {expr} 781 test_setmouse({row}, {col}) none set the mouse position for testing 782 test_settime({expr}) none set current time for testing 783 test_srand_seed([{seed}]) none set seed for testing srand() 784 test_unknown() any unknown value for testing 785 test_void() none void value for testing 786 timer_info([{id}]) List information about timers 787 timer_pause({id}, {pause}) none pause or unpause a timer 788 timer_start({time}, {callback} [, {options}]) 789 Number create a timer 790 timer_stop({timer}) none stop a timer 791 timer_stopall() none stop all timers 792 tolower({expr}) String the String {expr} switched to 793 lowercase 794 toupper({expr}) String the String {expr} switched to 795 uppercase 796 tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr} 797 to chars in {tostr} 798 trim({text} [, {mask} [, {dir}]]) 799 String trim characters in {mask} from {text} 800 trunc({expr}) Float truncate Float {expr} 801 tuple2list({tuple}) List turn {tuple} of items into a list 802 type({expr}) Number type of value {expr} 803 typename({expr}) String representation of the type of {expr} 804 undofile({name}) String undo file name for {name} 805 undotree([{buf}]) Dict undo file tree for buffer {buf} 806 uniq({list} [, {func} [, {dict}]]) 807 List remove adjacent duplicates from a list 808 uri_decode({string}) String URI-decode a string 809 uri_encode({string}) String URI-encode a string 810 utf16idx({string}, {idx} [, {countcc} [, {charidx}]]) 811 Number UTF-16 index of byte {idx} in {string} 812 values({dict}) List values in {dict} 813 virtcol({expr} [, {list} [, {winid}]]) 814 Number/List 815 screen column of cursor or mark 816 virtcol2col({winid}, {lnum}, {col}) 817 Number byte index of a character on screen 818 visualmode([{expr}]) String last visual mode used 819 wildmenumode() Number whether 'wildmenu' mode is active 820 wildtrigger() none start wildcard expansion 821 win_execute({id}, {command} [, {silent}]) 822 String execute {command} in window {id} 823 win_findbuf({bufnr}) List find windows containing {bufnr} 824 win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab} 825 win_gettype([{nr}]) String type of window {nr} 826 win_gotoid({expr}) Number go to window with ID {expr} 827 win_id2tabwin({expr}) List get tab and window nr from window ID 828 win_id2win({expr}) Number get window nr from window ID 829 win_move_separator({nr}, {offset}) 830 Number move window vertical separator 831 win_move_statusline({nr}, {offset}) 832 Number move window status line 833 win_screenpos({nr}) List get screen position of window {nr} 834 win_splitmove({nr}, {target} [, {options}]) 835 Number move window {nr} to split of {target} 836 winbufnr({nr}) Number buffer number of window {nr} 837 wincol() Number window column of the cursor 838 windowsversion() String MS-Windows OS version 839 winheight({nr}) Number height of window {nr} 840 winlayout([{tabnr}]) List layout of windows in tab {tabnr} 841 winline() Number window line of the cursor 842 winnr([{expr}]) Number number of current window 843 winrestcmd() String returns command to restore window 844 sizes 845 winrestview({dict}) none restore view of current window 846 winsaveview() Dict save view of current window 847 winwidth({nr}) Number width of window {nr} 848 wordcount() Dict get byte/char/word statistics 849 writefile({object}, {fname} [, {flags}]) 850 Number write |Blob| or |List| of lines to file 851 xor({expr}, {expr}) Number bitwise XOR 852 853 ============================================================================== 854 2. Details *builtin-function-details* 855 856 Not all functions are here, some have been moved to a help file covering the 857 specific functionality. 858 Return type specifies the type for |Vim9-script|, see |vim9-types| 859 860 abs({expr}) *abs()* 861 Return the absolute value of {expr}. When {expr} evaluates to 862 a |Float| abs() returns a |Float|. When {expr} can be 863 converted to a |Number| abs() returns a |Number|. Otherwise 864 abs() gives an error message and returns -1. 865 Examples: > 866 echo abs(1.456) 867 < 1.456 > 868 echo abs(-5.456) 869 < 5.456 > 870 echo abs(-4) 871 < 4 872 873 Can also be used as a |method|: > 874 Compute()->abs() 875 < 876 Return type: |Number| or |Float| depending on {expr} 877 878 879 acos({expr}) *acos()* 880 Return the arc cosine of {expr} measured in radians, as a 881 |Float| in the range of [0, pi]. 882 {expr} must evaluate to a |Float| or a |Number| in the range 883 [-1, 1]. Otherwise acos() returns "nan". 884 Examples: > 885 :echo acos(0) 886 < 1.570796 > 887 :echo acos(-0.5) 888 < 2.094395 889 890 Can also be used as a |method|: > 891 Compute()->acos() 892 < 893 Return type: |Float| 894 895 896 add({object}, {expr}) *add()* 897 Append the item {expr} to |List| or |Blob| {object}. Returns 898 the resulting |List| or |Blob|. Examples: > 899 :let alist = add([1, 2, 3], item) 900 :call add(mylist, "woodstock") 901 < Note that when {expr} is a |List| it is appended as a single 902 item. Use |extend()| to concatenate |Lists|. 903 When {object} is a |Blob| then {expr} must be a number. 904 Use |insert()| to add an item at another position. 905 Returns 1 if {object} is not a |List| or a |Blob|. 906 907 Can also be used as a |method|: > 908 mylist->add(val1)->add(val2) 909 < 910 Return type: list<{type}> (depending on the given |List|) or 911 |Blob| 912 913 914 and({expr}, {expr}) *and()* 915 Bitwise AND on the two arguments. The arguments are converted 916 to a number. A List, Dict or Float argument causes an error. 917 Also see |or()| and |xor()|. 918 Example: > 919 :let flag = and(bits, 0x80) 920 < Can also be used as a |method|: > 921 :let flag = bits->and(0x80) 922 < 923 Return type: |Number| 924 925 926 append({lnum}, {text}) *append()* 927 When {text} is a |List|: Append each item of the |List| as a 928 text line below line {lnum} in the current buffer. 929 Otherwise append {text} as one text line below line {lnum} in 930 the current buffer. 931 Any type of item is accepted and converted to a String. 932 {lnum} can be zero to insert a line before the first one. 933 {lnum} is used like with |getline()|. 934 Returns 1 for failure ({lnum} out of range or out of memory), 935 0 for success. When {text} is an empty list zero is returned, 936 no matter the value of {lnum}. 937 In |Vim9| script an invalid argument or negative number 938 results in an error. Example: > 939 :let failed = append(line('$'), "# THE END") 940 :let failed = append(0, ["Chapter 1", "the beginning"]) 941 942 < Can also be used as a |method| after a List, the base is 943 passed as the second argument: > 944 mylist->append(lnum) 945 < 946 Return type: |Number| 947 948 949 appendbufline({buf}, {lnum}, {text}) *appendbufline()* 950 Like |append()| but append the text in buffer {buf}. 951 952 This function works only for loaded buffers. First call 953 |bufload()| if needed. 954 955 For the use of {buf}, see |bufname()|. 956 957 {lnum} is the line number to append below. Note that using 958 |line()| would use the current buffer, not the one appending 959 to. Use "$" to append at the end of the buffer. Other string 960 values are not supported. 961 962 On success 0 is returned, on failure 1 is returned. 963 In |Vim9| script an error is given for an invalid {lnum}. 964 965 If {buf} is not a valid buffer or {lnum} is not valid, an 966 error message is given. Example: > 967 :let failed = appendbufline(13, 0, "# THE START") 968 < However, when {text} is an empty list then no error is given 969 for an invalid {lnum}, since {lnum} isn't actually used. 970 971 Can also be used as a |method| after a List, the base is 972 passed as the third argument: > 973 mylist->appendbufline(buf, lnum) 974 < 975 Return type: |Number| 976 977 978 argc([{winid}]) *argc()* 979 The result is the number of files in the argument list. See 980 |arglist|. 981 If {winid} is not supplied, the argument list of the current 982 window is used. 983 If {winid} is -1, the global argument list is used. 984 Otherwise {winid} specifies the window of which the argument 985 list is used: either the window number or the window ID. 986 Returns -1 if the {winid} argument is invalid. 987 988 Return type: |Number| 989 990 991 argidx() *argidx()* 992 The result is the current index in the argument list. 0 is 993 the first file. |argc()| - 1 is the last one. See |arglist|. 994 995 Return type: |Number| 996 997 998 arglistid([{winnr} [, {tabnr}]]) *arglistid()* 999 Return the argument list ID. This is a number which 1000 identifies the argument list being used. Zero is used for the 1001 global argument list. See |arglist|. 1002 Returns -1 if the arguments are invalid. 1003 1004 Without arguments use the current window. 1005 With {winnr} only use this window in the current tab page. 1006 With {winnr} and {tabnr} use the window in the specified tab 1007 page. 1008 {winnr} can be the window number or the |window-ID|. 1009 1010 Return type: |Number| 1011 1012 1013 argv([{nr} [, {winid}]]) *argv()* 1014 The result is the {nr}th file in the argument list. See 1015 |arglist|. "argv(0)" is the first one. Example: > 1016 :let i = 0 1017 :while i < argc() 1018 : let f = escape(fnameescape(argv(i)), '.') 1019 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>' 1020 : let i = i + 1 1021 :endwhile 1022 < Without the {nr} argument, or when {nr} is -1, a |List| with 1023 the whole |arglist| is returned. 1024 1025 The {winid} argument specifies the window ID, see |argc()|. 1026 For the Vim command line arguments see |v:argv|. 1027 1028 Returns an empty string if {nr}th argument is not present in 1029 the argument list. Returns an empty List if the {winid} 1030 argument is invalid. 1031 1032 Return type: |String| 1033 1034 1035 asin({expr}) *asin()* 1036 Return the arc sine of {expr} measured in radians, as a |Float| 1037 in the range of [-pi/2, pi/2]. 1038 {expr} must evaluate to a |Float| or a |Number| in the range 1039 [-1, 1]. 1040 Returns "nan" if {expr} is outside the range [-1, 1]. Returns 1041 0.0 if {expr} is not a |Float| or a |Number|. 1042 Examples: > 1043 :echo asin(0.8) 1044 < 0.927295 > 1045 :echo asin(-0.5) 1046 < -0.523599 1047 1048 Can also be used as a |method|: > 1049 Compute()->asin() 1050 < 1051 Return type: |Float| 1052 1053 assert_ functions are documented here: |assert-functions-details| 1054 1055 1056 atan({expr}) *atan()* 1057 Return the principal value of the arc tangent of {expr}, in 1058 the range [-pi/2, +pi/2] radians, as a |Float|. 1059 {expr} must evaluate to a |Float| or a |Number|. 1060 Returns 0.0 if {expr} is not a |Float| or a |Number|. 1061 Examples: > 1062 :echo atan(100) 1063 < 1.560797 > 1064 :echo atan(-4.01) 1065 < -1.326405 1066 1067 Can also be used as a |method|: > 1068 Compute()->atan() 1069 < 1070 Return type: |Float| 1071 1072 1073 atan2({expr1}, {expr2}) *atan2()* 1074 Return the arc tangent of {expr1} / {expr2}, measured in 1075 radians, as a |Float| in the range [-pi, pi]. 1076 {expr1} and {expr2} must evaluate to a |Float| or a |Number|. 1077 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a 1078 |Number|. 1079 Examples: > 1080 :echo atan2(-1, 1) 1081 < -0.785398 > 1082 :echo atan2(1, -1) 1083 < 2.356194 1084 1085 Can also be used as a |method|: > 1086 Compute()->atan2(1) 1087 < 1088 Return type: |Float| 1089 1090 1091 autocmd_add({acmds}) *autocmd_add()* 1092 Adds a List of autocmds and autocmd groups. 1093 1094 The {acmds} argument is a List where each item is a Dict with 1095 the following optional items: 1096 bufnr buffer number to add a buffer-local autocmd. 1097 If this item is specified, then the "pattern" 1098 item is ignored. 1099 cmd Ex command to execute for this autocmd event 1100 event autocmd event name. Refer to |autocmd-events|. 1101 This can be either a String with a single 1102 event name or a List of event names. 1103 group autocmd group name. Refer to |autocmd-groups|. 1104 If this group doesn't exist then it is 1105 created. If not specified or empty, then the 1106 default group is used. 1107 nested boolean flag, set to v:true to add a nested 1108 autocmd. Refer to |autocmd-nested|. 1109 once boolean flag, set to v:true to add an autocmd 1110 which executes only once. Refer to 1111 |autocmd-once|. 1112 pattern autocmd pattern string. Refer to 1113 |autocmd-patterns|. If "bufnr" item is 1114 present, then this item is ignored. This can 1115 be a String with a single pattern or a List of 1116 patterns. 1117 replace boolean flag, set to v:true to remove all the 1118 commands associated with the specified autocmd 1119 event and group and add the {cmd}. This is 1120 useful to avoid adding the same command 1121 multiple times for an autocmd event in a 1122 group. 1123 1124 Returns v:true on success and v:false on failure. 1125 Examples: > 1126 " Create a buffer-local autocmd for buffer 5 1127 let acmd = {} 1128 let acmd.group = 'MyGroup' 1129 let acmd.event = 'BufEnter' 1130 let acmd.bufnr = 5 1131 let acmd.cmd = 'call BufEnterFunc()' 1132 call autocmd_add([acmd]) 1133 < 1134 Can also be used as a |method|: > 1135 GetAutocmdList()->autocmd_add() 1136 < 1137 Return type: |vim9-boolean| 1138 1139 1140 autocmd_delete({acmds}) *autocmd_delete()* 1141 Deletes a List of autocmds and autocmd groups. 1142 1143 The {acmds} argument is a List where each item is a Dict with 1144 the following optional items: 1145 bufnr buffer number to delete a buffer-local 1146 autocmd. If this item is specified, then the 1147 "pattern" item is ignored. 1148 cmd Ex command for this autocmd event 1149 event autocmd event name. Refer to |autocmd-events|. 1150 If '*' then all the autocmd events in this 1151 group are deleted. 1152 group autocmd group name. Refer to |autocmd-groups|. 1153 If not specified or empty, then the default 1154 group is used. 1155 nested set to v:true for a nested autocmd. 1156 Refer to |autocmd-nested|. 1157 once set to v:true for an autocmd which executes 1158 only once. Refer to |autocmd-once|. 1159 pattern autocmd pattern string. Refer to 1160 |autocmd-patterns|. If "bufnr" item is 1161 present, then this item is ignored. 1162 1163 If only {group} is specified in a {acmds} entry and {event}, 1164 {pattern} and {cmd} are not specified, then that autocmd group 1165 is deleted. 1166 1167 Returns |v:true| on success and |v:false| on failure. 1168 Examples: > 1169 " :autocmd! BufLeave *.vim 1170 let acmd = #{event: 'BufLeave', pattern: '*.vim'} 1171 call autocmd_delete([acmd]}) 1172 " :autocmd! MyGroup1 BufLeave 1173 let acmd = #{group: 'MyGroup1', event: 'BufLeave'} 1174 call autocmd_delete([acmd]) 1175 " :autocmd! MyGroup2 BufEnter *.c 1176 let acmd = #{group: 'MyGroup2', event: 'BufEnter', 1177 \ pattern: '*.c'} 1178 " :autocmd! MyGroup2 * *.c 1179 let acmd = #{group: 'MyGroup2', event: '*', 1180 \ pattern: '*.c'} 1181 call autocmd_delete([acmd]) 1182 " :autocmd! MyGroup3 1183 let acmd = #{group: 'MyGroup3'} 1184 call autocmd_delete([acmd]) 1185 < 1186 Can also be used as a |method|: > 1187 GetAutocmdList()->autocmd_delete() 1188 < 1189 Return type: |vim9-boolean| 1190 1191 1192 autocmd_get([{opts}]) *autocmd_get()* 1193 Returns a |List| of autocmds. If {opts} is not supplied, then 1194 returns the autocmds for all the events in all the groups. 1195 1196 The optional {opts} Dict argument supports the following 1197 items: 1198 group Autocmd group name. If specified, returns 1199 only the autocmds defined in this group. If 1200 the specified group doesn't exist, results in 1201 an error message. If set to an empty string, 1202 then the default autocmd group is used. 1203 event Autocmd event name. If specified, returns 1204 only the autocmds defined for this event. If 1205 set to "*", then returns autocmds for all the 1206 events. If the specified event doesn't exist, 1207 results in an error message. 1208 pattern Autocmd pattern. If specified, returns only 1209 the autocmds defined for this pattern. 1210 A combination of the above three times can be supplied in 1211 {opts}. 1212 1213 Each Dict in the returned List contains the following items: 1214 bufnr For buffer-local autocmds, buffer number where 1215 the autocmd is defined. 1216 cmd Command executed for this autocmd. 1217 event Autocmd event name. 1218 group Autocmd group name. 1219 nested Boolean flag, set to v:true for a nested 1220 autocmd. See |autocmd-nested|. 1221 once Boolean flag, set to v:true, if the autocmd 1222 will be executed only once. See |autocmd-once|. 1223 pattern Autocmd pattern. For a buffer-local 1224 autocmd, this will be of the form 1225 "<buffer=n>". 1226 If there are multiple commands for an autocmd event in a 1227 group, then separate items are returned for each command. 1228 1229 Returns an empty List if an autocmd with the specified group 1230 or event or pattern is not found. 1231 1232 Examples: > 1233 " :autocmd MyGroup 1234 echo autocmd_get(#{group: 'Mygroup'}) 1235 " :autocmd G BufUnload 1236 echo autocmd_get(#{group: 'G', event: 'BufUnload'}) 1237 " :autocmd G * *.ts 1238 let acmd = #{group: 'G', event: '*', pattern: '*.ts'} 1239 echo autocmd_get(acmd) 1240 " :autocmd Syntax 1241 echo autocmd_get(#{event: 'Syntax'}) 1242 " :autocmd G BufEnter *.ts 1243 let acmd = #{group: 'G', event: 'BufEnter', 1244 \ pattern: '*.ts'} 1245 echo autocmd_get(acmd) 1246 < 1247 Can also be used as a |method|: > 1248 Getopts()->autocmd_get() 1249 < 1250 Return type: list<dict<any>> 1251 1252 1253 balloon_gettext() *balloon_gettext()* 1254 Return the current text in the balloon. Only for the string, 1255 not used for the List. Returns an empty string if balloon 1256 is not present. 1257 1258 Return type: |String| 1259 1260 1261 balloon_show({expr}) *balloon_show()* 1262 Show {expr} inside the balloon. For the GUI {expr} is used as 1263 a string. For a terminal {expr} can be a list, which contains 1264 the lines of the balloon. If {expr} is not a list it will be 1265 split with |balloon_split()|. 1266 If {expr} is an empty string any existing balloon is removed. 1267 1268 Example: > 1269 func GetBalloonContent() 1270 " ... initiate getting the content 1271 return '' 1272 endfunc 1273 set balloonexpr=GetBalloonContent() 1274 1275 func BalloonCallback(result) 1276 call balloon_show(a:result) 1277 endfunc 1278 < Can also be used as a |method|: > 1279 GetText()->balloon_show() 1280 < 1281 The intended use is that fetching the content of the balloon 1282 is initiated from 'balloonexpr'. It will invoke an 1283 asynchronous method, in which a callback invokes 1284 balloon_show(). The 'balloonexpr' itself can return an 1285 empty string or a placeholder, e.g. "loading...". 1286 1287 When showing a balloon is not possible then nothing happens, 1288 no error message is given. 1289 {only available when compiled with the |+balloon_eval| or 1290 |+balloon_eval_term| feature} 1291 1292 Return type: void 1293 1294 1295 balloon_split({msg}) *balloon_split()* 1296 Split String {msg} into lines to be displayed in a balloon. 1297 The splits are made for the current window size and optimize 1298 to show debugger output. 1299 Returns a |List| with the split lines. Returns an empty List 1300 on error. 1301 Can also be used as a |method|: > 1302 GetText()->balloon_split()->balloon_show() 1303 1304 < {only available when compiled with the |+balloon_eval_term| 1305 feature} 1306 1307 Return type: list<any> or list<string> 1308 1309 1310 base64_decode({string}) *base64_decode()* 1311 Return a Blob containing the bytes decoded from the base64 1312 encoded characters in {string}. 1313 1314 The {string} argument should contain only base64-encoded 1315 characters and should have a length that is a multiple of 4. 1316 1317 Returns an empty blob on error. 1318 1319 Examples: > 1320 " Write the decoded contents to a binary file 1321 call writefile(base64_decode(s), 'tools.bmp') 1322 " Decode a base64-encoded string 1323 echo blob2str(base64_decode(encodedstr)) 1324 < 1325 Can also be used as a |method|: > 1326 GetEncodedString()->base64_decode() 1327 < 1328 Return type: |Blob| 1329 1330 1331 base64_encode({blob}) *base64_encode()* 1332 Return a base64-encoded String representing the bytes in 1333 {blob}. The base64 alphabet defined in RFC 4648 is used. 1334 1335 Examples: > 1336 " Encode the contents of a binary file 1337 echo base64_encode(readblob('somefile.bin')) 1338 " Encode a string 1339 echo base64_encode(str2blob(somestr->split("\n"))) 1340 < 1341 Can also be used as a |method|: > 1342 GetBinaryData()->base64_encode() 1343 < 1344 Return type: |String| 1345 1346 1347 bindtextdomain({package}, {path}) *bindtextdomain()* 1348 Bind a specific {package} to a {path} so that the 1349 |gettext()| function can be used to get language-specific 1350 translations for a package. {path} is the directory name 1351 for the translations. See |package-translation|. 1352 1353 Returns v:true on success and v:false on failure (out of 1354 memory). 1355 1356 Return type: |vim9-boolean| 1357 1358 1359 blob2list({blob}) *blob2list()* 1360 Return a List containing the number value of each byte in Blob 1361 {blob}. Examples: > 1362 blob2list(0z0102.0304) returns [1, 2, 3, 4] 1363 blob2list(0z) returns [] 1364 < Returns an empty List on error. |list2blob()| does the 1365 opposite. 1366 1367 Can also be used as a |method|: > 1368 GetBlob()->blob2list() 1369 < 1370 Return type: list<any> or list<number> 1371 1372 1373 blob2str({blob} [, {options}]) *blob2str()* 1374 Return a List of Strings in the current 'encoding' by 1375 converting the bytes in {blob} into characters. 1376 1377 Each <NL> byte in the blob is interpreted as the end of a 1378 string and a new list item is added. Each <NUL> byte in the 1379 blob is converted into a <NL> character. 1380 1381 If {options} is not supplied, the current 'encoding' value is 1382 used to decode the bytes in {blob}. 1383 1384 The argument {options} is a |Dict| and supports the following 1385 items: 1386 encoding Decode the bytes in {blob} using this 1387 encoding. The value is a |String|. See 1388 |encoding-names| for the supported values 1389 (plus the special value "none"). 1390 *E1515* *E1516* 1391 When current 'encoding' is "utf-8", an error is given and an 1392 empty List is returned if an invalid byte sequence is 1393 encountered in {blob}. To suppress this validation and get 1394 potentially invalid string, set "encoding" in {options} to 1395 "none". 1396 1397 Returns an empty List if blob is empty. 1398 1399 See also |str2blob()| 1400 1401 Examples: > 1402 blob2str(0z6162) returns ['ab'] 1403 blob2str(0zC2ABC2BB) returns ['«»'] 1404 blob2str(0z610A62) returns ['a', 'b'] 1405 blob2str(0z610062) returns ['a\nb'] 1406 blob2str(0zABBB, {'encoding': 'latin1'}) returns ['«»'] 1407 < 1408 Can also be used as a |method|: > 1409 GetBlob()->blob2str() 1410 < 1411 If `iconv` is not available and the encoding cannot be converted 1412 using built-in conversion rules, an error will be reported. 1413 1414 Return type: list<string> 1415 1416 1417 browse({save}, {title}, {initdir}, {default}) *browse()* 1418 Put up a file requester. This only works when "has("browse")" 1419 returns |TRUE| (only in some GUI versions). 1420 The input fields are: 1421 {save} when |TRUE|, select file to write 1422 {title} title for the requester 1423 {initdir} directory to start browsing in 1424 {default} default file name 1425 An empty string is returned when the "Cancel" button is hit, 1426 something went wrong, or browsing is not possible. 1427 1428 Return type: |String| 1429 1430 1431 browsedir({title}, {initdir}) *browsedir()* 1432 Put up a directory requester. This only works when 1433 "has("browse")" returns |TRUE| (only in some GUI versions). 1434 On systems where a directory browser is not supported a file 1435 browser is used. In that case: select a file in the directory 1436 to be used. 1437 The input fields are: 1438 {title} title for the requester 1439 {initdir} directory to start browsing in 1440 When the "Cancel" button is hit, something went wrong, or 1441 browsing is not possible, an empty string is returned. 1442 1443 Return type: |String| 1444 1445 1446 bufadd({name}) *bufadd()* 1447 Add a buffer to the buffer list with name {name} (must be a 1448 String). 1449 If a buffer for file {name} already exists, return that buffer 1450 number. Otherwise return the buffer number of the newly 1451 created buffer. When {name} is an empty string then a new 1452 buffer is always created. 1453 The buffer will not have 'buflisted' set and not be loaded 1454 yet. To add some text to the buffer use this: > 1455 let bufnr = bufadd('someName') 1456 call bufload(bufnr) 1457 call setbufline(bufnr, 1, ['some', 'text']) 1458 < Returns 0 on error. 1459 Can also be used as a |method|: > 1460 let bufnr = 'somename'->bufadd() 1461 < 1462 Return type: |Number| 1463 1464 1465 bufexists({buf}) *bufexists()* 1466 The result is a Number, which is |TRUE| if a buffer called 1467 {buf} exists. 1468 If the {buf} argument is a number, buffer numbers are used. 1469 Number zero is the alternate buffer for the current window. 1470 1471 If the {buf} argument is a string it must match a buffer name 1472 exactly. The name can be: 1473 - Relative to the current directory. 1474 - A full path. 1475 - The name of a buffer with 'buftype' set to "nofile". 1476 - A URL name. 1477 Unlisted buffers will be found. 1478 Note that help files are listed by their short name in the 1479 output of |:buffers|, but bufexists() requires using their 1480 long name to be able to find them. 1481 bufexists() may report a buffer exists, but to use the name 1482 with a |:buffer| command you may need to use |expand()|. Esp 1483 for MS-Windows 8.3 names in the form "c:\DOCUME~1" 1484 Use "bufexists(0)" to test for the existence of an alternate 1485 file name. 1486 1487 Can also be used as a |method|: > 1488 let exists = 'somename'->bufexists() 1489 < 1490 Return type: |Number| 1491 1492 Obsolete name: buffer_exists(). *buffer_exists()* 1493 1494 1495 buflisted({buf}) *buflisted()* 1496 The result is a Number, which is |TRUE| if a buffer called 1497 {buf} exists and is listed (has the 'buflisted' option set). 1498 The {buf} argument is used like with |bufexists()|. 1499 1500 Can also be used as a |method|: > 1501 let listed = 'somename'->buflisted() 1502 < 1503 Return type: |Number| 1504 1505 1506 bufload({buf}) *bufload()* 1507 Ensure the buffer {buf} is loaded. When the buffer name 1508 refers to an existing file then the file is read. Otherwise 1509 the buffer will be empty. If the buffer was already loaded 1510 then there is no change. If the buffer is not related to a 1511 file then no file is read (e.g., when 'buftype' is "nofile"). 1512 If there is an existing swap file for the file of the buffer, 1513 there will be no dialog, the buffer will be loaded anyway. 1514 The {buf} argument is used like with |bufexists()|. 1515 1516 Can also be used as a |method|: > 1517 eval 'somename'->bufload() 1518 < 1519 Return type: void 1520 1521 1522 bufloaded({buf}) *bufloaded()* 1523 The result is a Number, which is |TRUE| if a buffer called 1524 {buf} exists and is loaded (shown in a window or hidden). 1525 The {buf} argument is used like with |bufexists()|. 1526 1527 Can also be used as a |method|: > 1528 let loaded = 'somename'->bufloaded() 1529 < 1530 Return type: |Number| 1531 1532 1533 bufname([{buf}]) *bufname()* 1534 The result is the name of a buffer. Mostly as it is displayed 1535 by the `:ls` command, but not using special names such as 1536 "[No Name]". 1537 If {buf} is omitted the current buffer is used. 1538 If {buf} is a Number, that buffer number's name is given. 1539 Number zero is the alternate buffer for the current window. 1540 If {buf} is a String, it is used as a |file-pattern| to match 1541 with the buffer names. This is always done like 'magic' is 1542 set and 'cpoptions' is empty. When there is more than one 1543 match an empty string is returned. 1544 "" or "%" can be used for the current buffer, "#" for the 1545 alternate buffer. 1546 A full match is preferred, otherwise a match at the start, end 1547 or middle of the buffer name is accepted. If you only want a 1548 full match then put "^" at the start and "$" at the end of the 1549 pattern. 1550 Listed buffers are found first. If there is a single match 1551 with a listed buffer, that one is returned. Next unlisted 1552 buffers are searched for. 1553 If the {buf} is a String, but you want to use it as a buffer 1554 number, force it to be a Number by adding zero to it: > 1555 :echo bufname("3" + 0) 1556 < Can also be used as a |method|: > 1557 echo bufnr->bufname() 1558 1559 < If the buffer doesn't exist, or doesn't have a name, an empty 1560 string is returned. > 1561 bufname("#") alternate buffer name 1562 bufname(3) name of buffer 3 1563 bufname("%") name of current buffer 1564 bufname("file2") name of buffer where "file2" matches. 1565 < 1566 Return type: |String| 1567 *buffer_name()* 1568 Obsolete name: buffer_name(). 1569 1570 1571 bufnr([{buf} [, {create}]]) *bufnr()* 1572 The result is the number of a buffer, as it is displayed by 1573 the `:ls` command. For the use of {buf}, see |bufname()| 1574 above. 1575 1576 If the buffer doesn't exist, -1 is returned. Or, if the 1577 {create} argument is present and TRUE, a new, unlisted, 1578 buffer is created and its number is returned. Example: > 1579 let newbuf = bufnr('Scratch001', 1) 1580 < Using an empty name uses the current buffer. To create a new 1581 buffer with an empty name use |bufadd()|. 1582 1583 bufnr("$") is the last buffer: > 1584 :let last_buffer = bufnr("$") 1585 < The result is a Number, which is the highest buffer number 1586 of existing buffers. Note that not all buffers with a smaller 1587 number necessarily exist, because ":bwipeout" may have removed 1588 them. Use |bufexists()| to test for the existence of a buffer. 1589 1590 Can also be used as a |method|: > 1591 echo bufref->bufnr() 1592 < 1593 Return type: |Number| 1594 1595 Obsolete name: buffer_number(). *buffer_number()* 1596 *last_buffer_nr()* 1597 Obsolete name for bufnr("$"): last_buffer_nr(). 1598 1599 1600 bufwinid({buf}) *bufwinid()* 1601 The result is a Number, which is the |window-ID| of the first 1602 window associated with buffer {buf}. For the use of {buf}, 1603 see |bufname()| above. If buffer {buf} doesn't exist or 1604 there is no such window, -1 is returned. Example: > 1605 1606 echo "A window containing buffer 1 is " .. (bufwinid(1)) 1607 < 1608 Only deals with the current tab page. See |win_findbuf()| for 1609 finding more. 1610 1611 Can also be used as a |method|: > 1612 FindBuffer()->bufwinid() 1613 < 1614 Return type: |Number| 1615 1616 1617 bufwinnr({buf}) *bufwinnr()* 1618 Like |bufwinid()| but return the window number instead of the 1619 |window-ID|. 1620 If buffer {buf} doesn't exist or there is no such window, -1 1621 is returned. Example: > 1622 1623 echo "A window containing buffer 1 is " .. (bufwinnr(1)) 1624 1625 < The number can be used with |CTRL-W_w| and ":wincmd w" 1626 |:wincmd|. 1627 1628 Can also be used as a |method|: > 1629 FindBuffer()->bufwinnr() 1630 < 1631 Return type: |Number| 1632 1633 1634 byte2line({byte}) *byte2line()* 1635 Return the line number that contains the character at byte 1636 count {byte} in the current buffer. This includes the 1637 end-of-line character, depending on the 'fileformat' option 1638 for the current buffer. The first character has byte count 1639 one. 1640 Also see |line2byte()|, |go| and |:goto|. 1641 1642 Returns -1 if the {byte} value is invalid. 1643 1644 Can also be used as a |method|: > 1645 GetOffset()->byte2line() 1646 < 1647 Return type: |Number| 1648 1649 {not available when compiled without the |+byte_offset| feature} 1650 1651 1652 byteidx({expr}, {nr} [, {utf16}]) *byteidx()* 1653 Return byte index of the {nr}'th character in the String 1654 {expr}. Use zero for the first character, it then returns 1655 zero. 1656 If there are no multibyte characters the returned value is 1657 equal to {nr}. 1658 Composing characters are not counted separately, their byte 1659 length is added to the preceding base character. See 1660 |byteidxcomp()| below for counting composing characters 1661 separately. 1662 When {utf16} is present and TRUE, {nr} is used as the UTF-16 1663 index in the String {expr} instead of as the character index. 1664 The UTF-16 index is the index in the string when it is encoded 1665 with 16-bit words. If the specified UTF-16 index is in the 1666 middle of a character (e.g. in a 4-byte character), then the 1667 byte index of the first byte in the character is returned. 1668 Refer to |string-offset-encoding| for more information. 1669 Example : > 1670 echo matchstr(str, ".", byteidx(str, 3)) 1671 < will display the fourth character. Another way to do the 1672 same: > 1673 let s = strpart(str, byteidx(str, 3)) 1674 echo strpart(s, 0, byteidx(s, 1)) 1675 < Also see |strgetchar()| and |strcharpart()|. 1676 1677 If there are less than {nr} characters -1 is returned. 1678 If there are exactly {nr} characters the length of the string 1679 in bytes is returned. 1680 See |charidx()| and |utf16idx()| for getting the character and 1681 UTF-16 index respectively from the byte index. 1682 Examples: > 1683 echo byteidx('a😊😊', 2) returns 5 1684 echo byteidx('a😊😊', 2, 1) returns 1 1685 echo byteidx('a😊😊', 3, 1) returns 5 1686 < 1687 Can also be used as a |method|: > 1688 GetName()->byteidx(idx) 1689 < 1690 Return type: |Number| 1691 1692 1693 byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()* 1694 Like |byteidx()|, except that a composing character is counted 1695 as a separate character. Example: > 1696 let s = 'e' .. nr2char(0x301) 1697 echo byteidx(s, 1) 1698 echo byteidxcomp(s, 1) 1699 echo byteidxcomp(s, 2) 1700 < The first and third echo result in 3 ('e' plus composing 1701 character is 3 bytes), the second echo results in 1 ('e' is 1702 one byte). 1703 Only works differently from |byteidx()| when 'encoding' is set 1704 to a Unicode encoding. 1705 1706 Can also be used as a |method|: > 1707 GetName()->byteidxcomp(idx) 1708 < 1709 Return type: |Number| 1710 1711 1712 call({func}, {arglist} [, {dict}]) *call()* *E699* 1713 Call function {func} with the items in |List| {arglist} as 1714 arguments. 1715 {func} can either be a |Funcref| or the name of a function. 1716 a:firstline and a:lastline are set to the cursor line. 1717 Returns the return value of the called function. 1718 {dict} is for functions with the "dict" attribute. It will be 1719 used to set the local variable "self". |Dictionary-function| 1720 1721 Can also be used as a |method|: > 1722 GetFunc()->call([arg, arg], dict) 1723 < 1724 Return type: any, depending on {func} 1725 1726 1727 ceil({expr}) *ceil()* 1728 Return the smallest integral value greater than or equal to 1729 {expr} as a |Float| (round up). 1730 {expr} must evaluate to a |Float| or a |Number|. 1731 Examples: > 1732 echo ceil(1.456) 1733 < 2.0 > 1734 echo ceil(-5.456) 1735 < -5.0 > 1736 echo ceil(4.0) 1737 < 4.0 1738 1739 Returns 0.0 if {expr} is not a |Float| or a |Number|. 1740 1741 Can also be used as a |method|: > 1742 Compute()->ceil() 1743 < 1744 Return type: |Float| 1745 1746 1747 ch_ functions are documented here: |channel-functions-details| 1748 1749 1750 changenr() *changenr()* 1751 Return the number of the most recent change. This is the same 1752 number as what is displayed with |:undolist| and can be used 1753 with the |:undo| command. 1754 When a change was made it is the number of that change. After 1755 redo it is the number of the redone change. After undo it is 1756 one less than the number of the undone change. 1757 Returns 0 if the undo list is empty. 1758 1759 Return type: |Number| 1760 1761 1762 char2nr({string} [, {utf8}]) *char2nr()* 1763 Return Number value of the first char in {string}. 1764 Examples: > 1765 char2nr(" ") returns 32 1766 char2nr("ABC") returns 65 1767 < When {utf8} is omitted or zero, the current 'encoding' is 1768 used. 1769 Example for "utf-8": > 1770 char2nr("á") returns 225 1771 char2nr("á"[0]) returns 195 1772 < When {utf8} is TRUE, always treat as UTF-8 characters. 1773 A combining character is a separate character. 1774 |nr2char()| does the opposite. 1775 To turn a string into a list of character numbers: > 1776 let str = "ABC" 1777 let list = map(split(str, '\zs'), {_, val -> char2nr(val)}) 1778 < Result: [65, 66, 67] 1779 1780 Returns 0 if {string} is not a |String|. 1781 1782 Can also be used as a |method|: > 1783 GetChar()->char2nr() 1784 < 1785 Return type: |Number| 1786 1787 1788 charclass({string}) *charclass()* 1789 Return the character class of the first character in {string}. 1790 The character class is one of: 1791 0 blank 1792 1 punctuation 1793 2 word character (depends on 'iskeyword') 1794 3 emoji 1795 other specific Unicode class 1796 The class is used in patterns and word motions. 1797 Returns 0 if {string} is not a |String|. 1798 1799 Return type: |Number| 1800 1801 1802 charcol({expr} [, {winid}]) *charcol()* 1803 Same as |col()| but returns the character index of the column 1804 position given with {expr} instead of the byte position. 1805 1806 Example: 1807 With the cursor on '세' in line 5 with text "여보세요": > 1808 charcol('.') returns 3 1809 col('.') returns 7 1810 1811 < Can also be used as a |method|: > 1812 GetPos()->col() 1813 < 1814 Return type: |Number| 1815 1816 1817 charidx({string}, {idx} [, {countcc} [, {utf16}]]) *charidx()* 1818 Return the character index of the byte at {idx} in {string}. 1819 The index of the first character is zero. 1820 If there are no multibyte characters the returned value is 1821 equal to {idx}. 1822 1823 When {countcc} is omitted or |FALSE|, then composing characters 1824 are not counted separately, their byte length is added to the 1825 preceding base character. 1826 When {countcc} is |TRUE|, then composing characters are 1827 counted as separate characters. 1828 1829 When {utf16} is present and TRUE, {idx} is used as the UTF-16 1830 index in the String {expr} instead of as the byte index. 1831 1832 Returns -1 if the arguments are invalid or if there are less 1833 than {idx} bytes. If there are exactly {idx} bytes the length 1834 of the string in characters is returned. 1835 1836 An error is given and -1 is returned if the first argument is 1837 not a string, the second argument is not a number or when the 1838 third argument is present and is not zero or one. 1839 1840 See |byteidx()| and |byteidxcomp()| for getting the byte index 1841 from the character index and |utf16idx()| for getting the 1842 UTF-16 index from the character index. 1843 Refer to |string-offset-encoding| for more information. 1844 Examples: > 1845 echo charidx('áb́ć', 3) returns 1 1846 echo charidx('áb́ć', 6, 1) returns 4 1847 echo charidx('áb́ć', 16) returns -1 1848 echo charidx('a😊😊', 4, 0, 1) returns 2 1849 < 1850 Can also be used as a |method|: > 1851 GetName()->charidx(idx) 1852 < 1853 Return type: |Number| 1854 1855 1856 chdir({dir} [, {scope}]) *chdir()* 1857 Changes the current working directory to {dir}. The scope of 1858 the change is determined as follows: 1859 If {scope} is not present, the current working directory is 1860 changed to the scope of the current directory: 1861 - If the window local directory (|:lcd|) is set, it 1862 changes the current working directory for that scope. 1863 - Otherwise, if the tab page local directory (|:tcd|) is 1864 set, it changes the current directory for that scope. 1865 - Otherwise, changes the global directory for that scope. 1866 1867 If {scope} is present, changes the current working directory 1868 for the specified scope: 1869 "window" Changes the window local directory. |:lcd| 1870 "tabpage" Changes the tab page local directory. |:tcd| 1871 "global" Changes the global directory. |:cd| 1872 1873 {dir} must be a String. 1874 If successful, returns the previous working directory. Pass 1875 this to another chdir() to restore the directory. 1876 On failure, returns an empty string. 1877 1878 Example: > 1879 let save_dir = chdir(newdir) 1880 if save_dir != "" 1881 " ... do some work 1882 call chdir(save_dir) 1883 endif 1884 1885 < Can also be used as a |method|: > 1886 GetDir()->chdir() 1887 < 1888 Return type: |String| 1889 1890 1891 cindent({lnum}) *cindent()* 1892 Get the amount of indent for line {lnum} according the C 1893 indenting rules, as with 'cindent'. 1894 The indent is counted in spaces, the value of 'tabstop' is 1895 relevant. {lnum} is used just like in |getline()|. 1896 When {lnum} is invalid -1 is returned. 1897 See |C-indenting|. 1898 1899 Can also be used as a |method|: > 1900 GetLnum()->cindent() 1901 < 1902 Return type: |Number| 1903 1904 1905 clearmatches([{win}]) *clearmatches()* 1906 Clears all matches previously defined for the current window 1907 by |matchadd()| and the |:match| commands. 1908 If {win} is specified, use the window with this number or 1909 window ID instead of the current window. 1910 1911 Can also be used as a |method|: > 1912 GetWin()->clearmatches() 1913 < 1914 Return type: void 1915 1916 1917 cmdcomplete_info() *cmdcomplete_info()* 1918 Returns a |Dictionary| with information about cmdline 1919 completion. See |cmdline-completion|. 1920 The items are: 1921 cmdline_orig The original command-line string before 1922 completion began. 1923 pum_visible |TRUE| if popup menu is visible. 1924 See |pumvisible()|. 1925 matches List of all completion candidates. Each item 1926 is a string. 1927 selected Selected item index. First index is zero. 1928 Index is -1 if no item is selected (showing 1929 typed text only, or the last completion after 1930 no item is selected when using the <Up> or 1931 <Down> keys) 1932 1933 Returns an empty |Dictionary| if no completion was attempted, 1934 if there was only one candidate and it was fully completed, or 1935 if an error occurred. 1936 1937 Return type: dict<any> 1938 1939 1940 col({expr} [, {winid}]) *col()* 1941 The result is a Number, which is the byte index of the column 1942 position given with {expr}. 1943 For accepted positions see |getpos()|. 1944 When {expr} is "$", it means the end of the cursor line, so 1945 the result is the number of bytes in the cursor line plus one. 1946 Additionally {expr} can be [lnum, col]: a |List| with the line 1947 and column number. Most useful when the column is "$", to get 1948 the last column of a specific line. When "lnum" or "col" is 1949 out of range then col() returns zero. 1950 1951 With the optional {winid} argument the values are obtained for 1952 that window instead of the current window. 1953 1954 To get the line number use |line()|. To get both use 1955 |getpos()|. 1956 For the screen column position use |virtcol()|. For the 1957 character position use |charcol()|. 1958 1959 Note that only marks in the current file can be used. 1960 1961 Examples: > 1962 col(".") column of cursor 1963 col("$") length of cursor line plus one 1964 col("'t") column of mark t 1965 col("'" .. markname) column of mark markname 1966 < 1967 The first column is 1. Returns 0 if {expr} is invalid or when 1968 the window with ID {winid} is not found. 1969 For an uppercase mark the column may actually be in another 1970 buffer. 1971 For the cursor position, when 'virtualedit' is active, the 1972 column is one higher if the cursor is after the end of the 1973 line. Also, when using a <Cmd> mapping the cursor isn't 1974 moved, this can be used to obtain the column in Insert mode: > 1975 :imap <F2> <Cmd>echowin col(".")<CR> 1976 1977 < Can also be used as a |method|: > 1978 GetPos()->col() 1979 < 1980 Return type: |Number| 1981 1982 1983 complete({startcol}, {matches}) *complete()* *E785* 1984 Set the matches for Insert mode completion. Can only be 1985 used in Insert mode. Typically invoked from a mapping with 1986 CTRL-R = (see |i_CTRL-R|), but may also be called from a 1987 |<Cmd>| or |<ScriptCmd>| mapping. It does not work after 1988 CTRL-O or with an expression mapping. 1989 {startcol} is the byte offset in the line where the completed 1990 text start. The text up to the cursor is the original text 1991 that will be replaced by the matches. Use col('.') for an 1992 empty string. "col('.') - 1" will replace one character by a 1993 match. 1994 {matches} must be a |List|. Each |List| item is one match. 1995 See |complete-items| for the kind of items that are possible. 1996 "longest" in 'completeopt' is ignored. 1997 Note that the after calling this function you need to avoid 1998 inserting anything that would cause completion to stop. 1999 The match can be selected with CTRL-N and CTRL-P as usual with 2000 Insert mode completion. The popup menu will appear if 2001 specified, see |ins-completion-menu|. 2002 Unlike with other |ins-completion| modes, the CTRL-N and 2003 CTRL-P keys can be mapped while this completion is active. 2004 For example, to make CTRL-N move the selection without 2005 inserting the match: > 2006 2007 inoremap <expr> <C-N> complete_info().mode ==# 'eval' 2008 \ ? '<Down>' : '<C-N>' 2009 < 2010 2011 Example (using legacy Vim script): > 2012 2013 inoremap <F5> <C-R>=ListMonths()<CR> 2014 2015 func ListMonths() 2016 call complete(col('.'), ['January', 'February', 'March', 2017 \ 'April', 'May', 'June', 'July', 'August', 2018 \ 'September', 'October', 'November', 'December']) 2019 return '' 2020 endfunc 2021 < 2022 Example (using Vim9 script): > 2023 2024 vim9script 2025 def ListMonths(): string 2026 const months = [ 'January', 'February', 'March', 'April', 2027 'May', 'June', 'July', 'September', 'October', 2028 'November', 'December'] 2029 complete(col('.'), months) 2030 return '' 2031 enddef 2032 2033 inoremap <F5> <ScriptCmd>ListMonths()<CR> 2034 2035 < This isn't very useful, but it shows how it works. Note that 2036 an empty string is returned to avoid a zero being inserted. 2037 2038 Can also be used as a |method|, the base is passed as the 2039 second argument: > 2040 GetMatches()->complete(col('.')) 2041 < 2042 Return type: void 2043 2044 2045 complete_add({expr}) *complete_add()* 2046 Add {expr} to the list of matches. Only to be used by the 2047 function specified with the 'completefunc' option. 2048 Returns 0 for failure (empty string or out of memory), 2049 1 when the match was added, 2 when the match was already in 2050 the list. 2051 See |complete-functions| for an explanation of {expr}. It is 2052 the same as one item in the list that 'omnifunc' would return. 2053 2054 Can also be used as a |method|: > 2055 GetMoreMatches()->complete_add() 2056 < 2057 Return type: |Number| 2058 2059 2060 complete_check() *complete_check()* 2061 Check for a key typed while looking for completion matches. 2062 This is to be used when looking for matches takes some time. 2063 Returns |TRUE| when searching for matches is to be aborted, 2064 zero otherwise. 2065 Only to be used by the function specified with the 2066 'completefunc' option. 2067 2068 Return type: |Number| 2069 2070 2071 complete_info([{what}]) *complete_info()* 2072 Returns a |Dictionary| with information about Insert mode 2073 completion. See |ins-completion|. 2074 The items are: 2075 auto |TRUE| when Vim started this completion by 2076 itself, which is what 'autocomplete' does, 2077 and |FALSE| when a key asked for it, such as 2078 |i_CTRL-X_CTRL-O|. A |complete-functions| 2079 function can read this to tell the two apart. 2080 Returned only when asked for in {what}. 2081 completed Return a dictionary containing the entries of 2082 the currently selected index item. 2083 items List of all completion candidates. Each item 2084 is a dictionary containing the entries "word", 2085 "abbr", "menu", "kind", "info", "abbr_hlgroup", 2086 "kind_hlgroup" and "user_data". The highlight 2087 group entries hold the name that the item was 2088 added with, or an empty string. 2089 See |complete-items|. 2090 matches Same as "items", but only returns items that 2091 are matching current query. If both "matches" 2092 and "items" are in "what", the returned list 2093 will still be named "items", but each item 2094 will have an additional "match" field. 2095 mode Current completion mode name string. 2096 See |complete_info_mode| for the values. 2097 preinserted_text 2098 The actual text that is pre-inserted, see 2099 |preinserted()|. 2100 pum_visible |TRUE| if popup menu is visible. 2101 See |pumvisible()|. 2102 selected Selected item index. First index is zero. 2103 Index is -1 if no item is selected (showing 2104 typed text only, or the last completion after 2105 no item is selected when using the <Up> or 2106 <Down> keys) 2107 2108 *complete_info_mode* 2109 mode values are: 2110 "" Not in completion mode 2111 "keyword" Keyword completion |i_CTRL-X_CTRL-N| 2112 "ctrl_x" Just pressed CTRL-X |i_CTRL-X| 2113 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or 2114 |i_CTRL-X_CTRL-Y| 2115 "whole_line" Whole lines |i_CTRL-X_CTRL-L| 2116 "files" File names |i_CTRL-X_CTRL-F| 2117 "tags" Tags |i_CTRL-X_CTRL-]| 2118 "path_defines" Definition completion |i_CTRL-X_CTRL-D| 2119 "path_patterns" Include completion |i_CTRL-X_CTRL-I| 2120 "dictionary" Dictionary |i_CTRL-X_CTRL-K| 2121 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T| 2122 "cmdline" Vim Command line |i_CTRL-X_CTRL-V| 2123 "function" User defined completion |i_CTRL-X_CTRL-U| 2124 "omni" Omni completion |i_CTRL-X_CTRL-O| 2125 "spell" Spelling suggestions |i_CTRL-X_s| 2126 "eval" |complete()| completion 2127 "register" Words from registers |i_CTRL-X_CTRL-R| 2128 "unknown" Other internal modes 2129 2130 If the optional {what} list argument is supplied, then only 2131 the items listed in {what} are returned. Unsupported items in 2132 {what} are silently ignored. 2133 2134 To get the position and size of the popup menu, see 2135 |pum_getpos()|. It's also available in |v:event| during the 2136 |CompleteChanged| event. 2137 2138 Returns an empty |Dictionary| on error. 2139 2140 Examples: > 2141 " Get all items 2142 call complete_info() 2143 " Get only 'mode' 2144 call complete_info(['mode']) 2145 " Get only 'mode' and 'pum_visible' 2146 call complete_info(['mode', 'pum_visible']) 2147 2148 < Can also be used as a |method|: > 2149 GetItems()->complete_info() 2150 < 2151 Return type: dict<any> 2152 2153 2154 confirm({msg} [, {choices} [, {default} [, {type}]]]) *confirm()* 2155 confirm() offers the user a dialog, from which a choice can be 2156 made. It returns the number of the choice. For the first 2157 choice this is 1. 2158 Note: confirm() is only supported when compiled with dialog 2159 support, see |+dialog_con| |+dialog_con_gui| and |+dialog_gui|. 2160 2161 {msg} is displayed in a |dialog| with {choices} as the 2162 alternatives. When {choices} is missing or empty, "&OK" is 2163 used (and translated). 2164 {msg} is a String, use '\n' to include a newline. Only on 2165 some systems the string is wrapped when it doesn't fit. 2166 2167 {choices} is a String, with the individual choices separated 2168 by '\n', e.g. > 2169 confirm("Save changes?", "&Yes\n&No\n&Cancel") 2170 < The letter after the '&' is the shortcut key for that choice. 2171 Thus you can type 'c' to select "Cancel". The shortcut does 2172 not need to be the first letter: > 2173 confirm("file has been modified", "&Save\nSave &All") 2174 < For the console, the first letter of each choice is used as 2175 the default shortcut key. Case is ignored. 2176 2177 The optional {default} argument is the number of the choice 2178 that is made if the user hits <CR>. Use 1 to make the first 2179 choice the default one. Use 0 to not set a default. If 2180 {default} is omitted, 1 is used. 2181 2182 The optional {type} String argument gives the type of dialog. 2183 This is only used for the icon of the GTK, Mac, Motif and 2184 Win32 GUI. It can be one of these values: "Error", 2185 "Question", "Info", "Warning" or "Generic". Only the first 2186 character is relevant. When {type} is omitted, "Generic" is 2187 used. 2188 2189 If the user aborts the dialog by pressing <Esc>, CTRL-C, 2190 or another valid interrupt key, confirm() returns 0. 2191 2192 An example: > 2193 let choice = confirm("What do you want?", 2194 \ "&Apples\n&Oranges\n&Bananas", 2) 2195 if choice == 0 2196 echo "make up your mind!" 2197 elseif choice == 3 2198 echo "tasteful" 2199 else 2200 echo "I prefer bananas myself." 2201 endif 2202 < In a GUI dialog, buttons are used. The layout of the buttons 2203 depends on the 'v' flag in 'guioptions'. If it is included, 2204 the buttons are always put vertically. Otherwise, confirm() 2205 tries to put the buttons in one horizontal line. If they 2206 don't fit, a vertical layout is used anyway. For some systems 2207 the horizontal layout is always used. 2208 2209 Can also be used as a |method|in: > 2210 BuildMessage()->confirm("&Yes\n&No") 2211 < 2212 Return type: |Number| 2213 2214 2215 copy({expr}) *copy()* 2216 Make a copy of {expr}. For Numbers and Strings this isn't 2217 different from using {expr} directly. 2218 When {expr} is a |List| a shallow copy is created. This means 2219 that the original |List| can be changed without changing the 2220 copy, and vice versa. But the items are identical, thus 2221 changing an item changes the contents of both |Lists|. 2222 A |Tuple| or |Dictionary| is copied in a similar way as a 2223 |List|. 2224 Also see |deepcopy()|. 2225 Can also be used as a |method|: > 2226 mylist->copy() 2227 < 2228 Return type: any, depending on {expr} 2229 2230 2231 cos({expr}) *cos()* 2232 Return the cosine of {expr}, measured in radians, as a |Float|. 2233 {expr} must evaluate to a |Float| or a |Number|. 2234 Returns 0.0 if {expr} is not a |Float| or a |Number|. 2235 Examples: > 2236 :echo cos(100) 2237 < 0.862319 > 2238 :echo cos(-4.01) 2239 < -0.646043 2240 2241 Can also be used as a |method|: > 2242 Compute()->cos() 2243 < 2244 Return type: |Float| 2245 2246 2247 cosh({expr}) *cosh()* 2248 Return the hyperbolic cosine of {expr} as a |Float| in the range 2249 [1, inf]. 2250 {expr} must evaluate to a |Float| or a |Number|. 2251 Returns 0.0 if {expr} is not a |Float| or a |Number|. 2252 Examples: > 2253 :echo cosh(0.5) 2254 < 1.127626 > 2255 :echo cosh(-0.5) 2256 < 1.127626 2257 2258 Can also be used as a |method|: > 2259 Compute()->cosh() 2260 < 2261 Return type: |Float| 2262 2263 2264 count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706* 2265 Return the number of times an item with value {expr} appears 2266 in |String|, |List|, |Tuple| or |Dictionary| {comp}. 2267 2268 If {start} is given then start with the item with this index. 2269 {start} can only be used with a |List| or a |Tuple|. 2270 2271 When {ic} is given and it's |TRUE| then case is ignored. 2272 2273 When {comp} is a string then the number of not overlapping 2274 occurrences of {expr} is returned. Zero is returned when 2275 {expr} is an empty string. 2276 2277 Can also be used as a |method|: > 2278 mylist->count(val) 2279 < 2280 Return type: |Number| 2281 2282 2283 cscope_connection([{num} , {dbpath} [, {prepend}]]) *cscope_connection()* 2284 Checks for the existence of a |cscope| connection. If no 2285 parameters are specified, then the function returns: 2286 0, if cscope was not available (not compiled in), or 2287 if there are no cscope connections; 2288 1, if there is at least one cscope connection. 2289 2290 If parameters are specified, then the value of {num} 2291 determines how existence of a cscope connection is checked: 2292 2293 {num} Description of existence check 2294 ----- ------------------------------ 2295 0 Same as no parameters (e.g., "cscope_connection()"). 2296 1 Ignore {prepend}, and use partial string matches for 2297 {dbpath}. 2298 2 Ignore {prepend}, and use exact string matches for 2299 {dbpath}. 2300 3 Use {prepend}, use partial string matches for both 2301 {dbpath} and {prepend}. 2302 4 Use {prepend}, use exact string matches for both 2303 {dbpath} and {prepend}. 2304 2305 Note: All string comparisons are case sensitive! 2306 2307 Examples. Suppose we had the following (from ":cs show"): > 2308 2309 # pid database name prepend path 2310 0 27664 cscope.out /usr/local 2311 < 2312 Invocation Return Val ~ 2313 ---------- ---------- > 2314 cscope_connection() 1 2315 cscope_connection(1, "out") 1 2316 cscope_connection(2, "out") 0 2317 cscope_connection(3, "out") 0 2318 cscope_connection(3, "out", "local") 1 2319 cscope_connection(4, "out") 0 2320 cscope_connection(4, "out", "local") 0 2321 cscope_connection(4, "cscope.out", "/usr/local") 1 2322 < 2323 Return type: |Number| 2324 2325 2326 cursor({lnum}, {col} [, {off}]) *cursor()* 2327 cursor({list}) 2328 Positions the cursor at the column (byte count) {col} in the 2329 line {lnum}. The first column is one. 2330 2331 When there is one argument {list} this is used as a |List| 2332 with two, three or four item: 2333 [{lnum}, {col}] 2334 [{lnum}, {col}, {off}] 2335 [{lnum}, {col}, {off}, {curswant}] 2336 This is like the return value of |getpos()| or |getcurpos()|, 2337 but without the first item. 2338 2339 To position the cursor using {col} as the character count, use 2340 |setcursorcharpos()|. 2341 2342 Does not change the jumplist. 2343 {lnum} is used like with |getline()|, except that if {lnum} is 2344 zero, the cursor will stay in the current line. 2345 If {lnum} is greater than the number of lines in the buffer, 2346 the cursor will be positioned at the last line in the buffer. 2347 If {col} is greater than the number of bytes in the line, 2348 the cursor will be positioned at the last character in the 2349 line. 2350 If {col} is zero, the cursor will stay in the current column. 2351 If {curswant} is given it is used to set the preferred column 2352 for vertical movement. Otherwise {col} is used. 2353 2354 When 'virtualedit' is used {off} specifies the offset in 2355 screen columns from the start of the character. E.g., a 2356 position within a <Tab> or after the last character. 2357 Returns 0 when the position could be set, -1 otherwise. 2358 2359 Can also be used as a |method|: > 2360 GetCursorPos()->cursor() 2361 < 2362 Return type: |Number| 2363 2364 2365 debugbreak({pid}) *debugbreak()* 2366 Specifically used to interrupt a program being debugged. It 2367 will cause process {pid} to get a SIGTRAP. Behavior for other 2368 processes is undefined. See |terminal-debugger|. 2369 {only available on MS-Windows} 2370 2371 Returns |TRUE| if successfully interrupted the program. 2372 Otherwise returns |FALSE|. 2373 2374 Can also be used as a |method|: > 2375 GetPid()->debugbreak() 2376 < 2377 Return type: |Number| 2378 2379 2380 deepcopy({expr} [, {noref}]) *deepcopy()* *E698* 2381 Make a copy of {expr}. For Numbers and Strings this isn't 2382 different from using {expr} directly. 2383 When {expr} is a |List| a full copy is created. This means 2384 that the original |List| can be changed without changing the 2385 copy, and vice versa. When an item is a |List| or 2386 |Dictionary|, a copy for it is made, recursively. Thus 2387 changing an item in the copy does not change the contents of 2388 the original |List|. 2389 A |Tuple| or |Dictionary| is copied in a similar way as a 2390 |List|. 2391 2392 When {noref} is omitted or zero a contained |List| or 2393 |Dictionary| is only copied once. All references point to 2394 this single copy. With {noref} set to 1 every occurrence of a 2395 |List| or |Dictionary| results in a new copy. This also means 2396 that a cyclic reference causes deepcopy() to fail. 2397 *E724* 2398 Nesting is possible up to 100 levels. When there is an item 2399 that refers back to a higher level making a deep copy with 2400 {noref} set to 1 will fail. 2401 Also see |copy()|. 2402 2403 Can also be used as a |method|: > 2404 GetObject()->deepcopy() 2405 < 2406 Return type: any, depending on {expr} 2407 2408 2409 delete({fname} [, {flags}]) *delete()* 2410 Without {flags} or with {flags} empty: Deletes the file by the 2411 name {fname}. 2412 2413 This also works when {fname} is a symbolic link. The symbolic 2414 link itself is deleted, not what it points to. 2415 2416 When {flags} is "d": Deletes the directory by the name 2417 {fname}. This fails when directory {fname} is not empty. 2418 2419 When {flags} is "rf": Deletes the directory by the name 2420 {fname} and everything in it, recursively. BE CAREFUL! 2421 Note: on MS-Windows it is not possible to delete a directory 2422 that is being used. 2423 2424 The result is a Number, which is 0/false if the delete 2425 operation was successful and -1/true when the deletion failed 2426 or partly failed. 2427 2428 Use |remove()| to delete an item from a |List|. 2429 To delete a line from the buffer use |:delete| or 2430 |deletebufline()|. 2431 2432 Can also be used as a |method|: > 2433 GetName()->delete() 2434 < 2435 Return type: |Number| 2436 2437 2438 deletebufline({buf}, {first} [, {last}]) *deletebufline()* 2439 Delete lines {first} to {last} (inclusive) from buffer {buf}. 2440 If {last} is omitted then delete line {first} only. 2441 On success 0 is returned, on failure 1 is returned. 2442 2443 This function works only for loaded buffers. First call 2444 |bufload()| if needed. 2445 2446 For the use of {buf}, see |bufname()| above. 2447 2448 {first} and {last} are used like with |getline()|. Note that 2449 when using |line()| this refers to the current buffer. Use "$" 2450 to refer to the last line in buffer {buf}. 2451 2452 Can also be used as a |method|: > 2453 GetBuffer()->deletebufline(1) 2454 < 2455 Return type: |Number| 2456 2457 2458 did_filetype() *did_filetype()* 2459 Returns |TRUE| when autocommands are being executed and the 2460 FileType event has been triggered at least once. Can be used 2461 to avoid triggering the FileType event again in the scripts 2462 that detect the file type. |FileType| 2463 Returns |FALSE| when `:setf FALLBACK` was used. 2464 When editing another file, the counter is reset, thus this 2465 really checks if the FileType event has been triggered for the 2466 current buffer. This allows an autocommand that starts 2467 editing another buffer to set 'filetype' and load a syntax 2468 file. 2469 2470 Return type: |Number| 2471 2472 2473 diff({fromlist}, {tolist} [, {options}]) *diff()* 2474 Returns a String or a List containing the diff between the 2475 strings in {fromlist} and {tolist}. Uses the Vim internal 2476 diff library to compute the diff. 2477 2478 *E106* 2479 The optional "output" item in {options} specifies the returned 2480 diff format. The following values are supported: 2481 indices Return a List of the starting and ending 2482 indices and a count of the strings in each 2483 diff hunk. 2484 unified Return the unified diff output as a String. 2485 This is the default. 2486 2487 If the "output" item in {options} is "indices", then a List is 2488 returned. Each List item contains a Dict with the following 2489 items for each diff hunk: 2490 from_idx start index in {fromlist} for this diff hunk. 2491 from_count number of strings in {fromlist} that are 2492 added/removed/modified in this diff hunk. 2493 to_idx start index in {tolist} for this diff hunk. 2494 to_count number of strings in {tolist} that are 2495 added/removed/modified in this diff hunk. 2496 2497 The {options} Dict argument also specifies diff options 2498 (similar to 'diffopt') and supports the following items: 2499 algorithm Dict specifying the diff algorithm to 2500 use. Supported boolean items are 2501 "myers", "minimal", "patience" and 2502 "histogram". 2503 context diff context length. Default is 0. 2504 iblank ignore changes where lines are all 2505 blank. 2506 icase ignore changes in case of text. 2507 indent-heuristic use the indent heuristic for the 2508 internal diff library. 2509 iwhite ignore changes in amount of white 2510 space. 2511 iwhiteall ignore all white space changes. 2512 iwhiteeol ignore white space changes at end of 2513 line. 2514 For more information about these options, refer to 'diffopt'. 2515 2516 To compute the unified diff, all the items in {fromlist} are 2517 concatenated into a string using a newline separator and the 2518 same for {tolist}. The unified diff output uses line numbers. 2519 2520 Returns an empty List or String if {fromlist} and {tolist} are 2521 identical. 2522 2523 Examples: > 2524 :echo diff(['abc'], ['xxx']) 2525 @@ -1 +1 @@ 2526 -abc 2527 +xxx 2528 2529 :echo diff(['abc'], ['xxx'], {'output': 'indices'}) 2530 [{'from_idx': 0, 'from_count': 1, 'to_idx': 0, 'to_count': 1}] 2531 :echo diff(readfile('oldfile'), readfile('newfile')) 2532 :echo diff(getbufline(5, 1, '$'), getbufline(6, 1, '$')) 2533 < 2534 For more examples, refer to |diff-func-examples| 2535 2536 Can also be used as a |method|: > 2537 GetFromList->diff(to_list) 2538 < 2539 Return type: |String| or list<dict<number>> or list<any> 2540 depending on {options} 2541 2542 2543 diff_filler({lnum}) *diff_filler()* 2544 Returns the number of filler lines above line {lnum}. 2545 These are the lines that were inserted at this point in 2546 another diff'ed window. These filler lines are shown in the 2547 display but don't exist in the buffer. 2548 {lnum} is used like with |getline()|. Thus "." is the current 2549 line, "'m" mark m, etc. 2550 2551 To get the filler lines after the last buffer line, use: > 2552 echo diff_filler(line('$')+1) 2553 < 2554 Returns 0 if the current window is not in diff mode or filler 2555 lines have been disabled using 'diffopt'. 2556 2557 Can also be used as a |method|: > 2558 GetLnum()->diff_filler() 2559 < 2560 Return type: |Number| 2561 2562 2563 diff_hlID({lnum}, {col}) *diff_hlID()* 2564 Returns the highlight ID for diff mode at line {lnum} column 2565 {col} (byte index). When the current line does not have a 2566 diff change zero is returned. 2567 {lnum} is used like with |getline()|. Thus "." is the current 2568 line, "'m" mark m, etc. 2569 {col} is 1 for the leftmost column, {lnum} is 1 for the first 2570 line. 2571 The highlight ID can be used with |synIDattr()| to obtain 2572 syntax information about the highlighting. 2573 2574 Can also be used as a |method|: > 2575 GetLnum()->diff_hlID(col) 2576 < 2577 Return type: |Number| 2578 2579 2580 digraph_get({chars}) *digraph_get()* *E1214* 2581 Return the digraph of {chars}. This should be a string with 2582 exactly two characters. If {chars} are not just two 2583 characters, or the digraph of {chars} does not exist, an error 2584 is given and an empty string is returned. 2585 2586 The character will be converted from Unicode to 'encoding' 2587 when needed. This does require the conversion to be 2588 available, it might fail. 2589 2590 Also see |digraph_getlist()|. 2591 2592 Examples: > 2593 " Get a built-in digraph 2594 :echo digraph_get('00') " Returns '∞' 2595 2596 " Get a user-defined digraph 2597 :call digraph_set('aa', 'あ') 2598 :echo digraph_get('aa') " Returns 'あ' 2599 < 2600 Can also be used as a |method|: > 2601 GetChars()->digraph_get() 2602 < 2603 Return type: |String| 2604 2605 This function works only when compiled with the |+digraphs| 2606 feature. If this feature is disabled, this function will 2607 display an error message. 2608 2609 2610 digraph_getlist([{listall}]) *digraph_getlist()* 2611 Return a list of digraphs. If the {listall} argument is given 2612 and it is TRUE, return all digraphs, including the default 2613 digraphs. Otherwise, return only user-defined digraphs. 2614 2615 The characters will be converted from Unicode to 'encoding' 2616 when needed. This does require the conservation to be 2617 available, it might fail. 2618 2619 Also see |digraph_get()|. 2620 2621 Examples: > 2622 " Get user-defined digraphs 2623 :echo digraph_getlist() 2624 2625 " Get all the digraphs, including default digraphs 2626 :echo digraph_getlist(1) 2627 < 2628 Can also be used as a |method|: > 2629 GetNumber()->digraph_getlist() 2630 < 2631 Return type: list<list<string>> 2632 2633 This function works only when compiled with the |+digraphs| 2634 feature. If this feature is disabled, this function will 2635 display an error message. 2636 2637 2638 digraph_set({chars}, {digraph}) *digraph_set()* 2639 Add digraph {chars} to the list. {chars} must be a string 2640 with two characters. {digraph} is a string with one UTF-8 2641 encoded character. *E1215* 2642 Be careful, composing characters are NOT ignored. This 2643 function is similar to |:digraphs| command, but useful to add 2644 digraphs start with a white space. 2645 2646 The function returns v:true if |digraph| is registered. If 2647 this fails an error message is given and v:false is returned. 2648 2649 If you want to define multiple digraphs at once, you can use 2650 |digraph_setlist()|. 2651 2652 Example: > 2653 call digraph_set(' ', 'あ') 2654 < 2655 Can be used as a |method|: > 2656 GetString()->digraph_set('あ') 2657 < 2658 Return type: |vim9-boolean| 2659 2660 This function works only when compiled with the |+digraphs| 2661 feature. If this feature is disabled, this function will 2662 display an error message. 2663 2664 2665 digraph_setlist({digraphlist}) *digraph_setlist()* 2666 Similar to |digraph_set()| but this function can add multiple 2667 digraphs at once. {digraphlist} is a list composed of lists, 2668 where each list contains two strings with {chars} and 2669 {digraph} as in |digraph_set()|. *E1216* 2670 Example: > 2671 call digraph_setlist([['aa', 'あ'], ['ii', 'い']]) 2672 < 2673 It is similar to the following: > 2674 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']] 2675 call digraph_set(chars, digraph) 2676 endfor 2677 < Except that the function returns after the first error, 2678 following digraphs will not be added. 2679 2680 Can be used as a |method|: > 2681 GetList()->digraph_setlist() 2682 < 2683 Return type: |vim9-boolean| 2684 2685 This function works only when compiled with the |+digraphs| 2686 feature. If this feature is disabled, this function will 2687 display an error message. 2688 2689 2690 echoraw({string}) *echoraw()* 2691 Output {string} as-is, including unprintable characters. 2692 This can be used to output a terminal code. For example, to 2693 disable modifyOtherKeys: > 2694 call echoraw(&t_TE) 2695 < and to enable it again: > 2696 call echoraw(&t_TI) 2697 < Use with care, you can mess up the terminal this way. 2698 2699 Return type: void 2700 2701 2702 empty({expr}) *empty()* 2703 Return the Number 1 if {expr} is empty, zero otherwise. 2704 - A |List|, |Tuple| or |Dictionary| is empty when it does 2705 not have any items. 2706 - A |String| is empty when its length is zero. 2707 - A |Number| and |Float| are empty when their value is zero. 2708 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not. 2709 - A |Job| is empty when it failed to start. 2710 - A |Channel| is empty when it is closed. 2711 - A |Blob| is empty when its length is zero. 2712 - An |Object| is empty, when the empty() method in the object 2713 (if present) returns true. |object-empty()| 2714 2715 For a long |List| this is much faster than comparing the 2716 length with zero. 2717 2718 Can also be used as a |method|: > 2719 mylist->empty() 2720 < 2721 Return type: |Number| 2722 2723 2724 environ() *environ()* 2725 Return all of environment variables as dictionary. You can 2726 check if an environment variable exists like this: > 2727 :echo has_key(environ(), 'HOME') 2728 < Note that the variable name may be CamelCase; to ignore case 2729 use this: > 2730 :echo index(keys(environ()), 'HOME', 0, 1) != -1 2731 < 2732 Return type: dict<string> 2733 2734 2735 err_teapot([{expr}]) *err_teapot()* 2736 Produce an error with number 418, needed for implementation of 2737 RFC 2324. 2738 If {expr} is present and it is TRUE error 503 is given, 2739 indicating that coffee is temporarily not available. 2740 If {expr} is present it must be a String. 2741 2742 Return type: void 2743 2744 2745 escape({string}, {chars}) *escape()* 2746 Escape the characters in {chars} that occur in {string} with a 2747 backslash. Example: > 2748 :echo escape('c:\program files\vim', ' \') 2749 < results in: > 2750 c:\\program\ files\\vim 2751 < Also see |shellescape()| and |fnameescape()|. 2752 2753 Can also be used as a |method|: > 2754 GetText()->escape(' \') 2755 < 2756 Return type: |String| 2757 2758 2759 eval({string}) *eval()* 2760 Evaluate {string} and return the result. Especially useful to 2761 turn the result of |string()| back into the original value. 2762 This works for Numbers, Floats, Strings, Blobs and composites 2763 of them. Also works for |Funcref|s that refer to existing 2764 functions. In |Vim9| script, it can be used to obtain |enum| 2765 values from their fully qualified names. 2766 2767 Can also be used as a |method|: > 2768 argv->join()->eval() 2769 < 2770 Return type: any, depending on {string} 2771 2772 2773 eventhandler() *eventhandler()* 2774 Returns 1 when inside an event handler. That is that Vim got 2775 interrupted while waiting for the user to type a character, 2776 e.g., when dropping a file on Vim. This means interactive 2777 commands cannot be used. Otherwise zero is returned. 2778 2779 Return type: |Number| 2780 2781 2782 executable({expr}) *executable()* 2783 This function checks if an executable with the name {expr} 2784 exists. {expr} must be the name of the program without any 2785 arguments. 2786 2787 executable() uses the value of $PATH and/or the normal 2788 searchpath for programs. 2789 *PATHEXT* 2790 On MS-Windows the ".exe", ".bat", etc. can optionally be 2791 included. Then the extensions in $PATHEXT are tried. Thus if 2792 "foo.exe" does not exist, "foo.exe.bat" can be found. If 2793 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot 2794 by itself can be used in $PATHEXT to try using the name 2795 without an extension. When 'shell' looks like a Unix shell, 2796 then the name is also tried without adding an extension. 2797 On MS-Windows it only checks if the file exists and is not a 2798 directory, not if it's really executable. 2799 2800 On MS-Windows an executable in the same directory as the Vim 2801 executable is always found. Since this directory is added to 2802 $PATH it should also work to execute it |win32-PATH|. 2803 *$NoDefaultCurrentDirectoryInExePath* 2804 On MS-Windows when using cmd.exe as 'shell' an executable in 2805 Vim's current working directory is also normally found, which 2806 can be disabled by setting the 2807 `$NoDefaultCurrentDirectoryInExePath` environment variable. 2808 This variable is always set by Vim when executing external 2809 commands (e.g., via |:!|, |:make|, or |system()|) for security 2810 reasons. 2811 2812 The result is a Number: 2813 1 exists 2814 0 does not exist 2815 -1 not implemented on this system 2816 |exepath()| can be used to get the full path of an executable. 2817 2818 Can also be used as a |method|: > 2819 GetCommand()->executable() 2820 < 2821 Return type: |Number| 2822 2823 2824 execute({command} [, {silent}]) *execute()* 2825 Execute an Ex command or commands and return the output as a 2826 string. 2827 {command} can be a string or a List. In case of a List the 2828 lines are executed one by one. 2829 This is more or less equivalent to: > 2830 redir => var 2831 {command} 2832 redir END 2833 < Except that line continuation in {command} is not recognized. 2834 2835 The optional {silent} argument can have these values: 2836 "" no `:silent` used 2837 "silent" `:silent` used 2838 "silent!" `:silent!` used 2839 The default is "silent". Note that with "silent!", unlike 2840 `:redir`, error messages are dropped. When using an external 2841 command the screen may be messed up, use `system()` instead. 2842 *E930* 2843 It is not possible to use `:redir` anywhere in {command}. 2844 2845 To get a list of lines use `split()` on the result: > 2846 execute('args')->split("\n") 2847 2848 < To execute a command in another window than the current one 2849 use `win_execute()`. 2850 2851 When used recursively the output of the recursive call is not 2852 included in the output of the higher level call. 2853 2854 Can also be used as a |method|: > 2855 GetCommand()->execute() 2856 < 2857 Return type: |String| 2858 2859 2860 exepath({expr}) *exepath()* 2861 If {expr} is an executable and is either an absolute path, a 2862 relative path or found in $PATH, return the full path. 2863 Note that the current directory is used when {expr} starts 2864 with "./", which may be a problem for Vim: > 2865 echo exepath(v:progpath) 2866 < If {expr} cannot be found in $PATH or is not executable then 2867 an empty string is returned. 2868 2869 Can also be used as a |method|: > 2870 GetCommand()->exepath() 2871 < 2872 Return type: |String| 2873 2874 2875 exists({expr}) *exists()* 2876 The result is a Number, which is |TRUE| if {expr} is defined, 2877 zero otherwise. 2878 2879 Note: In a compiled |:def| function the evaluation is done at 2880 runtime. Use `exists_compiled()` to evaluate the expression 2881 at compile time. 2882 2883 For checking for a supported feature use |has()|. 2884 For checking if a file exists use |filereadable()|. 2885 2886 The {expr} argument is a string, which contains one of these: 2887 varname internal variable (see 2888 dict.key |internal-variables|). Also works 2889 list[i] for |curly-braces-names|, |Dictionary| 2890 import.Func entries, |List| items, class and 2891 class.Func object methods, imported items, etc. 2892 object.Func Does not work for local variables in a 2893 class.varname compiled `:def` function. 2894 object.varname Also works for a function in |Vim9| 2895 script, since it can be used as a 2896 function reference. 2897 Beware that evaluating an index may 2898 cause an error message for an invalid 2899 expression. E.g.: > 2900 :let l = [1, 2, 3] 2901 :echo exists("l[5]") 2902 < 0 > 2903 :echo exists("l[xx]") 2904 < E121: Undefined variable: xx 2905 0 2906 &option-name Vim option (only checks if it exists, 2907 not if it really works) 2908 +option-name Vim option that works. 2909 $ENVNAME environment variable (could also be 2910 done by comparing with an empty 2911 string) 2912 *funcname built-in function (see |functions|) 2913 or user defined function (see 2914 |user-functions|) that is implemented. 2915 Also works for a variable that is a 2916 Funcref. 2917 ?funcname built-in function that could be 2918 implemented; to be used to check if 2919 "funcname" is valid 2920 :cmdname Ex command: built-in command, user 2921 command or command modifier |:command|. 2922 Returns: 2923 1 for match with start of a command 2924 2 full match with a command 2925 3 matches several user commands 2926 To check for a supported command 2927 always check the return value to be 2. 2928 :2match The |:2match| command. 2929 :3match The |:3match| command (but you 2930 probably should not use it, it is 2931 reserved for internal usage) 2932 #event autocommand defined for this event 2933 #event#pattern autocommand defined for this event and 2934 pattern (the pattern is taken 2935 literally and compared to the 2936 autocommand patterns character by 2937 character) 2938 #group autocommand group exists 2939 #group#event autocommand defined for this group and 2940 event. 2941 #group#event#pattern 2942 autocommand defined for this group, 2943 event and pattern. 2944 ##event autocommand for this event is 2945 supported. 2946 2947 Examples: > 2948 exists("&shortname") 2949 exists("$HOSTNAME") 2950 exists("*strftime") 2951 exists("*s:MyFunc") " only for legacy script 2952 exists("*MyFunc") 2953 exists("bufcount") 2954 exists(":Make") 2955 exists("#CursorHold") 2956 exists("#BufReadPre#*.gz") 2957 exists("#filetypeindent") 2958 exists("#filetypeindent#FileType") 2959 exists("#filetypeindent#FileType#*") 2960 exists("##ColorScheme") 2961 < There must be no space between the symbol (&/$/*/#) and the 2962 name. 2963 There must be no extra characters after the name, although in 2964 a few cases this is ignored. That may become stricter in the 2965 future, thus don't count on it! 2966 Working example: > 2967 exists(":make") 2968 < NOT working example: > 2969 exists(":make install") 2970 2971 < Note that the argument must be a string, not the name of the 2972 variable itself. For example: > 2973 exists(bufcount) 2974 < This doesn't check for existence of the "bufcount" variable, 2975 but gets the value of "bufcount", and checks if that exists. 2976 2977 Can also be used as a |method|: > 2978 Varname()->exists() 2979 < 2980 Return type: |Number| 2981 2982 2983 exists_compiled({expr}) *exists_compiled()* 2984 Like `exists()` but evaluated at compile time. This is useful 2985 to skip a block where a function is used that would otherwise 2986 give an error: > 2987 if exists_compiled('*ThatFunction') 2988 ThatFunction('works') 2989 endif 2990 < If `exists()` were used then a compilation error would be 2991 given if ThatFunction() is not defined. 2992 2993 {expr} must be a literal string. *E1232* 2994 Can only be used in a |:def| function. *E1233* 2995 This does not work to check for arguments or local variables. 2996 2997 Return type: |Number| 2998 2999 3000 exp({expr}) *exp()* 3001 Return the exponential of {expr} as a |Float| in the range 3002 [0, inf]. 3003 {expr} must evaluate to a |Float| or a |Number|. 3004 Returns 0.0 if {expr} is not a |Float| or a |Number|. 3005 Examples: > 3006 :echo exp(2) 3007 < 7.389056 > 3008 :echo exp(-1) 3009 < 0.367879 3010 3011 Can also be used as a |method|: > 3012 Compute()->exp() 3013 < 3014 Return type: |Float| 3015 3016 3017 expand({string} [, {nosuf} [, {list}]]) *expand()* 3018 Expand wildcards and the following special keywords in 3019 {string}. 'wildignorecase' applies. 3020 3021 If {list} is given and it is |TRUE|, a List will be returned. 3022 Otherwise the result is a String and when there are several 3023 matches, they are separated by <NL> characters. [Note: in 3024 version 5.0 a space was used, which caused problems when a 3025 file name contains a space] 3026 3027 If the expansion fails, the result is an empty string. A name 3028 for a non-existing file is not included, unless {string} does 3029 not start with '%', '#' or '<', see below. 3030 3031 For a |:terminal| window '%' expands to a '!' followed by 3032 the command or shell that is run. |terminal-bufname| 3033 3034 When {string} starts with '%', '#' or '<', the expansion is 3035 done like for the |cmdline-special| variables with their 3036 associated modifiers. Here is a short overview: 3037 3038 % current file name 3039 # alternate file name 3040 #n alternate file name n 3041 <cfile> file name under the cursor 3042 <afile> autocmd file name 3043 <abuf> autocmd buffer number (as a String!) 3044 <amatch> autocmd matched name 3045 <cexpr> C expression under the cursor 3046 <sfile> sourced script file or function name 3047 <slnum> sourced script line number or function 3048 line number 3049 <sflnum> script file line number, also when in 3050 a function 3051 <SID> "<SNR>123_" where "123" is the 3052 current script ID |<SID>| 3053 <script> sourced script file, or script file 3054 where the current function was defined 3055 <stack> call stack 3056 <cword> word under the cursor 3057 <cWORD> WORD under the cursor 3058 <client> the {clientid} of the last received 3059 message |server2client()| 3060 Modifiers: 3061 :p expand to full path 3062 :h head (last path component removed) 3063 :t tail (last path component only) 3064 :r root (one extension removed) 3065 :e extension only 3066 3067 More modifiers are supported, for the full list see 3068 |filename-modifiers|. 3069 3070 Example: > 3071 :let &tags = expand("%:p:h") .. "/tags" 3072 < Note that when expanding a string that starts with '%', '#' or 3073 '<', any following text is ignored. This does NOT work: > 3074 :let doesntwork = expand("%:h.bak") 3075 < Use this: > 3076 :let doeswork = expand("%:h") .. ".bak" 3077 < Also note that expanding "<cfile>" and others only returns the 3078 referenced file name without further expansion. If "<cfile>" 3079 is "~/.cshrc", you need to do another expand() to have the 3080 "~/" expanded into the path of the home directory: > 3081 :echo expand(expand("<cfile>")) 3082 < 3083 There cannot be white space between the variables and the 3084 following modifier. The |fnamemodify()| function can be used 3085 to modify normal file names. 3086 3087 When using '%' or '#', and the current or alternate file name 3088 is not defined, an empty string is used. Using "%:p" in a 3089 buffer with no name, results in the current directory, with a 3090 '/' added. 3091 When 'verbose' is set then expanding '%', '#' and <> items 3092 will result in an error message if the argument cannot be 3093 expanded. 3094 3095 When {string} does not start with '%', '#' or '<', it is 3096 expanded like a file name is expanded on the command line. 3097 'suffixes' and 'wildignore' are used, unless the optional 3098 {nosuf} argument is given and it is |TRUE|. 3099 Names for non-existing files are included. The "**" item can 3100 be used to search in a directory tree. For example, to find 3101 all "README" files in the current directory and below: > 3102 :echo expand("**/README") 3103 < 3104 expand() can also be used to expand variables and environment 3105 variables that are only known in a shell. But this can be 3106 slow, because a shell may be used to do the expansion. See 3107 |expr-env-expand|. 3108 The expanded variable is still handled like a list of file 3109 names. When an environment variable cannot be expanded, it is 3110 left unchanged. Thus ":echo expand('$FOOBAR')" results in 3111 "$FOOBAR". 3112 3113 See |glob()| for finding existing files. See |system()| for 3114 getting the raw output of an external command. 3115 3116 Can also be used as a |method|: > 3117 Getpattern()->expand() 3118 < 3119 Return type: |String| or list<string> depending on {list} 3120 3121 3122 expandcmd({string} [, {options}]) *expandcmd()* 3123 Expand special items in String {string} like what is done for 3124 an Ex command such as `:edit`. This expands special keywords, 3125 like with |expand()|, and environment variables, anywhere in 3126 {string}. "~user" and "~/path" are only expanded at the 3127 start. 3128 The expansion is done in two steps: the special keywords are 3129 evaluated first, then "~" and environment variables are 3130 expanded in the result. Thus `expand('%:~')` keeps the "~", 3131 while `expandcmd('%:~')` returns the full path. 3132 3133 The following items are supported in the {options} Dict 3134 argument: 3135 errmsg If set to TRUE, error messages are displayed 3136 if an error is encountered during expansion. 3137 By default, error messages are not displayed. 3138 3139 Returns the expanded string. If an error is encountered 3140 during expansion, the unmodified {string} is returned. 3141 3142 Example: > 3143 :echo expandcmd('make %<.o') 3144 make /path/runtime/doc/builtin.o 3145 :echo expandcmd('make %<.o', {'errmsg': v:true}) 3146 < 3147 Can also be used as a |method|: > 3148 GetCommand()->expandcmd() 3149 < 3150 Return type: |String| or list<string> depending on {list} 3151 3152 3153 extend({expr1}, {expr2} [, {expr3}]) *extend()* 3154 {expr1} and {expr2} must be both |Lists|, |Dictionaries| or 3155 |Blobs|. 3156 3157 If they are |Lists| or |Blobs|: Append {expr2} to {expr1}. 3158 If {expr3} is given insert the items of {expr2} before the 3159 item with index/byte {expr3} in {expr1}. When {expr3} is zero 3160 insert before the first item. When {expr3} is equal to 3161 len({expr1}) then {expr2} is appended. 3162 Examples: > 3163 :echo sort(extend(mylist, [7, 5])) 3164 :call extend(mylist, [2, 3], 1) 3165 < When {expr1} is the same List or Blob as {expr2} then the 3166 number of items copied is equal to the original length of the 3167 List or the Blob. 3168 E.g., when {expr3} is 1 you get N new copies of the first item 3169 (where N is the original length of the List). 3170 Use |add()| to concatenate one item to a list or a blob. 3171 To concatenate two lists or blobs into a new one use the + 3172 operator: > 3173 :let newlist = [1, 2, 3] + [4, 5] 3174 :let newblob = 0z1122 + 0z3344 3175 < 3176 If they are |Dictionaries|: 3177 Add all entries from {expr2} to {expr1}. 3178 If a key exists in both {expr1} and {expr2} then {expr3} is 3179 used to decide what to do: 3180 {expr3} = "keep": keep the value of {expr1} 3181 {expr3} = "force": use the value of {expr2} 3182 {expr3} = "error": give an error message *E737* 3183 When {expr3} is omitted then "force" is assumed. 3184 3185 {expr1} is changed when {expr2} is not empty. If necessary 3186 make a copy of {expr1} first or use |extendnew()| to return a 3187 new List/Dictionary/Blob. 3188 {expr2} remains unchanged. 3189 When {expr1} is locked and {expr2} is not empty the operation 3190 fails. 3191 Returns {expr1}. Returns 0 on error. 3192 3193 Can also be used as a |method|: > 3194 mylist->extend(otherlist) 3195 < 3196 Return type: list<{type}>, dict<{type}> or blob depending on 3197 {expr1} and {expr2}, in case of error: |Number| 3198 3199 3200 extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()* 3201 Like |extend()| but instead of adding items to {expr1} a new 3202 List, Dictionary or Blob is created and returned. {expr1} 3203 remains unchanged. 3204 3205 Return type: list<{type}>, dict<{type}> or blob depending on 3206 {expr1} and {expr2}, in case of error: |Number| 3207 3208 3209 feedkeys({string} [, {mode}]) *feedkeys()* 3210 Characters in {string} are queued for processing as if they 3211 come from a mapping or were typed by the user. 3212 3213 By default the string is added to the end of the typeahead 3214 buffer, thus if a mapping is still being executed the 3215 characters come after them. Use the 'i' flag to insert before 3216 other characters, they will be executed next, before any 3217 characters from a mapping. 3218 3219 The function does not wait for processing of keys contained in 3220 {string}. 3221 3222 To include special keys into {string}, use double-quotes 3223 and "\..." notation |expr-quote|. For example, 3224 feedkeys("\<CR>") simulates pressing of the <Enter> key. But 3225 feedkeys('\<CR>') pushes 5 characters. 3226 A special code that might be useful is <Ignore>, it exits the 3227 wait for a character without doing anything. *<Ignore>* 3228 3229 {mode} is a String, which can contain these character flags: 3230 'm' Remap keys. This is default. If {mode} is absent, 3231 keys are remapped. 3232 'n' Do not remap keys. 3233 't' Handle keys as if typed; otherwise they are handled as 3234 if coming from a mapping. This matters for undo, 3235 opening folds, etc. 3236 'L' Lowlevel input. Only works for Unix or when using the 3237 GUI. Keys are used as if they were coming from the 3238 terminal. Other flags are not used. *E980* 3239 When a CTRL-C interrupts and 't' is included it sets 3240 the internal "got_int" flag. 3241 'i' Insert the string instead of appending (see above). 3242 'x' Execute commands until typeahead is empty. This is 3243 similar to using ":normal!". You can call feedkeys() 3244 several times without 'x' and then one time with 'x' 3245 (possibly with an empty {string}) to execute all the 3246 typeahead. Note that when Vim ends in Insert mode it 3247 will behave as if <Esc> is typed, to avoid getting 3248 stuck, waiting for a character to be typed before the 3249 script continues. 3250 Note that if you manage to call feedkeys() while 3251 executing commands, thus calling it recursively, then 3252 all typeahead will be consumed by the last call. 3253 'c' Remove any script context when executing, so that 3254 legacy script syntax applies, "s:var" does not work, 3255 etc. Note that if the string being fed sets a script 3256 context this still applies. 3257 '!' When used with 'x' will not end Insert mode. Can be 3258 used in a test when a timer is set to exit Insert mode 3259 a little later. Useful for testing CursorHoldI. 3260 3261 Return value is always 0. 3262 3263 Can also be used as a |method|: > 3264 GetInput()->feedkeys() 3265 < 3266 Return type: void 3267 3268 3269 filecopy({from}, {to}) *filecopy()* 3270 Copy the file pointed to by the name {from} to {to}. The 3271 result is a Number, which is |TRUE| if the file was copied 3272 successfully, and |FALSE| when it failed. 3273 If a file with name {to} already exists, it will fail. 3274 Note that it does not handle directories (yet). 3275 3276 This function is not available in the |sandbox|. 3277 3278 Can also be used as a |method|: > 3279 GetOldName()->filecopy(newname) 3280 < 3281 Return type: |Number| 3282 3283 3284 filereadable({file}) *filereadable()* 3285 The result is a Number, which is |TRUE| when a file with the 3286 name {file} exists, and can be read. If {file} doesn't exist, 3287 or is a directory, the result is |FALSE|. {file} is any 3288 expression, which is used as a String. 3289 If you don't care about the file being readable you can use 3290 |glob()|. 3291 {file} is used as-is, you may want to expand wildcards first: > 3292 echo filereadable('~/.vimrc') 3293 0 3294 echo filereadable(expand('~/.vimrc')) 3295 1 3296 3297 < Can also be used as a |method|: > 3298 GetName()->filereadable() 3299 < 3300 Return type: |Number| 3301 3302 *file_readable()* 3303 Obsolete name: file_readable(). 3304 3305 3306 filewritable({file}) *filewritable()* 3307 The result is a Number, which is 1 when a file with the 3308 name {file} exists, and can be written. If {file} doesn't 3309 exist, or is not writable, the result is 0. If {file} is a 3310 directory, and we can write to it, the result is 2. 3311 3312 Can also be used as a |method|: > 3313 GetName()->filewritable() 3314 < 3315 Return type: |Number| 3316 3317 3318 filter({expr1}, {expr2}) *filter()* 3319 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. 3320 For each item in {expr1} evaluate {expr2} and when the result 3321 is zero or false remove the item from the |List| or 3322 |Dictionary|. Similarly for each byte in a |Blob| and each 3323 character in a |String|. 3324 3325 {expr2} must be a |string| or |Funcref|. 3326 3327 If {expr2} is a |string|, inside {expr2} |v:val| has the value 3328 of the current item. For a |Dictionary| |v:key| has the key 3329 of the current item and for a |List| |v:key| has the index of 3330 the current item. For a |Blob| |v:key| has the index of the 3331 current byte. For a |String| |v:key| has the index of the 3332 current character. 3333 Examples: > 3334 call filter(mylist, 'v:val !~ "OLD"') 3335 < Removes the items where "OLD" appears. > 3336 call filter(mydict, 'v:key >= 8') 3337 < Removes the items with a key below 8. > 3338 call filter(var, 0) 3339 < Removes all the items, thus clears the |List| or |Dictionary|. 3340 3341 Note that {expr2} is the result of expression and is then 3342 used as an expression again. Often it is good to use a 3343 |literal-string| to avoid having to double backslashes. 3344 3345 If {expr2} is a |Funcref| it must take two arguments: 3346 1. the key or the index of the current item. 3347 2. the value of the current item. 3348 The function must return |TRUE| if the item should be kept. 3349 Example that keeps the odd items of a list: > 3350 func Odd(idx, val) 3351 return a:idx % 2 == 1 3352 endfunc 3353 call filter(mylist, function('Odd')) 3354 < It is shorter when using a |lambda|. In |Vim9| syntax: > 3355 call filter(myList, (idx, val) => idx * val <= 42) 3356 < In legacy script syntax: > 3357 call filter(myList, {idx, val -> idx * val <= 42}) 3358 < If you do not use "val" you can leave it out: > 3359 call filter(myList, {idx -> idx % 2 == 1}) 3360 < 3361 In |Vim9| script the result must be true, false, zero or one. 3362 Other values will result in a type error. 3363 3364 For a |List| and a |Dictionary| the operation is done 3365 in-place. If you want it to remain unmodified make a copy 3366 first: > 3367 :let l = filter(copy(mylist), 'v:val =~ "KEEP"') 3368 3369 < Returns {expr1}, the |List| or |Dictionary| that was filtered, 3370 or a new |Blob| or |String|. 3371 When an error is encountered while evaluating {expr2} no 3372 further items in {expr1} are processed. 3373 When {expr2} is a Funcref errors inside a function are 3374 ignored, unless it was defined with the "abort" flag. 3375 3376 Can also be used as a |method|: > 3377 mylist->filter(expr2) 3378 < 3379 Return type: |String|, |Blob|, list<{type}> or dict<{type}> 3380 depending on {expr1} 3381 3382 3383 finddir({name} [, {path} [, {count}]]) *finddir()* 3384 Find directory {name} in {path}. Supports both downwards and 3385 upwards recursive directory searches. See |file-searching| 3386 for the syntax of {path}. 3387 3388 Returns the path of the first found match. When the found 3389 directory is below the current directory a relative path is 3390 returned. Otherwise a full path is returned. 3391 If {path} is omitted or empty then 'path' is used. 3392 3393 If the optional {count} is given, find {count}'s occurrence of 3394 {name} in {path} instead of the first one. 3395 When {count} is negative return all the matches in a |List|. 3396 3397 Returns an empty string if the directory is not found. 3398 3399 This is quite similar to the ex-command `:find`. 3400 3401 Can also be used as a |method|: > 3402 GetName()->finddir() 3403 < 3404 Return type: list<string> if {count} is negative, |String| 3405 otherwise 3406 3407 3408 findfile({name} [, {path} [, {count}]]) *findfile()* 3409 Just like |finddir()|, but find a file instead of a directory. 3410 Uses 'suffixesadd'. 3411 Example: > 3412 :echo findfile("tags.vim", ".;") 3413 < Searches from the directory of the current file upwards until 3414 it finds the file "tags.vim". 3415 3416 Can also be used as a |method|: > 3417 GetName()->findfile() 3418 < 3419 Return type: list<string> if {count} is negative, |String| 3420 otherwise 3421 3422 3423 flatten({list} [, {maxdepth}]) *flatten()* 3424 Flatten {list} up to {maxdepth} levels. Without {maxdepth} 3425 the result is a |List| without nesting, as if {maxdepth} is 3426 a very large number. 3427 The {list} is changed in place, use |flattennew()| if you do 3428 not want that. 3429 In Vim9 script flatten() cannot be used, you must always use 3430 |flattennew()|. 3431 *E900* 3432 {maxdepth} means how deep in nested lists changes are made. 3433 {list} is not modified when {maxdepth} is 0. 3434 {maxdepth} must be positive number. 3435 3436 If there is an error the number zero is returned. 3437 3438 Example: > 3439 :echo flatten([1, [2, [3, 4]], 5]) 3440 < [1, 2, 3, 4, 5] > 3441 :echo flatten([1, [2, [3, 4]], 5], 1) 3442 < [1, 2, [3, 4], 5] 3443 3444 Can also be used as a |method|: > 3445 mylist->flatten() 3446 < 3447 Return type: list<{type}> 3448 3449 3450 flattennew({list} [, {maxdepth}]) *flattennew()* 3451 Like |flatten()| but first make a copy of {list}. 3452 3453 Return type: list<{type}> 3454 3455 3456 float2nr({expr}) *float2nr()* 3457 Convert {expr} to a Number by omitting the part after the 3458 decimal point. 3459 {expr} must evaluate to a |Float| or a |Number|. 3460 Returns 0 if {expr} is not a |Float| or a |Number|. 3461 When the value of {expr} is out of range for a |Number| the 3462 result is truncated to 0x7fffffff or -0x7fffffff (or when 3463 64-bit Number support is enabled, 0x7fffffffffffffff or 3464 -0x7fffffffffffffff). NaN results in -0x80000000 (or when 3465 64-bit Number support is enabled, -0x8000000000000000). 3466 Examples: > 3467 echo float2nr(3.95) 3468 < 3 > 3469 echo float2nr(-23.45) 3470 < -23 > 3471 echo float2nr(1.0e100) 3472 < 2147483647 (or 9223372036854775807) > 3473 echo float2nr(-1.0e150) 3474 < -2147483647 (or -9223372036854775807) > 3475 echo float2nr(1.0e-100) 3476 < 0 3477 3478 Can also be used as a |method|: > 3479 Compute()->float2nr() 3480 < 3481 Return type: |Number| 3482 3483 3484 floor({expr}) *floor()* 3485 Return the largest integral value less than or equal to 3486 {expr} as a |Float| (round down). 3487 {expr} must evaluate to a |Float| or a |Number|. 3488 Returns 0.0 if {expr} is not a |Float| or a |Number|. 3489 Examples: > 3490 echo floor(1.856) 3491 < 1.0 > 3492 echo floor(-5.456) 3493 < -6.0 > 3494 echo floor(4.0) 3495 < 4.0 3496 3497 Can also be used as a |method|: > 3498 Compute()->floor() 3499 < 3500 Return type: |Float| 3501 3502 3503 fmod({expr1}, {expr2}) *fmod()* 3504 Return the remainder of {expr1} / {expr2}, even if the 3505 division is not representable. Returns {expr1} - i * {expr2} 3506 for some integer i such that if {expr2} is non-zero, the 3507 result has the same sign as {expr1} and magnitude less than 3508 the magnitude of {expr2}. If {expr2} is zero, the value 3509 returned is zero. The value returned is a |Float|. 3510 {expr1} and {expr2} must evaluate to a |Float| or a |Number|. 3511 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a 3512 |Number|. 3513 Examples: > 3514 :echo fmod(12.33, 1.22) 3515 < 0.13 > 3516 :echo fmod(-12.33, 1.22) 3517 < -0.13 3518 3519 Can also be used as a |method|: > 3520 Compute()->fmod(1.22) 3521 < 3522 Return type: |Float| 3523 3524 3525 fnameescape({string}) *fnameescape()* 3526 Escape {string} for use as file name command argument. All 3527 characters that have a special meaning, such as '%' and '|' 3528 are escaped with a backslash. 3529 For most systems the characters escaped are 3530 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash 3531 appears in a filename, it depends on the value of 'isfname'. 3532 A leading '+' and '>' is also escaped (special after |:edit| 3533 and |:write|). And a "-" by itself (special after |:cd|). 3534 Returns an empty string on error. 3535 Example: > 3536 :let fname = '+some str%nge|name' 3537 :exe "edit " .. fnameescape(fname) 3538 < results in executing: > 3539 edit \+some\ str\%nge\|name 3540 < 3541 Can also be used as a |method|: > 3542 GetName()->fnameescape() 3543 < 3544 Return type: |String| 3545 3546 3547 fnamemodify({fname}, {mods}) *fnamemodify()* 3548 Modify file name {fname} according to {mods}. {mods} is a 3549 string of characters like it is used for file names on the 3550 command line. See |filename-modifiers|. 3551 Example: > 3552 :echo fnamemodify("main.c", ":p:h") 3553 < results in: > 3554 /home/user/vim/vim/src 3555 < If {mods} is empty or an unsupported modifier is used then 3556 {fname} is returned. 3557 When {fname} is empty then with {mods} ":h" returns ".", so 3558 that `:cd` can be used with it. This is different from 3559 expand('%:h') without a buffer name, which returns an empty 3560 string. 3561 Note: Environment variables don't work in {fname}, use 3562 |expand()| first then. 3563 3564 Can also be used as a |method|: > 3565 GetName()->fnamemodify(':p:h') 3566 < 3567 Return type: |String| 3568 3569 3570 foldclosed({lnum} [, {winid}]) *foldclosed()* 3571 The result is a Number. If the line {lnum} is in a closed 3572 fold, the result is the number of the first line in that fold. 3573 If the line {lnum} is not in a closed fold, -1 is returned. 3574 {lnum} is used like with |getline()|. Thus "." is the current 3575 line, "'m" mark m, etc. 3576 3577 With the optional {winid} argument the values are obtained for 3578 that window instead of the current window. If {winid} is 3579 invalid, return -2. 3580 3581 Can also be used as a |method|: > 3582 GetLnum()->foldclosed() 3583 GetLnum()->foldclosed(winid) 3584 < 3585 Return type: |Number| 3586 3587 3588 foldclosedend({lnum} [, {winid}]) *foldclosedend()* 3589 The result is a Number. If the line {lnum} is in a closed 3590 fold, the result is the number of the last line in that fold. 3591 If the line {lnum} is not in a closed fold, -1 is returned. 3592 {lnum} is used like with |getline()|. Thus "." is the current 3593 line, "'m" mark m, etc. 3594 3595 With the optional {winid} argument the values are obtained for 3596 that window instead of the current window. If {winid} is 3597 invalid, return -2. 3598 3599 Can also be used as a |method|: > 3600 GetLnum()->foldclosedend() 3601 GetLnum()->foldclosedend(winid) 3602 < 3603 Return type: |Number| 3604 3605 3606 foldlevel({lnum} [, {winid}]) *foldlevel()* 3607 The result is a Number, which is the foldlevel of line {lnum} 3608 in the current buffer. For nested folds the deepest level is 3609 returned. If there is no fold at line {lnum}, zero is 3610 returned. It doesn't matter if the folds are open or closed. 3611 When used while updating folds (from 'foldexpr') -1 is 3612 returned for lines where folds are still to be updated and the 3613 foldlevel is unknown. As a special case the level of the 3614 previous line is usually available. 3615 {lnum} is used like with |getline()|. Thus "." is the current 3616 line, "'m" mark m, etc. 3617 3618 With the optional {winid} argument the values are obtained for 3619 that window instead of the current window. If {winid} is 3620 invalid, return -2. 3621 3622 Can also be used as a |method|: > 3623 GetLnum()->foldlevel() 3624 GetLnum()->foldlevel(winid) 3625 < 3626 Return type: |Number| 3627 3628 3629 foldtext() *foldtext()* 3630 Returns a String, to be displayed for a closed fold. This is 3631 the default function used for the 'foldtext' option and should 3632 only be called from evaluating 'foldtext'. It uses the 3633 |v:foldstart|, |v:foldend| and |v:folddashes| variables. 3634 The returned string looks like this: > 3635 +-- 45 lines: abcdef 3636 < The number of leading dashes depends on the foldlevel. The 3637 "45" is the number of lines in the fold. "abcdef" is the text 3638 in the first non-blank line of the fold. Leading white space, 3639 "//" or "/*" and the text from the 'foldmarker' and 3640 'commentstring' options is removed. 3641 When used to draw the actual foldtext, the rest of the line 3642 will be filled with the fold char from the 'fillchars' 3643 setting. 3644 Returns an empty string when there is no fold. 3645 3646 Return type: |String| 3647 {not available when compiled without the |+folding| feature} 3648 3649 3650 foldtextresult({lnum} [, {winid}]) *foldtextresult()* 3651 Returns the text that is displayed for the closed fold at line 3652 {lnum}. Evaluates 'foldtext' in the appropriate context. 3653 When there is no closed fold at {lnum} an empty string is 3654 returned. 3655 {lnum} is used like with |getline()|. Thus "." is the current 3656 line, "'m" mark m, etc. 3657 Useful when exporting folded text, e.g., to HTML. 3658 {not available when compiled without the |+folding| feature} 3659 3660 With the optional {winid} argument the values are obtained for 3661 that window instead of the current window. If {winid} is 3662 invalid, an empty string is returned. 3663 3664 Can also be used as a |method|: > 3665 GetLnum()->foldtextresult() 3666 GetLnum()->foldtextresult(winid) 3667 < 3668 Return type: |String| 3669 3670 3671 foreach({expr1}, {expr2}) *foreach()* *E1525* 3672 {expr1} must be a |List|, |Tuple|, |String|, |Blob| or 3673 |Dictionary|. 3674 For each item in {expr1} execute {expr2}. {expr1} is not 3675 modified; its values may be, as with |:lockvar| 1. |E741| 3676 See |map()| and |filter()| to modify {expr1}. 3677 3678 {expr2} must be a |string| or |Funcref|. 3679 3680 If {expr2} is a |string|, inside {expr2} |v:val| has the value 3681 of the current item. For a |Dictionary| |v:key| has the key 3682 of the current item and for a |List| or a |Tuple| |v:key| has 3683 the index of the current item. For a |Blob| |v:key| has the 3684 index of the current byte. For a |String| |v:key| has the 3685 index of the current character. 3686 Examples: > 3687 call foreach(mylist, 'used[v:val] = true') 3688 < This records the items that are in the {expr1} list. 3689 3690 Note that {expr2} is the result of expression and is then used 3691 as a command. Often it is good to use a |literal-string| to 3692 avoid having to double backslashes. 3693 3694 If {expr2} is a |Funcref| it must take two arguments: 3695 1. the key or the index of the current item. 3696 2. the value of the current item. 3697 With a legacy script lambda you don't get an error if it only 3698 accepts one argument, but with a Vim9 lambda you get "E1106: 3699 One argument too many", the number of arguments must match. 3700 If the function returns a value, it is ignored. 3701 3702 Returns {expr1} in all cases. 3703 When an error is encountered while executing {expr2} no 3704 further items in {expr1} are processed. 3705 When {expr2} is a Funcref errors inside a function are 3706 ignored, unless it was defined with the "abort" flag. 3707 3708 Can also be used as a |method|: > 3709 mylist->foreach(expr2) 3710 < 3711 Return type: |String|, |Blob|, list<{type}>, tuple<{type}> or 3712 dict<{type}> depending on {expr1} 3713 3714 3715 foreground() *foreground()* 3716 Move the Vim window to the foreground. Useful when sent from 3717 a client to a Vim server. |remote_send()| 3718 On Win32 systems this might not work, the OS does not always 3719 allow a window to bring itself to the foreground. Use 3720 |remote_foreground()| instead. 3721 3722 Return type: void 3723 {only in the Win32, Motif and GTK GUI versions and the 3724 Win32 console version} 3725 3726 fullcommand({name} [, {vim9}]) *fullcommand()* 3727 Get the full command name from a short abbreviated command 3728 name; see |20.2| for details on command abbreviations. 3729 3730 The string argument {name} may start with a `:` and can 3731 include a [range], these are skipped and not returned. 3732 Returns an empty string if a command doesn't exist, if it's 3733 ambiguous (for user-defined commands) or cannot be shortened 3734 this way. |vim9-no-shorten| 3735 3736 Without the {vim9} argument, the current script version is 3737 used. When {vim9} is present and FALSE, legacy script rules 3738 are used. When {vim9} is present and TRUE, Vim9 rules are 3739 used (e.g., "en" is not a short form of "endif"). 3740 3741 Note: Command validation is not performed. Results depend on 3742 Vim's internal command-specific identification rules. 3743 Examples: 3744 >vim 3745 echo [fullcommand('s')] |" ['substitute'] 3746 echo [fullcommand('sub')] |" ['substitute'] 3747 echo [fullcommand(': mark word')] |" ['mark'] 3748 echo [fullcommand(': markword')] |" [''] 3749 echo [fullcommand('en')] |" ['endif'] 3750 echo [fullcommand('en', v:true)] |" [''] 3751 < 3752 Can also be used as a |method|: > 3753 GetName()->fullcommand() 3754 < 3755 Return type: |String| 3756 3757 3758 funcref({name} [, {arglist}] [, {dict}]) *funcref()* 3759 Just like |function()|, but the returned Funcref will lookup 3760 the function by reference, not by name. This matters when the 3761 function {name} is redefined later. 3762 3763 Unlike |function()|, {name} must be an existing user function. 3764 It only works for an autoloaded function if it has already 3765 been loaded (to avoid mistakenly loading the autoload script 3766 when only intending to use the function name, use |function()| 3767 instead). {name} cannot be a builtin function. 3768 Returns 0 on error. 3769 3770 Can also be used as a |method|: > 3771 GetFuncname()->funcref([arg]) 3772 < 3773 Return type: func(...): any or |Number| on error 3774 3775 3776 function({name} [, {arglist}] [, {dict}]) *function()* *partial* *E700* *E923* 3777 Return a |Funcref| variable that refers to function {name}. 3778 {name} can be the name of a user defined function or an 3779 internal function. 3780 3781 {name} can also be a Funcref or a partial. When it is a 3782 partial the dict stored in it will be used and the {dict} 3783 argument is not allowed. E.g.: > 3784 let FuncWithArg = function(dict.Func, [arg]) 3785 let Broken = function(dict.Func, [arg], dict) 3786 < 3787 When using the Funcref the function will be found by {name}, 3788 also when it was redefined later. Use |funcref()| to keep the 3789 same function. 3790 3791 When {arglist} or {dict} is present this creates a partial. 3792 That means the argument list and/or the dictionary is stored 3793 in the Funcref and will be used when the Funcref is called. 3794 3795 The arguments are passed to the function in front of other 3796 arguments, but after any argument from |method|. Example: > 3797 func Callback(arg1, arg2, name) 3798 ... 3799 let Partial = function('Callback', ['one', 'two']) 3800 ... 3801 call Partial('name') 3802 < Invokes the function as with: > 3803 call Callback('one', 'two', 'name') 3804 3805 < With a |method|: > 3806 func Callback(one, two, three) 3807 ... 3808 let Partial = function('Callback', ['two']) 3809 ... 3810 eval 'one'->Partial('three') 3811 < Invokes the function as with: > 3812 call Callback('one', 'two', 'three') 3813 3814 < The function() call can be nested to add more arguments to the 3815 Funcref. The extra arguments are appended to the list of 3816 arguments. Example: > 3817 func Callback(arg1, arg2, name) 3818 "... 3819 let Func = function('Callback', ['one']) 3820 let Func2 = function(Func, ['two']) 3821 "... 3822 call Func2('name') 3823 < Invokes the function as with: > 3824 call Callback('one', 'two', 'name') 3825 3826 < The Dictionary is only useful when calling a "dict" function. 3827 In that case the {dict} is passed in as "self". Example: > 3828 function Callback() dict 3829 echo "called for " .. self.name 3830 endfunction 3831 "... 3832 let context = {"name": "example"} 3833 let Func = function('Callback', context) 3834 "... 3835 call Func() " will echo: called for example 3836 < The use of function() is not needed when there are no extra 3837 arguments, these two are equivalent, if Callback() is defined 3838 as context.Callback(): > 3839 let Func = function('Callback', context) 3840 let Func = context.Callback 3841 3842 < The argument list and the Dictionary can be combined: > 3843 function Callback(arg1, count) dict 3844 "... 3845 let context = {"name": "example"} 3846 let Func = function('Callback', ['one'], context) 3847 "... 3848 call Func(500) 3849 < Invokes the function as with: > 3850 call context.Callback('one', 500) 3851 < 3852 Returns 0 on error. 3853 3854 Can also be used as a |method|: > 3855 GetFuncname()->function([arg]) 3856 3857 < 3858 Return type: func(...): any or |Number| on error 3859 3860 3861 garbagecollect([{atexit}]) *garbagecollect()* 3862 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs| 3863 that have circular references. 3864 3865 There is hardly ever a need to invoke this function, as it is 3866 automatically done when Vim runs out of memory or is waiting 3867 for the user to press a key after 'updatetime'. Items without 3868 circular references are always freed when they become unused. 3869 This is useful if you have deleted a very big |List| and/or 3870 |Dictionary| with circular references in a script that runs 3871 for a long time. 3872 3873 When the optional {atexit} argument is one, garbage 3874 collection will also be done when exiting Vim, if it wasn't 3875 done before. This is useful when checking for memory leaks. 3876 3877 The garbage collection is not done immediately but only when 3878 it's safe to perform. This is when waiting for the user to 3879 type a character. To force garbage collection immediately use 3880 |test_garbagecollect_now()|. 3881 3882 Return type: void 3883 3884 3885 get({list}, {idx} [, {default}]) *get()* *get()-list* 3886 Get item {idx} from |List| {list}. When this item is not 3887 available return {default}. Return zero when {default} is 3888 omitted. 3889 Preferably used as a |method|: > 3890 mylist->get(idx) 3891 < 3892 Return type: any, depending on {list} 3893 3894 3895 get({tuple}, {idx} [, {default}]) *get()-tuple* 3896 Get item {idx} from |Tuple| {tuple}. When this item is not 3897 available return {default}. Return zero when {default} is 3898 omitted. 3899 Preferably used as a |method|: > 3900 mytuple->get(idx) 3901 < 3902 Return type: any, depending on {tuple} 3903 3904 3905 get({blob}, {idx} [, {default}]) *get()-blob* 3906 Get byte {idx} from |Blob| {blob}. When this byte is not 3907 available return {default}. Return -1 when {default} is 3908 omitted. 3909 Preferably used as a |method|: > 3910 myblob->get(idx) 3911 < 3912 Return type: |Number| 3913 3914 3915 get({dict}, {key} [, {default}]) *get()-dict* 3916 Get item with key {key} from |Dictionary| {dict}. When this 3917 item is not available return {default}. Return zero when 3918 {default} is omitted. Useful example: > 3919 let val = get(g:, 'var_name', 'default') 3920 < This gets the value of g:var_name if it exists, and uses 3921 'default' when it does not exist. 3922 Preferably used as a |method|: > 3923 mydict->get(key) 3924 < 3925 Return type: any, depending on {dict} 3926 3927 3928 get({func}, {what}) *get()-func* 3929 Get item {what} from |Funcref| {func}. Possible values for 3930 {what} are: 3931 "name" The function name 3932 "func" The function 3933 "dict" The dictionary 3934 "args" The list with arguments 3935 "arity" A dictionary with information about the number of 3936 arguments accepted by the function (minus the 3937 {arglist}) with the following fields: 3938 required the number of positional arguments 3939 optional the number of optional arguments, 3940 in addition to the required ones 3941 varargs |TRUE| if the function accepts a 3942 variable number of arguments |...| 3943 3944 Note: There is no error, if the {arglist} of 3945 the Funcref contains more arguments than the 3946 Funcref expects, it's not validated. 3947 3948 Returns zero on error. 3949 3950 Preferably used as a |method|: > 3951 myfunc->get(what) 3952 < 3953 Return type: any, depending on {func} and {what} 3954 3955 3956 getbufinfo([{buf}]) *getbufinfo()* 3957 getbufinfo([{dict}]) 3958 Get information about buffers as a List of Dictionaries. 3959 3960 Without an argument information about all the buffers is 3961 returned. 3962 3963 When the argument is a |Dictionary| only the buffers matching 3964 the specified criteria are returned. The following keys can 3965 be specified in {dict}: 3966 buflisted include only listed buffers. 3967 bufloaded include only loaded buffers. 3968 bufmodified include only modified buffers. 3969 3970 Otherwise, {buf} specifies a particular buffer to return 3971 information for. For the use of {buf}, see |bufname()| 3972 above. If the buffer is found the returned List has one item. 3973 Otherwise the result is an empty list. 3974 3975 Each returned List item is a dictionary with the following 3976 entries: 3977 bufnr Buffer number. 3978 changed TRUE if the buffer is modified. 3979 changedtick Number of changes made to the buffer. 3980 command TRUE if the buffer belongs to the 3981 command-line window |cmdwin|. 3982 hidden TRUE if the buffer is hidden. 3983 lastused Timestamp in seconds, like 3984 |localtime()|, when the buffer was 3985 last used. 3986 {only with the |+viminfo| feature} 3987 listed TRUE if the buffer is listed. 3988 lnum Line number used for the buffer when 3989 opened in the current window. 3990 Only valid if the buffer has been 3991 displayed in the window in the past. 3992 If you want the line number of the 3993 last known cursor position in a given 3994 window, use |line()|: > 3995 :echo line('.', {winid}) 3996 < 3997 linecount Number of lines in the buffer (only 3998 valid when loaded) 3999 loaded TRUE if the buffer is loaded. 4000 name Full path to the file in the buffer. 4001 signs List of signs placed in the buffer. 4002 Each list item is a dictionary with 4003 the following fields: 4004 id sign identifier 4005 lnum line number 4006 name sign name 4007 variables A reference to the dictionary with 4008 buffer-local variables. 4009 windows List of |window-ID|s that display this 4010 buffer 4011 popups List of popup |window-ID|s that 4012 display this buffer 4013 4014 Examples: > 4015 for buf in getbufinfo() 4016 echo buf.name 4017 endfor 4018 for buf in getbufinfo({'buflisted':1}) 4019 if buf.changed 4020 .... 4021 endif 4022 endfor 4023 < 4024 To get buffer-local options use: > 4025 getbufvar({bufnr}, '&option_name') 4026 < 4027 Can also be used as a |method|: > 4028 GetBufnr()->getbufinfo() 4029 < 4030 Return type: list<dict<any>> 4031 4032 4033 getbufline({buf}, {lnum} [, {end}]) *getbufline()* 4034 Return a |List| with the lines starting from {lnum} to {end} 4035 (inclusive) in the buffer {buf}. If {end} is omitted, a 4036 |List| with only the line {lnum} is returned. See 4037 `getbufoneline()` for only getting the line. 4038 4039 For the use of {buf}, see |bufname()| above. 4040 4041 For {lnum} and {end} "$" can be used for the last line of the 4042 buffer. Otherwise a number must be used. 4043 4044 When {lnum} is smaller than 1 or bigger than the number of 4045 lines in the buffer, an empty |List| is returned. 4046 4047 When {end} is greater than the number of lines in the buffer, 4048 it is treated as {end} is set to the number of lines in the 4049 buffer. When {end} is before {lnum} an empty |List| is 4050 returned. 4051 4052 This function works only for loaded buffers. For unloaded and 4053 non-existing buffers, an empty |List| is returned. 4054 4055 Example: > 4056 :let lines = getbufline(bufnr("myfile"), 1, "$") 4057 4058 < Can also be used as a |method|: > 4059 GetBufnr()->getbufline(lnum) 4060 < 4061 Return type: list<string> 4062 4063 4064 getbufoneline({buf}, {lnum}) *getbufoneline()* 4065 Just like `getbufline()` but only get one line and return it 4066 as a string. 4067 4068 Return type: |String| 4069 4070 4071 getbufvar({buf}, {varname} [, {def}]) *getbufvar()* 4072 The result is the value of option or local buffer variable 4073 {varname} in buffer {buf}. Note that the name without "b:" 4074 must be used. 4075 The {varname} argument is a string. 4076 When {varname} is empty returns a |Dictionary| with all the 4077 buffer-local variables. 4078 When {varname} is equal to "&" returns a |Dictionary| with all 4079 the buffer-local options. 4080 Otherwise, when {varname} starts with "&" returns the value of 4081 a buffer-local option. 4082 This also works for a global or buffer-local option, but it 4083 doesn't work for a global variable, window-local variable or 4084 window-local option. 4085 For the use of {buf}, see |bufname()| above. 4086 When the buffer or variable doesn't exist {def} or an empty 4087 string is returned, there is no error message. 4088 Examples: > 4089 :let bufmodified = getbufvar(1, "&mod") 4090 :echo "todo myvar = " .. getbufvar("todo", "myvar") 4091 4092 < Can also be used as a |method|: > 4093 GetBufnr()->getbufvar(varname) 4094 < 4095 Return type: any, depending on {varname} 4096 4097 4098 getbgcolor() *getbgcolor()* 4099 Returns a |List| describing the current background colour as 4100 [red, green, blue], each component in the range 0..255. 4101 4102 In the GUI (or with 'termguicolors' set) the value comes from 4103 the |hl-Normal| highlight group's background. In a terminal 4104 it comes from the OSC 11 response (also available as 4105 |v:termrbgresp|). 4106 Returns [] when no value is available, e.g. before the 4107 terminal has answered the OSC 11 query, or when |hl-Normal| 4108 has no background colour set. 4109 4110 Useful when manually crafting RGB image data and you want to 4111 flatten alpha onto the same colour the terminal will actually 4112 display behind the image. 4113 4114 Return type: list<any> 4115 4116 4117 getcellpixels() *getcellpixels()* 4118 Returns a |List| of terminal cell pixel size. 4119 List format is [xpixel, ypixel]. 4120 4121 Only works on Unix (terminal and gVim) and Windows (gVim 4122 only). 4123 Returns [] on other systems or on failure. 4124 Note that there could be variations across different 4125 terminals. 4126 On macOS, system Terminal.app returns sizes in points (before 4127 Retina scaling), whereas third-party terminals return raw 4128 pixel sizes (post Retina scaling). 4129 4130 Return type: list<any> 4131 4132 4133 getcellwidths() *getcellwidths()* 4134 Returns a |List| of cell widths of character ranges overridden 4135 by |setcellwidths()|. The format is equal to the argument of 4136 |setcellwidths()|. If no character ranges have their cell 4137 widths overridden, an empty List is returned. 4138 4139 Return type: list<any> 4140 4141 4142 getchangelist([{buf}]) *getchangelist()* 4143 Returns the |changelist| for the buffer {buf}. For the use 4144 of {buf}, see |bufname()| above. If buffer {buf} doesn't 4145 exist, an empty list is returned. 4146 4147 The returned list contains two entries: a list with the change 4148 locations and the current position in the list. Each 4149 entry in the change list is a dictionary with the following 4150 entries: 4151 col column number 4152 coladd column offset for 'virtualedit' 4153 lnum line number 4154 If buffer {buf} is the current buffer, then the current 4155 position refers to the position in the list. For other 4156 buffers, it is set to the length of the list. 4157 4158 Can also be used as a |method|: > 4159 GetBufnr()->getchangelist() 4160 < 4161 Return type: list<any> 4162 4163 4164 getchar([{expr} [, {opts}]]) *getchar()* 4165 Get a single character from the user or input stream. 4166 If {expr} is omitted or is -1, wait until a character is 4167 available. 4168 If {expr} is 0, only get a character when one is available. 4169 Return zero otherwise. 4170 If {expr} is 1, only check if a character is available, it is 4171 not consumed. Return zero if no character available. 4172 If you prefer always getting a string use |getcharstr()|, or 4173 specify |FALSE| as "number" in {opts}. 4174 4175 Without {expr} and when {expr} is 0 a whole character or 4176 special key is returned. If it is a single character, the 4177 result is a Number. Use |nr2char()| to convert it to a String. 4178 Otherwise a String is returned with the encoded character. 4179 For a special key it's a String with a sequence of bytes 4180 starting with 0x80 (decimal: 128). This is the same value as 4181 the String "\<Key>", e.g., "\<Left>". The returned value is 4182 also a String when a modifier (shift, control, alt) was used 4183 that is not included in the character. |keytrans()| can also 4184 be used to convert a returned String into a readable form. 4185 4186 When {expr} is 0 and Esc is typed, there will be a short delay 4187 while Vim waits to see if this is the start of an escape 4188 sequence. 4189 4190 When {expr} is 1 only the first byte is returned. For a 4191 one-byte character it is the character itself as a number. 4192 Use |nr2char()| to convert it to a String. 4193 4194 Use |getcharmod()| to obtain any additional modifiers. 4195 4196 The optional argument {opts} is a Dict and supports the 4197 following items: 4198 4199 cursor A String specifying cursor behavior 4200 when waiting for a character. 4201 "hide": hide the cursor. 4202 "keep": keep current cursor unchanged. 4203 "msg": move cursor to message area. 4204 (default: "msg") 4205 4206 number If |TRUE|, return a Number when getting 4207 a single character. 4208 If |FALSE|, the return value is always 4209 converted to a String, and an empty 4210 String (instead of 0) is returned when 4211 no character is available. 4212 (default: |TRUE|) 4213 4214 simplify If |TRUE|, include modifiers in the 4215 character if possible. E.g., return 4216 the same value for CTRL-I and <Tab>. 4217 If |FALSE|, don't include modifiers in 4218 the character. 4219 (default: |TRUE|) 4220 4221 When the user clicks a mouse button, the mouse event will be 4222 returned. The position can then be found in |v:mouse_col|, 4223 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. 4224 |getmousepos()| can also be used. Mouse move events will be 4225 ignored. 4226 This example positions the mouse as it would normally happen: > 4227 let c = getchar() 4228 if c == "\<LeftMouse>" && v:mouse_win > 0 4229 exe v:mouse_win .. "wincmd w" 4230 exe v:mouse_lnum 4231 exe "normal " .. v:mouse_col .. "|" 4232 endif 4233 < 4234 When using bracketed paste only the first character is 4235 returned, the rest of the pasted text is dropped. 4236 |xterm-bracketed-paste|. 4237 4238 There is no prompt, you will somehow have to make clear to the 4239 user that a character has to be typed. The screen is not 4240 redrawn, e.g. when resizing the window. When using a popup 4241 window it should work better with a |popup-filter|. 4242 4243 There is no mapping for the character. 4244 Key codes are replaced, thus when the user presses the <Del> 4245 key you get the code for the <Del> key, not the raw character 4246 sequence. Examples: > 4247 getchar() == "\<Del>" 4248 getchar() == "\<S-Left>" 4249 < This example redefines "f" to ignore case: > 4250 :nmap f :call FindChar()<CR> 4251 :function FindChar() 4252 : let c = nr2char(getchar()) 4253 : while col('.') < col('$') - 1 4254 : normal l 4255 : if getline('.')[col('.') - 1] ==? c 4256 : break 4257 : endif 4258 : endwhile 4259 :endfunction 4260 < 4261 You may also receive synthetic characters, such as 4262 |<CursorHold>|. Often you will want to ignore this and get 4263 another character: > 4264 :function GetKey() 4265 : let c = getchar() 4266 : while c == "\<CursorHold>" 4267 : let c = getchar() 4268 : endwhile 4269 : return c 4270 :endfunction 4271 < 4272 Return type: |Number| or |String| 4273 4274 4275 getcharmod() *getcharmod()* 4276 The result is a Number which is the state of the modifiers for 4277 the last obtained character with |getchar()| or in another way. 4278 These values are added together: 4279 2 shift 4280 4 control 4281 8 alt (meta) 4282 16 meta (when it's different from ALT) 4283 32 mouse double click 4284 64 mouse triple click 4285 96 mouse quadruple click (== 32 + 64) 4286 128 command (Mac) or super (GTK) 4287 Only the modifiers that have not been included in the 4288 character itself are obtained. Thus Shift-a results in "A" 4289 without a modifier. Returns 0 if no modifiers are used. 4290 4291 Return type: |Number| 4292 4293 4294 getcharpos({expr}) *getcharpos()* 4295 Get the position for String {expr}. Same as |getpos()| but the 4296 column number in the returned List is a character index 4297 instead of a byte index. 4298 If |getpos()| returns a very large column number, equal to 4299 |v:maxcol|, then getcharpos() will return the character index 4300 of the last character. 4301 4302 Example: 4303 With the cursor on '세' in line 5 with text "여보세요": > 4304 getcharpos('.') returns [0, 5, 3, 0] 4305 getpos('.') returns [0, 5, 7, 0] 4306 < 4307 Can also be used as a |method|: > 4308 GetMark()->getcharpos() 4309 < 4310 Return type: list<number> 4311 4312 4313 getcharsearch() *getcharsearch()* 4314 Return the current character search information as a {dict} 4315 with the following entries: 4316 4317 char character previously used for a character 4318 search (|t|, |f|, |T|, or |F|); empty string 4319 if no character search has been performed 4320 forward direction of character search; 1 for forward, 4321 0 for backward 4322 until type of character search; 1 for a |t| or |T| 4323 character search, 0 for an |f| or |F| 4324 character search 4325 4326 This can be useful to always have |;| and |,| search 4327 forward/backward regardless of the direction of the previous 4328 character search: > 4329 :nnoremap <expr> ; getcharsearch().forward ? ';' : ',' 4330 :nnoremap <expr> , getcharsearch().forward ? ',' : ';' 4331 < Also see |setcharsearch()|. 4332 4333 Return type: dict<any> 4334 4335 4336 getcharstr([{expr} [, {opts}]]) *getcharstr()* 4337 The same as |getchar()|, except that this always returns a 4338 String, and "number" isn't allowed in {opts}. 4339 4340 Return type: |String| 4341 4342 4343 getcmdcomplpat() *getcmdcomplpat()* 4344 Return completion pattern of the current command-line. 4345 Only works when the command line is being edited, thus 4346 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|. 4347 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|, 4348 |getcmdprompt()|, |getcmdcompltype()| and |setcmdline()|. 4349 Returns an empty string when completion is not defined. 4350 4351 Return type: |String| 4352 4353 4354 getcmdcompltype() *getcmdcompltype()* 4355 Return the type of the current command-line completion. 4356 Only works when the command line is being edited, thus 4357 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|. 4358 See |:command-completion| for the return string. 4359 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|, 4360 |getcmdprompt()|, |getcmdcomplpat()| and |setcmdline()|. 4361 Returns an empty string when completion is not defined. 4362 4363 To get the type of the command-line completion for a specified 4364 string, use |getcompletiontype()|. 4365 4366 Return type: |String| 4367 4368 4369 getcmdline() *getcmdline()* 4370 Return the current command-line input. Only works when the 4371 command line is being edited, thus requires use of 4372 |c_CTRL-\_e| or |c_CTRL-R_=|. 4373 Example: > 4374 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR> 4375 < Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()|, 4376 |getcmdprompt()| and |setcmdline()|. 4377 Returns an empty string when entering a password or using 4378 |inputsecret()|. 4379 4380 Return type: |String| 4381 4382 4383 getcmdpos() *getcmdpos()* 4384 Return the position of the cursor in the command line as a 4385 byte count. The first column is 1. 4386 Only works when editing the command line, thus requires use of 4387 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. 4388 Returns 0 otherwise. 4389 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|, 4390 |getcmdprompt()| and |setcmdline()|. 4391 4392 Return type: |Number| 4393 4394 4395 getcmdprompt() *getcmdprompt()* 4396 Return the current command-line prompt when using functions 4397 like |input()| or |confirm()|. 4398 Only works when the command line is being edited, thus 4399 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|. 4400 Also see |getcmdtype()|, |getcmdline()|, |getcmdpos()|, 4401 |setcmdpos()| and |setcmdline()|. 4402 4403 Return type: |String| 4404 4405 4406 getcmdscreenpos() *getcmdscreenpos()* 4407 Return the screen position of the cursor in the command line 4408 as a byte count. The first column is 1. 4409 Instead of |getcmdpos()|, it adds the prompt position. 4410 Only works when editing the command line, thus requires use of 4411 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. 4412 Returns 0 otherwise. 4413 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and 4414 |setcmdline()|. 4415 4416 Return type: |Number| 4417 4418 4419 getcmdtype() *getcmdtype()* 4420 Return the current command-line type. Possible return values 4421 are: 4422 : normal Ex command 4423 > debug mode command |debug-mode| 4424 / forward search command 4425 ? backward search command 4426 @ |input()| command 4427 - |:insert| or |:append| command 4428 = |i_CTRL-R_=| 4429 Only works when editing the command line, thus requires use of 4430 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. 4431 Returns an empty string otherwise. 4432 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|. 4433 4434 Return type: |String| 4435 4436 4437 getcmdwintype() *getcmdwintype()* 4438 Return the current |command-line-window| type. Possible return 4439 values are the same as |getcmdtype()|. Returns an empty string 4440 when not in the command-line window. 4441 4442 Return type: |String| 4443 4444 4445 getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* 4446 Return a list of command-line completion matches. The String 4447 {type} argument specifies what for. The following completion 4448 types are supported: 4449 4450 arglist file names in argument list 4451 augroup autocmd groups 4452 buffer buffer names 4453 behave |:behave| suboptions 4454 breakpoint |:breakadd| and |:breakdel| suboptions 4455 color color schemes 4456 command Ex command 4457 cmdline |cmdline-completion| result 4458 compiler compilers 4459 cscope |:cscope| suboptions 4460 custom,{func} custom completion, defined via {func} 4461 customlist,{func} custom completion, defined via {func} 4462 diff_buffer |:diffget| and |:diffput| completion 4463 dir directory names 4464 dir_in_path directory names in 'cdpath' 4465 environment environment variable names 4466 event autocommand events 4467 expression Vim expression 4468 file file and directory names 4469 file_in_path file and directory names in 'path' 4470 filetype filetype names 'filetype' 4471 filetypecmd |:filetype| suboptions 4472 function function name 4473 help help subjects 4474 highlight highlight groups 4475 history |:history| suboptions 4476 keymap keyboard mappings 4477 locale locale names (as output of locale -a) 4478 mapclear buffer argument 4479 mapping mapping name 4480 menu menus 4481 messages |:messages| suboptions 4482 option options 4483 packadd optional package |pack-add| names 4484 retab |:retab| suboptions 4485 runtime |:runtime| completion 4486 scriptnames sourced script names |:scriptnames| 4487 shellcmd Shell command 4488 shellcmdline Shell command line with filename arguments 4489 sign |:sign| suboptions 4490 syntax syntax file names 'syntax' 4491 syntime |:syntime| suboptions 4492 tag tags 4493 tag_listfiles tags, file names 4494 user user names 4495 var user variables 4496 4497 If {pat} is an empty string, then all the matches are 4498 returned. Otherwise only items matching {pat} are returned. 4499 See |wildcards| for the use of special characters in {pat}. 4500 4501 If the optional {filtered} flag is set to 1, then 'wildignore' 4502 is applied to filter the results. Otherwise all the matches 4503 are returned. The 'wildignorecase' option always applies. 4504 4505 If the 'wildoptions' option contains 'fuzzy', then fuzzy 4506 matching is used to get the completion matches. Otherwise 4507 regular expression matching is used. Thus this function 4508 follows the user preference, what happens on the command line. 4509 If you do not want this you can make 'wildoptions' empty 4510 before calling getcompletion() and restore it afterwards. 4511 4512 If {type} is "cmdline", then the |cmdline-completion| result is 4513 returned. For example, to complete the possible values after 4514 a ":call" command: > 4515 echo getcompletion('call ', 'cmdline') 4516 < 4517 If there are no matches, an empty list is returned. An 4518 invalid value for {type} produces an error. 4519 4520 Can also be used as a |method|: > 4521 GetPattern()->getcompletion('color') 4522 < 4523 Return type: list<string> 4524 4525 4526 getcompletiontype({pat}) *getcompletiontype()* 4527 Return the type of the command-line completion using {pat}. 4528 When no corresponding completion type is found, an empty 4529 string is returned. 4530 To get the current command-line completion type, use 4531 |getcmdcompltype()|. 4532 4533 Return type: |String| 4534 4535 4536 getcurpos([{winid}]) *getcurpos()* 4537 Get the position of the cursor. This is like getpos('.'), but 4538 includes an extra "curswant" item in the list: 4539 [0, lnum, col, off, curswant] ~ 4540 The "curswant" number is the preferred column when moving the 4541 cursor vertically. After |$| command it will be a very large 4542 number equal to |v:maxcol|. Also see |getcursorcharpos()| and 4543 |getpos()|. 4544 The first "bufnum" item is always zero. The byte position of 4545 the cursor is returned in 'col'. To get the character 4546 position, use |getcursorcharpos()|. 4547 4548 The optional {winid} argument can specify the window. It can 4549 be the window number or the |window-ID|. The last known 4550 cursor position is returned, this may be invalid for the 4551 current value of the buffer if it is not the current window. 4552 If {winid} is invalid a list with zeroes is returned. 4553 4554 This can be used to save and restore the cursor position: > 4555 let save_cursor = getcurpos() 4556 MoveTheCursorAround 4557 call setpos('.', save_cursor) 4558 < Note that this only works within the window. See 4559 |winrestview()| for restoring more state. 4560 4561 Can also be used as a |method|: > 4562 GetWinid()->getcurpos() 4563 < 4564 Return type: list<number> 4565 4566 4567 getcursorcharpos([{winid}]) *getcursorcharpos()* 4568 Same as |getcurpos()| but the column number in the returned 4569 List is a character index instead of a byte index. 4570 4571 Example: 4572 With the cursor on '보' in line 3 with text "여보세요": > 4573 getcursorcharpos() returns [0, 3, 2, 0, 3] 4574 getcurpos() returns [0, 3, 4, 0, 3] 4575 < 4576 Can also be used as a |method|: > 4577 GetWinid()->getcursorcharpos() 4578 < 4579 Return type: list<number> 4580 4581 4582 getcwd([{winnr} [, {tabnr}]]) *getcwd()* 4583 The result is a String, which is the name of the current 4584 working directory. 'autochdir' is ignored. 4585 4586 With {winnr} return the local current directory of this window 4587 in the current tab page. {winnr} can be the window number or 4588 the |window-ID|. 4589 If {winnr} is -1 return the name of the global working 4590 directory. See also |haslocaldir()|. 4591 4592 With {winnr} and {tabnr} return the local current directory of 4593 the window in the specified tab page. If {winnr} is -1 return 4594 the working directory of the tabpage. 4595 If {winnr} is zero use the current window, if {tabnr} is zero 4596 use the current tabpage. 4597 Without any arguments, return the actual working directory of 4598 the current window. 4599 Return an empty string if the arguments are invalid. 4600 4601 Examples: > 4602 " Get the working directory of the current window 4603 :echo getcwd() 4604 :echo getcwd(0) 4605 :echo getcwd(0, 0) 4606 " Get the working directory of window 3 in tabpage 2 4607 :echo getcwd(3, 2) 4608 " Get the global working directory 4609 :echo getcwd(-1) 4610 " Get the working directory of tabpage 3 4611 :echo getcwd(-1, 3) 4612 " Get the working directory of current tabpage 4613 :echo getcwd(-1, 0) 4614 4615 < Can also be used as a |method|: > 4616 GetWinnr()->getcwd() 4617 < 4618 Return type: |String| 4619 4620 4621 getenv({name}) *getenv()* 4622 Return the value of environment variable {name}. The {name} 4623 argument is a string, without a leading '$'. Example: > 4624 myHome = getenv('HOME') 4625 4626 < When the variable does not exist |v:null| is returned. That 4627 is different from a variable set to an empty string, although 4628 some systems interpret the empty value as the variable being 4629 deleted. See also |expr-env|. 4630 4631 Can also be used as a |method|: > 4632 GetVarname()->getenv() 4633 < 4634 Return type: |String| or |Number| 4635 4636 4637 getfontname([{name}]) *getfontname()* 4638 Without an argument returns the name of the normal font being 4639 used. Like what is used for the Normal highlight group 4640 |hl-Normal|. 4641 With an argument a check is done whether String {name} is a 4642 valid font name. If not then an empty string is returned. 4643 Otherwise the actual font name is returned, or {name} if the 4644 GUI does not support obtaining the real name. 4645 Only works when the GUI is running, thus not in your vimrc or 4646 gvimrc file. Use the |GUIEnter| autocommand to use this 4647 function just after the GUI has started. 4648 Note that the GTK GUI accepts any font name, thus checking for 4649 a valid name does not work. 4650 4651 Return type: |String| 4652 4653 4654 getfperm({fname}) *getfperm()* 4655 The result is a String, which is the read, write, and execute 4656 permissions of the given file {fname}. 4657 If {fname} does not exist or its directory cannot be read, an 4658 empty string is returned. 4659 The result is of the form "rwxrwxrwx", where each group of 4660 "rwx" flags represent, in turn, the permissions of the owner 4661 of the file, the group the file belongs to, and other users. 4662 If a user does not have a given permission the flag for this 4663 is replaced with the string "-". Examples: > 4664 :echo getfperm("/etc/passwd") 4665 :echo getfperm(expand("~/.vimrc")) 4666 < This will hopefully (from a security point of view) display 4667 the string "rw-r--r--" or even "rw-------". 4668 4669 Can also be used as a |method|: > 4670 GetFilename()->getfperm() 4671 < 4672 Return type: |String| 4673 4674 For setting permissions use |setfperm()|. 4675 4676 4677 getfsize({fname}) *getfsize()* 4678 The result is a Number, which is the size in bytes of the 4679 given file {fname}. 4680 If {fname} is a directory, 0 is returned. 4681 If the file {fname} can't be found, -1 is returned. 4682 If the size of {fname} is too big to fit in a Number then -2 4683 is returned. 4684 4685 Can also be used as a |method|: > 4686 GetFilename()->getfsize() 4687 < 4688 Return type: |Number| 4689 4690 4691 getftime({fname}) *getftime()* 4692 The result is a Number, which is the last modification time of 4693 the given file {fname}. The value is measured as seconds 4694 since 1st Jan 1970, and may be passed to |strftime()|. See also 4695 |localtime()| and |strftime()|. 4696 If the file {fname} can't be found -1 is returned. 4697 4698 Can also be used as a |method|: > 4699 GetFilename()->getftime() 4700 < 4701 Return type: |Number| 4702 4703 4704 getftype({fname}) *getftype()* 4705 The result is a String, which is a description of the kind of 4706 file of the given file {fname}. 4707 If {fname} does not exist an empty string is returned. 4708 Here is a table over different kinds of files and their 4709 results: 4710 Normal file "file" 4711 Directory "dir" 4712 Symbolic link "link" 4713 Block device "bdev" 4714 Character device "cdev" 4715 Socket "socket" 4716 FIFO "fifo" 4717 All other "other" 4718 Example: > 4719 getftype("/home") 4720 < Note that a type such as "link" will only be returned on 4721 systems that support it. On some systems only "dir" and 4722 "file" are returned. On MS-Windows a symbolic link to a 4723 directory returns "dir" instead of "link". 4724 4725 Can also be used as a |method|: > 4726 GetFilename()->getftype() 4727 < 4728 Return type: |String| 4729 4730 4731 getimstatus() *getimstatus()* 4732 The result is a Number, which is |TRUE| when the IME status is 4733 active and |FALSE| otherwise. 4734 See 'imstatusfunc'. 4735 4736 Return type: |Number| 4737 4738 4739 getinfo({kind}, {name} [, {opts}]) *getinfo()* 4740 Return a Dict with the definition of {name}. {kind} tells 4741 what {name} is looked up as: "function", "command", "option" 4742 or "vimvar". Another {kind} is an error. The result is an 4743 empty Dict when {name} is not found. 4744 4745 Every Dict has an "available" item, which is |FALSE| for a 4746 function or an option that this Vim was built without and for 4747 an Ex command that it does not implement. The other items 4748 depend on {kind}, and so do the items of the optional Dict 4749 {opts}. An item of {opts} for another {kind} is an error. 4750 4751 "function" a built-in function, or a user defined 4752 function when there is no built-in one with 4753 that name. "s:Func" finds a script-local 4754 function in that script, its "<SNR>12_Func" 4755 name from anywhere. 4756 4757 For a built-in function: 4758 name the name of the function 4759 kind "builtin" 4760 minargs the number of arguments that are required 4761 maxargs the maximum number of arguments, -1 when there 4762 is no maximum 4763 method the number of the argument that the base of a 4764 |method| call fills in, zero when the function 4765 cannot be used as a method 4766 args a List with a Dict for each argument: 4767 name the name of the argument as in the 4768 help, missing when the help does not 4769 name it 4770 types the types the argument accepts as a 4771 List of Strings, see |vim9-types|; 4772 "any" for an argument that is not 4773 checked or is checked against another 4774 argument 4775 For a function without a maximum the last item 4776 is for all the remaining arguments. 4777 returns the type of the returned value as a String, 4778 or "void" when the function returns nothing, 4779 or "any" when the type depends on the 4780 arguments and "argtypes" in {opts} is not 4781 given 4782 4783 Example: > 4784 echo getinfo('function', 'strlen') 4785 < {'name': 'strlen', 'kind': 'builtin', 4786 'available': v:true, 'minargs': 1, 'maxargs': 1, 4787 'method': 1, 4788 'args': [{'name': 'string', 4789 'types': ['string', 'number']}], 4790 'returns': 'number'} 4791 4792 When {opts} has an "argtypes" item with a List of 4793 |vim9-types|, "returns" is the type for a call with 4794 arguments of those types. A required argument that is 4795 not in the List is taken as "any". Giving more types 4796 than "maxargs" or an unknown type is an error. A type 4797 that the argument does not accept is not checked. 4798 Example: > 4799 let opts = {'argtypes': ['list<number>']} 4800 echo getinfo('function', 'sort', opts).returns 4801 < list<number> 4802 4803 For a user defined function: 4804 name the name of the function, with the script ID 4805 in front for a script-local function, as in 4806 "<SNR>12_Func" 4807 kind "function" for |:function|, "def" for |:def| 4808 args a List with a Dict for each argument: 4809 name the name of the argument 4810 type the type as a String, see 4811 |vim9-types|; "any" for a function 4812 defined with |:function| 4813 default the expression for the default value 4814 as a String, only present when there 4815 is one 4816 varargs a Dict for the variable arguments |...|, 4817 only present when the function has them: 4818 name the name of the arguments, or an empty 4819 String for "..." 4820 type the type as a String, or "list<any>" 4821 for a function defined with 4822 |:function| 4823 returns the type of the returned value as a String, 4824 or "void" when the function returns nothing, 4825 or "any" for a function defined with 4826 |:function| 4827 abort |TRUE| when the function aborts on an error, 4828 see |:func-abort| 4829 range |TRUE| when the function takes a range, see 4830 |:func-range| 4831 dict |TRUE| for a |Dictionary-function| 4832 closure |TRUE| for a closure, see |:func-closure| 4833 sid the script ID where the function was defined 4834 lnum the line number in that script 4835 4836 Example: > 4837 def g:Twice(n: number): number 4838 return n * 2 4839 enddef 4840 echo getinfo('function', 'g:Twice') 4841 < {'name': 'Twice', 'kind': 'def', 'available': v:true, 4842 'args': [{'name': 'n', 'type': 'number'}], 4843 'returns': 'number', 'abort': v:false, 4844 'range': v:false, 'dict': v:false, 4845 'closure': v:false, 'sid': 1, 'lnum': 1} 4846 4847 "command" an Ex command. {name} can be abbreviated. 4848 A user defined command is found first, as 4849 with |exists()|. The Dict is empty for an 4850 ambiguous abbreviation. 4851 name the full name of the command 4852 kind "builtin" for a built-in command, "modifier" 4853 for a command modifier like |:silent|, or 4854 "user" for a user defined command 4855 nargs a String with the number of arguments as 4856 for |:command-nargs|: "0", "1", "_", "*", 4857 "?" or "+" 4858 range |FALSE| when a range is not allowed, otherwise 4859 the default range: "." for the cursor line, 4860 "%" for the whole buffer or a Number as with 4861 |:command-range| 4862 count |FALSE| when a count is not allowed as 4863 with |:command-count|, otherwise the 4864 default count as a Number 4865 bang |TRUE| when a "!" after the name is allowed 4866 bar |TRUE| when "|" ends the command, see |:bar| 4867 register 4868 |TRUE| when a register name is accepted 4869 addr a String with what a range refers to: a 4870 value of |:command-addr|, or for a built-in 4871 command also "none", "tabs_relative", 4872 "quickfix_valid" or "unsigned" 4873 4874 Only for "user": 4875 buffer |TRUE| for a buffer-local command 4876 complete 4877 a String with the completion as for 4878 |:command-complete|, or an empty String when 4879 there is none 4880 definition 4881 the replacement text 4882 sid the script ID where the command was defined 4883 lnum the line number in that script 4884 4885 When {opts} has a "vim9" item that is |TRUE|, the 4886 command is found as in |Vim9| script: an abbreviation 4887 is not accepted and some commands do not exist. When 4888 it is |FALSE|, the command is found as in legacy Vim 4889 script. Without it the context of the caller is 4890 used. 4891 4892 Example: > 4893 echo getinfo('command', 's') 4894 < {'name': 'substitute', 'kind': 'builtin', 4895 'available': v:true, 'nargs': '*', 'range': '.', 4896 'count': v:false, 'bang': v:false, 'bar': v:false, 4897 'register': v:false, 'addr': 'lines'} 4898 4899 "option" an option. An option that is not supported 4900 in this Vim is also found, see 4901 |hidden-options|. 4902 name the full name of the option 4903 shortname 4904 the abbreviation, or an empty String when 4905 there is none 4906 type "bool", "number" or "string" 4907 scope "global", "window", "buffer", "global-window" 4908 or "global-buffer", see |global-local| 4909 default the Vim default value as a Boolean, Number 4910 or String to match "type" 4911 4912 Example: > 4913 echo getinfo('option', 'tw') 4914 < {'name': 'textwidth', 'shortname': 'tw', 4915 'available': v:true, 'type': 'number', 4916 'scope': 'buffer', 'default': 0} 4917 4918 "vimvar" a predefined Vim variable, see |v:var|. 4919 {name} must start with "v:", as in "v:count". 4920 name the name of the variable including the "v:" 4921 type the type as a String, see |vim9-types| 4922 readonly 4923 |TRUE| when the variable cannot be set 4924 compat |TRUE| when the variable can also be used 4925 without the "v:", like "count" for v:count 4926 4927 Example: > 4928 echo getinfo('vimvar', 'v:count') 4929 < {'name': 'v:count', 'available': v:true, 4930 'type': 'number', 'readonly': v:true, 4931 'compat': v:true} 4932 4933 Can also be used as a |method|: > 4934 GetName()->getinfo('function') 4935 < 4936 Return type: dict<any> 4937 4938 4939 getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* 4940 Returns the |jumplist| for the specified window. 4941 4942 Without arguments use the current window. 4943 With {winnr} only use this window in the current tab page. 4944 {winnr} can also be a |window-ID|. 4945 With {winnr} and {tabnr} use the window in the specified tab 4946 page. If {winnr} or {tabnr} is invalid, an empty list is 4947 returned. 4948 4949 The returned list contains two entries: a list with the jump 4950 locations and the last used jump position number in the list. 4951 Each entry in the jump location list is a dictionary with 4952 the following entries: 4953 bufnr buffer number 4954 col column number 4955 coladd column offset for 'virtualedit' 4956 filename filename if available 4957 lnum line number 4958 4959 Can also be used as a |method|: > 4960 GetWinnr()->getjumplist() 4961 < 4962 Return type: list<any> 4963 4964 4965 getline({lnum} [, {end}]) *getline()* 4966 Without {end} the result is a String, which is line {lnum} 4967 from the current buffer. Example: > 4968 getline(1) 4969 < When {lnum} is a String that doesn't start with a 4970 digit, |line()| is called to translate the String into a Number. 4971 To get the line under the cursor: > 4972 getline(".") 4973 < When {lnum} is a number smaller than 1 or bigger than the 4974 number of lines in the buffer, an empty string is returned. 4975 4976 When {end} is given the result is a |List| where each item is 4977 a line from the current buffer in the range {lnum} to {end}, 4978 including line {end}. 4979 {end} is used in the same way as {lnum}. 4980 Non-existing lines are silently omitted. 4981 When {end} is before {lnum} an empty |List| is returned. 4982 Example: > 4983 :let start = line('.') 4984 :let end = search("^$") - 1 4985 :let lines = getline(start, end) 4986 4987 < Can also be used as a |method|: > 4988 ComputeLnum()->getline() 4989 < 4990 Return type: list<string> or |String| depending on {end} 4991 4992 To get lines from another buffer see |getbufline()| and 4993 |getbufoneline()| 4994 4995 getloclist({nr} [, {what}]) *getloclist()* 4996 Returns a |List| with all the entries in the location list for 4997 window {nr}. {nr} can be the window number or the |window-ID|. 4998 When {nr} is zero the current window is used. 4999 5000 For a location list window, the displayed location list is 5001 returned. For an invalid window number {nr}, an empty list is 5002 returned. Otherwise, same as |getqflist()|. 5003 5004 If the optional {what} dictionary argument is supplied, then 5005 returns the items listed in {what} as a dictionary. Refer to 5006 |getqflist()| for the supported items in {what}. 5007 5008 In addition to the items supported by |getqflist()| in {what}, 5009 the following item is supported by |getloclist()|: 5010 5011 filewinid id of the window used to display files 5012 from the location list. This field is 5013 applicable only when called from a 5014 location list window. See 5015 |location-list-file-window| for more 5016 details. 5017 5018 Returns a |Dictionary| with default values if there is no 5019 location list for the window {nr}. 5020 Returns an empty Dictionary if window {nr} does not exist. 5021 5022 Examples (See also |getqflist-examples|): > 5023 :echo getloclist(3, {'all': 0}) 5024 :echo getloclist(5, {'filewinid': 0}) 5025 < 5026 Return type: list<dict<any>> or dict<any> 5027 5028 5029 getmarklist([{buf}]) *getmarklist()* 5030 Without the {buf} argument returns a |List| with information 5031 about all the global marks. |mark| 5032 5033 If the optional {buf} argument is specified, returns the 5034 local marks defined in buffer {buf}. For the use of {buf}, 5035 see |bufname()|. If {buf} is invalid, an empty list is 5036 returned. 5037 5038 Each item in the returned List is a |Dict| with the following: 5039 mark name of the mark prefixed by "'" 5040 pos a |List| with the position of the mark: 5041 [bufnum, lnum, col, off] 5042 Refer to |getpos()| for more information. 5043 file file name 5044 5045 Refer to |getpos()| for getting information about a specific 5046 mark. 5047 5048 Can also be used as a |method|: > 5049 GetBufnr()->getmarklist() 5050 < 5051 Return type: list<dict<any>> or list<any> 5052 5053 5054 getmatches([{win}]) *getmatches()* 5055 Returns a |List| with all matches previously defined for the 5056 current window by |matchadd()| and the |:match| commands. 5057 |getmatches()| is useful in combination with |setmatches()|, 5058 as |setmatches()| can restore a list of matches saved by 5059 |getmatches()|. 5060 If {win} is specified, use the window with this number or 5061 window ID instead of the current window. If {win} is invalid, 5062 an empty list is returned. 5063 Example: > 5064 :echo getmatches() 5065 < [{'group': 'MyGroup1', 'pattern': 'TODO', 5066 'priority': 10, 'id': 1}, {'group': 'MyGroup2', 5067 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > 5068 :let m = getmatches() 5069 :call clearmatches() 5070 :echo getmatches() 5071 < [] > 5072 :call setmatches(m) 5073 :echo getmatches() 5074 < [{'group': 'MyGroup1', 'pattern': 'TODO', 5075 'priority': 10, 'id': 1}, {'group': 'MyGroup2', 5076 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > 5077 :unlet m 5078 < 5079 Return type: list<dict<any>> or list<any> 5080 5081 5082 getmousepos() *getmousepos()* 5083 Returns a |Dictionary| with the last known position of the 5084 mouse. This can be used in a mapping for a mouse click or in 5085 a filter of a popup window. The items are: 5086 screenrow screen row 5087 screencol screen column 5088 winid Window ID of the click 5089 winrow row inside "winid" 5090 wincol column inside "winid" 5091 line text line inside "winid" 5092 column text column inside "winid" 5093 coladd offset (in screen columns) from the 5094 start of the clicked char 5095 All numbers are 1-based. 5096 5097 If not over a window, e.g. when in the command line or within 5098 |tabpanel|, then only "screenrow" and "screencol" are valid, 5099 the others are zero. 5100 5101 When on the status line below a window or the vertical 5102 separator right of a window, the "line" and "column" values 5103 are zero. 5104 5105 When the position is after the text then "column" is the 5106 length of the text in bytes plus one. 5107 5108 If the mouse is over a popup window then that window is used. 5109 5110 When using |getchar()| the Vim variables |v:mouse_lnum|, 5111 |v:mouse_col| and |v:mouse_winid| also provide these values. 5112 5113 Return type: dict<number> 5114 5115 5116 getmouseshape() *getmouseshape()* 5117 Returns the name of the currently showing mouse pointer. 5118 When the |+mouseshape| feature is not supported or the shape 5119 is unknown an empty string is returned. 5120 This function is mainly intended for testing. 5121 5122 Return type: |String| 5123 5124 5125 getpid() *getpid()* 5126 Return a Number which is the process ID of the Vim process. 5127 On Unix and MS-Windows this is a unique number, until Vim 5128 exits. 5129 5130 Return type: |Number| 5131 5132 5133 getpos({expr}) *getpos()* 5134 Get the position for String {expr}. 5135 The accepted values for {expr} are: *E1209* 5136 . The cursor position. 5137 $ The last line in the current buffer. 5138 'x Position of mark x (if the mark is not set, 0 is 5139 returned for all values). 5140 w0 First line visible in current window (one if the 5141 display isn't updated, e.g. in silent Ex mode). 5142 w$ Last line visible in current window (this is one 5143 less than "w0" if no lines are visible). 5144 v When not in Visual mode, returns the cursor 5145 position. In Visual mode, returns the other end 5146 of the Visual area. A good way to think about 5147 this is that in Visual mode "v" and "." complement 5148 each other. While "." refers to the cursor 5149 position, "v" refers to where |v_o| would move the 5150 cursor. As a result, you can use "v" and "." 5151 together to work on all of a selection in 5152 characterwise Visual mode. If the cursor is at 5153 the end of a characterwise Visual area, "v" refers 5154 to the start of the same Visual area. And if the 5155 cursor is at the start of a characterwise Visual 5156 area, "v" refers to the end of the same Visual 5157 area. "v" differs from |'<| and |'>| in that it's 5158 updated right away. 5159 Note that a mark in another file can be used. The line number 5160 then applies to another buffer. 5161 5162 The result is a |List| with four numbers: 5163 [bufnum, lnum, col, off] 5164 "bufnum" is zero, unless a mark like '0 or 'A is used, then it 5165 is the buffer number of the mark. 5166 "lnum" and "col" are the position in the buffer. The first 5167 column is 1. 5168 The "off" number is zero, unless 'virtualedit' is used. Then 5169 it is the offset in screen columns from the start of the 5170 character. E.g., a position within a <Tab> or after the last 5171 character. 5172 5173 For getting the cursor position see |getcurpos()|. 5174 The column number in the returned List is the byte position 5175 within the line. To get the character position in the line, 5176 use |getcharpos()|. 5177 5178 The visual marks |'<| and |'>| refer to the beginning and end 5179 of the visual selection relative to the buffer. Note that 5180 this differs from |setpos()|, where they are relative to the 5181 cursor position. 5182 5183 Note that for '< and '> Visual mode matters: when it is "V" 5184 (visual line mode) the column of '< is zero and the column of 5185 '> is a large number equal to |v:maxcol|. 5186 A very large column number equal to |v:maxcol| can be returned, 5187 in which case it means "after the end of the line". 5188 If {expr} is invalid, returns a list with all zeros. 5189 5190 This can be used to save and restore the position of a mark: > 5191 let save_a_mark = getpos("'a") 5192 ... 5193 call setpos("'a", save_a_mark) 5194 < 5195 Also see |getcharpos()|, |getcurpos()| and |setpos()|. 5196 5197 Can also be used as a |method|: > 5198 GetMark()->getpos() 5199 < 5200 Return type: list<number> 5201 5202 5203 getqflist([{what}]) *getqflist()* 5204 Returns a |List| with all the current quickfix errors. Each 5205 list item is a dictionary with these entries: 5206 bufnr number of buffer that has the file name, use 5207 |bufname()| to get the name 5208 module module name 5209 lnum line number in the buffer (first line is 1) 5210 end_lnum 5211 end of line number if the item is multiline 5212 col column number (first column is 1) 5213 end_col end of column number if the item has range 5214 vcol |TRUE|: "col" is visual column 5215 |FALSE|: "col" is byte index 5216 nr error number 5217 pattern search pattern used to locate the error 5218 text description of the error 5219 type type of the error, 'E', '1', etc. 5220 valid |TRUE|: recognized error message 5221 user_data 5222 custom data associated with the item, can be 5223 any type. This entry is present only when 5224 user data was set for this item. 5225 5226 When there is no error list or it's empty, an empty list is 5227 returned. Quickfix list entries with a non-existing buffer 5228 number are returned with "bufnr" set to zero (Note: some 5229 functions accept buffer number zero for the alternate buffer, 5230 you may need to explicitly check for zero). 5231 5232 Useful application: Find pattern matches in multiple files and 5233 do something with them: > 5234 :vimgrep /theword/jg *.c 5235 :for d in getqflist() 5236 : echo bufname(d.bufnr) ':' d.lnum '=' d.text 5237 :endfor 5238 < 5239 If the optional {what} dictionary argument is supplied, then 5240 returns only the items listed in {what} as a dictionary. The 5241 following string items are supported in {what}: 5242 changedtick get the total number of changes made 5243 to the list |quickfix-changedtick| 5244 context get the |quickfix-context| 5245 efm errorformat to use when parsing "lines". If 5246 not present, then the 'errorformat' option 5247 value is used. 5248 id get information for the quickfix list with 5249 |quickfix-ID|; zero means the id for the 5250 current list or the list specified by "nr" 5251 idx get information for the quickfix entry at this 5252 index in the list specified by 'id' or 'nr'. 5253 If set to zero, then uses the current entry. 5254 See |quickfix-index| 5255 items quickfix list entries 5256 lines parse a list of lines using 'efm' and return 5257 the resulting entries. Only a |List| type is 5258 accepted. The current quickfix list is not 5259 modified. See |quickfix-parse|. 5260 nr get information for this quickfix list; zero 5261 means the current quickfix list and "$" means 5262 the last quickfix list 5263 qfbufnr number of the buffer displayed in the quickfix 5264 window. Returns 0 if the quickfix buffer is 5265 not present. See |quickfix-buffer|. 5266 quickfixtextfunc 5267 function to get the text to display in the 5268 quickfix window. Returns an empty string if 5269 this function is not set for the list. See 5270 |quickfix-window-function|. 5271 size number of entries in the quickfix list 5272 title get the list title |quickfix-title| 5273 winid get the quickfix |window-ID| 5274 all all of the above quickfix properties 5275 Non-string items in {what} are ignored. To get the value of a 5276 particular item, set it to zero. 5277 If "nr" is not present then the current quickfix list is used. 5278 If both "nr" and a non-zero "id" are specified, then the list 5279 specified by "id" is used. 5280 To get the number of lists in the quickfix stack, set "nr" to 5281 "$" in {what}. The "nr" value in the returned dictionary 5282 contains the quickfix stack size. 5283 When "lines" is specified, all the other items except "efm" 5284 are ignored. The returned dictionary contains the entry 5285 "items" with the list of entries. 5286 5287 The returned dictionary contains the following entries: 5288 changedtick total number of changes made to the 5289 list |quickfix-changedtick| 5290 context quickfix list context. See |quickfix-context| 5291 If not present, set to "". 5292 id quickfix list ID |quickfix-ID|. If not 5293 present, set to 0. 5294 idx index of the quickfix entry in the list. If 5295 not present, set to 0. 5296 items quickfix list entries. If not present, set to 5297 an empty list. 5298 nr quickfix list number. If not present, set to 5299 0 5300 qfbufnr number of the buffer displayed in the quickfix 5301 window. If not present, set to 0. 5302 quickfixtextfunc 5303 'quickfixtextfunc' setting of the list. If 5304 not present, set to "". 5305 size number of entries in the quickfix list. If 5306 not present, set to 0. 5307 title quickfix list title text. If not present, set 5308 to "". 5309 winid quickfix |window-ID|. If not present, set to 0 5310 5311 Examples (See also |getqflist-examples|): > 5312 :echo getqflist({'all': 1}) 5313 :echo getqflist({'nr': 2, 'title': 1}) 5314 :echo getqflist({'lines' : ["F1:10:L10"]}) 5315 < 5316 Return type: list<dict<any>> or dict<any> 5317 5318 5319 getreg([{regname} [, 1 [, {list}]]]) *getreg()* 5320 The result is a String, which is the contents of register 5321 {regname}. Example: > 5322 :let cliptext = getreg('*') 5323 < When register {regname} was not set the result is an empty 5324 string. 5325 The {regname} argument must be a string. *E1162* 5326 5327 getreg('=') returns the last evaluated value of the expression 5328 register. (For use in maps.) 5329 getreg('=', 1) returns the expression itself, so that it can 5330 be restored with |setreg()|. For other registers the extra 5331 argument is ignored, thus you can always give it. 5332 5333 If {list} is present and |TRUE|, the result type is changed 5334 to |List|. Each list item is one text line. Use it if you care 5335 about zero bytes possibly present inside register: without 5336 third argument both NLs and zero bytes are represented as NLs 5337 (see |NL-used-for-Nul|). 5338 When the register was not set an empty list is returned. 5339 5340 If {regname} is "", the unnamed register '"' is used. 5341 If {regname} is not specified, |v:register| is used. 5342 In |Vim9-script| {regname} must be one character. 5343 5344 Can also be used as a |method|: > 5345 GetRegname()->getreg() 5346 < 5347 Return type: |String| or list<string> depending on {list} 5348 5349 5350 getreginfo([{regname}]) *getreginfo()* 5351 Returns detailed information about register {regname} as a 5352 Dictionary with the following entries: 5353 regcontents List of lines contained in register 5354 {regname}, like 5355 |getreg|({regname}, 1, 1). 5356 regtype the type of register {regname}, as in 5357 |getregtype()|. 5358 isunnamed Boolean flag, v:true if this register 5359 is currently pointed to by the unnamed 5360 register. 5361 points_to for the unnamed register, gives the 5362 single letter name of the register 5363 currently pointed to (see |quotequote|). 5364 For example, after deleting a line 5365 with `dd`, this field will be "1", 5366 which is the register that got the 5367 deleted text. 5368 5369 The {regname} argument is a string. If {regname} is invalid 5370 or not set, an empty Dictionary will be returned. 5371 If {regname} is "" or "@", the unnamed register '"' is used. 5372 If {regname} is not specified, |v:register| is used. 5373 The returned Dictionary can be passed to |setreg()|. 5374 In |Vim9-script| {regname} must be one character. 5375 5376 Can also be used as a |method|: > 5377 GetRegname()->getreginfo() 5378 < 5379 Return type: dict<any> 5380 5381 5382 getregion({pos1}, {pos2} [, {opts}]) *getregion()* 5383 Returns the list of strings from {pos1} to {pos2} from a 5384 buffer. 5385 5386 {pos1} and {pos2} must both be |List|s with four numbers. 5387 See |getpos()| for the format of the list. It's possible 5388 to specify positions from a different buffer, but please 5389 note the limitations at |getregion-notes|. 5390 5391 The optional argument {opts} is a Dict and supports the 5392 following items: 5393 5394 type Specify the region's selection type. 5395 See |getregtype()| for possible values, 5396 except that the width can be omitted 5397 and an empty string cannot be used. 5398 (default: "v") 5399 5400 exclusive If |TRUE|, use exclusive selection 5401 for the end position. 5402 (default: follow 'selection') 5403 5404 You can get the last selection type by |visualmode()|. 5405 If Visual mode is active, use |mode()| to get the Visual mode 5406 (e.g., in a |:vmap|). 5407 This function is useful to get text starting and ending in 5408 different columns, such as a |characterwise-visual| selection. 5409 5410 *getregion-notes* 5411 Note that: 5412 - Order of {pos1} and {pos2} doesn't matter, it will always 5413 return content from the upper left position to the lower 5414 right position. 5415 - If 'virtualedit' is enabled and the region is past the end 5416 of the lines, resulting lines are padded with spaces. 5417 - If the region is blockwise and it starts or ends in the 5418 middle of a multi-cell character, it is not included but 5419 its selected part is substituted with spaces. 5420 - If {pos1} and {pos2} are not in the same buffer, an empty 5421 list is returned. 5422 - {pos1} and {pos2} must belong to a |bufloaded()| buffer. 5423 - It is evaluated in current window context, which makes a 5424 difference if the buffer is displayed in a window with 5425 different 'virtualedit' or 'list' values. 5426 - When specifying an exclusive selection and {pos1} and {pos2} 5427 are equal, the returned list contains a single character as 5428 if selection is inclusive, to match the behavior of an empty 5429 exclusive selection in Visual mode. 5430 5431 Examples: > 5432 :xnoremap <CR> 5433 \ <Cmd>echow getregion( 5434 \ getpos('v'), getpos('.'), #{ type: mode() })<CR> 5435 < 5436 Can also be used as a |method|: > 5437 getpos('.')->getregion(getpos("'a")) 5438 < 5439 Return type: list<string> 5440 5441 5442 getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()* 5443 Same as |getregion()|, but returns a list of positions 5444 describing the buffer text segments bound by {pos1} and 5445 {pos2}. 5446 The segments are a pair of positions for every line: > 5447 [[{startpos}, {endpos}], ...] 5448 < 5449 The position is a |List| with four numbers: 5450 [bufnum, lnum, col, off] 5451 "bufnum" is the buffer number. 5452 "lnum" and "col" are the position in the buffer. The first 5453 column is 1. 5454 If the "off" number of a starting position is non-zero, it is 5455 the offset in screen columns from the start of the character. 5456 E.g., a position within a <Tab> or after the last character. 5457 If the "off" number of an ending position is non-zero, it is 5458 the offset of the character's first cell not included in the 5459 selection, otherwise all its cells are included. 5460 5461 Apart from the options supported by |getregion()|, {opts} also 5462 supports the following: 5463 5464 eol If |TRUE|, indicate positions beyond 5465 the end of a line with "col" values 5466 one more than the length of the line. 5467 If |FALSE|, positions are limited 5468 within their lines, and if a line is 5469 empty or the selection is entirely 5470 beyond the end of a line, a "col" 5471 value of 0 is used for both positions. 5472 (default: |FALSE|) 5473 5474 bounds If |TRUE|, return only the outer 5475 bounds of the region as a single 5476 pair: > 5477 [[{startpos}, {endpos}]] 5478 < {startpos} is the start position on 5479 the first line of the region and 5480 {endpos} the end position on its last 5481 line. The lines in between are not 5482 visited, which is much faster for a 5483 large region. 5484 (default: |FALSE|) 5485 5486 Using "bounds" with the same {opts} is equivalent to taking 5487 the outer positions of the full result: > 5488 let full = getregionpos(pos1, pos2, opts) 5489 let bounds = [[full[0][0], full[-1][1]]] 5490 < When the full result is empty, e.g. because {pos1} and {pos2} 5491 are in different buffers, the result is empty as well. 5492 Note that the two positions then come from different lines, so 5493 they describe a diagonal of the region and not its shape. For 5494 a blockwise region they are the start of the first line and 5495 the end of the last line, not the corners of the block. 5496 Likewise, when the first line is empty and "eol" is |FALSE|, 5497 {startpos} has a "col" of 0 while {endpos} may not. 5498 5499 Can also be used as a |method|: > 5500 getpos('.')->getregionpos(getpos("'a")) 5501 < 5502 For an example, see the highlight-yank plugin |52.6| 5503 5504 Return type: list<list<list<number>>> 5505 5506 5507 getregtype([{regname}]) *getregtype()* 5508 The result is a String, which is type of register {regname}. 5509 The value will be one of: 5510 "v" for |characterwise| text 5511 "V" for |linewise| text 5512 "<CTRL-V>{width}" for |blockwise-visual| text 5513 "" for an empty or unknown register 5514 <CTRL-V> is one character with value 0x16. 5515 The {regname} argument is a string. If {regname} is "", the 5516 unnamed register '"' is used. If {regname} is not specified, 5517 |v:register| is used. 5518 In |Vim9-script| {regname} must be one character. 5519 5520 Can also be used as a |method|: > 5521 GetRegname()->getregtype() 5522 < 5523 Return type: |String| 5524 5525 5526 getscriptinfo([{opts}]) *getscriptinfo()* 5527 Returns a |List| with information about all the sourced Vim 5528 scripts in the order they were sourced, like what 5529 `:scriptnames` shows. 5530 5531 The optional Dict argument {opts} supports the following 5532 optional items: 5533 name Script name match pattern. If specified, 5534 and "sid" is not specified, information about 5535 scripts with a name that match the pattern 5536 "name" are returned. 5537 sid Script ID |<SID>|. If specified, only 5538 information about the script with ID "sid" is 5539 returned and "name" is ignored. 5540 5541 Each item in the returned List is a |Dict| with the following 5542 items: 5543 autoload Set to TRUE for a script that was used with 5544 `import autoload` but was not actually sourced 5545 yet (see |import-autoload|). 5546 functions List of script-local function names defined in 5547 the script. Present only when a particular 5548 script is specified using the "sid" item in 5549 {opts}. 5550 name Vim script file name. 5551 sid Script ID |<SID>|. 5552 sourced Script ID of the actually sourced script that 5553 this script name links to, if any, otherwise 5554 zero 5555 variables A dictionary with the script-local variables. 5556 Present only when a particular script is 5557 specified using the "sid" item in {opts}. 5558 Note that this is a copy, the value of 5559 script-local variables cannot be changed using 5560 this dictionary. 5561 version Vim script version (|scriptversion|) 5562 5563 Examples: > 5564 :echo getscriptinfo({'name': 'myscript'}) 5565 :echo getscriptinfo({'sid': 15})[0].variables 5566 < 5567 Return type: list<dict<any>> 5568 5569 5570 getstacktrace() *getstacktrace()* 5571 Returns the current stack trace of Vim scripts. 5572 Stack trace is a |List|, of which each item is a |Dictionary| 5573 with the following items: 5574 funcref The funcref if the stack is at a function, 5575 otherwise this item is omitted. 5576 event The string of the event description if the 5577 stack is at an autocmd event, otherwise this 5578 item is omitted. 5579 lnum The line number in the script on the stack. 5580 filepath The file path of the script on the stack. 5581 5582 Return type: list<dict<any>> 5583 5584 5585 gettabinfo([{tabnr}]) *gettabinfo()* 5586 If {tabnr} is not specified, then information about all the 5587 tab pages is returned as a |List|. Each List item is a 5588 |Dictionary|. Otherwise, {tabnr} specifies the tab page 5589 number and information about that one is returned. If the tab 5590 page does not exist an empty List is returned. 5591 5592 Each List item is a |Dictionary| with the following entries: 5593 tabnr tab page number. 5594 variables a reference to the dictionary with 5595 tabpage-local variables 5596 windows List of |window-ID|s in the tab page. 5597 5598 Can also be used as a |method|: > 5599 GetTabnr()->gettabinfo() 5600 < 5601 Return type: list<dict<any>> 5602 5603 5604 gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* 5605 Get the value of a tab-local variable {varname} in tab page 5606 {tabnr}. |t:var| 5607 Tabs are numbered starting with one. 5608 The {varname} argument is a string. When {varname} is empty a 5609 dictionary with all tab-local variables is returned. 5610 Note that the name without "t:" must be used. 5611 When the tab or variable doesn't exist {def} or an empty 5612 string is returned, there is no error message. 5613 5614 Can also be used as a |method|: > 5615 GetTabnr()->gettabvar(varname) 5616 < 5617 Return type: any, depending on {varname} 5618 5619 5620 gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* 5621 Get the value of window-local variable {varname} in window 5622 {winnr} in tab page {tabnr}. 5623 The {varname} argument is a string. When {varname} is empty a 5624 dictionary with all window-local variables is returned. 5625 When {varname} is equal to "&" get the values of all 5626 window-local options in a |Dictionary|. 5627 Otherwise, when {varname} starts with "&" get the value of a 5628 window-local option. 5629 Note that {varname} must be the name without "w:". 5630 Tabs are numbered starting with one. For the current tabpage 5631 use |getwinvar()|. 5632 {winnr} can be the window number or the |window-ID|. 5633 When {winnr} is zero the current window is used. 5634 This also works for a global option, buffer-local option and 5635 window-local option, but it doesn't work for a global variable 5636 or buffer-local variable. 5637 When the tab, window or variable doesn't exist {def} or an 5638 empty string is returned, there is no error message. 5639 Examples: > 5640 :let list_is_on = gettabwinvar(1, 2, '&list') 5641 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar') 5642 < 5643 To obtain all window-local variables use: > 5644 gettabwinvar({tabnr}, {winnr}, '&') 5645 5646 < Can also be used as a |method|: > 5647 GetTabnr()->gettabwinvar(winnr, varname) 5648 < 5649 Return type: any, depending on {varname} 5650 5651 5652 gettagstack([{winnr}]) *gettagstack()* 5653 The result is a Dict, which is the tag stack of window 5654 {winnr}. 5655 {winnr} can be the window number or the |window-ID|. 5656 When {winnr} is not specified, the current window is used. 5657 When window {winnr} doesn't exist, an empty Dict is returned. 5658 5659 The returned dictionary contains the following entries: 5660 curidx Current index in the stack. When at 5661 top of the stack, set to (length + 1). 5662 Index of bottom of the stack is 1. 5663 items List of items in the stack. Each item 5664 is a dictionary containing the 5665 entries described below. 5666 length Number of entries in the stack. 5667 5668 Each item in the stack is a dictionary with the following 5669 entries: 5670 bufnr buffer number of the current jump 5671 from cursor position before the tag jump. 5672 See |getpos()| for the format of the 5673 returned list. 5674 matchnr current matching tag number. Used 5675 when multiple matching tags are found 5676 for a name. 5677 tagname name of the tag 5678 5679 See |tagstack| for more information about the tag stack. 5680 5681 Can also be used as a |method|: > 5682 GetWinnr()->gettagstack() 5683 < 5684 Return type: dict<any> 5685 5686 5687 gettext({text} [, {package}]) *gettext()* 5688 Translate String {text} if possible. 5689 This is intended for use in Vim scripts. When generating 5690 message translations the {text} is extracted by `xgettext`, 5691 the translator can add translated messages into the .po file 5692 and Vim will lookup the translation when gettext() is called. 5693 For {text} double quoted strings are preferred, because 5694 `xgettext` does not support single quoted escaped text. 5695 5696 When the {package} is specified, the translation is looked up 5697 for that specific package. This is mainly required for 5698 third-party Vim scripts. You need to specify a path to the 5699 translations with the |bindtextdomain()| function before 5700 using the gettext() function. 5701 5702 Return type: |String| 5703 5704 5705 getwininfo([{winid}]) *getwininfo()* 5706 Returns information about windows as a |List| with 5707 Dictionaries. 5708 5709 If {winid} is given, information about the window with that ID 5710 is returned, as a |List| with one item. When that window is a 5711 |popup| window, information about that popup window is 5712 returned. If the window does not exist the result is an empty 5713 list. 5714 5715 Without {winid} information about all the windows in all the 5716 tab pages (excluding |popup|s) is returned. 5717 5718 Each List item is a |Dictionary| with the following entries: 5719 botline last complete displayed buffer line 5720 bufnr number of buffer in the window 5721 height window height (excluding winbar) 5722 leftcol first column displayed; only used when 5723 'wrap' is off 5724 loclist 1 if showing a location list 5725 {only with the +quickfix feature} 5726 quickfix 1 if quickfix or location list window 5727 {only with the +quickfix feature} 5728 status_height status lines height (0 or 1) 5729 tabnr tab page number 5730 terminal 1 if a terminal window 5731 {only with the +terminal feature} 5732 textoff number of columns occupied by any 5733 'foldcolumn', 'signcolumn' and line 5734 number in front of the text 5735 topline first displayed buffer line 5736 variables a reference to the dictionary with 5737 window-local variables 5738 width window width 5739 winbar 1 if the window has a toolbar, 0 5740 otherwise 5741 wincol leftmost screen column of the window; 5742 "col" from |win_screenpos()| 5743 winid |window-ID| 5744 winnr window number 5745 winrow topmost screen line of the window; 5746 "row" from |win_screenpos()| 5747 5748 Can also be used as a |method|: > 5749 GetWinnr()->getwininfo() 5750 < 5751 Return type: list<dict<any>> 5752 5753 5754 getwinpos([{timeout}]) *getwinpos()* 5755 The result is a |List| with two numbers, the result of 5756 |getwinposx()| and |getwinposy()| combined: 5757 [x-pos, y-pos] 5758 {timeout} can be used to specify how long to wait in msec for 5759 a response from the terminal. When omitted 100 msec is used. 5760 Use a longer time for a remote terminal. 5761 When using a value less than 10 and no response is received 5762 within that time, a previously reported position is returned, 5763 if available. This can be used to poll for the position and 5764 do some work in the meantime: > 5765 while 1 5766 let res = getwinpos(1) 5767 if res[0] >= 0 5768 break 5769 endif 5770 " Do some work here 5771 endwhile 5772 < 5773 5774 Can also be used as a |method|: > 5775 GetTimeout()->getwinpos() 5776 < 5777 Return type: list<number> 5778 5779 5780 getwinposx() *getwinposx()* 5781 The result is a Number, which is the X coordinate in pixels of 5782 the left hand side of the GUI Vim window. Also works for an 5783 xterm (uses a timeout of 100 msec). 5784 The result will be -1 if the information is not available 5785 (e.g. on the Wayland backend). 5786 The value can be used with `:winpos`. 5787 5788 Return type: |Number| 5789 5790 5791 getwinposy() *getwinposy()* 5792 The result is a Number, which is the Y coordinate in pixels of 5793 the top of the GUI Vim window. Also works for an xterm (uses 5794 a timeout of 100 msec). 5795 The result will be -1 if the information is not available 5796 (e.g. on the Wayland backend). 5797 The value can be used with `:winpos`. 5798 5799 Return type: |Number| 5800 5801 5802 getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* 5803 Like |gettabwinvar()| for the current tabpage. 5804 Examples: > 5805 :let list_is_on = getwinvar(2, '&list') 5806 :echo "myvar = " .. getwinvar(1, 'myvar') 5807 5808 < Can also be used as a |method|: > 5809 GetWinnr()->getwinvar(varname) 5810 < 5811 Return type: any, depending on {varname} 5812 5813 5814 glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* 5815 Expand the file wildcards in {expr}. See |wildcards| for the 5816 use of special characters. 5817 5818 Unless the optional {nosuf} argument is given and is |TRUE|, 5819 the 'suffixes' and 'wildignore' options apply: Names matching 5820 one of the patterns in 'wildignore' will be skipped and 5821 'suffixes' affect the ordering of matches. 5822 'wildignorecase' always applies. 5823 5824 When {list} is present and it is |TRUE| the result is a |List| 5825 with all matching files. The advantage of using a List is, 5826 you also get filenames containing newlines correctly. 5827 Otherwise the result is a String and when there are several 5828 matches, they are separated by <NL> characters. 5829 5830 If the expansion fails, the result is an empty String or List. 5831 5832 You can also use |readdir()| if you need to do complicated 5833 things, such as limiting the number of matches. 5834 5835 A name for a non-existing file is not included. A symbolic 5836 link is only included if it points to an existing file. 5837 However, when the {alllinks} argument is present and it is 5838 |TRUE| then all symbolic links are included. 5839 5840 For most systems backticks can be used to get files names from 5841 any external command. Example: > 5842 :let tagfiles = glob("`find . -name tags -print`") 5843 :let &tags = substitute(tagfiles, "\n", ",", "g") 5844 < The result of the program inside the backticks should be one 5845 item per line. Spaces inside an item are allowed. 5846 5847 See |expand()| for expanding special Vim variables. See 5848 |system()| for getting the raw output of an external command. 5849 5850 Can also be used as a |method|: > 5851 GetExpr()->glob() 5852 < 5853 Return type: |String| or list<string> or list<any> depending 5854 on {list} 5855 5856 5857 glob2regpat({string}) *glob2regpat()* 5858 Convert a file pattern, as used by |glob()|, into a search 5859 pattern. The result can be used to match with a string that 5860 is a file name. E.g. > 5861 if filename =~ glob2regpat('Make*.mak') 5862 < This is equivalent to: > 5863 if filename =~ '^Make.*\.mak$' 5864 < When {string} is an empty string the result is "^$", match an 5865 empty string. 5866 Note that the result depends on the system. On MS-Windows 5867 a backslash usually means a path separator. 5868 5869 Can also be used as a |method|: > 5870 GetExpr()->glob2regpat() 5871 < 5872 Return type: |String| 5873 5874 *globpath()* 5875 globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) 5876 Perform |glob()| for String {expr} on all directories in {path} 5877 and concatenate the results. Example: > 5878 :echo globpath(&rtp, "syntax/c.vim") 5879 < 5880 {path} is a comma-separated list of directory names. Each 5881 directory name is prepended to {expr} and expanded like with 5882 |glob()|. A path separator is inserted when needed. 5883 To add a comma inside a directory name escape it with a 5884 backslash. Note that on MS-Windows a directory may have a 5885 trailing backslash, remove it if you put a comma after it. 5886 If the expansion fails for one of the directories, there is no 5887 error message. 5888 5889 Unless the optional {nosuf} argument is given and is |TRUE|, 5890 the 'suffixes' and 'wildignore' options apply: Names matching 5891 one of the patterns in 'wildignore' will be skipped and 5892 'suffixes' affect the ordering of matches. 5893 5894 When {list} is present and it is |TRUE| the result is a |List| 5895 with all matching files. The advantage of using a List is, 5896 you also get filenames containing newlines correctly. 5897 Otherwise the result is a String and when there are several 5898 matches, they are separated by <NL> characters. Example: > 5899 :echo globpath(&rtp, "syntax/c.vim", 0, 1) 5900 < 5901 {alllinks} is used as with |glob()|. 5902 5903 The "**" item can be used to search in a directory tree. 5904 For example, to find all "README.txt" files in the directories 5905 in 'runtimepath' and below: > 5906 :echo globpath(&rtp, "**/README.txt") 5907 < Upwards search and limiting the depth of "**" is not 5908 supported, thus using 'path' will not always work properly. 5909 5910 Can also be used as a |method|, the base is passed as the 5911 second argument: > 5912 GetExpr()->globpath(&rtp) 5913 < 5914 Return type: |String| or list<string> or list<any> depending 5915 on {list} 5916 5917 5918 has({feature} [, {check}]) *has()* 5919 When {check} is omitted or is zero: The result is a Number, 5920 which is 1 if the feature {feature} is supported, zero 5921 otherwise. The {feature} argument is a string, case is 5922 ignored. See |feature-list| below. 5923 5924 When {check} is present and not zero: The result is a Number, 5925 which is 1 if the feature {feature} could ever be supported, 5926 zero otherwise. This is useful to check for a typo in 5927 {feature} and to detect dead code. Keep in mind that an older 5928 Vim version will not know about a feature added later and 5929 features that have been abandoned will not be known by the 5930 current Vim version. 5931 5932 Also see |exists()| and |exists_compiled()|. 5933 5934 Note that to skip code that has a syntax error when the 5935 feature is not available, Vim may skip the rest of the line 5936 and miss a following `endif`. Therefore put the `endif` on a 5937 separate line: > 5938 if has('feature') 5939 let x = this->breaks->without->the->feature 5940 endif 5941 < If the `endif` would be moved to the second line as "| endif" it 5942 would not be found. 5943 5944 Return type: |Number| 5945 5946 5947 has_key({dict}, {key}) *has_key()* 5948 The result is a Number, which is TRUE if |Dictionary| {dict} 5949 has an entry with key {key}. FALSE otherwise. 5950 The {key} argument is a string. In |Vim9| script a number is 5951 also accepted (and converted to a string) but no other types. 5952 In legacy script the usual automatic conversion to string is 5953 done. 5954 5955 Can also be used as a |method|: > 5956 mydict->has_key(key) 5957 < 5958 Return type: |Number| 5959 5960 5961 haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* 5962 The result is a Number: 5963 1 when the window has set a local directory via |:lcd| 5964 2 when the tab-page has set a local directory via |:tcd| 5965 0 otherwise. 5966 5967 Without arguments use the current window. 5968 With {winnr} use this window in the current tab page. 5969 With {winnr} and {tabnr} use the window in the specified tab 5970 page. 5971 {winnr} can be the window number or the |window-ID|. 5972 If {winnr} is -1 it is ignored and only the tabpage is used. 5973 Return 0 if the arguments are invalid. 5974 Examples: > 5975 if haslocaldir() == 1 5976 " window local directory case 5977 elseif haslocaldir() == 2 5978 " tab-local directory case 5979 else 5980 " global directory case 5981 endif 5982 5983 " current window 5984 :echo haslocaldir() 5985 :echo haslocaldir(0) 5986 :echo haslocaldir(0, 0) 5987 " window n in current tab page 5988 :echo haslocaldir(n) 5989 :echo haslocaldir(n, 0) 5990 " window n in tab page m 5991 :echo haslocaldir(n, m) 5992 " tab page m 5993 :echo haslocaldir(-1, m) 5994 < 5995 Can also be used as a |method|: > 5996 GetWinnr()->haslocaldir() 5997 < 5998 Return type: |Number| 5999 6000 6001 hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* 6002 The result is a Number, which is TRUE if there is a mapping 6003 that contains {what} in somewhere in the rhs (what it is 6004 mapped to) and this mapping exists in one of the modes 6005 indicated by {mode}. 6006 The arguments {what} and {mode} are strings. 6007 When {abbr} is there and it is |TRUE| use abbreviations 6008 instead of mappings. Don't forget to specify Insert and/or 6009 Command-line mode. 6010 Both the global mappings and the mappings local to the current 6011 buffer are checked for a match. 6012 If no matching mapping is found FALSE is returned. 6013 The following characters are recognized in {mode}: 6014 n Normal mode 6015 v Visual and Select mode 6016 x Visual mode 6017 s Select mode 6018 o Operator-pending mode 6019 i Insert mode 6020 l Language-Argument ("r", "f", "t", etc.) 6021 c Command-line mode 6022 When {mode} is omitted, "nvo" is used. 6023 6024 This function is useful to check if a mapping already exists 6025 to a function in a Vim script. Example: > 6026 :if !hasmapto('\ABCdoit') 6027 : map <Leader>d \ABCdoit 6028 :endif 6029 < This installs the mapping to "\ABCdoit" only if there isn't 6030 already a mapping to "\ABCdoit". 6031 6032 Can also be used as a |method|: > 6033 GetRHS()->hasmapto() 6034 < 6035 Return type: |Number| 6036 6037 6038 histadd({history}, {item}) *histadd()* 6039 Add the String {item} to the history {history} which can be 6040 one of: *hist-names* 6041 "cmd" or ":" command line history 6042 "search" or "/" search pattern history 6043 "expr" or "=" typed expression history 6044 "input" or "@" input line history 6045 "debug" or ">" debug command history 6046 empty the current or last used history 6047 The {history} string does not need to be the whole name, one 6048 character is sufficient. 6049 If {item} does already exist in the history, it will be 6050 shifted to become the newest entry. 6051 The result is a Number: TRUE if the operation was successful, 6052 otherwise FALSE is returned. 6053 6054 Example: > 6055 :call histadd("input", strftime("%Y %b %d")) 6056 :let date=input("Enter date: ") 6057 < This function is not available in the |sandbox|. 6058 6059 Can also be used as a |method|, the base is passed as the 6060 second argument: > 6061 GetHistory()->histadd('search') 6062 < 6063 Return type: |Number| 6064 6065 6066 histdel({history} [, {item}]) *histdel()* 6067 Clear {history}, i.e. delete all its entries. See |hist-names| 6068 for the possible values of {history}. 6069 6070 If the parameter {item} evaluates to a String, it is used as a 6071 regular expression. All entries matching that expression will 6072 be removed from the history (if there are any). 6073 Upper/lowercase must match, unless "\c" is used |/\c|. 6074 If {item} evaluates to a Number, it will be interpreted as 6075 an index, see |:history-indexing|. The respective entry will 6076 be removed if it exists. 6077 6078 The result is TRUE for a successful operation, otherwise FALSE 6079 is returned. 6080 6081 Examples: 6082 Clear expression register history: > 6083 :call histdel("expr") 6084 < 6085 Remove all entries starting with "*" from the search history: > 6086 :call histdel("/", '^\*') 6087 < 6088 The following three are equivalent: > 6089 :call histdel("search", histnr("search")) 6090 :call histdel("search", -1) 6091 :call histdel("search", '^' .. histget("search", -1) .. '$') 6092 < 6093 To delete the last search pattern and use the last-but-one for 6094 the "n" command and 'hlsearch': > 6095 :call histdel("search", -1) 6096 :let @/ = histget("search", -1) 6097 < 6098 Can also be used as a |method|: > 6099 GetHistory()->histdel() 6100 < 6101 Return type: |Number| 6102 6103 6104 histget({history} [, {index}]) *histget()* 6105 The result is a String, the entry with Number {index} from 6106 {history}. See |hist-names| for the possible values of 6107 {history}, and |:history-indexing| for {index}. If there is 6108 no such entry, an empty String is returned. When {index} is 6109 omitted, the most recent item from the history is used. 6110 6111 Examples: 6112 Redo the second last search from history. > 6113 :execute '/' .. histget("search", -2) 6114 6115 < Define an Ex command ":H {num}" that supports re-execution of 6116 the {num}th entry from the output of |:history|. > 6117 :command -nargs=1 H execute histget("cmd", 0+<args>) 6118 < 6119 Can also be used as a |method|: > 6120 GetHistory()->histget() 6121 < 6122 Return type: |String| 6123 6124 6125 histnr({history}) *histnr()* 6126 The result is the Number of the current entry in {history}. 6127 See |hist-names| for the possible values of {history}. 6128 If an error occurred, -1 is returned. 6129 6130 Example: > 6131 :let inp_index = histnr("expr") 6132 6133 < Can also be used as a |method|: > 6134 GetHistory()->histnr() 6135 < 6136 Return type: |Number| 6137 6138 6139 hlexists({name}) *hlexists()* 6140 The result is a Number, which is TRUE if a highlight group 6141 called {name} exists. This is when the group has been 6142 defined in some way. Not necessarily when highlighting has 6143 been defined for it, it may also have been used for a syntax 6144 item. 6145 *highlight_exists()* 6146 Obsolete name: highlight_exists(). 6147 6148 Can also be used as a |method|: > 6149 GetName()->hlexists() 6150 < 6151 Return type: |Number| 6152 6153 6154 hlget([{name} [, {resolve}]]) *hlget()* 6155 Returns a List of all the highlight group attributes. If the 6156 optional {name} is specified, then returns a List with only 6157 the attributes of the specified highlight group. Returns an 6158 empty List if the highlight group {name} is not present. 6159 6160 If the optional {resolve} argument is set to v:true and the 6161 highlight group {name} is linked to another group, then the 6162 link is resolved recursively and the attributes of the 6163 resolved highlight group are returned. 6164 6165 Each entry in the returned List is a Dictionary with the 6166 following items: 6167 cleared boolean flag, set to v:true if the highlight 6168 group attributes are cleared or not yet 6169 specified. See |highlight-clear|. 6170 cterm cterm attributes. See |highlight-cterm|. 6171 ctermbg cterm background color. 6172 See |highlight-ctermbg|. 6173 ctermfg cterm foreground color. 6174 See |highlight-ctermfg|. 6175 ctermul cterm underline color. See |highlight-ctermul|. 6176 default boolean flag, set to v:true if the highlight 6177 group link is a default link. See 6178 |highlight-default|. 6179 font highlight group font. See |highlight-font|. 6180 gui gui attributes. See |highlight-gui|. 6181 guibg gui background color. See |highlight-guibg|. 6182 guifg gui foreground color. See |highlight-guifg|. 6183 guisp gui special color. See |highlight-guisp|. 6184 id highlight group ID. 6185 linksto linked highlight group name. 6186 See |:highlight-link|. 6187 name highlight group name. See |group-name|. 6188 start start terminal keycode. See |highlight-start|. 6189 stop stop terminal keycode. See |highlight-stop|. 6190 term term attributes. See |highlight-term|. 6191 6192 The 'term', 'cterm' and 'gui' items in the above Dictionary 6193 have a dictionary value with the following optional boolean 6194 items: 'bold', 'standout', 'underline', 'undercurl', 'italic', 6195 'reverse', 'inverse' and 'strikethrough'. 6196 6197 Example(s): > 6198 :echo hlget() 6199 :echo hlget('ModeMsg') 6200 :echo hlget('Number', v:true) 6201 < 6202 Can also be used as a |method|: > 6203 GetName()->hlget() 6204 < 6205 Return type: list<dict<any>> 6206 6207 6208 hlset({list}) *hlset()* 6209 Creates or modifies the attributes of a List of highlight 6210 groups. Each item in {list} is a dictionary containing the 6211 attributes of a highlight group. See |hlget()| for the list of 6212 supported items in this dictionary. 6213 6214 In addition to the items described in |hlget()|, the following 6215 additional items are supported in the dictionary: 6216 6217 force boolean flag to force the creation of 6218 a link for an existing highlight group 6219 with attributes. 6220 6221 The highlight group is identified using the 'name' item and 6222 the 'id' item (if supplied) is ignored. If a highlight group 6223 with a specified name doesn't exist, then it is created. 6224 Otherwise the attributes of an existing highlight group are 6225 modified. 6226 6227 If an empty dictionary value is used for the 'term' or 'cterm' 6228 or 'gui' entries, then the corresponding attributes are 6229 cleared. If the 'cleared' item is set to v:true, then all the 6230 attributes of the highlight group are cleared. 6231 6232 The 'linksto' item can be used to link a highlight group to 6233 another highlight group. See |:highlight-link|. 6234 6235 Returns zero for success, -1 for failure. 6236 6237 Example(s): > 6238 " add bold attribute to the Visual highlight group 6239 :call hlset([#{name: 'Visual', 6240 \ term: #{reverse: 1 , bold: 1}}]) 6241 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}]) 6242 :let l = hlget() 6243 :call hlset(l) 6244 " clear the Search highlight group 6245 :call hlset([#{name: 'Search', cleared: v:true}]) 6246 " clear the 'term' attributes for a highlight group 6247 :call hlset([#{name: 'Title', term: {}}]) 6248 " create the MyHlg group linking it to DiffAdd 6249 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}]) 6250 " remove the MyHlg group link 6251 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}]) 6252 " clear the attributes and a link 6253 :call hlset([#{name: 'MyHlg', cleared: v:true, 6254 \ linksto: 'NONE'}]) 6255 < 6256 Can also be used as a |method|: > 6257 GetAttrList()->hlset() 6258 < 6259 Return type: |Number| 6260 6261 6262 hlID({name}) *hlID()* 6263 The result is a Number, which is the ID of the highlight group 6264 with name {name}. When the highlight group doesn't exist, 6265 zero is returned. 6266 This can be used to retrieve information about the highlight 6267 group. For example, to get the background color of the 6268 "Comment" group: > 6269 :echo synIDattr(synIDtrans(hlID("Comment")), "bg") 6270 < *highlightID()* 6271 Obsolete name: highlightID(). 6272 6273 Can also be used as a |method|: > 6274 GetName()->hlID() 6275 < 6276 Return type: |Number| 6277 6278 6279 hostname() *hostname()* 6280 The result is a String, which is the name of the machine on 6281 which Vim is currently running. Machine names greater than 6282 256 characters long are truncated. 6283 6284 Return type: |String| 6285 6286 6287 iconv({string}, {from}, {to}) *iconv()* 6288 The result is a String, which is the text {string} converted 6289 from encoding {from} to encoding {to}. 6290 When the conversion completely fails an empty string is 6291 returned. When some characters could not be converted they 6292 are replaced with "?". 6293 The encoding names are whatever the iconv() library function 6294 can accept, see ":!man 3 iconv". 6295 Most conversions require Vim to be compiled with the |+iconv| 6296 feature. Otherwise only UTF-8 to latin1 conversion and back 6297 can be done. 6298 This can be used to display messages with special characters, 6299 no matter what 'encoding' is set to. Write the message in 6300 UTF-8 and use: > 6301 echo iconv(utf8_str, "utf-8", &enc) 6302 < Note that Vim uses UTF-8 for all Unicode encodings, conversion 6303 from/to UCS-2 is automatically changed to use UTF-8. You 6304 cannot use UCS-2 in a string anyway, because of the NUL bytes. 6305 6306 Can also be used as a |method|: > 6307 GetText()->iconv('latin1', 'utf-8') 6308 < 6309 Return type: |String| 6310 6311 6312 id({item}) *id()* 6313 The result is a unique String associated with the {item} and 6314 not with the {item}'s contents. It is only valid while the 6315 {item} exists and is referenced. It is valid only in the 6316 instance of vim that produces the result. The whole idea is 6317 that `id({item})` does not change if the contents of {item} 6318 changes. This is useful as a `key` for creating an identity 6319 dictionary, rather than one based on equals. 6320 6321 This operation does not reference {item} and there is no 6322 function to convert the `id` to the {item}. It may be useful to 6323 have a map of `id` to {item}. The following > 6324 var referenceMap: dict<any> 6325 var id = item->id() 6326 referenceMap[id] = item 6327 < prevents {item} from being garbage collected and provides a 6328 way to get the {item} from the `id`. 6329 6330 {item} may be a List, Tuple, Dictionary, Object, Job, Channel 6331 or Blob. If the item is not a permitted type, or it is a null 6332 value, then an empty String is returned. 6333 6334 Can also be used as a |method|: > 6335 GetItem()->id() 6336 < 6337 Return type: |String| 6338 6339 6340 indent({lnum}) *indent()* 6341 The result is a Number, which is indent of line {lnum} in the 6342 current buffer. The indent is counted in spaces, the value 6343 of 'tabstop' is relevant. {lnum} is used just like in 6344 |getline()|. 6345 When {lnum} is invalid -1 is returned. In |Vim9| script an 6346 error is given. 6347 6348 Can also be used as a |method|: > 6349 GetLnum()->indent() 6350 < 6351 Return type: |Number| 6352 6353 6354 index({object}, {expr} [, {start} [, {ic}]]) *index()* 6355 Find {expr} in {object} and return its index. See 6356 |indexof()| for using a lambda to select the item. 6357 6358 If {object} is a |List| or a |Tuple| return the lowest index 6359 where the item has a value equal to {expr}. There is no 6360 automatic conversion, so the String "4" is different from the 6361 Number 4. And the number 4 is different from the Float 4.0. 6362 The value of 'ignorecase' is not used here, case matters as 6363 indicated by the {ic} argument. 6364 6365 If {object} is |Blob| return the lowest index where the byte 6366 value is equal to {expr}. 6367 6368 If {start} is given then start looking at the item with index 6369 {start} (may be negative for an item relative to the end). 6370 6371 When {ic} is given and it is |TRUE|, ignore case. Otherwise 6372 case must match. 6373 6374 -1 is returned when {expr} is not found in {object}. 6375 Example: > 6376 :let idx = index(words, "the") 6377 :if index(numbers, 123) >= 0 6378 6379 < Can also be used as a |method|: > 6380 GetObject()->index(what) 6381 < 6382 Return type: |Number| 6383 6384 6385 indexof({object}, {expr} [, {opts}]) *indexof()* 6386 Returns the index of an item in {object} where {expr} is 6387 v:true. {object} must be a |List|, a |Tuple| or a |Blob|. 6388 6389 If {object} is a |List| or a |Tuple|, evaluate {expr} for each 6390 item in the List or Tuple until the expression is v:true 6391 and return the index of this item. 6392 6393 If {object} is a |Blob| evaluate {expr} for each byte in the 6394 Blob until the expression is v:true and return the index of 6395 this byte. 6396 6397 {expr} must be a |string| or |Funcref|. 6398 6399 If {expr} is a |string|: If {object} is a |List| or a |Tuple|, 6400 inside {expr} |v:key| has the index of the current List or 6401 Tuple item and |v:val| has the value of the item. If {object} 6402 is a |Blob|, inside {expr} |v:key| has the index of the 6403 current byte and |v:val| has the byte value. 6404 6405 If {expr} is a |Funcref| it must take two arguments: 6406 1. the key or the index of the current item. 6407 2. the value of the current item. 6408 The function must return |TRUE| if the item is found and the 6409 search should stop. 6410 6411 The optional argument {opts} is a Dict and supports the 6412 following items: 6413 startidx start evaluating {expr} at the item with this 6414 index; may be negative for an item relative to 6415 the end 6416 Returns -1 when {expr} evaluates to v:false for all the items. 6417 Example: > 6418 :let l = [#{n: 10}, #{n: 20}, #{n: 30}] 6419 :echo indexof(l, "v:val.n == 20") 6420 :echo indexof(l, {i, v -> v.n == 30}) 6421 :echo indexof(l, "v:val.n == 20", #{startidx: 1}) 6422 6423 < Can also be used as a |method|: > 6424 mylist->indexof(expr) 6425 < 6426 Return type: |Number| 6427 6428 6429 image_add({dict}) *image_add()* 6430 Add an image using the given information in {dict}. This does 6431 not display an image, it simply loads the image data so that 6432 it can be reference elsewhere (e.g. popup windows) multiple 6433 times. 6434 6435 The {dict} argument must contain the following fields: 6436 "data" a blob containing RGB or RGBA data, the format 6437 is automatically detected using the dimensions 6438 and blob size. 6439 "width" width of image in pixels 6440 "height" height of image in pixels 6441 6442 *E1584* 6443 The image may not have more than 2147483647 pixels, that is 6444 "width" times "height" must fit in a 32-bit signed integer. 6445 6446 The return value is an arbitrary ID that can be used to 6447 reference the image. 6448 6449 {only available when compiled with the |+image| feature} 6450 6451 Can also be used as a |method|: > 6452 info->image_add() 6453 < 6454 Return type: |Number| 6455 6456 6457 image_discard({id}) *image_discard()* 6458 Discard an image with ID {id}, internally decreasing its 6459 reference count. The image will only actually be deleted when 6460 there are no more references to it left. Note that after this, 6461 the given image and its ID can not be referenced or modified. 6462 This function only works on images created with |image_add()|, 6463 images created directly from popup windows can not be 6464 discarded or referenced anywhere else. 6465 6466 For example, if discarding an image that is still referenced 6467 by a popup window, the popup window will still display the 6468 image. 6469 6470 It is an error to provide an invalid image ID |E1587|. 6471 6472 {only available when compiled with the |+image| feature} 6473 6474 Can also be used as a |method|: > 6475 id->image_discard() 6476 < 6477 Return type: void 6478 6479 6480 image_info([{id}]) *image_info()* *E1587* 6481 Return a list with information about loaded images. 6482 When {id} is given only information about this image is 6483 returned. It is an error to use an invalid image ID. 6484 6485 When {id} is omitted information about all images is returned. 6486 6487 For each image the information is stored in a |Dictionary| 6488 with these items: 6489 "id" the image ID 6490 "data" newly copied blob of the image data 6491 "width" width of image in pixels 6492 "height" height of image in pixels 6493 "alpha" if image has an alpha channel (RGBA) 6494 "format" image format, either "rgb" or "rgba" 6495 6496 {only available when compiled with the |+image| feature} 6497 6498 Can also be used as a |method|: > 6499 GetImage()->image_info() 6500 < 6501 Return type: list<dict<any>> 6502 6503 6504 input({prompt} [, {text} [, {completion}]]) *input()* 6505 The result is a String, which is whatever the user typed on 6506 the command-line. The {prompt} argument is either a prompt 6507 string, or a blank string (for no prompt). A '\n' can be used 6508 in the prompt to start a new line. 6509 The highlighting set with |:echohl| is used for the prompt. 6510 The input is entered just like a command-line, with the same 6511 editing commands and mappings. There is a separate history 6512 for lines typed for input(). 6513 Example: > 6514 :if input("Coffee or beer? ") == "beer" 6515 : echo "Cheers!" 6516 :endif 6517 < 6518 If the optional {text} argument is present and not empty, this 6519 is used for the default reply, as if the user typed this. 6520 Example: > 6521 :let color = input("Color? ", "white") 6522 6523 < The optional {completion} argument specifies the type of 6524 completion supported for the input. Without it completion is 6525 not performed. The supported completion types are the same as 6526 that can be supplied to a user-defined command using the 6527 "-complete=" argument. Refer to |:command-completion| for 6528 more information. Example: > 6529 let fname = input("File: ", "", "file") 6530 < 6531 NOTE: This function must not be used in a startup file, for 6532 the versions that only run in GUI mode (e.g., the Win32 GUI). 6533 Note: When input() is called from within a mapping it will 6534 consume remaining characters from that mapping, because a 6535 mapping is handled like the characters were typed. 6536 Use |inputsave()| before input() and |inputrestore()| 6537 after input() to avoid that. Another solution is to avoid 6538 that further characters follow in the mapping, e.g., by using 6539 |:execute| or |:normal|. 6540 6541 Example with a mapping: > 6542 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR> 6543 :function GetFoo() 6544 : call inputsave() 6545 : let g:Foo = input("enter search pattern: ") 6546 : call inputrestore() 6547 :endfunction 6548 6549 < Can also be used as a |method|: > 6550 GetPrompt()->input() 6551 < 6552 Return type: |String| 6553 6554 6555 inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()* 6556 Like |input()|, but when the GUI is running and text dialogs 6557 are supported, a dialog window pops up to input the text. 6558 Example: > 6559 :let n = inputdialog("value for shiftwidth", shiftwidth()) 6560 :if n != "" 6561 : let &sw = n 6562 :endif 6563 < When the dialog is cancelled {cancelreturn} is returned. When 6564 omitted an empty string is returned. 6565 Hitting <Enter> works like pressing the OK button. Hitting 6566 <Esc> works like pressing the Cancel button. 6567 NOTE: Command-line completion is not supported. 6568 6569 Can also be used as a |method|: > 6570 GetPrompt()->inputdialog() 6571 < 6572 Return type: |String| 6573 6574 6575 inputlist({textlist}) *inputlist()* 6576 {textlist} must be a |List| of strings. This |List| is 6577 displayed, one string per line. The user will be prompted to 6578 enter a number, which is returned. 6579 The user can also select an item by clicking on it with the 6580 mouse, if the mouse is enabled in the command line ('mouse' is 6581 "a" or includes "c"). For the first string 0 is returned. 6582 When clicking above the first item a negative number is 6583 returned. When clicking on the prompt one more than the 6584 length of {textlist} is returned. 6585 Make sure {textlist} has less than 'lines' entries, otherwise 6586 it won't work. It's a good idea to put the entry number at 6587 the start of the string. And put a prompt in the first item. 6588 Example: > 6589 let color = inputlist(['Select color:', '1. red', 6590 \ '2. green', '3. blue']) 6591 6592 < Can also be used as a |method|: > 6593 GetChoices()->inputlist() 6594 < 6595 Return type: |Number| 6596 6597 6598 inputrestore() *inputrestore()* 6599 Restore typeahead that was saved with a previous |inputsave()|. 6600 Should be called the same number of times |inputsave()| is 6601 called. Calling it more often is harmless though. 6602 Returns TRUE when there is nothing to restore, FALSE 6603 otherwise. 6604 6605 Return type: |Number| 6606 6607 6608 inputsave() *inputsave()* 6609 Preserve typeahead (also from mappings) and clear it, so that 6610 a following prompt gets input from the user. Should be 6611 followed by a matching |inputrestore()| after the prompt. Can 6612 be used several times, in which case there must be just as 6613 many |inputrestore()| calls. 6614 Returns TRUE when out of memory, FALSE otherwise. 6615 6616 Return type: |Number| 6617 6618 6619 inputsecret({prompt} [, {text}]) *inputsecret()* 6620 This function acts much like the |input()| function with but 6621 two exceptions: 6622 a) the user's response will be displayed as a sequence of 6623 asterisks ("*") thereby keeping the entry secret, and 6624 b) the user's response will not be recorded on the input 6625 |history| stack. 6626 The result is a String, which is whatever the user actually 6627 typed on the command-line in response to the issued prompt. 6628 NOTE: Command-line completion is not supported. 6629 6630 Can also be used as a |method|: > 6631 GetPrompt()->inputsecret() 6632 < 6633 Return type: |String| 6634 6635 6636 insert({object}, {item} [, {idx}]) *insert()* 6637 When {object} is a |List| or a |Blob| insert {item} at the start 6638 of it. 6639 6640 If {idx} is specified insert {item} before the item with index 6641 {idx}. If {idx} is zero it goes before the first item, just 6642 like omitting {idx}. A negative {idx} is also possible, see 6643 |list-index|. -1 inserts just before the last item. 6644 6645 Returns the resulting |List| or |Blob|. Examples: > 6646 :let mylist = insert([2, 3, 5], 1) 6647 :call insert(mylist, 4, -1) 6648 :call insert(mylist, 6, len(mylist)) 6649 < The last example can be done simpler with |add()|. 6650 Note that when {item} is a |List| it is inserted as a single 6651 item. Use |extend()| to concatenate |Lists|. 6652 6653 Can also be used as a |method|: > 6654 mylist->insert(item) 6655 < 6656 Return type: |Number| 6657 6658 6659 instanceof({object}, {class} ...) *instanceof()* *E616* *E693* 6660 The result is a Number, which is |TRUE| when the {object} 6661 argument is a direct or indirect instance of a |Class|, 6662 |Interface|, or class |:type| alias specified by {class}. 6663 If {class} is varargs, the function returns |TRUE| when 6664 {object} is an instance of any of the specified classes. 6665 Example: > 6666 instanceof(animal, Dog, Cat) 6667 6668 < Can also be used as a |method|: > 6669 myobj->instanceof(mytype) 6670 < 6671 Return type: |vim9-boolean| 6672 6673 6674 interrupt() *interrupt()* 6675 Interrupt script execution. It works more or less like the 6676 user typing CTRL-C, most commands won't execute and control 6677 returns to the user. This is useful to abort execution 6678 from lower down, e.g. in an autocommand. Example: > 6679 :function s:check_typoname(file) 6680 : if fnamemodify(a:file, ':t') == '[' 6681 : echomsg 'Maybe typo' 6682 : call interrupt() 6683 : endif 6684 :endfunction 6685 :au BufWritePre * call s:check_typoname(expand('<amatch>')) 6686 < 6687 Return type: void 6688 6689 6690 invert({expr}) *invert()* 6691 Bitwise invert. The argument is converted to a number. A 6692 List, Dict or Float argument causes an error. Example: > 6693 :let bits = invert(bits) 6694 < Can also be used as a |method|: > 6695 :let bits = bits->invert() 6696 < 6697 Return type: |Number| 6698 6699 6700 isabsolutepath({path}) *isabsolutepath()* 6701 The result is a Number, which is |TRUE| when {path} is an 6702 absolute path. 6703 On Unix, a path is considered absolute when it starts with 6704 '/'. 6705 On MS-Windows, it is considered absolute when it starts with 6706 an optional drive prefix and is followed by a '\' or '/'. UNC 6707 paths are always absolute. 6708 Example: > 6709 echo isabsolutepath('/usr/share/') " 1 6710 echo isabsolutepath('./foobar') " 0 6711 echo isabsolutepath('C:\Windows') " 1 6712 echo isabsolutepath('foobar') " 0 6713 echo isabsolutepath('\\remote\file') " 1 6714 < 6715 Can also be used as a |method|: > 6716 GetName()->isabsolutepath() 6717 < 6718 Return type: |Number| 6719 6720 6721 isdirectory({directory}) *isdirectory()* 6722 The result is a Number, which is |TRUE| when a directory 6723 with the name {directory} exists. If {directory} doesn't 6724 exist, or isn't a directory, the result is |FALSE|. {directory} 6725 is any expression, which is used as a String. 6726 6727 Can also be used as a |method|: > 6728 GetName()->isdirectory() 6729 < 6730 Return type: |Number| 6731 6732 6733 isinf({expr}) *isinf()* 6734 Return 1 if {expr} is a positive infinity, or -1 a negative 6735 infinity, otherwise 0. > 6736 :echo isinf(1.0 / 0.0) 6737 < 1 > 6738 :echo isinf(-1.0 / 0.0) 6739 < -1 6740 6741 Can also be used as a |method|: > 6742 Compute()->isinf() 6743 < 6744 Return type: |Number| 6745 6746 6747 islocked({expr}) *islocked()* *E786* 6748 The result is a Number, which is |TRUE| when {expr} is the 6749 name of a locked variable. 6750 The string argument {expr} must be the name of a variable, 6751 |List| item or |Dictionary| entry, not the variable itself! 6752 Example: > 6753 :let alist = [0, ['a', 'b'], 2, 3] 6754 :lockvar 1 alist 6755 :echo islocked('alist') " 1 6756 :echo islocked('alist[1]') " 0 6757 6758 < When {expr} is a variable that does not exist -1 is returned. 6759 If {expr} uses a range, list or dict index that is out of 6760 range or does not exist you get an error message. Use 6761 |exists()| to check for existence. 6762 In Vim9 script it does not work for local function variables. 6763 6764 Can also be used as a |method|: > 6765 GetName()->islocked() 6766 < 6767 Return type: |Number| 6768 6769 6770 isnan({expr}) *isnan()* 6771 Return |TRUE| if {expr} is a float with value NaN. > 6772 echo isnan(0.0 / 0.0) 6773 < 1 6774 6775 Can also be used as a |method|: > 6776 Compute()->isnan() 6777 < 6778 Return type: |Number| 6779 6780 6781 items({expr}) *items()* 6782 Return a |List| with all key/index and value pairs of {expr}. 6783 Each |List| item is a list with two items: 6784 - for a |Dict|: the key and the value 6785 - for a |List|, |Tuple|, |Blob| or |String|: the index and the 6786 value 6787 The returned |List| is in arbitrary order for a |Dict|, 6788 otherwise it's in ascending order of the index. 6789 6790 Also see |keys()| and |values()|. 6791 6792 Examples: > 6793 let mydict = #{a: 'red', b: 'blue'} 6794 for [key, value] in items(mydict) 6795 echo $"{key} = {value}" 6796 endfor 6797 echo items([1, 2, 3]) 6798 echo items(('a', 'b', 'c')) 6799 echo items("foobar") 6800 echo items(0z0102) 6801 < 6802 Can also be used as a |method|: > 6803 mydict->items() 6804 < 6805 Return type: list<list<any>> or list<any> 6806 6807 6808 job_ functions are documented here: |job-functions-details| 6809 6810 6811 join({expr} [, {sep}]) *join()* 6812 Join the items in {expr} together into one String. {expr} can 6813 be a |List| or a |Tuple|. 6814 When {sep} is specified it is put in between the items. If 6815 {sep} is omitted a single space is used. 6816 Note that {sep} is not added at the end. You might want to 6817 add it there too: > 6818 let lines = join(mylist, "\n") .. "\n" 6819 < String items are used as-is. |Lists|, |Tuples| and 6820 |Dictionaries| are converted into a string like with 6821 |string()|. The opposite function is |split()|. 6822 6823 Can also be used as a |method|: > 6824 mylist->join() 6825 < 6826 Return type: |String| 6827 6828 6829 js_decode({string}) *js_decode()* 6830 This is similar to |json_decode()| with these differences: 6831 - Object key names do not have to be in quotes. 6832 - Strings can be in single quotes. 6833 - Empty items in an array (between two commas) are allowed and 6834 result in v:none items. 6835 - Capitalization is ignored in keywords: true, false, null, 6836 NaN, Infinity and -Infinity. 6837 6838 Can also be used as a |method|: > 6839 ReadObject()->js_decode() 6840 < 6841 Return type: any, depending on {varname} 6842 6843 6844 js_encode({expr}) *js_encode()* 6845 This is similar to |json_encode()| with these differences: 6846 - Object key names are not in quotes. 6847 - v:none items in an array result in an empty item between 6848 commas. 6849 For example, the Vim object: 6850 [1,v:none,{"one":1},v:none] ~ 6851 Will be encoded as: 6852 [1,,{one:1},,] ~ 6853 While json_encode() would produce: 6854 [1,null,{"one":1},null] ~ 6855 This encoding is valid for JavaScript. It is more efficient 6856 than JSON, especially when using an array with optional items. 6857 6858 Can also be used as a |method|: > 6859 GetObject()->js_encode() 6860 < 6861 Return type: |String| 6862 6863 6864 json_decode({string}) *json_decode()* *E491* 6865 This parses a JSON formatted string and returns the equivalent 6866 in Vim values. See |json_encode()| for the relation between 6867 JSON and Vim values. 6868 The decoding is permissive: 6869 - A trailing comma in an array and object is ignored, e.g. 6870 "[1, 2, ]" is the same as "[1, 2]". 6871 - Integer keys are accepted in objects, e.g. {1:2} is the 6872 same as {"1":2}. 6873 - More floating point numbers are recognized, e.g. "1." for 6874 "1.0", or "001.2" for "1.2". Special floating point values 6875 "Infinity", "-Infinity" and "NaN" are accepted. 6876 - Leading zeroes in integer numbers are ignored, e.g. "012" 6877 for "12" or "-012" for "-12". 6878 - Control characters U+0000 through U+001F which are not 6879 escaped in strings are accepted, e.g. " " (tab 6880 character in string) for "\t". 6881 - An empty JSON expression or made of only spaces is accepted 6882 and results in v:none. 6883 - Backslash in an invalid 2-character sequence escape is 6884 ignored, e.g. "\a" is decoded as "a". 6885 - A surrogate pair in JSON strings is a 12 character sequence 6886 such as "\uD834\uDD1E". A lone surrogate or an invalid 6887 surrogate pair (e.g. "\uD800" or "\uD800\uD800") results 6888 in an error. 6889 *E938* 6890 A duplicate key in an object, valid in rfc7159, is not 6891 accepted by json_decode() as the result must be a valid Vim 6892 type, e.g. this fails: {"a":"b", "a":"c"} 6893 6894 Can also be used as a |method|: > 6895 ReadObject()->json_decode() 6896 < 6897 Return type: any, depending on {varname} 6898 6899 6900 json_encode({expr}) *json_encode()* 6901 Encode {expr} as JSON and return this as a string. 6902 The encoding is specified in: 6903 https://tools.ietf.org/html/rfc7159.html 6904 Vim values are converted as follows: *E1161* 6905 |Number| decimal number 6906 |Float| floating point number 6907 Float nan "NaN" 6908 Float inf "Infinity" 6909 Float -inf "-Infinity" 6910 |String| in double quotes (possibly null) 6911 |Funcref| not possible, error 6912 |List| as an array (possibly null); when 6913 used recursively: [] 6914 |Tuple| as an array (possibly null); when 6915 used recursively: [] 6916 |Dict| as an object (possibly null); when 6917 used recursively: {} 6918 |Blob| as an array of the individual bytes 6919 v:false "false" 6920 v:true "true" 6921 v:none "null" 6922 v:null "null" 6923 Note that NaN and Infinity are passed on as values. This is 6924 missing in the JSON standard, but several implementations do 6925 allow it. If not then you will get an error. 6926 If a string contains an illegal character then the replacement 6927 character 0xfffd is used. 6928 6929 Can also be used as a |method|: > 6930 GetObject()->json_encode() 6931 < 6932 Return type: |String| 6933 6934 6935 keys({dict}) *keys()* 6936 Return a |List| with all the keys of {dict}. The |List| is in 6937 arbitrary order. Also see |items()| and |values()|. 6938 6939 Can also be used as a |method|: > 6940 mydict->keys() 6941 < 6942 Return type: list<string> 6943 6944 6945 keytrans({string}) *keytrans()* 6946 Turn the internal byte representation of keys into a form that 6947 can be used for |:map|. E.g. > 6948 :let xx = "\<C-Home>" 6949 :echo keytrans(xx) 6950 < <C-Home> 6951 6952 Can also be used as a |method|: > 6953 "\<C-Home>"->keytrans() 6954 < 6955 Return type: |String| 6956 6957 6958 len({expr}) *len()* *E701* 6959 The result is a Number, which is the length of the argument. 6960 When {expr} is a String or a Number the length in bytes is 6961 used, as with |strlen()|. 6962 When {expr} is a |List| the number of items in the |List| is 6963 returned. 6964 When {expr} is a |Tuple| the number of items in the |Tuple| is 6965 returned. 6966 When {expr} is a |Blob| the number of bytes is returned. 6967 When {expr} is a |Dictionary| the number of entries in the 6968 |Dictionary| is returned. 6969 When {expr} is an |Object|, invokes the len() method in the 6970 object (if present) to get the length (|object-len()|). 6971 Otherwise returns zero. 6972 6973 Can also be used as a |method|: > 6974 mylist->len() 6975 < 6976 Return type: |Number| 6977 6978 6979 libcall({libname}, {funcname}, {argument}) *libcall()* *E364* *E368* 6980 Call function {funcname} in the run-time library {libname} 6981 with single argument {argument}. 6982 This is useful to call functions in a library that you 6983 especially made to be used with Vim. Since only one argument 6984 is possible, calling standard library functions is rather 6985 limited. 6986 The result is the String returned by the function. If the 6987 function returns NULL, this will appear as an empty string "" 6988 to Vim. 6989 If the function returns a number, use |libcallnr()|! 6990 If {argument} is a number, it is passed to the function as an 6991 int; if {argument} is a string, it is passed as a 6992 null-terminated string. 6993 This function will fail in |restricted-mode|. 6994 6995 libcall() allows you to write your own 'plug-in' extensions to 6996 Vim without having to recompile the program. It is NOT a 6997 means to call system functions! If you try to do so Vim will 6998 very probably crash. 6999 7000 For Win32, the functions you write must be placed in a DLL 7001 and use the normal C calling convention (NOT Pascal which is 7002 used in Windows System DLLs). The function must take exactly 7003 one parameter, either a character pointer or a long integer, 7004 and must return a character pointer or NULL. The character 7005 pointer returned must point to memory that will remain valid 7006 after the function has returned (e.g. in static data in the 7007 DLL). If it points to allocated memory, that memory will 7008 leak away. Using a static buffer in the function should work, 7009 it's then freed when the DLL is unloaded. 7010 7011 WARNING: If the function returns a non-valid pointer, Vim may 7012 crash! This also happens if the function returns a number, 7013 because Vim thinks it's a pointer. 7014 For Win32 systems, {libname} should be the filename of the DLL 7015 without the ".DLL" suffix. A full path is only required if 7016 the DLL is not in the usual places. 7017 For Unix: When compiling your own plugins, remember that the 7018 object code must be compiled as position-independent ('PIC'). 7019 {only in Win32 and some Unix versions, when the |+libcall| 7020 feature is present} 7021 Examples: > 7022 :echo libcall("libc.so", "getenv", "HOME") 7023 7024 < Can also be used as a |method|, the base is passed as the 7025 third argument: > 7026 GetValue()->libcall("libc.so", "getenv") 7027 < 7028 7029 libcallnr({libname}, {funcname}, {argument}) *libcallnr()* 7030 Just like |libcall()|, but used for a function that returns an 7031 int instead of a string. 7032 {only in Win32 and some Unix versions, when the |+libcall| 7033 feature is present} 7034 Examples: > 7035 :echo libcallnr("/usr/lib/libc.so", "getpid", "") 7036 :call libcallnr("libc.so", "printf", "Hello World!\n") 7037 :call libcallnr("libc.so", "sleep", 10) 7038 < 7039 Can also be used as a |method|, the base is passed as the 7040 third argument: > 7041 GetValue()->libcallnr("libc.so", "printf") 7042 < 7043 Return type: |Number| 7044 7045 7046 line({expr} [, {winid}]) *line()* 7047 The result is a Number, which is the line number of the file 7048 position given with {expr}. The {expr} argument is a string. 7049 See |getpos()| for accepted positions. 7050 7051 To get the column number use |col()|. To get both use 7052 |getpos()|. 7053 7054 With the optional {winid} argument the values are obtained for 7055 that window instead of the current window. 7056 7057 Returns 0 for invalid values of {expr} and {winid}. 7058 7059 Examples: > 7060 line(".") line number of the cursor 7061 line(".", winid) idem, in window "winid" 7062 line("'t") line number of mark t 7063 line("'" .. marker) line number of mark marker 7064 < 7065 To jump to the last known position when opening a file see 7066 |last-position-jump|. 7067 7068 Can also be used as a |method|: > 7069 GetValue()->line() 7070 < 7071 Return type: |Number| 7072 7073 7074 line2byte({lnum}) *line2byte()* 7075 Return the byte count from the start of the buffer for line 7076 {lnum}. This includes the end-of-line character, depending on 7077 the 'fileformat' option for the current buffer. The first 7078 line returns 1. 'encoding' matters, 'fileencoding' is ignored. 7079 This can also be used to get the byte count for the line just 7080 below the last line: > 7081 line2byte(line("$") + 1) 7082 < This is the buffer size plus one. If 'fileencoding' is empty 7083 it is the file size plus one. {lnum} is used like with 7084 |getline()|. When {lnum} is invalid, or the |+byte_offset| 7085 feature has been disabled at compile time, -1 is returned. 7086 Also see |byte2line()|, |go| and |:goto|. 7087 7088 Can also be used as a |method|: > 7089 GetLnum()->line2byte() 7090 < 7091 Return type: |Number| 7092 7093 7094 lispindent({lnum}) *lispindent()* 7095 Get the amount of indent for line {lnum} according the lisp 7096 indenting rules, as with 'lisp'. 7097 The indent is counted in spaces, the value of 'tabstop' is 7098 relevant. {lnum} is used just like in |getline()|. 7099 When {lnum} is invalid -1 is returned. In |Vim9| script an 7100 error is given. 7101 7102 Can also be used as a |method|: > 7103 GetLnum()->lispindent() 7104 < 7105 Return type: |Number| 7106 7107 7108 list2blob({list}) *list2blob()* 7109 Return a Blob concatenating all the number values in {list}. 7110 Examples: > 7111 list2blob([1, 2, 3, 4]) returns 0z01020304 7112 list2blob([]) returns 0z 7113 < Returns an empty Blob on error. If one of the numbers is 7114 negative or more than 255 error *E1239* is given. 7115 7116 |blob2list()| does the opposite. 7117 7118 Can also be used as a |method|: > 7119 GetList()->list2blob() 7120 < 7121 Return type: |Blob| 7122 7123 7124 list2str({list} [, {utf8}]) *list2str()* 7125 Convert each number in {list} to a character string and 7126 concatenates them all. Examples: > 7127 list2str([32]) returns " " 7128 list2str([65, 66, 67]) returns "ABC" 7129 < The same can be done (slowly) with: > 7130 join(map(list, {nr, val -> nr2char(val)}), '') 7131 < |str2list()| does the opposite. 7132 7133 When {utf8} is omitted or zero, the current 'encoding' is 7134 used. 7135 When {utf8} is TRUE, always return UTF-8 characters. 7136 With UTF-8 composing characters work as expected: > 7137 list2str([97, 769]) returns "á" 7138 < 7139 Returns an empty string on error. 7140 7141 Can also be used as a |method|: > 7142 GetList()->list2str() 7143 < 7144 Return type: |String| 7145 7146 7147 list2tuple({list}) *list2tuple()* 7148 Create a Tuple from a shallow copy of the list items. 7149 Examples: > 7150 list2tuple([1, 2, 3]) returns (1, 2, 3) 7151 < |tuple2list()| does the opposite. 7152 7153 This function doesn't recursively convert all the List items 7154 in {list} to a Tuple. Note that the items are identical 7155 between the list and the tuple, changing an item changes the 7156 contents of both the tuple and the list. 7157 7158 Returns an empty tuple on error. 7159 7160 Can also be used as a |method|: > 7161 GetList()->list2tuple() 7162 < 7163 Return type: tuple<{type}> (depending on the given |List|) 7164 7165 7166 listener_add({callback} [, {buf} [, {options}]]) *listener_add()* 7167 Add a callback function that will be invoked when changes have 7168 been made to buffer {buf}. 7169 {buf} refers to a buffer name or number. For the accepted 7170 values, see |bufname()|. When {buf} is omitted the current 7171 buffer is used. 7172 Returns a unique ID that can be passed to |listener_remove()|. 7173 7174 If the {buf} already has registered callbacks then the 7175 equivalent of > 7176 listener_flush({buf}) 7177 < is performed before the new callback is added. 7178 7179 The {callback} is invoked with five arguments: 7180 bufnr the buffer that was changed 7181 start first changed line number 7182 end first line number below the change 7183 added number of lines added, negative if lines were 7184 deleted 7185 changes a List of items with details about the changes 7186 7187 Example: > 7188 func Listener(bufnr, start, end, added, changes) 7189 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed' 7190 endfunc 7191 call listener_add('Listener', bufnr) 7192 7193 < The List cannot be changed. Each item in "changes" is a 7194 dictionary with these entries: 7195 lnum the first line number of the change 7196 end the first line below the change 7197 added number of lines added; negative if lines were 7198 deleted 7199 col first column in "lnum" that was affected by 7200 the change; one if unknown or the whole line 7201 was affected; this is a byte index, first 7202 character has a value of one. 7203 text only present when the "text" option is set 7204 for at least one listener, see below 7205 When lines are inserted (not when a line is split, e.g. by 7206 typing CR in Insert mode) the values are: 7207 lnum line above which the new line is added 7208 end equal to "lnum" 7209 added number of lines inserted 7210 col 1 7211 When lines are deleted the values are: 7212 lnum the first deleted line 7213 end the line below the first deleted line, before 7214 the deletion was done 7215 added negative, number of lines deleted 7216 col 1 7217 When lines are changed: 7218 lnum the first changed line 7219 end the line below the last changed line 7220 added 0 7221 col first column with a change or 1 7222 7223 {options} is a Dictionary with these optional entries: 7224 unbuffered invoke the {callback} for every single change 7225 instead of for a batch of changes 7226 text include the resulting text as a |List| of 7227 Strings in each item of "changes" 7228 For backwards compatibility {options} may also be a |Boolean|, 7229 which is then used for the "unbuffered" entry. 7230 7231 When "unbuffered" is |FALSE| or not provided the {callback} is 7232 invoked: 7233 7234 1. Just before the screen is updated. 7235 2. When |listener_flush()| is called. 7236 3. When a change is being made that changes the line count in 7237 a way that causes a line number in the list of changes to 7238 become invalid. 7239 4. When "text" is set and a lot of text has been recorded. 7240 7241 The entries are in the order the changes were made, thus the 7242 most recent change is at the end. 7243 7244 Reasons three and four make the {callback} run while another 7245 command is executing, carrying the changes made before it. Do 7246 not assume that what a {callback} receives was caused by the 7247 command that is running. 7248 7249 Because of the third reason for triggering a callback listed 7250 above, the line numbers passed to the callback are not 7251 guaranteed to be valid. In particular, the end value can be 7252 greater than line('$') + 1. If this is a problem then set 7253 "unbuffered". 7254 7255 When "unbuffered" is |TRUE| the {callback} is invoked for every 7256 single change. The changes list only holds a single 7257 dictionary and the "start", "end" and "added" values in the 7258 dictionary are the same as the corresponding callback 7259 arguments. The line numbers are valid when the callback is 7260 invoked, but later changes may make them invalid, thus keeping 7261 a copy for later might not work. 7262 7263 *listener-text* 7264 When "text" is set each item in "changes" gets a "text" entry, 7265 a List with the lines that occupy the changed region right 7266 after that change was made: the lines "lnum" up to but not 7267 including "end" plus "added". This List is empty when the 7268 change only deleted lines. Together with "lnum", "end" and 7269 "added" the item then fully describes the change: replace the 7270 lines "lnum" up to but not including "end" with "text". 7271 7272 The text is copied at the moment the change is recorded, so it 7273 is not affected by later changes. Without it a buffered 7274 {callback} cannot reliably obtain the text of a change: two 7275 changes to the same line do not change the line count and are 7276 reported together, and by then |getbufline()| can only return 7277 the result of the second one. Setting "unbuffered" avoids 7278 that as well, but then the {callback} is invoked for every 7279 single change, which is expensive for a command that changes 7280 many lines. 7281 7282 Setting "text" costs a copy of the changed lines for every 7283 change. To keep the memory used by a long sequence of changes 7284 bounded, the {callback} is also invoked when a lot of text has 7285 been recorded. 7286 7287 The recorded changes are kept per buffer and shared by all 7288 listeners for that buffer. Therefore, when at least one 7289 listener for the buffer sets "text", every {callback} for that 7290 buffer gets the "text" entry. 7291 7292 The {callback} is invoked with the text locked, see 7293 |textlock|. If you do need to make changes to the buffer, use 7294 a timer to do this later |timer_start()|. 7295 7296 You may not call listener_add() during the {callback}. *E1569* 7297 7298 The {callback} is not invoked when the buffer is first loaded. 7299 Use the |BufReadPost| autocmd event to handle the initial text 7300 of a buffer. 7301 The {callback} is also not invoked when the buffer is 7302 unloaded, use the |BufUnload| autocmd event for that. 7303 7304 Returns zero if {callback} or {buf} is invalid. 7305 7306 Can also be used as a |method|, the base is passed as the 7307 second argument: > 7308 GetBuffer()->listener_add(callback) 7309 < 7310 This function is not available in the |sandbox|. 7311 7312 Return type: |Number| 7313 7314 7315 listener_flush([{buf}]) *listener_flush()* 7316 Invoke listener callbacks for buffer {buf}. If there are no 7317 pending changes then no callbacks are invoked. 7318 7319 {buf} refers to a buffer name or number. For the accepted 7320 values, see |bufname()|. When {buf} is omitted the current 7321 buffer is used. 7322 7323 Can also be used as a |method|: > 7324 GetBuffer()->listener_flush() 7325 < 7326 This function is not available in the |sandbox|. 7327 7328 Return type: void 7329 7330 7331 listener_remove({id}) *listener_remove()* 7332 Remove a listener previously added with |listener_add()|. 7333 Returns FALSE when {id} could not be found, TRUE when {id} was 7334 removed. 7335 7336 Can also be used as a |method|: > 7337 GetListenerId()->listener_remove() 7338 < 7339 This function is not available in the |sandbox|. 7340 7341 Return type: |Number| 7342 7343 7344 localtime() *localtime()* 7345 Return the current time, measured as seconds since 1st Jan 7346 1970. See also |strftime()|, |strptime()| and |getftime()|. 7347 7348 Return type: |Number| 7349 7350 7351 log({expr}) *log()* 7352 Return the natural logarithm (base e) of {expr} as a |Float|. 7353 {expr} must evaluate to a |Float| or a |Number| in the range 7354 (0, inf]. 7355 Returns 0.0 if {expr} is not a |Float| or a |Number|. 7356 Examples: > 7357 :echo log(10) 7358 < 2.302585 > 7359 :echo log(exp(5)) 7360 < 5.0 7361 7362 Can also be used as a |method|: > 7363 Compute()->log() 7364 < 7365 Return type: |Float| 7366 7367 7368 log10({expr}) *log10()* 7369 Return the logarithm of Float {expr} to base 10 as a |Float|. 7370 {expr} must evaluate to a |Float| or a |Number|. 7371 Returns 0.0 if {expr} is not a |Float| or a |Number|. 7372 Examples: > 7373 :echo log10(1000) 7374 < 3.0 > 7375 :echo log10(0.01) 7376 < -2.0 7377 7378 Can also be used as a |method|: > 7379 Compute()->log10() 7380 < 7381 Return type: |Float| 7382 7383 7384 luaeval({expr} [, {expr}]) *luaeval()* 7385 Evaluate Lua expression {expr} and return its result converted 7386 to Vim data structures. Second {expr} may hold additional 7387 argument accessible as _A inside first {expr}. 7388 Strings are returned as they are. 7389 Boolean objects are converted to numbers. 7390 Numbers are converted to |Float| values. 7391 Dictionaries and lists obtained by vim.eval() are returned 7392 as-is. 7393 Other objects are returned as zero without any errors. 7394 See |lua-luaeval| for more details. 7395 Note that in a `:def` function local variables are not visible 7396 to {expr}. 7397 7398 Can also be used as a |method|: > 7399 GetExpr()->luaeval() 7400 < 7401 Return type: any, depending on {expr} 7402 7403 {only available when compiled with the |+lua| feature} 7404 7405 7406 map({expr1}, {expr2}) *map()* 7407 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. 7408 When {expr1} is a |List| or |Dictionary|, replace each 7409 item in {expr1} with the result of evaluating {expr2}. 7410 For a |Blob| each byte is replaced. 7411 For a |String|, each character, including composing 7412 characters, is replaced. 7413 If the item type changes you may want to use |mapnew()| to 7414 create a new List or Dictionary. This is required when using 7415 Vim9 script. 7416 7417 {expr2} must be a |String| or |Funcref|. 7418 7419 If {expr2} is a |String|, inside {expr2} |v:val| has the value 7420 of the current item. For a |Dictionary| |v:key| has the key 7421 of the current item and for a |List| |v:key| has the index of 7422 the current item. For a |Blob| |v:key| has the index of the 7423 current byte. For a |String| |v:key| has the index of the 7424 current character. 7425 Example: > 7426 :call map(mylist, '"> " .. v:val .. " <"') 7427 < This puts "> " before and " <" after each item in "mylist". 7428 7429 Note that {expr2} is the result of an expression and is then 7430 used as an expression again. Often it is good to use a 7431 |literal-string| to avoid having to double backslashes. You 7432 still have to double single (') quotes, though. 7433 7434 If {expr2} is a |Funcref| it is called with two arguments: 7435 1. The key or the index of the current item. 7436 2. the value of the current item. 7437 With a legacy script lambda you don't get an error if it only 7438 accepts one argument, but with a Vim9 lambda you get "E1106: 7439 One argument too many", the number of arguments must match. 7440 7441 The function must return the new value of the item. Example 7442 that changes each value by "key-value": > 7443 func KeyValue(key, val) 7444 return a:key .. '-' .. a:val 7445 endfunc 7446 call map(myDict, function('KeyValue')) 7447 < It is shorter when using a |lambda|: > 7448 call map(myDict, {key, val -> key .. '-' .. val}) 7449 < If you do not use "val" you can leave it out: > 7450 call map(myDict, {key -> 'item: ' .. key}) 7451 < If you do not use "key" you can use a short name: > 7452 call map(myDict, {_, val -> 'item: ' .. val}) 7453 < 7454 The operation is done in-place for a |List| and |Dictionary|. 7455 If you want it to remain unmodified make a copy first: > 7456 :let tlist = map(copy(mylist), ' v:val .. "\t"') 7457 7458 < Returns {expr1}, the |List| or |Dictionary| that was filtered, 7459 or a new |Blob| or |String|. 7460 When an error is encountered while evaluating {expr2} no 7461 further items in {expr1} are processed. 7462 When {expr2} is a Funcref errors inside a function are 7463 ignored, unless it was defined with the "abort" flag. 7464 7465 Can also be used as a |method|: > 7466 mylist->map(expr2) 7467 < 7468 Return type: |String|, |Blob|, list<{type}> or dict<{type}> 7469 depending on {expr1} 7470 7471 7472 maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* 7473 When {dict} is omitted or zero: Return the rhs of mapping 7474 {name} in mode {mode}. The returned String has special 7475 characters translated like in the output of the ":map" command 7476 listing. When {dict} is TRUE a dictionary is returned, see 7477 below. To get a list of all mappings see |maplist()|. 7478 7479 When there is no mapping for {name}, an empty String is 7480 returned if {dict} is FALSE, otherwise returns an empty Dict. 7481 When the mapping for {name} is empty, then "<Nop>" is 7482 returned. 7483 7484 The {name} can have special key names, like in the ":map" 7485 command. 7486 7487 {mode} can be one of these strings: 7488 "n" Normal 7489 "v" Visual (including Select) 7490 "o" Operator-pending 7491 "i" Insert 7492 "c" Cmd-line 7493 "s" Select 7494 "x" Visual 7495 "l" langmap |language-mapping| 7496 "t" Terminal-Job 7497 "" Normal, Visual and Operator-pending 7498 When {mode} is omitted, the modes for "" are used. 7499 7500 When {abbr} is there and it is |TRUE| use abbreviations 7501 instead of mappings. 7502 7503 When {dict} is there and it is |TRUE| return a dictionary 7504 containing all the information of the mapping with the 7505 following items: *mapping-dict* 7506 "lhs" The {lhs} of the mapping as it would be typed 7507 "lhsraw" The {lhs} of the mapping as raw bytes 7508 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate 7509 form, only present when it differs from "lhsraw" 7510 "rhs" The {rhs} of the mapping as typed. 7511 "silent" 1 for a |:map-silent| mapping, else 0. 7512 "noremap" 1 if the {rhs} of the mapping is not remappable. 7513 "script" 1 if mapping was defined with <script>. 7514 "expr" 1 for an expression mapping (|:map-<expr>|). 7515 "buffer" 1 for a buffer local mapping (|:map-local|). 7516 "mode" Modes for which the mapping is defined. In 7517 addition to the modes mentioned above, these 7518 characters will be used: 7519 " " Normal, Visual and Operator-pending 7520 "!" Insert and Commandline mode 7521 (|mapmode-ic|) 7522 "sid" The script local ID, used for <sid> mappings 7523 (|<SID>|). Negative for special contexts. 7524 "scriptversion" The version of the script. 999999 for 7525 |Vim9| script. 7526 "lnum" The line number in "sid", zero if unknown. 7527 "nowait" Do not wait for other, longer mappings. 7528 (|:map-<nowait>|). 7529 "abbr" True if this is an abbreviation |abbreviations|. 7530 "mode_bits" Vim's internal binary representation of "mode". 7531 |mapset()| ignores this; only "mode" is used. 7532 See |maplist()| for usage examples. The values 7533 are from src/vim.h and may change in the future. 7534 7535 The dictionary can be used to restore a mapping with 7536 |mapset()|. 7537 7538 The mappings local to the current buffer are checked first, 7539 then the global mappings. 7540 This function can be used to map a key even when it's already 7541 mapped, and have it do the original mapping too. Sketch: > 7542 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n') 7543 7544 < Can also be used as a |method|: > 7545 GetKey()->maparg('n') 7546 < 7547 Return type: |String| or dict<any> depending on {dict} 7548 7549 7550 mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()* 7551 Check if there is a mapping that matches with {name} in mode 7552 {mode}. See |maparg()| for {mode} and special names in 7553 {name}. 7554 When {abbr} is there and it is |TRUE| use abbreviations 7555 instead of mappings. 7556 A match happens with a mapping that starts with {name} and 7557 with a mapping which is equal to the start of {name}. 7558 7559 matches mapping "a" "ab" "abc" ~ 7560 mapcheck("a") yes yes yes 7561 mapcheck("abc") yes yes yes 7562 mapcheck("ax") yes no no 7563 mapcheck("b") no no no 7564 7565 The difference with |maparg()| is that mapcheck() finds a 7566 mapping that matches with {name}, while |maparg()| only finds a 7567 mapping for {name} exactly. 7568 When there is no mapping that starts with {name}, an empty 7569 String is returned. If there is one, the RHS of that mapping 7570 is returned. If there are several mappings that start with 7571 {name}, the RHS of one of them is returned. This will be 7572 "<Nop>" if the RHS is empty. 7573 The mappings local to the current buffer are checked first, 7574 then the global mappings. 7575 This function can be used to check if a mapping can be added 7576 without being ambiguous. Example: > 7577 :if mapcheck("_vv") == "" 7578 : map _vv :set guifont=7x13<CR> 7579 :endif 7580 < This avoids adding the "_vv" mapping when there already is a 7581 mapping for "_v" or for "_vvv". 7582 7583 Can also be used as a |method|: > 7584 GetKey()->mapcheck('n') 7585 < 7586 Return type: |String| 7587 7588 7589 maplist([{abbr}]) *maplist()* 7590 Returns a |List| of all mappings. Each List item is a |Dict|, 7591 the same as what is returned by |maparg()|, see 7592 |mapping-dict|. When {abbr} is there and it is |TRUE| use 7593 abbreviations instead of mappings. 7594 7595 Example to show all mappings with 'MultiMatch' in rhs: > 7596 vim9script 7597 echo maplist()->filter( 7598 (_, m) => match(m.rhs, 'MultiMatch') >= 0) 7599 < It can be tricky to find mappings for particular |:map-modes|. 7600 |mapping-dict|'s "mode_bits" can simplify this. For example, 7601 the mode_bits for Normal, Insert or Command-line modes are 7602 0x19. To find all the mappings available in those modes you 7603 can do: > 7604 vim9script 7605 var saved_maps = [] 7606 for m in maplist() 7607 if and(m.mode_bits, 0x19) != 0 7608 saved_maps->add(m) 7609 endif 7610 endfor 7611 echo saved_maps->mapnew((_, m) => m.lhs) 7612 < The values of the mode_bits are defined in Vim's src/vim.h 7613 file and they can be discovered at runtime using 7614 |:map-commands| and "maplist()". Example: > 7615 vim9script 7616 omap xyzzy <Nop> 7617 var op_bit = maplist()->filter( 7618 (_, m) => m.lhs == 'xyzzy')[0].mode_bits 7619 ounmap xyzzy 7620 echo printf("Operator-pending mode bit: 0x%x", op_bit) 7621 < 7622 Return type: list<dict<any>> 7623 7624 7625 mapnew({expr1}, {expr2}) *mapnew()* 7626 Like |map()| but instead of replacing items in {expr1} a new 7627 List or Dictionary is created and returned. {expr1} remains 7628 unchanged. Items can still be changed by {expr2}, if you 7629 don't want that use |deepcopy()| first. 7630 7631 Return type: |String|, |Blob|, list<{type}> or dict<{type}> 7632 depending on {expr1} 7633 7634 7635 mapset({mode}, {abbr}, {dict}) *mapset()* 7636 mapset({dict}) 7637 Restore a mapping from a dictionary, possibly returned by 7638 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer 7639 is true, is set on the current buffer; it is up to the caller 7640 to ensure that the intended buffer is the current buffer. 7641 This feature allows copying mappings from one buffer to 7642 another. 7643 The dict.mode value may restore a single mapping that covers 7644 more than one mode, like with mode values of '!', ' ', 'nox', 7645 or 'v'. *E1276* 7646 7647 In the first form, {mode} and {abbr} should be the same as 7648 for the call to |maparg()|. *E460* 7649 {mode} is used to define the mode in which the mapping is set, 7650 not the "mode" entry in {dict}. 7651 Example for saving and restoring a mapping: > 7652 let save_map = maparg('K', 'n', 0, 1) 7653 nnoremap K somethingelse 7654 ... 7655 call mapset('n', 0, save_map) 7656 < Note that if you are going to replace a map in several modes, 7657 e.g. with `:map!`, you need to save/restore the mapping for 7658 all of them, when they might differ. 7659 7660 In the second form, with {dict} as the only argument, mode 7661 and abbr are taken from the dict. 7662 Example: > 7663 vim9script 7664 var save_maps = maplist()->filter( 7665 (_, m) => m.lhs == 'K') 7666 nnoremap K somethingelse 7667 cnoremap K somethingelse2 7668 # ... 7669 unmap K 7670 for d in save_maps 7671 mapset(d) 7672 endfor 7673 < 7674 Return type: void 7675 7676 7677 match({expr}, {pat} [, {start} [, {count}]]) *match()* 7678 When {expr} is a |List| then this returns the index of the 7679 first item where {pat} matches. Each item is used as a 7680 String, |Lists| and |Dictionaries| are used as echoed. 7681 7682 Otherwise, {expr} is used as a String. The result is a 7683 Number, which gives the index (byte offset) in {expr} where 7684 {pat} matches. 7685 7686 A match at the first character or |List| item returns zero. 7687 If there is no match -1 is returned. 7688 7689 For getting submatches see |matchlist()|. 7690 Example: > 7691 :echo match("testing", "ing") " results in 4 7692 :echo match([1, 'x'], '\a') " results in 1 7693 < See |string-match| for how {pat} is used. 7694 *strpbrk()* 7695 Vim doesn't have a strpbrk() function. But you can do: > 7696 :let sepidx = match(line, '[.,;: \t]') 7697 < *strcasestr()* 7698 Vim doesn't have a strcasestr() function. But you can add 7699 "\c" to the pattern to ignore case: > 7700 :let idx = match(haystack, '\cneedle') 7701 < 7702 If {start} is given, the search starts from byte index 7703 {start} in a String or item {start} in a |List|. 7704 The result, however, is still the index counted from the 7705 first character/item. Example: > 7706 :echo match("testing", "ing", 2) 7707 < result is again "4". > 7708 :echo match("testing", "ing", 4) 7709 < result is again "4". > 7710 :echo match("testing", "t", 2) 7711 < result is "3". 7712 For a String, if {start} > 0 then it is like the string starts 7713 {start} bytes later, thus "^" will match at {start}. Except 7714 when {count} is given, then it's like matches before the 7715 {start} byte are ignored (this is a bit complicated to keep it 7716 backwards compatible). 7717 For a String, if {start} < 0, it will be set to 0. For a list 7718 the index is counted from the end. 7719 If {start} is out of range ({start} > strlen({expr}) for a 7720 String or {start} > len({expr}) for a |List|) -1 is returned. 7721 7722 When {count} is given use the {count}'th match. When a match 7723 is found in a String the search for the next one starts one 7724 character further. Thus this example results in 1: > 7725 echo match("testing", "..", 0, 2) 7726 < In a |List| the search continues in the next item. 7727 Note that when {count} is added the way {start} works changes, 7728 see above. 7729 7730 *match-pattern* 7731 See |pattern| for the patterns that are accepted. 7732 The 'ignorecase' option is used to set the ignore-caseness of 7733 the pattern. 'smartcase' is NOT used. The matching is always 7734 done like 'magic' is set and 'cpoptions' is empty. 7735 Note that a match at the start is preferred, thus when the 7736 pattern is using "*" (any number of matches) it tends to find 7737 zero matches at the start instead of a number of matches 7738 further down in the text. 7739 7740 Can also be used as a |method|: > 7741 GetText()->match('word') 7742 GetList()->match('word') 7743 < 7744 Return type: |Number| 7745 7746 7747 *matchadd()* *E290* *E798* *E799* *E801* *E957* 7748 matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) 7749 Defines a pattern to be highlighted in the current window (a 7750 "match"). It will be highlighted with {group}. Returns an 7751 identification number (ID), which can be used to delete the 7752 match using |matchdelete()|. The ID is bound to the window. 7753 Matching is case sensitive and magic, unless case sensitivity 7754 or magicness are explicitly overridden in {pattern}. The 7755 'magic', 'smartcase' and 'ignorecase' options are not used. 7756 The "Conceal" value is special, it causes the match to be 7757 concealed. 7758 7759 The optional {priority} argument assigns a priority to the 7760 match. A match with a high priority will have its 7761 highlighting overrule that of a match with a lower priority. 7762 A priority is specified as an integer (negative numbers are no 7763 exception). If the {priority} argument is not specified, the 7764 default priority is 10. The priority of 'hlsearch' is zero, 7765 hence all matches with a priority greater than zero will 7766 overrule it. Syntax highlighting (see 'syntax') is a separate 7767 mechanism, and regardless of the chosen priority a match will 7768 always overrule syntax highlighting. 7769 7770 The optional {id} argument allows the request for a specific 7771 match ID. If a specified ID is already taken, an error 7772 message will appear and the match will not be added. An ID 7773 is specified as a positive integer (zero excluded). IDs 1, 2 7774 and 3 are reserved for |:match|, |:2match| and |:3match|, 7775 respectively. 3 is reserved for use by the |matchparen| 7776 plugin. 7777 If the {id} argument is not specified or -1, |matchadd()| 7778 automatically chooses a free ID, which is at least 1000. 7779 7780 The optional {dict} argument allows for further custom 7781 values. Currently this is used to specify a match specific 7782 conceal character that will be shown for |hl-Conceal| 7783 highlighted matches. The dict can have the following members: 7784 7785 conceal Special character to show instead of the 7786 match (only for |hl-Conceal| highlighted 7787 matches, see |:syn-cchar|) 7788 window Instead of the current window use the 7789 window with this number or window ID. 7790 7791 The number of matches is not limited, as it is the case with 7792 the |:match| commands. 7793 7794 Returns -1 on error. 7795 7796 Example: > 7797 :highlight MyGroup ctermbg=green guibg=green 7798 :let m = matchadd("MyGroup", "TODO") 7799 < Deletion of the pattern: > 7800 :call matchdelete(m) 7801 7802 < A list of matches defined by |matchadd()| and |:match| are 7803 available from |getmatches()|. All matches can be deleted in 7804 one operation by |clearmatches()|. 7805 7806 Can also be used as a |method|: > 7807 GetGroup()->matchadd('TODO') 7808 < 7809 Return type: |Number| 7810 7811 7812 *matchaddpos()* 7813 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) 7814 Same as |matchadd()|, but requires a list of positions {pos} 7815 instead of a pattern. This command is faster than |matchadd()| 7816 because it does not handle regular expressions and it sets 7817 buffer line boundaries to redraw screen. It is supposed to be 7818 used when fast match additions and deletions are required, for 7819 example to highlight matching parentheses. 7820 7821 {pos} is a list of positions. Each position can be one of 7822 these: 7823 - A number. This whole line will be highlighted. The first 7824 line has number 1. 7825 - A list with one number, e.g., [23]. The whole line with 7826 this number will be highlighted. 7827 - A list with two numbers, e.g., [23, 11]. The first number 7828 is the line number, the second one is the column number 7829 (first column is 1, the value must correspond to the byte 7830 index as |col()| would return). The character at this 7831 position will be highlighted. 7832 - A list with three numbers, e.g., [23, 11, 3]. As above, but 7833 the third number gives the length of the highlight in bytes. 7834 7835 Returns -1 on error. 7836 7837 Example: > 7838 :highlight MyGroup ctermbg=green guibg=green 7839 :let m = matchaddpos("MyGroup", [[23, 24], 34]) 7840 < Deletion of the pattern: > 7841 :call matchdelete(m) 7842 7843 < Matches added by |matchaddpos()| are returned by 7844 |getmatches()|. 7845 7846 Can also be used as a |method|: > 7847 GetGroup()->matchaddpos([23, 11]) 7848 < 7849 Return type: |Number| 7850 7851 7852 matcharg({nr}) *matcharg()* 7853 Selects the {nr} match item, as set with a |:match|, 7854 |:2match| or |:3match| command. 7855 Return a |List| with two elements: 7856 The name of the highlight group used 7857 The pattern used. 7858 When {nr} is not 1, 2 or 3 returns an empty |List|. 7859 When there is no match item set returns ['', '']. 7860 This is useful to save and restore a |:match|. 7861 Highlighting matches using the |:match| commands are limited 7862 to three matches. |matchadd()| does not have this limitation. 7863 7864 Can also be used as a |method|: > 7865 GetMatch()->matcharg() 7866 < 7867 Return type: list<string> 7868 7869 7870 matchbufline({buf}, {pat}, {lnum}, {end} [, {dict}]) *matchbufline()* 7871 Returns the |List| of matches in lines from {lnum} to {end} in 7872 buffer {buf} where {pat} matches. 7873 7874 {lnum} and {end} can either be a line number or the string "$" 7875 to refer to the last line in {buf}. 7876 7877 The {dict} argument supports following items: 7878 submatches include submatch information (|/\(|) 7879 7880 For each match, a |Dict| with the following items is returned: 7881 byteidx starting byte index of the match 7882 lnum line number where there is a match 7883 text matched string 7884 Note that there can be multiple matches in a single line. 7885 7886 This function works only for loaded buffers. First call 7887 |bufload()| if needed. 7888 7889 See |match-pattern| for information about the effect of some 7890 option settings on the pattern. 7891 7892 When {buf} is not a valid buffer, the buffer is not loaded or 7893 {lnum} or {end} is not valid then an error is given and an 7894 empty |List| is returned. 7895 7896 Examples: > 7897 " Assuming line 3 in buffer 5 contains "a" 7898 :echo matchbufline(5, '\<\k\+\>', 3, 3) 7899 [{'lnum': 3, 'byteidx': 0, 'text': 'a'}] 7900 " Assuming line 4 in buffer 10 contains "tik tok" 7901 :echo matchbufline(10, '\<\k\+\>', 1, 4) 7902 [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, 7903 {'lnum': 4, 'byteidx': 4, 'text': 'tok'}] 7904 < 7905 If {submatch} is present and is v:true, then submatches like 7906 "\1", "\2", etc. are also returned. Example: > 7907 " Assuming line 2 in buffer 2 contains "acd" 7908 :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2 7909 \ {'submatches': v:true}) 7910 [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': 7911 ['a', '', 'c', 'd', '', '', '', '', '']}] 7912 < The "submatches" List always contains 9 items. If a submatch 7913 is not found, then an empty string is returned for that 7914 submatch. 7915 7916 Can also be used as a |method|: > 7917 GetBuffer()->matchbufline('mypat', 1, '$') 7918 < 7919 Return type: list<dict<any>> or list<any> 7920 7921 7922 matchdelete({id} [, {win}]) *matchdelete()* *E802* *E803* 7923 Deletes a match with ID {id} previously defined by |matchadd()| 7924 or one of the |:match| commands. Returns 0 if successful, 7925 otherwise -1. See example for |matchadd()|. All matches can 7926 be deleted in one operation by |clearmatches()|. 7927 If {win} is specified, use the window with this number or 7928 window ID instead of the current window. 7929 7930 Can also be used as a |method|: > 7931 GetMatch()->matchdelete() 7932 < 7933 Return type: |Number| 7934 7935 7936 matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()* 7937 Same as |match()|, but return the index of first character 7938 after the match. Example: > 7939 :echo matchend("testing", "ing") 7940 < results in "7". 7941 *strspn()* *strcspn()* 7942 Vim doesn't have a strspn() or strcspn() function, but you can 7943 do it with matchend(): > 7944 :let span = matchend(line, '[a-zA-Z]') 7945 :let span = matchend(line, '[^a-zA-Z]') 7946 < Except that -1 is returned when there are no matches. 7947 7948 The {start}, if given, has the same meaning as for |match()|. > 7949 :echo matchend("testing", "ing", 2) 7950 < results in "7". > 7951 :echo matchend("testing", "ing", 5) 7952 < result is "-1". 7953 When {expr} is a |List| the result is equal to |match()|. 7954 7955 Can also be used as a |method|: > 7956 GetText()->matchend('word') 7957 < 7958 Return type: |Number| 7959 7960 7961 matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()* 7962 If {list} is a list of strings, then returns a |List| with all 7963 the strings in {list} that fuzzy match {str}. The strings in 7964 the returned list are sorted based on the matching score. 7965 7966 The optional {dict} argument always supports the following 7967 items: 7968 matchseq When this item is present return only matches 7969 that contain the characters in {str} in the 7970 given sequence. 7971 limit Maximum number of matches in {list} to be 7972 returned. Zero means no limit. 7973 7974 If {list} is a list of dictionaries, then the optional {dict} 7975 argument supports the following additional items: 7976 key Key of the item which is fuzzy matched against 7977 {str}. The value of this item should be a 7978 string. 7979 text_cb |Funcref| that will be called for every item 7980 in {list} to get the text for fuzzy matching. 7981 This should accept a dictionary item as the 7982 argument and return the text for that item to 7983 use for fuzzy matching. 7984 7985 {str} is treated as a literal string and regular expression 7986 matching is NOT supported. Only the first 1024 characters of 7987 {str} and of each item in {list} are used for matching; 7988 characters beyond that are ignored. 7989 7990 When {str} has multiple words each separated by white space, 7991 then the list of strings that have all the words is returned. 7992 7993 If there are no matching strings or there is an error, then an 7994 empty list is returned. 7995 7996 When {limit} is given, matchfuzzy() will find up to this 7997 number of matches in {list} and return them in sorted order. 7998 7999 Refer to |fuzzy-matching| for more information about fuzzy 8000 matching strings. 8001 8002 Example: > 8003 :echo matchfuzzy(["clay", "crow"], "cay") 8004 < results in ["clay"]. > 8005 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl") 8006 < results in a list of buffer names fuzzy matching "ndl". > 8007 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'}) 8008 < results in a list of buffer information dicts with buffer 8009 names fuzzy matching "ndl". > 8010 :echo getbufinfo()->matchfuzzy("spl", 8011 \ {'text_cb' : {v -> v.name}}) 8012 < results in a list of buffer information dicts with buffer 8013 names fuzzy matching "spl". > 8014 :echo v:oldfiles->matchfuzzy("test") 8015 < results in a list of file names fuzzy matching "test". > 8016 :let l = readfile("buffer.c")->matchfuzzy("str") 8017 < results in a list of lines in "buffer.c" fuzzy matching "str". > 8018 :echo ['one two', 'two one']->matchfuzzy('two one') 8019 < results in ['two one', 'one two']. > 8020 :echo ['one two', 'two one']->matchfuzzy('two one', 8021 \ {'matchseq': 1}) 8022 < results in ['two one']. 8023 8024 Return type: list<string> or list<any> 8025 8026 8027 matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()* 8028 Same as |matchfuzzy()|, but returns the list of matched 8029 strings, the list of character positions where characters 8030 in {str} matches and a list of matching scores. You can 8031 use |byteidx()| to convert a character position to a byte 8032 position. 8033 8034 If {str} matches multiple times in a string, then only the 8035 positions for the best match is returned. 8036 8037 If there are no matching strings or there is an error, then a 8038 list with three empty list items is returned. 8039 8040 Example: > 8041 :echo matchfuzzypos(['testing'], 'tsg') 8042 < results in [['testing'], [[0, 2, 6]], [99]] > 8043 :echo matchfuzzypos(['clay', 'lacy'], 'la') 8044 < results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] > 8045 :echo [{'text': 'hello', 'id' : 10}] 8046 \ ->matchfuzzypos('ll', {'key' : 'text'}) 8047 < results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]] 8048 8049 Return type: list<list<any>> 8050 8051 8052 matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* 8053 Same as |match()|, but return a |List|. The first item in the 8054 list is the matched string, same as what |matchstr()| would 8055 return. Following items are submatches, like "\1", "\2", etc. 8056 in |:substitute|. When an optional submatch didn't match an 8057 empty string is used. Example: > 8058 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)') 8059 < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', ''] 8060 When there is no match an empty list is returned. 8061 8062 You can pass in a List, but that is not very useful. 8063 8064 Can also be used as a |method|: > 8065 GetText()->matchlist('word') 8066 < 8067 Return type: list<string> or list<any> 8068 8069 8070 matchstrlist({list}, {pat} [, {dict}]) *matchstrlist()* 8071 Returns the |List| of matches in {list} where {pat} matches. 8072 {list} is a |List| of strings. {pat} is matched against each 8073 string in {list}. 8074 8075 The {dict} argument supports following items: 8076 submatches include submatch information (|/\(|) 8077 8078 For each match, a |Dict| with the following items is returned: 8079 byteidx starting byte index of the match. 8080 idx index in {list} of the match. 8081 text matched string 8082 submatches a List of submatches. Present only if 8083 "submatches" is set to v:true in {dict}. 8084 8085 See |match-pattern| for information about the effect of some 8086 option settings on the pattern. 8087 8088 Example: > 8089 :echo matchstrlist(['tik tok'], '\<\k\+\>') 8090 [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, 8091 {'idx': 0, 'byteidx': 4, 'text': 'tok'}] 8092 :echo matchstrlist(['a', 'b'], '\<\k\+\>') 8093 [{'idx': 0, 'byteidx': 0, 'text': 'a'}, 8094 {'idx': 1, 'byteidx': 0, 'text': 'b'}] 8095 < 8096 If "submatches" is present and is v:true, then submatches like 8097 "\1", "\2", etc. are also returned. Example: > 8098 :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 8099 \ #{submatches: v:true}) 8100 [{'idx': 0, 'byteidx': 0, 'text': 'acd', 8101 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] 8102 < The "submatches" List always contains 9 items. If a submatch 8103 is not found, then an empty string is returned for that 8104 submatch. 8105 8106 Can also be used as a |method|: > 8107 GetListOfStrings()->matchstrlist('mypat') 8108 < 8109 Return type: list<dict<any>> or list<any> 8110 8111 8112 matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* 8113 Same as |match()|, but return the matched string. Example: > 8114 :echo matchstr("testing", "ing") 8115 < results in "ing". 8116 When there is no match "" is returned. 8117 The {start}, if given, has the same meaning as for |match()|. > 8118 :echo matchstr("testing", "ing", 2) 8119 < results in "ing". > 8120 :echo matchstr("testing", "ing", 5) 8121 < result is "". 8122 When {expr} is a |List| then the matching item is returned. 8123 The type isn't changed, it's not necessarily a String. 8124 8125 Can also be used as a |method|: > 8126 GetText()->matchstr('word') 8127 < 8128 Return type: |String| 8129 8130 8131 matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* 8132 Same as |matchstr()|, but return the matched string, the start 8133 position and the end position of the match. Example: > 8134 :echo matchstrpos("testing", "ing") 8135 < results in ["ing", 4, 7]. 8136 When there is no match ["", -1, -1] is returned. 8137 The {start}, if given, has the same meaning as for |match()|. > 8138 :echo matchstrpos("testing", "ing", 2) 8139 < results in ["ing", 4, 7]. > 8140 :echo matchstrpos("testing", "ing", 5) 8141 < result is ["", -1, -1]. 8142 When {expr} is a |List| then the matching item, the index 8143 of first item where {pat} matches, the start position and the 8144 end position of the match are returned. > 8145 :echo matchstrpos([1, '__x'], '\a') 8146 < result is ["x", 1, 2, 3]. 8147 The type isn't changed, it's not necessarily a String. 8148 8149 Can also be used as a |method|: > 8150 GetText()->matchstrpos('word') 8151 < 8152 Return type: list<any> 8153 8154 8155 max({expr}) *max()* 8156 Return the maximum value of all items in {expr}. Example: > 8157 echo max([apples, pears, oranges]) 8158 8159 < {expr} can be a |List|, a |Tuple| or a |Dictionary|. For a 8160 Dictionary, it returns the maximum of all values in the 8161 Dictionary. If {expr} is neither a List nor a Tuple nor a 8162 Dictionary, or one of the items in {expr} cannot be used as a 8163 Number this results in an error. An empty |List|, |Tuple| 8164 or |Dictionary| results in zero. 8165 8166 Can also be used as a |method|: > 8167 mylist->max() 8168 < 8169 Return type: any, depending on {expr} 8170 8171 8172 menu_info({name} [, {mode}]) *menu_info()* 8173 Return information about the specified menu {name} in 8174 mode {mode}. The menu name should be specified without the 8175 shortcut character ('&'). If {name} is "", then the top-level 8176 menu names are returned. 8177 8178 {mode} can be one of these strings: 8179 "n" Normal 8180 "v" Visual (including Select) 8181 "o" Operator-pending 8182 "i" Insert 8183 "c" Cmd-line 8184 "s" Select 8185 "x" Visual 8186 "t" Terminal-Job 8187 "" Normal, Visual and Operator-pending 8188 "!" Insert and Cmd-line 8189 When {mode} is omitted, the modes for "" are used. 8190 8191 Returns a |Dictionary| containing the following items: 8192 accel menu item accelerator text |menu-text| 8193 display display name (name without '&') 8194 enabled v:true if this menu item is enabled 8195 Refer to |:menu-enable| 8196 icon name of the icon file (for toolbar) 8197 |toolbar-icon| 8198 iconidx index of a built-in icon 8199 modes modes for which the menu is defined. In 8200 addition to the modes mentioned above, these 8201 characters will be used: 8202 " " Normal, Visual and Operator-pending 8203 name menu item name. 8204 noremenu v:true if the {rhs} of the menu item is not 8205 remappable else v:false. 8206 priority menu order priority |menu-priority| 8207 rhs right-hand-side of the menu item. The 8208 returned string has special characters 8209 translated like in the output of the ":menu" 8210 command listing. When the {rhs} of a menu 8211 item is empty, then "<Nop>" is returned. 8212 script v:true if script-local remapping of {rhs} is 8213 allowed else v:false. See |:menu-script|. 8214 shortcut shortcut key (character after '&' in 8215 the menu name) |menu-shortcut| 8216 silent v:true if the menu item is created 8217 with <silent> argument |:menu-silent| 8218 submenus |List| containing the names of 8219 all the submenus. Present only if the menu 8220 item has submenus. 8221 8222 Returns an empty dictionary if the menu item is not found. 8223 8224 Examples: > 8225 :echo menu_info('Edit.Cut') 8226 :echo menu_info('File.Save', 'n') 8227 8228 " Display the entire menu hierarchy in a buffer 8229 func ShowMenu(name, pfx) 8230 let m = menu_info(a:name) 8231 call append(line('$'), a:pfx .. m.display) 8232 for child in m->get('submenus', []) 8233 call ShowMenu(a:name .. '.' .. escape(child, '.'), 8234 \ a:pfx .. ' ') 8235 endfor 8236 endfunc 8237 new 8238 for topmenu in menu_info('').submenus 8239 call ShowMenu(topmenu, '') 8240 endfor 8241 < 8242 Can also be used as a |method|: > 8243 GetMenuName()->menu_info('v') 8244 < 8245 Return type: dict<any> 8246 8247 8248 min({expr}) *min()* 8249 Return the minimum value of all items in {expr}. Example: > 8250 echo min([apples, pears, oranges]) 8251 8252 < {expr} can be a |List|, a |Tuple| or a |Dictionary|. For a 8253 Dictionary, it returns the minimum of all values in the 8254 Dictionary. If {expr} is neither a List nor a Tuple nor a 8255 Dictionary, or one of the items in {expr} cannot be used as a 8256 Number this results in an error. An empty |List|, |Tuple| or 8257 |Dictionary| results in zero. 8258 8259 Can also be used as a |method|: > 8260 mylist->min() 8261 < 8262 Return type: any, depending on {expr} 8263 8264 8265 mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E739* 8266 Create directory {name}. 8267 8268 When {flags} is present it must be a string. An empty string 8269 has no effect. 8270 8271 {flags} can contain these character flags: 8272 "p" intermediate directories will be created as necessary 8273 "D" {name} will be deleted at the end of the current 8274 function, but not recursively |:defer| 8275 "R" {name} will be deleted recursively at the end of the 8276 current function |:defer| 8277 8278 Note that when {name} has more than one part and "p" is used 8279 some directories may already exist. Only the first one that 8280 is created and what it contains is scheduled to be deleted. 8281 E.g. when using: > 8282 call mkdir('subdir/tmp/autoload', 'pR') 8283 < and "subdir" already exists then "subdir/tmp" will be 8284 scheduled for deletion, like with: > 8285 defer delete('subdir/tmp', 'rf') 8286 < Note that if scheduling the defer fails the directory is not 8287 deleted. This should only happen when out of memory. 8288 8289 If {prot} is given it is used to set the protection bits of 8290 the new directory. The default is 0o755 (rwxr-xr-x: r/w for 8291 the user, readable for others). Use 0o700 to make it 8292 unreadable for others. This is used for the newly created 8293 directories. Note: umask is applied to {prot} (on Unix). 8294 Example: > 8295 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700) 8296 8297 < This function is not available in the |sandbox|. 8298 8299 There is no error if the directory already exists and the "p" 8300 flag is passed (since patch 8.0.1708). However, without the 8301 "p" option the call will fail. 8302 8303 The function result is a Number, which is TRUE if the call was 8304 successful or FALSE if the directory creation failed or partly 8305 failed. 8306 8307 Not available on all systems. To check use: > 8308 :if exists("*mkdir") 8309 8310 < Can also be used as a |method|: > 8311 GetName()->mkdir() 8312 < 8313 Return type: |Number| 8314 8315 8316 mode([{expr}]) *mode()* 8317 Return a string that indicates the current mode. 8318 If {expr} is supplied and it evaluates to a non-zero Number or 8319 a non-empty String (|non-zero-arg|), then the full mode is 8320 returned, otherwise only the first letter is returned. 8321 Also see |state()|. 8322 8323 n Normal 8324 no Operator-pending 8325 nov Operator-pending (forced characterwise |o_v|) 8326 noV Operator-pending (forced linewise |o_V|) 8327 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|); 8328 CTRL-V is one character 8329 niI Normal using |i_CTRL-O| in |Insert-mode| 8330 niR Normal using |i_CTRL-O| in |Replace-mode| 8331 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode| 8332 nt Terminal-Normal (insert goes to Terminal-Job mode) 8333 v Visual by character 8334 vs Visual by character using |v_CTRL-O| in Select mode 8335 V Visual by line 8336 Vs Visual by line using |v_CTRL-O| in Select mode 8337 CTRL-V Visual blockwise 8338 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode 8339 s Select by character 8340 S Select by line 8341 CTRL-S Select blockwise 8342 i Insert 8343 ic Insert mode completion |compl-generic| 8344 ix Insert mode |i_CTRL-X| completion 8345 R Replace |R| 8346 Rc Replace mode completion |compl-generic| 8347 Rx Replace mode |i_CTRL-X| completion 8348 Rv Virtual Replace |gR| 8349 Rvc Virtual Replace mode completion |compl-generic| 8350 Rvx Virtual Replace mode |i_CTRL-X| completion 8351 c Command-line editing 8352 ct Command-line editing via Terminal-Job mode 8353 cr Command-line editing overstrike mode |c_<Insert>| 8354 cv Vim Ex mode |gQ| 8355 cvr Vim Ex mode while in overstrike mode |c_<Insert>| 8356 ce Normal Ex mode |Q| 8357 r Hit-enter prompt 8358 rm The -- more -- prompt 8359 r? A |:confirm| query of some sort 8360 ! Shell or external command is executing 8361 t Terminal-Job mode: keys go to the job 8362 8363 This is useful in the 'statusline' option or when used 8364 with |remote_expr()| In most other places it always returns 8365 "c" or "n". 8366 Note that in the future more modes and more specific modes may 8367 be added. It's better not to compare the whole string but 8368 only the leading character(s). 8369 Also see |visualmode()|. 8370 8371 Can also be used as a |method|: > 8372 DoFull()->mode() 8373 < 8374 Return type: |String| 8375 8376 8377 mzeval({expr}) *mzeval()* 8378 Evaluate MzScheme expression {expr} and return its result 8379 converted to Vim data structures. 8380 Numbers and strings are returned as they are. 8381 Pairs (including lists and improper lists) and vectors are 8382 returned as Vim |Lists|. 8383 Hash tables are represented as Vim |Dictionary| type with keys 8384 converted to strings. 8385 All other types are converted to string with display function. 8386 Examples: > 8387 :mz (define l (list 1 2 3)) 8388 :mz (define h (make-hash)) (hash-set! h "list" l) 8389 :echo mzeval("l") 8390 :echo mzeval("h") 8391 < 8392 Note that in a `:def` function local variables are not visible 8393 to {expr}. 8394 8395 Can also be used as a |method|: > 8396 GetExpr()->mzeval() 8397 < 8398 Return type: any, depending on {expr} 8399 8400 {only available when compiled with the |+mzscheme| feature} 8401 8402 8403 nextnonblank({lnum}) *nextnonblank()* 8404 Return the line number of the first line at or below {lnum} 8405 that is not blank. Example: > 8406 if getline(nextnonblank(1)) =~ "Java" 8407 < When {lnum} is invalid or there is no non-blank line at or 8408 below it, zero is returned. 8409 {lnum} is used like with |getline()|. 8410 See also |prevnonblank()|. 8411 8412 Can also be used as a |method|: > 8413 GetLnum()->nextnonblank() 8414 < 8415 Return type: |Number| 8416 8417 8418 ngettext({single}, {plural}, {number} [, {domain}]) *ngettext()* 8419 Return a string that contains the correct value for a 8420 message based on the rules for plural form(s) in 8421 a language. Examples: > 8422 ngettext("File", "Files", 2) # returns "Files" 8423 < 8424 Can be used as a |method|: > 8425 1->ngettext("File", "Files") # returns "File" 8426 < 8427 See |gettext()| for information on the domain parameter. 8428 8429 Return type: |String| 8430 8431 8432 nr2char({expr} [, {utf8}]) *nr2char()* 8433 Return a string with a single character, which has the number 8434 value {expr}. Examples: > 8435 nr2char(64) returns "@" 8436 nr2char(32) returns " " 8437 < When {utf8} is omitted or zero, the current 'encoding' is 8438 used. Example for "utf-8": > 8439 nr2char(300) returns I with bow character 8440 < When {utf8} is TRUE, always return UTF-8 characters. 8441 Note that a NUL character in the file is specified with 8442 nr2char(10), because NULs are represented with newline 8443 characters. nr2char(0) is a real NUL and terminates the 8444 string, thus results in an empty string. 8445 To turn a list of character numbers into a string: > 8446 let list = [65, 66, 67] 8447 let str = join(map(list, {_, val -> nr2char(val)}), '') 8448 < Result: "ABC" 8449 8450 Can also be used as a |method|: > 8451 GetNumber()->nr2char() 8452 < 8453 Return type: |String| 8454 8455 8456 or({expr}, {expr}) *or()* 8457 Bitwise OR on the two arguments. The arguments are converted 8458 to a number. A List, Dict or Float argument causes an error. 8459 Also see `and()` and `xor()`. 8460 Example: > 8461 :let bits = or(bits, 0x80) 8462 < Can also be used as a |method|: > 8463 :let bits = bits->or(0x80) 8464 8465 < Rationale: The reason this is a function and not using the "|" 8466 character like many languages, is that Vi has always used "|" 8467 to separate commands. In many places it would not be clear if 8468 "|" is an operator or a command separator. 8469 8470 Return type: |Number| 8471 8472 8473 pathshorten({path} [, {len}]) *pathshorten()* 8474 Shorten directory names in the path {path} and return the 8475 result. The tail, the file name, is kept as-is. The other 8476 components in the path are reduced to {len} letters in length. 8477 If {len} is omitted or smaller than 1 then 1 is used (single 8478 letters). Leading '~' and '.' characters are kept. Examples: > 8479 :echo pathshorten('~/.vim/autoload/myfile.vim') 8480 < ~/.v/a/myfile.vim ~ 8481 > 8482 :echo pathshorten('~/.vim/autoload/myfile.vim', 2) 8483 < ~/.vi/au/myfile.vim ~ 8484 It doesn't matter if the path exists or not. 8485 Returns an empty string on error. 8486 8487 Can also be used as a |method|: > 8488 GetDirectories()->pathshorten() 8489 < 8490 Return type: |String| 8491 8492 8493 perleval({expr}) *perleval()* 8494 Evaluate Perl expression {expr} in scalar context and return 8495 its result converted to Vim data structures. If value can't 8496 be converted, it is returned as a string Perl representation. 8497 Note: If you want an array or hash, {expr} must return a 8498 reference to it. 8499 Example: > 8500 :echo perleval('[1 .. 4]') 8501 < [1, 2, 3, 4] 8502 8503 Note that in a `:def` function local variables are not visible 8504 to {expr}. 8505 8506 Can also be used as a |method|: > 8507 GetExpr()->perleval() 8508 < 8509 Return type: any, depending on {expr} 8510 8511 {only available when compiled with the |+perl| feature} 8512 8513 8514 popup_ functions are documented here: |popup-functions| 8515 8516 8517 pow({x}, {y}) *pow()* 8518 Return the power of {x} to the exponent {y} as a |Float|. 8519 {x} and {y} must evaluate to a |Float| or a |Number|. 8520 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|. 8521 Examples: > 8522 :echo pow(3, 3) 8523 < 27.0 > 8524 :echo pow(2, 16) 8525 < 65536.0 > 8526 :echo pow(32, 0.20) 8527 < 2.0 8528 8529 Can also be used as a |method|: > 8530 Compute()->pow(3) 8531 < 8532 Return type: |Float| 8533 8534 8535 preinserted() *preinserted()* 8536 Returns non-zero if text has been inserted after the cursor 8537 because "preinsert" is present in 'completeopt', or because 8538 "longest" is present in 'completeopt' while 'autocomplete' 8539 is active. Otherwise returns zero. 8540 8541 Return type: |Number| 8542 8543 8544 prevnonblank({lnum}) *prevnonblank()* 8545 Return the line number of the first line at or above {lnum} 8546 that is not blank. Example: > 8547 let ind = indent(prevnonblank(v:lnum - 1)) 8548 < When {lnum} is invalid or there is no non-blank line at or 8549 above it, zero is returned. 8550 {lnum} is used like with |getline()|. 8551 Also see |nextnonblank()|. 8552 8553 Can also be used as a |method|: > 8554 GetLnum()->prevnonblank() 8555 < 8556 Return type: |Number| 8557 8558 8559 printf({fmt} [, {expr1} ...]) *printf()* 8560 Return a String with {fmt}, where "%" items are replaced by 8561 the formatted form of their respective arguments. Example: > 8562 printf("%4d: E%d %.30s", lnum, errno, msg) 8563 < May result in: 8564 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~ 8565 8566 When used as a |method| the base is passed as the second 8567 argument: > 8568 Compute()->printf("result: %d") 8569 < 8570 You can use `call()` to pass the items as a list. 8571 8572 Often used items are: 8573 %s string 8574 %6S string right-aligned in 6 display cells 8575 %6s string right-aligned in 6 bytes 8576 %.9s string truncated to 9 bytes 8577 %c single byte 8578 %d decimal number 8579 %5d decimal number padded with spaces to 5 characters 8580 %x hex number 8581 %04x hex number padded with zeros to at least 4 characters 8582 %X hex number using upper case letters 8583 %o octal number 8584 %08b binary number padded with zeros to at least 8 chars 8585 %f floating point number as 12.23, inf, -inf or nan 8586 %F floating point number as 12.23, INF, -INF or NAN 8587 %e floating point number as 1.23e3, inf, -inf or nan 8588 %E floating point number as 1.23E3, INF, -INF or NAN 8589 %g floating point number, as %f or %e depending on value 8590 %G floating point number, as %F or %E depending on value 8591 %% the % character itself 8592 8593 Conversion specifications start with '%' and end with the 8594 conversion type. All other characters are copied unchanged to 8595 the result. 8596 8597 The "%" starts a conversion specification. The following 8598 arguments appear in sequence: 8599 8600 % [pos-argument] [flags] [field-width] [.precision] type 8601 8602 pos-argument 8603 At most one positional argument specifier. These take 8604 the form {n$}, where n is >= 1. 8605 8606 flags 8607 Zero or more of the following flags: 8608 8609 # The value should be converted to an "alternate 8610 form". For c, d, and s conversions, this option 8611 has no effect. For o conversions, the precision 8612 of the number is increased to force the first 8613 character of the output string to a zero (except 8614 if a zero value is printed with an explicit 8615 precision of zero). 8616 For b and B conversions, a non-zero result has 8617 the string "0b" (or "0B" for B conversions) 8618 prepended to it. 8619 For x and X conversions, a non-zero result has 8620 the string "0x" (or "0X" for X conversions) 8621 prepended to it. 8622 8623 0 (zero) Zero padding. For all conversions the converted 8624 value is padded on the left with zeros rather 8625 than blanks. If a precision is given with a 8626 numeric conversion (d, b, B, o, x, and X), the 0 8627 flag is ignored. 8628 8629 - A negative field width flag; the converted value 8630 is to be left adjusted on the field boundary. 8631 The converted value is padded on the right with 8632 blanks, rather than on the left with blanks or 8633 zeros. A - overrides a 0 if both are given. 8634 8635 ' ' (space) A blank should be left before a positive 8636 number produced by a signed conversion (d). 8637 8638 + A sign must always be placed before a number 8639 produced by a signed conversion. A + overrides 8640 a space if both are used. 8641 8642 field-width 8643 An optional decimal digit string specifying a minimum 8644 field width. If the converted value has fewer bytes 8645 than the field width, it will be padded with spaces on 8646 the left (or right, if the left-adjustment flag has 8647 been given) to fill out the field width. For the S 8648 conversion the count is in cells. 8649 8650 .precision 8651 An optional precision, in the form of a period '.' 8652 followed by an optional digit string. If the digit 8653 string is omitted, the precision is taken as zero. 8654 This gives the minimum number of digits to appear for 8655 d, o, x, and X conversions, the maximum number of 8656 bytes to be printed from a string for s conversions, 8657 or the maximum number of cells to be printed from a 8658 string for S conversions. 8659 For floating point it is the number of digits after 8660 the decimal point. 8661 8662 type 8663 A character that specifies the type of conversion to 8664 be applied, see below. 8665 8666 A field width or precision, or both, may be indicated by an 8667 asterisk '*' instead of a digit string. In this case, a 8668 Number argument supplies the field width or precision. A 8669 negative field width is treated as a left adjustment flag 8670 followed by a positive field width; a negative precision is 8671 treated as though it were missing. Example: > 8672 :echo printf("%d: %.*s", nr, width, line) 8673 < This limits the length of the text used from "line" to 8674 "width" bytes. 8675 8676 If the argument to be formatted is specified using a 8677 positional argument specifier, and a '*' is used to indicate 8678 that a number argument is to be used to specify the width or 8679 precision, the argument(s) to be used must also be specified 8680 using a {n$} positional argument specifier. See |printf-$|. 8681 8682 The conversion specifiers and their meanings are: 8683 8684 *printf-d* *printf-b* *printf-B* *printf-o* 8685 *printf-x* *printf-X* 8686 dbBoxX The Number argument is converted to signed decimal 8687 (d), unsigned binary (b and B), unsigned octal (o), or 8688 unsigned hexadecimal (x and X) notation. The letters 8689 "abcdef" are used for x conversions; the letters 8690 "ABCDEF" are used for X conversions. 8691 The precision, if any, gives the minimum number of 8692 digits that must appear; if the converted value 8693 requires fewer digits, it is padded on the left with 8694 zeros. 8695 In no case does a non-existent or small field width 8696 cause truncation of a numeric field; if the result of 8697 a conversion is wider than the field width, the field 8698 is expanded to contain the conversion result. 8699 The 'h' modifier indicates the argument is 16 bits. 8700 The 'l' modifier indicates the argument is a long 8701 integer. The size will be 32 bits or 64 bits 8702 depending on your platform. 8703 The "ll" modifier indicates the argument is 64 bits. 8704 The b and B conversion specifiers never take a width 8705 modifier and always assume their argument is a 64 bit 8706 integer. 8707 Generally, these modifiers are not useful. They are 8708 ignored when type is known from the argument. 8709 8710 i alias for d 8711 D alias for ld 8712 U alias for lu 8713 O alias for lo 8714 8715 *printf-c* 8716 c The Number argument is converted to a byte, and the 8717 resulting character is written. 8718 8719 *printf-s* 8720 s The text of the String argument is used. If a 8721 precision is specified, no more bytes than the number 8722 specified are used. 8723 If the argument is not a String type, it is 8724 automatically converted to text with the same format 8725 as ":echo". 8726 *printf-S* 8727 S The text of the String argument is used. If a 8728 precision is specified, no more display cells than the 8729 number specified are used. 8730 8731 *printf-f* *E807* 8732 f F The Float argument is converted into a string of the 8733 form 123.456. The precision specifies the number of 8734 digits after the decimal point. When the precision is 8735 zero the decimal point is omitted. When the precision 8736 is not specified 6 is used. A really big number 8737 (out of range or dividing by zero) results in "inf" 8738 or "-inf" with %f (INF or -INF with %F). 8739 "0.0 / 0.0" results in "nan" with %f (NAN with %F). 8740 Example: > 8741 echo printf("%.2f", 12.115) 8742 < 12.12 8743 Note that roundoff depends on the system libraries. 8744 Use |round()| when in doubt. 8745 8746 *printf-e* *printf-E* 8747 e E The Float argument is converted into a string of the 8748 form 1.234e+03 or 1.234E+03 when using 'E'. The 8749 precision specifies the number of digits after the 8750 decimal point, like with 'f'. 8751 8752 *printf-g* *printf-G* 8753 g G The Float argument is converted like with 'f' if the 8754 value is between 0.001 (inclusive) and 10000000.0 8755 (exclusive). Otherwise 'e' is used for 'g' and 'E' 8756 for 'G'. When no precision is specified superfluous 8757 zeroes and '+' signs are removed, except for the zero 8758 immediately after the decimal point. Thus 10000000.0 8759 results in 1.0e7. 8760 8761 *printf-%* 8762 % A '%' is written. No argument is converted. The 8763 complete conversion specification is "%%". 8764 8765 When a Number argument is expected a String argument is also 8766 accepted and automatically converted. 8767 When a Float or String argument is expected a Number argument 8768 is also accepted and automatically converted. 8769 Any other argument type results in an error message. 8770 8771 *E766* *E767* 8772 The number of {exprN} arguments must exactly match the number 8773 of "%" items. If there are not sufficient or too many 8774 arguments an error is given. Up to 18 arguments can be used. 8775 8776 *printf-$* 8777 In certain languages, error and informative messages are 8778 more readable when the order of words is different from the 8779 corresponding message in English. To accommodate translations 8780 having a different word order, positional arguments may be 8781 used to indicate this. For instance: > 8782 8783 #, c-format 8784 msgid "%s returning %s" 8785 msgstr "waarde %2$s komt terug van %1$s" 8786 < 8787 In this example, the sentence has its 2 string arguments 8788 reversed in the output. > 8789 8790 echo printf( 8791 "In The Netherlands, vim's creator's name is: %1$s %2$s", 8792 "Bram", "Moolenaar") 8793 < In The Netherlands, vim's creator's name is: Bram Moolenaar > 8794 8795 echo printf( 8796 "In Belgium, vim's creator's name is: %2$s %1$s", 8797 "Bram", "Moolenaar") 8798 < In Belgium, vim's creator's name is: Moolenaar Bram 8799 8800 Width (and precision) can be specified using the '*' 8801 specifier. In this case, you must specify the field width 8802 position in the argument list. > 8803 8804 echo printf("%1$*2$.*3$d", 1, 2, 3) 8805 < 001 > 8806 echo printf("%2$*3$.*1$d", 1, 2, 3) 8807 < 2 > 8808 echo printf("%3$*1$.*2$d", 1, 2, 3) 8809 < 03 > 8810 echo printf("%1$*2$.*3$g", 1.4142, 2, 3) 8811 < 1.414 8812 8813 You can mix specifying the width and/or precision directly 8814 and via positional arguments: > 8815 8816 echo printf("%1$4.*2$f", 1.4142135, 6) 8817 < 1.414214 > 8818 echo printf("%1$*2$.4f", 1.4142135, 6) 8819 < 1.4142 > 8820 echo printf("%1$*2$.*3$f", 1.4142135, 6, 2) 8821 < 1.41 8822 8823 You will get an overflow error |E1510|, when the field-width 8824 or precision will result in a string longer than 1 MiB 8825 (1024*1024 = 1048576) chars. 8826 8827 *E1500* 8828 You cannot mix positional and non-positional arguments: > 8829 echo printf("%s%1$s", "One", "Two") 8830 < E1500: Cannot mix positional and non-positional arguments: 8831 %s%1$s 8832 8833 *E1501* 8834 You cannot skip a positional argument in a format string: > 8835 echo printf("%3$s%1$s", "One", "Two", "Three") 8836 < E1501: format argument 2 unused in $-style format: 8837 %3$s%1$s 8838 8839 *E1502* 8840 You can re-use a [field-width] (or [precision]) argument: > 8841 echo printf("%1$d at width %2$d is: %1$0*2$d", 1, 2) 8842 < 1 at width 2 is: 01 8843 8844 However, you can't use it as a different type: > 8845 echo printf("%1$d at width %2$ld is: %1$0*2$d", 1, 2) 8846 < E1502: Positional argument 2 used as field width reused as 8847 different type: long int/int 8848 8849 *E1503* 8850 When a positional argument is used, but not the correct number 8851 or arguments is given, an error is raised: > 8852 echo printf("%1$d at width %2$d is: %1$0*2$.*3$d", 1, 2) 8853 < E1503: Positional argument 3 out of bounds: %1$d at width 8854 %2$d is: %1$0*2$.*3$d 8855 8856 Only the first error is reported: > 8857 echo printf("%1$0*2$.*3$d %4$d", 1, 2) 8858 < E1503: Positional argument 3 out of bounds: %1$0*2$.*3$d 8859 %4$d 8860 8861 *E1504* 8862 A positional argument can be used more than once: > 8863 echo printf("%1$s %2$s %1$s", "One", "Two") 8864 < One Two One 8865 8866 However, you can't use a different type the second time: > 8867 echo printf("%1$s %2$s %1$d", "One", "Two") 8868 < E1504: Positional argument 1 type used inconsistently: 8869 int/string 8870 8871 *E1505* 8872 Various other errors that lead to a format string being 8873 wrongly formatted lead to: > 8874 echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2) 8875 < E1505: Invalid format specifier: %1$d at width %2$d is: 8876 %01$*2$.3$d 8877 8878 *E1507* 8879 This internal error indicates that the logic to parse a 8880 positional format argument ran into a problem that couldn't be 8881 otherwise reported. Please file a bug against Vim if you run 8882 into this, copying the exact format string and parameters that 8883 were used. 8884 8885 Return type: |String| 8886 8887 8888 prompt_getprompt({buf}) *prompt_getprompt()* 8889 Returns the effective prompt text for buffer {buf}. {buf} can 8890 be a buffer name or number. See |prompt-buffer|. 8891 8892 If the buffer doesn't exist or isn't a prompt buffer, an empty 8893 string is returned. 8894 8895 Can also be used as a |method|: > 8896 GetBuffer()->prompt_getprompt() 8897 < 8898 Return type: |String| 8899 8900 {only available when compiled with the |+channel| feature} 8901 8902 8903 prompt_setcallback({buf}, {expr}) *prompt_setcallback()* 8904 Set prompt callback for buffer {buf} to {expr}. When {expr} 8905 is an empty string the callback is removed. This has only 8906 effect if {buf} has 'buftype' set to "prompt". 8907 8908 The callback is invoked when pressing Enter. The current 8909 buffer will always be the prompt buffer. A new line for a 8910 prompt is added before invoking the callback, thus the prompt 8911 for which the callback was invoked will be in the last but one 8912 line. 8913 If the callback wants to add text to the buffer, it must 8914 insert it above the last line, since that is where the current 8915 prompt is. This can also be done asynchronously. 8916 The callback is invoked with one argument, which is the text 8917 that was entered at the prompt. This can be an empty string 8918 if the user only typed Enter. 8919 Example: > 8920 func s:TextEntered(text) 8921 if a:text == 'exit' || a:text == 'quit' 8922 stopinsert 8923 " Reset 'modified' to allow the buffer to be closed. 8924 " We assume there is nothing useful to be saved. 8925 set nomodified 8926 close 8927 else 8928 " Do something useful with "a:text". In this example 8929 " we just repeat it. 8930 call append(line('$') - 1, 'Entered: "' .. a:text .. '"') 8931 endif 8932 endfunc 8933 call prompt_setcallback(bufnr(), function('s:TextEntered')) 8934 8935 < Can also be used as a |method|: > 8936 GetBuffer()->prompt_setcallback(callback) 8937 < 8938 Return type: void 8939 8940 {only available when compiled with the |+channel| feature} 8941 8942 prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()* 8943 Set a callback for buffer {buf} to {expr}. When {expr} is an 8944 empty string the callback is removed. This has only effect if 8945 {buf} has 'buftype' set to "prompt". 8946 8947 This callback will be invoked when pressing CTRL-C in Insert 8948 mode. Without setting a callback Vim will exit Insert mode, 8949 as in any buffer. 8950 8951 Can also be used as a |method|: > 8952 GetBuffer()->prompt_setinterrupt(callback) 8953 < 8954 Return type: void 8955 8956 {only available when compiled with the |+channel| feature} 8957 8958 prompt_setprompt({buf}, {text}) *prompt_setprompt()* 8959 Set prompt for buffer {buf} to {text}. You most likely want 8960 {text} to end in a space. 8961 The result is only visible if {buf} has 'buftype' set to 8962 "prompt". Example: > 8963 call prompt_setprompt(bufnr(), 'command: ') 8964 < 8965 Can also be used as a |method|: > 8966 GetBuffer()->prompt_setprompt('command: ') 8967 < 8968 Return type: void 8969 8970 {only available when compiled with the |+channel| feature} 8971 8972 prop_ functions are documented here: |text-prop-functions| 8973 8974 pum_getpos() *pum_getpos()* 8975 If the popup menu (see |ins-completion-menu|) is not visible, 8976 returns an empty |Dictionary|, otherwise, returns a 8977 |Dictionary| with the following keys: 8978 height nr of items visible 8979 width screen cells 8980 row top screen row (0 first row) 8981 col leftmost screen column (0 first col) 8982 size total nr of items 8983 scrollbar |TRUE| if scrollbar is visible 8984 8985 The values are the same as in |v:event| during 8986 |CompleteChanged|. 8987 8988 Return type: dict<number> 8989 8990 8991 pumvisible() *pumvisible()* 8992 Returns non-zero when the popup menu is visible, zero 8993 otherwise. See |ins-completion-menu|. 8994 This can be used to avoid some things that would remove the 8995 popup menu. 8996 8997 Return type: |Number| 8998 8999 9000 py3eval({expr} [, {locals}]) *py3eval()* 9001 Evaluate Python expression {expr} and return its result 9002 converted to Vim data structures. 9003 If a {locals} |Dictionary| is given, it defines set of local 9004 variables available in the expression. The keys are variable 9005 names and the values are the variable values. |Dictionary|, 9006 |List| and |Tuple| values are referenced, and may be updated 9007 by the expression (as if |python-bindeval| was used). 9008 Numbers and strings are returned as they are (strings are 9009 copied though, Unicode strings are additionally converted to 9010 'encoding'). 9011 Lists are represented as Vim |List| type. 9012 Tuples are represented as Vim |Tuple| type. 9013 Dictionaries are represented as Vim |Dictionary| type with 9014 keys converted to strings. 9015 Note that in a `:def` function local variables are not visible 9016 to {expr}. 9017 9018 Can also be used as a |method|: > 9019 GetExpr()->py3eval() 9020 'b",".join(l)'->py3eval({'l': ['a', 'b', 'c']}) 9021 < 9022 Return type: any, depending on {expr} 9023 9024 {only available when compiled with the |+python3| feature} 9025 9026 *E858* *E859* 9027 pyeval({expr} [, {locals}]) *pyeval()* 9028 Evaluate Python expression {expr} and return its result 9029 converted to Vim data structures. 9030 For {locals} see |py3eval()|. 9031 Numbers and strings are returned as they are (strings are 9032 copied though). 9033 Lists are represented as Vim |List| type. 9034 Tuples are represented as Vim |Tuple| type. 9035 Dictionaries are represented as Vim |Dictionary| type, 9036 non-string keys result in error. 9037 Note that in a `:def` function local variables are not visible 9038 to {expr}. 9039 9040 Can also be used as a |method|: > 9041 GetExpr()->pyeval() 9042 < 9043 Return type: any, depending on {expr} 9044 9045 {only available when compiled with the |+python| feature} 9046 9047 pyxeval({expr} [, {locals}]) *pyxeval()* 9048 Evaluate Python expression {expr} and return its result 9049 converted to Vim data structures. 9050 For {locals} see |py3eval()|. 9051 Uses Python 2 or 3, see |python_x| and 'pyxversion'. 9052 See also: |pyeval()|, |py3eval()| 9053 9054 Can also be used as a |method|: > 9055 GetExpr()->pyxeval() 9056 < 9057 Return type: any, depending on {expr} 9058 9059 {only available when compiled with the |+python| or the 9060 |+python3| feature} 9061 9062 rand([{expr}]) *rand()* *random* 9063 Return a pseudo-random Number generated with an xoshiro128** 9064 algorithm using seed {expr}. The returned number is 32 bits, 9065 also on 64 bits systems, for consistency. 9066 {expr} can be initialized by |srand()| and will be updated by 9067 rand(). If {expr} is omitted, an internal seed value is used 9068 and updated. 9069 Returns -1 if {expr} is invalid. 9070 9071 Examples: > 9072 :echo rand() 9073 :let seed = srand() 9074 :echo rand(seed) 9075 :echo rand(seed) % 16 " random number 0 - 15 9076 < 9077 Return type: |Number| 9078 9079 *E726* *E727* 9080 range({expr} [, {max} [, {stride}]]) *range()* 9081 Returns a |List| with Numbers: 9082 - If only {expr} is specified: [0, 1, ..., {expr} - 1] 9083 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}] 9084 - If {stride} is specified: [{expr}, {expr} + {stride}, ..., 9085 {max}] (increasing {expr} with {stride} each time, not 9086 producing a value past {max}). 9087 When the maximum is one before the start the result is an 9088 empty list. When the maximum is more than one before the 9089 start this is an error. 9090 The list can have at most 2147483647 items and {stride} must 9091 fit in a 32 bit number, otherwise |E1510| is given. 9092 Examples: > 9093 range(4) " [0, 1, 2, 3] 9094 range(2, 4) " [2, 3, 4] 9095 range(2, 9, 3) " [2, 5, 8] 9096 range(2, -2, -1) " [2, 1, 0, -1, -2] 9097 range(0) " [] 9098 range(2, 0) " error! 9099 < 9100 Can also be used as a |method|: > 9101 GetExpr()->range() 9102 < 9103 Return type: list<number> 9104 9105 9106 readblob({fname} [, {offset} [, {size}]]) *readblob()* 9107 Read file {fname} in binary mode and return a |Blob|. 9108 If {offset} is specified, read the file from the specified 9109 offset. If it is a negative value, it is used as an offset 9110 from the end of the file. E.g., to read the last 12 bytes: > 9111 readblob('file.bin', -12) 9112 < If {size} is specified, only the specified size will be read. 9113 E.g. to read the first 100 bytes of a file: > 9114 readblob('file.bin', 0, 100) 9115 < If {size} is -1 or omitted, the whole data starting from 9116 {offset} will be read. 9117 This can be also used to read the data from a character device 9118 on Unix when {size} is explicitly set. Only if the device 9119 supports seeking {offset} can be used. Otherwise it should be 9120 zero. E.g. to read 10 bytes from a serial console: > 9121 readblob('/dev/ttyS0', 0, 10) 9122 < When the file can't be opened an error message is given and 9123 the result is an empty |Blob|. 9124 When the offset is beyond the end of the file the result is an 9125 empty blob. 9126 When trying to read more bytes than are available the result 9127 is truncated. 9128 Also see |readfile()| and |writefile()|. 9129 9130 Return type: |Blob| 9131 9132 9133 readdir({directory} [, {expr} [, {dict}]]) *readdir()* 9134 Return a list with file and directory names in {directory}. 9135 You can also use |glob()| if you don't need to do complicated 9136 things, such as limiting the number of matches. 9137 The list will be sorted (case sensitive), see the {dict} 9138 argument below for changing the sort order. 9139 9140 When {expr} is omitted all entries are included. 9141 When {expr} is given, it is evaluated to check what to do: 9142 If {expr} results in -1 then no further entries will 9143 be handled. 9144 If {expr} results in 0 then this entry will not be 9145 added to the list. 9146 If {expr} results in 1 then this entry will be added 9147 to the list. 9148 The entries "." and ".." are always excluded. 9149 Each time {expr} is evaluated |v:val| is set to the entry name. 9150 When {expr} is a function the name is passed as the argument. 9151 For example, to get a list of files ending in ".txt": > 9152 readdir(dirname, {n -> n =~ '\.txt$'}) 9153 < To skip hidden and backup files: > 9154 readdir(dirname, {n -> n !~ '^\.\|\~$'}) 9155 < *E857* 9156 The optional {dict} argument allows for further custom 9157 values. Currently this is used to specify if and how sorting 9158 should be performed. The dict can have the following members: 9159 9160 sort How to sort the result returned from the system. 9161 Valid values are: 9162 "none" do not sort (fastest method) 9163 "case" sort case sensitive (byte value of 9164 each character, technically, using 9165 strcmp()) (default) 9166 "icase" sort case insensitive (technically 9167 using strcasecmp()) 9168 "collate" sort using the collation order 9169 of the "POSIX" or "C" |locale| 9170 (technically using strcoll()) 9171 Other values are silently ignored. 9172 9173 For example, to get a list of all files in the current 9174 directory without sorting the individual entries: > 9175 readdir('.', '1', #{sort: 'none'}) 9176 < If you want to get a directory tree: > 9177 function! s:tree(dir) 9178 return {a:dir : map(readdir(a:dir), 9179 \ {_, x -> isdirectory(x) ? 9180 \ {x : s:tree(a:dir .. '/' .. x)} : x})} 9181 endfunction 9182 echo s:tree(".") 9183 < 9184 Returns an empty List on error. 9185 9186 Can also be used as a |method|: > 9187 GetDirName()->readdir() 9188 < 9189 Return type: list<string> or list<any> 9190 9191 9192 readdirex({directory} [, {expr} [, {dict}]]) *readdirex()* 9193 Extended version of |readdir()|. 9194 Return a list of Dictionaries with file and directory 9195 information in {directory}. 9196 This is useful if you want to get the attributes of file and 9197 directory at the same time as getting a list of a directory. 9198 This is much faster than calling |readdir()| then calling 9199 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for 9200 each file and directory especially on MS-Windows. 9201 The list will by default be sorted by name (case sensitive), 9202 the sorting can be changed by using the optional {dict} 9203 argument, see |readdir()|. 9204 9205 The Dictionary for file and directory information has the 9206 following items: 9207 group Group name of the entry. (Only on Unix) 9208 name Name of the entry. 9209 perm Permissions of the entry. See |getfperm()|. 9210 size Size of the entry. See |getfsize()|. 9211 time Timestamp of the entry. See |getftime()|. 9212 type Type of the entry. 9213 On Unix, almost same as |getftype()| except: 9214 Symlink to a dir "linkd" 9215 Other symlink "link" 9216 On MS-Windows: 9217 Normal file "file" 9218 Directory "dir" 9219 Junction "junction" 9220 Symlink to a dir "linkd" 9221 Other symlink "link" 9222 Other reparse point "reparse" 9223 user User name of the entry's owner. (Only on Unix) 9224 On Unix, if the entry is a symlink, the Dictionary includes 9225 the information of the target (except the "type" item). 9226 On MS-Windows, it includes the information of the symlink 9227 itself because of performance reasons. 9228 9229 When {expr} is omitted all entries are included. 9230 When {expr} is given, it is evaluated to check what to do: 9231 If {expr} results in -1 then no further entries will 9232 be handled. 9233 If {expr} results in 0 then this entry will not be 9234 added to the list. 9235 If {expr} results in 1 then this entry will be added 9236 to the list. 9237 The entries "." and ".." are always excluded. 9238 Each time {expr} is evaluated |v:val| is set to a |Dictionary| 9239 of the entry. 9240 When {expr} is a function the entry is passed as the argument. 9241 For example, to get a list of files ending in ".txt": > 9242 readdirex(dirname, {e -> e.name =~ '.txt$'}) 9243 < 9244 For example, to get a list of all files in the current 9245 directory without sorting the individual entries: > 9246 readdirex(dirname, '1', #{sort: 'none'}) 9247 < 9248 Can also be used as a |method|: > 9249 GetDirName()->readdirex() 9250 < 9251 Return type: list<dict<any>> or list<any> 9252 9253 9254 readfile({fname} [, {type} [, {max}]]) *readfile()* 9255 Read file {fname} and return a |List|, each line of the file 9256 as an item. Lines are broken at NL characters. Macintosh 9257 files separated with CR will result in a single long line 9258 (unless a NL appears somewhere). 9259 All NUL characters are replaced with a NL character. 9260 When {type} contains "b" binary mode is used: 9261 - When the last line ends in a NL an extra empty list item is 9262 added. 9263 - No CR characters are removed. 9264 Otherwise: 9265 - CR characters that appear before a NL are removed. 9266 - Whether the last line ends in a NL or not does not matter. 9267 - When 'encoding' is Unicode any UTF-8 byte order mark is 9268 removed from the text. 9269 When {max} is given this specifies the maximum number of lines 9270 to be read. Useful if you only want to check the first ten 9271 lines of a file: > 9272 :for line in readfile(fname, '', 10) 9273 : if line =~ 'Date' | echo line | endif 9274 :endfor 9275 < When {max} is negative -{max} lines from the end of the file 9276 are returned, or as many as there are. 9277 When {max} is zero the result is an empty list. 9278 Note that without {max} the whole file is read into memory. 9279 Also note that there is no recognition of encoding. Read a 9280 file into a buffer if you need to. 9281 Deprecated (use |readblob()| instead): When {type} contains 9282 "B" a |Blob| is returned with the binary data of the file 9283 unmodified. 9284 When the file can't be opened an error message is given and 9285 the result is an empty list. 9286 Also see |writefile()|. 9287 9288 Can also be used as a |method|: > 9289 GetFileName()->readfile() 9290 < 9291 Return type: list<string> or list<any> 9292 9293 9294 redraw_listener_add({opts}) *redraw_listener_add()* 9295 Add a listener that holds callback functions that will be 9296 called at specific times in the redraw cycle. {opts} is a 9297 dictionary that contain the callback functions to be defined. 9298 At least one callback must be specified. *E1571* 9299 Returns a unique ID that can be passed to 9300 |redraw_listener_remove()|. 9301 9302 {opts} may have the following entries: 9303 9304 on_start Called first on each screen redraw. Takes no 9305 arguments and returns nothing. 9306 on_end Called at the end of each screen redraw. 9307 Takes no arguments and returns nothing. 9308 9309 A good use case for this function is with the |listener_add()| 9310 callback with unbuffered set to TRUE. This allows you to 9311 modify the state on buffer changes, and finally render that 9312 state just before the next redraw, only if it has changed. 9313 Attempting to render or redraw for every single buffer change 9314 would be very inefficient. 9315 9316 You may not call redraw_listener_add() during any of the 9317 callbacks defined in {opts}. *E1570* 9318 9319 Can also be used as a |method|: > 9320 GetOpts()->redraw_listener_add() 9321 < 9322 This function is not available in the |sandbox|. 9323 9324 Return type: |Number| 9325 9326 9327 redraw_listener_remove({id}) *redraw_listener_remove()* 9328 Remove a redraw listener previously added with 9329 |redraw_listener_add()|. Returns FALSE when {id} could not be 9330 found, TRUE when {id} was removed. 9331 9332 Can also be used as a |method|: > 9333 GetRedrawListenerId()->redraw_listener_remove() 9334 < 9335 Return type: void 9336 9337 9338 reduce({object}, {func} [, {initial}]) *reduce()* *E998* 9339 {func} is called for every item in {object}, which can be a 9340 |String|, |List|, |Tuple| or a |Blob|. {func} is called with 9341 two arguments: the result so far and current item. After 9342 processing all items the result is returned. *E1132* 9343 9344 {initial} is the initial result. When omitted, the first item 9345 in {object} is used and {func} is first called for the second 9346 item. If {initial} is not given and {object} is empty no 9347 result can be computed, an E998 error is given. 9348 9349 Examples: > 9350 echo reduce([1, 3, 5], { acc, val -> acc + val }) 9351 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a') 9352 echo reduce(0z1122, { acc, val -> 2 * acc + val }) 9353 echo reduce('xyz', { acc, val -> acc .. ',' .. val }) 9354 < 9355 Can also be used as a |method|: > 9356 echo mylist->reduce({ acc, val -> acc + val }, 0) 9357 < 9358 Return type: |String|, |Blob|, list<{type}> or dict<{type}> 9359 depending on {object} and {func} 9360 9361 9362 reg_executing() *reg_executing()* 9363 Returns the single letter name of the register being executed. 9364 Returns an empty string when no register is being executed. 9365 See |@|. 9366 9367 Return type: |String| 9368 9369 9370 reg_recording() *reg_recording()* 9371 Returns the single letter name of the register being recorded. 9372 Returns an empty string when not recording. See |q|. 9373 9374 Return type: |String| 9375 9376 9377 reltime() *reltime()* 9378 reltime({start}) 9379 reltime({start}, {end}) 9380 Return an item that represents a time value. The item is a 9381 list with items that depend on the system. In Vim 9 script 9382 the type list<any> can be used. 9383 The item can be passed to |reltimestr()| to convert it to a 9384 string or |reltimefloat()| to convert to a Float. For 9385 example, to see the time spent in function Work(): > 9386 var startTime = reltime() 9387 Work() 9388 echo startTime->reltime()->reltimestr() 9389 < 9390 Without an argument reltime() returns the current time (the 9391 representation is system-dependent, it cannot be used as the 9392 wall-clock time, see |localtime()| for that). 9393 With one argument it returns the time passed since the time 9394 specified in the argument. 9395 With two arguments it returns the time passed between {start} 9396 and {end}. 9397 9398 The {start} and {end} arguments must be values returned by 9399 reltime(). If there is an error an empty List is returned in 9400 legacy script, in Vim9 script an error is given. 9401 9402 Can also be used as a |method|: > 9403 GetStart()->reltime() 9404 < 9405 Return type: list<number> 9406 9407 {only available when compiled with the |+reltime| feature} 9408 9409 9410 reltimefloat({time}) *reltimefloat()* 9411 Return a Float that represents the time value of {time}. 9412 Example: > 9413 let start = reltime() 9414 call MyFunction() 9415 let seconds = reltimefloat(reltime(start)) 9416 < See the note of |reltimestr()| about overhead. 9417 Also see |profiling|. 9418 If there is an error 0.0 is returned in legacy script, in Vim9 9419 script an error is given. 9420 9421 Can also be used as a |method|: > 9422 reltime(start)->reltimefloat() 9423 < 9424 Return type: |Float| 9425 9426 {only available when compiled with the |+reltime| feature} 9427 9428 9429 reltimestr({time}) *reltimestr()* 9430 Return a String that represents the time value of {time}. 9431 This is the number of seconds, a dot and the number of 9432 microseconds. Example: > 9433 let start = reltime() 9434 call MyFunction() 9435 echo reltimestr(reltime(start)) 9436 < Note that overhead for the commands will be added to the time. 9437 The accuracy depends on the system. Use |reltimefloat()| for 9438 the greatest accuracy which is nanoseconds on some systems. 9439 Leading spaces are used to make the string align nicely. You 9440 can use |split()| to remove it. > 9441 echo split(reltimestr(reltime(start)))[0] 9442 < Also see |profiling|. 9443 If there is an error an empty string is returned in legacy 9444 script, in Vim9 script an error is given. 9445 9446 Can also be used as a |method|: > 9447 reltime(start)->reltimestr() 9448 < 9449 Return type: |String| 9450 9451 {only available when compiled with the |+reltime| feature} 9452 9453 *remote_expr()* *E449* 9454 remote_expr({server}, {string} [, {idvar} [, {timeout}]]) 9455 Send the {string} to {server}. The {server} argument is a 9456 string, also see |{server}|. 9457 9458 The string is sent as an expression and the result is returned 9459 after evaluation. The result must be a String or a |List| 9460 other types will be converted to String. A |List| is turned 9461 into a String by joining the items with a line break in 9462 between (not at the end), like with join(expr, "\n"). 9463 9464 If {idvar} is present and not empty, it is taken as the name 9465 of a variable and a {serverid} for later use with 9466 |remote_read()| is stored there. 9467 9468 If {timeout} is given the read times out after this many 9469 seconds. Otherwise a timeout of 600 seconds is used. 9470 9471 See also |clientserver| |RemoteReply|. 9472 This function is not available in the |sandbox|. 9473 {only available when compiled with the |+clientserver| feature} 9474 Note: Any errors will cause a local error message to be issued 9475 and the result will be the empty string. 9476 9477 Variables will be evaluated in the global namespace, 9478 independent of a function currently being active. Except 9479 when in debug mode, then local function variables and 9480 arguments can be evaluated. 9481 9482 Examples: > 9483 :echo remote_expr("gvim", "2+2") 9484 :echo remote_expr("gvim1", "b:current_syntax") 9485 < 9486 Can also be used as a |method|: > 9487 ServerName()->remote_expr(expr) 9488 < 9489 Return type: |String| or list<{type}> 9490 9491 9492 remote_foreground({server}) *remote_foreground()* 9493 Move the Vim server with the name {server} to the foreground. 9494 The {server} argument is a string, also see |{server}|. 9495 This works like: > 9496 remote_expr({server}, "foreground()") 9497 < Except that on Win32 systems the client does the work, to work 9498 around the problem that the OS doesn't always allow the server 9499 to bring itself to the foreground. 9500 Note: This does not restore the window if it was minimized, 9501 like |foreground()| does. 9502 This function is not available in the |sandbox|. 9503 9504 Can also be used as a |method|: > 9505 ServerName()->remote_foreground() 9506 < 9507 Return type: void 9508 9509 {only in the Win32, Motif and GTK GUI versions and the 9510 Win32 console version} 9511 9512 9513 remote_peek({serverid} [, {retvar}]) *remote_peek()* 9514 Returns a positive number if there are available strings 9515 from {serverid}. Copies any reply string into the variable 9516 {retvar} if specified. {retvar} must be a string with the 9517 name of a variable. 9518 Returns zero if none are available. 9519 Returns -1 if something is wrong. 9520 See also |clientserver|. 9521 This function is not available in the |sandbox|. 9522 {only available when compiled with the |+clientserver| feature} 9523 Examples: > 9524 :let repl = "" 9525 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl 9526 9527 < Can also be used as a |method|: > 9528 ServerId()->remote_peek() 9529 < 9530 Return type: |Number| 9531 9532 9533 remote_read({serverid} [, {timeout}]) *remote_read()* 9534 Return the oldest available reply from {serverid} and consume 9535 it. Unless a {timeout} in seconds is given, it blocks until a 9536 reply is available. Returns an empty string, if a reply is 9537 not available or on error. 9538 See also |clientserver|. 9539 This function is not available in the |sandbox|. 9540 {only available when compiled with the |+clientserver| feature} 9541 Example: > 9542 :echo remote_read(id) 9543 9544 < Can also be used as a |method|: > 9545 ServerId()->remote_read() 9546 < 9547 Return type: |String| 9548 9549 9550 remote_send({server}, {string} [, {idvar}]) *remote_send()* *E241* 9551 Send the {string} to {server}. The {server} argument is a 9552 string, also see |{server}|. 9553 9554 The string is sent as input keys and the function returns 9555 immediately. At the Vim server the keys are not mapped 9556 |:map|. 9557 9558 If {idvar} is present, it is taken as the name of a variable 9559 and a {serverid} for later use with |remote_read()| is stored 9560 there. 9561 9562 See also |clientserver| |RemoteReply|. 9563 This function is not available in the |sandbox|. 9564 {only available when compiled with the |+clientserver| feature} 9565 9566 Note: Any errors will be reported in the server and may mess 9567 up the display. 9568 Examples: > 9569 :echo remote_send("gvim", ":DropAndReply " .. file, 9570 \ "serverid") .. remote_read(serverid) 9571 9572 :autocmd NONE RemoteReply * 9573 \ echo remote_read(expand("<amatch>")) 9574 :echo remote_send("gvim", ":sleep 10 | echo " .. 9575 \ 'server2client(expand("<client>"), "HELLO")<CR>') 9576 < 9577 Can also be used as a |method|: > 9578 ServerName()->remote_send(keys) 9579 < 9580 Return type: |String| 9581 9582 9583 remote_startserver({name}) *remote_startserver()* *E941* *E942* 9584 Become the server {name}. {name} must be a non-empty string. 9585 This fails if already running as a server, when |v:servername| 9586 is not empty. 9587 9588 Can also be used as a |method|: > 9589 ServerName()->remote_startserver() 9590 < 9591 Return type: void 9592 9593 {only available when compiled with the |+clientserver| feature} 9594 9595 9596 remove({list}, {idx}) *remove()* 9597 remove({list}, {idx}, {end}) 9598 Without {end}: Remove the item at {idx} from |List| {list} and 9599 return the item. 9600 With {end}: Remove items from {idx} to {end} (inclusive) and 9601 return a |List| with these items. When {idx} points to the same 9602 item as {end} a list with one item is returned. When {end} 9603 points to an item before {idx} this is an error. 9604 See |list-index| for possible values of {idx} and {end}. 9605 Returns zero on error. 9606 Example: > 9607 :echo "last item: " .. remove(mylist, -1) 9608 :call remove(mylist, 0, 9) 9609 < 9610 Use |delete()| to remove a file. 9611 9612 Can also be used as a |method|: > 9613 mylist->remove(idx) 9614 < 9615 Return type: any, depending on {list} 9616 9617 9618 remove({blob}, {idx}) 9619 remove({blob}, {idx}, {end}) 9620 Without {end}: Remove the byte at {idx} from |Blob| {blob} and 9621 return the byte. 9622 With {end}: Remove bytes from {idx} to {end} (inclusive) and 9623 return a |Blob| with these bytes. When {idx} points to the same 9624 byte as {end} a |Blob| with one byte is returned. When {end} 9625 points to a byte before {idx} this is an error. 9626 Returns zero on error. 9627 Example: > 9628 :echo "last byte: " .. remove(myblob, -1) 9629 :call remove(mylist, 0, 9) 9630 < 9631 Return type: |Number| 9632 9633 9634 remove({dict}, {key}) 9635 Remove the entry from {dict} with key {key} and return it. 9636 Example: > 9637 :echo "removed " .. remove(dict, "one") 9638 < If there is no {key} in {dict} this is an error. 9639 Returns zero on error. 9640 9641 Return type: any, depending on {dict} 9642 9643 9644 rename({from}, {to}) *rename()* 9645 Rename the file by the name {from} to the name {to}. This 9646 should also work to move files across file systems. The 9647 result is a Number, which is 0 if the file was renamed 9648 successfully, and non-zero when the renaming failed. 9649 NOTE: If {to} exists it is overwritten without warning. 9650 This function is not available in the |sandbox|. 9651 9652 Can also be used as a |method|: > 9653 GetOldName()->rename(newname) 9654 < 9655 Return type: |Number| 9656 9657 9658 repeat({expr}, {count}) *repeat()* 9659 Repeat {expr} {count} times and return the concatenated 9660 result. Example: > 9661 :let separator = repeat('-', 80) 9662 < When {count} is zero or negative the result is empty. 9663 When {expr} is a |List|, a |Tuple| or a |Blob| the result is 9664 {expr} concatenated {count} times. Example: > 9665 :let longlist = repeat(['a', 'b'], 3) 9666 < Results in ['a', 'b', 'a', 'b', 'a', 'b']. 9667 9668 Can also be used as a |method|: > 9669 mylist->repeat(count) 9670 < 9671 Return type: |String|, |Blob|, list<{type}> or tuple<{type}> 9672 depending on {expr} 9673 9674 9675 resolve({filename}) *resolve()* *E655* 9676 On MS-Windows, when {filename} is a shortcut (a .lnk file), 9677 returns the path the shortcut points to in a simplified form. 9678 When {filename} is a symbolic link or junction point, return 9679 the full path to the target. If the target of junction is 9680 removed, return {filename}. 9681 On Unix, repeat resolving symbolic links in all path 9682 components of {filename} and return the simplified result. 9683 To cope with link cycles, resolving of symbolic links is 9684 stopped after 100 iterations. 9685 On other systems, return the simplified {filename}. 9686 The simplification step is done as by |simplify()|. 9687 resolve() keeps a leading path component specifying the 9688 current directory (provided the result is still a relative 9689 path name) and also keeps a trailing path separator. 9690 9691 Can also be used as a |method|: > 9692 GetName()->resolve() 9693 < 9694 Return type: |String| 9695 9696 9697 reverse({object}) *reverse()* 9698 Reverse the order of items in {object}. {object} can be a 9699 |List|, a |Tuple|, a |Blob| or a |String|. For a List and a 9700 Blob the items are reversed in-place and {object} is returned. 9701 For a Tuple, a new Tuple is returned. 9702 For a String a new String is returned. 9703 Returns zero if {object} is not a List, Tuple, Blob or a 9704 String. If you want a List or Blob to remain unmodified make 9705 a copy first: > 9706 :let revlist = reverse(copy(mylist)) 9707 < Can also be used as a |method|: > 9708 mylist->reverse() 9709 < 9710 Return type: |String|, |Blob|, list<{type}> or tuple<{type}> 9711 depending on {object} 9712 9713 9714 round({expr}) *round()* 9715 Round off {expr} to the nearest integral value and return it 9716 as a |Float|. If {expr} lies halfway between two integral 9717 values, then use the larger one (away from zero). 9718 {expr} must evaluate to a |Float| or a |Number|. 9719 Returns 0.0 if {expr} is not a |Float| or a |Number|. 9720 Examples: > 9721 echo round(0.456) 9722 < 0.0 > 9723 echo round(4.5) 9724 < 5.0 > 9725 echo round(-4.5) 9726 < -5.0 9727 9728 Can also be used as a |method|: > 9729 Compute()->round() 9730 < 9731 Return type: |Float| 9732 9733 9734 rubyeval({expr}) *rubyeval()* 9735 Evaluate Ruby expression {expr} and return its result 9736 converted to Vim data structures. 9737 Numbers, floats and strings are returned as they are (strings 9738 are copied though). 9739 Arrays are represented as Vim |List| type. 9740 Hashes are represented as Vim |Dictionary| type. 9741 Other objects are represented as strings resulted from their 9742 "Object#to_s" method. 9743 Note that in a `:def` function local variables are not visible 9744 to {expr}. 9745 9746 Can also be used as a |method|: > 9747 GetRubyExpr()->rubyeval() 9748 < 9749 Return type: any, depending on {expr} 9750 9751 {only available when compiled with the |+ruby| feature} 9752 9753 screenattr({row}, {col}) *screenattr()* 9754 Like |screenchar()|, but return the attribute. This is a rather 9755 arbitrary number that can only be used to compare to the 9756 attribute at other positions. 9757 Returns -1 when row or col is out of range. 9758 9759 Can also be used as a |method|: > 9760 GetRow()->screenattr(col) 9761 < 9762 Return type: |Number| 9763 9764 9765 screenchar({row}, {col}) *screenchar()* 9766 The result is a Number, which is the character at position 9767 [row, col] on the screen. This works for every possible 9768 screen position, also status lines, window separators and the 9769 command line. The top left position is row one, column one 9770 The character excludes composing characters. For double-byte 9771 encodings it may only be the first byte. 9772 This is mainly to be used for testing. 9773 Returns -1 when row or col is out of range. 9774 9775 Can also be used as a |method|: > 9776 GetRow()->screenchar(col) 9777 < 9778 Return type: |Number| 9779 9780 9781 screenchars({row}, {col}) *screenchars()* 9782 The result is a |List| of Numbers. The first number is the same 9783 as what |screenchar()| returns. Further numbers are 9784 composing characters on top of the base character. 9785 This is mainly to be used for testing. 9786 Returns an empty List when row or col is out of range. 9787 9788 Can also be used as a |method|: > 9789 GetRow()->screenchars(col) 9790 < 9791 Return type: list<number> or list<any> 9792 9793 9794 screencol() *screencol()* 9795 The result is a Number, which is the current screen column of 9796 the cursor. The leftmost column has number 1. 9797 This function is mainly used for testing. 9798 9799 Note: Always returns the current screen column, thus if used 9800 in a command (e.g. ":echo screencol()") it will return the 9801 column inside the command line, which is 1 when the command is 9802 executed. To get the cursor position in the file use one of 9803 the following mappings: > 9804 nnoremap <expr> GG ":echom " .. screencol() .. "\n" 9805 nnoremap <silent> GG :echom screencol()<CR> 9806 nnoremap GG <Cmd>echom screencol()<CR> 9807 < 9808 Return type: |Number| 9809 9810 9811 screenpos({winid}, {lnum}, {col}) *screenpos()* 9812 The result is a Dict with the screen position of the text 9813 character in window {winid} at buffer line {lnum} and column 9814 {col}. {col} is a one-based byte index. 9815 The Dict has these members: 9816 row screen row 9817 col first screen column 9818 endcol last screen column 9819 curscol cursor screen column 9820 If the specified position is not visible, all values are zero. 9821 The "endcol" value differs from "col" when the character 9822 occupies more than one screen cell. E.g. for a Tab "col" can 9823 be 1 and "endcol" can be 8. 9824 The "curscol" value is where the cursor would be placed. For 9825 a Tab it would be the same as "endcol", while for a double 9826 width character it would be the same as "col". 9827 With 'rightleft' set, "col" and "endcol" are still counted 9828 from the start of the line, while "curscol" is the actual 9829 screen column, thus counted from the left side of the 9830 window. 9831 The |conceal| feature is ignored here, the column numbers are 9832 as if 'conceallevel' is zero. You can set the cursor to the 9833 right position and use |screencol()| to get the value with 9834 |conceal| taken into account. 9835 |virtual-text| above the line occupies its own screen line and 9836 is counted: the first character of the line is then on the 9837 screen line below it. 9838 If the position is in a closed fold the screen position of the 9839 first character is returned, {col} is not used. 9840 Returns an empty Dict if {winid} is invalid. 9841 9842 Can also be used as a |method|: > 9843 GetWinid()->screenpos(lnum, col) 9844 < 9845 Return type: dict<number> or dict<any> 9846 9847 9848 screenrow() *screenrow()* 9849 The result is a Number, which is the current screen row of the 9850 cursor. The top line has number one. 9851 This function is mainly used for testing. 9852 Alternatively you can use |winline()|. 9853 9854 Note: Same restrictions as with |screencol()|. 9855 9856 Return type: |Number| 9857 9858 9859 screenstring({row}, {col}) *screenstring()* 9860 The result is a String that contains the base character and 9861 any composing characters at position [row, col] on the screen. 9862 This is like |screenchars()| but returning a String with the 9863 characters. 9864 This is mainly to be used for testing. 9865 Returns an empty String when row or col is out of range. 9866 9867 Can also be used as a |method|: > 9868 GetRow()->screenstring(col) 9869 < 9870 Return type: |String| 9871 9872 *search()* 9873 search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) 9874 Search for regexp pattern {pattern}. The search starts at the 9875 cursor position (you can use |cursor()| to set it). 9876 9877 When a match has been found its line number is returned. 9878 If there is no match a 0 is returned and the cursor doesn't 9879 move. No error message is given. 9880 To get the matched string, use |matchbufline()|. 9881 9882 {flags} is a String, which can contain these character flags: 9883 'b' search Backward instead of forward 9884 'c' accept a match at the Cursor position 9885 'e' move to the End of the match 9886 'n' do Not move the cursor 9887 'p' return number of matching sub-Pattern (see below) 9888 's' Set the ' mark at the previous location of the cursor 9889 'w' Wrap around the end of the file 9890 'W' don't Wrap around the end of the file 9891 'z' start searching at the cursor column instead of Zero 9892 If neither 'w' or 'W' is given, the 'wrapscan' option applies. 9893 9894 If the 's' flag is supplied, the ' mark is set, only if the 9895 cursor is moved. The 's' flag cannot be combined with the 'n' 9896 flag. 9897 9898 'ignorecase', 'smartcase' and 'magic' are used. 9899 9900 When the 'z' flag is not given, forward searching always 9901 starts in column zero and then matches before the cursor are 9902 skipped. When the 'c' flag is present in 'cpo' the next 9903 search starts after the match. Without the 'c' flag the next 9904 search starts one column after the start of the match. This 9905 matters for overlapping matches. See |cpo-c|. You can also 9906 insert "\ze" to change where the match ends, see |/\ze|. 9907 9908 When searching backwards and the 'z' flag is given then the 9909 search starts in column zero, thus no match in the current 9910 line will be found (unless wrapping around the end of the 9911 file). 9912 9913 When the {stopline} argument is given then the search stops 9914 after searching this line. This is useful to restrict the 9915 search to a range of lines. Examples: > 9916 let match = search('(', 'b', line("w0")) 9917 let end = search('END', '', line("w$")) 9918 < When {stopline} is used and it is not zero this also implies 9919 that the search does not wrap around the end of the file. 9920 A zero value is equal to not giving the argument. 9921 *E1285* *E1286* *E1287* *E1288* *E1289* 9922 When the {timeout} argument is given the search stops when 9923 more than this many milliseconds have passed. Thus when 9924 {timeout} is 500 the search stops after half a second. 9925 The value must not be negative. A zero value is like not 9926 giving the argument. 9927 9928 Note: the timeout is only considered when searching, not 9929 while evaluating the {skip} expression. 9930 {only available when compiled with the |+reltime| feature} 9931 9932 If the {skip} expression is given it is evaluated with the 9933 cursor positioned on the start of a match. If it evaluates to 9934 non-zero this match is skipped. This can be used, for 9935 example, to skip a match in a comment or a string. 9936 {skip} can be a string, which is evaluated as an expression, a 9937 function reference or a lambda. 9938 When {skip} is omitted or empty, every match is accepted. 9939 When evaluating {skip} causes an error the search is aborted 9940 and -1 returned. 9941 *search()-sub-match* 9942 With the 'p' flag the returned value is one more than the 9943 first sub-match in \(\). One if none of them matched but the 9944 whole pattern did match. 9945 To get the column number too use |searchpos()|. 9946 9947 The cursor will be positioned at the match, unless the 'n' 9948 flag is used. 9949 9950 Example (goes over all files in the argument list): > 9951 :let n = 1 9952 :while n <= argc() " loop over all files in arglist 9953 : exe "argument " .. n 9954 : " start at the last char in the file and wrap for the 9955 : " first search to find match at start of file 9956 : normal G$ 9957 : let flags = "w" 9958 : while search("foo", flags) > 0 9959 : s/foo/bar/g 9960 : let flags = "W" 9961 : endwhile 9962 : update " write the file if modified 9963 : let n = n + 1 9964 :endwhile 9965 < 9966 Example for using some flags: > 9967 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe') 9968 < This will search for the keywords "if", "else", and "endif" 9969 under or after the cursor. Because of the 'p' flag, it 9970 returns 1, 2, or 3 depending on which keyword is found, or 0 9971 if the search fails. With the cursor on the first word of the 9972 line: 9973 if (foo == 0) | let foo = foo + 1 | endif ~ 9974 the function returns 1. Without the 'c' flag, the function 9975 finds the "endif" and returns 3. The same thing happens 9976 without the 'e' flag if the cursor is on the "f" of "if". 9977 The 'n' flag tells the function not to move the cursor. 9978 9979 Can also be used as a |method|: > 9980 GetPattern()->search() 9981 < 9982 Return type: |Number| 9983 9984 9985 searchcount([{options}]) *searchcount()* 9986 Get or update the last search count, like what is displayed 9987 without the "S" flag in 'shortmess'. This works even if 9988 'shortmess' does contain the "S" flag. 9989 9990 This returns a |Dictionary|. The dictionary is empty if the 9991 previous pattern was not set and "pattern" was not specified. 9992 9993 key type meaning ~ 9994 current |Number| current position of match; 9995 0 if the cursor position is 9996 before the first match 9997 exact_match |Boolean| 1 if "current" is matched on 9998 "pos", otherwise 0 9999 total |Number| total count of matches found 10000 incomplete |Number| 0: search was fully completed 10001 1: recomputing was timed out 10002 2: max count exceeded 10003 10004 For {options} see further down. 10005 10006 To get the last search count when |n| or |N| was pressed, call 10007 this function with `recompute: 0` . This sometimes returns 10008 wrong information because of 'maxsearchcount'. 10009 If the count exceeded 'maxsearchcount', the result must be 10010 'maxsearchcount' + 1. If you want to get correct information, 10011 specify `recompute: 1`: > 10012 10013 " result == 'maxsearchcount' + 1 when many matches 10014 let result = searchcount(#{recompute: 0}) 10015 10016 " Below returns correct result (recompute defaults 10017 " to 1) 10018 let result = searchcount() 10019 < 10020 The function is useful to add the count to 'statusline': > 10021 function! LastSearchCount() abort 10022 let result = searchcount(#{recompute: 0}) 10023 if empty(result) 10024 return '' 10025 endif 10026 if result.incomplete ==# 1 " timed out 10027 return printf(' /%s [?/??]', @/) 10028 elseif result.incomplete ==# 2 " max count exceeded 10029 if result.total > result.maxcount && 10030 \ result.current > result.maxcount 10031 return printf(' /%s [>%d/>%d]', @/, 10032 \ result.current, result.total) 10033 elseif result.total > result.maxcount 10034 return printf(' /%s [%d/>%d]', @/, 10035 \ result.current, result.total) 10036 endif 10037 endif 10038 return printf(' /%s [%d/%d]', @/, 10039 \ result.current, result.total) 10040 endfunction 10041 let &statusline ..= '%{LastSearchCount()}' 10042 10043 " Or if you want to show the count only when 10044 " 'hlsearch' was on 10045 " let &statusline ..= 10046 " \ '%{v:hlsearch ? LastSearchCount() : ""}' 10047 < 10048 You can also update the search count, which can be useful in a 10049 |CursorMoved| or |CursorMovedI| autocommand: > 10050 10051 autocmd CursorMoved,CursorMovedI * 10052 \ let s:searchcount_timer = timer_start( 10053 \ 200, function('s:update_searchcount')) 10054 function! s:update_searchcount(timer) abort 10055 if a:timer ==# s:searchcount_timer 10056 call searchcount(#{ 10057 \ recompute: 1, maxcount: 0, timeout: 100}) 10058 redrawstatus 10059 endif 10060 endfunction 10061 < 10062 This can also be used to count matched texts with specified 10063 pattern in the current buffer using "pattern": > 10064 10065 " Count '\<foo\>' in this buffer 10066 " (Note that it also updates search count) 10067 let result = searchcount(#{pattern: '\<foo\>'}) 10068 10069 " To restore old search count by old pattern, 10070 " search again 10071 call searchcount() 10072 < 10073 {options} must be a |Dictionary|. It can contain: 10074 key type meaning ~ 10075 recompute |Boolean| if |TRUE|, recompute the count 10076 like |n| or |N| was executed. 10077 otherwise returns the last 10078 computed result (when |n| or 10079 |N| was used when "S" is not 10080 in 'shortmess', or this 10081 function was called). 10082 (default: |TRUE|) 10083 pattern |String| recompute if this was given 10084 and different with |@/|. 10085 this works as same as the 10086 below command is executed 10087 before calling this function > 10088 let @/ = pattern 10089 < (default: |@/|) 10090 timeout |Number| 0 or negative number is no 10091 timeout. timeout milliseconds 10092 for recomputing the result 10093 (default: 0) 10094 maxcount |Number| 0 or negative number is no 10095 limit. max count of matched 10096 text while recomputing the 10097 result. if search exceeded 10098 total count, "total" value 10099 becomes `maxcount + 1` 10100 (default: 'maxsearchcount') 10101 pos |List| `[lnum, col, off]` value 10102 when recomputing the result. 10103 this changes "current" result 10104 value. see |cursor()|, 10105 |getpos()| 10106 (default: cursor's position) 10107 10108 Can also be used as a |method|: > 10109 GetSearchOpts()->searchcount() 10110 < 10111 Return type: dict<number> 10112 10113 10114 searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()* 10115 Search for the declaration of {name}. 10116 10117 With a non-zero {global} argument it works like |gD|, find 10118 first match in the file. Otherwise it works like |gd|, find 10119 first match in the function. 10120 10121 With a non-zero {thisblock} argument matches in a {} block 10122 that ends before the cursor position are ignored. Avoids 10123 finding variable declarations only valid in another scope. 10124 10125 Moves the cursor to the found match. 10126 Returns zero for success, non-zero for failure. 10127 Example: > 10128 if searchdecl('myvar') == 0 10129 echo getline('.') 10130 endif 10131 < 10132 Can also be used as a |method|: > 10133 GetName()->searchdecl() 10134 < 10135 Return type: |Number| 10136 10137 *searchpair()* 10138 searchpair({start}, {middle}, {end} [, {flags} [, {skip} 10139 [, {stopline} [, {timeout}]]]]) 10140 Search for the match of a nested start-end pair. This can be 10141 used to find the "endif" that matches an "if", while other 10142 if/endif pairs in between are ignored. 10143 The search starts at the cursor. The default is to search 10144 forward, include 'b' in {flags} to search backward. 10145 If a match is found, the cursor is positioned at it and the 10146 line number is returned. If no match is found 0 or -1 is 10147 returned and the cursor doesn't move. No error message is 10148 given. 10149 10150 {start}, {middle} and {end} are patterns, see |pattern|. They 10151 must not contain \( \) pairs. Use of \%( \) is allowed. When 10152 {middle} is not empty, it is found when searching from either 10153 direction, but only when not in a nested start-end pair. A 10154 typical use is: > 10155 searchpair('\<if\>', '\<else\>', '\<endif\>') 10156 < By leaving {middle} empty the "else" is skipped. 10157 10158 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with 10159 |search()|. Additionally: 10160 'r' Repeat until no more matches found; will find the 10161 outer pair. Implies the 'W' flag. 10162 'm' Return number of matches instead of line number with 10163 the match; will be > 1 when 'r' is used. 10164 Note: it's nearly always a good idea to use the 'W' flag, to 10165 avoid wrapping around the end of the file. 10166 10167 When a match for {start}, {middle} or {end} is found, the 10168 {skip} expression is evaluated with the cursor positioned on 10169 the start of the match. It should return non-zero if this 10170 match is to be skipped. E.g., because it is inside a comment 10171 or a string. 10172 When {skip} is omitted or empty, every match is accepted. 10173 When evaluating {skip} causes an error the search is aborted 10174 and -1 returned. 10175 {skip} can be a string, a lambda, a funcref or a partial. 10176 Anything else makes the function fail. 10177 In a `:def` function when the {skip} argument is a string 10178 constant it is compiled into instructions. 10179 10180 For {stopline} and {timeout} see |search()|. 10181 10182 The value of 'ignorecase' is used. 'magic' is ignored, the 10183 patterns are used like it's on. 10184 10185 The search starts exactly at the cursor. A match with 10186 {start}, {middle} or {end} at the next character, in the 10187 direction of searching, is the first one found. Example: > 10188 if 1 10189 if 2 10190 endif 2 10191 endif 1 10192 < When starting at the "if 2", with the cursor on the "i", and 10193 searching forwards, the "endif 2" is found. When starting on 10194 the character just before the "if 2", the "endif 1" will be 10195 found. That's because the "if 2" will be found first, and 10196 then this is considered to be a nested if/endif from "if 2" to 10197 "endif 2". 10198 When searching backwards and {end} is more than one character, 10199 it may be useful to put "\zs" at the end of the pattern, so 10200 that when the cursor is inside a match with the end it finds 10201 the matching start. 10202 10203 Example, to find the "endif" command in a Vim script: > 10204 10205 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W', 10206 \ 'getline(".") =~ "^\\s*\""') 10207 10208 < The cursor must be at or after the "if" for which a match is 10209 to be found. Note that single-quote strings are used to avoid 10210 having to double the backslashes. The skip expression only 10211 catches comments at the start of a line, not after a command. 10212 Also, a word "en" or "if" halfway a line is considered a 10213 match. 10214 Another example, to search for the matching "{" of a "}": > 10215 10216 :echo searchpair('{', '', '}', 'bW') 10217 10218 < This works when the cursor is at or before the "}" for which a 10219 match is to be found. To reject matches that syntax 10220 highlighting recognized as strings: > 10221 10222 :echo searchpair('{', '', '}', 'bW', 10223 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"') 10224 < 10225 Return type: |Number| 10226 10227 *searchpairpos()* 10228 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} 10229 [, {stopline} [, {timeout}]]]]) 10230 Same as |searchpair()|, but returns a |List| with the line and 10231 column position of the match. The first element of the |List| 10232 is the line number and the second element is the byte index of 10233 the column position of the match. If no match is found, 10234 returns [0, 0]. > 10235 10236 :let [lnum,col] = searchpairpos('{', '', '}', 'n') 10237 < 10238 See |match-parens| for a bigger and more useful example. 10239 10240 Return type: list<number> 10241 10242 *searchpos()* 10243 searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) 10244 Same as |search()|, but returns a |List| with the line and 10245 column position of the match. The first element of the |List| 10246 is the line number and the second element is the byte index of 10247 the column position of the match. If no match is found, 10248 returns [0, 0]. 10249 Example: > 10250 :let [lnum, col] = searchpos('mypattern', 'n') 10251 10252 < When the 'p' flag is given then there is an extra item with 10253 the sub-pattern match number |search()-sub-match|. Example: > 10254 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np') 10255 < In this example "submatch" is 2 when a lowercase letter is 10256 found |/\l|, 3 when an uppercase letter is found |/\u|. 10257 10258 Can also be used as a |method|: > 10259 GetPattern()->searchpos() 10260 < 10261 Return type: list<number> 10262 10263 10264 server2client({clientid}, {string}) *server2client()* 10265 Send a reply string to {clientid}. The most recent {clientid} 10266 that sent a string can be retrieved with expand("<client>"). 10267 {only available when compiled with the |+clientserver| feature} 10268 Returns zero for success, -1 for failure. 10269 Note: 10270 This id has to be stored before the next command can be 10271 received. I.e. before returning from the received command and 10272 before calling any commands that waits for input. 10273 See also |clientserver|. 10274 Example: > 10275 :echo server2client(expand("<client>"), "HELLO") 10276 10277 < Can also be used as a |method|: > 10278 GetClientId()->server2client(string) 10279 < 10280 Return type: |Number| 10281 10282 10283 serverlist([{dict}]) *serverlist()* 10284 Return a list of available server names, one per line. 10285 When there are no servers or the information is not available 10286 an empty string is returned, or an empty |List| when the 10287 "list" option below is used. 10288 10289 When the server cannot be reached, no error will be given and 10290 the result is an empty string or |List|. 10291 {only available when compiled with the |+clientserver| feature} 10292 10293 If {dict} is given, then it is a |Dictionary| supporting the 10294 following options: 10295 key type meaning ~ 10296 list |Boolean| Return a list of strings, 10297 where each string is a server 10298 name. 10299 10300 See also |clientserver|. 10301 10302 Example: > 10303 :echo serverlist() 10304 < 10305 Return type: |String| or list<string> 10306 10307 10308 setbufline({buf}, {lnum}, {text}) *setbufline()* 10309 Set line {lnum} to {text} in buffer {buf}. This works like 10310 |setline()| for the specified buffer. 10311 10312 This function works only for loaded buffers. First call 10313 |bufload()| if needed. 10314 10315 To insert lines use |appendbufline()|. 10316 Any text properties in {lnum} are cleared. 10317 10318 {text} can be a string to set one line, or a List of strings 10319 to set multiple lines. If the List extends below the last 10320 line then those lines are added. If the List is empty then 10321 nothing is changed and zero is returned. 10322 10323 For the use of {buf}, see |bufname()| above. 10324 10325 {lnum} is used like with |setline()|. 10326 Use "$" to refer to the last line in buffer {buf}. 10327 When {lnum} is just below the last line the {text} will be 10328 added below the last line. 10329 10330 When {buf} is not a valid buffer, the buffer is not loaded or 10331 {lnum} is not valid then 1 is returned. In |Vim9| script an 10332 error is given. 10333 On success 0 is returned. 10334 10335 Can also be used as a |method|, the base is passed as the 10336 third argument: > 10337 GetText()->setbufline(buf, lnum) 10338 < 10339 Return type: |Number| 10340 10341 10342 setbufvar({buf}, {varname}, {val}) *setbufvar()* 10343 Set option or local variable {varname} in buffer {buf} to 10344 {val}. 10345 This also works for a global option or a window-local option, 10346 but it doesn't work for a global or local window variable. A 10347 window-local option is set in a window of the current tab page 10348 that displays {buf}, and the global value is unchanged. When 10349 no window in the current tab page displays {buf} the option is 10350 not set and no error is given; use |setwinvar()| or 10351 |win_execute()| for that. 10352 For the use of {buf}, see |bufname()| above. 10353 The {varname} argument is a string. 10354 Note that the variable name without "b:" must be used. 10355 Examples: > 10356 :call setbufvar(1, "&mod", 1) 10357 :call setbufvar("todo", "myvar", "foobar") 10358 < This function is not available in the |sandbox|. 10359 10360 Can also be used as a |method|, the base is passed as the 10361 third argument: > 10362 GetValue()->setbufvar(buf, varname) 10363 < 10364 Return type: void 10365 10366 10367 setcellwidths({list}) *setcellwidths()* 10368 Specify overrides for cell widths of character ranges. This 10369 tells Vim how wide characters are when displayed in the 10370 terminal, counted in screen cells. The values override 10371 'ambiwidth'. Example: > 10372 call setcellwidths([ 10373 \ [0x111, 0x111, 1], 10374 \ [0x2194, 0x2199, 2], 10375 \ ]) 10376 10377 < The {list} argument is a List of Lists with each three 10378 numbers: [{low}, {high}, {width}]. *E1109* *E1110* 10379 {low} and {high} can be the same, in which case this refers to 10380 one character. Otherwise it is the range of characters from 10381 {low} to {high} (inclusive). *E1111* *E1114* 10382 Only characters with value 0x80 and higher can be used. 10383 10384 {width} must be either 1 or 2, indicating the character width 10385 in screen cells. *E1112* 10386 An error is given if the argument is invalid, also when a 10387 range overlaps with another. *E1113* 10388 10389 If the new value causes 'fillchars' or 'listchars' to become 10390 invalid it is rejected and an error is given. 10391 10392 To clear the overrides pass an empty {list}: > 10393 setcellwidths([]); 10394 10395 < You can use the script $VIMRUNTIME/tools/emoji_list.vim to see 10396 the effect for known emoji characters. Move the cursor 10397 through the text to check if the cell widths of your terminal 10398 match with what Vim knows about each emoji. If it doesn't 10399 look right you need to adjust the {list} argument. 10400 10401 |getcellwidths()| can be used to get the overrides later. 10402 10403 Return type: void 10404 10405 10406 setcharpos({expr}, {list}) *setcharpos()* 10407 Same as |setpos()| but uses the specified column number as the 10408 character index instead of the byte index in the line. 10409 10410 Example: 10411 With the text "여보세요" in line 8: > 10412 call setcharpos('.', [0, 8, 4, 0]) 10413 < positions the cursor on the fourth character '요'. > 10414 call setpos('.', [0, 8, 4, 0]) 10415 < positions the cursor on the second character '보'. 10416 10417 Can also be used as a |method|: > 10418 GetPosition()->setcharpos('.') 10419 < 10420 Return type: |Number| 10421 10422 10423 setcharsearch({dict}) *setcharsearch()* 10424 Set the current character search information to {dict}, 10425 which contains one or more of the following entries: 10426 10427 char character which will be used for a subsequent 10428 |,| or |;| command; an empty string clears the 10429 character search 10430 forward direction of character search; 1 for forward, 10431 0 for backward 10432 until type of character search; 1 for a |t| or |T| 10433 character search, 0 for an |f| or |F| 10434 character search 10435 10436 This can be useful to save/restore a user's character search 10437 from a script: > 10438 :let prevsearch = getcharsearch() 10439 :" Perform a command which clobbers user's search 10440 :call setcharsearch(prevsearch) 10441 < Also see |getcharsearch()|. 10442 10443 Can also be used as a |method|: > 10444 SavedSearch()->setcharsearch() 10445 < 10446 Return type: void 10447 10448 10449 setcmdline({str} [, {pos}]) *setcmdline()* 10450 Set the command line to {str} and set the cursor position to 10451 {pos}. 10452 If {pos} is omitted, the cursor is positioned after the text. 10453 Returns 0 when successful, 1 when not editing the command 10454 line. 10455 10456 Can also be used as a |method|: > 10457 GetText()->setcmdline() 10458 < 10459 Return type: |Number| 10460 10461 10462 setcmdpos({pos}) *setcmdpos()* 10463 Set the cursor position in the command line to byte position 10464 {pos}. The first position is 1. 10465 Use |getcmdpos()| to obtain the current position. 10466 Only works while editing the command line, thus you must use 10467 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For 10468 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is 10469 set after the command line is set to the expression. For 10470 |c_CTRL-R_=| it is set after evaluating the expression but 10471 before inserting the resulting text. 10472 When the number is too big the cursor is put at the end of the 10473 line. A number smaller than one has undefined results. 10474 Returns 0 when successful, 1 when not editing the command 10475 line. 10476 10477 Can also be used as a |method|: > 10478 GetPos()->setcmdpos() 10479 < 10480 Return type: |Number| 10481 10482 10483 setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()* 10484 setcursorcharpos({list}) 10485 Same as |cursor()| but uses the specified column number as the 10486 character index instead of the byte index in the line. 10487 10488 Example: 10489 With the text "여보세요" in line 4: > 10490 call setcursorcharpos(4, 3) 10491 < positions the cursor on the third character '세'. > 10492 call cursor(4, 3) 10493 < positions the cursor on the first character '여'. 10494 10495 Can also be used as a |method|: > 10496 GetCursorPos()->setcursorcharpos() 10497 < 10498 Returns 0 when the position could be set, -1 otherwise. 10499 Return type: |Number| 10500 10501 10502 setenv({name}, {val}) *setenv()* 10503 Set environment variable {name} to {val}. Example: > 10504 call setenv('HOME', '/home/myhome') 10505 10506 < When {val} is |v:null| the environment variable is deleted. 10507 See also |expr-env|. 10508 10509 Can also be used as a |method|, the base is passed as the 10510 second argument: > 10511 GetPath()->setenv('PATH') 10512 < 10513 Return type: void 10514 10515 10516 setfperm({fname}, {mode}) *setfperm()* *chmod* 10517 Set the file permissions for {fname} to {mode}. 10518 {mode} must be a string with 9 characters. It is of the form 10519 "rwxrwxrwx", where each group of "rwx" flags represent, in 10520 turn, the permissions of the owner of the file, the group the 10521 file belongs to, and other users. A '-' character means the 10522 permission is off, any other character means on. Multi-byte 10523 characters are not supported. 10524 10525 For example "rw-r-----" means read-write for the user, 10526 readable by the group, not accessible by others. "xx-x-----" 10527 would do the same thing. 10528 10529 Returns non-zero for success, zero for failure. 10530 10531 Can also be used as a |method|: > 10532 GetFilename()->setfperm(mode) 10533 < 10534 To read permissions see |getfperm()|. 10535 10536 Return type: |Number| 10537 10538 10539 setline({lnum}, {text}) *setline()* 10540 Set line {lnum} of the current buffer to {text}. To insert 10541 lines use |append()|. To set lines in another buffer use 10542 |setbufline()|. 10543 Any text properties in {lnum} are cleared. See 10544 |text-prop-cleared| 10545 10546 {lnum} is used like with |getline()|. 10547 When {lnum} is just below the last line the {text} will be 10548 added below the last line. 10549 {text} can be any type or a List of any type, each item is 10550 converted to a String. When {text} is an empty List then 10551 nothing is changed and FALSE is returned. 10552 10553 If this succeeds, FALSE is returned. If this fails (most 10554 likely because {lnum} is invalid) TRUE is returned. 10555 In |Vim9| script an error is given if {lnum} is invalid. 10556 10557 Example: > 10558 :call setline(5, strftime("%c")) 10559 10560 < When {text} is a |List| then line {lnum} and following lines 10561 will be set to the items in the list. Example: > 10562 :call setline(5, ['aaa', 'bbb', 'ccc']) 10563 < This is equivalent to: > 10564 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']] 10565 : call setline(n, l) 10566 :endfor 10567 10568 < Note: The '[ and '] marks are not set. 10569 10570 Can also be used as a |method|, the base is passed as the 10571 second argument: > 10572 GetText()->setline(lnum) 10573 < 10574 Return type: |Number| 10575 10576 10577 setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()* 10578 Create or replace or add to the location list for window {nr}. 10579 {nr} can be the window number or the |window-ID|. 10580 When {nr} is zero the current window is used. 10581 10582 For a location list window, the displayed location list is 10583 modified. For an invalid window number {nr}, -1 is returned. 10584 Otherwise, same as |setqflist()|. 10585 Also see |location-list|. 10586 10587 For {action} see |setqflist-action|. 10588 10589 If the optional {what} dictionary argument is supplied, then 10590 only the items listed in {what} are set. Refer to |setqflist()| 10591 for the list of supported keys in {what}. 10592 10593 Can also be used as a |method|, the base is passed as the 10594 second argument: > 10595 GetLoclist()->setloclist(winnr) 10596 < 10597 Return type: |Number| 10598 10599 10600 setmatches({list} [, {win}]) *setmatches()* 10601 Restores a list of matches saved by |getmatches()| for the 10602 current window. Returns 0 if successful, otherwise -1. All 10603 current matches are cleared before the list is restored. See 10604 example for |getmatches()|. 10605 If {win} is specified, use the window with this number or 10606 window ID instead of the current window. 10607 10608 Can also be used as a |method|: > 10609 GetMatches()->setmatches() 10610 < 10611 Return type: |Number| 10612 10613 10614 setpos({expr}, {list}) *setpos()* 10615 Set the position for String {expr}. Possible values: 10616 . the cursor 10617 'x mark x 10618 10619 {list} must be a |List| with four or five numbers: 10620 [bufnum, lnum, col, off] 10621 [bufnum, lnum, col, off, curswant] 10622 10623 "bufnum" is the buffer number. Zero can be used for the 10624 current buffer. When setting an uppercase mark "bufnum" is 10625 used for the mark position. For other marks it specifies the 10626 buffer to set the mark in. You can use the |bufnr()| function 10627 to turn a file name into a buffer number. 10628 For setting the cursor and the ' mark "bufnum" is ignored, 10629 since these are associated with a window, not a buffer. 10630 Does not change the jumplist. 10631 10632 "lnum" and "col" are the position in the buffer. The first 10633 column is 1. Use a zero "lnum" to delete a mark. If "col" is 10634 smaller than 1 then 1 is used. To use the character count 10635 instead of the byte count, use |setcharpos()|. 10636 10637 The "off" number is only used when 'virtualedit' is set. Then 10638 it is the offset in screen columns from the start of the 10639 character. E.g., a position within a <Tab> or after the last 10640 character. 10641 10642 The "curswant" number is only used when setting the cursor 10643 position. It sets the preferred column for when moving the 10644 cursor vertically. When the "curswant" number is missing the 10645 preferred column is not set. When it is present and setting a 10646 mark position it is not used. 10647 10648 Note that for |'<| and |'>| changing the line number may 10649 result in the marks to be effectively swapped, so that |'<| is 10650 always before |'>|. 10651 10652 The visual marks |'<| and |'>| refer to the beginning and end 10653 of the visual selection relative to the cursor position. 10654 Note that this differs from |getpos()|, where they are 10655 relative to the buffer. 10656 10657 Returns 0 when the position could be set, -1 otherwise. 10658 An error message is given if {expr} is invalid. 10659 10660 Also see |setcharpos()|, |getpos()| and |getcurpos()|. 10661 10662 This does not restore the preferred column for moving 10663 vertically; if you set the cursor position with this, |j| and 10664 |k| motions will jump to previous columns! Use |cursor()| to 10665 also set the preferred column. Also see the "curswant" key in 10666 |winrestview()|. 10667 10668 Can also be used as a |method|: > 10669 GetPosition()->setpos('.') 10670 < 10671 Return type: |Number| 10672 10673 10674 setqflist({list} [, {action} [, {what}]]) *setqflist()* 10675 Create or replace or add to the quickfix list. 10676 10677 If the optional {what} dictionary argument is supplied, then 10678 only the items listed in {what} are set. The first {list} 10679 argument is ignored. See below for the supported items in 10680 {what}. 10681 *setqflist-what* 10682 When {what} is not present, the items in {list} are used. 10683 Each item must be a dictionary. Non-dictionary items in 10684 {list} are ignored. Each dictionary item can contain the 10685 following entries: 10686 10687 bufnr buffer number; must be the number of a valid 10688 buffer 10689 filename name of a file; only used when "bufnr" is not 10690 present or it is invalid. 10691 module name of a module; if given it will be used in 10692 quickfix error window instead of the filename. 10693 lnum line number in the file 10694 end_lnum end of lines, if the item spans multiple lines 10695 pattern search pattern used to locate the error 10696 col column number 10697 vcol when non-zero: "col" is visual column 10698 when zero: "col" is byte index 10699 end_col end column, if the item spans multiple columns 10700 nr error number 10701 text description of the error 10702 type single-character error type, 'E', 'W', etc. 10703 valid recognized error message 10704 user_data custom data associated with the item, can be 10705 any type. 10706 10707 The "col", "vcol", "nr", "type" and "text" entries are 10708 optional. Either "lnum" or "pattern" entry can be used to 10709 locate a matching error line. 10710 If the "filename" and "bufnr" entries are not present or 10711 neither the "lnum" or "pattern" entries are present, then the 10712 item will not be handled as an error line. 10713 If both "pattern" and "lnum" are present then "pattern" will 10714 be used. 10715 If the "valid" entry is not supplied, then the valid flag is 10716 set when "bufnr" is a valid buffer or "filename" exists. 10717 If you supply an empty {list}, the quickfix list will be 10718 cleared. 10719 Note that the list is not exactly the same as what 10720 |getqflist()| returns. 10721 10722 {action} values: *setqflist-action* *E927* 10723 'a' The items from {list} are added to the existing 10724 quickfix list. If there is no existing list, then a 10725 new list is created. 10726 10727 'r' The items from the current quickfix list are replaced 10728 with the items from {list}. This can also be used to 10729 clear the list: > 10730 :call setqflist([], 'r') 10731 < 10732 'u' Like 'r', but tries to preserve the current selection 10733 in the quickfix list. The entry nearest to the 10734 previously selected one becomes the current entry. 10735 Proximity is determined by comparing the file, then 10736 the line number and then the column number. 10737 'f' All the quickfix lists in the quickfix stack are 10738 freed. 10739 10740 If {action} is not present or is set to ' ', then a new list 10741 is created. The new quickfix list is added after the current 10742 quickfix list in the stack and all the following lists are 10743 freed. To add a new quickfix list at the end of the stack, 10744 set "nr" in {what} to "$". 10745 10746 The following items can be specified in dictionary {what}: 10747 context quickfix list context. See |quickfix-context| 10748 efm errorformat to use when parsing text from 10749 "lines". If this is not present, then the 10750 'errorformat' option value is used. 10751 See |quickfix-parse| 10752 id quickfix list identifier |quickfix-ID| 10753 idx index of the current entry in the quickfix 10754 list specified by 'id' or 'nr'. If set to 10755 '$', then the last entry in the list is set as 10756 the current entry. See |quickfix-index| 10757 items list of quickfix entries. Same as the {list} 10758 argument. 10759 lines use 'errorformat' to parse a list of lines and 10760 add the resulting entries to the quickfix list 10761 {nr} or {id}. Only a |List| value is supported. 10762 See |quickfix-parse| 10763 nr list number in the quickfix stack; zero 10764 means the current quickfix list and "$" means 10765 the last quickfix list. 10766 quickfixtextfunc 10767 function to get the text to display in the 10768 quickfix window. The value can be the name of 10769 a function or a funcref or a lambda. Refer to 10770 |quickfix-window-function| for an explanation 10771 of how to write the function and an example. 10772 title quickfix list title text. See |quickfix-title| 10773 Unsupported keys in {what} are ignored. 10774 If the "nr" item is not present, then the current quickfix 10775 list is modified. When creating a new quickfix list, "nr" can 10776 be set to a value one greater than the quickfix stack size. 10777 When modifying a quickfix list, to guarantee that the correct 10778 list is modified, "id" should be used instead of "nr" to 10779 specify the list. 10780 10781 Examples (See also |setqflist-examples|): > 10782 :call setqflist([], 'r', {'title': 'My search'}) 10783 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'}) 10784 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]}) 10785 < 10786 Returns zero for success, -1 for failure. 10787 10788 This function can be used to create a quickfix list 10789 independent of the 'errorformat' setting. Use a command like 10790 `:cc 1` to jump to the first position. 10791 10792 Can also be used as a |method|, the base is passed as the 10793 second argument: > 10794 GetErrorlist()->setqflist() 10795 < 10796 Return type: |Number| 10797 10798 10799 setreg({regname}, {value} [, {options}]) *setreg()* 10800 Set the register {regname} to {value}. 10801 If {regname} is "" or "@", the unnamed register '"' is used. 10802 The {regname} argument is a string. In |Vim9-script| 10803 {regname} must be one character. 10804 10805 {value} may be any value returned by |getreg()| or 10806 |getreginfo()|, including a |List| or |Dict|. 10807 If {options} contains "a" or {regname} is upper case, 10808 then the value is appended. 10809 10810 {options} can also contain a register type specification: 10811 "c" or "v" |characterwise| mode 10812 "l" or "V" |linewise| mode 10813 "b" or "<CTRL-V>" |blockwise-visual| mode 10814 If a number immediately follows "b" or "<CTRL-V>" then this is 10815 used as the width of the selection - if it is not specified 10816 then the width of the block is set to the number of characters 10817 in the longest line (counting a <Tab> as 1 character). 10818 10819 If {options} contains no register settings, then the default 10820 is to use character mode unless {value} ends in a <NL> for 10821 string {value} and linewise mode for list {value}. Blockwise 10822 mode is never selected automatically. 10823 Returns zero for success, non-zero for failure. 10824 10825 *E883* 10826 Note: you may not use |List| containing more than one item to 10827 set search and expression registers. Lists containing 10828 no items act like empty strings. 10829 10830 Examples: > 10831 :call setreg(v:register, @*) 10832 :call setreg('*', @%, 'ac') 10833 :call setreg('a', "1\n2\n3", 'b5') 10834 :call setreg('"', { 'points_to': 'a'}) 10835 10836 < This example shows using the functions to save and restore a 10837 register: > 10838 :let var_a = getreginfo() 10839 :call setreg('a', var_a) 10840 < or: > 10841 :let var_a = getreg('a', 1, 1) 10842 :let var_amode = getregtype('a') 10843 .... 10844 :call setreg('a', var_a, var_amode) 10845 < Note: you may not reliably restore register value 10846 without using the third argument to |getreg()| as without it 10847 newlines are represented as newlines AND Nul bytes are 10848 represented as newlines as well, see |NL-used-for-Nul|. 10849 10850 You can also change the type of a register by appending 10851 nothing: > 10852 :call setreg('a', '', 'al') 10853 10854 < Can also be used as a |method|, the base is passed as the 10855 second argument: > 10856 GetText()->setreg('a') 10857 < 10858 Return type: |Number| 10859 10860 10861 settabvar({tabnr}, {varname}, {val}) *settabvar()* 10862 Set tab-local variable {varname} to {val} in tab page {tabnr}. 10863 |t:var| 10864 The {varname} argument is a string. 10865 Note that autocommands are blocked, side effects may not be 10866 triggered, e.g. when setting 'filetype'. 10867 Note that the variable name without "t:" must be used. 10868 Tabs are numbered starting with one. 10869 This function is not available in the |sandbox|. 10870 10871 Can also be used as a |method|, the base is passed as the 10872 third argument: > 10873 GetValue()->settabvar(tab, name) 10874 < 10875 Return type: void 10876 10877 10878 settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* 10879 Set option or local variable {varname} in window {winnr} to 10880 {val}. 10881 Tabs are numbered starting with one. For the current tabpage 10882 use |setwinvar()|. 10883 {winnr} can be the window number or the |window-ID|. 10884 When {winnr} is zero the current window is used. 10885 Note that autocommands are blocked, side effects may not be 10886 triggered, e.g. when setting 'filetype' or 'syntax'. 10887 This also works for a global or local buffer option, but it 10888 doesn't work for a global or local buffer variable. 10889 For a local buffer option the global value is unchanged. 10890 Note that the variable name without "w:" must be used. 10891 Examples: > 10892 :call settabwinvar(1, 1, "&list", 0) 10893 :call settabwinvar(3, 2, "myvar", "foobar") 10894 < This function is not available in the |sandbox|. 10895 10896 Can also be used as a |method|, the base is passed as the 10897 fourth argument: > 10898 GetValue()->settabwinvar(tab, winnr, name) 10899 < 10900 Return type: void 10901 10902 10903 settagstack({nr}, {dict} [, {action}]) *settagstack()* 10904 Modify the tag stack of the window {nr} using {dict}. 10905 {nr} can be the window number or the |window-ID|. 10906 10907 For a list of supported items in {dict}, refer to 10908 |gettagstack()|. "curidx" takes effect before changing the tag 10909 stack. 10910 *E962* 10911 How the tag stack is modified depends on the {action} 10912 argument: 10913 - If {action} is not present or is set to 'r', then the tag 10914 stack is replaced. 10915 - If {action} is set to 'a', then new entries from {dict} are 10916 pushed (added) onto the tag stack. 10917 - If {action} is set to 't', then all the entries from the 10918 current entry in the tag stack or "curidx" in {dict} are 10919 removed and then new entries are pushed to the stack. 10920 10921 The current index is set to one after the length of the tag 10922 stack after the modification. 10923 10924 Returns zero for success, -1 for failure. 10925 10926 Examples (for more examples see |tagstack-examples|): 10927 Empty the tag stack of window 3: > 10928 call settagstack(3, {'items' : []}) 10929 10930 < Save and restore the tag stack: > 10931 let stack = gettagstack(1003) 10932 " do something else 10933 call settagstack(1003, stack) 10934 unlet stack 10935 < 10936 Can also be used as a |method|, the base is passed as the 10937 second argument: > 10938 GetStack()->settagstack(winnr) 10939 < 10940 Return type: |Number| 10941 10942 10943 setwinvar({winnr}, {varname}, {val}) *setwinvar()* 10944 Like |settabwinvar()| for the current tab page. 10945 Examples: > 10946 :call setwinvar(1, "&list", 0) 10947 :call setwinvar(2, "myvar", "foobar") 10948 10949 < Can also be used as a |method|, the base is passed as the 10950 third argument: > 10951 GetValue()->setwinvar(winnr, name) 10952 < 10953 Return type: void 10954 10955 10956 sha256({expr}) *sha256()* 10957 Returns a String with 64 hex characters, which is the SHA256 10958 checksum of {expr}. 10959 {expr} is a String or a Blob. 10960 10961 Can also be used as a |method|: > 10962 GetText()->sha256() 10963 GetBlob()->sha256() 10964 < 10965 Return type: |String| 10966 10967 {only available when compiled with the |+cryptv| feature} 10968 10969 shellescape({string} [, {special}]) *shellescape()* 10970 Escape {string} for use as a shell command argument. 10971 When the 'shell' contains powershell (MS-Windows) or pwsh 10972 (MS-Windows, Linux, and macOS) then it will enclose {string} 10973 in single quotes and will double up all internal single 10974 quotes. 10975 On MS-Windows, when 'shellslash' is not set, it will enclose 10976 {string} in double quotes and double all double quotes within 10977 {string}. 10978 Otherwise it will enclose {string} in single quotes and 10979 replace all "'" with "'\''". 10980 10981 The {special} argument adds additional escaping of keywords 10982 used in Vim commands. When it is not omitted and a non-zero 10983 number or a non-empty String (|non-zero-arg|), then special 10984 items such as "!", "%", "#" and "<cword>" (as listed in 10985 |expand()|) will be preceded by a backslash. 10986 This backslash will be removed again by the |:!| command. 10987 10988 The "!" character will be escaped (again with a |non-zero-arg| 10989 {special}) when 'shell' contains "csh" in the tail. That is 10990 because for csh and tcsh "!" is used for history replacement 10991 even when inside single quotes. 10992 10993 With a |non-zero-arg| {special} the <NL> character is also 10994 escaped. When 'shell' containing "csh" in the tail it's 10995 escaped a second time. 10996 10997 The "\" character will be escaped when 'shell' contains "fish" 10998 in the tail. That is because for fish "\" is used as an 10999 escape character inside single quotes. 11000 11001 Example of use with a |:!| command: > 11002 :exe '!dir ' .. shellescape(expand('<cfile>'), 1) 11003 < This results in a directory listing for the file under the 11004 cursor. Example of use with |system()|: > 11005 :call system("chmod +w -- " .. shellescape(expand("%"))) 11006 < See also |::S|. 11007 11008 Can also be used as a |method|: > 11009 GetCommand()->shellescape() 11010 < 11011 Return type: |String| 11012 11013 11014 shiftwidth([{col}]) *shiftwidth()* 11015 Returns the effective value of 'shiftwidth'. This is the 11016 'shiftwidth' value unless it is zero, in which case it is the 11017 'tabstop' value. This function was introduced with patch 11018 7.3.694 in 2012, everybody should have it by now (however it 11019 did not allow for the optional {col} argument until 8.1.542). 11020 11021 When there is one argument {col} this is used as column number 11022 for which to return the 'shiftwidth' value. This matters for 11023 the 'vartabstop' feature. If the 'vartabstop' setting is 11024 enabled and no {col} argument is given, column 1 will be 11025 assumed. 11026 11027 Can also be used as a |method|: > 11028 GetColumn()->shiftwidth() 11029 < 11030 Return type: |Number| 11031 11032 sign_ functions are documented here: |sign-functions-details| 11033 11034 11035 simplify({filename}) *simplify()* 11036 Simplify the file name as much as possible without changing 11037 the meaning. Shortcuts (on MS-Windows) or symbolic links (on 11038 Unix) are not resolved. If the first path component in 11039 {filename} designates the current directory, this will be 11040 valid for the result as well. A trailing path separator is 11041 not removed either. On Unix "//path" is unchanged, but 11042 "///path" is simplified to "/path" (this follows the Posix 11043 standard). 11044 Example: > 11045 simplify("./dir/.././/file/") == "./file/" 11046 < Note: The combination "dir/.." is only removed if "dir" is 11047 a searchable directory or does not exist. On Unix, it is also 11048 removed when "dir" is a symbolic link within the same 11049 directory. In order to resolve all the involved symbolic 11050 links before simplifying the path name, use |resolve()|. 11051 11052 Can also be used as a |method|: > 11053 GetName()->simplify() 11054 < 11055 Return type: |String| 11056 11057 11058 sin({expr}) *sin()* 11059 Return the sine of {expr}, measured in radians, as a |Float|. 11060 {expr} must evaluate to a |Float| or a |Number|. 11061 Returns 0.0 if {expr} is not a |Float| or a |Number|. 11062 Examples: > 11063 :echo sin(100) 11064 < -0.506366 > 11065 :echo sin(-4.01) 11066 < 0.763301 11067 11068 Can also be used as a |method|: > 11069 Compute()->sin() 11070 < 11071 Return type: |Float| 11072 11073 11074 sinh({expr}) *sinh()* 11075 Return the hyperbolic sine of {expr} as a |Float| in the range 11076 [-inf, inf]. 11077 {expr} must evaluate to a |Float| or a |Number|. 11078 Returns 0.0 if {expr} is not a |Float| or a |Number|. 11079 Examples: > 11080 :echo sinh(0.5) 11081 < 0.521095 > 11082 :echo sinh(-0.9) 11083 < -1.026517 11084 11085 Can also be used as a |method|: > 11086 Compute()->sinh() 11087 < 11088 Return type: |Float| 11089 11090 11091 slice({expr}, {start} [, {end}]) *slice()* 11092 Similar to using a |slice| "expr[start : end]", but "end" is 11093 used exclusive. And for a string the indexes are used as 11094 character indexes instead of byte indexes, like in 11095 |vim9script|. Also, composing characters are treated as a 11096 part of the preceding base character. 11097 When {end} is omitted the slice continues to the last item. 11098 When {end} is -1 the last item is omitted. 11099 Returns an empty value if {start} or {end} are invalid. 11100 11101 Can also be used as a |method|: > 11102 GetList()->slice(offset) 11103 < 11104 Return type: |String|, list<{type}>, blob or tuple<{type}> 11105 11106 11107 sort({list} [, {how} [, {dict}]]) *sort()* *E702* 11108 Sort the items in {list} in-place. Returns {list}. 11109 11110 If you want a list to remain unmodified make a copy first: > 11111 :let sortedlist = sort(copy(mylist)) 11112 11113 < When {how} is omitted or is a string, then sort() uses the 11114 string representation of each item to sort on. Numbers sort 11115 after Strings, |Lists| after Numbers. For sorting text in the 11116 current buffer use |:sort|. 11117 11118 When {how} is given and it is 'i' then case is ignored. 11119 In legacy script, for backwards compatibility, the value one 11120 can be used to ignore case. Zero means to not ignore case. 11121 11122 When {how} is given and it is 'l' then the current collation 11123 locale is used for ordering. Implementation details: 11124 strcoll() is used to compare strings. See |:language| to check 11125 or set the collation locale. |v:collate| can also be used to 11126 check the current locale. Sorting using the locale typically 11127 ignores case. Example: > 11128 " ö is sorted similarly to o with English locale. 11129 :language collate en_US.UTF8 11130 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') 11131 < ['n', 'o', 'O', 'ö', 'p', 'z'] ~ 11132 > 11133 " ö is sorted after z with Swedish locale. 11134 :language collate sv_SE.UTF8 11135 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') 11136 < ['n', 'o', 'O', 'p', 'z', 'ö'] ~ 11137 This does not work properly on Mac. 11138 11139 When {how} is given and it is 'n' then all items will be 11140 sorted numerical (Implementation detail: this uses the 11141 strtod() function to parse numbers. Strings, Lists, Dicts and 11142 Funcrefs will be considered as being 0). Note that this won't 11143 sort a list of strings with numbers! 11144 11145 When {how} is given and it is 'N' then all items will be 11146 sorted numerical. This is like 'n' but a string containing 11147 digits will be used as the number they represent. 11148 11149 When {how} is given and it is 'f' then all items will be 11150 sorted numerical. All values must be a Number or a Float. 11151 11152 When {how} is a |Funcref| or a function name, this function 11153 is called to compare items. The function is invoked with two 11154 items as argument and must return zero if they are equal, 1 or 11155 bigger if the first one sorts after the second one, -1 or 11156 smaller if the first one sorts before the second one. 11157 11158 {dict} is for functions with the "dict" attribute. It will be 11159 used to set the local variable "self". |Dictionary-function| 11160 11161 The sort is stable, items which compare equal (as number or as 11162 string) will keep their relative position. E.g., when sorting 11163 on numbers, text strings will sort next to each other, in the 11164 same order as they were originally. 11165 11166 Can also be used as a |method|: > 11167 mylist->sort() 11168 11169 < Also see |uniq()|. 11170 11171 Example: > 11172 func MyCompare(i1, i2) 11173 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1 11174 endfunc 11175 eval mylist->sort("MyCompare") 11176 < A shorter compare version for this specific simple case, which 11177 ignores overflow: > 11178 func MyCompare(i1, i2) 11179 return a:i1 - a:i2 11180 endfunc 11181 < For a simple expression you can use a lambda: > 11182 eval mylist->sort({i1, i2 -> i1 - i2}) 11183 < 11184 Return type: list<{type}> 11185 11186 11187 sound_clear() *sound_clear()* 11188 Stop playing all sounds. 11189 11190 On some Linux systems you may need the libcanberra-pulse 11191 package, otherwise sound may not stop. 11192 11193 Return type: void 11194 11195 {only available when compiled with the |+sound| feature} 11196 11197 11198 sound_playevent({name} [, {callback}]) *sound_playevent()* 11199 Play a sound identified by {name}. Which event names are 11200 supported depends on the system. Often the XDG sound names 11201 are used. On Ubuntu they may be found in 11202 /usr/share/sounds/freedesktop/stereo. Example: > 11203 call sound_playevent('bell') 11204 < On MS-Windows, {name} can be SystemAsterisk, SystemDefault, 11205 SystemExclamation, SystemExit, SystemHand, SystemQuestion, 11206 SystemStart, SystemWelcome, etc. 11207 On macOS, {name} refers to files located in 11208 /System/Library/Sounds (e.g. "Tink"). It will also work for 11209 custom installed sounds in folders like ~/Library/Sounds. 11210 11211 When {callback} is specified it is invoked when the sound is 11212 finished. The first argument is the sound ID, the second 11213 argument is the status: 11214 0 sound was played to the end 11215 1 sound was interrupted 11216 2 error occurred after sound started 11217 Example: > 11218 func Callback(id, status) 11219 echomsg "sound " .. a:id .. " finished with " .. a:status 11220 endfunc 11221 call sound_playevent('bell', 'Callback') 11222 11223 < MS-Windows: {callback} doesn't work for this function. 11224 11225 Returns the sound ID, which can be passed to `sound_stop()`. 11226 Returns zero if the sound could not be played. 11227 11228 Can also be used as a |method|: > 11229 GetSoundName()->sound_playevent() 11230 < 11231 Return type: |Number| 11232 11233 {only available when compiled with the |+sound| feature} 11234 11235 11236 sound_playfile({path} [, {callback}]) *sound_playfile()* 11237 Like `sound_playevent()` but play sound file {path}. {path} 11238 must be a full path. On Ubuntu you may find files to play 11239 with this command: > 11240 :!find /usr/share/sounds -type f | grep -v index.theme 11241 11242 < Can also be used as a |method|: > 11243 GetSoundPath()->sound_playfile() 11244 < 11245 Return type: |Number| 11246 11247 {only available when compiled with the |+sound| feature} 11248 11249 11250 sound_stop({id}) *sound_stop()* 11251 Stop playing sound {id}. {id} must be previously returned by 11252 `sound_playevent()` or `sound_playfile()`. 11253 11254 On some Linux systems you may need the libcanberra-pulse 11255 package, otherwise sound may not stop. 11256 11257 On MS-Windows, this does not work for event sound started by 11258 `sound_playevent()`. To stop event sounds, use `sound_clear()`. 11259 11260 Can also be used as a |method|: > 11261 soundid->sound_stop() 11262 < 11263 Return type: void 11264 11265 {only available when compiled with the |+sound| feature} 11266 11267 11268 soundfold({word}) *soundfold()* 11269 Return the sound-folded equivalent of {word}. Uses the first 11270 language in 'spelllang' for the current window that supports 11271 soundfolding. 'spell' must be set. When no sound folding is 11272 possible the {word} is returned unmodified. 11273 This can be used for making spelling suggestions. Note that 11274 the method can be quite slow. 11275 11276 Can also be used as a |method|: > 11277 GetWord()->soundfold() 11278 < 11279 Return type: |String| 11280 11281 11282 spellbadword([{sentence}]) *spellbadword()* 11283 Without argument: The result is the badly spelled word under 11284 or after the cursor. The cursor is moved to the start of the 11285 bad word. When no bad word is found in the cursor line the 11286 result is an empty string and the cursor doesn't move. 11287 11288 With argument: The result is the first word in {sentence} that 11289 is badly spelled. If there are no spelling mistakes the 11290 result is an empty string. 11291 11292 The return value is a list with two items: 11293 - The badly spelled word or an empty string. 11294 - The type of the spelling error: 11295 "bad" spelling mistake 11296 "rare" rare word 11297 "local" word only valid in another region 11298 "caps" word should start with Capital 11299 Example: > 11300 echo spellbadword("the quik brown fox") 11301 < ['quik', 'bad'] ~ 11302 11303 The spelling information for the current window and the value 11304 of 'spelllang' are used. 11305 11306 Can also be used as a |method|: > 11307 GetText()->spellbadword() 11308 < 11309 Return type: list<string> 11310 11311 11312 spellsuggest({word} [, {max} [, {capital}]]) *spellsuggest()* 11313 Return a |List| with spelling suggestions to replace {word}. 11314 When {max} is given up to this number of suggestions are 11315 returned. Otherwise up to 25 suggestions are returned. 11316 11317 When the {capital} argument is given and it's non-zero only 11318 suggestions with a leading capital will be given. Use this 11319 after a match with 'spellcapcheck'. 11320 11321 {word} can be a badly spelled word followed by other text. 11322 This allows for joining two words that were split. The 11323 suggestions also include the following text, thus you can 11324 replace a line. 11325 11326 {word} may also be a good word. Similar words will then be 11327 returned. {word} itself is not included in the suggestions, 11328 although it may appear capitalized. 11329 11330 The spelling information for the current window is used. The 11331 values of 'spelllang' and 'spellsuggest' are used. 11332 11333 Can also be used as a |method|: > 11334 GetWord()->spellsuggest() 11335 < 11336 Return type: list<string> or list<any> 11337 11338 11339 split({string} [, {pattern} [, {keepempty}]]) *split()* 11340 Make a |List| out of {string}. When {pattern} is omitted or 11341 empty each white space separated sequence of characters 11342 becomes an item. 11343 Otherwise the string is split where {pattern} matches, 11344 removing the matched characters. 'ignorecase' is not used 11345 here, add \c to ignore case. |/\c| 11346 When the first or last item is empty it is omitted, unless the 11347 {keepempty} argument is given and it's non-zero. 11348 Other empty items are kept when {pattern} matches at least one 11349 character or when {keepempty} is non-zero. 11350 Example: > 11351 :let words = split(getline('.'), '\W\+') 11352 < To split a string in individual characters: > 11353 :for c in split(mystring, '\zs') 11354 < If you want to keep the separator you can also use '\zs' at 11355 the end of the pattern: > 11356 :echo split('abc:def:ghi', ':\zs') 11357 < ['abc:', 'def:', 'ghi'] ~ 11358 Splitting a table where the first element can be empty: > 11359 :let items = split(line, ':', 1) 11360 < The opposite function is |join()|. 11361 11362 Can also be used as a |method|: > 11363 GetString()->split() 11364 < 11365 Return type: list<string> 11366 11367 11368 sqrt({expr}) *sqrt()* 11369 Return the non-negative square root of Float {expr} as a 11370 |Float|. 11371 {expr} must evaluate to a |Float| or a |Number|. When {expr} 11372 is negative the result is NaN (Not a Number). Returns 0.0 if 11373 {expr} is not a |Float| or a |Number|. 11374 Examples: > 11375 :echo sqrt(100) 11376 < 10.0 > 11377 :echo sqrt(-4.01) 11378 < nan 11379 "nan" may be different, it depends on system libraries. 11380 11381 Can also be used as a |method|: > 11382 Compute()->sqrt() 11383 < 11384 Return type: |Float| 11385 11386 11387 srand([{expr}]) *srand()* 11388 Initialize seed used by |rand()|: 11389 - If {expr} is not given, seed values are initialized by 11390 reading from /dev/urandom, if possible, or using time(NULL) 11391 a.k.a. epoch time otherwise; this only has second accuracy. 11392 - If {expr} is given it must be a Number. It is used to 11393 initialize the seed values. This is useful for testing or 11394 when a predictable sequence is intended. 11395 11396 Examples: > 11397 :let seed = srand() 11398 :let seed = srand(userinput) 11399 :echo rand(seed) 11400 < 11401 Return type: list<number> 11402 11403 11404 state([{what}]) *state()* 11405 Return a string which contains characters indicating the 11406 current state. Mostly useful in callbacks that want to do 11407 work that may not always be safe. Roughly this works like: 11408 - callback uses state() to check if work is safe to do. 11409 Yes: then do it right away. 11410 No: add to work queue and add a |SafeState| and/or 11411 |SafeStateAgain| autocommand (|SafeState| triggers at 11412 toplevel, |SafeStateAgain| triggers after handling 11413 messages and callbacks). 11414 - When SafeState or SafeStateAgain is triggered and executes 11415 your autocommand, check with `state()` if the work can be 11416 done now, and if yes remove it from the queue and execute. 11417 Remove the autocommand if the queue is now empty. 11418 Also see |mode()|. 11419 11420 When {what} is given only characters in this string will be 11421 added. E.g, this checks if the screen has scrolled: > 11422 if state('s') == '' 11423 " screen has not scrolled 11424 < 11425 These characters indicate the state, generally indicating that 11426 something is busy: 11427 m halfway a mapping, :normal command, |feedkeys()| or 11428 stuffed command 11429 o operator pending, e.g. after |d| 11430 a Insert mode autocomplete active 11431 x executing an autocommand 11432 w blocked on waiting, e.g. |ch_evalexpr()|, |ch_read()| and 11433 |ch_readraw()| when reading json 11434 S not triggering SafeState or SafeStateAgain, e.g. after 11435 |f| or a count 11436 c callback invoked, including timer (repeats for 11437 recursiveness up to "ccc") 11438 s screen has scrolled for messages 11439 11440 Return type: |String| 11441 11442 11443 str2blob({list} [, {options}]) *str2blob()* 11444 Return a Blob by converting the characters in the List of 11445 strings in {list} into bytes. 11446 11447 A <NL> byte is added to the blob after each list item. A 11448 newline character in the string is translated into a <NUL> 11449 byte in the blob. 11450 11451 If {options} is not supplied, the current 'encoding' value is 11452 used to convert the characters into bytes. 11453 11454 The argument {options} is a |Dict| and supports the following 11455 items: 11456 encoding Convert the characters using this encoding 11457 before making the Blob. 11458 The value is a |String|. See |encoding-names| 11459 for the supported values. 11460 11461 An error is given and an empty blob is returned if the 11462 character encoding fails. 11463 11464 Returns an empty Blob if {list} is empty. 11465 11466 See also |blob2str()| 11467 11468 Examples: > 11469 str2blob(["ab"]) returns 0z6162 11470 str2blob(["«»"]) returns 0zC2ABC2BB 11471 str2blob(["a\nb"]) returns 0z610062 11472 str2blob(["a","b"]) returns 0z610A62 11473 str2blob(["«»"], {'encoding': 'latin1'}) returns 0zABBB 11474 str2blob(readfile('myfile.txt')) 11475 < 11476 Can also be used as a |method|: > 11477 GetListOfStrings()->str2blob() 11478 < 11479 Return type: |Blob| 11480 11481 11482 str2float({string} [, {quoted}]) *str2float()* 11483 Convert String {string} to a Float. This mostly works the 11484 same as when using a floating point number in an expression, 11485 see |floating-point-format|. But it's a bit more permissive. 11486 E.g., "1e40" is accepted, while in an expression you need to 11487 write "1.0e40". The hexadecimal form "0x123" is also 11488 accepted, but not others, like binary or octal. 11489 When {quoted} is present and non-zero then embedded single 11490 quotes before the dot are ignored, thus "1'000.0" is a 11491 thousand. 11492 Text after the number is silently ignored. 11493 The decimal point is always '.', no matter what the locale is 11494 set to. A comma ends the number: "12,345.67" is converted to 11495 12.0. You can strip out thousands separators with 11496 |substitute()|: > 11497 let f = str2float(substitute(text, ',', '', 'g')) 11498 < 11499 Returns 0.0 if the conversion fails. 11500 11501 Can also be used as a |method|: > 11502 let f = text->substitute(',', '', 'g')->str2float() 11503 < 11504 Return type: |Float| 11505 11506 11507 str2list({string} [, {utf8}]) *str2list()* 11508 Return a list containing the number values which represent 11509 each character in String {string}. Examples: > 11510 str2list(" ") returns [32] 11511 str2list("ABC") returns [65, 66, 67] 11512 < |list2str()| does the opposite. 11513 11514 When {utf8} is omitted or zero, the current 'encoding' is 11515 used. 11516 When {utf8} is TRUE, always treat the String as UTF-8 11517 characters. With UTF-8 composing characters are handled 11518 properly: > 11519 str2list("á") returns [97, 769] 11520 11521 < Can also be used as a |method|: > 11522 GetString()->str2list() 11523 < 11524 Return type: list<number> 11525 11526 11527 str2nr({string} [, {base} [, {quoted}]]) *str2nr()* 11528 Convert string {string} to a number. 11529 {base} is the conversion base, it can be 2, 8, 10 or 16. 11530 When {quoted} is present and non-zero then embedded single 11531 quotes are ignored, thus "1'000'000" is a million. 11532 11533 When {base} is omitted base 10 is used. This also means that 11534 a leading zero doesn't cause octal conversion to be used, as 11535 with the default String to Number conversion. Example: > 11536 let nr = str2nr('0123') 11537 < 11538 When {base} is 16 a leading "0x" or "0X" is ignored. With a 11539 different base the result will be zero. Similarly, when 11540 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when 11541 {base} is 2 a leading "0b" or "0B" is ignored. 11542 Text after the number is silently ignored. 11543 11544 Returns 0 if {string} is empty or on error. 11545 11546 Can also be used as a |method|: > 11547 GetText()->str2nr() 11548 < 11549 Return type: |Number| 11550 11551 11552 strcharlen({string}) *strcharlen()* 11553 The result is a Number, which is the number of characters 11554 in String {string}. Composing characters are ignored. 11555 |strchars()| can count the number of characters, counting 11556 composing characters separately. 11557 11558 Returns 0 if {string} is empty or on error. 11559 11560 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. 11561 11562 Can also be used as a |method|: > 11563 GetText()->strcharlen() 11564 < 11565 Return type: |Number| 11566 11567 11568 strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()* 11569 Like |strpart()| but using character index and length instead 11570 of byte index and length. 11571 When {skipcc} is omitted or zero, composing characters are 11572 counted separately. 11573 When {skipcc} set to 1, composing characters are treated as a 11574 part of the preceding base character, similar to |slice()|. 11575 When a character index is used where a character does not 11576 exist it is omitted and counted as one character. For 11577 example: > 11578 strcharpart('abc', -1, 2) 11579 < results in 'a'. 11580 11581 Returns an empty string on error. 11582 11583 Can also be used as a |method|: > 11584 GetText()->strcharpart(5) 11585 < 11586 Return type: |String| 11587 11588 11589 strchars({string} [, {skipcc}]) *strchars()* 11590 The result is a Number, which is the number of characters 11591 in String {string}. 11592 When {skipcc} is omitted or zero, composing characters are 11593 counted separately. 11594 When {skipcc} set to 1, composing characters are ignored. 11595 |strcharlen()| always does this. 11596 11597 Returns zero on error. 11598 11599 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. 11600 11601 {skipcc} is only available after 7.4.755. For backward 11602 compatibility, you can define a wrapper function: > 11603 if has("patch-7.4.755") 11604 function s:strchars(str, skipcc) 11605 return strchars(a:str, a:skipcc) 11606 endfunction 11607 else 11608 function s:strchars(str, skipcc) 11609 if a:skipcc 11610 return strlen(substitute(a:str, ".", "x", "g")) 11611 else 11612 return strchars(a:str) 11613 endif 11614 endfunction 11615 endif 11616 < 11617 Can also be used as a |method|: > 11618 GetText()->strchars() 11619 < 11620 Return type: |Number| 11621 11622 11623 strdisplaywidth({string} [, {col}]) *strdisplaywidth()* 11624 The result is a Number, which is the number of display cells 11625 String {string} occupies on the screen when it starts at {col} 11626 (first column is zero). When {col} is omitted zero is used. 11627 Otherwise it is the screen column where to start. This 11628 matters for Tab characters. 11629 The option settings of the current window are used. This 11630 matters for anything that's displayed differently, such as 11631 'tabstop' and 'display'. 11632 When {string} contains characters with East Asian Width Class 11633 Ambiguous, this function's return value depends on 11634 'ambiwidth'. 11635 Returns zero on error. 11636 Also see |strlen()|, |strwidth()| and |strchars()|. 11637 11638 Can also be used as a |method|: > 11639 GetText()->strdisplaywidth() 11640 < 11641 Return type: |Number| 11642 11643 11644 strftime({format} [, {time}]) *strftime()* 11645 The result is a String, which is a formatted date and time, as 11646 specified by the {format} string. The given {time} is used, 11647 or the current time if no time is given. The accepted 11648 {format} depends on your system, thus this is not portable! 11649 See the manual page of the C function strftime() for the 11650 format. The maximum length of the result is 80 characters. 11651 See also |localtime()|, |getftime()| and |strptime()|. 11652 The language can be changed with the |:language| command. 11653 Examples: > 11654 :echo strftime("%c") Sun Apr 27 11:49:23 1997 11655 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25 11656 :echo strftime("%y%m%d %T") 970427 11:53:55 11657 :echo strftime("%H:%M") 11:55 11658 :echo strftime("%c", getftime("file.c")) 11659 Show mod time of file.c. 11660 < Not available on all systems. To check use: > 11661 :if exists("*strftime") 11662 11663 < Can also be used as a |method|: > 11664 GetFormat()->strftime() 11665 < 11666 Return type: |String| 11667 11668 11669 strgetchar({str}, {index}) *strgetchar()* 11670 Get a Number corresponding to the character at {index} in 11671 {str}. This uses a zero-based character index, not a byte 11672 index. Composing characters are considered separate 11673 characters here. Use |nr2char()| to convert the Number to a 11674 String. 11675 Returns -1 if {index} is invalid. 11676 Also see |strcharpart()| and |strchars()|. 11677 11678 Can also be used as a |method|: > 11679 GetText()->strgetchar(5) 11680 < 11681 Return type: |Number| 11682 11683 11684 stridx({haystack}, {needle} [, {start}]) *stridx()* 11685 The result is a Number, which gives the byte index in 11686 {haystack} of the first occurrence of the String {needle}. 11687 If {start} is specified, the search starts at index {start}. 11688 This can be used to find a second match: > 11689 :let colon1 = stridx(line, ":") 11690 :let colon2 = stridx(line, ":", colon1 + 1) 11691 < The search is done case-sensitive. 11692 For pattern searches use |match()|. 11693 -1 is returned if the {needle} does not occur in {haystack}. 11694 See also |strridx()|. 11695 Examples: > 11696 :echo stridx("An Example", "Example") 3 11697 :echo stridx("Starting point", "Start") 0 11698 :echo stridx("Starting point", "start") -1 11699 < *strstr()* *strchr()* 11700 stridx() works similar to the C function strstr(). When used 11701 with a single character it works similar to strchr(). 11702 11703 Can also be used as a |method|: > 11704 GetHaystack()->stridx(needle) 11705 < 11706 Return type: |Number| 11707 11708 11709 string({expr}) *string()* 11710 Return {expr} converted to a String. If {expr} is a Number, 11711 Float, String, Blob or a composition of them, then the result 11712 can be parsed back with |eval()|. 11713 {expr} type result ~ 11714 String 'string' (single quotes are doubled) 11715 Number 123 11716 Float 123.123456 or 1.123456e8 11717 Funcref function('name') 11718 Blob 0z00112233.44556677.8899 11719 List [item, item] 11720 Tuple (item, item) 11721 Dictionary {key: value, key: value} 11722 Class class SomeName 11723 Object object of SomeName {lnum: 1, col: 3} 11724 Enum enum EnumName 11725 EnumValue enum name.value {name: str, ordinal: nr} 11726 11727 When a |List|, |Tuple| or |Dictionary| has a recursive 11728 reference it is replaced by "[...]" or "(...)" or "{...}". 11729 Using |eval()| on the result will then fail. 11730 11731 For an object, invokes the string() method to get a textual 11732 representation of the object. If the method is not present, 11733 then the default representation is used. |object-string()| 11734 11735 Can also be used as a |method|: > 11736 mylist->string() 11737 11738 < Also see |strtrans()|. 11739 11740 Return type: |String| 11741 11742 11743 strlen({string}) *strlen()* 11744 The result is a Number, which is the length of the String 11745 {string} in bytes. 11746 If the argument is a Number it is first converted to a String. 11747 For other types an error is given and zero is returned. 11748 If you want to count the number of multibyte characters use 11749 |strchars()|. 11750 Also see |len()|, |strdisplaywidth()| and |strwidth()|. 11751 11752 Can also be used as a |method|: > 11753 GetString()->strlen() 11754 < 11755 Return type: |Number| 11756 11757 11758 strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* 11759 The result is a String, which is part of {src}, starting from 11760 byte {start}, with the byte length {len}. 11761 When {chars} is present and TRUE then {len} is the number of 11762 characters positions (composing characters are not counted 11763 separately, thus "1" means one base character and any 11764 following composing characters). 11765 To count {start} as characters instead of bytes use 11766 |strcharpart()|. 11767 11768 When bytes are selected which do not exist, this doesn't 11769 result in an error, the bytes are simply omitted. 11770 If {len} is missing, the copy continues from {start} till the 11771 end of the {src}. > 11772 strpart("abcdefg", 3, 2) == "de" 11773 strpart("abcdefg", -2, 4) == "ab" 11774 strpart("abcdefg", 5, 4) == "fg" 11775 strpart("abcdefg", 3) == "defg" 11776 11777 < Note: To get the first character, {start} must be 0. For 11778 example, to get the character under the cursor: > 11779 strpart(getline("."), col(".") - 1, 1, v:true) 11780 < 11781 Returns an empty string on error. 11782 11783 Can also be used as a |method|: > 11784 GetText()->strpart(5) 11785 < 11786 Return type: |String| 11787 11788 11789 strptime({format}, {timestring}) *strptime()* 11790 The result is a Number, which is a unix timestamp representing 11791 the date and time in {timestring}, which is expected to match 11792 the format specified in {format}. 11793 11794 The accepted {format} depends on your system, thus this is not 11795 portable! See the manual page of the C function strptime() 11796 for the format. Especially avoid "%c". The value of $TZ also 11797 matters. 11798 11799 If the {timestring} cannot be parsed with {format} zero is 11800 returned. If you do not know the format of {timestring} you 11801 can try different {format} values until you get a non-zero 11802 result. 11803 11804 Note: On MS-Windows, where the C runtime does not provide 11805 strptime(), Vim uses a built-in fallback that always uses 11806 English locale names regardless of the active locale. 11807 11808 See also |strftime()|. 11809 11810 Examples: > 11811 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23") 11812 < 862156163 > 11813 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55")) 11814 < Sun Apr 27 11:53:55 1997 > 11815 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600) 11816 < Sun Apr 27 12:53:55 1997 11817 11818 Can also be used as a |method|: > 11819 GetFormat()->strptime(timestring) 11820 < 11821 Not available on all systems. To check use: > 11822 :if exists("*strptime") 11823 < 11824 Return type: |Number| 11825 11826 11827 strridx({haystack}, {needle} [, {start}]) *strridx()* 11828 The result is a Number, which gives the byte index in 11829 {haystack} of the last occurrence of the String {needle}. 11830 When {start} is specified, matches beyond this index are 11831 ignored. This can be used to find a match before a previous 11832 match: > 11833 :let lastcomma = strridx(line, ",") 11834 :let comma2 = strridx(line, ",", lastcomma - 1) 11835 < The search is done case-sensitive. 11836 For pattern searches use |match()|. 11837 -1 is returned if the {needle} does not occur in {haystack}. 11838 If the {needle} is empty the length of {haystack} is returned. 11839 See also |stridx()|. Examples: > 11840 :echo strridx("an angry armadillo", "an") 3 11841 < *strrchr()* 11842 When used with a single character it works similar to the C 11843 function strrchr(). 11844 11845 Can also be used as a |method|: > 11846 GetHaystack()->strridx(needle) 11847 < 11848 Return type: |Number| 11849 11850 11851 strtrans({string}) *strtrans()* 11852 The result is a String, which is {string} with all unprintable 11853 characters translated into printable characters 'isprint'. 11854 Like they are shown in a window. Example: > 11855 echo strtrans(@a) 11856 < This displays a newline in register a as "^@" instead of 11857 starting a new line. 11858 11859 Returns an empty string on error. 11860 11861 Can also be used as a |method|: > 11862 GetString()->strtrans() 11863 < 11864 Return type: |String| 11865 11866 11867 strutf16len({string} [, {countcc}]) *strutf16len()* 11868 The result is a Number, which is the number of UTF-16 code 11869 units in String {string} (after converting it to UTF-16). 11870 11871 When {countcc} is TRUE, composing characters are counted 11872 separately. 11873 When {countcc} is omitted or FALSE, composing characters are 11874 ignored. 11875 11876 Returns zero on error. 11877 11878 Also see |strlen()| and |strcharlen()|. 11879 Examples: > 11880 echo strutf16len('a') returns 1 11881 echo strutf16len('©') returns 1 11882 echo strutf16len('😊') returns 2 11883 echo strutf16len('ą́') returns 1 11884 echo strutf16len('ą́', v:true) returns 3 11885 < 11886 Can also be used as a |method|: > 11887 GetText()->strutf16len() 11888 < 11889 Return type: |Number| 11890 11891 11892 strwidth({string}) *strwidth()* 11893 The result is a Number, which is the number of display cells 11894 String {string} occupies. A Tab character is counted as one 11895 cell, alternatively use |strdisplaywidth()|. 11896 When {string} contains characters with East Asian Width Class 11897 Ambiguous, this function's return value depends on 11898 'ambiwidth'. 11899 Returns zero on error. 11900 Also see |strlen()|, |strdisplaywidth()| and |strchars()|. 11901 11902 Can also be used as a |method|: > 11903 GetString()->strwidth() 11904 < 11905 Return type: |Number| 11906 11907 11908 submatch({nr} [, {list}]) *submatch()* *E935* 11909 Only for an expression in a |:substitute| command or 11910 |substitute()| function. 11911 Returns the {nr}'th submatch of the matched text. When {nr} 11912 is 0 the whole matched text is returned. 11913 Note that a NL in the string can stand for a line break of a 11914 multi-line match or a NUL character in the text. 11915 Also see |sub-replace-expression|. 11916 11917 If {list} is present and non-zero then submatch() returns 11918 a list of strings, similar to |getline()| with two arguments. 11919 NL characters in the text represent NUL characters in the 11920 text. 11921 Only returns more than one item for |:substitute|, inside 11922 |substitute()| this list will always contain one or zero 11923 items, since there are no real line breaks. 11924 11925 When |substitute()| is used recursively only the submatches in 11926 the current (deepest) call can be obtained. 11927 11928 Returns an empty string or list on error. 11929 11930 Examples: > 11931 :s/\d\+/\=submatch(0) + 1/ 11932 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '') 11933 < This finds the first number in the line and adds one to it. 11934 A line break is included as a newline character. 11935 11936 Can also be used as a |method|: > 11937 GetNr()->submatch() 11938 < 11939 Return type: |String| or list<string> depending on {list} 11940 11941 11942 substitute({string}, {pat}, {sub}, {flags}) *substitute()* 11943 The result is a String, which is a copy of {string}, in which 11944 the first match of {pat} is replaced with {sub}. 11945 When {flags} is "g", all matches of {pat} in {string} are 11946 replaced. Otherwise {flags} should be "". 11947 11948 This works like the ":substitute" command (without any flags). 11949 But the matching with {pat} is always done like the 'magic' 11950 option is set and 'cpoptions' is empty (to make scripts 11951 portable). 'ignorecase' is still relevant, use |/\c| or |/\C| 11952 if you want to ignore or match case and ignore 'ignorecase'. 11953 'smartcase' is not used. See |string-match| for how {pat} is 11954 used. 11955 11956 A "~" in {sub} is not replaced with the previous {sub}. 11957 Note that some codes in {sub} have a special meaning 11958 |sub-replace-special|. For example, to replace something with 11959 "\n" (two characters), use "\\\\n" or '\\n'. 11960 11961 When {pat} does not match in {string}, {string} is returned 11962 unmodified. 11963 11964 Example: > 11965 :let &path = substitute(&path, ",\\=[^,]*$", "", "") 11966 < This removes the last component of the 'path' option. > 11967 :echo substitute("testing", ".*", "\\U\\0", "") 11968 < results in "TESTING". 11969 11970 When {sub} starts with "\=", the remainder is interpreted as 11971 an expression. See |sub-replace-expression|. Example: > 11972 :echo substitute(s, '%\(\x\x\)', 11973 \ '\=nr2char("0x" .. submatch(1))', 'g') 11974 11975 < When {sub} is a Funcref that function is called, with one 11976 optional argument. Example: > 11977 :echo substitute(s, '%\(\x\x\)', SubNr, 'g') 11978 < The optional argument is a list which contains the whole 11979 matched string and up to nine submatches, like what 11980 |submatch()| returns. Example: > 11981 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g') 11982 11983 < Returns an empty string on error. 11984 11985 Can also be used as a |method|: > 11986 GetString()->substitute(pat, sub, flags) 11987 < 11988 Return type: |String| 11989 11990 11991 swapfilelist() *swapfilelist()* 11992 Returns a list of swap file names, like what "vim -r" shows. 11993 See the |-r| command argument. The 'directory' option is used 11994 for the directories to inspect. If you only want to get a 11995 list of swap files in the current directory then temporarily 11996 set 'directory' to a dot: > 11997 let save_dir = &directory 11998 let &directory = '.' 11999 let swapfiles = swapfilelist() 12000 let &directory = save_dir 12001 < 12002 Return type: list<string> 12003 12004 12005 swapinfo({fname}) *swapinfo()* 12006 The result is a dictionary, which holds information about the 12007 swapfile {fname}. The available fields are: 12008 version Vim version 12009 user user name 12010 host host name 12011 fname original file name 12012 pid PID of the Vim process that created the swap 12013 file 12014 mtime last modification time in seconds 12015 inode Optional: INODE number of the file 12016 dirty 1 if file was modified, 0 if not 12017 Note that "user" and "host" are truncated to at most 39 bytes. 12018 In case of failure an "error" item is added with the reason: 12019 Cannot open file: file not found or in accessible 12020 Cannot read file: cannot read first block 12021 Not a swap file: does not contain correct block ID 12022 Magic number mismatch: Info in first block is invalid 12023 12024 Can also be used as a |method|: > 12025 GetFilename()->swapinfo() 12026 < 12027 Return type: dict<any> or dict<string> 12028 12029 12030 swapname({buf}) *swapname()* 12031 The result is the swap file path of the buffer {expr}. 12032 For the use of {buf}, see |bufname()| above. 12033 If buffer {buf} is the current buffer, the result is equal to 12034 |:swapname| (unless there is no swap file). 12035 If buffer {buf} has no swap file, returns an empty string. 12036 12037 Can also be used as a |method|: > 12038 GetBufname()->swapname() 12039 < 12040 Return type: |String| 12041 12042 12043 synID({lnum}, {col}, {trans}) *synID()* 12044 The result is a Number, which is the syntax ID at the position 12045 {lnum} and {col} in the current window. 12046 The syntax ID can be used with |synIDattr()| and 12047 |synIDtrans()| to obtain syntax information about text. 12048 12049 {col} is 1 for the leftmost column, {lnum} is 1 for the first 12050 line. 'synmaxcol' applies, in a longer line zero is returned. 12051 Note that when the position is after the last character, 12052 that's where the cursor can be in Insert mode, synID() returns 12053 zero. {lnum} is used like with |getline()|. 12054 12055 When {trans} is |TRUE|, transparent items are reduced to the 12056 item that they reveal. This is useful when wanting to know 12057 the effective color. When {trans} is |FALSE|, the transparent 12058 item is returned. This is useful when wanting to know which 12059 syntax item is effective (e.g. inside parens). 12060 Warning: This function can be very slow. Best speed is 12061 obtained by going through the file in forward direction. 12062 12063 Returns zero on error. 12064 12065 Example (echoes the name of the syntax item under the cursor): > 12066 :echo synIDattr(synID(line("."), col("."), 1), "name") 12067 < 12068 Return type: |Number| 12069 12070 12071 synIDattr({synID}, {what} [, {mode}]) *synIDattr()* 12072 The result is a String, which is the {what} attribute of 12073 syntax ID {synID}. This can be used to obtain information 12074 about a syntax item. 12075 {mode} can be "gui", "cterm" or "term", to get the attributes 12076 for that mode. When {mode} is omitted, or an invalid value is 12077 used, the attributes for the currently active highlighting are 12078 used (GUI, cterm or term). 12079 Use |synIDtrans()| to follow linked highlight groups. 12080 {what} result 12081 "name" the name of the syntax item 12082 "fg" foreground color (GUI: color name used to set 12083 the color, cterm: color number as a string, 12084 term: empty string) 12085 "bg" background color (as with "fg") 12086 "font" font name (only available in the GUI) 12087 |highlight-font| 12088 "sp" special color for the GUI (as with "fg") 12089 |highlight-guisp| 12090 "ul" underline color for cterm: number as a string 12091 "fg#" like "fg", but for the GUI and the GUI is 12092 running the name in "#RRGGBB" form 12093 "bg#" like "fg#" for "bg" 12094 "sp#" like "fg#" for "sp" 12095 "bold" "1" if bold 12096 "italic" "1" if italic 12097 "reverse" "1" if reverse 12098 "inverse" "1" if inverse (= reverse) 12099 "standout" "1" if standout 12100 "underline" "1" if underlined 12101 "undercurl" "1" if undercurled 12102 "strike" "1" if strikethrough 12103 "nocombine" "1" if nocombine 12104 12105 Returns an empty string on error. 12106 12107 Example (echoes the color of the syntax item under the 12108 cursor): > 12109 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg") 12110 < 12111 Can also be used as a |method|: > 12112 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") 12113 < 12114 Return type: |String| 12115 12116 12117 synIDtrans({synID}) *synIDtrans()* 12118 The result is a Number, which is the translated syntax ID of 12119 {synID}. This is the syntax group ID of what is being used to 12120 highlight the character. Highlight links given with 12121 ":highlight link" are followed. 12122 12123 Returns zero on error. 12124 12125 Can also be used as a |method|: > 12126 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") 12127 < 12128 Return type: |Number| 12129 12130 12131 synconcealed({lnum}, {col}) *synconcealed()* 12132 The result is a |List| with three items: 12133 1. The first item in the list is 0 if the character at the 12134 position {lnum} and {col} is not part of a concealable 12135 region, 1 if it is. {lnum} is used like with |getline()|. 12136 2. The second item in the list is a string. If the first item 12137 is 1, the second item contains the text which will be 12138 displayed in place of the concealed text, depending on the 12139 current setting of 'conceallevel' and 'listchars'. 12140 3. The third and final item in the list is a number 12141 representing the specific syntax region matched in the 12142 line. When the character is not concealed the value is 12143 zero. This allows detection of the beginning of a new 12144 concealable region if there are two consecutive regions 12145 with the same replacement character. For an example, if 12146 the text is "123456" and both "23" and "45" are concealed 12147 and replaced by the character "X", then: 12148 call returns ~ 12149 synconcealed(lnum, 1) [0, '', 0] 12150 synconcealed(lnum, 2) [1, 'X', 1] 12151 synconcealed(lnum, 3) [1, 'X', 1] 12152 synconcealed(lnum, 4) [1, 'X', 2] 12153 synconcealed(lnum, 5) [1, 'X', 2] 12154 synconcealed(lnum, 6) [0, '', 0] 12155 12156 Note: Doesn't consider |matchadd()| highlighting items, 12157 since syntax and matching highlighting are two different 12158 mechanisms |syntax-vs-match|. 12159 12160 Return type: list<any> 12161 12162 12163 synstack({lnum}, {col}) *synstack()* 12164 Return a |List|, which is the stack of syntax items at the 12165 position {lnum} and {col} in the current window. {lnum} is 12166 used like with |getline()|. Each item in the List is an ID 12167 like what |synID()| returns. 12168 The first item in the List is the outer region, following are 12169 items contained in that one. The last one is what |synID()| 12170 returns, unless not the whole item is highlighted or it is a 12171 transparent item. 12172 This function is useful for debugging a syntax file. 12173 Example that shows the syntax stack under the cursor: > 12174 for id in synstack(line("."), col(".")) 12175 echo synIDattr(id, "name") 12176 endfor 12177 < When the position specified with {lnum} and {col} is invalid 12178 an empty List is returned. The position just after the last 12179 character in a line and the first column in an empty line are 12180 valid positions. 12181 12182 Return type: list<number> or list<any> 12183 12184 12185 system({expr} [, {input}]) *system()* *E677* 12186 Get the output of the shell command {expr} as a |String|. See 12187 |systemlist()| to get the output as a |List|. 12188 12189 {expr} can be a |String| or a |List|. 12190 When {expr} is a |String|, the command is executed through the 12191 shell (see below for how the command is constructed). 12192 12193 *E1575* 12194 When {expr} is a |List|, the first item is the executable and 12195 the remaining items are passed as arguments directly. The 12196 command is executed without using a shell, similar to 12197 |job_start()|. Since no shell is involved, shell features 12198 such as redirection, piping, globbing, environment variable 12199 expansion and backtick expansion will not work. Characters 12200 like ">" are passed as literal arguments to the command, not 12201 interpreted as redirection. Use this form when arguments may 12202 contain special characters that should not be interpreted by 12203 the shell. Example: > 12204 :let out = system(['grep', '-r', 'pattern', '.']) 12205 < With the String form ">" would be shell redirection, but 12206 with a List it is passed as a literal argument: > 12207 :let out = system(['echo', 'hello', '>', 'world']) 12208 < This outputs "hello > world", not redirect to a file. 12209 12210 To use the shell explicitly with a List: > 12211 :let out = system(['/bin/sh', '-c', 'echo $HOME']) 12212 < 12213 When {input} is given and is a |String| this string is written 12214 to a file and passed as stdin to the command. The string is 12215 written as-is, you need to take care of using the correct line 12216 separators yourself. 12217 If {input} is given and is a |List| it is written to the file 12218 in a way |writefile()| does with {binary} set to "b" (i.e. 12219 with a newline between each list item with newlines inside 12220 list items converted to NULs). 12221 When {input} is given and is a number that is a valid id for 12222 an existing buffer then the content of the buffer is written 12223 to the file line by line, each line terminated by a NL and 12224 NULs characters where the text has a NL. 12225 12226 Pipes are not used, the 'shelltemp' option is not used. 12227 12228 When prepended by |:silent| the terminal will not be set to 12229 cooked mode. This is meant to be used for commands that do 12230 not need the user to type. It avoids stray characters showing 12231 up on the screen which require |CTRL-L| to remove. 12232 When calling system() from a 'statusline' expression, an 12233 |autocommand| or a |timer| callback, you should use |:silent| 12234 to avoid terminal responses (e.g. from cursor style queries) 12235 being echoed on the screen. > 12236 :silent let f = system('ls *.vim') 12237 < 12238 Note: When {expr} is a String, use |shellescape()| or |::S| 12239 with |expand()| or |fnamemodify()| to escape special 12240 characters in a command argument. Newlines in {expr} may 12241 cause the command to fail. The characters in 'shellquote' 12242 and 'shellxquote' may also cause trouble. 12243 This is not to be used for interactive commands. 12244 12245 The result is a String. Example: > 12246 :let files = system('ls ' .. shellescape(expand('%:h'))) 12247 :let files = system('ls ' .. expand('%:h:S')) 12248 12249 < To make the result more system-independent, the shell output 12250 is filtered to replace <CR> with <NL> for Macintosh, and 12251 <CR><NL> with <NL> for DOS-like systems. 12252 To avoid the string being truncated at a NUL, all NUL 12253 characters are replaced with SOH (0x01). 12254 12255 When {expr} is a String, the command executed is constructed 12256 using several options: 12257 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote' 12258 ({tmp} is an automatically generated file name). 12259 For Unix, braces are put around {expr} to allow for 12260 concatenated commands. 12261 12262 The command will be executed in "cooked" mode, so that a 12263 CTRL-C will interrupt the command (on Unix at least). 12264 12265 The resulting error code can be found in |v:shell_error|. 12266 This function will fail in |restricted-mode|. 12267 12268 Note that any wrong value in the options mentioned above may 12269 make the function fail. It has also been reported to fail 12270 when using a security agent application. 12271 Unlike ":!cmd" there is no automatic check for changed files. 12272 Use |:checktime| to force a check. 12273 12274 Can also be used as a |method|: > 12275 :echo GetCmd()->system() 12276 < 12277 Return type: |String| 12278 12279 12280 systemlist({expr} [, {input}]) *systemlist()* 12281 Same as |system()|, but returns a |List| with lines (parts of 12282 output separated by NL) with NULs transformed into NLs. 12283 Like |system()|, {expr} can be a |String| (executed through 12284 the shell) or a |List| (executed directly without a shell). 12285 See |system()| for details. 12286 Output is the same as |readfile()| will output with {binary} 12287 argument set to "b", except that there is no extra empty item 12288 when the result ends in a NL. 12289 Note that on MS-Windows you may get trailing CR characters. 12290 12291 To see the difference between "echo hello" and "echo -n hello" 12292 use |system()| and |split()|: > 12293 echo system('echo hello')->split('\n', 1) 12294 < 12295 Returns an empty string on error. 12296 12297 Like |system()|, prepend |:silent| when the command does not 12298 need user interaction and is called from a 'statusline' 12299 expression, an |autocommand| or a |timer| callback. See 12300 |system()| for details. 12301 12302 Can also be used as a |method|: > 12303 :echo GetCmd()->systemlist() 12304 < 12305 Return type: list<string> 12306 12307 12308 tabpagebuflist([{arg}]) *tabpagebuflist()* 12309 The result is a |List|, where each item is the number of the 12310 buffer associated with each window in the current tab page. 12311 {arg} specifies the number of the tab page to be used. When 12312 omitted the current tab page is used. 12313 When {arg} is invalid the number zero is returned. 12314 To get a list of all buffers in all tabs use this: > 12315 let buflist = [] 12316 for i in range(tabpagenr('$')) 12317 call extend(buflist, tabpagebuflist(i + 1)) 12318 endfor 12319 < Note that a buffer may appear in more than one window. 12320 12321 Can also be used as a |method|: > 12322 GetTabpage()->tabpagebuflist() 12323 < 12324 Return type: list<number> 12325 12326 12327 tabpagenr([{arg}]) *tabpagenr()* 12328 The result is a Number, which is the number of the current 12329 tab page. The first tab page has number 1. 12330 12331 The optional argument {arg} supports the following values: 12332 $ the number of the last tab page (the tab page 12333 count). 12334 # the number of the last accessed tab page 12335 (where |g<Tab>| goes to). if there is no 12336 previous tab page 0 is returned. 12337 The number can be used with the |:tab| command. 12338 12339 Returns zero on error. 12340 12341 Return type: |Number| 12342 12343 12344 tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()* 12345 Like |winnr()| but for tab page {tabarg}. 12346 {tabarg} specifies the number of tab page to be used. 12347 {arg} is used like with |winnr()|: 12348 - When omitted the current window number is returned. This is 12349 the window which will be used when going to this tab page. 12350 - When "$" the number of windows is returned. 12351 - When "#" the previous window nr is returned. 12352 Useful examples: > 12353 tabpagewinnr(1) " current window of tab page 1 12354 tabpagewinnr(4, '$') " number of windows in tab page 4 12355 < When {tabarg} is invalid zero is returned. 12356 12357 Can also be used as a |method|: > 12358 GetTabpage()->tabpagewinnr() 12359 < 12360 Return type: |Number| 12361 12362 12363 tabpanel_getinfo() *tabpanel_getinfo()* 12364 Return a |Dictionary| describing the current state of the 12365 tabpanel (see |tabpanel|). The dictionary has these keys: 12366 align "left" or "right" 12367 columns width in screen columns 12368 scrollbar |TRUE| if a scrollbar is shown 12369 offset current scroll offset in rows 12370 total total number of rows rendered 12371 max_offset largest valid value for "offset" 12372 12373 The "total" and "max_offset" values are only accurate after 12374 the tabpanel has been drawn at least once. 12375 12376 Return type: dict<any> 12377 12378 12379 tabpanel_scroll({n} [, {opts}]) *tabpanel_scroll()* 12380 Scroll the tabpanel by {n} rows. Positive values scroll down 12381 (later tab pages become visible), negative values scroll up. 12382 The new offset is clamped to the valid range. 12383 12384 When {opts} is a |Dictionary| and its "absolute" entry is 12385 |TRUE|, {n} is used as the new absolute scroll offset instead 12386 of a delta. 12387 12388 Returns |TRUE| if the scroll offset changed, |FALSE| otherwise 12389 (for example when the tabpanel is not shown, or the offset is 12390 already at the requested value). 12391 12392 Return type: |vim9-boolean| 12393 12394 12395 tagfiles() *tagfiles()* 12396 Returns a |List| with the file names used to search for tags 12397 for the current buffer. This is the 'tags' option expanded. 12398 12399 Return type: list<string> or list<any> 12400 12401 12402 taglist({expr} [, {filename}]) *taglist()* 12403 Returns a |List| of tags matching the regular expression {expr}. 12404 12405 If {filename} is passed it is used to prioritize the results 12406 in the same way that |:tselect| does. See |tag-priority|. 12407 {filename} should be the full path of the file. 12408 12409 Each list item is a dictionary with at least the following 12410 entries: 12411 name Name of the tag. 12412 filename Name of the file where the tag is 12413 defined. It is either relative to the 12414 current directory or a full path. 12415 cmd Ex command used to locate the tag in 12416 the file. 12417 kind Type of the tag. The value for this 12418 entry depends on the language specific 12419 kind values. Only available when 12420 using a tags file generated by 12421 Universal/Exuberant ctags or hdrtag. 12422 static A file specific tag. Refer to 12423 |static-tag| for more information. 12424 More entries may be present, depending on the content of the 12425 tags file: access, implementation, inherits and signature. 12426 Refer to the ctags documentation for information about these 12427 fields. For C code the fields "struct", "class" and "enum" 12428 may appear, they give the name of the entity the tag is 12429 contained in. 12430 12431 The ex-command "cmd" can be either an ex search pattern, a 12432 line number or a line number followed by a byte number. 12433 12434 If there are no matching tags, then an empty list is returned. 12435 12436 To get an exact tag match, the anchors '^' and '$' should be 12437 used in {expr}. This also make the function work faster. 12438 Refer to |tag-regexp| for more information about the tag 12439 search regular expression pattern. 12440 12441 Refer to 'tags' for information about how the tags file is 12442 located by Vim. Refer to |tags-file-format| for the format of 12443 the tags file generated by the different ctags tools. 12444 12445 Can also be used as a |method|: > 12446 GetTagpattern()->taglist() 12447 < 12448 Return type: list<dict<any>> or list<any> 12449 12450 12451 tan({expr}) *tan()* 12452 Return the tangent of {expr}, measured in radians, as a |Float| 12453 in the range [-inf, inf]. 12454 {expr} must evaluate to a |Float| or a |Number|. 12455 Returns 0.0 if {expr} is not a |Float| or a |Number|. 12456 Examples: > 12457 :echo tan(10) 12458 < 0.648361 > 12459 :echo tan(-4.01) 12460 < -1.181502 12461 12462 Can also be used as a |method|: > 12463 Compute()->tan() 12464 < 12465 Return type: |Float| 12466 12467 12468 tanh({expr}) *tanh()* 12469 Return the hyperbolic tangent of {expr} as a |Float| in the 12470 range [-1, 1]. 12471 {expr} must evaluate to a |Float| or a |Number|. 12472 Returns 0.0 if {expr} is not a |Float| or a |Number|. 12473 Examples: > 12474 :echo tanh(0.5) 12475 < 0.462117 > 12476 :echo tanh(-1) 12477 < -0.761594 12478 12479 Can also be used as a |method|: > 12480 Compute()->tanh() 12481 < 12482 Return type: |Float| 12483 12484 12485 tempname() *tempname()* *temp-file-name* 12486 The result is a String, which is the name of a file that 12487 doesn't exist. It can be used for a temporary file. The name 12488 is different for at least 26 consecutive calls. Example: > 12489 :let tmpfile = tempname() 12490 :exe "redir > " .. tmpfile 12491 < For Unix, the file will be in a private directory |tempfile| 12492 that is recursively deleted when Vim exits, on other systems 12493 temporary files are not cleaned up automatically on exit. 12494 For MS-Windows forward slashes are used when the 'shellslash' 12495 option is set, or when 'shellcmdflag' starts with '-' and 12496 'shell' does not contain powershell or pwsh. 12497 12498 Return type: |String| 12499 12500 12501 term_ functions are documented here: |terminal-function-details| 12502 12503 12504 terminalprops() *terminalprops()* 12505 Returns a |Dictionary| with properties of the terminal that Vim 12506 detected from the response to |t_RV| request. See 12507 |v:termresponse| for the response itself. If |v:termresponse| 12508 is empty most values here will be 'u' for unknown. 12509 cursor_style whether sending |t_RS| works ** 12510 cursor_blink_mode whether sending |t_RC| works ** 12511 underline_rgb whether |t_8u| works ** 12512 mouse mouse type supported 12513 kitty whether Kitty terminal was detected 12514 decrqm whether sending DECRQM sequences work 12515 rgb whether the terminal has true color ** 12516 12517 ** value 'u' for unknown, 'y' for yes, 'n' for no 12518 12519 If the |+termresponse| feature is missing then the result is 12520 an empty dictionary. 12521 12522 If "cursor_style" is 'y' then |t_RS| will be sent to request the 12523 current cursor style. 12524 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to 12525 request the cursor blink status. 12526 "cursor_style" and "cursor_blink_mode" are also set if |t_u7| 12527 is not empty, Vim will detect the working of sending |t_RS| 12528 and |t_RC| on startup. 12529 12530 When "underline_rgb" is not 'y', then |t_8u| will be made empty. 12531 This avoids sending it to xterm, which would clear the colors. 12532 12533 For "mouse" the value 'u' is unknown 12534 12535 If "decrqm" is 'y', then Vim will query support for the 12536 'termsync' and 'termresize' ("inband") options. 12537 12538 "rgb" is 'y' when 't_Co' is 16777216, as it is for the 12539 "xterm-direct" terminal entry. See |xterm-true-color|. 12540 12541 Also see: 12542 - 'ambiwidth' - detected by using |t_u7|. 12543 - |v:termstyleresp| and |v:termblinkresp| for the response to 12544 |t_RS| and |t_RC|. 12545 12546 Return type: dict<string> 12547 12548 12549 test_ functions are documented here: |test-functions-details| 12550 12551 12552 timer_info([{id}]) *timer_info()* 12553 Return a list with information about timers. 12554 When {id} is given only information about this timer is 12555 returned. When timer {id} does not exist an empty list is 12556 returned. 12557 When {id} is omitted information about all timers is returned. 12558 12559 For each timer the information is stored in a |Dictionary| with 12560 these items: 12561 "id" the timer ID 12562 "time" time the timer was started with 12563 "remaining" time until the timer fires 12564 "repeat" number of times the timer will still fire; 12565 -1 means forever 12566 "callback" the callback 12567 "paused" 1 if the timer is paused, 0 otherwise 12568 12569 Can also be used as a |method|: > 12570 GetTimer()->timer_info() 12571 < 12572 Return type: list<dict<any>> or list<any> 12573 12574 {only available when compiled with the |+timers| feature} 12575 12576 12577 timer_pause({timer}, {paused}) *timer_pause()* 12578 Pause or unpause a timer. A paused timer does not invoke its 12579 callback when its time expires. Unpausing a timer may cause 12580 the callback to be invoked almost immediately if enough time 12581 has passed. 12582 12583 Pausing a timer is useful to avoid the callback to be called 12584 for a short time. 12585 12586 If {paused} evaluates to a non-zero Number or a non-empty 12587 String, then the timer is paused, otherwise it is unpaused. 12588 See |non-zero-arg|. 12589 12590 Can also be used as a |method|: > 12591 GetTimer()->timer_pause(1) 12592 < 12593 Return type: void 12594 12595 {only available when compiled with the |+timers| feature} 12596 12597 12598 *timer_start()* *timer* *timers* 12599 timer_start({time}, {callback} [, {options}]) 12600 Create a timer and return the timer ID. 12601 12602 {time} is the waiting time in milliseconds. This is the 12603 minimum time before invoking the callback. When the system is 12604 busy or Vim is not waiting for input the time will be longer. 12605 Zero can be used to execute the callback when Vim is back in 12606 the main loop. 12607 12608 {callback} is the function to call. It can be the name of a 12609 function or a |Funcref|. It is called with one argument, which 12610 is the timer ID. The callback is only invoked when Vim is 12611 waiting for input. 12612 If you want to show a message look at |popup_notification()| 12613 to avoid interfering with what the user is doing. 12614 12615 {options} is a dictionary. Supported entries: 12616 "repeat" Number of times to repeat calling the 12617 callback. -1 means forever. When not present 12618 the callback will be called once. 12619 If the timer causes an error three times in a 12620 row the repeat is cancelled. This avoids that 12621 Vim becomes unusable because of all the error 12622 messages. 12623 12624 Returns -1 on error. 12625 12626 Example: > 12627 func MyHandler(timer) 12628 echo 'Handler called' 12629 endfunc 12630 let timer = timer_start(500, 'MyHandler', 12631 \ {'repeat': 3}) 12632 < This will invoke MyHandler() three times at 500 msec 12633 intervals. 12634 12635 Can also be used as a |method|: > 12636 GetMsec()->timer_start(callback) 12637 12638 < Not available in the |sandbox|. 12639 12640 Return type: |Number| 12641 12642 {only available when compiled with the |+timers| feature} 12643 12644 12645 timer_stop({timer}) *timer_stop()* 12646 Stop a timer. The timer callback will no longer be invoked. 12647 {timer} is an ID returned by |timer_start()|, thus it must be a 12648 Number. If {timer} does not exist there is no error. 12649 12650 Can also be used as a |method|: > 12651 GetTimer()->timer_stop() 12652 < 12653 Return type: void 12654 12655 {only available when compiled with the |+timers| feature} 12656 12657 12658 timer_stopall() *timer_stopall()* 12659 Stop all timers. The timer callbacks will no longer be 12660 invoked. Useful if a timer is misbehaving. If there are no 12661 timers there is no error. 12662 12663 Return type: void 12664 12665 {only available when compiled with the |+timers| feature} 12666 12667 12668 tolower({expr}) *tolower()* 12669 The result is a copy of the String given, with all uppercase 12670 characters turned into lowercase (just like applying |gu| to 12671 the string). Returns an empty string on error. 12672 12673 Can also be used as a |method|: > 12674 GetText()->tolower() 12675 < 12676 Return type: |String| 12677 12678 12679 toupper({expr}) *toupper()* 12680 The result is a copy of the String given, with all lowercase 12681 characters turned into uppercase (just like applying |gU| to 12682 the string). Returns an empty string on error. 12683 12684 Can also be used as a |method|: > 12685 GetText()->toupper() 12686 < 12687 Return type: |String| 12688 12689 12690 tr({src}, {fromstr}, {tostr}) *tr()* 12691 The result is a copy of the {src} string with all characters 12692 which appear in {fromstr} replaced by the character in that 12693 position in the {tostr} string. Thus the first character in 12694 {fromstr} is translated into the first character in {tostr} 12695 and so on. Exactly like the unix "tr" command. 12696 This code also deals with multibyte characters properly. 12697 12698 Returns an empty string on error. 12699 12700 Examples: > 12701 echo tr("hello there", "ht", "HT") 12702 < returns "Hello THere" > 12703 echo tr("<blob>", "<>", "{}") 12704 < returns "{blob}" 12705 12706 Can also be used as a |method|: > 12707 GetText()->tr(from, to) 12708 < 12709 Return type: |String| 12710 12711 12712 trim({text} [, {mask} [, {dir}]]) *trim()* 12713 Return {text} as a String where any character in {mask} is 12714 removed from the beginning and/or end of {text}. 12715 12716 If {mask} is not given, or is an empty string, {mask} is all 12717 characters up to 0x20, which includes Tab, space, NL and CR, 12718 plus the non-breaking space character 0xa0. 12719 12720 The optional {dir} argument specifies where to remove the 12721 characters: 12722 0 remove from the beginning and end of {text} 12723 1 remove only at the beginning of {text} 12724 2 remove only at the end of {text} 12725 When omitted both ends are trimmed. 12726 12727 This function deals with multibyte characters properly. 12728 Returns an empty string on error. 12729 12730 Examples: > 12731 echo trim(" some text ") 12732 < returns "some text" > 12733 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL" 12734 < returns "RESERVE_TAIL" > 12735 echo trim("rm<Xrm<>X>rrm", "rm<>") 12736 < returns "Xrm<>X" (characters in the middle are not removed) > 12737 echo trim(" vim ", " ", 2) 12738 < returns " vim" 12739 12740 Can also be used as a |method|: > 12741 GetText()->trim() 12742 < 12743 Return type: |String| 12744 12745 12746 trunc({expr}) *trunc()* 12747 Return the largest integral value with magnitude less than or 12748 equal to {expr} as a |Float| (truncate towards zero). 12749 {expr} must evaluate to a |Float| or a |Number|. 12750 Returns 0.0 if {expr} is not a |Float| or a |Number|. 12751 Examples: > 12752 echo trunc(1.456) 12753 < 1.0 > 12754 echo trunc(-5.456) 12755 < -5.0 > 12756 echo trunc(4.0) 12757 < 4.0 12758 12759 Can also be used as a |method|: > 12760 Compute()->trunc() 12761 < 12762 Return type: |Float| 12763 12764 12765 tuple2list({tuple}) *tuple2list()* 12766 Create a List from a shallow copy of the tuple items. 12767 Examples: > 12768 tuple2list((1, 2, 3)) returns [1, 2, 3] 12769 < |list2tuple()| does the opposite. 12770 12771 This function doesn't recursively convert all the Tuple items 12772 in {tuple} to a List. Note that the items are identical 12773 between the list and the tuple, changing an item changes the 12774 contents of both the tuple and the list. 12775 12776 Returns an empty list on error. 12777 12778 Can also be used as a |method|: > 12779 GetTuple()->tuple2list() 12780 < 12781 Return type: list<{type}> (depending on the given |Tuple|) 12782 12783 12784 type({expr}) *type()* 12785 The result is a Number representing the type of {expr}. 12786 Instead of using the number directly, it is better to use the 12787 v:t_ variable that has the value: 12788 Number: 0 |v:t_number| 12789 String: 1 |v:t_string| 12790 Funcref: 2 |v:t_func| 12791 List: 3 |v:t_list| 12792 Dictionary: 4 |v:t_dict| 12793 Float: 5 |v:t_float| 12794 Boolean: 6 |v:t_bool| (v:false and v:true) 12795 None: 7 |v:t_none| (v:null and v:none) 12796 Job: 8 |v:t_job| 12797 Channel: 9 |v:t_channel| 12798 Blob: 10 |v:t_blob| 12799 Class: 12 |v:t_class| 12800 Object: 13 |v:t_object| 12801 Typealias: 14 |v:t_typealias| 12802 Enum: 15 |v:t_enum| 12803 EnumValue: 16 |v:t_enumvalue| 12804 Tuple: 17 |v:t_tuple| 12805 For backward compatibility, this method can be used: > 12806 :if type(myvar) == type(0) 12807 :if type(myvar) == type("") 12808 :if type(myvar) == type(function("tr")) 12809 :if type(myvar) == type([]) 12810 :if type(myvar) == type({}) 12811 :if type(myvar) == type(0.0) 12812 :if type(myvar) == type(v:false) 12813 :if type(myvar) == type(v:none) 12814 < To check if the v:t_ variables exist use this: > 12815 :if exists('v:t_number') 12816 12817 < Can also be used as a |method|: > 12818 mylist->type() 12819 < 12820 Return type: |Number| 12821 12822 12823 typename({expr}) *typename()* 12824 Return a string representation of the type of {expr}. 12825 Example: > 12826 echo typename([1, 2, 3]) 12827 < list<number> ~ 12828 12829 Return type: |String| 12830 12831 12832 undofile({name}) *undofile()* 12833 Return the name of the undo file that would be used for a file 12834 with name {name} when writing. This uses the 'undodir' 12835 option, finding directories that exist. It does not check if 12836 the undo file exists. 12837 {name} is always expanded to the full path, since that is what 12838 is used internally. 12839 If {name} is empty undofile() returns an empty string, since a 12840 buffer without a file name will not write an undo file. 12841 Useful in combination with |:wundo| and |:rundo|. 12842 When compiled without the |+persistent_undo| option this always 12843 returns an empty string. 12844 12845 Can also be used as a |method|: > 12846 GetFilename()->undofile() 12847 < 12848 Return type: |String| 12849 12850 12851 undotree([{buf}]) *undotree()* 12852 Return the current state of the undo tree for the current 12853 buffer, or for a specific buffer if {buf} is given. The 12854 result is a dictionary with the following items: 12855 "seq_last" The highest undo sequence number used. 12856 "seq_cur" The sequence number of the current position in 12857 the undo tree. This differs from "seq_last" 12858 when some changes were undone. 12859 "time_cur" Time last used for |:earlier| and related 12860 commands. Use |strftime()| to convert to 12861 something readable. 12862 "save_last" Number of the last file write. Zero when no 12863 write yet. 12864 "save_cur" Number of the current position in the undo 12865 tree. 12866 "synced" Non-zero when the last undo block was synced. 12867 This happens when waiting from input from the 12868 user. See |undo-blocks|. 12869 "entries" A list of dictionaries with information about 12870 undo blocks. 12871 12872 The first item in the "entries" list is the oldest undo item. 12873 Each List item is a |Dictionary| with these items: 12874 "seq" Undo sequence number. Same as what appears in 12875 |:undolist|. 12876 "time" Timestamp when the change happened. Use 12877 |strftime()| to convert to something readable. 12878 "newhead" Only appears in the item that is the last one 12879 that was added. This marks the last change 12880 and where further changes will be added. 12881 "curhead" Only appears in the item that is the last one 12882 that was undone. This marks the current 12883 position in the undo tree, the block that will 12884 be used by a redo command. When nothing was 12885 undone after the last change this item will 12886 not appear anywhere. 12887 "save" Only appears on the last block before a file 12888 write. The number is the write count. The 12889 first write has number 1, the last one the 12890 "save_last" mentioned above. 12891 "alt" Alternate entry. This is again a List of undo 12892 blocks. Each item may again have an "alt" 12893 item. 12894 12895 Return type: dict<any> 12896 12897 12898 uniq({list} [, {func} [, {dict}]]) *uniq()* *E882* 12899 Remove second and succeeding copies of repeated adjacent 12900 {list} items in-place. Returns {list}. If you want a list 12901 to remain unmodified make a copy first: > 12902 :let newlist = uniq(copy(mylist)) 12903 < The default compare function uses the string representation of 12904 each item. For the use of {func} and {dict} see |sort()|. 12905 For deduplicating text in the current buffer see |:uniq|. 12906 12907 Returns zero if {list} is not a |List|. 12908 12909 Can also be used as a |method|: > 12910 mylist->uniq() 12911 < 12912 Return type: list<{type}> 12913 12914 12915 uri_decode({string}) *uri_decode()* 12916 Returns the URI-decoded form of {string}, reversing 12917 percent-encoding (converting sequences like "%3D" back to 12918 the corresponding character). 12919 12920 The decoding follows standard percent-decoding rules: 12921 - "%HH" is replaced with the character for the hex value 12922 HH. 12923 - If the decoded bytes form valid UTF-8, they are combined 12924 into the corresponding character(s). Otherwise, the 12925 bytes are kept as-is. 12926 - Invalid or incomplete encodings (e.g. "%GZ", "%3", or a 12927 trailing "%") are left unchanged. 12928 12929 Returns an empty String if {string} is empty. 12930 12931 Example: > 12932 :echo uri_decode('c%3A%5Cmy%5Cdir%5Cfoo%20bar') 12933 c:\my\dir\foo bar 12934 :echo uri_decode('%CE%B1%CE%B2%CE%B3') 12935 αβγ 12936 < 12937 Can also be used as a |method|: > 12938 mystr->uri_decode() 12939 < 12940 Return type: |String| 12941 12942 12943 uri_encode({string}) *uri_encode()* 12944 Returns the URI-encoded form of {string}. URI encoding 12945 replaces unsafe or reserved characters with percent-encoded 12946 sequences. 12947 12948 The encoding follows standard percent-encoding rules: 12949 - Alphanumeric characters [0-9A-Za-z] remain unchanged. 12950 - The characters "-", "_", ".", and "~" also remain 12951 unchanged. 12952 - All other characters are replaced with "%HH", where HH 12953 is the two-digit uppercase hexadecimal value. 12954 - Existing percent-encoded sequences are not modified. 12955 12956 Returns an empty String if {string} is empty. 12957 12958 Example: > 12959 :echo uri_encode('c:\my\dir\foo bar') 12960 c%3A%5Cmy%5Cdir%5Cfoo%20bar 12961 :echo uri_encode('key=value&name=αβγ') 12962 key%3Dvalue%26name%3D%CE%B1%CE%B2%CE%B3 12963 < 12964 Can also be used as a |method|: > 12965 mystr->uri_encode() 12966 < 12967 Return type: |String| 12968 12969 12970 utf16idx({string}, {idx} [, {countcc} [, {charidx}]]) *utf16idx()* 12971 Same as |charidx()| but returns the UTF-16 code unit index of 12972 the byte at {idx} in {string} (after converting it to UTF-16). 12973 12974 When {charidx} is present and TRUE, {idx} is used as the 12975 character index in the String {string} instead of as the byte 12976 index. 12977 An {idx} in the middle of a UTF-8 sequence is rounded 12978 downwards to the beginning of that sequence. 12979 12980 Returns -1 if the arguments are invalid or if there are less 12981 than {idx} bytes in {string}. If there are exactly {idx} 12982 bytes, the length of the string in UTF-16 code units is 12983 returned. 12984 12985 See |byteidx()| and |byteidxcomp()| for getting the byte index 12986 from the UTF-16 index and |charidx()| for getting the 12987 character index from the UTF-16 index. 12988 Refer to |string-offset-encoding| for more information. 12989 Examples: > 12990 echo utf16idx('a😊😊', 3) returns 2 12991 echo utf16idx('a😊😊', 7) returns 4 12992 echo utf16idx('a😊😊', 1, 0, 1) returns 2 12993 echo utf16idx('a😊😊', 2, 0, 1) returns 4 12994 echo utf16idx('aą́c', 6) returns 2 12995 echo utf16idx('aą́c', 6, 1) returns 4 12996 echo utf16idx('a😊😊', 9) returns -1 12997 < 12998 Can also be used as a |method|: > 12999 GetName()->utf16idx(idx) 13000 < 13001 Return type: |Number| 13002 13003 13004 values({dict}) *values()* 13005 Return a |List| with all the values of {dict}. The |List| is 13006 in arbitrary order. Also see |items()| and |keys()|. 13007 Returns zero if {dict} is not a |Dict|. 13008 13009 Can also be used as a |method|: > 13010 mydict->values() 13011 < 13012 Return type: list<any> 13013 13014 13015 virtcol({expr} [, {list} [, {winid}]]) *virtcol()* 13016 The result is a Number, which is the screen column of the file 13017 position given with {expr}. That is, the total number of 13018 screen cells occupied by the part of the line until the end of 13019 the character at that position. When there is a <Tab> at the 13020 position, the returned Number will be the column at the end of 13021 the <Tab>. For example, for a <Tab> in column 1, with 'ts' 13022 set to 8, it returns 8. |conceal| is ignored. 13023 For the byte position use |col()|. 13024 13025 For the use of {expr} see |getpos()| and |col()|. 13026 When {expr} is "$", it means the end of the cursor line, so 13027 the result is the number of cells in the cursor line plus one. 13028 13029 When 'virtualedit' is used {expr} can be [lnum, col, off], 13030 where "off" is the offset in screen columns from the start of 13031 the character. E.g., a position within a <Tab> or after the 13032 last character. When "off" is omitted zero is used. When 13033 Virtual editing is active in the current mode, a position 13034 beyond the end of the line can be returned. Also see 13035 'virtualedit' 13036 13037 |virtual-text| above the line occupies its own screen line and 13038 is counted like a wrapped line: with a window 80 columns wide 13039 the first character of the line is then in virtual column 81. 13040 13041 If {list} is present and non-zero then virtcol() returns a 13042 List with the first and last screen position occupied by the 13043 character. 13044 13045 With the optional {winid} argument the values are obtained for 13046 that window instead of the current window. 13047 13048 Note that only marks in the current file can be used. 13049 13050 Examples: > 13051 " With text "foo^Lbar" and cursor on the "^L": 13052 13053 virtcol(".") " returns 5 13054 virtcol(".", 1) " returns [4, 5] 13055 virtcol("$") " returns 9 13056 13057 " With text " there", with 't at 'h': 13058 13059 virtcol("'t") " returns 6 13060 < 13061 The first column is 1. 0 or [0, 0] is returned for an error. 13062 13063 A more advanced example that echoes the maximum length of 13064 all lines: > 13065 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])")) 13066 13067 < Can also be used as a |method|: > 13068 GetPos()->virtcol() 13069 < 13070 Return type: |Number| 13071 13072 13073 virtcol2col({winid}, {lnum}, {col}) *virtcol2col()* 13074 The result is a Number, which is the byte index of the 13075 character in window {winid} at buffer line {lnum} and virtual 13076 column {col}. 13077 13078 If buffer line {lnum} is an empty line, 0 is returned. 13079 13080 If {col} is greater than the last virtual column in line 13081 {lnum}, then the byte index of the character at the last 13082 virtual column is returned. 13083 13084 For a multi-byte character, the column number of the first 13085 byte in the character is returned. 13086 13087 The {winid} argument can be the window number or the 13088 |window-ID|. If this is zero, then the current window is used. 13089 13090 Returns -1 if the window {winid} doesn't exist or the buffer 13091 line {lnum} or virtual column {col} is invalid. 13092 13093 See also |screenpos()|, |virtcol()| and |col()|. 13094 13095 Can also be used as a |method|: > 13096 GetWinid()->virtcol2col(lnum, col) 13097 < 13098 Return type: |Number| 13099 13100 13101 visualmode([{expr}]) *visualmode()* 13102 The result is a String, which describes the last Visual mode 13103 used in the current buffer. Initially it returns an empty 13104 string, but once Visual mode has been used, it returns "v", 13105 "V", or "<CTRL-V>" (a single CTRL-V character) for 13106 character-wise, line-wise, or block-wise Visual mode 13107 respectively. 13108 Example: > 13109 :exe "normal " .. visualmode() 13110 < This enters the same Visual mode as before. It is also useful 13111 in scripts if you wish to act differently depending on the 13112 Visual mode that was used. 13113 If Visual mode is active, use |mode()| to get the Visual mode 13114 (e.g., in a |:vmap|). 13115 If {expr} is supplied and it evaluates to a non-zero Number or 13116 a non-empty String, then the Visual mode will be cleared and 13117 the old value is returned. See |non-zero-arg|. 13118 13119 Return type: |String| 13120 13121 13122 wildmenumode() *wildmenumode()* 13123 Returns |TRUE| when the wildmenu is active and |FALSE| 13124 otherwise. See 'wildmenu' and 'wildmode'. 13125 This can be used in mappings to handle the 'wildcharm' option 13126 gracefully. (Makes only sense with |mapmode-c| mappings). 13127 13128 For example to make <c-j> work like <down> in wildmode, use: > 13129 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>" 13130 < 13131 (Note: this needs the 'wildcharm' option set appropriately). 13132 13133 Return type: |Number| 13134 13135 13136 wildtrigger() *wildtrigger()* 13137 Start wildcard expansion in the command-line, using the 13138 behavior defined by the 'wildmode' and 'wildoptions' settings. 13139 13140 This function also enables completion in search patterns such 13141 as |/|, |?|, |:s|, |:g|, |:v| and |:vimgrep|. 13142 13143 Unlike pressing 'wildchar' manually, this function does not 13144 produce a beep when no matches are found and generally 13145 operates more quietly. This makes it suitable for triggering 13146 completion automatically. 13147 13148 Note: After navigating command-line history, the first call to 13149 wildtrigger() is a no-op; a second call is needed to start 13150 expansion. This is to support history navigation in 13151 command-line autocompletion. 13152 13153 See |cmdline-autocompletion|. 13154 13155 Return value is always 0. 13156 13157 Return type: void 13158 13159 13160 win_execute({id}, {command} [, {silent}]) *win_execute()* 13161 Like `execute()` but in the context of window {id}. 13162 The window will temporarily be made the current window, 13163 without triggering autocommands or changing directory. When 13164 executing {command} autocommands will be triggered, this may 13165 have unexpected side effects. Use `:noautocmd` if needed. 13166 Example: > 13167 call win_execute(winid, 'set syntax=python') 13168 < Doing the same with `setwinvar()` would not trigger 13169 autocommands and not actually show syntax highlighting. 13170 *E994* 13171 Not all commands are allowed in popup windows. 13172 When window {id} does not exist then no error is given and 13173 an empty string is returned. 13174 13175 Can also be used as a |method|, the base is passed as the 13176 second argument: > 13177 GetCommand()->win_execute(winid) 13178 < 13179 Return type: |String| 13180 13181 13182 win_findbuf({bufnr}) *win_findbuf()* 13183 Returns a |List| with |window-ID|s for windows that contain 13184 buffer {bufnr}. When there is none the list is empty. 13185 13186 Can also be used as a |method|: > 13187 GetBufnr()->win_findbuf() 13188 < 13189 Return type: list<number> 13190 13191 win_getid([{win} [, {tab}]]) *win_getid()* 13192 Get the |window-ID| for the specified window. 13193 When {win} is missing use the current window. 13194 With {win} this is the window number. The top window has 13195 number 1. 13196 Without {tab} use the current tab, otherwise the tab with 13197 number {tab}. The first tab has number one. 13198 Return zero if the window cannot be found. 13199 13200 Can also be used as a |method|: > 13201 GetWinnr()->win_getid() 13202 < 13203 Return type: |Number| 13204 13205 13206 win_gettype([{nr}]) *win_gettype()* 13207 Return the type of the window: 13208 "autocmd" autocommand window. Temporary window 13209 used to execute autocommands. 13210 "command" command-line window |cmdwin| 13211 (empty) normal window 13212 "loclist" |location-list-window| 13213 "popup" popup window |popup| 13214 "preview" preview window |preview-window| 13215 "quickfix" |quickfix-window| 13216 "unknown" window {nr} not found 13217 13218 When {nr} is omitted return the type of the current window. 13219 When {nr} is given return the type of this window by number or 13220 |window-ID|. 13221 13222 Also see the 'buftype' option. When running a terminal in a 13223 popup window then 'buftype' is "terminal" and win_gettype() 13224 returns "popup". 13225 13226 Can also be used as a |method|: > 13227 GetWinid()->win_gettype() 13228 < 13229 Return type: |String| 13230 13231 13232 win_gotoid({expr}) *win_gotoid()* 13233 Go to window with ID {expr}. This may also change the current 13234 tabpage. 13235 Return TRUE if successful, FALSE if the window cannot be 13236 found. 13237 13238 Can also be used as a |method|: > 13239 GetWinid()->win_gotoid() 13240 < 13241 Return type: |Number| 13242 13243 13244 win_id2tabwin({expr}) *win_id2tabwin()* 13245 Return a list with the tab number and window number of window 13246 with ID {expr}: [tabnr, winnr]. 13247 Return [0, 0] if the window cannot be found. 13248 13249 Can also be used as a |method|: > 13250 GetWinid()->win_id2tabwin() 13251 < 13252 Return type: list<number> 13253 13254 13255 win_id2win({expr}) *win_id2win()* 13256 Return the window number of window with ID {expr}. 13257 Return 0 if the window cannot be found in the current tabpage. 13258 13259 Can also be used as a |method|: > 13260 GetWinid()->win_id2win() 13261 < 13262 Return type: |Number| 13263 13264 13265 win_move_separator({nr}, {offset}) *win_move_separator()* 13266 Move window {nr}'s vertical separator (i.e., the right border) 13267 by {offset} columns, as if being dragged by the mouse. {nr} 13268 can be a window number or |window-ID|. A positive {offset} 13269 moves right and a negative {offset} moves left. Moving a 13270 window's vertical separator will change the width of the 13271 window and the width of other windows adjacent to the vertical 13272 separator. The magnitude of movement may be smaller than 13273 specified (e.g., as a consequence of maintaining 13274 'winminwidth'). Returns TRUE if the window can be found and 13275 FALSE otherwise. 13276 This will fail for the rightmost window and a full-width 13277 window, since it has no separator on the right. 13278 Only works for the current tab page. *E1308* 13279 13280 Can also be used as a |method|: > 13281 GetWinnr()->win_move_separator(offset) 13282 < 13283 Return type: |Number| 13284 13285 13286 win_move_statusline({nr}, {offset}) *win_move_statusline()* 13287 Move window {nr}'s status line (i.e., the bottom border) by 13288 {offset} rows, as if being dragged by the mouse. {nr} can be 13289 a window number or |window-ID|. A positive {offset} moves 13290 down and a negative {offset} moves up. Moving a window's 13291 status line will change the height of the window and the 13292 height of other windows adjacent to the status line. The 13293 magnitude of movement may be smaller than specified (e.g., as 13294 a consequence of maintaining 'winminheight'). Returns TRUE if 13295 the window can be found and FALSE otherwise. 13296 Only works for the current tab page. 13297 13298 Can also be used as a |method|: > 13299 GetWinnr()->win_move_statusline(offset) 13300 < 13301 Return type: |Number| 13302 13303 13304 win_screenpos({nr}) *win_screenpos()* 13305 Return the screen position of window {nr} as a list with two 13306 numbers: [row, col]. The first window always has position 13307 [1, 1], unless there is a tabline, then it is [2, 1]. 13308 {nr} can be the window number or the |window-ID|. Use zero 13309 for the current window. 13310 Returns [0, 0] if the window cannot be found. 13311 13312 Can also be used as a |method|: > 13313 GetWinid()->win_screenpos() 13314 < 13315 Return type: list<number> 13316 13317 13318 win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* 13319 Temporarily switch to window {target}, then move window {nr} 13320 to a new split adjacent to {target}. 13321 Unlike commands such as |:split|, no new windows are created 13322 (the |window-ID| of window {nr} is unchanged after the move). 13323 13324 Both {nr} and {target} can be window numbers or |window-ID|s. 13325 Both must be in the current tab page. 13326 13327 Returns zero for success, non-zero for failure. 13328 13329 {options} is a |Dictionary| with the following optional entries: 13330 "vertical" When TRUE, the split is created vertically, 13331 like with |:vsplit|. 13332 "rightbelow" When TRUE, the split is made below or to the 13333 right (if vertical). When FALSE, it is done 13334 above or to the left (if vertical). When not 13335 present, the values of 'splitbelow' and 13336 'splitright' are used. 13337 13338 Can also be used as a |method|: > 13339 GetWinid()->win_splitmove(target) 13340 < 13341 Return type: |Number| 13342 13343 13344 winbufnr({nr}) *winbufnr()* 13345 The result is a Number, which is the number of the buffer 13346 associated with window {nr}. {nr} can be the window number or 13347 the |window-ID|. 13348 When {nr} is zero, the number of the buffer in the current 13349 window is returned. 13350 When window {nr} doesn't exist, -1 is returned. 13351 Example: > 13352 :echo "The file in the current window is " .. bufname(winbufnr(0)) 13353 < 13354 Can also be used as a |method|: > 13355 FindWindow()->winbufnr()->bufname() 13356 < 13357 Return type: |Number| 13358 13359 13360 wincol() *wincol()* 13361 The result is a Number, which is the virtual column of the 13362 cursor in the window. This is counting screen cells from the 13363 left side of the window. The leftmost column is one. 13364 13365 Return type: |Number| 13366 13367 13368 windowsversion() *windowsversion()* 13369 The result is a String. For MS-Windows it indicates the OS 13370 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2", 13371 Windows XP is "5.1". For non-MS-Windows systems the result is 13372 an empty string. 13373 13374 Return type: |String| 13375 13376 13377 winheight({nr}) *winheight()* 13378 The result is a Number, which is the height of window {nr}. 13379 {nr} can be the window number or the |window-ID|. 13380 When {nr} is zero, the height of the current window is 13381 returned. When window {nr} doesn't exist, -1 is returned. 13382 An existing window always has a height of zero or more. 13383 This excludes any window toolbar line. 13384 Examples: > 13385 :echo "The current window has " .. winheight(0) .. " lines." 13386 13387 < Can also be used as a |method|: > 13388 GetWinid()->winheight() 13389 < 13390 Return type: |Number| 13391 13392 13393 winlayout([{tabnr}]) *winlayout()* 13394 The result is a nested List containing the layout of windows 13395 in a tabpage. 13396 13397 Without {tabnr} use the current tabpage, otherwise the tabpage 13398 with number {tabnr}. If the tabpage {tabnr} is not found, 13399 returns an empty list. 13400 13401 For a leaf window, it returns: 13402 ['leaf', {winid}] 13403 For horizontally split windows, which form a column, it 13404 returns: 13405 ['col', [{nested list of windows}]] 13406 For vertically split windows, which form a row, it returns: 13407 ['row', [{nested list of windows}]] 13408 13409 Example: > 13410 " Only one window in the tab page 13411 :echo winlayout() 13412 ['leaf', 1000] 13413 " Two horizontally split windows 13414 :echo winlayout() 13415 ['col', [['leaf', 1000], ['leaf', 1001]]] 13416 " The second tab page, with three horizontally split 13417 " windows, with two vertically split windows in the 13418 " middle window 13419 :echo winlayout(2) 13420 ['col', [['leaf', 1002], ['row', [['leaf', 1003], 13421 ['leaf', 1001]]], ['leaf', 1000]]] 13422 < 13423 Can also be used as a |method|: > 13424 GetTabnr()->winlayout() 13425 < 13426 Return type: list<any> 13427 13428 13429 winline() *winline()* 13430 The result is a Number, which is the screen line of the cursor 13431 in the window. This is counting screen lines from the top of 13432 the window. The first line is one. 13433 If the cursor was moved the view on the file will be updated 13434 first, this may cause a scroll. 13435 13436 Return type: |Number| 13437 13438 13439 winnr([{arg}]) *winnr()* 13440 The result is a Number, which is the number of the current 13441 window. The top window has number 1. 13442 Returns zero for a popup window. 13443 13444 The optional argument {arg} supports the following values: 13445 $ the number of the last window (the window 13446 count). 13447 # the number of the last accessed window (where 13448 |CTRL-W_p| goes to). If there is no previous 13449 window or it is in another tab page 0 is 13450 returned. May refer to the current window in 13451 some cases (e.g. when evaluating 'statusline' 13452 expressions). 13453 {N}j the number of the Nth window below the 13454 current window (where |CTRL-W_j| goes to). 13455 {N}k the number of the Nth window above the current 13456 window (where |CTRL-W_k| goes to). 13457 {N}h the number of the Nth window left of the 13458 current window (where |CTRL-W_h| goes to). 13459 {N}l the number of the Nth window right of the 13460 current window (where |CTRL-W_l| goes to). 13461 The number can be used with |CTRL-W_w| and ":wincmd w" 13462 |:wincmd|. 13463 When {arg} is invalid an error is given and zero is returned. 13464 Also see |tabpagewinnr()| and |win_getid()|. 13465 Examples: > 13466 let window_count = winnr('$') 13467 let prev_window = winnr('#') 13468 let wnum = winnr('3k') 13469 13470 < Can also be used as a |method|: > 13471 GetWinval()->winnr() 13472 < 13473 Return type: |Number| 13474 13475 13476 winrestcmd() *winrestcmd()* 13477 Returns a sequence of |:resize| commands that should restore 13478 the current window sizes. Only works properly when no windows 13479 are opened or closed and the current window and tab page is 13480 unchanged. 13481 Example: > 13482 :let cmd = winrestcmd() 13483 :call MessWithWindowSizes() 13484 :exe cmd 13485 < 13486 Return type: |String| 13487 13488 13489 winrestview({dict}) *winrestview()* 13490 Uses the |Dictionary| returned by |winsaveview()| to restore 13491 the view of the current window. 13492 Note: The {dict} does not have to contain all values, that are 13493 returned by |winsaveview()|. If values are missing, those 13494 settings won't be restored. So you can use: > 13495 :call winrestview({'curswant': 4}) 13496 < 13497 This will only set the curswant value (the column the cursor 13498 wants to move on vertical movements) of the cursor to column 5 13499 (yes, that is 5), while all other settings will remain the 13500 same. This is useful, if you set the cursor position 13501 manually. 13502 13503 If you have changed the values the result is unpredictable. 13504 If the window size changed the result won't be the same. 13505 13506 Can also be used as a |method|: > 13507 GetView()->winrestview() 13508 < 13509 Return type: void 13510 13511 13512 winsaveview() *winsaveview()* 13513 Returns a |Dictionary| that contains information to restore 13514 the view of the current window. Use |winrestview()| to 13515 restore the view. 13516 This is useful if you have a mapping that jumps around in the 13517 buffer and you want to go back to the original view. 13518 This does not save fold information. Use the 'foldenable' 13519 option to temporarily switch off folding, so that folds are 13520 not opened when moving around. This may have side effects. 13521 The return value includes: 13522 lnum cursor line number 13523 col cursor column (Note: the first column 13524 zero, as opposed to what |getcurpos()| 13525 returns) 13526 coladd cursor column offset for 'virtualedit' 13527 curswant column for vertical movement (Note: 13528 the first column is zero, as opposed 13529 to what |getcurpos()| returns). After 13530 |$| command it will be a very large 13531 number equal to |v:maxcol|. 13532 topline first line in the window 13533 topfill filler lines, only in diff mode 13534 leftcol first column displayed; only used when 13535 'wrap' is off 13536 skipcol columns skipped 13537 Note that no option values are saved. 13538 13539 Return type: dict<number> 13540 13541 13542 winwidth({nr}) *winwidth()* 13543 The result is a Number, which is the width of window {nr}. 13544 {nr} can be the window number or the |window-ID|. 13545 When {nr} is zero, the width of the current window is 13546 returned. When window {nr} doesn't exist, -1 is returned. 13547 An existing window always has a width of zero or more. 13548 Examples: > 13549 :echo "The current window has " .. winwidth(0) .. " columns." 13550 :if winwidth(0) <= 50 13551 : 50 wincmd | 13552 :endif 13553 < For getting the terminal or screen size, see the 'columns' 13554 option. 13555 13556 Can also be used as a |method|: > 13557 GetWinid()->winwidth() 13558 < 13559 Return type: |Number| 13560 13561 13562 wordcount() *wordcount()* 13563 The result is a dictionary of byte/chars/word statistics for 13564 the current buffer. This is the same info as provided by 13565 |g_CTRL-G| 13566 The return value includes: 13567 bytes Number of bytes in the buffer 13568 chars Number of chars in the buffer 13569 words Number of words in the buffer 13570 cursor_bytes Number of bytes before cursor position 13571 (not in Visual mode) 13572 cursor_chars Number of chars before cursor position 13573 (not in Visual mode) 13574 cursor_words Number of words before cursor position 13575 (not in Visual mode) 13576 visual_bytes Number of bytes visually selected 13577 (only in Visual mode) 13578 visual_chars Number of chars visually selected 13579 (only in Visual mode) 13580 visual_words Number of words visually selected 13581 (only in Visual mode) 13582 13583 Return type: dict<number> 13584 13585 13586 writefile({object}, {fname} [, {flags}]) *writefile()* 13587 When {object} is a |List| write it to file {fname}. Each list 13588 item is separated with a NL. Each list item must be a String 13589 or Number. 13590 All NL characters are replaced with a NUL character. 13591 Inserting CR characters needs to be done before passing {list} 13592 to writefile(). 13593 13594 When {object} is a |Blob| write the bytes to file {fname} 13595 unmodified, also when binary mode is not specified. 13596 13597 {flags} must be a String. These characters are recognized: 13598 13599 'b' Binary mode is used: There will not be a NL after the 13600 last list item. An empty item at the end does cause the 13601 last line in the file to end in a NL. 13602 13603 'a' Append mode is used, lines are appended to the file: > 13604 :call writefile(["foo"], "event.log", "a") 13605 :call writefile(["bar"], "event.log", "a") 13606 < 13607 'D' Delete the file when the current function ends. This 13608 works like: > 13609 :defer delete({fname}) 13610 < Fails when not in a function. Also see |:defer|. 13611 13612 's' fsync() is called after writing the file. This flushes 13613 the file to disk, if possible. This takes more time but 13614 avoids losing the file if the system crashes. 13615 13616 'S' fsync() is not called, even when 'fsync' is set. 13617 13618 When {flags} does not contain "S" or "s" then fsync() is 13619 called if the 'fsync' option is set. 13620 13621 An existing file is overwritten, if possible. 13622 13623 When the write fails -1 is returned, otherwise 0. There is an 13624 error message if the file can't be created or when writing 13625 fails. 13626 13627 Also see |readfile()|. 13628 To copy a file byte for byte: > 13629 :let fl = readfile("foo", "b") 13630 :call writefile(fl, "foocopy", "b") 13631 13632 < Can also be used as a |method|: > 13633 GetText()->writefile("thefile") 13634 < 13635 Return type: |Number| 13636 13637 13638 xor({expr}, {expr}) *xor()* 13639 Bitwise XOR on the two arguments. The arguments are converted 13640 to a number. A List, Dict or Float argument causes an error. 13641 Also see `and()` and `or()`. 13642 Example: > 13643 :let bits = xor(bits, 0x80) 13644 < 13645 Can also be used as a |method|: > 13646 :let bits = bits->xor(0x80) 13647 < 13648 Return type: |Number| 13649 13650 ============================================================================== 13651 3. Feature list *feature-list* 13652 13653 There are three types of features: 13654 1. Features that are only supported when they have been enabled when Vim 13655 was compiled |+feature-list|. Example: > 13656 :if has("cindent") 13657 < *gui_running* 13658 2. Features that are only supported when certain conditions have been met. 13659 Example: > 13660 :if has("gui_running") 13661 < *has-patch* 13662 3. Beyond a certain version or at a certain version and including a specific 13663 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or 13664 later, or it is version 7.4 and patch 248 was included. Example: > 13665 :if has("patch-7.4.248") 13666 < Note that it's possible for patch 248 to be omitted even though 249 is 13667 included. Only happens when cherry-picking patches. 13668 Note that this form only works for patch 7.4.237 and later, before that 13669 you need to check for the patch and the v:version. Example (checking 13670 version 6.2.148 or later): > 13671 :if v:version > 602 || (v:version == 602 && has("patch148")) 13672 13673 Hint: To find out if Vim supports backslashes in a file name (MS-Windows), 13674 use: `if exists('+shellslash')` 13675 13676 13677 acl Compiled with |ACL| support. 13678 all_builtin_terms Compiled with all builtin terminals enabled. (always 13679 true) 13680 amiga Amiga version of Vim. 13681 android Android version of Vim. *android* 13682 arabic Compiled with Arabic support |Arabic|. 13683 arp Compiled with ARP support (Amiga). 13684 autocmd Compiled with autocommand support. (always true) 13685 autochdir Compiled with support for 'autochdir' 13686 autoservername Automatically enable |clientserver| 13687 balloon_eval Compiled with |balloon-eval| support. 13688 balloon_multiline GUI supports multiline balloons. 13689 beos BeOS version of Vim. 13690 browse Compiled with |:browse| support, and |browse()| will 13691 work. 13692 browsefilter Compiled with support for |browsefilter|. 13693 bsd Compiled on an OS in the BSD family (excluding macOS). 13694 builtin_terms Compiled with some builtin terminals. (always true) 13695 byte_offset Compiled with support for 'o' in 'statusline' 13696 channel Compiled with support for |channel| and |job| 13697 cindent Compiled with 'cindent' support. (always true) 13698 clientserver Compiled with remote invocation support |clientserver|. 13699 clipboard Compiled with 'clipboard' support. 13700 clipboard_working Compiled with 'clipboard' support and it can be used. 13701 cmdline_compl Compiled with |cmdline-completion| support. 13702 cmdline_hist Compiled with |cmdline-history| support. 13703 cmdline_info Compiled with 'showcmd' and 'ruler' support. 13704 comments Compiled with 'comments' support. 13705 compatible Compiled to be very Vi compatible. 13706 conpty Platform where |ConPTY| can be used. 13707 cryptv Compiled with encryption support |encryption|. 13708 cscope Compiled with |cscope| support. 13709 cursorbind Compiled with 'cursorbind' (always true) 13710 debug Compiled with "DEBUG" defined. 13711 dialog_con Compiled with console dialog support. 13712 dialog_con_gui Compiled with console and GUI dialog support. 13713 dialog_gui Compiled with GUI dialog support. 13714 diff Compiled with |vimdiff| and 'diff' support. 13715 digraphs Compiled with support for digraphs. 13716 directx Compiled with support for DirectX and 'renderoptions'. 13717 dnd Compiled with support for the "~ register |quote_~|. 13718 drop_file Compiled with |drop_file| support. 13719 ebcdic Compiled on a machine with ebcdic character set. 13720 emacs_tags Compiled with support for Emacs tags. 13721 eval Compiled with expression evaluation support. Always 13722 true, of course! 13723 ex_extra |+ex_extra| (always true) 13724 extra_search Compiled with support for 'incsearch' and 'hlsearch' 13725 farsi Support for Farsi was removed |farsi|. 13726 file_in_path Compiled with support for |gf| and |<cfile>| (always 13727 true) 13728 filterpipe When 'shelltemp' is off pipes are used for shell 13729 read/write/filter commands 13730 find_in_path Compiled with support for include file searches 13731 |+find_in_path|. 13732 float Compiled with support for |Float|. 13733 fname_case Case in file names matters (for Amiga and MS-Windows 13734 this is not present). 13735 folding Compiled with |folding| support. 13736 footer Compiled with GUI footer support. |gui-footer| 13737 fork Compiled to use fork()/exec() instead of system(). 13738 gettext Compiled with message translation |multi-lang| 13739 gui Compiled with GUI enabled. 13740 gui_athena Compiled with Athena GUI (always false). 13741 gui_gnome Compiled with Gnome support (gui_gtk is also defined). 13742 gui_gtk Compiled with GTK+ GUI (any version). 13743 gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined). 13744 gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined). 13745 gui_haiku Compiled with Haiku GUI. 13746 gui_mac Compiled with Macintosh GUI. 13747 gui_motif Compiled with Motif GUI. 13748 gui_photon Compiled with Photon GUI. 13749 gui_running Vim is running in the GUI, or it will start soon. 13750 gui_win32 Compiled with MS-Windows Win32 GUI. 13751 gui_win32s idem, and Win32s system being used (Windows 3.1) 13752 haiku Haiku version of Vim. 13753 hangul_input Compiled with Hangul input support. |hangul| 13754 hpux HP-UX version of Vim. 13755 hurd GNU/Hurd version of Vim 13756 iconv Can use iconv() for conversion. 13757 image Compiled with the popup window "image" attribute. 13758 See |popup-image|. 13759 image_cairo Compiled with the Cairo image backend (GTK2 and GTK3 GUI). 13760 image_gdi Compiled with the GDI image backend (Windows GUI). 13761 image_gdk Compiled with the GDK image backend (GTK4 GUI). 13762 image_kitty Compiled with the kitty graphics protocol image backend 13763 (terminal). 13764 image_sixel Compiled with the DEC sixel image backend (terminal). 13765 insert_expand Compiled with support for CTRL-X expansion commands in 13766 Insert mode. (always true) 13767 job Compiled with support for |channel| and |job| 13768 ipv6 Compiled with support for IPv6 networking in |channel|. 13769 jumplist Compiled with |jumplist| support. (always true) 13770 keymap Compiled with 'keymap' support. 13771 lambda Compiled with |lambda| support. 13772 langmap Compiled with 'langmap' support. 13773 libcall Compiled with |libcall()| support. 13774 linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and 13775 'breakindent' support. 13776 linux Linux version of Vim. 13777 lispindent Compiled with support for lisp indenting. 13778 (always true) 13779 listcmds Compiled with commands for the buffer list |:files| 13780 and the argument list |arglist|. 13781 localmap Compiled with local mappings and abbr. |:map-local| 13782 lua Compiled with Lua interface |Lua|. 13783 mac Any Macintosh version of Vim cf. osx 13784 macunix Synonym for osxdarwin 13785 menu Compiled with support for |:menu|. 13786 mksession Compiled with support for |:mksession|. 13787 modify_fname Compiled with file name modifiers. |filename-modifiers| 13788 (always true) 13789 mouse Compiled with support for mouse. 13790 mouse_dec Compiled with support for Dec terminal mouse. 13791 mouse_gpm Compiled with support for gpm (Linux console mouse) 13792 mouse_gpm_enabled GPM mouse is working 13793 mouse_netterm Compiled with support for netterm mouse. 13794 mouse_pterm Compiled with support for qnx pterm mouse. 13795 mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse) 13796 mouse_sgr Compiled with support for sgr mouse. 13797 mouse_urxvt Compiled with support for urxvt mouse. 13798 mouse_xterm Compiled with support for xterm mouse. 13799 mouseshape Compiled with support for 'mouseshape'. 13800 multi_byte Compiled with support for 'encoding' (always true) 13801 multi_byte_encoding 'encoding' is set to a multibyte encoding. 13802 multi_byte_ime Compiled with support for IME input method. 13803 multi_lang Compiled with support for multiple languages. 13804 mzscheme Compiled with MzScheme interface |mzscheme|. 13805 nanotime Compiled with sub-second time stamp checks. 13806 netbeans_enabled Compiled with support for |netbeans| and connected. 13807 netbeans_intg Compiled with support for |netbeans|. 13808 num64 Compiled with 64-bit |Number| support. (always true) 13809 ole Compiled with OLE automation support for Win32. 13810 osx Compiled for macOS cf. mac 13811 osxdarwin Compiled for macOS, with |mac-darwin-feature| 13812 packages Compiled with |packages| support. 13813 path_extra Compiled with up/downwards search in 'path' and 'tags' 13814 perl Compiled with Perl interface. 13815 persistent_undo Compiled with support for persistent undo history. 13816 postscript Compiled with PostScript file printing. 13817 printer Compiled with |:hardcopy| support. 13818 profile Compiled with |:profile| support. 13819 prof_nsec Profile results are in nanoseconds. 13820 python Python 2.x interface available. |has-python| 13821 python_compiled Compiled with Python 2.x interface. |has-python| 13822 python_dynamic Python 2.x interface is dynamically loaded. |has-python| 13823 python3 Python 3.x interface available. |has-python| 13824 python3_compiled Compiled with Python 3.x interface. |has-python| 13825 python3_dynamic Python 3.x interface is dynamically loaded. |has-python| 13826 python3_stable Python 3.x interface is using Python Stable ABI. 13827 |has-python| 13828 pythonx Python 2.x and/or 3.x interface available. |python_x| 13829 qnx QNX version of Vim. 13830 quickfix Compiled with |quickfix| support. 13831 reltime Compiled with |reltime()| support. 13832 rightleft Compiled with 'rightleft' support. 13833 ruby Compiled with Ruby interface |ruby|. 13834 scrollbind Compiled with 'scrollbind' support. (always true) 13835 showcmd Compiled with 'showcmd' support. 13836 signs Compiled with |:sign| support. 13837 smartindent Compiled with 'smartindent' support. (always true) 13838 socketserver Compiled with socket server functionality. (Unix only) 13839 sodium Compiled with libsodium for better crypt support 13840 sound Compiled with sound support, e.g. `sound_playevent()` 13841 spell Compiled with spell checking support |spell|. 13842 startuptime Compiled with |--startuptime| support. 13843 statusline Compiled with support for 'statusline', 'rulerformat' 13844 and special formats of 'titlestring' and 'iconstring'. 13845 statusline_click Click handlers in 'statusline' |stl-%[FuncName]| 13846 sun SunOS version of Vim. 13847 sun_workshop Support for Sun |workshop| has been removed. 13848 syntax Compiled with syntax highlighting support |syntax|. 13849 syntax_items There are active syntax highlighting items for the 13850 current buffer. 13851 system Compiled to use system() instead of fork()/exec(). 13852 tag_binary Compiled with binary searching in tags files 13853 |tag-binary-search|. (always true) 13854 tag_old_static Support for old static tags was removed, see 13855 |tag-old-static|. 13856 tcl Compiled with Tcl interface. 13857 termguicolors Compiled with true color in terminal support. 13858 terminal Compiled with |terminal| support. 13859 terminfo Compiled with terminfo instead of termcap. 13860 termresponse Compiled with support for |t_RV| and |v:termresponse|. 13861 termux Termux version of Vim. *termux* 13862 textobjects Compiled with support for |text-objects|. 13863 textprop Compiled with support for |text-properties|. 13864 tgetent Compiled with tgetent support, able to use a termcap 13865 or terminfo file. 13866 timers Compiled with |timer_start()| support. 13867 title Compiled with window title support 'title'. 13868 (always true) 13869 toolbar Compiled with support for |gui-toolbar|. 13870 ttyin input is a terminal (tty) 13871 ttyout output is a terminal (tty) 13872 unix Unix version of Vim. *+unix* 13873 unnamedplus Compiled with support for "unnamedplus" in 'clipboard' 13874 user_commands User-defined commands. (always true) 13875 vartabs Compiled with variable tabstop support 'vartabstop'. 13876 vcon Win32: Virtual console support is working, can use 13877 'termguicolors'. Also see |+vtp|. 13878 vertsplit Compiled with vertically split windows |:vsplit|. 13879 (always true) 13880 vim_starting True while initial source'ing takes place. |startup| 13881 *vim_starting* 13882 vim9script Compiled with |Vim9| script support 13883 viminfo Compiled with viminfo support. 13884 vimscript-1 Compiled Vim script version 1 support 13885 vimscript-2 Compiled Vim script version 2 support 13886 vimscript-3 Compiled Vim script version 3 support 13887 vimscript-4 Compiled Vim script version 4 support 13888 virtualedit Compiled with 'virtualedit' option. (always true) 13889 visual Compiled with Visual mode. (always true) 13890 visualextra Compiled with extra Visual mode commands. (always 13891 true) |blockwise-operators|. 13892 vms VMS version of Vim. 13893 vreplace Compiled with |gR| and |gr| commands. (always true) 13894 vtp Compiled for vcon support |+vtp| (check vcon to find 13895 out if it works in the current console). 13896 wayland Compiled with Wayland protocol support. 13897 wayland_clipboard Compiled with support for Wayland clipboard. 13898 wildignore Compiled with 'wildignore' option. 13899 wildmenu Compiled with 'wildmenu' option. 13900 win16 old version for MS-Windows 3.1 (always false) 13901 win32 Win32 version of Vim (MS-Windows 95 and later, 32 or 13902 64 bits) 13903 win32unix Win32 version of Vim, using Unix files (Cygwin) 13904 win64 Win64 version of Vim (MS-Windows 64 bit). 13905 win95 Win32 version for MS-Windows 95/98/ME (always false) 13906 winaltkeys Compiled with 'winaltkeys' option. 13907 windows Compiled with support for more than one window. 13908 (always true) 13909 writebackup Compiled with 'writebackup' default on. 13910 xattr Compiled with extended attributes support |xattr| 13911 (currently only supported on Linux). 13912 xfontset Compiled with X fontset support |xfontset|. 13913 xim Compiled with X input method support |xim|. 13914 xpm Compiled with pixmap support. 13915 xpm_w32 Compiled with pixmap support for Win32. (Only for 13916 backward compatibility. Use "xpm" instead.) 13917 xsmp Compiled with X session management support. 13918 xsmp_interact Compiled with interactive X session management 13919 support. 13920 xterm_clipboard Compiled with support for xterm clipboard. 13921 xterm_save Compiled with support for saving and restoring the 13922 xterm screen. 13923 x11 Compiled with X11 support. 13924 13925 13926 ============================================================================== 13927 4. Matching a pattern in a String *string-match* 13928 13929 This is common between several functions. A regexp pattern as explained at 13930 |pattern| is normally used to find a match in the buffer lines. When a 13931 pattern is used to find a match in a String, almost everything works in the 13932 same way. The difference is that a String is handled like it is one line. 13933 When it contains a "\n" character, this is not seen as a line break for the 13934 pattern. It can be matched with a "\n" in the pattern, or with ".". Example: 13935 > 13936 :let a = "aaaa\nxxxx" 13937 :echo matchstr(a, "..\n..") 13938 aa 13939 xx 13940 :echo matchstr(a, "a.x") 13941 a 13942 x 13943 13944 Don't forget that "^" will only match at the first character of the String and 13945 "$" at the last character of the string. They don't match after or before a 13946 "\n". 13947 13948 vim:tw=78:ts=8:noet:ft=help:norl: