#

## Issue WITH-OUTPUT-TO-STRING-APPEND-STYLE Writeup

    Issue:         WITH-OUTPUT-TO-STRING-APPEND-STYLE

    References:    CLtL, pages 331, 386

    Category:      CLARIFICATION

    Edit history:  Version 1, 25-Mar-88 JonL
    	       Version 2, 29-Mar-88 JonL (fix typos; comments by Daniels)
    	       Version 3, 23-May-88 JonL (fix nits raised by Masinter)
    	       Version 4, 23-May-88 JonL (change issue name -- only 1 proposal)
    	       Version 5,  7-Jun-88 Masinter (more nits)

    Problem description:

    CLtL p386 says that FORMATting to a fill-pointer'd string should add
    characters "as if by use of VECTOR-PUSH-EXTEND"; but CLtL p331 says that
    WITH-OUTPUT-TO-STRING will work "as if using VECTOR-PUSH-EXTEND if the
    string is adjustable, and otherwise as if using VECTOR-PUSH".  It's very
    unlikely that the original authors of these parts intended differing
    semantics for these two cases.  Furthermore, the semantics for
    WITH-OUTPUT-TO-STRING permit the inconspicuous loss of characters
    written to the string, since VECTOR-PUSH will just "drop on the floor"
    any characters that would go beyond the end.

    Proposal (WITH-OUTPUT-TO-STRING-APPEND-STYLE:VECTOR-PUSH-EXTEND):

    Change the documentation of WITH-OUTPUT-TO-STRING to be like that under
    FORMAT.  That is, replace the first sentence of the next-to-last paragraph
    on CLtL p331 by:
      "If *string* is specified, it must be a string with a fill pointer;
       the output is incrementally appended to the string (as if by use of
       VECTOR-PUSH-EXTEND)."

    Test Case:
        (let ((str (make-array 4 :element-type 'string-char :fill-pointer 0)))
          (with-output-to-string (s str) (princ "You Luz, Bunkie!" s))
          str)
    CLtL behaviour will return "You "; proposed behaviour will signal an error.

    Rationale:

    It's unlikely that the mention of VECTOR-PUSH in CLtL p331 was intended
    to suggest that characters could be quietly "dropped on the floor".  In
    any case, there is no practical or theoretical reason to make FORMAT and
    WITH-OUTPUT-TO-STRING act differently on non-adjustable strings.

    Current Practice:

    VaxLisp 2.2 and Lucid 3.0 implement the proposal; Lucid 2.1 and earlier
    versions implement CLtL.  For WITH-OUTPUT-TO-STRING, Xerox Common Lisp
    implements CLtL.  Symbolics Genera 7.2 implements the proposal.

    Cost to Implementors:

    Very small.

    Cost to Users:

    Virtually none.

    Benefits:

    Less special-casing in the semantics of "printing" to strings.
    More conformity with naive expectations about printing to strings.

    Aesthetics:

    Minor impact.

    Discussion:

    Implementations may want to actually call VECTOR-PUSH, rather than
    VECTOR-PUSH-EXTEND, on non-adjustable string in order to test the
    result -- nil means an overflow of the total length of the string;
    thus they may signal an error more directly related to the problem,
    rather than permitting VECTOR-PUSH-EXTEND to complain about a non-
    adjustable array.  But either way, the semantics is still that of
    VECTOR-PUSH-EXTEND: when you get to the end of the string, adjustable
    strings are extended, and non-adjustable strings cause error signals.

    It's perfectly acceptable to use VECTOR-PUSH-EXTEND with a non-adjustable
    array.  It's the error-signalling property of VECTOR-PUSH-EXTEND, as opposed
    to the "dropping on the floor" of VECTOR-PUSH, that motivated this proposal.

Copyright 1996-2005, LispWorks Ltd. All rights reserved.