comparison lispref/positions.texi @ 7729:a1c07008521d

*** empty log message ***

7728:23f5b77e3773

@setfilename ../info/positions
@node Positions, Markers, Frames, Top
@chapter Positions
@cindex position (in buffer)

  A @dfn{position} is the index of a character in the text of buffer.
More precisely, a position identifies the place between two characters
(or before the first character, or after the last character), so we can
speak of the character before or after a given position.  However, the
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 which relocate
automatically when text is inserted or deleted so they stay with the
surrounding characters.  @xref{Markers}.

@menu
* Point::         The special position where editing takes place.

so the distinction is rarely important.  @xref{Window Point}, for more
details.

@defun point
@cindex current buffer position
  This function returns the position of point in the current buffer,
as an integer.

@need 700
@example
@group

@end group
@end example
@end defun

@defun point-min
  This function returns the minimum accessible value of point in the
current buffer.  This is 1, unless narrowing is in effect, in
which case it is the position of the start of the region that you
narrowed to.  (@xref{Narrowing}.)
@end defun

@defun point-max
  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}).
@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.
@end defun

@defun buffer-size
  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.

@example
@group

@node Character Motion
@subsection Motion by Characters

  These functions move point based on a count of characters.
@code{goto-char} is the fundamental primitive; the functions others use
that.

@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

In an interactive call, @var{count} is set to the numeric prefix
argument.
@end deffn

@deffn Command backward-word count
This function 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 negative argument.
@end deffn

@defvar words-include-escapes
@c Emacs 19 feature
This variable affects the behavior of @code{forward-word} and everything

@group
(goto-char (point-max))
@end group
@end example

  Here are two commands which users use to do these things.  They are
documented here to warn you not to use them in Lisp programs, because
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

@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.

In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.

Don't use this function in Lisp programs!

of the window, by line continuation in display, or by how tabs and
control characters are displayed.

@deffn Command goto-line line
This function moves point to the front of the @var{line}th line,
counting from line 1 at beginning of buffer.  If @var{line} is less than
1, it moves point to the beginning of the buffer.  If @var{line} is
greater than the number of lines in the buffer, it moves point to the
@emph{end of the last line} of the buffer.

If narrowing is in effect, then @var{line} still counts from the
beginning of the buffer, but point cannot go outside the accessible
portion.  So @code{goto-line} moves point to the beginning or end of the
accessible portion, if the line number specifies an inaccessible
position.

The return value of @code{goto-line} is the difference between
@var{line} and the line number of the line to which point actually was
able move (in the full buffer, disregarding any narrowing).  Thus, the
value is positive if the scan encounters the real end of the buffer.

In an interactive call, @var{line} is the numeric prefix argument if
one has been provided.  Otherwise @var{line} is read in the minibuffer.
@end deffn

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.

If this function reaches the end of the buffer (or of the accessible
portion, if narrowing is in effect), it positions point at the end of
the buffer.  No error is signaled.
@end deffn

@deffn Command end-of-line &optional count
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.

If this function reaches the end of the buffer (or of the accessible
portion, if narrowing is in effect), it positions point at the end of
the buffer.  No error is signaled.
@end deffn

@deffn Command forward-line &optional count
@cindex beginning of line
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 the line.

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
there.  No error is signaled.

  In some cases, text lines are truncated on the screen rather than
continued onto additional screen lines.  In these cases,
@code{vertical-motion} moves point much like @code{forward-line}.
@xref{Truncation}.

  Because the width of a given string depends on the flags which control
the appearance of certain characters, @code{vertical-motion} behaves
differently, for a given piece of text, depending on the buffer it is
in, and even on the selected window (because the width, the truncation
flag, and display table may vary between windows).  @xref{Usual
Display}.

@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
line @var{count} screen lines from the top of the window.  If
@var{count} is negative, that specifies a position
@w{@minus{}@var{count}} lines from the bottom---or else the last line of
the buffer, if the buffer ends above the specified screen position.

If @var{count} is @code{nil}, then point moves to the beginning of the
line in the middle of the window.  If the absolute value of @var{count}
is greater than the size of the window, then point moves to the place
which would appear on that screen line if the window were tall enough.
This will probably cause the next redisplay to scroll to bring that
location onto the screen.

In an interactive call, @var{count} is the numeric prefix argument.

The value returned is the window line number, with the top line in the
window numbered 0.
@end deffn

@defun compute-motion from frompos to topos width offsets window
This function scan through the current buffer, calculating screen
position.  It scans the current buffer forward from position @var{from},
assuming that is at screen coordinates @var{frompos}, to position
@var{to} or coordinates @var{topos}, whichever comes first.  It returns
the ending buffer position and screen coordinates.

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

@var{tab-offset} is the offset between column numbers on the screen and
column numbers in the buffer.  This can be nonzero in a continuation
line, when the previous screen lines' widths do not add up to a multiple
of @code{tab-width}.  It is always zero in a non-continuation line.

The window @var{window} serves to specify which display table to use;
that is its only effect.  @code{compute-motion} always operates on the
current buffer, 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})
@end example

