Scheme 48 Manual -- Accessing Scheme data from C

Scheme 48 Manual | Contents | In Chapter: Mixing Scheme 48 and C
Previous: Accessing Scheme data from C | Next: Accessing Scheme data from C

## Accessing Scheme data from C

The C header file `scheme48.h` provides access to Scheme 48 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 `vector-length` or the boolean returned by `pair?`, the corresponding C procedure returns a C value of the appropriate type, and not a `s48_value`. Predicates return `1` for true and `0` for false.

### Constants

The following macros denote Scheme constants:

- `S48_FALSE` is `#f`.
- `S48_TRUE` is `#t`.
- `S48_NULL` is the empty list.
- `S48_UNSPECIFIC` is a value used for functions which have no meaningful return value (in Scheme 48 this value returned by the nullary procedure `unspecific` in the structure `util`).
- `S48_EOF` is the end-of-file object (in Scheme 48 this value is returned by the nullary procedure `eof-object` in the structure `i/o-internal`).

### Converting values

The following macros and functions convert values between Scheme and C representations. The `extract' ones convert from Scheme to C and the `enter's go the other way.

- `int S48_EXTRACT_BOOLEAN(s48_value)`
- `unsigned char s48_extract_char(s48_value)`
- `char * s48_extract_string(s48_value)`
- `char * s48_extract_byte_vector(s48_value)`

- `long s48_extract_integer(s48_value)` | (may GC)

- `double s48_extract_double(s48_value)`
- `s48_value S48_ENTER_BOOLEAN(int)`
- `s48_value s48_enter_char(unsigned char)`

- `s48_value s48_enter_string(char *)` | (may GC)

- `s48_value s48_enter_byte_vector(char *, long)` | (may GC)

- `s48_value s48_enter_integer(long)` | (may GC)

- `s48_value s48_enter_double(double)` | (may GC)

`S48_EXTRACT_BOOLEAN` is false if its argument is `#f` and true otherwise. `S48_ENTER_BOOLEAN` is `#f` if its argument is zero and `#t` otherwise.

`s48_extract_string` and `s48_extract_byte_vector` return pointers to the actual storage used by the string or byte vector. These pointers are valid only until the next garbage collection.

The second argument to `s48_enter_byte_vector` is the length of byte vector.

`s48_enter_integer()` needs to allocate storage when its argument is too large to fit in a Scheme 48 fixnum. In cases where the number is known to fit within a fixnum (currently 30 bits including the sign), the following procedures can be used. These have the disadvantage of only having a limited range, but the advantage of never causing a garbage collection. `S48_FIXNUM_P` is a macro that true if its argument is a fixnum and false otherwise.

- `int S48_TRUE_P(s48_value)`
- `int S48_FALSE_P(s48_value)`

`S48_TRUE_P` is true if its argument is `S48_TRUE` and `S48_FALSE_P` is true if its argument is `S48_FALSE`.

- `int S48_FIXNUM_P(s48_value)`
- `long s48_extract_fixnum(s48_value)`
- `s48_value s48_enter_fixnum(long)`
- `long S48_MAX_FIXNUM_VALUE`
- `long S48_MIN_FIXNUM_VALUE`

An error is signalled if `s48_extract_fixnum`'s argument is not a fixnum or if the argument to `s48_enter_fixnum` is less than `S48_MIN_FIXNUM_VALUE` or greater than `S48_MAX_FIXNUM_VALUE` (-229 and 229-1 in the current system).

### C versions of Scheme procedures

The following macros and procedures are C versions of Scheme procedures. The names were derived by replacing ``-`' with ``_`', ``?`' with ``_P`', and dropping ``!`.

- `int S48_EQ_P(s48_value, s48_VALUE)`
- `int S48_CHAR_P(s48_value)`

- `int S48_PAIR_P(s48_value)`
- `s48_value S48_CAR(s48_value)`
- `s48_value S48_CDR(s48_value)`
- `void S48_SET_CAR(s48_value, s48_value)`
- `void S48_SET_CDR(s48_value, s48_value)`

- `s48_value s48_cons(s48_value, s48_value)` | (may GC)

- `long s48_length(s48_value)`

- `int S48_VECTOR_P(s48_value)`
- `long S48_VECTOR_LENGTH(s48_value)`
- `s48_value S48_VECTOR_REF(s48_value, long)`
- `void S48_VECTOR_SET(s48_value, long, s48_value)`

- `s48_value s48_make_vector(long, s48_value)` | (may GC)

- `int S48_STRING_P(s48_value)`
- `long S48_STRING_LENGTH(s48_value)`
- `char S48_STRING_REF(s48_value, long)`
- `void S48_STRING_SET(s48_value, long, char)`

- `s48_value s48_make_string(long, char)` | (may GC)

- `int S48_SYMBOL_P(s48_value)`
- `s48_value s48_SYMBOL_TO_STRING(s48_value)`

- `int S48_BYTE_VECTOR_P(s48_value)`
- `long S48_BYTE_VECTOR_LENGTH(s48_value)`
- `char S48_BYTE_VECTOR_REF(s48_value, long)`
- `void S48_BYTE_VECTOR_SET(s48_value, long, int)`

- `s48_value s48_make_byte_vector(long, int)` | (may GC)

Previous: Accessing Scheme data from C | Next: Accessing Scheme data from C