# HG changeset patch # User Bram Moolenaar # Date 1640640602 -3600 # Node ID 629e7046ef63a046caa5899f6f4b32e2c8f7e306 # Parent 7560ecdb2a6ea4d3ca23f9fe8447b789a3b133d5 patch 8.2.3917: the eval.txt help file is way too big Commit: https://github.com/vim/vim/commit/1cae5a0a034d0545360387407a7a409310f1efe2 Author: Bram Moolenaar Date: Mon Dec 27 21:28:34 2021 +0000 patch 8.2.3917: the eval.txt help file is way too big Problem: The eval.txt help file is way too big. Solution: Move the builtin function details to a separate file. diff --git a/runtime/doc/Makefile b/runtime/doc/Makefile --- a/runtime/doc/Makefile +++ b/runtime/doc/Makefile @@ -16,6 +16,7 @@ include ../../src/auto/config.mk DOCS = \ arabic.txt \ autocmd.txt \ + builtin.txt \ change.txt \ channel.txt \ cmdline.txt \ @@ -161,6 +162,7 @@ DOCS = \ HTMLS = \ arabic.html \ autocmd.html \ + builtin.html \ change.html \ channel.html \ cmdline.html \ diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt new file mode 100644 --- /dev/null +++ b/runtime/doc/builtin.txt @@ -0,0 +1,10125 @@ +*builtin.txt* For Vim version 8.2. Last change: 2021 Dec 27 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Builtin functions *builtin-functions* + +Note: Expression evaluation can be disabled at compile time. If this has been +done, the builtin functions are not available. See |+eval| and +|no-eval-feature|. + +1. Overview |builtin-function-list| +2. Details |builtin-function-details| +3. Feature list |feature-list| +4. Matching a pattern in a String |string-match| + +============================================================================== +1. Overview *builtin-function-list* + +Use CTRL-] on the function name to jump to the full explanation. + +USAGE RESULT DESCRIPTION ~ + +abs({expr}) Float or Number absolute value of {expr} +acos({expr}) Float arc cosine of {expr} +add({object}, {item}) List/Blob append {item} to {object} +and({expr}, {expr}) Number bitwise AND +append({lnum}, {text}) Number append {text} below line {lnum} +appendbufline({expr}, {lnum}, {text}) + Number append {text} below line {lnum} + in buffer {expr} +argc([{winid}]) Number number of files in the argument list +argidx() Number current index in the argument list +arglistid([{winnr} [, {tabnr}]]) Number argument list id +argv({nr} [, {winid}]) String {nr} entry of the argument list +argv([-1, {winid}]) List the argument list +asin({expr}) Float arc sine of {expr} +assert_beeps({cmd}) Number assert {cmd} causes a beep +assert_equal({exp}, {act} [, {msg}]) + Number assert {exp} is equal to {act} +assert_equalfile({fname-one}, {fname-two} [, {msg}]) + Number assert file contents are equal +assert_exception({error} [, {msg}]) + Number assert {error} is in v:exception +assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]]) + Number assert {cmd} fails +assert_false({actual} [, {msg}]) + Number assert {actual} is false +assert_inrange({lower}, {upper}, {actual} [, {msg}]) + Number assert {actual} is inside the range +assert_match({pat}, {text} [, {msg}]) + Number assert {pat} matches {text} +assert_nobeep({cmd}) Number assert {cmd} does not cause a beep +assert_notequal({exp}, {act} [, {msg}]) + Number assert {exp} is not equal {act} +assert_notmatch({pat}, {text} [, {msg}]) + Number assert {pat} not matches {text} +assert_report({msg}) Number report a test failure +assert_true({actual} [, {msg}]) Number assert {actual} is true +atan({expr}) Float arc tangent of {expr} +atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2} +balloon_gettext() String current text in the balloon +balloon_show({expr}) none show {expr} inside the balloon +balloon_split({msg}) List split {msg} as used for a balloon +blob2list({blob}) List convert {blob} into a list of numbers +browse({save}, {title}, {initdir}, {default}) + String put up a file requester +browsedir({title}, {initdir}) String put up a directory requester +bufadd({name}) Number add a buffer to the buffer list +bufexists({buf}) Number |TRUE| if buffer {buf} exists +buflisted({buf}) Number |TRUE| if buffer {buf} is listed +bufload({buf}) Number load buffer {buf} if not loaded yet +bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded +bufname([{buf}]) String Name of the buffer {buf} +bufnr([{buf} [, {create}]]) Number Number of the buffer {buf} +bufwinid({buf}) Number window ID of buffer {buf} +bufwinnr({buf}) Number window number of buffer {buf} +byte2line({byte}) Number line number at byte count {byte} +byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr} +byteidxcomp({expr}, {nr}) 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}) Number column number of cursor or mark +charidx({string}, {idx} [, {countcc}]) + 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}) 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_filler({lnum}) Number diff filler lines about {lnum} +diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col} +digraph_get({chars}) String get the |digraph| of {chars} +digraph_getlist([{listall}]) List get all |digraph|s +digraph_set({chars}, {digraph}) Boolean register |digraph| +digraph_setlist({digraphlist}) Boolean register multiple |digraph|s +echoraw({expr}) none output {expr} as-is +empty({expr}) Number |TRUE| if {expr} is empty +environ() Dict return environment variables +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({expr}) String expand {expr} like with `:edit` +extend({expr1}, {expr2} [, {expr3}]) + List/Dict insert items of {expr2} into {expr1} +extendnew({expr1}, {expr2} [, {expr3}]) + List/Dict like |extend()| but creates a new + List or Dictionary +feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer +filereadable({file}) Number |TRUE| if {file} is a readable file +filewritable({file}) Number |TRUE| if {file} is a writable file +filter({expr1}, {expr2}) List/Dict/Blob/String + remove items from {expr1} where + {expr2} is 0 +finddir({name} [, {path} [, {count}]]) + String find directory {name} in {path} +findfile({name} [, {path} [, {count}]]) + String find file {name} in {path} +flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels +flattennew({list} [, {maxdepth}]) + List flatten a copy of {list} +float2nr({expr}) Number convert Float {expr} to a Number +floor({expr}) Float round {expr} down +fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2} +fnameescape({fname}) String escape special characters in {fname} +fnamemodify({fname}, {mods}) String modify file name +foldclosed({lnum}) Number first line of fold at {lnum} if closed +foldclosedend({lnum}) Number last line of fold at {lnum} if closed +foldlevel({lnum}) Number fold level at {lnum} +foldtext() String line displayed for closed fold +foldtextresult({lnum}) String text for closed fold at {lnum} +foreground() Number bring the Vim window to the foreground +fullcommand({name}) 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} +getbufvar({buf}, {varname} [, {def}]) + any variable {varname} in buffer {buf} +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 +getcmdline() String return the current command-line +getcmdpos() Number return cursor 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 +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 +getregtype([{regname}]) String type of a register +gettabinfo([{expr}]) List list of tab pages +gettabvar({nr}, {varname} [, {def}]) + any variable {varname} in tab {nr} or {def} +gettabwinvar({tabnr}, {winnr}, {name} [, {def}]) + any {name} in {winnr} in tab page {tabnr} +gettagstack([{nr}]) Dict get the tag stack of window {nr} +gettext({text}) String lookup translation of {text} +getwininfo([{winid}]) List list of info about each window +getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window +getwinposx() Number X coord in pixels of the Vim window +getwinposy() Number Y coord in pixels of the Vim window +getwinvar({nr}, {varname} [, {def}]) + any variable {varname} in window {nr} +glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) + any expand file wildcards in {expr} +glob2regpat({expr}) String convert a glob pat into a search pat +globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) + String do glob({expr}) for all dirs in {path} +has({feature} [, {check}]) Number |TRUE| if feature {feature} supported +has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key} +haslocaldir([{winnr} [, {tabnr}]]) + Number |TRUE| if the window executed |:lcd| + or |:tcd| +hasmapto({what} [, {mode} [, {abbr}]]) + Number |TRUE| if mapping to {what} exists +histadd({history}, {item}) Number add an item to a history +histdel({history} [, {item}]) Number remove an item from a history +histget({history} [, {index}]) String get the item {index} from a history +histnr({history}) Number highest index of a history +hlID({name}) Number syntax ID of highlight group {name} +hlexists({name}) Number |TRUE| if highlight group {name} exists +hlget([{name} [, {resolve}]]) List get highlight group attributes +hlset({list}) Number set highlight group attributes +hostname() String name of the machine Vim is running on +iconv({expr}, {from}, {to}) String convert encoding of {expr} +indent({lnum}) Number indent of line {lnum} +index({object}, {expr} [, {start} [, {ic}]]) + Number index in {object} where {expr} appears +input({prompt} [, {text} [, {completion}]]) + String get input from the user +inputdialog({prompt} [, {text} [, {completion}]]) + 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}] +interrupt() none interrupt script execution +invert({expr}) Number bitwise invert +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} +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} +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| +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} +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} [, {path} [, {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_findinfo() Number get window ID of info popup window +popup_findpreview() Number get window ID of preview popup window +popup_getoptions({id}) Dict get options of popup window {id} +popup_getpos({id}) Dict get position of popup window {id} +popup_hide({id}) none hide popup menu {id} +popup_list() List get a list of window IDs of all popups +popup_locate({row}, {col}) Number get window ID of popup at position +popup_menu({what}, {options}) Number create a popup window used as a menu +popup_move({id}, {options}) none set position of popup window {id} +popup_notification({what}, {options}) + Number create a notification popup window +popup_setoptions({id}, {options}) + none set options for popup window {id} +popup_settext({id}, {text}) none set the text of popup window {id} +popup_show({id}) none unhide popup window {id} +pow({x}, {y}) Float {x} to the power of {y} +prevnonblank({lnum}) Number line nr of non-blank line <= {lnum} +printf({fmt}, {expr1}...) String format text +prompt_getprompt({buf}) String get prompt text +prompt_setcallback({buf}, {expr}) none set prompt callback function +prompt_setinterrupt({buf}, {text}) none set prompt interrupt function +prompt_setprompt({buf}, {text}) none set prompt text +prop_add({lnum}, {col}, {props}) none add one text property +prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) + none add multiple text properties +prop_clear({lnum} [, {lnum-end} [, {props}]]) + none remove all text properties +prop_find({props} [, {direction}]) + Dict search for a text property +prop_list({lnum} [, {props}]) List text properties in {lnum} +prop_remove({props} [, {lnum} [, {lnum-end}]]) + Number remove a text property +prop_type_add({name}, {props}) none define a new property type +prop_type_change({name}, {props}) + none change an existing property type +prop_type_delete({name} [, {props}]) + none delete a property type +prop_type_get({name} [, {props}]) + Dict get property type values +prop_type_list([{props}]) List get list of property types +pum_getpos() Dict position and size of pum if visible +pumvisible() Number whether popup menu is visible +py3eval({expr}) any evaluate |python3| expression +pyeval({expr}) any evaluate |Python| expression +pyxeval({expr}) any evaluate |python_x| expression +rand([{expr}]) Number get pseudo-random number +range({expr} [, {max} [, {stride}]]) + List items from {expr} to {max} +readblob({fname}) 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}) String repeat {expr} {count} times +resolve({filename}) String get filename a shortcut points to +reverse({list}) List reverse {list} in-place +round({expr}) Float round off {expr} +rubyeval({expr}) any evaluate |Ruby| expression +screenattr({row}, {col}) Number attribute at screen position +screenchar({row}, {col}) Number character at screen position +screenchars({row}, {col}) List List of characters at screen position +screencol() Number current cursor column +screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character +screenrow() Number current cursor row +screenstring({row}, {col}) String characters at screen position +search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) + Number search for {pattern} +searchcount([{options}]) Dict get or update search stats +searchdecl({name} [, {global} [, {thisblock}]]) + Number search for variable declaration +searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) + Number search for other end of start/end pair +searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) + List search for other end of start/end pair +searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) + List search for {pattern} +server2client({clientid}, {string}) + Number send reply string +serverlist() String get a list of available servers +setbufline({expr}, {lnum}, {text}) + Number set line {lnum} to {text} in buffer + {expr} +setbufvar({buf}, {varname}, {val}) + none set {varname} in buffer {buf} to {val} +setcellwidths({list}) none set character cell width overrides +setcharpos({expr}, {list}) Number set the {expr} position to {list} +setcharsearch({dict}) Dict set character search from {dict} +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} [, {func} [, {dict}]]) + List sort {list}, using {func} to compare +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 +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} +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_drop_files({list}, {row}, {col}, {mods}) + none drop a list of files in a window +test_gui_mouse_event({button}, {row}, {col}, {repeated}, {mods}) + none add a mouse event to the input buffer +test_ignore_error({expr}) none ignore a specific error +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_scrollbar({which}, {value}, {dragging}) + none scroll in the GUI for testing +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() List undo file tree +uniq({list} [, {func} [, {dict}]]) + List remove adjacent duplicates from a list +values({dict}) List values in {dict} +virtcol({expr}) Number screen column of cursor or mark +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_screenpos({nr}) List get screen position of window {nr} +win_splitmove({nr}, {target} [, {options}]) + Number move window {nr} to split of {target} +winbufnr({nr}) Number buffer number of window {nr} +wincol() Number window column of the cursor +windowsversion() String MS-Windows OS version +winheight({nr}) Number height of window {nr} +winlayout([{tabnr}]) List layout of windows in tab {tabnr} +winline() Number window line of the cursor +winnr([{expr}]) Number number of current window +winrestcmd() String returns command to restore window sizes +winrestview({dict}) none restore view of current window +winsaveview() Dict save view of current window +winwidth({nr}) Number width of window {nr} +wordcount() Dict get byte/char/word statistics +writefile({object}, {fname} [, {flags}]) + Number write |Blob| or |List| of lines to file +xor({expr}, {expr}) Number bitwise XOR + +============================================================================== +2. Details *builtin-function-details* + +Not all functions are here, some have been moved to a help file covering the +specific functionality. + +abs({expr}) *abs()* + Return the absolute value of {expr}. When {expr} evaluates to + a |Float| abs() returns a |Float|. When {expr} can be + converted to a |Number| abs() returns a |Number|. Otherwise + abs() gives an error message and returns -1. + Examples: > + echo abs(1.456) +< 1.456 > + echo abs(-5.456) +< 5.456 > + echo abs(-4) +< 4 + + Can also be used as a |method|: > + Compute()->abs() + +< {only available when compiled with the |+float| feature} + + +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]. + Examples: > + :echo acos(0) +< 1.570796 > + :echo acos(-0.5) +< 2.094395 + + Can also be used as a |method|: > + Compute()->acos() + +< {only available when compiled with the |+float| feature} + + +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. + + Can also be used as a |method|: > + mylist->add(val1)->add(val2) + + +and({expr}, {expr}) *and()* + Bitwise AND on the two arguments. The arguments are converted + to a number. A List, Dict or Float argument causes an error. + Example: > + :let flag = and(bits, 0x80) +< Can also be used as a |method|: > + :let flag = bits->and(0x80) + + +append({lnum}, {text}) *append()* + When {text} is a |List|: Append each item of the |List| as a + text line below line {lnum} in the current buffer. + Otherwise append {text} as one text line below line {lnum} in + the current buffer. + Any type of item is accepted and converted to a String. + {lnum} can be zero to insert a line before the first one. + {lnum} is used like with |getline()|. + Returns 1 for failure ({lnum} out of range or out of memory), + 0 for success. In |Vim9| script an invalid argument or + negative number results in an error. Example: > + :let failed = append(line('$'), "# THE END") + :let failed = append(0, ["Chapter 1", "the beginning"]) + +< Can also be used as a |method| after a List, the base is + passed as the second argument: > + mylist->append(lnum) + + +appendbufline({buf}, {lnum}, {text}) *appendbufline()* + Like |append()| but append the text in buffer {buf}. + + This function works only for loaded buffers. First call + |bufload()| if needed. + + For the use of {buf}, see |bufname()|. + + {lnum} is used like with |append()|. Note that using |line()| + would use the current buffer, not the one appending to. + Use "$" to append at the end of the buffer. + + 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") +< + Can also be used as a |method| after a List, the base is + passed as the second argument: > + mylist->appendbufline(buf, lnum) + + +argc([{winid}]) *argc()* + The result is the number of files in the argument list. See + |arglist|. + If {winid} is not supplied, the argument list of the current + window is used. + If {winid} is -1, the global argument list is used. + Otherwise {winid} specifies the window of which the argument + list is used: either the window number or the window ID. + Returns -1 if the {winid} argument is invalid. + + *argidx()* +argidx() The result is the current index in the argument list. 0 is + the first file. argc() - 1 is the last one. See |arglist|. + + *arglistid()* +arglistid([{winnr} [, {tabnr}]]) + Return the argument list ID. This is a number which + identifies the argument list being used. Zero is used for the + global argument list. See |arglist|. + Returns -1 if the arguments are invalid. + + Without arguments use the current window. + With {winnr} only use this window in the current tab page. + With {winnr} and {tabnr} use the window in the specified tab + page. + {winnr} can be the window number or the |window-ID|. + + *argv()* +argv([{nr} [, {winid}]]) + The result is the {nr}th file in the argument list. See + |arglist|. "argv(0)" is the first one. Example: > + :let i = 0 + :while i < argc() + : let f = escape(fnameescape(argv(i)), '.') + : exe 'amenu Arg.' . f . ' :e ' . f . '' + : let i = i + 1 + :endwhile +< Without the {nr} argument, or when {nr} is -1, a |List| with + the whole |arglist| is returned. + + The {winid} argument specifies the window ID, see |argc()|. + For the Vim command line arguments see |v:argv|. + +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]. + Examples: > + :echo asin(0.8) +< 0.927295 > + :echo asin(-0.5) +< -0.523599 + + Can also be used as a |method|: > + Compute()->asin() +< + {only available when compiled with the |+float| feature} + + +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|. + Examples: > + :echo atan(100) +< 1.560797 > + :echo atan(-4.01) +< -1.326405 + + Can also be used as a |method|: > + Compute()->atan() +< + {only available when compiled with the |+float| feature} + + +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|. + Examples: > + :echo atan2(-1, 1) +< -0.785398 > + :echo atan2(1, -1) +< 2.356194 + + Can also be used as a |method|: > + Compute()->atan2(1) +< + {only available when compiled with the |+float| feature} + +balloon_gettext() *balloon_gettext()* + Return the current text in the balloon. Only for the string, + not used for the List. + +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. + + When showing a balloon is not possible nothing happens, no + error message. + {only available when compiled with the |+balloon_eval| or + |+balloon_eval_term| feature} + +balloon_split({msg}) *balloon_split()* + Split String {msg} into lines to be displayed in a balloon. + The splits are made for the current window size and optimize + to show debugger output. + Returns a |List| with the split lines. + Can also be used as a |method|: > + GetText()->balloon_split()->balloon_show() + +< {only available when compiled with the |+balloon_eval_term| + feature} + +blob2list({blob}) *blob2list()* + Return a List containing the number value of each byte in Blob + {blob}. Examples: > + blob2list(0z0102.0304) returns [1, 2, 3, 4] + blob2list(0z) returns [] +< Returns an empty List on error. |list2blob()| does the + opposite. + + Can also be used as a |method|: > + GetBlob()->blob2list() + + *browse()* +browse({save}, {title}, {initdir}, {default}) + Put up a file requester. This only works when "has("browse")" + returns |TRUE| (only in some GUI versions). + The input fields are: + {save} when |TRUE|, select file to write + {title} title for the requester + {initdir} directory to start browsing in + {default} default file name + An empty string is returned when the "Cancel" button is hit, + something went wrong, or browsing is not possible. + + *browsedir()* +browsedir({title}, {initdir}) + Put up a directory requester. This only works when + "has("browse")" returns |TRUE| (only in some GUI versions). + On systems where a directory browser is not supported a file + browser is used. In that case: select a file in the directory + to be used. + The input fields are: + {title} title for the requester + {initdir} directory to start browsing in + When the "Cancel" button is hit, something went wrong, or + browsing is not possible, an empty string is returned. + +bufadd({name}) *bufadd()* + Add a buffer to the buffer list with String {name}. + 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']) +< Can also be used as a |method|: > + let bufnr = 'somename'->bufadd() + +bufexists({buf}) *bufexists()* + The result is a Number, which is |TRUE| if a buffer called + {buf} exists. + If the {buf} argument is a number, buffer numbers are used. + Number zero is the alternate buffer for the current window. + + If the {buf} argument is a string it must match a buffer name + exactly. The name can be: + - Relative to the current directory. + - A full path. + - The name of a buffer with 'buftype' set to "nofile". + - A URL name. + Unlisted buffers will be found. + Note that help files are listed by their short name in the + output of |:buffers|, but bufexists() requires using their + long name to be able to find them. + bufexists() may report a buffer exists, but to use the name + with a |:buffer| command you may need to use |expand()|. Esp + for MS-Windows 8.3 names in the form "c:\DOCUME~1" + Use "bufexists(0)" to test for the existence of an alternate + file name. + + Can also be used as a |method|: > + let exists = 'somename'->bufexists() +< + Obsolete name: buffer_exists(). *buffer_exists()* + +buflisted({buf}) *buflisted()* + The result is a Number, which is |TRUE| if a buffer called + {buf} exists and is listed (has the 'buflisted' option set). + The {buf} argument is used like with |bufexists()|. + + Can also be used as a |method|: > + let listed = 'somename'->buflisted() + +bufload({buf}) *bufload()* + Ensure the buffer {buf} is loaded. When the buffer name + refers to an existing file then the file is read. Otherwise + the buffer will be empty. If the buffer was already loaded + then there is no change. + If there is an existing swap file for the file of the buffer, + there will be no dialog, the buffer will be loaded anyway. + The {buf} argument is used like with |bufexists()|. + + Can also be used as a |method|: > + eval 'somename'->bufload() + +bufloaded({buf}) *bufloaded()* + The result is a Number, which is |TRUE| if a buffer called + {buf} exists and is loaded (shown in a window or hidden). + The {buf} argument is used like with |bufexists()|. + + Can also be used as a |method|: > + let loaded = 'somename'->bufloaded() + +bufname([{buf}]) *bufname()* + The result is the name of a buffer. Mostly as it is displayed + by the `:ls` command, but not using special names such as + "[No Name]". + If {buf} is omitted the current buffer is used. + If {buf} is a Number, that buffer number's name is given. + Number zero is the alternate buffer for the current window. + If {buf} is a String, it is used as a |file-pattern| to match + with the buffer names. This is always done like 'magic' is + set and 'cpoptions' is empty. When there is more than one + match an empty string is returned. + "" or "%" can be used for the current buffer, "#" for the + alternate buffer. + A full match is preferred, otherwise a match at the start, end + or middle of the buffer name is accepted. If you only want a + full match then put "^" at the start and "$" at the end of the + pattern. + Listed buffers are found first. If there is a single match + with a listed buffer, that one is returned. Next unlisted + buffers are searched for. + If the {buf} is a String, but you want to use it as a buffer + number, force it to be a Number by adding zero to it: > + :echo bufname("3" + 0) +< Can also be used as a |method|: > + echo bufnr->bufname() + +< If the buffer doesn't exist, or doesn't have a name, an empty + string is returned. > + bufname("#") alternate buffer name + bufname(3) name of buffer 3 + bufname("%") name of current buffer + bufname("file2") name of buffer where "file2" matches. +< *buffer_name()* + Obsolete name: buffer_name(). + + *bufnr()* +bufnr([{buf} [, {create}]]) + The result is the number of a buffer, as it is displayed by + the `:ls` command. For the use of {buf}, see |bufname()| + above. + + If the buffer doesn't exist, -1 is returned. Or, if the + {create} argument is present and TRUE, a new, unlisted, + buffer is created and its number is returned. Example: > + let newbuf = bufnr('Scratch001', 1) +< Using an empty name uses the current buffer. To create a new + buffer with an empty name use |bufadd()|. + + bufnr("$") is the last buffer: > + :let last_buffer = bufnr("$") +< The result is a Number, which is the highest buffer number + of existing buffers. Note that not all buffers with a smaller + number necessarily exist, because ":bwipeout" may have removed + them. Use bufexists() to test for the existence of a buffer. + + Can also be used as a |method|: > + echo bufref->bufnr() +< + Obsolete name: buffer_number(). *buffer_number()* + *last_buffer_nr()* + Obsolete name for bufnr("$"): last_buffer_nr(). + +bufwinid({buf}) *bufwinid()* + The result is a Number, which is the |window-ID| of the first + window associated with buffer {buf}. For the use of {buf}, + see |bufname()| above. If buffer {buf} doesn't exist or + there is no such window, -1 is returned. Example: > + + echo "A window containing buffer 1 is " . (bufwinid(1)) +< + Only deals with the current tab page. + + Can also be used as a |method|: > + FindBuffer()->bufwinid() + +bufwinnr({buf}) *bufwinnr()* + Like |bufwinid()| but return the window number instead of the + |window-ID|. + If buffer {buf} doesn't exist or there is no such window, -1 + is returned. Example: > + + echo "A window containing buffer 1 is " . (bufwinnr(1)) + +< The number can be used with |CTRL-W_w| and ":wincmd w" + |:wincmd|. + + Can also be used as a |method|: > + FindBuffer()->bufwinnr() + +byte2line({byte}) *byte2line()* + Return the line number that contains the character at byte + count {byte} in the current buffer. This includes the + end-of-line character, depending on the 'fileformat' option + for the current buffer. The first character has byte count + one. + Also see |line2byte()|, |go| and |:goto|. + + Can also be used as a |method|: > + GetOffset()->byte2line() + +< {not available when compiled without the |+byte_offset| + feature} + +byteidx({expr}, {nr}) *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. + 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. + + Can also be used as a |method|: > + GetName()->byteidx(idx) + +byteidxcomp({expr}, {nr}) *byteidxcomp()* + Like byteidx(), except that a composing character is counted + as a separate character. Example: > + let s = 'e' . nr2char(0x301) + echo byteidx(s, 1) + echo byteidxcomp(s, 1) + echo byteidxcomp(s, 2) +< The first and third echo result in 3 ('e' plus composing + character is 3 bytes), the second echo results in 1 ('e' is + one byte). + Only works differently from byteidx() when 'encoding' is set + to a Unicode encoding. + + Can also be used as a |method|: > + GetName()->byteidxcomp(idx) + +call({func}, {arglist} [, {dict}]) *call()* *E699* + Call function {func} with the items in |List| {arglist} as + arguments. + {func} can either be a |Funcref| or the name of a function. + a:firstline and a:lastline are set to the cursor line. + Returns the return value of the called function. + {dict} is for functions with the "dict" attribute. It will be + used to set the local variable "self". |Dictionary-function| + + Can also be used as a |method|: > + GetFunc()->call([arg, arg], dict) + +ceil({expr}) *ceil()* + Return the smallest integral value greater than or equal to + {expr} as a |Float| (round up). + {expr} must evaluate to a |Float| or a |Number|. + Examples: > + echo ceil(1.456) +< 2.0 > + echo ceil(-5.456) +< -5.0 > + echo ceil(4.0) +< 4.0 + + Can also be used as a |method|: > + Compute()->ceil() +< + {only available when compiled with the |+float| feature} + + +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. + +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] + + Can also be used as a |method|: > + GetChar()->char2nr() + + +charclass({string}) *charclass()* + Return the character class of the first character in {string}. + The character class is one of: + 0 blank + 1 punctuation + 2 word character + 3 emoji + other specific Unicode class + The class is used in patterns and word motions. + + +charcol({expr}) *charcol()* + Same as |col()| but returns the character index of the column + position given with {expr} instead of the byte position. + + Example: + With the cursor on '세' in line 5 with text "여보세요": > + charcol('.') returns 3 + col('.') returns 7 + +< Can also be used as a |method|: > + GetPos()->col() +< + *charidx()* +charidx({string}, {idx} [, {countcc}]) + 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. + Returns -1 if the arguments are invalid or if {idx} is greater + than the index of the last byte in {string}. An error is + given 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. + Examples: > + echo charidx('áb́ć', 3) returns 1 + echo charidx('áb́ć', 6, 1) returns 4 + echo charidx('áb́ć', 16) returns -1 +< + Can also be used as a |method|: > + GetName()->charidx(idx) + +chdir({dir}) *chdir()* + Change the current working directory to {dir}. The scope of + the directory change depends on the directory of the current + window: + - If the current window has a window-local directory + (|:lcd|), then changes the window local directory. + - Otherwise, if the current tabpage has a local + directory (|:tcd|) then changes the tabpage local + directory. + - Otherwise, changes the global directory. + {dir} must be a String. + If successful, returns the previous working directory. Pass + this to another chdir() to restore the directory. + On failure, returns an empty string. + + Example: > + let save_dir = chdir(newdir) + if save_dir != "" + " ... do some work + call chdir(save_dir) + endif + +< Can also be used as a |method|: > + GetDir()->chdir() +< +cindent({lnum}) *cindent()* + Get the amount of indent for line {lnum} according the C + indenting rules, as with 'cindent'. + The indent is counted in spaces, the value of 'tabstop' is + relevant. {lnum} is used just like in |getline()|. + When {lnum} is invalid or Vim was not compiled the |+cindent| + feature, -1 is returned. + See |C-indenting|. + + Can also be used as a |method|: > + GetLnum()->cindent() + +clearmatches([{win}]) *clearmatches()* + Clears all matches previously defined for the current window + by |matchadd()| and the |:match| commands. + If {win} is specified, use the window with this number or + window ID instead of the current window. + + Can also be used as a |method|: > + GetWin()->clearmatches() +< + *col()* +col({expr}) The result is a Number, which is the byte index of the column + position given with {expr}. The accepted positions are: + . the cursor position + $ the end of the cursor line (the result is the + number of bytes in the cursor line plus one) + 'x position of mark x (if the mark is not set, 0 is + returned) + v In Visual mode: the start of the Visual area (the + cursor is the end). When not in Visual mode + returns the cursor position. Differs from |'<| in + that it's updated right away. + Additionally {expr} can be [lnum, col]: a |List| with the line + and column number. Most useful when the column is "$", to get + the last column of a specific line. When "lnum" or "col" is + out of range then col() returns zero. + 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. 0 is returned for an error. + 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. This can be used to obtain the column in Insert mode: > + :imap :let save_ve = &ve + \:set ve=all + \:echo col(".") . "\n" + \let &ve = save_ve + +< Can also be used as a |method|: > + GetPos()->col() +< + +complete({startcol}, {matches}) *complete()* *E785* + Set the matches for Insert mode completion. + Can only be used in Insert mode. You need to use a mapping + with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O + or with an expression mapping. + {startcol} is the byte offset in the line where the completed + text start. The text up to the cursor is the original text + that will be replaced by the matches. Use col('.') for an + empty string. "col('.') - 1" will replace one character by a + match. + {matches} must be a |List|. Each |List| item is one match. + See |complete-items| for the kind of items that are possible. + "longest" in 'completeopt' is ignored. + Note that the after calling this function you need to avoid + inserting anything that would cause completion to stop. + The match can be selected with CTRL-N and CTRL-P as usual with + Insert mode completion. The popup menu will appear if + specified, see |ins-completion-menu|. + Example: > + inoremap =ListMonths() + + func! ListMonths() + call complete(col('.'), ['January', 'February', 'March', + \ 'April', 'May', 'June', 'July', 'August', 'September', + \ 'October', 'November', 'December']) + return '' + endfunc +< This isn't very useful, but it shows how it works. Note that + an empty string is returned to avoid a zero being inserted. + + Can also be used as a |method|, the base is passed as the + second argument: > + GetMatches()->complete(col('.')) + +complete_add({expr}) *complete_add()* + Add {expr} to the list of matches. Only to be used by the + function specified with the 'completefunc' option. + Returns 0 for failure (empty string or out of memory), + 1 when the match was added, 2 when the match was already in + the list. + See |complete-functions| for an explanation of {expr}. It is + the same as one item in the list that 'omnifunc' would return. + + Can also be used as a |method|: > + GetMoreMatches()->complete_add() + +complete_check() *complete_check()* + Check for a key typed while looking for completion matches. + This is to be used when looking for matches takes some time. + Returns |TRUE| when searching for matches is to be aborted, + zero otherwise. + Only to be used by the function specified with the + 'completefunc' option. + + +complete_info([{what}]) *complete_info()* + Returns a |Dictionary| with information about Insert mode + completion. See |ins-completion|. + The items are: + mode Current completion mode name string. + See |complete_info_mode| for the values. + pum_visible |TRUE| if popup menu is visible. + See |pumvisible()|. + items List of completion matches. Each item is a + dictionary containing the entries "word", + "abbr", "menu", "kind", "info" and "user_data". + See |complete-items|. + selected Selected item index. First index is zero. + Index is -1 if no item is selected (showing + typed text only, or the last completion after + no item is selected when using the or + keys) + inserted Inserted string. [NOT IMPLEMENT 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. + + Examples: > + " Get all items + call complete_info() + " Get only 'mode' + call complete_info(['mode']) + " Get only 'mode' and 'pum_visible' + call complete_info(['mode', 'pum_visible']) + +< Can also be used as a |method|: > + GetItems()->complete_info() +< + *confirm()* +confirm({msg} [, {choices} [, {default} [, {type}]]]) + confirm() offers the user a dialog, from which a choice can be + made. It returns the number of the choice. For the first + choice this is 1. + Note: confirm() is only supported when compiled with dialog + support, see |+dialog_con| and |+dialog_gui|. + + {msg} is displayed in a |dialog| with {choices} as the + alternatives. When {choices} is missing or empty, "&OK" is + used (and translated). + {msg} is a String, use '\n' to include a newline. Only on + some systems the string is wrapped when it doesn't fit. + + {choices} is a String, with the individual choices separated + by '\n', e.g. > + confirm("Save changes?", "&Yes\n&No\n&Cancel") +< The letter after the '&' is the shortcut key for that choice. + Thus you can type 'c' to select "Cancel". The shortcut does + not need to be the first letter: > + confirm("file has been modified", "&Save\nSave &All") +< For the console, the first letter of each choice is used as + the default shortcut key. Case is ignored. + + The optional {default} argument is the number of the choice + that is made if the user hits . Use 1 to make the first + choice the default one. Use 0 to not set a default. If + {default} is omitted, 1 is used. + + The optional {type} String argument gives the type of dialog. + This is only used for the icon of the GTK, Mac, Motif and + Win32 GUI. It can be one of these values: "Error", + "Question", "Info", "Warning" or "Generic". Only the first + character is relevant. When {type} is omitted, "Generic" is + used. + + If the user aborts the dialog by pressing , CTRL-C, + or another valid interrupt key, confirm() returns 0. + + An example: > + :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2) + :if choice == 0 + : echo "make up your mind!" + :elseif choice == 3 + : echo "tasteful" + :else + : echo "I prefer bananas myself." + :endif +< In a GUI dialog, buttons are used. The layout of the buttons + depends on the 'v' flag in 'guioptions'. If it is included, + the buttons are always put vertically. Otherwise, confirm() + tries to put the buttons in one horizontal line. If they + don't fit, a vertical layout is used anyway. For some systems + the horizontal layout is always used. + + Can also be used as a |method|in: > + BuildMessage()->confirm("&Yes\n&No") +< + *copy()* +copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't + different from using {expr} directly. + When {expr} is a |List| a shallow copy is created. This means + that the original |List| can be changed without changing the + copy, and vice versa. But the items are identical, thus + changing an item changes the contents of both |Lists|. + A |Dictionary| is copied in a similar way as a |List|. + Also see |deepcopy()|. + Can also be used as a |method|: > + mylist->copy() + +cos({expr}) *cos()* + Return the cosine of {expr}, measured in radians, as a |Float|. + {expr} must evaluate to a |Float| or a |Number|. + Examples: > + :echo cos(100) +< 0.862319 > + :echo cos(-4.01) +< -0.646043 + + Can also be used as a |method|: > + Compute()->cos() +< + {only available when compiled with the |+float| feature} + + +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|. + Examples: > + :echo cosh(0.5) +< 1.127626 > + :echo cosh(-0.5) +< -1.127626 + + Can also be used as a |method|: > + Compute()->cosh() +< + {only available when compiled with the |+float| feature} + + +count({comp}, {expr} [, {ic} [, {start}]]) *count()* + Return the number of times an item with value {expr} appears + in |String|, |List| or |Dictionary| {comp}. + + If {start} is given then start with the item with this index. + {start} can only be used with a |List|. + + When {ic} is given and it's |TRUE| then case is ignored. + + When {comp} is a string then the number of not overlapping + occurrences of {expr} is returned. Zero is returned when + {expr} is an empty string. + + Can also be used as a |method|: > + mylist->count(val) +< + *cscope_connection()* +cscope_connection([{num} , {dbpath} [, {prepend}]]) + Checks for the existence of a |cscope| connection. If no + parameters are specified, then the function returns: + 0, if cscope was not available (not compiled in), or + if there are no cscope connections; + 1, if there is at least one cscope connection. + + If parameters are specified, then the value of {num} + determines how existence of a cscope connection is checked: + + {num} Description of existence check + ----- ------------------------------ + 0 Same as no parameters (e.g., "cscope_connection()"). + 1 Ignore {prepend}, and use partial string matches for + {dbpath}. + 2 Ignore {prepend}, and use exact string matches for + {dbpath}. + 3 Use {prepend}, use partial string matches for both + {dbpath} and {prepend}. + 4 Use {prepend}, use exact string matches for both + {dbpath} and {prepend}. + + Note: All string comparisons are case sensitive! + + Examples. Suppose we had the following (from ":cs show"): > + + # pid database name prepend path + 0 27664 cscope.out /usr/local +< + Invocation Return Val ~ + ---------- ---------- > + cscope_connection() 1 + cscope_connection(1, "out") 1 + cscope_connection(2, "out") 0 + cscope_connection(3, "out") 0 + cscope_connection(3, "out", "local") 1 + cscope_connection(4, "out") 0 + cscope_connection(4, "out", "local") 0 + cscope_connection(4, "cscope.out", "/usr/local") 1 +< +cursor({lnum}, {col} [, {off}]) *cursor()* +cursor({list}) + Positions the cursor at the column (byte count) {col} in the + line {lnum}. The first column is one. + + When there is one argument {list} this is used as a |List| + with two, three or four item: + [{lnum}, {col}] + [{lnum}, {col}, {off}] + [{lnum}, {col}, {off}, {curswant}] + This is like the return value of |getpos()| or |getcurpos()|, + but without the first item. + + To position the cursor using the character count, use + |setcursorcharpos()|. + + Does not change the jumplist. + {lnum} is used like with |getline()|. + 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 {lnum} is zero, the cursor will stay in the current line. + If {col} is greater than the number of bytes in the line, + the cursor will be positioned at the last character in the + line. + If {col} is zero, the cursor will stay in the current column. + If {curswant} is given it is used to set the preferred column + for vertical movement. Otherwise {col} is used. + + When 'virtualedit' is used {off} specifies the offset in + screen columns from the start of the character. E.g., a + position within a or after the last character. + Returns 0 when the position could be set, -1 otherwise. + + Can also be used as a |method|: > + GetCursorPos()->cursor() + +debugbreak({pid}) *debugbreak()* + Specifically used to interrupt a program being debugged. It + will cause process {pid} to get a SIGTRAP. Behavior for other + processes is undefined. See |terminal-debugger|. + {only available on MS-Windows} + + Can also be used as a |method|: > + GetPid()->debugbreak() + +deepcopy({expr} [, {noref}]) *deepcopy()* *E698* + Make a copy of {expr}. For Numbers and Strings this isn't + different from using {expr} directly. + When {expr} is a |List| a full copy is created. This means + that the original |List| can be changed without changing the + copy, and vice versa. When an item is a |List| or + |Dictionary|, a copy for it is made, recursively. Thus + changing an item in the copy does not change the contents of + the original |List|. + A |Dictionary| is copied in a similar way as a |List|. + + When {noref} is omitted or zero a contained |List| or + |Dictionary| is only copied once. All references point to + this single copy. With {noref} set to 1 every occurrence of a + |List| or |Dictionary| results in a new copy. This also means + that a cyclic reference causes deepcopy() to fail. + *E724* + Nesting is possible up to 100 levels. When there is an item + that refers back to a higher level making a deep copy with + {noref} set to 1 will fail. + Also see |copy()|. + + Can also be used as a |method|: > + GetObject()->deepcopy() + +delete({fname} [, {flags}]) *delete()* + Without {flags} or with {flags} empty: Deletes the file by the + name {fname}. This also works when {fname} is a symbolic link. + + 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. + + A symbolic link itself is deleted, not what it points to. + + The result is a Number, which is 0/false if the delete + operation was successful and -1/true when the deletion failed + or partly failed. + + Use |remove()| to delete an item from a |List|. + To delete a line from the buffer use |:delete| or + |deletebufline()|. + + Can also be used as a |method|: > + GetName()->delete() + +deletebufline({buf}, {first} [, {last}]) *deletebufline()* + Delete lines {first} to {last} (inclusive) from buffer {buf}. + If {last} is omitted then delete line {first} only. + On success 0 is returned, on failure 1 is returned. + + This function works only for loaded buffers. First call + |bufload()| if needed. + + For the use of {buf}, see |bufname()| above. + + {first} and {last} are used like with |getline()|. Note that + when using |line()| this refers to the current buffer. Use "$" + to refer to the last line in buffer {buf}. + + Can also be used as a |method|: > + GetBuffer()->deletebufline(1) +< + *did_filetype()* +did_filetype() Returns |TRUE| when autocommands are being executed and the + FileType event has been triggered at least once. Can be used + to avoid triggering the FileType event again in the scripts + that detect the file type. |FileType| + Returns |FALSE| when `:setf FALLBACK` was used. + When editing another file, the counter is reset, thus this + really checks if the FileType event has been triggered for the + current buffer. This allows an autocommand that starts + editing another buffer to set 'filetype' and load a syntax + file. + +diff_filler({lnum}) *diff_filler()* + Returns the number of filler lines above line {lnum}. + These are the lines that were inserted at this point in + another diff'ed window. These filler lines are shown in the + display but don't exist in the buffer. + {lnum} is used like with |getline()|. Thus "." is the current + line, "'m" mark m, etc. + Returns 0 if the current window is not in diff mode. + + Can also be used as a |method|: > + GetLnum()->diff_filler() + +diff_hlID({lnum}, {col}) *diff_hlID()* + Returns the highlight ID for diff mode at line {lnum} column + {col} (byte index). When the current line does not have a + diff change zero is returned. + {lnum} is used like with |getline()|. Thus "." is the current + line, "'m" mark m, etc. + {col} is 1 for the leftmost column, {lnum} is 1 for the first + line. + The highlight ID can be used with |synIDattr()| to obtain + syntax information about the highlighting. + + Can also be used as a |method|: > + GetLnum()->diff_hlID(col) +< + +digraph_get({chars}) *digraph_get()* *E1214* + Return the digraph of {chars}. This should be a string with + exactly two characters. If {chars} are not just two + characters, or the digraph of {chars} does not exist, an error + is given and an empty string is returned. + + The character will be converted from Unicode to 'encoding' + when needed. This does require the conversion to be + available, it might fail. + + Also see |digraph_getlist()|. + + Examples: > + " Get a built-in digraph + :echo digraph_get('00') " Returns '∞' + + " Get a user-defined digraph + :call digraph_set('aa', 'あ') + :echo digraph_get('aa') " Returns 'あ' +< + Can also be used as a |method|: > + GetChars()->digraph_get() +< + This function works only when compiled with the |+digraphs| + feature. If this feature is disabled, this function will + display an error message. + + +digraph_getlist([{listall}]) *digraph_getlist()* + Return a list of digraphs. If the {listall} argument is given + and it is TRUE, return all digraphs, including the default + digraphs. Otherwise, return only user-defined digraphs. + + The characters will be converted from Unicode to 'encoding' + when needed. This does require the conservation to be + available, it might fail. + + Also see |digraph_get()|. + + Examples: > + " Get user-defined digraphs + :echo digraph_getlist() + + " Get all the digraphs, including default digraphs + :echo digraph_getlist(1) +< + Can also be used as a |method|: > + GetNumber()->digraph_getlist() +< + This function works only when compiled with the |+digraphs| + feature. If this feature is disabled, this function will + display an error message. + + +digraph_set({chars}, {digraph}) *digraph_set()* *E1205* + Add digraph {chars} to the list. {chars} must be a string + with two characters. {digraph} is a string with one UTF-8 + encoded character. Be careful, composing characters are NOT + ignored. This function is similar to |:digraphs| command, but + useful to add digraphs start with a white space. + + The function result is v:true if |digraph| is registered. If + this fails an error message is given and v:false is returned. + + If you want to define multiple digraphs at once, you can use + |digraph_setlist()|. + + Example: > + call digraph_set(' ', 'あ') +< + Can be used as a |method|: > + GetString()->digraph_set('あ') +< + This function works only when compiled with the |+digraphs| + feature. If this feature is disabled, this function will + display an error message. + + +digraph_setlist({digraphlist}) *digraph_setlist()* + Similar to |digraph_set()| but this function can add multiple + digraphs at once. {digraphlist} is a list composed of lists, + where each list contains two strings with {chars} and + {digraph} as in |digraph_set()|. + Example: > + call digraph_setlist([['aa', 'あ'], ['ii', 'い']]) +< + It is similar to the following: > + for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']] + call digraph_set(chars, digraph) + endfor +< Except that the function returns after the first error, + following digraphs will not be added. + + Can be used as a |method|: > + GetList()->digraph_setlist() +< + This function works only when compiled with the |+digraphs| + feature. If this feature is disabled, this function will + display an error message. + + +echoraw({string}) *echoraw()* + Output {string} as-is, including unprintable characters. + This can be used to output a terminal code. For example, to + disable modifyOtherKeys: > + call echoraw(&t_TE) +< and to enable it again: > + call echoraw(&t_TI) +< Use with care, you can mess up the terminal this way. + + +empty({expr}) *empty()* + Return the Number 1 if {expr} is empty, zero otherwise. + - A |List| or |Dictionary| is empty when it does not have any + items. + - A |String| is empty when its length is zero. + - A |Number| and |Float| are empty when their value is zero. + - |v:false|, |v:none| and |v:null| are empty, |v:true| is not. + - A |Job| is empty when it failed to start. + - A |Channel| is empty when it is closed. + - A |Blob| is empty when its length is zero. + + For a long |List| this is much faster than comparing the + length with zero. + + Can also be used as a |method|: > + mylist->empty() + +environ() *environ()* + Return all of environment variables as dictionary. You can + check if an environment variable exists like this: > + :echo has_key(environ(), 'HOME') +< Note that the variable name may be CamelCase; to ignore case + use this: > + :echo index(keys(environ()), 'HOME', 0, 1) != -1 + +escape({string}, {chars}) *escape()* + Escape the characters in {chars} that occur in {string} with a + backslash. Example: > + :echo escape('c:\program files\vim', ' \') +< results in: > + c:\\program\ files\\vim +< Also see |shellescape()| and |fnameescape()|. + + Can also be used as a |method|: > + GetText()->escape(' \') +< + *eval()* +eval({string}) Evaluate {string} and return the result. Especially useful to + turn the result of |string()| back into the original value. + This works for Numbers, Floats, Strings, Blobs and composites + of them. Also works for |Funcref|s that refer to existing + functions. + + Can also be used as a |method|: > + argv->join()->eval() + +eventhandler() *eventhandler()* + Returns 1 when inside an event handler. That is that Vim got + interrupted while waiting for the user to type a character, + e.g., when dropping a file on Vim. This means interactive + commands cannot be used. Otherwise zero is returned. + +executable({expr}) *executable()* + This function checks if an executable with the name {expr} + exists. {expr} must be the name of the program without any + arguments. + executable() uses the value of $PATH and/or the normal + searchpath for programs. *PATHEXT* + On MS-Windows the ".exe", ".bat", etc. can optionally be + included. Then the extensions in $PATHEXT are tried. Thus if + "foo.exe" does not exist, "foo.exe.bat" can be found. If + $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot + by itself can be used in $PATHEXT to try using the name + without an extension. When 'shell' looks like a Unix shell, + then the name is also tried without adding an extension. + On MS-Windows it only checks if the file exists and is not a + directory, not if it's really executable. + On MS-Windows an executable in the same directory as Vim is + always found. Since this directory is added to $PATH it + should also work to execute it |win32-PATH|. + The result is a Number: + 1 exists + 0 does not exist + -1 not implemented on this system + |exepath()| can be used to get the full path of an executable. + + Can also be used as a |method|: > + GetCommand()->executable() + +execute({command} [, {silent}]) *execute()* + Execute an Ex command or commands and return the output as a + string. + {command} can be a string or a List. In case of a List the + lines are executed one by one. + This is equivalent to: > + redir => var + {command} + redir END +< + 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: > + split(execute('args'), "\n") + +< To execute a command in another window than the current one + use `win_execute()`. + + When used recursively the output of the recursive call is not + included in the output of the higher level call. + + Can also be used as a |method|: > + GetCommand()->execute() + +exepath({expr}) *exepath()* + If {expr} is an executable and is either an absolute path, a + relative path or found in $PATH, return the full path. + Note that the current directory is used when {expr} starts + with "./", which may be a problem for Vim: > + echo exepath(v:progpath) +< If {expr} cannot be found in $PATH or is not executable then + an empty string is returned. + + Can also be used as a |method|: > + GetCommand()->exepath() +< + *exists()* +exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined, + zero otherwise. + + Note: In a compiled |:def| function the evaluation is done at + runtime. Use `exists_compiled()` to evaluate the expression + at compile time. + + For checking for a supported feature use |has()|. + For checking if a file exists use |filereadable()|. + + The {expr} argument is a string, which contains one of these: + &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 + varname internal variable (see + |internal-variables|). Also works + for |curly-braces-names|, |Dictionary| + entries, |List| items, etc. + Does not work for local variables in a + compiled `:def` function. + 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 + :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. + #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") + 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 more strict in + the future, thus don't count on it! + Working example: > + exists(":make") +< NOT working example: > + exists(":make install") + +< Note that the argument must be a string, not the name of the + variable itself. For example: > + exists(bufcount) +< This doesn't check for existence of the "bufcount" variable, + but gets the value of "bufcount", and checks if that exists. + + Can also be used as a |method|: > + Varname()->exists() +< + +exists_compiled({expr}) *exists_compiled()* + Like `exists()` but evaluated at compile time. This is useful + to skip a block where a function is used that would otherwise + give an error: > + if exists_compiled('*ThatFunction') + ThatFunction('works') + endif +< If `exists()` were used then a compilation error would be + given if ThatFunction() is not defined. + + {expr} must be a literal string. *E1232* + Can only be used in a |:def| function. *E1233* + This does not work to check for arguments or local variables. + + +exp({expr}) *exp()* + Return the exponential of {expr} as a |Float| in the range + [0, inf]. + {expr} must evaluate to a |Float| or a |Number|. + Examples: > + :echo exp(2) +< 7.389056 > + :echo exp(-1) +< 0.367879 + + Can also be used as a |method|: > + Compute()->exp() +< + {only available when compiled with the |+float| feature} + + +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. + + 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 || + call stack + word under the cursor + WORD under the cursor + the {clientid} of the last received + message |server2client()| + Modifiers: + :p expand to full path + :h head (last path component removed) + :t tail (last path component only) + :r root (one extension removed) + :e extension only + + Example: > + :let &tags = expand("%:p:h") . "/tags" +< Note that when expanding a string that starts with '%', '#' or + '<', any following text is ignored. This does NOT work: > + :let doesntwork = expand("%:h.bak") +< Use this: > + :let doeswork = expand("%:h") . ".bak" +< Also note that expanding "" and others only returns the + referenced file name without further expansion. If "" + is "~/.cshrc", you need to do another expand() to have the + "~/" expanded into the path of the home directory: > + :echo expand(expand("")) +< + There cannot be white space between the variables and the + following modifier. The |fnamemodify()| function can be used + to modify normal file names. + + When using '%' or '#', and the current or alternate file name + is not defined, an empty string is used. Using "%:p" in a + buffer with no name, results in the current directory, with a + '/' added. + + When {string} does not start with '%', '#' or '<', it is + expanded like a file name is expanded on the command line. + 'suffixes' and 'wildignore' are used, unless the optional + {nosuf} argument is given and it is |TRUE|. + Names for non-existing files are included. The "**" item can + be used to search in a directory tree. For example, to find + all "README" files in the current directory and below: > + :echo expand("**/README") +< + expand() can also be used to expand variables and environment + variables that are only known in a shell. But this can be + slow, because a shell may be used to do the expansion. See + |expr-env-expand|. + The expanded variable is still handled like a list of file + names. When an environment variable cannot be expanded, it is + left unchanged. Thus ":echo expand('$FOOBAR')" results in + "$FOOBAR". + + See |glob()| for finding existing files. See |system()| for + getting the raw output of an external command. + + Can also be used as a |method|: > + Getpattern()->expand() + +expandcmd({string}) *expandcmd()* + Expand special items in String {string} like what is done for + an Ex command such as `:edit`. This expands special keywords, + like with |expand()|, and environment variables, anywhere in + {string}. "~user" and "~/path" are only expanded at the + start. + Returns the expanded string. Example: > + :echo expandcmd('make %<.o') + +< Can also be used as a |method|: > + GetCommand()->expandcmd() +< +extend({expr1}, {expr2} [, {expr3}]) *extend()* + {expr1} and {expr2} must be both |Lists| or both + |Dictionaries|. + + If they are |Lists|: Append {expr2} to {expr1}. + If {expr3} is given insert the items of {expr2} before the + item with index {expr3} in {expr1}. When {expr3} is zero + insert before the first item. When {expr3} is equal to + len({expr1}) then {expr2} is appended. + Examples: > + :echo sort(extend(mylist, [7, 5])) + :call extend(mylist, [2, 3], 1) +< When {expr1} is the same List as {expr2} then the number of + items copied is equal to the original length of the List. + E.g., when {expr3} is 1 you get N new copies of the first item + (where N is the original length of the List). + Use |add()| to concatenate one item to a list. To concatenate + two lists into a new list use the + operator: > + :let newlist = [1, 2, 3] + [4, 5] +< + If they are |Dictionaries|: + Add all entries from {expr2} to {expr1}. + If a key exists in both {expr1} and {expr2} then {expr3} is + used to decide what to do: + {expr3} = "keep": keep the value of {expr1} + {expr3} = "force": use the value of {expr2} + {expr3} = "error": give an error message *E737* + When {expr3} is omitted then "force" is assumed. + + {expr1} is changed when {expr2} is not empty. If necessary + make a copy of {expr1} first. + {expr2} remains unchanged. + When {expr1} is locked and {expr2} is not empty the operation + fails. + Returns {expr1}. + + Can also be used as a |method|: > + mylist->extend(otherlist) + + +extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()* + Like |extend()| but instead of adding items to {expr1} a new + List or Dictionary is created and returned. {expr1} remains + unchanged. Items can still be changed by {expr2}, if you + don't want that use |deepcopy()| first. + + +feedkeys({string} [, {mode}]) *feedkeys()* + Characters in {string} are queued for processing as if they + come from a mapping or were typed by the user. + + By default the string is added to the end of the typeahead + buffer, thus if a mapping is still being executed the + characters come after them. Use the 'i' flag to insert before + other characters, they will be executed next, before any + characters from a mapping. + + The function does not wait for processing of keys contained in + {string}. + + To include special keys into {string}, use double-quotes + and "\..." notation |expr-quote|. For example, + feedkeys("\") simulates pressing of the key. But + feedkeys('\') pushes 5 characters. + A special code that might be useful is , it exits the + wait for a character without doing anything. ** + + {mode} is a String, which can contain these character flags: + 'm' Remap keys. This is default. If {mode} is absent, + keys are remapped. + 'n' Do not remap keys. + 't' Handle keys as if typed; otherwise they are handled as + if coming from a mapping. This matters for undo, + opening folds, etc. + 'L' Lowlevel input. Only works for Unix or when using the + GUI. Keys are used as if they were coming from the + terminal. Other flags are not used. *E980* + When a CTRL-C interrupts and 't' is included it sets + the internal "got_int" flag. + 'i' Insert the string instead of appending (see above). + 'x' Execute commands until typeahead is empty. This is + similar to using ":normal!". You can call feedkeys() + several times without 'x' and then one time with 'x' + (possibly with an empty {string}) to execute all the + typeahead. Note that when Vim ends in Insert mode it + will behave as if is typed, to avoid getting + stuck, waiting for a character to be typed before the + script continues. + Note that if you manage to call feedkeys() while + executing commands, thus calling it recursively, then + all typeahead will be consumed by the last call. + '!' When used with 'x' will not end Insert mode. Can be + used in a test when a timer is set to exit Insert mode + a little later. Useful for testing CursorHoldI. + + Return value is always 0. + + Can also be used as a |method|: > + GetInput()->feedkeys() + +filereadable({file}) *filereadable()* + The result is a Number, which is |TRUE| when a file with the + name {file} exists, and can be read. If {file} doesn't exist, + or is a directory, the result is |FALSE|. {file} is any + expression, which is used as a String. + If you don't care about the file being readable you can use + |glob()|. + {file} is used as-is, you may want to expand wildcards first: > + echo filereadable('~/.vimrc') + 0 + echo filereadable(expand('~/.vimrc')) + 1 + +< Can also be used as a |method|: > + GetName()->filereadable() +< *file_readable()* + Obsolete name: file_readable(). + + +filewritable({file}) *filewritable()* + The result is a Number, which is 1 when a file with the + name {file} exists, and can be written. If {file} doesn't + exist, or is not writable, the result is 0. If {file} is a + directory, and we can write to it, the result is 2. + + Can also be used as a |method|: > + GetName()->filewritable() + + +filter({expr1}, {expr2}) *filter()* + {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. + For each item in {expr1} evaluate {expr2} and when the result + is zero or false remove the item from the |List| or + |Dictionary|. Similarly for each byte in a |Blob| and each + charactor in a |String|. + + {expr2} must be a |string| or |Funcref|. + + If {expr2} is a |string|, inside {expr2} |v:val| has the value + of the current item. For a |Dictionary| |v:key| has the key + of the current item and for a |List| |v:key| has the index of + the current item. For a |Blob| |v:key| has the index of the + current byte. For a |String| |v:key| has the index of the + current character. + Examples: > + call filter(mylist, 'v:val !~ "OLD"') +< Removes the items where "OLD" appears. > + call filter(mydict, 'v:key >= 8') +< Removes the items with a key below 8. > + call filter(var, 0) +< Removes all the items, thus clears the |List| or |Dictionary|. + + Note that {expr2} is the result of expression and is then + used as an expression again. Often it is good to use a + |literal-string| to avoid having to double backslashes. + + If {expr2} is a |Funcref| it must take two arguments: + 1. the key or the index of the current item. + 2. the value of the current item. + The function must return |TRUE| if the item should be kept. + Example that keeps the odd items of a list: > + func Odd(idx, val) + return a:idx % 2 == 1 + endfunc + call filter(mylist, function('Odd')) +< It is shorter when using a |lambda|: > + call filter(myList, {idx, val -> idx * val <= 42}) +< If you do not use "val" you can leave it out: > + call filter(myList, {idx -> idx % 2 == 1}) +< + In |Vim9| script the result must be true, false, zero or one. + Other values will result in a type error. + + For a |List| and a |Dictionary| the operation is done + in-place. If you want it to remain unmodified make a copy + first: > + :let l = filter(copy(mylist), 'v:val =~ "KEEP"') + +< Returns {expr1}, the |List| or |Dictionary| that was filtered, + or a new |Blob| or |String|. + When an error is encountered while evaluating {expr2} no + further items in {expr1} are processed. + When {expr2} is a Funcref errors inside a function are ignored, + unless it was defined with the "abort" flag. + + Can also be used as a |method|: > + mylist->filter(expr2) + +finddir({name} [, {path} [, {count}]]) *finddir()* + Find directory {name} in {path}. Supports both downwards and + upwards recursive directory searches. See |file-searching| + for the syntax of {path}. + + Returns the path of the first found match. When the found + directory is below the current directory a relative path is + returned. Otherwise a full path is returned. + If {path} is omitted or empty then 'path' is used. + + If the optional {count} is given, find {count}'s occurrence of + {name} in {path} instead of the first one. + When {count} is negative return all the matches in a |List|. + + This is quite similar to the ex-command `:find`. + {only available when compiled with the |+file_in_path| + feature} + + Can also be used as a |method|: > + GetName()->finddir() + +findfile({name} [, {path} [, {count}]]) *findfile()* + Just like |finddir()|, but find a file instead of a directory. + Uses 'suffixesadd'. + Example: > + :echo findfile("tags.vim", ".;") +< Searches from the directory of the current file upwards until + it finds the file "tags.vim". + + Can also be used as a |method|: > + GetName()->findfile() + +flatten({list} [, {maxdepth}]) *flatten()* + Flatten {list} up to {maxdepth} levels. Without {maxdepth} + the result is a |List| without nesting, as if {maxdepth} is + a very large number. + The {list} is changed in place, use |flattennew()| if you do + not want that. + In Vim9 script flatten() cannot be used, you must always use + |flattennew()|. + *E900* + {maxdepth} means how deep in nested lists changes are made. + {list} is not modified when {maxdepth} is 0. + {maxdepth} must be positive number. + + If there is an error the number zero is returned. + + Example: > + :echo flatten([1, [2, [3, 4]], 5]) +< [1, 2, 3, 4, 5] > + :echo flatten([1, [2, [3, 4]], 5], 1) +< [1, 2, [3, 4], 5] + + Can also be used as a |method|: > + mylist->flatten() +< +flattennew({list} [, {maxdepth}]) *flattennew()* + Like |flatten()| but first make a copy of {list}. + + +float2nr({expr}) *float2nr()* + Convert {expr} to a Number by omitting the part after the + decimal point. + {expr} must evaluate to a |Float| or a Number. + When the value of {expr} is out of range for a |Number| the + result is truncated to 0x7fffffff or -0x7fffffff (or when + 64-bit Number support is enabled, 0x7fffffffffffffff or + -0x7fffffffffffffff). NaN results in -0x80000000 (or when + 64-bit Number support is enabled, -0x8000000000000000). + Examples: > + echo float2nr(3.95) +< 3 > + echo float2nr(-23.45) +< -23 > + echo float2nr(1.0e100) +< 2147483647 (or 9223372036854775807) > + echo float2nr(-1.0e150) +< -2147483647 (or -9223372036854775807) > + echo float2nr(1.0e-100) +< 0 + + Can also be used as a |method|: > + Compute()->float2nr() +< + {only available when compiled with the |+float| feature} + + +floor({expr}) *floor()* + Return the largest integral value less than or equal to + {expr} as a |Float| (round down). + {expr} must evaluate to a |Float| or a |Number|. + Examples: > + echo floor(1.856) +< 1.0 > + echo floor(-5.456) +< -6.0 > + echo floor(4.0) +< 4.0 + + Can also be used as a |method|: > + Compute()->floor() +< + {only available when compiled with the |+float| feature} + + +fmod({expr1}, {expr2}) *fmod()* + Return the remainder of {expr1} / {expr2}, even if the + division is not representable. Returns {expr1} - i * {expr2} + for some integer i such that if {expr2} is non-zero, the + result has the same sign as {expr1} and magnitude less than + the magnitude of {expr2}. If {expr2} is zero, the value + returned is zero. The value returned is a |Float|. + {expr1} and {expr2} must evaluate to a |Float| or a |Number|. + Examples: > + :echo fmod(12.33, 1.22) +< 0.13 > + :echo fmod(-12.33, 1.22) +< -0.13 + + Can also be used as a |method|: > + Compute()->fmod(1.22) +< + {only available when compiled with |+float| feature} + + +fnameescape({string}) *fnameescape()* + Escape {string} for use as file name command argument. All + characters that have a special meaning, such as '%' and '|' + are escaped with a backslash. + For most systems the characters escaped are + " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash + appears in a filename, it depends on the value of 'isfname'. + A leading '+' and '>' is also escaped (special after |:edit| + and |:write|). And a "-" by itself (special after |:cd|). + Example: > + :let fname = '+some str%nge|name' + :exe "edit " . fnameescape(fname) +< results in executing: > + edit \+some\ str\%nge\|name +< + Can also be used as a |method|: > + GetName()->fnameescape() + +fnamemodify({fname}, {mods}) *fnamemodify()* + Modify file name {fname} according to {mods}. {mods} is a + string of characters like it is used for file names on the + command line. See |filename-modifiers|. + Example: > + :echo fnamemodify("main.c", ":p:h") +< results in: > + /home/mool/vim/vim/src +< If {mods} is empty then {fname} is returned. + Note: Environment variables don't work in {fname}, use + |expand()| first then. + + Can also be used as a |method|: > + GetName()->fnamemodify(':p:h') + +foldclosed({lnum}) *foldclosed()* + The result is a Number. If the line {lnum} is in a closed + fold, the result is the number of the first line in that fold. + If the line {lnum} is not in a closed fold, -1 is returned. + {lnum} is used like with |getline()|. Thus "." is the current + line, "'m" mark m, etc. + + Can also be used as a |method|: > + GetLnum()->foldclosed() + +foldclosedend({lnum}) *foldclosedend()* + The result is a Number. If the line {lnum} is in a closed + fold, the result is the number of the last line in that fold. + If the line {lnum} is not in a closed fold, -1 is returned. + {lnum} is used like with |getline()|. Thus "." is the current + line, "'m" mark m, etc. + + Can also be used as a |method|: > + GetLnum()->foldclosedend() + +foldlevel({lnum}) *foldlevel()* + The result is a Number, which is the foldlevel of line {lnum} + in the current buffer. For nested folds the deepest level is + returned. If there is no fold at line {lnum}, zero is + returned. It doesn't matter if the folds are open or closed. + When used while updating folds (from 'foldexpr') -1 is + returned for lines where folds are still to be updated and the + foldlevel is unknown. As a special case the level of the + previous line is usually available. + {lnum} is used like with |getline()|. Thus "." is the current + line, "'m" mark m, etc. + + Can also be used as a |method|: > + GetLnum()->foldlevel() +< + *foldtext()* +foldtext() Returns a String, to be displayed for a closed fold. This is + the default function used for the 'foldtext' option and should + only be called from evaluating 'foldtext'. It uses the + |v:foldstart|, |v:foldend| and |v:folddashes| variables. + The returned string looks like this: > + +-- 45 lines: abcdef +< The number of leading dashes depends on the foldlevel. The + "45" is the number of lines in the fold. "abcdef" is the text + in the first non-blank line of the fold. Leading white space, + "//" or "/*" and the text from the 'foldmarker' and + 'commentstring' options is removed. + When used to draw the actual foldtext, the rest of the line + will be filled with the fold char from the 'fillchars' + setting. + {not available when compiled without the |+folding| feature} + +foldtextresult({lnum}) *foldtextresult()* + Returns the text that is displayed for the closed fold at line + {lnum}. Evaluates 'foldtext' in the appropriate context. + When there is no closed fold at {lnum} an empty string is + returned. + {lnum} is used like with |getline()|. Thus "." is the current + line, "'m" mark m, etc. + Useful when exporting folded text, e.g., to HTML. + {not available when compiled without the |+folding| feature} + + + Can also be used as a |method|: > + GetLnum()->foldtextresult() +< + *foreground()* +foreground() Move the Vim window to the foreground. Useful when sent from + a client to a Vim server. |remote_send()| + On Win32 systems this might not work, the OS does not always + allow a window to bring itself to the foreground. Use + |remote_foreground()| instead. + {only in the Win32, Athena, Motif and GTK GUI versions and the + Win32 console version} + +fullcommand({name}) *fullcommand()* + Get the full command name from a short abbreviated command + name; see |20.2| for details on command abbreviations. + + The string argument {name} may start with a `:` and can + include a [range], these are skipped and not returned. + Returns an empty string if a command doesn't exist or if it's + ambiguous (for user-defined commands). + + For example `fullcommand('s')`, `fullcommand('sub')`, + `fullcommand(':%substitute')` all return "substitute". + + Can also be used as a |method|: > + GetName()->fullcommand() +< + *funcref()* +funcref({name} [, {arglist}] [, {dict}]) + Just like |function()|, but the returned Funcref will lookup + the function by reference, not by name. This matters when the + function {name} is redefined later. + + Unlike |function()|, {name} must be an existing user function. + Also for autoloaded functions. {name} cannot be a builtin + function. + + Can also be used as a |method|: > + GetFuncname()->funcref([arg]) +< + *function()* *partial* *E700* *E922* *E923* +function({name} [, {arglist}] [, {dict}]) + Return a |Funcref| variable that refers to function {name}. + {name} can be the name of a user defined function or an + internal function. + + {name} can also be a Funcref or a partial. When it is a + partial the dict stored in it will be used and the {dict} + argument is not allowed. E.g.: > + let FuncWithArg = function(dict.Func, [arg]) + let Broken = function(dict.Func, [arg], dict) +< + When using the Funcref the function will be found by {name}, + also when it was redefined later. Use |funcref()| to keep the + same function. + + When {arglist} or {dict} is present this creates a partial. + That means the argument list and/or the dictionary is stored in + the Funcref and will be used when the Funcref is called. + + The arguments are passed to the function in front of other + arguments, but after any argument from |method|. Example: > + func Callback(arg1, arg2, name) + ... + let Partial = function('Callback', ['one', 'two']) + ... + call Partial('name') +< Invokes the function as with: > + call Callback('one', 'two', 'name') + +< With a |method|: > + func Callback(one, two, three) + ... + let Partial = function('Callback', ['two']) + ... + eval 'one'->Partial('three') +< Invokes the function as with: > + call Callback('one', 'two', 'three') + +< The function() call can be nested to add more arguments to the + Funcref. The extra arguments are appended to the list of + arguments. Example: > + func Callback(arg1, arg2, name) + ... + let Func = function('Callback', ['one']) + let Func2 = function(Func, ['two']) + ... + call Func2('name') +< Invokes the function as with: > + call Callback('one', 'two', 'name') + +< The Dictionary is only useful when calling a "dict" function. + In that case the {dict} is passed in as "self". Example: > + function Callback() dict + echo "called for " . self.name + endfunction + ... + let context = {"name": "example"} + let Func = function('Callback', context) + ... + call Func() " will echo: called for example +< The use of function() is not needed when there are no extra + arguments, these two are equivalent: > + let Func = function('Callback', context) + let Func = context.Callback + +< The argument list and the Dictionary can be combined: > + function Callback(arg1, count) dict + ... + let context = {"name": "example"} + let Func = function('Callback', ['one'], context) + ... + call Func(500) +< Invokes the function as with: > + call context.Callback('one', 500) +< + Can also be used as a |method|: > + GetFuncname()->function([arg]) + + +garbagecollect([{atexit}]) *garbagecollect()* + Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs| + that have circular references. + + There is hardly ever a need to invoke this function, as it is + automatically done when Vim runs out of memory or is waiting + for the user to press a key after 'updatetime'. Items without + circular references are always freed when they become unused. + This is useful if you have deleted a very big |List| and/or + |Dictionary| with circular references in a script that runs + for a long time. + + When the optional {atexit} argument is one, garbage + collection will also be done when exiting Vim, if it wasn't + done before. This is useful when checking for memory leaks. + + The garbage collection is not done immediately but only when + it's safe to perform. This is when waiting for the user to + type a character. To force garbage collection immediately use + |test_garbagecollect_now()|. + +get({list}, {idx} [, {default}]) *get()* + Get item {idx} from |List| {list}. When this item is not + available return {default}. Return zero when {default} is + omitted. + Preferably used as a |method|: > + mylist->get(idx) +get({blob}, {idx} [, {default}]) + Get byte {idx} from |Blob| {blob}. When this byte is not + available return {default}. Return -1 when {default} is + omitted. + Preferably used as a |method|: > + myblob->get(idx) +get({dict}, {key} [, {default}]) + Get item with key {key} from |Dictionary| {dict}. When this + item is not available return {default}. Return zero when + {default} is omitted. Useful example: > + let val = get(g:, 'var_name', 'default') +< This gets the value of g:var_name if it exists, and uses + 'default' when it does not exist. + Preferably used as a |method|: > + mydict->get(key) +get({func}, {what}) + Get an item with from Funcref {func}. Possible values for + {what} are: + "name" The function name + "func" The function + "dict" The dictionary + "args" The list with arguments + Preferably used as a |method|: > + myfunc->get(what) +< + *getbufinfo()* +getbufinfo([{buf}]) +getbufinfo([{dict}]) + Get information about buffers as a List of Dictionaries. + + Without an argument information about all the buffers is + returned. + + When the argument is a |Dictionary| only the buffers matching + the specified criteria are returned. The following keys can + be specified in {dict}: + buflisted include only listed buffers. + bufloaded include only loaded buffers. + bufmodified include only modified buffers. + + Otherwise, {buf} specifies a particular buffer to return + information for. For the use of {buf}, see |bufname()| + above. If the buffer is found the returned List has one item. + Otherwise the result is an empty list. + + Each returned List item is a dictionary with the following + entries: + bufnr Buffer number. + changed TRUE if the buffer is modified. + changedtick Number of changes made to the buffer. + hidden TRUE if the buffer is hidden. + lastused Timestamp in seconds, like + |localtime()|, when the buffer was + last used. + {only with the |+viminfo| feature} + listed TRUE if the buffer is listed. + lnum Line number used for the buffer when + opened in the current window. + Only valid if the buffer has been + displayed in the window in the past. + If you want the line number of the + last known cursor position in a given + window, use |line()|: > + :echo line('.', {winid}) +< + linecount Number of lines in the buffer (only + valid when loaded) + loaded TRUE if the buffer is loaded. + name Full path to the file in the buffer. + signs List of signs placed in the buffer. + Each list item is a dictionary with + the following fields: + id sign identifier + lnum line number + name sign name + variables A reference to the dictionary with + buffer-local variables. + windows List of |window-ID|s that display this + buffer + popups List of popup |window-ID|s that + display this buffer + + Examples: > + for buf in getbufinfo() + echo buf.name + endfor + for buf in getbufinfo({'buflisted':1}) + if buf.changed + .... + endif + endfor +< + To get buffer-local options use: > + getbufvar({bufnr}, '&option_name') +< + Can also be used as a |method|: > + GetBufnr()->getbufinfo() +< + + *getbufline()* +getbufline({buf}, {lnum} [, {end}]) + Return a |List| with the lines starting from {lnum} to {end} + (inclusive) in the buffer {buf}. If {end} is omitted, a + |List| with only the line {lnum} is returned. + + For the use of {buf}, see |bufname()| above. + + For {lnum} and {end} "$" can be used for the last line of the + buffer. Otherwise a number must be used. + + When {lnum} is smaller than 1 or bigger than the number of + lines in the buffer, an empty |List| is returned. + + When {end} is greater than the number of lines in the buffer, + it is treated as {end} is set to the number of lines in the + buffer. When {end} is before {lnum} an empty |List| is + returned. + + This function works only for loaded buffers. For unloaded and + non-existing buffers, an empty |List| is returned. + + Example: > + :let lines = getbufline(bufnr("myfile"), 1, "$") + +< Can also be used as a |method|: > + GetBufnr()->getbufline(lnum) + +getbufvar({buf}, {varname} [, {def}]) *getbufvar()* + The result is the value of option or local buffer variable + {varname} in buffer {buf}. Note that the name without "b:" + must be used. + The {varname} argument is a string. + When {varname} is empty returns a |Dictionary| with all the + buffer-local variables. + When {varname} is equal to "&" returns a |Dictionary| with all + the buffer-local options. + Otherwise, when {varname} starts with "&" returns the value of + a buffer-local option. + This also works for a global or buffer-local option, but it + doesn't work for a global variable, window-local variable or + window-local option. + For the use of {buf}, see |bufname()| above. + When the buffer or variable doesn't exist {def} or an empty + string is returned, there is no error message. + Examples: > + :let bufmodified = getbufvar(1, "&mod") + :echo "todo myvar = " . getbufvar("todo", "myvar") + +< Can also be used as a |method|: > + GetBufnr()->getbufvar(varname) +< +getchangelist([{buf}]) *getchangelist()* + Returns the |changelist| for the buffer {buf}. For the use + of {buf}, see |bufname()| above. If buffer {buf} doesn't + exist, an empty list is returned. + + The returned list contains two entries: a list with the change + locations and the current position in the list. Each + entry in the change list is a dictionary with the following + entries: + col column number + coladd column offset for 'virtualedit' + lnum line number + If buffer {buf} is the current buffer, then the current + position refers to the position in the list. For other + buffers, it is set to the length of the list. + + Can also be used as a |method|: > + GetBufnr()->getchangelist() + +getchar([expr]) *getchar()* + Get a single character from the user or input stream. + If [expr] is omitted, wait until a character is available. + If [expr] is 0, only get a character when one is available. + Return zero otherwise. + If [expr] is 1, only check if a character is available, it is + not consumed. Return zero if no character available. + If you prefer always getting a string use |getcharstr()|. + + Without [expr] and when [expr] is 0 a whole character or + special key is returned. If it is a single character, the + result is a number. Use nr2char() to convert it to a String. + Otherwise a String is returned with the encoded character. + For a special key it's a String with a sequence of bytes + starting with 0x80 (decimal: 128). This is the same value as + the String "\", e.g., "\". The returned value is + also a String when a modifier (shift, control, alt) was used + that is not included in the character. + + When [expr] is 0 and Esc is typed, there will be a short delay + while Vim waits to see if this is the start of an escape + sequence. + + When [expr] is 1 only the first byte is returned. For a + one-byte character it is the character itself as a number. + Use nr2char() to convert it to a String. + + Use getcharmod() to obtain any additional modifiers. + + When the user clicks a mouse button, the mouse event will be + returned. The position can then be found in |v:mouse_col|, + |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. + |getmousepos()| can also be used. Mouse move events will be + ignored. + This example positions the mouse as it would normally happen: > + let c = getchar() + if c == "\" && v:mouse_win > 0 + exe v:mouse_win . "wincmd w" + exe v:mouse_lnum + exe "normal " . v:mouse_col . "|" + endif +< + When using bracketed paste only the first character is + returned, the rest of the pasted text is dropped. + |xterm-bracketed-paste|. + + There is no prompt, you will somehow have to make clear to the + user that a character has to be typed. The screen is not + redrawn, e.g. when resizing the window. When using a popup + window it should work better with a |popup-filter|. + + There is no mapping for the character. + Key codes are replaced, thus when the user presses the + key you get the code for the key, not the raw character + sequence. Examples: > + getchar() == "\" + getchar() == "\" +< This example redefines "f" to ignore case: > + :nmap f :call FindChar() + :function FindChar() + : let c = nr2char(getchar()) + : while col('.') < col('$') - 1 + : normal l + : if getline('.')[col('.') - 1] ==? c + : break + : endif + : endwhile + :endfunction +< + You may also receive synthetic characters, such as + ||. Often you will want to ignore this and get + another character: > + :function GetKey() + : let c = getchar() + : while c == "\" + : let c = getchar() + : endwhile + : return c + :endfunction + +getcharmod() *getcharmod()* + The result is a Number which is the state of the modifiers for + the last obtained character with getchar() or in another way. + These values are added together: + 2 shift + 4 control + 8 alt (meta) + 16 meta (when it's different from ALT) + 32 mouse double click + 64 mouse triple click + 96 mouse quadruple click (== 32 + 64) + 128 command (Macintosh only) + Only the modifiers that have not been included in the + character itself are obtained. Thus Shift-a results in "A" + without a modifier. + + *getcharpos()* +getcharpos({expr}) + Get the position for String {expr}. Same as |getpos()| but the + column number in the returned List is a character index + instead of a byte index. + If |getpos()| returns a very large column number, such as + 2147483647, then getcharpos() will return the character index + of the last character. + + Example: + With the cursor on '세' in line 5 with text "여보세요": > + getcharpos('.') returns [0, 5, 3, 0] + getpos('.') returns [0, 5, 7, 0] +< + Can also be used as a |method|: > + GetMark()->getcharpos() + +getcharsearch() *getcharsearch()* + Return the current character search information as a {dict} + with the following entries: + + char character previously used for a character + search (|t|, |f|, |T|, or |F|); empty string + if no character search has been performed + forward direction of character search; 1 for forward, + 0 for backward + until type of character search; 1 for a |t| or |T| + character search, 0 for an |f| or |F| + character search + + This can be useful to always have |;| and |,| search + forward/backward regardless of the direction of the previous + character search: > + :nnoremap ; getcharsearch().forward ? ';' : ',' + :nnoremap , getcharsearch().forward ? ',' : ';' +< Also see |setcharsearch()|. + + +getcharstr([expr]) *getcharstr()* + Get a single character from the user or input stream as a + string. + If [expr] is omitted, wait until a character is available. + If [expr] is 0 or false, only get a character when one is + available. Return an empty string otherwise. + If [expr] is 1 or true, only check if a character is + available, it is not consumed. Return an empty string + if no character is available. + Otherwise this works like |getchar()|, except that a number + result is converted to a string. + + +getcmdline() *getcmdline()* + Return the current command-line. Only works when the command + line is being edited, thus requires use of |c_CTRL-\_e| or + |c_CTRL-R_=|. + Example: > + :cmap eescape(getcmdline(), ' \') +< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|. + Returns an empty string when entering a password or using + |inputsecret()|. + +getcmdpos() *getcmdpos()* + Return the position of the cursor in the command line as a + byte count. The first column is 1. + Only works when editing the command line, thus requires use of + |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. + Returns 0 otherwise. + Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|. + +getcmdtype() *getcmdtype()* + Return the current command-line type. Possible return values + are: + : normal Ex command + > debug mode command |debug-mode| + / forward search command + ? backward search command + @ |input()| command + - |:insert| or |:append| command + = |i_CTRL-R_=| + Only works when editing the command line, thus requires use of + |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. + Returns an empty string otherwise. + Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|. + +getcmdwintype() *getcmdwintype()* + Return the current |command-line-window| type. Possible return + values are the same as |getcmdtype()|. Returns an empty string + when not in the command-line window. + +getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* + Return a list of command-line completion matches. The String + {type} argument specifies what for. The following completion + types are supported: + + arglist file names in argument list + augroup autocmd groups + buffer buffer names + behave :behave suboptions + color color schemes + command Ex command + cmdline |cmdline-completion| result + compiler compilers + cscope |:cscope| suboptions + diff_buffer |:diffget| and |:diffput| completion + dir directory names + environment environment variable names + event autocommand events + expression Vim expression + file file and directory names + file_in_path file and directory names in |'path'| + filetype filetype names |'filetype'| + function function name + help help subjects + highlight highlight groups + history :history suboptions + locale locale names (as output of locale -a) + mapclear buffer argument + mapping mapping name + menu menus + messages |:messages| suboptions + option options + packadd optional package |pack-add| names + shellcmd Shell command + sign |:sign| suboptions + syntax syntax file names |'syntax'| + syntime |:syntime| suboptions + tag tags + tag_listfiles tags, file names + user user names + var user variables + + If {pat} is an empty string, then all the matches are + returned. Otherwise only items matching {pat} are returned. + See |wildcards| for the use of special characters in {pat}. + + If the optional {filtered} flag is set to 1, then 'wildignore' + is applied to filter the results. Otherwise all the matches + are returned. The 'wildignorecase' option always applies. + + If {type} is "cmdline", then the |cmdline-completion| result is + returned. For example, to complete the possible values after + a ":call" command: > + echo getcompletion('call ', 'cmdline') +< + If there are no matches, an empty list is returned. An + invalid value for {type} produces an error. + + Can also be used as a |method|: > + GetPattern()->getcompletion('color') +< + *getcurpos()* +getcurpos([{winid}]) + Get the position of the cursor. This is like getpos('.'), but + includes an extra "curswant" item in the list: + [0, lnum, col, off, curswant] ~ + The "curswant" number is the preferred column when moving the + cursor vertically. Also see |getcursorcharpos()| and + |getpos()|. + The first "bufnum" item is always zero. The byte position of + the cursor is returned in 'col'. To get the character + position, use |getcursorcharpos()|. + + The optional {winid} argument can specify the window. It can + be the window number or the |window-ID|. The last known + cursor position is returned, this may be invalid for the + current value of the buffer if it is not the current window. + If {winid} is invalid a list with zeroes is returned. + + This can be used to save and restore the cursor position: > + let save_cursor = getcurpos() + MoveTheCursorAround + call setpos('.', save_cursor) +< Note that this only works within the window. See + |winrestview()| for restoring more state. + + Can also be used as a |method|: > + GetWinid()->getcurpos() +< + *getcursorcharpos()* +getcursorcharpos([{winid}]) + Same as |getcurpos()| but the column number in the returned + List is a character index instead of a byte index. + + Example: + With the cursor on '보' in line 3 with text "여보세요": > + getcursorcharpos() returns [0, 3, 2, 0, 3] + getcurpos() returns [0, 3, 4, 0, 3] +< + Can also be used as a |method|: > + GetWinid()->getcursorcharpos() + +< *getcwd()* +getcwd([{winnr} [, {tabnr}]]) + The result is a String, which is the name of the current + working directory. 'autochdir' is ignored. + + With {winnr} return the local current directory of this window + in the current tab page. {winnr} can be the window number or + the |window-ID|. + If {winnr} is -1 return the name of the global working + directory. See also |haslocaldir()|. + + With {winnr} and {tabnr} return the local current directory of + the window in the specified tab page. If {winnr} is -1 return + the working directory of the tabpage. + If {winnr} is zero use the current window, if {tabnr} is zero + use the current tabpage. + Without any arguments, return the actual working directory of + the current window. + Return an empty string if the arguments are invalid. + + Examples: > + " Get the working directory of the current window + :echo getcwd() + :echo getcwd(0) + :echo getcwd(0, 0) + " Get the working directory of window 3 in tabpage 2 + :echo getcwd(3, 2) + " Get the global working directory + :echo getcwd(-1) + " Get the working directory of tabpage 3 + :echo getcwd(-1, 3) + " Get the working directory of current tabpage + :echo getcwd(-1, 0) + +< Can also be used as a |method|: > + GetWinnr()->getcwd() + +getenv({name}) *getenv()* + Return the value of environment variable {name}. The {name} + argument is a string, without a leading '$'. Example: > + myHome = getenv('HOME') + +< When the variable does not exist |v:null| is returned. That + is different from a variable set to an empty string, although + some systems interpret the empty value as the variable being + deleted. See also |expr-env|. + + Can also be used as a |method|: > + GetVarname()->getenv() + +getfontname([{name}]) *getfontname()* + Without an argument returns the name of the normal font being + used. Like what is used for the Normal highlight group + |hl-Normal|. + With an argument a check is done whether String {name} is a + valid font name. If not then an empty string is returned. + Otherwise the actual font name is returned, or {name} if the + GUI does not support obtaining the real name. + Only works when the GUI is running, thus not in your vimrc or + gvimrc file. Use the |GUIEnter| autocommand to use this + function just after the GUI has started. + Note that the GTK GUI accepts any font name, thus checking for + a valid name does not work. + +getfperm({fname}) *getfperm()* + The result is a String, which is the read, write, and execute + permissions of the given file {fname}. + If {fname} does not exist or its directory cannot be read, an + empty string is returned. + The result is of the form "rwxrwxrwx", where each group of + "rwx" flags represent, in turn, the permissions of the owner + of the file, the group the file belongs to, and other users. + If a user does not have a given permission the flag for this + is replaced with the string "-". Examples: > + :echo getfperm("/etc/passwd") + :echo getfperm(expand("~/.vimrc")) +< This will hopefully (from a security point of view) display + the string "rw-r--r--" or even "rw-------". + + Can also be used as a |method|: > + GetFilename()->getfperm() +< + For setting permissions use |setfperm()|. + +getfsize({fname}) *getfsize()* + The result is a Number, which is the size in bytes of the + given file {fname}. + If {fname} is a directory, 0 is returned. + If the file {fname} can't be found, -1 is returned. + If the size of {fname} is too big to fit in a Number then -2 + is returned. + + Can also be used as a |method|: > + GetFilename()->getfsize() + +getftime({fname}) *getftime()* + The result is a Number, which is the last modification time of + the given file {fname}. The value is measured as seconds + since 1st Jan 1970, and may be passed to strftime(). See also + |localtime()| and |strftime()|. + If the file {fname} can't be found -1 is returned. + + Can also be used as a |method|: > + GetFilename()->getftime() + +getftype({fname}) *getftype()* + The result is a String, which is a description of the kind of + file of the given file {fname}. + If {fname} does not exist an empty string is returned. + Here is a table over different kinds of files and their + results: + Normal file "file" + Directory "dir" + Symbolic link "link" + Block device "bdev" + Character device "cdev" + Socket "socket" + FIFO "fifo" + All other "other" + Example: > + getftype("/home") +< Note that a type such as "link" will only be returned on + systems that support it. On some systems only "dir" and + "file" are returned. On MS-Windows a symbolic link to a + directory returns "dir" instead of "link". + + Can also be used as a |method|: > + GetFilename()->getftype() + +getimstatus() *getimstatus()* + The result is a Number, which is |TRUE| when the IME status is + active. + See 'imstatusfunc'. + +getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* + Returns the |jumplist| for the specified window. + + Without arguments use the current window. + With {winnr} only use this window in the current tab page. + {winnr} can also be a |window-ID|. + With {winnr} and {tabnr} use the window in the specified tab + page. + + The returned list contains two entries: a list with the jump + locations and the last used jump position number in the list. + Each entry in the jump location list is a dictionary with + the following entries: + bufnr buffer number + col column number + coladd column offset for 'virtualedit' + filename filename if available + lnum line number + + Can also be used as a |method|: > + GetWinnr()->getjumplist() + +< *getline()* +getline({lnum} [, {end}]) + Without {end} the result is a String, which is line {lnum} + from the current buffer. Example: > + getline(1) +< When {lnum} is a String that doesn't start with a + digit, |line()| is called to translate the String into a Number. + To get the line under the cursor: > + getline(".") +< When {lnum} is a number smaller than 1 or bigger than the + number of lines in the buffer, an empty string is returned. + + When {end} is given the result is a |List| where each item is + a line from the current buffer in the range {lnum} to {end}, + including line {end}. + {end} is used in the same way as {lnum}. + Non-existing lines are silently omitted. + When {end} is before {lnum} an empty |List| is returned. + Example: > + :let start = line('.') + :let end = search("^$") - 1 + :let lines = getline(start, end) + +< Can also be used as a |method|: > + ComputeLnum()->getline() + +< To get lines from another buffer see |getbufline()| + +getloclist({nr} [, {what}]) *getloclist()* + Returns a |List| with all the entries in the location list for + window {nr}. {nr} can be the window number or the |window-ID|. + When {nr} is zero the current window is used. + + For a location list window, the displayed location list is + returned. For an invalid window number {nr}, an empty list is + returned. Otherwise, same as |getqflist()|. + + If the optional {what} dictionary argument is supplied, then + returns the items listed in {what} as a dictionary. Refer to + |getqflist()| for the supported items in {what}. + + In addition to the items supported by |getqflist()| in {what}, + the following item is supported by |getloclist()|: + + filewinid id of the window used to display files + from the location list. This field is + applicable only when called from a + location list window. See + |location-list-file-window| for more + details. + + Returns a |Dictionary| with default values if there is no + location list for the window {nr}. + Returns an empty Dictionary if window {nr} does not exist. + + Examples (See also |getqflist-examples|): > + :echo getloclist(3, {'all': 0}) + :echo getloclist(5, {'filewinid': 0}) + + +getmarklist([{buf}]) *getmarklist()* + Without the {buf} argument returns a |List| with information + about all the global marks. |mark| + + If the optional {buf} argument is specified, returns the + local marks defined in buffer {buf}. For the use of {buf}, + see |bufname()|. + + Each item in the returned List is a |Dict| with the following: + mark name of the mark prefixed by "'" + pos a |List| with the position of the mark: + [bufnum, lnum, col, off] + Refer to |getpos()| for more information. + file file name + + Refer to |getpos()| for getting information about a specific + mark. + + Can also be used as a |method|: > + GetBufnr()->getmarklist() + +getmatches([{win}]) *getmatches()* + Returns a |List| with all matches previously defined for the + current window by |matchadd()| and the |:match| commands. + |getmatches()| is useful in combination with |setmatches()|, + as |setmatches()| can restore a list of matches saved by + |getmatches()|. + If {win} is specified, use the window with this number or + window ID instead of the current window. + Example: > + :echo getmatches() +< [{'group': 'MyGroup1', 'pattern': 'TODO', + 'priority': 10, 'id': 1}, {'group': 'MyGroup2', + 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > + :let m = getmatches() + :call clearmatches() + :echo getmatches() +< [] > + :call setmatches(m) + :echo getmatches() +< [{'group': 'MyGroup1', 'pattern': 'TODO', + 'priority': 10, 'id': 1}, {'group': 'MyGroup2', + 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > + :unlet m +< +getmousepos() *getmousepos()* + Returns a |Dictionary| with the last known position of the + mouse. This can be used in a mapping for a mouse click or in + a filter of a popup window. The items are: + screenrow screen row + screencol screen column + winid Window ID of the click + winrow row inside "winid" + wincol column inside "winid" + line text line inside "winid" + column text column inside "winid" + All numbers are 1-based. + + If not over a window, e.g. when in the command line, then only + "screenrow" and "screencol" are valid, the others are zero. + + When on the status line below a window or the vertical + separator right of a window, the "line" and "column" values + are zero. + + When the position is after the text then "column" is the + length of the text in bytes plus one. + + If the mouse is over a popup window then that window is used. + + When using |getchar()| the Vim variables |v:mouse_lnum|, + |v:mouse_col| and |v:mouse_winid| also provide these values. + + *getpid()* +getpid() Return a Number which is the process ID of the Vim process. + On Unix and MS-Windows this is a unique number, until Vim + exits. + + *getpos()* +getpos({expr}) Get the position for String {expr}. For possible values of + {expr} see |line()|. For getting the cursor position see + |getcurpos()|. + The result is a |List| with four numbers: + [bufnum, lnum, col, off] + "bufnum" is zero, unless a mark like '0 or 'A is used, then it + is the buffer number of the mark. + "lnum" and "col" are the position in the buffer. The first + column is 1. + The "off" number is zero, unless 'virtualedit' is used. Then + it is the offset in screen columns from the start of the + character. E.g., a position within a or after the last + character. + Note that for '< and '> Visual mode matters: when it is "V" + (visual line mode) the column of '< is zero and the column of + '> is a large number. + The column number in the returned List is the byte position + within the line. To get the character position in the line, + use |getcharpos()|. + The column number can be very large, e.g. 2147483647, in which + case it means "after the end of the line". + This can be used to save and restore the position of a mark: > + let save_a_mark = getpos("'a") + ... + call setpos("'a", save_a_mark) +< Also see |getcharpos()|, |getcurpos()| and |setpos()|. + + Can also be used as a |method|: > + GetMark()->getpos() + +getqflist([{what}]) *getqflist()* + Returns a |List| with all the current quickfix errors. Each + list item is a dictionary with these entries: + bufnr number of buffer that has the file name, use + bufname() to get the name + module module name + lnum line number in the buffer (first line is 1) + end_lnum + end of line number if the item is multiline + col column number (first column is 1) + end_col end of column number if the item has range + vcol |TRUE|: "col" is visual column + |FALSE|: "col" is byte index + nr error number + pattern search pattern used to locate the error + text description of the error + type type of the error, 'E', '1', etc. + valid |TRUE|: recognized error message + + When there is no error list or it's empty, an empty list is + returned. Quickfix list entries with a non-existing buffer + number are returned with "bufnr" set to zero (Note: some + functions accept buffer number zero for the alternate buffer, + you may need to explicitly check for zero). + + Useful application: Find pattern matches in multiple files and + do something with them: > + :vimgrep /theword/jg *.c + :for d in getqflist() + : echo bufname(d.bufnr) ':' d.lnum '=' d.text + :endfor +< + If the optional {what} dictionary argument is supplied, then + returns only the items listed in {what} as a dictionary. The + following string items are supported in {what}: + changedtick get the total number of changes made + to the list |quickfix-changedtick| + context get the |quickfix-context| + efm errorformat to use when parsing "lines". If + not present, then the 'errorformat' option + value is used. + id get information for the quickfix list with + |quickfix-ID|; zero means the id for the + current list or the list specified by "nr" + idx get information for the quickfix entry at this + index in the list specified by 'id' or 'nr'. + If set to zero, then uses the current entry. + See |quickfix-index| + items quickfix list entries + lines parse a list of lines using 'efm' and return + the resulting entries. Only a |List| type is + accepted. The current quickfix list is not + modified. See |quickfix-parse|. + nr get information for this quickfix list; zero + means the current quickfix list and "$" means + the last quickfix list + qfbufnr number of the buffer displayed in the quickfix + window. Returns 0 if the quickfix buffer is + not present. See |quickfix-buffer|. + size number of entries in the quickfix list + title get the list title |quickfix-title| + winid get the quickfix |window-ID| + all all of the above quickfix properties + Non-string items in {what} are ignored. To get the value of a + particular item, set it to zero. + If "nr" is not present then the current quickfix list is used. + If both "nr" and a non-zero "id" are specified, then the list + specified by "id" is used. + To get the number of lists in the quickfix stack, set "nr" to + "$" in {what}. The "nr" value in the returned dictionary + contains the quickfix stack size. + When "lines" is specified, all the other items except "efm" + are ignored. The returned dictionary contains the entry + "items" with the list of entries. + + The returned dictionary contains the following entries: + changedtick total number of changes made to the + list |quickfix-changedtick| + context quickfix list context. See |quickfix-context| + If not present, set to "". + id quickfix list ID |quickfix-ID|. If not + present, set to 0. + idx index of the quickfix entry in the list. If not + present, set to 0. + items quickfix list entries. If not present, set to + an empty list. + nr quickfix list number. If not present, set to 0 + qfbufnr number of the buffer displayed in the quickfix + window. If not present, set to 0. + size number of entries in the quickfix list. If not + present, set to 0. + title quickfix list title text. If not present, set + to "". + winid quickfix |window-ID|. If not present, set to 0 + + Examples (See also |getqflist-examples|): > + :echo getqflist({'all': 1}) + :echo getqflist({'nr': 2, 'title': 1}) + :echo getqflist({'lines' : ["F1:10:L10"]}) +< +getreg([{regname} [, 1 [, {list}]]]) *getreg()* + The result is a String, which is the contents of register + {regname}. Example: > + :let cliptext = getreg('*') +< When register {regname} was not set the result is an empty + string. + The {regname} argument must be a string. + + getreg('=') returns the last evaluated value of the expression + register. (For use in maps.) + getreg('=', 1) returns the expression itself, so that it can + be restored with |setreg()|. For other registers the extra + argument is ignored, thus you can always give it. + + If {list} is present and |TRUE|, the result type is changed + to |List|. Each list item is one text line. Use it if you care + about zero bytes possibly present inside register: without + third argument both NLs and zero bytes are represented as NLs + (see |NL-used-for-Nul|). + When the register was not set an empty list is returned. + + If {regname} is "", the unnamed register '"' is used. + If {regname} is not specified, |v:register| is used. + In |Vim9-script| {regname} must be one character. + + Can also be used as a |method|: > + GetRegname()->getreg() + +getreginfo([{regname}]) *getreginfo()* + Returns detailed information about register {regname} as a + Dictionary with the following entries: + regcontents List of lines contained in register + {regname}, like + |getreg|({regname}, 1, 1). + regtype the type of register {regname}, as in + |getregtype()|. + isunnamed Boolean flag, v:true if this register + is currently pointed to by the unnamed + register. + points_to for the unnamed register, gives the + single letter name of the register + currently pointed to (see |quotequote|). + For example, after deleting a line + with `dd`, this field will be "1", + which is the register that got the + deleted text. + + The {regname} argument is a string. If {regname} is invalid + or not set, an empty Dictionary will be returned. + If {regname} is "" or "@", the unnamed register '"' is used. + If {regname} is not specified, |v:register| is used. + The returned Dictionary can be passed to |setreg()|. + In |Vim9-script| {regname} must be one character. + + Can also be used as a |method|: > + GetRegname()->getreginfo() + +getregtype([{regname}]) *getregtype()* + The result is a String, which is type of register {regname}. + The value will be one of: + "v" for |characterwise| text + "V" for |linewise| text + "{width}" for |blockwise-visual| text + "" for an empty or unknown register + is one character with value 0x16. + The {regname} argument is a string. If {regname} is "", the + unnamed register '"' is used. If {regname} is not specified, + |v:register| is used. + In |Vim9-script| {regname} must be one character. + + Can also be used as a |method|: > + GetRegname()->getregtype() + +gettabinfo([{tabnr}]) *gettabinfo()* + If {tabnr} is not specified, then information about all the + tab pages is returned as a |List|. Each List item is a + |Dictionary|. Otherwise, {tabnr} specifies the tab page + number and information about that one is returned. If the tab + page does not exist an empty List is returned. + + Each List item is a |Dictionary| with the following entries: + tabnr tab page number. + variables a reference to the dictionary with + tabpage-local variables + windows List of |window-ID|s in the tab page. + + Can also be used as a |method|: > + GetTabnr()->gettabinfo() + +gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* + Get the value of a tab-local variable {varname} in tab page + {tabnr}. |t:var| + Tabs are numbered starting with one. + The {varname} argument is a string. When {varname} is empty a + dictionary with all tab-local variables is returned. + Note that the name without "t:" must be used. + When the tab or variable doesn't exist {def} or an empty + string is returned, there is no error message. + + Can also be used as a |method|: > + GetTabnr()->gettabvar(varname) + +gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* + Get the value of window-local variable {varname} in window + {winnr} in tab page {tabnr}. + The {varname} argument is a string. When {varname} is empty a + dictionary with all window-local variables is returned. + When {varname} is equal to "&" get the values of all + window-local options in a |Dictionary|. + Otherwise, when {varname} starts with "&" get the value of a + window-local option. + Note that {varname} must be the name without "w:". + Tabs are numbered starting with one. For the current tabpage + use |getwinvar()|. + {winnr} can be the window number or the |window-ID|. + When {winnr} is zero the current window is used. + This also works for a global option, buffer-local option and + window-local option, but it doesn't work for a global variable + or buffer-local variable. + When the tab, window or variable doesn't exist {def} or an + empty string is returned, there is no error message. + Examples: > + :let list_is_on = gettabwinvar(1, 2, '&list') + :echo "myvar = " . gettabwinvar(3, 1, 'myvar') +< + To obtain all window-local variables use: > + gettabwinvar({tabnr}, {winnr}, '&') + +< Can also be used as a |method|: > + GetTabnr()->gettabwinvar(winnr, varname) + +gettagstack([{winnr}]) *gettagstack()* + The result is a Dict, which is the tag stack of window {winnr}. + {winnr} can be the window number or the |window-ID|. + When {winnr} is not specified, the current window is used. + When window {winnr} doesn't exist, an empty Dict is returned. + + The returned dictionary contains the following entries: + curidx Current index in the stack. When at + top of the stack, set to (length + 1). + Index of bottom of the stack is 1. + items List of items in the stack. Each item + is a dictionary containing the + entries described below. + length Number of entries in the stack. + + Each item in the stack is a dictionary with the following + entries: + bufnr buffer number of the current jump + from cursor position before the tag jump. + See |getpos()| for the format of the + returned list. + matchnr current matching tag number. Used when + multiple matching tags are found for a + name. + tagname name of the tag + + See |tagstack| for more information about the tag stack. + + Can also be used as a |method|: > + GetWinnr()->gettagstack() + + +gettext({text}) *gettext()* + Translate String {text} if possible. + This is mainly for use in the distributed Vim scripts. When + generating message translations the {text} is extracted by + xgettext, the translator can add the translated message in the + .po file and Vim will lookup the translation when gettext() is + called. + For {text} double quoted strings are preferred, because + xgettext does not understand escaping in single quoted + strings. + + +getwininfo([{winid}]) *getwininfo()* + Returns information about windows as a |List| with Dictionaries. + + If {winid} is given Information about the window with that ID + is returned, as a |List| with one item. If the window does not + exist the result is an empty list. + + Without {winid} information about all the windows in all the + tab pages is returned. + + Each List item is a |Dictionary| with the following entries: + botline last complete displayed buffer line + bufnr number of buffer in the window + height window height (excluding winbar) + loclist 1 if showing a location list + {only with the +quickfix feature} + quickfix 1 if quickfix or location list window + {only with the +quickfix feature} + terminal 1 if a terminal window + {only with the +terminal feature} + tabnr tab page number + topline first displayed buffer line + variables a reference to the dictionary with + window-local variables + width window width + winbar 1 if the window has a toolbar, 0 + otherwise + wincol leftmost screen column of the window; + "col" from |win_screenpos()| + textoff number of columns occupied by any + 'foldcolumn', 'signcolumn' and line + number in front of the text + winid |window-ID| + winnr window number + winrow topmost screen line of the window; + "row" from |win_screenpos()| + + Can also be used as a |method|: > + GetWinnr()->getwininfo() + +getwinpos([{timeout}]) *getwinpos()* + The result is a |List| with two numbers, the result of + |getwinposx()| and |getwinposy()| combined: + [x-pos, y-pos] + {timeout} can be used to specify how long to wait in msec for + a response from the terminal. When omitted 100 msec is used. + Use a longer time for a remote terminal. + When using a value less than 10 and no response is received + within that time, a previously reported position is returned, + if available. This can be used to poll for the position and + do some work in the meantime: > + while 1 + let res = getwinpos(1) + if res[0] >= 0 + break + endif + " Do some work here + endwhile +< + + Can also be used as a |method|: > + GetTimeout()->getwinpos() +< + *getwinposx()* +getwinposx() The result is a Number, which is the X coordinate in pixels of + the left hand side of the GUI Vim window. Also works for an + xterm (uses a timeout of 100 msec). + The result will be -1 if the information is not available. + The value can be used with `:winpos`. + + *getwinposy()* +getwinposy() The result is a Number, which is the Y coordinate in pixels of + the top of the GUI Vim window. Also works for an xterm (uses + a timeout of 100 msec). + The result will be -1 if the information is not available. + The value can be used with `:winpos`. + +getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* + Like |gettabwinvar()| for the current tabpage. + Examples: > + :let list_is_on = getwinvar(2, '&list') + :echo "myvar = " . getwinvar(1, 'myvar') + +< Can also be used as a |method|: > + GetWinnr()->getwinvar(varname) +< +glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* + Expand the file wildcards in {expr}. See |wildcards| for the + use of special characters. + + Unless the optional {nosuf} argument is given and is |TRUE|, + the 'suffixes' and 'wildignore' options apply: Names matching + one of the patterns in 'wildignore' will be skipped and + 'suffixes' affect the ordering of matches. + 'wildignorecase' always applies. + + When {list} is present and it is |TRUE| the result is a |List| + with all matching files. The advantage of using a List is, + you also get filenames containing newlines correctly. + Otherwise the result is a String and when there are several + matches, they are separated by characters. + + If the expansion fails, the result is an empty String or List. + + You can also use |readdir()| if you need to do complicated + things, such as limiting the number of matches. + + A name for a non-existing file is not included. A symbolic + link is only included if it points to an existing file. + However, when the {alllinks} argument is present and it is + |TRUE| then all symbolic links are included. + + For most systems backticks can be used to get files names from + any external command. Example: > + :let tagfiles = glob("`find . -name tags -print`") + :let &tags = substitute(tagfiles, "\n", ",", "g") +< The result of the program inside the backticks should be one + item per line. Spaces inside an item are allowed. + + See |expand()| for expanding special Vim variables. See + |system()| for getting the raw output of an external command. + + Can also be used as a |method|: > + GetExpr()->glob() + +glob2regpat({string}) *glob2regpat()* + Convert a file pattern, as used by glob(), into a search + pattern. The result can be used to match with a string that + is a file name. E.g. > + if filename =~ glob2regpat('Make*.mak') +< This is equivalent to: > + if filename =~ '^Make.*\.mak$' +< When {string} is an empty string the result is "^$", match an + empty string. + Note that the result depends on the system. On MS-Windows + a backslash usually means a path separator. + + Can also be used as a |method|: > + GetExpr()->glob2regpat() +< *globpath()* +globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) + Perform glob() for String {expr} on all directories in {path} + and concatenate the results. Example: > + :echo globpath(&rtp, "syntax/c.vim") +< + {path} is a comma-separated list of directory names. Each + directory name is prepended to {expr} and expanded like with + |glob()|. A path separator is inserted when needed. + To add a comma inside a directory name escape it with a + backslash. Note that on MS-Windows a directory may have a + trailing backslash, remove it if you put a comma after it. + If the expansion fails for one of the directories, there is no + error message. + + Unless the optional {nosuf} argument is given and is |TRUE|, + the 'suffixes' and 'wildignore' options apply: Names matching + one of the patterns in 'wildignore' will be skipped and + 'suffixes' affect the ordering of matches. + + When {list} is present and it is |TRUE| the result is a |List| + with all matching files. The advantage of using a List is, you + also get filenames containing newlines correctly. Otherwise + the result is a String and when there are several matches, + they are separated by characters. Example: > + :echo globpath(&rtp, "syntax/c.vim", 0, 1) +< + {alllinks} is used as with |glob()|. + + The "**" item can be used to search in a directory tree. + For example, to find all "README.txt" files in the directories + in 'runtimepath' and below: > + :echo globpath(&rtp, "**/README.txt") +< Upwards search and limiting the depth of "**" is not + supported, thus using 'path' will not always work properly. + + Can also be used as a |method|, the base is passed as the + second argument: > + GetExpr()->globpath(&rtp) +< + *has()* +has({feature} [, {check}]) + When {check} is omitted or is zero: The result is a Number, + which is 1 if the feature {feature} is supported, zero + otherwise. The {feature} argument is a string, case is + ignored. See |feature-list| below. + + When {check} is present and not zero: The result is a Number, + which is 1 if the feature {feature} could ever be supported, + zero otherwise. This is useful to check for a typo in + {feature} and to detect dead code. Keep in mind that an older + Vim version will not know about a feature added later and + features that have been abandoned will not be known by the + current Vim version. + + Also see |exists()| and |exists_compiled()|. + + Note that to skip code that has a syntax error when the + feature is not available, Vim may skip the rest of the line + and miss a following `endif`. Therefore put the `endif` on a + separate line: > + if has('feature') + let x = this->breaks->without->the->feature + endif +< If the `endif` would be moved to the second line as "| endif" it + would not be found. + + +has_key({dict}, {key}) *has_key()* + The result is a Number, which is TRUE if |Dictionary| {dict} + has an entry with key {key}. FALSE otherwise. The {key} + argument is a string. + + Can also be used as a |method|: > + mydict->has_key(key) + +haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* + The result is a Number: + 1 when the window has set a local directory via |:lcd| + 2 when the tab-page has set a local directory via |:tcd| + 0 otherwise. + + Without arguments use the current window. + With {winnr} 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|. + If {winnr} is -1 it is ignored and only the tabpage is used. + Return 0 if the arguments are invalid. + Examples: > + if haslocaldir() == 1 + " window local directory case + elseif haslocaldir() == 2 + " tab-local directory case + else + " global directory case + endif + + " current window + :echo haslocaldir() + :echo haslocaldir(0) + :echo haslocaldir(0, 0) + " window n in current tab page + :echo haslocaldir(n) + :echo haslocaldir(n, 0) + " window n in tab page m + :echo haslocaldir(n, m) + " tab page m + :echo haslocaldir(-1, m) +< + Can also be used as a |method|: > + GetWinnr()->haslocaldir() + +hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* + The result is a Number, which is TRUE if there is a mapping + that contains {what} in somewhere in the rhs (what it is + mapped to) and this mapping exists in one of the modes + indicated by {mode}. + The arguments {what} and {mode} are strings. + When {abbr} is there and it is |TRUE| use abbreviations + instead of mappings. Don't forget to specify Insert and/or + Command-line mode. + Both the global mappings and the mappings local to the current + buffer are checked for a match. + If no matching mapping is found FALSE is returned. + The following characters are recognized in {mode}: + n Normal mode + v Visual and Select mode + x Visual mode + s Select mode + o Operator-pending mode + i Insert mode + l Language-Argument ("r", "f", "t", etc.) + c Command-line mode + When {mode} is omitted, "nvo" is used. + + This function is useful to check if a mapping already exists + to a function in a Vim script. Example: > + :if !hasmapto('\ABCdoit') + : map d \ABCdoit + :endif +< This installs the mapping to "\ABCdoit" only if there isn't + already a mapping to "\ABCdoit". + + Can also be used as a |method|: > + GetRHS()->hasmapto() + +histadd({history}, {item}) *histadd()* + Add the String {item} to the history {history} which can be + one of: *hist-names* + "cmd" or ":" command line history + "search" or "/" search pattern history + "expr" or "=" typed expression history + "input" or "@" input line history + "debug" or ">" debug command history + empty the current or last used history + The {history} string does not need to be the whole name, one + character is sufficient. + If {item} does already exist in the history, it will be + shifted to become the newest entry. + The result is a Number: TRUE if the operation was successful, + otherwise FALSE is returned. + + Example: > + :call histadd("input", strftime("%Y %b %d")) + :let date=input("Enter date: ") +< This function is not available in the |sandbox|. + + Can also be used as a |method|, the base is passed as the + second argument: > + GetHistory()->histadd('search') + +histdel({history} [, {item}]) *histdel()* + Clear {history}, i.e. delete all its entries. See |hist-names| + for the possible values of {history}. + + If the parameter {item} evaluates to a String, it is used as a + regular expression. All entries matching that expression will + be removed from the history (if there are any). + Upper/lowercase must match, unless "\c" is used |/\c|. + If {item} evaluates to a Number, it will be interpreted as + an index, see |:history-indexing|. The respective entry will + be removed if it exists. + + The result is TRUE for a successful operation, otherwise FALSE + is returned. + + Examples: + Clear expression register history: > + :call histdel("expr") +< + Remove all entries starting with "*" from the search history: > + :call histdel("/", '^\*') +< + The following three are equivalent: > + :call histdel("search", histnr("search")) + :call histdel("search", -1) + :call histdel("search", '^'.histget("search", -1).'$') +< + To delete the last search pattern and use the last-but-one for + the "n" command and 'hlsearch': > + :call histdel("search", -1) + :let @/ = histget("search", -1) +< + Can also be used as a |method|: > + GetHistory()->histdel() + +histget({history} [, {index}]) *histget()* + The result is a String, the entry with Number {index} from + {history}. See |hist-names| for the possible values of + {history}, and |:history-indexing| for {index}. If there is + no such entry, an empty String is returned. When {index} is + omitted, the most recent item from the history is used. + + Examples: + Redo the second last search from history. > + :execute '/' . histget("search", -2) + +< Define an Ex command ":H {num}" that supports re-execution of + the {num}th entry from the output of |:history|. > + :command -nargs=1 H execute histget("cmd", 0+) +< + Can also be used as a |method|: > + GetHistory()->histget() + +histnr({history}) *histnr()* + The result is the Number of the current entry in {history}. + See |hist-names| for the possible values of {history}. + If an error occurred, -1 is returned. + + Example: > + :let inp_index = histnr("expr") + +< Can also be used as a |method|: > + GetHistory()->histnr() +< +hlexists({name}) *hlexists()* + The result is a Number, which is TRUE if a highlight group + called {name} exists. This is when the group has been + defined in some way. Not necessarily when highlighting has + been defined for it, it may also have been used for a syntax + item. + *highlight_exists()* + Obsolete name: highlight_exists(). + + Can also be used as a |method|: > + GetName()->hlexists() +< +hlget([{name} [, {resolve}]]) *hlget()* + Returns a List of all the highlight group attributes. If the + optional {name} is specified, then returns a List with only + the attributes of the specified highlight group. Returns an + empty List if the highlight group {name} is not present. + + If the optional {resolve} argument is set to v:true and the + highlight group {name} is linked to another group, then the + link is resolved recursively and the attributes of the + resolved highlight group are returned. + + Each entry in the returned List is a Dictionary with the + following items: + cleared boolean flag, set to v:true if the highlight + group attributes are cleared or not yet + specified. See |highlight-clear|. + cterm cterm attributes. See |highlight-cterm|. + ctermbg cterm background color. + See |highlight-ctermbg|. + ctermfg cterm foreground color. + See |highlight-ctermfg|. + ctermul cterm underline color. See |highlight-ctermul|. + default boolean flag, set to v:true if the highlight + group link is a default link. See + |highlight-default|. + font highlight group font. See |highlight-font|. + gui gui attributes. See |highlight-gui|. + guibg gui background color. See |highlight-guibg|. + guifg gui foreground color. See |highlight-guifg|. + guisp gui special color. See |highlight-guisp|. + id highlight group ID. + linksto linked highlight group name. + See |:highlight-link|. + name highlight group name. See |group-name|. + start start terminal keycode. See |highlight-start|. + stop stop terminal keycode. See |highlight-stop|. + term term attributes. See |highlight-term|. + + The 'term', 'cterm' and 'gui' items in the above Dictionary + have a dictionary value with the following optional boolean + items: 'bold', 'standout', 'underline', 'undercurl', 'italic', + 'reverse', 'inverse' and 'strikethrough'. + + Example(s): > + :echo hlget() + :echo hlget('ModeMsg') + :echo hlget('Number', v:true) +< + Can also be used as a |method|: > + GetName()->hlget() +< +hlset({list}) *hlset()* + Creates or modifies the attributes of a List of highlight + groups. Each item in {list} is a dictionary containing the + attributes of a highlight group. See |hlget()| for the list of + supported items in this dictionary. + + In addition to the items described in |hlget()|, the following + additional items are supported in the dictionary: + + force boolean flag to force the creation of + a link for an existing highlight group + with attributes. + + The highlight group is identified using the 'name' item and + the 'id' item (if supplied) is ignored. If a highlight group + with a specified name doesn't exist, then it is created. + Otherwise the attributes of an existing highlight group are + modified. + + If an empty dictionary value is used for the 'term' or 'cterm' + or 'gui' entries, then the corresponding attributes are + cleared. If the 'cleared' item is set to v:true, then all the + attributes of the highlight group are cleared. + + The 'linksto' item can be used to link a highlight group to + another highlight group. See |:highlight-link|. + + Returns zero for success, -1 for failure. + + Example(s): > + " add bold attribute to the Visual highlight group + :call hlset([#{name: 'Visual', + \ term: #{reverse: 1 , bold: 1}}]) + :call hlset([#{name: 'Type', guifg: 'DarkGreen'}]) + :let l = hlget() + :call hlset(l) + " clear the Search highlight group + :call hlset([#{name: 'Search', cleared: v:true}]) + " clear the 'term' attributes for a highlight group + :call hlset([#{name: 'Title', term: {}}]) + " create the MyHlg group linking it to DiffAdd + :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}]) + " remove the MyHlg group link + :call hlset([#{name: 'MyHlg', linksto: 'NONE'}]) + " clear the attributes and a link + :call hlset([#{name: 'MyHlg', cleared: v:true, + \ linksto: 'NONE'}]) +< + Can also be used as a |method|: > + GetAttrList()->hlset() +< + *hlID()* +hlID({name}) The result is a Number, which is the ID of the highlight group + with name {name}. When the highlight group doesn't exist, + zero is returned. + This can be used to retrieve information about the highlight + group. For example, to get the background color of the + "Comment" group: > + :echo synIDattr(synIDtrans(hlID("Comment")), "bg") +< *highlightID()* + Obsolete name: highlightID(). + + Can also be used as a |method|: > + GetName()->hlID() + +hostname() *hostname()* + The result is a String, which is the name of the machine on + which Vim is currently running. Machine names greater than + 256 characters long are truncated. + +iconv({string}, {from}, {to}) *iconv()* + The result is a String, which is the text {string} converted + from encoding {from} to encoding {to}. + When the conversion completely fails an empty string is + returned. When some characters could not be converted they + are replaced with "?". + The encoding names are whatever the iconv() library function + can accept, see ":!man 3 iconv". + Most conversions require Vim to be compiled with the |+iconv| + feature. Otherwise only UTF-8 to latin1 conversion and back + can be done. + This can be used to display messages with special characters, + no matter what 'encoding' is set to. Write the message in + UTF-8 and use: > + echo iconv(utf8_str, "utf-8", &enc) +< Note that Vim uses UTF-8 for all Unicode encodings, conversion + from/to UCS-2 is automatically changed to use UTF-8. You + cannot use UCS-2 in a string anyway, because of the NUL bytes. + + Can also be used as a |method|: > + GetText()->iconv('latin1', 'utf-8') +< + *indent()* +indent({lnum}) The result is a Number, which is indent of line {lnum} in the + current buffer. 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. In |Vim9| script an + error is given. + + Can also be used as a |method|: > + GetLnum()->indent() + +index({object}, {expr} [, {start} [, {ic}]]) *index()* + If {object} is a |List| return the lowest index where the item + has a value equal to {expr}. There is no automatic + conversion, so the String "4" is different from the Number 4. + And the number 4 is different from the Float 4.0. The value + of 'ignorecase' is not used here, case always matters. + + If {object} is |Blob| return the lowest index where the byte + value is equal to {expr}. + + If {start} is given then start looking at the item with index + {start} (may be negative for an item relative to the end). + When {ic} is given and it is |TRUE|, ignore case. Otherwise + case must match. + -1 is returned when {expr} is not found in {object}. + Example: > + :let idx = index(words, "the") + :if index(numbers, 123) >= 0 + +< Can also be used as a |method|: > + GetObject()->index(what) + +input({prompt} [, {text} [, {completion}]]) *input()* + The result is a String, which is whatever the user typed on + the command-line. The {prompt} argument is either a prompt + string, or a blank string (for no prompt). A '\n' can be used + in the prompt to start a new line. + The highlighting set with |:echohl| is used for the prompt. + The input is entered just like a command-line, with the same + editing commands and mappings. There is a separate history + for lines typed for input(). + Example: > + :if input("Coffee or beer? ") == "beer" + : echo "Cheers!" + :endif +< + If the optional {text} argument is present and not empty, this + is used for the default reply, as if the user typed this. + Example: > + :let color = input("Color? ", "white") + +< The optional {completion} argument specifies the type of + completion supported for the input. Without it completion is + not performed. The supported completion types are the same as + that can be supplied to a user-defined command using the + "-complete=" argument. Refer to |:command-completion| for + more information. Example: > + let fname = input("File: ", "", "file") +< + NOTE: This function must not be used in a startup file, for + the versions that only run in GUI mode (e.g., the Win32 GUI). + Note: When input() is called from within a mapping it will + consume remaining characters from that mapping, because a + mapping is handled like the characters were typed. + Use |inputsave()| before input() and |inputrestore()| + after input() to avoid that. Another solution is to avoid + that further characters follow in the mapping, e.g., by using + |:execute| or |:normal|. + + Example with a mapping: > + :nmap \x :call GetFoo():exe "/" . Foo + :function GetFoo() + : call inputsave() + : let g:Foo = input("enter search pattern: ") + : call inputrestore() + :endfunction + +< Can also be used as a |method|: > + GetPrompt()->input() + +inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()* + Like |input()|, but when the GUI is running and text dialogs + are supported, a dialog window pops up to input the text. + Example: > + :let n = inputdialog("value for shiftwidth", shiftwidth()) + :if n != "" + : let &sw = n + :endif +< When the dialog is cancelled {cancelreturn} is returned. When + omitted an empty string is returned. + Hitting works like pressing the OK button. Hitting + works like pressing the Cancel button. + NOTE: Command-line completion is not supported. + + Can also be used as a |method|: > + GetPrompt()->inputdialog() + +inputlist({textlist}) *inputlist()* + {textlist} must be a |List| of strings. This |List| is + displayed, one string per line. The user will be prompted to + enter a number, which is returned. + The user can also select an item by clicking on it with the + mouse, if the mouse is enabled in the command line ('mouse' is + "a" or includes "c"). For the first string 0 is returned. + When clicking above the first item a negative number is + returned. When clicking on the prompt one more than the + length of {textlist} is returned. + Make sure {textlist} has less than 'lines' entries, otherwise + it won't work. It's a good idea to put the entry number at + the start of the string. And put a prompt in the first item. + Example: > + let color = inputlist(['Select color:', '1. red', + \ '2. green', '3. blue']) + +< Can also be used as a |method|: > + GetChoices()->inputlist() + +inputrestore() *inputrestore()* + Restore typeahead that was saved with a previous |inputsave()|. + Should be called the same number of times inputsave() is + called. Calling it more often is harmless though. + Returns TRUE when there is nothing to restore, FALSE otherwise. + +inputsave() *inputsave()* + Preserve typeahead (also from mappings) and clear it, so that + a following prompt gets input from the user. Should be + followed by a matching inputrestore() after the prompt. Can + be used several times, in which case there must be just as + many inputrestore() calls. + Returns TRUE when out of memory, FALSE otherwise. + +inputsecret({prompt} [, {text}]) *inputsecret()* + This function acts much like the |input()| function with but + two exceptions: + a) the user's response will be displayed as a sequence of + asterisks ("*") thereby keeping the entry secret, and + b) the user's response will not be recorded on the input + |history| stack. + The result is a String, which is whatever the user actually + typed on the command-line in response to the issued prompt. + NOTE: Command-line completion is not supported. + + Can also be used as a |method|: > + GetPrompt()->inputsecret() + +insert({object}, {item} [, {idx}]) *insert()* + When {object} is a |List| or a |Blob| insert {item} at the start + of it. + + If {idx} is specified insert {item} before the item with index + {idx}. If {idx} is zero it goes before the first item, just + like omitting {idx}. A negative {idx} is also possible, see + |list-index|. -1 inserts just before the last item. + + Returns the resulting |List| or |Blob|. Examples: > + :let mylist = insert([2, 3, 5], 1) + :call insert(mylist, 4, -1) + :call insert(mylist, 6, len(mylist)) +< The last example can be done simpler with |add()|. + Note that when {item} is a |List| it is inserted as a single + item. Use |extend()| to concatenate |Lists|. + + Can also be used as a |method|: > + mylist->insert(item) + +interrupt() *interrupt()* + Interrupt script execution. It works more or less like the + user typing CTRL-C, most commands won't execute and control + returns to the user. This is useful to abort execution + from lower down, e.g. in an autocommand. Example: > + :function s:check_typoname(file) + : if fnamemodify(a:file, ':t') == '[' + : echomsg 'Maybe typo' + : call interrupt() + : endif + :endfunction + :au BufWritePre * call s:check_typoname(expand('')) + +invert({expr}) *invert()* + Bitwise invert. The argument is converted to a number. A + List, Dict or Float argument causes an error. Example: > + :let bits = invert(bits) +< Can also be used as a |method|: > + :let bits = bits->invert() + +isdirectory({directory}) *isdirectory()* + The result is a Number, which is |TRUE| when a directory + with the name {directory} exists. If {directory} doesn't + exist, or isn't a directory, the result is |FALSE|. {directory} + is any expression, which is used as a String. + + Can also be used as a |method|: > + GetName()->isdirectory() + +isinf({expr}) *isinf()* + Return 1 if {expr} is a positive infinity, or -1 a negative + infinity, otherwise 0. > + :echo isinf(1.0 / 0.0) +< 1 > + :echo isinf(-1.0 / 0.0) +< -1 + + Can also be used as a |method|: > + Compute()->isinf() +< + {only available when compiled with the |+float| feature} + +islocked({expr}) *islocked()* *E786* + The result is a Number, which is |TRUE| when {expr} is the + name of a locked variable. + The string argument {expr} must be the name of a variable, + |List| item or |Dictionary| entry, not the variable itself! + Example: > + :let alist = [0, ['a', 'b'], 2, 3] + :lockvar 1 alist + :echo islocked('alist') " 1 + :echo islocked('alist[1]') " 0 + +< When {expr} is a variable that does not exist you get an error + message. Use |exists()| to check for existence. + In Vim9 script it does not work for local variables. + + Can also be used as a |method|: > + GetName()->islocked() + +isnan({expr}) *isnan()* + Return |TRUE| if {expr} is a float with value NaN. > + echo isnan(0.0 / 0.0) +< 1 + + Can also be used as a |method|: > + Compute()->isnan() +< + {only available when compiled with the |+float| feature} + +items({dict}) *items()* + Return a |List| with all the key-value pairs of {dict}. Each + |List| item is a list with two items: the key of a {dict} + entry and the value of this entry. The |List| is in arbitrary + order. Also see |keys()| and |values()|. + Example: > + for [key, value] in items(mydict) + echo key . ': ' . value + endfor + +< Can also be used as a |method|: > + mydict->items() + +job_ functions are documented here: |job-functions-details| + + +join({list} [, {sep}]) *join()* + Join the items in {list} together into one String. + When {sep} is specified it is put in between the items. If + {sep} is omitted a single space is used. + Note that {sep} is not added at the end. You might want to + add it there too: > + let lines = join(mylist, "\n") . "\n" +< String items are used as-is. |Lists| and |Dictionaries| are + converted into a string like with |string()|. + The opposite function is |split()|. + + Can also be used as a |method|: > + mylist->join() + +js_decode({string}) *js_decode()* + This is similar to |json_decode()| with these differences: + - Object key names do not have to be in quotes. + - Strings can be in single quotes. + - Empty items in an array (between two commas) are allowed and + result in v:none items. + + Can also be used as a |method|: > + ReadObject()->js_decode() + +js_encode({expr}) *js_encode()* + This is similar to |json_encode()| with these differences: + - Object key names are not in quotes. + - v:none items in an array result in an empty item between + commas. + For example, the Vim object: + [1,v:none,{"one":1},v:none] ~ + Will be encoded as: + [1,,{one:1},,] ~ + While json_encode() would produce: + [1,null,{"one":1},null] ~ + This encoding is valid for JavaScript. It is more efficient + than JSON, especially when using an array with optional items. + + Can also be used as a |method|: > + GetObject()->js_encode() + +json_decode({string}) *json_decode()* + This parses a JSON formatted string and returns the equivalent + in Vim values. See |json_encode()| for the relation between + JSON and Vim values. + The decoding is permissive: + - A trailing comma in an array and object is ignored, e.g. + "[1, 2, ]" is the same as "[1, 2]". + - Integer keys are accepted in objects, e.g. {1:2} is the + same as {"1":2}. + - More floating point numbers are recognized, e.g. "1." for + "1.0", or "001.2" for "1.2". Special floating point values + "Infinity", "-Infinity" and "NaN" (capitalization ignored) + are accepted. + - Leading zeroes in integer numbers are ignored, e.g. "012" + for "12" or "-012" for "-12". + - Capitalization is ignored in literal names null, true or + false, e.g. "NULL" for "null", "True" for "true". + - Control characters U+0000 through U+001F which are not + escaped in strings are accepted, e.g. " " (tab + character in string) for "\t". + - An empty JSON expression or made of only spaces is accepted + and results in v:none. + - Backslash in an invalid 2-character sequence escape is + ignored, e.g. "\a" is decoded as "a". + - A correct surrogate pair in JSON strings should normally be + a 12 character sequence such as "\uD834\uDD1E", but + json_decode() silently accepts truncated surrogate pairs + such as "\uD834" or "\uD834\u" + *E938* + A duplicate key in an object, valid in rfc7159, is not + accepted by json_decode() as the result must be a valid Vim + type, e.g. this fails: {"a":"b", "a":"c"} + + Can also be used as a |method|: > + ReadObject()->json_decode() + +json_encode({expr}) *json_encode()* + Encode {expr} as JSON and return this as a string. + The encoding is specified in: + https://tools.ietf.org/html/rfc7159.html + Vim values are converted as follows: + |Number| decimal number + |Float| floating point number + Float nan "NaN" + Float inf "Infinity" + Float -inf "-Infinity" + |String| in double quotes (possibly null) + |Funcref| not possible, error + |List| as an array (possibly null); when + used recursively: [] + |Dict| as an object (possibly null); when + used recursively: {} + |Blob| as an array of the individual bytes + v:false "false" + v:true "true" + v:none "null" + v:null "null" + Note that NaN and Infinity are passed on as values. This is + missing in the JSON standard, but several implementations do + allow it. If not then you will get an error. + + Can also be used as a |method|: > + GetObject()->json_encode() + +keys({dict}) *keys()* + Return a |List| with all the keys of {dict}. The |List| is in + arbitrary order. Also see |items()| and |values()|. + + Can also be used as a |method|: > + mydict->keys() + +< *len()* *E701* +len({expr}) The result is a Number, which is the length of the argument. + When {expr} is a String or a Number the length in bytes is + used, as with |strlen()|. + When {expr} is a |List| the number of items in the |List| is + returned. + When {expr} is a |Blob| the number of bytes is returned. + When {expr} is a |Dictionary| the number of entries in the + |Dictionary| is returned. + Otherwise an error is given. + + Can also be used as a |method|: > + mylist->len() + +< *libcall()* *E364* *E368* +libcall({libname}, {funcname}, {argument}) + Call function {funcname} in the run-time library {libname} + with single argument {argument}. + This is useful to call functions in a library that you + especially made to be used with Vim. Since only one argument + is possible, calling standard library functions is rather + limited. + The result is the String returned by the function. If the + function returns NULL, this will appear as an empty string "" + to Vim. + If the function returns a number, use libcallnr()! + If {argument} is a number, it is passed to the function as an + int; if {argument} is a string, it is passed as a + null-terminated string. + This function will fail in |restricted-mode|. + + libcall() allows you to write your own 'plug-in' extensions to + Vim without having to recompile the program. It is NOT a + means to call system functions! If you try to do so Vim will + very probably crash. + + For Win32, the functions you write must be placed in a DLL + and use the normal C calling convention (NOT Pascal which is + used in Windows System DLLs). The function must take exactly + one parameter, either a character pointer or a long integer, + and must return a character pointer or NULL. The character + pointer returned must point to memory that will remain valid + after the function has returned (e.g. in static data in the + DLL). If it points to allocated memory, that memory will + leak away. Using a static buffer in the function should work, + it's then freed when the DLL is unloaded. + + WARNING: If the function returns a non-valid pointer, Vim may + crash! This also happens if the function returns a number, + because Vim thinks it's a pointer. + For Win32 systems, {libname} should be the filename of the DLL + without the ".DLL" suffix. A full path is only required if + the DLL is not in the usual places. + For Unix: When compiling your own plugins, remember that the + object code must be compiled as position-independent ('PIC'). + {only in Win32 and some Unix versions, when the |+libcall| + feature is present} + Examples: > + :echo libcall("libc.so", "getenv", "HOME") + +< Can also be used as a |method|, the base is passed as the + third argument: > + GetValue()->libcall("libc.so", "getenv") +< + *libcallnr()* +libcallnr({libname}, {funcname}, {argument}) + Just like |libcall()|, but used for a function that returns an + int instead of a string. + {only in Win32 on some Unix versions, when the |+libcall| + feature is present} + Examples: > + :echo libcallnr("/usr/lib/libc.so", "getpid", "") + :call libcallnr("libc.so", "printf", "Hello World!\n") + :call libcallnr("libc.so", "sleep", 10) +< + Can also be used as a |method|, the base is passed as the + third argument: > + GetValue()->libcallnr("libc.so", "printf") +< + +line({expr} [, {winid}]) *line()* + The result is a Number, which is the line number of the file + position given with {expr}. The {expr} argument is a string. + The accepted positions are: + . the cursor position + $ the last line in the current buffer + 'x position of mark x (if the mark is not set, 0 is + returned) + w0 first line visible in current window (one if the + display isn't updated, e.g. in silent Ex mode) + w$ last line visible in current window (this is one + less than "w0" if no lines are visible) + v In Visual mode: the start of the Visual area (the + cursor is the end). When not in Visual mode + returns the cursor position. Differs from |'<| in + that it's updated right away. + Note that a mark in another file can be used. The line number + then applies to another buffer. + To get the column number use |col()|. To get both use + |getpos()|. + With the optional {winid} argument the values are obtained for + that window instead of the current window. + Examples: > + line(".") line number of the cursor + line(".", winid) idem, in window "winid" + line("'t") line number of mark t + line("'" . marker) line number of mark marker +< + To jump to the last known position when opening a file see + |last-position-jump|. + + Can also be used as a |method|: > + GetValue()->line() + +line2byte({lnum}) *line2byte()* + Return the byte count from the start of the buffer for line + {lnum}. This includes the end-of-line character, depending on + the 'fileformat' option for the current buffer. The first + line returns 1. 'encoding' matters, 'fileencoding' is ignored. + This can also be used to get the byte count for the line just + below the last line: > + line2byte(line("$") + 1) +< This is the buffer size plus one. If 'fileencoding' is empty + it is the file size plus one. {lnum} is used like with + |getline()|. When {lnum} is invalid, or the |+byte_offset| + feature has been disabled at compile time, -1 is returned. + Also see |byte2line()|, |go| and |:goto|. + + Can also be used as a |method|: > + GetLnum()->line2byte() + +lispindent({lnum}) *lispindent()* + Get the amount of indent for line {lnum} according the lisp + indenting rules, as with 'lisp'. + The indent is counted in spaces, the value of 'tabstop' is + relevant. {lnum} is used just like in |getline()|. + When {lnum} is invalid or Vim was not compiled the + |+lispindent| feature, -1 is returned. In |Vim9| script an + error is given. + + Can also be used as a |method|: > + GetLnum()->lispindent() + +list2blob({list}) *list2blob()* + Return a Blob concatenating all the number values in {list}. + Examples: > + list2blob([1, 2, 3, 4]) returns 0z01020304 + list2blob([]) returns 0z +< Returns an empty Blob on error. If one of the numbers is + negative or more than 255 error *E1239* is given. + + |blob2list()| does the opposite. + + Can also be used as a |method|: > + GetList()->list2blob() + +list2str({list} [, {utf8}]) *list2str()* + Convert each number in {list} to a character string can + concatenate them all. Examples: > + list2str([32]) returns " " + list2str([65, 66, 67]) returns "ABC" +< The same can be done (slowly) with: > + join(map(list, {nr, val -> nr2char(val)}), '') +< |str2list()| does the opposite. + + When {utf8} is omitted or zero, the current 'encoding' is used. + When {utf8} is TRUE, always return UTF-8 characters. + With UTF-8 composing characters work as expected: > + list2str([97, 769]) returns "á" +< + Can also be used as a |method|: > + GetList()->list2str() + +listener_add({callback} [, {buf}]) *listener_add()* + Add a callback function that will be invoked when changes have + been made to buffer {buf}. + {buf} refers to a buffer name or number. For the accepted + values, see |bufname()|. When {buf} is omitted the current + buffer is used. + Returns a unique ID that can be passed to |listener_remove()|. + + The {callback} is invoked with five arguments: + a:bufnr the buffer that was changed + a:start first changed line number + a:end first line number below the change + a:added number of lines added, negative if lines were + deleted + a:changes a List of items with details about the changes + + Example: > + func Listener(bufnr, start, end, added, changes) + echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed' + endfunc + call listener_add('Listener', bufnr) + +< The List cannot be changed. Each item in a:changes is a + dictionary with these entries: + lnum the first line number of the change + end the first line below the change + added number of lines added; negative if lines were + deleted + col first column in "lnum" that was affected by + the change; one if unknown or the whole line + was affected; this is a byte index, first + character has a value of one. + When lines are inserted the values are: + lnum line above which the new line is added + end equal to "lnum" + added number of lines inserted + col 1 + When lines are deleted the values are: + lnum the first deleted line + end the line below the first deleted line, before + the deletion was done + added negative, number of lines deleted + col 1 + When lines are changed: + lnum the first changed line + end the line below the last changed line + added 0 + col first column with a change or 1 + + The entries are in the order the changes were made, thus the + most recent change is at the end. The line numbers are valid + when the callback is invoked, but later changes may make them + invalid, thus keeping a copy for later might not work. + + The {callback} is invoked just before the screen is updated, + when |listener_flush()| is called or when a change is being + made that changes the line count in a way it causes a line + number in the list of changes to become invalid. + + The {callback} is invoked with the text locked, see + |textlock|. If you do need to make changes to the buffer, use + a timer to do this later |timer_start()|. + + The {callback} is not invoked when the buffer is first loaded. + Use the |BufReadPost| autocmd event to handle the initial text + of a buffer. + The {callback} is also not invoked when the buffer is + unloaded, use the |BufUnload| autocmd event for that. + + Can also be used as a |method|, the base is passed as the + second argument: > + GetBuffer()->listener_add(callback) + +listener_flush([{buf}]) *listener_flush()* + Invoke listener callbacks for buffer {buf}. If there are no + pending changes then no callbacks are invoked. + + {buf} refers to a buffer name or number. For the accepted + values, see |bufname()|. When {buf} is omitted the current + buffer is used. + + Can also be used as a |method|: > + GetBuffer()->listener_flush() + +listener_remove({id}) *listener_remove()* + Remove a listener previously added with listener_add(). + Returns FALSE when {id} could not be found, TRUE when {id} was + removed. + + Can also be used as a |method|: > + GetListenerId()->listener_remove() + +localtime() *localtime()* + Return the current time, measured as seconds since 1st Jan + 1970. See also |strftime()|, |strptime()| and |getftime()|. + + +log({expr}) *log()* + Return the natural logarithm (base e) of {expr} as a |Float|. + {expr} must evaluate to a |Float| or a |Number| in the range + (0, inf]. + Examples: > + :echo log(10) +< 2.302585 > + :echo log(exp(5)) +< 5.0 + + Can also be used as a |method|: > + Compute()->log() +< + {only available when compiled with the |+float| feature} + + +log10({expr}) *log10()* + Return the logarithm of Float {expr} to base 10 as a |Float|. + {expr} must evaluate to a |Float| or a |Number|. + Examples: > + :echo log10(1000) +< 3.0 > + :echo log10(0.01) +< -2.0 + + Can also be used as a |method|: > + Compute()->log10() +< + {only available when compiled with the |+float| feature} + +luaeval({expr} [, {expr}]) *luaeval()* + Evaluate Lua expression {expr} and return its result converted + to Vim data structures. Second {expr} may hold additional + argument accessible as _A inside first {expr}. + Strings are returned as they are. + Boolean objects are converted to numbers. + Numbers are converted to |Float| values if vim was compiled + with |+float| and to numbers otherwise. + Dictionaries and lists obtained by vim.eval() are returned + as-is. + Other objects are returned as zero without any errors. + See |lua-luaeval| for more details. + Note that in a `:def` function local variables are not visible + to {expr}. + + Can also be used as a |method|: > + GetExpr()->luaeval() + +< {only available when compiled with the |+lua| feature} + +map({expr1}, {expr2}) *map()* + {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. + When {expr1} is a |List|| or |Dictionary|, replace each + item in {expr1} with the result of evaluating {expr2}. + For a |Blob| each byte is replaced. + For a |String|, each character, including composing + characters, is replaced. + If the item type changes you may want to use |mapnew()| to + create a new List or Dictionary. This is required when using + Vim9 script. + + {expr2} must be a |String| or |Funcref|. + + If {expr2} is a |String|, inside {expr2} |v:val| has the value + of the current item. For a |Dictionary| |v:key| has the key + of the current item and for a |List| |v:key| has the index of + the current item. For a |Blob| |v:key| has the index of the + current byte. For a |String| |v:key| has the index of the + current character. + Example: > + :call map(mylist, '"> " . v:val . " <"') +< This puts "> " before and " <" after each item in "mylist". + + Note that {expr2} is the result of an expression and is then + used as an expression again. Often it is good to use a + |literal-string| to avoid having to double backslashes. You + still have to double ' quotes + + If {expr2} is a |Funcref| it is called with two arguments: + 1. The key or the index of the current item. + 2. the value of the current item. + The function must return the new value of the item. Example + that changes each value by "key-value": > + func KeyValue(key, val) + return a:key . '-' . a:val + endfunc + call map(myDict, function('KeyValue')) +< It is shorter when using a |lambda|: > + call map(myDict, {key, val -> key . '-' . val}) +< If you do not use "val" you can leave it out: > + call map(myDict, {key -> 'item: ' . key}) +< If you do not use "key" you can use a short name: > + call map(myDict, {_, val -> 'item: ' . val}) +< + The operation is done in-place for a |List| and |Dictionary|. + If you want it to remain unmodified make a copy first: > + :let tlist = map(copy(mylist), ' v:val . "\t"') + +< Returns {expr1}, the |List| or |Dictionary| that was filtered, + or a new |Blob| or |String|. + When an error is encountered while evaluating {expr2} no + further items in {expr1} are processed. + When {expr2} is a Funcref errors inside a function are ignored, + unless it was defined with the "abort" flag. + + Can also be used as a |method|: > + mylist->map(expr2) + + +maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* + When {dict} is omitted or zero: Return the rhs of mapping + {name} in mode {mode}. The returned String has special + characters translated like in the output of the ":map" command + listing. + + When there is no mapping for {name}, an empty String is + returned. When the mapping for {name} is empty, then "" + is returned. + + The {name} can have special key names, like in the ":map" + command. + + {mode} can be one of these strings: + "n" Normal + "v" Visual (including Select) + "o" Operator-pending + "i" Insert + "c" Cmd-line + "s" Select + "x" Visual + "l" langmap |language-mapping| + "t" Terminal-Job + "" Normal, Visual and Operator-pending + When {mode} is omitted, the modes for "" are used. + + When {abbr} is there and it is |TRUE| use abbreviations + instead of mappings. + + When {dict} is there and it is |TRUE| return a dictionary + containing all the information of the mapping with the + following items: + "lhs" The {lhs} of the mapping as it would be typed + "lhsraw" The {lhs} of the mapping as raw bytes + "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate + form, only present when it differs from "lhsraw" + "rhs" The {rhs} of the mapping as typed. + "silent" 1 for a |:map-silent| mapping, else 0. + "noremap" 1 if the {rhs} of the mapping is not remappable. + "script" 1 if mapping was defined with