diff options
Diffstat (limited to 'devdocs/elisp/rings.html')
| -rw-r--r-- | devdocs/elisp/rings.html | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/devdocs/elisp/rings.html b/devdocs/elisp/rings.html new file mode 100644 index 00000000..01c54680 --- /dev/null +++ b/devdocs/elisp/rings.html @@ -0,0 +1,42 @@ + <h3 class="section">Managing a Fixed-Size Ring of Objects</h3> <p>A <em>ring</em> is a fixed-size data structure that supports insertion, deletion, rotation, and modulo-indexed reference and traversal. An efficient ring data structure is implemented by the <code>ring</code> package. It provides the functions listed in this section. </p> <p>Note that several rings in Emacs, like the kill ring and the mark ring, are actually implemented as simple lists, <em>not</em> using the <code>ring</code> package; thus the following functions won’t work on them. </p> <dl> <dt id="make-ring">Function: <strong>make-ring</strong> <em>size</em> +</dt> <dd><p>This returns a new ring capable of holding <var>size</var> objects. <var>size</var> should be an integer. </p></dd> +</dl> <dl> <dt id="ring-p">Function: <strong>ring-p</strong> <em>object</em> +</dt> <dd><p>This returns <code>t</code> if <var>object</var> is a ring, <code>nil</code> otherwise. </p></dd> +</dl> <dl> <dt id="ring-size">Function: <strong>ring-size</strong> <em>ring</em> +</dt> <dd><p>This returns the maximum capacity of the <var>ring</var>. </p></dd> +</dl> <dl> <dt id="ring-length">Function: <strong>ring-length</strong> <em>ring</em> +</dt> <dd><p>This returns the number of objects that <var>ring</var> currently contains. The value will never exceed that returned by <code>ring-size</code>. </p></dd> +</dl> <dl> <dt id="ring-elements">Function: <strong>ring-elements</strong> <em>ring</em> +</dt> <dd><p>This returns a list of the objects in <var>ring</var>, in order, newest first. </p></dd> +</dl> <dl> <dt id="ring-copy">Function: <strong>ring-copy</strong> <em>ring</em> +</dt> <dd><p>This returns a new ring which is a copy of <var>ring</var>. The new ring contains the same (<code>eq</code>) objects as <var>ring</var>. </p></dd> +</dl> <dl> <dt id="ring-empty-p">Function: <strong>ring-empty-p</strong> <em>ring</em> +</dt> <dd><p>This returns <code>t</code> if <var>ring</var> is empty, <code>nil</code> otherwise. </p></dd> +</dl> <p>The newest element in the ring always has index 0. Higher indices correspond to older elements. Indices are computed modulo the ring length. Index -1 corresponds to the oldest element, -2 to the next-oldest, and so forth. </p> <dl> <dt id="ring-ref">Function: <strong>ring-ref</strong> <em>ring index</em> +</dt> <dd><p>This returns the object in <var>ring</var> found at index <var>index</var>. <var>index</var> may be negative or greater than the ring length. If <var>ring</var> is empty, <code>ring-ref</code> signals an error. </p></dd> +</dl> <dl> <dt id="ring-insert">Function: <strong>ring-insert</strong> <em>ring object</em> +</dt> <dd> +<p>This inserts <var>object</var> into <var>ring</var>, making it the newest element, and returns <var>object</var>. </p> <p>If the ring is full, insertion removes the oldest element to make room for the new element. </p> +</dd> +</dl> <dl> <dt id="ring-remove">Function: <strong>ring-remove</strong> <em>ring &optional index</em> +</dt> <dd><p>Remove an object from <var>ring</var>, and return that object. The argument <var>index</var> specifies which item to remove; if it is <code>nil</code>, that means to remove the oldest item. If <var>ring</var> is empty, <code>ring-remove</code> signals an error. </p></dd> +</dl> <dl> <dt id="ring-insert-at-beginning">Function: <strong>ring-insert-at-beginning</strong> <em>ring object</em> +</dt> <dd> +<p>This inserts <var>object</var> into <var>ring</var>, treating it as the oldest element. The return value is not significant. </p> <p>If the ring is full, this function removes the newest element to make room for the inserted element. </p> +</dd> +</dl> <dl> <dt id="ring-resize">Function: <strong>ring-resize</strong> <em>ring size</em> +</dt> <dd><p>Set the size of <var>ring</var> to <var>size</var>. If the new size is smaller, then the oldest items in the ring are discarded. </p></dd> +</dl> <p>If you are careful not to exceed the ring size, you can use the ring as a first-in-first-out queue. For example: </p> <div class="lisp"> <pre class="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))) + ⇒ (0 t one t "two") +</pre> +</div><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Rings.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Rings.html</a> + </p> +</div> |