General Sequences

Vectors (one dimensional arrays) and lists are generic sequences. A string is a sequence, since it is a vector of characters.

For the specification of result type in map, concatenate and coerce, use class name symbol, such as cons, string, integer-vector, float-vector, etc. without quotes, since the class object is bound to the symbol.

elt sequence pos [function]

elt is the most general function to get and put (in conjunction with setf) value at the specific position pos in sequence. Sequence may be a list, or a vector of arbitrary object, bit, char, integer, or float. Elt cannot be applied to a multi-dimensional array.

length sequence [function]

returns the length of sequence. For vectors, length finishes in constant time, but time proportional to the length is required for a list. Length never terminates if sequence is a circular list. Use list-length, instead. If sequence is an array with a fill-pointer, length returns the fill-pointer, not the entire size of the array entity. Use array-total-size to know the entire size of those arrays.

subseq sequence start [end] [function]

makes a copy of the subsequence from startth through (end-1)th inclusively out of sequence. end is defaulted to the length of sequence.

copy-seq sequence [function]

does shallow-copying of sequence, that is, only the top-level references in sequence are copied. Use copy-tree to copy a nested list, or copy-object for deep-copying of a sequence containing recursive references.

reverse sequence [function]

reverse the order of sequence and returns a new sequence of the same type as sequence.

nreverse sequence [function]

Nreverse is the destructive version of reverse. Nreverse does not allocate memory, while reverse does.

concatenate result-type sequence* [function]

concatenates all sequences. Each sequence may be of any sequence type. Unlike append, all the sequences including the last one are copied. Result-type should be a class such as cons, string, vector, float-vector etc.

coerce sequence result-type [function]

changes the type of sequence. For examples, (coerce '(a b c) vector) = #(a b c) and (coerce "ABC" cons) = (a b c). A new sequence of type result-type is created, and each element of sequence is copied to it. result-type should be one of vector, integer-vector, float-vector, bit-vector, string, cons or other user-defined classes inheriting one of these. Note that sequence is copied even if its type equals to result-type.

map result-type function seq &rest more-seqs [function]

function is applied to a list of arguments taken from seq and more-seqs orderly, and the result is accumulated in a sequence of type result-type.

fill sequence item &key (:start 0) (:end (length sequence)) [function]

fills item from startth through (end-1)th in sequence.

replace dest source &key :start1 :end1 :start2 :end2 [function]

elements in dest sequence indexed between start1 and end1 are replaced with elements in source indexed between start2 and end2. start1 and start2 are defaulted to zero, and end1 and end2 to the length of each sequence. If the one of subsequences is longer than the other, its end is truncated to match with the shorter subsequence.

sort sequence compare &optional key [function]

sequence is destructively sorted using Unix's quick-sort subroutine. key is not a keyword parameter. Be careful with the sorting of a sequence which have same elements. For example, (sort '(1 1) #'>) fails because comparisons between 1 and 1 in both direction fail. To avoid this problem, use functions like #'$>=$ or #'$<=$ for comparison.

merge result-type seq1 seq2 pred &key (key #'identity) [function]

two sequences seq1 and seq2 are merged to form a single sequence of result-type whose elements satisfy the comparison specified by pred.

merge-list list1 list2 pred key [function]

merges two lists. Unlike merge no general sequences are allowed for the arguments, but merge-list runs faster than merge.

Following functions consist of one basic function and its variants suffixed by -if and -if-not. The basic form takes at least the item and sequence arguments, and compares item with each element in the sequence, and do some processing, such as finding the index, counting the number of appearances, removing the item, etc. Variant forms take predicate and sequence arguments, applies the predicate to each element of sequence, and do something if the predicate returns non-nil (-if version), or nil (-if-not version).

position item seq &key :start :end :test :test-not :key (:count 1) [function]

finds countth appearance of item in seq and returns its index. The search begins from the startth element, ignoring elements before it. By default, the search is performed by eql, which can be altered by the test or test-not parameter.

position-if predicate seq &key :start :end :key [function]

position-if-not predicate seq &key :start :end :key [function]

find item seq &key :start :end :test :test-not :key (:count 1) [function]

finds countth element between the startth element and the endth element in seq. The element found, which is eql to item if no test or test-not other than #'eql is specified, is returned.

find-if predicate seq &key :start :end :key (:count 1) [function]

finds countth element in seq for which pred returns non nil.

find-if-not predicate seq &key :start :end :key [function]

count item seq &key :start :end :test :test-not :key [function]

counts the number of items which appear between the startth element and the endth element in seq.

count-if predicate seq &key :start :end :key [function]

count the number of elements in seq for which pred returns non nil.

count-if-not predicate seq &key :start :end :key [function]

remove item seq &key :start :end :test :test-not :key :count [function]

creates a new sequence which has eliminated count (defaulted to infinity) occurrences of of item(s) between the startth element and the endth element in seq. If you are sure that there is only one occurrence of item, count=1 should be specified to avoid meaningless scan over the whole sequence.

remove-if predicate seq &key :start :end :key :count [function]

remove-if-not predicate seq &key :start :end :key :count [function]

remove-duplicates seq &key :start :end :key :test :test-not :count [function]

removes duplicated items in seq and creates a new sequence.

delete item seq &key :start :end :test :test-not :key :count [function]

is same with remove except that delete modifies seq destructively and does not create a new sequence. If you are sure that there is only one occurrence of item, count=1 should be specified to avoid meaningless scan over the whole sequence.

delete-if predicate seq &key :start :end :key :count [function]

delete-if-not predicate seq &key :start :end :key :count [function]

count for removes and deletes is defaulted to 1,000,000. If you have a long sequence and you want to delete an element which appears only once, :count should be specified as 1.

substitute newitem olditem seq &key :start :end :test :test-not :key :count [function]

returns a new sequence which has substituted the count occurrence(s) of olditem in seq with newitem. By default, all the olditems are substituted.

substitute-if newitem predicate seq &key :start :end :key :count [function]

substitute-if-not newitem predicate seq &key :start :end :key :count [function]

nsubstitute newitem olditem seq &key :start :end :test :test-not :key :count [function]

substitute the count occurrences of olditem in seq with newitem destructively. By default, all the olditems are substituted.

nsubstitute-if newitem predicate seq &key :start :end :key :count [function]

nsubstitute-if-not newitem predicate seq &key :start :end :key :count [function]