Mercurial > emacs
annotate lispref/sequences.texi @ 21009:f3149849a051
(change-log-font-lock-keywords): Recognize + in date.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Sun, 01 Mar 1998 22:22:58 +0000 |
parents | 66d807bdc5b4 |
children | 90da2489c498 |
rev | line source |
---|---|
6374 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. |
6374 | 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 | |
7119 | 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 | |
12098 | 18 length of an existing array cannot be changed. Strings and vectors are |
19 the two types of arrays. | |
7119 | 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. | |
6374 | 26 |
27 The following diagram shows the relationship between these types: | |
28 | |
29 @example | |
30 @group | |
7119 | 31 ___________________________________ |
32 | | | |
33 | Sequence | | |
34 | ______ ______________________ | | |
35 | | | | | | | |
36 | | List | | Array | | | |
37 | | | | ________ _______ | | | |
38 | |______| | | | | | | | | |
12098 | 39 | | | Vector | | String| | | |
7119 | 40 | | |________| |_______| | | |
41 | |______________________| | | |
42 |___________________________________| | |
6374 | 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. | |
7119 | 53 * Vectors:: Special characteristics of Emacs Lisp vectors. |
54 * Vector Functions:: Functions specifically for vectors. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
55 * Char-Tables:: How to work with char-tables. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
56 * Bool-Vectors:: How to work with bool-vectors. |
6374 | 57 @end menu |
58 | |
59 @node Sequence Functions | |
60 @section Sequences | |
61 | |
62 In Emacs Lisp, a @dfn{sequence} is either a list, a vector or a | |
63 string. The common property that all sequences have is that each is an | |
64 ordered collection of elements. This section describes functions that | |
65 accept any kind of sequence. | |
66 | |
67 @defun sequencep object | |
68 Returns @code{t} if @var{object} is a list, vector, or | |
69 string, @code{nil} otherwise. | |
70 @end defun | |
71 | |
72 @defun copy-sequence sequence | |
73 @cindex copying sequences | |
74 Returns a copy of @var{sequence}. The copy is the same type of object | |
75 as the original sequence, and it has the same elements in the same order. | |
76 | |
77 Storing a new element into the copy does not affect the original | |
78 @var{sequence}, and vice versa. However, the elements of the new | |
79 sequence are not copies; they are identical (@code{eq}) to the elements | |
80 of the original. Therefore, changes made within these elements, as | |
81 found via the copied sequence, are also visible in the original | |
82 sequence. | |
83 | |
84 If the sequence is a string with text properties, the property list in | |
85 the copy is itself a copy, not shared with the original's property | |
86 list. However, the actual values of the properties are shared. | |
87 @xref{Text Properties}. | |
88 | |
89 See also @code{append} in @ref{Building Lists}, @code{concat} in | |
90 @ref{Creating Strings}, and @code{vconcat} in @ref{Vectors}, for others | |
91 ways to copy sequences. | |
92 | |
93 @example | |
94 @group | |
95 (setq bar '(1 2)) | |
96 @result{} (1 2) | |
97 @end group | |
98 @group | |
99 (setq x (vector 'foo bar)) | |
100 @result{} [foo (1 2)] | |
101 @end group | |
102 @group | |
103 (setq y (copy-sequence x)) | |
104 @result{} [foo (1 2)] | |
105 @end group | |
106 | |
107 @group | |
108 (eq x y) | |
109 @result{} nil | |
110 @end group | |
111 @group | |
112 (equal x y) | |
113 @result{} t | |
114 @end group | |
115 @group | |
116 (eq (elt x 1) (elt y 1)) | |
117 @result{} t | |
118 @end group | |
119 | |
120 @group | |
121 ;; @r{Replacing an element of one sequence.} | |
122 (aset x 0 'quux) | |
123 x @result{} [quux (1 2)] | |
124 y @result{} [foo (1 2)] | |
125 @end group | |
126 | |
127 @group | |
128 ;; @r{Modifying the inside of a shared element.} | |
129 (setcar (aref x 1) 69) | |
130 x @result{} [quux (69 2)] | |
131 y @result{} [foo (69 2)] | |
132 @end group | |
133 @end example | |
134 @end defun | |
135 | |
136 @defun length sequence | |
137 @cindex string length | |
138 @cindex list length | |
139 @cindex vector length | |
140 @cindex sequence length | |
141 Returns the number of elements in @var{sequence}. If @var{sequence} is | |
142 a cons cell that is not a list (because the final @sc{cdr} is not | |
143 @code{nil}), a @code{wrong-type-argument} error is signaled. | |
144 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
145 @xref{List Elements}, for the related function @code{safe-list}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
146 |
6374 | 147 @example |
148 @group | |
149 (length '(1 2 3)) | |
150 @result{} 3 | |
151 @end group | |
152 @group | |
153 (length ()) | |
154 @result{} 0 | |
155 @end group | |
156 @group | |
157 (length "foobar") | |
158 @result{} 6 | |
159 @end group | |
160 @group | |
161 (length [1 2 3]) | |
162 @result{} 3 | |
163 @end group | |
164 @end example | |
165 @end defun | |
166 | |
167 @defun elt sequence index | |
168 @cindex elements of sequences | |
169 This function returns the element of @var{sequence} indexed by | |
170 @var{index}. Legitimate values of @var{index} are integers ranging from | |
171 0 up to one less than the length of @var{sequence}. If @var{sequence} | |
172 is a list, then out-of-range values of @var{index} return @code{nil}; | |
173 otherwise, they trigger an @code{args-out-of-range} error. | |
174 | |
175 @example | |
176 @group | |
177 (elt [1 2 3 4] 2) | |
178 @result{} 3 | |
179 @end group | |
180 @group | |
181 (elt '(1 2 3 4) 2) | |
182 @result{} 3 | |
183 @end group | |
184 @group | |
185 (char-to-string (elt "1234" 2)) | |
186 @result{} "3" | |
187 @end group | |
188 @group | |
189 (elt [1 2 3 4] 4) | |
190 @error{}Args out of range: [1 2 3 4], 4 | |
191 @end group | |
192 @group | |
193 (elt [1 2 3 4] -1) | |
194 @error{}Args out of range: [1 2 3 4], -1 | |
195 @end group | |
196 @end example | |
197 | |
12098 | 198 This function generalizes @code{aref} (@pxref{Array Functions}) and |
199 @code{nth} (@pxref{List Elements}). | |
6374 | 200 @end defun |
201 | |
202 @node Arrays | |
203 @section Arrays | |
204 @cindex array | |
205 | |
7119 | 206 An @dfn{array} object has slots that hold a number of other Lisp |
6374 | 207 objects, called the elements of the array. Any element of an array may |
208 be accessed in constant time. In contrast, an element of a list | |
209 requires access time that is proportional to the position of the element | |
210 in the list. | |
211 | |
212 When you create an array, you must specify how many elements it has. | |
213 The amount of space allocated depends on the number of elements. | |
214 Therefore, it is impossible to change the size of an array once it is | |
7119 | 215 created; you cannot add or remove elements. However, you can replace an |
216 element with a different value. | |
6374 | 217 |
218 Emacs defines two types of array, both of which are one-dimensional: | |
219 @dfn{strings} and @dfn{vectors}. A vector is a general array; its | |
220 elements can be any Lisp objects. A string is a specialized array; its | |
221 elements must be characters (i.e., integers between 0 and 255). Each | |
222 type of array has its own read syntax. @xref{String Type}, and | |
223 @ref{Vector Type}. | |
224 | |
7119 | 225 Both kinds of array share these characteristics: |
6374 | 226 |
227 @itemize @bullet | |
228 @item | |
229 The first element of an array has index zero, the second element has | |
230 index 1, and so on. This is called @dfn{zero-origin} indexing. For | |
231 example, an array of four elements has indices 0, 1, 2, @w{and 3}. | |
232 | |
233 @item | |
234 The elements of an array may be referenced or changed with the functions | |
235 @code{aref} and @code{aset}, respectively (@pxref{Array Functions}). | |
236 @end itemize | |
237 | |
12098 | 238 In principle, if you wish to have an array of text characters, you |
239 could use either a string or a vector. In practice, we always choose | |
240 strings for such applications, for four reasons: | |
6374 | 241 |
242 @itemize @bullet | |
243 @item | |
244 They occupy one-fourth the space of a vector of the same elements. | |
245 | |
246 @item | |
247 Strings are printed in a way that shows the contents more clearly | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
248 as text. |
6374 | 249 |
250 @item | |
251 Strings can hold text properties. @xref{Text Properties}. | |
252 | |
253 @item | |
254 Many of the specialized editing and I/O facilities of Emacs accept only | |
255 strings. For example, you cannot insert a vector of characters into a | |
256 buffer the way you can insert a string. @xref{Strings and Characters}. | |
257 @end itemize | |
258 | |
12098 | 259 By contrast, for an array of keyboard input characters (such as a key |
260 sequence), a vector may be necessary, because many keyboard input | |
261 characters are outside the range that will fit in a string. @xref{Key | |
262 Sequence Input}. | |
263 | |
6374 | 264 @node Array Functions |
265 @section Functions that Operate on Arrays | |
266 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
267 In this section, we describe the functions that accept all types of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
268 arrays. |
6374 | 269 |
270 @defun arrayp object | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
271 This function returns @code{t} if @var{object} is an array (i.e., a |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
272 vector, a string, a bool-vector or a char-table). |
6374 | 273 |
274 @example | |
275 @group | |
276 (arrayp [a]) | |
277 @result{} t | |
278 (arrayp "asdf") | |
279 @result{} t | |
280 @end group | |
281 @end example | |
282 @end defun | |
283 | |
284 @defun aref array index | |
285 @cindex array elements | |
286 This function returns the @var{index}th element of @var{array}. The | |
287 first element is at index zero. | |
288 | |
289 @example | |
290 @group | |
291 (setq primes [2 3 5 7 11 13]) | |
292 @result{} [2 3 5 7 11 13] | |
293 (aref primes 4) | |
294 @result{} 11 | |
295 (elt primes 4) | |
296 @result{} 11 | |
297 @end group | |
298 | |
299 @group | |
300 (aref "abcdefg" 1) | |
301 @result{} 98 ; @r{@samp{b} is @sc{ASCII} code 98.} | |
302 @end group | |
303 @end example | |
304 | |
305 See also the function @code{elt}, in @ref{Sequence Functions}. | |
306 @end defun | |
307 | |
308 @defun aset array index object | |
309 This function sets the @var{index}th element of @var{array} to be | |
310 @var{object}. It returns @var{object}. | |
311 | |
312 @example | |
313 @group | |
314 (setq w [foo bar baz]) | |
315 @result{} [foo bar baz] | |
316 (aset w 0 'fu) | |
317 @result{} fu | |
318 w | |
319 @result{} [fu bar baz] | |
320 @end group | |
321 | |
322 @group | |
323 (setq x "asdfasfd") | |
324 @result{} "asdfasfd" | |
325 (aset x 3 ?Z) | |
326 @result{} 90 | |
327 x | |
328 @result{} "asdZasfd" | |
329 @end group | |
330 @end example | |
331 | |
332 If @var{array} is a string and @var{object} is not a character, a | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
333 @code{wrong-type-argument} error results. If @var{array} is a string |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
334 and @var{object} is character, but @var{object} does not use the same |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
335 number of bytes as the character currently stored in @code{(aref |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
336 @var{object} @var{index})}, that is also an error. @xref{Chars and |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
337 Bytes}. |
6374 | 338 @end defun |
339 | |
340 @defun fillarray array object | |
7119 | 341 This function fills the array @var{array} with @var{object}, so that |
342 each element of @var{array} is @var{object}. It returns @var{array}. | |
6374 | 343 |
344 @example | |
345 @group | |
346 (setq a [a b c d e f g]) | |
347 @result{} [a b c d e f g] | |
348 (fillarray a 0) | |
349 @result{} [0 0 0 0 0 0 0] | |
350 a | |
351 @result{} [0 0 0 0 0 0 0] | |
352 @end group | |
353 @group | |
354 (setq s "When in the course") | |
355 @result{} "When in the course" | |
356 (fillarray s ?-) | |
357 @result{} "------------------" | |
358 @end group | |
359 @end example | |
360 | |
361 If @var{array} is a string and @var{object} is not a character, a | |
362 @code{wrong-type-argument} error results. | |
363 @end defun | |
364 | |
365 The general sequence functions @code{copy-sequence} and @code{length} | |
366 are often useful for objects known to be arrays. @xref{Sequence Functions}. | |
367 | |
368 @node Vectors | |
369 @section Vectors | |
370 @cindex vector | |
371 | |
372 Arrays in Lisp, like arrays in most languages, are blocks of memory | |
373 whose elements can be accessed in constant time. A @dfn{vector} is a | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
374 general-purpose array; its elements can be any Lisp objects. (By |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
375 contrast, a string can hold only characters as elements.) Vectors in |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
376 Emacs are used for obarrays (vectors of symbols), and as part of keymaps |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
377 (vectors of commands). They are also used internally as part of the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
378 representation of a byte-compiled function; if you print such a |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
379 function, you will see a vector in it. |
6374 | 380 |
381 In Emacs Lisp, the indices of the elements of a vector start from zero | |
382 and count up from there. | |
383 | |
7119 | 384 Vectors are printed with square brackets surrounding the elements. |
385 Thus, a vector whose elements are the symbols @code{a}, @code{b} and | |
386 @code{a} is printed as @code{[a b a]}. You can write vectors in the | |
387 same way in Lisp input. | |
6374 | 388 |
389 A vector, like a string or a number, is considered a constant for | |
390 evaluation: the result of evaluating it is the same vector. This does | |
391 not evaluate or even examine the elements of the vector. | |
392 @xref{Self-Evaluating Forms}. | |
393 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
394 Here are examples illustrating these principles: |
6374 | 395 |
396 @example | |
397 @group | |
398 (setq avector [1 two '(three) "four" [five]]) | |
399 @result{} [1 two (quote (three)) "four" [five]] | |
400 (eval avector) | |
401 @result{} [1 two (quote (three)) "four" [five]] | |
402 (eq avector (eval avector)) | |
403 @result{} t | |
404 @end group | |
405 @end example | |
406 | |
7119 | 407 @node Vector Functions |
408 @section Functions That Operate on Vectors | |
409 | |
6374 | 410 Here are some functions that relate to vectors: |
411 | |
412 @defun vectorp object | |
413 This function returns @code{t} if @var{object} is a vector. | |
414 | |
415 @example | |
416 @group | |
417 (vectorp [a]) | |
418 @result{} t | |
419 (vectorp "asdf") | |
420 @result{} nil | |
421 @end group | |
422 @end example | |
423 @end defun | |
424 | |
425 @defun vector &rest objects | |
426 This function creates and returns a vector whose elements are the | |
427 arguments, @var{objects}. | |
428 | |
429 @example | |
430 @group | |
431 (vector 'foo 23 [bar baz] "rats") | |
432 @result{} [foo 23 [bar baz] "rats"] | |
433 (vector) | |
434 @result{} [] | |
435 @end group | |
436 @end example | |
437 @end defun | |
438 | |
439 @defun make-vector length object | |
440 This function returns a new vector consisting of @var{length} elements, | |
441 each initialized to @var{object}. | |
442 | |
443 @example | |
444 @group | |
445 (setq sleepy (make-vector 9 'Z)) | |
446 @result{} [Z Z Z Z Z Z Z Z Z] | |
447 @end group | |
448 @end example | |
449 @end defun | |
450 | |
451 @defun vconcat &rest sequences | |
452 @cindex copying vectors | |
453 This function returns a new vector containing all the elements of the | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
454 @var{sequences}. The arguments @var{sequences} may be any kind of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
455 arrays, including lists, vectors, or strings. If no @var{sequences} are |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
456 given, an empty vector is returned. |
6374 | 457 |
458 The value is a newly constructed vector that is not @code{eq} to any | |
459 existing vector. | |
460 | |
461 @example | |
462 @group | |
463 (setq a (vconcat '(A B C) '(D E F))) | |
464 @result{} [A B C D E F] | |
465 (eq a (vconcat a)) | |
466 @result{} nil | |
467 @end group | |
468 @group | |
469 (vconcat) | |
470 @result{} [] | |
471 (vconcat [A B C] "aa" '(foo (6 7))) | |
472 @result{} [A B C 97 97 foo (6 7)] | |
473 @end group | |
474 @end example | |
475 | |
12067 | 476 The @code{vconcat} function also allows integers as arguments. It |
477 converts them to strings of digits, making up the decimal print | |
478 representation of the integer, and then uses the strings instead of the | |
479 original integers. @strong{Don't use this feature; we plan to eliminate | |
480 it. If you already use this feature, change your programs now!} The | |
481 proper way to convert an integer to a decimal number in this way is with | |
6374 | 482 @code{format} (@pxref{Formatting Strings}) or @code{number-to-string} |
483 (@pxref{String Conversion}). | |
484 | |
485 For other concatenation functions, see @code{mapconcat} in @ref{Mapping | |
486 Functions}, @code{concat} in @ref{Creating Strings}, and @code{append} | |
487 in @ref{Building Lists}. | |
488 @end defun | |
489 | |
490 The @code{append} function provides a way to convert a vector into a | |
491 list with the same elements (@pxref{Building Lists}): | |
492 | |
493 @example | |
494 @group | |
495 (setq avector [1 two (quote (three)) "four" [five]]) | |
496 @result{} [1 two (quote (three)) "four" [five]] | |
497 (append avector nil) | |
498 @result{} (1 two (quote (three)) "four" [five]) | |
499 @end group | |
500 @end example | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
501 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
502 @node Char-Tables |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
503 @section Char-Tables |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
504 @cindex char-tables |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
505 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
506 A char-table is much like a vector, except that it is indexed by |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
507 character codes. Any valid character code, without modifiers, can be |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
508 used as an index in a char-table. You can access a char-table with |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
509 @code{aref} and @code{aset}, just like a vector. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
510 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
511 @cindex extra slots of char-table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
512 @cindex subtype of char-table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
513 Each char-table has a @dfn{subtype} which is a symbol. In order to be |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
514 a valid subtype, a symbol must have a @code{char-table-extra-slots} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
515 property which is an integer between 0 and 10. This integer specifies |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
516 the number of @dfn{extra slots} in the char-table. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
517 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
518 @cindex parent of char-table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
519 A char-table can have a @dfn{parent}. which is another char-table. If |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
520 it does, then whenever the char-table specifies @code{nil} for a |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
521 particular character @var{c}, it inherits the value specified in the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
522 parent. In other words, @code{(aref @var{char-table} @var{c})} returns |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
523 the value from the parent of @var{char-table} if @var{char-table} itself |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
524 specifies @code{nil}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
525 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
526 @cindex default value of char-table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
527 A char-table can also have a @dfn{default value}. If so, then |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
528 @code{(aref @var{char-table} @var{c})} returns the default value |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
529 whenever the char-table does not specify any other non-@code{nil} value. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
530 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
531 @tindex make-char-table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
532 @defun make-char-table subtype &optional init |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
533 Return a newly created char-table, with subtype @var{subtype}. Each |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
534 element is initialized to @var{init}, which defaults to @code{nil}. You |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
535 cannot alter the subtype of a char-table after the char-table is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
536 created. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
537 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
538 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
539 @tindex char-table-p |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
540 @defun char-table-p object |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
541 This function returns @code{t} if @code{object} is a char-table, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
542 otherwise @code{nil}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
543 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
544 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
545 @tindex char-table-subtype |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
546 @defun char-table-subtype char-table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
547 This function returns the subtype symbol of @var{char-table}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
548 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
549 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
550 @tindex set-char-table-default |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
551 @defun set-char-table-default char-table new-default |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
552 This function sets the default value of @var{char-table} to |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
553 @var{new-default}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
554 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
555 There is no special function to access the default value of a char-table. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
556 To do that, use @code{(char-table-range @var{char-table} nil)}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
557 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
558 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
559 @tindex char-table-parent |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
560 @defun char-table-parent char-table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
561 This function returns the parent of @var{char-table}. The parent is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
562 always either @code{nil} or another char-table. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
563 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
564 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
565 @tindex set-char-table-parent |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
566 @defun set-char-table-parent char-table new-parent |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
567 This function sets the parent of @var{char-table} to @var{new-parent}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
568 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
569 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
570 @tindex char-table-extra-slot |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
571 @defun char-table-extra-slot char-table n |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
572 This function returns the contents of extra slot @var{n} of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
573 @var{char-table}. The number of extra slots in a char-table is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
574 determined by its subtype. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
575 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
576 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
577 @tindex set-char-table-extra-slot |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
578 @defun set-char-table-extra-slot char-table n value |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
579 This function stores @var{value} in extra slot @var{n} of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
580 @var{char-table}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
581 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
582 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
583 A char-table can specify an element value for a single character code; |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
584 it can also specify a value for an entire character set. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
585 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
586 @tindex char-table-range |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
587 @defun char-table-range char-table range |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
588 This returns the value specified in @var{char-table} for a range of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
589 characters @var{range}. Here @var{range} may be |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
590 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
591 @table @asis |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
592 @item @code{nil} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
593 Refers to the default value. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
594 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
595 @item @var{char} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
596 Refers to the element for character @var{char}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
597 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
598 @item @var{charset} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
599 Refers to the value specified for the whole character set |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
600 @var{charset} (@pxref{Character Sets}). |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
601 @end table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
602 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
603 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
604 @tindex set-char-table-range |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
605 @defun set-char-table-range char-table range value |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
606 This function set the value in @var{char-table} for a range of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
607 characters @var{range}. Here @var{range} may be |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
608 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
609 @table @asis |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
610 @item @code{nil} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
611 Refers to the default value. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
612 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
613 @item @code{t} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
614 Refers to the whole range of character codes. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
615 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
616 @item @var{char} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
617 Refers to the element for character @var{char}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
618 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
619 @item @var{charset} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
620 Refers to the value specified for the whole character set |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
621 @var{charset} (@pxref{Character Sets}). |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
622 @end table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
623 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
624 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
625 @tindex map-char-table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
626 @defun map-char-table function char-table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
627 This function calls @var{function} for each element of @var{char-table}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
628 @var{function} is called with two arguments, a key and a value. The key |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
629 is a possible @var{range} argument for @code{char-table-range}, and the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
630 value is @code{(char-table-range @var{char-table} @var{key})}. Invalid |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
631 character codes are never used as the key. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
632 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
633 Overall, the keys-value pairs passed to @var{function} describe all the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
634 values stored in @var{char-table}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
635 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
636 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
637 @node Bool-Vectors |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
638 @section Bool-vectors |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
639 @cindex Bool-vectors |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
640 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
641 A bool-vector is much like a vector, except that it stores only the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
642 values @code{t} and @code{nil}. If you try to store any non-@code{nil} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
643 value into an element of the bool-vector, that actually stores @code{t} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
644 there. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
645 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
646 There are two special functions for working with bool-vectors; aside |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
647 from that, you manipulate them with same functions used for other kinds |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
648 of arrays. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
649 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
650 @tindex make-bool-vector |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
651 @defun make-bool-vector length initial |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
652 Return a new book-vector of @var{length} elements, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
653 each one initialized to @var{initial}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
654 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
655 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
656 @defun bool-vector-p object |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
657 This returns @code{t} if @var{object} is a bool-vector, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
658 and @code{nil} otherwise. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
659 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
660 |