diff options
Diffstat (limited to 'devdocs/elisp/mapping-functions.html')
| -rw-r--r-- | devdocs/elisp/mapping-functions.html | 62 |
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 &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 © 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> |