⟦bc5f78530⟧

TextFile

@setfilename ../info/sequences
@node Sequences Arrays Vectors, Symbols, Lists, Top
@chapter Sequences, Arrays, and Vectors
@cindex sequence

@c name problem: node names cannot have commas.  There is also
@c a section named Sequences below.  What is the chapter to be called??

  Two supertypes are described in this chapter, sequences and arrays.
The primitive type, vector, is also described here.

  Recall that the @dfn{sequence} type is a supertype of three other Lisp
types: lists, vectors, and strings.  In other words, any list is a
sequence, any vector is a sequence, and any string is a sequence.  The
common property that all sequences have is that each is an ordered
collection of elements.

  An @dfn{array} is a sequence in which all element is accessible in
constant time, and whose length cannot be changed.  Both strings and
vectors are arrays.  A list is not an array because the elements of a
list are not all accessible in constant time; in fact, the access time
of an element of a list is proportional to its position in the list.

  The following diagram shows the relationship between all these types.

@example
            ___________________________________
           |                                   |
           |          Sequence                 |
           |  ______   ______________________  |
           | |      | |                      | |
           | | List | |         Array        | |
           | |      | |  ________   _______  | |   
           | |______| | |        | |       | | |
           |          | | String | | Vector| | |
           |          | |________| |_______| | |
           |          |______________________| |
           |___________________________________|

@center @r{The Relationship between Sequences, Arrays, and Vectors}
@end example

  The elements of vectors and lists may be any Lisp objects.  The elements
of strings are all characters.

@menu
* Sequence Functions::  
* Arrays::      
* Vectors::     
@end menu

