new repository

1 files changed, 62 insertions, 0 deletions

diff --git a/devdocs/elisp/mapping-functions.html b/devdocs/elisp/mapping-functions.html
new file mode 100644
index 00000000..2f920180
--- /dev/null
+++ b/devdocs/elisp/mapping-functions.html
@@ -0,0 +1,62 @@
+ <h3 class="section">Mapping Functions</h3>  <p>A <em>mapping function</em> applies a given function (<em>not</em> a special form or macro) to each element of a list or other collection. Emacs Lisp has several such functions; this section describes <code>mapcar</code>, <code>mapc</code>, <code>mapconcat</code>, and <code>mapcan</code>, which map over a list. See <a href="creating-symbols#Definition-of-mapatoms">Definition of mapatoms</a>, for the function <code>mapatoms</code> which maps over the symbols in an obarray. See <a href="hash-access#Definition-of-maphash">Definition of maphash</a>, for the function <code>maphash</code> which maps over key/value associations in a hash table. </p> <p>These mapping functions do not allow char-tables because a char-table is a sparse array whose nominal range of indices is very large. To map over a char-table in a way that deals properly with its sparse nature, use the function <code>map-char-table</code> (see <a href="char_002dtables">Char-Tables</a>). </p> <dl> <dt id="mapcar">Function: <strong>mapcar</strong> <em>function sequence</em>
+</dt> <dd>
+<p><code>mapcar</code> applies <var>function</var> to each element of <var>sequence</var> in turn, and returns a list of the results. </p> <p>The argument <var>sequence</var> can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string. The result is always a list. The length of the result is the same as the length of <var>sequence</var>. For example: </p> <div class="example"> <pre class="example">(mapcar #'car '((a b) (c d) (e f)))
+     ⇒ (a c e)
+(mapcar #'1+ [1 2 3])
+     ⇒ (2 3 4)
+(mapcar #'string "abc")
+     ⇒ ("a" "b" "c")
+</pre>
+
+<pre class="example">;; <span class="roman">Call each function in <code>my-hooks</code>.</span>
+(mapcar 'funcall my-hooks)
+</pre>
+
+<pre class="example">(defun mapcar* (function &amp;rest args)
+  "Apply FUNCTION to successive cars of all ARGS.
+Return the list of results."
+  ;; <span class="roman">If no list is exhausted,</span>
+  (if (not (memq nil args))
+      ;; <span class="roman">apply function to CARs.</span>
+      (cons (apply function (mapcar #'car args))
+            (apply #'mapcar* function
+                   ;; <span class="roman">Recurse for rest of elements.</span>
+                   (mapcar #'cdr args)))))
+</pre>
+
+<pre class="example">(mapcar* #'cons '(a b c) '(1 2 3 4))
+     ⇒ ((a . 1) (b . 2) (c . 3))
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="mapcan">Function: <strong>mapcan</strong> <em>function sequence</em>
+</dt> <dd>
+<p>This function applies <var>function</var> to each element of <var>sequence</var>, like <code>mapcar</code>, but instead of collecting the results into a list, it returns a single list with all the elements of the results (which must be lists), by altering the results (using <code>nconc</code>; see <a href="rearrangement">Rearrangement</a>). Like with <code>mapcar</code>, <var>sequence</var> can be of any type except a char-table. </p> <div class="example"> <pre class="example">;; <span class="roman">Contrast this:</span>
+(mapcar #'list '(a b c d))
+     ⇒ ((a) (b) (c) (d))
+;; <span class="roman">with this:</span>
+(mapcan #'list '(a b c d))
+     ⇒ (a b c d)
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="mapc">Function: <strong>mapc</strong> <em>function sequence</em>
+</dt> <dd><p><code>mapc</code> is like <code>mapcar</code> except that <var>function</var> is used for side-effects only—the values it returns are ignored, not collected into a list. <code>mapc</code> always returns <var>sequence</var>. </p></dd>
+</dl> <dl> <dt id="mapconcat">Function: <strong>mapconcat</strong> <em>function sequence separator</em>
+</dt> <dd>
+<p><code>mapconcat</code> applies <var>function</var> to each element of <var>sequence</var>; the results, which must be sequences of characters (strings, vectors, or lists), are concatenated into a single string return value. Between each pair of result sequences, <code>mapconcat</code> inserts the characters from <var>separator</var>, which also must be a string, or a vector or list of characters. See <a href="sequences-arrays-vectors">Sequences Arrays Vectors</a>. </p> <p>The argument <var>function</var> must be a function that can take one argument and returns a sequence of characters: a string, a vector, or a list. The argument <var>sequence</var> can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string. </p> <div class="example"> <pre class="example">(mapconcat #'symbol-name
+           '(The cat in the hat)
+           " ")
+     ⇒ "The cat in the hat"
+</pre>
+
+<pre class="example">(mapconcat (lambda (x) (format "%c" (1+ x)))
+           "HAL-8000"
+           "")
+     ⇒ "IBM.9111"
+</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/Mapping-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Mapping-Functions.html</a>
+  </p>
+</div>