transcoded-port - convert a binary port to a textual port

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs io ports))            ;R6RS

SYNOPSIS

(transcoded-port binary-port transcoder)

DESCRIPTION

Returns a new textual port with the specified transcoder.

The new textual port's state is largely the same as that of binary-port.

The binary-port is closed in a special way that allows the new textual port to continue to use the byte source and/or sink represented by binary-port, even though binary-port itself is closed and cannot be used anymore for input and output.

RETURN VALUES

Returns a single value, which is a textual port.

EXAMPLES

;; This is like utf8->string
(let* ((p (open-bytevector-input-port #vu8(194 169)))
       (tc (make-transcoder (utf-8-codec)))
       (tp (transcoded-port p tc)))
  (get-string-all tp))
        => "©"

APPLICATION USAGE

This is used in applications that initially operate on a port in binary mode before switching to textual mode, such as programs that detect a file's encoding or that write a binary header. It is also used when an API provides a binary port, such as in networking libraries, but the port is passed to a library designed for textual ports.

RATIONALE

Transcoding is more efficient when performed on a buffer. If the underlying port was still directly usable then it would be in conflict with such buffering. Therefore the binary port is closed, while the underlying sink and/or source is kept open.

COMPATIBILITY

Compatible with R6RS and semi-compatible with Scheme implementations that provide SRFI-181. The latter attempted to remove textual input/output ports but does not say what happens when a binary input/output port is passed to transcoded-port. It also makes it an error to read from or write to the binary-port before calling transcoded-port.

ERRORS

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. May be raised if binary-port is closed.

SEE ALSO

make-transcoder(3scm), open-input-file(3scm), ports(7scm)

STANDARDS

R6RS, SRFI-181

HISTORY

The transcoded-port procedure first appeared in R6RS as part of the reworked I/O system. It was much later the subject of SRFI-186, which was withdrawn and superseded by the somewhat earlier SRFI-181 (an instance of the "twin paradox" in special relativity).

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/.

BUGS

How to close the port in the "special way" is not obvious and has been interpreted differently, but the intention is clearly just to stop the sink and/or source from being used through passing binary-port to an I/O procedure.

Ports can be both input and output ports. This gives rise to some tricky situations, and gets worse in combination with transcoders. Implementors should be careful to get the edge cases right.

Markup created by unroff 1.0sc,    March 04, 2023.