| 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 |
| 4 | @c 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, |
| 73 | string, 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 cons cell that is not a list (because the final |
| 84 | @sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is |
| 85 | signaled. For a char-table, the value returned is always one more |
| 86 | than the maximum Emacs character code. |
| 87 | |
| 88 | @xref{List Elements}, 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 | @defun string-bytes string |
| 115 | @cindex string, number of bytes |
| 116 | This function returns the number of bytes in @var{string}. |
| 117 | If @var{string} is a multibyte string, this is greater than |
| 118 | @code{(length @var{string})}. |
| 119 | @end defun |
| 120 | |
| 121 | @defun elt sequence index |
| 122 | @cindex elements of sequences |
| 123 | This function returns the element of @var{sequence} indexed by |
| 124 | @var{index}. Legitimate values of @var{index} are integers ranging from |
| 125 | 0 up to one less than the length of @var{sequence}. If @var{sequence} |
| 126 | is a list, then out-of-range values of @var{index} return @code{nil}; |
| 127 | otherwise, they trigger an @code{args-out-of-range} error. |
| 128 | |
| 129 | @example |
| 130 | @group |
| 131 | (elt [1 2 3 4] 2) |
| 132 | @result{} 3 |
| 133 | @end group |
| 134 | @group |
| 135 | (elt '(1 2 3 4) 2) |
| 136 | @result{} 3 |
| 137 | @end group |
| 138 | @group |
| 139 | ;; @r{We use @code{string} to show clearly which character @code{elt} returns.} |
| 140 | (string (elt "1234" 2)) |
| 141 | @result{} "3" |
| 142 | @end group |
| 143 | @group |
| 144 | (elt [1 2 3 4] 4) |
| 145 | @error{} Args out of range: [1 2 3 4], 4 |
| 146 | @end group |
| 147 | @group |
| 148 | (elt [1 2 3 4] -1) |
| 149 | @error{} Args out of range: [1 2 3 4], -1 |
| 150 | @end group |
| 151 | @end example |
| 152 | |
| 153 | This function generalizes @code{aref} (@pxref{Array Functions}) and |
| 154 | @code{nth} (@pxref{List Elements}). |
| 155 | @end defun |
| 156 | |
| 157 | @defun copy-sequence sequence |
| 158 | @cindex copying sequences |
| 159 | Returns a copy of @var{sequence}. The copy is the same type of object |
| 160 | as the original sequence, and it has the same elements in the same order. |
| 161 | |
| 162 | Storing a new element into the copy does not affect the original |
| 163 | @var{sequence}, and vice versa. However, the elements of the new |
| 164 | sequence are not copies; they are identical (@code{eq}) to the elements |
| 165 | of the original. Therefore, changes made within these elements, as |
| 166 | found via the copied sequence, are also visible in the original |
| 167 | sequence. |
| 168 | |
| 169 | If the sequence is a string with text properties, the property list in |
| 170 | the copy is itself a copy, not shared with the original's property |
| 171 | list. However, the actual values of the properties are shared. |
| 172 | @xref{Text Properties}. |
| 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 | The array is a constant, for evaluation---in other words, it evaluates |
| 252 | 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 |
| 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 any kind of |
| 476 | arrays, including lists, vectors, or strings. If no @var{sequences} are |
| 477 | given, an 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 provides a way to convert a vector into a |
| 513 | list with the same elements (@pxref{Building Lists}): |
| 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 new-default |
| 580 | This function sets the default value of @var{char-table} to |
| 581 | @var{new-default}. |
| 582 | |
| 583 | There is no special function to access the default value of a char-table. |
| 584 | To do that, use @code{(char-table-range @var{char-table} nil)}. |
| 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; specifying the generic |
| 628 | character as argument is equivalent to specifying the character set |
| 629 | name. @xref{Splitting Characters}, for a description of generic characters. |
| 630 | @end table |
| 631 | @end defun |
| 632 | |
| 633 | @defun set-char-table-range char-table range value |
| 634 | This function sets the value in @var{char-table} for a range of |
| 635 | characters @var{range}. Here are the possibilities for @var{range}: |
| 636 | |
| 637 | @table @asis |
| 638 | @item @code{nil} |
| 639 | Refers to the default value. |
| 640 | |
| 641 | @item @code{t} |
| 642 | Refers to the whole range of character codes. |
| 643 | |
| 644 | @item @var{char} |
| 645 | Refers to the element for character @var{char} |
| 646 | (supposing @var{char} is a valid character code). |
| 647 | |
| 648 | @item @var{charset} |
| 649 | Refers to the value specified for the whole character set |
| 650 | @var{charset} (@pxref{Character Sets}). |
| 651 | |
| 652 | @item @var{generic-char} |
| 653 | A generic character stands for a character set; specifying the generic |
| 654 | character as argument is equivalent to specifying the character set |
| 655 | name. @xref{Splitting Characters}, for a description of generic characters. |
| 656 | @end table |
| 657 | @end defun |
| 658 | |
| 659 | @defun map-char-table function char-table |
| 660 | This function calls @var{function} for each element of @var{char-table}. |
| 661 | @var{function} is called with two arguments, a key and a value. The key |
| 662 | is a possible @var{range} argument for @code{char-table-range}---either |
| 663 | a valid character or a generic character---and the value is |
| 664 | @code{(char-table-range @var{char-table} @var{key})}. |
| 665 | |
| 666 | Overall, the key-value pairs passed to @var{function} describe all the |
| 667 | values stored in @var{char-table}. |
| 668 | |
| 669 | The return value is always @code{nil}; to make this function useful, |
| 670 | @var{function} should have side effects. For example, |
| 671 | here is how to examine each element of the syntax table: |
| 672 | |
| 673 | @example |
| 674 | (let (accumulator) |
| 675 | (map-char-table |
| 676 | #'(lambda (key value) |
| 677 | (setq accumulator |
| 678 | (cons (list key value) accumulator))) |
| 679 | (syntax-table)) |
| 680 | accumulator) |
| 681 | @result{} |
| 682 | ((475008 nil) (474880 nil) (474752 nil) (474624 nil) |
| 683 | ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3))) |
| 684 | @end example |
| 685 | @end defun |
| 686 | |
| 687 | @node Bool-Vectors |
| 688 | @section Bool-vectors |
| 689 | @cindex Bool-vectors |
| 690 | |
| 691 | A bool-vector is much like a vector, except that it stores only the |
| 692 | values @code{t} and @code{nil}. If you try to store any non-@code{nil} |
| 693 | value into an element of the bool-vector, the effect is to store |
| 694 | @code{t} there. As with all arrays, bool-vector indices start from 0, |
| 695 | and the length cannot be changed once the bool-vector is created. |
| 696 | Bool-vectors are constants when evaluated. |
| 697 | |
| 698 | There are two special functions for working with bool-vectors; aside |
| 699 | from that, you manipulate them with same functions used for other kinds |
| 700 | of arrays. |
| 701 | |
| 702 | @defun make-bool-vector length initial |
| 703 | Return a new bool-vector of @var{length} elements, |
| 704 | each one initialized to @var{initial}. |
| 705 | @end defun |
| 706 | |
| 707 | @defun bool-vector-p object |
| 708 | This returns @code{t} if @var{object} is a bool-vector, |
| 709 | and @code{nil} otherwise. |
| 710 | @end defun |
| 711 | |
| 712 | Here is an example of creating, examining, and updating a |
| 713 | bool-vector. Note that the printed form represents up to 8 boolean |
| 714 | values as a single character. |
| 715 | |
| 716 | @example |
| 717 | (setq bv (make-bool-vector 5 t)) |
| 718 | @result{} #&5"^_" |
| 719 | (aref bv 1) |
| 720 | @result{} t |
| 721 | (aset bv 3 nil) |
| 722 | @result{} nil |
| 723 | bv |
| 724 | @result{} #&5"^W" |
| 725 | @end example |
| 726 | |
| 727 | @noindent |
| 728 | These results make sense because the binary codes for control-_ and |
| 729 | control-W are 11111 and 10111, respectively. |
| 730 | |
| 731 | @ignore |
| 732 | arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386 |
| 733 | @end ignore |