2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/sequences
6 @node Sequences Arrays Vectors, Symbols, Lists, Top
7 @chapter Sequences, Arrays, and Vectors
10 Recall that the @dfn{sequence} type is the union of three other Lisp
11 types: lists, vectors, and strings. In other words, any list is a
12 sequence, any vector is a sequence, and any string is a sequence. The
13 common property that all sequences have is that each is an ordered
14 collection of elements.
16 An @dfn{array} is a single primitive object directly containing all
17 its elements. Therefore, all the elements are accessible in constant
18 time. The length of an existing array cannot be changed. Both strings
19 and vectors are arrays. A list is a sequence of elements, but it is not
20 a single primitive object; it is made of cons cells, one cell per
21 element. Therefore, elements farther from the beginning of the list
22 take longer to access, but it is possible to add elements to the list or
25 The following diagram shows the relationship between these types:
29 ___________________________________
32 | ______ ______________________ |
34 | | List | | Array | |
35 | | | | ________ _______ | |
36 | |______| | | | | | | |
37 | | | String | | Vector| | |
38 | | |________| |_______| | |
39 | |______________________| |
40 |___________________________________|
42 @center @r{The relationship between sequences, arrays, and vectors}
46 The elements of vectors and lists may be any Lisp objects. The
47 elements of strings are all characters.
50 * Sequence Functions:: Functions that accept any kind of sequence.
51 * Arrays:: Characteristics of arrays in Emacs Lisp.
52 * Array Functions:: Functions specifically for arrays.
53 * Vectors:: Functions specifically for vectors.
56 @node Sequence Functions
59 In Emacs Lisp, a @dfn{sequence} is either a list, a vector or a
60 string. The common property that all sequences have is that each is an
61 ordered collection of elements. This section describes functions that
62 accept any kind of sequence.
64 @defun sequencep object
65 Returns @code{t} if @var{object} is a list, vector, or
66 string, @code{nil} otherwise.
69 @defun copy-sequence sequence
70 @cindex copying sequences
71 Returns a copy of @var{sequence}. The copy is the same type of object
72 as the original sequence, and it has the same elements in the same order.
74 Storing a new element into the copy does not affect the original
75 @var{sequence}, and vice versa. However, the elements of the new
76 sequence are not copies; they are identical (@code{eq}) to the elements
77 of the original. Therefore, changes made within these elements, as
78 found via the copied sequence, are also visible in the original
81 If the sequence is a string with text properties, the property list in
82 the copy is itself a copy, not shared with the original's property
83 list. However, the actual values of the properties are shared.
84 @xref{Text Properties}.
86 See also @code{append} in @ref{Building Lists}, @code{concat} in
87 @ref{Creating Strings}, and @code{vconcat} in @ref{Vectors}, for others
88 ways to copy sequences.
96 (setq x (vector 'foo bar))
100 (setq y (copy-sequence x))
101 @result{} [foo (1 2)]
113 (eq (elt x 1) (elt y 1))
118 ;; @r{Replacing an element of one sequence.}
120 x @result{} [quux (1 2)]
121 y @result{} [foo (1 2)]
125 ;; @r{Modifying the inside of a shared element.}
126 (setcar (aref x 1) 69)
127 x @result{} [quux (69 2)]
128 y @result{} [foo (69 2)]
133 @defun length sequence
134 @cindex string length
136 @cindex vector length
137 @cindex sequence length
138 Returns the number of elements in @var{sequence}. If @var{sequence} is
139 a cons cell that is not a list (because the final @sc{cdr} is not
140 @code{nil}), a @code{wrong-type-argument} error is signaled.
162 @defun elt sequence index
163 @cindex elements of sequences
164 This function returns the element of @var{sequence} indexed by
165 @var{index}. Legitimate values of @var{index} are integers ranging from
166 0 up to one less than the length of @var{sequence}. If @var{sequence}
167 is a list, then out-of-range values of @var{index} return @code{nil};
168 otherwise, they trigger an @code{args-out-of-range} error.
180 (char-to-string (elt "1234" 2))
185 @error{}Args out of range: [1 2 3 4], 4
189 @error{}Args out of range: [1 2 3 4], -1
193 This function duplicates @code{aref} (@pxref{Array Functions}) and
194 @code{nth} (@pxref{List Elements}), except that it works for any kind of
202 An @dfn{array} object refers directly to a number of other Lisp
203 objects, called the elements of the array. Any element of an array may
204 be accessed in constant time. In contrast, an element of a list
205 requires access time that is proportional to the position of the element
208 When you create an array, you must specify how many elements it has.
209 The amount of space allocated depends on the number of elements.
210 Therefore, it is impossible to change the size of an array once it is
211 created. You cannot add or remove elements. However, you can replace
212 an element with a different value.
214 Emacs defines two types of array, both of which are one-dimensional:
215 @dfn{strings} and @dfn{vectors}. A vector is a general array; its
216 elements can be any Lisp objects. A string is a specialized array; its
217 elements must be characters (i.e., integers between 0 and 255). Each
218 type of array has its own read syntax. @xref{String Type}, and
221 Both kinds of arrays share these characteristics:
225 The first element of an array has index zero, the second element has
226 index 1, and so on. This is called @dfn{zero-origin} indexing. For
227 example, an array of four elements has indices 0, 1, 2, @w{and 3}.
230 The elements of an array may be referenced or changed with the functions
231 @code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
234 In principle, if you wish to have an array of characters, you could use
235 either a string or a vector. In practice, we always choose strings for
236 such applications, for four reasons:
240 They occupy one-fourth the space of a vector of the same elements.
243 Strings are printed in a way that shows the contents more clearly
247 Strings can hold text properties. @xref{Text Properties}.
250 Many of the specialized editing and I/O facilities of Emacs accept only
251 strings. For example, you cannot insert a vector of characters into a
252 buffer the way you can insert a string. @xref{Strings and Characters}.
255 @node Array Functions
256 @section Functions that Operate on Arrays
258 In this section, we describe the functions that accept both strings
262 This function returns @code{t} if @var{object} is an array (i.e., either a
275 @defun aref array index
276 @cindex array elements
277 This function returns the @var{index}th element of @var{array}. The
278 first element is at index zero.
282 (setq primes [2 3 5 7 11 13])
283 @result{} [2 3 5 7 11 13]
292 @result{} 98 ; @r{@samp{b} is @sc{ASCII} code 98.}
296 See also the function @code{elt}, in @ref{Sequence Functions}.
299 @defun aset array index object
300 This function sets the @var{index}th element of @var{array} to be
301 @var{object}. It returns @var{object}.
305 (setq w [foo bar baz])
306 @result{} [foo bar baz]
310 @result{} [fu bar baz]
323 If @var{array} is a string and @var{object} is not a character, a
324 @code{wrong-type-argument} error results.
327 @defun fillarray array object
328 This function fills the array @var{array} with pointers to @var{object},
329 replacing any previous values. It returns @var{array}.
333 (setq a [a b c d e f g])
334 @result{} [a b c d e f g]
336 @result{} [0 0 0 0 0 0 0]
338 @result{} [0 0 0 0 0 0 0]
341 (setq s "When in the course")
342 @result{} "When in the course"
344 @result{} "------------------"
348 If @var{array} is a string and @var{object} is not a character, a
349 @code{wrong-type-argument} error results.
352 The general sequence functions @code{copy-sequence} and @code{length}
353 are often useful for objects known to be arrays. @xref{Sequence Functions}.
359 Arrays in Lisp, like arrays in most languages, are blocks of memory
360 whose elements can be accessed in constant time. A @dfn{vector} is a
361 general-purpose array; its elements can be any Lisp objects. (The other
362 kind of array in Emacs Lisp is the @dfn{string}, whose elements must be
363 characters.) Vectors in Emacs serve as syntax tables (vectors of
364 integers), as obarrays (vectors of symbols), and in keymaps (vectors of
365 commands). They are also used internally as part of the representation
366 of a byte-compiled function; if you print such a function, you will see
369 In Emacs Lisp, the indices of the elements of a vector start from zero
370 and count up from there.
372 Vectors are printed with square brackets surrounding the elements
373 in their order. Thus, a vector containing the symbols @code{a},
374 @code{b} and @code{c} is printed as @code{[a b c]}. You can write
375 vectors in the same way in Lisp input.
377 A vector, like a string or a number, is considered a constant for
378 evaluation: the result of evaluating it is the same vector. This does
379 not evaluate or even examine the elements of the vector.
380 @xref{Self-Evaluating Forms}.
382 Here are examples of these principles:
386 (setq avector [1 two '(three) "four" [five]])
387 @result{} [1 two (quote (three)) "four" [five]]
389 @result{} [1 two (quote (three)) "four" [five]]
390 (eq avector (eval avector))
395 Here are some functions that relate to vectors:
397 @defun vectorp object
398 This function returns @code{t} if @var{object} is a vector.
410 @defun vector &rest objects
411 This function creates and returns a vector whose elements are the
412 arguments, @var{objects}.
416 (vector 'foo 23 [bar baz] "rats")
417 @result{} [foo 23 [bar baz] "rats"]
424 @defun make-vector length object
425 This function returns a new vector consisting of @var{length} elements,
426 each initialized to @var{object}.
430 (setq sleepy (make-vector 9 'Z))
431 @result{} [Z Z Z Z Z Z Z Z Z]
436 @defun vconcat &rest sequences
437 @cindex copying vectors
438 This function returns a new vector containing all the elements of the
439 @var{sequences}. The arguments @var{sequences} may be lists, vectors,
440 or strings. If no @var{sequences} are given, an empty vector is
443 The value is a newly constructed vector that is not @code{eq} to any
448 (setq a (vconcat '(A B C) '(D E F)))
449 @result{} [A B C D E F]
456 (vconcat [A B C] "aa" '(foo (6 7)))
457 @result{} [A B C 97 97 foo (6 7)]
461 When an argument is an integer (not a sequence of integers), it is
462 converted to a string of digits making up the decimal printed
463 representation of the integer. This special case exists for
464 compatibility with Mocklisp, and we don't recommend you take advantage
465 of it. If you want to convert an integer to digits in this way, use
466 @code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
467 (@pxref{String Conversion}).
469 For other concatenation functions, see @code{mapconcat} in @ref{Mapping
470 Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
471 in @ref{Building Lists}.
474 The @code{append} function provides a way to convert a vector into a
475 list with the same elements (@pxref{Building Lists}):
479 (setq avector [1 two (quote (three)) "four" [five]])
480 @result{} [1 two (quote (three)) "four" [five]]
482 @result{} (1 two (quote (three)) "four" [five])