---

13.6 Mapping Functions

A mapping function applies a given function (not a special form or macro) to each element of a sequence, such as a list or a vector or a string (see Sequences, Arrays, and Vectors). Emacs Lisp has several such functions; this section describes mapcar, mapc, mapconcat, and mapcan, which map over sequences. See Definition of mapatoms, for the function mapatoms which maps over the symbols in an obarray. See Definition of maphash, for the function maphash which maps over key/value associations in a hash table.

These mapping functions do not work on 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 map-char-table (see Char-Tables).

Function: mapcar function sequence ¶

mapcar applies function to each element of sequence in turn, and returns a list of the results.

The argument sequence 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 sequence. For 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")

;; Call each function in my-hooks.
(mapcar 'funcall my-hooks)

(defun mapcar* (function &rest args)
 "Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
 ;; If no list is exhausted,
 (if (not (memq nil args))
 ;; apply function to CARs.
 (cons (apply function (mapcar #'car args))
 (apply #'mapcar* function
 ;; Recurse for rest of elements.
 (mapcar #'cdr args)))))

(mapcar* #'cons '(a b c) '(1 2 3 4))
 ⇒ ((a . 1) (b . 2) (c . 3))

Function: mapcan function sequence ¶

This function applies function to each element of sequence, like mapcar, 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 nconc; see Functions that Rearrange Lists). Like with mapcar, sequence can be of any type except a char-table.

;; Contrast this:
(mapcar #'list '(a b c d))
 ⇒ ((a) (b) (c) (d))
;; with this:
(mapcan #'list '(a b c d))
 ⇒ (a b c d)

Function: mapc function sequence ¶

mapc is like mapcar except that function is used for side-effects only—the values it returns are ignored, not collected into a list. mapc always returns sequence.

Function: mapconcat function sequence &optional separator ¶

mapconcat applies function to each element of sequence; 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, mapconcat inserts the characters from separator, which also must be a string, or a vector or list of characters; a nil value is treated as the empty string. See Sequences, Arrays, and Vectors.

The argument function must be a function that can take one argument and returns a sequence of characters: a string, a vector, or a list. The argument sequence can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string.

(mapconcat #'symbol-name
 '(The cat in the hat)
 " ")
 ⇒ "The cat in the hat"

(mapconcat (lambda (x) (format "%c" (1+ x)))
 "HAL-8000")
 ⇒ "IBM.9111"

Next: Anonymous Functions, Previous: Calling Functions, Up: Functions [Contents][Index]