GNU Info

(emacs-lisp-intro.info)copy-to-buffer

---

Next: insert-buffer Prev: More Complex Up: More Complex

---

Enter node , (file) or (file)node

The Definition of `copy-to-buffer'
==================================

   After understanding how `append-to-buffer' works, it is easy to
understand `copy-to-buffer'.  This function copies text into a buffer,
but instead of adding to the second buffer, it replaces the previous
text in the second buffer.  The code for the `copy-to-buffer' function
is almost the same as the code for `append-to-buffer', except that
`erase-buffer' and a second `save-excursion' are used.  (Note: The
Definition of `append-to-buffer', for the description
of `append-to-buffer'.)

   The body of `copy-to-buffer' looks like this

     ...
     (interactive "BCopy to buffer: \nr")
       (let ((oldbuf (current-buffer)))
         (save-excursion
           (set-buffer (get-buffer-create buffer))
           (erase-buffer)
           (save-excursion
             (insert-buffer-substring oldbuf start end)))))

   This code is similar to the code in `append-to-buffer': it is only
after changing to the buffer to which the text will be copied that the
definition for this function diverges from the definition for
`append-to-buffer': the `copy-to-buffer' function erases the buffer's
former contents.  (This is what is meant by `replacement'; to replace
text, Emacs erases the previous text and then inserts new text.)  After
erasing the previous contents of the buffer, `save-excursion' is used
for a second time and the new text is inserted.

   Why is `save-excursion' used twice?  Consider again what the
function does.

   In outline, the body of `copy-to-buffer' looks like this:

     (let (BIND-`oldbuf'-TO-VALUE-OF-`current-buffer')
       (save-excursion         ; First use of `save-excursion'.
         CHANGE-BUFFER
           (erase-buffer)
           (save-excursion     ; Second use of `save-excursion'.
             INSERT-SUBSTRING-FROM-`oldbuf'-INTO-BUFFER)))

   The first use of `save-excursion' returns Emacs to the buffer from
which the text is being copied.  That is clear, and is just like its use
in `append-to-buffer'.  Why the second use?  The reason is that
`insert-buffer-substring' always leaves point at the _end_ of the
region being inserted.  The second `save-excursion' causes Emacs to
leave point at the beginning of the text being inserted.  In most
circumstances, users prefer to find point at the beginning of inserted
text.  (Of course, the `copy-to-buffer' function returns the user to
the original buffer when done--but if the user _then_ switches to the
copied-to buffer, point will go to the beginning of the text.  Thus,
this use of a second `save-excursion' is a little nicety.)