Node:Pair Data, Next:, Up:Non-immediate Datatypes


18.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.

int SCM_CONSP (SCM x) Macro
Return non-zero iff x is a Scheme pair object.

int SCM_NCONSP (SCM x) Macro
The complement of SCM_CONSP.

void SCM_NEWCELL (SCM into) Macro
Allocate a new cell, and set into to point to it. This macro expands to a statement, not an expression, and into must be an lvalue of type SCM.

This is the most primitive way to allocate a cell; it is quite fast.

The CAR of the cell initially tags it as a "free cell". If the caller intends to use it as an ordinary cons, she must store ordinary SCM values in its CAR and CDR.

If the caller intends to use it as a header for some other type, she must store an appropriate magic value in the cell's CAR, to mark it as a member of that type, and store whatever value in the CDR that type expects. You should generally not do this, unless you are implementing a new datatype, and thoroughly understand the code in <libguile/tags.h>.

SCM scm_cons (SCM car, SCM cdr) Function
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.)

SCM SCM_CAR (SCM cell) Macro
Return the CAR, or first field, of cell.

SCM SCM_CDR (SCM cell) Macro
Return the CDR, or second field, of cell.

void SCM_SETCAR (SCM cell, SCM x) Macro
Set the CAR of cell to x.

void SCM_SETCDR (SCM cell, SCM x) Macro
Set the CDR of cell to x.

SCM SCM_CAAR (SCM cell) Macro
SCM SCM_CADR (SCM cell) Macro
SCM SCM_CDAR (SCM cell) ... Macro
SCM SCM_CDDDDR (SCM cell) Macro
Return the CAR of the CAR of cell, the CAR of the CDR of cell, et cetera.