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 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
Calling a C function that takes an array of strings