read-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 read-sequence is performed. Otherwise an error is generated.

For a simple-stream: if the vector is a string, then for the first element of the string, a read-char equivalent is performed, and for every element thereafter, a read-char-no-hang equivalent is performed. Following the last-read-character, the unread-char length is set (instead of at every character read).

If the vector is not a string, the equivalent of read-byte is performed on the first byte of the vector, and the equivalent of excl::read-byte-no-hang is performed on each byte thereafter, 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 to be read, and are specified as octet offsets into the vector (instead of numbers of elements, as in read-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 read (and stored into 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 replaced.

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 that read-vector is similar to read-sequence, but is different fundamentally in the following ways:

read-vector operations on non-strings are done on an octet basis, whereas read-sequence on non-strings is specified to read (variably-sized) bytes on an element-by-element basis. Thus, there is a general packing that occurs in read-vector into any size vector. Also, the start and end keyword arguments and the return value are always in terms of octets, except for string simple-streams, where they are in terms of characters.
The name -sequence implies too much for efficient implementation; it includes handling of input into lists. read-vector reads into vectors for efficiency.

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.