with-native-string

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.

Conversion is done using the specified external-format. If external-format is not specified (or, equivalently, if the value of external-format is :default, then the external format returned by the following form is used:

(locale-external-format *locale*)

See locale-external-format and *locale*.

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)
    ...))

See also iacl.htm for general information on international character set support in Allegro CL and see string-to-native, native-to-string, and foreign-functions.htm for information on foreign functions.

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page was not revised from the 6.1 page.
Created 2002.2.26.