[Emacs-diffs] Changes to emacs/lispref/lists.texi

[Richard M . Stallman]

Index: emacs/lispref/lists.texi
diff -c emacs/lispref/lists.texi:1.51 emacs/lispref/lists.texi:1.52
*** emacs/lispref/lists.texi:1.51       Thu Apr 21 21:22:58 2005
--- emacs/lispref/lists.texi    Fri Jun 17 13:47:44 2005
***************
*** 24,29 ****
--- 24,30 ----
  * Modifying Lists::     Storing new pieces into an existing list.
  * Sets And Lists::      A list can represent a finite mathematical set.
  * Association Lists::   A list can represent a finite relation or mapping.
+ * Rings::               Managing a fixed-size ring of objects.
  @end menu
  
  @node Cons Cells
***************
*** 1676,1681 ****
--- 1677,1769 ----
  @sc{car}.
  @end defun
  
+ @node Rings
+ @section Managing a Fixed-Size Ring of Objects
+ 
+ @cindex ring data structure
+   This section describes functions for operating on rings.  A
+ @dfn{ring} is a fixed-size data structure that supports insertion,
+ deletion, rotation, and modulo-indexed reference and traversal.
+ 
+ @defun make-ring size
+ This returns a new ring capable of holding @var{size} objects.
+ @var{size} should be an integer.
+ @end defun
+ 
+ @defun ring-p object
+ This returns @code{t} if @var{object} is a ring.
+ @end defun
+ 
+ @defun ring-size ring
+ This returns the maximum capacity of the @var{ring}.
+ @end defun
+ 
+ @defun ring-length ring
+ This returns the number of objects that @var{ring} currently contains.
+ The value will never exceed that returned by @code{ring-size}.
+ @end defun
+ 
+ @defun ring-elements ring
+ This returns a list of the objects in @var{ring}, in no particular
+ order.
+ @end defun
+ 
+ @defun ring-copy ring
+ This returns a new ring which is a copy of @var{ring}.
+ The new ring contains the same objects as @var{ring}.
+ @end defun
+ 
+ @defun ring-empty-p ring
+ This returns @code{t} if @var{ring} is empty.
+ @end defun
+ 
+   The newest element in the ring always has index 0.  Higher indexes
+ correspond to older elements.  Index @minus{}1 corresponds to the
+ oldest element, @minus{}2 to the next-oldest, and so forth.
+ 
+ @defun ring-ref ring index
+ This returns the object in @var{ring} found at index @var{index}.
+ @var{index} may be negative or greater than the ring length.  If
+ @var{ring} is empty, @code{ring-ref} signals an error.
+ @end defun
+ 
+ @defun ring-insert ring object
+ This inserts @var{object} into @var{ring}, making it the newest
+ element, and returns @var{object}.
+ 
+ If the ring is full, insertion removes the oldest element to
+ make room for the new element.
+ @end defun
+ 
+ @defun ring-remove ring &optional index
+ Remove an object from @var{ring}, and return that object.  The
+ argument @var{index} specifies which item to remove; if it is
+ @code{nil}, that means to remove the oldest item.  If @var{ring} is
+ empty, @code{ring-remove} signals an error.
+ @end defun
+ 
+ @defun ring-insert-at-beginning ring object
+ This inserts @var{object} into @var{ring}, treating it as the oldest
+ element, and returns @var{object}.
+ 
+ If the ring is full, this function removes the newest element to make
+ room for the inserted element.
+ @end defun
+ 
+ @cindex fifo data structure
+   If you are careful not to exceed the ring size, you can
+ use the ring as a first-in-first-out queue.  For example:
+ 
+ @lisp
+ (let ((fifo (make-ring 5)))
+   (mapc (lambda (obj) (ring-insert fifo obj))
+         '(0 one "two"))
+   (list (ring-remove fifo) t
+         (ring-remove fifo) t
+         (ring-remove fifo)))
+      @result{} (0 t one t "two")
+ @end lisp
+ 
  @ignore
     arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4
  @end ignore