---

E.3.4 Accessing Sequence Elements

Cons Elements Using ‘car’ and ‘cdr’

Function: car cons-cell ¶

This function returns the value referred to by the first slot of the cons cell CONS-CELL, e.g., the CAR of the CONS-CELL. If the CONS-CELL is ‘nil’, it returns ‘nil’. An error is signaled if the argument is not a cons cell or ‘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. It does not signal an error if OBJECT is not a list or ‘nil’.

Function: cdr cons-cell ¶

This function returns the value referred to by the second slot of the cons cell CONS-CELL, e.g., the CDR of the CONS-CELL. If the CONS-CELL is ‘nil’, it returns ‘nil’. An error is signaled if the argument is not a cons cell or ‘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. It does not signal an error if OBJECT is not a list or ‘nil’.

Sequence Elements

Function: elt sequence index ¶

This function returns the element of SEQUENCE indexed by INDEX (starting from zero). Whereas the function nth applies only to lists and aref applies to arrays, this function applies to any kind of sequence. (Note that nth takes its arguments in opposite order).

Legitimate values of INDEX are integers ranging from 0 up to one less than the length of SEQUENCE. If SEQUENCE is a list and the INDEX is out of range, NIL is returned. Otherwise, an ‘args-out-of-range’ error is returned.

This function generalizes ‘aref’ and ‘nth’.

Function: nth n list ¶

This function returns the Nth element of LIST (using zero indexing), or ‘nil’ if N is out of bounds.

Function: aref arr index ¶

This function returns the INDEXth element of the array or record ARR. The first element is at index zero.

Function: nthcdr n list ¶

This function returns the Nth CDR of LIST. In other words, it skips past the first N links of LIST and returns what follows. If N is zero, ‘nthcdr’ returns all of LIST. If the length of LIST is N or less, ‘nthcdr’ returns ‘nil’.

Function: last list &optional n ¶

This function returns the last link of LIST. The ‘car’ of this link is the list’s last element. If LIST is null, ‘nil’ is returned. If N is non-‘nil’, the Nth-to-last link is returned instead, or the whole of LIST if N is bigger than LIST’s length.

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.

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: caar cons-cell ¶

This is the same as ‘(car (car CONS-CELL))’.

Function: cdar cons-cell ¶

This is the same as ‘(car (cdr CONS-CELL))’ or ‘(nth 1 CONS-CELL)’.

Function: cdar cons-cell ¶

This is the same as ‘(cdr (car CONS-CELL))’.

Function: cddr cons-cell ¶

This is the same as ‘(cdr (cdr CONS-CELL))’ or ‘(nthcdr 2 CONS-CELL)’.

cXXXr

In addition to the above, 24 additional compositions of ‘car’ and ‘cdr’ are defined as ‘cXXXr’ and ‘cXXXXr’, where each ‘X’ is either ‘a’ or ‘d’. ‘cadr’, ‘caddr’, and ‘cadddr’ pick out the second, third or fourth elements of a list, respectively (‘cl-second’, ‘cl-third’, and ‘cl-fourth’).