GNU Info

(elisp)Mapping Functions

---

Next: Anonymous Functions Prev: Calling Functions Up: Functions

---

Enter node , (file) or (file)node

Mapping Functions
=================

   A "mapping function" applies a given function to each element of a
list or other collection.  Emacs Lisp has several such functions;
`mapcar' and `mapconcat', which scan a list, are described here.  Note:
Creating Symbols, for the function `mapatoms' which maps over the
symbols in an obarray.  Note: Hash Access, 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' (Note: 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 'char-to-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: 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 separator
     `mapconcat' applies FUNCTION to each element of SEQUENCE: the
     results, which must be strings, are concatenated.  Between each
     pair of result strings, `mapconcat' inserts the string SEPARATOR.
     Usually SEPARATOR contains a space or comma or other suitable
     punctuation.

     The argument FUNCTION must be a function that can take one
     argument and return a string.  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 (function (lambda (x) (format "%c" (1+ x))))
                     "HAL-8000"
                     "")
               => "IBM.9111"