diff options
Diffstat (limited to 'runtime/doc/eval.txt')
-rw-r--r-- | runtime/doc/eval.txt | 821 |
1 files changed, 588 insertions, 233 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 126b98b92d..349df2f251 100644 --- 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 +*eval.txt* For Vim version 7.2a. Last change: 2008 Jun 24 - VIM REFERENCE MANUAL by Bram Moolenaar + VIM REFERENCE MANUAL by Bram Moolenaar Expression evaluation *expression* *expr* *E15* *eval* @@ -9,7 +9,7 @@ Expression evaluation *expression* *expr* *E15* *eval* 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 @@ done, the features in this document are not available. See |+eval| and 1.1 Variable types ~ *E712* -There are five types of variables: +There are six types of variables: -Number A 32 bit signed number. +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()| function: > :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" with a value not matching 'x'. 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 |Funcref| and only "equal" and "not 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 last byte. 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 characters: \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* *E115* 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 changes to the current buffer. It is 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 purposes: 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 read/write command. When a "!" *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 characters of the runtime 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. Only valid while '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 but one Normal mode command. < 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 script or function that caused the 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 can set this to the selected choice '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 loaded or saved session file. See *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 exception most recently caught and not < 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 by what the function is used for. 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 argument list 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 at byte count {byte} 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} exists 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, last line or mark 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 items in {list} 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 (move) file from {from} to {to} repeat( {expr}, {count}) String repeat {expr} {count} times resolve( {filename}) String get filename a shortcut points to reverse( {list}) List reverse {list} in-place +round( {expr}) Float round off {expr} 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 {varname} in window {nr} to {val} 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} [, {capital}]]) 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 syntax ID at {lnum} and {col} synIDattr( {synID}, {what} [, {mode}]) String attribute {what} of syntax ID {synID} synIDtrans( {synID}) Number translated syntax ID of {synID} -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 {nr} 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 file in the argument list of the 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}]) *call()* *E699* {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, which is the byte index of the column 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, which is the byte index of the column 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} [, {type}]]]) 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} [, {type}]]]) :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 +< Also see |shellescape()|. -< *eval()* + *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, which is non-zero if {expr} is 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()* |