read-vector

Arguments: sequence stream &key start end endian-swap

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 be a vector.

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). 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 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. On big endian machines octets read will be stored in the most significant though least significant octets of the values in the array. The reverse is true on little endian machines.

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.

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 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.

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 that one dimension.

See also write-vector.

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

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page has had moderate revisions compared to the 6.1 page.
Created 2002.2.26.