1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
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>
|
