►The Racket Foreign Interface
▼3 C Types
►3.4 String Types
On this page:
3.4.1 Primitive String Types
_  string/  ucs-4
_  string/  utf-16
_  path
_  symbol
3.4.2 Fixed Auto-Converting String Types
_  string/  utf-8
_  string/  latin-1
_  string/  locale
_  string*/  utf-8
_  string*/  latin-1
_  string*/  locale
3.4.3 Variable Auto-Converting String Type
_  string
default-_  string-type
3.4.4 Other String Types
_  file
_  bytes/  eof
_  string/  eof
  top  ← prev  up  next → 

3.4 String Types

3.4.1 Primitive String Types

See also _bytes/nul-terminated and _bytes for converting between byte strings and C’s char* type.

value

_string/ucs-4 : ctype?

A type for UCS-4 format strings that include a nul terminator. As usual, the type treats #f as NULL and vice versa.

For the 3m and CGC variants of Racket, the conversion of a Racket string for the foreign side shares memory with the Racket string representation, since UCS-4 is the native representation format for those variants. The foreign pointer corresponds to the mzchar* type in Racket’s C API.

For the CS variant of Racket, the conversion of a Racket string for the foreign side is a copy of the Racket representation, where the copy is managed by the garbage collector.

value

_string/utf-16 : ctype?

Unicode strings in UTF-16 format that include a nul terminator. As usual, the types treat #f as NULL and vice versa.

The conversion of a Racket string for the foreign side is a copy of the Racket representation (reencoded), where the copy is managed by the garbage collector.

value

_path : ctype?

Simple char* strings that are nul terminated, corresponding to Racket’s path or string. As usual, the type treats #f as NULL and vice versa.

For the 3m and CGC variants of Racket, the conversion of a Racket path for the foreign side shares memory with the Racket path representation. Otherwise (for the CS variant or for Racket strings), conversion for the foreign side creates a copy that is managed by the garbage collector.

Beware that changing the current directory via current-directory does not change the OS-level current directory as seen by foreign library functions. Paths normally should be converted to absolute form using path->complete-path (which uses the current-directory parameter) before passing them to a foreign function.

value

_symbol : ctype?

Simple char* strings as Racket symbols (encoded in UTF-8 and nul terminated), intended as read-only for the foreign side. Return values using this type are interned as symbols.

For the 3m and CGC variants of Racket, the conversion of a Racket symbol for the foreign side shares memory with the Racket symbol representation, but points to the middle of the symbol’s allocated memory—so the string pointer must not be used across a garbage collection.

For the CS variant of Racket, the conversion of a Racket symbol for the foreign side is a copy of the Racket representation, where the copy is managed by the garbage collector.

3.4.2 Fixed Auto-Converting String Types

value

_string/utf-8 : ctype?

_string/latin-1 : ctype?
_string/locale : ctype?
Types that correspond to (character) strings on the Racket side and char* strings on the C side. The bridge between the two requires a transformation on the content of the string. As usual, the types treat #f as NULL and vice versa.

value

_string*/utf-8 : ctype?

_string*/latin-1 : ctype?
_string*/locale : ctype?
Similar to _string/utf-8, etc., but accepting a wider range of values: Racket byte strings are allowed and passed as is, and Racket paths are converted using path->bytes.

3.4.3 Variable Auto-Converting String Type

The _string/ucs-4 type is rarely useful when interacting with foreign code, while using _bytes/nul-terminated is somewhat unnatural, since it forces Racket programmers to use byte strings. Using _string/utf-8, etc., meanwhile, may prematurely commit to a particular encoding of strings as bytes. The _string type supports conversion between Racket strings and char* strings using a parameter-determined conversion.

value

_string : ctype?

Expands to a use of the default-_string-type parameter. The parameter’s value is consulted when _string is evaluated, so the parameter should be set before any interface definition that uses _string.

parameter

(default-_string-type) → ctype?

(default-_string-type type) → void?
  type : ctype?
A parameter that determines the current meaning of _string. It is initially set to _string*/utf-8. If you change it, do so before interfaces are defined.

3.4.4 Other String Types

value

_file : ctype?

Like _path, but when values go from Racket to C, cleanse-path is used on the given value. As an output value, it is identical to _path.

value

_bytes/eof : ctype?

Similar to the _bytes type, except that a foreign return value of NULL is translated to a Racket eof value.

value

_string/eof : ctype?

Similar to the _string type, except that a foreign return value of NULL is translated to a Racket eof value.

  top  ← prev  up  next →