Macro

Summary

Converts a Lisp string to a foreign string, binds variables to a pointer to the foreign string, the number of elements in the string, and the number of bytes taken up by the string, then executes a list of forms, and finally de-allocates the foreign string and pointer.

Package

fli

Signature

with-foreign-string (pointer element-count byte-count &key external-format null-terminated-p allow-null) string &body body => last

body::= form*

Arguments

pointer

A symbol bound to a pointer to the foreign string.

element-count

A symbol bound to the number of elements in the foreign string.

byte-count

A symbol bound to the number of bytes occupied by the foreign string. If the element size of the string is equal to one byte, then byte-count will be the same as element-count.

external-format

An external format specification.

null-terminated-p

If t, the foreign string is terminated by a null character. The null character is included in the element-count of the string.

allow-null

A boolean. The default is nil.

string

The Lisp string to convert.

body

A list of forms to be executed.

form

A form to be executed.

Values

last

The value of the last form in body.

Description

The macro with-foreign-string is used to dynamically convert a Lisp string to a foreign string and execute a list of forms using the foreign string. The macro first converts string, a Lisp string, into a foreign string. The symbol pointer is bound to a pointer to the start of the string, the symbol element-count is set equal to the number of elements in the string, and the symbol byte-count is set equal to the number of bytes the string occupies. Then the list of forms specified by body is executed. Finally, the memory allocated for the foreign string and pointer is de-allocated.

external-format is used to specify the encoding of the foreign string. It defaults to a format appropriate for C string of type char*. For Unicode encoded strings, specify :unicode. If you want to pass a string to the Win32 API, known as STR in the Win32 API terminology, specify *multibyte-code-page-ef*, which is a variable holding the external format corresponding to the current Windows multi-byte code page. To change the default, call set-locale or set-locale-encodings. The names of available external formats are listed in the section "External formats" in the LispWorks User Guide and Reference Manual .

null-terminated-p specifies whether the foreign string is terminated with a null character. It defaults to t. If the string terminates in a null character, it is included in the element-count.

If allow-null is non-nil, then if string is nil a null pointer is passed.

See also

Modifying a string in a C function
Passing a string to a Windows function
Section "External formats" in the LispWorks User Guide and Reference Manual
convert-to-foreign-string
set-locale
set-locale-encodings
with-dynamic-foreign-objects