10.1 List Functions

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

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.