Mercurial > emacs
comparison lispref/sequences.texi @ 6374:71e61b314fe9
Initial revision
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Wed, 16 Mar 1994 05:25:03 +0000 |
parents | |
children | 19bd3bfc57de |
comparison
equal
deleted
inserted
replaced
6373:284634d109ee | 6374:71e61b314fe9 |
---|---|
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 | |
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 | |
23 remove elements. | |
24 | |
25 The following diagram shows the relationship between these types: | |
26 | |
27 @example | |
28 @group | |
29 ___________________________________ | |
30 | | | |
31 | Sequence | | |
32 | ______ ______________________ | | |
33 | | | | | | | |
34 | | List | | Array | | | |
35 | | | | ________ _______ | | | |
36 | |______| | | | | | | | | |
37 | | | String | | Vector| | | | |
38 | | |________| |_______| | | | |
39 | |______________________| | | |
40 |___________________________________| | |
41 | |
42 @center @r{The relationship between sequences, arrays, and vectors} | |
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. | |
53 * Vectors:: Functions specifically for vectors. | |
54 @end menu | |
55 | |
56 @node Sequence Functions | |
57 @section Sequences | |
58 | |
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. | |
63 | |
64 @defun sequencep object | |
65 Returns @code{t} if @var{object} is a list, vector, or | |
66 string, @code{nil} otherwise. | |
67 @end defun | |
68 | |
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. | |
73 | |
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 | |
79 sequence. | |
80 | |
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}. | |
85 | |
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. | |
89 | |
90 @example | |
91 @group | |
92 (setq bar '(1 2)) | |
93 @result{} (1 2) | |
94 @end group | |
95 @group | |
96 (setq x (vector 'foo bar)) | |
97 @result{} [foo (1 2)] | |
98 @end group | |
99 @group | |
100 (setq y (copy-sequence x)) | |
101 @result{} [foo (1 2)] | |
102 @end group | |
103 | |
104 @group | |
105 (eq x y) | |
106 @result{} nil | |
107 @end group | |
108 @group | |
109 (equal x y) | |
110 @result{} t | |
111 @end group | |
112 @group | |
113 (eq (elt x 1) (elt y 1)) | |
114 @result{} t | |
115 @end group | |
116 | |
117 @group | |
118 ;; @r{Replacing an element of one sequence.} | |
119 (aset x 0 'quux) | |
120 x @result{} [quux (1 2)] | |
121 y @result{} [foo (1 2)] | |
122 @end group | |
123 | |
124 @group | |
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)] | |
129 @end group | |
130 @end example | |
131 @end defun | |
132 | |
133 @defun length sequence | |
134 @cindex string length | |
135 @cindex list 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. | |
141 | |
142 @example | |
143 @group | |
144 (length '(1 2 3)) | |
145 @result{} 3 | |
146 @end group | |
147 @group | |
148 (length ()) | |
149 @result{} 0 | |
150 @end group | |
151 @group | |
152 (length "foobar") | |
153 @result{} 6 | |
154 @end group | |
155 @group | |
156 (length [1 2 3]) | |
157 @result{} 3 | |
158 @end group | |
159 @end example | |
160 @end defun | |
161 | |
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. | |
169 | |
170 @example | |
171 @group | |
172 (elt [1 2 3 4] 2) | |
173 @result{} 3 | |
174 @end group | |
175 @group | |
176 (elt '(1 2 3 4) 2) | |
177 @result{} 3 | |
178 @end group | |
179 @group | |
180 (char-to-string (elt "1234" 2)) | |
181 @result{} "3" | |
182 @end group | |
183 @group | |
184 (elt [1 2 3 4] 4) | |
185 @error{}Args out of range: [1 2 3 4], 4 | |
186 @end group | |
187 @group | |
188 (elt [1 2 3 4] -1) | |
189 @error{}Args out of range: [1 2 3 4], -1 | |
190 @end group | |
191 @end example | |
192 | |
193 This function duplicates @code{aref} (@pxref{Array Functions}) and | |
194 @code{nth} (@pxref{List Elements}), except that it works for any kind of | |
195 sequence. | |
196 @end defun | |
197 | |
198 @node Arrays | |
199 @section Arrays | |
200 @cindex array | |
201 | |
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 | |
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 | |
211 created. You cannot add or remove elements. However, you can replace | |
212 an element with a different value. | |
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 | |
221 Both kinds of arrays share these characteristics: | |
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 | |
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: | |
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 | |
255 @node Array Functions | |
256 @section Functions that Operate on Arrays | |
257 | |
258 In this section, we describe the functions that accept both strings | |
259 and vectors. | |
260 | |
261 @defun arrayp object | |
262 This function returns @code{t} if @var{object} is an array (i.e., either a | |
263 vector or a string). | |
264 | |
265 @example | |
266 @group | |
267 (arrayp [a]) | |
268 @result{} t | |
269 (arrayp "asdf") | |
270 @result{} t | |
271 @end group | |
272 @end example | |
273 @end defun | |
274 | |
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. | |
279 | |
280 @example | |
281 @group | |
282 (setq primes [2 3 5 7 11 13]) | |
283 @result{} [2 3 5 7 11 13] | |
284 (aref primes 4) | |
285 @result{} 11 | |
286 (elt primes 4) | |
287 @result{} 11 | |
288 @end group | |
289 | |
290 @group | |
291 (aref "abcdefg" 1) | |
292 @result{} 98 ; @r{@samp{b} is @sc{ASCII} code 98.} | |
293 @end group | |
294 @end example | |
295 | |
296 See also the function @code{elt}, in @ref{Sequence Functions}. | |
297 @end defun | |
298 | |
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}. | |
302 | |
303 @example | |
304 @group | |
305 (setq w [foo bar baz]) | |
306 @result{} [foo bar baz] | |
307 (aset w 0 'fu) | |
308 @result{} fu | |
309 w | |
310 @result{} [fu bar baz] | |
311 @end group | |
312 | |
313 @group | |
314 (setq x "asdfasfd") | |
315 @result{} "asdfasfd" | |
316 (aset x 3 ?Z) | |
317 @result{} 90 | |
318 x | |
319 @result{} "asdZasfd" | |
320 @end group | |
321 @end example | |
322 | |
323 If @var{array} is a string and @var{object} is not a character, a | |
324 @code{wrong-type-argument} error results. | |
325 @end defun | |
326 | |
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}. | |
330 | |
331 @example | |
332 @group | |
333 (setq a [a b c d e f g]) | |
334 @result{} [a b c d e f g] | |
335 (fillarray a 0) | |
336 @result{} [0 0 0 0 0 0 0] | |
337 a | |
338 @result{} [0 0 0 0 0 0 0] | |
339 @end group | |
340 @group | |
341 (setq s "When in the course") | |
342 @result{} "When in the course" | |
343 (fillarray s ?-) | |
344 @result{} "------------------" | |
345 @end group | |
346 @end example | |
347 | |
348 If @var{array} is a string and @var{object} is not a character, a | |
349 @code{wrong-type-argument} error results. | |
350 @end defun | |
351 | |
352 The general sequence functions @code{copy-sequence} and @code{length} | |
353 are often useful for objects known to be arrays. @xref{Sequence Functions}. | |
354 | |
355 @node Vectors | |
356 @section Vectors | |
357 @cindex vector | |
358 | |
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 | |
367 a vector in it. | |
368 | |
369 In Emacs Lisp, the indices of the elements of a vector start from zero | |
370 and count up from there. | |
371 | |
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. | |
376 | |
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}. | |
381 | |
382 Here are examples of these principles: | |
383 | |
384 @example | |
385 @group | |
386 (setq avector [1 two '(three) "four" [five]]) | |
387 @result{} [1 two (quote (three)) "four" [five]] | |
388 (eval avector) | |
389 @result{} [1 two (quote (three)) "four" [five]] | |
390 (eq avector (eval avector)) | |
391 @result{} t | |
392 @end group | |
393 @end example | |
394 | |
395 Here are some functions that relate to vectors: | |
396 | |
397 @defun vectorp object | |
398 This function returns @code{t} if @var{object} is a vector. | |
399 | |
400 @example | |
401 @group | |
402 (vectorp [a]) | |
403 @result{} t | |
404 (vectorp "asdf") | |
405 @result{} nil | |
406 @end group | |
407 @end example | |
408 @end defun | |
409 | |
410 @defun vector &rest objects | |
411 This function creates and returns a vector whose elements are the | |
412 arguments, @var{objects}. | |
413 | |
414 @example | |
415 @group | |
416 (vector 'foo 23 [bar baz] "rats") | |
417 @result{} [foo 23 [bar baz] "rats"] | |
418 (vector) | |
419 @result{} [] | |
420 @end group | |
421 @end example | |
422 @end defun | |
423 | |
424 @defun make-vector length object | |
425 This function returns a new vector consisting of @var{length} elements, | |
426 each initialized to @var{object}. | |
427 | |
428 @example | |
429 @group | |
430 (setq sleepy (make-vector 9 'Z)) | |
431 @result{} [Z Z Z Z Z Z Z Z Z] | |
432 @end group | |
433 @end example | |
434 @end defun | |
435 | |
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 | |
441 returned. | |
442 | |
443 The value is a newly constructed vector that is not @code{eq} to any | |
444 existing vector. | |
445 | |
446 @example | |
447 @group | |
448 (setq a (vconcat '(A B C) '(D E F))) | |
449 @result{} [A B C D E F] | |
450 (eq a (vconcat a)) | |
451 @result{} nil | |
452 @end group | |
453 @group | |
454 (vconcat) | |
455 @result{} [] | |
456 (vconcat [A B C] "aa" '(foo (6 7))) | |
457 @result{} [A B C 97 97 foo (6 7)] | |
458 @end group | |
459 @end example | |
460 | |
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}). | |
468 | |
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}. | |
472 @end defun | |
473 | |
474 The @code{append} function provides a way to convert a vector into a | |
475 list with the same elements (@pxref{Building Lists}): | |
476 | |
477 @example | |
478 @group | |
479 (setq avector [1 two (quote (three)) "four" [five]]) | |
480 @result{} [1 two (quote (three)) "four" [five]] | |
481 (append avector nil) | |
482 @result{} (1 two (quote (three)) "four" [five]) | |
483 @end group | |
484 @end example |