On this page:
3.1 Global Constants
3.2 Value Functions

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:

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.