Star Sapphire Common LISP Home

Download Star Saphire
Index

14. SEQUENCES

This chapter contains the following sections:

14.1 Simple Sequence Functions

14.2 Concatenating, Mapping, and Reducing Sequences

14.3 Modifying Sequences

14.4 Searching Sequences for Items

14.5 Sorting and Merging

 

The type sequence encompasses both lists and vectors (one-dimensional arrays). While these are different data structures with different structural properties leading to different algorithmic uses, they do have a common property: each contains an ordered set of elements. Note that nil is considered to be a sequence of length zero.

There are some operations that are useful on both lists and arrays because they deal with ordered sets of elements. One may count the number of elements, reverse the ordering, extract a subsequence, and so on.

If the operation requires testing sequence elements according to some criterion, then the criterion may be specified in one of two ways. The basic operation accepts an item, and elements are tested for being eql to that item. (A test other than eql can be specified by the :test or :test-not keyword. It is an error to use both of these keywords in the same call.) The variants formed by adding -if and -if-not to the basic operation name do not take an item, but instead a one-argument predicate, and elements are tested for satisfying or not satisfying the predicate.

Many operations allow the specification of a subsequence to be operated upon. Such operations have keyword arguments called :start and :end. These arguments should be integer indices into the sequence, with start<end (it is an error if start>end). They indicate the subsequence starting with and including element start and up to but excluding element end. The length of the subsequence is therefore end-start. If start is omitted, it defaults to zero; and if end is omitted or nil, it defaults to the length of the sequence. Therefore if both start and end are omitted the entire sequence is processed by default. For the most part, subsequence specification is permitted purely for the sake of efficiency; one can simply call subseq instead to extract the subsequence before operating on it. Note, however, that operations that calculate indices return indices into the original sequence, not into the subsequence.

If two sequences are involved, then the keyword arguments :start1, :end1, :start2, and :end2 are used to specify separate subsequences for each sequence.

For some functions, the keyword argument :count is used to specify how many occurrences of the item should be affected. If this is nil or is not supplied, all matching items are affected.

In the following function descriptions, an element x of a sequence "satisfies the test" if any of the following holds:

A basic function was called, testfn was specified by the keyword :test, and (funcall testfn item (keyfn x)) is true.

A basic function was called, testfn was specified by the keyword :test-not, and (funcall testfn item (keyfn x)) is false.

An -if function was called, and (funcall predicate (keyfn x)) is true.

An -if-not function was called, and (funcall predicate (keyfn x)) is false.

In each case keyfn is the value of the :key keyword argument (the default being the identity function).

In the following function descriptions, two elements x and y taken from sequences match if either of the following holds:

testfn was specified by the keyword :test, and (funcall testfn (keyfn x) (keyfn y)) is true.

testfn was specified by the keyword :test-not, and (funcall testfn (keyfn x) (keyfn y)) is false.

You may depend on the order in which arguments are given to testfn; this permits the use of non-commutative test functions in a predictable manner. The order of the arguments to testfn corresponds to the order in which those arguments (or the sequences containing those arguments) were given to the sequence function in question. If a sequence function gives two elements from the same sequence argument to testfn, they are given in the same order in which they appear in the sequence.

Whenever a sequence function must construct and return a new vector, it always returns a simple vector (see section 2.5). Similarly, any strings constructed will be simple strings.

 

14.1 Simple Sequence Functions

Most of the following functions perform simple operations on a single sequence; make-sequence constructs a new sequence.

elt

subseq

copy-seq

length

reverse

nreverse

make-sequence

 

14.2 Concatenating, Mapping, and Reducing Sequences

The functions in this section each operate on an arbitrary number of sequence except for reduce, which is included here because of its conceptual relationship to the mapping functions.

concatenate

map

some

every

notany

notevery

reduce

 

14.3 Modifying Sequences

Each of these functions alters the contents of a sequence or produces an altered copy of a given sequence.

fill

replace

remove

remove-if

remove-if-not

delete

delete-if

delete-if-not

 

14.4 Searching Sequences for Items

Each of these functions searches a sequence to locate one or more elements satisfying some test.

find

find-if

find-if-not

position

position-if

position-if-not

count

count-if

count-if-not

 

14.5 Sorting and Merging

These functions may destructively modify argument sequences in order to put a sequence into sorted order or to merge two already sorted sequences.

sort

merge