Skip to content

Commit 6f02b00

Browse files
brammoolbrammool
committed
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)
1 parent 31a11b9 commit 6f02b00

File tree

9 files changed

+668
-190
lines changed

9 files changed

+668
-190
lines changed

‎runtime/doc/eval.txt‎

Lines changed: 121 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
*eval.txt* For Vim version 8.2. Last change: 2020 Dec 29
1+
*eval.txt* For Vim version 8.2. Last change: 2021 Jan 10
22

33

44
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -49,7 +49,7 @@ There are ten types of variables:
4949
*Number* *Integer*
5050
Number A 32 or 64 bit signed number. |expr-number|
5151
The number of bits is available in |v:numbersize|.
52-
Examples: -123 0x10 0177 0b1011
52+
Examples: -123 0x10 0177 0o177 0b1011
5353

5454
Float A floating point number. |floating-point-format| *Float*
5555
{only when compiled with the |+float| feature}
@@ -97,9 +97,10 @@ the Number. Examples:
9797
Conversion from a String to a Number only happens in legacy Vim script, not in
9898
Vim9 script. It is done by converting the first digits to a number.
9999
Hexadecimal "0xf9", Octal "017" or "0o17", and Binary "0b10"
100-
numbers are recognized (NOTE: when using |scriptversion-4| octal with a
101-
leading "0" is not recognized). If the String doesn't start with digits, the
102-
result is zero.
100+
numbers are recognized
101+
NOTE: when using |scriptversion-4| octal with a leading "0" is not recognized.
102+
The 0o notation requires patch 8.2.0886.
103+
If the String doesn't start with digits, the result is zero.
103104
Examples:
104105
String "456" --> Number 456 ~
105106
String "6bar" --> Number 6 ~
@@ -1150,7 +1151,7 @@ expr7 *expr7*
11501151

11511152
For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one).
11521153
For '-' the sign of the number is changed.
1153-
For '+' the number is unchanged.
1154+
For '+' the number is unchanged. Note: "++" has no effect.
11541155

11551156
A String will be converted to a Number first.
11561157

@@ -1191,6 +1192,7 @@ start with one!
11911192
If the length of the String is less than the index, the result is an empty
11921193
String. A negative index always results in an empty string (reason: backward
11931194
compatibility). Use [-1:] to get the last byte or character.
1195+
In Vim9 script a negative index is used like with a list: count from the end.
11941196

11951197
If expr8 is a |List| then it results the item at index expr1. See |list-index|
11961198
for possible index values. If the index is out of range this results in an
@@ -1318,8 +1320,8 @@ When using the lambda form there must be no white space between the } and the
13181320
number
13191321
------
13201322
number number constant *expr-number*
1321-
*hex-number* *octal-number* *binary-number*
13221323

1324+
*0x* *hex-number* *0o* *octal-number* *binary-number*
13231325
Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
13241326
and Octal (starting with 0, 0o or 0O).
13251327

@@ -1572,7 +1574,7 @@ Note how execute() is used to execute an Ex command. That's ugly though.
15721574

15731575
Lambda expressions have internal names like '<lambda>42'. If you get an error
15741576
for a lambda expression, you can find what it is with the following command: >
1575-
:function {'<lambda>42'}
1577+
:function <lambda>42
15761578
See also: |numbered-function|
15771579

