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