native-to-string

Function

Package: excl

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

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 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 third 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.

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, then 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 charcaters 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, a 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 handle situations where you do not know in advance how may 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.)

By default, this function will convert from the native representation assumed for foreign function strings. Under International Allegro CL, this conversion is to EUC (ie, external-format :euc) under Unix, and to Windows MultiByte (ie, external-format :mb) under Windows. Overriding the default external-format is not supported in this Allegro CL release. When :default is specified, the value of *default-external-format* is used.

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

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.