convert-to-foreign-string

convert-to-foreign-string 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, length, byte-count

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.

external-format is interpreted as by with-foreign-string. The names of available external formats are listed in section 26.6 External Formats to translate Lisp characters from/to external encodings 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 allow-null is non-nil and string is nil then a null pointer pointer is returned. Otherwise, an error is signalled if string is nil.

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 and length and byte-count are not returned.