9.1 Sequence Basics

Many of the sequence functions take keyword arguments; see 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.