summaryrefslogtreecommitdiff
path: root/devdocs/elisp/list-variables.html
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2025-08-14 22:58:58 -0500
committerCraig Jennings <c@cjennings.net>2025-08-14 22:58:58 -0500
commit82ba818ff456bcd6d56a06226e3f27e98fbb55c3 (patch)
tree158cfc17b2f644a10f063cb546752cfaae12c97f /devdocs/elisp/list-variables.html
parent9278ddd4ea1a8b1a4c1edaa8894516e3f48d245b (diff)
downloaddotemacs-82ba818ff456bcd6d56a06226e3f27e98fbb55c3.tar.gz
dotemacs-82ba818ff456bcd6d56a06226e3f27e98fbb55c3.zip
removing all downloaded devdocs files
Diffstat (limited to 'devdocs/elisp/list-variables.html')
-rw-r--r--devdocs/elisp/list-variables.html66
1 files changed, 0 insertions, 66 deletions
diff --git a/devdocs/elisp/list-variables.html b/devdocs/elisp/list-variables.html
deleted file mode 100644
index 37df9e3b..00000000
--- a/devdocs/elisp/list-variables.html
+++ /dev/null
@@ -1,66 +0,0 @@
- <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 &amp;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 &amp;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 &copy; 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>