X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/37680279159b37e6bcb20039988aff6a26204ad4..27c5714a63cac48fd2eaa28543d206c24967f365:/lispref/positions.texi

diff --git a/lispref/positions.texi b/lispref/positions.texi
index 0680dd3ead..f56e1a6a38 100644
--- a/lispref/positions.texi
+++ b/lispref/positions.texi
@@ -1,7 +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, 1999
-@c  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
@@ -15,13 +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 cursur-motion commands.
+functions that are used by many cursor-motion commands.
 
 @menu
 * Point::         The special position where editing takes place.
@@ -89,8 +96,9 @@ 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 &optional buffer
@@ -160,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
@@ -185,14 +190,17 @@ 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.  However, this function cannot move point past
-the boundary of the accessible part 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.
+@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
@@ -203,18 +211,12 @@ 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.
+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
@@ -259,22 +261,24 @@ 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
-accessible portion 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 accessible portion of the
-buffer.
+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 (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}.
@@ -326,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.
@@ -342,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.
@@ -359,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
@@ -375,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
@@ -389,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 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
@@ -490,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}
@@ -506,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
@@ -538,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
@@ -558,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
@@ -590,12 +636,12 @@ the end of the accessible portion of the buffer, and pass @var{line} and
 
 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
@@ -605,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, The 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
@@ -654,30 +701,53 @@ 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
-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
@@ -687,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,
@@ -694,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
@@ -754,13 +829,13 @@ after the completion of the excursion.
 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}).
 
@@ -780,8 +855,8 @@ One way to restore these correspondences, and the selected window, is to
 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
@@ -803,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
@@ -845,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
@@ -897,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
@@ -948,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