User Tools



  • with-output-to-string (var &optional string-form &key element-type) declaration* form*result*

Arguments and Values

var - a variable name. string-form - a form or nil; if non-nil, evaluated to produce string. string - a string that has a fill pointer. element-type - a type specifier; evaluated. The default is character. declaration - a decdeclarelare expression; not evaluated. forms - an implicit progn. results - If a string-form is not supplied or nil, a string; otherwise, the values returned by the forms.


with-output-to-string creates acharacter output stream, performs a series of operations that may send results to this stream, and then closes the stream.

The element-type names the type of the elements of the stream; a stream is constructed of the most specialized type that can accommodate elements of the given type.

The body is executed as an implicit progn with var bound to an output string stream. All output to that string stream is saved in a string.

If string is supplied, element-type is ignored, and the output is incrementally appended to string as if by use of vector-push-extend.

The output stream is automatically closed on exit from with-output-to-string, no matter whether the exit is normal or abnormal.

The output string stream to which the variable var is bound has dynamic extent; its extent ends when the form is exited.

If no string is provided, then with-output-to-string produces a stream that accepts characters and returns a string of the indicated element-type. If string is provided, with-output-to-string returns the results of evaluating the last form.

The consequences are undefined if an attempt is made to assign the variable var.


(defparameter *fstr* (make-array '(0) :element-type 'base-char :fill-pointer 0 :adjustable t))




(with-output-to-string (s *fstr*) (format s "here's some output") (input-stream-p s))



"here's some output"

Side Effects

If string-form was non-nil, then the string is modified.

Affected By


Exceptional Situations

The consequences are undefined if destructive modifications are performed directly on the string during the dynamic extent of the call.

See Also



Editor Notes

If no string is provided, the specification doesn't explicitly mention that with-output-to-string will return a fresh string.

While the implementations seem to always produce fresh strings, this behaviour is theoretically unspecified and implementation-defined.