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
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
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>
|
