diff options
Diffstat (limited to 'runtime/doc/builtin.txt')
| -rw-r--r-- | runtime/doc/builtin.txt | 157 |
1 files changed, 126 insertions, 31 deletions
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 91531db656..b37ac117f3 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -60,17 +60,19 @@ browse({save}, {title}, {initdir}, {default}) String put up a file requester browsedir({title}, {initdir}) String put up a directory requester bufadd({name}) Number add a buffer to the buffer list -bufexists({expr}) Number |TRUE| if buffer {expr} exists -buflisted({expr}) Number |TRUE| if buffer {expr} is listed -bufload({expr}) Number load buffer {expr} if not loaded yet -bufloaded({expr}) Number |TRUE| if buffer {expr} is loaded -bufname([{expr}]) String Name of the buffer {expr} -bufnr([{expr} [, {create}]]) Number Number of the buffer {expr} -bufwinid({expr}) Number |window-ID| of buffer {expr} -bufwinnr({expr}) Number window number of buffer {expr} +bufexists({buf}) Number |TRUE| if buffer {buf} exists +buflisted({buf}) Number |TRUE| if buffer {buf} is listed +bufload({buf}) Number load buffer {buf} if not loaded yet +bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded +bufname([{buf}]) String Name of the buffer {buf} +bufnr([{buf} [, {create}]]) Number Number of the buffer {buf} +bufwinid({buf}) Number window ID of buffer {buf} +bufwinnr({buf}) Number window number of buffer {buf} byte2line({byte}) Number line number at byte count {byte} -byteidx({expr}, {nr}) Number byte index of {nr}th char in {expr} -byteidxcomp({expr}, {nr}) Number byte index of {nr}th char in {expr} +byteidx({expr}, {nr} [, {utf16}]) + Number byte index of {nr}th char in {expr} +byteidxcomp({expr}, {nr} [, {utf16}]) + Number byte index of {nr}th char in {expr} call({func}, {arglist} [, {dict}]) any call {func} with arguments {arglist} ceil({expr}) Float round {expr} up @@ -80,7 +82,7 @@ chansend({id}, {data}) Number Writes {data} to channel char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr} charclass({string}) Number character class of {string} charcol({expr} [, {winid}]) Number column number of cursor or mark -charidx({string}, {idx} [, {countcc}]) +charidx({string}, {idx} [, {countcc} [, {utf16}]]) Number char index of byte {idx} in {string} chdir({dir}) String change current working directory cindent({lnum}) Number C indent for line {lnum} @@ -501,6 +503,8 @@ strptime({format}, {timestring}) strridx({haystack}, {needle} [, {start}]) Number last index of {needle} in {haystack} strtrans({expr}) String translate string to make it printable +strutf16len({string} [, {countcc}]) + Number number of UTF-16 code units in {string} strwidth({expr}) Number display cell length of the String {expr} submatch({nr} [, {list}]) String or List specific match in ":s" or substitute() @@ -545,8 +549,11 @@ undofile({name}) String undo file name for {name} undotree() List undo file tree uniq({list} [, {func} [, {dict}]]) List remove adjacent duplicates from a list +utf16idx({string}, {idx} [, {countcc} [, {charidx}]]) + Number UTF-16 index of byte {idx} in {string} values({dict}) List values in {dict} -virtcol({expr}) Number screen column of cursor or mark +virtcol({expr} [, {list}]) Number or List + screen column of cursor or mark virtcol2col({winid}, {lnum}, {col}) Number byte index of a character on screen visualmode([expr]) String last visual mode used @@ -637,6 +644,7 @@ add({object}, {expr}) *add()* and({expr}, {expr}) *and()* Bitwise AND on the two arguments. The arguments are converted to a number. A List, Dict or Float argument causes an error. + Also see `or()` and `xor()`. Example: > :let flag = and(bits, 0x80) < Can also be used as a |method|: > @@ -980,7 +988,7 @@ byte2line({byte}) *byte2line()* Can also be used as a |method|: > GetOffset()->byte2line() -byteidx({expr}, {nr}) *byteidx()* +byteidx({expr}, {nr} [, {utf16}]) *byteidx()* Return byte index of the {nr}th character in the String {expr}. Use zero for the first character, it then returns zero. @@ -990,6 +998,13 @@ byteidx({expr}, {nr}) *byteidx()* length is added to the preceding base character. See |byteidxcomp()| below for counting composing characters separately. + When {utf16} is present and TRUE, {nr} is used as the UTF-16 + index in the String {expr} instead of as the character index. + The UTF-16 index is the index in the string when it is encoded + with 16-bit words. If the specified UTF-16 index is in the + middle of a character (e.g. in a 4-byte character), then the + byte index of the first byte in the character is returned. + Refer to |string-offset-encoding| for more information. Example : > echo matchstr(str, ".", byteidx(str, 3)) < will display the fourth character. Another way to do the @@ -1001,11 +1016,17 @@ byteidx({expr}, {nr}) *byteidx()* If there are less than {nr} characters -1 is returned. If there are exactly {nr} characters the length of the string in bytes is returned. - + See |charidx()| and |utf16idx()| for getting the character and + UTF-16 index respectively from the byte index. + Examples: > + echo byteidx('a😊😊', 2) returns 5 + echo byteidx('a😊😊', 2, 1) returns 1 + echo byteidx('a😊😊', 3, 1) returns 5 +< Can also be used as a |method|: > GetName()->byteidx(idx) -byteidxcomp({expr}, {nr}) *byteidxcomp()* +byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()* Like byteidx(), except that a composing character is counted as a separate character. Example: > let s = 'e' .. nr2char(0x301) @@ -1129,27 +1150,36 @@ charcol({expr} [, {winid}]) *charcol()* GetPos()->col() < *charidx()* -charidx({string}, {idx} [, {countcc}]) +charidx({string}, {idx} [, {countcc} [, {utf16}]]) Return the character index of the byte at {idx} in {string}. The index of the first character is zero. If there are no multibyte characters the returned value is equal to {idx}. + When {countcc} is omitted or |FALSE|, then composing characters - are not counted separately, their byte length is - added to the preceding base character. + are not counted separately, their byte length is added to the + preceding base character. When {countcc} is |TRUE|, then composing characters are counted as separate characters. + + When {utf16} is present and TRUE, {idx} is used as the UTF-16 + index in the String {expr} instead of as the byte index. + Returns -1 if the arguments are invalid or if {idx} is greater than the index of the last byte in {string}. An error is given if the first argument is not a string, the second argument is not a number or when the third argument is present and is not zero or one. + See |byteidx()| and |byteidxcomp()| for getting the byte index - from the character index. + from the character index and |utf16idx()| for getting the + UTF-16 index from the character index. + Refer to |string-offset-encoding| for more information. Examples: > echo charidx('áb́ć', 3) returns 1 echo charidx('áb́ć', 6, 1) returns 4 echo charidx('áb́ć', 16) returns -1 + echo charidx('a😊😊', 4, 0, 1) returns 2 < Can also be used as a |method|: > GetName()->charidx(idx) @@ -1969,7 +1999,7 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is Can also be used as a |method|: > Varname()->exists() -exp({expr}) *exp()* +exp({expr}) *exp()* Return the exponential of {expr} as a |Float| in the range [0, inf]. {expr} must evaluate to a |Float| or a |Number|. @@ -2525,7 +2555,7 @@ funcref({name} [, {arglist}] [, {dict}]) Can also be used as a |method|: > GetFuncname()->funcref([arg]) < - *function()* *partial* *E700* *E922* *E923* + *function()* *partial* *E700* *E923* function({name} [, {arglist}] [, {dict}]) Return a |Funcref| variable that refers to function {name}. {name} can be the name of a user defined function or an @@ -8330,6 +8360,28 @@ strtrans({string}) *strtrans()* Can also be used as a |method|: > GetString()->strtrans() +strutf16len({string} [, {countcc}]) *strutf16len()* + The result is a Number, which is the number of UTF-16 code + units in String {string} (after converting it to UTF-16). + + When {countcc} is TRUE, composing characters are counted + separately. + When {countcc} is omitted or FALSE, composing characters are + ignored. + + Returns zero on error. + + Also see |strlen()| and |strcharlen()|. + Examples: > + echo strutf16len('a') returns 1 + echo strutf16len('©') returns 1 + echo strutf16len('😊') returns 2 + echo strutf16len('ą́') returns 1 + echo strutf16len('ą́', v:true) returns 3 + + Can also be used as a |method|: > + GetText()->strutf16len() +< strwidth({string}) *strwidth()* The result is a Number, which is the number of display cells String {string} occupies. A Tab character is counted as one @@ -9061,6 +9113,34 @@ uniq({list} [, {func} [, {dict}]]) *uniq()* *E882* Can also be used as a |method|: > mylist->uniq() +< + *utf16idx()* +utf16idx({string}, {idx} [, {countcc} [, {charidx}]]) + Same as |charidx()| but returns the UTF-16 index of the byte + at {idx} in {string} (after converting it to UTF-16). + + When {charidx} is present and TRUE, {idx} is used as the + character index in the String {string} instead of as the byte + index. + An {idx} in the middle of a UTF-8 sequence is rounded upwards + to the end of that sequence. + + See |byteidx()| and |byteidxcomp()| for getting the byte index + from the UTF-16 index and |charidx()| for getting the + character index from the UTF-16 index. + Refer to |string-offset-encoding| for more information. + Examples: > + echo utf16idx('a😊😊', 3) returns 2 + echo utf16idx('a😊😊', 7) returns 4 + echo utf16idx('a😊😊', 1, 0, 1) returns 2 + echo utf16idx('a😊😊', 2, 0, 1) returns 4 + echo utf16idx('aą́c', 6) returns 2 + echo utf16idx('aą́c', 6, 1) returns 4 + echo utf16idx('a😊😊', 9) returns -1 +< + Can also be used as a |method|: > + GetName()->utf16idx(idx) + values({dict}) *values()* Return a |List| with all the values of {dict}. The |List| is @@ -9070,7 +9150,7 @@ values({dict}) *values()* Can also be used as a |method|: > mydict->values() -virtcol({expr}) *virtcol()* +virtcol({expr} [, {list}]) *virtcol()* The result is a Number, which is the screen column of the file position given with {expr}. That is, the last screen position occupied by the character at that position, when the screen @@ -9079,13 +9159,17 @@ virtcol({expr}) *virtcol()* the <Tab>. For example, for a <Tab> in column 1, with 'ts' set to 8, it returns 8. |conceal| is ignored. For the byte position use |col()|. + For the use of {expr} see |col()|. - When 'virtualedit' is used {expr} can be [lnum, col, off], where - "off" is the offset in screen columns from the start of the - character. E.g., a position within a <Tab> or after the last - character. When "off" is omitted zero is used. - When Virtual editing is active in the current mode, a position - beyond the end of the line can be returned. |'virtualedit'| + + When 'virtualedit' is used {expr} can be [lnum, col, off], + where "off" is the offset in screen columns from the start of + the character. E.g., a position within a <Tab> or after the + last character. When "off" is omitted zero is used. When + Virtual editing is active in the current mode, a position + beyond the end of the line can be returned. Also see + |'virtualedit'| + The accepted positions are: . the cursor position $ the end of the cursor line (the result is the @@ -9097,11 +9181,22 @@ virtcol({expr}) *virtcol()* cursor is the end). When not in Visual mode returns the cursor position. Differs from |'<| in that it's updated right away. + + If {list} is present and non-zero then virtcol() returns a List + with the first and last screen position occupied by the + character. + Note that only marks in the current file can be used. 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 + " With text "foo^Lbar" and cursor on the "^L": + + virtcol(".") " returns 5 + virtcol(".", 1) " returns [4, 5] + virtcol("$") " returns 9 + + " With text " there", with 't at 'h': + + virtcol("'t") " 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: > |