@node Sequence Functions, Arrays, Sequences Arrays Vectors, Sequences Arrays Vectors
@section Sequences

  In Emacs Lisp, a @dfn{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.

@defun sequencep object
Returns @code{t} if @var{object} is a list, vector, or
string, @code{nil} otherwise.
@end defun

@defun copy-sequence sequence
@cindex copying sequences
Returns a copy of @var{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
@var{sequence}, and vice versa.  However, the elements of the new
sequence are not copies; they are identical (@code{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.

See also @code{append} in @ref{Building Cons Cells and Lists}, and
@code{concat} in @ref{Creating Strings}, for others ways to copy
sequences.

@example
(setq bar '(1 2))
     @result{} (1 2)
(setq x (vector 'foo bar))
     @result{} [foo (1 2)]
(setq y (copy-sequence x))
     @result{} [foo (1 2)]

(eq x y)
     @result{} nil
(equal x y)
     @result{} t
(eq (elt x 1) (elt y 1))
     @result{} t

;; @r{Replacing an element of one sequence.}
(aset x 0 'quux)
x @result{} [quux (1 2)]
y @result{} [foo (1 2)]

;; @r{Modifying the inside of a shared element.}
(setcar (aref x 1) 69)
x @result{} [quux (69 2)]
y @result{} [foo (69 2)]
@end example
@end defun

@defun length sequence
@cindex string length
@cindex list length
@cindex vector length
@cindex sequence length
Returns the number of elements in @var{sequence}.  If @var{sequence}
is a cons that is not a list (the final @sc{cdr} is not @code{nil}), a
@code{wrong-type-argument} error results.

@example
(length '(1 2 3))
    @result{} 3
(length nil)
    @result{} 0
(length "foobar")
    @result{} 6
(length [1 2 3])
    @result{} 3
@end example
@end defun

@defun elt sequence integer
@cindex elements of sequences
This function returns the element of @var{sequence} indexed by
@var{integer}.  Legitimate values of @var{integer} range from 0 up to one
less than the length of @var{sequence}; other values produce an
@code{args-out-of-range} error.

@example
(elt [1 2 3 4] 2)
     @result{} 3
(elt '(1 2 3 4) 2)
     @result{} 3
(char-to-string (elt "1234" 2))
     @result{} "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
@end example

This function duplicates @code{aref} (@pxref{Arrays}) and @code{nth}
(@pxref{List Elements, , Accessing Elements of Lists}), except that it
works for any kind of sequence.
@end defun

@node Arrays, Vectors, Sequence Functions, Sequences Arrays Vectors
@section Arrays
@cindex array

  Arrays in Lisp, like arrays in most languages, are blocks of memory
whose elements can be accessed in equal time.  All Emacs Lisp arrays are
single dimensional and zero-based (their first element is indexed with
zero).

  Emacs Lisp provides two kinds of arrays, distinguished by what kinds
of element they can contain.  A @dfn{vector} is a general array; its
elements can be any Lisp objects.  A @dfn{string} is a specialized
array; its elements must be characters (i.e., integers between 0 and
255).

  In principle, if you wish to have an array of characters, you could use
either a string or a vector.  In practice, we always choose strings for
such applications, for three reasons:

@itemize @bullet
@item
They occupy one fourth the space of a vector.

@item
Strings are printed in a way that shows the contents more clearly
as characters.

@item
Many of the specialized editing and I/O facilities of Emacs accept only
strings.  For example, you cannot insert a vector of characters into a
buffer the way you can insert a string.  @xref{Strings and Characters}.
@end itemize

  In this section, we describe the functions that accept both strings
and vectors.

@defun arrayp object
This function returns @code{t} if the object is an array (i.e., either a
vector or a string).

@example
(arrayp [a])
@result{} t
(arrayp "asdf")
@result{} t
@end example
@end defun

@defun aref array integer
@cindex array elements
This function returns the @var{integer}'th element of the @var{array}
The first element is indexed with zero.  In the example, the character
@kbd{b} is @sc{ASCII} code 98.

@example
(setq primes [2 3 5 7 11 13])
     @result{} [2 3 5 7 11 13]
(aref primes 4)
     @result{} 11
(aref "abcdefg" 1)
     @result{} 98
(elt primes 4)
     @result{} 11
@end example

See also the function @code{elt}, in @ref{Sequence Functions}.
@end defun

@defun aset array integer object
This function sets the @var{integer}'th element of @var{array} to be
@var{object}.  It returns @var{object}.

@example
(setq w [foo bar baz])
     @result{} [foo bar baz]
(aset w 0 'fu)
     @result{} fu
w
     @result{} [fu bar baz]

(setq x "asdfasfd")
     @result{} "asdfasfd"
(aset x 3 ?Z)
     @result{} 90
x
     @result{} "asdZasfd"
@end example

If @var{array} is a string and @var{object} is not a character, a
@code{wrong-type-argument} error results.
@end defun

@defun fillarray array object
This function fills the array with pointers to @var{object}, replacing
any previous values.  It returns @var{array}.

@example
(setq a [a b c d e f g])
     @result{} [a b c d e f g]
(fillarray a 0)
     @result{} [0 0 0 0 0 0 0]
a
     @result{} [0 0 0 0 0 0 0]
(setq s "When in the course")
     @result{} "When in the course"
(fillarray s ?-)
     @result{} "------------------"
@end example

If @var{array} is a string and @var{object} is not a character, a
@code{wrong-type-argument} error results.
@end defun

The general sequence functions @code{copy-sequence} and @code{length}
are often useful for objects known to be arrays.  @xref{Sequence Functions}.

@node Vectors,  , Arrays, Sequences Arrays Vectors
@section Vectors

  Arrays in Lisp, like arrays in most languages, are blocks of memory
whose elements can be accessed in constant time.  A @dfn{vector} is a
general-purpose array; its elements can be any Lisp objects.  (The other
kind of array provided in Emacs Lisp is the @dfn{string}, whose elements
must be characters.)  The main uses of vectors in Emacs are as syntax
tables (vectors of integers), keymaps (vectors of commands), and inside
of compiled functions.

  The elements of a vector are numbered starting with zero in Emacs Lisp.

  Vectors are printed with square brackets surrounding the elements
in their order.  Thus, a vector containing the symbols @code{a},
@code{b} and @code{c} is printed as @code{[a b c]}.  You can write
vectors in the same way in Lisp input.

@cindex vector evaluation
  A vector, like a string or a number, is considered a constant:
the result of evaluating it is the same vector.  The elements of the
vector are not evaluated.

  Here are examples of these principles:

@example
(setq avector
      [1 two '(three) "four" [five]])
     @result{} [1 two (quote (three)) "four" [five]]
(eval avector)
     @result{} [1 two (quote (three)) "four" [five]]
(eq avector (eval avector))
     @result{} t
@end example

Here are some functions that relate specifically to vectors:

@defun vectorp object
This function returns @code{t} if the object is a vector.

@example
(vectorp [a])
     @result{} t
(vectorp "asdf")
     @result{} nil
@end example
@end defun

@defun vector &rest objects
This function returns a vector whose elements are the arguments,
@var{objects}.

@example
(vector 'foo 23 [bar baz] "rats")
     @result{} [foo 23 [bar baz] "rats"]
(vector)
     @result{} []
@end example
@end defun

@defun make-vector integer object
This function returns a new vector consisting of @var{integer} elements,
all initialized to @var{object}.

@example
(setq sleepy (make-vector 9 'Z))
     @result{} [Z Z Z Z Z Z Z Z Z]
@end example
@end defun

@defun vconcat &rest sequences
@cindex copying vectors
@cindex copying sequences
This function returns a new vector containing all the elements of the
arguments, @var{sequences}.  These arguments may be lists, vectors, or
strings; they may also be integers.  If no @var{sequences} are given, an
empty vector is returned.

The value is a newly constructed vector which is not @code{eq} to any
existing vector.

@example
(setq a (vconcat '(A B C) '(D E F)))
     @result{} [A B C D E F]
(eq a (vconcat a))
     @result{} nil
(vconcat)
     @result{} []
@end example

@cindex integer to decimal
As a special feature, if one of the @var{sequences} is an integer (not a
sequence of integers), it is first converted to the string of digits
making up the decimal print representation of the integer.  In the
second example below, the number 123 is divided into three digits.  Note
that the @sc{ASCII} code of the character @samp{1} is 49, and that of
@samp{a} is 97.

@example
(vconcat [A B C] 123 "aa" '(foo (6 7)))
     @result{} [A B C 49 50 51 97 97 foo (6 7)]
@end example

For other concatenation functions, @code{mapconcat} in @ref{Mapping Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
in @ref{Building Cons Cells and Lists}.
@end defun

  The @code{append} function may be used to convert a vector into a list
with the same elements (@pxref{Building Cons Cells and Lists}):

@example
(append avector nil)
     @result{} (1 two (quote (three)) "four" [five])
@end example
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦bc5f78530⟧ TextFile

Derivation

TextFile
