2.2 Base Foreign Types🔗ℹ

Every type has a C representation and a Rhombus representation and conversion functions to get from one to the other. For example, the base type int_t is represented on the C side as a int, while it is represented in the racket side by a Int that fits into a 32-bit two’s complement representation.

When an address is converted from C to Rhombus, then ptr_t produces a pointer object that references memory (assumed to be) not managed by Racket’s garbage collector. The ptr_t/gcable type implies that a pointer converted from C should be treated as (potentially) managed by Rhombus’s garbage collector. In both cases, conversion from Rhombus to C allows any pointer object.

The void_t* type is equivalent to ptr_t, and the (void_t*)/gcable type is equivalent to ptr_t/gcable.

All are represented as exact integers on the Rhombus side, constrained to a range that fits in the platform-specific C representation.

The range of wchar_t on the C side may include integers that do not correspond to a Rhombus character, and it may omit values that do correspond to a Rhombus character. The Rhombus representation of a wchar_t is constrained to characters that fit in the C representation, and values from C that are are not representable as Rhombus characters are converted to the Unicode replacement character, Char"\uFFFD".

For Rhombus to C conversion, the string_t type converts a Rhombus string to a null-terminated UTF-8 byte string and passes the address of the start of the byte string to the C side. The string_utf16_t type is similar, but conversion uses UTF-16 and a two-byte null terminator. The bytes_t type similarly copies a Rhombus byte string to add a null terminator, while bytes_ptr_t passes the start of a Rhombus byte string as-is, without adding a terminator (and where mutation of pointer content on the C side is reflected as changes to the byte string content). The path_t is like string_t, but for paths in the sense of CrossPath. All of these types convert #false on the Racket side to NULL on the C side.

When converting from C to Rhombus, the non-NULL pointer received from C is treated as a reference to a null-terminated C string, and a fresh Racket byte string is created to hold the content up to the null terminator. The string_t, string_utf16_t, and path_t types then convert that byte string to a string or path. A NULL from C is converted to #false for Rhombus.

> cast ~from (bytes_t) ~to (bytes_t) #"apple\0pie"

#"apple".copy()

> cast ~from (bytes_t) ~to (string_t) #"apple\0pie"

"apple"

> mem (cast ~from (bytes_ptr_t) ~to (byte_t*) #"apple\0pie")[6]

112

> cast ~from (string_t) ~to (path_t) "source"

Path("source")

> cast ~from (path_t) ~to (bytes_t) Path("source")

#"/home/racket/rhombus-build/plt/build/user/9.2.0.3/pkgs/rhombus-ffi/rhombus/ffi/scribblings/source"

.copy()

> cast ~to (string_t) uintptr_to_ptr(0)

#false