new repository

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>&amp;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>&amp;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
+|                           |
+|     --- ---      --- ---   -&gt; --- ---      --- ---
+ --&gt; |   |   |--&gt; |   |   |--&gt; |   |   |--&gt; |   |   |--&gt; nil
+      --- ---      --- ---      --- ---      --- ---
+       |            |            |            |
+       |            |            |            |
+        --&gt; maple    --&gt;birch     --&gt; pine     --&gt; 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 &amp;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 &amp;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 &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/Building-Lists.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Building-Lists.html</a>
+  </p>
+</div>