Strings

A string is a specialized vector (one-dimensional array) whose elements are characters.

Create

string x ⇒ string

Convert symbol, keyword, or character to a string.

(string :hello) ;⇒ "hello"

make-string size &key initial-element element-type ⇒ string

Return a simple-string of length size.

(make-string 10 :initial-element #\5) ;⇒ "5555555555"

parse-integer str &key start end radix junk-allowed ⇒ int, idx

Parses an integer in the specified :radix.

(parse-integer "24h" :junk-allowed t) ;⇒ 24, 2

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

char str idx ⇒ character

Specialized element accessor for type string. Is setfable.

(char "hello" 1) ;⇒ #\e
(elt "hello" 1)  ;⇒ #\e

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

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

string-trim chars str ⇒ new-str

Returns a substring of str, with all characters in chars stripped off the beginning and end.

(string-trim "abc" "abcaakaaakabcaaa") ;⇒ "kaaak"
(string-trim '(#\Space #\Tab #\Newline) " garbanzo beans ") ;⇒ "garbanzo beans"
(string-trim " (*)" " ( *three (silly) words* ) ") ;⇒ "three (silly) words"

string-left-trim chars str ⇒ new-str

(string-left-trim "abc" "labcabcabc") ;⇒ "labcabcabc"
(string-left-trim " (*)" " ( *three (silly) words* ) ") ;⇒ "three (silly) words* ) "

string-right-trim chars str ⇒ new-str

(string-right-trim " (*)" " ( *three (silly) words* ) ") ;⇒ " ( *three (silly) words"

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

Comparison

string= str1 str2 &key start1 end1 start2 end2 ⇒ boolean

Returns t if the given strings are of the same length and contain the same characters, otherwise return nil. Ignore differences in case using string-equal.

(string= "foo" "foo") ;⇒ T
(string= "foo" "Foo") ;⇒ NIL
(string= "abcd" "01234abcd9012" :start2 5 :end2 9) ;⇒ T
(string-equal "foo" "Foo") ;⇒ T

string/= str1 str2 &key start1 end1 start2 end2 ⇒ mismatch-idx

Returns t if the given strings are different, otherwise nil. Ignore differences in case using string-not-equal.

(string-not-equal "AAAA" "aaaA") ;⇒ NIL

string< str1 str2 &key start1 end1 start2 end2 ⇒ mismatch-idx

Returns t if str1 is less than str2, otherwise nil. Ignore differences in case using string-lessp.

(string< "aaaa" "aaab") ;⇒ 3
(string-lessp "012AAAA789" "01aaab6" :start1 3 :end1 7 :start2 2 :end2 6) ;⇒ 6

string> str1 str2 &key start1 end1 start2 end2 ⇒ mismatch-idx

Returns t if str1 is greater than str2, otherwise nil. Ignore differences in case using string-greaterp.

string<= str1 str2 &key start1 end1 start2 end2 ⇒ mismatch-idx

Returns t if str1 is less than or equal to str2, otherwise nil. Ignore differences in case using string-not-greaterp.

(string>= "aaaaa" "aaaa") ;⇒ 4
(string-not-greaterp "Abcde" "abcdE") ;⇒ 5

string>= str1 str2 &key start1 end1 start2 end2 ⇒ mismatch-idx

Returns t if str1 is greater than or equal to str2, otherwise nil. Ignore differences in case using string-not-lessp.

Predicates

stringp obj ⇒ boolean

Test if an object is a string.

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