Contents|Symbol Index|Up: Chapter 15 Dictionary|Prev: make-array|Next: adjustable-array-p

Function `adjust-array`

Syntax:

adjust-array array new-dimensions &key element-type initial-element initial-contents fill-pointer displaced-to displaced-index-offset → adjusted-array

Arguments and Values:

array—an array.

new-dimensions—a valid array dimension or a list of valid array dimensions.

17.6.0 6element-type—a type specifier. !!! Not sure how to express the default. Mail sent to Quinquevirate asking for thoughts.

17.6.0 7initial-element—an object. Initial-element must not be supplied if either initial-contents or displaced-to is supplied. !!! How to express this default??

!!! "array contents designator" ? -kmp 14-May-91initial-contents—an object. If array has rank greater than zero, then initial-contents is composed of nested sequences, the depth of which must equal the rank of array. Otherwise, array is zero-dimensional and initial-contents supplies the single element. initial-contents must not be supplied if either initial-element or displaced-to is given.

17.6.0 8fill-pointer—a valid fill pointer for the array to be created, or t, or nil. The default is nil.

displaced-to—an array or nil. initial-elements and initial-contents must not be supplied if displaced-to is supplied. !!! Default?

displaced-index-offset—an object of type (fixnum 0 n) where n is (array-total-size displaced-to). displaced-index-offset may be supplied only if displaced-to is supplied. !!! Default?

adjusted-array—an array.

Description:

17.6.0 3adjust-array changes the dimensions or elements of array. The result is an array of the same type and rank as array, 17.6.0 4 17.6.0 9that is either the modified array, or a newly created array to which array can be displaced, and that has the given new-dimensions.

Sandra points out that this is implied by the definition of "valid array dimension". The total number of elements that \param{array} can contain (as given by the product of all \param{new-dimensions}) must be less than \conref{array-total-size-limit}.

New-dimensions specify the size of each dimension of array.

Element-type specifies the type of the elements of the resulting array. If element-type is supplied, the consequences are unspecified if it is not a \term{type} What does "compatible" mean here?? -kmp 29-Apr-91 Sandra's curious, too. -kmp 14-Feb-92 that is compatible with {\tt (array-element-type \param{array})}. Sandra's suggested rewrite: the consequences are unspecified if \f{(upgraded-array-element-type \param{element-type})} is not the same as {\tt (array-element-type \param{array})}. KMP's rewritethe consequences are unspecified if the upgraded array element type of element-type is not the same as the actual array element type of array. Sandra thinks this is redundant. If the resulting \term{array} is a displaced \term{array}, the consequences are unspecified if \param{element-type} is not compatible with the \term{element type} of the \term{array} that the resulting \term{array} shares elements with. Redundant with Arguments and Values. If \kwd{element-type} is not supplied, the elements are of type \t.

If initial-contents is supplied, it is treated as for make-array. In this case none of the original contents of array appears in the resulting array.

If fill-pointer is an integer, it becomes the fill pointer for the resulting array. If fill-pointer is the symbol t, it indicates that the size of the resulting array should be used as the fill pointer. If fill-pointer is nil, it indicates that the fill pointer should be left as it is.

If displaced-to is supplied andnon-nil, a displaced array is created. The resulting array shares its contents with the array given by displaced-to. The resulting array cannot contain more elements than the array it is displaced to. If displaced-to is not supplied or nil, the resulting array is not a displaced array. If array $A$ is created displaced to array $B$ and subsequently array $B$ is given to adjust-array, array $A$ will still be displaced to array $B$ . Although array might be a displaced array, the resulting array is not a displaced array unless displaced-to is supplied and not nil. The interaction between adjust-array and displaced arrays is as follows given three arrays, A, B, and C:

A is not displaced before or after the call
```
 (adjust-array A ...)
```
The dimensions of A are altered, and the contents rearranged as appropriate. Additional elements of A are taken from initial-element. The use of initial-contents causes all old contents to be discarded.
A is not displaced before, but is displaced to C after the call
```
 (adjust-array A ... :displaced-to C)
```
None of the original contents of A appears in A afterwards; A now contains the contents of C, without any rearrangement of C.
A is displaced to B before the call, and is displaced to C after the call
```
 (adjust-array A ... :displaced-to B)
 (adjust-array A ... :displaced-to C)
```
B and C might be the same. 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 supplied in the adjust-array call, it defaults to zero; the old offset into B is not retained.
17.6.0 11
A is displaced to B before the call, but not displaced afterward.
```
 (adjust-array A ... :displaced-to B)
 (adjust-array A ... :displaced-to nil)
```
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 initial-element if supplied. However, the use of initial-contents causes all old contents to be discarded. If \param{array} is displaced to another array \f{x} when \funref{adjust-array} is applied to \param{array}, then afterwards neither \param{array} nor the returned result is displaced to \f{x} unless such displacement is explicitly re-specified in the call to \funref{adjust-array}.