15781580
==============================================================================
@@ -2475,12 +2477,13 @@ ch_status({handle} [, {options}])
24752477
changenr() Number current change number
24762478
char2nr({expr} [, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
24772479
charclass({string}) Number character class of {string}
2480+
charcol({expr}) Number column number of cursor or mark
24782481
charidx({string}, {idx} [, {countcc}])
24792482
Number char index of byte {idx} in {string}
24802483
chdir({dir}) String change current working directory
24812484
cindent({lnum}) Number C indent for line {lnum}
24822485
clearmatches([{win}]) none clear all matches
2483-
col({expr}) Number column nr of cursor or mark
2486+
col({expr}) Number column byte index of cursor or mark
24842487
complete({startcol}, {matches}) none set Insert mode completion
24852488
complete_add({expr}) Number add completion match
24862489
complete_check() Number check for key typed during completion
@@ -2558,6 +2561,7 @@ getbufvar({expr}, {varname} [, {def}])
25582561
getchangelist([{expr}]) List list of change list items
25592562
getchar([expr]) Number get one character from the user
25602563
getcharmod() Number modifiers for the last typed character
2564+
getcharpos({expr}) List position of cursor, mark, etc.
25612565
getcharsearch() Dict last character search
25622566
getcmdline() String return the current command-line
25632567
getcmdpos() Number return cursor position in command-line
@@ -2566,6 +2570,7 @@ getcmdwintype() String return current command-line window type
25662570
getcompletion({pat}, {type} [, {filtered}])
25672571
List list of cmdline completion matches
25682572
getcurpos([{winnr}]) List position of the cursor
2573+
getcursorcharpos([{winnr}]) List character position of the cursor
25692574
getcwd([{winnr} [, {tabnr}]]) String get the current working directory
25702575
getenv({name}) String return environment variable
25712576
getfontname([{name}]) String name of font being used
@@ -2828,8 +2833,10 @@ setbufline({expr}, {lnum}, {text})
28282833
setbufvar({expr}, {varname}, {val})
28292834
none set {varname} in buffer {expr} to {val}
28302835
setcellwidths({list}) none set character cell width overrides
2836+
setcharpos({expr}, {list}) Number set the {expr} position to {list}
28312837
setcharsearch({dict}) Dict set character search from {dict}
28322838
setcmdpos({pos}) Number set cursor position in command-line
2839+
setcursorcharpos({list}) Number move cursor to position in {list}
28332840
setenv({name}, {val}) none set environment variable
28342841
setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
28352842
setline({lnum}, {line}) Number set line {lnum} to {line}
@@ -3513,8 +3520,8 @@ byteidxcomp({expr}, {nr}) *byteidxcomp()*
35133520
< The first and third echo result in 3 ('e' plus composing
35143521
character is 3 bytes), the second echo results in 1 ('e' is
35153522
one byte).
3516-
Only works differently from byteidx() when 'encoding' is set to
3517-
a Unicode encoding.
3523+
Only works differently from byteidx() when 'encoding' is set
3524+
to a Unicode encoding.
35183525

35193526
Can also be used as a |method|: >
35203527
GetName()->byteidxcomp(idx)
@@ -3590,6 +3597,18 @@ charclass({string}) *charclass()*
35903597
other specific Unicode class
35913598
The class is used in patterns and word motions.
35923599

3600+
*charcol()*
3601+
charcol({expr}) Same as |col()| but returns the character index of the column
3602+
position given with {expr} instead of the byte position.
3603+
3604+
Example:
3605+
With the cursor on '세' in line 5 with text "여보세요": >
3606+
charcol('.') returns 3
3607+
col('.') returns 7
3608+
3609+
< Can also be used as a |method|: >
3610+
GetPos()->col()
3611+
<
35933612
*charidx()*
35943613
charidx({string}, {idx} [, {countcc}])
35953614
Return the character index of the byte at {idx} in {string}.
@@ -3680,7 +3699,8 @@ col({expr}) The result is a Number, which is the byte index of the column
36803699
out of range then col() returns zero.
36813700
To get the line number use |line()|. To get both use
36823701
|getpos()|.
3683-
For the screen column position use |virtcol()|.
3702+
For the screen column position use |virtcol()|. For the
3703+
character position use |charcol()|.
36843704
Note that only marks in the current file can be used.
36853705
Examples: >
36863706
col(".") column of cursor
@@ -3981,6 +4001,9 @@ cursor({list})
39814001
This is like the return value of |getpos()| or |getcurpos()|,
39824002
but without the first item.
39834003

4004+
To position the cursor using the character count, use
4005+
|setcursorcharpos()|.
4006+
39844007
Does not change the jumplist.
39854008
If {lnum} is greater than the number of lines in the buffer,
39864009
the cursor will be positioned at the last line in the buffer.
@@ -5220,6 +5243,20 @@ getcharmod() *getcharmod()*
52205243
character itself are obtained. Thus Shift-a results in "A"
52215244
without a modifier.
52225245

5246+
*getcharpos()*
5247+
getcharpos({expr})
5248+
Get the position for {expr}. Same as |getpos()| but the column
5249+
number in the returned List is a character index instead of
5250+
a byte index.
5251+
5252+
Example:
5253+
With the cursor on '세' in line 5 with text "여보세요": >
5254+
getcharpos('.') returns [0, 5, 3, 0]
5255+
getpos('.') returns [0, 5, 7, 0]
5256+
<
5257+
Can also be used as a |method|: >
5258+
GetMark()->getcharpos()
5259+
52235260
getcharsearch() *getcharsearch()*
52245261
Return the current character search information as a {dict}
52255262
with the following entries:
@@ -5345,8 +5382,11 @@ getcurpos([{winid}])
53455382
includes an extra "curswant" item in the list:
53465383
[0, lnum, col, off, curswant] ~
53475384
The "curswant" number is the preferred column when moving the
5348-
cursor vertically. Also see |getpos()|.
5349-
The first "bufnum" item is always zero.
5385+
cursor vertically. Also see |getcursorcharpos()| and
5386+
|getpos()|.
5387+
The first "bufnum" item is always zero. The byte position of
5388+
the cursor is returned in 'col'. To get the character
5389+
position, use |getcursorcharpos()|.
53505390

53515391
The optional {winid} argument can specify the window. It can
53525392
be the window number or the |window-ID|. The last known
@@ -5360,7 +5400,24 @@ getcurpos([{winid}])
53605400
call setpos('.', save_cursor)
53615401
< Note that this only works within the window. See
53625402
|winrestview()| for restoring more state.
5363-
*getcwd()*
5403+
5404+
Can also be used as a |method|: >
5405+
GetWinid()->getcurpos()
5406+
5407+
< *getcursorcharpos()*
5408+
getcursorcharpos([{winid}])
5409+
Same as |getcurpos()| but the column number in the returned
5410+
List is a character index instead of a byte index.
5411+
5412+
Example:
5413+
With the cursor on '보' in line 3 with text "여보세요": >
5414+
getcursorcharpos() returns [0, 3, 2, 0, 3]
5415+
getcurpos() returns [0, 3, 4, 0, 3]
5416+
5417+
< Can also be used as a |method|: >
5418+
GetWinid()->getcursorcharpos()
5419+
5420+
< *getcwd()*
53645421
getcwd([{winnr} [, {tabnr}]])
53655422
The result is a String, which is the name of the current
53665423
working directory.
@@ -5667,16 +5724,18 @@ getpos({expr}) Get the position for {expr}. For possible values of {expr}
56675724
Note that for '< and '> Visual mode matters: when it is "V"
56685725
(visual line mode) the column of '< is zero and the column of
56695726
'> is a large number.
5727+
The column number in the returned List is the byte position
5728+
within the line. To get the character position in the line,
5729+
use |getcharpos()|
56705730
This can be used to save and restore the position of a mark: >
56715731
let save_a_mark = getpos("'a")
56725732
...
56735733
call setpos("'a", save_a_mark)
5674-
< Also see |getcurpos()| and |setpos()|.
5734+
< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
56755735

56765736
Can also be used as a |method|: >
56775737
GetMark()->getpos()
56785738

5679-
56805739
getqflist([{what}]) *getqflist()*
56815740
Returns a |List| with all the current quickfix errors. Each
56825741
list item is a dictionary with these entries:
@@ -7542,8 +7601,10 @@ matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
75427601
<
75437602

75447603
*max()*
7545-
max({expr}) Return the maximum value of all items in {expr}.
7546-
{expr} can be a |List| or a |Dictionary|. For a Dictionary,
7604+
max({expr}) Return the maximum value of all items in {expr}. Example: >
7605+
echo max([apples, pears, oranges])
7606+
7607+
< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
75477608
it returns the maximum of all values in the Dictionary.
75487609
If {expr} is neither a List nor a Dictionary, or one of the
75497610
items in {expr} cannot be used as a Number this results in
@@ -7613,8 +7674,10 @@ menu_info({name} [, {mode}]) *menu_info()*
76137674

76147675

76157676
< *min()*
7616-
min({expr}) Return the minimum value of all items in {expr}.
7617-
{expr} can be a |List| or a |Dictionary|. For a Dictionary,
7677+
min({expr}) Return the minimum value of all items in {expr}. Example: >
7678+
echo min([apples, pears, oranges])
7679+
7680+
< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
76187681
it returns the minimum of all values in the Dictionary.
76197682
If {expr} is neither a List nor a Dictionary, or one of the
76207683
items in {expr} cannot be used as a Number this results in
@@ -7631,13 +7694,13 @@ mkdir({name} [, {path} [, {prot}]])
76317694
necessary. Otherwise it must be "".
76327695

76337696
If {prot} is given it is used to set the protection bits of
7634-
the new directory. The default is 0755 (rwxr-xr-x: r/w for
7635-
the user readable for others). Use 0700 to make it unreadable
7636-
for others. This is only used for the last part of {name}.
7637-
Thus if you create /tmp/foo/bar then /tmp/foo will be created
7638-
with 0755.
7697+
the new directory. The default is 0o755 (rwxr-xr-x: r/w for
7698+
the user, readable for others). Use 0o700 to make it
7699+
unreadable for others. This is only used for the last part of
7700+
{name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
7701+
created with 0o755.
76397702
Example: >
7640-
:call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
7703+
:call mkdir($HOME . "/tmp/foo/bar", "p", 0o700)
76417704

76427705
< This function is not available in the |sandbox|.
76437706

@@ -9200,6 +9263,19 @@ setcellwidths({list}) *setcellwidths()*
92009263
< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
92019264
the effect for known emoji characters.
92029265

9266+
setcharpos({expr}, {list}) *setcharpos()*
9267+
Same as |setpos()| but uses the specified column number as the
9268+
character index instead of the byte index in the line.
9269+
9270+
Example:
9271+
With the text "여보세요" in line 8: >
9272+
call setcharpos('.', [0, 8, 4, 0])
9273+
< positions the cursor on the fourth character '요'. >
9274+
call setpos('.', [0, 8, 4, 0])
9275+
< positions the cursor on the second character '보'.
9276+
9277+
Can also be used as a |method|: >
9278+
GetPosition()->setcharpos('.')
92039279

92049280
setcharsearch({dict}) *setcharsearch()*
92059281
Set the current character search information to {dict},
@@ -9242,6 +9318,21 @@ setcmdpos({pos}) *setcmdpos()*
92429318
Can also be used as a |method|: >
92439319
GetPos()->setcmdpos()
92449320

9321+
setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
9322+
setcursorcharpos({list})
9323+
Same as |cursor()| but uses the specified column number as the
9324+
character index instead of the byte index in the line.
9325+
9326+
Example:
9327+
With the text "여보세요" in line 4: >
9328+
call setcursorcharpos(4, 3)
9329+
< positions the cursor on the third character '세'. >
9330+
call cursor(4, 3)
9331+
< positions the cursor on the first character '여'.
9332+
9333+
Can also be used as a |method|: >
9334+
GetCursorPos()->setcursorcharpos()
9335+
92459336
setenv({name}, {val}) *setenv()*
92469337
Set environment variable {name} to {val}.
92479338
When {val} is |v:null| the environment variable is deleted.
@@ -9353,7 +9444,8 @@ setpos({expr}, {list})
93539444

93549445
"lnum" and "col" are the position in the buffer. The first
93559446
column is 1. Use a zero "lnum" to delete a mark. If "col" is
9356-
smaller than 1 then 1 is used.
9447+
smaller than 1 then 1 is used. To use the character count
9448+
instead of the byte count, use |setcharpos()|.
93579449

93589450
The "off" number is only used when 'virtualedit' is set. Then
93599451
it is the offset in screen columns from the start of the
@@ -9373,7 +9465,7 @@ setpos({expr}, {list})
93739465
Returns 0 when the position could be set, -1 otherwise.
93749466
An error message is given if {expr} is invalid.
93759467

9376-
Also see |getpos()| and |getcurpos()|.
9468+
Also see |setcharpos()|, |getpos()| and |getcurpos()|.
93779469

93789470
This does not restore the preferred column for moving
93799471
vertically; if you set the cursor position with this, |j| and

‎runtime/doc/usr_41.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -753,6 +753,11 @@ Cursor and mark position: *cursor-functions* *mark-functions*
753753
screenchar() get character code at a screen line/row
754754
screenchars() get character codes at a screen line/row
755755
screenstring() get string of characters at a screen line/row
756+
charcol() character number of the cursor or a mark
757+
getcharpos() get character position of cursor, mark, etc.
758+
setcharpos() set character position of cursor, mark, etc.
759+
getcursorcharpos() get character position of the cursor
760+
setcursorcharpos() set character position of the cursor
756761

757762
Working with text in the current buffer: *text-functions*
758763
getline() get a line or list of lines from the buffer

0 commit comments

Comments
 (0)