write-vector

Function

Package: excl

Arguments: sequence stream &key start end endian-swap

For a Gray stream, a check is made that the given vector is either a string or an octet vector (i.e. a vector of (signed-byte 8) or (unsigned-byte 8) elements), and the equivalent of write-sequence is performed. Otherwise an error is generated.

For a simple-stream:

If the vector is a string, then the equivalent of write-string is performed.

If the vector is not a string, the the equivalent of write-byte is performed on each byte of the vector, for as many octets as are specified for the vector. If each element consists of more than one octet, then the processing is done in the natural endianness of the machine architecture. Start and end arguments can be used to modify the number of octets written, and are specified as octet offsets into the vector (instead of numbers of elements, as in write-sequence). If the end argument is not specified, the length of the vector adjusted by the element-width is used instead. Note that if the vector is of an element-type that is smaller than an octet (8-bit byte) then the adjustment includes an alignment to the next higher octet boundary. Thus a bit vector of 10 bits will cause a transfer of 3 octets to occur.

The number of octets actually written (and stored from the vector) is added to the start argument and that result returned. Thus, the return value is the next octet in the vector that was not yet written. This interface more closely resembles that of read-vector/read-sequence, rather than that of write-sequence, which always returns the sequence argument. The reason for this implementation is to allow for partial and asynchronous writes.

If the vector argument is a single-float or double-float (and thus not an actual vector), it is treated specially and its bits are written as if the object were a vector of size one with element-type single- or double-float (as appropriate). This is an optimization to prevent consing when passing floats.

The endian-swap keyword argument allows the user to treat I/O with a consistent byte-ordering despite endian issues. See section The endian-swap keyword argument to read-vector and write-vector in streams.htm.

Note: write-vector is similar to write-sequence, but is different fundamentally in the following ways:

write-vector operations on non-strings are done on an octet basis, whereas write-sequence on non-strings is specified to write (variably-sized) bytes on an element-by-element basis. Thus, there is a general unpacking that occurs in write-vector.
The name "-sequence" implies too much; it includes handling of output from lists. write-vector writes vectors only for efficiency.

Note 2: the write-byte equivalent functionality can be optimized in the following way: If the stream's output buffer is not empty, it is written out with device-write. Then device-write is called for write-vector's vector argument, passing through the start and end arguments.

See streams.htm for information on the simple-streams implementation in Allegro CL.

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

Created 2000.10.5.