9.2 Introduction to generalised C strings

Generalised C strings are meant to be used in interfaces to foreign C language libraries, when a pointer to C string or input buffer is required as argument.

A generalised C string is an object capable of holding the representation of a C language string; such Scheme objects are: strings, bytevectors, pointer objects, instances of memory-block. (vicare-scheme)Memory blocks for details on memory blocks.

When a Scheme string is used as generalised C string: the application must take care of converting the Scheme string into a C string representation, for example using string->ascii.

When using generalised C strings we have to remember that:

• A run of the garbage collector may move the data area of Scheme bytevectors; for this reason Scheme bytevectors and Scheme strings converted to bytevectors are not suitable as arguments to Scheme functions interfacing to C functions that call back to Scheme.
• If a Scheme string is used as argument: the C function cannot modify it by using it as output buffer.

in these cases we should use generalised C buffers, Introduction to generalised C buffers.

Two arguments to function are usually needed to represent a generalised C string: the string value itself and an optional length.

1. The string argument is meant to be either a string, or bytevector, or memory-block instance, or pointer object.
2. The length argument is meant to be #f or an exact integer in the range of the C language type size_t. When the string argument is a pointer object: the length argument must represent the number of bytes available in the referenced memory block; otherwise the length argument is ignored.

Here is an example function accepting a generalised C string argument str and its optional length argument str.len, the string is converted to bytevector with string->ascii:

(define fun
  (case-lambda
    ((str)
     (fun str #f))
    ((str str.len)
     (define who 'fun)
     (with-arguments-validation (who)
         ((general-c-string     str)
          (general-c-string.len str str.len))
       (with-general-c-strings
           ((str^         str))
         (do-something-with str^ str.len))))))