@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/buffers
@node Buffers, Windows, Backups and Auto-Saving, Top
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some other buffer.
+* Swapping Text:: Swapping text between two buffers.
* Buffer Gap:: The gap in the buffer.
@end menu
This function returns @var{buffer}'s character-change modification-count.
Changes to text properties leave this counter unchanged; however, each
time text is inserted or removed from the buffer, the counter is reset
-to the value that would be returned @code{buffer-modified-tick}.
+to the value that would be returned by @code{buffer-modified-tick}.
By comparing the values returned by two @code{buffer-chars-modified-tick}
calls, you can tell whether a character change occurred in that buffer
in between the calls. If @var{buffer} is @code{nil} (or omitted), the
to the end when they are buried (see @code{bury-buffer}, below).
There are no functions available to the Lisp programmer which directly
manipulate the buffer list.
-
+
In addition to the fundamental Emacs buffer list, each frame has its
own version of the buffer list, in which the buffers that have been
selected in that frame come first, starting with the buffers most
indirect buffer.
@end defun
+@node Swapping Text
+@section Swapping Text Between Two Buffers
+@cindex swap text between buffers
+@cindex virtual buffers
+
+ Specialized modes sometimes need to let the user access from the
+same buffer several vastly different types of text. For example, you
+may need to display a summary of the buffer text, in addition to
+letting the user access the text itself.
+
+ This could be implemented with multiple buffers (kept in sync when
+the user edits the text), or with narrowing (@pxref{Narrowing}). But
+these alternatives might sometimes become tedious or prohibitively
+expensive, especially if each type of text requires expensive
+buffer-global operations in order to provide correct display and
+editing commands.
+
+ Emacs provides another facility for such modes: you can quickly swap
+buffer text between two buffers with @code{buffer-swap-text}. This
+function is very fast because it doesn't move any text, it only
+changes the internal data structures of the buffer object to point to
+a different chunk of text. Using it, you can pretend that a group of
+two or more buffers are actually a single virtual buffer that holds
+the contents of all the individual buffers together.
+
+@defun buffer-swap-text buffer
+This function swaps text between the current buffer and its argument
+@var{buffer}. It signals an error if one of the two buffers is an
+indirect buffer (@pxref{Indirect Buffers}) or is a base buffer of an
+indirect buffer.
+
+All the buffer properties that are related to the buffer text are
+swapped as well: the positions of point and mark, all the markers, the
+overlays, the text properties, the undo list, the value of the
+@code{enable-multibyte-characters} flag (@pxref{Text Representations,
+enable-multibyte-characters}), etc.
+@end defun
+
@node Buffer Gap
@section The Buffer Gap