patch 8.2.2324: not easy to get mark en cursor posotion by character countv8.2.2324

Problem:    Not easy to get mark en cursor posotion by character count.
Solution:   Add functions that use character index. (Yegappan Lakshmanan,
            closes #7648)

2 files changed, 126 insertions, 29 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 750448dfc6..7848534b5d 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 @@ There are ten types of variables:
 							*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 @@ the Number.  Examples:
 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 @@ expr7							*expr7*
 
 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 @@ start with one!
 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 @@ When using the lambda form there must be no white space between the } and the
 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 @@ Note how execute() is used to execute an Ex command.  That's ugly though.
 
 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 @@ ch_status({handle} [, {options}])
 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 @@ getbufvar({expr}, {varname} [, {def}])
 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 @@ getcmdwintype()			String	return current command-line window type
 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 @@ setbufline({expr}, {lnum}, {text})
 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 @@ byteidxcomp({expr}, {nr})					*byteidxcomp()*
 <		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 @@ charclass({string})					*charclass()*
 			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 @@ col({expr})	The result is a Number, which is the byte index of the column
 		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 @@ cursor({list})
 		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 @@ getcharmod()						*getcharmod()*
 		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 @@ getcurpos([{winid}])
 		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 @@ getcurpos([{winid}])
 			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 @@ getpos({expr})	Get the position for {expr}.  For possible values of {expr}
 		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 @@ matchstrpos({expr}, {pat} [, {start} [, {count}]])		*matchstrpos()*
 <
 
 							*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 @@ menu_info({name} [, {mode}])				*menu_info()*
 
 
 <							*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 @@ 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
-		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 @@ setcellwidths({list})					*setcellwidths()*
 <		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 @@ setcmdpos({pos})					*setcmdpos()*
 		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 @@ setpos({expr}, {list})
 
 		"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 @@ setpos({expr}, {list})
 		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
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index a035038e47..da095e13f4 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -753,6 +753,11 @@ Cursor and mark position:		*cursor-functions* *mark-functions*
 	screenchar()		get character code at a screen line/row
 	screenchars()		get character codes at a screen line/row
 	screenstring()		get string of characters at a screen line/row
+	charcol()		character number of the cursor or a mark
+	getcharpos()		get character position of cursor, mark, etc.
+	setcharpos()		set character position of cursor, mark, etc.
+	getcursorcharpos()	get character position of the cursor
+	setcursorcharpos()	set character position of the cursor
 
 Working with text in the current buffer:		*text-functions*
 	getline()		get a line or list of lines from the buffer