;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Accessing Array Elements =Text: 3ACCESSING ARRAY ELEMENTS aref* 1array* &rest 1subscripts* Returns the element of 1array* selected by the 1subscripts*. The 1subscripts* must be fixnums and their number must match the rank of 1array*. 3cli:aref* 1array* &rest 1subscripts* The Common Lisp version of 2aref* differs from the traditional one in that it returns a character object rather than an integer when 1array* is a string. See 4(CHARSTR-0)Characters and Strings* for a discussion of the data type of string elements. 3aset* 1x* 1array* &rest 1subscripts* Stores 1x* into the element of 1array* selected by the 1subscripts*. The 1subscripts* must be fixnums and their number must match the rank of 1array*. The returned value is 1x*. 2aset* is equivalent to 3(setf (aref 1array* 1subscripts*...) 1x*) aloc* 1array* &rest 1subscripts* Returns a locative pointer to the element-cell of 1array* selected by the 1subscripts*. The 1subscripts* must be fixnums and their number must match the rank of 1array*. The array must not be a numeric array, since locatives to the middle of a numeric array are not allowed. See the explanation of locatives in 4(LOCATIVES-0)Locatives*. It is equivalent, and preferable, to write 3(locf (aref 1array* 1subscripts*...)) ar-1-force* 1array* 1i* 3as-1-force* 1value* 1array* 1i* 3ap-1-force* 1array* 1i* These functions access an array with a single subscript regardless of how many dimensions the array has. They may be useful for manipulating arrays of varying rank, as an alternative to maintaining and updating lists of subscripts or to creating one-dimensional indirect arrays. 2ar-1-force* refers to an element, 2as-1-force* sets an element, and 2ap-1-force* returns a locative to the element's cell. In using these functions, you must pay attention to the order in which the array elements are actually stored. See 4(ARRAYS-3)Order of Array Elements*. 3array-row-major-index* 1array* &rest 1indices* Calculates the cumulative index in 1array* of the element at indices 1indices*. 3(ar-1-force 1array** 3 (array-row-major-index 1array* 1indices*...))* is equivalent to 2(aref 1array* 1indices*...)*. 3array-leader* 1array* 1i* 1array* should be an array with a leader, and 1i* should be a fixnum. This returns the 1i*th element of 1array*'s leader. This is analogous to 2aref*. 3store-array-leader* 1x* 1array* 1i* 1array* should be an array with a leader, and 1i* should be a fixnum. 1x* may be any object. 1x* is stored in the 1i*th element of 1array*'s leader. 2store-array-leader* returns 1x*. This is analogous to 2aset*. It is equivalent, and preferable, to write 3(setf (array-leader 1array* 1i*) 1x*) ap-leader* 1array* 1i* Is equivalent to 3(locf (array-leader 1array* 1i*))* The following array accessing functions generally need not be used by users. 3ar-1* 1array* 1i* 3ar-2* 1array* 1i* 1j* 3ar-3* 1array* 1i* 1j* 1k* 3as-1* 1x* 1array* 1i* 3as-2* 1x* 1array* 1i* 1j* 3as-3* 1x* 1array* 1i* 1j* 1k* 3ap-1* 1array* 1i* 3ap-2* 1array* 1i* 1j* 3ap-3* 1array* 1i* 1j* 1k* These are obsolete versions of 2aref*, 2aset* and 2aloc* that only work for one-, two-, or three-dimensional arrays, respectively. The compiler turns 2aref* into 2ar-1*, 2ar-2*, etc. according to the number of subscripts specified, turns 2aset* into 2as-1*, 2as-2*, etc., and turns 2aloc* into 2ap-1*, 2ap-2*, etc. For arrays with more than three dimensions the compiler uses the slightly less efficient form since the special routines only exist for one, two and three dimensions. There is no reason for any program to call 2ar-1*, 2as-1*, 2ar-2*, etc. explicitly; they are documented because there used to be such a reason, and many old programs use these functions. New programs should use 2aref*, 2aset*, and 2aloc*. A related function, provided only for Maclisp compatibility, is 2arraycall* (4(ARRAYS-3)Maclisp Array Compatibility*). 3svref* 1vector* 1index* A special accessing function defined by Common Lisp to work only on simple general vectors: vectors with no fill pointer, not displaced, and not adjustable (see 4(ARRAYS-1)Constructing Arrays*). Some other Lisp systems open code 2svref* so that it is faster than 2aref*, but on the Lisp Machine 2svref* is a synonym for 2cli:aref*. 3bit* 1bit-vector* 1index* 3sbit* 1bit-vector* 1index* 3char* 1bit-vector* 1index* 3schar* 1bit-vector* 1index* Special accessing functions defined to work only on bit vectors, only on simple bit vectors, only on strings, and only on simple strings, respectively. On the Lisp Machine they are all synonyms for 2cli:aref*. Here are the conditions signaled for various errors in accessing arrays. 3sys:array-has-no-leader* (3sys:bad-array-mixin* 3error*) 1Condition* This is signaled on a reference to the leader of an array that doesn't have one. The condition instance supports the 2:array* operation, which returns the array that was used. The 2:new-array* proceed-type is provided. 3sys:bad-array-mixin* 1Condition Flavor* This mixin is used in the conditions signaled by several kinds of problems pertaining to arrays. It defines prompting for the 2:new-array* proceed type. 3sys:array-wrong-number-of-dimensions* (3sys:bad-array-mixin* 3error*) 1Condition* This is signaled when an array is referenced (either reading or writing) with the wrong number of subscripts; for example, 2(aref "foo" 1 2)*. The 2:array* operation on the condition instance returns the array that was used. The 2:subscripts-used* operation returns the list of subscripts used. The 2:new-array* proceed type is provided. It expects one argument, an array to use instead of the original one. 3sys:subscript-out-of-bounds* (3error*) 1Condition* This is signaled when there are the right number of subscripts but their values specify an element that falls outside the bounds of the array. The same condition is used by 2sys:%instance-ref*, etc., when the index is out of bounds in the instance. The condition instance supports the operations 2:object* and 2:subscripts-used*, which return the array or instance and the list of subscripts. The 2:new-subscript* proceed type is provided. It takes an appropriate number of subscripts as arguments. You should provide as many subscripts as there originally were. 3sys:number-array-not-allowed* (3sys:bad-array-mixin* 3error*) 1Condition* This is signaled by an attempt to use 2aloc* on a numeric array such as an 2art-1b* array or a string. The 2:array* operation and the 2:new-array* proceed type are available. =Node: Getting Information About an Array =Text: 3GETTING INFORMATION ABOUT AN ARRAY array-type* 1array* Returns the symbolic type of 1array*. Example: 3(setq a (make-array '(3 5)))* 3(array-type a) => art-q array-element-type* 1array* Returns a type specifier which describes what elements could be stored in 1array* (see 4(PRIMOBJTYPE-0)Primitive Object Types* for more about type specifiers). Thus, if 1array* is a string, the value is 2string-char*. If 1array* is an 2art-1b* array, the value is 2bit*. If 1array* is an 2art-2b* array, the value is 2(mod 4)*. If array is an 2art-q* array, the value is 2t* (the type to which all objects belong). 3array-length* 1array* 3array-total-size* 1array* 1array* may be any array. This returns the total number of elements in 1array*. For a one-dimensional array, this is one greater than the maximum allowable subscript. (But if fill pointers are being used, you may want to use 2array-active-length*.) Example: 3(array-length (make-array 3)) => 3* 3(array-length (make-array '(3 5))) => 15* 2array-total-size* is the Common Lisp name of this function. 3array-active-length* 1array* If 1array* does not have a fill pointer, then this returns whatever 2(array-length 1array*)* would have. If 1array* does have a fill pointer, 2array-active-length* returns it. See the general explanation of the use of fill pointers on 4(ARRAYS-1)Extra Features of Arrays*. 3array-rank* 1array* Returns the number of dimensions of 1array*. Example: 3(array-rank (make-array '(3 5))) => 2 array-dimension* 1array* 1n* Returns the length of dimension 1n* of 1array*. Examples: 3(setq a (make-array '(2 3)))* 3(array-dimension a 0) => 2* 3(array-dimension a 1) => 3 array-dimension-n* 1n* 1array* 1array* may be any kind of array, and 1n* should be a fixnum. If 1n* is between 1 and the rank of 1array*, this returns the 1n*th dimension of 1array*. If 1n* is 0, this returns the length of the leader of 1array*; if 1array* has no leader it returns 2nil*. If 1n* is any other value, this returns 2nil*. This function is obsolete; use 2array-dimension-n*, whose calling sequence is cleaner. Examples: 3(setq a (make-array '(3 5) :leader-length 7))* 3(array-dimension-n 1 a) => 3* 3(array-dimension-n 2 a) => 5* 3(array-dimension-n 3 a) => nil* 3(array-dimension-n 0 a) => 7 array-dimensions* 1array* Returns a list whose elements are the dimensions of 1array*. Example: 3(setq a (make-array '(3 5)))* 3(array-dimensions a) => (3 5)* Note: the list returned by 2(array-dimensions 1x*)* is equal to the cdr of the list returned by 2(arraydims 1x*)*. 3arraydims* 1array* Returns a list whose first element is the symbolic name of the type of 1array*, and whose remaining elements are its dimensions. 1array* may be any array; it also may be a symbol whose function cell contains an array, for Maclisp compatibility (see 4(ARRAYS-3)Maclisp Array Compatibility*). Example: 3(setq a (make-array '(3 5)))* 3(arraydims a) => (art-q 3 5)* 2arraydims* is for Maclisp compatibility only. 3array-in-bounds-p* 1array* &rest 1subscripts* 2t* if 1subscripts* is a legal set of subscripts for 1array*, otherwise 2nil*. 3array-displaced-p* 1array* 2t* if 1array* is any kind of displaced array (including an indirect array), otherwise 2nil*. 1array* may be any kind of array. 3array-indirect-p* 1array* 2t* if 1array* is an indirect array, otherwise 2nil*. 1array* may be any kind of array. 3array-indexed-p* 1array* 2t* if 1array* is an indirect array with an index-offset, otherwise 2nil*. 1array* may be any kind of array. 3array-index-offset* 1array* Returns the index offset of 1array* if it is an indirect array which has an index offset. Otherwise it returns 2nil*. 1array* may be any kind of array. 3array-has-fill-pointer-p* 1array* 2t* if array has a fill pointer. It must have a leader and leader element 0 must be an integer. While array leaders are not standard Common Lisp, fill pointers are, and so is this function. 3array-has-leader-p* 1array* 2t* if 1array* has a leader, otherwise 2nil*. 3array-leader-length* 1array* Returns the length of 1array*'s leader if it has one, or 2nil* if it does not. 3adjustable-array-p* 1array* According to Common Lisp, returns 2t* if 1array*'s size may be adjusted with 2adjust-array* (see below). On the Lisp Machine, this function always returns 2t*. =Node: Changing the Size of an Array =Text: 3CHANGING THE SIZE OF AN ARRAY adjust-array* 1array* 1new-dimensions* &key 1element-type* 1initial-element* 1initial-contents* 1fill-pointer* 1displaced-to* 1displaced-index-offset* Modifies various aspects of an array. 1array* is modified in place if that is possible; otherwise, a new array is created and 1array* is forwarded to it. In either case, 1array* is returned. The arguments have the same names as arguments to 2make-array*, and signify approximately the same thing. However: 1element-type* is just an error check. 2adjust-array* cannot change the array type. If the array type of 1array* is not what 1element-type* would imply, you get an error. If 1displaced-to* is specified, the new array is displaced as specified by 1displaced-to* and 1displaced-index-offset*. If 1array* itself was already displaced, it is modified in place provided that either 1array* used to have an index offset and is supposed to continue to have one, or 1array* had no index offset and is not supposed to have one. Otherwise, if 1initial-contents* was specified, it is used to set all the contents of the array. The old contents of 1array* are irrelevant. Otherwise, each element of 1array* is copied forward into the new array to the slot with the same indices, if there is one. Any new slots whose indices were out of range in 1array* are initialized to 1initial-element*, or to 2nil* or 0 if 1initial-element* was not specified. 1fill-pointer*, if specified, is used to set the fill pointer of the array. Aside from this, the result has a leader with the same contents as the original 1array*. 2adjust-array* is the only function in this section which is standard Common Lisp. According to Common Lisp, an array's dimensions can be adjusted only if the 2:adjustable* option was specified to 2make-array* with a non-2nil* value when the array was created (see 4(ARRAYS-1)Constructing Arrays*). The Lisp Machine does not distinguish adjustable and nonadjustable arrays; any array may be adjusted. 3adjust-array-size* 1array* 1new-size* If 1array* is a one-dimensional array, its size is changed to be 1new-size*. If 1array* has more than one dimension, its size (2array-length*) is changed to 1new-size* by changing only the last dimension. If 1array* is made smaller, the extra elements are lost; if 1array* is made bigger, the new elements are initialized in the same fashion as 2make-array* (see 4(ARRAYS-1)Constructing Arrays*) would initialize them: either to 2nil* or 0, depending on the type of array. Example: 3(setq a (make-array 5))* 3(aset 'foo a 4)* 3(aref a 4) => foo* 3(adjust-array-size a 2)* 3(aref a 4) => 2an error occurs** If the size of the array is being increased, 2adjust-array-size* may have to allocate a new array somewhere. In that case, it alters 1array* so that references to it will be made to the new array instead, by means of invisible pointers (see 2structure-forward*, 4(SUBPRIMITIVES-1)Forwarding*). 2adjust-array-size* returns the new array if it creates one, and otherwise it returns 1array*. Be careful to be consistent about using the returned result of 2adjust-array-size*, because you may end up holding two arrays which are not the same (i.e. not 2eq*), but which share the same contents. 3array-grow* 1array* &rest 1dimensions* Equivalent to 2(adjust-array 1array* 1dimensions*)*. This name is obsolete. 3si:change-indirect-array* 1array* 1type* 1dimlist* 1displaced-p* 1index-offset* Changes an indirect array 1array*'s type, size, or target pointed at. 1type* specifies the new array type, 1dimlist* its new dimensions, 1displaced-p* the target it should point to (an array, locative or fixnum), and 1index-offset* the new offset in the new target. 1array* is returned. =Node: Arrays Overlaid With Lists =Text: 3ARRAYS OVERLAID WITH LISTS* These functions manipulate 2art-q-list* arrays, which were introduced on 4(ARRAYS-1)Array Types*. 3g-l-p* 1array* 1array* should be an 2art-q-list* array. This returns a list which shares the storage of 1array*. Example: 3(setq a (make-array 4 :type 'art-q-list))* 3(aref a 0) => nil* 3(setq b (g-l-p a)) => (nil nil nil nil)* 3(rplaca b t)* 3b => (t nil nil nil)* 3(aref a 0) => t* 3(aset 30 a 2)* 3b => (t nil 30 nil)* 2g-l-p* stands for `get list pointer'. The following two functions work strangely, in the same way that 2store* does, and should not be used in new programs. 3get-list-pointer-into-array* 1array-ref* The argument 1array-ref* is ignored, but should be a reference to an 2art-q-list* array by applying the array to subscripts (rather than by 2aref*). This returns a list object which is a portion of the ``list'' of the array, beginning with the last element of the last array which has been called as a function. 3get-locative-pointer-into-array* 1array-ref* 2get-locative-pointer-into-array* is similar to 2get-list-pointer-into-array*, except that it returns a locative, and doesn't require the array to be 2art-q-list*. Use 2locf* of 2aref* in new programs. =Node: Adding to the End of an Array =Text: 3ADDING TO THE END OF AN ARRAY vector-push* 1x* 1array* 3array-push* 1array* 1x* 1array* must be a one-dimensional array which has a fill pointer and 1x* may be any object. 2vector-push* attempts to store 1x* in the element of the array designated by the fill pointer, and increase the fill pointer by one. If the fill pointer does not designate an element of the array (specifically, when it gets too big), it is unaffected and 2vector-push* returns 2nil*; otherwise, the two actions (storing and incrementing) happen uninterruptibly, and 2vector-push* returns the 1former* value of the fill pointer, i.e. the array index in which it stored 1x*. If the array is of type 2art-q-list*, an operation similar to 2nconc* has taken place, in that the element has been added to the list by changing the cdr of the formerly last element. The cdr-coding is updated to ensure this. 2array-push* is an old name for this function. 2vector-push* is preferable because it takes arguments in an order like 2push*. 3vector-push-extend* 1x* 1array* &optional 1extension* 3array-push-extend* 1array* 1x* &optional 1extension* 2vector-push-extend* is just like 2vector-push* except that if the fill pointer gets too large, the array grows to fit the new element; it never ``fails'' the way 2vector-push* does, and so never returns 2nil*. 1extension* is the number of elements to be added to the array if it needs to grow. It defaults to something reasonable, based on the size of the array. 2array-push-extend* differs only in the order of arguments, 3vector-pop* 1array* 3array-pop* 1array* 1array* must be a one-dimensional array which has a fill pointer. The fill pointer is decreased by one and the array element designated by the new value of the fill pointer is returned. If the new value does not designate any element of the array (specifically, if it had already reached zero), an error is caused. The two operations (decrementing and array referencing) happen uninterruptibly. If the array is of type 2art-q-list*, an operation similar to 2nbutlast* has taken place. The cdr-coding is updated to ensure this. The two names are synonymous. 3sys:fill-pointer-not-fixnum* (3sys:bad-array-mixin* 3error*) 1Condition* This is signaled when one of the functions in this section is used with an array whose leader element zero is not a fixnum. Most other array accessing operations simply assume that the array has no fill pointer in such a case, but these cannot be performed without a fill pointer. The 2:array* operation on the condition instance returns the array that was used. The 2:new-array* proceed type is supported, with one argument, an array.