Add new function 'insert-into-buffer'

* doc/lispref/text.texi (Insertion): Document it.
* lisp/subr.el (insert-into-buffer): New function.

3 files changed, 21 insertions, 0 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index feb9e58f31c..6fbb475a325 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -502,6 +502,15 @@ This is like @code{insert-buffer-substring} except that it does not
 copy any text properties.
 @end defun
 
+@defun insert-into-buffer to-buffer &optional start end
+This is like @code{insert-buffer-substring}, but works in the opposite
+direction: The text is copied from the current buffer into
+@var{to-buffer}.  The block of text is copied to the current point in
+@var{to-buffer}, and point (in that buffer) is advanced to after the
+end of the copied text.  Is @code{start}/@code{end} is @code{nil}, the
+entire text in the current buffer is copied over.
+@end defun
+
   @xref{Sticky Properties}, for other insertion functions that inherit
 text properties from the nearby text in addition to inserting it.
 Whitespace inserted by indentation functions also inherits text
diff --git a/etc/NEWS b/etc/NEWS
index a3f12837f78..a0b62250d89 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2186,6 +2186,10 @@ summaries will include the failing condition.
 ** Miscellaneous
 
 +++
+*** New utility function 'insert-into-buffer'.
+This is like 'insert-into-buffer', but works in the opposite direction.
+
++++
 *** New user option 'lock-file-name-transforms'.
 This option allows controlling where lock files are written.  It uses
 the same syntax as 'auto-save-file-name-transforms'.
diff --git a/lisp/subr.el b/lisp/subr.el
index e49c2773357..c7e18646bfb 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -3850,6 +3850,14 @@ Before insertion, process text properties according to
     (insert-buffer-substring buffer start end)
     (remove-yank-excluded-properties opoint (point))))
 
+(defun insert-into-buffer (buffer &optional start end)
+  "Insert the contents of the current buffer into BUFFER.
+If START/END, only insert that region from the current buffer.
+Point in BUFFER will be placed after the inserted text."
+  (let ((current (current-buffer)))
+    (with-current-buffer buffer
+      (insert-buffer-substring current start end))))
+
 (defun yank-handle-font-lock-face-property (face start end)
   "If `font-lock-defaults' is nil, apply FACE as a `face' property.
 START and END denote the start and end of the text to act on.