@noindent
Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
is the vertical position, and @var{hpos} is the horizontal position.

The result @var{prevhpos} is the horizontal position one character back
from @var{pos}.  The result @var{contin} is @code{t} if a line was
continued after (or within) the previous character.

For example, to find the buffer position of column @var{col} of line
@var{line} of a certain window, pass the window's display start location
as @var{from} and the window's upper-left coordinates as @var{frompos}.
Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
the end of the visible section of the buffer, and pass @var{line} and
@var{col} as @var{topos}.  Here's a function that does this:

@example
(defun coordinates-of-position (col line)
  (car (compute-motion (window-start)
                       '(0 . 0)
                       (point)
                       (cons col line)
                       (window-width)
                       (cons (window-hscroll) 0))))
@end example

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}.

@defopt track-eol
This variable controls how the vertical line motion commands operate
when starting at the end of a line.  If @code{track-eol} is
non-@code{nil}, then vertical motion starting at the end of a line will
keep to the ends of lines.  This means moving to the end of each line
moved onto.  The value of @code{track-eol} has no effect if point is not
at the end of a line when the first vertical motion command is given.

@code{track-eol} has its effect by telling line motion commands to set
@code{temporary-goal-column} to 9999 instead of to the current column.
@end defopt

This function moves forward out of @var{arg} 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 down @var{arg} levels of parentheses.  A
negative argument means move backward but still go down @var{arg}
levels.
@end deffn

@deffn Command forward-sexp arg
This function moves forward across @var{arg} balanced expressions.
Balanced expressions include both those delimited by parentheses and

@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
Move 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.
@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, the a defun begins on a line which starts
with a match for this regular expression, followed by a character
with open-parenthesis syntax.
@end defopt

@node Skipping Characters
@comment  node-name,  next,  previous,  up
@subsection Skipping Characters

@defspec save-excursion forms@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 point and the mark.
All three saved values are restored even in case of an abnormal exit
via throw or error (@pxref{Nonlocal Exits}).

The @code{save-excursion} special form is the standard way to switch
buffers or move point within one part of a program and avoid affecting
the rest of the program.  It is used more than 500 times in the Lisp
sources of Emacs.

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, that 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
the entire buffer regardless of the any narrowing.

@deffn Command narrow-to-region start end
This function sets the accessible portion of the current buffer to start
at @var{start} and end at @var{end}.  Both arguments should be character
positions.

@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,
thus restoring the same state of narrowing (or absence thereof) formerly
in effect.  The state of narrowing is restored even in the event of an
abnormal exit via throw or error (@pxref{Nonlocal Exits}).  Therefore,
this construct is a clean way to narrow a buffer temporarily.

The value returned by @code{save-restriction} is that returned by the
last form in @var{body}, or @code{nil} if no body forms were given.

@c Wordy to avoid overfull hbox.  --rjc 16mar92

7729:a1c07008521d

@setfilename ../info/positions
@node Positions, Markers, Frames, Top
@chapter Positions
@cindex position (in buffer)

  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
(or before the first character, or after the last character), so we can
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}.

@menu
* Point::         The special position where editing takes place.

so the distinction is rarely important.  @xref{Window Point}, for more
details.

@defun point
@cindex current buffer position
This function returns the value of point in the current buffer,
as an integer.

@need 700
@example
@group

@end group
@end example
@end defun

@defun point-min
This function returns the minimum accessible value of point in the
current buffer.  This is normally 1, but if narrowing is in effect, it
is the position of the start of the region that you narrowed to.
(@xref{Narrowing}.)
@end defun

@defun point-max
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}).
@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.
@end defun

@defun buffer-size
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.

@example
@group

@node Character Motion
@subsection Motion by Characters

  These functions move point based on a count of characters.
@code{goto-char} is the fundamental primitive; the other functions use
that.

@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

In an interactive call, @var{count} is set to the numeric prefix
argument.
@end deffn

@deffn Command backward-word 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
@c Emacs 19 feature
This variable affects the behavior of @code{forward-word} and everything

@group
(goto-char (point-max))
@end group
@end example

  Here are two commands that users use to do these things.  They are
documented here to warn you not to use them in Lisp programs, because
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

@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.

In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.

Don't use this function in Lisp programs!

of the window, by line continuation in display, or by how tabs and
control characters are displayed.

@deffn Command goto-line line
This function moves point to the front of the @var{line}th line,
counting from line 1 at beginning of the buffer.  If @var{line} is less
than 1, it moves point to the beginning of the buffer.  If @var{line} is
greater than the number of lines in the buffer, it moves point to the
end of the buffer---that is, the @emph{end of the last line} of the
buffer.  This is the only case in which @code{goto-line} does not
necessarily move to the beginning of a line.

If narrowing is in effect, then @var{line} still counts from the
beginning of the buffer, but point cannot go outside the accessible
portion.  So @code{goto-line} moves point to the beginning or end of the
accessible portion, if the line number specifies an inaccessible
position.

