►The Racket Reference
►12 Input and Output
▼12.1 Ports
On this page:
open-input-bytes
open-input-string
open-output-bytes
open-output-string
get-output-bytes
get-output-string
  top← prev  up  next → 
12.1.6 String Ports

A string port reads or writes from a byte string. An input string port can be created from either a byte string or a string; in the latter case, the string is effectively converted to a byte string using string->bytes/utf-8. An output string port collects output into a byte string, but get-output-string conveniently converts the accumulated bytes to a string.

Input and output string ports do not need to be explicitly closed. The file-position procedure works for string ports in position-setting mode.

procedure

(open-input-bytes bstr [name]) → input-port?

  bstr : bytes?
  name : any/c = 'string
Creates an input string port that reads characters from bstr (see Byte Strings). Modifying bstr afterward does not affect the byte stream produced by the port. The optional name argument is used as the name for the returned port.

procedure

(open-input-string str [name]) → input-port?

  str : string?
  name : any/c = 'string
Creates an input string port that reads bytes from the UTF-8 encoding (see Encodings and Locales) of str. The optional name argument is used as the name for the returned port.

procedure

(open-output-bytes [name]) → output-port?

  name : any/c = 'string
Creates an output string port that accumulates the output into a byte string. The optional name argument is used as the name for the returned port.

procedure

(open-output-string [name]) → output-port?

  name : any/c = 'string
The same as open-output-bytes.

procedure

(get-output-bytes out    
  [reset?    
  start-pos    
  end-pos]) → bytes?
  out : output-port?
  reset? : any/c = #f
  start-pos : exact-nonnegative-integer? = 0
  end-pos : exact-nonnegative-integer? = #f
Returns the bytes accumulated in the string port out so far in a freshly allocated byte string (including any bytes written after the port’s current position, if any). The out port must be an output string port produced by open-output-bytes (or open-output-string) or a structure whose prop:output-port property refers to such an output port (transitively).

If reset? is true, then all bytes are removed from the port, and the port’s position is reset to 0; if reset? is #f, then all bytes remain in the port for further accumulation (so they are returned for later calls to get-output-bytes or get-output-string), and the port’s position is unchanged.

The start-pos and end-pos arguments specify the range of bytes in the port to return; supplying start-pos and end-pos is the same as using subbytes on the result of get-output-bytes, but supplying them to get-output-bytes can avoid an allocation. The end-pos argument can be #f, which corresponds to not passing a second argument to subbytes.

procedure

(get-output-string out) → string?

  out : output-port?
Returns (bytes->string/utf-8 (get-output-bytes out) #\?).

Examples:

> (define i (open-input-string "hello world"))
> (define o (open-output-string))
> (write (read i) o)
> (get-output-string o)

"hello"

  top← prev  up  next →