documentation: document make-array displaced arrays
Can ECL create displaced arrays to the different element type? (casting arrays) CLHS says, it's undefined behaviour: http://clhs.lisp.se/Body/f_mk_ar.htm . Additionally we have in the doc-string a keyword argument (static nil)
, but not in the code. If we still can create such continuous blocks of memory, then we should bring back this parameter (and document it). Having displaced arrays of different element type would be a potential efficiency gain.
(defun make-array (dimensions
&key (element-type t)
(initial-element nil initial-element-supplied-p)
(initial-contents nil initial-contents-supplied-p)
adjustable fill-pointer
displaced-to (displaced-index-offset 0))
"Args: (dimensions &key (element-type t) initial-element (initial-contents nil)
(adjustable nil) (fill-pointer nil) (displaced-to nil)
(displaced-index-offset 0) (static nil))
Creates an array of the specified DIMENSIONS. DIMENSIONS is a list of
non-negative integers each representing the length of the corresponding
dimension. It may be an integer for vectors, i.e., one-dimensional arrays.
ELEMENT-TYPE specifies the type of array elements. INITIAL-ELEMENT specifies
the initial value for all elements. Its default value depends on ELEMENT-
TYPE. INITIAL-CONTENTS specifies each element in terms of sequences.
ADJUSTABLE specifies whether or not the array is adjustable (see ADJUST-
ARRAY). FILL-POINTER is meaningful only for vectors. It specifies whether
the vector has fill-pointer or not, and if it has, the initial value of the
fill-pointer. Possible values are NIL (no fill-pointer), T (the length of the
vector), or an integer. See VECTOR-PUSH and VECTOR-POP. DISPLACED-TO, if
non-NIL, must be an array and specifies that the new array is displaced to the
given array. DISPLACED-INDEX-OFFSET is meaningful only when DISPLACED-TO is
non-NIL and specifies that the reference to the I-th element of the new array
in raw-major indexing is actually the reference to the (I + DISPLACED-INDEX-
OFFSET)th element of the given array.If the STATIC argument is supplied
with a non-nil value, then the body of the array is allocated as a
contiguous block."
(let ((x (sys:make-pure-array element-type dimensions adjustable
fill-pointer displaced-to displaced-index-offset)))
(declare (array x))
(cond (initial-element-supplied-p
(when initial-contents-supplied-p
(error "MAKE-ARRAY: Cannot supply both :INITIAL-ELEMENT and :INITIAL-CONTENTS"))
(fill-array-with-elt x initial-element 0 nil))
(initial-contents-supplied-p
(fill-array-with-seq x initial-contents))
(t
x))))