diff options
Diffstat (limited to 'devdocs/elisp/list-variables.html')
| -rw-r--r-- | devdocs/elisp/list-variables.html | 66 |
1 files changed, 66 insertions, 0 deletions
diff --git a/devdocs/elisp/list-variables.html b/devdocs/elisp/list-variables.html new file mode 100644 index 00000000..37df9e3b --- /dev/null +++ b/devdocs/elisp/list-variables.html @@ -0,0 +1,66 @@ + <h3 class="section">Modifying List Variables</h3> <p>These functions, and one macro, provide convenient ways to modify a list which is stored in a variable. </p> <dl> <dt id="push">Macro: <strong>push</strong> <em>element listname</em> +</dt> <dd> +<p>This macro creates a new list whose <small>CAR</small> is <var>element</var> and whose <small>CDR</small> is the list specified by <var>listname</var>, and saves that list in <var>listname</var>. In the simplest case, <var>listname</var> is an unquoted symbol naming a list, and this macro is equivalent to <code>(setq <var>listname</var> (cons <var>element</var> <var>listname</var>))</code>. </p> <div class="example"> <pre class="example">(setq l '(a b)) + ⇒ (a b) +(push 'c l) + ⇒ (c a b) +l + ⇒ (c a b) +</pre> +</div> <p>More generally, <code>listname</code> can be a generalized variable. In that case, this macro does the equivalent of <code>(setf <var>listname</var> (cons <var>element</var> <var>listname</var>))</code>. See <a href="generalized-variables">Generalized Variables</a>. </p> <p>For the <code>pop</code> macro, which removes the first element from a list, See <a href="list-elements">List Elements</a>. </p> +</dd> +</dl> <p>Two functions modify lists that are the values of variables. </p> <dl> <dt id="add-to-list">Function: <strong>add-to-list</strong> <em>symbol element &optional append compare-fn</em> +</dt> <dd> +<p>This function sets the variable <var>symbol</var> by consing <var>element</var> onto the old value, if <var>element</var> is not already a member of that value. It returns the resulting list, whether updated or not. The value of <var>symbol</var> had better be a list already before the call. <code>add-to-list</code> uses <var>compare-fn</var> to compare <var>element</var> against existing list members; if <var>compare-fn</var> is <code>nil</code>, it uses <code>equal</code>. </p> <p>Normally, if <var>element</var> is added, it is added to the front of <var>symbol</var>, but if the optional argument <var>append</var> is non-<code>nil</code>, it is added at the end. </p> <p>The argument <var>symbol</var> is not implicitly quoted; <code>add-to-list</code> is an ordinary function, like <code>set</code> and unlike <code>setq</code>. Quote the argument yourself if that is what you want. </p> <p>Do not use this function when <var>symbol</var> refers to a lexical variable. </p> +</dd> +</dl> <p>Here’s a scenario showing how to use <code>add-to-list</code>: </p> <div class="example"> <pre class="example">(setq foo '(a b)) + ⇒ (a b) + +(add-to-list 'foo 'c) ;; <span class="roman">Add <code>c</code>.</span> + ⇒ (c a b) + +(add-to-list 'foo 'b) ;; <span class="roman">No effect.</span> + ⇒ (c a b) + +foo ;; <span class="roman"><code>foo</code> was changed.</span> + ⇒ (c a b) +</pre> +</div> <p>An equivalent expression for <code>(add-to-list '<var>var</var> +<var>value</var>)</code> is this: </p> <div class="example"> <pre class="example">(if (member <var>value</var> <var>var</var>) + <var>var</var> + (setq <var>var</var> (cons <var>value</var> <var>var</var>))) +</pre> +</div> <dl> <dt id="add-to-ordered-list">Function: <strong>add-to-ordered-list</strong> <em>symbol element &optional order</em> +</dt> <dd> +<p>This function sets the variable <var>symbol</var> by inserting <var>element</var> into the old value, which must be a list, at the position specified by <var>order</var>. If <var>element</var> is already a member of the list, its position in the list is adjusted according to <var>order</var>. Membership is tested using <code>eq</code>. This function returns the resulting list, whether updated or not. </p> <p>The <var>order</var> is typically a number (integer or float), and the elements of the list are sorted in non-decreasing numerical order. </p> <p><var>order</var> may also be omitted or <code>nil</code>. Then the numeric order of <var>element</var> stays unchanged if it already has one; otherwise, <var>element</var> has no numeric order. Elements without a numeric list order are placed at the end of the list, in no particular order. </p> <p>Any other value for <var>order</var> removes the numeric order of <var>element</var> if it already has one; otherwise, it is equivalent to <code>nil</code>. </p> <p>The argument <var>symbol</var> is not implicitly quoted; <code>add-to-ordered-list</code> is an ordinary function, like <code>set</code> and unlike <code>setq</code>. Quote the argument yourself if necessary. </p> <p>The ordering information is stored in a hash table on <var>symbol</var>’s <code>list-order</code> property. <var>symbol</var> cannot refer to a lexical variable. </p> +</dd> +</dl> <p>Here’s a scenario showing how to use <code>add-to-ordered-list</code>: </p> <div class="example"> <pre class="example">(setq foo '()) + ⇒ nil + +(add-to-ordered-list 'foo 'a 1) ;; <span class="roman">Add <code>a</code>.</span> + ⇒ (a) + +(add-to-ordered-list 'foo 'c 3) ;; <span class="roman">Add <code>c</code>.</span> + ⇒ (a c) + +(add-to-ordered-list 'foo 'b 2) ;; <span class="roman">Add <code>b</code>.</span> + ⇒ (a b c) + +(add-to-ordered-list 'foo 'b 4) ;; <span class="roman">Move <code>b</code>.</span> + ⇒ (a c b) + +(add-to-ordered-list 'foo 'd) ;; <span class="roman">Append <code>d</code>.</span> + ⇒ (a c b d) + +(add-to-ordered-list 'foo 'e) ;; <span class="roman">Add <code>e</code></span>. + ⇒ (a c b e d) + +foo ;; <span class="roman"><code>foo</code> was changed.</span> + ⇒ (a c b e d) +</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/List-Variables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Variables.html</a> + </p> +</div> |