Issue ADJUST-ARRAY-DISPLACEMENT (Version 3)

[Masinter.pa@Xerox.COM]

(This was prepared before Kent's angry note.   I'm a little reluctant to
mail it out now, but I don't know what to do with it. I made the edits
in response to Kent's question, as well as changing the case of the lisp
words, changing revision to version, etc. I don't remember all of the
edits, but I spent quite a while on it.)

Rather than wait for some resolution of Kent's question about the
omission of the :DISPLACED-TO argument, I took the liberty of guessing
that adjusting a displaced-to array without setting the :displaced-to
meant that the result was displaced to the same place. I inserted rule 3
and renumbered the rules.

The previous version got lots of yes ballots. Any objections to this
one?

!
Issue:        ADJUST-ARRAY-DISPLACEMENT
Reference:    ADJUST-ARRAY (Steele p.297)
Category:     Clarification
Edit history: Version 1 by Fahlman, 18-Apr-87 (from Steele's list)
              Version 2 by Masinter
              Version 3 by Masinter, 5-Jun-87 (respond to comments)

Problem Description:

The interaction of ADJUST-ARRAY and displacement is insufficiently
specified in the case where the array being adjusted is displaced.

Proposal: ADJUST-ARRAY-DISPLAYCEMENT:RULES

Suppose we are adjusting array A, which is perhaps displaced to B before
the ADJUST-ARRAY call and perhaps to C after the call.

(1) A is not displaced before or after: The dimensions of A are altered,
and the contents rearranged as appropriate.  Additional elements of A
are taken from the :INITIAL-ELEMENT.  The use of :INITIAL-CONTENTS
causes all old contents to be discarded.

(2) A is not displaced before, but is displaced to C after.  As
specified in CLtL, none of the original contents of A appears in A
afterwards; A now contains the contents of C, without any rearrangement
of C.

(3) A is displaced to B before and after the call (A is displaced to B
before the call, and the :DISPLACED-TO argument of ADJUST-ARRAY either
is ommitted or is B.) The dimensions of A are altered, and the contents
rearranged as appropriate. If :DISPLACED-INDEX-OFFSET is not specified
in the ADJUST-ARRAY call, it defaults to zero; the old offset is not
retained. 

(4) A is displaced to B before the call, and is displaced to C after the
call.  As in case (2), the contents of B do not appear in A afterward
(unless such contents also happen to be in C).  If
:DISPLACED-INDEX-OFFSET is not specified in the ADJUST-ARRAY call, it
defaults to zero; the old offset (into B) is not retained.

(5) A is displaced to B before the call, but not displaced afterward.  A
gets a new "data region", and contents of B are copied into it as
appropriate to maintain the existing old contents; additional elements
of A are taken from the :INITIAL-ELEMENT.  However, the use of
:INITIAL-CONTENTS causes all old contents to be discarded.

If array X is displaced to array Y, and array Y is displaced to array Z,
and array Y is altered by ADJUST-ARRAY, array X must now refer to the
adjusted contents of Y.  This means that an implementation may not
collapse the chain to make X refer to Z directly and forget that the
chain of reference passes through array Y.  (Cacheing techniques are of
course permitted, as long as they preserve the semantics specified here
and in CLtL.)

If X is displaced to Y, it is an error to adjust Y in such a way that it
no longer has enough elements to satisfy X.  This error may be signalled
at the time of the adjustment, but this is not required.

Rationale:

This interaction must be clarified.  This set of rules was proposed some
time ago, as a result of discussions on the Common Lisp mailing list,
and this model has been adopted by many Common Lisp implementations.

Current Practice:

Many implementations currently follow the model proposed here.  Others
may do something random.  [See discussion below.]

Adoption cost:

Some existing implementations may have to be changed, but adopting any
other model would be worse.  Public-domain code implementing this model
is available from CMU.

Benefits:

Clarification of a situation that is currently not addressed by the
standard.

Conversion Cost:

This is a relatively uncommon situation, which is the reason it didn't
occur to the original language designers to specify how it works.  Any
user code that cares about this issue probably already follows the
proposed model.

Discussion:

The cleanup committee supports this clarification.

Moon pointed out that the Symbolics system currently does this, except
for case (5) above. The Symbolics system never copies the contents of B
in this case; all elements are taken from the :initial-element. However,
the behavior in the proposal seems as justifiable to him, and the
cleanup committee decided to stick with the proposal as described above.