Data Types
7. Symbols and Keywords
9.2 Basic Array Functions
seL provides the following basic operations for arrays:
Creates and returns an array.
make-array
aref Returns the specified element of the array.
August 1986
setf When used with aref, stores a value into the specified array element.
Iocf When used with aref, returns a locative pointer to the specified element of the array.
These constants contain implementation-specific limits on arrays:
array-rank-limit A constant that represents the upper exclusive bound on the rank of an array; the value is 8.
array-dimension~limit
August 1986 Data Types
A constant that represents the upper exclusive bound on each dimension of an array; the value is 134217728.
array-total-size-limit
A constant that represents the upper exclusive bound on the total number of elements in an array; the value is 134217728.
array-Ieader-Iength-limit
A constant that represents the upper exclusive bound on the length of an array leader; the value is 1024.
Zetalisp provides the following basic operations for arrays:
zl:make-array zl:aset
Creates and returns an array.
Stores a value into the specified array element. Note that setf of aref is preferred.
zl:aloc Returns a locative pointer to the specified element of the array.
Note that locf of aref is preferred.
For summaries of additional array operations: See the section "Common Operations on Arrays", page 177.
9.3 Creating Arrays
Use make-array to create new arrays.
make-array dimensions &key <element-type t) initial-element Function initial-contents adjustable fill-pointer
displaced-to displaced-index-offset displaced-conformally area leader-list leader-length named-structure-symbol
make-array creates and returns a new array. dimensions is the only required argument. dimensions is a list of integers that are the dimensions of the array; the length of the list is the dimensionality, or rank. of the array.
;; Create a two-dimensional array
(make-array '(3 4) :element-type 'string-char)
For convenience when making a one-dimensional array, the single
dimension can be provided as an integer rather than a list of one integer.
Symbo/ics Common Lisp: Language Concepts August 1986
;; Create a one-dimensional array of five elements.
(make-array 5)
The initialization of the elements of the array depends on the element type.
By default the array is a general array, the elements can be any type of Lisp object, and each element of the array is initially nil. However, if the :element-type option is supplied, and it constrains the array elements to being integers or characters, the elements of the array are initially 0 or characters whose character code is 0 and style is [nil.nil.nil]. You can specify initial values for the elements by using the :initial-contents or :initial-element options.
Several of the keyword options are enhancements to Common Lisp. These include: :displaced-conformally, :area, : leader-list, :leader-Iength, and :named-structure-symbol.
See the section "Keyword Options For make-array", page 160.
See the section "Examples Of make-array", page 163.
9.3.1 Keyword Options For make-array
The keyword options for make-array can be any of the following:
: element-type
Enables you to specify the type of Lisp object allowed as elements of the array. The value should be a symbolic name of a type. The default type is t, which yields a general array that can contain elements of any type. For a list of allowed array types: See the section "Common Lisp Array Element Types", page 163.
The initialization of the elements of the array depends on the element type.
If the array is of a type whose elements can only be integers or characters, the elements of the array are initially 0 or characters whose character code is 0 and style is [nil.nil.nil]. Otherwise, every element is initially nil.
To create a string, the :element-type option should be specified as string-char or character. Alternatively, you could use make-string
instead of make-array. Note that if :element-type is string, this creates a general array, just as if :element-type were t. This is because the
Symbolics computer does not have specialized arrays that hold just strings.
See the section "Strings", page 221.
: initial-element
Initializes each element in the array to the supplied value. The value must be of the type specified by the :element-type argument, if that keyword was supplied. Example:
August 1986 Data Types
(make-array 5 :element-type 'string-char :initial-element #\a)
=> HaaaaaH : initial-contents
Initializes the contents of the array. The value is a nested structure of sequences with values that correspond to the elements of the array.
Example:
(make-array '(2 3 4) :initial-contents
, «(a b c d) (1 2 3 4) (m n 0 p))
«e f g h) (5 6 7 8) (q r s t))))
=> #<ART-Q-2-3-4 3416617B>
:adjustable
If not nil, specifies that the array's size can be altered dynamically after it has been created. The default is nil. The Genera implementation makes most arrays adjustable whether or not you use this option.
The following functions can be used to modify the size of an existing array:
adjust-array Changes the size of an array.
zl:adjust-array-size
zl:array-grow : fill-pointer
Resizes or reshapes the fIrst dimension of an array.
Note that adjust-array is preferred.
Creates a new array of the same type as the specifIed array, and forwards the old array to the new.
Specifies that the array should have a fIll pointer and initializes the fill pointer to the value following the keyword. Note that :fill-pointer can only be used for one-dimensional arrays. Use this instead of :leader-length or :leader-list when you are using the leader only for a fill pointer. This argument defaults to nil. Fill pointers are discussed elsewhere: See the section "Array Leaders", page 164.
:displaced-to
Specifies that the array will be a displaced array, if the value is not nil. If the value is a fumum or a locative, make-array creates a regular displaced array that refers to the specified section of virtual address space. If the value is an array, make-array creates an indirect array. See the section
"Displaced Arrays", page 166. See the section "Indirect Arrays", page 166.
162
Symbolics Common Lisp: Language Concepts August 1986
:displaced-index-offset
If this is present, the value of the :displaced-to option should be an array, and the value should be a nonnegative integer; it is made to be the index-offset of the created indirect or displaced array. See the section "Indirect Arrays", page 166.
The function array-row-major-index can aid in constructing the desired value for multidimensional arrays.
:displaced-conformally
:area
Can be used with the :displaced-to option. If the value is t and make-array is creating an indirect array, the array uses conformal indirection. See the section "Conformal Indirection", page 168.
The value specifies in which area the array should be created. It should be either an area number (an integer), or nil to mean the default area. This argument defaults to nil. See the section "Areas" in Internals, Processes, and Storage Management.
:leader-Iength
The value should be an integer. The array has a leader with that many elements. The elements of the leader are initialized to nil unless the :leader-list, :fill-pointer, or :named-structure-symbol option is given.
The leader-length must be less than array-Ieader-Iength-limit.
: leader-list
The value should be a list. Call the number of elements in the list n. The first n elements of the leader are initialized from successive elements of this list. If the :leader-Iength option is not specified, then the length of the leader is n. If the :leader-length option is given, and its value is greater than n, then the extra leader elements are initialized to nil. If its value is less than n, an error is signalled. The leader elements are filled in forward order; that is, the car of the list is stored in leader element 0, the cadr in element 1, and so on. :fill-pointer overrides element 0, and :named-structure-symbol overrides element 1.
:named-structure-symbol
If this is not nil, it is a symbol to be stored in the named-structure cell of the array. The array is tagged as a named structure. See the section
"Named Structures", page 343. If the array has a leader, then this symbol is stored in leader element 1 regardless of the value of the :leader-list option. If the array does not have a leader, then this symbol is stored in array element 0.
August 1986 Data Types
9.3.2 Common Lisp Array Element Types
This section lists the types that can be given as the :element-type option for make-array.
Element Type t
Contents of Array
~y Lisp object
(unsigned-byte n)n is 1, 2, 4, 8 or 16. The array elements are positive integers limited in size to the number of bits indicated by n. Storing a larger fumUIn, or a negative one, truncates it to the specified number of bits. Array elements are packed into 32-bit words .•
If n is given as 1 and the array is one-dimensional, this is a bit-vector.
ilXllUln
character string-char
boolean
~y fumum, positive or negative.
~y character. If the array is one-dimensional, it is a fat string.
Characters in the Symbolics standard character set of character style NIL. NIL. NIL and bits field of zero. Array elements are packed four per word. If the array is one-dimensional, it is a thin string.
t or nil. Storing anything non-nil converts it to t. Elements are packed 32 per word.
9.3.3 Examples Of make-array
This section presents some examples of using make-array.
;; Create a one-dimensional array of five elements (make-array 5)
;; Create a two-dimensional array (make-array '(3 4»
;; Create an array with a three-element leader (make-array 5 :leader-length 3)
Symbollcs Common Lisp: Language Concepts
;; Create an array of fixnums with a leader,
;; providing initial values for the leader elements (setq a (make-array 1BB :element-type 'fixnum
:leader-list '(t nil))) (array-leader a B) => T
(array-leader a 1) => NIL
;; Create a named-structure with five leader
;; elements, initializing some of them (setq b (make-array 2B :leader-length 5
:leader-list '(B nil foo) :named-structure-symbol 'bar)) (array-leader b B) => B
(array-leader b 1) => BAR (array-leader b 2) =>
Foa
(array-leader b 3) => NIL (array-leader b 4) => NIL
;; Create a string with a fill pointer (make-array 1B :element-type 'string-char
:fill-pointer 5) => UN
;; Create a fat-string
(make-array 2 :element-type 'character :initial-element #\control-c)