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