@c -*-texinfo-*-
@setfilename ../info/markers
@node Markers, Text, Positions, Top
@chapter Markers
@cindex markers

  A @dfn{marker} is a Lisp object used to specify a position in a buffer
relative to the surrounding text.  A marker changes its offset from the
beginning of the buffer automatically whenever text is inserted or
deleted, so that it stays with the two characters on either side of it.

@menu
* Overview of Markers::      The components of a marker, and how it relocates.
* Predicates on Markers::    Testing whether an object is a marker.
* Creating Markers::         Making empty markers or markers at certain places.
* Information from Markers:: Finding the marker's buffer or character position.
* Changing Markers::         Moving the marker to a new buffer or position.
* The Mark::                 How ``the mark'' is implemented with a marker.
* The Region::               How to access ``the region''.
@end menu

@node Overview of Markers, Predicates on Markers, Markers, Markers
@section Overview of Markers

  A marker specifies a buffer and a position in that buffer.  The marker
can be used to represent a position in the functions that require one,
just as an integer could be used.  @xref{Positions}, for a complete
description of positions.

  A marker has two attributes: the marker position, and the marker
buffer.  The marker position is an integer which is equivalent (at the
moment) to the marker as a position in that buffer; however, as text is
inserted or deleted in the buffer, the marker is relocated, so that its
integer equivalent changes.  The idea is that a marker positioned
between two characters in a buffer will remain between those two
characters despite any changes made to the contents of the buffer; thus,
a marker's offset from the beginning of a buffer may change often during
the life of the marker.

@cindex marker relocation
  If the text around a marker is deleted, the marker is repositioned
between the characters immediately before and after the deleted text.  If
text is inserted at the position of a marker, the marker remains in front
of the new text unless it is inserted with @code{insert-before-markers}
(@pxref{Insertion}).  When text is inserted or deleted somewhere before the
marker position (not next to the marker), the marker moves back and forth
with the two neighboring characters.

@cindex marker garbage collection
  When a buffer is modified, all of its markers must be checked so that
they can be relocated if necessary.  This slows processing in a buffer
with a large number of markers.  For this reason, it is a good idea to
make a marker point nowhere if you are sure you don't need it any more.
Unreferenced markers will eventually be garbage collected, but until
then will continue to be updated if they do point somewhere.

@cindex markers as numbers
  Because it is quite common to perform arithmetic operations on a marker
position, most of the arithmetic operations (including @code{+} and
@code{-}) accept markers as arguments.  In such cases, the current position
of the marker is used.

Here are examples of creating markers, setting markers, and moving point
to markers:

@example
;; @r{Make a new marker that initially does not point anywhere:}
(setq m1 (make-marker))
     @result{} #<marker in no buffer>

;; @r{Set @code{m1} to point between the 100th and 101st characters.}
;; @r{in the current buffer:}
(set-marker m1 100)
     @result{} #<marker at 100 in markers.texi>

;; @r{Now insert one character at the beginning of the buffer:}
(goto-char (point-min))
     @result{} 1
(insert "Q")
     @result{} nil

;; @r{@code{m1} is updated appropriately.}
m1
     @result{} #<marker at 101 in markers.texi>

;; @r{Two markers that point to the same position}
;; @r{are not @code{eq}, but they are @code{equal}.}
(setq m2 (copy-marker m1))
     @result{} #<marker at 101 in markers.texi>
(eq m1 m2)
     @result{} nil
(equal m1 m2)
     @result{} t

;; @r{When you are finished using a marker, make it point nowhere.}
(set-marker m1 nil)
     @result{} #<marker in no buffer>
@end example

@node Predicates on Markers, Creating Markers, Overview of Markers, Markers
@section Predicates on Markers

  You can test an object to see whether it is a marker, or whether it is
either an integer or a marker.  The latter test is useful when you are
using the arithmetic functions that work with both markers and integers.

@defun markerp object
  This function returns @code{t} if @var{object} is a marker,
@code{nil} otherwise.  In particular, integers are not markers,
even though many functions will accept either a marker or an
integer.
@end defun

@defun integer-or-marker-p object
  This function returns @code{t} if @var{object} is an integer or a marker,
@code{nil} otherwise.
@end defun

@node Creating Markers, Information from Markers, Predicates on Markers, Markers
@section Functions That Create Markers

  When you create a new marker, you can make it point nowhere, or point
to the present position of point, or to the beginning or end of the
accessible portion of the buffer, or to the same place as another given
marker.

@defun make-marker
  This functions returns a newly allocated marker that does not point
anywhere.

@example
(make-marker)
     @result{} #<marker in no buffer>
@end example
@end defun

@defun point-marker
  This function returns a new marker that points to the present position
of point in the current buffer.  @xref{Point}.  For an example, see
@code{copy-marker}, below.
@end defun

@defun point-min-marker
  This function returns a new marker that points to the beginning of the
