X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/a859d1cc237eca05a8db2ccde69db9da1dc9e39c..eb0f65b4fbbea60100b53cb40a1d7138d47ad0d2:/doc/lispref/positions.texi diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index e32f0ef0b3..c972bbb2e4 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -1,6 +1,6 @@ @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 @@ -350,10 +350,11 @@ would move to. @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 @@ -362,7 +363,11 @@ there. No error is signaled. @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 @@ -465,6 +470,7 @@ beginning or end of a line. @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 @@ -492,7 +498,7 @@ If you intend to use them heavily, Emacs provides caches which may 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. @@ -514,6 +520,14 @@ The window @var{window} is used for obtaining parameters such as the 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 @@ -654,9 +668,9 @@ quotes are ignored.) @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. @@ -816,8 +830,8 @@ is zero or less. 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. @@ -832,18 +846,18 @@ Configurations} and in @ref{Frame Configurations}. @c frameset? @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: @@ -879,10 +893,13 @@ type @code{nil}. @xref{Marker Insertion Types}. Therefore, when the 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 @@ -971,7 +988,7 @@ restores the restrictions on the original buffer (the buffer whose 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