GNU Info

(cl)List Functions

---

Next: Substitution of Expressions Prev: Lists Up: Lists

---

Enter node , (file) or (file)node

List Functions
==============

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

 - Function: caddr x
     This function is equivalent to `(car (cdr (cdr X)))'.  Likewise,
     this package defines all 28 `cXXXr' 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: first x
     This function is a synonym for `(car X)'.  Likewise, the functions
     `second', `third', ..., through `tenth' return the given element
     of the list X.

 - Function: rest x
     This function is a synonym for `(cdr X)'.

 - Function: endp x
     Common Lisp defines this function to act like `null', but
     signaling an error if `x' is neither a `nil' nor a cons cell.
     This package simply defines `endp' as a synonym for `null'.

 - Function: 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.)

 - Function: list* arg &rest others
     This function constructs a list of its arguments.  The final
     argument becomes the `cdr' of the last cell constructed.  Thus,
     `(list* A B C)' is equivalent to `(cons A (cons B C))', and
     `(list* A B nil)' is equivalent to `(list A B)'.

     (Note that this function really is called `list*' in Common Lisp;
     it is not a name invented for this package like `member*' or
     `defun*'.)

 - Function: 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, `(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: copy-list list
     This function returns a copy of the list LIST.  It copies dotted
     lists like `(1 2 . 3)' correctly.

 - Function: copy-tree x &optional vecp
     This function returns a copy of the tree of cons cells X.  Unlike
     `copy-sequence' (and its alias `copy-list'), which copies only
     along the `cdr' direction, this function copies (recursively)
     along both the `car' and the `cdr' directions.  If X is not a cons
     cell, the function simply returns X unchanged.  If the optional
     VECP argument is true, this function copies vectors (recursively)
     as well as cons cells.

 - Function: 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 `car's and `cdr's 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.  Note:
     Sequences.