13.3 Byte and String Output (original) (raw)

13.3 Byte and String Output🔗ℹ

Writes a single character to out; more precisely, the bytes that are the UTF-8 encoding of char are written toout.

Writes a single byte to out.

The same as (write-char #\newline out).

Writes characters to out from str starting from index start-pos (inclusive) up to end-pos(exclusive). Like substring, the exn:fail:contract exception is raised if start-pos or end-pos is out-of-range forstr.

The result is the number of characters written to out, which is always (- end-pos start-pos).

If str is mutable, mutations after write-stringreturns do not affect the characters written to out. (This independence from mutation is not a special property ofwrite-string, but instead generally true of output functions.)

Like write-string, but writes bytes instead of characters.

Like write-bytes, but returns without blocking after writing as many bytes as it can immediately flush. It blocks only if no bytes can be flushed immediately. The result is the number of bytes written and flushed to out; if start-pos is the same asend-pos, then the result can be 0 (indicating a successful flush of any buffered data), otherwise the result is between1 and (- end-pos start-pos), inclusive.

The write-bytes-avail procedure never drops bytes; ifwrite-bytes-avail successfully writes some bytes and then encounters an error, it suppresses the error and returns the number of written bytes. (The error will be triggered by future writes.) If an error is encountered before any bytes have been written, an exception is raised.

Like write-bytes-avail, but never blocks, returns #fif the port contains buffered data that cannot be written immediately, and returns 0 if the port’s internal buffer (if any) is flushed but no additional bytes can be written immediately.

Like write-bytes-avail, except that breaks are enabled during the write. The procedure provides a guarantee about the interaction of writing and breaks: if breaking is disabled whenwrite-bytes-avail/enable-break is called, and if theexn:break exception is raised as a result of the call, then no bytes will have been written to out. See alsoBreaks.

Writes v directly to out if the port supports special writes, or raises exn:fail:contract if the port does not support special write. The result is always #t, indicating that the write succeeded.

Like write-special, but without blocking. If vcannot be written immediately, the result is #f without writing v, otherwise the result is #t and vis written.

Similar to write-bytes-avail, but instead of writing bytes immediately, it returns a synchronizable event (seeEvents). The out must support atomic writes, as indicated by port-writes-atomic?.

Synchronizing on the object starts a write from bstr, and the event becomes ready when bytes are written (unbuffered) to the port. If start-pos and end-pos are the same, then the synchronization result is 0 when the port’s internal buffer (if any) is flushed, otherwise the result is a positive exact integer. If the event is not selected in a synchronization, then no bytes will have been written to out.

Similar to write-special, but instead of writing the special value immediately, it returns a synchronizable event (seeEvents). The out must support atomic writes, as indicated by port-writes-atomic?.

Synchronizing on the object starts a write of the special value, and the event becomes ready when the value is written (unbuffered) to the port. If the event is not selected in a synchronization, then no value will have been written to out.

Returns #t if write-bytes-avail/enable-break can provide an exclusive-or guarantee (break or write, but not both) forout, and if the port can be used with procedures likewrite-bytes-avail-evt. Racket’s file-stream ports, pipes, string ports, and TCP ports all support atomic writes; ports created with make-output-port (see Custom Ports) may support atomic writes.

Returns #t if procedures like write-special can write arbitrary values to the port. Racket’s file-stream ports, pipes, string ports, and TCP ports all reject special values, but ports created with make-output-port (seeCustom Ports) may support them.