If displaced-index-offset is supplied, it specifies the offset of the resulting array from the beginning of the array that it is displaced to. If displaced-index-offset is not supplied, the offset is 0. The size of the resulting array plus the offset value cannot exceed the size of the array that it is displaced to.

17.6.0 5If only new-dimensions and an initial-element argument are supplied, those elements of array that are still in bounds appear in the resulting array. The elements of the resulting array that are not in the bounds of array are initialized to initial-element; if initial-element is not provided, This issue finally did pass at the March-93 meeting. -kmp 5-May-93 then the initial contents of any resulting \term{elements} Rewritten to conform to the fact that issue UNINITIALIZED-ELEMENTS failed to clarify this in the other direction because consensus was that this was well-defined already. -kmp 15-Jan-92 are undefined. is \term{implementation-dependent}.the consequences of later reading any such new element of new-array before it has been initialized are undefined.

If initial-contents or displaced-to is supplied, then none of the original contents of array appears in the new array.

17.6.0 10

The following will be deleted: The consequences are unspecified if \funref{adjust-array} is invoked with an \param{array} argument that is not adjustable.

If \param{fill-pointer} is \nil, then the consequences are unspecified if \param{array} has a \term{fill pointer}.The consequences are unspecified if array is adjusted to a size smaller than its fill pointer without supplying the fill-pointer argument so that its fill pointer is properly adjusted in the process.

If A is displaced to B, the consequences are unspecified if B is adjusted in such a way that it no longer has enough elements to satisfy A.

If adjust-array is applied to an array that is actually adjustable, the array returned is identical to array. This was only needed when "\term{expressly adjustable}" was used in the previous sentence. It is \term{implementation-dependent} whether \funref{adjust-array} returns an \term{array} that is \term{identical} to its first argument for any other \term{arrays}.If the array returned by adjust-array is distinct from array, then the argument array is unchanged.

Note that if an array $A$ is displaced to another array $B$ , and $B$ is displaced to another array $C$ , and $B$ is altered by adjust-array, $A$ must now refer to the adjust contents of $B$ . This means that an implementation cannot collapse the chain to make $A$ refer to $C$ directly and forget that the chain of reference passes through $B$ . However, caching techniques are permitted as long as they preserve the semantics specified here.

Examples:

 (adjustable-array-p
  (setq ada (adjust-array
              (make-array '(2 3)
                          :adjustable t
                          :initial-contents '((a b c) (1 2 3)))
              '(4 6)))) → T 
 (array-dimensions ada) → (4 6) 
 (aref ada 1 1) → 2 
 (setq beta (make-array '(2 3) :adjustable t))
→ #2A((NIL NIL NIL) (NIL NIL NIL)) 
 (adjust-array beta '(4 6) :displaced-to ada)
→ #2A((A B C NIL NIL NIL)
       (1 2 3 NIL NIL NIL)
       (NIL NIL NIL NIL NIL NIL) 
       (NIL NIL NIL NIL NIL NIL))
 (array-dimensions beta) → (4 6)
 (aref beta 1 1) → 2

17.6.0 11Suppose that the 4-by-4 array in m looks like this:

#2A(( alpha     beta      gamma     delta )
    ( epsilon   zeta      eta       theta )
    ( iota      kappa     lambda    mu    )
    ( nu        xi        omicron   pi    ))

Then the result of

 (adjust-array m '(3 5) :initial-element 'baz)

is a 3-by-5 array with contents

#2A(( alpha     beta      gamma     delta     baz )
    ( epsilon   zeta      eta       theta     baz )
    ( iota      kappa     lambda    mu        baz ))

Affected By:

None.

Exceptional Situations:

An error of type error is signaled if fill-pointer is supplied and non-nil but array has no fill pointer.

\issue{ADJUST-ARRAY-NOT-ADJUSTABLE:DONKEY} An error \oftype{error} is signaled if an attempt is made to adjust an \param{array} that is not adjustable (that is, an \param{array} for which \funref{adjustable-array-p} returns \term{false}). \endissue{ADJUST-ARRAY-NOT-ADJUSTABLE:DONKEY}

Notes: