octets-to-string

Arguments: octet-vector &key string (start 0) (end (or (position 0 octet-vector :start start) (length octet-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, 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 octet-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, 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 octets are available, filling additional strings as necessary.

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 native-to-string and string-to-octets.

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

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.