/[emacs]/emacs/lispref/lists.texi
ViewVC logotype

Diff of /emacs/lispref/lists.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.51 by lute, Thu Apr 21 21:22:58 2005 UTC revision 1.52 by rms, Fri Jun 17 13:47:44 2005 UTC
# Line 24  the whole list. Line 24  the whole list.
24  * Modifying Lists::     Storing new pieces into an existing list.  * Modifying Lists::     Storing new pieces into an existing list.
25  * Sets And Lists::      A list can represent a finite mathematical set.  * Sets And Lists::      A list can represent a finite mathematical set.
26  * Association Lists::   A list can represent a finite relation or mapping.  * Association Lists::   A list can represent a finite relation or mapping.
27    * Rings::               Managing a fixed-size ring of objects.
28  @end menu  @end menu
29    
30  @node Cons Cells  @node Cons Cells
# Line 1676  compares the @sc{cdr} of each @var{alist Line 1677  compares the @sc{cdr} of each @var{alist
1677  @sc{car}.  @sc{car}.
1678  @end defun  @end defun
1679    
1680    @node Rings
1681    @section Managing a Fixed-Size Ring of Objects
1682    
1683    @cindex ring data structure
1684      This section describes functions for operating on rings.  A
1685    @dfn{ring} is a fixed-size data structure that supports insertion,
1686    deletion, rotation, and modulo-indexed reference and traversal.
1687    
1688    @defun make-ring size
1689    This returns a new ring capable of holding @var{size} objects.
1690    @var{size} should be an integer.
1691    @end defun
1692    
1693    @defun ring-p object
1694    This returns @code{t} if @var{object} is a ring.
1695    @end defun
1696    
1697    @defun ring-size ring
1698    This returns the maximum capacity of the @var{ring}.
1699    @end defun
1700    
1701    @defun ring-length ring
1702    This returns the number of objects that @var{ring} currently contains.
1703    The value will never exceed that returned by @code{ring-size}.
1704    @end defun
1705    
1706    @defun ring-elements ring
1707    This returns a list of the objects in @var{ring}, in no particular
1708    order.
1709    @end defun
1710    
1711    @defun ring-copy ring
1712    This returns a new ring which is a copy of @var{ring}.
1713    The new ring contains the same objects as @var{ring}.
1714    @end defun
1715    
1716    @defun ring-empty-p ring
1717    This returns @code{t} if @var{ring} is empty.
1718    @end defun
1719    
1720      The newest element in the ring always has index 0.  Higher indexes
1721    correspond to older elements.  Index @minus{}1 corresponds to the
1722    oldest element, @minus{}2 to the next-oldest, and so forth.
1723    
1724    @defun ring-ref ring index
1725    This returns the object in @var{ring} found at index @var{index}.
1726    @var{index} may be negative or greater than the ring length.  If
1727    @var{ring} is empty, @code{ring-ref} signals an error.
1728    @end defun
1729    
1730    @defun ring-insert ring object
1731    This inserts @var{object} into @var{ring}, making it the newest
1732    element, and returns @var{object}.
1733    
1734    If the ring is full, insertion removes the oldest element to
1735    make room for the new element.
1736    @end defun
1737    
1738    @defun ring-remove ring &optional index
1739    Remove an object from @var{ring}, and return that object.  The
1740    argument @var{index} specifies which item to remove; if it is
1741    @code{nil}, that means to remove the oldest item.  If @var{ring} is
1742    empty, @code{ring-remove} signals an error.
1743    @end defun
1744    
1745    @defun ring-insert-at-beginning ring object
1746    This inserts @var{object} into @var{ring}, treating it as the oldest
1747    element, and returns @var{object}.
1748    
1749    If the ring is full, this function removes the newest element to make
1750    room for the inserted element.
1751    @end defun
1752    
1753    @cindex fifo data structure
1754      If you are careful not to exceed the ring size, you can
1755    use the ring as a first-in-first-out queue.  For example:
1756    
1757    @lisp
1758    (let ((fifo (make-ring 5)))
1759      (mapc (lambda (obj) (ring-insert fifo obj))
1760            '(0 one "two"))
1761      (list (ring-remove fifo) t
1762            (ring-remove fifo) t
1763            (ring-remove fifo)))
1764         @result{} (0 t one t "two")
1765    @end lisp
1766    
1767  @ignore  @ignore
1768     arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4     arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4
1769  @end ignore  @end ignore

Legend:
Removed from v.1.51  
changed lines
  Added in v.1.52

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26