diff options
Diffstat (limited to 'devdocs/elisp/building-lists.html')
| -rw-r--r-- | devdocs/elisp/building-lists.html | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/devdocs/elisp/building-lists.html b/devdocs/elisp/building-lists.html new file mode 100644 index 00000000..216000a2 --- /dev/null +++ b/devdocs/elisp/building-lists.html @@ -0,0 +1,134 @@ + <h3 class="section">Building Cons Cells and Lists</h3> <p>Many functions build lists, as lists reside at the very heart of Lisp. <code>cons</code> is the fundamental list-building function; however, it is interesting to note that <code>list</code> is used more times in the source code for Emacs than <code>cons</code>. </p> <dl> <dt id="cons">Function: <strong>cons</strong> <em>object1 object2</em> +</dt> <dd> +<p>This function is the most basic function for building new list structure. It creates a new cons cell, making <var>object1</var> the <small>CAR</small>, and <var>object2</var> the <small>CDR</small>. It then returns the new cons cell. The arguments <var>object1</var> and <var>object2</var> may be any Lisp objects, but most often <var>object2</var> is a list. </p> <div class="example"> <pre class="example">(cons 1 '(2)) + ⇒ (1 2) +</pre> +<pre class="example">(cons 1 '()) + ⇒ (1) +</pre> +<pre class="example">(cons 1 2) + ⇒ (1 . 2) +</pre> +</div> <p><code>cons</code> is often used to add a single element to the front of a list. This is called <em>consing the element onto the list</em>. <a id="DOCF5" href="#FOOT5"><sup>5</sup></a> For example: </p> <div class="example"> <pre class="example">(setq list (cons newelt list)) +</pre> +</div> <p>Note that there is no conflict between the variable named <code>list</code> used in this example and the function named <code>list</code> described below; any symbol can serve both purposes. </p> +</dd> +</dl> <dl> <dt id="list">Function: <strong>list</strong> <em>&rest objects</em> +</dt> <dd> +<p>This function creates a list with <var>objects</var> as its elements. The resulting list is always <code>nil</code>-terminated. If no <var>objects</var> are given, the empty list is returned. </p> <div class="example"> <pre class="example">(list 1 2 3 4 5) + ⇒ (1 2 3 4 5) +</pre> +<pre class="example">(list 1 2 '(3 4 5) 'foo) + ⇒ (1 2 (3 4 5) foo) +</pre> +<pre class="example">(list) + ⇒ nil +</pre> +</div> </dd> +</dl> <dl> <dt id="make-list">Function: <strong>make-list</strong> <em>length object</em> +</dt> <dd> +<p>This function creates a list of <var>length</var> elements, in which each element is <var>object</var>. Compare <code>make-list</code> with <code>make-string</code> (see <a href="creating-strings">Creating Strings</a>). </p> <div class="example"> <pre class="example">(make-list 3 'pigs) + ⇒ (pigs pigs pigs) +</pre> +<pre class="example">(make-list 0 'pigs) + ⇒ nil +</pre> +<pre class="example">(setq l (make-list 3 '(a b))) + ⇒ ((a b) (a b) (a b)) +(eq (car l) (cadr l)) + ⇒ t +</pre> +</div> </dd> +</dl> <dl> <dt id="append">Function: <strong>append</strong> <em>&rest sequences</em> +</dt> <dd> + <p>This function returns a list containing all the elements of <var>sequences</var>. The <var>sequences</var> may be lists, vectors, bool-vectors, or strings, but the last one should usually be a list. All arguments except the last one are copied, so none of the arguments is altered. (See <code>nconc</code> in <a href="rearrangement">Rearrangement</a>, for a way to join lists with no copying.) </p> <p>More generally, the final argument to <code>append</code> may be any Lisp object. The final argument is not copied or converted; it becomes the <small>CDR</small> of the last cons cell in the new list. If the final argument is itself a list, then its elements become in effect elements of the result list. If the final element is not a list, the result is a dotted list since its final <small>CDR</small> is not <code>nil</code> as required in a proper list (see <a href="cons-cells">Cons Cells</a>). </p> +</dd> +</dl> <p>Here is an example of using <code>append</code>: </p> <div class="example"> <pre class="example">(setq trees '(pine oak)) + ⇒ (pine oak) +(setq more-trees (append '(maple birch) trees)) + ⇒ (maple birch pine oak) +</pre> + +<pre class="example">trees + ⇒ (pine oak) +more-trees + ⇒ (maple birch pine oak) +</pre> +<pre class="example">(eq trees (cdr (cdr more-trees))) + ⇒ t +</pre> +</div> <p>You can see how <code>append</code> works by looking at a box diagram. The variable <code>trees</code> is set to the list <code>(pine oak)</code> and then the variable <code>more-trees</code> is set to the list <code>(maple birch pine +oak)</code>. However, the variable <code>trees</code> continues to refer to the original list: </p> <div class="example"> <pre class="example">more-trees trees +| | +| --- --- --- --- -> --- --- --- --- + --> | | |--> | | |--> | | |--> | | |--> nil + --- --- --- --- --- --- --- --- + | | | | + | | | | + --> maple -->birch --> pine --> oak +</pre> +</div> <p>An empty sequence contributes nothing to the value returned by <code>append</code>. As a consequence of this, a final <code>nil</code> argument forces a copy of the previous argument: </p> <div class="example"> <pre class="example">trees + ⇒ (pine oak) +</pre> +<pre class="example">(setq wood (append trees nil)) + ⇒ (pine oak) +</pre> +<pre class="example">wood + ⇒ (pine oak) +</pre> +<pre class="example">(eq wood trees) + ⇒ nil +</pre> +</div> <p>This once was the usual way to copy a list, before the function <code>copy-sequence</code> was invented. See <a href="sequences-arrays-vectors">Sequences Arrays Vectors</a>. </p> <p>Here we show the use of vectors and strings as arguments to <code>append</code>: </p> <div class="example"> <pre class="example">(append [a b] "cd" nil) + ⇒ (a b 99 100) +</pre> +</div> <p>With the help of <code>apply</code> (see <a href="calling-functions">Calling Functions</a>), we can append all the lists in a list of lists: </p> <div class="example"> <pre class="example">(apply 'append '((a b c) nil (x y z) nil)) + ⇒ (a b c x y z) +</pre> +</div> <p>If no <var>sequences</var> are given, <code>nil</code> is returned: </p> <div class="example"> <pre class="example">(append) + ⇒ nil +</pre> +</div> <p>Here are some examples where the final argument is not a list: </p> <div class="example"> <pre class="example">(append '(x y) 'z) + ⇒ (x y . z) +(append '(x y) [z]) + ⇒ (x y . [z]) +</pre> +</div> <p>The second example shows that when the final argument is a sequence but not a list, the sequence’s elements do not become elements of the resulting list. Instead, the sequence becomes the final <small>CDR</small>, like any other non-list final argument. </p> <dl> <dt id="copy-tree">Function: <strong>copy-tree</strong> <em>tree &optional vecp</em> +</dt> <dd> +<p>This function returns a copy of the tree <var>tree</var>. If <var>tree</var> is a cons cell, this makes a new cons cell with the same <small>CAR</small> and <small>CDR</small>, then recursively copies the <small>CAR</small> and <small>CDR</small> in the same way. </p> <p>Normally, when <var>tree</var> is anything other than a cons cell, <code>copy-tree</code> simply returns <var>tree</var>. However, if <var>vecp</var> is non-<code>nil</code>, it copies vectors too (and operates recursively on their elements). </p> +</dd> +</dl> <dl> <dt id="flatten-tree">Function: <strong>flatten-tree</strong> <em>tree</em> +</dt> <dd><p>This function returns a “flattened” copy of <var>tree</var>, that is, a list containing all the non-<code>nil</code> terminal nodes, or leaves, of the tree of cons cells rooted at <var>tree</var>. Leaves in the returned list are in the same order as in <var>tree</var>. </p></dd> +</dl> <div class="example"> <pre class="example">(flatten-tree '(1 (2 . 3) nil (4 5 (6)) 7)) + ⇒(1 2 3 4 5 6 7) +</pre> +</div> <dl> <dt id="ensure-list">Function: <strong>ensure-list</strong> <em>object</em> +</dt> <dd> +<p>This function returns <var>object</var> as a list. If <var>object</var> is already a list, the function returns it; otherwise, the function returns a one-element list containing <var>object</var>. </p> <p>This is usually useful if you have a variable that may or may not be a list, and you can then say, for instance: </p> <div class="lisp"> <pre class="lisp">(dolist (elem (ensure-list foo)) + (princ elem)) +</pre> +</div> </dd> +</dl> <dl> <dt id="number-sequence">Function: <strong>number-sequence</strong> <em>from &optional to separation</em> +</dt> <dd> +<p>This function returns a list of numbers starting with <var>from</var> and incrementing by <var>separation</var>, and ending at or just before <var>to</var>. <var>separation</var> can be positive or negative and defaults to 1. If <var>to</var> is <code>nil</code> or numerically equal to <var>from</var>, the value is the one-element list <code>(<var>from</var>)</code>. If <var>to</var> is less than <var>from</var> with a positive <var>separation</var>, or greater than <var>from</var> with a negative <var>separation</var>, the value is <code>nil</code> because those arguments specify an empty sequence. </p> <p>If <var>separation</var> is 0 and <var>to</var> is neither <code>nil</code> nor numerically equal to <var>from</var>, <code>number-sequence</code> signals an error, since those arguments specify an infinite sequence. </p> <p>All arguments are numbers. Floating-point arguments can be tricky, because floating-point arithmetic is inexact. For instance, depending on the machine, it may quite well happen that <code>(number-sequence 0.4 0.6 0.2)</code> returns the one element list <code>(0.4)</code>, whereas <code>(number-sequence 0.4 0.8 0.2)</code> returns a list with three elements. The <var>n</var>th element of the list is computed by the exact formula <code>(+ <var>from</var> (* <var>n</var> <var>separation</var>))</code>. Thus, if one wants to make sure that <var>to</var> is included in the list, one can pass an expression of this exact type for <var>to</var>. Alternatively, one can replace <var>to</var> with a slightly larger value (or a slightly more negative value if <var>separation</var> is negative). </p> <p>Some examples: </p> <div class="example"> <pre class="example">(number-sequence 4 9) + ⇒ (4 5 6 7 8 9) +(number-sequence 9 4 -1) + ⇒ (9 8 7 6 5 4) +(number-sequence 9 4 -2) + ⇒ (9 7 5) +(number-sequence 8) + ⇒ (8) +(number-sequence 8 5) + ⇒ nil +(number-sequence 5 8 -1) + ⇒ nil +(number-sequence 1.5 6 2) + ⇒ (1.5 3.5 5.5) +</pre> +</div> </dd> +</dl><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/Building-Lists.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Building-Lists.html</a> + </p> +</div> |