Next: Sequence Functions, Previous: Sequence Basics, Up: Sequences

### 10.2 Mapping over Sequences

These functions “map” the function you specify over the elements of lists or arrays. They are all variations on the theme of the built-in function `mapcar`.

— Function: mapcar* function seq &rest more-seqs

> This function calls function on successive parallel sets of elements from its argument sequences. Given a single seq argument it is equivalent to `mapcar`; given n sequences, it calls the function with the first elements of each of the sequences as the n arguments to yield the first element of the result list, then with the second elements, and so on. The mapping stops as soon as the shortest sequence runs out. The argument sequences may be any mixture of lists, strings, and vectors; the return sequence is always a list.

> Common Lisp's `mapcar` accepts multiple arguments but works only on lists; Emacs Lisp's `mapcar` accepts a single sequence argument. This package's `mapcar*` works as a compatible superset of both.

— Function: map result-type function seq &rest more-seqs

> This function maps function over the argument sequences, just like `mapcar*`, but it returns a sequence of type result-type rather than a list. result-type must be one of the following symbols: `vector`, `string`, `list` (in which case the effect is the same as for `mapcar*`), or `nil` (in which case the results are thrown away and `map` returns `nil`).

— Function: maplist function list &rest more-lists

> This function calls function on each of its argument lists, then on the `cdr`s of those lists, and so on, until the shortest list runs out. The results are returned in the form of a list. Thus, `maplist` is like `mapcar*` except that it passes in the list pointers themselves rather than the `car`s of the advancing pointers.

— Function: cl-mapc function seq &rest more-seqs

> This function is like `mapcar*`, except that the values returned by function are ignored and thrown away rather than being collected into a list. The return value of `cl-mapc` is seq, the first sequence. This function is more general than the Emacs primitive `mapc`.

— Function: mapl function list &rest more-lists

> This function is like `maplist`, except that it throws away the values returned by function.

— Function: mapcan function seq &rest more-seqs

> This function is like `mapcar*`, except that it concatenates the return values (which must be lists) using `nconc`, rather than simply collecting them into a list.

— Function: mapcon function list &rest more-lists

> This function is like `maplist`, except that it concatenates the return values using `nconc`.

— Function: some predicate seq &rest more-seqs

> This function calls predicate on each element of seq in turn; if predicate returns a non-`nil` value, `some` returns that value, otherwise it returns `nil`. Given several sequence arguments, it steps through the sequences in parallel until the shortest one runs out, just as in `mapcar*`. You can rely on the left-to-right order in which the elements are visited, and on the fact that mapping stops immediately as soon as predicate returns non-`nil`.

— Function: every predicate seq &rest more-seqs

> This function calls predicate on each element of the sequence(s) in turn; it returns `nil` as soon as predicate returns `nil` for any element, or `t` if the predicate was true for all elements.

— Function: notany predicate seq &rest more-seqs

> This function calls predicate on each element of the sequence(s) in turn; it returns `nil` as soon as predicate returns a non-`nil` value for any element, or `t` if the predicate was `nil` for all elements.

— Function: notevery predicate seq &rest more-seqs

> This function calls predicate on each element of the sequence(s) in turn; it returns a non-`nil` value as soon as predicate returns `nil` for any element, or `t` if the predicate was true for all elements.

— Function: reduce function seq `&key :from-end :start :end :initial-value :key`

> This function combines the elements of seq using an associative binary operation. Suppose function is `*` and seq is the list `(2 3 4 5)`. The first two elements of the list are combined with `(* 2 3) = 6`; this is combined with the next element, `(* 6 4) = 24`, and that is combined with the final element: `(* 24 5) = 120`. Note that the `*` function happens to be self-reducing, so that `(* 2 3 4 5)` has the same effect as an explicit call to `reduce`.

> If `:from-end` is true, the reduction is right-associative instead of left-associative:

>               (reduce '- '(1 2 3 4))
>                    == (- (- (- 1 2) 3) 4) ⇒ -8
>               (reduce '- '(1 2 3 4) :from-end t)
>                    == (- 1 (- 2 (- 3 4))) ⇒ -2

> If `:key` is specified, it is a function of one argument which is called on each of the sequence elements in turn.

> If `:initial-value` is specified, it is effectively added to the front (or rear in the case of `:from-end`) of the sequence. The `:key` function is not applied to the initial value.

> If the sequence, including the initial value, has exactly one element then that element is returned without ever calling function. If the sequence is empty (and there is no initial value), then function is called with no arguments to obtain the return value.

All of these mapping operations can be expressed conveniently in terms of the `loop` macro. In compiled code, `loop` will be faster since it generates the loop as in-line code with no function calls.