-@c -*-texinfo-*-
+@c -*- mode: texinfo; coding: utf-8 -*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Positions
@chapter Positions
normally ignore which buffer the marker points into; they convert the
marker to an integer, and use that integer, exactly as if you had
passed the integer as the argument, even if the marker points to the
-``wrong'' buffer. A marker that points nowhere cannot convert to an
+wrong buffer. A marker that points nowhere cannot convert to an
integer; using it instead of an integer causes an error.
@xref{Markers}.
- See also the ``field'' feature (@pxref{Fields}), which provides
+ See also the field feature (@pxref{Fields}), which provides
functions that are used by many cursor-motion commands.
@menu
@c Emacs 19 feature
This variable affects the behavior of @code{forward-word} and everything
that uses it. If it is non-@code{nil}, then characters in the
-``escape'' and ``character quote'' syntax classes count as part of
+escape and character-quote syntax classes count as part of
words. Otherwise, they do not.
@end defopt
@deffn Command forward-line &optional count
@cindex beginning of line
This function moves point forward @var{count} lines, to the beginning of
-the line. If @var{count} is negative, it moves point
-@minus{}@var{count} lines backward, to the beginning of a line. If
-@var{count} is zero, it moves point to the beginning of the current
-line. If @var{count} is @code{nil}, that means 1.
+the line following that. If @var{count} is negative, it moves point
+@minus{}@var{count} lines backward, to the beginning of a line
+preceding that. If @var{count} is zero, it moves point to the
+beginning of the current line. If @var{count} is @code{nil}, that
+means 1.
If @code{forward-line} encounters the beginning or end of the buffer (or
of the accessible portion) before finding that many lines, it sets point
@code{forward-line} returns the difference between @var{count} and the
number of lines actually moved. If you attempt to move down five lines
from the beginning of a buffer that has only three lines, point stops at
-the end of the last line, and the value will be 2.
+the end of the last line, and the value will be 2. As an explicit
+exception, if the last accessible line is non-empty, but has no
+newline (e.g., if the buffer ends without a newline), the function
+sets point to the end of that line, and the value returned by the
+function counts that line as one line successfully moved.
In an interactive call, @var{count} is the numeric prefix argument.
@end deffn
@deffn Command previous-line count
@cindex goal column
This function moves point up @var{count} lines (down if @var{count}
-is negative). In moving, it attempts to keep point in the ``goal column''
+is negative). In moving, it attempts to keep point in the @dfn{goal column}
(normally the same column that it was at the beginning of the move).
If there is no character in the target line exactly under the current
@deffn Command next-line count
This function moves point down @var{count} lines (up if @var{count}
-is negative). In moving, it attempts to keep point in the ``goal column''
+is negative). In moving, it attempts to keep point in the goal column
(normally the same column that it was at the beginning of the move).
If there is no character in the target line exactly under the current
improve the performance of your code. @xref{Truncation, cache-long-scans}.
@end ignore
-@defun vertical-motion count &optional window
+@defun vertical-motion count &optional window cur-col
This function moves point to the start of the screen line @var{count}
screen lines down from the screen line containing point. If @var{count}
is negative, it moves up instead.
width, the horizontal scrolling, and the display table. But
@code{vertical-motion} always operates on the current buffer, even if
@var{window} currently displays some other buffer.
+
+The optional argument @var{cur-col} specifies the current column when
+the function is called. This is the window-relative horizontal
+coordinate of point, measured in units of font width of the frame's
+default face. Providing it speeds up the function, especially in very
+long lines, because it doesn't have to go back in the buffer in order
+to determine the current column. Note that @var{cur-col} is also
+counted from the visual start of the line.
@end defun
@defun count-screen-lines &optional beg end count-final-newline window
the top line in the window numbered 0.
@end deffn
+@vindex move-to-window-group-line-function
+@defun move-to-window-group-line count
+This function is like @code{move-to-window-line}, except that when the
+selected window is a part of a group of windows (@pxref{Window
+Group}), @code{move-to-window-group-line} will move to a position with
+respect to the entire group, not just the single window. This
+condition holds when the buffer local variable
+@code{move-to-window-group-line-function} is set to a function. In
+this case, @code{move-to-window-group-line} calls the function with
+the argument @var{count}, then returns its result.
+@end defun
+
@defun compute-motion from frompos to topos width offsets window
This function scans the current buffer, calculating screen positions.
It scans the buffer forward from position @var{from}, assuming that is
This function moves forward out of @var{arg} (default 1) levels of
parentheses. A negative argument means move backward but still to a
less deep spot. If @var{escape-strings} is non-@code{nil} (as it is
-interactively), move out of enclosing strings as well. If
+interactively), move out of enclosing strings as well. If
@var{no-syntax-crossing} is non-@code{nil} (as it is interactively), prefer
to break out of any enclosing string instead of moving to the start of
a list broken across multiple strings. On error, location of point is
@section Excursions
@cindex excursion
- It is often useful to move point ``temporarily'' within a localized
+ It is often useful to move point temporarily within a localized
portion of the program. This is called an @dfn{excursion}, and it is
done with the @code{save-excursion} special form. This construct
-remembers the initial identity of the current buffer, and its values
-of point and the mark, and restores them after the excursion
+remembers the initial identity of the current buffer, and its value
+of point, and restores them after the excursion
completes. It is the standard way to move point within one part of a
program and avoid affecting the rest of the program, and is used
thousands of times in the Lisp sources of Emacs.
Configurations} and in @ref{Frame Configurations}. @c frameset?
@defspec save-excursion body@dots{}
-@cindex mark excursion
@cindex point excursion
This special form saves the identity of the current buffer and the
-values of point and the mark in it, evaluates @var{body}, and finally
-restores the buffer and its saved values of point and the mark. All
-three saved values are restored even in case of an abnormal exit via
+value of point in it, evaluates @var{body}, and finally
+restores the buffer and its saved value of point. Both saved values are
+restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
The value returned by @code{save-excursion} is the result of the last
form in @var{body}, or @code{nil} if no body forms were given.
@end defspec
- Because @code{save-excursion} only saves point and mark for the
+ Because @code{save-excursion} only saves point for the
buffer that was current at the start of the excursion, any changes
-made to point and/or mark in other buffers, during the excursion, will
+made to point in other buffers, during the excursion, will
remain in effect afterward. This frequently leads to unintended
consequences, so the byte compiler warns if you call @code{set-buffer}
during an excursion:
@example
-Warning: Use `with-current-buffer' rather than
+Warning: Use ‘with-current-buffer’ rather than
save-excursion+set-buffer
@end example
saved point value is restored, it normally comes before the inserted
text.
- Although @code{save-excursion} saves the location of the mark, it does
-not prevent functions which modify the buffer from setting
-@code{deactivate-mark}, and thus causing the deactivation of the mark
-after the command finishes. @xref{The Mark}.
+@defmac save-mark-and-excursion body@dots{}
+@cindex mark excursion
+@cindex point excursion
+This macro is like @code{save-excursion}, but also saves and restores
+the mark location and @code{mark-active}. This macro does what
+@code{save-excursion} did before Emacs 25.1.
+@end defmac
@node Narrowing
@section Narrowing
restrictions it saved from), but it does not restore the identity of the
current buffer.
-@code{save-restriction} does @emph{not} restore point and the mark; use
+@code{save-restriction} does @emph{not} restore point; use
@code{save-excursion} for that. If you use both @code{save-restriction}
and @code{save-excursion} together, @code{save-excursion} should come
first (on the outside). Otherwise, the old point value would be