@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/positions
-@node Positions, Markers, Frames, Top
+@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
1, even if @var{start} and @var{end} are on the same line. This is
because the text between them, considered in isolation, must contain at
least one line unless it is empty.
+@end defun
-Here is an example of using @code{count-lines}:
+@deffn Command count-words start end
+@cindex words in region
+This function returns the number of words between the positions
+@var{start} and @var{end} in the current buffer.
-@example
-@group
-(defun current-line ()
- "Return the vertical position of point@dots{}"
- (+ (count-lines (window-start) (point))
- (if (= (current-column) 0) 1 0)))
-@end group
-@end example
-@end defun
+This function can also be called interactively. In that case, it
+prints a message reporting the number of lines, words, and characters
+in the buffer, or in the region if the region is active.
+@end deffn
@defun line-number-at-pos &optional pos
@cindex line number
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}
@end defun
@node List Motion
-@comment node-name, next, previous, up
@subsection Moving over Balanced Expressions
@cindex sexp motion
@cindex Lisp expression motion
@end defvar
@node Skipping Characters
-@comment node-name, next, previous, up
@subsection Skipping Characters
@cindex skipping characters
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
during an excursion:
@example
-Warning: @code{save-excursion} defeated by @code{set-buffer}
+Warning: Use `with-current-buffer' rather than
+ save-excursion+set-buffer
@end example
@noindent
@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