WOLFRAM

Wolfram Language & System Documentation Center

"CString" (Compiled Type)

"CString"

represents a string compatible with C.

Details

  • "CString" can be used in Typed and related constructs to specify a type.
  • Objects with type "CString" are not automatically memory managed and must be manually freed.
  • "CString" is a macro for "CArray"::["CChar"].
  • "CString" is equivalent to char* or unsigned char* in C.

Constructors

Conversions

    Arrays

  • Array types can be Cast to managed C strings. Supported array types include "ListVector", "NumericArray" and "PackedArray".

    • "String"

  • Cast can be used to convert "String" objects to managed C strings.

    • "RawPointer" and "OpaqueRawPointer"

  • Cast can be used to bitcast C strings to and from raw pointers.

Examples

open all close all

Basic Examples  (1)

Compile a function that creates a managed C string and passes it to the C standard library function strlen to get its length:

Wolfram Language code: cf = FunctionCompile[Function[Typed[str, "String"], With[{cstr = CreateTypeInstance["Managed"::["CString"], str]}, LibraryFunction["strlen"][cstr] ] ]]

Evaluate the compiled function on a string:

Wolfram Language code: cf["Hello, World!"]

Scope  (2)

Compile a function that parses a C string to a number using the atof library function from the C standard:

Wolfram Language code: cf = FunctionCompile@Function[{}, Module[{cstr}, cstr = TypeHint["3.14", "CString"]; LibraryFunction["atof"][cstr] ] ]

Evaluate the compiled function:

Wolfram Language code: cf[]

Convert a "CInt" to a string and store it in a managed C string of size 512:

Wolfram Language code: libDecl = LibraryFunctionDeclaration[ "snprintf", {"CString", "CInt", "CString", "CInt"} -> "Integer32" ]; fun = Function[{Typed[n, "CInt"]}, Module[{size, cstr, fmt, err}, size = TypeHint[512, "CInt"]; cstr = CreateTypeInstance["Managed"::["CString"], size]; fmt = TypeHint["%d", "CString"]; err = LibraryFunction["snprintf"][cstr, size, fmt, n];CreateTypeInstance["String", cstr] ] ]; func = FunctionCompile[libDecl, fun]
Wolfram Language code: func[42]//InputForm

Possible Issues  (1)

C strings created outside of a "Managed" object are not automatically memory managed, and must be freed manually. Compile a function that creates unmanaged C strings:

Wolfram Language code: cf1 = FunctionCompile[Function[{}, With[{carr = CreateTypeInstance["CString", 100]}, Null ]]]

The function leaks memory:

Wolfram Language code: With[{before = MemoryInUse[]}, Do[cf1[], 10];MemoryInUse[] - before]

Use DeleteObject to manually free the C strings:

Wolfram Language code: cf2 = FunctionCompile[Function[{}, With[{carr = CreateTypeInstance["CString", 100]}, DeleteObject[carr] ]]]

The resulting function does not leak memory:

Wolfram Language code: With[{before = MemoryInUse[]}, Do[cf2[], 10];MemoryInUse[] - before]