new repository

1 files changed, 98 insertions, 0 deletions

diff --git a/devdocs/elisp/list-elements.html b/devdocs/elisp/list-elements.html
new file mode 100644
index 00000000..9c7f55fb
--- /dev/null
+++ b/devdocs/elisp/list-elements.html
@@ -0,0 +1,98 @@
+ <h3 class="section">Accessing Elements of Lists</h3>  <dl> <dt id="car">Function: <strong>car</strong> <em>cons-cell</em>
+</dt> <dd>
+<p>This function returns the value referred to by the first slot of the cons cell <var>cons-cell</var>. In other words, it returns the <small>CAR</small> of <var>cons-cell</var>. </p> <p>As a special case, if <var>cons-cell</var> is <code>nil</code>, this function returns <code>nil</code>. Therefore, any list is a valid argument. An error is signaled if the argument is not a cons cell or <code>nil</code>. </p> <div class="example"> <pre class="example">(car '(a b c))
+     ⇒ a
+</pre>
+<pre class="example">(car '())
+     ⇒ nil
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="cdr">Function: <strong>cdr</strong> <em>cons-cell</em>
+</dt> <dd>
+<p>This function returns the value referred to by the second slot of the cons cell <var>cons-cell</var>. In other words, it returns the <small>CDR</small> of <var>cons-cell</var>. </p> <p>As a special case, if <var>cons-cell</var> is <code>nil</code>, this function returns <code>nil</code>; therefore, any list is a valid argument. An error is signaled if the argument is not a cons cell or <code>nil</code>. </p> <div class="example"> <pre class="example">(cdr '(a b c))
+     ⇒ (b c)
+</pre>
+<pre class="example">(cdr '())
+     ⇒ nil
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="car-safe">Function: <strong>car-safe</strong> <em>object</em>
+</dt> <dd>
+<p>This function lets you take the <small>CAR</small> of a cons cell while avoiding errors for other data types. It returns the <small>CAR</small> of <var>object</var> if <var>object</var> is a cons cell, <code>nil</code> otherwise. This is in contrast to <code>car</code>, which signals an error if <var>object</var> is not a list. </p> <div class="example"> <pre class="example">(car-safe <var>object</var>)
+≡
+(let ((x <var>object</var>))
+  (if (consp x)
+      (car x)
+    nil))
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="cdr-safe">Function: <strong>cdr-safe</strong> <em>object</em>
+</dt> <dd>
+<p>This function lets you take the <small>CDR</small> of a cons cell while avoiding errors for other data types. It returns the <small>CDR</small> of <var>object</var> if <var>object</var> is a cons cell, <code>nil</code> otherwise. This is in contrast to <code>cdr</code>, which signals an error if <var>object</var> is not a list. </p> <div class="example"> <pre class="example">(cdr-safe <var>object</var>)
+≡
+(let ((x <var>object</var>))
+  (if (consp x)
+      (cdr x)
+    nil))
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="pop">Macro: <strong>pop</strong> <em>listname</em>
+</dt> <dd>
+<p>This macro provides a convenient way to examine the <small>CAR</small> of a list, and take it off the list, all at once. It operates on the list stored in <var>listname</var>. It removes the first element from the list, saves the <small>CDR</small> into <var>listname</var>, then returns the removed element. </p> <p>In the simplest case, <var>listname</var> is an unquoted symbol naming a list; in that case, this macro is equivalent to <code>(prog1 (car listname) (setq listname (cdr listname)))</code>. </p> <div class="example"> <pre class="example">x
+     ⇒ (a b c)
+(pop x)
+     ⇒ a
+x
+     ⇒ (b c)
+</pre>
+</div> <p>More generally, <var>listname</var> can be a generalized variable. In that case, this macro saves into <var>listname</var> using <code>setf</code>. See <a href="generalized-variables">Generalized Variables</a>. </p> <p>For the <code>push</code> macro, which adds an element to a list, See <a href="list-variables">List Variables</a>. </p>
+</dd>
+</dl> <dl> <dt id="nth">Function: <strong>nth</strong> <em>n list</em>
+</dt> <dd>
+<p>This function returns the <var>n</var>th element of <var>list</var>. Elements are numbered starting with zero, so the <small>CAR</small> of <var>list</var> is element number zero. If the length of <var>list</var> is <var>n</var> or less, the value is <code>nil</code>. </p> <div class="example"> <pre class="example">(nth 2 '(1 2 3 4))
+     ⇒ 3
+</pre>
+<pre class="example">(nth 10 '(1 2 3 4))
+     ⇒ nil
+
+(nth n x) ≡ (car (nthcdr n x))
+</pre>
+</div> <p>The function <code>elt</code> is similar, but applies to any kind of sequence. For historical reasons, it takes its arguments in the opposite order. See <a href="sequence-functions">Sequence Functions</a>. </p>
+</dd>
+</dl> <dl> <dt id="nthcdr">Function: <strong>nthcdr</strong> <em>n list</em>
+</dt> <dd>
+<p>This function returns the <var>n</var>th <small>CDR</small> of <var>list</var>. In other words, it skips past the first <var>n</var> links of <var>list</var> and returns what follows. </p> <p>If <var>n</var> is zero, <code>nthcdr</code> returns all of <var>list</var>. If the length of <var>list</var> is <var>n</var> or less, <code>nthcdr</code> returns <code>nil</code>. </p> <div class="example"> <pre class="example">(nthcdr 1 '(1 2 3 4))
+     ⇒ (2 3 4)
+</pre>
+<pre class="example">(nthcdr 10 '(1 2 3 4))
+     ⇒ nil
+</pre>
+<pre class="example">(nthcdr 0 '(1 2 3 4))
+     ⇒ (1 2 3 4)
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="last">Function: <strong>last</strong> <em>list &amp;optional n</em>
+</dt> <dd><p>This function returns the last link of <var>list</var>. The <code>car</code> of this link is the list’s last element. If <var>list</var> is null, <code>nil</code> is returned. If <var>n</var> is non-<code>nil</code>, the <var>n</var>th-to-last link is returned instead, or the whole of <var>list</var> if <var>n</var> is bigger than <var>list</var>’s length. </p></dd>
+</dl> <dl> <dt id="safe-length">Function: <strong>safe-length</strong> <em>list</em>
+</dt> <dd>
+<p>This function returns the length of <var>list</var>, with no risk of either an error or an infinite loop. It generally returns the number of distinct cons cells in the list. However, for circular lists, the value is just an upper bound; it is often too large. </p> <p>If <var>list</var> is not <code>nil</code> or a cons cell, <code>safe-length</code> returns 0. </p>
+</dd>
+</dl> <p>The most common way to compute the length of a list, when you are not worried that it may be circular, is with <code>length</code>. See <a href="sequence-functions">Sequence Functions</a>. </p> <dl> <dt id="caar">Function: <strong>caar</strong> <em>cons-cell</em>
+</dt> <dd><p>This is the same as <code>(car (car <var>cons-cell</var>))</code>. </p></dd>
+</dl> <dl> <dt id="cadr">Function: <strong>cadr</strong> <em>cons-cell</em>
+</dt> <dd><p>This is the same as <code>(car (cdr <var>cons-cell</var>))</code> or <code>(nth 1 <var>cons-cell</var>)</code>. </p></dd>
+</dl> <dl> <dt id="cdar">Function: <strong>cdar</strong> <em>cons-cell</em>
+</dt> <dd><p>This is the same as <code>(cdr (car <var>cons-cell</var>))</code>. </p></dd>
+</dl> <dl> <dt id="cddr">Function: <strong>cddr</strong> <em>cons-cell</em>
+</dt> <dd><p>This is the same as <code>(cdr (cdr <var>cons-cell</var>))</code> or <code>(nthcdr 2 <var>cons-cell</var>)</code>. </p></dd>
+</dl>                         <p>In addition to the above, 24 additional compositions of <code>car</code> and <code>cdr</code> are defined as <code>c<var>xxx</var>r</code> and <code>c<var>xxxx</var>r</code>, where each <code><var>x</var></code> is either <code>a</code> or <code>d</code>. <code>cadr</code>, <code>caddr</code>, and <code>cadddr</code> pick out the second, third or fourth elements of a list, respectively. <samp>cl-lib</samp> provides the same under the names <code>cl-second</code>, <code>cl-third</code>, and <code>cl-fourth</code>. See <a href="https://www.gnu.org/software/emacs/manual/html_node/cl/List-Functions.html#List-Functions">List Functions</a> in <cite>Common Lisp Extensions</cite>. </p> <dl> <dt id="butlast">Function: <strong>butlast</strong> <em>x &amp;optional n</em>
+</dt> <dd><p>This function returns the list <var>x</var> with the last element, or the last <var>n</var> elements, removed. If <var>n</var> is greater than zero it makes a copy of the list so as not to damage the original list. In general, <code>(append (butlast <var>x</var> <var>n</var>)
+(last <var>x</var> <var>n</var>))</code> will return a list equal to <var>x</var>. </p></dd>
+</dl> <dl> <dt id="nbutlast">Function: <strong>nbutlast</strong> <em>x &amp;optional n</em>
+</dt> <dd><p>This is a version of <code>butlast</code> that works by destructively modifying the <code>cdr</code> of the appropriate element, rather than making a copy of the list. </p></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/List-Elements.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Elements.html</a>
+  </p>
+</div>