12.1 Sequences

In SXEmacs Lisp, a sequence is either a list, a double-linked list, a vector, a bit vector, or a string. The common property that all sequences have is that each is an ordered collection of elements. This section describes functions that accept any kind of sequence.

Function: sequencep object

Returns t if object is a list, dllist, vector, bit vector, or string, nil otherwise.

Function: copy-sequence sequence

Returns a copy of sequence. The copy is the same type of object as the original sequence, and it has the same elements in the same order.

Storing a new element into the copy does not affect the original sequence, and vice versa. However, the elements of the new sequence are not copies; they are identical (eq) to the elements of the original. Therefore, changes made within these elements, as found via the copied sequence, are also visible in the original sequence.

If the sequence is a string with extents or text properties, the extents and text properties in the copy are also copied, not shared with the original. (This means that modifying the extents or text properties of the original will not affect the copy.) However, the actual values of the properties are shared. See Extents, See Text Properties.

See also append in Building Lists, concat in Creating Strings, vconcat in Vectors, and bvconcat in Bit Vectors, for other ways to copy sequences.

(setq bar '(1 2))
     ⇒ (1 2)

(setq x (vector 'foo bar))
     ⇒ [foo (1 2)]

(setq y (copy-sequence x))
     ⇒ [foo (1 2)]

(eq x y)
     ⇒ nil

(equal x y)
     ⇒ t

(eq (elt x 1) (elt y 1))
     ⇒ t

;; Replacing an element of one sequence.
(aset x 0 'quux)
x ⇒ [quux (1 2)]
y ⇒ [foo (1 2)]

;; Modifying the inside of a shared element.
(setcar (aref x 1) 69)
x ⇒ [quux (69 2)]
y ⇒ [foo (69 2)]

;; Creating a bit vector.
(bit-vector 1 0 1 1 0 1 0 0)
     ⇒ #*10110100

Function: length sequence

Returns the number of elements in sequence. If sequence is a cons cell that is not a list (because the final CDR is not nil), a wrong-type-argument error is signaled.

(length '(1 2 3))
    ⇒ 3

(length ())
    ⇒ 0

(length (dllist 2 4))
    ⇒ 2

(length "foobar")
    ⇒ 6

(length [1 2 3])
    ⇒ 3

(length #*01101)
    ⇒ 5

Function: elt sequence index

This function returns the element of sequence indexed by index. Legitimate values of index are integers ranging from 0 up to one less than the length of sequence. If sequence is a list, then out-of-range values of index return nil; otherwise, they trigger an args-out-of-range error.

(elt [1 2 3 4] 2)
     ⇒ 3

(elt '(1 2 3 4) 2)
     ⇒ 3

(elt (dllist 1 2 3 4) 2)
     ⇒ 3

(char-to-string (elt "1234" 2))
     ⇒ "3"

(elt #*00010000 3)
     ⇒ 1

(elt [1 2 3 4] 4)
     error→Args out of range: [1 2 3 4], 4

(elt [1 2 3 4] -1)
     error→Args out of range: [1 2 3 4], -1

This function generalizes aref (see Array Functions) and nth (see List Elements).