Next: , Previous: Dynamic loading of C modules, Up: C interface


7.5 Accessing Scheme data from C

The C header file scheme48.h provides access to Scheme48 data structures. The type s48_value is used for Scheme values. When the type of a value is known, such as the integer returned by the Scheme procedure vector-length or the boolean returned by pair, the corresponding C function returns a C value of the appropriate type, not an s48_value. Predicates return 1 for true and 0 for false.

— C macro: s48_value S48_FALSE
— C macro: s48_value S48_TRUE
— C macro: s48_value S48_NULL
— C macro: s48_value S48_UNSPECIFIC
— C macro: s48_value S48_EOF
— C macro: long S48_MAX_FIXNUM_VALUE
— C macro: long S48_MIN_FIXNUM_VALUE

These C macros denote various Scheme constants. S48_FALSE is the boolean false value, written in Scheme as #f. S48_TRUE is the boolean true value, or #t. S48_NULL is the empty list (). S48_UNSPECIFIC is a miscellaneous value returned by procedures that have no meaningful return value (accessed in Scheme48 by the nullary procedure unspecific in the util structure). S48_EOF is the end-of-file object (which the Scheme procedure eof-object? answers true for). S48_MAX_FIXNUM_VALUE is the maximum integer as a long that can be represented in a Scheme48 fixnum. S48_MIN_FIXNUM_VALUE is similar, but the minimum integer.

— C macro: int S48_EXTRACT_BOOLEAN (s48_value boolean)
— C function: unsigned char s48_extract_char (s48_value char)
— C function: char * s48_extract_string (s48_value string)
— C function: char * s48_extract_byte_vector (s48_value bytev)
— C function: long s48_extract_integer (s48_value integer)
— C function: double s48_extract_double (s48_value double)
— C macro: s48_value S48_ENTER_BOOLEAN (int boolean)
— C function: s48_value s48_enter_char (unsigned char char)
— C function: s48_value s48_enter_string (char *string)
— C function: s48_value s48_enter_byte_vector (char *bytev, long length)
— C function: s48_value s48_enter_integer (long integer)
— C function: s48_value s48_enter_double (double double)

These functions & macros convert values between their respective Scheme & C representations.

S48_EXTRACT_BOOLEAN returns 0 if boolean is #f and 1 otherwise. S48_ENTER_BOOLEAN returns the Scheme value #f if its argument is zero and #t otherwise.

s48_extract_char & s48_enter_char convert between Scheme characters and C chars.

s48_extract_string & s48_extract_byte_vector return pointers to the actual storage used by string or bytev. These pointers are valid only until the next garbage collection, however; see Interacting with the Scheme heap in C. s48_enter_string & s48_enter_byte_vector allocate space on the Scheme48 heap for the given strings or byte vectors. s48_enter_string copies the data starting from the pointer it is given up to the first ASCII NUL character, whereas s48_enter_byte_vector is given the number of bytes to copy into the Scheme heap.

s48_extract_integer returns a C long that represents the Scheme integer as input. If the Scheme integer is too large to be represented in a long, an exception is signalled. (The Scheme integer may be a fixnum or a bignum.) s48_enter_integer converts back to Scheme integers, and it will never signal an exception.

s48_extract_double & s48_enter_double convert between Scheme & C double-precision floating point representations.

Of these, s48_enter_string, s48_enter_byte_vector, s48_enter_integer, & s48_enter_double may cause the garbage collector to be invoked: the former two copy the string or byte vector onto the Scheme heap first, s48_enter_integer may need to allocate a bignum (since C longs are wider than Scheme48 fixnums), and floats are heap-allocated in Scheme48.

— C macro: int S48_TRUE_P (s48_value object)
— C macro: int S48_FALSE_P (s48_value object)

S48_TRUE_P returns true if object is the true constant S48_TRUE and false if otherwise. S48_FALSE_P returns true if its argument is the false constant S48_FALSE and false if otherwise.

— C macro: int S48_FIXNUM_P (s48_value object)
— C function: long s48_extract_fixnum (s48_value fixnum)
— C function: s48_value s48_enter_fixnum (long integer)

S48_FIXNUM_P is the C predicate for Scheme48 fixnums, delimited in range by S48_MIN_FIXNUM_VALUE & S48_MAX_FIXNUM_VALUE. s48_extract_fixnum returns the C long representation of the Scheme fixnum, and s48_enter_fixnum returns the Scheme fixnum representation of the C long. These are identical to s48_extract_integer & s48_enter_integer, except that s48_extract_fixnum will never raise a range exception, but s48_enter_fixnum may, and s48_enter_fixnum will never return a bignum; this is due to the fact that C longs have a wider range than Scheme48 fixnums.

— C macro: int S48_EQ_P (s48_value a, s48_value b)
— C macro: int S48_CHAR_P (s48_value object)
— C macro: int S48_PAIR_P (s48_value object)
— C macro: int S48_VECTOR_P (s48_value object)
— C macro: int S48_STRING_P (s48_value object)
— C macro: int S48_SYMBOL_P (s48_value object)
— C macro: int S48_BYTE_VECTOR_P (s48_value object)

— C macro: s48_value S48_CAR (s48_value pair)
— C macro: s48_value S48_CDR (s48_value pair)
— C macro: void S48_SET_CAR (s48_value pair, s48_value object)
— C macro: void S48_SET_CDR (s48_value pair, s48_value object)
— C function (may GC): s48_value s48_cons (s48_value car, s48_value cdr)
— C function: s48_value s48_length (s48_value list)

— C macro: long S48_VECTOR_LENGTH (s48_value vector)
— C macro: s48_value S48_VECTOR_REF (s48_value vector, long index)
— C macro: void S48_VECTOR_SET (s48_value vector, long index, s48_value object)
— C function (may GC): s48_value s48_make_vector (long length, s48_value fill)

— C macro: long S48_STRING_LENGTH (s48_value string)
— C macro: char S48_STRING_REF (s48_value string, long index)
— C macro: void S48_STRING_SET (s48_value string, long index, char char)
— C function (may GC): s48_value s48_make_string (long length, char fill)
— C macro: s48_value S48_SYMBOL_TO_STRING (s48_value symbol)

— C macro: long S48_BYTE_VECTOR_LENGTH (s48_value bytev)
— C macro: char S48_BYTE_VECTOR_REF (s48_value bytev, long index)
— C macro: void S48_BYTE_VECTOR_SET (s48_value bytev, long index, char byte)
— C function (may GC): s48_value s48_make_byte_vector (long length)

C versions of miscellaneous Scheme procedures. The names were derived from their Scheme counterparts by replacing hyphens with underscores, ? suffixes with _P, and dropping ! suffixes.