Arrays

An array is an object with components arranged according to a rectilinear coordinate system. One-dimensional arrays are called vectors.

A general array may contain any Lisp object, whereas a specialized array contains elements restricted to a specified type. Vectors whose elements are restricted to type string-char are called strings. Vectors whose elements are restricted to type bit are called bit-vectors.

Create

make-array dims &key type initial-element initial-contents adjustable fill-pointer displaced-to displaced-index-offset ⇒ new-array

(make-array '(2 3)) ;⇒ #2A((0 0 0) (0 0 0))
(make-array 5 :fill-pointer 0 :adjustable t :element-type 'character) ;⇒ ""

adjust-array array new-dims &key type initial-element initial-contents fill-pointer displaced-to displaced-index-offset ⇒ adjusted-array

alexandria:copy-array array &key element-type fill-pointer adjustable ⇒ new-array

Returns an undisplaced copy of array, with same fill-pointer and adjustability as the original.

Select

aref array &rest subscripts ⇒ element

Access array elements. Related: svref —Access index of a simple vector.

(setf a (make-array '(2 2) :initial-contents '((1 2) (3 4))))
(aref a 1 1) ;⇒ 4
(setf (aref a 0 1) 99) ; a ⇒ #2A((1 99) (3 4))

row-major-aref array index ⇒ element

Considers array as a vector by viewing its elements in row-major order, and returns the element of that vector which is referred to by the given index.

array-row-major-index array subscripts* ⇒ index

Computes the position according to the row-major ordering of array for the element that is specified by subscripts, and returns the offset of the element in the computed position from the beginning of array.

array-dimensions array ⇒ dimensions

Returns a list of the dimensions of array. (If array is a vector with a fill pointer, that fill pointer is ignored.)

(array-dimensions (make-array 4))                 ;⇒ (4)
(array-dimensions (make-array '(2 3)))            ;⇒ (2 3)
(array-dimensions (make-array 4 :fill-pointer 2)) ;⇒ (4)

array-dimension array axis-number ⇒ dimension

Returns the axis-number dimension[1] of array. (Any fill pointer is ignored.)

(array-dimension (make-array 4) 0)      ;⇒ 4
(array-dimension (make-array '(2 3)) 1) ;⇒ 3

array-total-size array ⇒ size

Returns the array total size of the array.

(array-total-size (make-array 4))                 ;⇒ 4
(array-total-size (make-array 4 :fill-pointer 2)) ;⇒ 4
(array-total-size (make-array 0))                 ;⇒ 0
(array-total-size (make-array '(4 2)))            ;⇒ 8
(array-total-size (make-array '(4 0)))            ;⇒ 0
(array-total-size (make-array '()))               ;⇒ 1

array-rank array ⇒ rank

Returns the number of dimensions of array.

(array-rank (make-array '()))    ;⇒ 0
(array-rank (make-array 4))      ;⇒ 1
(array-rank (make-array '(4)))   ;⇒ 1
(array-rank (make-array '(2 3))) ;⇒ 2

array-displacement array ⇒ displaced-to, displaced-index-offset

If the array is a displaced array, returns the values of the :displaced-to and :displaced-index-offset options for the array (see the functions make-array and adjust-array). If the array is not a displaced array, nil and 0 are returned.

array-rank-limit

Constant.

array-dimension-limit

Constant.

array-total-size-limit

Constant variable. The upper exclusive bound on the array total size of an array.

elt seq idx ⇒ element

Related: nth, nthcdr, car, cdr, firsttenth

(setf seq '(a b c))
(elt seq 1)             ;⇒ B
(setf (elt seq 1) "hi") ; seq ⇒ (A "hi" C)

alexandria:random-elt

Return a random element from a sequence.

length seq ⇒ n

(length '(a b c)) ;⇒ 3
(length "hello")  ;⇒ 5

find item seq &key from-end test test-not start end key ⇒ element

If the sequence seq contains an element satisfying test, then the leftmost such element is returned; otherwise nil is returned. Functional variants are find-if and find-if-not.

(find 3 '(1 2 3 4 5))                            ;⇒ 3
(find-if #'oddp '(1 2 3 4 5) :end 3 :from-end t) ;⇒ 3

position item seq &key from-end test test-not start end key ⇒ idx

Return the first index position of an item in the sequence, otherwise nil.

(position #\a "baobab" :from-end t)                         ;⇒ 4
(position-if #'oddp '((1) (2) (3) (4)) :start 1 :key #'car) ;⇒ 2

count item seq &key from-end start end key test test-not ⇒ n

The number of elements in the specified subsequence of seq. Functional variants are count-if and count-if-not.

(count 'a '(a b c a))      ;⇒ 2
(count-if #'oddp '(1 2 3)) ;⇒ 2

cl-utilities:extremum seq fn &key key (start 0) end ⇒ smallest-element

Returns first element of sequence if it were ordered by sort using the predicate fn. extrema is similar but returns a list of values since there may be more than one extremum determined by the predicate. n-most-extreme returns a list of n values of a sorted sequence. ref

(extremum '(1 2 9 7 3 2) #'>)         ;⇒ 9
(extrema '(1 2 9 7 3 2) #'>)          ;⇒ (9)
(n-most-extreme 3 '(1 2 9 7 3 2) #'>) ;⇒ (9 7 3)

subseq seq start &optional end ⇒ sub-seq

Returns the sub-sequence of seq specified by start and end.

(setf str "hello")
(subseq str 2 4) ;⇒ "ll"
(setf (subseq str 2 4) "ad") ; str ⇒ "heado"

search seq1 seq2 &key from-end test test-not key start1 start2 end1 end2 ⇒ idx

Searches sequence seq2 for a sub-sequence that matches seq1. Returns its index position.

(search '(c d) '(a b c d)) ;⇒ 2
(search "bar" "foobarbaz") ;⇒ 3

mismatch seq1 seq2 &key from-end test test-not key start1 start2 end1 end2 ⇒ idx

Return the index position where two sequences diverge.

(mismatch "foobarbaz" "foom") ;⇒ 3