Simple Sequence Functions

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

[Function] elt sequence index

This returns the element of sequence speciﬁed by index, which must be a non-negative integer less than the length of the sequence as returned by length. The ﬁrst element of a sequence has index 0.

(Note that elt observes the ﬁll pointer in those vectors that have ﬁll pointers. The array-speciﬁc function aref may be used to access vector elements that are beyond the vector’s ﬁll pointer.)

setf may be used with elt to destructively replace a sequence element with a new value.

[Function] subseq sequence start &optional end

This returns the subsequence of sequence speciﬁed by start and end. subseq always allocates a new sequence for a result; it never shares storage with an old sequence. The result subsequence is always of the same type as the argument sequence.

setf may be used with subseq to destructively replace a subsequence with a sequence of new values; see also replace.

[Function] copy-seq sequence

A copy is made of the argument sequence; the result is equalp to the argument but not eq to it.

(copy-seq x) ≡ (subseq x 0)

but the name copy-seq is more perspicuous when applicable.

[Function] length sequence

The number of elements in sequence is returned as a non-negative integer. If the sequence is a vector with a ﬁll pointer, the “active length” as speciﬁed by the ﬁll pointer is returned (see section 17.5).

[Function] reverse sequence

The result is a new sequence of the same kind as sequence, containing the same elements but in reverse order. The argument is not modiﬁed.

[Function] nreverse sequence

The result is a sequence containing the same elements as sequence but in reverse order. The argument may be destroyed and re-used to produce the result. The result may or may not be eq to the argument, so it is usually wise to say something like (setq x (nreverse x)), because simply (nreverse x) is not guaranteed to leave a reversed value in x.

X3J13 voted in March 1989 to clarify the permissible side eﬀects of certain operations. When the sequence is a list, nreverse is permitted to perform a setf on any part, car or cdr, of the top-level list structure of that list. When the sequence is an array, nreverse is permitted to re-order the elements of the given array in order to produce the resulting array.

[Function] make-sequence type size &key :initial-element

This returns a sequence of type type and of length size, each of whose elements has been initialized to the :initial-element argument. If speciﬁed, the :initial-element argument must be an object that can be an element of a sequence of type type. For example:

(make-sequence ’(vector double-ﬂoat) 100 :initial-element 1d0)

If an :initial-element argument is not speciﬁed, then the sequence will be initialized in an implementation-dependent way.

X3J13 voted in January 1989 to clarify that the type argument must be a type speciﬁer, and the size argument must be a non-negative integer less than the value of array-dimension-limit.

X3J13 voted in June 1989 to specify that make-sequence should signal an error if the sequence type speciﬁes the number of elements and the size argument is diﬀerent.

X3J13 voted in March 1989 to specify that if type is string, the result is the same as if make-string had been called with the same size and :initial-element arguments.

14.1 Simple Sequence Functions