Common Lisp defines a number of functions that operate on
sequences, which are either lists, strings, or vectors.
Emacs Lisp includes a few of these, notably
length; this package defines most of the rest.
Many of the sequence functions take keyword arguments; see section Argument Lists. All keyword arguments are optional and, if specified, may appear in any order.
:key argument should be passed either
nil, or a
function of one argument. This key function is used as a filter
through which the elements of the sequence are seen; for example,
(find x y :key 'car) is similar to
(assoc* x y):
It searches for an element of the list whose
x, rather than for an element which equals
:key is omitted or
nil, the filter is effectively
the identity function.
:test-not arguments should be either
nil, or functions of two arguments. The test function is
used to compare two sequence elements, or to compare a search value
with sequence elements. (The two values are passed to the test
function in the same order as the original sequence function
arguments from which they are derived, or, if they both come from
the same sequence, in the same order as they appear in that sequence.)
:test argument specifies a function which must return
nil) to indicate a match; instead, you may use
:test-not to give a function which returns false to
indicate a match. The default test function is
Many functions which take item and
arguments also come in
where a predicate function is passed instead of item,
and sequence elements match if the predicate returns true on them
(or false in the case of
-if-not). For example:
(remove* 0 seq :test '=) == (remove-if 'zerop seq)
to remove all zeros from sequence
Some operations can work on a subsequence of the argument sequence;
these function take
:end arguments which
default to zero and the length of the sequence, respectively.
Only elements between start (inclusive) and end
(exclusive) are affected by the operation. The end argument
may be passed
nil to signify the length of the sequence;
otherwise, both start and end must be integers, with
0 <= start <= end <= (length seq).
If the function takes two sequence arguments, the limits are
defined by keywords
:end1 for the first,
:end2 for the second.
A few functions accept a
:from-end argument, which, if
nil, causes the operation to go from right-to-left
through the sequence instead of left-to-right, and a
argument, which specifies an integer maximum number of elements
to be removed or otherwise processed.
The sequence functions make no guarantees about the order in
are called on various elements. Therefore, it is a bad idea to depend
on side effects of these functions. For example,
may cause the sequence to be scanned actually in reverse, or it may
be scanned forwards but computing a result "as if" it were scanned
backwards. (Some functions, like
do specify exactly the order in which the function is called
so side effects are perfectly acceptable in those cases.)
Strings in GNU Emacs 19 may contain "text properties" as well
as character data. Except as noted, it is undefined whether or
not text properties are preserved by sequence functions. For
(remove* ?A str) may or may not preserve
the properties of the characters copied from str into the
These functions "map" the function you specify over the elements
of lists or arrays. They are all variations on the theme of the
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.
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.
mapcar*, but it returns a sequence of type result-type rather than a list. result-type must be one of the following symbols:
list(in which case the effect is the same as for
nil(in which case the results are thrown away and
cdrs of those lists, and so on, until the shortest list runs out. The results are returned in the form of a list. Thus,
mapcar*except that it passes in the list pointers themselves rather than the
cars of the advancing pointers.
mapcar*, except that the values returned by function are ignored and thrown away rather than being collected into a list. The return value of
mapcis seq, the first sequence.
maplist, except that it throws away the values returned by function.
mapcar*, except that it concatenates the return values (which must be lists) using
nconc, rather than simply collecting them into a list.
maplist, except that it concatenates the return values using
somereturns 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-
nilas soon as predicate returns
nilfor any element, or
tif the predicate was true for all elements.
nilas soon as predicate returns a non-
nilvalue for any element, or
tif the predicate was
nilfor all elements.
nilvalue as soon as predicate returns
nilfor any element, or
tif the predicate was true for all elements.
*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
:from-end is true, the reduction is right-associative instead
(reduce '- '(1 2 3 4)) == (- (- (- 1 2) 3) 4) => -8 (reduce '- '(1 2 3 4) :from-end t) == (- 1 (- 2 (- 3 4))) => -2
:key is specified, it is a function of one argument which
is called on each of the sequence elements in turn.
:initial-value is specified, it is effectively added to the
front (or rear in the case of
:from-end) of the sequence.
: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,
be faster since it generates the loop as in-line code with no
This section describes a number of Common Lisp functions for operating on sequences.
As an extension to Common Lisp, start and/or end
may be negative, in which case they represent a distance back
from the end of the sequence. This is for compatibility with
substring function. Note that
the only sequence function that allows negative
start and end.
You can use
setf on a
subseq form to replace a
specified range of elements with elements from another sequence.
The replacement is done as if by
replace, described below.
list. The arguments are always copied, even in cases such as
(concatenate 'list '(1 2 3))where the result is identical to an argument.
If seq1 and seq2 are
eq, then the replacement
will work correctly even if the regions indicated by the start
and end arguments overlap. However, if seq1 and seq2
are lists which share storage but are not
eq, and the
start and end arguments specify overlapping regions, the effect
eqto seq in some circumstances, but the original seq will not be modified. The
:keyarguments define the matching test that is used; by default, elements
eqlto item are removed. The
:countargument specifies the maximum number of matching elements that can be removed (only the leftmost count matches are removed). The
:endarguments specify a region in seq in which elements will be removed; elements outside that region are not matched or removed. The
:from-endargument, if true, says that elements should be deleted from the end of the sequence rather than the beginning (this matters only if count was also specified).
remove*for those sequence types. On lists,
remove*will copy the list if necessary to preserve the original list, whereas
delete*will splice out parts of the argument list. Compare
nconc, which are analogous non-destructive and destructive list operations in Emacs Lisp.
The predicate-oriented functions
delete-if-not are defined similarly.
equalto item. The
deletefunction is built-in to Emacs 19; this package defines it equivalently in Emacs 18.
equalto item. This package defines it for symmetry with
delete, even though
removeis not built-in to Emacs 19.
eqto item. This package defines it for symmetry with
delq, even though
remqis not built-in to Emacs 19.
:keyarguments, only the rightmost one is retained. If
:from-endis true, the leftmost one is retained instead. If
:endis specified, only elements within that subsequence are examined or removed.
:from-endarguments may be used to limit the number of substitutions made.
substitute; it performs the substitution using
asetrather than by returning a changed copy of the sequence.
nsubstitute-if-not functions are defined similarly. For
these, a predicate is given in place of the old argument.
These functions search for elements or subsequences in a sequence.
assoc*; see section Lists.)
nil. It returns the leftmost match, unless
:from-endis true, in which case it returns the rightmost match. The
:endarguments may be used to limit the range of elements that are searched.
find, except that it returns the integer position in the sequence of the matching item rather than the item itself. The position is relative to the start of the sequence as a whole, even if
:startis non-zero. The function returns
nilif no matching element was found.
functions are defined similarly.
:key), the function returns
nil. If there is a mismatch, the function returns the index (relative to seq1) of the first mismatching element. This will be the leftmost pair of elements which do not match, or the position at which the shorter of the two otherwise-matching sequences runs out.
:from-end is true, then the elements are compared from right
to left starting at
(1- end1) and
If the sequences differ, then one plus the index of the rightmost
difference (relative to seq1) is returned.
An interesting example is
(mismatch str1 str2 :key 'upcase),
which compares two strings case-insensitively.
:end1.) Only matches which fall entirely within the region defined by
:end2will be considered. The return value is the index of the leftmost element of the leftmost match, relative to the start of seq2, or
nilif no matches were found. If
:from-endis true, the function finds the rightmost matching subsequence.
nil) if and only if its first argument is less than (not equal to) its second argument. For example,
string-lesspare suitable predicate functions for sorting numbers and strings, respectively;
>would sort numbers into decreasing rather than increasing order.
This function differs from Emacs' built-in
sort in that it
can operate on any type of sequence, not just lists. Also, it
:key argument which is used to preprocess data
fed to the predicate function. For example,
(setq data (sort data 'string-lessp :key 'downcase))
sorts data, a sequence of strings, into increasing alphabetical
order without regard to case. A
:key function of
would be useful for sorting association lists.
sort* function is destructive; it sorts lists by actually
cdr pointers in suitable fashion.
stable-sort are equivalent
in Emacs Lisp because the underlying
sort function is
stable by default. However, this package reserves the right to
use non-stable methods for
sort* in the future.
concatenate), has length equal to the sum of the lengths of the two input sequences. The sequences may be modified destructively. Order of elements within seq1 and seq2 is preserved in the interleaving; elements of the two sequences are compared by predicate (in the sense of
sort) and the lesser element goes first in the result. When elements are equal, those from seq1 precede those from seq2 in the result. Thus, if seq1 and seq2 are both sorted according to predicate, then the result will be a merged sequence which is (stably) sorted according to predicate.
Go to the first, previous, next, last section, table of contents.