GNU Info

(emacs-lisp-intro.info)Point and mark

---

Next: Template for save-excursion Prev: save-excursion Up: save-excursion

---

Enter node , (file) or (file)node

Point and Mark
--------------

   Before discussing `save-excursion', however, it may be useful first
to review what point and mark are in GNU Emacs.  "Point" is the current
location of the cursor.  Wherever the cursor is, that is point.  More
precisely, on terminals where the cursor appears to be on top of a
character, point is immediately before the character.  In Emacs Lisp,
point is an integer.  The first character in a buffer is number one,
the second is number two, and so on.  The function `point' returns the
current position of the cursor as a number.  Each buffer has its own
value for point.

   The "mark" is another position in the buffer; its value can be set
with a command such as `C-<SPC>' (`set-mark-command').  If a mark has
been set, you can use the command `C-x C-x' (`exchange-point-and-mark')
to cause the cursor to jump to the mark and set the mark to be the
previous position of point.  In addition, if you set another mark, the
position of the previous mark is saved in the mark ring.  Many mark
positions can be saved this way.  You can jump the cursor to a saved
mark by typing `C-u C-<SPC>' one or more times.

   The part of the buffer between point and mark is called "the
region".  Numerous commands work on the region, including
`center-region', `count-lines-region', `kill-region', and
`print-region'.

   The `save-excursion' special form saves the locations of point and
mark and restores those positions after the code within the body of the
special form is evaluated by the Lisp interpreter.  Thus, if point were
in the beginning of a piece of text and some code moved point to the end
of the buffer, the `save-excursion' would put point back to where it
was before, after the expressions in the body of the function were
evaluated.

   In Emacs, a function frequently moves point as part of its internal
workings even though a user would not expect this.  For example,
`count-lines-region' moves point.  To prevent the user from being
bothered by jumps that are both unexpected and (from the user's point of
view) unnecessary, `save-excursion' is often used to keep point and
mark in the location expected by the user.  The use of `save-excursion'
is good housekeeping.

   To make sure the house stays clean, `save-excursion' restores the
values of point and mark even if something goes wrong in the code inside
of it (or, to be more precise and to use the proper jargon, "in case of
abnormal exit").  This feature is very helpful.

   In addition to recording the values of point and mark,
`save-excursion' keeps track of the current buffer, and restores it,
too.  This means you can write code that will change the buffer and
have `save-excursion' switch you back to the original buffer.  This is
how `save-excursion' is used in `append-to-buffer'.  (Note: The
Definition of `append-to-buffer'.)