string-to-native

Arguments: string &key (start 0) (end (length string)) address (external-format :default) aligned (null-terminate t) result-vector

This function was modified by a patch which added the two additional keyword arguments null-terminate and result-vector. Behavior of this function if those arguments are unspecified has not changed. The documentation assumes the patch has been applied. (The patch is for version 10.0 only. Earlier versions are not changed.)

There are two return values. The second return value is always the number of bytes copied. The first return value depends on the value of the result-vector argument:

• If result-vector is nil (the default), the first return value is the address of the first copied byte.
• If result-vector is an octet vector, it is returned as the first return value.

This function converts (according to the external-format argument) and copies the string data from indices specified by start to end out of the Lisp string into a location determined by other arguments. Here is where the data is copied to:

• If result-vector and address are both nil or unspecified, the string data is copied to static (ie, non-Lisp heap) memory. In that case the address of the first character of the copied data is returned.
• If address is specified (as an integer giving a valid address) and result-vector is nil or unspecified, the string data is copied to that address and no new memory is allocated. address is typically in static space (having previously been allocated and now being reused). Extreme care should be excercised when address is in the Lisp heap as addresses may not remain valid after a garbage collection. Note in SMP Lisps, garbage collections cannot be avoided with certainty. Copying data to an incorrect address in the Lisp heap can cause the data to be lost or can cause data corruption and Lisp failure. Do not specify an address in the Lisp heap when using a SMP Lisp. address is returned as the first return value.
• If result-vector is an octet vector (of type (unsigned-byte 8)) and address is nil: the string data will be copied to it and it is returned as the first return value. (It is an error to specify non-nil values for both address and result-vector.) The vector can be a static vector (see Weak vectors, finalizations, static arrays, etc. in gc.htm), in which case its address can be used freely. If result-vector is stored in the Lisp heap, care should be taken not to take the address of the result vector (e.g. with lispval-to-address) until there is no chance for a gc. In an SMP Lisp, it is difficult to impossible to ensure garbage collections do not happen.

If the aligned keyword argument is true, then address is an aligned address. Aligned addresses are returned by functions like lispval-to-aligned-malloc-address.

The copied string data will be null-terminated if the null-terminate keyword argument is true (the default). Null terminated means that the byte following the last data element is 0. The number of 8-bit bytes copied including the null-terminator if present is returned as the second value of this function.

Conversion is done using the specified external-format. If external-format is not specified (or, equivalently, if the value of external-format is :default), then the external format returned by the following form is used:

(locale-external-format *locale*)

See locale-external-format and *locale*. See also string-to-octets, native-to-string, octets-to-native, and with-native-string.

See also iacl.htm for general information on international character set support in Allegro CL. See foreign-functions.htm for information on foreign functions.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.