@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Positions
@chapter Positions
@cindex position (in buffer)
+@cindex buffer position
A @dfn{position} is the index of a character in the text of a buffer.
More precisely, a position identifies the place between two characters
@deffn Command goto-char position
This function sets point in the current buffer to the value
-@var{position}. If @var{position} is less than 1, it moves point to the
-beginning of the buffer. If @var{position} is greater than the length
-of the buffer, it moves point to the end.
+@var{position}.
+@c This behavior used to be documented until 2013/08.
+@ignore
+If @var{position} is less than 1, it moves point to the beginning of
+the buffer. If @var{position} is greater than the length of the
+buffer, it moves point to the end.
+@end ignore
If narrowing is in effect, @var{position} still counts from the
beginning of the buffer, but point cannot go outside the accessible
@deffn Command forward-word &optional count
This function moves point forward @var{count} words (or backward if
-@var{count} is negative). If @var{count} is @code{nil}, it moves
-forward one word.
+@var{count} is negative). If @var{count} is omitted or @code{nil}, it
+defaults to 1.
``Moving one word'' means moving until point crosses a
word-constituent character and then encounters a word-separator
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.
+argument.
@end deffn
@deffn Command backward-word &optional count
Display}.
These functions scan text to determine where screen lines break, and
-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}.
+thus take time proportional to the distance scanned.
+@ignore
+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
This function moves point to the start of the screen line @var{count}
The @var{count} argument can be a cons cell, @code{(@var{cols}
. @var{lines})}, instead of an integer. Then the function moves by
@var{lines} screen lines, and puts point @var{cols} columns from the
-start of that screen line.
+visual start of that screen line. Note that @var{cols} are counted
+from the @emph{visual} start of the line; if the window is scrolled
+horizontally (@pxref{Horizontal Scrolling}), the column on which point
+will end is in addition to the number of columns by which the text is
+scrolled.
The return value is the number of screen lines over which point was
moved. The value may be less in absolute value than @var{count} if
quotes are ignored.)
@end deffn
-@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.
+@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
+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.
+@end deffn
+
+@deffn Command backward-up-list &optional arg escape-strings no-syntax-crossing
+This function is just like @code{up-list}, but with a negated argument.
@end deffn
@deffn Command down-list &optional arg
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}.
+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
buffer, use @code{save-current-buffer} or @code{with-current-buffer}
instead (@pxref{Current Buffer}). If you need to save or restore
window configurations, see the forms described in @ref{Window
-Configurations} and in @ref{Frame Configurations}.
+Configurations} and in @ref{Frame Configurations}. @c frameset?
@defspec save-excursion body@dots{}
@cindex mark excursion
@cindex window excursions
Likewise, @code{save-excursion} does not restore window-buffer
correspondences altered by functions such as @code{switch-to-buffer}.
-One way to restore these correspondences, and the selected window, is to
-use @code{save-window-excursion} inside @code{save-excursion}
-(@pxref{Window Configurations}).
@strong{Warning:} Ordinary insertion of text adjacent to the saved
point value relocates the saved value, just as it relocates all
remains addressable is called the @dfn{accessible portion} of the
buffer.
- Narrowing is specified with two buffer positions which become the
-beginning and end of the accessible portion. For most editing commands
-and most Emacs primitives, these positions replace the values of the
-beginning and end of the buffer. While narrowing is in effect, no text
-outside the accessible portion is displayed, and point cannot move
-outside the accessible portion.
-
- Values such as positions or line numbers, which usually count from the
-beginning of the buffer, do so despite narrowing, but the functions
-which use them refuse to operate on text that is inaccessible.
-
- The commands for saving buffers are unaffected by narrowing; they save
+ Narrowing is specified with two buffer positions, which become the
+beginning and end of the accessible portion. For most editing
+commands and primitives, these positions replace the values of the
+beginning and end of the buffer. While narrowing is in effect, no
+text outside the accessible portion is displayed, and point cannot
+move outside the accessible portion. Note that narrowing does not
+alter actual buffer positions (@pxref{Point}); it only determines
+which positions are considered the accessible portion of the buffer.
+Most functions refuse to operate on text that is outside the
+accessible portion.
+
+ Commands for saving buffers are unaffected by narrowing; they save
the entire buffer regardless of any narrowing.
If you need to display in a single buffer several very different
@end example
@end deffn
+@defun buffer-narrowed-p
+This function returns non-@code{nil} if the buffer is narrowed, and
+@code{nil} otherwise.
+@end defun
+
@defspec save-restriction body@dots{}
This special form saves the current bounds of the accessible portion,
evaluates the @var{body} forms, and finally restores the saved bounds,
HCoop / bpt / emacs.git / blobdiff