vim-patch:8.2.0924: cannot save and restore a register properly

Problem:    Cannot save and restore a register properly.
Solution:   Add getreginfo() and make setreg() accept a dictionary. (Andy
            Massimino, closes vim/vim#3370)
https://github.com/vim/vim/commit/bb861e293e0170455184079fa537278754b07911

Cherry-pick eval.txt changes for getreginfo() from:
https://github.com/vim/vim/commit/6aa57295cfbe8f21c15f0671e45fd53cf990d404
https://github.com/vim/vim/commit/207f009326c8f878defde0e594d7d9ed9860106e

2 files changed, 36 insertions, 4 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 14e240783d..ac02bdae32 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2436,8 +2436,9 @@ getpos({expr})			List	position of cursor, mark, etc.
 getqflist()			List	list of quickfix items
 getqflist({what})		Dict	get specific quickfix list properties
 getreg([{regname} [, 1 [, {list}]]])
-				String or List   contents of register
-getregtype([{regname}])		String	type of register
+				String or List   contents of a register
+getreginfo([{regname}])		Dict	information about a register
+getregtype([{regname}])		String	type of a register
 gettabinfo([{expr}])		List	list of tab pages
 gettabvar({nr}, {varname} [, {def}])
 				any	variable {varname} in tab {nr} or {def}
@@ -5247,6 +5248,32 @@ getreg([{regname} [, 1 [, {list}]]])			*getreg()*
 
 		If {regname} is not specified, |v:register| is used.
 
+getreginfo([{regname}])					*getreginfo()*
+		Returns detailed information about register {regname} as a
+		Dictionary with the following entries:
+			regcontents	List of lines contained in register
+					{regname}, like
+					|getreg|({regname}, 1, 1).
+			regtype		the type of register {regname}, as in
+					|getregtype()|.
+			isunnamed	Boolean flag, v:true if this register
+					is currently pointed to by the unnamed
+					register.
+			points_to	for the unnamed register, gives the
+					single letter name of the register
+					currently pointed to (see |quotequote|).
+					For example, after deleting a line
+					with `dd`, this field will be "1",
+					which is the register that got the
+					deleted text.
+
+		The {regname} argument is a string.  If {regname} is invalid
+		or not set, an empty Dictionary will be returned.
+		If {regname} is not specified, |v:register| is used.
+		The returned Dictionary can be passed to |setreg()|.
+
+		Can also be used as a |method|: >
+			GetRegname()->getreginfo()
 
 getregtype([{regname}])					*getregtype()*
 		The result is a String, which is type of register {regname}.
@@ -8435,8 +8462,8 @@ setreg({regname}, {value} [, {options}])
 		Set the register {regname} to {value}.
 		The {regname} argument is a string.
 
-		{value} may be any value returned by |getreg()|, including
-		a |List|.
+		{value} may be any value returned by |getreg()| or
+		|getreginfo()|, including a |List| or |Dict|.
 		If {options} contains "a" or {regname} is upper case,
 		then the value is appended.
 
@@ -8466,9 +8493,13 @@ setreg({regname}, {value} [, {options}])
 			:call setreg(v:register, @*)
 			:call setreg('*', @%, 'ac')
 			:call setreg('a', "1\n2\n3", 'b5')
+			:call setreg('"', { 'points_to': 'a'})
 
 <		This example shows using the functions to save and restore a
 		register: >
+			:let var_a = getreginfo()
+			:call setreg('a', var_a)
+<		or: >
 			:let var_a = getreg('a', 1, 1)
 			:let var_amode = getregtype('a')
 			    ....
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 5fddadcf01..5d70834ddc 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1025,6 +1025,7 @@ Various:					*various-functions*
 	undotree()		return the state of the undo tree
 
 	getreg()		get contents of a register
+	getreginfo()		get information about a register
 	getregtype()		get type of a register
 	setreg()		set contents and type of a register
 	reg_executing()		return the name of the register being executed