*builtin.txt* For Vim version 9.1. Last change: 2024 Apr 07 VIM REFERENCE MANUAL by Bram Moolenaar Builtin functions *builtin-functions* Note: Expression evaluation can be disabled at compile time, the builtin functions are not available then. See |+eval| and |no-eval-feature|. For functions grouped by what they are used for see |function-list|. 1. Overview |builtin-function-list| 2. Details |builtin-function-details| 3. Feature list |feature-list| 4. Matching a pattern in a String |string-match| ============================================================================== 1. Overview *builtin-function-list* Use CTRL-] on the function name to jump to the full explanation. USAGE RESULT DESCRIPTION ~ abs({expr}) Float or Number absolute value of {expr} acos({expr}) Float arc cosine of {expr} add({object}, {item}) List/Blob append {item} to {object} and({expr}, {expr}) Number bitwise AND append({lnum}, {text}) Number append {text} below line {lnum} appendbufline({expr}, {lnum}, {text}) Number append {text} below line {lnum} in buffer {expr} argc([{winid}]) Number number of files in the argument list argidx() Number current index in the argument list arglistid([{winnr} [, {tabnr}]]) Number argument list id argv({nr} [, {winid}]) String {nr} entry of the argument list argv([-1, {winid}]) List the argument list asin({expr}) Float arc sine of {expr} assert_beeps({cmd}) Number assert {cmd} causes a beep assert_equal({exp}, {act} [, {msg}]) Number assert {exp} is equal to {act} assert_equalfile({fname-one}, {fname-two} [, {msg}]) Number assert file contents are equal assert_exception({error} [, {msg}]) Number assert {error} is in v:exception assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]]) Number assert {cmd} fails assert_false({actual} [, {msg}]) Number assert {actual} is false assert_inrange({lower}, {upper}, {actual} [, {msg}]) Number assert {actual} is inside the range assert_match({pat}, {text} [, {msg}]) Number assert {pat} matches {text} assert_nobeep({cmd}) Number assert {cmd} does not cause a beep assert_notequal({exp}, {act} [, {msg}]) Number assert {exp} is not equal {act} assert_notmatch({pat}, {text} [, {msg}]) Number assert {pat} not matches {text} assert_report({msg}) Number report a test failure assert_true({actual} [, {msg}]) Number assert {actual} is true atan({expr}) Float arc tangent of {expr} atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2} autocmd_add({acmds}) Bool add a list of autocmds and groups autocmd_delete({acmds}) Bool delete a list of autocmds and groups autocmd_get([{opts}]) List return a list of autocmds balloon_gettext() String current text in the balloon balloon_show({expr}) none show {expr} inside the balloon balloon_split({msg}) List split {msg} as used for a balloon blob2list({blob}) List convert {blob} into a list of numbers browse({save}, {title}, {initdir}, {default}) String put up a file requester browsedir({title}, {initdir}) String put up a directory requester bufadd({name}) Number add a buffer to the buffer list bufexists({buf}) Number |TRUE| if buffer {buf} exists buflisted({buf}) Number |TRUE| if buffer {buf} is listed bufload({buf}) Number load buffer {buf} if not loaded yet bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded bufname([{buf}]) String Name of the buffer {buf} bufnr([{buf} [, {create}]]) Number Number of the buffer {buf} bufwinid({buf}) Number window ID of buffer {buf} bufwinnr({buf}) Number window number of buffer {buf} byte2line({byte}) Number line number at byte count {byte} byteidx({expr}, {nr} [, {utf16}]) Number byte index of {nr}'th char in {expr} byteidxcomp({expr}, {nr} [, {utf16}]) Number byte index of {nr}'th char in {expr} call({func}, {arglist} [, {dict}]) any call {func} with arguments {arglist} ceil({expr}) Float round {expr} up ch_canread({handle}) Number check if there is something to read ch_close({handle}) none close {handle} ch_close_in({handle}) none close in part of {handle} ch_evalexpr({handle}, {expr} [, {options}]) any evaluate {expr} on JSON {handle} ch_evalraw({handle}, {string} [, {options}]) any evaluate {string} on raw {handle} ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what} ch_getjob({channel}) Job get the Job of {channel} ch_info({handle}) String info about channel {handle} ch_log({msg} [, {handle}]) none write {msg} in the channel log file ch_logfile({fname} [, {mode}]) none start logging channel activity ch_open({address} [, {options}]) Channel open a channel to {address} ch_read({handle} [, {options}]) String read from {handle} ch_readblob({handle} [, {options}]) Blob read Blob from {handle} ch_readraw({handle} [, {options}]) String read raw from {handle} ch_sendexpr({handle}, {expr} [, {options}]) any send {expr} over JSON {handle} ch_sendraw({handle}, {expr} [, {options}]) any send {expr} over raw {handle} ch_setoptions({handle}, {options}) none set options for {handle} ch_status({handle} [, {options}]) String status of channel {handle} changenr() Number current change number char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr} charclass({string}) Number character class of {string} charcol({expr} [, {winid}]) Number column number of cursor or mark charidx({string}, {idx} [, {countcc} [, {utf16}]]) Number char index of byte {idx} in {string} chdir({dir}) String change current working directory cindent({lnum}) Number C indent for line {lnum} clearmatches([{win}]) none clear all matches col({expr} [, {winid}]) Number column byte index of cursor or mark complete({startcol}, {matches}) none set Insert mode completion complete_add({expr}) Number add completion match complete_check() Number check for key typed during completion complete_info([{what}]) Dict get current completion information confirm({msg} [, {choices} [, {default} [, {type}]]]) Number number of choice picked by user copy({expr}) any make a shallow copy of {expr} cos({expr}) Float cosine of {expr} cosh({expr}) Float hyperbolic cosine of {expr} count({comp}, {expr} [, {ic} [, {start}]]) Number count how many {expr} are in {comp} cscope_connection([{num}, {dbpath} [, {prepend}]]) Number checks existence of cscope connection cursor({lnum}, {col} [, {off}]) Number move cursor to {lnum}, {col}, {off} cursor({list}) Number move cursor to position in {list} debugbreak({pid}) Number interrupt process being debugged deepcopy({expr} [, {noref}]) any make a full copy of {expr} delete({fname} [, {flags}]) Number delete the file or directory {fname} deletebufline({buf}, {first} [, {last}]) Number delete lines from buffer {buf} did_filetype() Number |TRUE| if FileType autocmd event used diff({fromlist}, {tolist} [, {options}]) List diff two Lists of strings diff_filler({lnum}) Number diff filler lines about {lnum} diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col} digraph_get({chars}) String get the |digraph| of {chars} digraph_getlist([{listall}]) List get all |digraph|s digraph_set({chars}, {digraph}) Boolean register |digraph| digraph_setlist({digraphlist}) Boolean register multiple |digraph|s echoraw({expr}) none output {expr} as-is empty({expr}) Number |TRUE| if {expr} is empty environ() Dict return environment variables err_teapot([{expr}]) none give E418, or E503 if {expr} is |TRUE| escape({string}, {chars}) String escape {chars} in {string} with '\' eval({string}) any evaluate {string} into its value eventhandler() Number |TRUE| if inside an event handler executable({expr}) Number 1 if executable {expr} exists execute({command}) String execute {command} and get the output exepath({expr}) String full path of the command {expr} exists({expr}) Number |TRUE| if {expr} exists exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time exp({expr}) Float exponential of {expr} expand({expr} [, {nosuf} [, {list}]]) any expand special keywords in {expr} expandcmd({string} [, {options}]) String expand {string} like with `:edit` extend({expr1}, {expr2} [, {expr3}]) List/Dict insert items of {expr2} into {expr1} extendnew({expr1}, {expr2} [, {expr3}]) List/Dict like |extend()| but creates a new List or Dictionary feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer filereadable({file}) Number |TRUE| if {file} is a readable file filewritable({file}) Number |TRUE| if {file} is a writable file filter({expr1}, {expr2}) List/Dict/Blob/String remove items from {expr1} where {expr2} is 0 finddir({name} [, {path} [, {count}]]) String find directory {name} in {path} findfile({name} [, {path} [, {count}]]) String find file {name} in {path} flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels flattennew({list} [, {maxdepth}]) List flatten a copy of {list} float2nr({expr}) Number convert Float {expr} to a Number floor({expr}) Float round {expr} down fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2} fnameescape({fname}) String escape special characters in {fname} fnamemodify({fname}, {mods}) String modify file name foldclosed({lnum}) Number first line of fold at {lnum} if closed foldclosedend({lnum}) Number last line of fold at {lnum} if closed foldlevel({lnum}) Number fold level at {lnum} foldtext() String line displayed for closed fold foldtextresult({lnum}) String text for closed fold at {lnum} foreach({expr1}, {expr2}) List/Dict/Blob/String for each item in {expr1} call {expr2} foreground() Number bring the Vim window to the foreground fullcommand({name} [, {vim9}]) String get full command from {name} funcref({name} [, {arglist}] [, {dict}]) Funcref reference to function {name} function({name} [, {arglist}] [, {dict}]) Funcref named reference to function {name} garbagecollect([{atexit}]) none free memory, breaking cyclic references get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def} get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def} get({func}, {what}) any get property of funcref/partial {func} getbufinfo([{buf}]) List information about buffers getbufline({buf}, {lnum} [, {end}]) List lines {lnum} to {end} of buffer {buf} getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf} getbufvar({buf}, {varname} [, {def}]) any variable {varname} in buffer {buf} getcellwidths() List get character cell width overrides getchangelist([{buf}]) List list of change list items getchar([{expr}]) Number or String get one character from the user getcharmod() Number modifiers for the last typed character getcharpos({expr}) List position of cursor, mark, etc. getcharsearch() Dict last character search getcharstr([{expr}]) String get one character from the user getcmdcompltype() String return the type of the current command-line completion getcmdline() String return the current command-line getcmdpos() Number return cursor position in command-line getcmdscreenpos() Number return cursor screen position in command-line getcmdtype() String return current command-line type getcmdwintype() String return current command-line window type getcompletion({pat}, {type} [, {filtered}]) List list of cmdline completion matches getcurpos([{winnr}]) List position of the cursor getcursorcharpos([{winnr}]) List character position of the cursor getcwd([{winnr} [, {tabnr}]]) String get the current working directory getenv({name}) String return environment variable getfontname([{name}]) String name of font being used getfperm({fname}) String file permissions of file {fname} getfsize({fname}) Number size in bytes of file {fname} getftime({fname}) Number last modification time of file getftype({fname}) String description of type of file {fname} getimstatus() Number |TRUE| if the IME status is active getjumplist([{winnr} [, {tabnr}]]) List list of jump list items getline({lnum}) String line {lnum} of current buffer getline({lnum}, {end}) List lines {lnum} to {end} of current buffer getloclist({nr}) List list of location list items getloclist({nr}, {what}) Dict get specific location list properties getmarklist([{buf}]) List list of global/local marks getmatches([{win}]) List list of current matches getmousepos() Dict last known mouse position getmouseshape() String current mouse shape name getpid() Number process ID of Vim getpos({expr}) List position of cursor, mark, etc. getqflist() List list of quickfix items getqflist({what}) Dict get specific quickfix list properties getreg([{regname} [, 1 [, {list}]]]) String or List contents of a register getreginfo([{regname}]) Dict information about a register getregion({pos1}, {pos2} [, {opts}]) List get the text from {pos1} to {pos2} getregtype([{regname}]) String type of a register getscriptinfo([{opts}]) List list of sourced scripts gettabinfo([{expr}]) List list of tab pages gettabvar({nr}, {varname} [, {def}]) any variable {varname} in tab {nr} or {def} gettabwinvar({tabnr}, {winnr}, {name} [, {def}]) any {name} in {winnr} in tab page {tabnr} gettagstack([{nr}]) Dict get the tag stack of window {nr} gettext({text}) String lookup translation of {text} getwininfo([{winid}]) List list of info about each window getwinpos([{timeout}]) List X and Y coord in pixels of Vim window getwinposx() Number X coord in pixels of the Vim window getwinposy() Number Y coord in pixels of the Vim window getwinvar({nr}, {varname} [, {def}]) any variable {varname} in window {nr} glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) any expand file wildcards in {expr} glob2regpat({expr}) String convert a glob pat into a search pat globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) String do glob({expr}) for all dirs in {path} has({feature} [, {check}]) Number |TRUE| if feature {feature} supported has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key} haslocaldir([{winnr} [, {tabnr}]]) Number |TRUE| if the window executed |:lcd| or |:tcd| hasmapto({what} [, {mode} [, {abbr}]]) Number |TRUE| if mapping to {what} exists histadd({history}, {item}) Number add an item to a history histdel({history} [, {item}]) Number remove an item from a history histget({history} [, {index}]) String get the item {index} from a history histnr({history}) Number highest index of a history hlID({name}) Number syntax ID of highlight group {name} hlexists({name}) Number |TRUE| if highlight group {name} exists hlget([{name} [, {resolve}]]) List get highlight group attributes hlset({list}) Number set highlight group attributes hostname() String name of the machine Vim is running on iconv({expr}, {from}, {to}) String convert encoding of {expr} indent({lnum}) Number indent of line {lnum} index({object}, {expr} [, {start} [, {ic}]]) Number index in {object} where {expr} appears indexof({object}, {expr} [, {opts}]]) Number index in {object} where {expr} is true input({prompt} [, {text} [, {completion}]]) String get input from the user inputdialog({prompt} [, {text} [, {cancelreturn}]]) String like input() but in a GUI dialog inputlist({textlist}) Number let the user pick from a choice list inputrestore() Number restore typeahead inputsave() Number save and clear typeahead inputsecret({prompt} [, {text}]) String like input() but hiding the text insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}] instanceof({object}, {class}) Number |TRUE| if {object} is an instance of {class} interrupt() none interrupt script execution invert({expr}) Number bitwise invert isabsolutepath({path}) Number |TRUE| if {path} is an absolute path isdirectory({directory}) Number |TRUE| if {directory} is a directory isinf({expr}) Number determine if {expr} is infinity value (positive or negative) islocked({expr}) Number |TRUE| if {expr} is locked isnan({expr}) Number |TRUE| if {expr} is NaN items({dict}) List key-value pairs in {dict} job_getchannel({job}) Channel get the channel handle for {job} job_info([{job}]) Dict get information about {job} job_setoptions({job}, {options}) none set options for {job} job_start({command} [, {options}]) Job start a job job_status({job}) String get the status of {job} job_stop({job} [, {how}]) Number stop {job} join({list} [, {sep}]) String join {list} items into one String js_decode({string}) any decode JS style JSON js_encode({expr}) String encode JS style JSON json_decode({string}) any decode JSON json_encode({expr}) String encode JSON keys({dict}) List keys in {dict} keytrans({string}) String translate internal keycodes to a form that can be used by |:map| len({expr}) Number the length of {expr} libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg} libcallnr({lib}, {func}, {arg}) Number idem, but return a Number line({expr} [, {winid}]) Number line nr of cursor, last line or mark line2byte({lnum}) Number byte count of line {lnum} lispindent({lnum}) Number Lisp indent for line {lnum} list2blob({list}) Blob turn {list} of numbers into a Blob list2str({list} [, {utf8}]) String turn {list} of numbers into a String listener_add({callback} [, {buf}]) Number add a callback to listen to changes listener_flush([{buf}]) none invoke listener callbacks listener_remove({id}) none remove a listener callback localtime() Number current time log({expr}) Float natural logarithm (base e) of {expr} log10({expr}) Float logarithm of Float {expr} to base 10 luaeval({expr} [, {expr}]) any evaluate |Lua| expression map({expr1}, {expr2}) List/Dict/Blob/String change each item in {expr1} to {expr2} maparg({name} [, {mode} [, {abbr} [, {dict}]]]) String or Dict rhs of mapping {name} in mode {mode} mapcheck({name} [, {mode} [, {abbr}]]) String check for mappings matching {name} maplist([{abbr}]) List list of all mappings, a dict for each mapnew({expr1}, {expr2}) List/Dict/Blob/String like |map()| but creates a new List or Dictionary mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result match({expr}, {pat} [, {start} [, {count}]]) Number position where {pat} matches in {expr} matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) Number highlight {pattern} with {group} matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) Number highlight positions with {group} matcharg({nr}) List arguments of |:match| matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}) List all the {pat} matches in buffer {buf} matchdelete({id} [, {win}]) Number delete match identified by {id} matchend({expr}, {pat} [, {start} [, {count}]]) Number position where {pat} ends in {expr} matchfuzzy({list}, {str} [, {dict}]) List fuzzy match {str} in {list} matchfuzzypos({list}, {str} [, {dict}]) List fuzzy match {str} in {list} matchlist({expr}, {pat} [, {start} [, {count}]]) List match and submatches of {pat} in {expr} matchstr({expr}, {pat} [, {start} [, {count}]]) String {count}'th match of {pat} in {expr} matchstrlist({list}, {pat} [, {dict}) List all the {pat} matches in {list} matchstrpos({expr}, {pat} [, {start} [, {count}]]) List {count}'th match of {pat} in {expr} max({expr}) Number maximum value of items in {expr} menu_info({name} [, {mode}]) Dict get menu item information min({expr}) Number minimum value of items in {expr} mkdir({name} [, {flags} [, {prot}]]) Number create directory {name} mode([{expr}]) String current editing mode mzeval({expr}) any evaluate |MzScheme| expression nextnonblank({lnum}) Number line nr of non-blank line >= {lnum} nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr} or({expr}, {expr}) Number bitwise OR pathshorten({expr} [, {len}]) String shorten directory names in a path perleval({expr}) any evaluate |Perl| expression popup_atcursor({what}, {options}) Number create popup window near the cursor popup_beval({what}, {options}) Number create popup window for 'ballooneval' popup_clear() none close all popup windows popup_close({id} [, {result}]) none close popup window {id} popup_create({what}, {options}) Number create a popup window popup_dialog({what}, {options}) Number create a popup window used as a dialog popup_filter_menu({id}, {key}) Number filter for a menu popup window popup_filter_yesno({id}, {key}) Number filter for a dialog popup window popup_findecho() Number get window ID of popup for `:echowin` popup_findinfo() Number get window ID of info popup window popup_findpreview() Number get window ID of preview popup window popup_getoptions({id}) Dict get options of popup window {id} popup_getpos({id}) Dict get position of popup window {id} popup_hide({id}) none hide popup menu {id} popup_list() List get a list of window IDs of all popups popup_locate({row}, {col}) Number get window ID of popup at position popup_menu({what}, {options}) Number create a popup window used as a menu popup_move({id}, {options}) none set position of popup window {id} popup_notification({what}, {options}) Number create a notification popup window popup_setoptions({id}, {options}) none set options for popup window {id} popup_settext({id}, {text}) none set the text of popup window {id} popup_show({id}) none unhide popup window {id} pow({x}, {y}) Float {x} to the power of {y} prevnonblank({lnum}) Number line nr of non-blank line <= {lnum} printf({fmt}, {expr1}...) String format text prompt_getprompt({buf}) String get prompt text prompt_setcallback({buf}, {expr}) none set prompt callback function prompt_setinterrupt({buf}, {text}) none set prompt interrupt function prompt_setprompt({buf}, {text}) none set prompt text prop_add({lnum}, {col}, {props}) none add one text property prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) none add multiple text properties prop_clear({lnum} [, {lnum-end} [, {props}]]) none remove all text properties prop_find({props} [, {direction}]) Dict search for a text property prop_list({lnum} [, {props}]) List text properties in {lnum} prop_remove({props} [, {lnum} [, {lnum-end}]]) Number remove a text property prop_type_add({name}, {props}) none define a new property type prop_type_change({name}, {props}) none change an existing property type prop_type_delete({name} [, {props}]) none delete a property type prop_type_get({name} [, {props}]) Dict get property type values prop_type_list([{props}]) List get list of property types pum_getpos() Dict position and size of pum if visible pumvisible() Number whether popup menu is visible py3eval({expr}) any evaluate |python3| expression pyeval({expr}) any evaluate |Python| expression pyxeval({expr}) any evaluate |python_x| expression rand([{expr}]) Number get pseudo-random number range({expr} [, {max} [, {stride}]]) List items from {expr} to {max} readblob({fname} [, {offset} [, {size}]]) Blob read a |Blob| from {fname} readdir({dir} [, {expr} [, {dict}]]) List file names in {dir} selected by {expr} readdirex({dir} [, {expr} [, {dict}]]) List file info in {dir} selected by {expr} readfile({fname} [, {type} [, {max}]]) List get list of lines from file {fname} reduce({object}, {func} [, {initial}]) any reduce {object} using {func} reg_executing() String get the executing register name reg_recording() String get the recording register name reltime([{start} [, {end}]]) List get time value reltimefloat({time}) Float turn the time value into a Float reltimestr({time}) String turn time value into a String remote_expr({server}, {string} [, {idvar} [, {timeout}]]) String send expression remote_foreground({server}) Number bring Vim server to the foreground remote_peek({serverid} [, {retvar}]) Number check for reply string remote_read({serverid} [, {timeout}]) String read reply string remote_send({server}, {string} [, {idvar}]) String send key sequence remote_startserver({name}) none become server {name} remove({list}, {idx} [, {end}]) any/List remove items {idx}-{end} from {list} remove({blob}, {idx} [, {end}]) Number/Blob remove bytes {idx}-{end} from {blob} remove({dict}, {key}) any remove entry {key} from {dict} rename({from}, {to}) Number rename (move) file from {from} to {to} repeat({expr}, {count}) List/Blob/String repeat {expr} {count} times resolve({filename}) String get filename a shortcut points to reverse({obj}) List/Blob/String reverse {obj} round({expr}) Float round off {expr} rubyeval({expr}) any evaluate |Ruby| expression screenattr({row}, {col}) Number attribute at screen position screenchar({row}, {col}) Number character at screen position screenchars({row}, {col}) List List of characters at screen position screencol() Number current cursor column screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character screenrow() Number current cursor row screenstring({row}, {col}) String characters at screen position search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) Number search for {pattern} searchcount([{options}]) Dict get or update search stats searchdecl({name} [, {global} [, {thisblock}]]) Number search for variable declaration searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) Number search for other end of start/end pair searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) List search for other end of start/end pair searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) List search for {pattern} server2client({clientid}, {string}) Number send reply string serverlist() String get a list of available servers setbufline({expr}, {lnum}, {text}) Number set line {lnum} to {text} in buffer {expr} setbufvar({buf}, {varname}, {val}) none set {varname} in buffer {buf} to {val} setcellwidths({list}) none set character cell width overrides setcharpos({expr}, {list}) Number set the {expr} position to {list} setcharsearch({dict}) Dict set character search from {dict} setcmdline({str} [, {pos}]) Number set command-line setcmdpos({pos}) Number set cursor position in command-line setcursorcharpos({list}) Number move cursor to position in {list} setenv({name}, {val}) none set environment variable setfperm({fname}, {mode}) Number set {fname} file permissions to {mode} setline({lnum}, {line}) Number set line {lnum} to {line} setloclist({nr}, {list} [, {action}]) Number modify location list using {list} setloclist({nr}, {list}, {action}, {what}) Number modify specific location list props setmatches({list} [, {win}]) Number restore a list of matches setpos({expr}, {list}) Number set the {expr} position to {list} setqflist({list} [, {action}]) Number modify quickfix list using {list} setqflist({list}, {action}, {what}) Number modify specific quickfix list props setreg({n}, {v} [, {opt}]) Number set register to value and type settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val} settabwinvar({tabnr}, {winnr}, {varname}, {val}) none set {varname} in window {winnr} in tab page {tabnr} to {val} settagstack({nr}, {dict} [, {action}]) Number modify tag stack using {dict} setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val} sha256({string}) String SHA256 checksum of {string} shellescape({string} [, {special}]) String escape {string} for use as shell command argument shiftwidth([{col}]) Number effective value of 'shiftwidth' sign_define({name} [, {dict}]) Number define or update a sign sign_define({list}) List define or update a list of signs sign_getdefined([{name}]) List get a list of defined signs sign_getplaced([{buf} [, {dict}]]) List get a list of placed signs sign_jump({id}, {group}, {buf}) Number jump to a sign sign_place({id}, {group}, {name}, {buf} [, {dict}]) Number place a sign sign_placelist({list}) List place a list of signs sign_undefine([{name}]) Number undefine a sign sign_undefine({list}) List undefine a list of signs sign_unplace({group} [, {dict}]) Number unplace a sign sign_unplacelist({list}) List unplace a list of signs simplify({filename}) String simplify filename as much as possible sin({expr}) Float sine of {expr} sinh({expr}) Float hyperbolic sine of {expr} slice({expr}, {start} [, {end}]) String, List or Blob slice of a String, List or Blob sort({list} [, {how} [, {dict}]]) List sort {list}, compare with {how} sound_clear() none stop playing all sounds sound_playevent({name} [, {callback}]) Number play an event sound sound_playfile({path} [, {callback}]) Number play sound file {path} sound_stop({id}) none stop playing sound {id} soundfold({word}) String sound-fold {word} spellbadword() String badly spelled word at cursor spellsuggest({word} [, {max} [, {capital}]]) List spelling suggestions split({expr} [, {pat} [, {keepempty}]]) List make |List| from {pat} separated {expr} sqrt({expr}) Float square root of {expr} srand([{expr}]) List get seed for |rand()| state([{what}]) String current state of Vim str2float({expr} [, {quoted}]) Float convert String to Float str2list({expr} [, {utf8}]) List convert each character of {expr} to ASCII/UTF-8 value str2nr({expr} [, {base} [, {quoted}]]) Number convert String to Number strcharlen({expr}) Number character length of the String {expr} strcharpart({str}, {start} [, {len} [, {skipcc}]]) String {len} characters of {str} at character {start} strchars({expr} [, {skipcc}]) Number character count of the String {expr} strdisplaywidth({expr} [, {col}]) Number display length of the String {expr} strftime({format} [, {time}]) String format time with a specified format strgetchar({str}, {index}) Number get char {index} from {str} stridx({haystack}, {needle} [, {start}]) Number index of {needle} in {haystack} string({expr}) String String representation of {expr} value strlen({expr}) Number length of the String {expr} strpart({str}, {start} [, {len} [, {chars}]]) String {len} bytes/chars of {str} at byte {start} strptime({format}, {timestring}) Number Convert {timestring} to unix timestamp strridx({haystack}, {needle} [, {start}]) Number last index of {needle} in {haystack} strtrans({expr}) String translate string to make it printable strutf16len({string} [, {countcc}]) Number number of UTF-16 code units in {string} strwidth({expr}) Number display cell length of the String {expr} submatch({nr} [, {list}]) String or List specific match in ":s" or substitute() substitute({expr}, {pat}, {sub}, {flags}) String all {pat} in {expr} replaced with {sub} swapfilelist() List swap files found in 'directory' swapinfo({fname}) Dict information about swap file {fname} swapname({buf}) String swap file of buffer {buf} synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col} synIDattr({synID}, {what} [, {mode}]) String attribute {what} of syntax ID {synID} synIDtrans({synID}) Number translated syntax ID of {synID} synconcealed({lnum}, {col}) List info about concealing synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col} system({expr} [, {input}]) String output of shell command/filter {expr} systemlist({expr} [, {input}]) List output of shell command/filter {expr} tabpagebuflist([{arg}]) List list of buffer numbers in tab page tabpagenr([{arg}]) Number number of current or last tab page tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page tagfiles() List tags files used taglist({expr} [, {filename}]) List list of tags matching {expr} tan({expr}) Float tangent of {expr} tanh({expr}) Float hyperbolic tangent of {expr} tempname() String name for a temporary file term_dumpdiff({filename}, {filename} [, {options}]) Number display difference between two dumps term_dumpload({filename} [, {options}]) Number displaying a screen dump term_dumpwrite({buf}, {filename} [, {options}]) none dump terminal window contents term_getaltscreen({buf}) Number get the alternate screen flag term_getansicolors({buf}) List get ANSI palette in GUI color mode term_getattr({attr}, {what}) Number get the value of attribute {what} term_getcursor({buf}) List get the cursor position of a terminal term_getjob({buf}) Job get the job associated with a terminal term_getline({buf}, {row}) String get a line of text from a terminal term_getscrolled({buf}) Number get the scroll count of a terminal term_getsize({buf}) List get the size of a terminal term_getstatus({buf}) String get the status of a terminal term_gettitle({buf}) String get the title of a terminal term_gettty({buf}, [{input}]) String get the tty name of a terminal term_list() List get the list of terminal buffers term_scrape({buf}, {row}) List get row of a terminal screen term_sendkeys({buf}, {keys}) none send keystrokes to a terminal term_setansicolors({buf}, {colors}) none set ANSI palette in GUI color mode term_setapi({buf}, {expr}) none set |terminal-api| function name prefix term_setkill({buf}, {how}) none set signal to stop job in terminal term_setrestore({buf}, {command}) none set command to restore terminal term_setsize({buf}, {rows}, {cols}) none set the size of a terminal term_start({cmd} [, {options}]) Number open a terminal window and run a job term_wait({buf} [, {time}]) Number wait for screen to be updated terminalprops() Dict properties of the terminal test_alloc_fail({id}, {countdown}, {repeat}) none make memory allocation fail test_autochdir() none enable 'autochdir' during startup test_feedinput({string}) none add key sequence to input buffer test_garbagecollect_now() none free memory right now for testing test_garbagecollect_soon() none free memory soon for testing test_getvalue({string}) any get value of an internal variable test_gui_event({event}, {args}) bool generate a GUI event for testing test_ignore_error({expr}) none ignore a specific error test_mswin_event({event}, {args}) bool generate MS-Windows event for testing test_null_blob() Blob null value for testing test_null_channel() Channel null value for testing test_null_dict() Dict null value for testing test_null_function() Funcref null value for testing test_null_job() Job null value for testing test_null_list() List null value for testing test_null_partial() Funcref null value for testing test_null_string() String null value for testing test_option_not_set({name}) none reset flag indicating option was set test_override({expr}, {val}) none test with Vim internal overrides test_refcount({expr}) Number get the reference count of {expr} test_setmouse({row}, {col}) none set the mouse position for testing test_settime({expr}) none set current time for testing test_srand_seed([{seed}]) none set seed for testing srand() test_unknown() any unknown value for testing test_void() any void value for testing timer_info([{id}]) List information about timers timer_pause({id}, {pause}) none pause or unpause a timer timer_start({time}, {callback} [, {options}]) Number create a timer timer_stop({timer}) none stop a timer timer_stopall() none stop all timers tolower({expr}) String the String {expr} switched to lowercase toupper({expr}) String the String {expr} switched to uppercase tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr} to chars in {tostr} trim({text} [, {mask} [, {dir}]]) String trim characters in {mask} from {text} trunc({expr}) Float truncate Float {expr} type({expr}) Number type of value {expr} typename({expr}) String representation of the type of {expr} undofile({name}) String undo file name for {name} undotree([{buf}]) List undo file tree for buffer {buf} uniq({list} [, {func} [, {dict}]]) List remove adjacent duplicates from a list utf16idx({string}, {idx} [, {countcc} [, {charidx}]]) Number UTF-16 index of byte {idx} in {string} values({dict}) List values in {dict} virtcol({expr} [, {list} [, {winid}]) Number or List screen column of cursor or mark virtcol2col({winid}, {lnum}, {col}) Number byte index of a character on screen visualmode([{expr}]) String last visual mode used wildmenumode() Number whether 'wildmenu' mode is active win_execute({id}, {command} [, {silent}]) String execute {command} in window {id} win_findbuf({bufnr}) List find windows containing {bufnr} win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab} win_gettype([{nr}]) String type of window {nr} win_gotoid({expr}) Number go to window with ID {expr} win_id2tabwin({expr}) List get tab and window nr from window ID win_id2win({expr}) Number get window nr from window ID win_move_separator({nr}) Number move window vertical separator win_move_statusline({nr}) Number move window status line win_screenpos({nr}) List get screen position of window {nr} win_splitmove({nr}, {target} [, {options}]) Number move window {nr} to split of {target} winbufnr({nr}) Number buffer number of window {nr} wincol() Number window column of the cursor windowsversion() String MS-Windows OS version winheight({nr}) Number height of window {nr} winlayout([{tabnr}]) List layout of windows in tab {tabnr} winline() Number window line of the cursor winnr([{expr}]) Number number of current window winrestcmd() String returns command to restore window sizes winrestview({dict}) none restore view of current window winsaveview() Dict save view of current window winwidth({nr}) Number width of window {nr} wordcount() Dict get byte/char/word statistics writefile({object}, {fname} [, {flags}]) Number write |Blob| or |List| of lines to file xor({expr}, {expr}) Number bitwise XOR ============================================================================== 2. Details *builtin-function-details* Not all functions are here, some have been moved to a help file covering the specific functionality. abs({expr}) *abs()* Return the absolute value of {expr}. When {expr} evaluates to a |Float| abs() returns a |Float|. When {expr} can be converted to a |Number| abs() returns a |Number|. Otherwise abs() gives an error message and returns -1. Examples: > echo abs(1.456) < 1.456 > echo abs(-5.456) < 5.456 > echo abs(-4) < 4 Can also be used as a |method|: > Compute()->abs() acos({expr}) *acos()* Return the arc cosine of {expr} measured in radians, as a |Float| in the range of [0, pi]. {expr} must evaluate to a |Float| or a |Number| in the range [-1, 1]. Otherwise acos() returns "nan". Examples: > :echo acos(0) < 1.570796 > :echo acos(-0.5) < 2.094395 Can also be used as a |method|: > Compute()->acos() add({object}, {expr}) *add()* Append the item {expr} to |List| or |Blob| {object}. Returns the resulting |List| or |Blob|. Examples: > :let alist = add([1, 2, 3], item) :call add(mylist, "woodstock") < Note that when {expr} is a |List| it is appended as a single item. Use |extend()| to concatenate |Lists|. When {object} is a |Blob| then {expr} must be a number. Use |insert()| to add an item at another position. Returns 1 if {object} is not a |List| or a |Blob|. Can also be used as a |method|: > mylist->add(val1)->add(val2) and({expr}, {expr}) *and()* Bitwise AND on the two arguments. The arguments are converted to a number. A List, Dict or Float argument causes an error. Also see `or()` and `xor()`. Example: > :let flag = and(bits, 0x80) < Can also be used as a |method|: > :let flag = bits->and(0x80) append({lnum}, {text}) *append()* When {text} is a |List|: Append each item of the |List| as a text line below line {lnum} in the current buffer. Otherwise append {text} as one text line below line {lnum} in the current buffer. Any type of item is accepted and converted to a String. {lnum} can be zero to insert a line before the first one. {lnum} is used like with |getline()|. Returns 1 for failure ({lnum} out of range or out of memory), 0 for success. When {text} is an empty list zero is returned, no matter the value of {lnum}. In |Vim9| script an invalid argument or negative number results in an error. Example: > :let failed = append(line('$'), "# THE END") :let failed = append(0, ["Chapter 1", "the beginning"]) < Can also be used as a |method| after a List, the base is passed as the second argument: > mylist->append(lnum) appendbufline({buf}, {lnum}, {text}) *appendbufline()* Like |append()| but append the text in buffer {buf}. This function works only for loaded buffers. First call |bufload()| if needed. For the use of {buf}, see |bufname()|. {lnum} is the line number to append below. Note that using |line()| would use the current buffer, not the one appending to. Use "$" to append at the end of the buffer. Other string values are not supported. On success 0 is returned, on failure 1 is returned. In |Vim9| script an error is given for an invalid {lnum}. If {buf} is not a valid buffer or {lnum} is not valid, an error message is given. Example: > :let failed = appendbufline(13, 0, "# THE START") < However, when {text} is an empty list then no error is given for an invalid {lnum}, since {lnum} isn't actually used. Can also be used as a |method| after a List, the base is passed as the second argument: > mylist->appendbufline(buf, lnum) argc([{winid}]) *argc()* The result is the number of files in the argument list. See |arglist|. If {winid} is not supplied, the argument list of the current window is used. If {winid} is -1, the global argument list is used. Otherwise {winid} specifies the window of which the argument list is used: either the window number or the window ID. Returns -1 if the {winid} argument is invalid. *argidx()* argidx() The result is the current index in the argument list. 0 is the first file. argc() - 1 is the last one. See |arglist|. *arglistid()* arglistid([{winnr} [, {tabnr}]]) Return the argument list ID. This is a number which identifies the argument list being used. Zero is used for the global argument list. See |arglist|. Returns -1 if the arguments are invalid. Without arguments use the current window. With {winnr} only use this window in the current tab page. With {winnr} and {tabnr} use the window in the specified tab page. {winnr} can be the window number or the |window-ID|. *argv()* argv([{nr} [, {winid}]]) The result is the {nr}th file in the argument list. See |arglist|. "argv(0)" is the first one. Example: > :let i = 0 :while i < argc() : let f = escape(fnameescape(argv(i)), '.') : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '' : let i = i + 1 :endwhile < Without the {nr} argument, or when {nr} is -1, a |List| with the whole |arglist| is returned. The {winid} argument specifies the window ID, see |argc()|. For the Vim command line arguments see |v:argv|. Returns an empty string if {nr}th argument is not present in the argument list. Returns an empty List if the {winid} argument is invalid. asin({expr}) *asin()* Return the arc sine of {expr} measured in radians, as a |Float| in the range of [-pi/2, pi/2]. {expr} must evaluate to a |Float| or a |Number| in the range [-1, 1]. Returns "nan" if {expr} is outside the range [-1, 1]. Returns 0.0 if {expr} is not a |Float| or a |Number|. Examples: > :echo asin(0.8) < 0.927295 > :echo asin(-0.5) < -0.523599 Can also be used as a |method|: > Compute()->asin() assert_ functions are documented here: |assert-functions-details| atan({expr}) *atan()* Return the principal value of the arc tangent of {expr}, in the range [-pi/2, +pi/2] radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. Examples: > :echo atan(100) < 1.560797 > :echo atan(-4.01) < -1.326405 Can also be used as a |method|: > Compute()->atan() atan2({expr1}, {expr2}) *atan2()* Return the arc tangent of {expr1} / {expr2}, measured in radians, as a |Float| in the range [-pi, pi]. {expr1} and {expr2} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr1} or {expr2} is not a |Float| or a |Number|. Examples: > :echo atan2(-1, 1) < -0.785398 > :echo atan2(1, -1) < 2.356194 Can also be used as a |method|: > Compute()->atan2(1) autocmd_add({acmds}) *autocmd_add()* Adds a List of autocmds and autocmd groups. The {acmds} argument is a List where each item is a Dict with the following optional items: bufnr buffer number to add a buffer-local autocmd. If this item is specified, then the "pattern" item is ignored. cmd Ex command to execute for this autocmd event event autocmd event name. Refer to |autocmd-events|. This can be either a String with a single event name or a List of event names. group autocmd group name. Refer to |autocmd-groups|. If this group doesn't exist then it is created. If not specified or empty, then the default group is used. nested boolean flag, set to v:true to add a nested autocmd. Refer to |autocmd-nested|. once boolean flag, set to v:true to add an autocmd which executes only once. Refer to |autocmd-once|. pattern autocmd pattern string. Refer to |autocmd-patterns|. If "bufnr" item is present, then this item is ignored. This can be a String with a single pattern or a List of patterns. replace boolean flag, set to v:true to remove all the commands associated with the specified autocmd event and group and add the {cmd}. This is useful to avoid adding the same command multiple times for an autocmd event in a group. Returns v:true on success and v:false on failure. Examples: > " Create a buffer-local autocmd for buffer 5 let acmd = {} let acmd.group = 'MyGroup' let acmd.event = 'BufEnter' let acmd.bufnr = 5 let acmd.cmd = 'call BufEnterFunc()' call autocmd_add([acmd]) < Can also be used as a |method|: > GetAutocmdList()->autocmd_add() < autocmd_delete({acmds}) *autocmd_delete()* Deletes a List of autocmds and autocmd groups. The {acmds} argument is a List where each item is a Dict with the following optional items: bufnr buffer number to delete a buffer-local autocmd. If this item is specified, then the "pattern" item is ignored. cmd Ex command for this autocmd event event autocmd event name. Refer to |autocmd-events|. If '*' then all the autocmd events in this group are deleted. group autocmd group name. Refer to |autocmd-groups|. If not specified or empty, then the default group is used. nested set to v:true for a nested autocmd. Refer to |autocmd-nested|. once set to v:true for an autocmd which executes only once. Refer to |autocmd-once|. pattern autocmd pattern string. Refer to |autocmd-patterns|. If "bufnr" item is present, then this item is ignored. If only {group} is specified in a {acmds} entry and {event}, {pattern} and {cmd} are not specified, then that autocmd group is deleted. Returns |v:true| on success and |v:false| on failure. Examples: > " :autocmd! BufLeave *.vim let acmd = #{event: 'BufLeave', pattern: '*.vim'} call autocmd_delete([acmd]}) " :autocmd! MyGroup1 BufLeave let acmd = #{group: 'MyGroup1', event: 'BufLeave'} call autocmd_delete([acmd]) " :autocmd! MyGroup2 BufEnter *.c let acmd = #{group: 'MyGroup2', event: 'BufEnter', \ pattern: '*.c'} " :autocmd! MyGroup2 * *.c let acmd = #{group: 'MyGroup2', event: '*', \ pattern: '*.c'} call autocmd_delete([acmd]) " :autocmd! MyGroup3 let acmd = #{group: 'MyGroup3'} call autocmd_delete([acmd]) < Can also be used as a |method|: > GetAutocmdList()->autocmd_delete() autocmd_get([{opts}]) *autocmd_get()* Returns a |List| of autocmds. If {opts} is not supplied, then returns the autocmds for all the events in all the groups. The optional {opts} Dict argument supports the following items: group Autocmd group name. If specified, returns only the autocmds defined in this group. If the specified group doesn't exist, results in an error message. If set to an empty string, then the default autocmd group is used. event Autocmd event name. If specified, returns only the autocmds defined for this event. If set to "*", then returns autocmds for all the events. If the specified event doesn't exist, results in an error message. pattern Autocmd pattern. If specified, returns only the autocmds defined for this pattern. A combination of the above three times can be supplied in {opts}. Each Dict in the returned List contains the following items: bufnr For buffer-local autocmds, buffer number where the autocmd is defined. cmd Command executed for this autocmd. event Autocmd event name. group Autocmd group name. nested Boolean flag, set to v:true for a nested autocmd. See |autocmd-nested|. once Boolean flag, set to v:true, if the autocmd will be executed only once. See |autocmd-once|. pattern Autocmd pattern. For a buffer-local autocmd, this will be of the form "". If there are multiple commands for an autocmd event in a group, then separate items are returned for each command. Returns an empty List if an autocmd with the specified group or event or pattern is not found. Examples: > " :autocmd MyGroup echo autocmd_get(#{group: 'Mygroup'}) " :autocmd G BufUnload echo autocmd_get(#{group: 'G', event: 'BufUnload'}) " :autocmd G * *.ts let acmd = #{group: 'G', event: '*', pattern: '*.ts'} echo autocmd_get(acmd) " :autocmd Syntax echo autocmd_get(#{event: 'Syntax'}) " :autocmd G BufEnter *.ts let acmd = #{group: 'G', event: 'BufEnter', \ pattern: '*.ts'} echo autocmd_get(acmd) < Can also be used as a |method|: > Getopts()->autocmd_get() < balloon_gettext() *balloon_gettext()* Return the current text in the balloon. Only for the string, not used for the List. Returns an empty string if balloon is not present. balloon_show({expr}) *balloon_show()* Show {expr} inside the balloon. For the GUI {expr} is used as a string. For a terminal {expr} can be a list, which contains the lines of the balloon. If {expr} is not a list it will be split with |balloon_split()|. If {expr} is an empty string any existing balloon is removed. Example: > func GetBalloonContent() " ... initiate getting the content return '' endfunc set balloonexpr=GetBalloonContent() func BalloonCallback(result) call balloon_show(a:result) endfunc < Can also be used as a |method|: > GetText()->balloon_show() < The intended use is that fetching the content of the balloon is initiated from 'balloonexpr'. It will invoke an asynchronous method, in which a callback invokes balloon_show(). The 'balloonexpr' itself can return an empty string or a placeholder, e.g. "loading...". When showing a balloon is not possible then nothing happens, no error message is given. {only available when compiled with the |+balloon_eval| or |+balloon_eval_term| feature} balloon_split({msg}) *balloon_split()* Split String {msg} into lines to be displayed in a balloon. The splits are made for the current window size and optimize to show debugger output. Returns a |List| with the split lines. Returns an empty List on error. Can also be used as a |method|: > GetText()->balloon_split()->balloon_show() < {only available when compiled with the |+balloon_eval_term| feature} blob2list({blob}) *blob2list()* Return a List containing the number value of each byte in Blob {blob}. Examples: > blob2list(0z0102.0304) returns [1, 2, 3, 4] blob2list(0z) returns [] < Returns an empty List on error. |list2blob()| does the opposite. Can also be used as a |method|: > GetBlob()->blob2list() < *browse()* browse({save}, {title}, {initdir}, {default}) Put up a file requester. This only works when "has("browse")" returns |TRUE| (only in some GUI versions). The input fields are: {save} when |TRUE|, select file to write {title} title for the requester {initdir} directory to start browsing in {default} default file name An empty string is returned when the "Cancel" button is hit, something went wrong, or browsing is not possible. *browsedir()* browsedir({title}, {initdir}) Put up a directory requester. This only works when "has("browse")" returns |TRUE| (only in some GUI versions). On systems where a directory browser is not supported a file browser is used. In that case: select a file in the directory to be used. The input fields are: {title} title for the requester {initdir} directory to start browsing in When the "Cancel" button is hit, something went wrong, or browsing is not possible, an empty string is returned. bufadd({name}) *bufadd()* Add a buffer to the buffer list with name {name} (must be a String). If a buffer for file {name} already exists, return that buffer number. Otherwise return the buffer number of the newly created buffer. When {name} is an empty string then a new buffer is always created. The buffer will not have 'buflisted' set and not be loaded yet. To add some text to the buffer use this: > let bufnr = bufadd('someName') call bufload(bufnr) call setbufline(bufnr, 1, ['some', 'text']) < Returns 0 on error. Can also be used as a |method|: > let bufnr = 'somename'->bufadd() bufexists({buf}) *bufexists()* The result is a Number, which is |TRUE| if a buffer called {buf} exists. If the {buf} argument is a number, buffer numbers are used. Number zero is the alternate buffer for the current window. If the {buf} argument is a string it must match a buffer name exactly. The name can be: - Relative to the current directory. - A full path. - The name of a buffer with 'buftype' set to "nofile". - A URL name. Unlisted buffers will be found. Note that help files are listed by their short name in the output of |:buffers|, but bufexists() requires using their long name to be able to find them. bufexists() may report a buffer exists, but to use the name with a |:buffer| command you may need to use |expand()|. Esp for MS-Windows 8.3 names in the form "c:\DOCUME~1" Use "bufexists(0)" to test for the existence of an alternate file name. Can also be used as a |method|: > let exists = 'somename'->bufexists() < Obsolete name: buffer_exists(). *buffer_exists()* buflisted({buf}) *buflisted()* The result is a Number, which is |TRUE| if a buffer called {buf} exists and is listed (has the 'buflisted' option set). The {buf} argument is used like with |bufexists()|. Can also be used as a |method|: > let listed = 'somename'->buflisted() bufload({buf}) *bufload()* Ensure the buffer {buf} is loaded. When the buffer name refers to an existing file then the file is read. Otherwise the buffer will be empty. If the buffer was already loaded then there is no change. If the buffer is not related to a file then no file is read (e.g., when 'buftype' is "nofile"). If there is an existing swap file for the file of the buffer, there will be no dialog, the buffer will be loaded anyway. The {buf} argument is used like with |bufexists()|. Can also be used as a |method|: > eval 'somename'->bufload() bufloaded({buf}) *bufloaded()* The result is a Number, which is |TRUE| if a buffer called {buf} exists and is loaded (shown in a window or hidden). The {buf} argument is used like with |bufexists()|. Can also be used as a |method|: > let loaded = 'somename'->bufloaded() bufname([{buf}]) *bufname()* The result is the name of a buffer. Mostly as it is displayed by the `:ls` command, but not using special names such as "[No Name]". If {buf} is omitted the current buffer is used. If {buf} is a Number, that buffer number's name is given. Number zero is the alternate buffer for the current window. If {buf} is a String, it is used as a |file-pattern| to match with the buffer names. This is always done like 'magic' is set and 'cpoptions' is empty. When there is more than one match an empty string is returned. "" or "%" can be used for the current buffer, "#" for the alternate buffer. A full match is preferred, otherwise a match at the start, end or middle of the buffer name is accepted. If you only want a full match then put "^" at the start and "$" at the end of the pattern. Listed buffers are found first. If there is a single match with a listed buffer, that one is returned. Next unlisted buffers are searched for. If the {buf} is a String, but you want to use it as a buffer number, force it to be a Number by adding zero to it: > :echo bufname("3" + 0) < Can also be used as a |method|: > echo bufnr->bufname() < If the buffer doesn't exist, or doesn't have a name, an empty string is returned. > bufname("#") alternate buffer name bufname(3) name of buffer 3 bufname("%") name of current buffer bufname("file2") name of buffer where "file2" matches. < *buffer_name()* Obsolete name: buffer_name(). *bufnr()* bufnr([{buf} [, {create}]]) The result is the number of a buffer, as it is displayed by the `:ls` command. For the use of {buf}, see |bufname()| above. If the buffer doesn't exist, -1 is returned. Or, if the {create} argument is present and TRUE, a new, unlisted, buffer is created and its number is returned. Example: > let newbuf = bufnr('Scratch001', 1) < Using an empty name uses the current buffer. To create a new buffer with an empty name use |bufadd()|. bufnr("$") is the last buffer: > :let last_buffer = bufnr("$") < The result is a Number, which is the highest buffer number of existing buffers. Note that not all buffers with a smaller number necessarily exist, because ":bwipeout" may have removed them. Use bufexists() to test for the existence of a buffer. Can also be used as a |method|: > echo bufref->bufnr() < Obsolete name: buffer_number(). *buffer_number()* *last_buffer_nr()* Obsolete name for bufnr("$"): last_buffer_nr(). bufwinid({buf}) *bufwinid()* The result is a Number, which is the |window-ID| of the first window associated with buffer {buf}. For the use of {buf}, see |bufname()| above. If buffer {buf} doesn't exist or there is no such window, -1 is returned. Example: > echo "A window containing buffer 1 is " .. (bufwinid(1)) < Only deals with the current tab page. See |win_findbuf()| for finding more. Can also be used as a |method|: > FindBuffer()->bufwinid() bufwinnr({buf}) *bufwinnr()* Like |bufwinid()| but return the window number instead of the |window-ID|. If buffer {buf} doesn't exist or there is no such window, -1 is returned. Example: > echo "A window containing buffer 1 is " .. (bufwinnr(1)) < The number can be used with |CTRL-W_w| and ":wincmd w" |:wincmd|. Can also be used as a |method|: > FindBuffer()->bufwinnr() byte2line({byte}) *byte2line()* Return the line number that contains the character at byte count {byte} in the current buffer. This includes the end-of-line character, depending on the 'fileformat' option for the current buffer. The first character has byte count one. Also see |line2byte()|, |go| and |:goto|. Returns -1 if the {byte} value is invalid. Can also be used as a |method|: > GetOffset()->byte2line() < {not available when compiled without the |+byte_offset| feature} byteidx({expr}, {nr} [, {utf16}]) *byteidx()* Return byte index of the {nr}'th character in the String {expr}. Use zero for the first character, it then returns zero. If there are no multibyte characters the returned value is equal to {nr}. Composing characters are not counted separately, their byte length is added to the preceding base character. See |byteidxcomp()| below for counting composing characters separately. When {utf16} is present and TRUE, {nr} is used as the UTF-16 index in the String {expr} instead of as the character index. The UTF-16 index is the index in the string when it is encoded with 16-bit words. If the specified UTF-16 index is in the middle of a character (e.g. in a 4-byte character), then the byte index of the first byte in the character is returned. Refer to |string-offset-encoding| for more information. Example : > echo matchstr(str, ".", byteidx(str, 3)) < will display the fourth character. Another way to do the same: > let s = strpart(str, byteidx(str, 3)) echo strpart(s, 0, byteidx(s, 1)) < Also see |strgetchar()| and |strcharpart()|. If there are less than {nr} characters -1 is returned. If there are exactly {nr} characters the length of the string in bytes is returned. See |charidx()| and |utf16idx()| for getting the character and UTF-16 index respectively from the byte index. Examples: > echo byteidx('a😊😊', 2) returns 5 echo byteidx('a😊😊', 2, 1) returns 1 echo byteidx('a😊😊', 3, 1) returns 5 < Can also be used as a |method|: > GetName()->byteidx(idx) byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()* Like byteidx(), except that a composing character is counted as a separate character. Example: > let s = 'e' .. nr2char(0x301) echo byteidx(s, 1) echo byteidxcomp(s, 1) echo byteidxcomp(s, 2) < The first and third echo result in 3 ('e' plus composing character is 3 bytes), the second echo results in 1 ('e' is one byte). Only works differently from byteidx() when 'encoding' is set to a Unicode encoding. Can also be used as a |method|: > GetName()->byteidxcomp(idx) call({func}, {arglist} [, {dict}]) *call()* *E699* Call function {func} with the items in |List| {arglist} as arguments. {func} can either be a |Funcref| or the name of a function. a:firstline and a:lastline are set to the cursor line. Returns the return value of the called function. {dict} is for functions with the "dict" attribute. It will be used to set the local variable "self". |Dictionary-function| Can also be used as a |method|: > GetFunc()->call([arg, arg], dict) ceil({expr}) *ceil()* Return the smallest integral value greater than or equal to {expr} as a |Float| (round up). {expr} must evaluate to a |Float| or a |Number|. Examples: > echo ceil(1.456) < 2.0 > echo ceil(-5.456) < -5.0 > echo ceil(4.0) < 4.0 Returns 0.0 if {expr} is not a |Float| or a |Number|. Can also be used as a |method|: > Compute()->ceil() ch_ functions are documented here: |channel-functions-details| changenr() *changenr()* Return the number of the most recent change. This is the same number as what is displayed with |:undolist| and can be used with the |:undo| command. When a change was made it is the number of that change. After redo it is the number of the redone change. After undo it is one less than the number of the undone change. Returns 0 if the undo list is empty. char2nr({string} [, {utf8}]) *char2nr()* Return Number value of the first char in {string}. Examples: > char2nr(" ") returns 32 char2nr("ABC") returns 65 < When {utf8} is omitted or zero, the current 'encoding' is used. Example for "utf-8": > char2nr("Γ‘") returns 225 char2nr("Γ‘"[0]) returns 195 < When {utf8} is TRUE, always treat as UTF-8 characters. A combining character is a separate character. |nr2char()| does the opposite. To turn a string into a list of character numbers: > let str = "ABC" let list = map(split(str, '\zs'), {_, val -> char2nr(val)}) < Result: [65, 66, 67] Returns 0 if {string} is not a |String|. Can also be used as a |method|: > GetChar()->char2nr() charclass({string}) *charclass()* Return the character class of the first character in {string}. The character class is one of: 0 blank 1 punctuation 2 word character 3 emoji other specific Unicode class The class is used in patterns and word motions. Returns 0 if {string} is not a |String|. charcol({expr} [, {winid}]) *charcol()* Same as |col()| but returns the character index of the column position given with {expr} instead of the byte position. Example: With the cursor on 'μ„Έ' in line 5 with text "μ—¬λ³΄μ„Έμš”": > charcol('.') returns 3 col('.') returns 7 < Can also be used as a |method|: > GetPos()->col() < *charidx()* charidx({string}, {idx} [, {countcc} [, {utf16}]]) Return the character index of the byte at {idx} in {string}. The index of the first character is zero. If there are no multibyte characters the returned value is equal to {idx}. When {countcc} is omitted or |FALSE|, then composing characters are not counted separately, their byte length is added to the preceding base character. When {countcc} is |TRUE|, then composing characters are counted as separate characters. When {utf16} is present and TRUE, {idx} is used as the UTF-16 index in the String {expr} instead of as the byte index. Returns -1 if the arguments are invalid or if there are less than {idx} bytes. If there are exactly {idx} bytes the length of the string in characters is returned. An error is given and -1 is returned if the first argument is not a string, the second argument is not a number or when the third argument is present and is not zero or one. See |byteidx()| and |byteidxcomp()| for getting the byte index from the character index and |utf16idx()| for getting the UTF-16 index from the character index. Refer to |string-offset-encoding| for more information. Examples: > echo charidx('áb́ć', 3) returns 1 echo charidx('áb́ć', 6, 1) returns 4 echo charidx('áb́ć', 16) returns -1 echo charidx('a😊😊', 4, 0, 1) returns 2 < Can also be used as a |method|: > GetName()->charidx(idx) chdir({dir}) *chdir()* Change the current working directory to {dir}. The scope of the directory change depends on the directory of the current window: - If the current window has a window-local directory (|:lcd|), then changes the window local directory. - Otherwise, if the current tabpage has a local directory (|:tcd|) then changes the tabpage local directory. - Otherwise, changes the global directory. {dir} must be a String. If successful, returns the previous working directory. Pass this to another chdir() to restore the directory. On failure, returns an empty string. Example: > let save_dir = chdir(newdir) if save_dir != "" " ... do some work call chdir(save_dir) endif < Can also be used as a |method|: > GetDir()->chdir() < cindent({lnum}) *cindent()* Get the amount of indent for line {lnum} according the C indenting rules, as with 'cindent'. The indent is counted in spaces, the value of 'tabstop' is relevant. {lnum} is used just like in |getline()|. When {lnum} is invalid -1 is returned. See |C-indenting|. Can also be used as a |method|: > GetLnum()->cindent() clearmatches([{win}]) *clearmatches()* Clears all matches previously defined for the current window by |matchadd()| and the |:match| commands. If {win} is specified, use the window with this number or window ID instead of the current window. Can also be used as a |method|: > GetWin()->clearmatches() < col({expr} [, {winid}]) *col()* The result is a Number, which is the byte index of the column position given with {expr}. The accepted positions are: . the cursor position $ the end of the cursor line (the result is the number of bytes in the cursor line plus one) 'x position of mark x (if the mark is not set, 0 is returned) v In Visual mode: the start of the Visual area (the cursor is the end). When not in Visual mode returns the cursor position. Differs from |'<| in that it's updated right away. Additionally {expr} can be [lnum, col]: a |List| with the line and column number. Most useful when the column is "$", to get the last column of a specific line. When "lnum" or "col" is out of range then col() returns zero. With the optional {winid} argument the values are obtained for that window instead of the current window. To get the line number use |line()|. To get both use |getpos()|. For the screen column position use |virtcol()|. For the character position use |charcol()|. Note that only marks in the current file can be used. Examples: > col(".") column of cursor col("$") length of cursor line plus one col("'t") column of mark t col("'" .. markname) column of mark markname < The first column is 1. Returns 0 if {expr} is invalid or when the window with ID {winid} is not found. For an uppercase mark the column may actually be in another buffer. For the cursor position, when 'virtualedit' is active, the column is one higher if the cursor is after the end of the line. Also, when using a mapping the cursor isn't moved, this can be used to obtain the column in Insert mode: > :imap echowin col(".") < Can also be used as a |method|: > GetPos()->col() < complete({startcol}, {matches}) *complete()* *E785* Set the matches for Insert mode completion. Can only be used in Insert mode. You need to use a mapping with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O or with an expression mapping. {startcol} is the byte offset in the line where the completed text start. The text up to the cursor is the original text that will be replaced by the matches. Use col('.') for an empty string. "col('.') - 1" will replace one character by a match. {matches} must be a |List|. Each |List| item is one match. See |complete-items| for the kind of items that are possible. "longest" in 'completeopt' is ignored. Note that the after calling this function you need to avoid inserting anything that would cause completion to stop. The match can be selected with CTRL-N and CTRL-P as usual with Insert mode completion. The popup menu will appear if specified, see |ins-completion-menu|. Example: > inoremap =ListMonths() func ListMonths() call complete(col('.'), ['January', 'February', 'March', \ 'April', 'May', 'June', 'July', 'August', 'September', \ 'October', 'November', 'December']) return '' endfunc < This isn't very useful, but it shows how it works. Note that an empty string is returned to avoid a zero being inserted. Can also be used as a |method|, the base is passed as the second argument: > GetMatches()->complete(col('.')) complete_add({expr}) *complete_add()* Add {expr} to the list of matches. Only to be used by the function specified with the 'completefunc' option. Returns 0 for failure (empty string or out of memory), 1 when the match was added, 2 when the match was already in the list. See |complete-functions| for an explanation of {expr}. It is the same as one item in the list that 'omnifunc' would return. Can also be used as a |method|: > GetMoreMatches()->complete_add() complete_check() *complete_check()* Check for a key typed while looking for completion matches. This is to be used when looking for matches takes some time. Returns |TRUE| when searching for matches is to be aborted, zero otherwise. Only to be used by the function specified with the 'completefunc' option. complete_info([{what}]) *complete_info()* Returns a |Dictionary| with information about Insert mode completion. See |ins-completion|. The items are: mode Current completion mode name string. See |complete_info_mode| for the values. pum_visible |TRUE| if popup menu is visible. See |pumvisible()|. items List of completion matches. Each item is a dictionary containing the entries "word", "abbr", "menu", "kind", "info" and "user_data". See |complete-items|. selected Selected item index. First index is zero. Index is -1 if no item is selected (showing typed text only, or the last completion after no item is selected when using the or keys) inserted Inserted string. [NOT IMPLEMENTED YET] *complete_info_mode* mode values are: "" Not in completion mode "keyword" Keyword completion |i_CTRL-X_CTRL-N| "ctrl_x" Just pressed CTRL-X |i_CTRL-X| "scroll" Scrolling with |i_CTRL-X_CTRL-E| or |i_CTRL-X_CTRL-Y| "whole_line" Whole lines |i_CTRL-X_CTRL-L| "files" File names |i_CTRL-X_CTRL-F| "tags" Tags |i_CTRL-X_CTRL-]| "path_defines" Definition completion |i_CTRL-X_CTRL-D| "path_patterns" Include completion |i_CTRL-X_CTRL-I| "dictionary" Dictionary |i_CTRL-X_CTRL-K| "thesaurus" Thesaurus |i_CTRL-X_CTRL-T| "cmdline" Vim Command line |i_CTRL-X_CTRL-V| "function" User defined completion |i_CTRL-X_CTRL-U| "omni" Omni completion |i_CTRL-X_CTRL-O| "spell" Spelling suggestions |i_CTRL-X_s| "eval" |complete()| completion "unknown" Other internal modes If the optional {what} list argument is supplied, then only the items listed in {what} are returned. Unsupported items in {what} are silently ignored. To get the position and size of the popup menu, see |pum_getpos()|. It's also available in |v:event| during the |CompleteChanged| event. Returns an empty |Dictionary| on error. Examples: > " Get all items call complete_info() " Get only 'mode' call complete_info(['mode']) " Get only 'mode' and 'pum_visible' call complete_info(['mode', 'pum_visible']) < Can also be used as a |method|: > GetItems()->complete_info() < *confirm()* confirm({msg} [, {choices} [, {default} [, {type}]]]) confirm() offers the user a dialog, from which a choice can be made. It returns the number of the choice. For the first choice this is 1. Note: confirm() is only supported when compiled with dialog support, see |+dialog_con| |+dialog_con_gui| and |+dialog_gui|. {msg} is displayed in a |dialog| with {choices} as the alternatives. When {choices} is missing or empty, "&OK" is used (and translated). {msg} is a String, use '\n' to include a newline. Only on some systems the string is wrapped when it doesn't fit. {choices} is a String, with the individual choices separated by '\n', e.g. > confirm("Save changes?", "&Yes\n&No\n&Cancel") < The letter after the '&' is the shortcut key for that choice. Thus you can type 'c' to select "Cancel". The shortcut does not need to be the first letter: > confirm("file has been modified", "&Save\nSave &All") < For the console, the first letter of each choice is used as the default shortcut key. Case is ignored. The optional {default} argument is the number of the choice that is made if the user hits . Use 1 to make the first choice the default one. Use 0 to not set a default. If {default} is omitted, 1 is used. The optional {type} String argument gives the type of dialog. This is only used for the icon of the GTK, Mac, Motif and Win32 GUI. It can be one of these values: "Error", "Question", "Info", "Warning" or "Generic". Only the first character is relevant. When {type} is omitted, "Generic" is used. If the user aborts the dialog by pressing , CTRL-C, or another valid interrupt key, confirm() returns 0. An example: > let choice = confirm("What do you want?", \ "&Apples\n&Oranges\n&Bananas", 2) if choice == 0 echo "make up your mind!" elseif choice == 3 echo "tasteful" else echo "I prefer bananas myself." endif < In a GUI dialog, buttons are used. The layout of the buttons depends on the 'v' flag in 'guioptions'. If it is included, the buttons are always put vertically. Otherwise, confirm() tries to put the buttons in one horizontal line. If they don't fit, a vertical layout is used anyway. For some systems the horizontal layout is always used. Can also be used as a |method|in: > BuildMessage()->confirm("&Yes\n&No") < *copy()* copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't different from using {expr} directly. When {expr} is a |List| a shallow copy is created. This means that the original |List| can be changed without changing the copy, and vice versa. But the items are identical, thus changing an item changes the contents of both |Lists|. A |Dictionary| is copied in a similar way as a |List|. Also see |deepcopy()|. Can also be used as a |method|: > mylist->copy() cos({expr}) *cos()* Return the cosine of {expr}, measured in radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. Examples: > :echo cos(100) < 0.862319 > :echo cos(-4.01) < -0.646043 Can also be used as a |method|: > Compute()->cos() cosh({expr}) *cosh()* Return the hyperbolic cosine of {expr} as a |Float| in the range [1, inf]. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. Examples: > :echo cosh(0.5) < 1.127626 > :echo cosh(-0.5) < -1.127626 Can also be used as a |method|: > Compute()->cosh() count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706* Return the number of times an item with value {expr} appears in |String|, |List| or |Dictionary| {comp}. If {start} is given then start with the item with this index. {start} can only be used with a |List|. When {ic} is given and it's |TRUE| then case is ignored. When {comp} is a string then the number of not overlapping occurrences of {expr} is returned. Zero is returned when {expr} is an empty string. Can also be used as a |method|: > mylist->count(val) < *cscope_connection()* cscope_connection([{num} , {dbpath} [, {prepend}]]) Checks for the existence of a |cscope| connection. If no parameters are specified, then the function returns: 0, if cscope was not available (not compiled in), or if there are no cscope connections; 1, if there is at least one cscope connection. If parameters are specified, then the value of {num} determines how existence of a cscope connection is checked: {num} Description of existence check ----- ------------------------------ 0 Same as no parameters (e.g., "cscope_connection()"). 1 Ignore {prepend}, and use partial string matches for {dbpath}. 2 Ignore {prepend}, and use exact string matches for {dbpath}. 3 Use {prepend}, use partial string matches for both {dbpath} and {prepend}. 4 Use {prepend}, use exact string matches for both {dbpath} and {prepend}. Note: All string comparisons are case sensitive! Examples. Suppose we had the following (from ":cs show"): > # pid database name prepend path 0 27664 cscope.out /usr/local < Invocation Return Val ~ ---------- ---------- > cscope_connection() 1 cscope_connection(1, "out") 1 cscope_connection(2, "out") 0 cscope_connection(3, "out") 0 cscope_connection(3, "out", "local") 1 cscope_connection(4, "out") 0 cscope_connection(4, "out", "local") 0 cscope_connection(4, "cscope.out", "/usr/local") 1 < cursor({lnum}, {col} [, {off}]) *cursor()* cursor({list}) Positions the cursor at the column (byte count) {col} in the line {lnum}. The first column is one. When there is one argument {list} this is used as a |List| with two, three or four item: [{lnum}, {col}] [{lnum}, {col}, {off}] [{lnum}, {col}, {off}, {curswant}] This is like the return value of |getpos()| or |getcurpos()|, but without the first item. To position the cursor using {col} as the character count, use |setcursorcharpos()|. Does not change the jumplist. {lnum} is used like with |getline()|, except that if {lnum} is zero, the cursor will stay in the current line. If {lnum} is greater than the number of lines in the buffer, the cursor will be positioned at the last line in the buffer. If {col} is greater than the number of bytes in the line, the cursor will be positioned at the last character in the line. If {col} is zero, the cursor will stay in the current column. If {curswant} is given it is used to set the preferred column for vertical movement. Otherwise {col} is used. When 'virtualedit' is used {off} specifies the offset in screen columns from the start of the character. E.g., a position within a or after the last character. Returns 0 when the position could be set, -1 otherwise. Can also be used as a |method|: > GetCursorPos()->cursor() debugbreak({pid}) *debugbreak()* Specifically used to interrupt a program being debugged. It will cause process {pid} to get a SIGTRAP. Behavior for other processes is undefined. See |terminal-debugger|. {only available on MS-Windows} Returns |TRUE| if successfully interrupted the program. Otherwise returns |FALSE|. Can also be used as a |method|: > GetPid()->debugbreak() deepcopy({expr} [, {noref}]) *deepcopy()* *E698* Make a copy of {expr}. For Numbers and Strings this isn't different from using {expr} directly. When {expr} is a |List| a full copy is created. This means that the original |List| can be changed without changing the copy, and vice versa. When an item is a |List| or |Dictionary|, a copy for it is made, recursively. Thus changing an item in the copy does not change the contents of the original |List|. A |Dictionary| is copied in a similar way as a |List|. When {noref} is omitted or zero a contained |List| or |Dictionary| is only copied once. All references point to this single copy. With {noref} set to 1 every occurrence of a |List| or |Dictionary| results in a new copy. This also means that a cyclic reference causes deepcopy() to fail. *E724* Nesting is possible up to 100 levels. When there is an item that refers back to a higher level making a deep copy with {noref} set to 1 will fail. Also see |copy()|. Can also be used as a |method|: > GetObject()->deepcopy() delete({fname} [, {flags}]) *delete()* Without {flags} or with {flags} empty: Deletes the file by the name {fname}. This also works when {fname} is a symbolic link. The symbolic link itself is deleted, not what it points to. When {flags} is "d": Deletes the directory by the name {fname}. This fails when directory {fname} is not empty. When {flags} is "rf": Deletes the directory by the name {fname} and everything in it, recursively. BE CAREFUL! Note: on MS-Windows it is not possible to delete a directory that is being used. The result is a Number, which is 0/false if the delete operation was successful and -1/true when the deletion failed or partly failed. Use |remove()| to delete an item from a |List|. To delete a line from the buffer use |:delete| or |deletebufline()|. Can also be used as a |method|: > GetName()->delete() deletebufline({buf}, {first} [, {last}]) *deletebufline()* Delete lines {first} to {last} (inclusive) from buffer {buf}. If {last} is omitted then delete line {first} only. On success 0 is returned, on failure 1 is returned. This function works only for loaded buffers. First call |bufload()| if needed. For the use of {buf}, see |bufname()| above. {first} and {last} are used like with |getline()|. Note that when using |line()| this refers to the current buffer. Use "$" to refer to the last line in buffer {buf}. Can also be used as a |method|: > GetBuffer()->deletebufline(1) < *did_filetype()* did_filetype() Returns |TRUE| when autocommands are being executed and the FileType event has been triggered at least once. Can be used to avoid triggering the FileType event again in the scripts that detect the file type. |FileType| Returns |FALSE| when `:setf FALLBACK` was used. When editing another file, the counter is reset, thus this really checks if the FileType event has been triggered for the current buffer. This allows an autocommand that starts editing another buffer to set 'filetype' and load a syntax file. diff({fromlist}, {tolist} [, {options}]) *diff()* Returns a String or a List containing the diff between the strings in {fromlist} and {tolist}. Uses the Vim internal diff library to compute the diff. *E106* The optional "output" item in {options} specifies the returned diff format. The following values are supported: indices Return a List of the starting and ending indices and a count of the strings in each diff hunk. unified Return the unified diff output as a String. This is the default. If the "output" item in {options} is "indices", then a List is returned. Each List item contains a Dict with the following items for each diff hunk: from_idx start index in {fromlist} for this diff hunk. from_count number of strings in {fromlist} that are added/removed/modified in this diff hunk. to_idx start index in {tolist} for this diff hunk. to_count number of strings in {tolist} that are added/removed/modified in this diff hunk. The {options} Dict argument also specifies diff options (similar to 'diffopt') and supports the following items: algorithm Dict specifying the diff algorithm to use. Supported boolean items are "myers", "minimal", "patience" and "histogram". context diff context length. Default is 0. iblank ignore changes where lines are all blank. icase ignore changes in case of text. indent-heuristic use the indent heuristic for the internal diff library. iwhite ignore changes in amount of white space. iwhiteall ignore all white space changes. iwhiteeol ignore white space changes at end of line. For more information about these options, refer to 'diffopt'. To compute the unified diff, all the items in {fromlist} are concatenated into a string using a newline separator and the same for {tolist}. The unified diff output uses line numbers. Returns an empty List or String if {fromlist} and {tolist} are identical. Examples: > :echo diff(['abc'], ['xxx']) @@ -1 +1 @@ -abc +xxx :echo diff(['abc'], ['xxx'], {'output': 'indices'}) [{'from_idx': 0, 'from_count': 1, 'to_idx': 0, 'to_count': 1}] :echo diff(readfile('oldfile'), readfile('newfile')) :echo diff(getbufline(5, 1, '$'), getbufline(6, 1, '$')) < For more examples, refer to |diff-func-examples| Can also be used as a |method|: > GetFromList->diff(to_list) < diff_filler({lnum}) *diff_filler()* Returns the number of filler lines above line {lnum}. These are the lines that were inserted at this point in another diff'ed window. These filler lines are shown in the display but don't exist in the buffer. {lnum} is used like with |getline()|. Thus "." is the current line, "'m" mark m, etc. Returns 0 if the current window is not in diff mode. Can also be used as a |method|: > GetLnum()->diff_filler() diff_hlID({lnum}, {col}) *diff_hlID()* Returns the highlight ID for diff mode at line {lnum} column {col} (byte index). When the current line does not have a diff change zero is returned. {lnum} is used like with |getline()|. Thus "." is the current line, "'m" mark m, etc. {col} is 1 for the leftmost column, {lnum} is 1 for the first line. The highlight ID can be used with |synIDattr()| to obtain syntax information about the highlighting. Can also be used as a |method|: > GetLnum()->diff_hlID(col) < digraph_get({chars}) *digraph_get()* *E1214* Return the digraph of {chars}. This should be a string with exactly two characters. If {chars} are not just two characters, or the digraph of {chars} does not exist, an error is given and an empty string is returned. The character will be converted from Unicode to 'encoding' when needed. This does require the conversion to be available, it might fail. Also see |digraph_getlist()|. Examples: > " Get a built-in digraph :echo digraph_get('00') " Returns '∞' " Get a user-defined digraph :call digraph_set('aa', 'あ') :echo digraph_get('aa') " Returns 'あ' < Can also be used as a |method|: > GetChars()->digraph_get() < This function works only when compiled with the |+digraphs| feature. If this feature is disabled, this function will display an error message. digraph_getlist([{listall}]) *digraph_getlist()* Return a list of digraphs. If the {listall} argument is given and it is TRUE, return all digraphs, including the default digraphs. Otherwise, return only user-defined digraphs. The characters will be converted from Unicode to 'encoding' when needed. This does require the conservation to be available, it might fail. Also see |digraph_get()|. Examples: > " Get user-defined digraphs :echo digraph_getlist() " Get all the digraphs, including default digraphs :echo digraph_getlist(1) < Can also be used as a |method|: > GetNumber()->digraph_getlist() < This function works only when compiled with the |+digraphs| feature. If this feature is disabled, this function will display an error message. digraph_set({chars}, {digraph}) *digraph_set()* Add digraph {chars} to the list. {chars} must be a string with two characters. {digraph} is a string with one UTF-8 encoded character. *E1215* Be careful, composing characters are NOT ignored. This function is similar to |:digraphs| command, but useful to add digraphs start with a white space. The function result is v:true if |digraph| is registered. If this fails an error message is given and v:false is returned. If you want to define multiple digraphs at once, you can use |digraph_setlist()|. Example: > call digraph_set(' ', 'あ') < Can be used as a |method|: > GetString()->digraph_set('あ') < This function works only when compiled with the |+digraphs| feature. If this feature is disabled, this function will display an error message. digraph_setlist({digraphlist}) *digraph_setlist()* Similar to |digraph_set()| but this function can add multiple digraphs at once. {digraphlist} is a list composed of lists, where each list contains two strings with {chars} and {digraph} as in |digraph_set()|. *E1216* Example: > call digraph_setlist([['aa', 'あ'], ['ii', 'い']]) < It is similar to the following: > for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']] call digraph_set(chars, digraph) endfor < Except that the function returns after the first error, following digraphs will not be added. Can be used as a |method|: > GetList()->digraph_setlist() < This function works only when compiled with the |+digraphs| feature. If this feature is disabled, this function will display an error message. echoraw({string}) *echoraw()* Output {string} as-is, including unprintable characters. This can be used to output a terminal code. For example, to disable modifyOtherKeys: > call echoraw(&t_TE) < and to enable it again: > call echoraw(&t_TI) < Use with care, you can mess up the terminal this way. empty({expr}) *empty()* Return the Number 1 if {expr} is empty, zero otherwise. - A |List| or |Dictionary| is empty when it does not have any items. - A |String| is empty when its length is zero. - A |Number| and |Float| are empty when their value is zero. - |v:false|, |v:none| and |v:null| are empty, |v:true| is not. - A |Job| is empty when it failed to start. - A |Channel| is empty when it is closed. - A |Blob| is empty when its length is zero. - An |Object| is empty, when the empty() method in the object (if present) returns true. |object-empty()| For a long |List| this is much faster than comparing the length with zero. Can also be used as a |method|: > mylist->empty() environ() *environ()* Return all of environment variables as dictionary. You can check if an environment variable exists like this: > :echo has_key(environ(), 'HOME') < Note that the variable name may be CamelCase; to ignore case use this: > :echo index(keys(environ()), 'HOME', 0, 1) != -1 err_teapot([{expr}]) *err_teapot()* Produce an error with number 418, needed for implementation of RFC 2324. If {expr} is present and it is TRUE error 503 is given, indicating that coffee is temporarily not available. If {expr} is present it must be a String. escape({string}, {chars}) *escape()* Escape the characters in {chars} that occur in {string} with a backslash. Example: > :echo escape('c:\program files\vim', ' \') < results in: > c:\\program\ files\\vim < Also see |shellescape()| and |fnameescape()|. Can also be used as a |method|: > GetText()->escape(' \') < *eval()* eval({string}) Evaluate {string} and return the result. Especially useful to turn the result of |string()| back into the original value. This works for Numbers, Floats, Strings, Blobs and composites of them. Also works for |Funcref|s that refer to existing functions. In |Vim9| script, it can be used to obtain |enum| values from their fully qualified names. Can also be used as a |method|: > argv->join()->eval() eventhandler() *eventhandler()* Returns 1 when inside an event handler. That is that Vim got interrupted while waiting for the user to type a character, e.g., when dropping a file on Vim. This means interactive commands cannot be used. Otherwise zero is returned. executable({expr}) *executable()* This function checks if an executable with the name {expr} exists. {expr} must be the name of the program without any arguments. executable() uses the value of $PATH and/or the normal searchpath for programs. *PATHEXT* On MS-Windows the ".exe", ".bat", etc. can optionally be included. Then the extensions in $PATHEXT are tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be found. If $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot by itself can be used in $PATHEXT to try using the name without an extension. When 'shell' looks like a Unix shell, then the name is also tried without adding an extension. On MS-Windows it only checks if the file exists and is not a directory, not if it's really executable. On MS-Windows an executable in the same directory as Vim is normally found. Since this directory is added to $PATH it should also work to execute it |win32-PATH|. This can be disabled by setting the $NoDefaultCurrentDirectoryInExePath environment variable. *NoDefaultCurrentDirectoryInExePath* The result is a Number: 1 exists 0 does not exist -1 not implemented on this system |exepath()| can be used to get the full path of an executable. Can also be used as a |method|: > GetCommand()->executable() execute({command} [, {silent}]) *execute()* Execute an Ex command or commands and return the output as a string. {command} can be a string or a List. In case of a List the lines are executed one by one. This is more or less equivalent to: > redir => var {command} redir END < Except that line continuation in {command} is not recognized. The optional {silent} argument can have these values: "" no `:silent` used "silent" `:silent` used "silent!" `:silent!` used The default is "silent". Note that with "silent!", unlike `:redir`, error messages are dropped. When using an external command the screen may be messed up, use `system()` instead. *E930* It is not possible to use `:redir` anywhere in {command}. To get a list of lines use `split()` on the result: > execute('args')->split("\n") < To execute a command in another window than the current one use `win_execute()`. When used recursively the output of the recursive call is not included in the output of the higher level call. Can also be used as a |method|: > GetCommand()->execute() exepath({expr}) *exepath()* If {expr} is an executable and is either an absolute path, a relative path or found in $PATH, return the full path. Note that the current directory is used when {expr} starts with "./", which may be a problem for Vim: > echo exepath(v:progpath) < If {expr} cannot be found in $PATH or is not executable then an empty string is returned. Can also be used as a |method|: > GetCommand()->exepath() < *exists()* exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined, zero otherwise. Note: In a compiled |:def| function the evaluation is done at runtime. Use `exists_compiled()` to evaluate the expression at compile time. For checking for a supported feature use |has()|. For checking if a file exists use |filereadable()|. The {expr} argument is a string, which contains one of these: varname internal variable (see dict.key |internal-variables|). Also works list[i] for |curly-braces-names|, |Dictionary| import.Func entries, |List| items, class and class.Func object methods, imported items, etc. object.Func Does not work for local variables in a class.varname compiled `:def` function. object.varname Also works for a function in |Vim9| script, since it can be used as a function reference. Beware that evaluating an index may cause an error message for an invalid expression. E.g.: > :let l = [1, 2, 3] :echo exists("l[5]") < 0 > :echo exists("l[xx]") < E121: Undefined variable: xx 0 &option-name Vim option (only checks if it exists, not if it really works) +option-name Vim option that works. $ENVNAME environment variable (could also be done by comparing with an empty string) *funcname built-in function (see |functions|) or user defined function (see |user-functions|) that is implemented. Also works for a variable that is a Funcref. ?funcname built-in function that could be implemented; to be used to check if "funcname" is valid :cmdname Ex command: built-in command, user command or command modifier |:command|. Returns: 1 for match with start of a command 2 full match with a command 3 matches several user commands To check for a supported command always check the return value to be 2. :2match The |:2match| command. :3match The |:3match| command (but you probably should not use it, it is reserved for internal usage) #event autocommand defined for this event #event#pattern autocommand defined for this event and pattern (the pattern is taken literally and compared to the autocommand patterns character by character) #group autocommand group exists #group#event autocommand defined for this group and event. #group#event#pattern autocommand defined for this group, event and pattern. ##event autocommand for this event is supported. Examples: > exists("&shortname") exists("$HOSTNAME") exists("*strftime") exists("*s:MyFunc") " only for legacy script exists("*MyFunc") exists("bufcount") exists(":Make") exists("#CursorHold") exists("#BufReadPre#*.gz") exists("#filetypeindent") exists("#filetypeindent#FileType") exists("#filetypeindent#FileType#*") exists("##ColorScheme") < There must be no space between the symbol (&/$/*/#) and the name. There must be no extra characters after the name, although in a few cases this is ignored. That may become stricter in the future, thus don't count on it! Working example: > exists(":make") < NOT working example: > exists(":make install") < Note that the argument must be a string, not the name of the variable itself. For example: > exists(bufcount) < This doesn't check for existence of the "bufcount" variable, but gets the value of "bufcount", and checks if that exists. Can also be used as a |method|: > Varname()->exists() < exists_compiled({expr}) *exists_compiled()* Like `exists()` but evaluated at compile time. This is useful to skip a block where a function is used that would otherwise give an error: > if exists_compiled('*ThatFunction') ThatFunction('works') endif < If `exists()` were used then a compilation error would be given if ThatFunction() is not defined. {expr} must be a literal string. *E1232* Can only be used in a |:def| function. *E1233* This does not work to check for arguments or local variables. exp({expr}) *exp()* Return the exponential of {expr} as a |Float| in the range [0, inf]. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. Examples: > :echo exp(2) < 7.389056 > :echo exp(-1) < 0.367879 Can also be used as a |method|: > Compute()->exp() expand({string} [, {nosuf} [, {list}]]) *expand()* Expand wildcards and the following special keywords in {string}. 'wildignorecase' applies. If {list} is given and it is |TRUE|, a List will be returned. Otherwise the result is a String and when there are several matches, they are separated by characters. [Note: in version 5.0 a space was used, which caused problems when a file name contains a space] If the expansion fails, the result is an empty string. A name for a non-existing file is not included, unless {string} does not start with '%', '#' or '<', see below. For a |:terminal| window '%' expands to a '!' followed by the command or shell that is run |terminal-bufname| When {string} starts with '%', '#' or '<', the expansion is done like for the |cmdline-special| variables with their associated modifiers. Here is a short overview: % current file name # alternate file name #n alternate file name n file name under the cursor autocmd file name autocmd buffer number (as a String!) autocmd matched name C expression under the cursor sourced script file or function name sourced script line number or function line number script file line number, also when in a function "123_" where "123" is the current script ID ||