cl: Mapping over Sequences
9.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: cl-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 ‘cl-mapcar’ works as a compatible superset of both.
-- Function: cl-map result-type function seq &rest more-seqs
This function maps FUNCTION over the argument sequences, just like
‘cl-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 ‘cl-mapcar’), or ‘nil’ (in which case the results are thrown
away and ‘cl-map’ returns ‘nil’).
-- Function: cl-maplist function list &rest more-lists
This function calls FUNCTION on each of its argument lists, then on
the CDRs of those lists, and so on, until the shortest list runs
out. The results are returned in the form of a list. Thus,
‘cl-maplist’ is like ‘cl-mapcar’ except that it passes in the list
pointers themselves rather than the CARs of the advancing pointers.
-- Function: cl-mapc function seq &rest more-seqs
This function is like ‘cl-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’. (Note that this function is called ‘cl-mapc’ even in
‘cl.el’, rather than ‘mapc*’ as you might expect.)
-- Function: cl-mapl function list &rest more-lists
This function is like ‘cl-maplist’, except that it throws away the
values returned by FUNCTION.
-- Function: cl-mapcan function seq &rest more-seqs
This function is like ‘cl-mapcar’, except that it concatenates the
return values (which must be lists) using ‘nconc’, rather than
simply collecting them into a list.
-- Function: cl-mapcon function list &rest more-lists
This function is like ‘cl-maplist’, except that it concatenates the
return values using ‘nconc’.
-- Function: cl-some predicate seq &rest more-seqs
This function calls PREDICATE on each element of SEQ in turn; if
PREDICATE returns a non-‘nil’ value, ‘cl-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 ‘cl-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: cl-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: cl-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: cl-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 ‘nil’ if the predicate was true for all
elements.
-- Function: cl-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 ‘cl-reduce’.
If ‘:from-end’ is true, the reduction is right-associative instead
of left-associative:
(cl-reduce '- '(1 2 3 4))
≡ (- (- (- 1 2) 3) 4) ⇒ -8
(cl-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 ‘cl-loop’ macro. In compiled code, ‘cl-loop’ will be
faster since it generates the loop as in-line code with no function
calls.
Info Catalog
cl: Sequence Basics
cl: Sequences
cl: Sequence Functions