Common Lisp the Language, 2nd Edition

Next: ConcatenatingMapping, and Up: Sequences Previous: Sequences

# 14.1. 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 specified by index, which must be a non-negative integer less than the length of the sequence as returned by `length`. The first element of a sequence has index `0`.

(Note that `elt` observes the fill pointer in those vectors that have fill pointers. The array-specific function `aref` may be used to access vector elements that are beyond the vector's fill 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 specified 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 fill pointer, the ``active length'' as specified by the fill 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 modified.

[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 (REMF-DESTRUCTION-UNSPECIFIED) to clarify the permissible side effects 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 specified, 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-float)
                   100
                   :initial-element 1d0)

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

X3J13 voted in January 1989 (ARGUMENTS-UNDERSPECIFIED) to clarify that the type argument must be a type specifier, and the size argument must be a non-negative integer less than the value of `array-dimension-limit`.

X3J13 voted in June 1989 (SEQUENCE-TYPE-LENGTH) to specify that `make-sequence` should signal an error if the sequence type specifies the number of elements and the size argument is different.

X3J13 voted in March 1989 (CHARACTER-PROPOSAL) 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.

Next: ConcatenatingMapping, and Up: Sequences Previous: Sequences