# Lists

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``````

### rest

Also cdr

``````(rest '(:a :b :c)) ;⇒ (:B :C)
(cdr '(:a :b :c))  ;⇒ (:B :C)``````

### nth

Also first, second, third, … tenth.

### 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"

### 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

### atom object ⇒ boolean

Returns T if object is not a cons.

### 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]``````

### 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``