3 Values and Types (CS)

► |  | Inside: Racket C API

I | Inside Racket CS
II | Inside Racket BC (3m and CGC)
III | Appendices
| Index

▼ | I | Inside Racket CS

1 | Overview (CS)
2 | Embedding into a Program (CS)
3 | Values and Types (CS)
4 | Calling Procedures (CS)
5 | Starting and Declaring Initial Modules (CS)
6 | Evaluation and Running Modules (CS)
7 | Managing OS-Level Threads (CS)

► | 3 | Values and Types (CS)

3.1 | Global Constants
3.2 | Value Functions

On this page:

3.1 Global Constants
3.2 Value Functions

top contents ← prev up next →

## 3 Values and Types (CS)🔗ℹ

A Racket value is represented by a pointer-sized value. The low bits of the value indicate the encoding that it uses. For example, two (on 32-bit platform) or three (on 64-bit platforms) low bits indicates a fixnum encoding, while a one low bit and zero second-lowest bit indicates a pair whose address in memory is specified by the other bits.

The C type for a Racket value is ptr. For most Racket types, a constructor is provided for creating values of the type. For example, Scons takes two ptr values and returns the cons of the values as a new ptr value. In addition to providing constructors, Racket defines several global constant Racket values, such as Strue for #t.

### 3.1 Global Constants🔗ℹ

There are six global constants:

- Strue — #t

- Sfalse — #f

- Snil — null

- Seof_object — eof-object

- Svoid — (void)

### 3.2 Value Functions🔗ℹ

Many of these functions are actually macros.

int |  | Sfixnump | ( | ptr v)
int |  | Scharp | ( | ptr v)
int |  | Snullp | ( | ptr v)
int |  | Seof_objectp | ( | ptr v)
int |  | Sbooleanp | ( | ptr v)
int |  | Spairp | ( | ptr v)
int |  | Ssymbolp | ( | ptr v)
int |  | Sprocedurep | ( | ptr v)
int |  | Sflonump | ( | ptr v)
int |  | Svectorp | ( | ptr v)
int |  | Sfxvectorp | ( | ptr v)
int |  | Sbytevectorp | ( | ptr v)
int |  | Sstringp | ( | ptr v)
int |  | Sbignump | ( | ptr v)
int |  | Sboxp | ( | ptr v)
int |  | Sinexactnump | ( | ptr v)
int |  | Sexactnump | ( | ptr v)
int |  | Sratnump | ( | ptr v)
int |  | Srecordp | ( | ptr v)

Predicates to recognize different kinds of Racket values, such as fixnums, characters, the empty list, etc. The Srecordp predicate recognizes structures, but some built-in Racket datatypes are also implemented as records.

ptr |  | Sfixnum | ( | int i)

Returns a Racket integer value, where i must fit in a fixnum.

ptr |  | Sinteger | ( | iptr i)
ptr |  | Sunsigned | ( | uptr i)
ptr |  | Sinteger32 | ( | int i)
ptr |  | Sunsigned32 | ( | unsigned int i)
ptr |  | Sinteger64 | ( | long i)
ptr |  | Sunsigned64 | ( | unsigned long i)

Returns an integer value for different conversions from C, where the result is allocated as a bignum if necessary to hold the value.

iptr |  | Sfixnum_value | ( | ptr v)

Converts a Racket fixnum to a C integer.

iptr |  | Sinteger_value | ( | ptr v)
uptr |  | Sunsigned_value | ( | ptr v)
int |  | Sinteger32_value | ( | ptr v)
long |  | Sunsigned32_value | ( | ptr v)
long |  | Sinteger64_value | ( | ptr v)
unsigned long |  | Sunsigned64_value | ( | ptr v)

Converts a Racket integer (possibly a bignum) to a C integer, assuming that the integer fits in the return type.

ptr |  | Sflonum | ( | double f)

Returns a Racket flonum value.

double |  | Sflonum_value | ( | ptr v)

Converts a Racket flonum value to a C floating-point number.

ptr |  | Schar | ( | int ch)

Returns a Racket character value. The ch value must be a legal Unicode code point (and not a surrogate, for example). All characters are represented by constant values.

ptr |  | Schar_value | ( | ptr ch)

Returns the Unicode code point for the Racket character ch.

ptr |  | Sboolean | ( | int bool)

Returns Strue or Sfalse.

ptr |  | Scons | ( | ptr car,
|  |  |  | ptr cdr)

Makes a cons pair.

ptr |  | Scar | ( | ptr pr)
ptr |  | Scdr | ( | ptr pr)

Extracts the car or cdr of a pair.

ptr |  | Sstring_to_symbol | ( | const char* str)

Returns the interned symbol whose name matches str.

ptr |  | Ssymbol_to_string | ( | ptr sym)

Returns the Racket immutable string value for the Racket symbol sym.

ptr |  | Smake_string | ( | iptr len,
|  |  |  | int ch)
ptr |  | Smake_uninitialized_string | ( | iptr len)

