Mercurial > vim
diff runtime/doc/eval.txt @ 1621:82b5078be2dd
updated for version 7.2a
| author | vimboss |
|---|---|
| date | Tue, 24 Jun 2008 21:56:24 +0000 |
| parents | 1324b7b755f3 |
| children | 5bbc2d6658ad |
line wrap: on
line diff
--- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,7 +1,7 @@ -*eval.txt* For Vim version 7.1. Last change: 2008 May 28 - - - VIM REFERENCE MANUAL by Bram Moolenaar +*eval.txt* For Vim version 7.2a. Last change: 2008 Jun 24 + + + VIM REFERENCE MANUAL by Bram Moolenaar Expression evaluation *expression* *expr* *E15* *eval* @@ -9,7 +9,7 @@ Expression evaluation *expression* *ex Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|. Note: Expression evaluation can be disabled at compile time. If this has been -done, the features in this document are not available. See |+eval| and +done, the features in this document are not available. See |+eval| and |no-eval-feature|. 1. Variables |variables| @@ -37,13 +37,17 @@ 1. Variables *variables* 1.1 Variable types ~ *E712* -There are five types of variables: - -Number A 32 bit signed number. +There are six types of variables: + +Number A 32 bit signed number. |expr-number| *Number* Examples: -123 0x10 0177 +Float A floating point number. |floating-point-format| *Float* + {only when compiled with the |+float| feature} + Examples: 123.456 1.15e-6 -1.1e3 + String A NUL terminated string of 8-bit unsigned characters (bytes). - Examples: "ab\txx\"--" 'x-z''a,c' + |expr-string| Examples: "ab\txx\"--" 'x-z''a,c' Funcref A reference to a function |Funcref|. Example: function("strlen") @@ -92,18 +96,26 @@ use strlen(): > < *E745* *E728* *E703* *E729* *E730* *E731* List, Dictionary and Funcref types are not automatically converted. - *E706* + *E805* *E806* *E808* +When mixing Number and Float the Number is converted to Float. Otherwise +there is no automatic conversion of Float. You can use str2float() for String +to Float, printf() for Float to String and float2nr() for Float to Number. + + *E706* *sticky-type-checking* You will get an error if you try to change the type of a variable. You need to |:unlet| it first to avoid this error. String and Number are considered -equivalent though. Consider this sequence of commands: > +equivalent though, as well are Float and Number. Consider this sequence of +commands: > :let l = "string" :let l = 44 " changes type from String to Number - :let l = [1, 2, 3] " error! + :let l = [1, 2, 3] " error! l is still a Number + :let l = 4.4 " changes type from Number to Float + :let l = "string" " error! 1.2 Function references ~ *Funcref* *E695* *E718* -A Funcref variable is obtained with the |function()| function. It can be used +A Funcref variable is obtained with the |function()| function. It can be used in an expression in the place of a function name, before the parenthesis around the arguments, to invoke the function it refers to. Example: > @@ -137,7 +149,7 @@ arguments: > 1.3 Lists ~ *List* *Lists* *E686* A List is an ordered sequence of items. An item can be of any type. Items -can be accessed by their index number. Items can be added and removed at any +can be accessed by their index number. Items can be added and removed at any position in the sequence. @@ -148,7 +160,7 @@ Examples: > :let mylist = [1, two, 3, "four"] :let emptylist = [] -An item can be any expression. Using a List for an item creates a +An item can be any expression. Using a List for an item creates a List of Lists: > :let nestlist = [[11, 12], [21, 22], [31, 32]] @@ -207,7 +219,7 @@ length minus one is used: > :echo mylist[2:8] " result: [2, 3] NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for -using a single letter variable before the ":". Insert a space when needed: +using a single letter variable before the ":". Insert a space when needed: mylist[s : e]. @@ -258,13 +270,13 @@ variables. Example: > < 0 Thus comparing Lists is more strict than comparing numbers and strings. You -can compare simple values this way too by putting them in a string: > +can compare simple values this way too by putting them in a list: > :let a = 5 :let b = "5" - echo a == b + :echo a == b < 1 > - echo [a] == [b] + :echo [a] == [b] < 0 @@ -339,7 +351,7 @@ the loop. If all you want to do is modify each item in the list then the |map()| function will be a simpler method than a for loop. -Just like the |:let| command, |:for| also accepts a list of variables. This +Just like the |:let| command, |:for| also accepts a list of variables. This requires the argument to be a list of lists. > :for [lnum, col] in [[1, 3], [2, 8], [3, 0]] : call Doit(lnum, col) @@ -396,10 +408,10 @@ only appear once. Examples: > < *E713* *E716* *E717* A key is always a String. You can use a Number, it will be converted to a String automatically. Thus the String '4' and the number 4 will find the same -entry. Note that the String '04' and the Number 04 are different, since the +entry. Note that the String '04' and the Number 04 are different, since the Number will be converted to the String '4'. -A value can be any expression. Using a Dictionary for a value creates a +A value can be any expression. Using a Dictionary for a value creates a nested Dictionary: > :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}} @@ -426,7 +438,7 @@ key lookup can be repeated: > Dictionary to List conversion ~ -You may want to loop over the entries in a dictionary. For this you need to +You may want to loop over the entries in a dictionary. For this you need to turn the Dictionary into a List and pass it to |:for|. Most often you want to loop over the keys, using the |keys()| function: > @@ -443,7 +455,7 @@ To loop over the values use the |values( :endfor If you want both the key and the value use the |items()| function. It returns -a List in which each item is a List with two items, the key and the value: > +a List in which each item is a List with two items, the key and the value: > :for [key, value] in items(mydict) : echo key . ': ' . value :endfor @@ -493,7 +505,7 @@ This removes all entries from "dict" wit Dictionary function ~ *Dictionary-function* *self* *E725* When a function is defined with the "dict" attribute it can be used in a -special way with a dictionary. Example: > +special way with a dictionary. Example: > :function Mylen() dict : return len(self.data) :endfunction @@ -517,7 +529,7 @@ assigned to a Dictionary in this way: > :echo mydict.len() The function will then get a number and the value of dict.len is a |Funcref| -that references this function. The function can only be used through a +that references this function. The function can only be used through a |Funcref|. It will automatically be deleted when there is no |Funcref| remaining that refers to it. @@ -699,7 +711,7 @@ expr5 {cmp} expr5 Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1 if it evaluates to true. - *expr-==* *expr-!=* *expr->* *expr->=* + *expr-==* *expr-!=* *expr->* *expr->=* *expr-<* *expr-<=* *expr-=~* *expr-!~* *expr-==#* *expr-!=#* *expr->#* *expr->=#* *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#* @@ -738,21 +750,21 @@ A |Funcref| can only be compared with a equal" can be used. Case is never ignored. When using "is" or "isnot" with a |List| this checks if the expressions are -referring to the same |List| instance. A copy of a |List| is different from +referring to the same |List| instance. A copy of a |List| is different from the original |List|. When using "is" without a |List| it is equivalent to using "equal", using "isnot" equivalent to using "not equal". Except that a -different type means the values are different. "4 == '4'" is true, "4 is '4'" +different type means the values are different. "4 == '4'" is true, "4 is '4'" is false. When comparing a String with a Number, the String is converted to a Number, -and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE, +and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE, because 'x' converted to a Number is zero. When comparing two Strings, this is done with strcmp() or stricmp(). This results in the mathematical difference (comparing byte values), not necessarily the alphabetical difference in the local language. -When using the operators with a trailing '#", or the short version and +When using the operators with a trailing '#', or the short version and 'ignorecase' is off, the comparing is done with strcmp(): case matters. When using the operators with a trailing '?', or the short version and @@ -792,11 +804,30 @@ Note the difference between "+" and ".": "123" + "456" = 579 "123" . "456" = "123456" -When the righthand side of '/' is zero, the result is 0x7fffffff. +Since '.' has the same precedence as '+' and '-', you need to read: > + 1 . 90 + 90.0 +As: > + (1 . 90) + 90.0 +That works, since the String "190" is automatically converted to the Number +190, which can be added to the Float 90.0. However: > + 1 . 90 * 90.0 +Should be read as: > + 1 . (90 * 90.0) +Since '.' has lower precedence than '*'. This does NOT work, since this +attempts to concatenate a Float and a String. + +When dividing a Number by zero the result depends on the value: + 0 / 0 = -0x80000000 (like NaN for Float) + >0 / 0 = 0x7fffffff (like positive infinity) + <0 / 0 = -0x7fffffff (like negative infinity) + (before Vim 7.2 it was always 0x7fffffff) + When the righthand side of '%' is zero, the result is 0. None of these work for |Funcref|s. +. and % do not work for Float. *E804* + expr7 *expr7* ----- @@ -810,7 +841,7 @@ For '+' the number is unchanged. A String will be converted to a Number first. -These three can be repeated and mixed. Examples: +These three can be repeated and mixed. Examples: !-1 == 0 !!8 == 1 --9 == 9 @@ -835,7 +866,7 @@ compatibility). Use [-1:] to get the la If expr8 is a |List| then it results the item at index expr1. See |list-index| for possible index values. If the index is out of range this results in an -error. Example: > +error. Example: > :let item = mylist[-1] " get last item Generally, if a |List| index is equal to or higher than the length of the @@ -866,7 +897,7 @@ Examples: > :let s = s[:-3] " remove last two bytes If expr8 is a |List| this results in a new |List| with the items indicated by -the indexes expr1a and expr1b. This works like with a String, as explained +the indexes expr1a and expr1b. This works like with a String, as explained just above, except that indexes out of range cause an error. Examples: > :let l = mylist[:3] " first four items :let l = mylist[4:4] " List with one item @@ -909,6 +940,53 @@ number number constant *expr-number* Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0). + *floating-point-format* +Floating point numbers can be written in two forms: + + [-+]{N}.{M} + [-+]{N}.{M}e[-+]{exp} + +{N} and {M} are numbers. Both {N} and {M} must be present and can only +contain digits. +[-+] means there is an optional plus or minus sign. +{exp} is the exponent, power of 10. +Only a decimal point is accepted, not a comma. No matter what the current +locale is. +{only when compiled with the |+float| feature} + +Examples: + 123.456 + +0.0001 + 55.0 + -0.123 + 1.234e03 + 1.0E-6 + -3.1416e+88 + +These are INVALID: + 3. empty {M} + 1e40 missing .{M} + +Rationale: +Before floating point was introduced, the text "123.456" was interpreted as +the two numbers "123" and "456", both converted to a string and concatenated, +resulting in the string "123456". Since this was considered pointless, and we +could not find it actually being used in Vim scripts, this backwards +incompatibility was accepted in favor of being able to use the normal notation +for floating point numbers. + + *floating-point-precision* +The precision and range of floating points numbers depends on what "double" +means in the library Vim was compiled with. There is no way to change this at +runtime. + +The default for displaying a |Float| is to use 6 decimal places, like using +printf("%g", f). You can select something else when using the |printf()| +function. Example: > + :echo printf('%.15e', atan(1)) +< 7.853981633974483e-01 + + string *expr-string* *E114* ------ @@ -924,7 +1002,7 @@ A string constant accepts these special \x. byte specified with one hex number (must be followed by non-hex char) \X.. same as \x.. \X. same as \x. -\u.... character specified with up to 4 hex numbers, stored according to the +\u.... character specified with up to 4 hex numbers, stored according to the current value of 'encoding' (e.g., "\u02a4") \U.... same as \u.... \b backspace <BS> @@ -950,11 +1028,11 @@ literal-string *literal-string* *E1 Note that single quotes are used. -This string is taken as it is. No backslashes are removed or have a special +This string is taken as it is. No backslashes are removed or have a special meaning. The only exception is that two quotes stand for one quote. Single quoted strings are useful for patterns, so that backslashes do not need -to be doubled. These two commands are equivalent: > +to be doubled. These two commands are equivalent: > if a =~ "\\s*" if a =~ '\s*' @@ -980,7 +1058,7 @@ register *expr-register* *@r* The result is the contents of the named register, as a single string. Newlines are inserted where required. To get the contents of the unnamed -register use @" or @@. See |registers| for an explanation of the available +register use @" or @@. See |registers| for an explanation of the available registers. When using the '=' register you get the expression itself, not what it @@ -1047,7 +1125,7 @@ specified by what is prepended: |local-variable| l: Local to a function. |script-variable| s: Local to a |:source|'ed Vim script. |function-argument| a: Function argument (only inside a function). -|vim-variable| v: Global, predefined by Vim. +|vim-variable| v: Global, predefined by Vim. The scope name by itself can be used as a |Dictionary|. For example, to delete all script-local variables: > @@ -1068,8 +1146,8 @@ b:changedtick The total number of change in this case. This can be used to perform an action only when the buffer has changed. Example: > :if my_changedtick != b:changedtick - : let my_changedtick = b:changedtick - : call My_Update() + : let my_changedtick = b:changedtick + : call My_Update() :endif < *window-variable* *w:var* @@ -1083,7 +1161,7 @@ without the +windows feature} *global-variable* *g:var* Inside functions global variables are accessed with "g:". Omitting this will -access a variable local to a function. But "g:" can also be used in any other +access a variable local to a function. But "g:" can also be used in any other place if you like. *local-variable* *l:var* @@ -1216,7 +1294,7 @@ v:cmdarg This variable is used for two p set before an autocommand event for a file read/write command is triggered. There is a leading space to make it possible to append this variable directly after the - read/write command. Note: The "+cmd" argument isn't + read/write command. Note: The "+cmd" argument isn't included here, because it will be executed anyway. 2. When printing a PostScript file with ":hardcopy" this is the argument for the ":hardcopy" command. This can be used @@ -1230,7 +1308,7 @@ v:cmdbang Set like v:cmdarg for a file r *v:count* *count-variable* v:count The count given for the last Normal mode command. Can be used - to get the count before a mapping. Read-only. Example: > + to get the count before a mapping. Read-only. Example: > :map _x :<C-U>echo "the count is " . v:count<CR> < Note: The <C-U> is required to remove the line range that you get when typing ':' after a count. @@ -1251,7 +1329,7 @@ v:ctype The current locale setting for See |multi-lang|. *v:dying* *dying-variable* -v:dying Normally zero. When a deadly signal is caught it's set to +v:dying Normally zero. When a deadly signal is caught it's set to one. When multiple signals are caught the number increases. Can be used in an autocommand to check if Vim didn't terminate normally. {only works on Unix} @@ -1321,7 +1399,7 @@ v:fname_out The name of the output file. 'diffexpr' output of diff 'patchexpr' resulting patched file (*) When doing conversion for a write command (e.g., ":w - file") it will be equal to v:fname_in. When doing conversion + file") it will be equal to v:fname_in. When doing conversion for a read command (e.g., ":e file") it will be a temporary file and different from v:fname_in. @@ -1423,7 +1501,7 @@ v:prevcount The count given for the last < Read-only. *v:profiling* *profiling-variable* -v:profiling Normally zero. Set to one after using ":profile start". +v:profiling Normally zero. Set to one after using ":profile start". See |profiling|. *v:progname* *progname-variable* @@ -1448,6 +1526,15 @@ v:scrollstart String describing the scri v:servername The resulting registered |x11-clientserver| name if any. Read-only. + +v:searchforward *v:searchforward* *searchforward-variable* + Search direction: 1 after a forward search, 0 after a + backward search. It is reset to forward when directly setting + the last search pattern, see |quote/|. + Note that the value is restored when returning from a + function. |function-search-undo|. + Read-write. + *v:shell_error* *shell_error-variable* v:shell_error Result of the last shell command. When non-zero, the last shell command had an error. When zero, there was no problem. @@ -1477,20 +1564,20 @@ v:swapchoice |SwapExists| autocommands c 'd' Delete swapfile 'q' Quit 'a' Abort - The value should be a single-character string. An empty value + The value should be a single-character string. An empty value results in the user being asked, as would happen when there is no SwapExists autocommand. The default is empty. *v:swapcommand* *swapcommand-variable* v:swapcommand Normal mode command to be executed after a file has been opened. Can be used for a |SwapExists| autocommand to have - another Vim open the file and jump to the right place. For + another Vim open the file and jump to the right place. For example, when jumping to a tag the value is ":tag tagname\r". For ":edit +cmd file" the value is ":cmd\r". *v:termresponse* *termresponse-variable* v:termresponse The escape sequence returned by the terminal for the |t_RV| - termcap entry. It is set when Vim receives an escape sequence + termcap entry. It is set when Vim receives an escape sequence that starts with ESC [ or CSI and ends in a 'c', with only digits, ';' and '.' in between. When this option is set, the TermResponse autocommand event is @@ -1510,7 +1597,7 @@ v:this_session Full filename of the last *v:throwpoint* *throwpoint-variable* v:throwpoint The point where the exception most recently caught and not - finished was thrown. Not set when commands are typed. See + finished was thrown. Not set when commands are typed. See also |v:exception| and |throw-variables|. Example: > :try @@ -1521,7 +1608,7 @@ v:throwpoint The point where the excepti < Output: "Exception from test.vim, line 2" *v:val* *val-variable* -v:val Value of the current item of a |List| or |Dictionary|. Only +v:val Value of the current item of a |List| or |Dictionary|. Only valid while evaluating the expression used with |map()| and |filter()|. Read-only. @@ -1548,6 +1635,7 @@ See |function-list| for a list grouped b USAGE RESULT DESCRIPTION ~ +abs( {expr}) Float or Number absolute value of {expr} add( {list}, {item}) List append {item} to |List| {list} append( {lnum}, {string}) Number append {string} below line {lnum} append( {lnum}, {list}) Number append lines {list} below line {lnum} @@ -1555,9 +1643,10 @@ argc() Number number of files in the argidx() Number current index in the argument list argv( {nr}) String {nr} entry of the argument list argv( ) List the argument list +atan( {expr}) Float arc tangent of {expr} browse( {save}, {title}, {initdir}, {default}) String put up a file requester -browsedir( {title}, {initdir}) String put up a directory requester +browsedir( {title}, {initdir}) String put up a directory requester bufexists( {expr}) Number TRUE if buffer {expr} exists buflisted( {expr}) Number TRUE if buffer {expr} is listed bufloaded( {expr}) Number TRUE if buffer {expr} is loaded @@ -1568,17 +1657,19 @@ byte2line( {byte}) Number line number a byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr} call( {func}, {arglist} [, {dict}]) any call {func} with arguments {arglist} -changenr() Number current change number +ceil( {expr}) Float round {expr} up +changenr() Number current change number char2nr( {expr}) Number ASCII value of first char in {expr} cindent( {lnum}) Number C indent for line {lnum} clearmatches() None clear all matches col( {expr}) Number column nr of cursor or mark -complete({startcol}, {matches}) String set Insert mode completion +complete({startcol}, {matches}) String set Insert mode completion complete_add( {expr}) Number add completion match -complete_check() Number check for key typed during completion +complete_check() Number check for key typed during completion 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} count( {list}, {expr} [, {start} [, {ic}]]) Number count how many {expr} are in {list} cscope_connection( [{num} , {dbpath} [, {prepend}]]) @@ -1600,7 +1691,7 @@ exists( {expr}) Number TRUE if {expr} extend({expr1}, {expr2} [, {expr3}]) List/Dict insert items of {expr2} into {expr1} expand( {expr}) String expand special keywords in {expr} -feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer +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( {expr}, {string}) List/Dict remove items from {expr} where @@ -1609,6 +1700,8 @@ finddir( {name}[, {path}[, {count}]]) String find directory {name} in {path} findfile( {name}[, {path}[, {count}]]) String find file {name} in {path} +float2nr( {expr}) Number convert Float {expr} to a Number +floor( {expr}) Float round {expr} down 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 @@ -1687,6 +1780,7 @@ line( {expr}) Number line nr of cursor line2byte( {lnum}) Number byte count of line {lnum} lispindent( {lnum}) Number Lisp indent for line {lnum} localtime() Number current time +log10( {expr}) Float logarithm of Float {expr} to base 10 map( {expr}, {string}) List/Dict change each item in {expr} to {expr} maparg( {name}[, {mode} [, {abbr}]]) String rhs of mapping {name} in mode {mode} @@ -1708,13 +1802,14 @@ max({list}) Number maximum value of it min({list}) Number minimum value of items in {list} mkdir({name} [, {path} [, {prot}]]) Number create directory {name} -mode() String current editing mode +mode( [expr]) String current editing mode nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum} nr2char( {expr}) String single char with ASCII value {expr} pathshorten( {expr}) String shorten directory names in a path +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 -pumvisible() Number whether popup menu is visible +printf( {fmt}, {expr1}...) String format text +pumvisible() Number whether popup menu is visible range( {expr} [, {max} [, {stride}]]) List items from {expr} to {max} readfile({fname} [, {binary} [, {max}]]) @@ -1735,10 +1830,11 @@ rename( {from}, {to}) Number rename (mo 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} search( {pattern} [, {flags} [, {stopline} [, {timeout}]]]) Number search for {pattern} searchdecl({name} [, {global} [, {thisblock}]]) - Number search for variable declaration + 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} [...]]]) @@ -1763,6 +1859,7 @@ setwinvar( {nr}, {varname}, {val}) set { shellescape( {string}) String escape {string} for use as shell command argument simplify( {filename}) String simplify filename as much as possible +sin( {expr}) Float sine of {expr} sort( {list} [, {func}]) List sort {list}, using {func} to compare soundfold( {word}) String sound-fold {word} spellbadword() String badly spelled word at cursor @@ -1770,7 +1867,9 @@ spellsuggest( {word} [, {max} [, {capita List spelling suggestions split( {expr} [, {pat} [, {keepempty}]]) List make |List| from {pat} separated {expr} -str2nr( {expr} [, {base}]) Number convert string to number +sqrt( {expr} Float squar root of {expr} +str2float( {expr}) Float convert String to Float +str2nr( {expr} [, {base}]) Number convert String to Number strftime( {format}[, {time}]) String time in specified format stridx( {haystack}, {needle}[, {start}]) Number index of {needle} in {haystack} @@ -1788,19 +1887,20 @@ synID( {lnum}, {col}, {trans}) Number sy synIDattr( {synID}, {what} [, {mode}]) String attribute {what} of syntax ID {synID} synIDtrans( {synID}) Number translated syntax ID of {synID} -synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col} +synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col} system( {expr} [, {input}]) String 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 taglist( {expr}) List list of tags matching {expr} -tagfiles() List tags files used +tagfiles() List tags files used tempname() String name for a temporary file 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} +trunc( {expr} Float truncate Float {expr} type( {name}) Number type of variable {name} values( {dict}) List values in {dict} virtcol( {expr}) Number screen column of cursor or mark @@ -1817,6 +1917,20 @@ winwidth( {nr}) Number width of window writefile({list}, {fname} [, {binary}]) Number write list of lines to file {fname} +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 + {only available when compiled with the |+float| feature} + add({list}, {expr}) *add()* Append the item {expr} to |List| {list}. Returns the resulting |List|. Examples: > @@ -1834,7 +1948,7 @@ append({lnum}, {expr}) *append()* the current buffer. {lnum} can be zero to insert a line before the first one. Returns 1 for failure ({lnum} out of range or out of memory), - 0 for success. Example: > + 0 for success. Example: > :let failed = append(line('$'), "# THE END") :let failed = append(0, ["Chapter 1", "the beginning"]) < @@ -1852,13 +1966,24 @@ argv([{nr}]) The result is the {nr}th fi Example: > :let i = 0 :while i < argc() - : let f = escape(argv(i), '. ') + : let f = escape(fnameescape(argv(i)), '.') : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>' : let i = i + 1 :endwhile < Without the {nr} argument a |List| with the whole |arglist| is returned. +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 + {only available when compiled with the |+float| feature} + *browse()* browse({save}, {title}, {initdir}, {default}) Put up a file requester. This only works when "has("browse")" @@ -1892,12 +2017,15 @@ bufexists({expr}) *bufexists()* exactly. The name can be: - Relative to the current directory. - A full path. - - The name of a buffer with 'filetype' set to "nofile". + - 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. *buffer_exists()* @@ -1919,7 +2047,7 @@ bufname({expr}) *bufname()* If {expr} is a Number, that buffer number's name is given. Number zero is the alternate buffer for the current window. If {expr} is a String, it is used as a |file-pattern| to match - with the buffer names. This is always done like 'magic' is + 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 @@ -1965,7 +2093,7 @@ bufnr({expr} [, {create}]) bufwinnr({expr}) *bufwinnr()* The result is a Number, which is the number of the first window associated with buffer {expr}. For the use of {expr}, - see |bufname()| above. If buffer {expr} doesn't exist or + see |bufname()| above. If buffer {expr} doesn't exist or there is no such window, -1 is returned. Example: > echo "A window containing buffer 1 is " . (bufwinnr(1)) @@ -2010,6 +2138,19 @@ call({func}, {arglist} [, {dict}]) *ca {dict} is for functions with the "dict" attribute. It will be used to set the local variable "self". |Dictionary-function| +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 + {only available when compiled with the |+float| feature} + 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 @@ -2025,7 +2166,7 @@ char2nr({expr}) *char2nr()* < The current 'encoding' is used. Example for "utf-8": > char2nr("á") returns 225 char2nr("á"[0]) returns 195 -< nr2char() does the opposite. +< |nr2char()| does the opposite. cindent({lnum}) *cindent()* Get the amount of indent for line {lnum} according the C @@ -2050,7 +2191,7 @@ col({expr}) The result is a Number, whic returned) Additionally {expr} can be [lnum, col]: a |List| with the line and column number. Most useful when the column is "$", to get - the las column of a specific line. When "lnum" or "col" is + 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()|. @@ -2061,7 +2202,7 @@ col({expr}) The result is a Number, whic 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. +< 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 @@ -2108,7 +2249,7 @@ complete_add({expr}) *complete_add()* 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 + See |complete-functions| for an explanation of {expr}. It is the same as one item in the list that 'omnifunc' would return. complete_check() *complete_check()* @@ -2144,7 +2285,7 @@ confirm({msg} [, {choices} [, {default} that is made if the user hits <CR>. 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} argument gives the type of dialog. This + The optional {type} argument gives the type of dialog. This is only used for the icon of the Win32 GUI. It can be one of these values: "Error", "Question", "Info", "Warning" or "Generic". Only the first character is relevant. When {type} @@ -2163,20 +2304,31 @@ confirm({msg} [, {choices} [, {default} :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() + 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. *copy()* -copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't +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 vise versa. But the items are identical, thus - changing an item changes the contents of both |Lists|. Also + copy, and vice versa. But the items are identical, thus + changing an item changes the contents of both |Lists|. Also see |deepcopy()|. +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 + {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 |List| or |Dictionary| {comp}. @@ -2247,11 +2399,11 @@ cursor({list}) deepcopy({expr}[, {noref}]) *deepcopy()* *E698* - Make a copy of {expr}. For Numbers and Strings this isn't + 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 vise versa. When an item is a |List|, a copy for it + copy, and vice versa. When an item is a |List|, a copy for it is made, recursively. Thus changing an item in the copy does not change the contents of the original |List|. When {noref} is omitted or zero a contained |List| or @@ -2305,7 +2457,7 @@ diff_hlID({lnum}, {col}) *diff_hlID() 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 Number is empty when its value is zero. + items. A Number is empty when its value is zero. For a long |List| this is much faster then comparing the length with zero. @@ -2315,12 +2467,14 @@ escape({string}, {chars}) *escape()* :echo escape('c:\program files\vim', ' \') < results in: > c:\\program\ files\\vim - -< *eval()* +< Also see |shellescape()|. + + *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, Strings and composites of them. - Also works for |Funcref|s that refer to existing functions. + This works for Numbers, Floats, Strings and composites of + them. Also works for |Funcref|s that refer to existing + functions. eventhandler() *eventhandler()* Returns 1 when inside an event handler. That is that Vim got @@ -2336,10 +2490,10 @@ executable({expr}) *executable()* searchpath for programs. *PATHEXT* On MS-DOS and 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 ".exe;.com;.bat;.cmd" is + tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be + found. If $PATHEXT is not set then ".exe;.com;.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 + the name without an extension. When 'shell' looks like a Unix shell, then the name is also tried without adding an extension. On MS-DOS and MS-Windows it only checks if the file exists and @@ -2366,7 +2520,7 @@ exists({expr}) The result is a Number, w or user defined function (see |user-functions|). varname internal variable (see - |internal-variables|). Also works + |internal-variables|). Also works for |curly-braces-names|, |Dictionary| entries, |List| items, etc. Beware that this may cause functions to be @@ -2435,7 +2589,7 @@ expand({expr} [, {flag}]) *expand()* 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 + If the expansion fails, the result is an empty string. A name for a non-existing file is not included. When {expr} starts with '%', '#' or '<', the expansion is done @@ -2494,9 +2648,9 @@ expand({expr} [, {flag}]) *expand()* < 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 must be started. See |expr-env-expand|. + slow, because a shell must be started. 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 + names. When an environment variable cannot be expanded, it is left unchanged. Thus ":echo expand('$FOOBAR')" results in "$FOOBAR". @@ -2515,7 +2669,7 @@ extend({expr1}, {expr2} [, {expr3}]) * Examples: > :echo sort(extend(mylist, [7, 5])) :call extend(mylist, [2, 3], 1) -< Use |add()| to concatenate one item to a list. To concatenate +< 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] < @@ -2536,7 +2690,7 @@ extend({expr1}, {expr2} [, {expr3}]) * feedkeys({string} [, {mode}]) *feedkeys()* Characters in {string} are queued for processing as if they - come from a mapping or were typed by the user. They are added + come from a mapping or were typed by the user. They are added to the end of the typeahead buffer, thus if a mapping is still being executed these characters come after them. The function does not wait for processing of keys contained in @@ -2568,7 +2722,7 @@ filereadable({file}) *filereadable() 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 + exist, or is not writable, the result is 0. If {file} is a directory, and we can write to it, the result is 2. @@ -2621,13 +2775,47 @@ findfile({name}[, {path}[, {count}]]) < Searches from the directory of the current file upwards until it finds the file "tags.vim". +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. NaN results + in -0x80000000. + Examples: > + echo float2nr(3.95) +< 3 > + echo float2nr(-23.45) +< -23 > + echo float2nr(1.0e100) +< 2147483647 > + echo float2nr(-1.0e150) +< -2147483647 > + echo float2nr(1.0e-100) +< 0 + {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 + {only available when compiled with the |+float| feature} + fnameescape({string}) *fnameescape()* - Escape {string} for use as file name command argument. All + 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 "". For systems - where a backslash appears in a filename, it depends on the - value of 'isfname'. + 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'. Example: > :let fname = 'some str%nge|name' :exe "edit " . fnameescape(fname) @@ -2642,7 +2830,7 @@ fnamemodify({fname}, {mods}) *fnamemo :echo fnamemodify("main.c", ":p:h") < results in: > /home/mool/vim/vim/src -< Note: Environment variables and "~" don't work in {fname}, use +< Note: Environment variables don't work in {fname}, use |expand()| first then. foldclosed({lnum}) *foldclosed()* @@ -2657,7 +2845,7 @@ foldclosedend({lnum}) *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 + 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 @@ -2672,7 +2860,7 @@ foldtext() Returns a String, to be displ |v:foldstart|, |v:foldend| and |v:folddashes| variables. The returned string looks like this: > +-- 45 lines: abcdef -< The number of dashes depends on the foldlevel. The "45" is +< The number of 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' @@ -2690,7 +2878,7 @@ foldtextresult({lnum}) *foldtextresu {not available when compiled without the |+folding| feature} *foreground()* -foreground() Move the Vim window to the foreground. Useful when sent from +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 @@ -2793,7 +2981,7 @@ getchar([expr]) *getchar()* |v:mouse_lnum| and |v:mouse_win|. This example positions the mouse as it would normally happen: > let c = getchar() - if c == "\<LeftMouse>" && v:mouse_win > 0 + if c == "\<LeftMouse>" && v:mouse_win > 0 exe v:mouse_win . "wincmd w" exe v:mouse_lnum exe "normal " . v:mouse_col . "|" @@ -2831,7 +3019,7 @@ getcharmod() *getcharmod()* 64 mouse quadruple click 128 Macintosh only: command Only the modifiers that have not been included in the - character itself are obtained. Thus Shift-a results in "A" + character itself are obtained. Thus Shift-a results in "A" with no modifier. getcmdline() *getcmdline()* @@ -3058,7 +3246,7 @@ getwinposx() The result is a Number, whi *getwinposy()* getwinposy() The result is a Number, which is the Y coordinate in pixels of - the top of the GUI Vim window. The result will be -1 if the + the top of the GUI Vim window. The result will be -1 if the information is not available. getwinvar({winnr}, {varname}) *getwinvar()* @@ -3073,6 +3261,8 @@ glob({expr}) Expand the file wildcards i The result is a String. When there are several matches, they are separated by <NL> characters. + The 'wildignore' option applies: Names matching one of the + patterns in 'wildignore' will be skipped. If the expansion fails, the result is an empty string. A name for a non-existing file is not included. @@ -3081,7 +3271,7 @@ glob({expr}) Expand the file wildcards i :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. + 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. @@ -3119,7 +3309,7 @@ has_key({dict}, {key}) *has_key()* haslocaldir() *haslocaldir()* The result is a Number, which is 1 when the current - window has set a local path via |:lcd|, and 0 otherwise. + window has set a local path via |:lcd|, and 0 otherwise. hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* The result is a Number, which is 1 if there is a mapping that @@ -3142,7 +3332,7 @@ hasmapto({what} [, {mode} [, {abbr}]]) 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: > + to a function in a Vim script. Example: > :if !hasmapto('\ABCdoit') : map <Leader>d \ABCdoit :endif @@ -3154,7 +3344,7 @@ histadd({history}, {item}) *histadd() one of: *hist-names* "cmd" or ":" command line history "search" or "/" search pattern history - "expr" or "=" typed expression history + "expr" or "=" typed expression history "input" or "@" input line history If {item} does already exist in the history, it will be shifted to become the newest entry. @@ -3171,7 +3361,7 @@ histdel({history} [, {item}]) *histde for the possible values of {history}. If the parameter {item} is given as String, this is seen - as regular expression. All entries matching that expression + as 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} is a Number, it will be interpreted as index, see @@ -3235,7 +3425,7 @@ hlID({name}) The result is a Number, whi 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 + group. For example, to get the background color of the "Comment" group: > :echo synIDattr(synIDtrans(hlID("Comment")), "bg") < *highlightID()* @@ -3292,7 +3482,7 @@ input({prompt} [, {text} [, {completion} 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 + editing commands and mappings. There is a separate history for lines typed for input(). Example: > :if input("Coffee or beer? ") == "beer" @@ -3305,9 +3495,9 @@ input({prompt} [, {text} [, {completion} < 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 + 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 + "-complete=" argument. Refer to |:command-completion| for more information. Example: > let fname = input("File: ", "", "file") < @@ -3348,12 +3538,12 @@ inputlist({textlist}) *inputlist()* 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. For the first string 0 is returned. When clicking + mouse. 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 then 'lines' entries, otherwise - it won't work. It's a good idea to put the entry number at + 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', @@ -3387,7 +3577,7 @@ inputsecret({prompt} [, {text}]) *inpu insert({list}, {item} [, {idx}]) *insert()* Insert {item} at the start of |List| {list}. If {idx} is specified insert {item} before the item with index - {idx}. If {idx} is zero it goes before the first item, just + {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|. Examples: > @@ -3483,7 +3673,7 @@ libcall({libname}, {funcname}, {argument 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, + 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 @@ -3494,7 +3684,6 @@ libcall({libname}, {funcname}, {argument feature is present} Examples: > :echo libcall("libc.so", "getenv", "HOME") - :echo libcallnr("/usr/lib/libc.so", "getpid", "") < *libcallnr()* libcallnr({libname}, {funcname}, {argument}) @@ -3502,7 +3691,8 @@ libcallnr({libname}, {funcname}, {argume int instead of a string. {only in Win32 on some Unix versions, when the |+libcall| feature is present} - Example (not very useful...): > + Examples: > + :echo libcallnr("/usr/lib/libc.so", "getpid", "") :call libcallnr("libc.so", "printf", "Hello World!\n") :call libcallnr("libc.so", "sleep", 10) < @@ -3530,7 +3720,7 @@ line({expr}) The result is a Number, whi < *last-position-jump* This autocommand jumps to the last known position in a file just after opening it, if the '" mark is set: > - :au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | exe "normal g'\"" | endif + :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g'\"" | endif line2byte({lnum}) *line2byte()* Return the byte count from the start of the buffer for line @@ -3558,6 +3748,16 @@ localtime() *localtime()* 1970. See also |strftime()| and |getftime()|. +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 + {only available when compiled with the |+float| feature} + map({expr}, {string}) *map()* {expr} must be a |List| or a |Dictionary|. Replace each item in {expr} with the result of evaluating @@ -3615,7 +3815,7 @@ mapcheck({name}[, {mode} [, {abbr}]]) A match happens with a mapping that starts with {name} and with a mapping which is equal to the start of {name}. - matches mapping "a" "ab" "abc" ~ + matches mapping "a" "ab" "abc" ~ mapcheck("a") yes yes yes mapcheck("abc") yes yes yes mapcheck("ax") yes no no @@ -3642,7 +3842,7 @@ match({expr}, {pat}[, {start}[, {count}] When {expr} is a |List| then this returns the index of the first item where {pat} matches. Each item is used as a String, |Lists| and |Dictionaries| are used as echoed. - Otherwise, {expr} is used as a String. The result is a + Otherwise, {expr} is used as a String. The result is a Number, which gives the index (byte offset) in {expr} where {pat} matches. A match at the first character or |List| item returns zero. @@ -3652,7 +3852,7 @@ match({expr}, {pat}[, {start}[, {count}] :echo match([1, 'x'], '\a') " results in 1 < See |string-match| for how {pat} is used. *strpbrk()* - Vim doesn't have a strpbrk() function. But you can do: > + Vim doesn't have a strpbrk() function. But you can do: > :let sepidx = match(line, '[.,;: \t]') < *strcasestr()* Vim doesn't have a strcasestr() function. But you can add @@ -3689,7 +3889,7 @@ match({expr}, {pat}[, {start}[, {count}] See |pattern| for the patterns that are accepted. The 'ignorecase' option is used to set the ignore-caseness of - the pattern. 'smartcase' is NOT used. The matching is always + the pattern. 'smartcase' is NOT used. The matching is always done like 'magic' is set and 'cpoptions' is empty. *matchadd()* *E798* *E799* *E801* @@ -3700,7 +3900,7 @@ matchadd({group}, {pattern}[, {priority} match using |matchdelete()|. The optional {priority} argument assigns a priority to the - match. A match with a high priority will have its + match. A match with a high priority will have its highlighting overrule that of a match with a lower priority. A priority is specified as an integer (negative numbers are no exception). If the {priority} argument is not specified, the @@ -3728,7 +3928,7 @@ matchadd({group}, {pattern}[, {priority} :call matchdelete(m) < A list of matches defined by |matchadd()| and |:match| are - available from |getmatches()|. All matches can be deleted in + available from |getmatches()|. All matches can be deleted in one operation by |clearmatches()|. matcharg({nr}) *matcharg()* @@ -3745,7 +3945,7 @@ matcharg({nr}) *matcharg()* matchdelete({id}) *matchdelete()* *E802* *E803* Deletes a match with ID {id} previously defined by |matchadd()| - or one of the |:match| commands. Returns 0 if succesfull, + or one of the |:match| commands. Returns 0 if successful, otherwise -1. See example for |matchadd()|. All matches can be deleted in one operation by |clearmatches()|. @@ -3779,7 +3979,7 @@ matchlist({expr}, {pat}[, {start}[, {cou When there is no match an empty list is returned. matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()* - Same as match(), but return the matched string. Example: > + Same as |match()|, but return the matched string. Example: > :echo matchstr("testing", "ing") < results in "ing". When there is no match "" is returned. @@ -3810,15 +4010,21 @@ mkdir({name} [, {path} [, {prot}]]) necessary. Otherwise it must be "". If {prot} is given it is used to set the protection bits of the new directory. The default is 0755 (rwxr-xr-x: r/w for - the user readable for others). Use 0700 to make it unreadable + the user readable for others). Use 0700 to make it unreadable for others. This function is not available in the |sandbox|. Not available on all systems. To check use: > :if exists("*mkdir") < *mode()* -mode() Return a string that indicates the current mode: +mode([expr]) Return a string that indicates the current mode. + If [expr] is supplied and it evaluates to a non-zero number or + a non-empty string, then the full mode is returned, otherwise + only the first letter is returned. Note that " " and "0" are + also non-empty strings. + n Normal + no Operator-pending v Visual by character V Visual by line CTRL-V Visual blockwise @@ -3826,11 +4032,19 @@ mode() Return a string that indicates t S Select by line CTRL-S Select blockwise i Insert - R Replace + R Replace |R| + Rv Virtual Replace |gR| c Command-line + cv Vim Ex mode |gQ| + ce Normal Ex mode |Q| r Hit-enter prompt - This is useful in the 'statusline' option. In most other - places it always returns "c" or "n". + rm The -- more -- prompt + r? A |:confirm| query of some sort + ! Shell or external command is executing + This is useful in the 'statusline' option or when used + with |remote_expr()| In most other places it always returns + "c" or "n". + Also see |visualmode()|. nextnonblank({lnum}) *nextnonblank()* Return the line number of the first line at or below {lnum} @@ -3854,7 +4068,8 @@ nr2char({expr}) *nr2char()* *getpid()* getpid() Return a Number which is the process ID of the Vim process. - On Unix this is a unique number. On MS-DOS it's always zero. + On Unix and MS-Windows this is a unique number, until Vim + exits. On MS-DOS it's always zero. *getpos()* getpos({expr}) Get the position for {expr}. For possible values of {expr} @@ -3884,6 +4099,18 @@ pathshorten({expr}) *pathshorten()* < ~/.v/a/myfile.vim ~ It doesn't matter if the path exists or not. +pow({x}, {y}) *pow()* + Return the power of {x} to the exponent {y} as a |Float|. + {x} and {y} must evaluate to a |Float| or a |Number|. + Examples: > + :echo pow(3, 3) +< 27.0 > + :echo pow(2, 16) +< 65536.0 > + :echo pow(32, 0.20) +< 2.0 + {only available when compiled with the |+float| feature} + prevnonblank({lnum}) *prevnonblank()* Return the line number of the first line at or above {lnum} that is not blank. Example: > @@ -3903,15 +4130,20 @@ printf({fmt}, {expr1} ...) *printf()* Often used items are: %s string %6s string right-aligned in 6 bytes - %.9s string truncated to 9 bytes - %c single byte - %d decimal number - %5d decimal number padded with spaces to 5 characters - %x hex number - %04x hex number padded with zeros to at least 4 characters - %X hex number using upper case letters - %o octal number - %% the % character itself + %.9s string truncated to 9 bytes + %c single byte + %d decimal number + %5d decimal number padded with spaces to 5 characters + %x hex number + %04x hex number padded with zeros to at least 4 characters + %X hex number using upper case letters + %o octal number + %f floating point number in the form 123.456 + %e floating point number in the form 1.234e3 + %E floating point number in the form 1.234E3 + %g floating point number, as %f or %e depending on value + %G floating point number, as %f or %E depending on value + %% the % character itself Conversion specifications start with '%' and end with the conversion type. All other characters are copied unchanged to @@ -3952,7 +4184,7 @@ printf({fmt}, {expr1} ...) *printf()* number produced by a signed conversion (d). + A sign must always be placed before a number - produced by a signed conversion. A + overrides + produced by a signed conversion. A + overrides a space if both are used. field-width @@ -3969,6 +4201,8 @@ printf({fmt}, {expr1} ...) *printf()* This gives the minimum number of digits to appear for d, o, x, and X conversions, or the maximum number of bytes to be printed from a string for s conversions. + For floating point it is the number of digits after + the decimal point. type A character that specifies the type of conversion to @@ -3976,7 +4210,7 @@ printf({fmt}, {expr1} ...) *printf()* A field width or precision, or both, may be indicated by an asterisk '*' instead of a digit string. In this case, a - Number argument supplies the field width or precision. A + Number argument supplies the field width or precision. A negative field width is treated as a left adjustment flag followed by a positive field width; a negative precision is treated as though it were missing. Example: > @@ -3986,7 +4220,8 @@ printf({fmt}, {expr1} ...) *printf()* The conversion specifiers and their meanings are: - doxX The Number argument is converted to signed decimal + *printf-d* *printf-o* *printf-x* *printf-X* + doxX The Number argument is converted to signed decimal (d), unsigned octal (o), or unsigned hexadecimal (x and X) notation. The letters "abcdef" are used for x conversions; the letters "ABCDEF" are used for X @@ -4000,18 +4235,50 @@ printf({fmt}, {expr1} ...) *printf()* a conversion is wider than the field width, the field is expanded to contain the conversion result. + *printf-c* c The Number argument is converted to a byte, and the resulting character is written. + *printf-s* s The text of the String argument is used. If a precision is specified, no more bytes than the number specified are used. + *printf-f* *E807* + f The Float argument is converted into a string of the + form 123.456. The precision specifies the number of + digits after the decimal point. When the precision is + zero the decimal point is omitted. When the precision + is not specified 6 is used. A really big number + (out of range or dividing by zero) results in "inf". + "0.0 / 0.0" results in "nan". + Example: > + echo printf("%.2f", 12.115) +< 12.12 + Note that roundoff depends on the system libraries. + Use |round()| when in doubt. + + *printf-e* *printf-E* + e E The Float argument is converted into a string of the + form 1.234e+03 or 1.234E+03 when using 'E'. The + precision specifies the number of digits after the + decimal point, like with 'f'. + + *printf-g* *printf-G* + g G The Float argument is converted like with 'f' if the + value is between 0.001 (inclusive) and 10000000.0 + (exclusive). Otherwise 'e' is used for 'g' and 'E' + for 'G'. When no precision is specified superfluous + zeroes and '+' signs are removed, except for the zero + immediately after the decimal point. Thus 10000000.0 + results in 1.0e7. + + *printf-%* % A '%' is written. No argument is converted. The complete conversion specification is "%%". Each argument can be Number or String and is converted - automatically to fit the conversion specifier. Any other + automatically to fit the conversion specifier. Any other argument type results in an error message. *E766* *E767* @@ -4105,7 +4372,7 @@ reltimestr({time}) *reltimestr()* *remote_expr()* *E449* remote_expr({server}, {string} [, {idvar}]) - Send the {string} to {server}. The string is sent as an + Send the {string} to {server}. The string is sent as an expression and the result is returned after evaluation. The result must be a String or a |List|. A |List| is turned into a String by joining the items with a line break in @@ -4140,7 +4407,7 @@ remote_foreground({server}) *remote_f remote_peek({serverid} [, {retvar}]) *remote_peek()* Returns a positive number if there are available strings from {serverid}. Copies any reply string into the variable - {retvar} if specified. {retvar} must be a string with the + {retvar} if specified. {retvar} must be a string with the name of a variable. Returns zero if none are available. Returns -1 if something is wrong. @@ -4162,7 +4429,7 @@ remote_read({serverid}) *remote_read( < *remote_send()* *E241* remote_send({server}, {string} [, {idvar}]) - Send the {string} to {server}. The string is sent as input + Send the {string} to {server}. The string is sent as input keys and the function returns immediately. At the Vim server the keys are not mapped |:map|. If {idvar} is present, it is taken as the name of a variable @@ -4213,7 +4480,7 @@ repeat({expr}, {count}) *repeat()* :let separator = repeat('-', 80) < When {count} is zero or negative the result is empty. When {expr} is a |List| the result is {expr} concatenated - {count} times. Example: > + {count} times. Example: > :let longlist = repeat(['a', 'b'], 3) < Results in ['a', 'b', 'a', 'b', 'a', 'b']. @@ -4232,18 +4499,33 @@ resolve({filename}) *resolve()* *E65 path name) and also keeps a trailing path separator. *reverse()* -reverse({list}) Reverse the order of items in {list} in-place. Returns +reverse({list}) Reverse the order of items in {list} in-place. Returns {list}. If you want a list to remain unmodified make a copy first: > :let revlist = reverse(copy(mylist)) +round({expr}) *round()* + Round off {expr} to a the nearest integral value and return it + as a |Float|. If {expr} lies halfway between two integral + values, then use the larger one (away from zero). + {expr} must evaluate to a |Float| or a |Number|. + Examples: > + echo round(0.456) +< 0.0 > + echo round(4.5) +< 5.0 > + echo round(-4.5) +< -5.0 + {only available when compiled with the |+float| feature} + + search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()* Search for regexp pattern {pattern}. The search starts at the cursor position (you can use |cursor()| to set it). {flags} is a String, which can contain these character flags: 'b' search backward instead of forward - 'c' accept a match at the cursor position + 'c' accept a match at the cursor position 'e' move to the End of the match 'n' do Not move the cursor 'p' return number of matching sub-pattern (see below) @@ -4268,7 +4550,7 @@ search({pattern} [, {flags} [, {stopline A zero value is equal to not giving the argument. When the {timeout} argument is given the search stops when - more than this many milli seconds have passed. Thus when + more than this many milli seconds have passed. Thus when {timeout} is 500 the search stops after half a second. The value must not be negative. A zero value is like not giving the argument. @@ -4295,7 +4577,7 @@ search({pattern} [, {flags} [, {stopline : normal G$ : let flags = "w" : while search("foo", flags) > 0 - : s/foo/bar/g + : s/foo/bar/g : let flags = "W" : endwhile : update " write the file if modified @@ -4358,9 +4640,11 @@ searchpair({start}, {middle}, {end} [, { {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with |search()|. Additionally: 'r' Repeat until no more matches found; will find the - outer pair - 'm' return number of Matches instead of line number with + outer pair. Implies the 'W' flag. + 'm' Return number of matches instead of line number with the match; will be > 1 when 'r' is used. + Note: it's nearly always a good idea to use the 'W' flag, to + avoid wrapping around the end of the file. When a match for {start}, {middle} or {end} is found, the {skip} expression is evaluated with the cursor positioned on @@ -4386,7 +4670,7 @@ searchpair({start}, {middle}, {end} [, { < When starting at the "if 2", with the cursor on the "i", and searching forwards, the "endif 2" is found. When starting on the character just before the "if 2", the "endif 1" will be - found. That's because the "if 2" will be found first, and + found. That's because the "if 2" will be found first, and then this is considered to be a nested if/endif from "if 2" to "endif 2". When searching backwards and {end} is more than one character, @@ -4479,7 +4763,7 @@ setbufvar({expr}, {varname}, {val}) *s setcmdpos({pos}) *setcmdpos()* Set the cursor position in the command line to byte position - {pos}. The first position is 1. + {pos}. The first position is 1. Use |getcmdpos()| to obtain the current position. Only works while editing the command line, thus you must use |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For @@ -4492,15 +4776,15 @@ setcmdpos({pos}) *setcmdpos()* Returns 0 when successful, 1 when not editing the command line. -setline({lnum}, {line}) *setline()* - Set line {lnum} of the current buffer to {line}. +setline({lnum}, {text}) *setline()* + Set line {lnum} of the current buffer to {text}. {lnum} is used like with |getline()|. - When {lnum} is just below the last line the {line} will be + When {lnum} is just below the last line the {text} will be added as a new line. If this succeeds, 0 is returned. If this fails (most likely because {lnum} is invalid) 1 is returned. Example: > :call setline(5, strftime("%c")) -< When {line} is a |List| then line {lnum} and following lines +< When {text} is a |List| then line {lnum} and following lines will be set to the items in the list. Example: > :call setline(5, ['aaa', 'bbb', 'ccc']) < This is equivalent to: > @@ -4519,7 +4803,7 @@ setloclist({nr}, {list} [, {action}]) setmatches({list}) *setmatches()* Restores a list of matches saved by |getmatches()|. Returns 0 - if succesfull, otherwise -1. All current matches are cleared + if successful, otherwise -1. All current matches are cleared before the list is restored. See example for |getmatches()|. *setpos()* @@ -4531,7 +4815,7 @@ setpos({expr}, {list}) {list} must be a |List| with four numbers: [bufnum, lnum, col, off] - "bufnum" is the buffer number. Zero can be used for the + "bufnum" is the buffer number. Zero can be used for the current buffer. Setting the cursor is only possible for the current buffer. To set a mark in another buffer you can use the |bufnr()| function to turn a file name into a buffer @@ -4562,9 +4846,9 @@ setqflist({list} [, {action}]) *setqf item can contain the following entries: bufnr buffer number; must be the number of a valid - buffer + buffer filename name of a file; only used when "bufnr" is not - present or it is invalid. + present or it is invalid. lnum line number in the file pattern search pattern used to locate the error col column number @@ -4688,6 +4972,17 @@ simplify({filename}) *simplify()* links before simplifying the path name, use |resolve()|. +sin({expr}) *sin()* + Return the sine of {expr}, measured in radians, as a |Float|. + {expr} must evaluate to a |Float| or a |Number|. + Examples: > + :echo sin(100) +< -0.506366 > + :echo sin(-4.01) +< 0.763301 + {only available when compiled with the |+float| feature} + + sort({list} [, {func}]) *sort()* *E702* Sort the items in {list} in-place. Returns {list}. If you want a list to remain unmodified make a copy first: > @@ -4710,7 +5005,7 @@ sort({list} [, {func}]) *sort()* *E7 *soundfold()* soundfold({word}) Return the sound-folded equivalent of {word}. Uses the first - language in 'spellang' for the current window that supports + language in 'spelllang' for the current window that supports soundfolding. 'spell' must be set. When no sound folding is possible the {word} is returned unmodified. This can be used for making spelling suggestions. Note that @@ -4788,6 +5083,34 @@ split({expr} [, {pattern} [, {keepempty} < The opposite function is |join()|. +sqrt({expr}) *sqrt()* + Return the non-negative square root of Float {expr} as a + |Float|. + {expr} must evaluate to a |Float| or a |Number|. When {expr} + is negative the result is NaN (Not a Number). + Examples: > + :echo sqrt(100) +< 10.0 > + :echo sqrt(-4.01) +< nan + {only available when compiled with the |+float| feature} + + +str2float( {expr}) *str2float()* + Convert String {expr} to a Float. This mostly works the same + as when using a floating point number in an expression, see + |floating-point-format|. But it's a bit more permissive. + E.g., "1e40" is accepted, while in an expression you need to + write "1.0e40". + Text after the number is silently ignored. + The decimal point is always '.', no matter what the locale is + set to. A comma ends the number: "12,345.67" is converted to + 12.0. You can strip out thousands separators with + |substitute()|: > + let f = str2float(substitute(text, ',', '', 'g')) +< {only available when compiled with the |+float| feature} + + str2nr( {expr} [, {base}]) *str2nr()* Convert string {expr} to a number. {base} is the conversion base, it can be 8, 10 or 16. @@ -4839,11 +5162,12 @@ stridx({haystack}, {needle} [, {start}]) *string()* string({expr}) Return {expr} converted to a String. If {expr} is a Number, - String or a composition of them, then the result can be parsed - back with |eval()|. + Float, String or a composition of them, then the result can be + parsed back with |eval()|. {expr} type result ~ String 'string' Number 123 + Float 123.123456 or 1.123456e8 Funcref function('name') List [item, item] Dictionary {key: value, key: value} @@ -4872,7 +5196,7 @@ strpart({src}, {start}[, {len}]) *strp strpart("abcdefg", 3, 2) == "de" strpart("abcdefg", -2, 4) == "ab" strpart("abcdefg", 5, 4) == "fg" - strpart("abcdefg", 3) == "defg" + strpart("abcdefg", 3) == "defg" < Note: To get the first character, {start} must be 0. For example, to get three bytes under and after the cursor: > strpart(getline("."), col(".") - 1, 3) @@ -4922,7 +5246,7 @@ substitute({expr}, {pat}, {sub}, {flags} See |string-match| for how {pat} is used. And a "~" in {sub} is not replaced with the previous {sub}. Note that some codes in {sub} have a special meaning - |sub-replace-special|. For example, to replace something with + |sub-replace-special|. For example, to replace something with "\n" (two characters), use "\\\\n" or '\\n'. When {pat} does not match in {expr}, {expr} is returned unmodified. @@ -4944,7 +5268,7 @@ synID({lnum}, {col}, {trans}) *synID( line. 'synmaxcol' applies, in a longer line zero is returned. When {trans} is non-zero, transparent items are reduced to the - item that they reveal. This is useful when wanting to know + item that they reveal. This is useful when wanting to know the effective color. When {trans} is zero, the transparent item is returned. This is useful when wanting to know which syntax item is effective (e.g. inside parens). @@ -4959,7 +5283,7 @@ synIDattr({synID}, {what} [, {mode}]) syntax ID {synID}. This can be used to obtain information about a syntax item. {mode} can be "gui", "cterm" or "term", to get the attributes - for that mode. When {mode} is omitted, or an invalid value is + for that mode. When {mode} is omitted, or an invalid value is used, the attributes for the currently active highlighting are used (GUI, cterm or term). Use synIDtrans() to follow linked highlight groups. @@ -5118,7 +5442,7 @@ taglist({expr}) *taglist()* tempname() *tempname()* *temp-file-name* The result is a String, which is the name of a file that - doesn't exist. It can be used for a temporary file. The name + doesn't exist. It can be used for a temporary file. The name is different for at least 26 consecutive calls. Example: > :let tmpfile = tempname() :exe "redir > " . tmpfile @@ -5153,6 +5477,19 @@ tr({src}, {fromstr}, {tostr}) *tr()* echo tr("<blob>", "<>", "{}") < returns "{blob}" +trunc({expr}) *trunc()* + Return the largest integral value with magnituted less than or + equal to {expr} as a |Float| (truncate towards zero). + {expr} must evaluate to a |Float| or a |Number|. + Examples: > + echo trunc(1.456) +< 1.0 > + echo trunc(-5.456) +< -5.0 > + echo trunc(4.0) +< 4.0 + {only available when compiled with the |+float| feature} + *type()* type({expr}) The result is a Number, depending on the type of {expr}: Number: 0 @@ -5160,15 +5497,17 @@ type({expr}) The result is a Number, dep Funcref: 2 List: 3 Dictionary: 4 + Float: 5 To avoid the magic numbers it should be used this way: > :if type(myvar) == type(0) :if type(myvar) == type("") :if type(myvar) == type(function("tr")) :if type(myvar) == type([]) :if type(myvar) == type({}) + :if type(myvar) == type(0.0) values({dict}) *values()* - Return a |List| with all the values of {dict}. The |List| is + Return a |List| with all the values of {dict}. The |List| is in arbitrary order. @@ -5199,8 +5538,8 @@ virtcol({expr}) *virtcol()* Examples: > virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5 virtcol("$") with text "foo^Lbar", returns 9 - virtcol("'t") with text " there", with 't at 'h', returns 6 -< The first column is 1. 0 is returned for an error. + virtcol("'t") with text " there", with 't at 'h', returns 6 +< The first column is 1. 0 is returned for an error. A more advanced example that echoes the maximum length of all lines: > echo max(map(range(1, line('$')), "virtcol([v:val, '$'])")) @@ -5218,10 +5557,12 @@ visualmode([expr]) *visualmode()* < This enters the same Visual mode as before. It is also useful in scripts if you wish to act differently depending on the Visual mode that was used. - - If an expression is supplied that results in a non-zero number - or a non-empty string, then the Visual mode will be cleared - and the old value is returned. Note that " " and "0" are also + If Visual mode is active, use |mode()| to get the Visual mode + (e.g., in a |:vmap|). + + If [expr] is supplied and it evaluates to a non-zero number or + a non-empty string, then the Visual mode will be cleared and + the old value is returned. Note that " " and "0" are also non-empty strings, thus cause the mode to be cleared. *winbufnr()* @@ -5247,7 +5588,7 @@ winheight({nr}) *winheight()* < *winline()* winline() The result is a Number, which is the screen line of the cursor - in the window. This is counting screen lines from the top of + in the window. This is counting screen lines from the top of the window. The first line is one. If the cursor was moved the view on the file will be updated first, this may cause a scroll. @@ -5394,6 +5735,7 @@ filterpipe When 'shelltemp' is off pipe read/write/filter commands find_in_path Compiled with support for include file searches |+find_in_path|. +float Compiled with support for |Float|. fname_case Case in file names matters (for Amiga, MS-DOS, and Windows this is not present). folding Compiled with |folding| support. @@ -5404,6 +5746,7 @@ gui Compiled with GUI enabled. gui_athena Compiled with Athena GUI. gui_gtk Compiled with GTK+ GUI (any version). gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined). +gui_gnome Compiled with Gnome support (gui_gtk is also defined). gui_mac Compiled with Macintosh GUI. gui_motif Compiled with Motif GUI. gui_photon Compiled with Photon GUI. @@ -5435,6 +5778,7 @@ mouse_dec Compiled with support for Dec mouse_gpm Compiled with support for gpm (Linux console mouse) mouse_netterm Compiled with support for netterm mouse. mouse_pterm Compiled with support for qnx pterm mouse. +mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse) mouse_xterm Compiled with support for xterm mouse. multi_byte Compiled with support for editing Korean et al. multi_byte_ime Compiled with support for IME input method. @@ -5587,9 +5931,9 @@ See |:verbose-cmd| for more information. {name} can also be a |Dictionary| entry that is a |Funcref|: > :function dict.init(arg) -< "dict" must be an existing dictionary. The entry +< "dict" must be an existing dictionary. The entry "init" is added if it didn't exist yet. Otherwise [!] - is required to overwrite an existing function. The + is required to overwrite an existing function. The result is a |Funcref| to a numbered function. The function can only be used with a |Funcref| and will be deleted if there are no more references to it. @@ -5613,12 +5957,15 @@ See |:verbose-cmd| for more information. abort as soon as an error is detected. When the [dict] argument is added, the function must - be invoked through an entry in a |Dictionary|. The + be invoked through an entry in a |Dictionary|. The local variable "self" will then be set to the dictionary. See |Dictionary-function|. + *function-search-undo* The last used search pattern and the redo command "." - will not be changed by the function. + will not be changed by the function. This also + implies that the effect of |:nohlsearch| is undone + when the function returns. *:endf* *:endfunction* *E126* *E193* :endf[unction] The end of a function definition. Must be on a line @@ -5629,7 +5976,7 @@ See |:verbose-cmd| for more information. {name} can also be a |Dictionary| entry that is a |Funcref|: > :delfunc dict.init -< This will remove the "init" entry from "dict". The +< This will remove the "init" entry from "dict". The function is deleted if there are no more references to it. *:retu* *:return* *E133* @@ -5649,7 +5996,7 @@ See |:verbose-cmd| for more information. returns at the outermost ":endtry". *function-argument* *a:var* -An argument can be defined by giving its name. In the function this can then +An argument can be defined by giving its name. In the function this can then be used as "a:name" ("a:" for argument). *a:0* *a:1* *a:000* *E740* *...* Up to 20 arguments can be given, separated by commas. After the named @@ -5721,7 +6068,7 @@ This function can then be called with: > itself, the function is executed for each line in the range, with the cursor in the first column of that line. The cursor is left at the last line (possibly moved by the last function - call). The arguments are re-evaluated for each line. Thus + call). The arguments are re-evaluated for each line. Thus this works: *function-range-example* > :function Mynumber(arg) @@ -5766,7 +6113,7 @@ This is introduced in the user manual, s The autocommand is useful if you have a plugin that is a long Vim script file. You can define the autocommand and quickly quit the script with |:finish|. -That makes Vim startup faster. The autocommand should then load the same file +That makes Vim startup faster. The autocommand should then load the same file again, setting a variable to skip the |:finish| command. Use the FuncUndefined autocommand event with a pattern that matches the @@ -5827,7 +6174,7 @@ function, the script will be sourced eve And you will get an error message every time. Also note that if you have two script files, and one calls a function in the -other and vise versa, before the used function is defined, it won't work. +other and vice versa, before the used function is defined, it won't work. Avoid using the autoload functionality at the toplevel. Hint: If you distribute a bunch of scripts you can pack them together with the @@ -5848,7 +6195,7 @@ name. So in the above example, if the v "adjective" was set to "quiet", then it would be to "my_quiet_variable". One application for this is to create a set of variables governed by an option -value. For example, the statement > +value. For example, the statement > echo my_{&background}_message would output the contents of "my_dark_message" or "my_light_message" depending @@ -5888,8 +6235,11 @@ 7. Commands *expression-commands* {expr1}. {var-name} must refer to a list and {idx} must be a valid index in that list. For nested list the index can be repeated. - This cannot be used to add an item to a list. - + This cannot be used to add an item to a |List|. + This cannot be used to set a byte in a String. You + can do that like this: > + :let var = var[0:2] . 'X' . var[4:] +< *E711* *E719* :let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710* Set a sequence of items in a |List| to the result of @@ -5931,7 +6281,7 @@ 7. Commands *expression-commands* that would match everywhere. :let @{reg-name} .= {expr1} - Append {expr1} to register {reg-name}. If the + Append {expr1} to register {reg-name}. If the register was empty it's like setting it to {expr1}. :let &{option-name} = {expr1} *:let-option* *:let-&* @@ -6006,7 +6356,7 @@ 7. Commands *expression-commands* Like above, but append/add/subtract the value for each |List| item. *E106* -:let {var-name} .. List the value of variable {var-name}. Multiple +:let {var-name} .. List the value of variable {var-name}. Multiple variable names may be given. Special names recognized here: *E738* g: global variables @@ -6150,7 +6500,7 @@ 7. Commands *expression-commands* :for item in copy(mylist) < When not making a copy, Vim stores a reference to the next item in the list, before executing the commands - with the current item. Thus the current item can be + with the current item. Thus the current item can be removed without effect. Removing any later item means it will not be found. Thus the following example works (an inefficient way to make a list empty): > @@ -6356,7 +6706,7 @@ 7. Commands *expression-commands* message in the |message-history|. When used in a script or function the line number will be added. Spaces are placed between the arguments as with the - :echo command. When used inside a try conditional, + :echo command. When used inside a try conditional, the message is raised as an error exception instead (see |try-echoerr|). Example: > @@ -6368,7 +6718,7 @@ 7. Commands *expression-commands* *:exe* *:execute* :exe[cute] {expr1} .. Executes the string that results from the evaluation of {expr1} as an Ex command. Multiple arguments are - concatenated, with a space in between. {expr1} is + concatenated, with a space in between. {expr1} is used as the processed command, command line editing keys are not recognized. Cannot be followed by a comment. @@ -6386,6 +6736,11 @@ 7. Commands *expression-commands* :execute "normal ixxx\<Esc>" < This has an <Esc> character, see |expr-string|. + Be careful to correctly escape special characters in + file names. The |fnameescape()| function can be used + for this. Example: > + :execute "e " . fnameescape(filename) +< Note: The executed string may be any command-line, but you cannot start or end a "while", "for" or "if" command. Thus this is illegal: > @@ -6428,21 +6783,21 @@ which must not be followed by any catch clauses and the finally clause is called a try block. > :try - : ... - : ... TRY BLOCK - : ... + : ... + : ... TRY BLOCK + : ... :catch /{pattern}/ - : ... - : ... CATCH CLAUSE - : ... + : ... + : ... CATCH CLAUSE + : ... :catch /{pattern}/ - : ... - : ... CATCH CLAUSE - : ... + : ... + : ... CATCH CLAUSE + : ... :finally - : ... - : ... FINALLY CLAUSE - : ... + : ... + : ... FINALLY CLAUSE + : ... :endtry The try conditional allows to watch code for exceptions and to take the @@ -6467,14 +6822,14 @@ the finally clause. It is resumed at th the ":endtry" are not executed and the exception might be caught elsewhere, see |try-nesting|. When during execution of a catch clause another exception is thrown, the -remaining lines in that catch clause are not executed. The new exception is +remaining lines in that catch clause are not executed. The new exception is not matched against the patterns in any of the ":catch" commands of the same try conditional and none of its catch clauses is taken. If there is, however, a finally clause, it is executed, and the exception pends during its execution. The commands following the ":endtry" are not executed. The new exception might, however, be caught elsewhere, see |try-nesting|. When during execution of the finally clause (if present) an exception is -thrown, the remaining lines in the finally clause are skipped. If the finally +thrown, the remaining lines in the finally clause are skipped. If the finally clause has been taken because of an exception from the try block or one of the catch clauses, the original (pending) exception is discarded. The commands following the ":endtry" are not executed, and the exception from the finally @@ -6508,7 +6863,7 @@ catch an exception thrown in its try blo of its catch clauses or its finally clause, the outer try conditional is checked according to the rules above. If the inner try conditional is in the try block of the outer try conditional, its catch clauses are checked, but -otherwise only the finally clause is executed. It does not matter for +otherwise only the finally clause is executed. It does not matter for nesting, whether the inner try conditional is directly contained in the outer one, or whether the outer one sources a script or calls a function containing the inner try conditional. @@ -6571,7 +6926,7 @@ executed. > however displays "in Bar" and throws 4711. Any other command that takes an expression as argument might also be -abandoned by an (uncaught) exception during the expression evaluation. The +abandoned by an (uncaught) exception during the expression evaluation. The exception is then propagated to the caller of the command. Example: > @@ -6748,20 +7103,20 @@ the original error exception value, you This code displays - Vim(echoerr):Vim:E492: Not an editor command: asdf ~ + Vim(echoerr):Vim:E492: Not an editor command: asdf ~ CLEANUP CODE *try-finally* Scripts often change global settings and restore them at their end. If the user however interrupts the script by pressing CTRL-C, the settings remain in -an inconsistent state. The same may happen to you in the development phase of +an inconsistent state. The same may happen to you in the development phase of a script when an error occurs or you explicitly throw an exception without catching it. You can solve these problems by using a try conditional with a finally clause for restoring the settings. Its execution is guaranteed on normal control flow, on error, on an explicit ":throw", and on interrupt. (Note that errors and interrupts from inside the try conditional are converted -to exceptions. When not caught, they terminate the script after the finally +to exceptions. When not caught, they terminate the script after the finally clause has been executed.) Example: > @@ -6819,7 +7174,7 @@ This displays "first", "cleanup", "secon :echo Foo() "returned by Foo" This displays "cleanup" and "4711 returned by Foo". You don't need to add an -extra ":return" in the finally clause. (Above all, this would override the +extra ":return" in the finally clause. (Above all, this would override the return value.) *except-from-finally* @@ -6863,7 +7218,7 @@ or > Vim:{errmsg} {cmdname} is the name of the command that failed; the second form is used when -the command name is not known. {errmsg} is the error message usually produced +the command name is not known. {errmsg} is the error message usually produced when the error occurs outside try conditionals. It always begins with a capital "E", followed by a two or three-digit error number, a colon, and a space. @@ -6968,7 +7323,7 @@ This works also when a try conditional i CATCHING INTERRUPTS *catch-interrupt* When there are active try conditionals, an interrupt (CTRL-C) is converted to -the exception "Vim:Interrupt". You can catch it like every exception. The +the exception "Vim:Interrupt". You can catch it like every exception. The script is not terminated, then. Example: > @@ -7002,7 +7357,7 @@ script is not terminated, then. :endwhile You can interrupt a task here by pressing CTRL-C; the script then asks for -a new command. If you press CTRL-C at the prompt, the script is terminated. +a new command. If you press CTRL-C at the prompt, the script is terminated. For testing what happens when CTRL-C would be pressed on a specific line in your script, use the debug mode and execute the |>quit| or |>interrupt| @@ -7159,7 +7514,7 @@ For some commands, the normal action can autocommands. Exceptions from that sequence will be catchable by the caller of the command. Example: For the ":write" command, the caller cannot know whether the file -had actually been written when the exception occurred. You need to tell it in +had actually been written when the exception occurred. You need to tell it in some way. > :if !exists("cnt") @@ -7255,7 +7610,7 @@ parentheses can be cut out from |v:excep : :function! Write(file) : try - : execute "write" a:file + : execute "write" fnameescape(a:file) : catch /^Vim(write):/ : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR" : endtry @@ -7307,8 +7662,8 @@ or ":endif". On the other hand, errors This problem has been solved by converting errors to exceptions and using immediate abortion (if not suppressed by ":silent!") only when a try -conditional is active. This is no restriction since an (error) exception can -be caught only from an active try conditional. If you want an immediate +conditional is active. This is no restriction since an (error) exception can +be caught only from an active try conditional. If you want an immediate termination without catching the error, just use a try conditional without catch clause. (You can cause cleanup code being executed before termination by specifying a finally clause.) @@ -7323,8 +7678,8 @@ conditional of a new script, you might c script on error. You get the immediate abortion on error and can catch the error in the new script. If however the sourced script suppresses error messages by using the ":silent!" command (checking for errors by testing -|v:errmsg| if appropriate), its execution path is not changed. The error is -not converted to an exception. (See |:silent|.) So the only remaining cause +|v:errmsg| if appropriate), its execution path is not changed. The error is +not converted to an exception. (See |:silent|.) So the only remaining cause where this happens is for scripts that don't care about errors and produce error messages. You probably won't want to use such code from your new scripts. @@ -7476,18 +7831,18 @@ code can be used: > silent scriptnames redir END - " Split the output into lines and parse each line. Add an entry to the + " Split the output into lines and parse each line. Add an entry to the " "scripts" dictionary. let scripts = {} for line in split(scriptnames_output, "\n") " Only do non-blank lines. if line =~ '\S' " Get the first number in the line. - let nr = matchstr(line, '\d\+') + let nr = matchstr(line, '\d\+') " Get the file name, remove the script number " 123: ". - let name = substitute(line, '.\+:\s*', '', '') + let name = substitute(line, '.\+:\s*', '', '') " Add an item to the Dictionary - let scripts[nr] = name + let scripts[nr] = name endif endfor unlet scriptnames_output @@ -7518,7 +7873,7 @@ 11. The sandbox *eval-sandbox* *sand The 'foldexpr', 'includeexpr', 'indentexpr', 'statusline' and 'foldtext' options are evaluated in a sandbox. This means that you are protected from these expressions having nasty side effects. This gives some safety for when -these options are set from a modeline. It is also used when the command from +these options are set from a modeline. It is also used when the command from a tags file is executed and for CTRL-R = in the command line. The sandbox is also used for the |:sandbox| command. @@ -7556,7 +7911,7 @@ 12. Textlock *textlock* In a few situations it is not allowed to change the text in the buffer, jump to another window and some other things that might confuse or break what Vim is currently doing. This mostly applies to things that happen when Vim is -actually doing something else. For example, evaluating the 'balloonexpr' may +actually doing something else. For example, evaluating the 'balloonexpr' may happen any moment the mouse cursor is resting at some position. This is not allowed when the textlock is active: