native-to-string

Arguments: address &key string make-string? length (external-format :default) truncate (string-start 0) string-end aligned

This function returns three values: (1) a string, (2) the number of characters copied, and (3) the number of octets used, which is a number representing the actual number of octets used by the conversion process.

This function converts (according to the external-format argument) and copies the string data from the memory location specified by address into a Lisp string. The string is returned. The number of characters copied to the string is returned as the second value and the number of octets used is returned as the third value.

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.

If the string argument is specified, then the string data will be copied into this argument. If a string is specified by string and it is not long enough, an error is signaled unless either make-string? is specified as non-nil, in which case a new string is created and string is ignored, or string-end is a number, in which case string will be filled to that point and information on how many characters were put in the string is returned as the second returned value. If string is not specified, make-string? is ignored (a new string is always created).

If the length argument is specified, then this argument's value specifies the number of bytes to copy. Note that if a null character is present in the string, conversion will stop at that character (which is taken to be a terminator) unless length is specified and greater than the location of the null character. See the example below.

The truncate keyword argument controls the behavior when the external-format convertor attempts to go past the end of the octet array. When truncate is true, native-to-string will terminate the current character conversion. When truncate is false, attempts to go past the end of the octet array are treated as external-format eof situations which may cause alternative valid character(s) to be returned. Using :truncate t is recommended when the octet array is a buffer that is not known to end with a complete character.

The arguments string-start and string-end are ignored unless string is specified. The string-start keyword argument determines at which position in the target string to insert converted characters. The string-end keyword argument determines the last position in the target string for inserting converted characters (its value, if a number, should be one greater than the last position in which to insert a character).

If string-end is nil and there are more characters to be inserted than space in the string, an error is signaled and no characters are inserted at all. If the value of string-end is a number, that error will not be signaled and instead characters are inserted up to position (- string-end 1). (But if string-end is greater than the length of the string, an array out of bounds type error might be signaled: this function does not test whether string-start and string-end have appropriate values.) The purpose of using string-end is to handle situations where you do not know in advance how many characters are to be converted. It allows filling a string, and then, using the third returned value (which tells how many octets were used) to determine if more characters are available, filling additional strings as necessary. (In the case of this function, you actually only know the address of remaining octets, if any. The related octets-to-string takes as its first argument an array of octets so you know how many are unconverted.)

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*)

;; Example of a string with a null charcater

cl-user(2): (string-to-native (coerce (list #\a (code-char 0) #\b)
'string))
549756032096
4
cl-user(3): (native-to-string *)
"a"  ;; default behavior: null terminates
1
1
cl-user(4): (native-to-string 549756032096 :length 4)
"a^@b^@" ;; this includes the final null-terminator because it was
generated by the original string-to-native
4
4
cl-user(5):

See locale-external-format and *locale*.

See also octets-to-string, string-to-octets, and string-to-native. See iacl.htm for general information on international character set support in Allegro CL and see foreign-functions.htm for information on foreign functions.

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