transcoded-port(3scm)

💅 transcoded-port 💅

okay so bestie, this is the transcoded-port page from the Scheme Programmer's Manual, and it's literally the glow-up move that turns a binary port into a textual port. no cap, it's giving “bytes put on their text-era outfit” ✨.

🌸 NAME 🌸

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

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

• If binary-port is an input port, the new textual port will be an input port and will transcode the bytes that have not yet been read from binary-port.
• If binary-port is an output port, the new textual port will be an output port and will transcode output characters into bytes that are written to the byte sink represented by 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. it's not a normal close, bestie — it's a main-character close 💅.

🎀 RETURN VALUES 🎀

Returns a single value, which is a textual port. one value, one textual-port queen 👑.

🌸 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. basically: binary first, text later, and everybody slays 🫶.

🧠 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. the buffer said “respect my boundaries” and honestly? fair 🧚.

🌈 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. so yeah, the details matter, iykyk 💜.

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

not me side-eyeing a closed binary-port 🙈 — yes, that can be a problem.

👀 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). the lore is lore-ing 😭.

👑 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. like, the vibe is clear even if the implementation recipe is not 💀.

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. fr fr, edge cases are the final boss 🍓.

---

mwah 💋 cute sign-off: this page's footer tag is transcoded-port(3scm) and the date on it is 2022-04-04. byeee bestie, go transcode responsibly 🫶🌈