get-bytevector-n!, read-bytevector! - read bytes from a port into a bytevector
(import (rnrs)) ;R6RS
(import (rnrs io ports)) ;R6RS
(import (scheme base)) ;R7RS
;; R6RS
(get-bytevector-n! binary-input-port bytevector start count)
;; R7RS
(read-bytevector! bytevector)
(read-bytevector! bytevector binary-input-port)
(read-bytevector! bytevector binary-input-port start)
(read-bytevector! bytevector binary-input-port start end)
Reads from binary-input-port, blocking as necessary, until count
bytes are available from binary-input-port or until an end of file is
reached. The return value depends on the result of the read operation:
- If count bytes are available before an end of file, they are
written into bytevector starting at index start, and the
result is count.
- If fewer bytes are available before the next end of file, the available
bytes are written into bytevector starting at index start,
and the result is a number object representing the number of bytes
actually read.
- If an end of file is reached before any bytes are available, an
end-of-file object is returned.
The input port is updated to point just past the bytes read.
- R7RS
- The procedure call (read-bytevector! bv port start
end) procedure is analogous to (get-bytevector-n!
port bv start (- end start)). The argument binary-input-port
defaults to the object returned by current-input-port(3scm),
start defaults to 0, and end defaults to the length of
bytevector.
- Multiple end-of-file conditions
- The port may return an end-of-file object and then still keep producing
data if another read is attempted. Files do not normally work this way,
but it is possible for other types of ports to do so, such as terminals.
R6RS explicitly mentions this situation while R7RS does not.
Returns a single value; an exact nonnegative integer, or an end-of-file object.
- R6RS
- There is a single, unique end-of-file object.
;; Apologies for the nonsensical example.
(call-with-port (open-file-input-port "/dev/zero")
(lambda (p)
(let ((bv (make-bytevector 4 1)))
(get-bytevector-n! p bv 1 1)
bv)))
=> #vu8(1 0 1 1)
This procedure is suitable when when you need to read binary data directly into
a buffer, which tends to be the case for some types of binary structures.
Other times it is more appropriate to use get-bytevector-n(3scm), which
will automatically give you a bytevector limited to the length of the data
returned by the read operation.
This procedure can raise exceptions with the following condition types:
- &assertion (R6RS)
- The wrong number of arguments was passed or an argument was outside its
domain. In particular, start and count must be exact,
nonnegative integer objects, and bytevector must be a mutable
bytevector with at least start+count elements.
- &i/o-read (R6RS)
- There was an I/O error during the read operation.
- &i/o-port (R6RS)
- This condition specifies the port object related to an
&i/o-read condition.
- R7RS
- The assertions described above are errors. Implementations may signal an
error, extend the procedure's domain of definition to include such
arguments, or fail catastrophically.
Reports prior to R6RS did not support binary I/O.
The default port used by read-bytevector! is the current input port,
which is normally a textual port that is not expected to support binary I/O.