master 210b10f 2/3: Add new function 'insert-into-buffer'

[Lars Ingebrigtsen]

branch: master
commit 210b10f3fe7d2b847f7af31276c05001c8fc0ed7
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    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 feb9e58..6fbb475 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 a3f1283..a0b6225 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 e49c277..c7e1864 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.