make-array (original) (raw)

Creates and returns an array constructed of the most specialized type that can accommodate elements of type given by element-type. If dimensions is nil then a zero-dimensional array is created.

Dimensions represents the dimensionality of the new array.

element-type indicates the type of the elements intended to be stored in the new-array. The new-array can actually store any _objects_of the type which results from upgrading element-type; see Section 15.1.2.1 Array Upgrading.

If initial-element is supplied, it is used to initialize each element of new-array. If initial-element is supplied, it must be of the type given by element-type.initial-element cannot be supplied if either the :initial-contents option is supplied or displaced-to is non-nil. If initial-element is not supplied, the consequences of later reading an uninitialized element of _new-array_are undefined unless either initial-contents is supplied or displaced-to is non-nil.

initial-contents is used to initialize the contents of array. For example:

(make-array '(4 2 3) :initial-contents '(((a b c) (1 2 3)) ((d e f) (3 1 2)) ((g h i) (2 3 1)) ((j k l) (0 0 0))))

initial-contents is composed of a nested structure of sequences. The numbers of levels in the structure must equal the rank of array. Each leaf of the nested structure must be of the type given by element-type. If array is zero-dimensional, then initial-contents specifies the single_element_. Otherwise, initial-contents must be a _sequence_whose length is equal to the first dimension; each element must be a nested structure for an array whose dimensions are the remaining dimensions, and so on.Initial-contents cannot be supplied if either initial-element is supplied or displaced-to is non-nil. If initial-contents is not supplied, the consequences of later reading an uninitialized element of _new-array_are undefined unless either initial-element is supplied or displaced-to is non-nil.

If adjustable is non-nil, the array is expressly adjustable (and so actually adjustable); otherwise, the array is not expressly adjustable (and it is implementation-dependent whether the array is actually adjustable).

If fill-pointer is non-nil, the array must be one-dimensional; that is, the array must be a vector. If fill-pointer is t, the length of the vector is used to initialize the fill pointer. If fill-pointer is an integer, it becomes the initial fill pointer for the vector.

If displaced-to is non-nil,make-array will create a _displaced array_and displaced-to is the target of that displaced array. In that case, the consequences are undefined if the actual array element type of displaced-to is not type equivalent to the _actual array element type_of the array being created. If displaced-to is nil, the array is not a displaced array.

The displaced-index-offset is made to be the index offset of the array. When an array A is given as the :displaced-to argument to make-arraywhen creating array B, then array B is said to be displaced to array A. The total number of elements in an array, called the total size of the array, is calculated as the product of all the dimensions. It is required that the total size of A be no smaller than the sum of the total size of B plus the offset n supplied by the displaced-index-offset. The effect of displacing is that array B does not have any elements of its own, but instead maps accesses to itself into_accesses_ to array A. The mapping treats both arrays as if they were one-dimensional by taking the elements in row-major order, and then maps an access to element k of array B to an access to elementk+n of array A.

If make-array is called with adjustable, fill-pointer, and displaced-to each nil, then the result is a simple array. If make-array is called with one or more of adjustable,fill-pointer, or displaced-to being true, whether the resulting array is a simple array is implementation-dependent.

When an array A is given as the :displaced-to argument tomake-array when creating array B, then array B is said to be displaced to array A. The total number of elements in an array, called the total size of the array, is calculated as the product of all the dimensions. The consequences are unspecified if the total size of A is smaller than the sum of the total size of B plus the offset n supplied by the displaced-index-offset. The effect of displacing is that array B does not have any elements of its own, but instead maps accesses to itself into_accesses_ to array A. The mapping treats both arrays as if they were one-dimensional by taking the elements in row-major order, and then maps an access to element k of array B to an _access_to element k+n of array A.