Lists

PCL: List Processing

The type sequence encompasses both lists and vectors (one-dimensional arrays).

Create

cons x y ⇒ cons

(cons 1 2)      ;⇒ (1 . 2)
(cons 1 '(2 3)) ;⇒ (1 2 3)

list objects* ⇒ list

Returns a list containing objects.

(list 1 2 3 4)     ;⇒ (1 2 3 4)

list* objects* list ⇒ list

Returns a list containing objects with the last argument becoming the cdr of the last cons constructed.

(list* 'a 'b)      ;⇒ (A . B)
(list* 1 2 '(3 4)) ;⇒ (1 2 3 4)

make-list size &key initial-element ⇒ list

Returns a list of length size.

(make-list 3)                     ;⇒ (NIL NIL NIL)
(make-list 2 :initial-element 'a) ;⇒ (A A)

copy-list list ⇒ copy

Returns a copy of list. Only the list structure is copied; the elements of the resulting list are the same as the corresponding elements of the given list.

Select

first

Also car

(first '(:a :b :c)) ;⇒ :A
(car '(:a :b :c))   ;⇒ :A

nthcdr

(nthcdr 2 '(:a :b :c :d)) ;⇒ (:C :D)

last

(last '(:a :b :c :d))   ;⇒ (:D)
(last '(:a :b :c :d) 2) ;⇒ (:C :D)

butlast list &optional n ⇒ result-list

Returns a copy of list with the last n conses omitted, defaults to 1. The destructive vesion is nbutlast.

(butlast '(a b c d))   ;⇒ (A B C)
(butlast '(a b c d) 2) ;⇒ (A B)

ldiff list sublist ⇒ result-list

Returns the list difference, in a new list, whose elements of list appear before sublist. If sublist is not the tail of list, then return a copy of the entire list.

(setf list1 '(a b c d))
(setf list2 (last list1 2)) ;⇒ (C D)
(ldiff list1 list2)         ;⇒ (A B)

list-length list ⇒ length

Returns the length of list. If list is a circular list, return nil.

(list-length '(a b c d))   ;⇒ 4
(list-length '(a (b c) d)) ;⇒ 3

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")  ;⇒ 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

Modify

append lists* ⇒ list

Return a new list that is the concatenation of the arguments. The destructive version is nconc. To append in place, use alexandria:appendf.

(append '(a b) '() '(c d)) ;⇒ (A B C D)

revappend list tail ⇒ result-list

Constructs a copy of list with the elements in reverse order, then append tail. The destructive version is nreconc.

(revappend '(1 2 3) '(a b c)) ;⇒ (3 2 1 A B C)

push item list ⇒ new-place-value

Prepend item to the front of the list and store in place. pushnew will only add the item if it does not already exist in the list.

(setf lst '(a b c))
(cons 'd lst)       ;⇒ (D A B C) [lst ⇒ (A B C)]
(push 'd lst)       ;⇒ (D A B C) [lst ⇒ (D A B C)]

pop list ⇒ element

Returns the car of a list and store in place.

(setf lst '(a b c))
(car lst)           ;⇒ A [lst ⇒ (A B C)]
(pop lst)           ;⇒ A [lst ⇒ (B C)]

rplaca cons object ⇒ cons

Replaces the car of the cons with object. Modifies cons in-place.

(setf lst '(a b c)) 
(rplaca lst 'd)     ;⇒ (D B C)

rplacd cons object ⇒ cons

Replaces the cdr of the cons with object. Modifies cons in-place.

(setf lst '(a b c))
(rplacd lst '(d e)) ;⇒ (A D E)

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)), 9

fill 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

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

listp object ⇒ boolean

consp object ⇒ boolean

atom object ⇒ boolean

Returns T if object is not a cons.

null object ⇒ boolean

endp object ⇒ boolean

tailp x list = > boolean

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))  ;⇒ NIL

every 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))   ;⇒ NIL

notevery 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))   ;⇒ T

notany 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))   ;⇒ NIL

Iteration

dolist (var list [result]) form* ⇒ result*

Iterate over the elements of a list. Terminate loop immediately with return.

(dolist (x '(1 2 3 4))
  (print x))

(dolist (x '(1 2 3 4) (print 'done))
  (print x))

mapcar

Iterates over successive list elements and returns the accumlated results. mapc is similar except the results are not accumulated and the first list is returned.

(mapcar #'+ '(1 2) '(3 4)) ;⇒ (4 6)
(mapcar (alexandria:compose #'print #'1+) '(1 2 3)) ;⇒ (2 3 4) [prints 2,3,4]

maplist

mapcan

mapcon

mapc

mapl

alexandria:mappend fn &rest lists… ⇒ list

Zips up list components and returns a flattened list. fn must return a list.

(mappend #'list '(1 3) '(2 4)) ;⇒ ((1 2) (3 4)) ⇒ (1 2 3 4)

(flet ((zipper (x y) (list (+ x y))))
  (mappend #'zipper '(1 3) '(2 4))) ;⇒ ((+ 1 2) (+ 3 4)) ⇒ (3 7)

alexandria:map-product fn list &rest lists… ⇒ list

Results of calling fn with one argument per list for every combination.

(map-product #'list '(1 2) '(3 4) '(5 6))
  ;⇒ ((1 3 5) (1 3 6) (1 4 5) (1 4 6) (2 3 5) (2 3 6) (2 4 5) (2 4 6))

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