X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/2616f5532c55807de343a3c1780d751782a0c699..b3ab615bc11f85df1a242dbdebd713a3ac5534e9:/lispref/positions.texi

diff --git a/lispref/positions.texi b/lispref/positions.texi
index 998dddd4d1..3c1e642e6b 100644
--- a/lispref/positions.texi
+++ b/lispref/positions.texi
@@ -1,6 +1,7 @@
 @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  Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/positions
 @node Positions, Markers, Frames, Top
@@ -14,10 +15,20 @@ speak of the character before or after a given position.  However, we
 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.
@@ -42,10 +53,10 @@ the character that immediately follows point; point is actually before
 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,
@@ -81,19 +92,23 @@ is the position of the start of the region that you narrowed to.
 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)
@@ -153,23 +168,20 @@ minibuffer.
 @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
@@ -178,31 +190,33 @@ In an interactive call, @var{count} is the numeric prefix argument.
   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
@@ -213,6 +227,13 @@ that uses it.  If it is non-@code{nil}, then characters in the
 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
 
@@ -240,11 +261,13 @@ they set the mark and display messages in the echo area.
 @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
@@ -252,8 +275,10 @@ if provided; otherwise @var{n} defaults to @code{nil}.
 @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}.
@@ -305,6 +330,15 @@ This function moves point to the beginning 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 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.
@@ -321,6 +355,12 @@ 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.
@@ -338,7 +378,7 @@ 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
@@ -354,6 +394,7 @@ In an interactive call, @var{count} is the numeric prefix argument.
 
 @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
@@ -368,12 +409,18 @@ Here is an example of using @code{count-lines}:
 (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 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
@@ -469,7 +516,6 @@ thus take time proportional to the distance scanned.  If you intend to
 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}
@@ -485,6 +531,27 @@ width, the horizontal scrolling, and the display table.  But
 @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
@@ -517,9 +584,9 @@ The coordinate arguments @var{frompos} and @var{topos} are cons cells of
 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
@@ -537,7 +604,7 @@ regardless of what buffer is displayed in @var{window}.
 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
@@ -574,7 +641,7 @@ beginning of the first screen line.  @xref{Minibuffer Misc}.
 
 @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
@@ -584,36 +651,37 @@ expressions (also called @dfn{sexps} in connection with moving across
 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
@@ -633,20 +701,22 @@ other kinds, such as words and string constants.  For example,
 @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
@@ -657,6 +727,27 @@ 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
@@ -666,6 +757,10 @@ open-parenthesis syntax.
 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,
@@ -673,12 +768,13 @@ then advances point if the character matches @var{character-set}.  This
 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
@@ -725,9 +821,9 @@ is zero or less.
   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
@@ -782,8 +878,9 @@ The value returned by @code{save-excursion} is the result of the last of
 
   @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
@@ -824,7 +921,7 @@ In an interactive call, @var{start} and @var{end} are set to the bounds
 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
@@ -876,29 +973,6 @@ restored with temporary narrowing still in effect.  If the old point
 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
@@ -927,3 +1001,7 @@ This is the contents of foo@point{}
 @end group
 @end example
 @end defspec
+
+@ignore
+   arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87
+@end ignore