Function

Summary

Converts a Lisp string to a foreign string.

Package

fli

Signature

convert-to-foreign-string string &key external-format null-terminated-p allow-null into limit allocation => pointer

convert-to-foreign-string string &key external-format null-terminated-p allow-null into limit allocation => pointer, length, byte-count

Package

fli

Arguments

string

A Lisp string.

external-format

An external format specification.

null-terminated-p

If t, the foreign string terminates with a null character. The default value is t.

allow-null

A boolean. The default is nil.

into

A foreign array, a foreign pointer or nil. The default is nil.

limit

A non-negative fixnum, or nil. The default is nil.

allocation

A keyword, either :dynamic or :static. The default is :static.

Values

pointer

A FLI pointer to the foreign string.

length

The length of the foreign string (including the terminating null character if there is one).

byte-count

The number of bytes in the foreign string.

Description

The function convert-to-foreign-string converts a Lisp string to a foreign string, and returns a pointer to the string.

The external-format argument is interpreted as by with-foreign-string. The names of available external formats are listed in the section "External formats" in the LispWorks User Guide and Reference Manual .

The null-terminated-p argument specifies whether the foreign string is terminated with a null character. It defaults to t.

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

If into is nil, then a new foreign string is allocated according to allocation, and limit is ignored.

If into is a FLI pointer to a integer type, then limit must be a fixnum and up to limit elements are filled with elements converted from the characters of string. The size of the integer type must equal the foreign size of external-format.

If into is a FLI array of integers or a pointer to a FLI array of integers, up to limit elements are filled with elements converted from the characters of string. If limit is nil, then the dimensions of the array are used. The size of the array element type must equal the foreign size of external-format.

If allocation is :dynamic, then convert-to-foreign-string allocates memory for the string and pointer within the scope of the body of with-dynamic-foreign-objects and additional values, length and byte-count are returned. This is equivalent to using convert-to-dynamic-foreign-string. Otherwise, the allocation is static.

See also

convert-from-foreign-string
set-locale
set-locale-encodings
with-foreign-string
Section "External formats" in the LispWorks User Guide and Reference Manual
Calling a C function that takes an array of strings