GNU Info

(elisp)Sequence Functions

---

Next: Arrays Up: Sequences Arrays Vectors

---

Enter node , (file) or (file)node

Sequences
=========

   In Emacs Lisp, a "sequence" is either a list or an array.  The
common property of all sequences is that they are ordered collections of
elements.  This section describes functions that accept any kind of
sequence.

 - Function: sequencep object
     Returns `t' if OBJECT is a list, vector, or string, `nil'
     otherwise.

 - Function: length sequence
     This function 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.

     Note: List Elements, 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

 - 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
          ;; 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' (Note: Array Functions) and
     `nth' (Note: List Elements).

 - 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 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.  Note: Text Properties.

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