Изменение измерений массива

Следующие функции могут использоваться для изменения размера или формы массива. Их опции почти совпадают с опциями функции make-array.

[Функция] adjust-array array new-dimensions &key :element-type :initial-element :initial-contents :ﬁll-pointer :displaced-to :displaced-index-oﬀset

adjust-array принимает массив и те же аргументы, что и для make-array. Количество измерений, указанных в new-dimensions должно равняться рангу массива array.

adjust-array возвращает массив такого же типа и ранга, что и массив array, но с другим измерениями new-dimensions. Фактически, аргумент array модифицируется в соответствие с новыми указаниями. Но это может быть достигнуто двумя путями: модификацией массива array или созданием нового массива и модификацией аргумента array для соединения его с новым массивом.

В простейшем случае, можно указать только измерения new-dimensions и, возможно, аргумент :initial-element. Не пустые элементы массива array вставляются в новый массив. Элементы нового массива, которые не были заполнены значениями из старого массива, получают значение из :initial-element. Если аргумент не был указан, то первоначальное значение элементов не определено.

Если указан :element-type, тогда массив array должен был быть создан с указанием такого же типа. В противном случае сигнализируется ошибка. Указание :element-type в adjust-array служит только для проверки на существование ошибки несовпадения типов.

Если указаны :initial-contents или :displaced-to, тогда они обрабатываются как для make-array. В таком случае,

Если указан :ﬁll-pointer, тогда указатель заполнения массива array принимает указанное значение. Если массив array не содержал указателя заполнения сигнализируется ошибка.

X3J13 voted in June 1988 to clarify the treatment of the :ﬁll-pointer argument as follows.

If the :ﬁll-pointer argument is not supplied, then the ﬁll pointer of the array is left alone. It is an error to try to adjust the array to a total size that is smaller than its ﬁll pointer.

If the :ﬁll-pointer argument is supplied, then its value must be either an integer, t, or nil. If it is an integer, then it is the new value for the ﬁll pointer; it must be non-negative and no greater than the new size to which the array is being adjusted. If it is t, then the ﬁll pointer is set equal to the new size for the array. If it is nil, then the ﬁll pointer is left alone; it is as if the argument had not been supplied. Again, it is an error to try to adjust the array to a total size that is smaller than its ﬁll pointer.

An error is signaled if a non-nil :ﬁll-pointer value is supplied and the array to be adjusted does not already have a ﬁll pointer.

This extended treatment of the :ﬁll-pointer argument to adjust-array is consistent with the previously existing treatment of the :ﬁll-pointer argument to make-array.

adjust-array может, в зависимости от реализации и аргументов, просто изменить исходный массив или создать и вернуть новый. В последнем случае исходный массив изменяется, а именно соединяется с новым массивом, и имеет новые измерения.

X3J13 voted in January 1989 to allow adjust-array to be applied to any array. If adjust-array is applied to an array that was originally created with :adjustable true, the array returned is eq to its ﬁrst argument. It is not speciﬁed whether adjust-array returns an array eq to its ﬁrst argument for any other arrays. If the array returned by adjust-array is not eq to its ﬁrst argument, the original array is unchanged and does not share storage with the new array.

Under this new deﬁnition, it is wise to treat adjust-array in the same manner as delete and nconc: one should carefully retain the returned value, for example by writing

(setq my-array (adjust-array my-array ...))

rather than relying solely on a side eﬀect.

Если adjust-array применяется к массиву array, который соединён с другим массивом x, тогда ни массив array, ни возвращённый результат не будет соединены с x, если только такое соединения не задано явно в вызове adjust-array.

Например, предположим что массив 4-на-4 m выглядит так:

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

Тогда результат выражения

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

является массивом 3-на-5 с содержимым

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

Следует отметить, что если массив a создаётся соединённым с массивом b и затем массив b передаётся в adjust-array, то массив a все ещё будет соединён с массивом b. При этом должны быть приняты во внимание правила соединения массивов и построчный порядок следования элементов.

X3J13 voted in June 1988 to clarify the interaction of adjust-array with array displacement.

Suppose that an array A is to be adjusted. There are four cases according to whether or not A was displaced before adjustment and whether or not the result is displaced after adjustment.

Suppose A is not displaced either before or after. The dimensions of A are altered, and the contents are rearranged as appropriate. Additional elements of A are taken from the :initial-element argument. However, the use of the :initial-contents argument causes all old contents to be discarded.
Suppose A is not displaced before, but is displaced to array C after. None of the original contents of A appears in A afterwards; A now contains (some of) the contents of C, without any rearrangement of C.
Suppose A is displaced to array B before the call, and is displaced to array C after the call. (Note that B and C may be the same array.) The contents of B do not appear in A afterwards (unless such contents also happen to be in C, as when B and C are the same, for example). If :displaced-index-oﬀset is not speciﬁed in the call to adjust-array, it defaults to zero; the old oﬀset (into B) is not retained.
Suppose A is displaced to array B before the call, but is not displaced afterwards. In this case A gets a new “data region” and (some of) the 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 argument. However, the use of the :initial-contents argument 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 . (Caching techniques are of course permitted, as long as they preserve the semantics speciﬁed here.)

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 signaled at the time of the adjustment, but this is not required.

Note that omitting the :displaced-to argument to adjust-array is equivalent to specifying :displaced-to nil; in either case, the array is not displaced after the call regardless of whether it was displaced before the call.

17.6 Изменение измерений массива