Next: , Up: Lists

### 10.1 List Functions

This section describes a number of simple operations on lists, i.e., chains of cons cells.

This function is equivalent to `(car (cdr (cdr `x`)))`. Likewise, this package aliases all 24 `c`xxx`r` functions where xxx is up to four ‘a’s and/or ‘d’s. All of these functions are `setf`-able, and calls to them are expanded inline by the byte-compiler for maximum efficiency.

— Function: cl-first x

This function is a synonym for `(car `x`)`. Likewise, the functions `cl-second`, `cl-third`, ..., through `cl-tenth` return the given element of the list x.

— Function: cl-rest x

This function is a synonym for `(cdr `x`)`.

— Function: cl-endp x

This function acts like `null`, but signals an error if `x` is neither a `nil` nor a cons cell.

— Function: cl-list-length x

This function returns the length of list x, exactly like `(length `x`)`, except that if x is a circular list (where the cdr-chain forms a loop rather than terminating with `nil`), this function returns `nil`. (The regular `length` function would get stuck if given a circular list. See also the `safe-length` function.)

— Function: cl-list* arg &rest others

This function constructs a list of its arguments. The final argument becomes the cdr of the last cell constructed. Thus, `(cl-list* `a b c`)` is equivalent to `(cons `a` (cons `b c`))`, and `(cl-list* `a b` nil)` is equivalent to `(list `a b`)`.

— Function: cl-ldiff list sublist

If sublist is a sublist of list, i.e., is `eq` to one of the cons cells of list, then this function returns a copy of the part of list up to but not including sublist. For example, `(cl-ldiff x (cddr x))` returns the first two elements of the list `x`. The result is a copy; the original list is not modified. If sublist is not a sublist of list, a copy of the entire list is returned.

— Function: cl-copy-list list

This function returns a copy of the list list. It copies dotted lists like `(1 2 . 3)` correctly.

— Function: cl-tree-equal x y &key :test :test-not :key

This function compares two trees of cons cells. If x and y are both cons cells, their cars and cdrs are compared recursively. If neither x nor y is a cons cell, they are compared by `eql`, or according to the specified test. The `:key` function, if specified, is applied to the elements of both trees. See Sequences.