Moved code around to minimize compiler warnings.
[emacs.git] / lispref / sequences.texi
blobc6de3f1c94d549b5d91f411acc58ed7cf6ba1d34
1 @c -*-texinfo-*-
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
8 @cindex sequence
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 that has a slot for each
17 elements.  All the elements are accessible in constant time, but the
18 length of an existing array cannot be changed.  Strings and vectors are
19 the two types of arrays.
21   A list is a sequence of elements, but it is not a single primitive
22 object; it is made of cons cells, one cell per element.  Finding the
23 @var{n}th element requires looking through @var{n} cons cells, so
24 elements farther from the beginning of the list take longer to access.
25 But it is possible to add elements to the list, or remove elements.
27   The following diagram shows the relationship between these types:
29 @example
30 @group
31           ___________________________________
32          |                                   |
33          |          Sequence                 |
34          |  ______   ______________________  |
35          | |      | |                      | |
36          | | List | |         Array        | |
37          | |      | |  ________   _______  | |   
38          | |______| | |        | |       | | |
39          |          | | Vector | | String| | |
40          |          | |________| |_______| | |
41          |          |______________________| |
42          |___________________________________|
43 @end group
44 @end example
46   The elements of vectors and lists may be any Lisp objects.  The
47 elements of strings are all characters.
49 @menu
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::               Special characteristics of Emacs Lisp vectors.
54 * Vector Functions::      Functions specifically for vectors.
55 @end menu
57 @node Sequence Functions
58 @section Sequences
60   In Emacs Lisp, a @dfn{sequence} is either a list, a vector or a
61 string.  The common property that all sequences have is that each is an
62 ordered collection of elements.  This section describes functions that
63 accept any kind of sequence.
65 @defun sequencep object
66 Returns @code{t} if @var{object} is a list, vector, or
67 string, @code{nil} otherwise.
68 @end defun
70 @defun copy-sequence sequence
71 @cindex copying sequences
72 Returns a copy of @var{sequence}.  The copy is the same type of object
73 as the original sequence, and it has the same elements in the same order.
75 Storing a new element into the copy does not affect the original
76 @var{sequence}, and vice versa.  However, the elements of the new
77 sequence are not copies; they are identical (@code{eq}) to the elements
78 of the original.  Therefore, changes made within these elements, as
79 found via the copied sequence, are also visible in the original
80 sequence.
82 If the sequence is a string with text properties, the property list in
83 the copy is itself a copy, not shared with the original's property
84 list.  However, the actual values of the properties are shared.
85 @xref{Text Properties}.
87 See also @code{append} in @ref{Building Lists}, @code{concat} in
88 @ref{Creating Strings}, and @code{vconcat} in @ref{Vectors}, for others
89 ways to copy sequences.
91 @example
92 @group
93 (setq bar '(1 2))
94      @result{} (1 2)
95 @end group
96 @group
97 (setq x (vector 'foo bar))
98      @result{} [foo (1 2)]
99 @end group
100 @group
101 (setq y (copy-sequence x))
102      @result{} [foo (1 2)]
103 @end group
105 @group
106 (eq x y)
107      @result{} nil
108 @end group
109 @group
110 (equal x y)
111      @result{} t
112 @end group
113 @group
114 (eq (elt x 1) (elt y 1))
115      @result{} t
116 @end group
118 @group
119 ;; @r{Replacing an element of one sequence.}
120 (aset x 0 'quux)
121 x @result{} [quux (1 2)]
122 y @result{} [foo (1 2)]
123 @end group
125 @group
126 ;; @r{Modifying the inside of a shared element.}
127 (setcar (aref x 1) 69)
128 x @result{} [quux (69 2)]
129 y @result{} [foo (69 2)]
130 @end group
131 @end example
132 @end defun
134 @defun length sequence
135 @cindex string length
136 @cindex list length
137 @cindex vector length
138 @cindex sequence length
139 Returns the number of elements in @var{sequence}.  If @var{sequence} is
140 a cons cell that is not a list (because the final @sc{cdr} is not
141 @code{nil}), a @code{wrong-type-argument} error is signaled.
143 @example
144 @group
145 (length '(1 2 3))
146     @result{} 3
147 @end group
148 @group
149 (length ())
150     @result{} 0
151 @end group
152 @group
153 (length "foobar")
154     @result{} 6
155 @end group
156 @group
157 (length [1 2 3])
158     @result{} 3
159 @end group
160 @end example
161 @end defun
163 @defun elt sequence index
164 @cindex elements of sequences
165 This function returns the element of @var{sequence} indexed by
166 @var{index}.  Legitimate values of @var{index} are integers ranging from
167 0 up to one less than the length of @var{sequence}.  If @var{sequence}
168 is a list, then out-of-range values of @var{index} return @code{nil};
169 otherwise, they trigger an @code{args-out-of-range} error.
171 @example
172 @group
173 (elt [1 2 3 4] 2)
174      @result{} 3
175 @end group
176 @group
177 (elt '(1 2 3 4) 2)
178      @result{} 3
179 @end group
180 @group
181 (char-to-string (elt "1234" 2))
182      @result{} "3"
183 @end group
184 @group
185 (elt [1 2 3 4] 4)
186      @error{}Args out of range: [1 2 3 4], 4
187 @end group
188 @group
189 (elt [1 2 3 4] -1)
190      @error{}Args out of range: [1 2 3 4], -1
191 @end group
192 @end example
194 This function generalizes @code{aref} (@pxref{Array Functions}) and
195 @code{nth} (@pxref{List Elements}).
196 @end defun
198 @node Arrays
199 @section Arrays
200 @cindex array
202   An @dfn{array} object has slots that hold 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
206 in the list.
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 an
212 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
219 @ref{Vector Type}.
221   Both kinds of array share these characteristics:
223 @itemize @bullet
224 @item
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}.
229 @item
230 The elements of an array may be referenced or changed with the functions
231 @code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
232 @end itemize
234   In principle, if you wish to have an array of text characters, you
235 could use either a string or a vector.  In practice, we always choose
236 strings for such applications, for four reasons:
238 @itemize @bullet
239 @item
240 They occupy one-fourth the space of a vector of the same elements.
242 @item
243 Strings are printed in a way that shows the contents more clearly
244 as characters.
246 @item
247 Strings can hold text properties.  @xref{Text Properties}.
249 @item
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}.
253 @end itemize
255   By contrast, for an array of keyboard input characters (such as a key
256 sequence), a vector may be necessary, because many keyboard input
257 characters are outside the range that will fit in a string.  @xref{Key
258 Sequence Input}.
260 @node Array Functions
261 @section Functions that Operate on Arrays
263   In this section, we describe the functions that accept both strings
264 and vectors.
266 @defun arrayp object
267 This function returns @code{t} if @var{object} is an array (i.e., either a
268 vector or a string).
270 @example
271 @group
272 (arrayp [a])
273 @result{} t
274 (arrayp "asdf")
275 @result{} t
276 @end group
277 @end example
278 @end defun
280 @defun aref array index
281 @cindex array elements
282 This function returns the @var{index}th element of @var{array}.  The
283 first element is at index zero.
285 @example
286 @group
287 (setq primes [2 3 5 7 11 13])
288      @result{} [2 3 5 7 11 13]
289 (aref primes 4)
290      @result{} 11
291 (elt primes 4)
292      @result{} 11
293 @end group
295 @group
296 (aref "abcdefg" 1)
297      @result{} 98           ; @r{@samp{b} is @sc{ASCII} code 98.}
298 @end group
299 @end example
301 See also the function @code{elt}, in @ref{Sequence Functions}.
302 @end defun
304 @defun aset array index object
305 This function sets the @var{index}th element of @var{array} to be
306 @var{object}.  It returns @var{object}.
308 @example
309 @group
310 (setq w [foo bar baz])
311      @result{} [foo bar baz]
312 (aset w 0 'fu)
313      @result{} fu
315      @result{} [fu bar baz]
316 @end group
318 @group
319 (setq x "asdfasfd")
320      @result{} "asdfasfd"
321 (aset x 3 ?Z)
322      @result{} 90
324      @result{} "asdZasfd"
325 @end group
326 @end example
328 If @var{array} is a string and @var{object} is not a character, a
329 @code{wrong-type-argument} error results.
330 @end defun
332 @defun fillarray array object
333 This function fills the array @var{array} with @var{object}, so that
334 each element of @var{array} is @var{object}.  It returns @var{array}.
336 @example
337 @group
338 (setq a [a b c d e f g])
339      @result{} [a b c d e f g]
340 (fillarray a 0)
341      @result{} [0 0 0 0 0 0 0]
343      @result{} [0 0 0 0 0 0 0]
344 @end group
345 @group
346 (setq s "When in the course")
347      @result{} "When in the course"
348 (fillarray s ?-)
349      @result{} "------------------"
350 @end group
351 @end example
353 If @var{array} is a string and @var{object} is not a character, a
354 @code{wrong-type-argument} error results.
355 @end defun
357 The general sequence functions @code{copy-sequence} and @code{length}
358 are often useful for objects known to be arrays.  @xref{Sequence Functions}.
360 @node Vectors
361 @section Vectors
362 @cindex vector
364   Arrays in Lisp, like arrays in most languages, are blocks of memory
365 whose elements can be accessed in constant time.  A @dfn{vector} is a
366 general-purpose array; its elements can be any Lisp objects.  (The other
367 kind of array in Emacs Lisp is the @dfn{string}, whose elements must be
368 characters.)  Vectors in Emacs serve as syntax tables (vectors of
369 integers), as obarrays (vectors of symbols), and in keymaps (vectors of
370 commands).  They are also used internally as part of the representation
371 of a byte-compiled function; if you print such a function, you will see
372 a vector in it.
374   In Emacs Lisp, the indices of the elements of a vector start from zero
375 and count up from there.
377   Vectors are printed with square brackets surrounding the elements.
378 Thus, a vector whose elements are the symbols @code{a}, @code{b} and
379 @code{a} is printed as @code{[a b a]}.  You can write vectors in the
380 same way in Lisp input.
382   A vector, like a string or a number, is considered a constant for
383 evaluation: the result of evaluating it is the same vector.  This does
384 not evaluate or even examine the elements of the vector.
385 @xref{Self-Evaluating Forms}.
387   Here are examples of these principles:
389 @example
390 @group
391 (setq avector [1 two '(three) "four" [five]])
392      @result{} [1 two (quote (three)) "four" [five]]
393 (eval avector)
394      @result{} [1 two (quote (three)) "four" [five]]
395 (eq avector (eval avector))
396      @result{} t
397 @end group
398 @end example
400 @node Vector Functions
401 @section Functions That Operate on Vectors
403   Here are some functions that relate to vectors:
405 @defun vectorp object
406 This function returns @code{t} if @var{object} is a vector.
408 @example
409 @group
410 (vectorp [a])
411      @result{} t
412 (vectorp "asdf")
413      @result{} nil
414 @end group
415 @end example
416 @end defun
418 @defun vector &rest objects
419 This function creates and returns a vector whose elements are the
420 arguments, @var{objects}.
422 @example
423 @group
424 (vector 'foo 23 [bar baz] "rats")
425      @result{} [foo 23 [bar baz] "rats"]
426 (vector)
427      @result{} []
428 @end group
429 @end example
430 @end defun
432 @defun make-vector length object
433 This function returns a new vector consisting of @var{length} elements,
434 each initialized to @var{object}.
436 @example
437 @group
438 (setq sleepy (make-vector 9 'Z))
439      @result{} [Z Z Z Z Z Z Z Z Z]
440 @end group
441 @end example
442 @end defun
444 @defun vconcat &rest sequences
445 @cindex copying vectors
446 This function returns a new vector containing all the elements of the
447 @var{sequences}.  The arguments @var{sequences} may be lists, vectors,
448 or strings.  If no @var{sequences} are given, an empty vector is
449 returned.
451 The value is a newly constructed vector that is not @code{eq} to any
452 existing vector.
454 @example
455 @group
456 (setq a (vconcat '(A B C) '(D E F)))
457      @result{} [A B C D E F]
458 (eq a (vconcat a))
459      @result{} nil
460 @end group
461 @group
462 (vconcat)
463      @result{} []
464 (vconcat [A B C] "aa" '(foo (6 7)))
465      @result{} [A B C 97 97 foo (6 7)]
466 @end group
467 @end example
469 The @code{vconcat} function also allows integers as arguments.  It
470 converts them to strings of digits, making up the decimal print
471 representation of the integer, and then uses the strings instead of the
472 original integers.  @strong{Don't use this feature; we plan to eliminate
473 it.  If you already use this feature, change your programs now!}  The
474 proper way to convert an integer to a decimal number in this way is with
475 @code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
476 (@pxref{String Conversion}).
478 For other concatenation functions, see @code{mapconcat} in @ref{Mapping
479 Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
480 in @ref{Building Lists}.
481 @end defun
483   The @code{append} function provides a way to convert a vector into a
484 list with the same elements (@pxref{Building Lists}):
486 @example
487 @group
488 (setq avector [1 two (quote (three)) "four" [five]])
489      @result{} [1 two (quote (three)) "four" [five]]
490 (append avector nil)
491      @result{} (1 two (quote (three)) "four" [five])
492 @end group
493 @end example