Immediate objects (Guile Reference Manual)

Warning: This is the manual of the legacy Guile 2.2 series. You may want to read the manual of the current stable series instead.

9.2.5.2 Immediate objects

A Scheme object may either be an immediate, i.e. carrying all necessary information by itself, or it may contain a reference to a cell with additional information on the heap. Although in general it should be irrelevant for user code whether an object is an immediate or not, within Guile’s own code the distinction is sometimes of importance. Thus, the following low level macro is provided:

Macro: int SCM_IMP (SCM x): A Scheme object is an immediate if it fulfills the SCM_IMP predicate, otherwise it holds an encoded reference to a heap cell. The result of the predicate is delivered as a C style boolean value. User code and code that extends Guile should normally not be required to use this macro.

Summary:

Given a Scheme object x of unknown type, check first with SCM_IMP (x) if it is an immediate object.
If so, all of the type and value information can be determined from the scm_t_bits value that is delivered by SCM_UNPACK (x).

There are a number of special values in Scheme, most of them documented elsewhere in this manual. It’s not quite the right place to put them, but for now, here’s a list of the C names given to some of these values:

Macro: SCM SCM_EOL: The Scheme empty list object, or “End Of List” object, usually written in Scheme as '().

Macro: SCM SCM_EOF_VAL: The Scheme end-of-file value. It has no standard written representation, for obvious reasons.

Macro: SCM SCM_UNSPECIFIED

The value returned by some (but not all) expressions that the Scheme standard says return an “unspecified” value.

This is sort of a weirdly literal way to take things, but the standard read-eval-print loop prints nothing when the expression returns this value, so it’s not a bad idea to return this when you can’t think of anything else helpful.

Macro: SCM SCM_UNDEFINED

The “undefined” value. Its most important property is that is not equal to any valid Scheme value. This is put to various internal uses by C code interacting with Guile.

For example, when you write a C function that is callable from Scheme and which takes optional arguments, the interpreter passes SCM_UNDEFINED for any arguments you did not receive.

We also use this to mark unbound variables.

Macro: int SCM_UNBNDP (SCM x): Return true if x is SCM_UNDEFINED. Note that this is not a check to see if x is SCM_UNBOUND. History will not be kind to us.