The return value of @code{goto-line} is the difference between
@var{line} and the line number of the line to which point actually was
able to move (in the full buffer, before taking account of narrowing).
Thus, the value is positive if the scan encounters the real end of the
buffer.  The value is zero if scan encounters the end of the accessible
portion but not the real end of the buffer.

In an interactive call, @var{line} is the numeric prefix argument if
one has been provided.  Otherwise @var{line} is read in the minibuffer.
@end deffn

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.

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.
@end deffn

@deffn Command end-of-line &optional count
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.

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.
@end deffn

@deffn Command forward-line &optional count
@cindex beginning of line
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.

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
there.  No error is signaled.

  In some cases, text lines are truncated on the screen rather than
continued onto additional screen lines.  In these cases,
@code{vertical-motion} moves point much like @code{forward-line}.
@xref{Truncation}.

  Because the width of a given string depends on the flags that control
the appearance of certain characters, @code{vertical-motion} behaves
differently, for a given piece of text, depending on the buffer it is
in, and even on the selected window (because the width, the truncation
flag, and display table may vary between windows).  @xref{Usual
Display}.

@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
line @var{count} screen lines from the top of the window.  If
@var{count} is negative, that specifies a position
@w{@minus{}@var{count}} lines from the bottom (or the last line of the
buffer, if the buffer ends above the specified screen position).

If @var{count} is @code{nil}, then point moves to the beginning of the
line in the middle of the window.  If the absolute value of @var{count}
is greater than the size of the window, then point moves to the place
that would appear on that screen line if the window were tall enough.
This will probably cause the next redisplay to scroll to bring that
location onto the screen.

In an interactive call, @var{count} is the numeric prefix argument.

The value returned is the window line number point has moved to, with
the top line in the window numbered 0.
@end deffn

@defun compute-motion from frompos to topos width offsets window
This function scans the current buffer, calculating screen positions.
It scans the buffer forward from position @var{from}, assuming that is
at screen coordinates @var{frompos}, to position @var{to} or coordinates
@var{topos}, whichever comes first.  It returns the ending buffer
position and screen coordinates.

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

@var{tab-offset} is the offset between column numbers on the screen and
column numbers in the buffer.  This can be nonzero in a continuation
line, when the previous screen lines' widths do not add up to a multiple
of @code{tab-width}.  It is always zero in a non-continuation line.

The window @var{window} serves only to specify which display table to
use.  @code{compute-motion} always operates on the current buffer,
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})
@end example

@noindent
Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
is the vertical screen position, and @var{hpos} is the horizontal screen
position.

The result @var{prevhpos} is the horizontal position one character back
from @var{pos}.  The result @var{contin} is @code{t} if the last line
was continued after (or within) the previous character.

For example, to find the buffer position of column @var{col} of line
@var{line} of a certain window, pass the window's display start location
as @var{from} and the window's upper-left coordinates as @var{frompos}.
Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
the end of the accessible portion of the buffer, and pass @var{line} and
@var{col} as @var{topos}.  Here's a function that does this:

@example
(defun coordinates-of-position (col line)
  (car (compute-motion (window-start)
                       '(0 . 0)
                       (point-max)
                       (cons col line)
                       (window-width)
                       (cons (window-hscroll) 0)
                       (selected-window))))
@end example

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}.

@defopt track-eol
This variable controls how the vertical line motion commands operate
when starting at the end of a line.  If @code{track-eol} is
non-@code{nil}, then vertical motion starting at the end of a line will
keep to the ends of lines (instead of keeping to a particular column).
This means moving to the end of each line moved onto.  The value of
@code{track-eol} has no effect if point is not at the end of a line when
the first vertical motion command is given.

@code{track-eol} has its effect by telling line motion commands to set
@code{temporary-goal-column} to 9999 instead of to the current column.
@end defopt

This function moves forward out of @var{arg} 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 @var{arg} levels
deeper in parentheses.
@end deffn

@deffn Command forward-sexp arg
This function moves forward across @var{arg} balanced expressions.
Balanced expressions include both those delimited by parentheses and

@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
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.
@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.
@end defopt

@node Skipping Characters
@comment  node-name,  next,  previous,  up
@subsection Skipping Characters

@defspec save-excursion forms@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
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}).

The @code{save-excursion} special form is the standard way to switch
buffers or move point within one part of a program and avoid affecting
the rest of the program.  It is used more than 500 times in the Lisp
sources of Emacs.

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
the entire buffer regardless of any narrowing.

@deffn Command narrow-to-region start end
This function sets the accessible portion of the current buffer to start
at @var{start} and end at @var{end}.  Both arguments should be character
positions.

@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,
thus restoring the same state of narrowing (or absence thereof) formerly
in effect.  The state of narrowing is restored even in the event of an
abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
Therefore, this construct is a clean way to narrow a buffer temporarily.

The value returned by @code{save-restriction} is that returned by the
last form in @var{body}, or @code{nil} if no body forms were given.

@c Wordy to avoid overfull hbox.  --rjc 16mar92