octets-to-string

Function

Package: excl

Arguments: octet-vector &key string (start 0) (end (or (position 0 mb-vector :start start) (length mb-vector))) make-string? (external-format :default) truncate (string-start 0) string-end

In releases prior to 6.0, this function was named mb-to-string. The old name is preserved for backward compatibility in release 6.0, but users should use the new name.

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 count of octets used by the conversion process.

This function converts (according to the external-format argument) and copies the string data from the subsequence of mb-vector denoted by the start and end arguments 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 octets are used (and thus how many remain) is returned as the third returned value.

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, octets-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 octets are available, filling additional strings as necessary.

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 iacl.htm for general information on international character set support in Allegro CL.

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

Created 2000.10.5.