LispWorks Foreign Language Interface User Guide and Reference Manual > 5 Function and Macro Reference

NextPrevUpTopContentsIndex

convert-to-foreign-string

Function
Summary

Converts a Lisp string to a foreign string.

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, 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 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 passed, then it is a foreign array which gets filled with elements converted from the characters of string up to limit .

If limit is a fixnum, then only the characters of string below index limit are converted.

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


LispWorks Foreign Language Interface User Guide and Reference Manual - 21 Dec 2009

NextPrevUpTopContentsIndex