(lispref.info)Sequence Functions


Next: Arrays Prev: Sequences Arrays Vectors Up: Sequences Arrays Vectors

Sequences
=========

   In Emacs Lisp, a "sequence" is either a list, a 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, 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 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 others
     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)]

 - 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 "foobar")
              => 6
          (length [1 2 3])
              => 3

 - 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 produce
     an `args-out-of-range' error.

          (elt [1 2 3 4] 2)
               => 3
          (elt '(1 2 3 4) 2)
               => 3
          (char-to-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 duplicates `aref' (Note: Array Functions.) and
     `nth' (Note: List Elements.), except that it works for any kind
     of sequence.


automatically generated by info2www