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