read-vector

Arguments: sequence stream &key start end endian-swap

Return value:

The number of octets actually read is added to the value of the start argument and that result returned. Thus, the return value is the index of the next octet in the vector (the value of sequence) that was not yet replaced.

For a Gray stream:

For a Gray stream, a check is made that the given vector (the value of sequence) 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 read-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.

If the vector is a string, the equivalent of read-char is performed on the stream and the result is stored into the first character of the portion of the sequence bounded by the start and end arguments. The equivalent of read-char-no-hang is performed for each character thereafter. Following the last-read-character, the unread-char length is set (instead of at every character read). See below for the blocking behavior of this function and the behavior when an EOF is encountered.

If the vector is not a string, the equivalent of read-byte is performed on the stream and the result is stored into the first byte of the portion of the sequence bounded by the start and end arguments. The equivalent of excl::read-byte-no-hang (a internal function analogous to read-char-no-hang) is performed for each byte thereafter, for as many octets as are specified for the vector. If each element of the vector consists of more than one octet, then the processing is done in the natural endianness of the machine architecture. On big endian machines octets read will be stored in the most significant through least significant octets of the values in the array. The reverse is true on little endian machines. See below for the blocking behavior of this function and the behavior when an EOF is encountered.

The 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 20 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 index of the next octet in the vector that was not yet replaced.

Note on blocking and EOF behavior

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

This function does not error if an EOF is encountered. It simply returns the number of octets actually read (and stored into the vector) added to the value start argument. That value contains the relevant information (how much was read) and can be analyzed if necessary to determine what occurred. For example

(read-vector vec stream)

returns 0 if an EOF is encountered immediately. Because at least one object is read if there is anything to read, a return value of 0 can only mean an EOF was encountered before an object was read.

If a value for start is specified and an EOF is encountered immediately, that value is returned (because the return value is the number of octets actually read -- 0 when an EOF is encountered immediately added to the value start argument). This, again assuming trying to read from stream will result in an immediate EOF,

(read-vector vec stream :start 4)

returns 4.

The endian-swap argument

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

read-vector and cl:read-sequence

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 -sequence (in the name of the function read-sequence) implies too much for efficient implementation since it includes handling of input into lists. read-vector reads into vectors for efficiency.
• read-vector works on specialized simple-arrays of one dimension. (A specialized array, of course, is an array whose element type is a proper subtype of t. See Data types in implementation.htm for a list of specialized arrays in Allegro CL.)

  read-vector is not supported for non-specialized arrays, non-simple arrays, or arrays of more than one dimension.

See also write-vector.

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

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.