with-output-to-buffer

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

Broadly 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. (Unlike with-output-to-string, which accepts adjustable strings and strings with fill pointers, with-output-to-buffer will not accept a vector with fill pointer nor an adjustable vector.)

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. If it 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-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.