write-vector

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 simple-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:

The value of sequence must normally be a vector, but there are some exceptions. sequence can also be an aligned-pointer (an integer), or a foreign-pointer with an address component that is word-aligned, but if it is either of these two kinds of addresses, then a valid end value must be given; no attempt will be made to figure out the length of the data at the address. sequence can also be a single-float or a double-float; see below

This function starts by blocking until any unwritten buffer contents are written out. Then if the vector is a string, then the equivalent of write-string is performed.

If the vector is not a string, then 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.

write-vector is a B/NB (blocking/non-blocking) function, blocking until the first element is written and not blocking thereafter. See Blocking behavior in simple-streams in streams.htm.

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 index of 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 sequence 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:

1. 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.
2. The name "-sequence" implies too much; it includes handling of output from lists. write-vector writes vectors only for efficiency.
3. write-vector works on simple-arrays of one dimension with an element-type other than t (these arrays contain data rather than pointers to data); it may not work on non-simple arrays or on arrays of more than one dimension.

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. This optimization only works if the vector is large and the length of the portion of the vector to be written exceeds a buffer-size. If the transfer is to be small, then it is worth taking the extra time to copy bytes into the stream's buffer, in order to avoid a device-write call for every call to write-vector.

See also read-vector.

See streams.htm for information on the simple-streams implementation 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.