FILE: C:\Program Files\Git\usr\share\vim\vim91\doc\builtin.txt
--
*builtin.txt* For Vim version 9.1. Last change: 2024 Oct 14
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({buf}, {lnum}, {text})
Number append {text} below line {lnum}
in buffer {buf}
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
bindtextdomain({package}, {path})
Bool bind text domain to specified path
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}) Bool register |digraph|
digraph_setlist({digraphlist}) Bool 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
filecopy({from}, {to}) Number |TRUE| if copying file {from} to {to}
worked
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
getcmdcomplpat() String return the completion pattern of the
current command-line completion
getcmdcompltype() String return the type of the current
command-line completion
getcmdline() String return the current command-line input
getcmdpos() Number return cursor position in command-line
getcmdprompt() String return the current command-line prompt
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}
getregionpos({pos1}, {pos2} [, {opts}])
List get a list of positions for a region
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} [, {package}]) 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}
id({item}) String get unique identity string of item
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_setbuf({id}, {buf}) Bool set the buffer for the popup window {id}
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({buf}, {lnum}, {text})
Number set line {lnum} to {text} in buffer
{buf}
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.
Return type specifies the type for |Vim9-script|, see |vim9-types|
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()
<
Return type: |Number| or |Float| depending on {expr}
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()
<
Return type: |Float|
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)
<
Return type: list<{type}> (depending on the given |List|) or
|Blob|
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)
<
Return type: |Number|
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)
<
Return type: |Number|
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)
<
Return type: |Number|
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.
Return type: |Number|
*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|.
Return type: |Number|
*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|.
Return type: |Number|
*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.
Return type: |String|
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()
<
Return type: |Float|
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()
<
Return type: |Float|
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)
<
Return type: |Float|
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()
<
Return type: |vim9-boolean|
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()
<
Return type: |vim9-boolean|
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()
<
Return type: list>
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.
Return type: |String|
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}
Return type: |Number|
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}
Return type: list or list
bindtextdomain({package}, {path}) *bindtextdomain()*
Bind a specific {package} to a {path} so that the
|gettext()| function can be used to get language-specific
translations for a package. {path} is the directory name
for the translations. See |package-translation|.
Returns v:true on success and v:false on failure (out of
memory).
Return type: |vim9-boolean|
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()
<
Return type: list or list
*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.
Return type: |String|
browsedir({title}, {initdir}) *browsedir()*
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.
Return type: |String|
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()
<
Return type: |Number|
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()
<
Return type: |Number|
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()
<
Return type: |Number|
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()
<
Return type: |Number|
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()
<
Return type: |Number|
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.
<
Return type: |String|
*buffer_name()*
Obsolete name: buffer_name().
bufnr([{buf} [, {create}]]) *bufnr()*
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()
<
Return type: |Number|
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()
<
Return type: |Number|
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()
<
Return type: |Number|
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()
<
Return type: |Number|
{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)
<
Return type: |Number|
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)
<
Return type: |Number|
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)
<
Return type: any, depending on {func}
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()
<
Return type: |Float|
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.
Return type: |Number|
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()
<
Return type: |Number|
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|.
Return type: |Number|
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()
<
Return type: |Number|
*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)
<
Return type: |Number|
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()
<
Return type: |String|
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()
<
Return type: |Number|
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()
<
Return type: |Number|
col({expr} [, {winid}]) *col()*
The result is a Number, which is the byte index of the column
position given with {expr}.
For accepted positions see |getpos()|.
When {expr} is "$", it means the end of the cursor line, so
the result is the number of bytes in the cursor line plus one.
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()
<
Return type: |Number|
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('.'))
<
Return type: |Number|
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()
<
Return type: |Number|
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.
Return type: |Number|
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()
<
Return type: dict
*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")
<
Return type: |Number|
copy({expr}) *copy()*
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()
<
Return type: any, depending on {expr}
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()
<
Return type: |Float|
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()
<
Return type: |Float|
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)
<
Return type: |Number|
*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
<
Return type: |Number|
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()
<
Return type: |Number|
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()
<
Return type: |Number|
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()
<
Return type: any, depending on {expr}
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()
<
Return type: |Number|
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)
<
Return type: |Number|
*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.
Return type: |Number|
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)
<
Return type: |String| or list> or list
depending on {options}
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()
<
Return type: |Number|
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)
<
Return type: |Number|
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()
<
Return type: |String|
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()
<
Return type: list>
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 returns 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('あ')
<
Return type: |vim9-boolean|
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()
<
Return type: |vim9-boolean|
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.
Return type: |Number|
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()
<
Return type: |Number|
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
<
Return type: dict
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.
Return type: |Number|
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(' \')
<
Return type: |String|
*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()
<
Return type: any, depending on {string}
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.
Return type: |Number|
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 the Vim
executable is always found. Since this directory is added to
$PATH it should also work to execute it |win32-PATH|.
*NoDefaultCurrentDirectoryInExePath*
On MS-Windows an executable in Vim's current working directory
is also normally found, but this can be disabled by setting
the $NoDefaultCurrentDirectoryInExePath environment variable.
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()
<
Return type: |Number|
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()
<
Return type: |String|
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()
<
Return type: |String|
exists({expr}) *exists()*
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()
<
Return type: |String|
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.
Return type: |String|
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()
<
Return type: |Float|
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 ||