X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/3a4208096f1e82d4295a5fb2ae19e7866d2407b1..d3c91027f319adabab13e92f645fd4e7503ca3d1:/lispref/positions.texi diff --git a/lispref/positions.texi b/lispref/positions.texi index 67e33cb2cb..22a800a221 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, 2000 -@c 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 @@ -18,10 +18,14 @@ 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}. +surrounding characters. Functions that expect an argument to be a +position (an integer), but accept a marker as a substitute, normally +ignore the marker buffer. Of course, markers used this way usually +point to a position in the buffer that the function operates on, but +that is entirely the programmer's responsibility. @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 +93,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 @@ -185,7 +190,7 @@ 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 @@ -203,19 +208,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. - -@c [Now optimized by compiler.] -@c This function is rarely used in programs, as it is more efficient to -@c call @code{forward-word} with a negative argument. @end deffn @defvar words-include-escapes @@ -327,6 +325,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. @@ -343,6 +350,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. @@ -390,12 +403,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 @@ -579,7 +598,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 @@ -616,7 +635,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 @@ -626,8 +645,8 @@ 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 &optional arg This function moves forward across @var{arg} (default 1) balanced groups of @@ -647,15 +666,16 @@ A negative argument means move backward but still to a less deep spot. @end deffn @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 +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 &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 @@ -679,13 +699,13 @@ other kinds, such as words and string constants. For example, 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. @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. @@ -729,6 +749,10 @@ of using its normal method. 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, @@ -770,6 +794,15 @@ comes back" twice. ---------- Buffer: foo ---------- @end group @end example + +Note that char classes are not currently supported in +@var{character-set}; they will be treated as literals. Thus you +cannot use @code{"[:alpha:]"} instead of @code{"a-zA-Z"} to include +non-@acronym{ASCII} letters. A way to skip forward over all letters is: + +@example +(re-search-forward "\\=[[:alpha:]]*" nil t) +@end example @end defun @defun skip-chars-backward character-set &optional limit @@ -845,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 @@ -887,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 @@ -967,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