Mercurial > emacs
annotate doc/lispref/sequences.texi @ 104201:7c433d89bd4c
Add missing arch-tags
author | Carsten Dominik <dominik@science.uva.nl> |
---|---|
date | Sat, 08 Aug 2009 12:18:56 +0000 |
parents | 51056176663a |
children | 1d1d5d9bd884 |
rev | line source |
---|---|
84097 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, | |
100974 | 4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. |
84097 | 5 @c See the file elisp.texi for copying conditions. |
84116
0ba80d073e27
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84097
diff
changeset
|
6 @setfilename ../../info/sequences |
84097 | 7 @node Sequences Arrays Vectors, Hash Tables, Lists, Top |
8 @chapter Sequences, Arrays, and Vectors | |
9 @cindex sequence | |
10 | |
11 Recall that the @dfn{sequence} type is the union of two other Lisp | |
12 types: lists and arrays. In other words, any list is a sequence, and | |
13 any array is a sequence. The common property that all sequences have is | |
14 that each is an ordered collection of elements. | |
15 | |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
16 An @dfn{array} is a fixed-length object with a slot for each of its |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
17 elements. All the elements are accessible in constant time. The four |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
18 types of arrays are strings, vectors, char-tables and bool-vectors. |
84097 | 19 |
20 A list is a sequence of elements, but it is not a single primitive | |
21 object; it is made of cons cells, one cell per element. Finding the | |
22 @var{n}th element requires looking through @var{n} cons cells, so | |
23 elements farther from the beginning of the list take longer to access. | |
24 But it is possible to add elements to the list, or remove elements. | |
25 | |
26 The following diagram shows the relationship between these types: | |
27 | |
28 @example | |
29 @group | |
30 _____________________________________________ | |
31 | | | |
32 | Sequence | | |
33 | ______ ________________________________ | | |
34 | | | | | | | |
35 | | List | | Array | | | |
36 | | | | ________ ________ | | | |
37 | |______| | | | | | | | | |
38 | | | Vector | | String | | | | |
39 | | |________| |________| | | | |
40 | | ____________ _____________ | | | |
41 | | | | | | | | | |
42 | | | Char-table | | Bool-vector | | | | |
43 | | |____________| |_____________| | | | |
44 | |________________________________| | | |
45 |_____________________________________________| | |
46 @end group | |
47 @end example | |
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:: Special characteristics of Emacs Lisp vectors. | |
54 * Vector Functions:: Functions specifically for vectors. | |
55 * Char-Tables:: How to work with char-tables. | |
56 * Bool-Vectors:: How to work with bool-vectors. | |
57 @end menu | |
58 | |
59 @node Sequence Functions | |
60 @section Sequences | |
61 | |
62 In Emacs Lisp, a @dfn{sequence} is either a list or an array. The | |
63 common property of all sequences is that they are ordered collections of | |
64 elements. This section describes functions that accept any kind of | |
65 sequence. | |
66 | |
67 @defun sequencep object | |
68 Returns @code{t} if @var{object} is a list, vector, string, | |
69 bool-vector, or char-table, @code{nil} otherwise. | |
70 @end defun | |
71 | |
72 @defun length sequence | |
73 @cindex string length | |
74 @cindex list length | |
75 @cindex vector length | |
76 @cindex sequence length | |
77 @cindex char-table length | |
78 This function returns the number of elements in @var{sequence}. If | |
79 @var{sequence} is a dotted list, a @code{wrong-type-argument} error is | |
80 signaled. Circular lists may cause an infinite loop. For a | |
81 char-table, the value returned is always one more than the maximum | |
82 Emacs character code. | |
83 | |
84 @xref{Definition of safe-length}, for the related function @code{safe-length}. | |
85 | |
86 @example | |
87 @group | |
88 (length '(1 2 3)) | |
89 @result{} 3 | |
90 @end group | |
91 @group | |
92 (length ()) | |
93 @result{} 0 | |
94 @end group | |
95 @group | |
96 (length "foobar") | |
97 @result{} 6 | |
98 @end group | |
99 @group | |
100 (length [1 2 3]) | |
101 @result{} 3 | |
102 @end group | |
103 @group | |
104 (length (make-bool-vector 5 nil)) | |
105 @result{} 5 | |
106 @end group | |
107 @end example | |
108 @end defun | |
109 | |
110 @noindent | |
111 See also @code{string-bytes}, in @ref{Text Representations}. | |
112 | |
113 @defun elt sequence index | |
114 @cindex elements of sequences | |
115 This function returns the element of @var{sequence} indexed by | |
116 @var{index}. Legitimate values of @var{index} are integers ranging | |
117 from 0 up to one less than the length of @var{sequence}. If | |
118 @var{sequence} is a list, out-of-range values behave as for | |
119 @code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values | |
120 trigger an @code{args-out-of-range} error. | |
121 | |
122 @example | |
123 @group | |
124 (elt [1 2 3 4] 2) | |
125 @result{} 3 | |
126 @end group | |
127 @group | |
128 (elt '(1 2 3 4) 2) | |
129 @result{} 3 | |
130 @end group | |
131 @group | |
132 ;; @r{We use @code{string} to show clearly which character @code{elt} returns.} | |
133 (string (elt "1234" 2)) | |
134 @result{} "3" | |
135 @end group | |
136 @group | |
137 (elt [1 2 3 4] 4) | |
138 @error{} Args out of range: [1 2 3 4], 4 | |
139 @end group | |
140 @group | |
141 (elt [1 2 3 4] -1) | |
142 @error{} Args out of range: [1 2 3 4], -1 | |
143 @end group | |
144 @end example | |
145 | |
146 This function generalizes @code{aref} (@pxref{Array Functions}) and | |
147 @code{nth} (@pxref{Definition of nth}). | |
148 @end defun | |
149 | |
150 @defun copy-sequence sequence | |
151 @cindex copying sequences | |
152 Returns a copy of @var{sequence}. The copy is the same type of object | |
153 as the original sequence, and it has the same elements in the same order. | |
154 | |
155 Storing a new element into the copy does not affect the original | |
156 @var{sequence}, and vice versa. However, the elements of the new | |
157 sequence are not copies; they are identical (@code{eq}) to the elements | |
158 of the original. Therefore, changes made within these elements, as | |
159 found via the copied sequence, are also visible in the original | |
160 sequence. | |
161 | |
162 If the sequence is a string with text properties, the property list in | |
163 the copy is itself a copy, not shared with the original's property | |
164 list. However, the actual values of the properties are shared. | |
165 @xref{Text Properties}. | |
166 | |
167 This function does not work for dotted lists. Trying to copy a | |
168 circular list may cause an infinite loop. | |
169 | |
170 See also @code{append} in @ref{Building Lists}, @code{concat} in | |
171 @ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions}, | |
172 for other ways to copy sequences. | |
173 | |
174 @example | |
175 @group | |
176 (setq bar '(1 2)) | |
177 @result{} (1 2) | |
178 @end group | |
179 @group | |
180 (setq x (vector 'foo bar)) | |
181 @result{} [foo (1 2)] | |
182 @end group | |
183 @group | |
184 (setq y (copy-sequence x)) | |
185 @result{} [foo (1 2)] | |
186 @end group | |
187 | |
188 @group | |
189 (eq x y) | |
190 @result{} nil | |
191 @end group | |
192 @group | |
193 (equal x y) | |
194 @result{} t | |
195 @end group | |
196 @group | |
197 (eq (elt x 1) (elt y 1)) | |
198 @result{} t | |
199 @end group | |
200 | |
201 @group | |
202 ;; @r{Replacing an element of one sequence.} | |
203 (aset x 0 'quux) | |
204 x @result{} [quux (1 2)] | |
205 y @result{} [foo (1 2)] | |
206 @end group | |
207 | |
208 @group | |
209 ;; @r{Modifying the inside of a shared element.} | |
210 (setcar (aref x 1) 69) | |
211 x @result{} [quux (69 2)] | |
212 y @result{} [foo (69 2)] | |
213 @end group | |
214 @end example | |
215 @end defun | |
216 | |
217 @node Arrays | |
218 @section Arrays | |
219 @cindex array | |
220 | |
221 An @dfn{array} object has slots that hold a number of other Lisp | |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
222 objects, called the elements of the array. Any element of an array |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
223 may be accessed in constant time. In contrast, the time to access an |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
224 element of a list is proportional to the position of that element in |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
225 the list. |
84097 | 226 |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
227 Emacs defines four types of array, all one-dimensional: |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
228 @dfn{strings} (@pxref{String Type}), @dfn{vectors} (@pxref{Vector |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
229 Type}), @dfn{bool-vectors} (@pxref{Bool-Vector Type}), and |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
230 @dfn{char-tables} (@pxref{Char-Table Type}). Vectors and char-tables |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
231 can hold elements of any type, but strings can only hold characters, |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
232 and bool-vectors can only hold @code{t} and @code{nil}. |
84097 | 233 |
234 All four kinds of array share these characteristics: | |
235 | |
236 @itemize @bullet | |
237 @item | |
238 The first element of an array has index zero, the second element has | |
239 index 1, and so on. This is called @dfn{zero-origin} indexing. For | |
240 example, an array of four elements has indices 0, 1, 2, @w{and 3}. | |
241 | |
242 @item | |
243 The length of the array is fixed once you create it; you cannot | |
244 change the length of an existing array. | |
245 | |
246 @item | |
247 For purposes of evaluation, the array is a constant---in other words, | |
248 it evaluates to itself. | |
249 | |
250 @item | |
251 The elements of an array may be referenced or changed with the functions | |
252 @code{aref} and @code{aset}, respectively (@pxref{Array Functions}). | |
253 @end itemize | |
254 | |
255 When you create an array, other than a char-table, you must specify | |
256 its length. You cannot specify the length of a char-table, because that | |
257 is determined by the range of character codes. | |
258 | |
259 In principle, if you want an array of text characters, you could use | |
260 either a string or a vector. In practice, we always choose strings for | |
261 such applications, for four reasons: | |
262 | |
263 @itemize @bullet | |
264 @item | |
265 They occupy one-fourth the space of a vector of the same elements. | |
266 | |
267 @item | |
268 Strings are printed in a way that shows the contents more clearly | |
269 as text. | |
270 | |
271 @item | |
272 Strings can hold text properties. @xref{Text Properties}. | |
273 | |
274 @item | |
275 Many of the specialized editing and I/O facilities of Emacs accept only | |
276 strings. For example, you cannot insert a vector of characters into a | |
277 buffer the way you can insert a string. @xref{Strings and Characters}. | |
278 @end itemize | |
279 | |
280 By contrast, for an array of keyboard input characters (such as a key | |
281 sequence), a vector may be necessary, because many keyboard input | |
282 characters are outside the range that will fit in a string. @xref{Key | |
283 Sequence Input}. | |
284 | |
285 @node Array Functions | |
286 @section Functions that Operate on Arrays | |
287 | |
288 In this section, we describe the functions that accept all types of | |
289 arrays. | |
290 | |
291 @defun arrayp object | |
292 This function returns @code{t} if @var{object} is an array (i.e., a | |
293 vector, a string, a bool-vector or a char-table). | |
294 | |
295 @example | |
296 @group | |
297 (arrayp [a]) | |
298 @result{} t | |
299 (arrayp "asdf") | |
300 @result{} t | |
301 (arrayp (syntax-table)) ;; @r{A char-table.} | |
302 @result{} t | |
303 @end group | |
304 @end example | |
305 @end defun | |
306 | |
307 @defun aref array index | |
308 @cindex array elements | |
309 This function returns the @var{index}th element of @var{array}. The | |
310 first element is at index zero. | |
311 | |
312 @example | |
313 @group | |
314 (setq primes [2 3 5 7 11 13]) | |
315 @result{} [2 3 5 7 11 13] | |
316 (aref primes 4) | |
317 @result{} 11 | |
318 @end group | |
319 @group | |
320 (aref "abcdefg" 1) | |
321 @result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.} | |
322 @end group | |
323 @end example | |
324 | |
325 See also the function @code{elt}, in @ref{Sequence Functions}. | |
326 @end defun | |
327 | |
328 @defun aset array index object | |
329 This function sets the @var{index}th element of @var{array} to be | |
330 @var{object}. It returns @var{object}. | |
331 | |
332 @example | |
333 @group | |
334 (setq w [foo bar baz]) | |
335 @result{} [foo bar baz] | |
336 (aset w 0 'fu) | |
337 @result{} fu | |
338 w | |
339 @result{} [fu bar baz] | |
340 @end group | |
341 | |
342 @group | |
343 (setq x "asdfasfd") | |
344 @result{} "asdfasfd" | |
345 (aset x 3 ?Z) | |
346 @result{} 90 | |
347 x | |
348 @result{} "asdZasfd" | |
349 @end group | |
350 @end example | |
351 | |
352 If @var{array} is a string and @var{object} is not a character, a | |
353 @code{wrong-type-argument} error results. The function converts a | |
354 unibyte string to multibyte if necessary to insert a character. | |
355 @end defun | |
356 | |
357 @defun fillarray array object | |
358 This function fills the array @var{array} with @var{object}, so that | |
359 each element of @var{array} is @var{object}. It returns @var{array}. | |
360 | |
361 @example | |
362 @group | |
363 (setq a [a b c d e f g]) | |
364 @result{} [a b c d e f g] | |
365 (fillarray a 0) | |
366 @result{} [0 0 0 0 0 0 0] | |
367 a | |
368 @result{} [0 0 0 0 0 0 0] | |
369 @end group | |
370 @group | |
371 (setq s "When in the course") | |
372 @result{} "When in the course" | |
373 (fillarray s ?-) | |
374 @result{} "------------------" | |
375 @end group | |
376 @end example | |
377 | |
378 If @var{array} is a string and @var{object} is not a character, a | |
379 @code{wrong-type-argument} error results. | |
380 @end defun | |
381 | |
382 The general sequence functions @code{copy-sequence} and @code{length} | |
383 are often useful for objects known to be arrays. @xref{Sequence Functions}. | |
384 | |
385 @node Vectors | |
386 @section Vectors | |
387 @cindex vector (type) | |
388 | |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
389 A @dfn{vector} is a general-purpose array whose elements can be any |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
390 Lisp objects. (By contrast, the elements of a string can only be |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
391 characters. @xref{Strings and Characters}.) Vectors are used in |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
392 Emacs for many purposes: as key sequences (@pxref{Key Sequences}), as |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
393 symbol-lookup tables (@pxref{Creating Symbols}), as part of the |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
394 representation of a byte-compiled function (@pxref{Byte Compilation}), |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
395 and more. |
84097 | 396 |
397 In Emacs Lisp, the indices of the elements of a vector start from zero | |
398 and count up from there. | |
399 | |
400 Vectors are printed with square brackets surrounding the elements. | |
401 Thus, a vector whose elements are the symbols @code{a}, @code{b} and | |
402 @code{a} is printed as @code{[a b a]}. You can write vectors in the | |
403 same way in Lisp input. | |
404 | |
405 A vector, like a string or a number, is considered a constant for | |
406 evaluation: the result of evaluating it is the same vector. This does | |
407 not evaluate or even examine the elements of the vector. | |
408 @xref{Self-Evaluating Forms}. | |
409 | |
410 Here are examples illustrating these principles: | |
411 | |
412 @example | |
413 @group | |
414 (setq avector [1 two '(three) "four" [five]]) | |
415 @result{} [1 two (quote (three)) "four" [five]] | |
416 (eval avector) | |
417 @result{} [1 two (quote (three)) "four" [five]] | |
418 (eq avector (eval avector)) | |
419 @result{} t | |
420 @end group | |
421 @end example | |
422 | |
423 @node Vector Functions | |
424 @section Functions for Vectors | |
425 | |
426 Here are some functions that relate to vectors: | |
427 | |
428 @defun vectorp object | |
429 This function returns @code{t} if @var{object} is a vector. | |
430 | |
431 @example | |
432 @group | |
433 (vectorp [a]) | |
434 @result{} t | |
435 (vectorp "asdf") | |
436 @result{} nil | |
437 @end group | |
438 @end example | |
439 @end defun | |
440 | |
441 @defun vector &rest objects | |
442 This function creates and returns a vector whose elements are the | |
443 arguments, @var{objects}. | |
444 | |
445 @example | |
446 @group | |
447 (vector 'foo 23 [bar baz] "rats") | |
448 @result{} [foo 23 [bar baz] "rats"] | |
449 (vector) | |
450 @result{} [] | |
451 @end group | |
452 @end example | |
453 @end defun | |
454 | |
455 @defun make-vector length object | |
456 This function returns a new vector consisting of @var{length} elements, | |
457 each initialized to @var{object}. | |
458 | |
459 @example | |
460 @group | |
461 (setq sleepy (make-vector 9 'Z)) | |
462 @result{} [Z Z Z Z Z Z Z Z Z] | |
463 @end group | |
464 @end example | |
465 @end defun | |
466 | |
467 @defun vconcat &rest sequences | |
468 @cindex copying vectors | |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
469 This function returns a new vector containing all the elements of |
84097 | 470 @var{sequences}. The arguments @var{sequences} may be true lists, |
471 vectors, strings or bool-vectors. If no @var{sequences} are given, an | |
472 empty vector is returned. | |
473 | |
474 The value is a newly constructed vector that is not @code{eq} to any | |
475 existing vector. | |
476 | |
477 @example | |
478 @group | |
479 (setq a (vconcat '(A B C) '(D E F))) | |
480 @result{} [A B C D E F] | |
481 (eq a (vconcat a)) | |
482 @result{} nil | |
483 @end group | |
484 @group | |
485 (vconcat) | |
486 @result{} [] | |
487 (vconcat [A B C] "aa" '(foo (6 7))) | |
488 @result{} [A B C 97 97 foo (6 7)] | |
489 @end group | |
490 @end example | |
491 | |
492 The @code{vconcat} function also allows byte-code function objects as | |
493 arguments. This is a special feature to make it easy to access the entire | |
494 contents of a byte-code function object. @xref{Byte-Code Objects}. | |
495 | |
496 For other concatenation functions, see @code{mapconcat} in @ref{Mapping | |
497 Functions}, @code{concat} in @ref{Creating Strings}, and @code{append} | |
498 in @ref{Building Lists}. | |
499 @end defun | |
500 | |
501 The @code{append} function also provides a way to convert a vector into a | |
502 list with the same elements: | |
503 | |
504 @example | |
505 @group | |
506 (setq avector [1 two (quote (three)) "four" [five]]) | |
507 @result{} [1 two (quote (three)) "four" [five]] | |
508 (append avector nil) | |
509 @result{} (1 two (quote (three)) "four" [five]) | |
510 @end group | |
511 @end example | |
512 | |
513 @node Char-Tables | |
514 @section Char-Tables | |
515 @cindex char-tables | |
516 @cindex extra slots of char-table | |
517 | |
518 A char-table is much like a vector, except that it is indexed by | |
519 character codes. Any valid character code, without modifiers, can be | |
520 used as an index in a char-table. You can access a char-table's | |
521 elements with @code{aref} and @code{aset}, as with any array. In | |
522 addition, a char-table can have @dfn{extra slots} to hold additional | |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
523 data not associated with particular character codes. Like vectors, |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
524 char-tables are constants when evaluated, and can hold elements of any |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
525 type. |
84097 | 526 |
527 @cindex subtype of char-table | |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
528 Each char-table has a @dfn{subtype}, a symbol, which serves two |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
529 purposes: |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
530 |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
531 @itemize @bullet |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
532 @item |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
533 The subtype provides an easy way to tell what the char-table is for. |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
534 For instance, display tables are char-tables with @code{display-table} |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
535 as the subtype, and syntax tables are char-tables with |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
536 @code{syntax-table} as the subtype. The subtype can be queried using |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
537 the function @code{char-table-subtype}, described below. |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
538 |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
539 @item |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
540 The subtype controls the number of @dfn{extra slots} in the |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
541 char-table. This number is specified by the subtype's |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
542 @code{char-table-extra-slots} symbol property, which should be an |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
543 integer between 0 and 10. If the subtype has no such symbol property, |
102194
51056176663a
(Char-Tables): Link to Property Lists node.
Chong Yidong <cyd@stupidchicken.com>
parents:
102190
diff
changeset
|
544 the char-table has no extra slots. @xref{Property Lists}, for |
51056176663a
(Char-Tables): Link to Property Lists node.
Chong Yidong <cyd@stupidchicken.com>
parents:
102190
diff
changeset
|
545 information about symbol properties. |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
546 @end itemize |
84097 | 547 |
548 @cindex parent of char-table | |
549 A char-table can have a @dfn{parent}, which is another char-table. If | |
550 it does, then whenever the char-table specifies @code{nil} for a | |
551 particular character @var{c}, it inherits the value specified in the | |
552 parent. In other words, @code{(aref @var{char-table} @var{c})} returns | |
553 the value from the parent of @var{char-table} if @var{char-table} itself | |
554 specifies @code{nil}. | |
555 | |
556 @cindex default value of char-table | |
557 A char-table can also have a @dfn{default value}. If so, then | |
558 @code{(aref @var{char-table} @var{c})} returns the default value | |
559 whenever the char-table does not specify any other non-@code{nil} value. | |
560 | |
561 @defun make-char-table subtype &optional init | |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
562 Return a newly-created char-table, with subtype @var{subtype} (a |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
563 symbol). Each element is initialized to @var{init}, which defaults to |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
564 @code{nil}. You cannot alter the subtype of a char-table after the |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
565 char-table is created. |
84097 | 566 |
567 There is no argument to specify the length of the char-table, because | |
568 all char-tables have room for any valid character code as an index. | |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
569 |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
570 If @var{subtype} has the @code{char-table-extra-slots} symbol |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
571 property, that specifies the number of extra slots in the char-table. |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
572 This should be an integer between 0 and 10; otherwise, |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
573 @code{make-char-table} raises an error. If @var{subtype} has no |
102194
51056176663a
(Char-Tables): Link to Property Lists node.
Chong Yidong <cyd@stupidchicken.com>
parents:
102190
diff
changeset
|
574 @code{char-table-extra-slots} symbol property (@pxref{Property |
51056176663a
(Char-Tables): Link to Property Lists node.
Chong Yidong <cyd@stupidchicken.com>
parents:
102190
diff
changeset
|
575 Lists}), the char-table has no extra slots. |
84097 | 576 @end defun |
577 | |
578 @defun char-table-p object | |
102190
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
579 This function returns @code{t} if @var{object} is a char-table, and |
220614a1aa60
(Sequences Arrays Vectors): Make introduction more concise.
Chong Yidong <cyd@stupidchicken.com>
parents:
102180
diff
changeset
|
580 @code{nil} otherwise. |
84097 | 581 @end defun |
582 | |
583 @defun char-table-subtype char-table | |
584 This function returns the subtype symbol of @var{char-table}. | |
585 @end defun | |
586 | |
587 There is no special function to access default values in a char-table. | |
588 To do that, use @code{char-table-range} (see below). | |
589 | |
590 @defun char-table-parent char-table | |
591 This function returns the parent of @var{char-table}. The parent is | |
592 always either @code{nil} or another char-table. | |
593 @end defun | |
594 | |
595 @defun set-char-table-parent char-table new-parent | |
596 This function sets the parent of @var{char-table} to @var{new-parent}. | |
597 @end defun | |
598 | |
599 @defun char-table-extra-slot char-table n | |
600 This function returns the contents of extra slot @var{n} of | |
601 @var{char-table}. The number of extra slots in a char-table is | |
602 determined by its subtype. | |
603 @end defun | |
604 | |
605 @defun set-char-table-extra-slot char-table n value | |
606 This function stores @var{value} in extra slot @var{n} of | |
607 @var{char-table}. | |
608 @end defun | |
609 | |
610 A char-table can specify an element value for a single character code; | |
611 it can also specify a value for an entire character set. | |
612 | |
613 @defun char-table-range char-table range | |
614 This returns the value specified in @var{char-table} for a range of | |
615 characters @var{range}. Here are the possibilities for @var{range}: | |
616 | |
617 @table @asis | |
618 @item @code{nil} | |
619 Refers to the default value. | |
620 | |
621 @item @var{char} | |
622 Refers to the element for character @var{char} | |
623 (supposing @var{char} is a valid character code). | |
624 | |
98711
43065c518c41
(Char-Tables): Remove documentation of set-char-table-default, which has no
Eli Zaretskii <eliz@gnu.org>
parents:
98704
diff
changeset
|
625 @item @code{(@var{from} . @var{to})} |
43065c518c41
(Char-Tables): Remove documentation of set-char-table-default, which has no
Eli Zaretskii <eliz@gnu.org>
parents:
98704
diff
changeset
|
626 A cons cell refers to all the characters in the inclusive range |
43065c518c41
(Char-Tables): Remove documentation of set-char-table-default, which has no
Eli Zaretskii <eliz@gnu.org>
parents:
98704
diff
changeset
|
627 @samp{[@var{from}..@var{to}]}. |
84097 | 628 @end table |
629 @end defun | |
630 | |
631 @defun set-char-table-range char-table range value | |
632 This function sets the value in @var{char-table} for a range of | |
633 characters @var{range}. Here are the possibilities for @var{range}: | |
634 | |
635 @table @asis | |
636 @item @code{nil} | |
637 Refers to the default value. | |
638 | |
639 @item @code{t} | |
640 Refers to the whole range of character codes. | |
641 | |
642 @item @var{char} | |
643 Refers to the element for character @var{char} | |
644 (supposing @var{char} is a valid character code). | |
645 | |
98711
43065c518c41
(Char-Tables): Remove documentation of set-char-table-default, which has no
Eli Zaretskii <eliz@gnu.org>
parents:
98704
diff
changeset
|
646 @item @code{(@var{from} . @var{to})} |
43065c518c41
(Char-Tables): Remove documentation of set-char-table-default, which has no
Eli Zaretskii <eliz@gnu.org>
parents:
98704
diff
changeset
|
647 A cons cell refers to all the characters in the inclusive range |
43065c518c41
(Char-Tables): Remove documentation of set-char-table-default, which has no
Eli Zaretskii <eliz@gnu.org>
parents:
98704
diff
changeset
|
648 @samp{[@var{from}..@var{to}]}. |
84097 | 649 @end table |
650 @end defun | |
651 | |
652 @defun map-char-table function char-table | |
98774
68912c77122d
(Char-Tables): Fix wording in last change.
Eli Zaretskii <eliz@gnu.org>
parents:
98711
diff
changeset
|
653 This function calls its argument @var{function} for each element of |
68912c77122d
(Char-Tables): Fix wording in last change.
Eli Zaretskii <eliz@gnu.org>
parents:
98711
diff
changeset
|
654 @var{char-table} that has a non-@code{nil} value. The call to |
68912c77122d
(Char-Tables): Fix wording in last change.
Eli Zaretskii <eliz@gnu.org>
parents:
98711
diff
changeset
|
655 @var{function} is with two arguments, a key and a value. The key |
84097 | 656 is a possible @var{range} argument for @code{char-table-range}---either |
98704
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
657 a valid character or a cons cell @code{(@var{from} . @var{to})}, |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
658 specifying a range of characters that share the same value. The value is |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
659 what @code{(char-table-range @var{char-table} @var{key})} returns. |
84097 | 660 |
661 Overall, the key-value pairs passed to @var{function} describe all the | |
662 values stored in @var{char-table}. | |
663 | |
98704
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
664 The return value is always @code{nil}; to make calls to |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
665 @code{map-char-table} useful, @var{function} should have side effects. |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
666 For example, here is how to examine the elements of the syntax table: |
84097 | 667 |
668 @example | |
669 (let (accumulator) | |
98704
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
670 (map-char-table |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
671 #'(lambda (key value) |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
672 (setq accumulator |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
673 (cons (list |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
674 (if (consp key) |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
675 (list (car key) (cdr key)) |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
676 key) |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
677 value) |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
678 accumulator))) |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
679 (syntax-table)) |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
680 accumulator) |
84097 | 681 @result{} |
98704
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
682 (((2597602 4194303) (2)) ((2597523 2597601) (3)) |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
683 ... (65379 (5 . 65378)) (65378 (4 . 65379)) (65377 (1)) |
92d4fd43578c
(Char-Tables): `map-char-table' can now call its argument FUNCTION with
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
684 ... (12 (0)) (11 (3)) (10 (12)) (9 (0)) ((0 8) (3))) |
84097 | 685 @end example |
686 @end defun | |
687 | |
688 @node Bool-Vectors | |
689 @section Bool-vectors | |
690 @cindex Bool-vectors | |
691 | |
692 A bool-vector is much like a vector, except that it stores only the | |
693 values @code{t} and @code{nil}. If you try to store any non-@code{nil} | |
694 value into an element of the bool-vector, the effect is to store | |
695 @code{t} there. As with all arrays, bool-vector indices start from 0, | |
696 and the length cannot be changed once the bool-vector is created. | |
697 Bool-vectors are constants when evaluated. | |
698 | |
699 There are two special functions for working with bool-vectors; aside | |
700 from that, you manipulate them with same functions used for other kinds | |
701 of arrays. | |
702 | |
703 @defun make-bool-vector length initial | |
704 Return a new bool-vector of @var{length} elements, | |
705 each one initialized to @var{initial}. | |
706 @end defun | |
707 | |
708 @defun bool-vector-p object | |
709 This returns @code{t} if @var{object} is a bool-vector, | |
710 and @code{nil} otherwise. | |
711 @end defun | |
712 | |
713 Here is an example of creating, examining, and updating a | |
714 bool-vector. Note that the printed form represents up to 8 boolean | |
715 values as a single character. | |
716 | |
717 @example | |
718 (setq bv (make-bool-vector 5 t)) | |
719 @result{} #&5"^_" | |
720 (aref bv 1) | |
721 @result{} t | |
722 (aset bv 3 nil) | |
723 @result{} nil | |
724 bv | |
725 @result{} #&5"^W" | |
726 @end example | |
727 | |
728 @noindent | |
729 These results make sense because the binary codes for control-_ and | |
730 control-W are 11111 and 10111, respectively. | |
731 | |
732 @ignore | |
733 arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386 | |
734 @end ignore |