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 return value depends on the value of the buffer argument. Return values are described below.

The buffer argument can either be an octet buffer (described above), or nil, or unsupplied (unsupplied is not the same as nil), or :growable (equivalent to unsupplied). If an octet buffer is supplied, an error will be signaled if the buffer overflows. The :growable value is necessary because some value must be supplied when a value is given for the external-format keyword argument.

If buffer is unsupplied or :growable, 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.

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): 

This macro returns the contents of the created buffer if buffer is unsupplied or :growable. If buffer is an octet array or nil, this macro returns, as multiple values, all values returned by the last form of the body.

;; buffer not supplied
cl-user(3): (with-output-to-buffer (b) 
              (values (write-string "hello" b) 1 2 3))
#(104 101 108 108 111)

;; buffer eq :growable
cl-user(5): (with-output-to-buffer (b :growable) 
              (values (write-string "hello" b) 1 2 3))
#(104 101 108 108 111)

;; buffer = nil
cl-user(4): (with-output-to-buffer (b nil) 
              (values (write-string "hello" b) (file-position b) 'more 'output))
"hello"
5
more
output

;; non-nil buffer supplied
cl-user(12): (with-output-to-buffer 
                (b (make-array 20 :element-type '(unsigned-byte 8))) 
              (values (write-string "hello" b) 1 2 3))
"hello"
1
2
3

;; non-nil buffer supplied but it is too small, 
;; so an error is signaled:
cg-user(13): (with-output-to-buffer 
                (b (make-array 10 :element-type '(unsigned-byte 8))) 
              (values (write-string "hello, how are you today?" b) 1 2 3))
Error: In sc-write-char-direct: Output exceeds workspace for #<buffer-output-simple-stream  pos 10 @ #x202796082>
[condition type: simple-error]
cg-user(14): 

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.
This page was not revised from the 9.0 page.
Created 2015.5.21.