Next: , Up: Non-immediate Datatypes

A.2.5.1 Pairs

Pairs are the essential building block of list structure in Scheme. A pair object has two fields, called the car and the cdr.

It is conventional for a pair's car to contain an element of a list, and the cdr to point to the next pair in the list, or to contain SCM_EOL, indicating the end of the list. Thus, a set of pairs chained through their cdrs constitutes a singly-linked list. Scheme and libguile define many functions which operate on lists constructed in this fashion, so although lists chained through the cars of pairs will work fine too, they may be less convenient to manipulate, and receive less support from the community.

Guile implements pairs by mapping the car and cdr of a pair directly into the two words of the cell.

— Macro: int SCM_CONSP (SCM x)

Return non-zero iff x is a Scheme pair object.

— Macro: int SCM_NCONSP (SCM x)

The complement of SCM_CONSP.

— Function: SCM scm_cons (SCM car, SCM cdr)

Allocate (“CONStruct”) a new pair, with car and cdr as its contents.

The macros below perform no type checking. The results are undefined if cell is an immediate. However, since all non-immediate Guile objects are constructed from cells, and these macros simply return the first element of a cell, they actually can be useful on datatypes other than pairs. (Of course, it is not very modular to use them outside of the code which implements that datatype.)

— Macro: SCM SCM_CAR (SCM cell)

Return the car, or first field, of cell.

— Macro: SCM SCM_CDR (SCM cell)

Return the cdr, or second field, of cell.

— Macro: void SCM_SETCAR (SCM cell, SCM x)

Set the car of cell to x.

— Macro: void SCM_SETCDR (SCM cell, SCM x)

Set the cdr of cell to x.

— Macro: SCM SCM_CAAR (SCM cell)
— Macro: SCM SCM_CADR (SCM cell)
— Macro: SCM SCM_CDAR (SCM cell) ...
— Macro: SCM SCM_CDDDDR (SCM cell)

Return the car of the car of cell, the car of the cdr of cell, et cetera.