accessible portion of the buffer.  This will be the beginning of the
buffer unless narrowing is in effect.  @xref{Narrowing}.
@end defun

@defun point-max-marker
@cindex end of buffer marker
  This function returns a new marker that points to the end of the
accessible portion of the buffer.  This will be the end of the buffer
unless narrowing is in effect.  @xref{Narrowing}.

Here are examples of this function and @code{point-min-marker}, shown in
a buffer containing a version of the source file for the text of this
chapter.

@example
(point-min-marker)
     @result{} #<marker at 1 in markers.texi>
(point-max-marker)
     @result{} #<marker at 15573 in markers.texi>

(narrow-to-region 100 200)
     @result{} nil
(point-min-marker)
     @result{} #<marker at 100 in markers.texi>
@group
(point-max-marker)
     @result{} #<marker at 200 in markers.texi>
@end group
@end example
@end defun

@defun copy-marker marker-or-integer
  If passed a marker as its argument, @code{copy-marker} returns a
new marker that points to the same place and the same buffer as does
@var{marker-or-integer}.  If passed an integer as its argument,
@code{copy-marker} returns a new marker that points to position
@var{marker-or-integer} in the current buffer.

  If passed an argument that is an integer whose value is less than 1,
@code{copy-marker} returns a new marker that points to the
beginning of the current buffer.  If passed an argument that is an
integer whose value is greater than the length of the buffer, then
@code{copy-marker} returns a new marker that points to the end of the
buffer.

  An error is signaled if @var{marker} is neither a marker nor an
integer.

@example
(setq p (point-marker))
     @result{} #<marker at 2139 in markers.texi>

(setq q (copy-marker p))
     @result{} #<marker at 2139 in markers.texi>

(eq p q)
     @result{} nil

(equal p q)
     @result{} t

(copy-marker 0)
     @result{} #<marker at 1 in markers.texi>

(copy-marker 20000)
     @result{} #<marker at 7572 in markers.texi>
@end example
@end defun

@node Information from Markers, Changing Markers, Creating Markers, Markers
@section Information from Markers

  This section describes the functions for accessing the components of a
marker object.

@defun marker-position marker
  This function returns the position that @var{marker} points to, or
@code{nil} if it points nowhere.
@end defun

@defun marker-buffer marker
  This function returns the buffer that @var{marker} points into, or
@code{nil} if it points nowhere.

@example
(setq m (make-marker))
     @result{} #<marker in no buffer>
(marker-position m)
     @result{} nil
(marker-buffer m)
     @result{} nil

(set-marker m 3770 (current-buffer))
     @result{} #<marker at 3770 in markers.texi>
(marker-buffer m)
     @result{} #<buffer markers.texi>
(marker-position m)
     @result{} 3770
@end example
@end defun

  Two distinct markers will be found @code{equal} (even though not
@code{eq}) to each other if they have the same position and buffer, or
if they both point nowhere.

@node Changing Markers, The Mark, Information from Markers, Markers
@section Changing Markers

  This section describes how to change the position of an existing
marker.  When you do this, be sure you know whether the marker is used
outside of your program, and, if so, what effects will result from
moving it---otherwise, confusing things may happen in other parts of
Emacs.

@defun set-marker marker position &optional buffer
  This function moves @var{marker} to @var{position}
in @var{buffer}.  If @var{buffer} is not provided, it defaults to
the current buffer.

  If @var{position} is less than 1, @code{set-marker} moves marker to
the beginning of the buffer.  If the value of @var{position} is greater
than the size of the buffer, @code{set-marker} moves marker to the end
of the buffer.  If @var{position} is @code{nil} or a marker that points
nowhere, then @var{marker} is set to point nowhere.

  The value returned is @var{marker}.

@example
(setq m (point-marker))
     @result{} #<marker at 4714 in markers.texi>
(set-marker m 55)
     @result{} #<marker at 55 in markers.texi>
(setq b (get-buffer "foo"))
     @result{} #<buffer foo>
(set-marker m 0 b)
     @result{} #<marker at 1 in foo>
@end example
@end defun

@defun move-marker marker position &optional buffer
  This is another name for @code{set-marker}.
@end defun

@node The Mark, The Region, Changing Markers, Markers
@section The Mark
@cindex mark, the
@cindex mark ring

  A special marker in each buffer is designated @dfn{the mark}.  It
records a position for the user for the sake of commands such as
@kbd{C-w} and @kbd{C-x @key{TAB}}.  Lisp programs should set the mark
only to values that have a potential use to the user, and never for
their own internal purposes.  For example, the @code{replace-regexp}
command sets the mark to the value of point before doing any
replacements, because this enables the user to move back there
conveniently after the replace is finished.

  Many commands are designed so that when called interactively they
operate on the text between point and the mark.  If you are writing such
a command, don't examine the mark directly; instead, use
@code{interactive} with the @samp{r} specification.  This will provide
the values of point and the mark as arguments to the command in an
interactive call, but will permit other Lisp programs to specify
arguments explicitly.  @xref{Interactive Codes}.

  Each buffer has its own value of the mark that is independent of the
