From 210b10f3fe7d2b847f7af31276c05001c8fc0ed7 Mon Sep 17 00:00:00 2001
From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Tue, 13 Jul 2021 23:46:16 +0200
Subject: [PATCH] Add new function 'insert-into-buffer'

* doc/lispref/text.texi (Insertion): Document it.
* lisp/subr.el (insert-into-buffer): New function.
---
 doc/lispref/text.texi | 9 +++++++++
 etc/NEWS              | 4 ++++
 lisp/subr.el          | 8 ++++++++
 3 files changed, 21 insertions(+)

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
@@ -500,6 +500,15 @@ We hold these truth@point{}
 @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
 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
diff --git a/etc/NEWS b/etc/NEWS
index a3f12837f78..a0b62250d89 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2185,6 +2185,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
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.
-- 
2.39.2