with-output-to-buffer

Arguments: (var &optional buffer &key external-format) forms

Similar to with-output-to-string but with an octet buffer (a vector that is a simple-array with element type (unsigned-byte 8) or (signed-byte 8)) instead of a Lisp string. The external-format argument should be the name of an external-format, or :default. :default will cause the external format to be looked up in the locale. with-output-to-buffer is implemented using a buffer-output-simple-stream.

The buffer argument can either be an octet buffer (described above) or nil or unsupplied (unsupplied is not the same as nil). If an octet buffer is supplied, an error will be signaled if the buffer overflows.

If buffer is unsupplied, a suitable buffer is created and used. That buffer extends automatically as needed and so cannot overflow. The contents are available in the body of this macro using get-output-stream-buffer. Note that this option is not available if a value is specified for the external-format keyword argument. (Specifying nil is not equivalent to being unsupplied.)

If buffer is nil, the stream acts like a counting bit-bucket: no output is generated, and so no overflow can occur, but the file-position of the stream can be queried at the end of the write. This allows the following to be done:

cl-user(1): (with-output-to-buffer (stm nil)
              (write-string "hello" stm)
              (file-position stm))
5
cl-user(2): 

The macro with-underlying-simple-vector may be useful in conjunction with this macro as it allows any (unsigned-byte 8) or (signed-byte 8) array (not just simple one or just vectors) to be effectively used as the buffer.

See streams.htm for information on the simple-streams implementation in Allegro CL.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
The object described on this page has been modified in the 9.0 release; see the Release Notes.
Created 2019.8.20.