vim-patch:8.2.2957: using getchar() in Vim9 script is problematic

Problem:    Using getchar() in Vim9 script is problematic.
Solution:   Add getcharstr(). (closes vim/vim#8343)
https://github.com/vim/vim/commit/3a7503c34c65ed15cc08deb5b54aaf2ea51525b4

Cherry-pick Test_getchar() changes from patch v8.1.2304
to sync with upstream.

Port f_getcharstr() to src/nvim/eval/funcs.c, not src/nvim/getchar.c.
Patch v8.1.2042 is not ported yet.

1 files changed, 18 insertions, 1 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 2b6e3aff29..83e10d649d 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2203,9 +2203,11 @@ getbufline({expr}, {lnum} [, {end}])
 getbufvar({expr}, {varname} [, {def}])
 				any	variable {varname} in buffer {expr}
 getchangelist({expr})		List	list of change list items
-getchar([expr])		Number	get one character from the user
+getchar([expr])			Number or String
+					get one character from the user
 getcharmod()			Number	modifiers for the last typed character
 getcharsearch()			Dict	last character search
+getcharstr([expr])		String	get one character from the user
 getcmdline()			String	return the current command-line
 getcmdpos()			Number	return cursor position in command-line
 getcmdtype()			String	return current command-line type
@@ -4308,6 +4310,7 @@ getchar([expr])						*getchar()*
 			Return zero otherwise.
 		If [expr] is 1, only check if a character is available, it is
 			not consumed.  Return zero if no character available.
+		If you prefer always getting a string use |getcharstr()|.
 
 		Without [expr] and when [expr] is 0 a whole character or
 		special key is returned.  If it is a single character, the
@@ -4399,6 +4402,20 @@ getcharsearch()						*getcharsearch()*
 			:nnoremap <expr> , getcharsearch().forward ? ',' : ';'
 <		Also see |setcharsearch()|.
 
+
+getcharstr([expr])					*getcharstr()*
+		Get a single character from the user or input stream as a
+		string.
+		If [expr] is omitted, wait until a character is available.
+		If [expr] is 0 or false, only get a character when one is
+			available.  Return an empty string otherwise.
+		If [expr] is 1 or true, only check if a character is
+			available, it is not consumed.  Return an empty string
+			if no character is available.
+		Otherwise this works like |getchar()|, except that a number
+		result is converted to a string.
+
+
 getcmdline()						*getcmdline()*
 		Return the current command-line.  Only works when the command
 		line is being edited, thus requires use of |c_CTRL-\_e| or