Non-immediate objects - Guile Reference Manual

Next: Heap Cell Type Information, Previous: Immediate objects, Up: Unpacking the SCM type

18.2.7.3 Non-immediate objects

A Scheme object of type SCM that does not fulfill the SCM_IMP predicate holds an encoded reference to a heap cell. This reference can be decoded to a C pointer to a heap cell using the SCM_SCM2PTR macro. The encoding of a pointer to a heap cell into a SCM value is done using the SCM_PTR2SCM macro. The pointer type is typedef'd as SCM_CELLPTR.

— C Macro: SCM_CELLPTR SCM_SCM2PTR (SCM x)

Extract and return the heap cell pointer from a non-immediate SCM object x.

— C Macro: SCM SCM_PTR2SCM (SCM_CELLPTR x)

Return a SCM value that encodes a reference to the heap cell pointer x.

Note that it is also possible to transform a non-immediate SCM value by using SCM_UNPACK into a scm_bits_t variable. However, the result of SCM_UNPACK may not be used as a SCM_CELLPTR; only SCM_SCM2PTR is guaranteed to transform a SCM object into a valid pointer to a heap cell. Also, it is not allowed to apply SCM_PTR2SCM to anything that is not a valid pointer to a heap cell.

Summary:

Only use SCM_SCM2PTR on SCM values for which SCM_IMP is false!
Don't use (SCM_CELLPTR) SCM_UNPACK (x)! Use SCM_SCM2PTR (x) instead!
Don't use SCM_PTR2SCM for anything but a SCM_CELLPTR!

Historical note: SCM_PTR2SCM and SCM_SCM2PTR were originally named PTR2SCM and SCM2PTR (without the leading SCM_) but this is violates the naming convention established to make Guile easy to embed. Although we provide the old names anyway, to avoid breaking compatibility for Guile 1.4.x, you should use the SCM_-prefixed names for new code.