Vectors
A vector is a basic integer-indexed collection, a one-dimensional array. Vectors and lists are collectively considered to be sequences.
Create
vector &rest objects* ⇒ vector
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
svref simple-vector index ⇒ element
Accesses the element of simple-vector specified by index.
fill-pointer vector ⇒ fill-pointer
Accesses the fill pointer of vector.
(setf arr (make-array 8 :fill-pointer 4)) ;⇒ #(NIL NIL NIL NIL)
(fill-pointer arr) ;⇒ 4
(vector-push 'a arr)
(fill-pointer arr) ;⇒ 5aref 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))elt seq idx ⇒ element
Related: nth, nthcdr, car, cdr, first … tenth
(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") ;⇒ 5find 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) ;⇒ 3position 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) ;⇒ 2count 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)) ;⇒ 2cl-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") ;⇒ 3mismatch 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") ;⇒ 3Modify
vector-push new-element vector ⇒ index
(setf v (make-array 2 :fill-pointer 0)) ;⇒ #()
(vector-push 'a v) ;⇒ 0 [v ⇒ #(A)]
(vector-push 'b v) ;⇒ 1 [v ⇒ #(A B)]
(vector-push 'c v) ;⇒ NIL [v ⇒ #(A B)]vector-push-extend new-element vector [extension] ⇒ index
(setf v (make-array 2 :fill-pointer 0 :adjustable t) ;⇒ #()
(vector-push 'a v) ;⇒ 0 [v ⇒ #(A)]
(vector-push 'b v) ;⇒ 1 [v ⇒ #(A B)]
(vector-push-extend 'c v) ;⇒ 2 [v ⇒ #(A B C)]vector-pop
Decreases the fill pointer of vector by one, and retrieves the element of vector that is designated by the new fill pointer.
concatenate result-type &rest seqs… ⇒ result-seq
(concatenate 'list '(a b) '(c d)) ;⇒ (A B C D)
(concatenate 'string "hello" "world") ;⇒ "helloworld"cl-utilities:split-sequence delimiter seq &key count remove-empty-subseqs from-end start end test test-not key ⇒ list, idx
Splits sequence into a list of subsequences delimited by objects satisfying the test. Also returns the lenbth of the sequence idx. Functional variants are cl-utilities:split-sequence-if and cl-utilities:split-sequence-if-not.
(split-sequence #\Space "hello world") ;⇒ ("hello" "world"), 11
(split-sequence-if #'evenp '(1 1 2 1 3 4 1 3 5)) ;⇒ ((1 1) (1 3) (1 3 5)), 9fill seq item &key start end ⇒ seq
Destructively replaces the elements of seq bounded by :start and :end with item.
(fill '(a b c d) 'x :start 1 :end 3) ;⇒ (A X X D)replace seq1 seq2 &key start1 end1 start2 end2 ⇒ seq1
Destructively replaces the elements of se1 bounded by :start1 and :end1 with the elements of seq2 bounded by :start2 and :end2.
(replace "abcde" "98765" :start1 1 :end1 3 :start2 3) ;⇒ "a65de"To remove an element from a sequence at a given position:
(setf lst '(a b c d e))
(setf i (position 'b lst)) ;⇒ 1
(replace lst lst :start1 i :start2 (1+ i)) ;⇒ (A C D E E)
(butlast lst) ;⇒ (A C D E)substitute new old seq &key from-end test test-not start end count key
Functional variants are substitute-if, substitute-if-not. Destructive variants are nsubstitute, nsubstitute-if, and nsubstitute-if-not. subst performs substitutions throughout a tree.
(substitute 10 1 '(1 2 1 3 1 4)) ;⇒ (10 2 10 3 10 4)
(substitute-if 0 #'oddp '(1 2 3 4 5)) ;⇒ (0 2 0 4 0)remove item seq &key from-end test test-not start end count key ⇒ result-seq
Functional variants are remove-if and remove-if-not. The destructive variants are delete, delete-if, and delete-if-not. To remove in place, use alexandria:removef or alexandria:deletef.
(remove 4 '(1 2 4 1 3 4 5)) ;⇒ (1 2 1 3 5)
(remove-if #'oddp '(1 2 4 1 3 4 5)) ;⇒ (2 4 4)
(remove-if-not #'oddp '(1 2 1 3 4 5)) ;⇒ (1 1 3 5)remove-duplicates seq &key from-end test test-not start end key
Destructive variant is delete-duplicates.
(remove-duplicates '(1 2 1 2 3 1 2 3 4)) ;⇒ (1 2 3 4)Sort
Sort
reverse seq ⇒ reversed-seq
Reverse the order of elements in a sequence. The destructive version is nreverse. To save the result in place, use alexandria:reversef.
(reverse '(a b c d)) ;⇒ (D C B A)sort seq fn &key key ⇒ sorted-seq
The sequence is destructively sorted according to an order determined by the predicate fn. stable-sort guarantees equal elements stay in same order.
(sort '(3 1 4 2) (lambda (x y) (< x y))) ;⇒ (1 2 3 4)merge result-type seq1 seq2 fn &key key ⇒ result-seq
Destructively concatenates the two sequences and sorts the combined elements based on the predicate fn.
(merge 'list '(1 3 5) '(2 4 6) #'<) ;⇒ (1 2 3 4 5 6)alexandria:rotate seq &optional n ⇒ result-seq
Returns a sequence with elements rotated by n, defaulting to 1.
(rotate '(a b c)) ;⇒ (C A B)
(rotate '(a b c) -1) ;⇒ (B C A)alexandria:shuffle seq &key start end ⇒ result-seq
Returns a random permutation of a sequence bounded by :start and :end. The original sequence may be modified.
Predicates
some fn seq &rest seqs* ⇒ result
Returns the first non-nil value which is returned by an invocation of the predicate fn.
(some #'evenp '(1 2 3 4)) ;⇒ T
(some #'1+ '(10 20 30 40)) ;⇒ 11
(some #'numberp '(a b c)) ;⇒ NILevery fn seq &rest seqs* ⇒ boolean
Returns nil as soon as any invocation of the predicate fn returns nil.
(every #'numberp '(1 2 3 4)) ;⇒ T
(every #'evenp '(1 2 3 4)) ;⇒ NILnotevery fn seq &rest seqs* ⇒ boolean
Returns t as soon as any invocation of predicate fn returns nil.
(notevery #'numberp '(1 2 3 4)) ;⇒ NIL
(notevery #'evenp '(1 2 3 4)) ;⇒ Tnotany fn seq &rest seqs* ⇒ boolean
Returns nil as soon as any invocation of predicate fn returns t.
(notany #'numberp '(1 2 3 4)) ;⇒ NIL
(notany #'evenp '(1 2 3 4)) ;⇒ NILarrayp
vectorp
simple-vector-p
bit-vector-p
simple-bit-vector-p
adjustable-array-p
array-has-fill-pointer-p
array-in-bounds-p
Iteration
map result-type fn &rest seqs* ⇒ result
Applies the function to elements of each sequence in turn. The result sequence is as long as the shortest of the sequences.
(map 'list #'cons '(a b) '(c d)) ;⇒ ((A . C) (B . D))
(map 'vector #'(lambda (x) (* 2 x)) '(1 2 3)) ;⇒ #(2 4 6)map-into result-seq fn &rest seqs* ⇒ result-seq
Destructively modifies result-seq to contain the results of applying the function to each element in the argument seqs in turn.
(map-into '(a b c) #'oddp '(1 2 3 4 5 6)) ;⇒ (T NIL T)remove-if-not fn seq &key from-end start end count key ⇒ seq
Filter
(remove-if-not #'oddp '(0 1 2 3 4)) ;⇒ (1 3)
(remove-if-not (alexandria:disjoin #'zerop #'oddp) '(0 1 2 3 4)) ;⇒ (0 1 3)remove-if fn seq &key from-end start end count key ⇒ seq
(remove-if #'oddp '(0 1 2 3 4)) ;⇒ (0 2 4)
(remove-if (alexandria:disjoin #'zerop #'oddp) '(0 1 2 3 4)) ;⇒ (2 4)reduce fn seq &key key from-end start end initial-value ⇒ result
(reduce #'* '(1 2 3 4 5)) ;⇒ 120