Next: Sequence Functions, Previous: Sequence Basics, Up: 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
.
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'smapcar
accepts a single sequence argument. This package'scl-mapcar
works as a compatible superset of both.
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 forcl-mapcar
), ornil
(in which case the results are thrown away andcl-map
returnsnil
).
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 likecl-mapcar
except that it passes in the list pointers themselves rather than the cars of the advancing pointers.
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 ofcl-mapc
is seq, the first sequence. This function is more general than the Emacs primitivemapc
. (Note that this function is calledcl-mapc
even in cl.el, rather thanmapc*
as you might expect.)
This function is like
cl-maplist
, except that it throws away the values returned by function.
This function is like
cl-mapcar
, except that it concatenates the return values (which must be lists) usingnconc
, rather than simply collecting them into a list.
This function is like
cl-maplist
, except that it concatenates the return values usingnconc
.
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 returnsnil
. Given several sequence arguments, it steps through the sequences in parallel until the shortest one runs out, just as incl-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
.
This function calls predicate on each element of the sequence(s) in turn; it returns
nil
as soon as predicate returnsnil
for any element, ort
if the predicate was true for all elements.
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, ort
if the predicate wasnil
for all elements.
This function calls predicate on each element of the sequence(s) in turn; it returns a non-
nil
value as soon as predicate returnsnil
for any element, ornil
if the predicate was true for all elements.
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 tocl-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))) ⇒ -2If
: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.