@c -*-texinfo-*-
@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
@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
@node Screen Lines
@subsection Motion by Screen Lines
+@cindex screen lines, moving by
The line functions in the previous section count text lines, delimited
only by newline characters. By contrast, these functions count screen
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
@deffn Command up-list &optional arg escape-strings no-syntax-crossing
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-nil (as it is
-interactively), move out of enclosing strings as well. If
-@var{no-syntax-crossing} is non-nil (as it is interactively), prefer
+less deep spot. If @var{escape-strings} is non-@code{nil} (as it is
+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
unspecified.
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.
@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:
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