value of the mark in other buffers.  When a buffer is created, the mark
exists but does not point anywhere.  We consider this state as ``the
absence of a mark in that buffer''.

  In addition to the mark, each buffer has a @dfn{mark ring} which is a
list of markers that are the previous values of the mark.  When editing
commands change the mark, they should normally save the old value of the
mark on the mark ring.  The mark ring may contain no more than the
maximum number of entries specified by the variable @code{mark-ring-max};
excess entries are discarded on a first-in-first-out basis.

@defun mark
@cindex current buffer mark
  This function returns the position of the current buffer's mark as an
integer.  @code{nil} is returned if the mark is not yet set for this
buffer.
@end defun

@defun mark-marker
  This function returns the current buffer's mark.  This the very marker
which records the mark location inside Emacs, not a copy.  Therefore,
changing this marker's position will directly affect the position of the mark.
Don't do it unless that is the effect you want.

@example
(setq m (mark-marker))
     @result{} #<marker at 3420 in markers.texi>
(set-marker m 100)
     @result{} #<marker at 100 in markers.texi>
(mark-marker)
     @result{} #<marker at 100 in markers.texi>
@end example

Like any marker, this marker can be set to point at any buffer you like.
We don't recommend that you make it point at any buffer other than the
one of which it is the mark.  If you do, it will yield perfectly
consistent, if rather odd, results.
@end defun

@deffn Command set-mark-command jump
  If @var{jump} is @code{nil}, this command sets the mark to the value
of point and pushes the previous value of the mark on the mark ring.  The
message @samp{Mark set} is also displayed in the echo area.

  If @var{jump} is not @code{nil}, this command sets point to the value
of the mark, and sets the mark to the previous saved mark value, which
is popped off the mark ring.

  This function is @emph{only} intended for interactive use.
@end deffn

@defun set-mark position
  This function sets the mark to @var{position}.
The old value of the mark is @emph{not} pushed onto the mark ring.

  @strong{Note:} use this function only if you want the user to see that
the mark has moved, and you want the previous mark position to be lost.
Normally, when a new mark is set, the old one should go on the
@code{mark-ring}, which is why most applications should use
@code{push-mark} and @code{pop-mark}, not @code{set-mark}.

  Novice Emacs Lisp programmers often try to use the mark for the wrong
purposes.  The mark saves a location for the user's convenience.  An
editing command should not alter the mark unless altering the mark is
part of the user-level functionality of the command.  (And, in that
case, this effect should be documented.)  To remember a location for
internal use in the Lisp program, store it in a Lisp variable.  For
example:

@example
   (let ((beg (point)))
      (forward-line 1)
      (delete-region beg (point))).
@end example
@end defun

@c for interactive use only
@ignore
@deffn Command exchange-point-and-mark
  This function exchanges the positions of point and the mark.
It is intended for interactive use.
@end deffn
@end ignore

@defvar mark-ring
  The value of this buffer-local variable is the list of saved former
marks of the current buffer, most recent first.

@example
mark-ring
@result{} (#<marker at 11050 in markers.texi> 
    #<marker at 10832 in markers.texi>
    @dots{})
@end example
@end defvar

@defopt mark-ring-max
  The value of this variable is the maximum size of @code{mark-ring}.
If more marks than this are pushed onto the @code{mark-ring}, it
discards marks on a first-in, first-out basis.
@end defopt

@defun push-mark &optional position nomsg
  This function sets the current buffer's mark to @var{position}, and
pushes a copy of the previous mark onto @code{mark-ring}.  If
@var{position} is @code{nil}, then the value of point is used.
@code{push-mark} returns @code{nil}.

  A @samp{Mark set} message is displayed unless @var{nomsg} is
non-@code{nil}.
@end defun

@defun pop-mark
  This function pops off the top element of @code{mark-ring} and makes
that mark become the buffer's actual mark.  This does not change the
buffer's point and does nothing if @code{mark-ring} is empty.

  The return value is not useful.
@end defun

@node The Region,  , The Mark, Markers
@section The Region
@cindex region, the

  The text between point and the mark is known as @dfn{the region}.
Various functions operate on text delimited by point and the mark, but
only those functions specifically related to the region itself are
described here.

@defun region-beginning
  This function returns the position of the beginning of the region (as
an integer).  This is the position of either point or the mark,
whichever is smaller.

  If the mark does not point anywhere, an error is signaled.
@end defun

@defun region-end
  This function returns the position of the end of the region (as an
integer).  This is the position of either point or the mark, whichever is
larger.

  If the mark does not point anywhere, an error is signaled.
@end defun

  Few programs need to use the @code{region-beginning} and
@code{region-end} functions.  A command designed to operate on a region
should instead use @code{interactive} with the @samp{r} specification,
so that the same function can be called with explicit bounds arguments
from programs.  (@xref{Interactive Codes}.)
