Next: , Up: Sequences Arrays Vectors

### 6.1 Sequences

This section describes functions that accept any kind of sequence.

— Function: sequencep object

This function returns `t` if object is a list, vector, string, bool-vector, or char-table, `nil` otherwise.

— Function: length sequence

This function returns the number of elements in sequence. If sequence is a dotted list, a `wrong-type-argument` error is signaled. Circular lists may cause an infinite loop. For a char-table, the value returned is always one more than the maximum Emacs character code.

See Definition of safe-length, for the related function `safe-length`.

```          (length '(1 2 3))
⇒ 3
(length ())
⇒ 0
(length "foobar")
⇒ 6
(length [1 2 3])
⇒ 3
(length (make-bool-vector 5 nil))
⇒ 5
```

See also `string-bytes`, in Text Representations.

If you need to compute the width of a string on display, you should use `string-width` (see Width), not `length`, since `length` only counts the number of characters, but does not account for the display width of each character.

— 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, out-of-range values behave as for `nth`. See Definition of nth. Otherwise, out-of-range values trigger an `args-out-of-range` error.

```          (elt [1 2 3 4] 2)
⇒ 3
(elt '(1 2 3 4) 2)
⇒ 3
;; We use `string` to show clearly which character `elt` returns.
(string (elt "1234" 2))
⇒ "3"
(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 Definition of nth).

— Function: copy-sequence sequence

This function 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 text properties, the property list in the copy is itself a copy, not shared with the original's property list. However, the actual values of the properties are shared. See Text Properties.

This function does not work for dotted lists. Trying to copy a circular list may cause an infinite loop.

See also `append` in Building Lists, `concat` in Creating Strings, and `vconcat` in Vector Functions, 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)]
```