(cl.info)List Functions

Next: Substitution of Expressions Prev: Lists Up: Lists
```
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
signalling 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: last X &optional N
This function returns the last cons, or the Nth-to-last cons, of
the list X.  If N is omitted it defaults to 1.  The "last cons"
means the first cons cell of the list whose `cdr' is not another
cons cell.  (For normal lists, the `cdr' of the last cons will be
`nil'.)  This function returns `nil' if X is `nil' or shorter than
N.  Note that the last *element* of the list is `(car (last X))'.

- Function: butlast X &optional N
This function returns the list X with the last element, or the
last N elements, removed.  If N is greater than zero it makes a
copy of the list so as not to damage the original list.  In
general, `(append (butlast X N) (last X N))' will return a list
equal to X.

- Function: nbutlast X &optional N
This is a version of `butlast' that works by destructively
modifying the `cdr' of the appropriate element, rather than making
a copy of the 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::.

```

automatically generated by info2www