@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/positions
@node Positions, Markers, Frames, Top
often speak of the character ``at'' a position, meaning the character
after that position.
- Positions are usually represented as integers starting from 1, but can
-also be represented as @dfn{markers}---special objects that relocate
-automatically when text is inserted or deleted so they stay with the
-surrounding characters. @xref{Markers}.
+ Positions are usually represented as integers starting from 1, but
+can also be represented as @dfn{markers}---special objects that
+relocate automatically when text is inserted or deleted so they stay
+with the surrounding characters. Functions that expect an argument to
+be a position (an integer), but accept a marker as a substitute,
+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
+integer; using it instead of an integer causes an error.
+@xref{Markers}.
+
+ See also the ``field'' feature (@pxref{Fields}), which provides
+functions that are used by many cursor-motion commands.
@menu
* Point:: The special position where editing takes place.
the character on which the cursor sits.
@cindex point with narrowing
- The value of point is a number between 1 and the buffer size plus 1.
-If narrowing is in effect (@pxref{Narrowing}), then point is constrained
-to fall within the accessible portion of the buffer (possibly at one end
-of it).
+ The value of point is a number no less than 1, and no greater than the
+buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then
+point is constrained to fall within the accessible portion of the buffer
+(possibly at one end of it).
Each buffer has its own value of point, which is independent of the
value of point in other buffers. Each window also has a value of point,
This function returns the maximum accessible value of point in the
current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is
in effect, in which case it is the position of the end of the region
-that you narrowed to. (@xref{Narrowing}).
+that you narrowed to. (@xref{Narrowing}.)
@end defun
@defun buffer-end flag
-This function returns @code{(point-min)} if @var{flag} is less than 1,
-@code{(point-max)} otherwise. The argument @var{flag} must be a number.
+This function returns @code{(point-max)} if @var{flag} is greater than
+0, @code{(point-min)} otherwise. The argument @var{flag} must be a
+number.
@end defun
-@defun buffer-size
+@defun buffer-size &optional buffer
This function returns the total number of characters in the current
buffer. In the absence of any narrowing (@pxref{Narrowing}),
@code{point-max} returns a value one larger than this.
+If you specify a buffer, @var{buffer}, then the value is the
+size of @var{buffer}.
+
@example
@group
(buffer-size)
@c @kindex end-of-buffer
This function moves point @var{count} characters forward, towards the
end of the buffer (or backward, towards the beginning of the buffer, if
-@var{count} is negative). If the function attempts to move point past
-the beginning or end of the buffer (or the limits of the accessible
-portion, when narrowing is in effect), an error is signaled with error
-code @code{beginning-of-buffer} or @code{end-of-buffer}.
+@var{count} is negative). If @var{count} is @code{nil}, the default
+is 1.
+
+If this attempts to move past the beginning or end of the buffer (or
+the limits of the accessible portion, when narrowing is in effect), it
+signals an error with error symbol @code{beginning-of-buffer} or
+@code{end-of-buffer}.
In an interactive call, @var{count} is the numeric prefix argument.
@end deffn
@deffn Command backward-char &optional count
-This function moves point @var{count} characters backward, towards the
-beginning of the buffer (or forward, towards the end of the buffer, if
-@var{count} is negative). If the function attempts to move point past
-the beginning or end of the buffer (or the limits of the accessible
-portion, when narrowing is in effect), an error is signaled with error
-code @code{beginning-of-buffer} or @code{end-of-buffer}.
-
-In an interactive call, @var{count} is the numeric prefix argument.
+This is just like @code{forward-char} except that it moves
+in the opposite direction.
@end deffn
@node Word Motion
These functions for parsing words use the syntax table to decide
whether a given character is part of a word. @xref{Syntax Tables}.
-@deffn Command forward-word count
+@deffn Command forward-word &optional count
This function moves point forward @var{count} words (or backward if
-@var{count} is negative). ``Moving one word'' means moving until point
-crosses a word-constituent character and then encounters a
-word-separator character (or the boundary of the accessible part of the
-buffer).
-
-If it is possible to move @var{count} words, without being stopped by
-the buffer boundary (except perhaps after the last word), the value is
-@code{t}. Otherwise, the return value is @code{nil} and point stops
-at the buffer boundary.
-
-In an interactive call, @var{count} is set to the numeric prefix
-argument.
+@var{count} is negative). If @var{count} is @code{nil}, it moves
+forward one word.
+
+``Moving one word'' means moving until point crosses a
+word-constituent character and then encounters a word-separator
+character. However, this function cannot move point past the boundary
+of the accessible portion of the buffer, or across a field boundary
+(@pxref{Fields}). The most common case of a field boundary is the end
+of the prompt in the minibuffer.
+
+If it is possible to move @var{count} words, without being stopped
+prematurely by the buffer boundary or a field boundary, the value is
+@code{t}. Otherwise, the return value is @code{nil} and point stops at
+the buffer boundary or field boundary.
+
+If @code{inhibit-field-text-motion} is non-@code{nil},
+this function ignores field boundaries.
+
+In an interactive call, @var{count} is specified by the numeric prefix
+argument. If @var{count} is omitted or @code{nil}, it defaults to 1.
@end deffn
-@deffn Command backward-word count
+@deffn Command backward-word &optional count
This function is just like @code{forward-word}, except that it moves
backward until encountering the front of a word, rather than forward.
-
-In an interactive call, @var{count} is set to the numeric prefix
-argument.
-
-This function is rarely used in programs, as it is more efficient to
-call @code{forward-word} with a negative argument.
@end deffn
@defvar words-include-escapes
words. Otherwise, they do not.
@end defvar
+@defvar inhibit-field-text-motion
+@tindex inhibit-field-text-motion
+If this variable is non-@code{nil}, certain motion functions including
+@code{forward-word}, @code{forward-sentence}, and
+@code{forward-paragraph} ignore field boundaries.
+@end defvar
+
@node Buffer End Motion
@subsection Motion to an End of the Buffer
@deffn Command beginning-of-buffer &optional n
This function moves point to the beginning of the buffer (or the limits
of the accessible portion, when narrowing is in effect), setting the
-mark at the previous position. If @var{n} is non-@code{nil}, then it
-puts point @var{n} tenths of the way from the beginning of the buffer.
+mark at the previous position (except in Transient Mark mode, if
+the mark is already active, it does not set the mark.)
-In an interactive call, @var{n} is the numeric prefix argument,
-if provided; otherwise @var{n} defaults to @code{nil}.
+If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the
+way from the beginning of the accessible portion of the buffer. In an
+interactive call, @var{n} is the numeric prefix argument, if provided;
+otherwise @var{n} defaults to @code{nil}.
@strong{Warning:} Don't use this function in Lisp programs!
@end deffn
@deffn Command end-of-buffer &optional n
This function moves point to the end of the buffer (or the limits of
the accessible portion, when narrowing is in effect), setting the mark
-at the previous position. If @var{n} is non-@code{nil}, then it puts
-point @var{n} tenths of the way from the end of the buffer.
+at the previous position (except in Transient Mark mode when the mark
+is already active). If @var{n} is non-@code{nil}, then it puts point
+@var{n} tenths of the way from the end of the accessible portion of
+the buffer.
In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.
argument @var{count} not @code{nil} or 1, it moves forward
@var{count}@minus{}1 lines and then to the beginning of the line.
+This function does not move point across a field boundary
+(@pxref{Fields}) unless doing so would move beyond there to a
+different line; therefore, if @var{count} is @code{nil} or 1, and
+point starts at a field boundary, point does not move. To ignore
+field boundaries, either bind @code{inhibit-field-text-motion} to
+@code{t}, or use the @code{forward-line} function instead. For
+instance, @code{(forward-line 0)} does the same thing as
+@code{(beginning-of-line)}, except that it ignores field boundaries.
+
If this function reaches the end of the buffer (or of the accessible
portion, if narrowing is in effect), it positions point there. No error
is signaled.
@end deffn
+@defun line-beginning-position &optional count
+@tindex line-beginning-position
+Return the position that @code{(beginning-of-line @var{count})}
+would move to.
+@end defun
+
@deffn Command end-of-line &optional count
This function moves point to the end of the current line. With an
argument @var{count} not @code{nil} or 1, it moves forward
@var{count}@minus{}1 lines and then to the end of the line.
+This function does not move point across a field boundary
+(@pxref{Fields}) unless doing so would move beyond there to a
+different line; therefore, if @var{count} is @code{nil} or 1, and
+point starts at a field boundary, point does not move. To ignore
+field boundaries, bind @code{inhibit-field-text-motion} to @code{t}.
+
If this function reaches the end of the buffer (or of the accessible
portion, if narrowing is in effect), it positions point there. No error
is signaled.
@end deffn
+@defun line-end-position &optional count
+@tindex line-end-position
+Return the position that @code{(end-of-line @var{count})}
+would move to.
+@end defun
+
@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.
+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
@defun count-lines start end
@cindex lines in region
+@anchor{Definition of count-lines}
This function returns the number of lines between the positions
@var{start} and @var{end} in the current buffer. If @var{start} and
@var{end} are equal, then it returns 0. Otherwise it returns at least
(defun current-line ()
"Return the vertical position of point@dots{}"
(+ (count-lines (window-start) (point))
- (if (= (current-column) 0) 1 0)
- -1))
+ (if (= (current-column) 0) 1 0)))
@end group
@end example
@end defun
+@defun line-number-at-pos &optional pos
+@cindex line number
+This function returns the line number in the current buffer
+corresponding to the buffer position @var{pos}. If @var{pos} is @code{nil}
+or omitted, the current buffer position is used.
+@end defun
+
@ignore
@c ================
The @code{previous-line} and @code{next-line} commands are functions
use them heavily, Emacs provides caches which may improve the
performance of your code. @xref{Truncation, cache-long-line-scans}.
-
@defun vertical-motion count &optional window
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}
@var{window} currently displays some other buffer.
@end defun
+@defun count-screen-lines &optional beg end count-final-newline window
+This function returns the number of screen lines in the text from
+@var{beg} to @var{end}. The number of screen lines may be different
+from the number of actual lines, due to line continuation, the display
+table, etc. If @var{beg} and @var{end} are @code{nil} or omitted,
+they default to the beginning and end of the accessible portion of the
+buffer.
+
+If the region ends with a newline, that is ignored unless the optional
+third argument @var{count-final-newline} is non-@code{nil}.
+
+The optional fourth argument @var{window} specifies the window for
+obtaining parameters such as width, horizontal scrolling, and so on.
+The default is to use the selected window's parameters.
+
+Like @code{vertical-motion}, @code{count-screen-lines} always uses the
+current buffer, regardless of which buffer is displayed in
+@var{window}. This makes possible to use @code{count-screen-lines} in
+any buffer, whether or not it is currently displayed in some window.
+@end defun
+
@deffn Command move-to-window-line count
This function moves point with respect to the text currently displayed
in the selected window. It moves point to the beginning of the screen
the form @code{(@var{hpos} . @var{vpos})}.
The argument @var{width} is the number of columns available to display
-text; this affects handling of continuation lines. Use the value
-returned by @code{window-width} for the window of your choice;
-normally, use @code{(window-width @var{window})}.
+text; this affects handling of continuation lines. @code{nil} means
+the actual number of usable text columns in the window, which is
+equivalent to the value returned by @code{(window-width window)}.
The argument @var{offsets} is either @code{nil} or a cons cell of the
form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
The return value is a list of five elements:
@example
-(@var{pos} @var{vpos} @var{hpos} @var{prevhpos} @var{contin})
+(@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin})
@end example
@noindent
When you use @code{compute-motion} for the minibuffer, you need to use
@code{minibuffer-prompt-width} to get the horizontal position of the
-beginning of the first screen line. @xref{Minibuffer Misc}.
+beginning of the first screen line. @xref{Minibuffer Contents}.
@end defun
@node List Motion
@comment node-name, next, previous, up
-@subsection Moving over Balanced Expressions
+@subsection Moving over Balanced Expressions
@cindex sexp motion
@cindex Lisp expression motion
@cindex list motion
them in Emacs). The syntax table controls how these functions interpret
various characters; see @ref{Syntax Tables}. @xref{Parsing
Expressions}, for lower-level primitives for scanning sexps or parts of
-sexps. For user-level commands, see @ref{Lists Commands,,, emacs, GNU
-Emacs Manual}.
+sexps. For user-level commands, see @ref{Parentheses,, Commands for
+Editing with Parentheses, emacs, The GNU Emacs Manual}.
-@deffn Command forward-list arg
-This function moves forward across @var{arg} balanced groups of
+@deffn Command forward-list &optional arg
+This function moves forward across @var{arg} (default 1) balanced groups of
parentheses. (Other syntactic entities such as words or paired string
quotes are ignored.)
@end deffn
-@deffn Command backward-list arg
-This function moves backward across @var{arg} balanced groups of
+@deffn Command backward-list &optional arg
+This function moves backward across @var{arg} (default 1) balanced groups of
parentheses. (Other syntactic entities such as words or paired string
quotes are ignored.)
@end deffn
-@deffn Command up-list arg
-This function moves forward out of @var{arg} levels of parentheses.
+@deffn Command up-list &optional arg
+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.
@end deffn
-@deffn Command down-list arg
-This function moves forward into @var{arg} levels of parentheses. A
-negative argument means move backward but still go
+@deffn Command down-list &optional arg
+This function moves forward into @var{arg} (default 1) levels of
+parentheses. A negative argument means move backward but still go
deeper in parentheses (@minus{}@var{arg} levels).
@end deffn
-@deffn Command forward-sexp arg
-This function moves forward across @var{arg} balanced expressions.
+@deffn Command forward-sexp &optional arg
+This function moves forward across @var{arg} (default 1) balanced expressions.
Balanced expressions include both those delimited by parentheses and
-other kinds, such as words and string constants. For example,
+other kinds, such as words and string constants
+@xref{Parsing Expressions}. For example,
@example
@group
@end example
@end deffn
-@deffn Command backward-sexp arg
-This function moves backward across @var{arg} balanced expressions.
+@deffn Command backward-sexp &optional arg
+This function moves backward across @var{arg} (default 1) balanced expressions.
@end deffn
-@deffn Command beginning-of-defun arg
+@deffn Command beginning-of-defun &optional arg
This function moves back to the @var{arg}th beginning of a defun. If
@var{arg} is negative, this actually moves forward, but it still moves
-to the beginning of a defun, not to the end of one.
+to the beginning of a defun, not to the end of one. @var{arg} defaults
+to 1.
@end deffn
-@deffn Command end-of-defun arg
+@deffn Command end-of-defun &optional arg
This function moves forward to the @var{arg}th end of a defun. If
@var{arg} is negative, this actually moves backward, but it still moves
-to the end of a defun, not to the beginning of one.
+to the end of a defun, not to the beginning of one. @var{arg} defaults
+to 1.
@end deffn
@defopt defun-prompt-regexp
-If non-@code{nil}, this variable holds a regular expression that
-specifies what text can appear before the open-parenthesis that starts a
-defun. That is to say, a defun begins on a line that starts with a
-match for this regular expression, followed by a character with
-open-parenthesis syntax.
+If non-@code{nil}, this buffer-local variable holds a regular
+expression that specifies what text can appear before the
+open-parenthesis that starts a defun. That is to say, a defun begins
+on a line that starts with a match for this regular expression,
+followed by a character with open-parenthesis syntax.
@end defopt
+@defopt open-paren-in-column-0-is-defun-start
+If this variable's value is non-@code{nil}, an open parenthesis in
+column 0 is considered to be the start of a defun. If it is
+@code{nil}, an open parenthesis in column 0 has no special meaning.
+The default is @code{t}.
+@end defopt
+
+@defvar beginning-of-defun-function
+@tindex beginning-of-defun-function
+If non-@code{nil}, this variable holds a function for finding the
+beginning of a defun. The function @code{beginning-of-defun}
+calls this function instead of using its normal method.
+@end defvar
+
+@defvar end-of-defun-function
+@tindex end-of-defun-function
+If non-@code{nil}, this variable holds a function for finding the end of
+a defun. The function @code{end-of-defun} calls this function instead
+of using its normal method.
+@end defvar
+
@node Skipping Characters
@comment node-name, next, previous, up
@subsection Skipping Characters
characters. For example, they are often used to skip whitespace. For
related functions, see @ref{Motion and Syntax}.
+These functions convert the set string to multibyte if the buffer is
+multibyte, and they convert it to unibyte if the buffer is unibyte, as
+the search functions do (@pxref{Searching and Matching}).
+
@defun skip-chars-forward character-set &optional limit
This function moves point in the current buffer forward, skipping over a
given set of characters. It examines the character following point,
continues until it reaches a character that does not match. The
function returns the number of characters moved over.
-The argument @var{character-set} is like the inside of a
-@samp{[@dots{}]} in a regular expression except that @samp{]} is never
-special and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. Thus,
-@code{"a-zA-Z"} skips over all letters, stopping before the first
-nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before the
-first letter. @xref{Regular Expressions}.
+The argument @var{character-set} is a string, like the inside of a
+@samp{[@dots{}]} in a regular expression except that @samp{]} does not
+terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}.
+Thus, @code{"a-zA-Z"} skips over all letters, stopping before the
+first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before
+the first letter. See @xref{Regular Expressions}. Character classes
+can also be used, e.g. @code{"[:alnum:]"}. See @pxref{Char Classes}.
If @var{limit} is supplied (it must be a number or a marker), it
specifies the maximum position in the buffer that point can be skipped
It is often useful to move point ``temporarily'' within a localized
portion of the program, or to switch buffers temporarily. This is
called an @dfn{excursion}, and it is done with the @code{save-excursion}
-special form. This construct saves the current buffer and its values of
-point and the mark so they can be restored after the completion of the
-excursion.
+special form. This construct initially remembers the identity of the
+current buffer, and its values of point and the mark, and restores them
+after the completion of the excursion.
The forms for saving and restoring the configuration of windows are
described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
Configurations}).
-@defspec save-excursion forms@dots{}
+@defspec save-excursion body@dots{}
@cindex mark excursion
@cindex point excursion
@cindex current buffer excursion
The @code{save-excursion} special form saves the identity of the current
buffer and the values of point and the mark in it, evaluates
-@var{forms}, and finally restores the buffer and its saved values of
+@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 @code{throw} or error (@pxref{Nonlocal Exits}).
use @code{save-window-excursion} inside @code{save-excursion}
(@pxref{Window Configurations}).
-The value returned by @code{save-excursion} is the result of the last of
-@var{forms}, or @code{nil} if no @var{forms} are given.
+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.
@example
@group
-(save-excursion
- @var{forms})
+(save-excursion @var{forms})
@equiv{}
(let ((old-buf (current-buffer))
(old-pnt (point-marker))
+@end group
(old-mark (copy-marker (mark-marker))))
(unwind-protect
(progn @var{forms})
(set-buffer old-buf)
+@group
(goto-char old-pnt)
(set-marker (mark-marker) old-mark)))
@end group
@strong{Warning:} Ordinary insertion of text adjacent to the saved
point value relocates the saved value, just as it relocates all markers.
-Therefore, when the saved point value is restored, it normally comes
-before the inserted text.
+More precisely, the saved value is a marker with insertion 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
of the current region (point and the mark, with the smallest first).
@end deffn
-@deffn Command narrow-to-page move-count
+@deffn Command narrow-to-page &optional move-count
This function sets the accessible portion of the current buffer to
include just the current page. An optional first argument
@var{move-count} non-@code{nil} means to move forward or backward by
value were outside the limits of the temporary narrowing, this would
fail to restore it accurately.
-The @code{save-restriction} special form records the values of the
-beginning and end of the accessible portion as distances from the
-beginning and end of the buffer. In other words, it records the amount
-of inaccessible text before and after the accessible portion.
-
-This method yields correct results if @var{body} does further narrowing.
-However, @code{save-restriction} can become confused if the body widens
-and then makes changes outside the range of the saved narrowing. When
-this is what you want to do, @code{save-restriction} is not the right
-tool for the job. Here is what you must use instead:
-
-@example
-@group
-(let ((beg (point-min-marker))
- (end (point-max-marker)))
- (unwind-protect
- (progn @var{body})
- (save-excursion
- (set-buffer (marker-buffer beg))
- (narrow-to-region beg end))))
-@end group
-@end example
-
Here is a simple example of correct use of @code{save-restriction}:
@example
@end group
@end example
@end defspec
+
+@ignore
+ arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87
+@end ignore