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 can specify an expression returning a lisp string. If either start or end is specified, the substring bounded by the start and end arguments is used.

The string-exp argument may also specify an expression returning a lisp vector of octet integers. In this case, no external-format conversion occurs, but the subsequence bounded by the start and end arguments is copied into a dynamic-extent array and bound by string-var as described below.

If string-exp is a string, then 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 null-terminated 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 native-length-var variable's value does not include the null-terminator byte(s). The ef-nulls function can be used to determine how many null terminator bytes are being used.

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

The macro with-native-strings* allows allows nesting of with-native-string calls.

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-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.