diff options
| author | Craig Jennings <c@cjennings.net> | 2025-08-14 22:58:58 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2025-08-14 22:58:58 -0500 |
| commit | 82ba818ff456bcd6d56a06226e3f27e98fbb55c3 (patch) | |
| tree | 158cfc17b2f644a10f063cb546752cfaae12c97f /devdocs/elisp/list-variables.html | |
| parent | 9278ddd4ea1a8b1a4c1edaa8894516e3f48d245b (diff) | |
| download | dotemacs-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.html | 66 |
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 &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> |
