comparison lispref/lists.texi @ 63541:ddec16fed4a2

(Rings): New node. (Lists): Add to menu.

63540:f69f062368dd

* List Elements::       Extracting the pieces of a list.
* Building Lists::      Creating list structure.
* 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.
@end menu

@node Cons Cells
@section Lists and Cons Cells
@cindex lists and cons cells

@code{rassq-delete-all} is like @code{assq-delete-all} except that it
compares the @sc{cdr} of each @var{alist} association instead of the
@sc{car}.
@end defun

@ignore
   arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4
@end ignore

63541:ddec16fed4a2

* List Elements::       Extracting the pieces of a list.
* Building Lists::      Creating list structure.
* 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
@section Lists and Cons Cells
@cindex lists and cons cells

@code{rassq-delete-all} is like @code{assq-delete-all} except that it
compares the @sc{cdr} of each @var{alist} association instead of the
@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