A mapping function applies a given function (not a
special form or macro) to each element of a list or other collection.
Emacs Lisp has several such functions; this section describes
mapcar
, mapc
, mapconcat
, and mapcan
, which
map over a list. 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 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 map-char-table
(see Char-Tables).
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))
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)
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.
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"