cl: Sequence Basics
9.1 Sequence Basics
===================
Many of the sequence functions take keyword arguments; 
Argument
Lists. All keyword arguments are optional and, if specified, may
appear in any order.
The ‘: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, ‘(cl-find x y :key
'car)’ is similar to ‘(cl-assoc x y)’. It searches for an element of
the list whose CAR equals ‘x’, rather than for an element which equals
‘x’ itself. If ‘:key’ is omitted or ‘nil’, the filter is effectively
the identity function.
The ‘:test’ and ‘: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.) The ‘:test’ argument specifies a function which must
return true (non-‘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 ‘eql’.
Many functions that take ITEM and ‘:test’ or ‘:test-not’ arguments
also come in ‘-if’ and ‘-if-not’ varieties, 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:
(cl-remove 0 seq :test '=) ≡ (cl-remove-if 'zerop seq)
to remove all zeros from sequence ‘seq’.
Some operations can work on a subsequence of the argument sequence;
these function take ‘:start’ and ‘: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 ‘:start1’ and ‘:end1’ for
the first, and ‘:start2’ and ‘:end2’ for the second.
A few functions accept a ‘:from-end’ argument, which, if non-‘nil’,
causes the operation to go from right-to-left through the sequence
instead of left-to-right, and a ‘:count’ 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 which
the ‘:test’, ‘:test-not’, and ‘:key’ functions are called on various
elements. Therefore, it is a bad idea to depend on side effects of
these functions. For example, ‘:from-end’ 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
‘cl-mapcar’ and ‘cl-every’, _do_ specify exactly the order in which the
function is called so side effects are perfectly acceptable in those
cases.)
Strings 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 example, ‘(cl-remove ?A STR)’ may
or may not preserve the properties of the characters copied from STR
into the result.
Info Catalog
cl: Sequences
cl: Mapping over Sequences