Commit | Line | Data |
---|---|---|
4672ee8f RS |
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 | |
9 | ||
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. | |
15 | ||
79d11238 RS |
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 | |
bfe721d1 KH |
18 | length of an existing array cannot be changed. Strings and vectors are |
19 | the two types of arrays. | |
79d11238 RS |
20 | |
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. | |
4672ee8f RS |
26 | |
27 | The following diagram shows the relationship between these types: | |
28 | ||
29 | @example | |
30 | @group | |
79d11238 RS |
31 | ___________________________________ |
32 | | | | |
33 | | Sequence | | |
34 | | ______ ______________________ | | |
35 | | | | | | | | |
36 | | | List | | Array | | | |
37 | | | | | ________ _______ | | | |
38 | | |______| | | | | | | | | |
bfe721d1 | 39 | | | | Vector | | String| | | |
79d11238 RS |
40 | | | |________| |_______| | | |
41 | | |______________________| | | |
42 | |___________________________________| | |
4672ee8f RS |
43 | @end group |
44 | @end example | |
45 | ||
46 | The elements of vectors and lists may be any Lisp objects. The | |
47 | elements of strings are all characters. | |
48 | ||
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. | |
79d11238 RS |
53 | * Vectors:: Special characteristics of Emacs Lisp vectors. |
54 | * Vector Functions:: Functions specifically for vectors. | |
4672ee8f RS |
55 | @end menu |
56 | ||
57 | @node Sequence Functions | |
58 | @section Sequences | |
59 | ||
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. | |
64 | ||
65 | @defun sequencep object | |
66 | Returns @code{t} if @var{object} is a list, vector, or | |
67 | string, @code{nil} otherwise. | |
68 | @end defun | |
69 | ||
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. | |
74 | ||
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. | |
81 | ||
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}. | |
86 | ||
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. | |
90 | ||
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 | |
104 | ||
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 | |
117 | ||
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 | |
124 | ||
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 | |
133 | ||
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. | |
142 | ||
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 | |
162 | ||
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. | |
170 | ||
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 | |
193 | ||
bfe721d1 KH |
194 | This function generalizes @code{aref} (@pxref{Array Functions}) and |
195 | @code{nth} (@pxref{List Elements}). | |
4672ee8f RS |
196 | @end defun |
197 | ||
198 | @node Arrays | |
199 | @section Arrays | |
200 | @cindex array | |
201 | ||
79d11238 | 202 | An @dfn{array} object has slots that hold a number of other Lisp |
4672ee8f RS |
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. | |
207 | ||
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 | |
79d11238 RS |
211 | created; you cannot add or remove elements. However, you can replace an |
212 | element with a different value. | |
4672ee8f RS |
213 | |
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}. | |
220 | ||
79d11238 | 221 | Both kinds of array share these characteristics: |
4672ee8f RS |
222 | |
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}. | |
228 | ||
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 | |
233 | ||
bfe721d1 KH |
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: | |
4672ee8f RS |
237 | |
238 | @itemize @bullet | |
239 | @item | |
240 | They occupy one-fourth the space of a vector of the same elements. | |
241 | ||
242 | @item | |
243 | Strings are printed in a way that shows the contents more clearly | |
244 | as characters. | |
245 | ||
246 | @item | |
247 | Strings can hold text properties. @xref{Text Properties}. | |
248 | ||
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 | |
254 | ||
bfe721d1 KH |
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}. | |
259 | ||
4672ee8f RS |
260 | @node Array Functions |
261 | @section Functions that Operate on Arrays | |
262 | ||
263 | In this section, we describe the functions that accept both strings | |
264 | and vectors. | |
265 | ||
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). | |
269 | ||
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 | |
279 | ||
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. | |
284 | ||
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 | |
294 | ||
295 | @group | |
296 | (aref "abcdefg" 1) | |
297 | @result{} 98 ; @r{@samp{b} is @sc{ASCII} code 98.} | |
298 | @end group | |
299 | @end example | |
300 | ||
301 | See also the function @code{elt}, in @ref{Sequence Functions}. | |
302 | @end defun | |
303 | ||
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}. | |
307 | ||
308 | @example | |
309 | @group | |
310 | (setq w [foo bar baz]) | |
311 | @result{} [foo bar baz] | |
312 | (aset w 0 'fu) | |
313 | @result{} fu | |
314 | w | |
315 | @result{} [fu bar baz] | |
316 | @end group | |
317 | ||
318 | @group | |
319 | (setq x "asdfasfd") | |
320 | @result{} "asdfasfd" | |
321 | (aset x 3 ?Z) | |
322 | @result{} 90 | |
323 | x | |
324 | @result{} "asdZasfd" | |
325 | @end group | |
326 | @end example | |
327 | ||
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 | |
331 | ||
332 | @defun fillarray array object | |
79d11238 RS |
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}. | |
4672ee8f RS |
335 | |
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] | |
342 | a | |
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 | |
352 | ||
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 | |
356 | ||
357 | The general sequence functions @code{copy-sequence} and @code{length} | |
358 | are often useful for objects known to be arrays. @xref{Sequence Functions}. | |
359 | ||
360 | @node Vectors | |
361 | @section Vectors | |
362 | @cindex vector | |
363 | ||
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. | |
373 | ||
374 | In Emacs Lisp, the indices of the elements of a vector start from zero | |
375 | and count up from there. | |
376 | ||
79d11238 RS |
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. | |
4672ee8f RS |
381 | |
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}. | |
386 | ||
387 | Here are examples of these principles: | |
388 | ||
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 | |
399 | ||
79d11238 RS |
400 | @node Vector Functions |
401 | @section Functions That Operate on Vectors | |
402 | ||
4672ee8f RS |
403 | Here are some functions that relate to vectors: |
404 | ||
405 | @defun vectorp object | |
406 | This function returns @code{t} if @var{object} is a vector. | |
407 | ||
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 | |
417 | ||
418 | @defun vector &rest objects | |
419 | This function creates and returns a vector whose elements are the | |
420 | arguments, @var{objects}. | |
421 | ||
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 | |
431 | ||
432 | @defun make-vector length object | |
433 | This function returns a new vector consisting of @var{length} elements, | |
434 | each initialized to @var{object}. | |
435 | ||
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 | |
443 | ||
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. | |
450 | ||
451 | The value is a newly constructed vector that is not @code{eq} to any | |
452 | existing vector. | |
453 | ||
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 | |
468 | ||
22697dac KH |
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 | |
4672ee8f RS |
475 | @code{format} (@pxref{Formatting Strings}) or @code{number-to-string} |
476 | (@pxref{String Conversion}). | |
477 | ||
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 | |
482 | ||
483 | The @code{append} function provides a way to convert a vector into a | |
484 | list with the same elements (@pxref{Building Lists}): | |
485 | ||
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 |