Allocates a fresh Racket mutable string with len characters. The content of the string is either all chs when ch is provided or unspecified otherwise.

ptr |  | Sstring | ( | const char* str)
ptr |  | Sstring_of_length | ( | const char* str,
|  |  |  | iptr len)
ptr |  | Sstring_utf8 | ( | const char* str,
|  |  |  | iptr len)

Allocates a fresh Racket mutable string with the content of str. If len is not provided, str must be nul-terminated. In the case of Sstring_utf8, str is decoded as UTF-8, otherwise it is decided as Latin-1.

uptr |  | Sstring_length | ( | ptr str)

Returns the length of the string str.

ptr |  | Sstring_ref | ( | ptr str,
|  |  |  | uptr i)

Returns the ith Racket character of the string str.

int |  | Sstring_set | ( | ptr str,
|  |  |  | uptr i,
|  |  |  | ptr ch)

Installs ch as the ith Racket character of the string str.

ptr |  | Smake_vector | ( | iptr len,
|  |  |  | ptr v)

Allocates a fresh mutable vector of length len and with v initially in every slot.

uptr |  | Svector_length | ( | ptr vec)

Returns the length of the vector vec.

ptr |  | Svector_ref | ( | ptr vec,
|  |  |  | uptr i)

Returns the ith element of the vector vec.

void |  | Svector_set | ( | ptr vec,
|  |  |  | uptr i,
|  |  |  | ptr v)

Installs v as the ith element of the vector vec.

ptr |  | Smake_fxvector | ( | iptr len,
|  |  |  | ptr v)

Allocates a fresh mutable fxvector of length len and with v initially in every slot.

uptr |  | Sfxvector_length | ( | ptr vec)

Returns the length of the fxvector vec.

iptr |  | Sfxvector_ref | ( | ptr vec,
|  |  |  | uptr i)

Returns the ith fixnum of the fxvector vec.

void |  | Sfxvector_set | ( | ptr vec,
|  |  |  | uptr i,
|  |  |  | ptr v)

Installs the fixnum v as the ith element of the fxvector vec.

ptr |  | Smake_bytevector | ( | iptr len,
|  |  |  | int byte)

Allocates a fresh mutable byte string of length len and with byte initially in every slot.

uptr |  | Sbytevector_length | ( | ptr bstr)

Returns the length of the byte string bstr.

int |  | Sbytevector_u8_ref | ( | ptr bstr,
|  |  |  | uptr i)

Returns the ith byte of the byte string bstr.

int |  | Sbytevector_u8_set | ( | ptr bstr,
|  |  |  | uptr i,
|  |  |  | int byte)

Installs byte as the ith byte of the byte string bstr.

char* |  | Sbytevector_data | ( | ptr vec)

Returns a pointer to the start of the bytes for the byte string bstr.

ptr |  | Sbox | ( | ptr v)

Allocates a fresh mutable box containing v.

ptr |  | Sunbox | ( | ptr bx)

Extract the content of the box bx.

ptr |  | Sset_box | ( | ptr bx,
|  |  |  | ptr v)

Installs v as the content of the box bx.

ptr |  | Srecord_type | ( | ptr rec)
ptr |  | Srecord_type_parent | ( | ptr rtd)
uptr |  | Srecord_type_size | ( | ptr rtd)
int |  | Srecord_type_uniformp | ( | ptr rtd)
ptr |  | Srecord_uniform_ref | ( | ptr rec,
|  |  |  | iptr i)

Accesses record information, where Racket structures are implemented as records. The Srecord_type returns a value representing a record’s type (so, a structure type). Given a record type, Srecord_type_parent returns its supertype or Sfalse, Srecord_type_size returns the allocation size of a record in bytes, and Srecord_type_uniformp indicates whether all of the record fields are Scheme values — which is always true for a Racket structure. When a record has all Scheme-valued fields, the allocation size is the number of fields plus one times the size of a pointer in bytes.

When a record has all Scheme fields (which is the case for all Racket structures), Srecord_uniform_ref accesses a field value in the same way as unsafe-struct*-ref.

void* |  | racket_cpointer_address | ( | ptr cptr)
void* |  | racket_cpointer_base_address | ( | ptr cptr)
iptr |  | racket_cpointer_offset | ( | ptr cptr)

Extracts an address and offset from a C-pointer object in the sense of cpointer?, but only for values using the predefined representation that is not a byte string, #f, or implemented by a new structure type with prop:cpointer.

The result of racket_cpointer_address is the same as racket_cpointer_base_address plus racket_cpointer_offset, where racket_cpointer_offset is non-zero for C-pointer values created by ptr-add.

void |  | Slock_object | ( | ptr cptr)
void |  | Sunlock_object | ( | ptr cptr)

“Locks” or “unlocks” n object, which prevents it from being garbage collected or moved to a different address.

Lock objects sparingly, because the garbage collector is not designed to deal with a large number of locked objects. To retain multiple values from use from C, a good approach may be to allocate and lock a vector that has a slot for each other (unlocked) object to retain.

top contents ← prev up next →