with-native-string

$Revision: 1.1.2.4 $

Function

Package: EXCL

Arguments: ((string-var string-exp &key (start 0) end native-length-var (external-format :default)) &body body)

This macro provides an efficient, portable, and non-garbage (from the lisp garbage collector's point of view) way of converting lisp-strings to addresses acceptable for foreign functions expecting native string arguments.

The string-exp argument specifies an expression returning a lisp string. If either start or end is specified, the substring bounded by the start and end arguments is used.

By default, this macro will convert to the native representation assumed for foreign function strings. Under International Allegro CL, this conversion is to EUC (ie, external-format :euc) under Unix, and to Windows MultiByte (ie, external-format :mb) under Windows. Overriding the default external-format is not supported in this Allegro CL release. When :default is specified, the value of excl:*default-external-format* is used.

The forms of body are evaluated (an implicit progn) with the variable string-var bound to the address of the converted string. If a variable is specified with native-length-var, that variable will be bound to the length in 8-bit bytes of the converted string. The 8-bit byte following the last data element is 0 (the null-terminator), but this null-byte is not included in the count of bytes bound to the native-length-var variable.

Note that the data assigned to string-var is considered to have dynamic-extent. This means that the value of string-var is not considered valid outside of the forms specified in body.

Note: For non-constant strings named by string-exp, this macro internally uses static (non-lisp heap) memory to hold the conversion buffer while the forms in body are being evaluated. Thus, this macro is a convenient way of ensuring string data passed to foreign functions will not be asynchronously moved by lisp's garbage collector. For optimization reasons, however, static storage is not necessarily used when string-exp names a literal string.

To force non-garbage-collected static storage to be used with constant strings by this macro, use a non-constant string expression. Example:

(let ((my-string "My String"))
  (with-native-string (my-converted-string my-string)
    ...))

International Allegro CL is described in iacl.htm. The foreign functions implementation is described in foreign_functions.htm.

The general documentation description is in introduction.htm. The index in index.htm.