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 |
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 |