[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/lists.texi
From: |
Richard M . Stallman |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/lists.texi |
Date: |
Fri, 17 Jun 2005 09:47:44 -0400 |
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
- [Emacs-diffs] Changes to emacs/lispref/lists.texi,
Richard M . Stallman <=