User Tools

A PCRE internal error occured. This might be caused by a faulty plugin

====== Function MAKE-ARRAY ====== ====Syntax==== * **make-array** //dimensions ''&key'' element-type initial-element initial-contents adjustable fill-pointer displaced-to displaced-index-offset// → //new-array// ====Arguments and Values==== * //dimensions// - a //[[CL:Glossary:designator]]// for a //[[CL:Glossary:list]]// of //[[CL:Glossary:valid array dimensions]]//. * //element-type// - a //[[CL:Glossary:type specifier]]//. The default is **[[CL:Types:t]]**. * //initial-element// - an //[[CL:Glossary:object]]//. * //initial-contents// - an //[[CL:Glossary:object]]//. * //adjustable// - a //[[CL:Glossary:generalized boolean]]//. The default is **[[CL:Constant Variables:nil]]**. * //fill-pointer// - a //[[CL:Glossary:valid fill pointer]]// for the //[[CL:Glossary:array]]// to be created, or **[[CL:Constant Variables:t]]** or **[[CL:Constant Variables:nil]]**. The default is **[[CL:Constant Variables:nil]]**. * //displaced-to// - an //[[CL:Glossary:array]]// or **[[CL:Constant Variables:nil]]**. The default is **[[CL:Constant Variables:nil]]**. This option must not be supplied if either //initial-element// or //initial-contents// is supplied. * //displaced-index-offset// - a //[[CL:Glossary:valid array row-major index]]// for //displaced-to//. The default is ''0''. This option must not be supplied unless a //[[CL:Glossary:non-nil]]// //displaced-to// is supplied. * //new-array// - an //[[CL:Glossary:array]]//. ====Description==== **make-array** creates and returns an //[[CL:Glossary:array]]// constructed of the most //[[CL:Glossary:specialized]]// //[[CL:Glossary:type]]// that can accommodate elements of //[[CL:Glossary:type]]// given by //element-type//. If //dimensions// is **[[CL:Constant Variables:nil]]** then a zero-dimensional //[[CL:Glossary:array]]// is created. //dimensions// represents the dimensionality of the new //[[CL:Glossary:array]]//. //element-type// indicates the //[[CL:Glossary:type]]// of the elements intended to be stored in the //new-array//. The //new-array// can actually store any //[[CL:Glossary:object|objects]]// of the //[[CL:Glossary:type]]// which results from //[[CL:Glossary:upgrade|upgrading]]// //element-type//; see section {\secref\ArrayUpgrading}. If //initial-element// is supplied, it is used to initialize each //[[CL:Glossary:element]]// of //new-array//. If //initial-element// is supplied, it must be of the //[[CL:Glossary:type]]// given by //element-type//. //initial-element// cannot be supplied if either the **'':initial-contents''** option is supplied or //displaced-to// is //[[CL:Glossary:non-nil]]//. If //initial-element// is not supplied, the consequences of later reading an uninitialized //[[CL:Glossary:element]]// of //new-array// are undefined unless either //initial-contents// is supplied or //displaced-to// is //[[CL:Glossary:non-nil]]//. //initial-contents// is used to initialize the contents of //[[CL:Glossary:array]]//. For example: <blockquote> (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)))) <o>#3A(((A B C) (1 2 3)) ((D E F) (3 1 2)) ((G H I) (2 3 1)) ((J K L) (0 0 0)))</o> </blockquote> //initial-contents// is composed of a nested structure of //[[CL:Glossary:sequences]]//. The numbers of levels in the structure must equal the rank of //[[CL:Glossary:array]]//. Each leaf of the nested structure must be of the //[[CL:Glossary:type]]// given by //element-type//. If //[[CL:Glossary:array]]// is zero-dimensional, then //initial-contents// specifies the single //[[CL:Glossary:element]]//. Otherwise, //initial-contents// must be a //[[CL:Glossary:sequence]]// whose length is equal to the first dimension; each element must be a nested structure for an //[[CL:Glossary: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 //[[CL:Glossary:non-nil]]//. If //initial-contents// is not supplied, the consequences of later reading an uninitialized //[[CL:Glossary:element]]// of //new-array// are undefined unless either //initial-element// is supplied or //displaced-to// is //[[CL:Glossary:non-nil]]//. If //adjustable// is //[[CL:Glossary:non-nil]]//, the array is //[[CL:Glossary:expressly adjustable]]// (and so //[[CL:Glossary:actually adjustable]]//); otherwise, the array is not //[[CL:Glossary:expressly adjustable]]// (and it is //[[CL:Glossary:implementation-dependent]]// whether the array is //[[CL:Glossary:actually adjustable]]//). If //fill-pointer// is //[[CL:Glossary:non-nil]]//, the //[[CL:Glossary:array]]// must be one-dimensional; that is, the //[[CL:Glossary:array]]// must be a //[[CL:Glossary:vector]]//. If //fill-pointer// is **[[CL:Constant Variables:t]]**, the length of the //[[CL:Glossary:vector]]// is used to initialize the //[[CL:Glossary:fill pointer]]//. If //fill-pointer// is an //[[CL:Glossary:integer]]//, it becomes the initial //[[CL:Glossary:fill pointer]]// for the //[[CL:Glossary:vector]]//. If //displaced-to// is //[[CL:Glossary:non-nil]]//, **make-array** will create a //[[CL:Glossary:displaced array]]// and //displaced-to// is the //[[CL:Glossary:target]]// of that //[[CL:Glossary:displaced array]]//. In that case, the consequences are undefined if the //[[CL:Glossary:actual array element type]]// of //displaced-to// is not //[[CL:Glossary:type equivalent]]// to the //[[CL:Glossary:actual array element type]]// of the //[[CL:Glossary:array]]// being created. If //displaced-to// is **[[CL:Constant Variables:nil]]**, the //[[CL:Glossary:array]]// is not a //[[CL:Glossary:displaced array]]//. The //displaced-index-offset// is made to be the index offset of the //[[CL:Glossary:array]]//. When an array A is given as the '':displaced-to'' argument to **make-array** when creating array B, then array B is said to be displaced to array A. The total number of elements in an //[[CL:Glossary:array]]//, called the total size of the //[[CL:Glossary: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 //[[CL:Glossary:access|accesses]]// to itself into //[[CL:Glossary:access|accesses]]// to array A. The mapping treats both //[[CL:Glossary:array|arrays]]// as if they were one-dimensional by taking the elements in row-major order, and then maps an //[[CL:Glossary:access]]// to element ''k'' of array B to an //[[CL:Glossary:access]]// to element ''k''+''n'' of array A. If **make-array** is called with //adjustable//, //fill-pointer//, and //displaced-to// each **[[CL:Constant Variables:nil]]**, then the result is a //[[CL:Glossary:simple array]]//. If **make-array** is called with one or more of //adjustable//, //fill-pointer//, or //displaced-to// being //[[CL:Glossary:true]]//, whether the resulting //[[CL:Glossary:array]]// is a //[[CL:Glossary:simple array]]// is //[[CL:Glossary:implementation-dependent]]//. When an array A is given as the '':displaced-to'' argument to **make-array** when creating array B, then array B is said to be displaced to array A. The total number of elements in an //[[CL:Glossary:array]]//, called the total size of the //[[CL:Glossary: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 //[[CL:Glossary:access|accesses]]// to itself into //[[CL:Glossary:access|accesses]]// to array A. The mapping treats both //[[CL:Glossary:array|arrays]]// as if they were one-dimensional by taking the elements in row-major order, and then maps an //[[CL:Glossary:access]]// to element ''k'' of array B to an //[[CL:Glossary:access]]// to //[[CL:Glossary:element]]// ''k''+''n'' of array A. ====Examples==== <blockquote> (make-array 5) ;;; Creates a one-dimensional array of five elements. (make-array '(3 4) :element-type '(mod 16)) ;;; Creates a two-dimensional array, 3 by 4, with four-bit elements. (make-array 5 :element-type 'single-float) ;;; Creates an array of single-floats. (make-array nil :initial-element nil) <r>#0ANIL</r> (make-array 4 :initial-element nil) <r>#(NIL NIL NIL NIL)</r> (make-array '(2 4) :element-type '(unsigned-byte 2) :initial-contents '((0 1 2 3) (3 2 1 0))) <r>#2A((0 1 2 3) (3 2 1 0))</r> (make-array 6 :element-type 'character :initial-element #\a :fill-pointer 3) <r>"aaa"</r> </blockquote> The following is an example of making a //[[CL:Glossary:displaced array]]//. <blockquote> ([[CL:Macros:defparameter]] a (make-array '(4 3))) <r>#<ARRAY 4x3 simple 32546632> </r> (dotimes (i 4) (dotimes (j 3) ([[CL:Macros:setf]] (aref a i j) (list i 'x j '= (* i j))))) <r>NIL </r> ([[CL:Macros:defparameter]] b (make-array 8 :displaced-to a :displaced-index-offset 2)) <r>#<ARRAY 8 indirect 32550757> </r> (dotimes (i 8) (print (list i (aref b i)))) <o>(0 (0 X 2 = 0)) (1 (1 X 0 = 0)) (2 (1 X 1 = 1)) (3 (1 X 2 = 2)) (4 (2 X 0 = 0)) (5 (2 X 1 = 2)) (6 (2 X 2 = 4)) (7 (3 X 0 = 0))</o> <r>NIL </r> </blockquote> The last example depends on the fact that //[[CL:Glossary:array|arrays]]// are, in effect, stored in row-major order. <blockquote> ([[CL:Macros:defparameter]] *a1* (make-array 50)) <r>*A1*</r> *a1* <r>#<ARRAY 50 simple 32562043> </r> ([[CL:Macros:defparameter]] *b1* (make-array 20 :displaced-to *a1* :displaced-index-offset 10)) <r>*B1*</r> *b1* <r>#<ARRAY 20 indirect 32563346></r> (length *b1*) <r>20</r> ([[CL:Macros:defparameter]] *a2* (make-array 50 :fill-pointer 10)) <r>*A2*</r> *a2* <r>#<ARRAY 50 fill-pointer 10 46100216> </r> ([[CL:Macros:defparameter]] *b2* (make-array 20 :displaced-to *a2* :displaced-index-offset 10)) *B2* *b2* <r>#<ARRAY 20 indirect 46104010> </r> (length *a2*) <r>10 </r> (length *b2*) <r>20</r> ([[CL:Macros:defparameter]] *a3* (make-array 50 :fill-pointer 10)) <r>*A3*</r> *a3* <r>#<ARRAY 50 fill-pointer 10 46105663> </r> ([[CL:Macros:defparameter]] *b3* (make-array 20 :displaced-to *a3* :displaced-index-offset 10 :fill-pointer 5)) <r>*B3*</r> *b3* <r>#<ARRAY 20 indirect, fill-pointer 5 46107432> </r> (length *a3*) <r>10 </r> (length *b3*) <r>5</r> </blockquote> ====Affected By==== None. ====Exceptional Situations==== None. ====See Also==== **[[CL:Functions:adjustable-array-p|Function ADJUSTABLE-ARRAY-P]]**, **[[CL:Functions:aref|Function AREF]]**, **[[CL:Functions:arrayp|Function ARRAYP]]**, **[[CL:Functions:array-element-type|Function ARRAY-ELEMENT-TYPE]]**, **[[CL:Constant Variables:array-rank-limit|Constant Variable ARRAY-RANK-LIMIT]]**, **[[CL:Constant Variables:array-dimension-limit|Constant Variable ARRAY-DIMENSION-LIMIT]]**, **[[CL:Functions:fill-pointer|Function FILL-POINTER]]**, **[[CL:Functions:upgraded-array-element-type|Function UPGRADED-ARRAY-ELEMENT-TYPE]]** ====Notes==== There is no specified way to create an //[[CL:Glossary:array]]// for which **[[CL:Functions:adjustable-array-p]]** definitely returns //[[CL:Glossary:false]]//. There is no specified way to create an //[[CL:Glossary:array]]// that is not a //[[CL:Glossary:simple array]]//. \issue{UNINITIALIZED-ELEMENTS:CONSEQUENCES-UNDEFINED} \issue{UNINITIALIZED-ELEMENTS:CONSEQUENCES-UNDEFINED} \issue{ADJUST-ARRAY-NOT-ADJUSTABLE:IMPLICIT-COPY} \issue{ADJUST-ARRAY-NOT-ADJUSTABLE:IMPLICIT-COPY}