Skip to main content

subseq

subseq Accessor

Syntax:

subseq sequence start &optional end → subsequence

(setf (subseq sequence start &optional end**)** new-subsequence**)**

Arguments and Values:

sequence—a proper sequence.

start, end—bounding index designators of sequence. The default for end is nil.

subsequence—a proper sequence.

new-subsequence—a proper sequence.

Description:

subseq creates a sequence that is a copy of the subsequence of sequence bounded by start and end.

Start specifies an offset into the original sequence and marks the beginning position of the subsequence. end marks the position following the last element of the subsequence.

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 sequence.

If sequence is a vector , the result is a fresh simple array of rank one that has the same actual array element type as sequence. If sequence is a list, the result is a fresh list.

setf may be used with subseq to destructively replace elements of a subsequence with elements taken from a sequence of new values. If the subsequence and the new sequence are not of equal

length, the shorter length determines the number of elements that are replaced. The remaining elements at the end of the longer sequence are not modified in the operation.

Examples:

(setq str "012345") → "012345" 
(subseq str 2) → "2345" 
(subseq str 3 5) → "34" 
(setf (subseq str 4) "abc") → "abc" 
str → "0123ab" 
(setf (subseq str 0 2) "A") → "A" 
str → "A123ab"

Exceptional Situations:

Should be prepared to signal an error of type type-error if sequence is not a proper sequence. Should be prepared to signal an error of type type-error if new-subsequence is not a proper sequence.

See Also:

replace

Expanded Reference: subseq​

Extracting a subsequence​

subseq creates a fresh copy of a portion of a sequence. The start index is inclusive, and the optional end index is exclusive.

(subseq "Hello, World!" 7)
=> "World!"
(subseq "Hello, World!" 0 5)
=> "Hello"
(subseq '(a b c d e) 1 3)
=> (B C)

Omitting the end argument​

When end is omitted or nil, subseq extracts from start to the end of the sequence.

(subseq #(10 20 30 40 50) 2)
=> #(30 40 50)
(subseq '(1 2 3 4) 0)
=> (1 2 3 4)

The result is always a fresh copy​

subseq always allocates a new sequence, even when extracting the entire sequence. The result is never eq to the original.

(let ((original '(a b c)))
  (eq original (subseq original 0)))
=> NIL

Using setf with subseq​

You can use setf with subseq to destructively replace a portion of a sequence. The shorter of the two subsequences determines how many elements are copied.

(let ((str (copy-seq "Hello, World!")))
  (setf (subseq str 7 12) "Lisp!")
  str)
=> "Hello, Lisp!!"

Partial replacement when lengths differ​

When the replacement is shorter than the target region, only that many elements are replaced. The rest of the original remains unchanged.

(let ((str (copy-seq "abcdef")))
  (setf (subseq str 0 4) "XY")
  str)
=> "XYcdef"

Extracting from vectors​

subseq returns a fresh simple vector when applied to a vector.

(subseq #(a b c d e f) 2 5)
=> #(C D E)