Next: , Up: Sequences   [Contents][Index]

### 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.

Next: , Up: Sequences   [Contents][Index]