Next: , Previous: , Up: Lists   [Contents][Index]

### 11.4 Accessing Elements of Lists

Function: car cons-cell

This function returns the value pointed to by the first pointer of the cons cell cons-cell. Expressed another way, this function returns the CAR of cons-cell.

As a special case, if cons-cell is `nil`, then `car` is defined to return `nil`; therefore, any list is a valid argument for `car`. An error is signaled if the argument is not a cons cell or `nil`.

```(car '(a b c))
⇒ a
```
```(car '())
⇒ nil
```
Function: cdr cons-cell

This function returns the value pointed to by the second pointer of the cons cell cons-cell. Expressed another way, this function returns the CDR of cons-cell.

As a special case, if cons-cell is `nil`, then `cdr` is defined to return `nil`; therefore, any list is a valid argument for `cdr`. An error is signaled if the argument is not a cons cell or `nil`.

```(cdr '(a b c))
⇒ (b c)
```
```(cdr '())
⇒ nil
```
Function: car-safe object

This function lets you take the CAR of a cons cell while avoiding errors for other data types. It returns the CAR of object if object is a cons cell, `nil` otherwise. This is in contrast to `car`, which signals an error if object is not a list.

```(car-safe object)
≡
(let ((x object))
(if (consp x)
(car x)
nil))
```
Function: cdr-safe object

This function lets you take the CDR of a cons cell while avoiding errors for other data types. It returns the CDR of object if object is a cons cell, `nil` otherwise. This is in contrast to `cdr`, which signals an error if object is not a list.

```(cdr-safe object)
≡
(let ((x object))
(if (consp x)
(cdr x)
nil))
```
Function: nth n list

This function returns the nth element of list. Elements are numbered starting with zero, so the CAR of list is element number zero. If the length of list is n or less, the value is `nil`.

If n is negative, `nth` returns the first element of list.

```(nth 2 '(1 2 3 4))
⇒ 3
```
```(nth 10 '(1 2 3 4))
⇒ nil
```
```(nth -3 '(1 2 3 4))
⇒ 1

(nth n x) ≡ (car (nthcdr n x))
```
Function: nthcdr n list

This function returns the nth CDR of list. In other words, it removes the first n links of list and returns what follows.

If n is zero or negative, `nthcdr` returns all of list. If the length of list is n or less, `nthcdr` returns `nil`.

```(nthcdr 1 '(1 2 3 4))
⇒ (2 3 4)
```
```(nthcdr 10 '(1 2 3 4))
⇒ nil
```
```(nthcdr -3 '(1 2 3 4))
⇒ (1 2 3 4)
```

Many convenience functions are provided to make it easier for you to access particular elements in a nested list. All of these can be rewritten in terms of the functions just described.

Function: caar cons-cell
Function: cdar cons-cell
Function: cddr cons-cell
Function: caaar cons-cell
Function: cdaar cons-cell
Function: cddar cons-cell
Function: cdddr cons-cell
Function: caaaar cons-cell
Function: cdaaar cons-cell
Function: cddaar cons-cell
Function: cdddar cons-cell
Function: cddddr cons-cell

Each of these functions is equivalent to one or more applications of `car` and/or `cdr`. For example,

```(cadr x)
```

is equivalent to

```(car (cdr x))
```

and

```(cdaddr x)
```

is equivalent to

```(cdr (car (cdr (cdr x))))
```

That is to say, read the a’s and d’s from right to left and apply a `car` or `cdr` for each a or d found, respectively.

Function: first list

This is equivalent to `(nth 0 list)`, i.e. the first element of list. (Note that this is also equivalent to `car`.)

Function: second list

This is equivalent to `(nth 1 list)`, i.e. the second element of list.

Function: third list
Function: fourth list
Function: fifth list
Function: sixth list
Function: seventh list
Function: eighth list
Function: ninth list
Function: tenth list

These are equivalent to `(nth 2 list)` through `(nth 9 list)` respectively, i.e. the third through tenth elements of list.

Next: , Previous: , Up: Lists   [Contents][Index]