| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
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.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |