List-Manipulation Functions

With that background out of the way, you’re ready to look at the library of functions Common Lisp provides for manipulating lists.

You’ve already seen the basic functions for getting at the elements of a list: **FIRST** and **REST**. Although you can get at any element of a list by combining enough calls to **REST** (to move down the list) with a **FIRST** (to extract the element), that can be a bit tedious. So Common Lisp provides functions named for the other ordinals from **SECOND** to **TENTH** that return the appropriate element. More generally, the function **NTH** takes two arguments, an index and a list, and returns the nth (zero-based) element of the list. Similarly, **NTHCDR** takes an index and a list and returns the result of calling **CDR** n times. (Thus, (nthcdr 0 ...) simply returns the original list, and (nthcdr 1 ...) is equivalent to **REST**.) Note, however, that none of these functions is any more efficient, in terms of work done by the computer, than the equivalent combinations of **FIRST**s and **REST**s—there’s no way to get to the nth element of a list without following n **CDR** references.11

The 28 composite **CAR**/**CDR** functions are another family of functions you may see used from time to time. Each function is named by placing a sequence of up to four As and Ds between a C and R, with each A representing a call to **CAR** and each D a call to **CDR**. Thus:

(caar list) === (car (car list))
(cadr list) === (car (cdr list))
(cadadr list) === (car (cdr (car (cdr list))))

Note, however, that many of these functions make sense only when applied to lists that contain other lists. For instance, **CAAR** extracts the **CAR** of the **CAR** of the list it’s given; thus, the list it’s passed must contain another list as its first element. In other words, these are really functions on trees rather than lists:

(caar (list 1 2 3))                  ==> error
(caar (list (list 1 2) 3))           ==> 1
(cadr (list (list 1 2) (list 3 4)))  ==> (3 4)
(caadr (list (list 1 2) (list 3 4))) ==> 3

These functions aren’t used as often now as in the old days. And even the most die-hard old-school Lisp hackers tend to avoid the longer combinations. However, they’re used quite a bit in older Lisp code, so it’s worth at least understanding how they work.12

The **FIRST**-**TENTH** and **CAR**, **CADR**, and so on, functions can also be used as **SETF**able places if you’re using lists nonfunctionally.

Table 12-1 summarizes some other list functions that I won’t cover in detail.

Table 12-1. Other List Functions