Warning: This is the manual of the legacy Guile 2.0 series. You may want to read the manual of the current stable series instead.

6.14.10.8 Binary Input

R6RS binary input ports can be created with the procedures described below.

Scheme Procedure: open-bytevector-input-port bv [transcoder]

C Function: scm_open_bytevector_input_port (bv, transcoder)

Return an input port whose contents are drawn from bytevector bv (see Bytevectors).

The transcoder argument is currently not supported.

Scheme Procedure: make-custom-binary-input-port id read! get-position set-position! close

C Function: scm_make_custom_binary_input_port (id, read!, get-position, set-position!, close)

Return a new custom binary input port¹⁷ named id (a string) whose input is drained by invoking read! and passing it a bytevector, an index where bytes should be written, and the number of bytes to read. The read! procedure must return an integer indicating the number of bytes read, or 0 to indicate the end-of-file.

Optionally, if get-position is not #f, it must be a thunk that will be called when port-position is invoked on the custom binary port and should return an integer indicating the position within the underlying data stream; if get-position was not supplied, the returned port does not support port-position.

Likewise, if set-position! is not #f, it should be a one-argument procedure. When set-port-position! is invoked on the custom binary input port, set-position! is passed an integer indicating the position of the next byte is to read.

Finally, if close is not #f, it must be a thunk. It is invoked when the custom binary input port is closed.

The returned port is fully buffered by default, but its buffering mode can be changed using setvbuf (see setvbuf).

Using a custom binary input port, the open-bytevector-input-port procedure could be implemented as follows:

(define (open-bytevector-input-port source)
  (define position 0)
  (define length (bytevector-length source))

  (define (read! bv start count)
    (let ((count (min count (- length position))))
      (bytevector-copy! source position
                        bv start count)
      (set! position (+ position count))
      count))

  (define (get-position) position)

  (define (set-position! new-position)
    (set! position new-position))

  (make-custom-binary-input-port "the port" read!
                                  get-position
                                  set-position!))

(read (open-bytevector-input-port (string->utf8 "hello")))
⇒ hello

Binary input is achieved using the procedures below:

Scheme Procedure: get-u8 port

C Function: scm_get_u8 (port)

Return an octet read from port, a binary input port, blocking as necessary, or the end-of-file object.

Scheme Procedure: lookahead-u8 port

C Function: scm_lookahead_u8 (port)

Like get-u8 but does not update port’s position to point past the octet.

Scheme Procedure: get-bytevector-n port count

C Function: scm_get_bytevector_n (port, count)

Read count octets from port, blocking as necessary and return a bytevector containing the octets read. If fewer bytes are available, a bytevector smaller than count is returned.

Scheme Procedure: get-bytevector-n! port bv start count

C Function: scm_get_bytevector_n_x (port, bv, start, count)

Read count bytes from port and store them in bv starting at index start. Return either the number of bytes actually read or the end-of-file object.

Scheme Procedure: get-bytevector-some port

C Function: scm_get_bytevector_some (port)

Read from port, blocking as necessary, until bytes are available or an end-of-file is reached. Return either the end-of-file object or a new bytevector containing some of the available bytes (at least one), and update the port position to point just past these bytes.

Scheme Procedure: get-bytevector-all port

C Function: scm_get_bytevector_all (port)

Read from port, blocking as necessary, until the end-of-file is reached. Return either a new bytevector containing the data read or the end-of-file object (if no data were available).

The (ice-9 binary-ports) module provides the following procedure as an extension to (rnrs io ports):

Scheme Procedure: unget-bytevector port bv [start [count]]

C Function: scm_unget_bytevector (port, bv, start, count)

Place the contents of bv in port, optionally starting at index start and limiting to count octets, so that its bytes will be read from left-to-right as the next bytes from port during subsequent read operations. If called multiple times, the unread bytes will be read again in last-in first-out order.