patch 8.2.2324: not easy to get mark en cursor posotion by character count
Problem: Not easy to get mark en cursor posotion by character count.
Solution: Add functions that use character index. (Yegappan Lakshmanan,
closes #7648)
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 750448d..7848534 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1,4 +1,4 @@
-*eval.txt* For Vim version 8.2. Last change: 2020 Dec 29
+*eval.txt* For Vim version 8.2. Last change: 2021 Jan 10
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -49,7 +49,7 @@
*Number* *Integer*
Number A 32 or 64 bit signed number. |expr-number|
The number of bits is available in |v:numbersize|.
- Examples: -123 0x10 0177 0b1011
+ Examples: -123 0x10 0177 0o177 0b1011
Float A floating point number. |floating-point-format| *Float*
{only when compiled with the |+float| feature}
@@ -97,9 +97,10 @@
Conversion from a String to a Number only happens in legacy Vim script, not in
Vim9 script. It is done by converting the first digits to a number.
Hexadecimal "0xf9", Octal "017" or "0o17", and Binary "0b10"
-numbers are recognized (NOTE: when using |scriptversion-4| octal with a
-leading "0" is not recognized). If the String doesn't start with digits, the
-result is zero.
+numbers are recognized
+NOTE: when using |scriptversion-4| octal with a leading "0" is not recognized.
+The 0o notation requires patch 8.2.0886.
+If the String doesn't start with digits, the result is zero.
Examples:
String "456" --> Number 456 ~
String "6bar" --> Number 6 ~
@@ -1150,7 +1151,7 @@
For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one).
For '-' the sign of the number is changed.
-For '+' the number is unchanged.
+For '+' the number is unchanged. Note: "++" has no effect.
A String will be converted to a Number first.
@@ -1191,6 +1192,7 @@
If the length of the String is less than the index, the result is an empty
String. A negative index always results in an empty string (reason: backward
compatibility). Use [-1:] to get the last byte or character.
+In Vim9 script a negative index is used like with a list: count from the end.
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
@@ -1318,8 +1320,8 @@
number
------
number number constant *expr-number*
- *hex-number* *octal-number* *binary-number*
+ *0x* *hex-number* *0o* *octal-number* *binary-number*
Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
and Octal (starting with 0, 0o or 0O).
@@ -1572,7 +1574,7 @@
Lambda expressions have internal names like '<lambda>42'. If you get an error
for a lambda expression, you can find what it is with the following command: >
- :function {'<lambda>42'}
+ :function <lambda>42
See also: |numbered-function|
==============================================================================
@@ -2475,12 +2477,13 @@
changenr() Number current change number
char2nr({expr} [, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
charclass({string}) Number character class of {string}
+charcol({expr}) Number column number of cursor or mark
charidx({string}, {idx} [, {countcc}])
Number char index of byte {idx} in {string}
chdir({dir}) String change current working directory
cindent({lnum}) Number C indent for line {lnum}
clearmatches([{win}]) none clear all matches
-col({expr}) Number column nr of cursor or mark
+col({expr}) Number column byte index of cursor or mark
complete({startcol}, {matches}) none set Insert mode completion
complete_add({expr}) Number add completion match
complete_check() Number check for key typed during completion
@@ -2558,6 +2561,7 @@
getchangelist([{expr}]) List list of change list items
getchar([expr]) Number get one character from the user
getcharmod() Number modifiers for the last typed character
+getcharpos({expr}) List position of cursor, mark, etc.
getcharsearch() Dict last character search
getcmdline() String return the current command-line
getcmdpos() Number return cursor position in command-line
@@ -2566,6 +2570,7 @@
getcompletion({pat}, {type} [, {filtered}])
List list of cmdline completion matches
getcurpos([{winnr}]) List position of the cursor
+getcursorcharpos([{winnr}]) List character position of the cursor
getcwd([{winnr} [, {tabnr}]]) String get the current working directory
getenv({name}) String return environment variable
getfontname([{name}]) String name of font being used
@@ -2828,8 +2833,10 @@
setbufvar({expr}, {varname}, {val})
none set {varname} in buffer {expr} to {val}
setcellwidths({list}) none set character cell width overrides
+setcharpos({expr}, {list}) Number set the {expr} position to {list}
setcharsearch({dict}) Dict set character search from {dict}
setcmdpos({pos}) Number set cursor position in command-line
+setcursorcharpos({list}) Number move cursor to position in {list}
setenv({name}, {val}) none set environment variable
setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
setline({lnum}, {line}) Number set line {lnum} to {line}
@@ -3513,8 +3520,8 @@
< The first and third echo result in 3 ('e' plus composing
character is 3 bytes), the second echo results in 1 ('e' is
one byte).
- Only works differently from byteidx() when 'encoding' is set to
- a Unicode encoding.
+ Only works differently from byteidx() when 'encoding' is set
+ to a Unicode encoding.
Can also be used as a |method|: >
GetName()->byteidxcomp(idx)
@@ -3590,6 +3597,18 @@
other specific Unicode class
The class is used in patterns and word motions.
+ *charcol()*
+charcol({expr}) Same as |col()| but returns the character index of the column
+ position given with {expr} instead of the byte position.
+
+ Example:
+ With the cursor on '세' in line 5 with text "여보세요": >
+ charcol('.') returns 3
+ col('.') returns 7
+
+< Can also be used as a |method|: >
+ GetPos()->col()
+<
*charidx()*
charidx({string}, {idx} [, {countcc}])
Return the character index of the byte at {idx} in {string}.
@@ -3680,7 +3699,8 @@
out of range then col() returns zero.
To get the line number use |line()|. To get both use
|getpos()|.
- For the screen column position use |virtcol()|.
+ For the screen column position use |virtcol()|. For the
+ character position use |charcol()|.
Note that only marks in the current file can be used.
Examples: >
col(".") column of cursor
@@ -3981,6 +4001,9 @@
This is like the return value of |getpos()| or |getcurpos()|,
but without the first item.
+ To position the cursor using the character count, use
+ |setcursorcharpos()|.
+
Does not change the jumplist.
If {lnum} is greater than the number of lines in the buffer,
the cursor will be positioned at the last line in the buffer.
@@ -5220,6 +5243,20 @@
character itself are obtained. Thus Shift-a results in "A"
without a modifier.
+ *getcharpos()*
+getcharpos({expr})
+ Get the position for {expr}. Same as |getpos()| but the column
+ number in the returned List is a character index instead of
+ a byte index.
+
+ Example:
+ With the cursor on '세' in line 5 with text "여보세요": >
+ getcharpos('.') returns [0, 5, 3, 0]
+ getpos('.') returns [0, 5, 7, 0]
+<
+ Can also be used as a |method|: >
+ GetMark()->getcharpos()
+
getcharsearch() *getcharsearch()*
Return the current character search information as a {dict}
with the following entries:
@@ -5345,8 +5382,11 @@
includes an extra "curswant" item in the list:
[0, lnum, col, off, curswant] ~
The "curswant" number is the preferred column when moving the
- cursor vertically. Also see |getpos()|.
- The first "bufnum" item is always zero.
+ cursor vertically. Also see |getcursorcharpos()| and
+ |getpos()|.
+ The first "bufnum" item is always zero. The byte position of
+ the cursor is returned in 'col'. To get the character
+ position, use |getcursorcharpos()|.
The optional {winid} argument can specify the window. It can
be the window number or the |window-ID|. The last known
@@ -5360,7 +5400,24 @@
call setpos('.', save_cursor)
< Note that this only works within the window. See
|winrestview()| for restoring more state.
- *getcwd()*
+
+ Can also be used as a |method|: >
+ GetWinid()->getcurpos()
+
+< *getcursorcharpos()*
+getcursorcharpos([{winid}])
+ Same as |getcurpos()| but the column number in the returned
+ List is a character index instead of a byte index.
+
+ Example:
+ With the cursor on '보' in line 3 with text "여보세요": >
+ getcursorcharpos() returns [0, 3, 2, 0, 3]
+ getcurpos() returns [0, 3, 4, 0, 3]
+
+< Can also be used as a |method|: >
+ GetWinid()->getcursorcharpos()
+
+< *getcwd()*
getcwd([{winnr} [, {tabnr}]])
The result is a String, which is the name of the current
working directory.
@@ -5667,16 +5724,18 @@
Note that for '< and '> Visual mode matters: when it is "V"
(visual line mode) the column of '< is zero and the column of
'> is a large number.
+ The column number in the returned List is the byte position
+ within the line. To get the character position in the line,
+ use |getcharpos()|
This can be used to save and restore the position of a mark: >
let save_a_mark = getpos("'a")
...
call setpos("'a", save_a_mark)
-< Also see |getcurpos()| and |setpos()|.
+< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
Can also be used as a |method|: >
GetMark()->getpos()
-
getqflist([{what}]) *getqflist()*
Returns a |List| with all the current quickfix errors. Each
list item is a dictionary with these entries:
@@ -7542,8 +7601,10 @@
<
*max()*
-max({expr}) Return the maximum value of all items in {expr}.
- {expr} can be a |List| or a |Dictionary|. For a Dictionary,
+max({expr}) Return the maximum value of all items in {expr}. Example: >
+ echo max([apples, pears, oranges])
+
+< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
it returns the maximum of all values in the Dictionary.
If {expr} is neither a List nor a Dictionary, or one of the
items in {expr} cannot be used as a Number this results in
@@ -7613,8 +7674,10 @@
< *min()*
-min({expr}) Return the minimum value of all items in {expr}.
- {expr} can be a |List| or a |Dictionary|. For a Dictionary,
+min({expr}) Return the minimum value of all items in {expr}. Example: >
+ echo min([apples, pears, oranges])
+
+< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
it returns the minimum of all values in the Dictionary.
If {expr} is neither a List nor a Dictionary, or one of the
items in {expr} cannot be used as a Number this results in
@@ -7631,13 +7694,13 @@
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
- for others. This is only used for the last part of {name}.
- Thus if you create /tmp/foo/bar then /tmp/foo will be created
- with 0755.
+ the new directory. The default is 0o755 (rwxr-xr-x: r/w for
+ the user, readable for others). Use 0o700 to make it
+ unreadable for others. This is only used for the last part of
+ {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
+ created with 0o755.
Example: >
- :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
+ :call mkdir($HOME . "/tmp/foo/bar", "p", 0o700)
< This function is not available in the |sandbox|.
@@ -9200,6 +9263,19 @@
< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
the effect for known emoji characters.
+setcharpos({expr}, {list}) *setcharpos()*
+ Same as |setpos()| but uses the specified column number as the
+ character index instead of the byte index in the line.
+
+ Example:
+ With the text "여보세요" in line 8: >
+ call setcharpos('.', [0, 8, 4, 0])
+< positions the cursor on the fourth character '요'. >
+ call setpos('.', [0, 8, 4, 0])
+< positions the cursor on the second character '보'.
+
+ Can also be used as a |method|: >
+ GetPosition()->setcharpos('.')
setcharsearch({dict}) *setcharsearch()*
Set the current character search information to {dict},
@@ -9242,6 +9318,21 @@
Can also be used as a |method|: >
GetPos()->setcmdpos()
+setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
+setcursorcharpos({list})
+ Same as |cursor()| but uses the specified column number as the
+ character index instead of the byte index in the line.
+
+ Example:
+ With the text "여보세요" in line 4: >
+ call setcursorcharpos(4, 3)
+< positions the cursor on the third character '세'. >
+ call cursor(4, 3)
+< positions the cursor on the first character '여'.
+
+ Can also be used as a |method|: >
+ GetCursorPos()->setcursorcharpos()
+
setenv({name}, {val}) *setenv()*
Set environment variable {name} to {val}.
When {val} is |v:null| the environment variable is deleted.
@@ -9353,7 +9444,8 @@
"lnum" and "col" are the position in the buffer. The first
column is 1. Use a zero "lnum" to delete a mark. If "col" is
- smaller than 1 then 1 is used.
+ smaller than 1 then 1 is used. To use the character count
+ instead of the byte count, use |setcharpos()|.
The "off" number is only used when 'virtualedit' is set. Then
it is the offset in screen columns from the start of the
@@ -9373,7 +9465,7 @@
Returns 0 when the position could be set, -1 otherwise.
An error message is given if {expr} is invalid.
- Also see |getpos()| and |getcurpos()|.
+ Also see |setcharpos()|, |getpos()| and |getcurpos()|.
This does not restore the preferred column for moving
vertically; if you set the cursor position with this, |j| and